diff --git a/.agents/skills/check-pr/SKILL.md b/.agents/skills/check-pr/SKILL.md deleted file mode 100644 index 15c76cde1cac..000000000000 --- a/.agents/skills/check-pr/SKILL.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -name: check-pr -description: > - Check a single PR's CI status, review comments, and requested changes. - Fix actionable failures and address feedback. "check PR 1234", "what's - the status of my PR", "address review comments on #500". -argument-hint: "" -context: fork ---- - -# Check PR - -Do one pass over PR **$ARGUMENTS**: check CI, read reviews, fix what's -actionable, report status. - -## 1. Gather PR state - -```bash -# Overall state -gh pr view $ARGUMENTS --repo docker/docs --json state,title,url,headRefName - -# CI checks -gh pr checks $ARGUMENTS --repo docker/docs --json name,state,detailsUrl - -# Top-level reviews -gh pr view $ARGUMENTS --repo docker/docs --json reviews,reviewDecision - -# Inline (line-level) comments — NOT included in the above -gh api repos/docker/docs/pulls/$ARGUMENTS/comments \ - --jq '[.[] | {id: .id, author: .user.login, body: .body, path: .path, line: .line}]' -``` - -Always check both the reviews endpoint and the inline comments endpoint. -A review with an empty body may still have line-level comments requiring -action. - -## 2. If merged - -Report the final state. Then check for any unanswered review comments (both -top-level and inline) and reply to each one explaining what was done or that -the issue was addressed in a follow-up. Skip to step 6 after. - -## 3. If closed without merge - -Read the closing context to understand why: - -```bash -gh pr view $ARGUMENTS --repo docker/docs --json closedAt,comments \ - --jq '{closedAt, lastComment: .comments[-1].body}' -``` - -Report the reason. Common causes: rejected by maintainers, superseded by -another PR, closed by automation. - -## 4. If CI is failing - -- Read the failure details (follow `detailsUrl` if needed) -- Determine if the failure is in the PR's changed files or pre-existing -- **Actionable:** check out the branch, fix, commit, push - ```bash - git checkout - # fix the issue - git add - git commit -m "fix: " - git push - ``` -- **Pre-existing / upstream:** note it, do not block - -## 5. If review comments or changes requested - -- Read each unresolved comment -- Address feedback in a follow-up commit -- Push, then reply to each comment explaining what was done: - ```bash - gh api repos/docker/docs/pulls/$ARGUMENTS/comments \ - --method POST \ - --field in_reply_to= \ - --field body="" - ``` -- End every comment reply with an accurate agent-disclosure footer that names - the active coding agent, for example `Generated by Codex` or `Generated by - Claude Code`. -- Resolve each thread via GraphQL after replying: - ```bash - # Get thread IDs - gh api graphql -f query=' - query($owner:String!, $repo:String!, $pr:Int!) { - repository(owner:$owner, name:$repo) { - pullRequest(number:$pr) { - reviewThreads(first:50) { - nodes { id isResolved comments(first:1) { nodes { path } } } - } - } - } - }' -f owner=docker -f repo=docs -F pr=$ARGUMENTS \ - --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | {id, path: .comments.nodes[0].path}' - - # Resolve a thread - gh api graphql -f query=' - mutation($id:ID!) { resolveReviewThread(input:{threadId:$id}) { thread { isResolved } } } - ' -f id= - ``` -- Re-request review if changes were requested - -## 6. Report - -``` -## PR #$ARGUMENTS: - -**State:** <open|merged|closed> -**CI:** <passing|failing|pending> -**Review:** <approved|changes requested|pending> -**Action taken:** <what was done, or "none needed"> -``` diff --git a/.agents/skills/create-lab-guide/SKILL.md b/.agents/skills/create-lab-guide/SKILL.md index 047a5276d120..a1d559a026b5 100644 --- a/.agents/skills/create-lab-guide/SKILL.md +++ b/.agents/skills/create-lab-guide/SKILL.md @@ -108,9 +108,8 @@ Use contractions ("it's", "you're", "don't"). ## Step 5: Validate 1. Confirm frontmatter has `title`, `description`, `keywords`, and `params.tags` including `labs`. -2. Run `npx prettier --write <file>` to format. +2. Run `npx --no-install rumdl fmt <file>` to format. 3. Run `docker buildx bake lint vale` and fix any errors. 4. Re-read the file and verify: correct shortcode syntax, objectives match source content, modules match `labspace.yaml`, no vendored paths edited. Do not proceed to commit until validation passes. - diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index dda1abfe8a96..2bec1eb3d360 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -12,23 +12,41 @@ Push the branch and create a properly structured pull request. ## 1. Verify the branch +Confirm you're on a dedicated branch, not the default branch: + +```bash +git branch --show-current # must not be main or master +``` + +If this returns `main` or `master`, stop. Create a branch and move your +commits onto it before continuing. + +Confirm commits exist and the working tree is clean: + ```bash git log --oneline main..HEAD # confirm commits exist -git diff --quiet # confirm no unstaged changes +git status --porcelain # must print nothing ``` +If `git status --porcelain` prints anything, there are uncommitted or +unstaged changes. Stop and commit them — or unstage stray files like +`package-lock.json` — before opening a PR. Don't open a PR mid-edit. + ## 2. Push the branch -Confirm origin points to your fork, not upstream: +Identify the remote that points at your fork. Inspect the remotes: ```bash -git remote get-url origin +git remote -v ``` -Then push: +If `origin` is your fork, use it. If `origin` points at canonical +`docker/docs` (the upstream), push to your separate fork remote instead — +never push the branch to `docker/docs` directly: ```bash -git push -u origin <branch-name> +FORK_REMOTE=origin # or the name of your fork remote if origin is upstream +git push -u "$FORK_REMOTE" <branch-name> ``` ## 3. Create the PR @@ -46,10 +64,10 @@ duplicate PR; report the existing PR instead. Only proceed if there is no open linked PR, or if the existing PR clearly does not address the issue and you explain why in the new PR body. -Derive the fork owner dynamically: +Derive the fork owner dynamically from the same fork remote you pushed to: ```bash -FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|') +FORK_OWNER=$(git remote get-url "$FORK_REMOTE" | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|') ``` ```bash @@ -68,31 +86,54 @@ EOF )" ``` +Prefix the title with the change type to match repo convention — `docs:` for +documentation changes (or another scope like `hub:` when appropriate), for +example `docs: fix broken link on install page`. + Keep the body short. Reviewers need to know what changed and why — nothing else. Do **not** add a "Test plan" section — documentation PRs don't need one. Use an accurate disclosure footer that names the active coding agent, for example `Generated by Codex` or `Generated by Claude Code`. -### Optional: Learnings section +### Optional: Netlify preview entry path -If while working on this PR you discovered something non-obvious about the -repo — a convention not documented in AGENTS.md, a gotcha that tripped you -up, a pattern that should be codified — add a Learnings section to the PR -body: +If the PR primarily edits a single page or a focused section of pages, add a +`@netlify` stanza to the PR body (for example, just below the Summary). This +sets the entry path for the Netlify deploy preview so reviewers land on the +edited page instead of the site root: ```markdown -## Learnings +@netlify /desktop/setup/install/ +``` + +The stanza takes a single published URL path. Derive it from the source file +path: drop the `content/` prefix and `.md` suffix, strip the `/manuals` +segment, and add a trailing slash. For example, +`content/manuals/desktop/setup/install/mac-install.md` becomes +`/desktop/setup/install/mac-install/`. + +Only add this when the change is focused on one page or section. Skip it for +PRs that touch many unrelated pages — there is no useful single entry path. + +### Optional: Preview links + +When the change is focused, also add direct links to the deploy preview in the +PR body so reviewers can jump straight to the affected pages. The preview URL +embeds the PR number: -- <what you learned and why it matters> ``` +https://deploy-preview-<pr-number>--docsdocker.netlify.app/path/to/page/ +``` + +The PR number isn't known until `gh pr create` returns, so add these links +after creating the PR by updating the body: -Add this section between the Summary and the `Closes` line. Only include -learnings that would help future contributors avoid the same issue. Do not -include things already documented in AGENTS.md or STYLE.md. +```bash +gh pr edit <pr-number> --repo docker/docs --body "..." +``` -The weekly PR learnings scanner reads these sections to surface recurring -patterns for the team to codify. +Use the same source-path-to-URL mapping as the `@netlify` stanza above. ## 4. Apply labels and request review diff --git a/.agents/skills/curate-whats-new/SKILL.md b/.agents/skills/curate-whats-new/SKILL.md new file mode 100644 index 000000000000..fb9bd323906b --- /dev/null +++ b/.agents/skills/curate-whats-new/SKILL.md @@ -0,0 +1,101 @@ +--- +name: curate-whats-new +description: Curate noteworthy Docker launches from documentation pull requests merged during a requested period. Use when generating or reviewing data/whats-new.json, preparing the Docker Docs What's new timeline, or deciding which documented releases merit Docker-wide highlights. +--- + +# Curate What's New + +Treat merged documentation as evidence that a capability shipped, but do not +treat a documentation change as news by itself. + +Include an item only when the merged documentation directly shows all of the +following: + +- A released user-facing feature, material enhancement, or broader availability + milestone that was not available before the period +- A substantial capability or workflow, not new syntax or a small control + within an existing workflow +- Enough Docker-wide editorial significance to merit proactively telling users + about it outside product release notes +- A useful published page and a factual title and description + +Apply a high bar. The result is a curated launch archive, not a complete +changelog. A specialized feature can qualify when its user impact is +substantial. A quiet period can produce few or no items. + +## Exclusions + +Exclude documentation maintenance; fixes; rewrites; guidance for old behavior; +routine release or generated-content syncs; limitations, prerequisites, and +workarounds; narrow flags, settings, command variants, protocols, and +compatibility changes; incremental UI, safety, permissions, or observability +improvements; and lower-level Engine, Build, networking, or storage changes. +These qualify only when they are part of an independently newsworthy +product-level launch. + +Judge the user outcome, not PR size, product popularity, labels, changed lines, +a dedicated page, or the existence of a new API or command. + +## Select highlights + +Include every qualifying launch; do not impose a quota. Mark the five most +important as `featured: true`, or all items when fewer than five qualify. Rank +by the magnitude and distinctness of the user outcome and the value of helping +its audience discover it. Breadth can matter, but a major capability for a +specialized audience can outrank a smaller change for a broad audience. Recency +and product variety are not ranking goals. + +Create one item per launch and combine PRs that document the same launch. +Preserve existing copy while it remains accurate and qualifies. Change featured +status only when the relative importance of the candidate set changes. + +## Procedure + +1. Read `data/whats-new.json`. +2. Determine the review mode from the request: + - If the request does not specify a publication window, end it on the + previous UTC day and start it 29 days earlier. + - For an incremental review, list PRs merged from the day after the supplied + checkpoint through the end of the publication window. Retain existing + items inside the publication window without re-reviewing their source PRs. + If the request does not supply a checkpoint, use the existing + `period_end` from `data/whats-new.json`. + - For a full review, inspect every PR merged in the supplied publication + window. +3. List PRs in the range that applies to the review mode: + + ```console + $ gh pr list --repo docker/docs --state merged --search 'merged:START..END' --limit 200 + ``` + + If an incremental search returns no PRs, skip candidate inspection and only + remove expired items. +4. Inspect the diff and resulting pages for every plausible new candidate. +5. Decide what qualifies using only evidence in the merged documentation. +6. Remove existing items published before the requested publication window. + Add newly qualifying launches, combine related PRs, and reconsider featured + status across the resulting list. Do not replace or rewrite retained items + merely because they were not part of the incremental candidate range. +7. Replace `period_start`, `period_end`, and `items` in + `data/whats-new.json`. Sort items by `published` date, newest first. +8. Report the curation outcome in the response: + - Enumerate every newly selected entry by product, title, and source PRs. + - Summarize retained and expired entries by count. Identify any retained + entry whose content or sources changed. + - Explain only the most relevant plausible exclusions. Do not enumerate + routine maintenance PRs that were never credible candidates. + +If the request includes creating a pull request, use the same report in the PR +body with `## Summary`, `## Selected entries`, and `## Curation notes` +sections. Put each selected entry on one Markdown bullet and reference PRs as +`#NNNN` rather than full same-repository links. Do not hard-wrap bullets. Do +not create `.pr-body.md` or another handoff file unless the request explicitly +asks for one. + +Each item must contain `product`, `title`, `description`, `url`, `published`, +`source_prs`, and `featured`. Use the canonical product name, a published +internal URL, the merge date in `YYYY-MM-DD` format, and source PR numbers. + +Write factual, restrained copy. Avoid superlatives, promotional language, and +claims about ease or importance. Do not modify tracked files other than +`data/whats-new.json`. diff --git a/.agents/skills/curate-whats-new/agents/openai.yaml b/.agents/skills/curate-whats-new/agents/openai.yaml new file mode 100644 index 000000000000..6b51529d64a8 --- /dev/null +++ b/.agents/skills/curate-whats-new/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Curate What's New" + short_description: "Curate noteworthy Docker launches from merged docs" + default_prompt: "Use $curate-whats-new to curate Docker launches published during the requested date range." diff --git a/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.json b/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.json new file mode 100644 index 000000000000..0277ac5b85c3 --- /dev/null +++ b/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.json @@ -0,0 +1,96 @@ +{ + "period_start": "2026-07-13", + "period_end": "2026-08-11", + "items": [ + { + "product": "Docker Desktop", + "title": "Use Docker VMM on Mac and Windows", + "description": "Run Docker Desktop with Docker's container-optimized hypervisor on supported Mac and Windows systems.", + "url": "/desktop/features/vmm/", + "published": "2026-08-10", + "source_prs": [25702, 25726], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Connect sandboxes through an MCP gateway", + "description": "Register local or remote MCP servers on the host, reuse them across sandboxes, and govern server and tool access with Cedar policies.", + "url": "/ai/sandboxes/mcp-gateway/", + "published": "2026-08-06", + "source_prs": [25559, 25707], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Author version 2 sandbox kits", + "description": "Define kit setup, permissions, networking, and API key or OAuth credential requirements with the version 2 kit schema.", + "url": "/ai/sandboxes/customize/kit-reference/#schema-versions", + "published": "2026-08-06", + "source_prs": [25467, 25707], + "featured": false + }, + { + "product": "Docker Sandboxes", + "title": "Run Claude Code with local models", + "description": "Route Claude Code sandbox requests to the bundled local-model server or an existing Ollama installation.", + "url": "/ai/sandboxes/agents/claude-code/#use-a-local-model", + "published": "2026-08-06", + "source_prs": [25641, 25707], + "featured": false + }, + { + "product": "Docker AI Governance", + "title": "Search and forward audit events", + "description": "Search and export policy decisions from Docker Cloud, or forward events to Splunk, Dynatrace, and custom HTTPS endpoints.", + "url": "/ai/sandboxes/governance/audit/", + "published": "2026-08-03", + "source_prs": [25679, 25687], + "featured": true + }, + { + "product": "Docker Desktop", + "title": "Install from the Microsoft Store without administrator privileges", + "description": "Fresh Microsoft Store installations on Windows use per-user mode by default.", + "url": "/desktop/release-notes/#4850", + "published": "2026-08-03", + "source_prs": [25665], + "featured": false + }, + { + "product": "Docker Sandboxes", + "title": "Share agent skills across sandboxes", + "description": "Import skills from supported host agents into a persistent store that sandboxes can share.", + "url": "/ai/sandboxes/workflows/#share-agent-skills", + "published": "2026-07-24", + "source_prs": [25588], + "featured": false + }, + { + "product": "Docker Sandboxes", + "title": "Connect editors and desktop apps over SSH", + "description": "Use a sandbox from VS Code, Cursor, Claude Desktop, ChatGPT, or another SSH-capable tool.", + "url": "/ai/sandboxes/integrations/", + "published": "2026-07-24", + "source_prs": [25557], + "featured": true + }, + { + "product": "Docker Hardened Images", + "title": "Query the DHI catalog from AI assistants", + "description": "Search DHI repositories, inspect images, retrieve SBOMs, check CVEs, and manage mirrors through the DHI MCP server.", + "url": "/dhi/tools/mcp/", + "published": "2026-07-23", + "source_prs": [25589], + "featured": false + }, + { + "product": "Docker Enterprise", + "title": "Authenticate GitHub Actions with OIDC connections", + "description": "Exchange GitHub OIDC tokens for short-lived access to Docker resources without storing long-lived workflow credentials.", + "url": "/enterprise/security/oidc-connections/", + "published": "2026-07-21", + "source_prs": [25336], + "featured": true + } + ] +} diff --git a/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.yaml b/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.yaml new file mode 100644 index 000000000000..da5a56f64868 --- /dev/null +++ b/.agents/skills/curate-whats-new/examples/2026-07-13--2026-08-11.yaml @@ -0,0 +1,39 @@ +# Human-reviewed example and regression criteria for the curate-whats-new skill. +# This file is not loaded into the skill's runtime context. +period_start: 2026-07-13 +period_end: 2026-08-11 +example_output: 2026-07-13--2026-08-11.json + +expected_archive: + - Docker VMM on Mac and Windows + - Docker Sandboxes MCP gateway + - Docker Sandboxes kit schema version 2 + - Claude Code with local models + - Docker AI Governance audit search, export, and forwarding + - Microsoft Store per-user installation + - Shared agent skills across sandboxes + - Docker Sandboxes editor and app integrations + - Docker Hardened Images MCP server + - Enterprise OIDC connections + +featured_guidance: + strong: + - Docker VMM on Mac and Windows + - Docker AI Governance audit search, export, and forwarding + - Docker Sandboxes editor and app integrations + - Enterprise OIDC connections + either_is_reasonable: + - Docker Sandboxes MCP gateway + - Docker Sandboxes kit schema version 2 + +must_exclude: + - Gordon safety modes and custom rules + - Swarm direct server return networking + - Engine image mounts + - Unix sockets on Windows + - Narrow flags, command variants, protocol options, and compatibility switches + +notes: + - Do not require product diversity. + - Treat featured choices as editorial judgment, not an exact golden ordering. + - Reject lower-level or incremental changes even when they are technically new. diff --git a/.agents/skills/maintain-pr/SKILL.md b/.agents/skills/maintain-pr/SKILL.md new file mode 100644 index 000000000000..ceb563616a43 --- /dev/null +++ b/.agents/skills/maintain-pr/SKILL.md @@ -0,0 +1,89 @@ +--- +name: maintain-pr +description: > + Maintain and follow up on a single Docker documentation pull request that + you own or are responsible for updating. Check CI and review feedback, fix + actionable failures, push changes, reply to comments, and report status. + Use for requests such as "babysit this PR", "check the status of my PR", + "fix CI on my PR", or "address review comments on #500". Do not use for + maintainer review of an incoming contribution; use review-pr for that. +--- + +# Maintain PR + +Do one maintenance pass over the specified author-owned PR: inspect its +state, fix actionable failures or feedback, reply to reviewers, and report +the result. This workflow may modify the branch and GitHub because the user +is asking to maintain the PR. Do not apply it to an incoming PR merely +because the user asks to review or assess it. + +## 1. Gather PR state + +```bash +gh pr view <PR> --repo docker/docs --json state,title,url,headRefName,headRepositoryOwner,comments,reviews,reviewDecision +gh pr checks <PR> --repo docker/docs --json name,state,detailsUrl +gh api repos/docker/docs/pulls/<PR>/comments \ + --jq '[.[] | {id, author: .user.login, body, path, line, in_reply_to_id}]' +``` + +Always check both top-level reviews and inline comments. A review with an +empty body may still contain line-level feedback. Confirm that the PR is one +the user owns or is authorized to update before checking out or pushing its +branch. If not, stop and use `review-pr`. + +## 2. Handle terminal states + +If merged, report the final state and identify unanswered review comments. +Reply only when the user remains responsible for follow-up. + +If closed without merge, read the closing context and report the reason. +Common causes include maintainer rejection, supersession, or automation. + +## 3. Diagnose CI failures + +- Read the failure details. +- Determine whether the failure comes from the PR or predates it. +- Fix actionable failures in the PR's changed files. +- Report pre-existing or upstream failures without changing unrelated files. + +Follow repository instructions for formatting, targeted linting, explicit +staging, commits, and pushes. Preserve unrelated working-tree changes. + +## 4. Address review feedback + +Treat every review comment as a claim to verify. Implement it only when the +evidence supports it; explain any evidence-based disagreement. + +After each fix: + +1. Format and validate the changed files. +2. Commit and push the focused change. +3. Reply to every addressed thread with what changed or why no change was + made. +4. End replies with an accurate agent-disclosure footer, such as + `Generated by Codex`. +5. Resolve threads only after replying. +6. Re-request review when appropriate. + +Use the inline comment endpoint to reply: + +```bash +gh api repos/docker/docs/pulls/<PR>/comments \ + --method POST \ + --field in_reply_to=<COMMENT_ID> \ + --field body='<RESPONSE>' +``` + +Use GraphQL to retrieve unresolved review-thread IDs and resolve only the +threads that were addressed. Do not silently fix feedback without replying. + +## 5. Report + +```markdown +## PR #<number>: <title> + +**State:** <open, merged, or closed> +**CI:** <passing, failing, or pending> +**Review:** <approved, changes requested, or pending> +**Action taken:** <changes, replies, and thread resolution, or none needed> +``` diff --git a/.agents/skills/maintain-pr/agents/openai.yaml b/.agents/skills/maintain-pr/agents/openai.yaml new file mode 100644 index 000000000000..54c4fb6d1d86 --- /dev/null +++ b/.agents/skills/maintain-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Maintain PR" + short_description: "Maintain an authored PR through review and CI" + default_prompt: "Use $maintain-pr to maintain this pull request through CI and review follow-up." diff --git a/.agents/skills/research/SKILL.md b/.agents/skills/research/SKILL.md index db9f98c3ffa0..98094ac4d64d 100644 --- a/.agents/skills/research/SKILL.md +++ b/.agents/skills/research/SKILL.md @@ -11,9 +11,9 @@ description: > # Research -Thoroughly investigate the topic at hand and produce a clear plan for -the fix. The goal is to identify exact files, named targets within those -files, and the verified content needed for the fix. +Investigate the topic and determine whether documentation needs to change. +When an update is warranted, identify exact files, named targets within +those files, and the verified content needed. ## 1. Gather context @@ -65,15 +65,34 @@ plan a fix based on an unverified claim. If the fix requires a replacement URL and that URL cannot be verified (e.g. network restrictions), report it as a blocker rather than guessing. -## 6. Check the live site (if needed) +## 6. Assess documentation impact + +A code change or release-note entry is evidence to investigate, not a reason +by itself to add documentation. Identify the reader's task and what the +change alters about it. Recommend an update when existing guidance becomes +incorrect, leaves a gap in that task, or omits a capability useful to readers. +An implementation fix may need no update if the docs already describe the +intended behavior. + +For each recommended update, connect the reader's task, the documentation +gap, the destination page and section, and the proposed treatment. Prefer +correcting existing prose or examples when they serve that task. Check related +pages for contradictions, without assuming each needs the same explanation. + +If there is no clear home, reconsider the value and scope before proposing a +section or page. A separate home can be justified by a distinct reader task, +not by the need to place a release-note bullet. "No documentation change" is +a valid finding; explain it briefly when assessing a set of changes. + +## 7. Check the live site (if needed) For URL or rendering issues, fetch the live page: -``` +```text https://docs.docker.com/<path>/ ``` -## 7. Report findings +## 8. Report findings Summarize what you found — files to change, the specific problem in each, what the fix should be, and any constraints. This context feeds directly diff --git a/.agents/skills/review-changes/SKILL.md b/.agents/skills/review-changes/SKILL.md index f147883a44b2..adaf54604a9e 100644 --- a/.agents/skills/review-changes/SKILL.md +++ b/.agents/skills/review-changes/SKILL.md @@ -82,6 +82,18 @@ context: - Would a reader be confused by anything the change introduces or leaves out? +Accuracy alone doesn't justify an addition. For each substantive addition, ask: + +- Does it help readers act, choose, or understand a consequence? +- Does it belong under this heading and at this point in the explanation? +- Does it interrupt a procedure, example, or explanation already in progress? +- Is the detail proportional to its value here, or would a link suffice? +- Would removing it improve the page without losing necessary guidance? + +Recommend shortening, moving, or deleting accurate text when it doesn't serve +the page's task. When reviewing multiple commits, check both each change in +context and the combined diff for repeated explanations. + ## 6. Review code and template changes For non-Markdown changes (JS, HTML, CSS, Hugo templates): @@ -102,6 +114,7 @@ accurate. - There is a factual error or contradiction (on-page or cross-page) - A cross-reference is broken or misleading - A reader would be confused +- An addition duplicates guidance or disrupts the page without enough reader value When requesting changes, be specific: quote the exact text that is wrong, explain why, and suggest the correct fix. diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md new file mode 100644 index 000000000000..7f5bfdb59b09 --- /dev/null +++ b/.agents/skills/review-pr/SKILL.md @@ -0,0 +1,205 @@ +--- +name: review-pr +description: > + Review one or more incoming Docker documentation pull requests as a + maintainer. Independently validate technical claims, assess editorial fit + and information architecture, choose a verdict, and draft exact inline or + PR-wide feedback behind a confirmation gate. Use for requests such as + "review PR 123", "is this PR correct?", "does this information belong + here?", "validate this PR", or "help review backlog PRs". Do not use to + maintain or fix a PR you own; use maintain-pr for that. +--- + +# Review PR + +Review incoming contributions for factual correctness and whether they make +the documentation better as a whole. Treat a technically true addition as +insufficient when it is misplaced, overemphasized, redundant, or unhelpful +to the page's intended reader. + +## Preserve the write boundary + +Perform the review in two phases: + +1. Research the PR, decide a verdict, and present the exact proposed + comment or review text. +2. Wait for explicit user confirmation, then post only the confirmed text. + +Before confirmation, do not post comments, submit a GitHub review, approve or +request changes, resolve threads, push commits, edit labels, or otherwise +mutate GitHub. A request to review or draft feedback is not confirmation to +post it. Ask `Post these comments?` and stop. Treat revisions to a draft as +unconfirmed until the user explicitly asks to post them. + +## 1. Gather the full context + +For each PR, inspect its metadata, body, commits, changed files, checks, +conversation, reviews, and linked issues. Always fetch inline comments +separately because `gh pr view --json reviews` omits them. + +```bash +gh pr view <PR> --repo docker/docs \ + --json number,title,url,state,author,body,baseRefName,headRefName,headRefOid,commits,files,comments,reviews,reviewDecision,statusCheckRollup +gh api repos/docker/docs/pulls/<PR>/comments \ + --jq '[.[] | {id, author: .user.login, body, path, line, side, commit_id}]' +gh pr diff <PR> --repo docker/docs +``` + +Read linked issues and relevant discussion. An issue is evidence that a +reader was confused, but it does not establish the reporter's diagnosis or +justify a new highlighted note by itself. Green CI establishes only that automated +checks passed, not that the content is correct. + +Fetch the PR head when local inspection is useful. Compare it with the +canonical upstream base rather than assuming the local branch is fresh. +Read each changed file in full, not only its diff. + +## 2. Research independently + +Verify every material claim against authoritative sources such as product +source code, upstream documentation, specifications, release notes, or safe +local reproduction. Do not accept the PR description, issue diagnosis, or +existing review feedback as fact. + +Search the documentation for related explanations and canonical pages. Read +`STYLE.md`, `COMPONENTS.md`, and applicable repository instructions. Check +whether a changed file is generated or maintained upstream and identify the correct +upstream repository instead of proposing a local edit. + +Distinguish among: + +- a wrong fact +- a correct fact expressed inaccurately +- a correct fact placed on the wrong page +- content already explained elsewhere +- a real discovery problem better addressed with a short signpost and link +- a request that needs no documentation change. + +If an external claim or replacement URL cannot be verified, report that +limitation instead of guessing. + +## 3. Assess editorial fit + +Apply these questions to each addition: + +- Does it change a reader's decision or next action on this page? +- Is this the canonical page for the concept? +- Is the fact general, or specific to this page, feature, or component? +- Is the information already documented elsewhere? +- Would a concise local signpost to canonical coverage solve the discovery + problem better than duplicating the explanation? +- Is the visual and textual weight proportional to the information's value? +- Does it preserve the page's scope, flow, and character? + +Prefer one coherent explanation in the canonical location. Add local context +only when it helps the reader complete the task at hand. Avoid stray notes, +callouts, and exhaustive edge cases whose prominence exceeds their value. + +## 4. Choose a decisive verdict + +Lead with one of these outcomes: + +- **Approve**: correct, useful, well placed, and ready to merge. +- **Approve with optional polish**: ready to merge; suggestions are genuinely + non-blocking. +- **Focused rewrite**: the underlying need is valid, but wording, scope, + placement, or structure should change before merge. +- **Close / no docs change**: incorrect, redundant, out of scope, or not a + documentation problem. + +Explain the verdict with evidence. When wording is the issue, provide exact +replacement text rather than a vague request to improve it. + +## 5. Place feedback deliberately + +Use an inline comment when the finding is anchored to a narrow changed line +or range and acting on it is local. Examples include an inaccurate sentence, +an ambiguous option description, a broken link, or a precise wording +replacement. + +Use a PR-wide comment for scope, information architecture, overall approach, +multiple intertwined edits, or a proposed replacement section. Do not attach +holistic feedback to an arbitrary line. + +Use both when appropriate: put the overall direction in the PR-wide comment +and line-specific corrections inline. Do not repeat the same point in both. +Consolidate related feedback so the author receives the fewest comments that +remain clear and actionable. + +For every proposed inline comment, resolve and display the current changed +file path and right-side diff line. If the target line is not part of the +current diff or cannot be identified reliably, use a PR-wide comment that +quotes the target text instead. Never guess a line number. + +End comments posted on the user's behalf with an accurate agent-disclosure +footer, such as `Generated by Codex`. + +## 6. Present drafts and stop + +Before any GitHub write, show the review in this form, omitting empty +sections: + +```markdown +## Verdict + +Focused rewrite + +## Findings + +- <finding and evidence> + +## Proposed inline comments + +1. `path/to/file.md:42` + > Exact comment text + +## Proposed PR-wide comment + +> Exact comment text + +Post these comments? +``` + +For multiple PRs, give each PR its own verdict and comment set. Make the +confirmation scope unambiguous. Do not interpret approval of one PR's drafts +as approval to post comments on the others. + +## 7. Post only confirmed feedback + +Immediately before posting, re-fetch the PR head SHA and diff. If either the +head or an inline target changed, stop and show the updated draft or +placement for confirmation. + +Post confirmed inline comments as a single comment-only review when +practical. Use the current head SHA and right-side diff lines: + +```bash +gh api repos/docker/docs/pulls/<PR>/reviews --method POST --input <payload> +``` + +The JSON payload contains `commit_id`, `event: "COMMENT"`, and a `comments` +array whose entries contain `path`, `line`, `side: "RIGHT"`, and `body`. +Submitting a review with `APPROVE` or `REQUEST_CHANGES` requires separate, +explicit user authorization; a verdict alone does not grant it. + +Post confirmed holistic feedback separately: + +```bash +gh pr comment <PR> --repo docker/docs --body-file <file> +``` + +Use a safely created temporary file or API input so Markdown, backticks, and +shell substitutions are preserved literally. Post exactly the confirmed +text. Verify the resulting review/comments and report their URLs and +placements. If GitHub rejects an inline location, do not silently fall back +to a PR-wide comment; report the failure and prepare a revised placement for +confirmation. + +## Definition of done + +- Verify technical claims with authoritative evidence. +- Evaluate usefulness, placement, duplication, and proportionality. +- Give a decisive verdict and exact actionable wording. +- Choose inline and PR-wide placement based on the feedback's scope. +- Show every exact draft and target before any GitHub mutation. +- Post only after explicit confirmation and verify what was posted. diff --git a/.agents/skills/review-pr/agents/openai.yaml b/.agents/skills/review-pr/agents/openai.yaml new file mode 100644 index 000000000000..05b429a0082d --- /dev/null +++ b/.agents/skills/review-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Review PR" + short_description: "Validate incoming documentation pull requests" + default_prompt: "Use $review-pr to validate this incoming documentation PR and draft maintainer feedback." diff --git a/.agents/skills/testcontainers-guides-migrator/SKILL.md b/.agents/skills/testcontainers-guides-migrator/SKILL.md index 2be7e74daad4..b934d1af4d7d 100644 --- a/.agents/skills/testcontainers-guides-migrator/SKILL.md +++ b/.agents/skills/testcontainers-guides-migrator/SKILL.md @@ -350,8 +350,8 @@ If any test fails, debug and fix the code in both the temporary project AND the **IMPORTANT**: Run ALL validation locally before committing. Vale checks run on CI and will block the PR if they fail — fixing after push wastes CI cycles and review time. -1. `npx prettier --write content/guides/testcontainers-{LANG}-{GUIDE_ID}/` -2. `npx prettier --write content/manuals/testcontainers.md` +1. `npx --no-install rumdl fmt content/guides/testcontainers-{LANG}-{GUIDE_ID}/` +2. `npx --no-install rumdl fmt content/manuals/testcontainers.md` 3. `docker buildx bake lint` — must pass with no errors 4. `docker buildx bake vale` — then check for errors in the new files: ```bash diff --git a/.agents/skills/write/SKILL.md b/.agents/skills/write/SKILL.md index 672a6ce0f43e..52678b12cd77 100644 --- a/.agents/skills/write/SKILL.md +++ b/.agents/skills/write/SKILL.md @@ -1,9 +1,13 @@ --- name: write description: > - Write a documentation fix on a branch. Makes the minimal change, formats, - self-reviews, and commits. Use after research has identified what to change. - "write the fix", "make the changes", "implement the fix for #1234". + Write or edit reader-facing technical prose for immediate comprehension. + Use for documentation, PR titles and descriptions, release notes, design + documents, user-facing explanations, and substantive comments. Also use + when asked to make writing clearer, more natural, less AI-generated, or + easier to read. For documentation fixes, handles edits, formatting, + self-review, and commits after research identifies what to change. + Do not use for code-only tasks with no prose deliverable. hooks: PostToolUse: - matcher: "Edit|Write" @@ -14,9 +18,37 @@ hooks: # Write -Make the minimal change that resolves the issue. Research has already -identified what to change — this skill handles the edit, formatting, -self-review, and commit. +Follow the human-readable prose guidance in AGENTS.md and the style rules in +STYLE.md. Apply the prose review below to every prose deliverable, including +titles and short comments. + +For a prose-only request, return the requested text after reviewing it. Use +the numbered workflow for a documentation fix after research has identified +what to change. Branch and commit steps apply to that workflow, not to drafting +a title, description, or comment. Publishing prose requires authorization +from the user. + +## Prose review + +Before returning or committing prose, read it as if explaining the change to +an experienced colleague. Fix sentences that require a second reading even +when their grammar is correct. Lint passing does not replace this review. + +- Replace invented labels and stacks of nouns with the action or relationship + they describe: "post-update configuration validation" becomes "validate + the configuration after the update" +- Use direct verbs: "perform an evaluation of" becomes "evaluate" +- State concrete behavior instead of vague claims: "improve navigation + discoverability" becomes "show the current page in the sidebar" when that + is the actual change +- Keep established technical terms, exact identifiers, and qualifications + needed for accuracy. Clarify the surrounding sentence instead of replacing + a precise term with a vague one +- Check titles and headings separately. Use enough words to make their meaning + clear without relying on the body to explain an invented label + +Make these edits silently. Return the requested prose without a report of +this review unless the user asks for one. ## 1. Create a branch @@ -32,6 +64,17 @@ Always read each file before modifying it. Make the minimal change that fixes the issue. Do not improve surrounding content, add comments, or address adjacent problems. +Before drafting an addition, identify the reader's task and read the destination +section with the surrounding content. Choose where the information fits and +whether to correct prose, replace an example, or extend the explanation. +Related subject matter alone doesn't make a section an appropriate home. + +Explain current behavior in terms of what readers need to do, choose, or +understand. Keep detail proportional to that need. Give each explanation a +clear home; elsewhere, include only the context needed for that page's task +and link to the fuller explanation. Don't interrupt a procedure, example, or +explanation to insert a related fact. + Follow the writing guidelines in CLAUDE.md, STYLE.md, and COMPONENTS.md. ## 3. Front matter check @@ -41,21 +84,23 @@ front matter. If any are missing from a file you touch, add them. ## 4. Validate -Prettier runs automatically after each edit via the PostToolUse hook. +rumdl runs automatically after each edit via the PostToolUse hook. Run lint manually after all edits are complete: ```bash -scripts/lint.sh <changed-files> +scripts/lint.sh <changed-markdown-files> ``` -The lint script runs markdownlint and vale on only the files you pass it, -so the output is scoped to your changes. Fix any errors it reports. +The lint script runs rumdl and Vale on only the files you pass it, +so the output is scoped to your changes. Fix errors and warnings on lines you +added or changed, and review each suggestion. Vale can exit successfully when +warnings or suggestions remain in its output. ## 5. Self-review Re-read each changed file: right file, right lines, change is complete, front matter is present. Run `git diff` and verify only intended changes -are present. +are present. Apply the prose review to the changed text and the commit message. ## 6. Commit diff --git a/.agents/skills/write/scripts/post-edit.sh b/.agents/skills/write/scripts/post-edit.sh index d5cb809554f9..73ac30611824 100755 --- a/.agents/skills/write/scripts/post-edit.sh +++ b/.agents/skills/write/scripts/post-edit.sh @@ -1,6 +1,6 @@ #!/bin/bash # PostToolUse hook for Edit/Write in the write skill. -# Auto-formats Markdown files with prettier after each edit. +# Auto-formats Markdown files with rumdl after each edit. set -euo pipefail input=$(cat) @@ -9,4 +9,4 @@ file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty') [ -z "$file_path" ] && exit 0 [[ "$file_path" != *.md ]] && exit 0 -npx prettier --write "$file_path" 2>/dev/null +npx --no-install rumdl fmt "$file_path" 2>/dev/null diff --git a/.gitattributes b/.gitattributes index 5d685b7d139e..e79ba3c59a01 100644 --- a/.gitattributes +++ b/.gitattributes @@ -11,3 +11,5 @@ content/**/*.md linguist-detectable /_vendor/** linguist-generated=true # Generated CLI reference data (vendored from upstream) /data/cli/** linguist-generated=true +# Generated API presentation data +/data/api-reference.json linguist-generated=true diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a7242821ed8f..32035af6ed63 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -25,18 +25,22 @@ /content/reference/cli/ @dvdksn -/content/manuals/subscription/ @sarahsanders-docker +/content/manuals/subscription-billing/ @akristen -/content/manuals/security/ @aevesdocker @sarahsanders-docker +/content/manuals/security/ @aevesdocker @akristen -/content/manuals/admin/ @sarahsanders-docker +/content/manuals/admin/ @akristen -/content/manuals/billing/ @sarahsanders-docker +/content/manuals/accounts/ @akristen -/content/manuals/accounts/ @sarahsanders-docker +/content/manuals/support/ @akristen + +/content/manuals/platform-release-notes.md @akristen /content/manuals/ai/ @dvdksn +/content/manuals/ai/sandboxes/governance/ @craig-osterhout + /_vendor @dvdksn /content/manuals/offload/ @craig-osterhout diff --git a/.github/agents/docs-scanner.yaml b/.github/agents/docs-scanner.yaml index 08731db9a610..88b660f64b4e 100644 --- a/.github/agents/docs-scanner.yaml +++ b/.github/agents/docs-scanner.yaml @@ -100,7 +100,7 @@ agents: - Broken or missing links → htmltest catches these; do not file - Time-relative words ("currently", "recently", "still", "yet", "new") with no broader context problem → Vale catches these - - Formatting or style problems → markdownlint/Vale catch these + - Formatting or style problems → rumdl/Vale catch these 4. Is this a legitimate product feature gate? "Limited Access", "Contact your Docker account team to request access", "available on paid plans", "coming soon for Business subscribers" are product decisions, not stale @@ -121,7 +121,7 @@ agents: - **Vague verification tasks** — "verify this diagram is up to date", "check these links are still valid" — if you cannot identify the specific problem from reading the file, don't file - - **Style and formatting** — Vale and markdownlint handle these + - **Style and formatting** — Vale and rumdl handle these - **Suspicions without evidence** — you must quote the specific wrong text ## Filing issues diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 2a9628fa72d3..4382b20c4501 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -8,6 +8,14 @@ updates: open-pull-requests-limit: 10 schedule: interval: daily + - package-ecosystem: npm + directory: / + schedule: + interval: daily + allow: + - dependency-name: '@docker/marlin-sdk-web-public' + open-pull-requests-limit: 1 + - package-ecosystem: gomod directory: / cooldown: diff --git a/.github/labeler.yml b/.github/labeler.yml index 24fd85545405..fbb9eeffe71c 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -32,7 +32,7 @@ area/tests: - changed-files: - any-glob-to-any-file: - .htmltest.yml - - .markdownlint.json + - .rumdl.toml - .vale.ini - _vale/** - hack/test/* @@ -143,17 +143,17 @@ area/scout: area/billing: - changed-files: - any-glob-to-any-file: - - content/manuals/billing/** + - content/manuals/subscription-billing/** area/subscription: - changed-files: - any-glob-to-any-file: - - content/manuals/subscription/** + - content/manuals/subscription-billing/** area/admin: - changed-files: - any-glob-to-any-file: - - content/manuals/admin/** + - content/manuals/accounts/organization/** area/extensions: - changed-files: @@ -175,6 +175,7 @@ area/accounts: - changed-files: - any-glob-to-any-file: - content/manuals/accounts/** + - content/manuals/faqs/** area/copilot: - changed-files: diff --git a/.github/prompts/freshness-tier1.prompt.md b/.github/prompts/freshness-tier1.prompt.md deleted file mode 100644 index 41a784ccb232..000000000000 --- a/.github/prompts/freshness-tier1.prompt.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -mode: 'edit' ---- - -Imagine you're an experienced technical writer. You need to review content for -how fresh and up to date it is. Apply the following: - -1. Fix spelling errors and typos -2. Verify whether the markdown structure conforms to common markdown standards -3. Ensure the content follows our [style guide file](../instructions/styleguide-instructions.md) as a guide. -4. Make sure the titles on the page provide better context about the content (for an improved search experience). -5. Ensure all the components formatted correctly. -6. Improve the SEO keywords. -7. If you find numbered lists, make sure their numbering only uses 1's. -8. Ensure each line is limited to 80 characters. - -Do your best and don't be lazy. \ No newline at end of file diff --git a/.github/prompts/freshness-tier2.prompt.md b/.github/prompts/freshness-tier2.prompt.md deleted file mode 100644 index e6cd05cba72e..000000000000 --- a/.github/prompts/freshness-tier2.prompt.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -mode: 'edit' ---- - -Imagine you're an experienced technical writer. You need to review content for -how fresh and up to date it is. Apply the following: - -1. Improve the presentational layer - components, splitting up the page into smaller pages - Consider the following: - - 1. Can you use tabs to display multiple variants of the same steps? - 2. Can you make a key item of information stand out with a call-out? - 3. Can you reduce a large amount of text to a series of bullet points? - 4. Are there other code components you could use? -2. Check if any operating systems or package versions mentioned are still current and supported -3. Check the accuracy of the content -4. If appropriate, follow the document from start to finish to see if steps make sense in sequence -5. Try to add some helpful next steps to the end of the document, but only if there are no *Next steps* or *Related pages* section, already. -6. Try to clarify, shorten or improve the efficiency of some sentences. -7. Check for LLM readability. -8. Ensure each line is limited to 80 characters. - -Do your best and don't be lazy. diff --git a/.github/prompts/review.prompt.md b/.github/prompts/review.prompt.md deleted file mode 100644 index 47a39e8e14c5..000000000000 --- a/.github/prompts/review.prompt.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -mode: edit -description: You are a technical writer reviewing an article for clarity, conciseness, and adherence to the documentation writing style guidelines. ---- -Review the article for clarity, conciseness, and adherence to our documentation [style guidelines](../instructions/styleguide-instructions.md). - -Provide concrete and practical suggestions for improvement. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 161fd2bdfffc..d3321d62e873 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -35,7 +35,9 @@ jobs: with: files: | docker-bake.hcl - targets: releaser-build + targets: | + releaser-build + releaser-test build: runs-on: ubuntu-24.04 @@ -70,6 +72,7 @@ jobs: validate: runs-on: ubuntu-24.04 + continue-on-error: ${{ matrix.target == 'validate-api-reference' }} strategy: fail-fast: false matrix: @@ -81,6 +84,7 @@ jobs: - test-go-redirects - dockerfile-lint - validate-vendor + - validate-api-reference steps: - name: Checkout @@ -104,6 +108,6 @@ jobs: name: Run reviewdog for vale if: ${{ matrix.target == 'vale' && github.event_name == 'pull_request' }} run: | - cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -fail-on-error=false -filter-mode=added -level=info -fail-level=warning + cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -filter-mode=added -level=info -fail-level=warning env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/nightly-docs-scan.yml b/.github/workflows/nightly-docs-scan.yml index 1fbd17afa916..24022dda42fe 100644 --- a/.github/workflows/nightly-docs-scan.yml +++ b/.github/workflows/nightly-docs-scan.yml @@ -66,7 +66,7 @@ jobs: echo "GITHUB_APP_TOKEN=$PAT" >> "$GITHUB_ENV" - name: Run documentation scan - uses: docker/cagent-action@f208610469d69f20983cad64c577949a132caa33 # v1.5.3 + uses: docker/docker-agent-action@e96a4bb40cac114f64358621e1d08346c8eadc8c # v2.0.1 env: GH_TOKEN: ${{ env.GITHUB_APP_TOKEN || github.token }} with: diff --git a/.github/workflows/pr-review-trigger.yml b/.github/workflows/pr-review-trigger.yml index c176020256e5..4606240577a2 100644 --- a/.github/workflows/pr-review-trigger.yml +++ b/.github/workflows/pr-review-trigger.yml @@ -1,7 +1,7 @@ name: PR Review - Trigger on: pull_request: - types: [ready_for_review, opened, review_requested] + types: [opened, review_requested] pull_request_review_comment: types: [created] @@ -9,18 +9,26 @@ permissions: {} jobs: save-context: + if: > + github.event_name != 'pull_request' || + github.event.action != 'review_requested' || + github.event.requested_reviewer.login == 'docker-agent' runs-on: ubuntu-latest steps: - name: Save event context env: PR_NUMBER: ${{ github.event.pull_request.number }} PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} + REQUESTED_REVIEWER: ${{ github.event.requested_reviewer.login }} COMMENT_JSON: ${{ toJSON(github.event.comment) }} run: | mkdir -p context printf '%s' "${{ github.event_name }}" > context/event_name.txt printf '%s' "$PR_NUMBER" > context/pr_number.txt printf '%s' "$PR_HEAD_SHA" > context/pr_head_sha.txt + if [ "${{ github.event_name }}" = "pull_request" ]; then + printf '%s' "$REQUESTED_REVIEWER" > context/requested_reviewer.txt + fi if [ "${{ github.event_name }}" = "pull_request_review_comment" ]; then printf '%s' "$COMMENT_JSON" > context/comment.json fi diff --git a/.github/workflows/pr-review.yml b/.github/workflows/pr-review.yml index 60d16270b166..e91f1f3c99fc 100644 --- a/.github/workflows/pr-review.yml +++ b/.github/workflows/pr-review.yml @@ -11,10 +11,7 @@ permissions: jobs: review: - if: | - github.event_name == 'issue_comment' || - github.event.workflow_run.conclusion == 'success' - uses: docker/cagent-action/.github/workflows/review-pr.yml@f208610469d69f20983cad64c577949a132caa33 # v1.5.3 + uses: docker/docker-agent-action/.github/workflows/review-pr.yml@06e1767af06263c93d712449cbf859778d9392ee # v2.0.5 # Scoped to the job so other jobs in this workflow aren't over-permissioned permissions: contents: read # Read repository files and PR diffs @@ -22,7 +19,7 @@ jobs: issues: write # Create security incident issues if secrets detected checks: write # (Optional) Show review progress as a check run id-token: write # Required for OIDC authentication to AWS Secrets Manager - actions: read # Download artifacts from trigger workflow + actions: write # Download artifacts from trigger workflow with: trigger-run-id: ${{ github.event_name == 'workflow_run' && format('{0}', github.event.workflow_run.id) || '' }} add-prompt-files: STYLE.md,COMPONENTS.md @@ -37,11 +34,24 @@ jobs: ## Priority Issues ### 1. Vendored/Generated Content (CRITICAL - Auto-reject) - Flag if changes touch: + Check for vendored or generated files before reviewing any changed content. + Treat these paths as vendored/generated: - Any file in `_vendor/` directory (vendored from upstream repos) - Any YAML file in `data/*/*.yaml` subdirectories (CLI reference data generated from upstream) - Examples: `data/engine-cli/*.yaml`, `data/buildx/*.yaml`, `data/scout-cli/*.yaml` - Exception: root-level data/ files are manually maintained (allow edits) + - `content/reference/api/ai-governance/api.yaml` (verbatim copy of the upstream OpenAPI spec, vendored from the private docker/governor-services repo via `hack/sync-governance-api.sh`) + + If all changed files are vendored/generated: + - Leave at most one PR-level review comment. + - Do not leave inline comments. + - Do not review style, wording, markdown, command accuracy, links, or content quality inside those files. + - Say only that the PR edits vendored/generated content, identify the affected path pattern, and direct the author to make the change upstream and sync it back. + + If a PR changes both vendored/generated files and hand-authored files: + - Leave one comment for the vendored/generated file issue. + - Review only the hand-authored files for the remaining priority issues below. + - Do not leave style, wording, markdown, command accuracy, link, or content-quality comments on vendored/generated files. ### 2. Missing Redirects When Removing/Moving Pages (HIGH) When a PR removes or moves a page: diff --git a/.github/workflows/sync-docker-agent-docs.yml b/.github/workflows/sync-docker-agent-docs.yml new file mode 100644 index 000000000000..3f24f332ca56 --- /dev/null +++ b/.github/workflows/sync-docker-agent-docs.yml @@ -0,0 +1,130 @@ +name: sync-docker-agent-docs + +on: + schedule: + # Run daily at 02:30 UTC, offset from sync-cli-docs + - cron: '30 2 * * *' + workflow_dispatch: + inputs: + version: + description: "(optional) docker-agent version - defaults to the latest release tag" + required: false + default: "" + pull_request: + paths: + - '.github/workflows/sync-docker-agent-docs.yml' + +permissions: + contents: write + pull-requests: write + +env: + BRANCH_NAME: "bot/sync-docker-agent-docs" + MODULE_NAME: "github.com/docker/docker-agent" + +jobs: + sync-docker-agent-docs: + runs-on: ubuntu-24.04 + steps: + - + name: Checkout docs repo + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + fetch-depth: 0 + - + name: Get target version + id: get-version + env: + GH_TOKEN: ${{ github.token }} + run: | + if [ -n "${{ inputs.version }}" ]; then + VERSION="${{ inputs.version }}" + else + VERSION=$(gh release view --repo docker/docker-agent --json tagName --jq .tagName) + fi + CURRENT=$(go list -m -f '{{ .Version }}' "$MODULE_NAME" || true) + + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + echo "current=$CURRENT" >> "$GITHUB_OUTPUT" + echo "docker-agent version: **$VERSION** (currently pinned: **$CURRENT**)" | tee -a "$GITHUB_STEP_SUMMARY" + - + name: Set up Docker Buildx + if: steps.get-version.outputs.version != steps.get-version.outputs.current + uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4 + - + # go mod edit sets the version before plain make vendor: passing + # VENDOR_MODULE would run hugo mod get, which records docker-agent's + # full transitive graph as indirect requires in go.mod. + name: Update vendor + if: steps.get-version.outputs.version != steps.get-version.outputs.current + run: | + go mod edit -require "${MODULE_NAME}@${{ steps.get-version.outputs.version }}" + make vendor + - + name: Detect changes + id: changes + if: steps.get-version.outputs.version != steps.get-version.outputs.current + run: | + if [ -n "$(git status --porcelain)" ]; then + echo "changes=true" >> "$GITHUB_OUTPUT" + echo "Changes detected - syncing Docker Agent docs" >> "$GITHUB_STEP_SUMMARY" + else + echo "changes=false" >> "$GITHUB_OUTPUT" + echo "No changes to sync - Docker Agent docs are up to date" >> "$GITHUB_STEP_SUMMARY" + fi + - + name: Commit changes + if: steps.changes.outputs.changes == 'true' + env: + BRANCH_NAME: ${{ env.BRANCH_NAME }} + VERSION: ${{ steps.get-version.outputs.version }} + run: | + git checkout -b "$BRANCH_NAME" + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add -A + git commit -m "docker-agent: sync docs with docker-agent $VERSION" + - + name: Create or update Pull Request + if: steps.changes.outputs.changes == 'true' && github.event_name != 'pull_request' + env: + GH_TOKEN: ${{ github.token }} + BRANCH_NAME: ${{ env.BRANCH_NAME }} + PR_TITLE: "docker-agent: sync docs with docker-agent ${{ steps.get-version.outputs.version }}" + PR_BODY: | + ## Summary + + Automated sync of Docker Agent documentation from the docker/docker-agent repository. + + **docker-agent version:** ${{ steps.get-version.outputs.version }} + + --- + + > [!IMPORTANT] + > **Reviewer:** Please close and reopen this PR to trigger CI checks. + > See: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow + run: | + # Check for existing open PR from this branch + EXISTING_PR=$(gh pr list --state open --head "$BRANCH_NAME" --json url --jq ".[0].url // empty") + + if [ -n "$EXISTING_PR" ]; then + echo "Updating existing PR: $EXISTING_PR" >> "$GITHUB_STEP_SUMMARY" + git push -u origin "$BRANCH_NAME" --force + gh pr edit "$EXISTING_PR" --title "$PR_TITLE" --body "$PR_BODY" + else + # Check if a closed PR with the same title already exists + CLOSED_PR=$(gh pr list --state closed --search "$PR_TITLE in:title" --json url --jq ".[0].url // empty") + if [ -n "$CLOSED_PR" ]; then + echo "A closed PR already exists for this version: $CLOSED_PR" >> "$GITHUB_STEP_SUMMARY" + echo "Skipping PR creation." + exit 0 + fi + + echo "Creating new PR" >> "$GITHUB_STEP_SUMMARY" + git push -u origin "$BRANCH_NAME" + gh pr create \ + --title "$PR_TITLE" \ + --body "$PR_BODY" \ + --base main \ + --head "$BRANCH_NAME" + fi diff --git a/.gitignore b/.gitignore index 7c450914435b..0385479d8ddf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,9 +11,9 @@ public resources static/pagefind tmp +_vale/Docker/ # Binary installed by cagent-action in CI cagent # cagent tmp files .cagent .pr-body.md -.validation.log diff --git a/.htmltest.yml b/.htmltest.yml index ea2330397f44..e6a29e2b2291 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -7,11 +7,9 @@ IgnoreAltEmpty: true IgnoreEmptyHref: true IgnoreDirectoryMissingTrailingSlash: true IgnoreURLs: -- "^/reference/api/hub/.*$" -- "^/reference/api/engine/v.+/#.*$" -- "^/reference/api/registry/.*$" -- "^/pagefind/.*$" + - "^/reference/api/engine/v.+/#.*$" + - "^/pagefind/.*$" IgnoreDirs: -- "registry/configuration" -- "compose/compose-file" # temporarily ignore until upstream is fixed + - "registry/configuration" + - "compose/compose-file" # temporarily ignore until upstream is fixed CacheExpires: "6h" diff --git a/.markdownlint.json b/.markdownlint.json deleted file mode 100644 index eecf08fddf6b..000000000000 --- a/.markdownlint.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "default": false, - "blanks-around-headings": true, - "hr-style": true, - "heading-start-left": true, - "single-h1": true, - "no-trailing-punctuation": true, - "no-missing-space-atx": true, - "no-multiple-space-atx": true, - "no-missing-space-closed-atx": true, - "no-multiple-space-closed-atx": true, - "no-space-in-emphasis": true, - "no-space-in-code": true, - "no-space-in-links": true, - "no-empty-links": true, - "ol-prefix": { "style": "one_or_ordered" }, - "no-reversed-links": true, - "reference-links-images": { - "shortcut_syntax": false - }, - "fenced-code-language": true, - "table-pipe-style": true, - "table-column-count": true, - "descriptive-link-text": { "prohibited_texts": ["click here","here","link","more","learn more","find out more"]} -} diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 000000000000..74756670b804 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,2 @@ +**/*.md +/data/api-reference.json diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 000000000000..9ad17f216170 --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,44 @@ +[global] +flavor = "hugo" +enable = [ + "MD011", + "MD018", + "MD019", + "MD020", + "MD021", + "MD022", + "MD023", + "MD025", + "MD026", + "MD029", + "MD035", + "MD037", + "MD038", + "MD039", + "MD040", + "MD042", + "MD052", + "MD055", + "MD056", + "MD059", +] +exclude = [ + "content/manuals/desktop/previous-versions/*.md", + "content/manuals/engine/release-notes/*.md", +] + +[MD029] +style = "one_or_ordered" + +[MD052] +shortcut-syntax = false + +[MD059] +prohibited-texts = [ + "click here", + "here", + "link", + "more", + "learn more", + "find out more", +] diff --git a/.sbx/kits/hugo/spec.yaml b/.sbx/kits/hugo/spec.yaml new file mode 100644 index 000000000000..815ddac9f7d3 --- /dev/null +++ b/.sbx/kits/hugo/spec.yaml @@ -0,0 +1,52 @@ +schemaVersion: "2" +kind: mixin +name: hugo +displayName: Hugo +description: Installs the Hugo Extended static site generator from a pinned GitHub release. + +permissions: + network: + allow: + # Release tarball download (install time, one-shot). + # github.com 302-redirects to release-assets.githubusercontent.com for binary downloads. + - github.com + - release-assets.githubusercontent.com + +setup: + install: + - command: | + set -euo pipefail + # Keep in sync with ARG HUGO_VERSION in this repo's Dockerfile. + HUGO_VERSION=0.163.0 + ARCH=$(dpkg --print-architecture) + case "$ARCH" in + amd64) + TARBALL="hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz" + SHA256="6291775b7d012f9b10fb377ba914e5b1589c0b0d2531b695fa9029be14750111" + ;; + arm64) + TARBALL="hugo_extended_${HUGO_VERSION}_linux-arm64.tar.gz" + SHA256="ed50d3ec8c5b427013137e38718a5d398a90956ce9e3a8a3cb7ebf3fdd01072b" + ;; + *) + echo "unsupported arch: $ARCH" >&2 + exit 1 + ;; + esac + curl --proto '=https' --tlsv1.2 -fsSL \ + -o /tmp/hugo.tgz \ + "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/${TARBALL}" + echo "${SHA256} /tmp/hugo.tgz" | sha256sum -c - + tar -C /usr/local/bin -xzf /tmp/hugo.tgz hugo + rm /tmp/hugo.tgz + hugo version + user: "0" + description: "Install pinned Hugo Extended CLI" + +agentInstructions: + content: | + ## Hugo static site generator + + The `hugo` CLI (extended edition, v0.163.0) is installed and available on + `PATH`. This repository builds https://docs.docker.com/ with Hugo. Run + `hugo version` to confirm, and `hugo server` to preview the site locally. diff --git a/.sbx/kits/rumdl/spec.yaml b/.sbx/kits/rumdl/spec.yaml new file mode 100644 index 000000000000..dfda7f855b88 --- /dev/null +++ b/.sbx/kits/rumdl/spec.yaml @@ -0,0 +1,52 @@ +schemaVersion: "2" +kind: mixin +name: rumdl +displayName: rumdl +description: Installs the rumdl Markdown linter/formatter from a pinned GitHub release, matching the version this repository uses. + +permissions: + network: + allow: + # Release tarball download (install time, one-shot). + # github.com 302-redirects to release-assets.githubusercontent.com for binary downloads. + - github.com + - release-assets.githubusercontent.com + +setup: + install: + - command: | + set -euo pipefail + # Keep in sync with the "rumdl" devDependency version in this repo's package.json. + RUMDL_VERSION=0.2.49 + ARCH=$(dpkg --print-architecture) + case "$ARCH" in + amd64) + TARBALL="rumdl-v${RUMDL_VERSION}-x86_64-unknown-linux-gnu.tar.gz" + SHA256="e208db27143592a18b26d9d42e6e76133a2dcdb8738d2ed0f8d3b44027b2d8d6" + ;; + arm64) + TARBALL="rumdl-v${RUMDL_VERSION}-aarch64-unknown-linux-gnu.tar.gz" + SHA256="b57cfdc83f4bbe0714c4a7642464107a5c64f258d5925d67bc9b3816dbe0701a" + ;; + *) + echo "unsupported arch: $ARCH" >&2 + exit 1 + ;; + esac + curl --proto '=https' --tlsv1.2 -fsSL \ + -o /tmp/rumdl.tgz \ + "https://github.com/rvben/rumdl/releases/download/v${RUMDL_VERSION}/${TARBALL}" + echo "${SHA256} /tmp/rumdl.tgz" | sha256sum -c - + tar -C /usr/local/bin -xzf /tmp/rumdl.tgz rumdl + rm /tmp/rumdl.tgz + rumdl --version + user: "0" + description: "Install pinned rumdl CLI" + +agentInstructions: + content: | + ## rumdl Markdown linter + + The `rumdl` CLI is installed and available on `PATH`. Format a Markdown + file with `rumdl fmt <file>` and lint it with `rumdl check <file>` (or + the project's `scripts/lint.sh <file>...`, which also runs Vale). diff --git a/.vale.ini b/.vale.ini index 398c9a2fd843..53a3c21eb821 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,36 +1,39 @@ StylesPath = _vale MinAlertLevel = suggestion IgnoredScopes = text.frontmatter, code, tt, b, strong, i, a +Packages = https://github.com/docker/docs-toolkit/releases/download/v0.1.0/Docker.zip Vocab = Docker # Generated reference content — disable rules that don't apply [content/reference/**] Docker.Capitalization = NO -Vale.Spelling = NO -Vale.Terms = NO +Docker.CanonicalNames = NO +Docker.IndustryTerms = NO # Skip release notes and old desktop changelog content entirely [{content/manuals/*/release-notes.md,content/manuals/*/release-notes/**,content/manuals/**/release-notes.md,content/manuals/desktop/previous-versions/**}] Docker.Avoid = NO Docker.Capitalization = NO +Docker.CanonicalNames = NO Docker.Exclamation = NO -Docker.Forbidden = NO Docker.GenericCTA = NO Docker.HeadingPunctuation = NO +Docker.IndustryTerms = NO Docker.ListComma = NO +Docker.MetaCommentary = NO Docker.OxfordComma = NO +Docker.PromotionalOpeners = NO Docker.RecommendedWords = NO Docker.Spacing = NO -Docker.Terms = NO Docker.URLFormat = NO Docker.Units = NO Docker.VersionText = NO Docker.We = NO -Vale.Spelling = NO Vale.Repetition = NO -Vale.Terms = NO [*.md] BasedOnStyles = Docker, Vale +Vale.Spelling = NO +Vale.Terms = NO TokenIgnores = ({{[^}]+}}\S*) BlockIgnores = (?m)^[ \t]*({{[^}]+}})[ \t]*$, (\[[^\]]*{{[^}]+}}[^\]]*\]\([^)]*\)), ({{<\s*file\s[^>]*>}}[\s\S]*?{{<\s*/\s*file\s*>}}) diff --git a/AGENTS.md b/AGENTS.md index a315461cd21c..6d7199a746e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ This site builds https://docs.docker.com/ using Hugo. ## Project structure -``` +```text content/ # Documentation source (Markdown + Hugo front matter) ├── manuals/ # Product docs (Engine, Desktop, Hub, etc.) ├── guides/ # Task-oriented guides @@ -45,10 +45,16 @@ must go to the source repository: | Model Runner reference | docker/model-runner | | Dockerfile reference | moby/buildkit | | Engine API reference | moby/moby | +| AI Governance API (`content/reference/api/ai-governance/api.yaml`) | docker/governor-services (private) | If a validation failure or broken link traces back to vendored content, note the upstream repo that needs fixing. Do not attempt to fix it locally. +`content/reference/api/ai-governance/api.yaml` is a verbatim copy of the +upstream `openapi.yaml` — do not edit it by hand. Re-vendor it with +`hack/sync-governance-api.sh`, which fetches the latest spec from the private +`docker/governor-services` repo (using your own `gh` auth). + ## Writing guidelines Read and follow [STYLE.md](STYLE.md) and [COMPONENTS.md](COMPONENTS.md). @@ -99,6 +105,21 @@ silence individual violations. - Don't add a wrong-cased entry to silence one false positive — it cascades into `Vale.Terms` violations on every correct usage. +## Human-readable prose + +For PR titles and descriptions, documentation, release notes, design documents, +comments, and other reader-facing prose: + +- Write so readers understand the meaning on the first read +- Use wording that an experienced colleague would plausibly say aloud +- Prefer verbs and clauses over invented nouns and compressed noun phrases +- Treat correct grammar as necessary but insufficient for clear writing +- Before returning prose, silently rewrite wording that is technically + interpretable but unnatural or hard to decode + +Keep established technical terms and qualifications needed for accuracy. +Use the write skill's prose review to catch patterns that lint cannot detect. + ## Alpine.js patterns Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the @@ -113,13 +134,61 @@ Every content page under `content/` requires: - `title:` — page title - `description:` — short description for SEO/previews -- `keywords:` — list of search keywords (omitting this fails markdownlint) +- `keywords:` — list of search keywords Additional common fields: - `linkTitle:` — sidebar label (keep under 30 chars) - `weight:` — ordering within a section +## Sidebar navigation + +The section sidebar is rendered by +`layouts/_partials/sidebar/sections.html`. It starts at `.FirstSection` and +recursively walks each section's `.Pages`. Page weight controls the default +order. Section front matter can group entries with `sidebar.groups`, reverse +their order with `sidebar.reverse`, override a link with `sidebar.goto`, and +add a badge with `sidebar.badge`. + +The sidebar expands the current page's ancestor sections and marks the current +page with `aria-current`. When changing the recursive templates, pass all +navigation state through both `renderChildren` and `renderList`. Keep the page +filter and the `$hasChildren` calculation aligned so an expand control never +points to an empty list or disappears for a rendered list. + +## Hidden pages + +Set `sitemap: false` to hide a page from site-wide discovery. This setting: + +- Excludes the page from `sitemap.xml`, `metadata.json`, and `llms-full.txt` +- Excludes the page body from the site search index +- Adds a `noindex` robots meta tag + +The page is still built and remains available through direct links. This is +not an access control mechanism. + +Hugo does not automatically apply `sitemap: false` from a section page to its +descendants. To hide an entire subtree, cascade the value from the section's +`_index.md`: + +```yaml +sitemap: false +cascade: + sitemap: false +``` + +## Hidden sections in the sidebar + +The sidebar uses `sitemap` as a navigation visibility filter. A hidden page is +absent from the sidebar outside its active navigation path. The current page +and its ancestors remain visible so direct links to hidden pages do not produce +an empty navigation path. + +When the active path enters a hidden section, `revealHidden` propagates down +that branch and renders the whole hidden subtree. This keeps the section's +navigation available while you are in it. The state must remain scoped to that +branch so unrelated hidden pages stay hidden. + ## Hugo shortcodes Shortcodes are defined in `layouts/shortcodes/`. Syntax reference is in @@ -129,17 +198,26 @@ produces broken HTML — always check COMPONENTS.md for correct syntax. ## Commands ```sh -npx prettier --write <file> # Format before committing -scripts/lint.sh <file>... # Lint specific files (markdownlint + vale) +npx --no-install rumdl fmt <file> # Format Markdown before committing +npx prettier --write <file> # Format non-Markdown files +scripts/lint.sh <markdown-file>... # Lint specific files (rumdl + Vale) docker buildx bake validate # Run all validation checks docker buildx bake lint # Markdown linting only docker buildx bake vale # Style guide checks only docker buildx bake test # HTML and link checking ``` -For incremental work, prefer `scripts/lint.sh` over the `bake` targets — -it runs the same checks on just the files you pass, so the output stays -scoped to your changes instead of the whole repo. +`npx --no-install` uses the repository-pinned rumdl binary and never downloads +a replacement. If the binary is unavailable, run `npm ci` to install the +repository dependencies. Install Vale separately. + +For incremental work, prefer `scripts/lint.sh` over the `bake` targets. Pass +only the Markdown files you changed so the output stays scoped instead of +including the whole repository. + +Vale exits successfully when it reports only warnings or suggestions. Read the +full output: fix errors and warnings on lines you added or changed, and review +each suggestion. Don't expand the change to unrelated alerts in existing text. ### Validation in git worktrees @@ -151,11 +229,11 @@ and `validate-vendor` targets run correctly in CI. ## Verification loop 1. Make changes -2. Format with prettier: `npx prettier --write <file>` -3. Lint the changed files: `scripts/lint.sh <file>...` +2. Format Markdown with rumdl: `npx --no-install rumdl fmt <file>` +3. Lint the changed Markdown files: `scripts/lint.sh <markdown-file>...` 4. Run a full build with `docker buildx bake` (optional for small changes) -Always lint the specific files you changed before committing. Use +Always lint the specific Markdown files you changed before committing. Use `scripts/lint.sh` rather than the `bake` targets so the output is scoped to your changes — bake runs across the entire repo and the noise makes real issues easy to miss. diff --git a/COMPONENTS.md b/COMPONENTS.md index 69eeef375181..34cf8aeef22d 100644 --- a/COMPONENTS.md +++ b/COMPONENTS.md @@ -86,6 +86,15 @@ params: | time | Estimated time to complete | | prerequisites | Prerequisites or "None" | +### Catalog navigation + +Set `params.sidebar.activeChildrenOnly: true` on a section to show only its +active child in the sidebar. Other children remain available in search and +the sitemap. Sidebar group headings are omitted in this mode. + +For a recipe catalog, set `params.recipeCatalog: true` on the section to add +a **Browse all recipes** link to each recipe page. + ## Shortcodes Shortcodes are reusable components that add rich functionality to your @@ -262,6 +271,25 @@ params: - Use green for new GA features - Use gray for deprecated features +### Setting metadata + +Use `setting-metadata` below a setting's heading to display its type, default, +and optional environment variable. Keep explanations and examples in the page +body. The component uses a definition list with wrapping values and preserves +the metadata in Markdown output. + +```markdown +{{</* setting-metadata + type="boolean" + default="false" + env="DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE" +*/>}} +``` + +The `type` and `default` parameters are required. Omit `env` when the setting +has no environment variable equivalent. Use `default="Empty string"` for an +empty string default. + ### Summary bars Summary bars indicate subscription requirements, version requirements, or @@ -296,7 +324,7 @@ features: | subscription | Subscription tier required | All, Personal, Pro, Team, Business | | availability | Product development stage | Experimental, Beta, Early Access, GA, Retired | | requires | Minimum version requirement | String describing version (link to release notes) | -| for | Indicates administrator-only features | Administrators | +| for | Audience for the feature | Administrators, Individuals | ### Buttons @@ -308,6 +336,18 @@ Create styled buttons for calls to action. {{</* button text="Download Docker Desktop" url="/get-docker/" */>}} ``` +### Copy as prompt + +Wrap a section with `copy-as-prompt` to add a **Copy as prompt** button. The +button copies the instruction followed by the section's source Markdown. +The section remains visible and appears in the page's Markdown output. + +```markdown +{{</* copy-as-prompt instruction="Update this project using the migration reference below." */>}} +Migration reference content +{{</* /copy-as-prompt */>}} +``` + ### Cards Create card layouts for organizing content. @@ -322,6 +362,18 @@ Create card layouts for organizing content. */>}} ``` +### Recipe lists + +List a section's recipes by their `params.sidebar.group` value: + +```markdown +{{</* recipe-list group="Working in a sandbox" */>}} +``` + +The list uses each page's sidebar title and description, ordered by page +weight. It renders in two columns on larger screens and one column on smaller +screens. The Markdown output includes the same links and descriptions. + ### Icons Use Material Symbols icons in your content. diff --git a/Dockerfile b/Dockerfile index 117b22f872d9..766ace607bb9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,10 +4,11 @@ ARG ALPINE_VERSION=3.23 ARG GO_VERSION=1.26 ARG HTMLTEST_VERSION=0.17.0 -ARG VALE_VERSION=3.11.2 +ARG VALE_VERSION=3.17.0 ARG HUGO_VERSION=0.163.0 ARG NODE_VERSION=24 ARG PAGEFIND_VERSION=1.5.2 +ARG TARGETARCH # base defines the generic base stage FROM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS base @@ -58,15 +59,44 @@ RUN --mount=type=cache,target=/tmp/hugo_cache \ --printUnusedTemplates \ -b $DOCS_URL \ -e $HUGO_ENV -RUN ./hack/flatten-and-resolve.js public +RUN node --test hack/test/flatten-and-resolve.mjs +RUN node hack/flatten-and-resolve.js public +RUN node hack/api-docs/verify-output.mjs public # lint lints markdown files -FROM ghcr.io/igorshubovych/markdownlint-cli:v0.45.0 AS lint -RUN --mount=type=bind,target=. \ - markdownlint \ - "content/**/*.md" \ - --ignore "content/manuals/engine/release-notes/*.md" \ - --ignore "content/manuals/desktop/previous-versions/*.md" +FROM ghcr.io/rvben/rumdl:0.2.49-alpine AS lint +RUN --mount=type=bind,target=. rumdl check content + +# vacuum downloads the prebuilt validator for the target architecture +FROM scratch AS vacuum-amd64 +ADD --unpack --checksum=sha256:973b8ed30cd36533da4cdb76729e833324a3043bad48c74f61b6a1cc3df40b78 \ + https://github.com/daveshanley/vacuum/releases/download/v0.30.3/vacuum_0.30.3_linux_x86_64.tar.gz /out/ + +FROM scratch AS vacuum-arm64 +ADD --unpack --checksum=sha256:04b604df0b1b570d5abd58b577c816122da162eb8ba12a7f70c3060aec12b3a9 \ + https://github.com/daveshanley/vacuum/releases/download/v0.30.3/vacuum_0.30.3_linux_arm64.tar.gz /out/ + +FROM vacuum-${TARGETARCH} AS vacuum + +# validate-api-reference checks the vendored presentation data +FROM base AS validate-api-reference +RUN apk add --no-cache bash +WORKDIR /project +COPY --from=vacuum /out/vacuum /usr/local/bin/vacuum +COPY hack/api-docs ./hack/api-docs +COPY content/reference/api ./content/reference/api +COPY data/api-reference.json ./data/api-reference.json +RUN --mount=type=cache,target=/go/pkg/mod \ + --mount=type=cache,target=/root/.cache/go-build <<"EOT" +set -eu +cp data/api-reference.json /tmp/api-reference-committed.json +./hack/api-docs/run.sh test +./hack/api-docs/run.sh generate +if ! cmp -s /tmp/api-reference-committed.json data/api-reference.json; then + echo >&2 'ERROR: API reference data is stale. Run ./hack/api-docs/run.sh generate and commit data/api-reference.json.' + exit 1 +fi +EOT # test validates HTML output and checks for broken links FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test diff --git a/STYLE.md b/STYLE.md index aca8d1477e74..6909b4b28a4c 100644 --- a/STYLE.md +++ b/STYLE.md @@ -81,6 +81,43 @@ These phrases add no value - state the fact directly: - **Write timelessly**: Avoid "currently" or "as of this writing" - the documentation describes the product as it is today +### Explain technical behavior + +Explain behavior from the reader's perspective. Lead with the observable +outcome, then add the implementation details needed to explain it. + +Prefer: + +> Changes made by the agent stay inside the sandbox until you fetch them. The +> agent works in a separate Git clone inside the sandbox. + +Avoid: + +> A session that works directly in the sandbox clone still can't modify your +> host repository. + +The preferred version tells readers where changes happen and when they become +visible. The second version makes readers reconstruct the relationship between +the session, sandbox clone, and host repository. + +Separate guarantees from variable behavior. Don't present behavior controlled +by another tool as a product default or guarantee. When behavior varies, +structure the explanation in this order: + +1. State what always happens +2. State what the product doesn't control +3. Tell the reader what to do + +For example: + +> The `--clone` flag creates the clone, but it doesn't separate one task from +> another. To keep parallel tasks isolated, instruct your agent tool to create +> a separate branch or worktree for each task. + +Avoid chains of qualifications such as "may," "can," and "depends" that leave +the reader without a conclusion. Keep qualifiers that are needed for accuracy. +State what controls the behavior and what the reader should do. + ### Scope preservation When updating existing documentation, resist the urge to expand @@ -109,6 +146,10 @@ remake it. Good additions fill genuine gaps. Bad additions change the document's character. When in doubt, add less rather than more. +Include caveats, failure scenarios, and fallback behavior only when they affect +a decision or action. Don't turn a clarification into a catalog of edge +cases. + ## Grammar and style Write in US English with US grammar. @@ -146,7 +187,11 @@ Use contractions to maintain a conversational tone, but don't overdo it. - Never contract a noun with a verb (your container is ready, not your container's ready) -### Dangling modifiers +### Clear subjects and modifiers + +Name the actor when a system includes multiple tools or components. Repeat the +noun instead of using an ambiguous pronoun. For example, distinguish between +what a CLI creates, what an agent edits, and what remains on the host. Avoid unclear subjects: @@ -180,6 +225,11 @@ Avoid unclear subjects: Remove unnecessary words to make documentation clearer and more direct. +Keep an adjective or qualifier only when it changes how readers understand the +behavior or complete the task. If removing it doesn't change an outcome, +decision, or next step, remove it. Apply the same test to implementation +details. + **Eliminate redundant phrases:** - ❌ "in order to" → ✅ "to" @@ -305,6 +355,19 @@ don't front-load complexity. - Don't use "**Bold:** format" for subsection labels (use plain text with colon) +### Guide structure + +Guides are single-page - don't split a guide into multiple sub-pages +(for example, separate "overview", "configure", and "deploy" pages for +one guide). Cover the full task on one page and use headings to +organize sections. + +Store each guide as a single Markdown file directly under +`content/guides/` (for example, `content/guides/django.md`), not +wrapped in its own directory with an `index.md`. Guide images belong in +the shared `content/guides/images/` folder, prefixed with the guide's +slug, not in a per-guide directory - see [Images](STYLE.md#images). + ### Lists - Limit bulleted lists to five items when possible @@ -396,6 +459,13 @@ For code block syntax, language hints, variables, and advanced features - Compress images before adding to repository - Remove unused images from repository +**File organization:** + +- Store guide images in the shared `content/guides/images/` folder, + not in a per-guide directory +- Prefix filenames with the guide's slug to avoid collisions (for + example, `kafka-architecture.webp`) + For image syntax and parameters (sizing, borders), see [COMPONENTS.md](COMPONENTS.md#images). @@ -539,6 +609,7 @@ Common phrases to transform for clearer, more direct writing: - ✅ Direct and practical - ✅ Conversational with active voice - ✅ Specific and actionable +- ✅ Lead with observable outcomes - ❌ Corporate-speak - ❌ Condescending - ❌ Overly formal diff --git a/_vale/Docker/Avoid.yml b/_vale/Docker/Avoid.yml deleted file mode 100644 index d49063c80190..000000000000 --- a/_vale/Docker/Avoid.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "Consider removing '%s'." -ignorecase: true -level: warning -tokens: - - please - - very - - really diff --git a/_vale/Docker/Capitalization.yml b/_vale/Docker/Capitalization.yml deleted file mode 100644 index ab22a9d32f13..000000000000 --- a/_vale/Docker/Capitalization.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "Please capitalize Docker." -level: error -ignorecase: false -action: - name: replace - params: - - Docker -tokens: - - '[^\[/\-.]docker[^/\-.\w]' diff --git a/_vale/Docker/Exclamation.yml b/_vale/Docker/Exclamation.yml deleted file mode 100644 index 6059a42870b1..000000000000 --- a/_vale/Docker/Exclamation.yml +++ /dev/null @@ -1,11 +0,0 @@ -extends: existence -message: "Don't use exclamation points in text." -nonword: true -level: error -action: - name: edit - params: - - trim_right - - "!" -tokens: - - '\w+!(?:\s|$)' diff --git a/_vale/Docker/Forbidden.yml b/_vale/Docker/Forbidden.yml deleted file mode 100644 index d8b7a37ae8c9..000000000000 --- a/_vale/Docker/Forbidden.yml +++ /dev/null @@ -1,6 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -level: error -ignorecase: false -swap: - Docker CE: Docker Engine diff --git a/_vale/Docker/GenericCTA.yml b/_vale/Docker/GenericCTA.yml deleted file mode 100644 index 4f4b0bfa92e3..000000000000 --- a/_vale/Docker/GenericCTA.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "Avoid generic calls to action: '%s'" -link: https://docs.docker.com/contribute/style/formatting/#links -level: warning -scope: raw -ignorecase: true -raw: - - \[(click here|(find out|learn) more)\] diff --git a/_vale/Docker/HeadingPunctuation.yml b/_vale/Docker/HeadingPunctuation.yml deleted file mode 100644 index acb2c71651ed..000000000000 --- a/_vale/Docker/HeadingPunctuation.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: existence -message: "Don't put a period at the end of a heading." -nonword: true -level: warning -scope: heading -action: - name: edit - params: - - trim_right - - "." -tokens: - - '[a-z0-9][.]\s*$' diff --git a/_vale/Docker/ListComma.yml b/_vale/Docker/ListComma.yml deleted file mode 100644 index 2af0bc710ddc..000000000000 --- a/_vale/Docker/ListComma.yml +++ /dev/null @@ -1,6 +0,0 @@ -extends: existence -message: Don’t add commas (,) or semicolons (;) to the ends of list items. -link: https://docs.docker.com/contribute/style/grammar/#lists -level: warning -scope: list -raw: '[,;]$' diff --git a/_vale/Docker/OxfordComma.yml b/_vale/Docker/OxfordComma.yml deleted file mode 100644 index 57124a6e05ac..000000000000 --- a/_vale/Docker/OxfordComma.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Use the Oxford comma in '%s'." -scope: sentence -level: warning -nonword: true -tokens: - - '(?:[^\s,]+,){1,}\s\w+\s(?:and|or)\s\w+[.?!]' diff --git a/_vale/Docker/RecommendedWords.yml b/_vale/Docker/RecommendedWords.yml deleted file mode 100644 index 8a37d58f0e1f..000000000000 --- a/_vale/Docker/RecommendedWords.yml +++ /dev/null @@ -1,39 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of '%s'" -link: https://docs.docker.com/contribute/style/recommended-words/ -ignorecase: true -level: suggestion -action: - name: replace -swap: - '\b(?:eg|e\.g\.)[\s,]': for example - '\b(?:ie|i\.e\.)[\s,]': that is - (?:account name|accountname|user name): username - (?:drop down|dropdown): drop-down - \blog out\b: sign out - \b(?:sign on|log on|log in)\b: sign in - adaptor: adapter - administrate: administer - afterwards: afterward - allows: lets - alphabetic: alphabetical - alphanumerical: alphanumeric - anti-aliasing: antialiasing - anti-malware: antimalware - anti-spyware: antispyware - anti-virus: antivirus - appendixes: appendices - assembler: assembly - check box: checkbox - check boxes: checkboxes - click: select - distro: distribution - ergo: therefore - file name: filename - keypress: keystroke - mutices: mutexes - repo: repository - scroll: navigate - url: URL - '\bvs\b(?!\.|\s+Code)': versus - wish: want diff --git a/_vale/Docker/Spacing.yml b/_vale/Docker/Spacing.yml deleted file mode 100644 index 5c6d52af5933..000000000000 --- a/_vale/Docker/Spacing.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "'%s' should have one space." -level: error -scope: - - list - - heading - - paragraph -nonword: true -tokens: - - " {2,}" diff --git a/_vale/Docker/URLFormat.yml b/_vale/Docker/URLFormat.yml deleted file mode 100644 index ace679768dc1..000000000000 --- a/_vale/Docker/URLFormat.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -ignorecase: true -level: warning -action: - name: replace -swap: - URL for: URL of - an URL: a URL diff --git a/_vale/Docker/Units.yml b/_vale/Docker/Units.yml deleted file mode 100644 index 4e67c1ac2799..000000000000 --- a/_vale/Docker/Units.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'" -link: https://docs.docker.com/contribute/style/recommended-words/ -level: error -swap: - kilobytes?: kB - gigabytes?: GB - megabytes?: MB - petabytes?: PB - terabytes?: TB diff --git a/_vale/Docker/VersionText.yml b/_vale/Docker/VersionText.yml deleted file mode 100644 index 37061de8da20..000000000000 --- a/_vale/Docker/VersionText.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: existence -message: Use later when talking about version numbers. -link: https://docs.docker.com/contribute/style/recommended-words/#later -scope: raw -raw: - - '\bv?' - - '(?P<major>0|[1-9]\d*)\.' - - '(?P<minor>0|[1-9]\d*)' - - '(?:\.(?P<patch>0|[1-9]\d*))?' - - '(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?' - - '(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?' - - '\b (and|or) (higher|above)' diff --git a/_vale/Docker/We.yml b/_vale/Docker/We.yml deleted file mode 100644 index bc94d6da743a..000000000000 --- a/_vale/Docker/We.yml +++ /dev/null @@ -1,11 +0,0 @@ -extends: existence -message: "Avoid using first-person plural like '%s'." -level: warning -ignorecase: false -tokens: - - '[Ww]e' - - "[Ww]e'(?:ve|re)" - - '[Oo]urs?' - - us - - Us - - "[Ll]et's" diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 109b27394a9f..bb35ac04d5da 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -17,18 +17,18 @@ Artifactory armhf [Aa]uditability auditable +[Aa]utoconfiguration autolock [Aa]llowlist(ing)? Azure Azure AD [Bb]ackport +[Bb]enchmarked bootup Bitnami Btrfs Bugsnag -BuildKit buildkitd -BusyBox cagent CD CentOS @@ -68,23 +68,17 @@ Dex displayName Django DMR -Docker Build Cloud -Docker Business Docker Dashboard -Docker Desktop -Docker Engine Docker Extension -Docker Hub -Docker Scout -Docker Team Docker-Sponsored Open Source Docker's -Dockerfile dockerignore Dockerize Dockerized Dockerizing +Dependabot DuckDuckGo +Dynatrace Entra EPERM ESXi @@ -102,8 +96,6 @@ GeoNetwork GGUF Git Gitea -GitHub -GitHub Actions Google Gradle Grafana @@ -125,7 +117,6 @@ IPv[46] IPvlan isort Jamf -JavaScript JetBrains JFrog JUnit @@ -138,7 +129,6 @@ Kubeadm kubectl kubefwd kubelet -Kubernetes Laradock Laravel libseccomp @@ -149,7 +139,6 @@ logback Loggly Logstash lookup -macOS macvlan Mail(chimp|gun) mfsymlinks @@ -160,7 +149,6 @@ misconfiguration [Mm]ixins? monorepos? musl -MySQL nameserver namespaced? namespacing @@ -171,11 +159,10 @@ netlabel netlink Netplan NFSv\d -Nginx npm +nvm Nutanix Nuxeo -NVIDIA OAuth Okta Ollama @@ -194,13 +181,13 @@ pluggable Postgres psycopg pytest -PowerShell Python Qualcomm Quickview rebalance reimplement reloader +repinning Rego Rekor ROCm @@ -219,10 +206,12 @@ Sigstore Snyk Solr SonarQube +Sonatype Sonoma Splunk SQLite stargz +eStargz stdin stdout subfolder @@ -236,7 +225,6 @@ sysctls Sysdig systemd teleop -Testcontainers tmpfs Traefik Trivy @@ -254,7 +242,6 @@ Unix unmarshalling unmanaged upsert -Visual Studio Code VMware VPNKit vSphere @@ -284,9 +271,7 @@ Zsh [Aa]utobuilds? [Aa]utotests? [Aa]utoscaling -[Bb]uildx [Bb]uildpack(s)? -[Bb]uildx [Cc]odenames? [Cc]ompose [Cc]onfigs @@ -319,6 +304,7 @@ Zsh README [Rr]eal-time [Rr]egex(es)? +[Rr]uleset(s)? [Rr]untimes? [Ss]andbox(ed)? [Ss]eccomp @@ -350,7 +336,6 @@ README [Ee]vals? [Ll]abspaces? [Uu]nsloth -AppArmor [Aa]utolocking [Bb]oolean [Bb]reakpoint @@ -420,20 +405,24 @@ bootloader Buildkite crypto Graylog +Heartbleed Kubuntu Libnetwork lockfile Lubuntu multimodal multithreading +Log4Shell NLP Nodemon oldoldstable parallelizable PHPUnit pnpm -PyTorch +Shellshock +Spring4Shell superset tokenization WebGL Xubuntu +Netlify diff --git a/_vendor/github.com/docker/buildx/docs/bake-reference.md b/_vendor/github.com/docker/buildx/docs/bake-reference.md index a4f236fa5299..380d0b30fabc 100644 --- a/_vendor/github.com/docker/buildx/docs/bake-reference.md +++ b/_vendor/github.com/docker/buildx/docs/bake-reference.md @@ -43,7 +43,7 @@ The following attributes are overridden by the last occurrence: - `target.cache-to` - `target.dockerfile-inline` - `target.dockerfile` -- `target.outputs` +- `target.output` - `target.platforms` - `target.pull` - `target.tags` @@ -228,7 +228,7 @@ The following table shows the complete list of attributes that you can assign to | [`dockerfile-inline`](#targetdockerfile-inline) | String | Inline Dockerfile string | | [`dockerfile`](#targetdockerfile) | String | Dockerfile location | | [`entitlements`](#targetentitlements) | List | Permissions that the build process requires to run | -| [`extra-hosts`](#targetextra-hosts) | List | Customs host-to-IP mapping | +| [`extra-hosts`](#targetextra-hosts) | List | Custom host-to-IP mapping | | [`inherits`](#targetinherits) | List | Inherit attributes from other targets | | [`labels`](#targetlabels) | Map | Metadata for images | | [`matrix`](#targetmatrix) | Map | Define a set of variables that forks a target into multiple targets. | @@ -239,6 +239,7 @@ The following table shows the complete list of attributes that you can assign to | [`policy`](#targetpolicy) | List | Policies to validate build sources and metadata | | [`platforms`](#targetplatforms) | List | Target platforms | | [`pull`](#targetpull) | Boolean | Always pull images | +| [`resources`](#targetresources) | Map | Resource limits for build containers | | [`secret`](#targetsecret) | List | Secrets to expose to the build | | [`shm-size`](#targetshm-size) | List | Size of `/dev/shm` | | [`ssh`](#targetssh) | List | SSH agent sockets or keys to expose to the build | @@ -415,6 +416,11 @@ target "app" { ``` This resolves to the current working directory (`"."`) by default. +Set `BUILDX_BAKE_FILE_RELATIVE_PATHS=1` to resolve local directory paths in +`target.context` and `target.contexts` relative to the Bake file that defines +each path. Compose files use the first Compose file directory as the base, which +matches Compose project directory semantics. Use `cwd://` for paths that should +remain relative to the current working directory when this opt-in is enabled. ```console $ docker buildx bake --print -f - <<< 'target "default" {}' @@ -588,7 +594,7 @@ Entitlements are enabled with a two-step process. First, a target must declare t ### `target.extra-hosts` -Use the `extra-hosts` attribute to define customs host-to-IP mapping for the +Use the `extra-hosts` attribute to define custom host-to-IP mapping for the target. This has the same effect as passing a [`--add-host`][add-host] flag to the build command. @@ -900,6 +906,10 @@ target "default" { } ``` +> [!NOTE] +> Local outputs with `mode=delete` require granting `--allow=buildx.local.delete` +> when invoking `docker buildx bake`. + ### `target.policy` Policies to validate build sources and metadata. Each entry uses the same keys @@ -939,6 +949,29 @@ target "default" { } ``` +### `target.resources` + +Sets cgroup resource limits for the containers that run `RUN` instructions +during the build. The supported keys are `memory`, `memory-swap`, `cpu-shares`, +`cpu-period`, `cpu-quota`, `cpuset-cpus`, and `cpuset-mems`. These map to the +equivalent `docker build` flags and to the +[`--resource`](https://docs.docker.com/reference/cli/docker/buildx/build/#resource) +flag for `docker buildx build`. + +```hcl +target "default" { + resources = { + memory = "2g" + memory-swap = "4g" + cpu-quota = 50000 + } +} +``` + +> [!NOTE] +> These limits require a BuildKit daemon that supports per-step resource limits +> and only take effect on Linux. They don't affect the build cache key. + ### `target.secret` Defines secrets to expose to the build target. @@ -973,6 +1006,14 @@ RUN --mount=type=secret,id=KUBECONFIG,env=KUBECONFIG \ helm upgrade --install ``` +You can override the source for an existing secret without changing the target's +secret IDs. The secret must already be declared by the target. + +```console +$ docker buildx bake --set default.secret.aws=env=AWS_CREDENTIALS +$ docker buildx bake --set default.secret.KUBECONFIG=src=/path/to/kubeconfig +``` + ### `target.shm-size` Sets the size of the shared memory allocated for build containers when using @@ -1016,6 +1057,12 @@ RUN --mount=type=ssh \ && git clone git@github.com:user/my-private-repo.git ``` +> [!NOTE] +> When overriding `ssh` from the command line with `--set`, use the inline +> `id=path` string form rather than the object form shown above, for example +> `docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519"`. Separate +> multiple paths with commas. See [`bake --set`][set] for details. + ### `target.tags` Image names and tags to use for the build target. @@ -1478,6 +1525,7 @@ target "webapp-dev" { [platform]: https://docs.docker.com/reference/cli/docker/buildx/build/#platform [run_mount_secret]: https://docs.docker.com/reference/dockerfile/#run---mounttypesecret [secret]: https://docs.docker.com/reference/cli/docker/buildx/build/#secret +[set]: https://docs.docker.com/reference/cli/docker/buildx/bake/#set [ssh]: https://docs.docker.com/reference/cli/docker/buildx/build/#ssh [tag]: https://docs.docker.com/reference/cli/docker/image/build/#tag [target]: https://docs.docker.com/reference/cli/docker/image/build/#target diff --git a/_vendor/github.com/docker/cli/docs/deprecated.md b/_vendor/github.com/docker/cli/docs/deprecated.md index 4271bbf0ac78..37ffcbc4705b 100644 --- a/_vendor/github.com/docker/cli/docs/deprecated.md +++ b/_vendor/github.com/docker/cli/docs/deprecated.md @@ -113,6 +113,7 @@ The following table provides an overview of the current status of deprecated fea | Deprecated | [`-h` shorthand for `--help`](#-h-shorthand-for---help) | v1.12 | v17.09 | | Removed | [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login) | v1.11 | v17.06 | | Deprecated | [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run) | v1.11 | v17.06 | +| Deprecated | [Links on the default bridge network](#links-on-the-default-bridge-network) | v1.10 | - | | Deprecated | [Ambiguous event fields in API](#ambiguous-event-fields-in-api) | v1.10 | - | | Removed | [`-f` flag on `docker tag`](#-f-flag-on-docker-tag) | v1.10 | v1.12 | | Removed | [HostConfig at API container start](#hostconfig-at-api-container-start) | v1.10 | v1.12 | @@ -1203,6 +1204,19 @@ The `docker login` no longer automatically registers an account with the target The flag `--security-opt` doesn't use the colon separator (`:`) anymore to divide keys and values, it uses the equal symbol (`=`) for consistency with other similar flags, like `--storage-opt`. +### Links on the default bridge network + +**Deprecated in release: v1.10** +**Target for removal in release: v30.0** + +The `--link` option on `docker create` and `docker run`, when used with no +`--network` specified, was deprecated in v1.10 and will be removed in a future +release. Custom networks should be used instead. Docker 29.6 added a deprecation +warning when this option is used for the default bridge network. + +Note that the `--link` option is still supported when a non-default network +is used. + ### Ambiguous event fields in API **Deprecated in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)** diff --git a/_vendor/github.com/docker/cli/docs/extend/plugins_authorization.md b/_vendor/github.com/docker/cli/docs/extend/plugins_authorization.md index 2380d370db11..605fac16fa04 100644 --- a/_vendor/github.com/docker/cli/docs/extend/plugins_authorization.md +++ b/_vendor/github.com/docker/cli/docs/extend/plugins_authorization.md @@ -74,11 +74,14 @@ The sequence diagrams below depict an allow and deny authorization flow: Each request sent to the plugin includes the authenticated user, the HTTP headers, and the request/response body. Only the user name and the authentication method used are passed to the plugin. Most importantly, no user -credentials or tokens are passed. Finally, not all request/response bodies -are sent to the authorization plugin. Only request/response bodies where -the `Content-Type` is `application/json` are sent to the authorization plugin; -bodies of any other `Content-Type` are not visible to the plugin and cannot -be used for enforcement, even though the daemon may still act on this data. +credentials or tokens are passed. + +> [!NOTE] +> Authorization plugins enforce requests to the Docker daemon's HTTP API only. gRPC method +> calls, whether dispatched natively or upgraded through `POST /grpc`, are not subject to authorization. +> Furthermore, HTTP request/response bodies where the `Content-Type` is `application/json` are forwarded; +> bodies of any other type are not visible to the plugin and cannot be used for enforcement, +> even though the daemon acts on this data. For commands that can potentially hijack the HTTP connection (`HTTP Upgrade`), such as `exec`, the authorization plugin is only called for the @@ -88,6 +91,22 @@ passed to the authorization plugins. For commands that return chunked HTTP response, such as `logs` and `events`, only the HTTP request is sent to the authorization plugins. +The Engine's authorization middleware fails closed: when a plugin returns an error or returns `Allow: false`, +the request is denied and the error is surfaced to the client. Plugins should also fail closed: if the plugin +cannot confidently evaluate a request, it should return an error or `Allow: false`. + +> [!WARNING] +> Because the plugin receives the [**raw** request body](#authzpluginauthzreq) from the daemon, it must +> apply the same decoding semantics as the daemon to be sure it evaluates the request the daemon will +> act on. The daemon decodes JSON with Go's [`encoding/json.Unmarshal`](https://pkg.go.dev/encoding/json#Unmarshal). +> +> The same requirement applies to the response body. Plugins that depend on `ResponseBody` +> inspection for redaction or content-filtering should restrict their policies to endpoints +> whose response is produced as a single write (typical of REST-style API responses). For +> commands whose responses are streamed or are likely to exceed the [buffer](#response-body-size-and-partial-buffering) through multiple +> writes, do not rely on `ResponseBody` for security-relevant decisions; perform the filtering +> in a separate layer in front of the daemon. + ### Response body size and partial buffering The internal buffer that holds the response body between the daemon's HTTP @@ -104,15 +123,6 @@ is the practical effect of this 64 KiB threshold combined with the is immediately drained to the client and is therefore no longer available for plugin inspection by the time the handler returns. -> [!NOTE] -> Plugins that depend on `ResponseBody` inspection for redaction or -> content-filtering should restrict their policies to endpoints whose -> response is produced as a single write (typical of REST-style API -> responses). For commands whose responses are streamed or are likely to -> exceed the buffer through multiple writes, do not rely on `ResponseBody` -> for security-relevant decisions; perform the filtering in a separate -> layer in front of the daemon. - During request/response processing, some authorization flows might need to do additional queries to the Docker daemon. To complete such flows, plugins can call the daemon API similar to a regular user. To enable these @@ -236,7 +246,7 @@ Name | Type | Description User | string | The user identification Authentication method | string | The authentication method used Request method | enum | The HTTP method (GET/DELETE/POST) -Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json) +Request URI | string | The HTTP request URI including API version, as sent by the client (e.g., v.1.17/containers/json) Request headers | map[string]string | Request headers as key value pairs (without the authorization header) Request body | []byte | Raw request body @@ -259,7 +269,7 @@ Name | Type | Description User | string | The user identification Authentication method | string | The authentication method used Request method | string | The HTTP method (GET/DELETE/POST) -Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json) +Request URI | string | The HTTP request URI including API version, as sent by the client (e.g., v.1.17/containers/json) Request headers | map[string]string | Request headers as key value pairs (without the authorization header) Request body | []byte | Raw request body Response status code | int | Status code from the Docker daemon diff --git a/_vendor/github.com/docker/cli/docs/reference/dockerd.md b/_vendor/github.com/docker/cli/docs/reference/dockerd.md index c0ef206cdac9..61a342c655f4 100644 --- a/_vendor/github.com/docker/cli/docs/reference/dockerd.md +++ b/_vendor/github.com/docker/cli/docs/reference/dockerd.md @@ -25,6 +25,7 @@ A self-sufficient runtime for containers. Options: --add-runtime runtime Register an additional OCI compatible runtime (default []) --allow-direct-routing Allow remote access to published ports on container IP addresses + --apparmor-profile string Path to AppArmor profile template --authorization-plugin list Authorization plugins to load --bip string IPv4 address for the default bridge --bip6 string IPv6 address for the default bridge @@ -51,6 +52,7 @@ Options: --default-network-opt mapmap Default network options (default map[]) --default-runtime string Default OCI runtime for containers (default "runc") --default-shm-size bytes Default shm size for containers (default 64MiB) + --default-stop-timeout int Set the default container stop timeout in seconds (0 to terminate immediately) (default 10) --default-ulimit ulimit Default ulimits for containers (default []) --dns list DNS server to use --dns-opt list DNS options to use @@ -758,6 +760,18 @@ This only adds the proxy and authentication to the Docker daemon's requests. To use the proxy when building images and running containers, see [Configure Docker to use a proxy server](https://docs.docker.com/engine/cli/proxy/) +### Default container stop timeout + +The `--default-stop-timeout` flag sets the number of seconds to wait for a +container to stop when the container doesn't have a `--stop-timeout` configured. +The default is `10` seconds on Linux and `30` seconds on Windows. A value of `0` +doesn't wait before forcefully terminating the container. Negative values are +invalid. + +You can also configure the timeout with the `default-stop-timeout` option in the +[daemon configuration file](#daemon-configuration-file). You can reload this +option without restarting the daemon. + ### Default `ulimit` settings The `--default-ulimit` flag lets you set the default `ulimit` options to use for @@ -793,6 +807,24 @@ allow the request for it to complete. For information about how to create an authorization plugin, refer to the [authorization plugin](https://docs.docker.com/engine/extend/plugins_authorization/) section. +### Configure the default AppArmor profile + +The `--apparmor-profile` option sets the path to an AppArmor profile definition +for Docker's default `docker-default` container profile. This option is only +supported on Linux hosts. The file can be a static profile or a Go template. + +The equivalent `daemon.json` configuration is: + +```json +{ + "apparmor-profile": "/etc/docker/apparmor/docker-default" +} +``` + +Restart the daemon to apply changes. For template values, safe file placement, +security considerations, and verification, see +[Customize the default AppArmor profile](https://docs.docker.com/engine/security/apparmor/#customize-the-default-profile). + ### Daemon user namespace options The Linux kernel @@ -1057,15 +1089,16 @@ $ echo $? ##### On Linux -The default location of the configuration file on Linux is -`/etc/docker/daemon.json`. Use the `--config-file` flag to specify a -non-default location. +The default location of the configuration file on Linux is `/etc/docker/daemon.json`. +If the file does not exist, you need to create it first. Use the `--config-file` +flag to specify a non-default location. The following is a full example of the allowed configuration options on Linux: ```json { "allow-direct-routing": false, + "apparmor-profile": "", "authorization-plugins": [], "bip": "", "bip6": "", @@ -1104,6 +1137,7 @@ The following is a full example of the allowed configuration options on Linux: "default-network-opts": {}, "default-runtime": "runc", "default-shm-size": "64M", + "default-stop-timeout": 10, "default-ulimits": { "nofile": { "Hard": 64000, @@ -1208,8 +1242,9 @@ The following is a full example of the allowed configuration options on Linux: ##### On Windows The default location of the configuration file on Windows is -`%programdata%\docker\config\daemon.json`. Use the `--config-file` flag -to specify a non-default location. +`%programdata%\docker\config\daemon.json`. If the file does not exist, you need +to create it first. Use the `--config-file` flag to specify a non-default +location. The following is a full example of the allowed configuration options on Windows: @@ -1224,6 +1259,7 @@ The following is a full example of the allowed configuration options on Windows: "debug": true, "default-network-opts": {}, "default-runtime": "", + "default-stop-timeout": 30, "default-ulimits": {}, "dns": [], "dns-opts": [], @@ -1316,6 +1352,7 @@ The list of currently supported options that can be reconfigured is this: | `max-concurrent-uploads` | Configures the max concurrent uploads for each push. | | `max-download-attempts` | Configures the max download attempts for each pull. | | `default-runtime` | Configures the runtime to be used if not is specified at container creation. | +| `default-stop-timeout` | Configures the timeout for stopping containers that have no container-specific timeout. | | `runtimes` | Configures the list of available OCI runtimes that can be used to run containers. | | `authorization-plugin` | Specifies the authorization plugins to use. | | `insecure-registries` | Specifies a list of registries that the daemon should consider insecure. | diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose.md index d80bb86ec626..50ebfba473dd 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose.md @@ -28,7 +28,7 @@ Define and run multi-container applications with Docker | [`logs`](compose_logs.md) | View output from containers | | [`ls`](compose_ls.md) | List running compose projects | | [`pause`](compose_pause.md) | Pause services | -| [`port`](compose_port.md) | Print the public port for a port binding | +| [`port`](compose_port.md) | List port mappings or print the public port for a specific mapping for the service | | [`ps`](compose_ps.md) | List containers | | [`publish`](compose_publish.md) | Publish compose application | | [`pull`](compose_pull.md) | Pull service images | diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_alpha_publish.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_alpha_publish.md deleted file mode 100644 index 6e77d714532b..000000000000 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_alpha_publish.md +++ /dev/null @@ -1,18 +0,0 @@ -# docker compose alpha publish - -<!---MARKER_GEN_START--> -Publish compose application - -### Options - -| Name | Type | Default | Description | -|:--------------------------|:---------|:--------|:-------------------------------------------------------------------------------| -| `--dry-run` | `bool` | | Execute command in dry run mode | -| `--oci-version` | `string` | | OCI image/artifact specification version (automatically determined by default) | -| `--resolve-image-digests` | `bool` | | Pin image tags to digests | -| `--with-env` | `bool` | | Include environment variables in the published OCI artifact | -| `-y`, `--yes` | `bool` | | Assume "yes" as answer to all prompts | - - -<!---MARKER_GEN_END--> - diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_bridge_convert.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_bridge_convert.md index d4b91ba172d2..09184d4c9784 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_bridge_convert.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_bridge_convert.md @@ -5,12 +5,13 @@ Convert compose files to Kubernetes manifests, Helm charts, or another model ### Options -| Name | Type | Default | Description | -|:-------------------------|:--------------|:--------|:-------------------------------------------------------------------------------------| -| `--dry-run` | `bool` | | Execute command in dry run mode | -| `-o`, `--output` | `string` | `out` | The output directory for the Kubernetes resources | -| `--templates` | `string` | | Directory containing transformation templates | -| `-t`, `--transformation` | `stringArray` | | Transformation to apply to compose model (default: docker/compose-bridge-kubernetes) | +| Name | Type | Default | Description | +|:-------------------------|:--------------|:--------|:---------------------------------------------------------------------------------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `-o`, `--output` | `string` | `out` | The output directory for the Kubernetes resources | +| `--templates` | `string` | | Directory containing transformation templates | +| `-t`, `--transformation` | `stringArray` | | Transformation to apply to compose model (default: docker/compose-bridge-kubernetes) | +| `-y`, `--yes` | `bool` | | Assume "yes" to the output directory overwrite prompt. For scripts/CI, where no interactive confirmation is possible | <!---MARKER_GEN_END--> diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_down.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_down.md index 2ac0bf2da423..a49ed9852717 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_down.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_down.md @@ -15,6 +15,18 @@ Anonymous volumes are not removed by default. However, as they don’t have a st mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or named volumes. +### Pre-start hook containers + +When a `pre_start` lifecycle hook fails, Compose retains its container for post-mortem inspection instead of removing +it immediately. `compose down` automatically removes these retained hook containers as part of teardown, so they do +not accumulate over time. + +To list retained hook containers before running `down`: + +```console +$ docker ps -a --filter label=com.docker.compose.hook=pre_start +``` + ### Options | Name | Type | Default | Description | @@ -43,3 +55,15 @@ Networks and volumes defined as external are never removed. Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or named volumes. + +### Pre-start hook containers + +When a `pre_start` lifecycle hook fails, Compose retains its container for post-mortem inspection instead of removing +it immediately. `compose down` automatically removes these retained hook containers as part of teardown, so they do +not accumulate over time. + +To list retained hook containers before running `down`: + +```console +$ docker ps -a --filter label=com.docker.compose.hook=pre_start +``` diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_logs.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_logs.md index 4c8ba7e34867..bcbb39e20810 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_logs.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_logs.md @@ -5,17 +5,17 @@ Displays log output from services ### Options -| Name | Type | Default | Description | -|:---------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------| -| `--dry-run` | `bool` | | Execute command in dry run mode | -| `-f`, `--follow` | `bool` | | Follow log output | -| `--index` | `int` | `0` | index of the container if service has multiple replicas | -| `--no-color` | `bool` | | Produce monochrome output | -| `--no-log-prefix` | `bool` | | Don't print prefix in logs | -| `--since` | `string` | | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | -| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs for each container | -| `-t`, `--timestamps` | `bool` | | Show timestamps | -| `--until` | `string` | | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | +| Name | Type | Default | Description | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| [`-f`](https://docs.docker.com/reference/cli/docker/container/logs/#follow), [`--follow`](https://docs.docker.com/reference/cli/docker/container/logs/#follow) | `bool` | | Follow log output | +| `--index` | `int` | `0` | index of the container if service has multiple replicas | +| `--no-color` | `bool` | | Produce monochrome output | +| `--no-log-prefix` | `bool` | | Don't print prefix in logs | +| [`--since`](https://docs.docker.com/reference/cli/docker/container/logs/#since) | `string` | | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | +| [`-n`](https://docs.docker.com/reference/cli/docker/container/logs/#tail), [`--tail`](https://docs.docker.com/reference/cli/docker/container/logs/#tail) | `string` | `all` | Number of lines to show from the end of the logs for each container | +| [`-t`](https://docs.docker.com/reference/cli/docker/container/logs/#timestamps), [`--timestamps`](https://docs.docker.com/reference/cli/docker/container/logs/#timestamps) | `bool` | | Show timestamps | +| [`--until`](https://docs.docker.com/reference/cli/docker/container/logs/#until) | `string` | | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | <!---MARKER_GEN_END--> diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_port.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_port.md index bbbfbf156168..a0b828a10ef5 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_port.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_port.md @@ -1,7 +1,7 @@ # docker compose port <!---MARKER_GEN_START--> -Prints the public port for a port binding +List port mappings or print the public port for a specific mapping for the service ### Options @@ -16,4 +16,4 @@ Prints the public port for a port binding ## Description -Prints the public port for a port binding +List port mappings or print the public port for a specific mapping for the service diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_ps.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_ps.md index 3572c5305568..71962d1d1c84 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_ps.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_ps.md @@ -25,7 +25,7 @@ example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited | `-a`, `--all` | `bool` | | Show all stopped containers (including those created by the run command) | | `--dry-run` | `bool` | | Execute command in dry run mode | | [`--filter`](#filter) | `string` | | Filter services by a property (supported filters: status) | -| [`--format`](#format) | `string` | `table` | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--no-trunc` | `bool` | | Don't truncate output | | `--orphans` | `bool` | `true` | Include orphaned services (not declared by project) | | `-q`, `--quiet` | `bool` | | Only display IDs | @@ -61,50 +61,50 @@ example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited By default, the `docker compose ps` command uses a table ("pretty") format to show the containers. The `--format` flag allows you to specify alternative presentations for the output. Currently, supported options are `pretty` (default), -and `json`, which outputs information about the containers as a JSON array: +and `json`, which outputs information about the containers as JSON Lines +(one JSON object per line), aligned with the output of `docker ps --format json`: ```console $ docker compose ps --format json -[{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}] +{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null} +{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]} ``` The JSON output allows you to use the information in other tools for further processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/) -to pretty-print the JSON: +to pretty-print each object: ```console $ docker compose ps --format json | jq . -[ - { - "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a", - "Name": "example-bar-1", - "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", - "Project": "example", - "Service": "bar", - "State": "exited", - "Health": "", - "ExitCode": 0, - "Publishers": null - }, - { - "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0", - "Name": "example-foo-1", - "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", - "Project": "example", - "Service": "foo", - "State": "running", - "Health": "", - "ExitCode": 0, - "Publishers": [ - { - "URL": "0.0.0.0", - "TargetPort": 80, - "PublishedPort": 8080, - "Protocol": "tcp" - } - ] - } -] +{ + "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a", + "Name": "example-bar-1", + "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", + "Project": "example", + "Service": "bar", + "State": "exited", + "Health": "", + "ExitCode": 0, + "Publishers": null +} +{ + "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0", + "Name": "example-foo-1", + "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", + "Project": "example", + "Service": "foo", + "State": "running", + "Health": "", + "ExitCode": 0, + "Publishers": [ + { + "URL": "0.0.0.0", + "TargetPort": 80, + "PublishedPort": 8080, + "Protocol": "tcp" + } + ] +} ``` ### <a name="status"></a> Filter containers by status (--status) diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md index 25b28d1ded85..14fb85479266 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md @@ -70,8 +70,8 @@ specified in the service configuration. | `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached | | `-l`, `--label` | `stringArray` | | Add or override a label | | `--name` | `string` | | Assign a name to the container | -| `-T`, `--no-TTY` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) | | `--no-deps` | `bool` | | Don't start linked services | +| `-T`, `--no-tty` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) | | `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host | | `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") | | `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT | diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_up.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_up.md index b7f17a0fac91..78b89ed9bed8 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_up.md +++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_up.md @@ -21,6 +21,19 @@ If you want to force Compose to stop and recreate all containers, use the `--for If the process encounters an error, the exit code for this command is `1`. If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`. +### Pre-start hook failures + +When a `pre_start` lifecycle hook exits with a non-zero code, Compose stops the service startup and retains the +hook’s container so you can inspect what went wrong: + +```console +$ docker ps -a --filter label=com.docker.compose.hook=pre_start +$ docker logs <container-id> +``` + +On the next `compose up`, any retained hook containers for the same service are cleaned up automatically before the +hook runs again. Running `compose down` also removes them. + ### Options | Name | Type | Default | Description | @@ -80,3 +93,16 @@ If you want to force Compose to stop and recreate all containers, use the `--for If the process encounters an error, the exit code for this command is `1`. If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`. + +### Pre-start hook failures + +When a `pre_start` lifecycle hook exits with a non-zero code, Compose stops the service startup and retains the +hook’s container so you can inspect what went wrong: + +```console +$ docker ps -a --filter label=com.docker.compose.hook=pre_start +$ docker logs <container-id> +``` + +On the next `compose up`, any retained hook containers for the same service are cleaned up automatically before the +hook runs again. Running `compose down` also removes them. diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha.yaml index e6b6b6e6b6f7..370e89670fa5 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha.yaml @@ -5,11 +5,9 @@ pname: docker compose plink: docker_compose.yaml cname: - docker compose alpha generate - - docker compose alpha publish - docker compose alpha viz clink: - docker_compose_alpha_generate.yaml - - docker_compose_alpha_publish.yaml - docker_compose_alpha_viz.yaml inherited_options: - option: dry-run diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha_publish.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha_publish.yaml deleted file mode 100644 index 9059cbf48695..000000000000 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_alpha_publish.yaml +++ /dev/null @@ -1,86 +0,0 @@ -command: docker compose alpha publish -short: Publish compose application -long: Publish compose application -usage: docker compose alpha publish [OPTIONS] REPOSITORY[:TAG] -pname: docker compose alpha -plink: docker_compose_alpha.yaml -options: - - option: app - value_type: bool - default_value: "false" - description: Published compose application (includes referenced images) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: insecure-registry - value_type: bool - default_value: "false" - description: Use insecure registry - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: oci-version - value_type: string - description: | - OCI image/artifact specification version (automatically determined by default) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: resolve-image-digests - value_type: bool - default_value: "false" - description: Pin image tags to digests - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: with-env - value_type: bool - default_value: "false" - description: Include environment variables in the published OCI artifact - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: "yes" - shorthand: "y" - value_type: bool - default_value: "false" - description: Assume "yes" as answer to all prompts - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: dry-run - value_type: bool - default_value: "false" - description: Execute command in dry run mode - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -hidden: true -experimental: false -experimentalcli: true -kubernetes: false -swarm: false - diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge.yaml index 5ef9ebf55850..86acb68f9fe0 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge.yaml @@ -1,6 +1,7 @@ command: docker compose bridge short: Convert compose files into another model long: Convert compose files into another model +usage: docker compose bridge CMD [OPTIONS] pname: docker compose plink: docker_compose.yaml cname: diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_convert.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_convert.yaml index f55f0b233c3c..c9478444b4a7 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_convert.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_convert.yaml @@ -39,6 +39,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: "yes" + shorthand: "y" + value_type: bool + default_value: "false" + description: | + Assume "yes" to the output directory overwrite prompt. For scripts/CI, where no interactive confirmation is possible + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: - option: dry-run value_type: bool diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_transformations.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_transformations.yaml index 2ab5661f0b2a..fadf1e336c19 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_transformations.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_bridge_transformations.yaml @@ -1,6 +1,7 @@ command: docker compose bridge transformations short: Manage transformation images long: Manage transformation images +usage: docker compose bridge transformations CMD [OPTIONS] pname: docker compose bridge plink: docker_compose_bridge.yaml cname: diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_down.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_down.yaml index 77bf526289b4..37bc94ac7dec 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_down.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_down.yaml @@ -14,6 +14,18 @@ long: |- Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or named volumes. + + ### Pre-start hook containers + + When a `pre_start` lifecycle hook fails, Compose retains its container for post-mortem inspection instead of removing + it immediately. `compose down` automatically removes these retained hook containers as part of teardown, so they do + not accumulate over time. + + To list retained hook containers before running `down`: + + ```console + $ docker ps -a --filter label=com.docker.compose.hook=pre_start + ``` usage: docker compose down [OPTIONS] [SERVICES] pname: docker compose plink: docker_compose.yaml diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_logs.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_logs.yaml index 92d94dd108cf..6b657ff8cb08 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_logs.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_logs.yaml @@ -10,6 +10,7 @@ options: value_type: bool default_value: "false" description: Follow log output + details_url: /reference/cli/docker/container/logs/#follow deprecated: false hidden: false experimental: false @@ -50,6 +51,7 @@ options: value_type: string description: | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) + details_url: /reference/cli/docker/container/logs/#since deprecated: false hidden: false experimental: false @@ -62,6 +64,7 @@ options: default_value: all description: | Number of lines to show from the end of the logs for each container + details_url: /reference/cli/docker/container/logs/#tail deprecated: false hidden: false experimental: false @@ -73,6 +76,7 @@ options: value_type: bool default_value: "false" description: Show timestamps + details_url: /reference/cli/docker/container/logs/#timestamps deprecated: false hidden: false experimental: false @@ -83,6 +87,7 @@ options: value_type: string description: | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) + details_url: /reference/cli/docker/container/logs/#until deprecated: false hidden: false experimental: false diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_port.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_port.yaml index 8a07f31ea505..88acd4be6d1e 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_port.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_port.yaml @@ -1,7 +1,9 @@ command: docker compose port -short: Print the public port for a port binding -long: Prints the public port for a port binding -usage: docker compose port [OPTIONS] SERVICE PRIVATE_PORT +short: | + List port mappings or print the public port for a specific mapping for the service +long: | + List port mappings or print the public port for a specific mapping for the service +usage: docker compose port [OPTIONS] SERVICE [PRIVATE_PORT] pname: docker compose plink: docker_compose.yaml options: diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_ps.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_ps.yaml index d03702756954..d42f24182a34 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_ps.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_ps.yaml @@ -45,7 +45,6 @@ options: swarm: false - option: format value_type: string - default_value: table description: |- Format output using a custom template: 'table': Print output in table format with column headers (default) @@ -130,50 +129,50 @@ examples: |- By default, the `docker compose ps` command uses a table ("pretty") format to show the containers. The `--format` flag allows you to specify alternative presentations for the output. Currently, supported options are `pretty` (default), - and `json`, which outputs information about the containers as a JSON array: + and `json`, which outputs information about the containers as JSON Lines + (one JSON object per line), aligned with the output of `docker ps --format json`: ```console $ docker compose ps --format json - [{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}] + {"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null} + {"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]} ``` The JSON output allows you to use the information in other tools for further processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/) - to pretty-print the JSON: + to pretty-print each object: ```console $ docker compose ps --format json | jq . - [ - { - "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a", - "Name": "example-bar-1", - "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", - "Project": "example", - "Service": "bar", - "State": "exited", - "Health": "", - "ExitCode": 0, - "Publishers": null - }, - { - "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0", - "Name": "example-foo-1", - "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", - "Project": "example", - "Service": "foo", - "State": "running", - "Health": "", - "ExitCode": 0, - "Publishers": [ - { - "URL": "0.0.0.0", - "TargetPort": 80, - "PublishedPort": 8080, - "Protocol": "tcp" - } - ] - } - ] + { + "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a", + "Name": "example-bar-1", + "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", + "Project": "example", + "Service": "bar", + "State": "exited", + "Health": "", + "ExitCode": 0, + "Publishers": null + } + { + "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0", + "Name": "example-foo-1", + "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'", + "Project": "example", + "Service": "foo", + "State": "running", + "Health": "", + "ExitCode": 0, + "Publishers": [ + { + "URL": "0.0.0.0", + "TargetPort": 80, + "PublishedPort": 8080, + "Protocol": "tcp" + } + ] + } ``` ### Filter containers by status (--status) {#status} diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml index 61c7ca0e8cbc..bc9f81e9ed0a 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml @@ -158,21 +158,21 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: no-TTY - shorthand: T + - option: no-deps value_type: bool - default_value: "true" - description: 'Disable pseudo-TTY allocation (default: auto-detected)' + default_value: "false" + description: Don't start linked services deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false - - option: no-deps + - option: no-tty + shorthand: T value_type: bool - default_value: "false" - description: Don't start linked services + default_value: "true" + description: 'Disable pseudo-TTY allocation (default: auto-detected)' deprecated: false hidden: false experimental: false diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_up.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_up.yaml index 8c78a8fa683e..7068ba4df5f5 100644 --- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_up.yaml +++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_up.yaml @@ -20,6 +20,19 @@ long: |- If the process encounters an error, the exit code for this command is `1`. If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`. + + ### Pre-start hook failures + + When a `pre_start` lifecycle hook exits with a non-zero code, Compose stops the service startup and retains the + hook’s container so you can inspect what went wrong: + + ```console + $ docker ps -a --filter label=com.docker.compose.hook=pre_start + $ docker logs <container-id> + ``` + + On the next `compose up`, any retained hook containers for the same service are cleaned up automatically before the + hook runs again. Running `compose down` also removes them. usage: docker compose up [OPTIONS] [SERVICE...] pname: docker compose plink: docker_compose.yaml diff --git a/_vendor/github.com/docker/docker-agent/docs/community/_index.md b/_vendor/github.com/docker/docker-agent/docs/community/_index.md new file mode 100644 index 000000000000..764483d9718c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/community/_index.md @@ -0,0 +1,5 @@ +--- +title: "Community" +description: "Contributing, troubleshooting, and telemetry." +weight: 80 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/community/contributing/index.md b/_vendor/github.com/docker/docker-agent/docs/community/contributing/index.md new file mode 100644 index 000000000000..302997a137dc --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/community/contributing/index.md @@ -0,0 +1,131 @@ +--- +title: "Contributing" +description: "Docker Agent is open source. Here's how to set up your development environment and contribute." +keywords: docker agent, ai agents, community, contributing +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/community/contributing/ +--- + +_Docker Agent is open source. Here's how to set up your development environment and contribute._ + +## Development Setup + +### Prerequisites + +- [Go 1.26](https://go.dev/dl/) or higher +- API key(s) for your chosen AI provider +- [Task](https://taskfile.dev/installation/) +- [golangci-lint](https://golangci-lint.run/docs/welcome/install/local/) + +> [!NOTE] +> **Platform Support** +> +> macOS and Linux are fully supported for development. On Windows, use `task build-local` to build via Docker. + +### Build from Source + +```bash +# Clone and build +git clone https://github.com/docker/docker-agent.git +cd docker-agent +task build + +# Set API keys +export OPENAI_API_KEY=your_key_here +export ANTHROPIC_API_KEY=your_key_here + +# Run an example +./bin/docker-agent run examples/code.yaml +``` + +### Development Commands + +| Command | Description | +| ------------------ | ----------------------------------------------- | +| `task build` | Build the binary to `./bin/docker-agent` | +| `task test` | Run all tests (clears API keys for determinism) | +| `task lint` | Run golangci-lint | +| `task format` | Format code | +| `task dev` | Run lint, test, and build in sequence | +| `task build-local` | Build for local platform via Docker | +| `task cross` | Cross-platform builds (all architectures) | + +## Dogfooding + +Use Docker Agent to work on Docker Agent! The project includes a specialized developer agent: + +```bash +cd docker-agent +docker agent run ./golang_developer.yaml +``` + +This agent is an expert Go developer that understands the Docker Agent codebase. Ask it questions, request fixes, or have it implement features. + +## Core Concepts + +- **Root Agent** — Main entry point that coordinates the system +- **Sub-Agents** — Specialized agents for specific domains +- **Tools** — External capabilities via MCP +- **Models** — AI provider configurations + +## Code Style + +The project uses `golangci-lint` with strict rules. As long as `task lint` passes, the code is stylistically acceptable. + +Key conventions: + +- Use `fmt.Errorf("context: %w", err)` for error wrapping +- Always pass `context.Context` as the first parameter +- Use `slog` for structured logging +- Use functional options pattern for constructors +- In tests: use `t.Context()`, `t.TempDir()`, `t.Setenv()`, and `t.Parallel()` + +## Opening Issues + +File issues on the [GitHub issue tracker](https://github.com/docker/docker-agent/issues). Please: + +> [!NOTE] +> **See also** +> +> [Troubleshooting](../troubleshooting/index.md) — Common issues and debug mode. [Telemetry](../telemetry/index.md) — What data is collected and how to opt out. + +- Use the included issue template +- Search for existing issues before creating new ones +- Only use issues for bugs and feature requests (not support) + +## Submitting Pull Requests + +1. **Fork** the repository and create a branch for your changes +2. **Write** your code following the style and testing guidelines above +3. **Test** your changes: run `task lint` and `task test` +4. **Sign** your commits with `git commit -s` (DCO required) +5. **Open a pull request** against the `main` branch + +> [!TIP] +> Use the dogfooding agent (`docker agent run ./golang_developer.yaml`) to help write and review your changes before submitting. + +## Sign Your Work + +All contributions require a Developer Certificate of Origin (DCO) sign-off: + +```bash +# Sign commits automatically +git config user.name "Your Name" +git config user.email "your.email@example.com" +git commit -s -m "Your commit message" +``` + +## Community + +Find us on [Slack](https://dockercommunity.slack.com/archives/C09DASHHRU4) for questions and discussions. + +## Code of Conduct + +We want to keep the Docker Agent community welcoming, inclusive, and collaborative. Key guidelines: + +- **Be nice** — Be courteous, respectful, and polite. No abuse of any kind will be tolerated. +- **Encourage diversity** — Make everyone feel welcome regardless of background. +- **Keep it legal** — Share only content you own and don't break the law. +- **Stay on topic** — Post to the correct channel and avoid off-topic discussions. + +The governance for this repository is handled by Docker Inc. diff --git a/_vendor/github.com/docker/docker-agent/docs/community/opentelemetry/index.md b/_vendor/github.com/docker/docker-agent/docs/community/opentelemetry/index.md new file mode 100644 index 000000000000..ae6b3c9a1304 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/community/opentelemetry/index.md @@ -0,0 +1,99 @@ +--- +title: "OpenTelemetry Tracing" +description: "Export Docker Agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows." +keywords: docker agent, ai agents, community, opentelemetry tracing +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/community/opentelemetry/ +--- + +_Docker Agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](../telemetry/index.md) and is opt-in via the `--otel` flag._ + +When enabled, Docker Agent emits OpenTelemetry GenAI (`gen_ai.*`) and MCP (`mcp.*`) spans following the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Spans cover the agent turn, model calls (with token usage and cost attributes), tool calls, MCP client/server activity, sub-agent hand-offs, and provider fallbacks. W3C `traceparent` context is propagated so the whole run renders as a single connected trace tree. + +## Enabling + +```bash +docker agent run agent.yaml --otel +``` + +Without an exporter endpoint configured, spans are recorded locally as no-ops. To ship them somewhere, set the standard OTLP environment variables described below. + +## Configuration + +Docker Agent reads the standard OTLP environment variables: + +| Variable | Purpose | +| --- | --- | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP/HTTP endpoint. The signal subpath (`/v1/traces`, `/v1/metrics`, `/v1/logs`) is appended automatically. | +| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers sent with every export request (for example, an `Authorization` header). | +| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes merged into every span. | +| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Set to `true` to capture prompt and response message content as span attributes. Off by default. | + +> [!NOTE] +> **Base endpoint, not the full signal URL** +> +> Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the **base** endpoint (for example `https://cloud.langfuse.com/api/public/otel`). Docker Agent appends `/v1/traces` for you, matching the value documented by Langfuse and LangSmith. A bare `host:port` is also accepted and gets `https://` (or `http://` for localhost). + +> [!WARNING] +> **Message content can contain sensitive data** +> +> `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is off by default because chat history routinely contains PII, secrets, and internal documents. Enable it only for backends and environments where exporting that content is acceptable. + +## Backends + +Protocol support is OTLP over HTTP (`http/protobuf`). gRPC endpoints are not currently supported. + +### Langfuse + +[Langfuse](https://langfuse.com) exposes an OTLP endpoint and authenticates with HTTP Basic auth built from a project's public and secret keys. + +```bash +# Base64 of "public_key:secret_key" +LANGFUSE_AUTH=$(echo -n "pk-lf-...:sk-lf-..." | base64) + +export OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel" +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${LANGFUSE_AUTH}" + +docker agent run agent.yaml --otel +``` + +Regional and self-hosted hosts use the same `/api/public/otel` base path: + +| Region | Endpoint | +| --- | --- | +| EU | `https://cloud.langfuse.com/api/public/otel` | +| US | `https://us.cloud.langfuse.com/api/public/otel` | +| Self-hosted (>= v3.22.0) | `http://localhost:3000/api/public/otel` | + +### LangSmith + +[LangSmith](https://docs.langchain.com/langsmith/trace-with-opentelemetry) authenticates with an `x-api-key` header (the raw API key, with no `Basic`/`Bearer` prefix). An optional `Langsmith-Project` header routes traces to a named project. + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.smith.langchain.com/otel" +export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-api-key>,Langsmith-Project=<project>" + +docker agent run agent.yaml --otel +``` + +### OpenTelemetry Collector + +Any OTLP/HTTP collector (the OpenTelemetry Collector, Grafana Alloy, Jaeger, and so on) works by pointing at its base endpoint: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" +docker agent run agent.yaml --otel +``` + +> [!NOTE] +> **Langfuse and LangSmith ingest traces only** +> +> Both backends accept the traces signal only. Docker Agent also wires metric and log exporters at the same endpoint, so their periodic exports return `404` against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs. + +## Inspecting traces locally + +Use `--debug` to print telemetry activity to the debug log (`~/.cagent/cagent.debug.log` by default) without standing up a backend: + +```bash +docker agent run agent.yaml --otel --debug +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/community/telemetry/index.md b/_vendor/github.com/docker/docker-agent/docs/community/telemetry/index.md new file mode 100644 index 000000000000..54974db155f8 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/community/telemetry/index.md @@ -0,0 +1,79 @@ +--- +title: "Telemetry" +description: "Docker Agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time." +keywords: docker agent, ai agents, community, telemetry +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/community/telemetry/ +--- + +_Docker Agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time._ + +On first startup, Docker Agent displays a notice about telemetry collection so you're always informed. All events are processed synchronously when recorded. + +## Disabling Telemetry + +```bash +# Disable via environment variable +$ TELEMETRY_ENABLED=false docker agent run agent.yaml + +# Or export it in your shell profile +$ export TELEMETRY_ENABLED=false +``` + +> [!NOTE] +> **Default** +> +> Telemetry is **enabled by default**. Set `TELEMETRY_ENABLED=false` to opt out. + +## What's Collected ✅ + +- Command names and success/failure status +- Agent names and model types +- Tool names and whether calls succeed or fail +- Token counts (input/output totals) and estimated costs +- Session metadata (durations, error counts) + +## What's NOT Collected ❌ + +- User input or prompts +- Agent responses or generated content +- File contents +- API keys or credentials +- Personally identifying information (PII) + +> [!TIP] +> **See events locally** +> +> Use `--debug` to see telemetry events printed to the debug log without sending them anywhere additional. + +```bash +docker agent run agent.yaml --debug +``` + +## Event Types + +The telemetry system uses structured, type-safe events: + +| Event Type | What It Tracks | +| ----------- | ------------------------------------------------------------------- | +| **Command** | CLI command execution with success status | +| **Tool** | Agent tool calls with timing and error information | +| **Token** | LLM token usage by model, session, and cost | +| **Session** | Agent session lifecycle with start/end events and aggregate metrics | + +## For Developers + +Telemetry is automatically wrapped around all commands. To record additional events, use the context-based API: + +```bash +// Recommended: context-based telemetry (clean, testable) +if telemetryClient := telemetry.FromContext(ctx); telemetryClient != nil { + telemetryClient.RecordToolCall(ctx, "filesystem", "session-id", "agentName", time.Millisecond*500, nil) + telemetryClient.RecordTokenUsage(ctx, "gpt-4", 100, 50, 0.01) +} + +// Or use direct calls +telemetry.TrackCommand("run", args) +``` + +Events are processed synchronously when `Track()` is called, sending HTTP requests immediately. diff --git a/_vendor/github.com/docker/docker-agent/docs/community/troubleshooting/index.md b/_vendor/github.com/docker/docker-agent/docs/community/troubleshooting/index.md new file mode 100644 index 000000000000..1e73169e067b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/community/troubleshooting/index.md @@ -0,0 +1,342 @@ +--- +title: "Troubleshooting" +description: "Common issues and how to resolve them when working with Docker Agent." +keywords: docker agent, ai agents, community, troubleshooting +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/community/troubleshooting/ +--- + +_Common issues and how to resolve them when working with Docker Agent._ + +## Common Errors + +### Context Window Exceeded + +Error message: `context_length_exceeded` or similar. + +- Use `/compact` in the TUI to summarize and reduce conversation history +- Set `num_history_items` in agent config to limit messages sent to the model +- Switch to a model with larger context (Claude Sonnet 4.5 supports 1M tokens, Gemini up to 2M) +- Break large tasks into smaller conversations + +### Max Iterations Reached + +The agent hit its `max_iterations` limit without completing the task. + +- Increase `max_iterations` in agent config (default is unlimited, but many agents set 20-50) +- Check if the agent is stuck in a loop (enable `--debug` to see tool calls) +- Break complex tasks into smaller steps + +### Model Fallback Triggered + +When the primary model fails, Docker Agent automatically switches to fallback models. Look for log messages like `"Switching to fallback model"`. + +- **429 errors:** Rate limited — the cooldown period keeps using the fallback +- **5xx errors:** Server issues — retries with exponential backoff first, then falls back +- **4xx errors:** Client errors — skips directly to next model + +Configure fallback behavior in your agent config: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + fallback: + models: [openai/gpt-5-mini, openai/gpt-4o-mini] + retries: 2 # retries per model for 5xx errors + cooldown: 1m # how long to stick with fallback after 429 +``` + +## Missing credentials or model errors + +When Docker Agent can't find a usable model at startup, it fails fast with an actionable error. The message names the exact next step. `docker agent doctor` is the fastest way to see the full picture — which providers have credentials, whether Docker Model Runner is reachable, and which model `auto` would pick. + +### Required environment variables not set + +An agent (or a tool it uses) depends on environment variables that aren't configured: + +```text +The following environment variables must be set: + - ANTHROPIC_API_KEY + +Provide them using any of these sources: + - Shell environment: export ANTHROPIC_API_KEY=<value> + - Env file: docker agent run --env-from-file <file> ... + - Docker Agent env file: docker agent setup (stores the key in ~/.config/cagent/.env) + +See https://docs.docker.com/ai/docker-agent/guides/secrets/ for details. +``` + +Set the variable through any of the listed [secret sources](../../guides/secrets/index.md). When the missing variable is a model-provider API key, the error also suggests running a local model instead (`docker agent run --model dmr/ai/qwen3 ...`), which needs no API key, and links to the [Set Up a Model](../../getting-started/set-up-a-model/index.md) tutorial. + +### No model available (`auto` selection failed) + +The `auto` model selector found no configured cloud provider and no usable Docker Model Runner model: + +```text +No model is currently available. + +To fix this, you can: + - Pull a Docker Model Runner model, e.g. `docker model pull ai/qwen3` + - Install Docker Model Runner: https://docs.docker.com/ai/model-runner/get-started/ + - Configure an API key for a cloud provider: + - anthropic: ANTHROPIC_API_KEY + - openai: OPENAI_API_KEY + ... +``` + +Either configure a cloud provider API key (see [API keys not set](#api-keys-not-set) below) or pull a local model. The [Set Up a Model](../../getting-started/set-up-a-model/index.md) tutorial walks through both paths. Run `docker agent doctor` to see which providers have credentials and whether Docker Model Runner is reachable. + +### Docker Model Runner model not pulled + +A `dmr/...` model was requested but isn't available locally: + +```text +model ai/qwen3 is not pulled in Docker Model Runner + +To resolve this, you can: + - Pull it first: docker model pull ai/qwen3 + - Or choose a model that is already available (see `docker model ls`). +``` + +If instead you see `cannot query Docker Model Runner at <url>`, Docker Model Runner isn't installed or running — see the [Model Runner get-started guide](https://docs.docker.com/ai/model-runner/get-started/). + +> [!TIP] +> **Diagnose before you run** +> +> Run `docker agent doctor` (or `docker agent doctor ./agent.yaml` to include a file's requirements) to check all three issues in one shot. It exits non-zero when something would block a run, making it useful as a CI preflight. See the [CLI reference](../../features/cli/index.md#docker-agent-doctor). + +## Debug Mode + +The first step for any issue is enabling debug logging. This provides detailed information about what Docker Agent is doing internally. + +```bash +# Enable debug logging (writes to ~/.cagent/cagent.debug.log) +$ docker agent run config.yaml --debug + +# Write debug logs to a custom file +$ docker agent run config.yaml --debug --log-file ./debug.log + +# Enable OpenTelemetry tracing for deeper analysis +$ docker agent run config.yaml --otel +``` + +> [!TIP] +> Always enable `--debug` when reporting issues. The log file contains detailed traces of API calls, tool executions, and agent interactions. + +## Agent Not Responding + +### API keys not set + +Each model provider requires its own API key as an environment variable: + +| Provider | Environment Variable | +| ------------- | --------------------------------------------------- | +| OpenAI | `OPENAI_API_KEY` | +| Anthropic | `ANTHROPIC_API_KEY` | +| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | +| Mistral | `MISTRAL_API_KEY` | +| xAI | `XAI_API_KEY` | +| Nebius | `NEBIUS_API_KEY` | +| MiniMax | `MINIMAX_API_KEY` | +| Requesty | `REQUESTY_API_KEY` | +| OpenRouter | `OPENROUTER_API_KEY` | +| GitHub Copilot | `GITHUB_TOKEN` (PAT with `copilot` scope) | +| Azure OpenAI | `AZURE_API_KEY` (override with `token_key`) | +| AWS Bedrock | `AWS_BEARER_TOKEN_BEDROCK` or AWS credentials chain | + +```bash +# Verify your keys are set +$ env | grep API_KEY +``` + +### Incorrect model name + +Model names must match the provider's naming exactly. Common mistakes: + +- Using a deprecated model name (e.g. `gpt-4` instead of `gpt-5-mini` or `gpt-4o`) +- Model references are case-sensitive: `openai/gpt-5-mini` ≠ `openai/GPT-5-mini` + +### Network connectivity + +If the agent hangs or times out, check that you can reach the provider's API endpoint. Firewalls, VPNs, or proxy settings may block requests. + +## Tool Execution Failures + +### MCP tools not found or failing + +- Ensure the MCP tool command is installed and on your `PATH` +- Check file permissions — tools need to be executable +- Test MCP tools independently before integrating with Docker Agent +- For Docker-based MCP tools (`ref: docker:*`), ensure Docker Desktop is running + +### Filesystem / shell tool errors + +- Verify the agent has the correct toolset configured (`type: filesystem`, `type: shell`) +- Check that the working directory exists and is accessible +- On macOS, ensure terminal has the necessary permissions (e.g., Full Disk Access) + +### Tool lifecycle issues + +MCP and LSP toolsets are managed by a supervisor that auto-restarts them when they crash or drop their session. The TUI exposes that supervisor through two slash commands: + +- `/tools` — the unified tools dialog. Its top section lists every toolset with its current state (`Stopped`, `Starting`, `Ready`, `Degraded`, `Restarting`, `Failed`), restart count, and last error; the bottom section lists every tool the agent can call. Start here whenever a tool seems missing or stuck. +- `/toolset-restart <name>` — force a supervisor-driven reconnect of the named toolset. Useful after completing OAuth, when a remote MCP server has been redeployed, or when a language server like `gopls` is unresponsive. + +Remote MCP servers that return `401 invalid_token` (e.g. because the stored OAuth token was revoked or rotated) are now self-healing: Docker Agent silently exchanges the refresh token for a new one when possible, or surfaces an OAuth re-authentication prompt on your next message when refresh is not possible. No more stuck toolsets that require a process restart — but if you want to trigger re-auth immediately, `/toolset-restart <name>` forces it right away. + +MCP tools using stdio transport must complete the initialization handshake before becoming available. If tools fail silently: + +1. Run `/tools` to see whether the toolset is `Failed` or stuck in `Restarting`, and what the last error was. +2. Enable `--debug` and look for MCP protocol messages in the log +3. Check that the MCP server process starts and responds to `initialize` +4. Verify environment variables required by the tool are set (check `env` and `env_file` in the toolset config) + +> [!NOTE] +> **Startup tool-listing timeout** +> +> At startup, Docker Agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable `--debug` to see the warning message, and use `/toolset-restart <name>` once the server becomes responsive. + +If a toolset keeps crashing in a tight loop, tune the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block on the toolset (e.g. raise `backoff.initial`, lower `max_restarts`, or switch to the `best-effort` profile) so a flaky dependency does not amplify into a restart storm. + +## Configuration Errors + +### YAML syntax issues + +Docker Agent validates config at startup and reports errors with line numbers. Common problems: + +- Incorrect indentation (YAML is whitespace-sensitive) +- Missing quotes around values containing special characters (`:`, `#`, `{`, `}`) +- Using tabs instead of spaces + +### Missing references + +- Local agents in `sub_agents` must be defined in the `agents` section (external OCI references like `myorg/agent:tag` are resolved from registries automatically) +- Named model references must exist in the `models` section (or use inline format like `openai/gpt-5`) +- RAG source names referenced by agents must be defined in the `rag` section + +### Toolset validation + +- The `path` field is valid for `memory` and `tasks` toolsets, and for the agent-level `cache` block +- MCP toolsets need either `command` (stdio), `remote` (Streamable HTTP/SSE), or `ref` (Docker) +- Provider names must be one of: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, etc. + +> [!NOTE] +> **Schema Validation** +> +> Use the [JSON schema](https://github.com/docker/docker-agent/blob/main/agent-schema.json) in your editor for real-time config validation and autocompletion. + +## Session & Connectivity Issues + +### Downgrade fails with a newer-database error + +If an older Docker Agent binary cannot open the session database after an upgrade, +the database may contain a schema migration that the older binary does not know. +Restore a database created by the older version, or use a binary that includes the +migration. + +### Port conflicts + +When running Docker Agent as an API server or MCP server, ensure the port is not already in use: + +```bash +# Check if port 8080 is in use +$ lsof -i :8080 + +# Use a different port +$ docker agent serve api config.yaml --listen :9090 +``` + +### MCP endpoint accessibility + +For remote MCP servers, verify the endpoint is reachable: + +```bash +# Test streamable HTTP endpoint +$ curl -v https://mcp-server.example.com/mcp +``` + +### Session isolation + +The API server stores every conversation as a distinct session in the SQLite database (`session.db` by default). Each session is identified by its UUID and only mixes messages when the same session ID is reused. If conversations seem to bleed into each other: + +- Make sure each client creates a fresh session via `POST /api/sessions` (don't reuse session IDs across users). +- Confirm `--session-db` points to the path you expect — a stale database from another run can resurface old sessions. +- Use `GET /api/sessions/:id` to inspect what is actually stored, and `DELETE /api/sessions/:id` to clear sessions you don't want anymore. + +### HTTP 413: request body too large + +Three kinds of process reject an oversized request body with `413 Request Entity Too Large`: `docker agent serve api`, `docker agent serve chat`, and an interactive run's control plane ([`docker agent run --listen`](../../features/api-server/index.md#listen)). They aren't configured the same way: `serve api` and `serve chat` each expose their own `--max-request-size` flag (1 MiB default). A `--listen` control plane has no such flag — it enforces a fixed, non-configurable 1 MiB limit — and no `--auth-token` either. Work through these layers in order: + +1. **Identify which server is involved.** `serve api`, `serve chat`, and an attached run's `--listen` control plane are three separate kinds of process. `serve api` and `serve chat` each have their own `--max-request-size` flag and 1 MiB default — check the flags the process that returned the 413 was actually started with. A `--listen` control plane has no `--max-request-size` flag: its 1 MiB cap is fixed. +2. **Measure the serialized request body, not a source file's size.** JSON string escaping and, for any base64-encoded binary content, base64's ~33% expansion both inflate the wire size well past the original file size — a file just under the limit can still push the encoded request over it. +3. **Rule out an intermediary.** If a reverse proxy, gateway, or load balancer sits in front of Docker Agent, it usually enforces its own, independent body-size limit — often with a differently formatted error — and can reject the request before Docker Agent ever sees it. +4. **Confirm who actually returned the error.** A 413 (or a context-length error) can also come from the model provider itself once the request reaches it; that is a separate limit unrelated to `--max-request-size` — see [Context Window Exceeded](#context-window-exceeded) above. +5. **Resolve it.** Once you've confirmed Docker Agent's own server rejected the request, send less content — split it across turns. On `serve api` or `serve chat` you can also restart the server with a deliberately chosen, larger `--max-request-size` (see [API Server](../../features/api-server/index.md#cli-flags) or [Chat Server](../../features/chat-server/index.md#cli-flags)). A `--listen` control plane has no `--max-request-size` flag to raise — sending less content is the only fix. + +A few things that catch people out: + +- `--max-request-size` is set once at process startup and applies to every request that server handles — it isn't per-request or per-client. Only `serve api` and `serve chat` have it; a `--listen` control plane's 1 MiB cap can't be changed. +- `0` or a negative value falls back to the 1 MiB default; it does not mean "no limit". +- Retrying the same oversized body against the same server won't succeed — the limit doesn't change between requests. +- On all three, the body-size check runs ahead of request authentication, so an oversized request can come back as 413 even without valid credentials. +- Piping stdin into a **local** run (`docker agent run agent.yaml -`) never crosses Docker Agent's own inbound HTTP boundary — Docker Agent may still send that content onward to a model/provider over HTTP, but no request reaches Docker Agent's own server to be measured against a `--max-request-size` cap. Piping stdin into `docker agent run --remote ... -`, however, does cross that boundary: the CLI serializes that stdin text into a native API run request and sends it to whichever Docker Agent server the `--remote` address points at — a `serve api` process or another run's `--listen` control plane, never `serve chat`, which speaks a different protocol — so it's measured against that server's own limit like any other request (a configurable `--max-request-size` for `serve api`, or the fixed 1 MiB cap for a `--listen` control plane). That initial request carries only message text — conversion currently drops any attachment resolved locally (`@path`, `/attach`, `--attach`) for the first message, so it alone can't be the cause of a 413. But a `--remote` run doesn't stay text-only for its whole lifetime: a locally resolved attachment added to a *later* message while the agent is still busy — via the default steer behavior or an explicit follow-up (Alt+Enter) — is forwarded as part of that native API request, counts toward the same limit, and can trigger 413 just like any other oversized request. + +> [!WARNING] +> Raising `--max-request-size` increases how much memory an unauthenticated or malicious client can force the server to buffer per request. Pick a value with your deployment's exposure in mind, and pair any non-loopback listener with `--auth-token` (API server) or `--api-key`/`--api-key-env` (chat server). A `--listen` control plane has neither flag — keep it on loopback, a unix socket, or behind an authenticating reverse proxy if it must be reachable from elsewhere. + +## Performance Issues + +### High memory usage + +- Large context windows (64K+ tokens) consume significant memory — consider reducing `max_tokens` +- Use `num_history_items` in agent config to limit conversation history +- For DMR (local models), tune `runtime_flags` for your hardware (e.g., `--ngl` for GPU layers) + +### Slow responses + +- Check if MCP tools are adding latency (visible in debug logs) +- Use the `/cost` command in TUI to see token usage and identify expensive interactions +- For DMR, consider enabling [speculative decoding](../../providers/dmr/index.md) for faster inference + +### Tool resource leaks + +Monitor for tools that don't clean up properly — check debug logs for MCP server start/stop lifecycle events. Orphaned tool processes can consume system resources. + +## Agent Store Issues + +### Pull / push failures + +```bash +# Test registry connectivity +$ docker pull docker.io/username/agent:latest + +# Verify pulled agent content +$ docker agent share pull docker.io/username/agent:latest +``` + +### Agent content issues + +- Ensure the pushed YAML is valid — run `docker agent run` locally before pushing +- Check that referenced resources (MCP tools, files) are available on the target machine +- For auto-refresh (`--pull-interval`), verify the registry is accessible from the server + +## Log Analysis + +When reviewing debug logs, search for these key patterns: + +| Log Pattern | What It Indicates | +| --------------------------- | ------------------------------------------------------------------------------------------------ | +| `"Starting runtime stream"` | Agent execution beginning | +| `"Tool call"` | A tool is being executed | +| `"Tool call result"` | Tool execution completed | +| `"Stream stopped"` | Agent finished processing | +| `HTTP 429` | Rate limiting — consider adding a [fallback model](../../configuration/agents/index.md) | +| `context canceled` | Operation was interrupted (timeout or user cancel) | +| `[RAG Manager]` | RAG retrieval operations | +| `[Reranker]` | Reranking operations | + +> [!WARNING] +> **Still stuck?** +> +> If these steps don't resolve your issue, file a bug on the [GitHub issue tracker](https://github.com/docker/docker-agent/issues) with your debug log attached, or ask on [Slack](https://dockercommunity.slack.com/archives/C09DASHHRU4). diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/_index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/_index.md new file mode 100644 index 000000000000..a4a44d04328a --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/_index.md @@ -0,0 +1,5 @@ +--- +title: "Core Concepts" +description: "The core ideas behind Docker Agent: agents, models, tools, and multi-agent teams." +weight: 20 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md new file mode 100644 index 000000000000..092f7af5104c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md @@ -0,0 +1,114 @@ +--- +title: "Agents" +description: "Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents." +keywords: docker agent, ai agents, concepts, agents +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/concepts/agents/ +--- + +_Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents._ + +## What is an Agent? + +An agent in Docker Agent is defined by: + +- **Model** — The AI model powering it (e.g., Claude, GPT-5, Gemini). See [Models](../models/index.md). +- **Description** — A brief summary of what the agent does (used by other agents for delegation) +- **Instruction** — The system prompt that defines the agent's behavior and personality +- **Tools** — Capabilities like filesystem access, shell commands, or external APIs +- **Sub-agents** — Other agents it can delegate tasks to + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Expert software developer + instruction: | + You are an expert developer. Write clean, efficient code + and explain your reasoning step by step. + toolsets: + - type: filesystem + - type: shell + - type: think +``` + +## The Root Agent + +Every Docker Agent configuration has a **root agent** — the entry point that receives user messages. In a single-agent setup, this is the only agent. In a multi-agent setup, the root agent acts as a coordinator, delegating tasks to specialized sub-agents. + +> [!NOTE] +> **Naming** +> +> The first agent defined in your YAML (or the one named `root`) is the root agent by default. You can also specify which agent to start with using `docker agent run config.yaml -a agent_name`. + +## Agent Properties + +| Property | Type | Required | Description | +| ---------------------- | ------- | -------- | -------------------------------------------------------------- | +| `model` | string | ✓ | Model reference (inline like `openai/gpt-5` or a named model) | +| `description` | string | ✓ | What the agent does — used by other agents for delegation | +| `instruction` | string | ✓ | System prompt defining behavior | +| `toolsets` | array | ✗ | List of tool configurations | +| `sub_agents` | array | ✗ | Names of agents this agent can delegate to | +| `fallback` | object | ✗ | Fallback model configuration for resilience | +| `add_date` | boolean | ✗ | Include current date in context | +| `add_environment_info` | boolean | ✗ | Include OS, working directory, git info in context | +| `max_iterations` | int | ✗ | Max tool-calling loops (default: unlimited) | +| `commands` | object | ✗ | Named prompts callable via `/command` | +| `skills` | boolean \| list | ✗ | Enable skill discovery and loading. `true` = `["local"]`; list values may combine `"local"` with remote skill-server URLs. | + +## Model Fallbacks + +Agents can automatically fail over to alternative models when the primary model is unavailable: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + fallback: + models: + - openai/gpt-5 + - google/gemini-3.5-flash + retries: 2 # retries per model for 5xx errors + cooldown: 1m # stick with fallback after 429 +``` + +## Named Commands + +Define reusable prompts that can be invoked as commands: + +```yaml +agents: + root: + model: openai/gpt-5 + instruction: You are a helpful assistant. + commands: + df: "Check how much free space I have on my disk" + greet: "Say hello to ${env.USER}" +``` + +```bash +# Run a named command +$ docker agent run agent.yaml /df +$ docker agent run agent.yaml /greet +``` + +Commands support environment variable interpolation using JavaScript template literal syntax. Undefined variables expand to empty strings. + +## Default Agent + +Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a capable built-in default agent for quick tasks without needing any configuration. + +```bash +# Use the project config or built-in default agent +$ docker agent run + +# Override the default with an alias +$ docker agent alias add default /path/to/my-agent.yaml +$ docker agent run # now runs your custom agent +``` + +> [!TIP] +> **See also** +> +> For reusable task-specific instructions, see [Skills](../../features/skills/index.md). For multi-agent patterns, see [Multi-Agent](../multi-agent/index.md). For full config reference, see [Agent Config](../../configuration/agents/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md new file mode 100644 index 000000000000..a2ea3aafde5f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md @@ -0,0 +1,135 @@ +--- +title: "Agent Distribution" +description: "Package, share, and run agents via OCI-compatible registries — just like container images." +keywords: docker agent, ai agents, concepts, agent distribution +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/concepts/distribution/ +aliases: + - /ai/docker-agent/sharing-agents/ +--- + +_Package, share, and run agents via OCI-compatible registries — just like container images._ + +## Overview + +Docker Agent agents can be pushed to any OCI-compatible registry (Docker Hub, GitHub Container Registry, etc.) and pulled/run anywhere. This makes sharing agents as easy as sharing Docker images. + +> [!TIP] +> For CLI commands related to distribution, see [CLI Reference](../../features/cli/index.md) (`docker agent share push`, `docker agent share pull`, `docker agent alias`). + +## Pushing Agents + +```bash +# Push to Docker Hub +$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest + +# Push to GitHub Container Registry +$ docker agent share push ./agent.yaml ghcr.io/username/my-agent:v1.0 +``` + +## Pulling Agents + +```bash +# Pull an agent +$ docker agent share pull docker.io/username/my-agent:latest + +# Pull from Docker Hub shorthand +$ docker agent share pull myorg/agent:tag +``` + +## Running from a Registry + +Run agents directly from a registry without pulling first: + +```bash +# Run directly from Docker Hub +$ docker agent run docker.io/username/my-agent:latest + +# Docker Hub shorthand (docker.io is implied) +$ docker agent run myorg/agent:tag + +# Run with a specific agent from a multi-agent config +$ docker agent run docker.io/username/dev-team:latest -a developer +``` + +## Using as Sub-Agents + +Registry agents can be used directly as sub-agents in a multi-agent configuration — no need to define them locally: + +```yaml +agents: + root: + model: openai/gpt-5 + description: Coordinator + instruction: Delegate tasks to the right sub-agent. + sub_agents: + - myorg/agent:tag # auto-named "agent" + - my_reviewer:myorg/reviewer # explicitly named "my_reviewer" +``` + +External sub-agents are automatically named after their last path segment. Use the `name:reference` syntax to give them a custom name. + +Tag references are checked against the registry on every `docker agent run`, which adds a network round-trip per sub-agent at startup. Pin them to a digest (`myorg/agent@sha256:…`) to serve them from cache instead. + +See [Pin external sub-agents to a digest](../multi-agent/index.md#pin-external-sub-agents-to-a-digest) and [External Sub-Agents](../multi-agent/index.md#external-sub-agents-from-registries) for details. + +## Using with Aliases + +Combine OCI references with aliases for convenient access: + +```bash +# Create an alias for a registry agent +$ docker agent alias add coder myorg/coder --yolo + +# Now just run +$ docker agent run coder +``` + +## Using with API Server + +The API server supports OCI references with auto-refresh: + +```bash +# Start API from registry, auto-pull every 10 minutes +$ docker agent serve api docker.io/username/agent:latest --pull-interval 10 +``` + +## Private Repositories + +Docker Agent supports pulling from private GitHub repositories and registries that require authentication. Use standard Docker login or GitHub authentication: + +```bash +# Login to a registry +$ docker login docker.io + +# Now push/pull works with private repos +$ docker agent share push ./agent.yaml docker.io/myorg/private-agent:latest +$ docker agent run docker.io/myorg/private-agent:latest +``` + +> [!NOTE] +> **Docker authentication** +> +> When pulling or running an agent from a `docker.com` or `*.docker.com` HTTPS URL (e.g. `desktop.docker.com`), Docker Agent automatically forwards a Docker token for authentication. If Docker Desktop is running and signed in, its token is used; otherwise, Docker Agent exchanges the access token stored by `docker login` for a fresh Docker token. Either way, no explicit login step is required beyond `docker login` (or being signed into Docker Desktop). +> +> Note: `docker.io` (the standard Docker Hub registry domain) is a separate domain and is **not** covered by automatic token forwarding. Agents pulled from `docker.io` or `registry-1.docker.io` still require `docker login docker.io` for private repositories. + +> [!NOTE] +> **Troubleshooting** +> +> Having issues with push/pull? See [Troubleshooting](../../community/troubleshooting/index.md) for common registry issues. + +## Local Development + +For local development and testing, you can run an agent directly from a local HTTP server without a registry: + +```bash +# Serve an agent config locally +$ python3 -m http.server 8080 + +# Run it directly via HTTP +$ docker agent run http://localhost:8080/agent.yaml +$ docker agent run http://127.0.0.1:8080/agent.yaml +``` + +This is useful for iterating on agent configs served from a local dev server before pushing to a registry. Both `localhost` and `127.0.0.1` addresses are supported with plain `http://` URLs. diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md new file mode 100644 index 000000000000..d966769d4562 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md @@ -0,0 +1,175 @@ +--- +title: "Models" +description: "Models are the AI brains behind your agents. Docker Agent supports multiple providers and flexible configuration." +keywords: docker agent, ai agents, concepts, models +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/concepts/models/ +--- + +_Models are the AI brains behind your agents. Docker Agent supports multiple providers and flexible configuration._ + +## Inline vs. Named Models + +There are two ways to assign a model to an agent: + +### Inline (Quick) + +Use the `provider/model` shorthand directly in the agent definition: + +```yaml +agents: + root: + model: openai/gpt-5 + instruction: You are a helpful assistant. +``` + +### Named (Full Control) + +Define models in a `models` section and reference them by name: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + temperature: 0.7 + +agents: + root: + model: claude + instruction: You are a helpful assistant. +``` + +Named models let you configure temperature, token limits, thinking budgets, and other parameters. They're also reusable across multiple agents. + +## First Available Models + +A named model can also select the first usable model from a priority list. This +is useful for shared configs that should prefer paid cloud models when their API +keys are present, but still work with a local fallback: + +```yaml +models: + smart: + first_available: + - anthropic/claude-sonnet-4-5 + - openai/gpt-5 + - dmr/ai/qwen3 + +agents: + root: + model: smart + instruction: You are a helpful assistant. +``` + +At load time, Docker Agent selects the first candidate whose credentials are +configured. You only need credentials for one candidate. See +[Model Configuration](../../configuration/models/index.md#first-available-models) +for details. + +## Supported Providers + +| Provider | Key | Example Models | API Key Env Var | +| ------------------- | ---------------- | ------------------------------------ | ----------------------------------- | +| OpenAI | `openai` | gpt-5, gpt-5-mini, gpt-4o | `OPENAI_API_KEY` | +| Anthropic | `anthropic` | claude-sonnet-4-5, claude-opus-5 | `ANTHROPIC_API_KEY` | +| Google | `google` | gemini-3.5-flash, gemini-3-pro | `GOOGLE_API_KEY` / `GEMINI_API_KEY` | +| AWS Bedrock | `amazon-bedrock` | Claude, Nova, Llama models | AWS credentials | +| Docker Model Runner | `dmr` | ai/qwen3, ai/llama3.2 | None (local) | +| Mistral | `mistral` | Mistral models | `MISTRAL_API_KEY` | +| xAI | `xai` | Grok models | `XAI_API_KEY` | +| Nebius | `nebius` | Open-source and specialised models | `NEBIUS_API_KEY` | +| NVIDIA NIM | `nvidia` | Nemotron, Llama, Qwen, DeepSeek (open models) | `NVIDIA_API_KEY` | +| MiniMax | `minimax` | MiniMax models | `MINIMAX_API_KEY` | +| Baseten | `baseten` | DeepSeek, Kimi, GLM, Llama models | `BASETEN_API_KEY` | +| OVHcloud | `ovhcloud` | Qwen, Llama, Mistral, DeepSeek (EU-hosted) | `OVH_AI_ENDPOINTS_ACCESS_TOKEN` | +| Groq | `groq` | Llama, Qwen, GPT-OSS (fast inference) | `GROQ_API_KEY` | +| Fireworks AI | `fireworks` | Kimi, Llama, Qwen, DeepSeek, GLM (open models) | `FIREWORKS_API_KEY` | +| DeepSeek | `deepseek` | DeepSeek-V3 chat and R1 reasoner | `DEEPSEEK_API_KEY` | +| Cerebras | `cerebras` | GPT-OSS, GLM (fast inference) | `CEREBRAS_API_KEY` | +| Together AI | `together` | Llama, Qwen, DeepSeek, Kimi (open models) | `TOGETHER_API_KEY` | +| Hugging Face | `huggingface` | Llama, Qwen, DeepSeek, GLM (open models) | `HF_TOKEN` | +| Cloudflare Workers AI | `cloudflare-workers-ai` | Llama, Mistral, Qwen, Gemma (edge-hosted open models) | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` | +| Moonshot AI | `moonshot` | Kimi K2 chat, reasoning, and coding models | `MOONSHOT_API_KEY` | +| Vercel AI Gateway | `vercel` | Multi-provider gateway | `AI_GATEWAY_API_KEY` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | Multi-provider gateway | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID` | +| Requesty | `requesty` | Multi-provider gateway | `REQUESTY_API_KEY` | +| OpenRouter | `openrouter` | Multi-provider gateway | `OPENROUTER_API_KEY` | +| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_API_KEY` + `base_url` | +| [Ollama](../../providers/local/index.md) | `ollama` | Any local Ollama model | None (local; optional `base_url`) | +| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) | +| ChatGPT (OpenAI account) | `chatgpt` | gpt-5 family via ChatGPT subscription | None (sign in via `docker agent setup`) | + +See the [Model Providers](../../providers/overview/index.md) section for detailed configuration guides. + +## Model Properties + +| Property | Type | Description | +| ------------------- | ---------- | ------------------------------------------------- | +| `provider` | string | Provider identifier (required) | +| `model` | string | Model name (required) | +| `description` | string | Human-readable summary of the model's purpose | +| `temperature` | float | Randomness: 0.0 (deterministic) to 1.0 (creative) | +| `max_tokens` | int | Maximum response length | +| `top_p` | float | Nucleus sampling: 0.0 to 1.0 | +| `frequency_penalty` | float | Reduce repetition: 0.0 to 2.0 | +| `presence_penalty` | float | Encourage topic diversity: 0.0 to 2.0 | +| `base_url` | string | Custom API endpoint | +| `thinking_budget` | string/int | Reasoning effort configuration | +| `task_budget` | int/object | Total token budget for an agentic task (Anthropic; honored by Opus 4.7 today) | +| `provider_opts` | object | Provider-specific options | + +## Reasoning / Thinking Budget + +Control how much the model "thinks" before responding: + +| Provider | Format | Values | Default | +| ---------- | ---------- | ------------------------------------------------------------------- | -------------------------------- | +| OpenAI | string | `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | `medium` (always-reasoning models only) | +| Anthropic | int or str | 1024–32768 tokens, or `adaptive`, `adaptive/<effort>`, effort level | off | +| Gemini 2.5 | int | 0 (off), -1 (dynamic), or token count | -1 (dynamic) | +| Gemini 3 | string | `minimal`, `low`, `medium`, `high` | varies | +| All | string/int | `none` or `0` clears Docker Agent's local config | — | + +`none` and `0` are not universal API-level disable switches. On genuine OpenAI +gpt-5.6+ endpoints (Sol/Terra/Luna), `none` is a real `reasoning_effort` value +that Docker Agent sends as-is and the model does not reason. On older OpenAI +models, `none`/`0` only clear the local `thinking_budget` — omitting the field +has the same effect — and the model falls back to the API's own default effort +(still reasoning internally for always-reasoning models like the o-series). +Providers with a true optional-thinking switch (Gemini 2.5, Claude, local +models) are fully disabled by `none`/`0`. See the +[Thinking / Reasoning guide](../../guides/thinking/index.md#disabling-thinking) +for the full per-provider breakdown. + +```yaml +models: + deep-thinker: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 16384 + + fast-responder: + provider: openai + model: gpt-5.6 + thinking_budget: none # real API-level disable on gpt-5.6+ +``` + +> [!NOTE] +> **Multi-provider teams** +> +> Different agents can use different providers in the same config. See [Multi-Agent](../multi-agent/index.md) for patterns. + +## Alloy Models + +"Alloy models" let you use more than one model in the same conversation — Docker Agent alternates between them to leverage the strengths of each: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5,openai/gpt-5 + instruction: You are a helpful assistant. +``` + +Read more about the alloy model concept at [xbow.com/blog/alloy-agents](https://xbow.com/blog/alloy-agents). diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md new file mode 100644 index 000000000000..e9632ff020d5 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md @@ -0,0 +1,421 @@ +--- +title: "Multi-Agent Systems" +description: "Build teams of specialized agents that collaborate and delegate tasks to each other." +keywords: docker agent, ai agents, concepts, multi-agent systems +linkTitle: "Multi-Agent" +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/concepts/multi-agent/ +--- + +_Build teams of specialized agents that collaborate and delegate tasks to each other._ + +## Why Multi-Agent? + +Complex tasks benefit from specialization. Instead of one monolithic agent trying to do everything, you can create a **team** of focused agents: + +- A **coordinator** that understands the overall goal and delegates +- A **developer** that writes code with filesystem and shell access +- A **reviewer** that checks code quality +- A **researcher** that searches the web for information + +Each agent has its own model, tools, and instructions — optimized for its specific role. + +## Two Patterns: Delegation vs. Handoffs + +Docker Agent supports two multi-agent patterns: + +| | **Delegation** (`sub_agents`) | **Handoffs** (`handoffs`) | +|---|---|---| +| **Topology** | Hierarchical (parent → child → parent) | Peer-to-peer graph (A → B → C → A) | +| **Session** | Child runs in a **sub-session** | Conversation stays in the **same session** | +| **Context** | Child gets a clean task description | Next agent sees the **full conversation history** | +| **Control flow** | Parent blocks until child finishes, then continues | Active agent switches — previous agent is no longer in the loop | +| **Tool** | `transfer_task` | `handoff` | +| **Best for** | Task delegation to specialists | Pipeline workflows, conversational routing | + +You can combine both patterns in the same configuration — an agent can have both `sub_agents` and `handoffs`. + +> [!TIP] +> **When to use which** +> +> **`sub_agents`** — Use when a coordinator needs to send tasks to specialists and synthesize their results. +> +> **`handoffs`** — Use when agents should take turns processing the same conversation (pipelines, routing). +> +> **`background_agents`** — Use when multiple independent tasks can run simultaneously. + +## Delegation with `sub_agents` + +Agents delegate tasks using the built-in `transfer_task` tool, which is automatically available to any agent with `sub_agents`. The parent agent sends a task to a child agent, waits for the result, and then continues. + +1. **User** sends a message to the root agent +2. **Root agent** analyzes the request and decides which sub-agent should handle it +3. **Root agent** calls `transfer_task` with the target agent, task description, and expected output +4. **Sub-agent** processes the task in its own agentic loop using its tools +5. **Results** flow back to the root agent, which responds to the user + +```bash +# The transfer_task tool call looks like: +transfer_task( + agent="developer", + task="Create a REST API endpoint for user authentication", + expected_output="Working Go code with tests" +) +``` + +> [!NOTE] +> **Auto-Approved** +> +> Unlike other tools, `transfer_task` is always auto-approved — no user confirmation needed. This allows seamless delegation between agents. + +## Handoffs Routing + +Handoffs are a peer-to-peer routing pattern where agents **hand off the entire conversation** to another agent. Unlike delegation, there is no sub-session — the conversation stays in a single session and the active agent simply switches. + +This pattern is ideal for: + +- **Pipeline workflows** — data flows through a chain of specialized agents +- **Conversational routing** — a coordinator routes the user to the right specialist, who can route back when done +- **Graph topologies** — agents can form cycles (A → B → C → A), enabling iterative workflows + +### How It Works + +1. **User** sends a message to the starting agent +2. **Agent A** processes the message, then calls `handoff` to route to **Agent B** +3. **Agent B** becomes the active agent and sees the **full conversation history** +4. **Agent B** can respond, use its own tools, or hand off to another agent +5. This continues until an agent responds directly without handing off + +```bash +# The handoff tool call looks like: +handoff( + agent="summarizer" +) +``` + +> [!NOTE] +> **Scoped Handoff Targets** +> +> Each agent can only hand off to agents listed in its own `handoffs` array. The `handoff` tool is automatically injected — you don't need to add it manually. + +### Example + +A coordinator routes to a researcher, who hands off to a summarizer, who returns to the coordinator: + +```text +Root ──→ Researcher ──→ Summarizer ──→ Root +``` + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Coordinator that routes queries + instruction: | + Route research queries to the researcher. + handoffs: + - researcher + + researcher: + model: openai/gpt-5 + description: Web researcher + instruction: | + Search the web, then hand off to the summarizer. + toolsets: + - type: mcp + ref: docker:duckduckgo + handoffs: + - summarizer + + summarizer: + model: openai/gpt-5 + description: Summarizes findings + instruction: | + Summarize the research results, then hand off + back to root. + handoffs: + - root +``` + +> [!TIP] +> **Full pipeline example** +> +> For a more complex handoff graph with branching and multiple processing stages, see [`examples/handoff.yaml`](https://github.com/docker/docker-agent/blob/main/examples/handoff.yaml). + +### Forced Handoffs + +With `handoffs`, the **model decides** whether to call the `handoff` tool — which means it can forget to, breaking pipelines that depend on a strict order. `force_handoff` removes that uncertainty: whenever the agent produces a final response, the **runtime itself** routes the conversation to the named agent, bypassing the LLM's tool-calling entirely. The full conversation context carries over. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Extracts key facts from the input + instruction: | + Extract the key facts from the user's input as a bullet list. + force_handoff: summarizer + + summarizer: + model: anthropic/claude-sonnet-4-5 + description: Produces the final summary + instruction: | + Summarize the extracted facts for the user. +``` + +Rules enforced at config load time: + +- The target must be an agent defined in the config (or an external reference) +- An agent cannot `force_handoff` to itself +- Chains of `force_handoff` edges must not form a cycle (A → B → A is rejected) + +See [`examples/force_handoff.yaml`](https://github.com/docker/docker-agent/blob/main/examples/force_handoff.yaml) for a runnable example. + +## Parallel Delegation with Background Agents + +`transfer_task` is **sequential** — the coordinator waits for the sub-agent to finish before continuing. When you need to fan out work to multiple agents at the same time, use the `background_agents` toolset instead. + +Add it to your coordinator's toolsets: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Research coordinator + sub_agents: [researcher, analyst, writer] + toolsets: + - type: think + - type: background_agents +``` + +The coordinator can then: + +1. **Dispatch** several tasks at once with `run_background_agent` — each returns a task ID immediately +2. **Monitor** progress with `list_background_agents` or `view_background_agent` +3. **Collect** results once tasks complete +4. **Cancel** tasks that are no longer needed with `stop_background_agent` + +```bash +# Start two tasks in parallel +run_background_agent(agent="researcher", task="Find recent papers on LLM agents") +run_background_agent(agent="analyst", task="Analyze our current architecture") + +# Check on all tasks +list_background_agents() + +# Read results when ready +view_background_agent(task_id="agent_task_abc123") +``` + +## External Sub-Agents from Registries + +Sub-agents don't have to be defined locally — you can reference agents from any OCI-compatible registry directly in your `sub_agents` list. This lets you compose teams using shared agents without duplicating their configuration. + +```yaml +agents: + root: + model: openai/gpt-5 + description: Coordinator that delegates to local and external sub-agents + instruction: | + Delegate tasks to the most appropriate sub-agent. + sub_agents: + - local_helper + - myorg/agent:tag # pulled from registry automatically + + local_helper: + model: openai/gpt-5 + description: A local helper agent for simple tasks + instruction: You are a helpful assistant. +``` + +External sub-agents are automatically named after their last path segment (without the tag) — for example, `myorg/agent:tag` becomes `agent`. You can also give them an explicit name using the `name:reference` syntax: + +```yaml + sub_agents: + - my_agent:myorg/agent:tag # available as "my_agent" + - reviewer:docker.io/myorg/review-agent:latest +``` + +### Pin external sub-agents to a digest + +External references use a tag by default: `myorg/agent` is shorthand for `myorg/agent:latest`. Tag references are re-resolved against the registry on **every** `docker agent run`: each unpinned external sub-agent triggers a digest lookup at startup, even when that sub-agent is never invoked in the session. On a healthy connection this typically adds a second or two per reference (it depends on your network and registry), and it is one of the paths that can stall if the registry or credential helper misbehaves. + +Pinning a reference to an immutable digest (`@sha256:…`) makes the runtime serve it straight from the local cache with no network round-trip, so startup stays fast and your team is fully reproducible: + +```yaml + sub_agents: + - reviewer:docker.io/myorg/review-agent@sha256:44117e73263afa5c861bdf3730dae7925918ffdd146827eee5bcff20bc55e8fa +``` + +Copy the digest from your registry (Docker Hub shows it next to the tag) or read it with a standard OCI tool such as `docker buildx imagetools inspect <reference>`. Docker Agent logs a startup warning for any external OCI reference that still uses a tag instead of a digest. + +External references in `handoffs` and `force_handoff` carry the same per-run cost, so pin those to a digest too. + +> [!TIP] +> External sub-agents work with any OCI-compatible registry. See [Agent Distribution](../distribution/index.md) for more on registry references. +> +> See [`examples/sub-agents-from-registry.yaml`](https://github.com/docker/docker-agent/blob/main/examples/sub-agents-from-registry.yaml) for a complete example mixing local and external sub-agents. + +## Harness-Backed Sub-Agents + +Sub-agents can be backed by external coding CLIs — Claude Code, Codex, opencode, or pi — instead of a model API. Add a `harness:` block in place of a `model:` field to create a harness sub-agent: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Orchestrator that plans and delegates + instruction: | + Break down coding tasks and delegate to the coding agents. + sub_agents: + - claude-coder + - codex-coder + + claude-coder: + description: Claude Code specialist + harness: + type: claude-code + effort: high + + codex-coder: + description: Codex specialist + harness: + type: codex +``` + +The orchestrator uses `transfer_task` to send work to a harness sub-agent just like any other sub-agent. Docker Agent handles the orchestration and hooks; the external CLI drives the coding loop. + +> [!TIP] +> **Learn more** +> +> See [Coding Harnesses](../../features/harnesses/index.md) for the full field reference, parallel dispatch patterns, and what does not work inside harness agents. + +## Example: Development Team + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Technical lead coordinating development + instruction: | + You are a technical lead managing a development team. + Analyze requests and delegate to the right specialist. + Ensure quality by reviewing results before responding. + sub_agents: [developer, reviewer, tester] + toolsets: + - type: think + + developer: + model: anthropic/claude-sonnet-4-5 + description: Expert software developer + instruction: | + You are an expert developer. Write clean, efficient code + and follow best practices. + toolsets: + - type: filesystem + - type: shell + - type: think + + reviewer: + model: openai/gpt-5 + description: Code review specialist + instruction: | + You review code for quality, security, and maintainability. + Provide actionable feedback. + toolsets: + - type: filesystem + + tester: + model: openai/gpt-5 + description: Quality assurance engineer + instruction: | + You write tests and ensure software quality. Run tests + and report results. + toolsets: + - type: shell + - type: todo +``` + +## Example: Research Team + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Research coordinator + instruction: | + Coordinate research tasks. Delegate web searches to + the researcher and writing to the writer. + sub_agents: [researcher, writer] + toolsets: + - type: think + + researcher: + model: openai/gpt-5 + description: Web researcher + instruction: Search the web and gather information. + toolsets: + - type: mcp + ref: docker:duckduckgo + - type: memory + path: ./research.db + + writer: + model: anthropic/claude-sonnet-4-5 + description: Content writer + instruction: Write clear, well-structured content. + toolsets: + - type: filesystem +``` + +## Multi-Model Teams + +A key advantage of multi-agent systems is using different models for different roles — picking the best model for each job: + +```yaml +models: + fast: + provider: openai + model: gpt-5-mini + temperature: 0.2 # precise + + creative: + provider: openai + model: gpt-5 + temperature: 0.8 # creative + + local: + provider: dmr + model: ai/qwen3 # runs locally, no API cost + +agents: + analyst: + model: fast # cheap and fast for analysis + writer: + model: creative # creative for content + helper: + model: local # free for simple tasks +``` + +## Shared Tools + +Tools like `todo` can be shared between agents for collaborative task tracking: + +```yaml +toolsets: + - type: todo + shared: true # all agents see the same todo list +``` + +## Best Practices + +- **Keep agents focused** — Each agent should have a clear, narrow role +- **Write clear descriptions** — The coordinator uses descriptions to decide who to delegate to +- **Give minimal tools** — Only give each agent the tools it needs for its specific role +- **Use the think tool when needed** — For models without native reasoning, give coordinators the think tool so they reason about delegation. Models with built-in thinking (e.g., via `thinking_budget`) don't need it +- **Use the right model** — Use capable models for complex reasoning, cheap models for simple tasks +- **Choose the right pattern** — Use `sub_agents` for hierarchical task delegation, `handoffs` for pipeline workflows and conversational routing + +> [!NOTE] +> **Beyond Docker Agent** +> +> For interoperability with other agent frameworks, Docker Agent supports the [A2A protocol](../../features/a2a/index.md) and can expose agents via [MCP Mode](../../features/mcp-mode/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md new file mode 100644 index 000000000000..149e876d9a7a --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md @@ -0,0 +1,78 @@ +--- +title: "Tools" +description: "Tools give agents the ability to interact with the world — read files, run commands, search the web, query databases, and more." +keywords: docker agent, ai agents, concepts, tools +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/concepts/tools/ +--- + +_Tools give agents the ability to interact with the world — read files, run commands, search the web, query databases, and more._ + +## How Tools Work + +When an agent needs to perform an action, it makes a **tool call**. The Docker Agent runtime executes the tool and returns the result to the agent, which can then use it to continue its work. + +1. Agent receives a user message +2. Agent decides it needs to use a tool (e.g., read a file) +3. Docker Agent executes the tool and returns the result +4. Agent incorporates the result and responds + +> [!NOTE] +> **Tool Confirmation** +> +> By default, Docker Agent asks for user confirmation before executing tools that have side effects (shell commands, file writes). Use `--yolo` to auto-approve all tool calls. + +## Built-in Tools + +Docker Agent ships with several built-in tools that require no external dependencies. Each is enabled by adding its `type` to the agent's `toolsets` list: + +| Tool | Description | +| --- | --- | +| [Filesystem](../../tools/filesystem/index.md) | Read, write, list, search, and navigate files and directories | +| [Shell](../../tools/shell/index.md) | Execute shell commands synchronously | +| [Background Jobs](../../tools/background-jobs/index.md) | Run and manage long-running shell commands | +| [Think](../../tools/think/index.md) | Step-by-step reasoning scratchpad for planning and decision-making | +| [Todo](../../tools/todo/index.md) | Task list management for complex multi-step workflows | +| [Tasks](../../tools/tasks/index.md) | Persistent task database shared across sessions | +| [Memory](../../tools/memory/index.md) | Persistent key-value storage backed by SQLite | +| [Fetch](../../tools/fetch/index.md) | Read content from HTTP/HTTPS URLs (GET only) | +| [Script](../../tools/script/index.md) | Define custom shell scripts as named tools | +| [LSP](../../tools/lsp/index.md) | Connect to Language Server Protocol servers for code intelligence | +| [API](../../tools/api/index.md) | Create custom tools that call HTTP APIs without writing code | +| [OpenAPI](../../tools/openapi/index.md) | Generate tools from an OpenAPI 3.x document | +| [RAG](../../tools/rag/index.md) | Retrieval-augmented generation over indexed sources | +| [Model Picker](../../tools/model-picker/index.md) | Let the agent pick between several models per turn | +| [User Prompt](../../tools/user-prompt/index.md) | Ask users questions and collect interactive input | +| [Open URL](../../tools/open-url/index.md) | Open a fixed URL in the user's default browser | +| [Transfer Task](../../tools/transfer-task/index.md) | Delegate tasks to sub-agents (auto-enabled with `sub_agents`) | +| [Background Agents](../../tools/background-agents/index.md) | Dispatch work to sub-agents concurrently | +| [Handoff](../../tools/handoff/index.md) | Hand the conversation off to another local agent in the same config (auto-enabled with `handoffs:`) | +| [A2A](../../tools/a2a/index.md) | Connect to remote agents via the Agent-to-Agent protocol | +| [MCP Catalog](../../tools/mcp-catalog/index.md) | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | +| [Git](../../tools/git/index.md) | Read-only git repository inspection | +| [Scheduler](../../tools/scheduler/index.md) | Schedule instructions to run at a time or on a recurring interval | +| [Webhook](../../tools/webhook/index.md) | Outbound notifications to Slack, Discord, Telegram, IFTTT, and more | +| [Plan](../../tools/plan/index.md) | Shared persistent scratchpad for multi-agent collaboration | +| [Session Plan](../../tools/session_plan/index.md) | Per-session plan tracker for the draft/review/execute workflow | +| [Session Context](../../tools/session_context/index.md) | Reference a previous session as context | + +## MCP Tools + +Docker Agent supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for extending agents with external tools. There are three ways to connect MCP tools: + +- **Docker MCP** (recommended) — Run MCP servers in Docker containers via the [MCP Gateway](https://github.com/docker/mcp-gateway). Browse the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp). +- **Local MCP (stdio)** — Run MCP servers as local processes communicating over stdin/stdout. +- **Remote MCP (Streamable HTTP / SSE)** — Connect to MCP servers running on a network. See [Remote MCP Servers](../../features/remote-mcp/index.md). + +```yaml +toolsets: + - type: mcp + ref: docker:duckduckgo +``` + +See [Tool Config](../../configuration/tools/index.md#mcp-tools) for full MCP configuration reference. + +> [!TIP] +> **See also** +> +> For full configuration reference, see [Tool Config](../../configuration/tools/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/_index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/_index.md new file mode 100644 index 000000000000..7b70d5fcfd0f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/_index.md @@ -0,0 +1,5 @@ +--- +title: "Configuration" +description: "Complete reference for configuring agents in YAML or HCL." +weight: 30 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md new file mode 100644 index 000000000000..9da240a9cb06 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md @@ -0,0 +1,618 @@ +--- +title: "Agent Configuration" +description: "Complete reference for defining agents in your YAML configuration." +keywords: docker agent, ai agents, configuration, yaml, agent configuration +linkTitle: "Agent Config" +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/configuration/agents/ +--- + +_Complete reference for defining agents in your YAML configuration._ + +A configuration must define at least one agent under `agents`. + +## Full Schema + +<!-- yaml-lint:skip --> +```yaml +agents: + agent_name: + model: string # Required: model reference + description: string # Required: what this agent does + instruction: string # Required (unless instruction_file): system prompt + instruction_file: string | [list] # Optional: load the system prompt from one or more files relative to this config (mutually exclusive with instruction) + sub_agents: [list] # Optional: local or external sub-agent references + toolsets: [list] # Optional: tool configurations (use `type: rag` for RAG sources) + fallback: # Optional: fallback config + models: [list] + retries: 2 + cooldown: 1m + add_date: boolean # Optional: add date to context + add_environment_info: boolean # Optional: add env info to context + add_prompt_files: [list] # Optional: include additional prompt files + add_description_parameter: bool # Optional: add description to tool schema + redact_secrets: boolean # Optional: scrub detected secrets out of tool args, outgoing chat messages, and tool output + code_mode_tools: boolean # Optional: let the agent write JavaScript to orchestrate tool calls (see Code Mode) + max_iterations: int # Optional: max tool-calling loops + max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls + max_old_tool_call_tokens: int # Optional: token budget for old tool call content (disabled unless positive) + max_tool_result_tokens: int # Optional: per-tool-result token cap with middle-out truncation (disabled unless positive) + num_history_items: int # Optional: limit conversation history + session_compaction: boolean # Optional: disable automatic session compaction (default: true) + compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9) + compaction_model: string # Optional: model used for session-compaction (summary generation) + use_toolsets: [list] # Optional: names of top-level toolsets to merge into this agent + readonly: boolean # Optional: restrict all toolsets to read-only tools only + skills: boolean | [list] # Optional: enable skill discovery (true/false or list of names and/or sources) + use_commands: [list] # Optional: names of top-level commands groups to merge into this agent + use_skills: [list] # Optional: names of top-level skills groups to merge into this agent + commands: # Optional: named prompts + name: "prompt text" # or {instruction: "prompt", agent: "sub_agent_name"} or {url: "https://..."} (TUI only) + welcome_message: string # Optional: message shown at session start + handoffs: [list] # Optional: agent names this agent can hand off to + force_handoff: string # Optional: agent that always receives the conversation when this agent stops + hooks: # Optional: lifecycle hooks + pre_tool_use: [list] + tool_response_transform: [list] + post_tool_use: [list] + session_start: [list] + session_end: [list] + on_user_input: [list] + stop: [list] + notification: [list] + structured_output: # Optional: constrain output format + name: string + schema: object + cache: # Optional: response cache (skip the model on repeat questions) + enabled: boolean + case_sensitive: boolean + trim_spaces: boolean + path: string + harness: # Optional: delegate to an external coding CLI (Claude Code, Codex, opencode, pi) + type: string # Required: claude-code | codex | opencode | pi + model: string # Optional: model override forwarded to the CLI (omit for the CLI's own default) + effort: string # claude-code only: low | medium | high | xhigh | max (omit for the Claude Code default) + agent: string # opencode only: agent profile name + thinking: boolean # opencode only: enable extended thinking +``` + +> [!TIP] +> **See also** +> +> For model parameters, see [Model Config](../models/index.md). For tool details, see [Tool Config](../tools/index.md). For multi-agent patterns, see [Multi-Agent](../../concepts/multi-agent/index.md). + +## Properties Reference + +| Property | Type | Required | Description | +| --------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `model` | string | ✓ | Model reference. Either inline (`openai/gpt-5`) or a named model from the `models` section. | +| `description` | string | ✓ | Brief description of the agent's purpose. Used by coordinators to decide delegation. | +| `instruction` | string | ✓ | System prompt that defines the agent's behavior, personality, and constraints. Required unless `instruction_file` is set. | +| `instruction_file` | string \| array | ✗ | Path(s) to a file or files (relative to the config file's directory) whose contents become the agent's instruction, loaded at startup. Accepts a single path or a list; multiple files are concatenated in order, separated by a blank line. Mutually exclusive with `instruction`. Each path must be a local relative path inside the config directory (absolute paths and `..` traversal are rejected). Only supported for local file-based configs, not OCI/URL sources. See [External Instruction Files](#external-instruction-files) below. | +| `sub_agents` | array | ✗ | List of agent names or external OCI references this agent can delegate to. Supports local agents, registry references (e.g., `myorg/agent:tag`), and named references (`name:reference`). Automatically enables the `transfer_task` tool. Pin external OCI references to a digest (`name@sha256:…`) to skip the per-run registry lookup that tag references incur. See [External Sub-Agents](../../concepts/multi-agent/index.md#external-sub-agents-from-registries). | +| `toolsets` | array | ✗ | List of tool configurations. See [Tool Config](../tools/index.md). | +| `fallback` | object | ✗ | Automatic model failover configuration. | +| `add_date` | boolean | ✗ | When `true`, injects the current date into the agent's context. | +| `add_environment_info` | boolean | ✗ | When `true`, injects working directory, OS, CPU architecture, and git info into context. | +| `add_prompt_files` | array | ✗ | List of file paths whose contents are appended to the system prompt. Useful for including coding standards, guidelines, or additional context. | +| `add_description_parameter` | boolean | ✗ | When `true`, adds agent descriptions as a parameter in tool schemas. Helps with tool selection in multi-agent scenarios. | +| `redact_secrets` | boolean | ✗ | When `true`, scrubs detected secrets (API keys, tokens, private keys, etc.) out of tool-call arguments, outgoing chat messages, and tool output before they reach a tool, the model, or downstream consumers. See [Redacting Secrets](#redacting-secrets) below. | +| `code_mode_tools` | boolean | ✗ | When `true`, replaces the agent's individual tools with a single tool that runs a JavaScript script calling as many of them as needed in one turn. See [Code Mode](../../features/code-mode/index.md). | +| `max_iterations` | int | ✗ | Maximum number of tool-calling loops. Default: unlimited (0). Set this to prevent infinite loops. | +| `max_consecutive_tool_calls` | int | ✗ | Maximum consecutive identical tool calls before the agent is terminated, preventing degenerate loops. Default: `5`. | +| `max_old_tool_call_tokens` | int | ✗ | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). | +| `max_tool_result_tokens` | int | ✗ | Maximum number of tokens to keep from each tool result when it is added to the session. Oversized results are truncated middle-out: the head and tail are kept and the removed middle is replaced with a truncation marker. Textual documents attached to the result share the same budget. Tokens are approximated as `len/4`. The cap is disabled by default; set a positive value to enable it. `0` and `-1` both leave tool results unbounded. | +| `num_history_items` | int | ✗ | Limit the number of conversation history messages sent to the model. Useful for managing context window size with long conversations. Default: unlimited (all messages sent). | +| `session_compaction` | boolean | ✗ | When `false`, disables automatic session compaction for this agent: neither the proactive threshold trigger nor the post-overflow auto-recovery runs. The manual `/compact` command remains available. Default: `true`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `compaction_threshold` | float | ✗ | Fraction of the model's context window at which proactive auto-compaction triggers. Must be greater than `0` and at most `1`. A `compaction_threshold` set on the agent's model takes precedence. Default: `0.9`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `compaction_model` | string | ✗ | Model used for session compaction (summary generation). Can be a named model or an inline `provider/model` string. This agent-level value takes precedence over a `compaction_model` set on the agent's model or provider; when none is set, the agent's own model compacts. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `skills` | bool/array | ✗ | Enable automatic skill discovery. `true` loads all discovered local skills, `false` disables them. A list can mix skill sources (`local` or `https://…` URLs) and skill names to include — see [Skills](../../features/skills/index.md). | +| `commands` | object | ✗ | Named prompts that can be run with `docker agent run config.yaml /command_name`. Can be simple strings or objects with `instruction` and/or `agent` fields for agent switching, or a `url` field to open a link in the browser (TUI only). See [Named Commands](#named-commands) below. | +| `use_commands` | list of string | ✗ | Names of top-level `commands` groups to merge into this agent. Inline `commands` entries take precedence on name conflicts. Default: `[]`. | +| `use_skills` | list of string | ✗ | Names of top-level `skills` groups to merge into this agent. Inline skills are deduplicated by name against merged entries. Default: `[]`. | +| `use_toolsets` | list of string | ✗ | Names of top-level `toolsets` groups to merge into this agent. See [Reusable Toolsets](../overview/index.md#reusable-toolsets-toolsets). Default: `[]`. | +| `readonly` | boolean | ✗ | When `true`, every toolset on this agent is filtered to expose only read-only tools (those annotated with a read-only hint). Mutating tools are removed at load time and cannot be called even if the model tries. See [Read-Only Agents](#read-only-agents) below. | +| `welcome_message` | string | ✗ | Message displayed to the user when a session starts. Rendered as Markdown in the TUI. **Not sent to the model** — it exists purely for the user's benefit. Useful for telling users what the agent can do and what commands are available. | +| `handoffs` | array | ✗ | List of agent names this agent can hand off the conversation to. Enables the `handoff` tool. See [Handoffs Routing](../../concepts/multi-agent/index.md#handoffs-routing). | +| `force_handoff` | string | ✗ | Name of an agent that unconditionally receives the conversation whenever this agent produces a final response. The runtime performs the switch itself, bypassing the LLM's tool-calling, guaranteeing deterministic pipelines. Must not reference the agent itself, and chains must not form a cycle. See [Forced Handoffs](../../concepts/multi-agent/index.md#forced-handoffs). | +| `hooks` | object | ✗ | Lifecycle hooks for running commands at various points. See [Hooks](../hooks/index.md). | +| `structured_output` | object | ✗ | Constrain agent output to match a JSON schema. See [Structured Output](../structured-output/index.md). | +| `cache` | object | ✗ | Response cache. When the same user question is asked again, the previous answer is replayed verbatim and the model is not called. See [Response Cache](#response-cache) below. | +| `harness` | object | ✗ | Run this agent through an external coding CLI instead of a model. **Note:** Any `toolsets:` defined on the same agent are silently ignored when `harness:` is set — the external CLI brings its own tools. See [Coding Harnesses](../../features/harnesses/index.md). | + +> [!WARNING] +> **max_iterations** +> +> Default is `0` (unlimited). Always set `max_iterations` for agents with powerful tools like `shell` to prevent infinite loops. A value of 20–50 is typical for development agents. + +> [!TIP] +> **Managing long sessions** +> +> `max_old_tool_call_tokens`, `max_tool_result_tokens`, `num_history_items`, `session_compaction`, and `compaction_threshold` all help keep long-running sessions inside the model's context window. See the [Context & Compaction guide](../../guides/compaction/index.md) for how to combine them. + +## External Instruction Files + +Long system prompts can be kept in their own files instead of being inlined in +the YAML, using `instruction_file`. This separates infrastructure configuration +(models, providers, tools) from behavioral content (the prompt), which keeps +version-control diffs focused, reduces merge conflicts on shared configs, and +lets instruction content be edited without risking YAML syntax errors. + +```yaml +agents: + coordinator: + model: openai/gpt-5-mini + description: Routes work between specialist agents + instruction_file: instructions/coordinator.md + sub_agents: + - writer + writer: + model: openai/gpt-5-mini + description: Drafts and edits written content + instruction_file: instructions/writer.md +``` + +The path is resolved relative to the config file's directory and the file's +contents are loaded as the agent's instruction when the config is loaded. Notes: + +- **Mutually exclusive** with `instruction`. Setting both is an error. +- Each path must be a **local relative path inside the config directory**. + Absolute paths and `..` traversal are rejected. +- A **list** of files is also accepted; their contents are concatenated in + order, separated by a blank line. This lets a shared preamble be reused + across agents while each agent appends its own specifics: + + ```yaml + agents: + writer: + model: openai/gpt-5-mini + description: Drafts and edits written content + instruction_file: + - instructions/shared-preamble.md + - instructions/writer.md + ``` + +- Only supported for **local file-based configs**, not agents loaded from OCI + registries or URLs. When an agent is pushed with `docker agent share push`, + the file contents are inlined into the pushed artifact, so the published + agent stays self-contained. + +A runnable example lives in [`examples/instruction_file.yaml`](https://github.com/docker/docker-agent/blob/main/examples/instruction_file.yaml). + +## Prompt Files + +`add_prompt_files` injects the contents of one or more files into the agent's +context at the start of every turn — handy for repo-wide conventions like +`AGENTS.md` or `CLAUDE.md` that should stay available without being pasted +into `instruction`: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A helpful coding assistant + instruction: You are an expert software developer. + add_prompt_files: + - AGENTS.md +``` + +For each name, the agent loads the closest match found by walking up from the +current working directory, plus (if it's a different file) a copy at that +name directly under the user's home directory — so a personal `~/AGENTS.md` +can layer on top of a repo-local one. Missing files are skipped rather than +erroring. Because resolution and the read happen on every turn, edits to the +file are picked up without restarting the agent. + +Use `--prompt-file` to add files for a single run without editing the +config. It's merged with any `add_prompt_files` already set on the agent, +with duplicates dropped: + +```bash +$ docker agent run agent.yaml --prompt-file CONTRIBUTING.md +``` + +Resolved prompt files show up as their own entries in the `/context` dialog — see [File Attachments](../../features/tui/index.md#file-attachments) in the Terminal UI guide. + +See [Choosing a Large-Input Strategy](../../guides/headless/index.md#choosing-a-large-input-strategy) for how prompt files compare to `@`/`/attach` attachments, the `rag` toolset, and sending content over the API/chat server. + +## Response Cache + +The response cache short-circuits the model when the same user question is asked again. The first time a question is asked, the agent calls the model normally and stores the assistant's reply. Subsequent identical questions skip the model entirely and replay the stored reply verbatim. + +```yaml +agents: + root: + model: openai/gpt-5 + description: Cached assistant + instruction: You are a helpful assistant. + cache: + enabled: true # required to turn the cache on + case_sensitive: false # default: false ("Hello" == "hello") + trim_spaces: true # default: false (" hello " == "hello") + path: ./cache.json # optional: persist to disk; omit for in-memory +``` + +| Property | Type | Default | Description | +| ---------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | boolean | `false` | Master switch. When `false` (or when the `cache` section is omitted), no caching is performed. | +| `case_sensitive` | boolean | `false` | When `true`, questions must match exactly (including case) to hit the cache. | +| `trim_spaces` | boolean | `false` | When `true`, leading and trailing whitespace is stripped from the question before it is compared. | +| `path` | string | _empty_ | When set, cache entries are persisted to a JSON file at the given path and reloaded on startup so the cache survives restarts. Relative paths resolve against the agent config directory. When empty, the cache lives in memory only. | + +**How it works** + +- The cache key is the latest user message in the session, normalized according to `case_sensitive` and `trim_spaces`. +- On a hit, the cached reply is added to the session as the assistant message and stop hooks fire normally — the rest of the agent (tools, sub-agents, the model) is bypassed. +- On a miss, the agent runs normally; the final assistant message produced by the first stop of the run is then stored under the question's key. +- Only the response to the original user question of a run is cached; follow-up turns inside the same `RunStream` are not. + +**File-backed storage** + +When `path` is set, every `Store` rewrites the entire cache file. Writes are **atomic**: the new content is written to a sibling temp file, `fsync`'d, and renamed over the destination, so a concurrent reader (or a process that crashes mid-write) will always see either the previous content or the new content in full — never a partially written file. The parent directory is also `fsync`'d after the rename so the rename itself is durable. + +**Cross-process sharing** + +Multiple processes can share the same `path:` cache file safely. Every `Store` takes an exclusive advisory lock on a sibling `<path>.lock` file (POSIX `flock(2)` on Unix, `LockFileEx` on Windows), reloads the current on-disk state under the lock, merges the new entry, and writes back atomically. Two processes that store *different* keys at the same time both see their writes preserved on disk; the lock window is short (one read + one fsync'd write). + +`Lookup` watches the file's modification time and reloads the in-memory map when the file has advanced since its last load, so writes from a sibling process become visible without a restart. The `<path>.lock` sentinel file is created on first write and never deleted: removing it would let two processes lock different inodes and lose mutual exclusion. + +## Redacting Secrets + +The `redact_secrets` flag is a single agent-level switch that scrubs accidentally leaked credentials, tokens, and private keys out of an agent's I/O. It wires up three complementary defenses: + +1. A `pre_tool_use` built-in hook that scrubs detected secrets from the **arguments of every tool call**, before the tool sees them. +2. A `before_llm_call` built-in hook that scrubs the same patterns from **outgoing chat messages** — message content, multi-part text content, prior reasoning content, and the JSON-encoded arguments of any tool call still in the conversation — before they reach the model provider. +3. A `tool_response_transform` built-in hook that scrubs **tool output at the source**, so the secret never reaches event consumers, the persisted session file, the `post_tool_use` hook input, or the next LLM call. + +```yaml +agents: + root: + model: openai/gpt-5 + description: A helpful assistant that scrubs secrets before they leak + instruction: | + You are a helpful assistant. If the user accidentally pastes a token, + do your best work without echoing the secret back. + redact_secrets: true + toolsets: + - type: shell +``` + +Detection uses the [portcullis](https://github.com/docker/portcullis) ruleset, which recognises common secret patterns including: + +- GitHub Personal Access Tokens (`ghp_*`, `gho_*`, `ghu_*`, `ghs_*`, `ghr_*`, fine-grained `github_pat_*`) +- AWS access keys (`AKIA*`, `ASIA*`, …) and secret access keys +- GitLab PATs (`glpat-*`), Hugging Face tokens (`hf_*`) +- Stripe (`sk_live_*`, `pk_test_*`, …), Slack (`xoxb-*`, …), Shopify, Twilio, Discord, Atlassian, Mailchimp, SendGrid, and many more +- JWTs, GCP service-account JSON, Heroku keys, Docker Hub PATs (`dckr_pat_*`) +- PEM-encoded private keys (`-----BEGIN … PRIVATE KEY-----` blocks) + +Each detected span is replaced with the literal string `[REDACTED]`; the surrounding text is preserved so a redacted argument still looks like a legitimate flag (e.g. `--token=[REDACTED]`). Redaction is idempotent — applying it twice yields the same result. + +> [!NOTE] +> **False positives vs. false negatives** +> +> False positives are extremely rare: every rule pairs a regex with a discriminating keyword, so plain English never trips detection. **False negatives are possible** — only patterns the ruleset recognises are scrubbed, so this is a defense-in-depth feature, not a substitute for keeping secrets out of the conversation in the first place. Pair it with a proper [secret manager](../../guides/secrets/index.md) for the credentials your agent actually needs. + +> [!NOTE] +> **Equivalent hook entry** +> +> Setting `redact_secrets: true` on the agent is shorthand for auto-registering all three legs of the feature as hook entries. They share the _same_ built-in name (`type: builtin`, `command: redact_secrets`) on `pre_tool_use`, `before_llm_call`, and `tool_response_transform` respectively — the implementation dispatches on the hook event. You can spell them out by hand to scope a leg to a subset of tools (set `matcher:` to a regex), stack them with other rewriters in a specific order, or enable just one or two legs. See [`examples/redact_secrets_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/redact_secrets_hooks.yaml) for a complete manual wiring and the [Hooks reference](../hooks/index.md#available-built-ins) for the builtin's event coverage. + +## Welcome Message + +Display a message when users start a session: + +```yaml +agents: + assistant: + model: openai/gpt-5 + description: Development assistant + instruction: You are a helpful coding assistant. + welcome_message: | + 👋 Welcome! I'm your development assistant. + + I can help you with: + - Writing and reviewing code + - Running tests and debugging + - Explaining concepts + + What would you like to work on? +``` + +## Deferred Tool Loading + +Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Multi-purpose assistant + instruction: You have access to many tools. + toolsets: + - type: mcp + ref: docker:github-official + defer: true + - type: filesystem +``` + +## Fallback Configuration + +Automatically switch to backup models when the primary fails: + +| Property | Type | Default | Description | +| ---------- | ------ | ------- | ---------------------------------------------------------- | +| `models` | array | `[]` | Fallback models to try in order | +| `retries` | int | `2` | Retries per model for 5xx errors. `-1` to disable. | +| `cooldown` | string | `1m` | How long to stick with a fallback after a rate limit (429) | + +**Error handling:** + +- **Retryable** (same model with backoff): HTTP 5xx, 408, network timeouts +- **Non-retryable** (skip to next model): HTTP 429, 4xx client errors + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + fallback: + models: + - openai/gpt-5 + - google/gemini-3.5-flash + retries: 2 + cooldown: 1m +``` + +## Named Commands + +> [!TIP] +> **Full reference** +> +> This section covers the basics. For URL commands, agent-switching commands, reusable top-level `commands:` groups, and hiding commands with `--disable-commands`, see [Custom Commands](../commands/index.md). + +Define reusable prompt shortcuts that can send prompts to the current agent, switch to a different sub-agent, or open a URL in the browser: + +> **Note:** Named slash commands execute immediately, even while the agent is processing another message. Unlike regular chat messages (which are queued), slash commands interrupt or direct the agent even while it is mid-response. + +```yaml +agents: + root: + model: openai/gpt-5 + instruction: You are a system administrator. + commands: + df: "Check how much free space I have on my disk" + logs: "Show me the last 50 lines of system logs" + greet: "Say hello to ${env.USER}" + deploy: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}" + + # Advanced format with agent switching + plan: + agent: planner # Switch to the 'planner' agent + instruction: "Create a detailed plan for: ${args.join(\" \")}" # Optional: send this prompt after switching + + # Agent switching without instruction - forwards remaining text as prompt + review: + agent: reviewer # Any text after /review is sent to the reviewer agent + + # URL command - opens a link in the browser instead of messaging the agent + docs: + description: "Open the documentation" + url: https://docs.docker.com/ +``` + +### Command Formats + +Commands support three formats: + +1. **Simple string format**: The string becomes the instruction sent to the current agent + + ```yaml + df: "Check disk space" + ``` + +2. **Advanced object format**: Supports agent switching and optional instructions + + ```yaml + plan: + agent: planner # Required: name of any agent defined in the team + instruction: "Plan: ${args.join(\" \")}" # Optional: prompt to send after switching + description: "Switch to planning mode" # Optional: shown in help text + ``` + +3. **URL format**: Opens a link in the browser instead of messaging the agent + + ```yaml + docs: + url: https://docs.docker.com/ # Required: URL to open + description: "Open the documentation" # Optional: shown in help text + ``` + +When `agent` is set without `instruction`, any text typed after the slash command (e.g., `/plan build a web app`) is forwarded as a prompt to the target agent. The target agent can be **any agent defined in the team configuration** — it does not need to be listed in the current agent's `sub_agents` array. + +**Argument and expansion syntax** + +An `instruction` string can reference the command's arguments and expand tool calls: + +- `${args[0]}`, `${args[1]}`, … — individual positional arguments, in the order the user typed them after the command +- `${args.join(" ")}` — all arguments joined into a single string +- `${tool_name({...})}` — calls a tool and inlines its return value (any tool available to the agent) +- `!tool_name(key=value)` — legacy tool-call form: calls a tool with plain `key=value` arguments and inlines its output + +### Agent-Switching Commands + +Commands with an `agent` field switch the active agent for that command's scope. This is useful for building workflow shortcuts where `/plan`, `/review`, `/deploy` each route the user to the appropriate specialist. + +```yaml +agents: + root: + model: openai/gpt-5 + description: Main assistant + instruction: You are a project coordinator. + sub_agents: [planner, reviewer] + commands: + # Switch to planner with a pre-filled prompt + plan: + agent: planner + instruction: "Create a detailed plan for: ${args.join(\" \")}" + # Switch to reviewer; any text after /review is forwarded + review: + agent: reviewer + # Simple prompt command (no switching) + status: "Summarize what we have accomplished so far" + + planner: + model: openai/gpt-5 + description: Planning specialist + instruction: You create detailed project plans. + + reviewer: + model: anthropic/claude-sonnet-4-5 + description: Code review specialist + instruction: You review code and suggest improvements. +``` + +**Agent-switching vs. `handoff`** + +| | Agent-switching command | `handoff` tool | +| --- | --- | --- | +| **Trigger** | User runs `/command` | Model calls `handoff()` | +| **Session** | Stays in the same session | Stays in the same session | +| **History** | Target agent sees full conversation | Target agent sees full conversation | +| **Return** | User must explicitly switch back | Target agent can chain to another agent | + +**Agent-switching vs. `transfer_task`** + +`transfer_task` launches a **sub-session**: the root agent sends a task, the child runs in isolation, and the result is returned to the root. The root agent stays in control and the child's work is never in the main conversation. Use `transfer_task` (via `sub_agents`) when you want delegation with a clean result; use agent-switching commands when you want to *become* a different agent for the rest of the conversation. + +See [`examples/agent_switching_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/agent_switching_commands.yaml) for a complete example. + +```bash +# Run commands from the CLI +$ docker agent run agent.yaml /df +$ docker agent run agent.yaml /greet +$ PROJECT_NAME=myapp ENV=production docker agent run agent.yaml /deploy +``` + +Commands use JavaScript template literal syntax (`${env.VAR}`) for environment variable interpolation. Undefined variables expand to empty strings. + +The same syntax is also expanded in agent and toolset instructions: `agents.<name>.instruction` and `toolsets[*].instruction` support `${env.X}` placeholders (with optional `||` defaults and ternary expressions). `agents.<name>.description` and `agents.<name>.welcome_message` also support it. + +Note that path-like fields (`working_dir`, `path`) primarily use a shell-style syntax (`$VAR`, `${VAR}`, `~`), and also accept `${env.X}` as an alias (though not richer JS expressions). See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full table. + +### URL Commands + +A command with a `url` field opens that URL in the user's default browser instead of sending a prompt to the agent. Any URI scheme the OS knows how to dispatch works — both standard web URLs and custom schemes such as `docker-desktop://` for deep links. URL commands are TUI-only — they have no effect when run from the CLI. + +```yaml +agents: + root: + model: openai/gpt-5 + description: An agent with handy URL shortcuts. + instruction: You are a helpful assistant. + commands: + feedback: + description: "Open the feedback site for this session" + url: https://example.com/feedback?session={{session_id}} + docs: + description: "Open the documentation" + url: https://docs.docker.com/ + desktop: + description: "Open this session in Docker Desktop" + url: docker-desktop://dashboard/session/{{session_id}} +``` + +The `{{session_id}}` token is replaced at invocation time with the current session ID (URL-query-escaped so it can't break the URL or inject extra query parameters), letting a command deep-link to something scoped to the conversation. This token deliberately uses `{{...}}` rather than the `${...}` JS-expansion syntax, since the session ID is only known at dispatch time. + +URLs are validated before being handed to the OS opener: a parseable URL with a non-empty scheme is required, and flag-like inputs (those starting with `-`) are rejected to prevent argument injection. + +See [`examples/url_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/url_commands.yaml) for a complete example. + +## Read-Only Agents + +Set `readonly: true` on an agent to restrict all of its toolsets to tools that are annotated as read-only. Mutating tools are filtered out at load time — the agent cannot list or call them, even if the model hallucinates a call. + +You can also set `readonly: true` on an individual toolset to restrict only that toolset while leaving others unrestricted. + +```yaml +agents: + # Agent-level readonly: every toolset is restricted to read-only tools. + inspector: + model: anthropic/claude-sonnet-4-5 + description: Read-only inspector that can explore but never modify. + instruction: Explore the project. Do not make changes. + readonly: true + toolsets: + - type: filesystem + - type: shell + + # Toolset-level readonly: only the filesystem toolset is restricted; + # the shell toolset keeps all of its tools. + mixed: + model: anthropic/claude-sonnet-4-5 + description: Read-only file access, full shell access. + instruction: You can read files and run any shell command. + toolsets: + - type: filesystem + readonly: true + - type: shell +``` + +See [`examples/readonly.yaml`](https://github.com/docker/docker-agent/blob/main/examples/readonly.yaml) for a complete example. + +> [!NOTE] +> **Which tools are read-only?** +> +> Whether a tool is read-only is determined by its `ReadOnlyHint` annotation. For built-in tools, read-only operations (list/read/search) carry the hint; mutating operations (write/delete/execute) do not. Custom and MCP tools expose the hint via their own annotations. + +## Complete Example + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + +agents: + root: + model: claude + description: Technical lead coordinating development + instruction: | + You are a technical lead. Analyze requests and delegate + to the right specialist. Always review work before responding. + welcome_message: "👋 I'm your tech lead. How can I help today?" + sub_agents: [developer, researcher] + add_date: true + add_environment_info: true + fallback: + models: [openai/gpt-5] + toolsets: + - type: think + commands: + review: "Review all recent code changes for issues" + hooks: + session_start: + - type: command + command: "./scripts/setup.sh" + + developer: + model: claude + description: Expert software developer + instruction: Write clean, tested, production-ready code. + max_iterations: 30 + toolsets: + - type: filesystem + - type: shell + - type: think + - type: todo + + researcher: + model: openai/gpt-5 + description: Web researcher with memory + instruction: Search for information and remember findings. + toolsets: + - type: mcp + ref: docker:duckduckgo + - type: memory + path: ./research.db +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md new file mode 100644 index 000000000000..67bbcf96ee75 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md @@ -0,0 +1,105 @@ +--- +title: "Ignoring files" +description: "Hide files from the agent with a .agentsignore file, using the same syntax as .gitignore." +keywords: docker agent, ai agents, configuration, agentsignore, gitignore, ignore, secrets +weight: 75 +canonical: https://docs.docker.com/ai/docker-agent/configuration/agentsignore/ +--- + +_Hide files from the agent with a `.agentsignore` file, using the same syntax as `.gitignore`._ + +## Overview + +Put a `.agentsignore` file in your project and the agent stops seeing the paths it lists. Matched files are absent from directory listings and searches, and reads, writes and edits targeting them are refused. + +```text +# .agentsignore +secrets.env +*.key +.env.* +build/ +docs/**/*.draft.md +!public.key +``` + +There is nothing to configure. The file's presence is the opt-in, and it is picked up automatically by the [filesystem toolset](../../tools/filesystem/index.md). + +## Syntax + +The syntax is `.gitignore` syntax — parsed with the same library git uses, so patterns behave identically to `.gitignore` and `.dockerignore`: + +| Pattern | Matches | +| --- | --- | +| `secrets.env` | that name at any depth (`secrets.env`, `config/secrets.env`) | +| `/secrets.env` | that name at the project root only | +| `*.key` | any file with the extension | +| `build/` | the directory and everything under it | +| `docs/**/*.draft.md` | nested matches via `**` | +| `!public.key` | re-includes a path an earlier pattern excluded | +| `# comment` | ignored, as are blank lines | + +## Where the file is found + +The nearest `.agentsignore` at or above the working directory is used, so starting a run in a subdirectory still honours the project's file. Patterns are anchored to the directory containing the file, exactly as git anchors to the directory containing `.gitignore`. + +Unlike `.gitignore`, **a git repository is not required** — `.agentsignore` works in any directory. + +## What it affects + +| Behaviour | Effect | +| --- | --- | +| `list_directory`, `directory_tree` | matched entries are omitted | +| `search_files_content` | matched files are skipped | +| `read_file`, `read_multiple_files` | refused | +| `write_file`, `edit_file` | refused, including for files that do not exist yet | +| `create_directory`, `remove_directory` | refused | +| `permissions` | matching deny rules are derived automatically, so `/permissions` shows them | + +Paths are resolved before matching — symlinks, `./` prefixes and `..` segments are all normalised — so an ignored file cannot be reached by spelling it differently. + +The `.agentsignore` file is itself always hidden: it names the very things being kept back, so handing it to the agent would be a map of what to look for. + +> [!NOTE] +> `.agentsignore` is independent of the filesystem toolset's [`ignore_vcs`](../tools/index.md) option. Setting `ignore_vcs: false` turns off `.gitignore` filtering but does **not** un-hide `.agentsignore` entries. + +## Relationship to `.gitignore` + +They are separate, and they do different amounts of work. + +`.gitignore` is respected by default (`ignore_vcs`), but only as a **display filter**: gitignored files are hidden from listings and searches while `read_file` still opens them. That is reasonable for build output, which is noise rather than secret. + +`.agentsignore` is for content the agent should not have at all, so it blocks reads and writes as well. Use `.gitignore` for noise, `.agentsignore` for secrets. + +## Limits + +> [!WARNING] +> `.agentsignore` governs the filesystem toolset. It is **not** a sandbox. +> +> An agent with the [`shell`](../../tools/shell/index.md) toolset can still run `cat secrets.env`, because the shell runs commands the toolset never inspects. The same applies to any toolset that reaches the filesystem on its own, such as [`lsp`](../../tools/lsp/index.md). +> +> Treat `.agentsignore` as a strong default that keeps sensitive files out of the agent's view and context — not as a boundary against an agent actively trying to reach them. When you need a real boundary, combine it with [permissions](../permissions/index.md) that restrict `shell`, or run in [sandbox mode](../sandbox/index.md). + +The derived permission rules are best-effort for the same reason: permission patterns match the argument string as the model wrote it, without resolving it first, so `./secrets.env` can slip past a rule written for `secrets.env`. The filesystem toolset's own check resolves paths first and is the part that actually enforces. + +## Example + +```text +# .agentsignore + +# Secrets +.env +.env.* +secrets.env +*.pem +*.key +!public.key # this one is safe to read + +# Credentials directories +.aws/ +.ssh/ + +# Large build output the agent doesn't need +build/ +dist/ +node_modules/ +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md new file mode 100644 index 000000000000..07086c2c5d8e --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md @@ -0,0 +1,217 @@ +--- +title: "Budget" +description: "Cap what a single run may spend in money, tokens, or working time." +keywords: docker agent, ai agents, configuration, yaml, budget, cost, limits +weight: 75 +canonical: https://docs.docker.com/ai/docker-agent/configuration/budget/ +--- + +_Cap what a single run may spend in money, tokens, or working time._ + +## Overview + +A budget sets ceilings on a run. When a ceiling is crossed the run stops with a message naming the exact limit that tripped, and the TUI tracks consumption live while the run is still going. + +Every limit is optional and an unset limit is unlimited, so you can cap money, tokens, time, or any combination. Declare no budget at all and runs are unbudgeted, which is the default. + +There are two ways to declare one, and they compose: + +| Block | Scope | +| --- | --- | +| `budget` | One run-wide ceiling, charged for every agent. | +| `budgets` | Named budgets an agent opts into by name. | + +### A run-wide budget + +```yaml +agents: + root: + model: openai/gpt-4o-mini + description: An agent on a short leash. + instruction: You are a helpful assistant. + +budget: + max_cost: 0.50 + max_tokens: 100000 + max_time: 10m +``` + +| Field | Type | Description | +| --- | --- | --- | +| `max_cost` | number | Maximum spend, in USD. | +| `max_tokens` | integer | Maximum cumulative input+output tokens. | +| `max_time` | string | Maximum time the agents spend working, in Go duration format (`10m`, `30s`, `1h30m`). | + +### Named budgets + +Define budgets by name under the top-level `budgets` key, then have each agent opt in by listing names in its own `budgets` field. The fields are the same three. + +```yaml +budgets: + shell-work: + max_cost: 0.03 + max_tokens: 8000 + research: + max_time: 1m + +agents: + root: + model: openai/gpt-4o-mini + description: Does shell work. + instruction: You are a helpful assistant. + budgets: [shell-work] + researcher: + model: openai/gpt-4o-mini + description: Answers questions. + instruction: You answer questions concisely. + budgets: [shell-work, research] +``` + +An agent may list several budgets; all of them apply, and the first to be exhausted stops the run. A run-wide `budget` applies on top of any named budget, so the ceiling that binds is whichever runs out first. + +Referencing a budget name that isn't defined is a config error, caught at parse time rather than silently leaving the agent uncapped. + +## A name is one shared pot + +When several agents reference the same budget name they draw from the **same** ceiling — not a copy each. Above, `root` and `researcher` share `shell-work`: together they cannot spend more than `$0.03`. + +This is deliberate, and it is the whole reason budgets are worth having. If each agent received its own allowance, a run could spend `max_cost` × N simply by fanning out to N sub-agents, and the ceiling would mean nothing for exactly the workloads that most need one. + +Give agents **distinct budget names** when you want independent pots. + +The same applies to the run-wide `budget`: every sub-session inside a run (transferred tasks, sub-agents, skills) spends from that one wallet. + +## Scope: a budget spans the session + +Spend accumulates for the life of the **session**, across every message you send — it does not reset each time you hit enter. A `max_cost: 0.50` you could re-spend on every message would not be a ceiling at all. + +Starting a new session starts a fresh budget. It is a per-session ceiling, not a lifetime quota across sessions. + +> [!NOTE] +> `max_time` measures the time the agents actually spend **working** — the sum of their turn durations — not wall-clock since the session opened. Because a budget spans a session, and a session sits idle while you read and type, wall-clock would let a budget expire during a coffee break: leave the TUI open for ten minutes and your next message would instantly trip a `max_time` of `2m` without the agent having done anything. + +## What stops a run + +Crossing any limit — run-wide or named — stops the run and produces: + +- an assistant message in the transcript naming the limit and the amounts, +- a `budget_exceeded` event carrying `budget`, `limit`, `used`, `max`, `config_path` and, under `stop_message`, the assistant stop message itself (agent name, role, content and timestamp only), +- a `notification` hook at `warning` level, +- a stream end reason of `budget_exceeded`, so a stopped run is distinguishable from a completed one in telemetry. + +The message names the exact YAML path to raise, so there is no ambiguity about which of several budgets tripped: + +```text +Execution stopped after reaching the configured budgets.shell-work.max_cost +limit (used $0.0312 of $0.0300). +``` + +Unlike [`max_iterations`](../agents/index.md), a budget stop is **terminal** — there is no prompt offering to continue. A budget is a ceiling you set deliberately, so raising it means editing the config rather than answering a dialog. + +## Budget stops in evaluation output + +When a budgeted agent is exercised with `docker agent eval`, a budget stop is recorded as a structured termination. It is not an error, and it is distinct from an ordinary stream stop: the run output JSON exposes it as an optional `eval_result.termination` object on the affected session. + +```json +"eval_result": { + "passed": true, + "termination": { + "reason": "budget_exceeded", + "budget": "run", + "limit": "max_cost", + "used": "$0.0312", + "max": "$0.0300", + "config_path": "budget.max_cost", + "message": "Execution stopped after reaching the configured budget.max_cost limit (used $0.0312 of $0.0300)." + } +} +``` + +- `reason` is always `budget_exceeded`. The other fields are optional and are copied from the runtime's `budget_exceeded` event through an allow-list: only `budget`, `limit`, `used`, `max`, `config_path`, and `message` are ever taken, each sanitized (invalid UTF-8 and control characters stripped, bounded length) and omitted when missing or unusable. +- The stored session (SQLite database and sessions JSON) keeps the stop marker at its chronological position, followed exactly once by the assistant stop message rebuilt from the event's embedded `stop_message` (again only agent name, role, content, and timestamp are taken, sanitized the same way). When the event carries no usable `stop_message`, the marker stands alone; nothing is invented from `termination.message`. +- The termination is informational: it does not change `passed`, `failures`, or `error`. A run that completed normally or failed with an error simply has no `termination` field, and older outputs written before the field existed load unchanged. + +## Tracking spend in the TUI + +The sidebar's Token Usage panel lists every active budget by name, with consumption against each ceiling it declares: + +```text +run $0.12/$0.50 · 12.3K/100.0K · 2m14s/10m +shell-work $0.09/$0.10 · 4.3K/20.0K +``` + +Only the ceilings you configured appear. Each reading is colored by the sidebar's shared gauge bands — the same ones a context gauge uses as it nears compaction — so a budget turns amber well before its ceiling and red just short of it, and a run about to be stopped is visible before it stops. + +For a per-agent view of who spent what, set **Sidebar info mode** to `Detailed` in `/settings` → Appearance: the Agents section then reports each agent's cost alongside its effort and context. The budget line deliberately does not repeat that breakdown — the same numbers twice would crowd the sidebar's narrowest column. The per-agent split is still carried on the `budget_usage` event for programmatic consumers, and `/cost` has a **By Agent** section. + +## Limits and caveats + +### Unpriced models do not count towards `max_cost` + +Only responses the runtime can price count towards `max_cost`. A model with no pricing data — an unknown model ID, or a custom endpoint such as a local or private deployment — contributes nothing, because there is no honest number to add. + +Such a run emits a warning and the TUI marks the reading `(unpriced spend)`, rather than silently reading low because the spend is invisible. To make a custom endpoint count, price it explicitly with a model-level [`cost`](../models/index.md#custom-token-pricing) block: + +```yaml +models: + local: + provider: openai + model: my-model + base_url: http://localhost:8000/v1 + cost: + input: 0.15 + output: 0.60 + +agents: + root: + model: local + description: A locally-served agent with real cost accounting. + instruction: You are a helpful assistant. + +budget: + max_cost: 0.50 +``` + +### Limits are checked at turn boundaries + +A run is checked between turns, so it can overshoot by at most the turn already in flight. `max_time` in particular will not interrupt a model call or tool that has already started; the run stops at the first boundary after the limit is reached. + +This is the same granularity [`max_iterations`](../agents/index.md) has, and it keeps the ceiling out of the streaming hot path. Set limits with a little headroom rather than at the exact number you cannot exceed. + +### `max_tokens` here is not the model's `max_tokens` + +The `max_tokens` in a budget is a **cumulative** count of input+output tokens across the whole run. It is unrelated to the provider- or model-level [`max_tokens`](../models/index.md), which caps the output of a single response. + +It is also not the session's context length: compaction resets that, while the budget keeps counting. + +## Examples + +Cap money only, and let the run take as long as it needs: + +```yaml +agents: + root: + model: openai/gpt-4o + description: A cost-capped agent. + instruction: You are a helpful assistant. + +budget: + max_cost: 5.00 +``` + +Cap working time for an unattended job: + +```yaml +agents: + root: + model: openai/gpt-4o-mini + description: A time-boxed agent. + instruction: You are a helpful assistant. + toolsets: + - type: shell + +budget: + max_time: 15m +``` + +See [`examples/budget.yaml`](https://github.com/docker/docker-agent/blob/main/examples/budget.yaml) for a runnable configuration. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md new file mode 100644 index 000000000000..1b621b1f1a6e --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md @@ -0,0 +1,218 @@ +--- +title: "Custom Commands" +description: "Define slash commands that send prompts, open URLs, or switch agents, and reuse them across agents with top-level command groups." +keywords: docker agent, ai agents, configuration, yaml, custom commands, slash commands +linkTitle: "Custom Commands" +weight: 55 +canonical: https://docs.docker.com/ai/docker-agent/configuration/commands/ +--- + +_Define slash commands that send prompts, open URLs, or switch agents._ + +## What Slash Commands Are + +A slash command is a named shortcut a user types in the TUI (`/df`, `/deploy`, `/plan`) or on the CLI (`docker agent run agent.yaml /df`) instead of typing out a full prompt. Every agent can declare its own commands under `commands:`, and top-level `commands:` groups let multiple agents share the same set without duplicating them. + +Unlike regular chat messages — which are queued while the agent is busy — slash commands (both built-in and named) execute immediately, even mid-response. + +Commands come in three shapes: + +| Shape | What it does | +| --- | --- | +| [Prompt command](#prompt-commands) | Sends a prompt to the current agent | +| [URL command](#url-commands) | Opens a link in the user's browser (full TUI only) | +| [Agent-switching command](#agent-switching-commands) | Switches the active agent, optionally with a prompt (full TUI and CLI) | + +> [!IMPORTANT] +> **Behavior differs by frontend** +> +> `url` and `agent` are only fully honored in the **full TUI**, which checks `url` before `agent` (a URL command opens the browser and stops there; an agent-switching command switches before sending any instruction). The **lean TUI** doesn't special-case either field — it only resolves a command's expanded text and sends it as a chat message, so a URL-only command silently sends whatever trailing text followed the slash (often nothing, opening no browser) and an agent-switching command sends its instruction to the *current* agent instead of the target. The **CLI** (`docker agent run agent.yaml /command`) switches agents like the full TUI, but has no browser to open, so `url` has no effect there. The **HTTP API** (`POST /api/sessions/:id/agent/:agent`) resolves agent-switching commands server-side: if the message content starts with a slash command whose `agent` field is set, the active agent is switched and the message is rewritten before the turn runs. Prompt-only and URL commands are not resolved server-side and pass through to the model unchanged. + +## Prompt Commands + +The simplest form: a string value that becomes the instruction sent to the current agent. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A system administrator assistant. + instruction: You are a system administrator. + commands: + df: "Check how much free space I have on my disk" + logs: "Show me the last 50 lines of system logs" + greet: "Say hello to ${env.USER}" +``` + +For more control, use the object form with an `instruction:` field, plus an optional `description:` shown in completion dialogs and help text: + +```yaml +commands: + deploy: + description: "Deploy the application to staging" + instruction: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}" +``` + +Commands support JavaScript template literal syntax (`${env.VAR}`) for environment variable interpolation, with optional `||` defaults and ternary expressions — the same syntax as agent `instruction` and `description`. Undefined variables expand to the empty string. See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full picture. + +Prompt commands can also reference the text typed after the slash and call tools, using the same `${...}` expansion engine as `${env.VAR}`: + +- `${args[0]}`, `${args[1]}`, … — individual positional arguments (whitespace-tokenized; quoted substrings keep their spaces together). +- `${args}` or `${args.join(" ")}` — the full argument list. +- `${tool_name({key: value, ...})}` — calls an agent tool and inlines its output. JS expressions are evaluated before tool commands, so tool output is never itself re-evaluated as JS. +- `` !tool_name(key=value) `` — legacy bang syntax for the same tool-call inlining; still supported alongside `${tool_name({...})}`. + +If `instruction` uses none of the `${args...}` placeholders, any text typed after the slash is appended to the resolved instruction automatically. + +```yaml +commands: + fix: + description: "Fix a file, with optional extra options" + instruction: "Fix the file ${args[0]} with options ${args[1]}" + run: + description: "Run a command with all the typed arguments" + instruction: 'Run command with args: ${args.join(" ")}' + lint: + description: "Show the current lint output" + instruction: 'Lint: ${shell({cmd: "task lint"})}' +``` + +```bash +# Run commands from the CLI too +$ docker agent run agent.yaml /df +$ docker agent run agent.yaml /greet +$ docker agent run agent.yaml /fix main.go --verbose +$ PROJECT_NAME=myapp ENV=production docker agent run agent.yaml /deploy +``` + +## URL Commands + +A command with a `url` field opens that URL in the user's default browser instead of sending a prompt to the agent. Any URI scheme the OS knows how to dispatch works — standard web URLs and custom schemes such as `docker-desktop://` for deep links. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: An agent with handy URL shortcuts. + instruction: You are a helpful assistant. + commands: + feedback: + description: "Open the feedback site for this session" + url: https://example.com/feedback?session={{session_id}} + docs: + description: "Open the documentation" + url: https://docs.docker.com/ + desktop: + description: "Open this session in Docker Desktop" + url: docker-desktop://dashboard/session/{{session_id}} +``` + +The `{{session_id}}` token is replaced at invocation time with the current session ID (URL-query-escaped so it can't break the URL or inject extra query parameters), letting a command deep-link to something scoped to the conversation. This token deliberately uses `{{...}}` rather than the `${...}` JS-expansion syntax, since the session ID is only known at dispatch time. + +URLs are validated before being handed to the OS opener: a parseable URL with a non-empty scheme is required, and flag-like inputs (those starting with `-`) are rejected to prevent argument injection. + +> [!NOTE] +> **Full TUI only** +> +> URL commands only open a browser in the full TUI. The CLI and lean TUI don't check the `url` field at all, so `docker agent run agent.yaml /docs` never opens a browser there — but the command is still dispatched: its resolved text (usually empty, for a URL-only command) is sent as a prompt and can trigger a model turn. + +See [`examples/url_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/url_commands.yaml) for a complete example. + +## Agent-Switching Commands + +A command with an `agent` field switches the active agent for the rest of the conversation. This is useful for building workflow shortcuts where `/plan`, `/review`, `/deploy` each route the user to the right specialist. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Main assistant + instruction: You are a project coordinator. + sub_agents: [planner, reviewer] + commands: + # Switch to planner with a pre-filled prompt + plan: + agent: planner + instruction: "Create a detailed plan for: ${args.join(' ')}" + # Switch to reviewer; any text after /review is forwarded + review: + agent: reviewer + + planner: + model: anthropic/claude-sonnet-4-5 + description: Planning specialist + instruction: You create detailed project plans. + + reviewer: + model: anthropic/claude-sonnet-4-5 + description: Code review specialist + instruction: You review code and suggest improvements. +``` + +When `agent` is set **without** `instruction`, any text typed after the slash command (e.g. `/review fix the auth bug`) is forwarded as a prompt to the target agent. When both are set, the agent is switched first, then the instruction is sent to the new agent. Either way, the target can be **any agent defined in the team**, not just one of the current agent's own `sub_agents` — `sub_agents` above is shown because `planner` and `reviewer` also happen to be delegation targets, not because `agent:` requires it. + +Agent switching stays in the same session — the target agent sees the full conversation history, and the user must explicitly switch back (there's no automatic return). This is different from the two other ways agents hand off work: + +| | Agent-switching command | `handoff` tool | `transfer_task` | +| --- | --- | --- | --- | +| **Trigger** | User runs `/command` | Model calls `handoff()` | Model calls `transfer_task()` | +| **Session** | Stays in the same session | Stays in the same session | Launches an isolated sub-session | +| **History** | Target agent sees full conversation | Target agent sees full conversation | Child runs in isolation; only the result returns | +| **Control** | User must explicitly switch back | Target agent can chain to another agent | Root agent stays in control | + +Use `transfer_task` (via `sub_agents`) when you want delegation with a clean result; use agent-switching commands when you want to *become* a different agent for the rest of the conversation. + +See [`examples/agent_switching_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/agent_switching_commands.yaml) for a complete example. + +## Reusable Command Groups + +Repeated command sets across agents can be hoisted into the top-level `commands:` section and pulled in by name with `use_commands:` — the same reuse pattern as `mcps:` for MCP servers and `toolsets:` for shared toolsets. + +```yaml +commands: + ci: + deploy: "Deploy the application" + test: "Run the test suite" + +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Lead developer + instruction: You are the lead developer. Coordinate the team. + use_commands: [ci] # reuse the "ci" command group + commands: + lint: "Run the linter" # inline command, merged in (wins on conflict) + + docs-writer: + model: anthropic/claude-sonnet-4-5 + description: Documentation writer + instruction: You write and maintain the project documentation. + use_commands: [ci] # same group, reused without duplication +``` + +An agent's own inline `commands:` entries take precedence over merged `use_commands:` entries on name conflicts. See [`examples/shared-commands-skills.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shared-commands-skills.yaml) for a complete example that also covers the equivalent `skills:` / `use_skills:` pattern. + +## Hiding Commands + +Use `--disable-commands` to hide and disable specific slash commands in the TUI — built-in ones (`/cost`, `/eval`, `/model`, …) or your own named ones. Accepts a comma-separated list; the leading slash is optional and matching is case-insensitive. + +```bash +$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model" +``` + +This is useful for shipping a distributed agent with a narrower command surface — for example, hiding `/model` so a published agent always runs its intended model. + +## Built-in Commands + +The TUI ships its own slash commands (`/new`, `/compact`, `/sessions`, `/settings`, …) alongside whatever an agent defines. See [Slash Commands](../../features/tui/index.md#slash-commands) in the TUI reference for the full list. + +## Command Configuration Reference + +| Property | Type | Description | +| --- | --- | --- | +| `description` | string | Shown in completion dialogs and help text. | +| `instruction` | string | The prompt sent to the agent. Supports argument expansion (`${args[0]}`, `${args.join(" ")}`, …), tool calls (`${tool_name({...})}`), and the legacy bang syntax `!tool_name(...)`. | +| `agent` | string | Name of an agent in the team to switch to when this command is invoked — any agent in the team's `agents:` map, not just one of the current agent's `sub_agents`. When set without `instruction`, any text typed after the slash command is forwarded as a prompt to the target agent. | +| `url` | string | URL to open in the user's default browser when this command is invoked, instead of sending a prompt to the agent (full TUI only — see [URL Commands](#url-commands)). The token `{{session_id}}` is replaced at invocation time with the current session ID (URL-query-escaped). | + +`instruction` and `agent` can be combined (the agent is switched first, then the instruction is sent to the new agent). In the full TUI, if `url` is set, it takes precedence over `agent` and `instruction` — the command only opens the browser; the lean TUI and CLI don't check `url` at all, so a URL-only command instead sends its (usually empty) resolved text as a prompt. See [Behavior differs by frontend](#what-slash-commands-are) above. The simple string form is shorthand for `{ instruction: "..." }`. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md new file mode 100644 index 000000000000..05be0fcf499b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md @@ -0,0 +1,172 @@ +--- +title: "Flavors" +description: "Ship one agent file with named variants, enabled at run time as YAML patches." +keywords: docker agent, ai agents, configuration, yaml, flavors, patch, variants, overrides +weight: 95 +canonical: https://docs.docker.com/ai/docker-agent/configuration/flavors/ +--- + +_Ship one agent file with named variants, enabled at run time as YAML patches._ + +## Overview + +A flavor is a named YAML patch declared in the agent file itself, under the +top-level `flavors` section. Enabling a flavor applies its patch on top of the +rest of the document before the config is parsed, so one file can carry +several variants — a cheaper model for local runs, extra tools for CI, a more +verbose instruction for debugging — without duplicating the whole config. + +```yaml +agents: + root: + model: claude + instruction: You are a helpful assistant. + +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + +flavors: + cheap: + models: + claude: + model: claude-3-5-haiku-latest +``` + +Enable flavors with the repeatable `--flavor` flag: + +```bash +$ docker agent run agent.yaml --flavor cheap +``` + +The flag works on every command that runs an agent — `run`, `chat`, `eval`, +`serve api`, `serve a2a`, `serve mcp` — and order matters: patches apply in +the order the flavors are requested, each on top of the previous result. + +```bash +$ docker agent run agent.yaml --flavor cheap --flavor verbose +``` + +Flavors the file does not define are ignored (with a debug log), so you can +enable the same flavor set across a fleet of agents and each file only reacts +to the names it declares. External sub-agents loaded from OCI or URL +references receive the same enabled flavors. + +## Merge Semantics + +Patches follow [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7386) +semantics, with two extensions for arrays: + +| Patch value | Effect | +| --- | --- | +| Object | Merged recursively into the existing object. | +| Scalar or array | Replaces the existing value. | +| `null` | Deletes the key. | +| Key ending in `+` | Appends the items to the existing array. | +| Key ending in `-` | Removes matching entries from an array or object. | + +### Merging and replacing + +An object patch only touches the keys it names — siblings survive: + +```yaml +flavors: + verbose: + agents: + root: + instruction: Explain your reasoning in detail. # model, tools, ... unchanged +``` + +### Deleting a key + +Set it to `null`: + +```yaml +flavors: + no-limit: + models: + claude: + max_tokens: null +``` + +### Appending to an array + +Plain arrays replace wholesale. To add entries instead, suffix the key +with `+`: + +```yaml +agents: + root: + toolsets: + - type: think + +flavors: + with-shell: + agents: + root: + toolsets+: + - type: shell +``` + +With `--flavor with-shell` the root agent gets both `think` and `shell`. + +### Removing entries + +Suffix the key with `-`. Each item in the patch value selects what to remove: + +- From an **array**: a scalar removes equal elements; an object removes every + element it partially matches (all of the matcher's keys must be present + with matching values). +- From an **object**: items are key names to drop. + +```yaml +flavors: + slim: + agents: + root: + toolsets-: + - type: shell # drop every shell toolset, however configured + sub_agents-: + - checker # drop by value + models-: + - spare # drop the named model definition +``` + +> [!NOTE] +> The `+` and `-` suffixes are reserved inside flavor patches: a patch cannot +> set a literal key ending in either character. Base documents are unaffected. + +## Inspecting the Result + +`docker agent debug config` prints the config exactly as the runtime sees it, +flavors applied: + +```bash +$ docker agent debug config agent.yaml --flavor cheap --flavor with-shell +``` + +## HCL + +Flavors work in [HCL configs](../hcl/index.md) too, as labeled blocks. The +append/remove operators need quoted attribute names inside object +expressions: + +```hcl +flavors "with-shell" { + agents = { + root = { + "toolsets+" = [{ type = "shell" }] + } + } +} +``` + +## Notes + +- Flavors require config schema version 13 or later; older versions reject + the `flavors` key with a hint to bump the top-level `version` field. +- Patches apply before validation, so a flavored config is validated exactly + like a hand-written one. +- `docker agent push` publishes the raw document, `flavors` section included, + so consumers of a pushed agent can enable its flavors too. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/hcl/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/hcl/index.md new file mode 100644 index 000000000000..7a465e47a1c0 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/hcl/index.md @@ -0,0 +1,306 @@ +--- +title: "HCL Configuration" +description: "Write Docker Agent configs in HCL instead of YAML, using labeled blocks, heredocs, and the same underlying schema." +keywords: docker agent, ai agents, configuration, yaml, hcl configuration +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/configuration/hcl/ +--- + +_Write Docker Agent configs in HCL instead of YAML. It maps to the same Docker Agent schema and validation rules._ + +`docker-agent` supports `.hcl` config files anywhere it supports `.yaml` or `.yml` files. HCL is useful if you prefer labeled blocks, less punctuation, and heredocs for long prompts. + +> [!TIP] +> **Same config model, different syntax** +> +> YAML and HCL are just two syntaxes for the same Docker Agent configuration model. Docker Agent converts HCL to the equivalent YAML structure internally, then runs the normal schema validation and loading pipeline. + +## Minimal Example + +```hcl +#!/usr/bin/env docker agent run + +agent "root" { + model = "openai/gpt-5" + description = "A helpful assistant" + instruction = <<-EOT + You are a helpful assistant. + EOT + + toolset "think" {} +} +``` + +Run it exactly like a YAML config: + +```bash +$ docker agent run agent.hcl +$ docker agent run --exec agent.hcl "Summarize this repository" +$ docker agent serve api ./agents/ # directories may mix .yaml, .yml, and .hcl files +``` + +> [!TIP] +> **See also** +> +> HCL changes the syntax, not the meaning of fields. For what each field does, see [Agent Config](../agents/index.md), [Model Config](../models/index.md), and [Tool Config](../tools/index.md). + +## YAML vs HCL + +These two configs are equivalent: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + +agents: + root: + model: claude + description: Coding assistant + instruction: You help with software development. + toolsets: + - type: filesystem + - type: shell +``` + +```hcl +model "claude" { + provider = "anthropic" + model = "claude-sonnet-4-5" +} + +agent "root" { + model = "claude" + description = "Coding assistant" + instruction = "You help with software development." + + toolset "filesystem" {} + toolset "shell" {} +} +``` + +## Core Conventions + +HCL follows a few simple mapping rules: + +| HCL syntax | YAML shape | +| --- | --- | +| `agent "root" { ... }` | `agents.root` | +| `model "claude" { ... }` | `models.claude` | +| `provider "team" { ... }` | `providers.team` | +| `mcp "github" { ... }` | `mcps.github` | +| `rag "docs" { ... }` | `rag.docs` | +| `command "fix" { ... }` inside an agent | `commands.fix` | +| `toolset "shell" {}` | list item in `toolsets` with `type: shell` | +| `metadata { ... }`, `permissions { ... }` | singleton blocks with the same top-level name | + +### Top-level keyed maps become labeled blocks + +In YAML, several sections are maps keyed by name. In HCL, those become labeled blocks: + +```hcl +model "claude" { + provider = "anthropic" + model = "claude-sonnet-4-5" +} + +agent "root" { + model = "claude" + description = "Primary assistant" + instruction = "You are helpful." +} +``` + +The supported top-level labeled blocks are: + +- `agent` +- `model` +- `provider` +- `mcp` +- `rag` + +The supported top-level singleton blocks are: + +- `metadata` +- `permissions` + +### Toolsets use the block label as `type` + +Instead of writing list entries with `type: ...`, HCL uses a `toolset` block whose label becomes the tool type: + +```hcl +agent "root" { + model = "openai/gpt-5" + description = "Dev assistant" + instruction = "You can inspect and modify code." + + toolset "filesystem" {} + + toolset "mcp" { + ref = "docker:github-official" + } +} +``` + +### Commands use labeled blocks too + +Agent commands are often nicer to write in HCL because each command gets its own block: + +```hcl +agent "root" { + model = "openai/gpt-5" + description = "Build helper" + instruction = "You help with builds." + + command "fix-lint" { + description = "Fix lint issues" + instruction = "Run the linter, then fix any problems." + } +} +``` + +## Strings and Heredocs + +Use quoted strings for short values and heredocs for long prompts, welcome messages, or embedded JSON. + +```hcl +agent "root" { + model = "openai/gpt-5" + description = "Friendly assistant" + + instruction = <<-EOT + You are a helpful assistant. + + Keep answers concise and practical. + EOT +} +``` + +### Escaping literal `${...}` + +HCL treats `${...}` inside strings and heredocs as template interpolation. If you need the literal text `${...}` in your prompt, escape it as `$${...}`. + +This matters for command prompts that intentionally show Docker Agent template snippets: + +```hcl +command "fix-lint" { + instruction = <<-EOT + Run the linter and inspect the result: + + $${shell({cmd: "task lint"})} + EOT +} +``` + +The model will receive the literal `${shell({cmd: "task lint"})}` text. + +## Loading Files with `file()` + +The `file()` function reads a UTF-8 text file and returns its contents as a string. Relative paths are resolved from the HCL config file's directory, and reads are restricted to that directory. + +This keeps long prompts out of the config: + +```hcl +agent "root" { + model = "openai/gpt-5" + description = "Coding assistant" + instruction = file("prompts/coding.md") +} +``` + +With a single argument, the file contents are returned exactly as written — any `${...}` in the file stays literal, so runtime snippets like `${shell({cmd: "..."})}` pass through untouched. + +### Rendering files as templates + +Pass an object as the second argument to render the file as an HCL template. Each key becomes a variable available inside the file: + +```hcl +agent "reviewer" { + model = "openai/gpt-5" + description = "Go reviewer" + instruction = file("prompts/reviewer.md", { + language = "Go" + strictness = "high" + }) +} + +agent "py_reviewer" { + model = "openai/gpt-5" + description = "Python reviewer" + instruction = file("prompts/reviewer.md", { + language = "Python" + strictness = "relaxed" + }) +} +``` + +With `prompts/reviewer.md` containing: + +```markdown +You review ${language} code with ${strictness} strictness. +``` + +Templates support the full HCL template syntax, including `%{ for }` and `%{ if }` directives: + +```markdown +Rules: +%{ for rule in rules ~} +- ${rule} +%{ endfor ~} +``` + +Two things to keep in mind: + +- Referencing a variable that is not in the object is an error. +- No functions are available inside templates, so a template cannot call `file()` again. If the file needs a literal `${...}` while being rendered as a template, escape it as `$${...}` inside the file. + +## Repeated Blocks Become Lists + +Some YAML sections are lists. In HCL, those are written as repeated blocks. + +For example, model routing rules become repeated `routing { ... }` blocks: + +```hcl +model "smart_router" { + provider = "openai" + model = "gpt-5" + + routing { + model = "anthropic/claude-sonnet-4-5" + examples = [ + "Write a detailed technical document", + "Review this code for security issues", + ] + } + + routing { + model = "openai/gpt-5" + examples = [ + "Generate some creative ideas", + "Help me brainstorm", + ] + } +} +``` + +The same idea applies to other list-shaped sections such as RAG `strategy` blocks and hook event entries. + +## Important Differences from Terraform + +Docker Agent uses HCL as a configuration syntax, not as Terraform: + +- There are no modules, `locals`, or `variable` blocks. +- The only function available in expressions is [`file()`](#loading-files-with-file); Terraform's function library (including `templatefile()`, which `file()` with a vars object replaces) is not available. +- Prefer normal literal values: strings, numbers, booleans, lists, objects, and nested blocks. +- After conversion, the result is validated exactly like the equivalent YAML config. + +If you already know Terraform, think of Docker Agent HCL as a thin block-based syntax over the existing config schema. + +## Examples + +See these real configs in the repository: + +- [`examples/pirate.hcl`](https://github.com/docker/docker-agent/blob/main/examples/pirate.hcl) +- [`examples/gopher.hcl`](https://github.com/docker/docker-agent/blob/main/examples/gopher.hcl) +- [`examples/instructions_from_file.hcl`](https://github.com/docker/docker-agent/blob/main/examples/instructions_from_file.hcl) diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md new file mode 100644 index 000000000000..34efe9d2b8e4 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md @@ -0,0 +1,952 @@ +--- +title: "Hooks" +description: "Run shell commands at various points during agent execution for deterministic control over behavior." +keywords: docker agent, ai agents, configuration, yaml, hooks +weight: 60 +canonical: https://docs.docker.com/ai/docker-agent/configuration/hooks/ +--- + +_Run shell commands at various points during agent execution for deterministic control over behavior._ + +## Overview + +Hooks allow you to execute shell commands or scripts at key points in an agent's lifecycle. They provide deterministic control that works alongside the LLM's behavior, enabling validation, logging, environment setup, and more. + +> [!NOTE] +> **Use Cases** +> +> - Validate or transform tool inputs before execution +> - Log all tool calls to an audit file +> - Block dangerous operations based on custom rules +> - Validate, redact, or enrich user prompts before they reach the model +> - Programmatically approve or deny tool calls without prompting the user +> - Steer or veto context-window compaction +> - Audit sub-agent handoffs in multi-agent setups +> - Set up the environment when a session starts +> - Clean up resources when a session ends +> - Log or validate model responses before returning to the user +> - Send external notifications on agent errors or warnings + +## Hook Types + +Docker Agent dispatches the following hook events: + +| Event | When it fires | Can block? | +| --------------------------- | --------------------------------------------------------------------------------- | ---------- | +| `pre_tool_use` | Before a tool call executes | Yes | +| `tool_response_transform` | Between a tool's execution and the runtime's emission/record of the response | No | +| `post_tool_use` | After a tool completes — fires for both success and failure | Yes | +| `permission_request` | Just before the runtime would prompt the user to approve a tool | Yes | +| `session_start` | When a session begins or resumes | No | +| `user_prompt_submit` | Once per user message, after submission and before the model runs | Yes | +| `user_steering_messages_submit` | Each time queued steering messages are drained (mid-turn, after stop, or while idle) | Yes | +| `user_followup_submit` | Each time a queued follow-up message starts a fresh turn (end-of-turn) | Yes | +| `turn_start` | At the start of every agent turn (each model call) | No | +| `turn_end` | At the end of every agent turn — fires no matter why the turn ended | No | +| `before_llm_call` | Just before every model call (after `turn_start`) | Yes | +| `after_llm_call` | After every successful model call, before the response is recorded | No | +| `session_end` | When a session terminates | No | +| `pre_compact` | Just before the runtime compacts the session transcript | Yes | +| `before_compaction` | Just before a compaction runs — can veto or supply a custom summary | Yes | +| `after_compaction` | After a successful compaction (summary applied to the session) | No | +| `subagent_stop` | When a sub-agent (transferred task / background / skill sub-session) finishes | No | +| `on_user_input` | When the agent is waiting for user input | No | +| `stop` | When the model finishes responding | No | +| `notification` | When the agent emits a notification (error or warning) | No | +| `on_error` | When the runtime hits an error during a turn (fires alongside `notification`) | No | +| `on_max_iterations` | When the runtime reaches its configured `max_iterations` limit | No | +| `on_agent_switch` | When the runtime moves the active agent (transfer_task, handoff, return) | No | +| `on_session_resume` | When the user explicitly approves continuation past `max_iterations` | No | +| `on_tool_approval_decision` | After the runtime's approval chain (permissions / yolo / readonly / ask) resolves | No | +| `worktree_create` | After `docker agent run --worktree` creates a git worktree, before the session | Yes | + +> [!NOTE] +> **Two compaction events** +> +> `pre_compact` and `before_compaction` both fire just before a compaction. `pre_compact` is the original event and is best-suited to _steering_ the LLM-generated summary by appending guidance via `additional_context`. `before_compaction` is the newer, structured event: it carries the input/output token counts, the model's context limit, and a `compaction_reason` so handlers can decide based on real session pressure, and it can _replace_ the LLM-generated summary verbatim via `hook_specific_output.summary`. + +## Configuration + +You can configure hooks directly in an agent YAML file under the agent's `hooks:` block: + +```yaml +agents: + root: + model: openai/gpt-4o + description: An agent with hooks + instruction: You are a helpful assistant. + hooks: + # Run before specific tools + pre_tool_use: + - matcher: "shell|edit_file" + hooks: + - type: command + command: "./scripts/validate-command.sh" + timeout: 30 + + # Run after all tool calls + post_tool_use: + - matcher: "*" + hooks: + - type: command + command: "./scripts/log-tool-call.sh" + + # Run when session starts + session_start: + - type: command + command: "./scripts/setup-env.sh" + + # Run when session ends + session_end: + - type: command + command: "./scripts/cleanup.sh" + + # Run when agent is waiting for user input + on_user_input: + - type: command + command: "./scripts/notify.sh" + + # Run when the model finishes responding + stop: + - type: command + command: "./scripts/log-response.sh" + + # Run on agent errors and warnings + notification: + - type: command + command: "./scripts/alert.sh" +``` + +Each event takes a list of hooks. A single hook can also be written directly +as a mapping, without the list dash: + +```yaml +stop: + type: command + command: "./scripts/log-response.sh" +``` + +## Global (user-level) hooks + +Global hooks let you apply the same hook configuration to every agent you run. Define them in your user config file at `~/.config/cagent/config.yaml` under `settings.hooks`: + +```yaml +# ~/.config/cagent/config.yaml +settings: + hooks: + session_start: + - type: command + command: "~/.config/cagent/hooks/session-start.sh" + pre_compact: + - type: command + command: "~/.config/cagent/hooks/pre-compact.sh" + pre_tool_use: + - matcher: "shell" + hooks: + - type: command + command: "~/.config/cagent/hooks/check-shell.sh" +``` + +Global hooks use the same schema as agent-level hooks and are additive. If an event is configured in multiple places, all matching hooks run in this order: + +1. Agent-config hooks from the agent YAML +2. Global hooks from `settings.hooks` +3. Hook drop-ins from `<config-dir>/hooks.d/` (lexicographic file order) +4. CLI hooks from `--hook-*` flags + +Global hooks cannot be suppressed by an individual agent. Use them for user-wide audit logging, personal guardrails, notifications, and setup/cleanup behavior that should apply everywhere. + +### Hook drop-in files (`hooks.d`) + +External tools that integrate with Docker Agent (terminal emulators, IDEs, audit or observability sidecars) shouldn't have to rewrite your `config.yaml` to install a hook. Instead, Docker Agent also loads every `*.yaml` / `*.yml` file from the `hooks.d` directory next to your user config (default: `~/.config/cagent/hooks.d/`). Each file is a standalone hooks block with the same schema as the content of `settings.hooks`: + +```yaml +# ~/.config/cagent/hooks.d/50-mytool.yaml +session_start: + - type: command + command: mytool notify --event session-start +stop: + - type: command + command: mytool notify --event stop +``` + +- Files are loaded in lexicographic order and merged additively after `settings.hooks` (use numeric prefixes like `10-`, `50-` to control ordering). +- A malformed file is skipped with a logged warning; a broken drop-in never breaks a run. +- Installing an integration means writing one self-contained file; uninstalling means deleting it. No shared-file edits, no conflicts between tools. + +The config directory can be relocated with the `--config-dir` flag or the `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) environment variable, which external tools can use to locate `hooks.d` under non-default config dirs. + +## Built-in Hooks + +In addition to shell `command` hooks, Docker Agent ships a small library of **built-in hooks** — in-process Go functions that run without spawning a subprocess. They're invoked with `type: builtin`, where `command` is the builtin's registered name and `args` are passed through as the builtin's parameters. + +```yaml +hooks: + turn_start: + - type: builtin + command: add_date + - type: builtin + command: add_prompt_files + args: + - GUIDELINES.md + - PROJECT.md + session_start: + - type: builtin + command: add_environment_info + before_llm_call: + - type: builtin + command: max_iterations + args: ["50"] +``` + +Built-ins are typically zero-config and faster than equivalent shell hooks because they don't fork a process. They cover the common "inject context into every turn / session" patterns out of the box. + +### Available built-ins + +| Builtin | Event | Args | What it does | +| ----------------------- | ----------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `add_date` | `turn_start` | _none_ | Prepends `Today's date: YYYY-MM-DD` so the model always knows the current date. | +| `add_environment_info` | `session_start` | _none_ | Adds the working directory, git-repo status, OS, and CPU architecture. | +| `add_prompt_files` | `turn_start` | `[file1, file2, ...]` | Reads each named file from the workdir hierarchy (walking up) and the home directory, and appends their contents. | +| `add_git_status` | `turn_start` | _none_ | Adds the output of `git status --short --branch` (no-op outside a git repo or when git isn't installed). | +| `add_git_diff` | `turn_start` | _none_, or `["full"]` | Adds `git diff --stat` by default. Pass `args: ["full"]` to emit the full unified diff. Output is capped to 4 KB. | +| `add_directory_listing` | `session_start` | _none_ | Adds an alphabetical listing of the cwd's top-level entries (skips dot-files, capped at 100 with a "... and N more"). | +| `add_user_info` | `session_start` | _none_ | Adds the current OS user (username and full name) and the hostname. | +| `add_recent_commits` | `session_start` | _none_, or `["<N>"]` | Adds `git log --oneline -n N`. `N` defaults to 10; pass a positive integer to override. | +| `max_iterations` | `before_llm_call` | `["<N>"]` (required) | Hard-stops the agent after `N` model calls. Stateless: the runtime supplies the iteration counter on every dispatch. | +| `snapshot` | `session_start`, `turn_start`, `turn_end`, `pre_tool_use`, `post_tool_use`, `session_end` | _none_ | Records filesystem snapshots in a shadow git repo under the Docker Agent data directory. No-op outside git repos; respects the source repo's ignore rules and skips newly-added files larger than 2 MiB. | +| `redact_secrets` | `pre_tool_use`, `before_llm_call`, `tool_response_transform` | _none_ | Scrubs detected secrets (API keys, tokens, private keys, …) out of tool call arguments, outgoing chat content, and tool output. The same builtin handles all three events and dispatches on the event name. Auto-registered on all three events by `redact_secrets: true` on the agent — see [`examples/redact_secrets_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/redact_secrets_hooks.yaml) for the manual wiring. | +| `limit_large_tool_results` | `tool_response_transform`, `session_end` | _none_ | **Always-on safety hook** — automatically injected by the runtime, no configuration required. When a tool result from the `filesystem`, `shell`, `mcp`, or `a2a` categories exceeds 2,000 lines or 50 KiB, the full payload is written to a per-session temp file and replaced in the conversation with a notice plus a bounded excerpt (2,000 lines, up to 50 KiB): the tail for most tools, but the head for the built-in filesystem `read_file`, whose notice suggests a follow-up call with `line`/`limit` to continue reading. The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | +| `safer_shell` | `pre_tool_use` | _none_ | **Deprecated compatibility shim.** The runtime now classifies every shell command natively (`safe` / `destructive` / `unknown`) and gates it through the session's [safety mode](../permissions/index.md#safety-modes), so this builtin no longer emits verdicts. Pinned entries keep working as pure labellers that attach classification metadata (`safety_label`, `blast_radius`, `category`, `reason`) to the call. Filters by tool name internally (no-op for non-shell calls). | +| `unload` | `on_agent_switch` | _none_ | POSTs `{"model": "<id>"}` to each of the previous agent's DMR model endpoints (`/_unload` by default, overridable per-model via `unload_api`) to free the GPU/RAM the just-departing model was holding. Pure HTTP — reads the model snapshot the runtime ships on `on_agent_switch` and depends on no provider-specific runtime state. Non-DMR providers (OpenAI, Anthropic, …) are silently skipped, so cross-provider chains are safe. Errors are logged and swallowed; agent switching never blocks on a slow or unreachable engine (each call has a 10 s timeout). See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml). | + +> [!NOTE] +> **Per-turn vs. per-session** +> +> `turn_start` built-ins recompute every turn and contribute **transient** context that is _not_ persisted to the session — perfect for fast-moving signals like the date or current git state. `session_start` built-ins run once per session and their context **persists** across turns and resumes — pick this for stable context like the OS user or the initial directory listing. + +> [!NOTE] +> **Auto-injected built-ins** +> +> The agent flags `add_date: true`, `add_environment_info: true`, `add_prompt_files: [...]`, and `redact_secrets: true` are shorthands that auto-register the matching built-in hook. You don't need to repeat them under `hooks:` — set the flag _or_ the hook entry(ies), not both. `redact_secrets: true` auto-registers the same builtin on all three of `pre_tool_use`, `before_llm_call`, and `tool_response_transform`; you can also wire any subset of them by hand for finer-grained control (per-tool matchers, ordering with other rewriters, …). +> +> `limit_large_tool_results` is injected unconditionally by the runtime — it is always active and cannot be removed from config. + +A minimal snapshot wiring looks like this: + +```yaml +hooks: + turn_start: + - type: builtin + command: snapshot + turn_end: + - type: builtin + command: snapshot + session_end: + - type: builtin + command: snapshot +``` + +The shadow repository stores tree objects only; it never writes commits or touches the source repository's `.git` directory. The source repository's `.gitignore` and `info/exclude` rules are mirrored before each capture so ignored files do not appear in snapshots. The built-in only records undo checkpoints when files changed, so a final no-op model response does not hide the last changed snapshot. + +You can also enable snapshots globally for every agent with user config: + +```yaml +settings: + snapshot: true +``` + +Omit `snapshot` or set it to `false` to leave automatic snapshots off; manually configured snapshot hooks still run. + +See [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) for a complete snapshot hook configuration. For an overview of the snapshot feature and the `/undo` / `/snapshots` commands, see [Snapshots](../../features/snapshots/index.md). + +> [!WARNING] +> **Two flavors of `max_iterations`** +> +> The `max_iterations` agent field has its own UX (it pauses and asks the user to resume past the limit). The `max_iterations` built-in hook is a **hard stop with no resume** — when its counter trips, the agent terminates with a block decision. Use the agent field for interactive sessions and the built-in hook to enforce non-negotiable caps in unattended runs. + +## Matcher Patterns + +The `matcher` field uses regex patterns to match tool names: + +| Pattern | Matches | +| ------------------ | ----------------------------- | +| `*` | All tools | +| `shell` | Only the `shell` tool | +| `shell\|edit_file` | Either `shell` or `edit_file` | +| `mcp:.*` | All MCP tools (regex) | + +## Hook Input + +Hooks receive JSON input via stdin with context about the event: + +```json +{ + "session_id": "abc123", + "cwd": "/path/to/project", + "hook_event_name": "pre_tool_use", + "tool_name": "shell", + "tool_use_id": "call_xyz", + "tool_input": { + "cmd": "rm -rf /tmp/cache", + "cwd": "." + } +} +``` + +### Common Fields + +Every hook event carries: + +| Field | Description | +| ----------------- | ------------------------------------- | +| `session_id` | The current session's ID. | +| `cwd` | The runtime's working directory. | +| `hook_event_name` | The event name (e.g. `pre_tool_use`). | + +### Per-Event Extra Fields + +In addition to the common fields, each event ships its own payload: + +| Event | Extra fields | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `pre_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` | +| `tool_response_transform` | `tool_name`, `tool_use_id`, `tool_input`, `tool_response` | +| `post_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_error` | +| `permission_request` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` | +| `session_start` | `source` — one of `startup`, `resume`, `clear`, `compact` | +| `user_prompt_submit` | `prompt` — the text the user just submitted | +| `user_steering_messages_submit` | `steering_messages` — the drained steering messages, in submission order | +| `user_followup_submit` | `prompt` — the text of the dequeued follow-up message | +| `turn_start` | _none_ (just the common fields) | +| `turn_end` | `agent_name`, `reason` — one of `normal`, `continue`, `steered`, `error`, `canceled`, `hook_blocked`, `loop_detected` | +| `before_llm_call` | `iteration` — 1-based run-loop iteration counter (the model call this hook is gating), `model_id` | +| `after_llm_call` | `agent_name`, `stop_response`, `last_user_message`, `model_id`, `usage`, `cost` | +| `session_end` | `reason` — one of `clear`, `logout`, `prompt_input_exit`, `other` | +| `pre_compact` | `source` — one of `manual`, `auto`, `overflow`, `tool_overflow` | +| `before_compaction` | `input_tokens`, `output_tokens`, `context_limit`, `compaction_reason` (one of `threshold`/`overflow`/`manual`) | +| `after_compaction` | `input_tokens`, `output_tokens`, `context_limit`, `compaction_reason`, `summary` | +| `subagent_stop` | `agent_name` (the sub-agent), `parent_session_id`, `stop_response` | +| `on_user_input` | _none_ | +| `stop` | `agent_name`, `stop_response`, `last_user_message` | +| `notification` | `notification_level` (`error` or `warning`), `notification_message` | +| `on_error` | `notification_level` (always `error`), `notification_message` | +| `on_max_iterations` | `notification_level` (always `warning`), `notification_message` | +| `on_agent_switch` | `from_agent`, `to_agent`, `agent_switch_kind` (`transfer_task`, `transfer_task_return`, `handoff`, or `force_handoff`) | +| `on_session_resume` | `previous_max_iterations`, `new_max_iterations` | +| `on_tool_approval_decision` | `tool_name`, `tool_use_id`, `tool_input`, `approval_decision`, `approval_source` | +| `worktree_create` | `worktree_path`, `worktree_branch`, `worktree_source_dir` (`cwd` is also set to the new worktree) | + +Notes: + +- `tool_response` for `post_tool_use` carries the tool's result; `tool_error` is `true` when the tool failed (the failure detail is surfaced inside `tool_response`). +- `agent_name` on `pre_tool_use`, `post_tool_use`, and `permission_request` identifies the agent that issued the tool call — in multi-agent setups this follows the active sub-agent, not always the root agent. +- `prompt` is only populated for `user_prompt_submit`. Sub-sessions (transferred tasks, background agents, skills) do **not** fire this event because their kick-off message is synthesised by the runtime, not authored by the user. +- `steering_messages` is only populated for `user_steering_messages_submit`. It carries the user messages the runtime just drained from the steering queue — messages submitted while the agent was already working (mid-turn, after the model stopped, or while idle before the first model call). +- `prompt` is also populated for `user_followup_submit`, carrying the text of the dequeued follow-up message (a user message queued for end-of-turn processing via the FollowUp API / queue, as opposed to mid-turn steering). +- `stop_response` carries the model's final assistant text for `stop`, `after_llm_call`, and `subagent_stop`. `last_user_message` carries the latest user message at dispatch time. +- `model_id` is populated for `after_llm_call` (and `before_llm_call`) in the canonical `<provider>/<model>` form (e.g. `anthropic/claude-sonnet-4-5`). For harness agents, `model_id` is the harness label (e.g. `claude-code`) rather than a canonical model name — see [Coding Harnesses](../../features/harnesses/index.md). +- `usage` and `cost` are populated for `after_llm_call` only. `usage` is the per-call token usage object (`input_tokens`, `output_tokens`, `cached_input_tokens`, `cached_write_tokens`, and `reasoning_tokens` — the last is itself omitted for non-reasoning models); the whole object is absent when the provider reported no usage. `cost` is the USD price of that one model response. For a **native model call** it is the price computed from `usage` and the model's pricing table, and equals the cost the session records for the turn: it is **absent** when the response is unpriced (no pricing data on file, or no usage) and an explicit `0` for a priced call that was free — so a present `cost` is authoritative and an absent one means "unpriced", with no need to cross-check `usage`. Models the catalogue does not price (custom endpoints, local models) can be priced explicitly with the model-level [`cost`](../models/index.md#custom-token-pricing) config. (For harness agents the meaning differs — see the next note.) A cost ledger can therefore record per-call spend from the payload alone, without subscribing to the runtime event channel. +- For [harness agents](../../features/harnesses/index.md), `cost` is the harness's own reported total for the call rather than a computed price, and is present only when the harness reported a non-zero cost (some harnesses, e.g. `codex`, report token counts but no cost — those turns carry `usage` with `cost` absent, even though the recorded message stores `0`). +- `after_llm_call` fires for **every** model call, including calls made inside sub-sessions (transferred tasks, background agents, skills). For those, `session_id` is the sub-session's id. Summing `cost` across `after_llm_call` events therefore captures **all** spend, including sub-sessions (and even sub-sessions that error before their cost is persisted). Do **not** add a separately-queried session cost total on top: the runtime's own total already recurses into and includes completed sub-session spend, so combining the two double-counts. Pick one source — the summed hook costs — as the authoritative ledger. +- `context_limit` is `0` when the model definition is unavailable (treat `0` as "unknown", not as a real limit). +- `approval_decision` is one of `allow`, `deny`, `canceled`. `approval_source` is a stable classifier of which step decided (e.g. `yolo`, `session_permissions_allow`, `session_permissions_deny`, `team_permissions_allow`, `team_permissions_deny`, `pre_tool_use_hook_allow`, `pre_tool_use_hook_deny`, `readonly_hint`, `user_approved`, `user_approved_session`, `user_approved_safe`, `user_approved_tool`, `user_rejected`, `context_canceled`). + +## Hook Output + +Hooks communicate back via JSON output to stdout: + +```json +{ + "continue": true, + "stop_reason": "Optional message when continue=false", + "suppress_output": false, + "system_message": "Warning message to show user", + "decision": "block", + "reason": "Explanation for the decision", + "hook_specific_output": { + "hook_event_name": "pre_tool_use", + "permission_decision": "allow", + "permission_decision_reason": "Command is safe", + "updated_input": { "cmd": "modified command" } + } +} +``` + +All fields are optional. Returning `{}` (or no output at all) means "do nothing, continue normally". + +### Output Fields + +| Field | Type | Description | +| ----------------- | ------- | ----------------------------------------------- | +| `continue` | boolean | Whether to continue execution (default: `true`) | +| `stop_reason` | string | Message to show when `continue=false` | +| `suppress_output` | boolean | Hide stdout from transcript | +| `system_message` | string | Warning message to display to user | +| `decision` | string | For blocking: `block` to prevent operation | +| `reason` | string | Explanation for the decision | + +### Pre-Tool-Use / Permission-Request Specific Output + +The `hook_specific_output` for `pre_tool_use` (and `permission_request`) supports: + +| Field | Type | Description | +| ---------------------------- | ------ | --------------------------------------- | +| `permission_decision` | string | `allow`, `deny`, or `ask` | +| `permission_decision_reason` | string | Explanation for the decision | +| `updated_input` | object | Modified tool input (replaces original) | +| `metadata` | object | (`permission_request` and `pre_tool_use` entries with `preempt_yolo: true` only) string key/value annotations merged onto the tool-call confirmation prompt — see below | + +### Preempting auto-approval from `pre_tool_use` + +`pre_tool_use` entries default to firing AFTER the deterministic approval +pipeline (custom allow rules / safety mode), so an auto-approved call +skips them entirely. For security-critical checks that MUST run on every +call regardless of the safety mode (including `autonomous`, the legacy +`--yolo`), set `preempt_yolo: true` on the matcher entry: + +```yaml +hooks: + pre_tool_use: + - matcher: "*" + preempt_yolo: true + hooks: + - type: command + command: ./security-check.sh +``` + +The entry then fires in a dedicated stage 0 BEFORE `Decide()`: + +- `deny` rejects the call outright; the user is not prompted. +- `ask` forces user confirmation. The default `pre_tool_use` lane and + `permission_request` are skipped on this path so a policy-level + allow there can't override the security verdict. The one exception + is a session-scoped allow grant (the interactive "always allow this + tool" decision) — an informed user opt-in made in response to this + very prompt. +- `allow` is advisory — the pipeline still runs `Decide()` and the + rest of `pre_tool_use`. Same shape as a regular `allow` on the + default lane, just observed earlier. +- No verdict (empty `permission_decision`) falls through. + +Hook crashes on a `preempt_yolo: true` entry fail closed (deny), matching +the default `pre_tool_use` posture. + +Preempting entries can attach structured context via +`hook_specific_output.metadata` (`map[string]string`). The runtime merges +that into the tool-call confirmation event, on top of the metadata it +already derives from its own safety classification (`safety_label`, +`blast_radius`, `category`, `reason`). Key conventions with special +rendering in the TUI confirmation prompt: + +- `safety_label` — the three-value taxonomy: `safe`, `destructive`, or + `unknown`. +- `blast_radius` — one of `safe`, `low`, `medium`, `high`, `unknown`. + Rendered as a colored severity badge (green / yellow / red / muted). +- `category` — taxonomy tag (e.g. `fs-delete`, `dk-volume-del`). + +Plus a free-form `reason` key that the dialog shows as supporting +context. Other keys render as plain text. Last writer wins on key +clashes across hooks, and preempting entries win over the runtime's own +classification. + +### Tool-Response-Transform Specific Output + +The `hook_specific_output` for `tool_response_transform` supports: + +| Field | Type | Description | +| ----------------------- | ------ | --------------------------------------------- | +| `updated_tool_response` | string | Rewritten tool output (replaces the original) | + +This is the symmetric counterpart of `pre_tool_use`'s `updated_input`, applied to tool **results** instead of tool **arguments**. The rewrite reaches every downstream consumer — event subscribers, the persisted session file, the `post_tool_use` hook input, and the next LLM call. Use it to truncate excessive output, scrub PII, or normalise tool dialects. The built-in `redact_secrets` registers itself on this event as the third leg of the redact_secrets feature. + +### Context-Contributing Events + +For `session_start`, `user_prompt_submit`, `user_steering_messages_submit`, `user_followup_submit`, `turn_start`, `post_tool_use`, `pre_compact`, and `stop`, hooks may set `hook_specific_output.additional_context` to inject text into the conversation. `turn_start` context is **transient** (recomputed every turn, never persisted); `session_start` context **persists** for the life of the session. `user_steering_messages_submit` and `user_followup_submit` context is **transient** like `user_prompt_submit` — it is spliced into the steered/follow-up turn only and never persisted. (`worktree_create` also surfaces stdout, but to the CLI user rather than the conversation — the session doesn't exist yet.) + +### Before-Compaction Specific Output + +For `before_compaction`, the `hook_specific_output.summary` field, when non-empty, replaces the LLM-generated compaction summary. The runtime applies the string verbatim and skips the model call. + +```json +{ + "hook_specific_output": { + "hook_event_name": "before_compaction", + "summary": "User asked to refactor pkg/foo. Done in commit abc123." + } +} +``` + +Returning `decision: "block"` (or exit code 2) instead vetoes the compaction entirely. Be cautious about denying when `compaction_reason` is `overflow`: the runtime is recovering from a context-overflow error and a denial there will leave the session unable to make progress. + +### Plain Text Output + +For `session_start`, `user_prompt_submit`, `user_steering_messages_submit`, `user_followup_submit`, `turn_start`, `post_tool_use`, `pre_compact`, and `stop` hooks, plain text written to stdout (i.e., output that is not valid JSON) is captured as additional context for the agent. For `pre_compact` it is appended to the compaction prompt; for the others it is spliced into the conversation as a (transient or persisted) system message depending on the event. + +## Exit Codes + +Hook exit codes have special meaning: + +| Exit Code | Meaning | +| --------- | -------------------------------------- | +| `0` | Success — continue normally | +| `2` | Blocking error — stop the operation | +| Other | Error — logged but execution continues | + +## Per-hook options + +Hooks have a default timeout of 60 seconds. You can also give hooks a name, add environment variables, choose a working directory, and control how non-security hook failures behave: + +```yaml +hooks: + post_tool_use: + - matcher: "shell" + hooks: + - name: "summarize shell output" + type: command + command: "./summarize.sh" + timeout: 120 # 2 minutes + working_dir: ./hooks + env: + PROFILE: dev + on_error: warn # warn | ignore | block +``` + +`pre_tool_use` is fail-closed for safety: a failed pre-tool hook blocks the tool call regardless of `on_error`. + +`working_dir` and `env` apply to `command` and `builtin` hooks. For `builtin` hooks, `working_dir` is resolved with the same logic as `command` hooks (absolute path wins; relative paths join onto the executor directory). `working_dir` accepts `~`, `$VAR`, `${VAR}` and `${env.VAR}`; `env` values expand only the plain `${env.VAR}` form (resolved from the OS process environment), keeping any other `$` literal (see [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields)). A `working_dir` that expands to an empty string (e.g. an unset variable) falls back to the executor's directory with a warning. For `model` hooks, both fields are accepted by the schema but have no effect: model hooks render a prompt template and call the LLM API directly — no subprocess is spawned and no file I/O is performed, so working directory and environment variables have no applicable semantics. + +> [!WARNING] +> **Performance** +> +> Hooks run synchronously and can slow down agent execution. Keep hook scripts fast and efficient. Consider using `suppress_output: true` for logging hooks to reduce noise. + +> [!NOTE] +> **Session End and Cancellation** +> +> `session_end` hooks are designed to run even when the session is interrupted (e.g., Ctrl+C). They are still subject to their configured timeout. + +## Examples + +### Validation Script + +A simple pre-tool-use hook that blocks dangerous shell commands: + +```bash +#!/bin/bash +# scripts/validate-command.sh + +# Read JSON input from stdin +INPUT=$(cat) +TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name') +CMD=$(echo "$INPUT" | jq -r '.tool_input.cmd // empty') + +# Block dangerous commands +if [[ "$TOOL_NAME" == "shell" ]]; then + if [[ "$CMD" =~ ^sudo ]] || [[ "$CMD" =~ rm.*-rf ]]; then + echo '{"decision": "block", "reason": "Dangerous command blocked by policy"}' + exit 2 + fi +fi + +# Allow everything else (returning {} means "do nothing, continue normally") +echo '{}' +exit 0 +``` + +### Audit Logging + +A post-tool-use hook that logs all tool calls: + +```bash +#!/bin/bash +# scripts/log-tool-call.sh + +INPUT=$(cat) +TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name') +SESSION_ID=$(echo "$INPUT" | jq -r '.session_id') + +# Append to audit log +echo "$TIMESTAMP | $SESSION_ID | $TOOL_NAME" >> ./audit.log + +# Don't block execution +echo '{"continue": true}' +exit 0 +``` + +### Session Lifecycle + +Session start and end hooks for environment setup and cleanup: + +```yaml +hooks: + session_start: + - type: command + timeout: 10 + command: | + INPUT=$(cat) + SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"') + echo "Session $SESSION_ID started at $(date)" >> /tmp/agent-session.log + echo '{"hook_specific_output":{"additional_context":"Session initialized."}}' + + session_end: + - type: command + timeout: 10 + command: | + INPUT=$(cat) + SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"') + REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"') + echo "Session $SESSION_ID ended ($REASON) at $(date)" >> /tmp/agent-session.log +``` + +### Response Logging with Stop Hook + +Log every model response for analytics or compliance: + +```yaml +hooks: + stop: + - type: command + timeout: 10 + command: | + INPUT=$(cat) + SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"') + RESPONSE_LENGTH=$(echo "$INPUT" | jq -r '.stop_response // ""' | wc -c | tr -d ' ') + echo "[$(date)] Session $SESSION_ID - Response: $RESPONSE_LENGTH chars" >> /tmp/agent-responses.log +``` + +The `stop` hook is useful for: + +- **Response quality checks** — validate that responses meet criteria before returning +- **Analytics** — track response lengths, patterns, or content +- **Compliance logging** — record all agent outputs for audit + +### Error Notifications + +Send alerts when the agent encounters errors: + +```yaml +hooks: + notification: + - type: command + timeout: 10 + command: | + INPUT=$(cat) + LEVEL=$(echo "$INPUT" | jq -r '.notification_level // "unknown"') + MESSAGE=$(echo "$INPUT" | jq -r '.notification_message // "no message"') + echo "[$(date)] [$LEVEL] $MESSAGE" >> /tmp/agent-notifications.log +``` + +The `notification` hook fires when: + +- The model returns an error (all models failed) — also fires `on_error` +- A degenerate tool call loop is detected — also fires `on_error` +- The maximum iteration limit is reached — also fires `on_max_iterations` + +Use `on_error` and `on_max_iterations` instead of `notification` when you want a structured handler for one of these conditions without parsing `notification_level`. + +### Turn-Start: per-turn context + +`turn_start` fires at the start of every agent turn (each model call). Anything you contribute via `additional_context` (or plain stdout) is appended as a **transient** system message for that turn only — it is *not* persisted to the session. Use it for fast-moving signals like the date, current git state, or per-turn prompt files. The built-in hooks `add_date`, `add_prompt_files`, `add_git_status`, and `add_git_diff` all target this event. + +### Turn-End: per-turn finalizer + +`turn_end` is the symmetric counterpart of `turn_start`. It fires once per turn when the iteration finishes — no matter why. The runtime guarantees the dispatch on every exit path (a normal stop, an error, a hook-driven shutdown, the loop detector, even context cancellation), and it uses `context.WithoutCancel` internally so handlers run to completion on Ctrl+C. + +The `reason` field classifies the exit: + +| `reason` | When | +| --------------- | ------------------------------------------------------------ | +| `normal` | Model finished cleanly with no follow-up | +| `continue` | More iterations to come (e.g. tool calls, follow-up message) | +| `steered` | Drained steered messages prompted a re-entry | +| `error` | Model call failed (`handleStreamError` exited the loop) | +| `canceled` | Context was cancelled (e.g. Ctrl+C) | +| `hook_blocked` | `before_llm_call` or `post_tool_use` denied the call | +| `loop_detected` | The consecutive-tool-call loop detector terminated the turn | + +`turn_end` is observational — the result is ignored. Use it to time turns, accumulate per-turn metrics (token usage, tool counts), or notify external observability pipelines symmetrically with `turn_start`. + +### Before/After-LLM-Call: budget guards and model auditing + +`before_llm_call` fires immediately before every model call (after `turn_start` has assembled the messages). It cannot contribute context — use `turn_start` for that — but it can **stop the run** by returning `decision: block` (or exit code 2). The built-in `max_iterations` hook implements a hard cap on top of this event. + +`after_llm_call` fires immediately after each successful model call, before the response is recorded into the session and tool calls are dispatched. The assistant text is in `stop_response`, and the call's `usage` and `cost` carry the per-turn token usage and computed USD spend (see the field notes above). Use it for response auditing, redaction logging, quality metrics, or a sidecar cost ledger that records per-call spend without subscribing to the runtime event channel. Failed model calls fire `on_error` instead. + +### Before/After-Compaction: structured compaction control + +`before_compaction` fires immediately before a compaction. Unlike `pre_compact`, it carries structured token-pressure data: `input_tokens`, `output_tokens`, `context_limit`, and a `compaction_reason` (`threshold`, `overflow`, or `manual`). Hooks can either: + +- veto compaction by returning `decision: block` (the runtime skips compaction entirely), or +- replace the LLM-generated summary by returning `hook_specific_output.summary` (the runtime applies that summary verbatim and skips the model call). + +`after_compaction` fires after a successful compaction. It carries the produced `summary` along with the *pre-compaction* `input_tokens` / `output_tokens` so observability handlers can naturally express "compacted from X to Y". `after_compaction` is purely observational; output is ignored. + +### Agent-Switch and Session-Resume: observability for multi-agent and long runs + +`on_agent_switch` fires whenever the runtime moves the active agent to a new one — `transfer_task`, `handoff`, `force_handoff`, or the return after a transferred task completes. The cause is in `agent_switch_kind`, the source and destination in `from_agent` and `to_agent`. Use it for audit, transcript, and metrics pipelines that track which agent ran which tools. + +The built-in [`unload`](#available-built-ins) hooks into this event to release the resources held by the previous agent's models. It's the canonical way to run two heavy local models on a GPU that can only fit one at a time: + +```yaml +agents: + coder: + model: qwen3-large + handoffs: [reviewer] + hooks: + on_agent_switch: + - type: builtin + command: unload + reviewer: + model: qwen3-coder + handoffs: [coder] + hooks: + on_agent_switch: + - type: builtin + command: unload + +models: + qwen3-large: + provider: dmr + model: ai/qwen3-large + qwen3-coder: + provider: dmr + model: ai/qwen3-coder +``` + +At every transfer the runtime ships a snapshot of the previous agent's model endpoints on the `on_agent_switch` hook input, and the `unload` builtin POSTs `{"model": "<id>"}` to each DMR endpoint's `/_unload` URL over plain HTTP. For cloud providers (OpenAI, Anthropic, …) the hook is a silent no-op since they don't expose an HTTP unload endpoint. Cross-provider chains are safe — only DMR endpoints are touched. See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml) for the full file. + +`on_session_resume` fires when the user explicitly approves the runtime to continue past its configured `max_iterations` limit. `previous_max_iterations` carries the cap that was reached and `new_max_iterations` carries the new cap after approval. Useful for alerting on extended-runtime sessions or for billing / quota pipelines that meter resumes. + +### Tool-Approval-Decision: who-approved-what audit trail + +`on_tool_approval_decision` fires after the runtime's tool-approval chain (permissions / yolo / readonly / pre_tool_use hooks / interactive prompt) has resolved a verdict for a tool call. `approval_decision` is `allow`, `deny`, or `canceled`; `approval_source` is a stable classifier of which step produced the verdict. Observational only — it gives audit pipelines a single, structured "who approved what" record without re-implementing the chain. + +### Worktree-Create: prepare an isolated checkout + +`worktree_create` fires once, just after `docker agent run --worktree[=name]` creates a fresh [git worktree](../../features/cli/index.md) and **before** the session starts. Each hook runs **inside** the new worktree — its working directory (and `cwd` in the input) is the fresh checkout — so setup commands operate on the new tree rather than your original one. The worktree path and branch are in `worktree_path` and `worktree_branch`, and `worktree_source_dir` carries the repository root it was branched from. + +Use it to prepare the checkout before the agent begins: copy untracked files git won't carry over (`.env`, local config), install dependencies, or warm caches. Because the worktree lives under the Docker Agent data directory — not next to your checkout — resolve the original files through `worktree_source_dir` rather than a relative path. A hook may **abort the run** by returning `decision: block` / `{"continue": false}` / exit code 2 (for example, when a setup step fails); plain stdout is surfaced as additional context. + +```yaml +hooks: + worktree_create: + # Copy untracked dotfiles git won't bring into the new worktree. + - name: seed local env + type: command + command: | + INPUT=$(cat) + SRC=$(echo "$INPUT" | jq -r '.worktree_source_dir // ""') + [ -n "$SRC" ] && [ -f "$SRC/.env" ] && [ ! -f .env ] && cp "$SRC/.env" .env + echo "Prepared worktree" + # Install dependencies, aborting the run on failure. + - name: install dependencies + type: command + timeout: 600 + command: | + if [ -f package.json ]; then + npm install || { echo '{"continue": false, "system_message": "npm install failed"}'; exit 2; } + fi +``` + +Unlike most events, `worktree_create` is dispatched from the CLI rather than the run loop, because the worktree (and the working directory the runtime, session, tools, and snapshot machinery all capture) must be settled before the runtime and session exist. See [`examples/worktree_create_hook.yaml`](https://github.com/docker/docker-agent/blob/main/examples/worktree_create_hook.yaml) for the full file. + +### Pre-Compact: steer the summary + +`pre_compact` fires just before the runtime compacts the session transcript. Its `source` field tells you why compaction was triggered: + +- `manual` — the user invoked `/compact` +- `auto` — proactive compaction at the configured threshold +- `overflow` — emergency compaction after a context-overflow error +- `tool_overflow` — proactive compaction triggered by tool results pushing the estimated context past the threshold + +Return `additional_context` (or plain stdout) to append guidance to the compaction prompt without modifying the agent's instruction. Block the event (`decision: block` / exit code 2) to cancel compaction — useful when you want to handle truncation yourself. + +### User-Prompt-Submit: gate or enrich every user message + +`user_prompt_submit` fires once per user message, after the prompt is recorded in the session and before the first model call. The submitted text is in `prompt`. Use it to: + +- block prompts that violate policy (`decision: block` / exit code 2), +- inject per-prompt context (`additional_context` is spliced as a transient system message for that turn), +- audit user prompts to a log. + +It does **not** fire for sub-sessions (transferred tasks, background agents, skill sub-sessions) because their kick-off message is synthesised by the runtime. + +### User-Steering-Messages-Submit: gate or enrich mid-flight steering + +`user_steering_messages_submit` is the steering-queue analogue of `user_prompt_submit`. It fires each time the runtime drains the steering queue — messages the user submitted while the agent was already working: mid-turn (after a batch of tool calls), after the model stopped, or while idle before the first model call. The drained messages arrive as a JSON array in `steering_messages`. Use it to: + +- block a run when steering violates policy (`decision: block` / exit code 2), +- inject context in response to the steering (`additional_context` is spliced as a transient system message for the steered turn — never persisted, exactly like `user_prompt_submit`), +- audit steering messages to a log. + +Unlike `turn_end` with `reason: steered`, which only observes the mid-turn and post-stop drains, this event fires on **every** drain — including steering applied while the agent was idle before its first model call. + +```yaml +hooks: + user_steering_messages_submit: + - type: command + timeout: 5 + command: | + INPUT=$(cat) + COUNT=$(echo "$INPUT" | jq -r '.steering_messages | length') + echo "$INPUT" | jq -r '.steering_messages[]' >> /tmp/agent-steering.log + if [ "$COUNT" -gt 0 ]; then + echo '{"hook_specific_output":{"additional_context":"The user sent new instructions while you were working — re-read the latest user messages and adjust course before continuing."}}' + fi +``` + +### User-Followup-Submit: gate or enrich queued follow-ups + +`user_followup_submit` is the follow-up-queue analogue of `user_prompt_submit`. It fires each time the runtime dequeues a follow-up message at the end of a turn and starts a fresh turn for it. Follow-ups are user messages queued for end-of-turn processing (the FollowUp API / queue) — distinct from mid-turn steering: the model sees a follow-up as fresh input, not an interruption, and each follow-up gets a full undivided turn. The follow-up text is in `prompt`. Use it to: + +- block a queued follow-up that violates policy (`decision: block` / exit code 2), +- inject per-follow-up context (`additional_context` is spliced as a transient system message for the follow-up turn — never persisted, exactly like `user_prompt_submit`), +- audit follow-up messages to a log. + +This closes the gap left by `user_prompt_submit`, which fires only for the first interactive prompt and never for queued follow-ups. + +```yaml +hooks: + user_followup_submit: + - type: command + timeout: 5 + command: | + INPUT=$(cat) + echo "$INPUT" | jq -r '.prompt' >> /tmp/agent-followups.log +``` + +### Subagent-Stop: observe handoff completions + +`subagent_stop` fires whenever a sub-agent finishes — `transfer_task` returns, a background agent completes, or a skill sub-session ends. It runs against the *parent* agent's hooks executor, so handlers configured on the orchestrator see every child completion in one place. The sub-agent's name is in `agent_name`, the parent's session ID in `parent_session_id`, and the child's final assistant message in `stop_response`. + +### Permission-Request: programmatic tool approval + +`permission_request` fires just before the runtime would prompt the user to approve a tool call (i.e. when neither the safety mode nor a permissions rule short-circuited the decision). Use the same `hook_specific_output.permission_decision` shape as `pre_tool_use` to auto-approve or auto-deny the call: + +```yaml +hooks: + permission_request: + - matcher: "shell" + hooks: + - type: command + command: | + INPUT=$(cat) + CMD=$(echo "$INPUT" | jq -r '.tool_input.cmd // ""') + if echo "$CMD" | grep -qE '^(ls|pwd|cat) '; then + echo '{"hook_specific_output":{"permission_decision":"allow","permission_decision_reason":"safe read-only command"}}' + fi +``` + +Return nothing to fall through to the usual interactive confirmation. + +When the hook falls through (returns no `permission_decision`), it can still attach key/value `metadata` to the confirmation prompt the runtime shows the user. The runtime merges it onto any static metadata the toolset attached to the tool (hook keys win on a clash) and emits it on the tool-call confirmation message, so clients (TUI, HTTP) can render extra per-call context. Keys from multiple matching hooks are merged; the last hook in config order wins on a clash. + +```yaml +hooks: + permission_request: + - matcher: "shell" + hooks: + - type: command + command: | + INPUT=$(cat) + CMD=$(echo "$INPUT" | jq -r '.tool_input.cmd // ""') + if echo "$CMD" | grep -qE '\brm\b'; then + echo '{"hook_specific_output":{"metadata":{"risk":"high","note":"deletes files"}}}' + fi +``` + +### LLM as a Judge (Auto-Approving Tool Calls) + +The `model` hook type asks an LLM and translates its reply into the +hook's native output — no Go code, no shell glue, no JSON parsing on +your side. Combined with the well-known `pre_tool_use_decision` +schema it gives you a fully-configurable LLM judge that decides +`allow` / `ask` / `deny` per tool call. + +```yaml +hooks: + pre_tool_use: + - matcher: "shell|edit_file|mcp:.*" + hooks: + - type: model + model: openai/gpt-4o-mini + timeout: 15 + schema: pre_tool_use_decision + prompt: | + You are a security judge for an autonomous agent. + Decide whether this tool call is safe to auto-approve. + + Tool: {{ .ToolName }} + Args: {{ .ToolInput | toJSON }} + + Project rules: + - Reads under the working directory are safe. + - Writes to ~/.ssh / ~/.aws / ~/.docker are deny. +``` + +| Field | Required | Description | +| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `model` | yes | Model spec (`provider/model`, e.g. `openai/gpt-4o-mini`). The judge model — small/cheap is recommended. | +| `prompt` | yes | Go [`text/template`](https://pkg.go.dev/text/template) body. Sees the hook [Input](#hook-input) as data, plus the `toJSON` and `truncate <n>` helpers. | +| `schema` | no | Well-known response interpretation. `pre_tool_use_decision` produces a `permission_decision` verdict; omit for free-form text injected as `additional_context`. | +| `timeout` | no (default 60s) | Per-call timeout. **Timeouts fail closed (deny) for `pre_tool_use`** regardless of any other setting. Match it to your judge model's typical latency plus a small buffer. | + +The `pre_tool_use_decision` schema constrains the judge to reply with +strict `{decision, reason}` JSON. Providers that honor structured +output (OpenAI, ...) are asked to emit that shape directly; on +providers that ignore it the framework still parses tolerant +JSON-in-text. Anything unparseable propagates as a hook error and the +executor falls closed (deny) on `pre_tool_use`. + +Pair it with deterministic `permissions:` rules so destructive calls +(e.g. `sudo`, `rm -rf`) are blocked even if the judge is misled, and +obvious read-only calls bypass the LLM entirely. See +[`examples/llm_judge.yaml`](https://github.com/docker/docker-agent/blob/main/examples/llm_judge.yaml) +for a complete configuration. + +**Security considerations**: + +- **Sensitive data**: Tool arguments (including file paths, command + arguments, and any other parameters) are sent to the judge LLM. Avoid + using the judge on tools that handle secrets, or ensure your judge + model is self-hosted. +- **Defense in depth**: The judge should not be your only security + layer. Use deterministic `permissions:` rules to block obviously + dangerous operations (e.g., `sudo`, `rm -rf`) before the judge sees + them, as shown in the example configuration. + +## CLI Flags + +You can add hooks from the command line without modifying the agent's YAML file. This is useful for one-off debugging, audit logging, or layering hooks onto an existing agent. + +| Flag | Description | +| ---------------------- | ------------------------------------------------ | +| `--hook-pre-tool-use` | Run a command before every tool call | +| `--hook-post-tool-use` | Run a command after every tool call | +| `--hook-session-start` | Run a command when a session starts | +| `--hook-session-end` | Run a command when a session ends | +| `--hook-on-user-input` | Run a command when waiting for input | +| `--hook-stop` | Run a command when the model finishes responding | + +All flags are repeatable — pass multiple to register multiple hooks. + +```bash +# Add a session-start hook +$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh" + +# Combine multiple hooks +$ docker agent run agent.yaml \ + --hook-pre-tool-use "./scripts/validate.sh" \ + --hook-post-tool-use "./scripts/log.sh" + +# Add hooks to an agent from a registry +$ docker agent run myorg/coder \ + --hook-pre-tool-use "./audit.sh" +``` + +> [!NOTE] +> **Merging behavior** +> +> Agent-config, global, drop-in, and CLI hooks are additive. For each event, hooks run in this order: agent-config hooks first, then global hooks from `settings.hooks`, then [hook drop-ins](#hook-drop-in-files-hooksd) from `hooks.d/`, then CLI hooks. No source replaces another, and individual agents cannot opt out of global hooks. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md new file mode 100644 index 000000000000..0626bd48ef43 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md @@ -0,0 +1,639 @@ +--- +title: "Model Configuration" +description: "Complete reference for defining models with providers, parameters, and reasoning settings." +keywords: docker agent, ai agents, configuration, yaml, model configuration +linkTitle: "Model Config" +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/configuration/models/ +--- + +_Complete reference for defining models with providers, parameters, and reasoning settings._ + +## Full Schema + +<!-- yaml-lint:skip --> +```yaml +models: + model_name: + first_available: [list] # Optional: candidate model refs, tried in order by available credentials. + # Mutually exclusive with other model settings. + provider: string # Required unless using first_available. One of: openai, anthropic, google, amazon-bedrock, + # dmr, mistral, xai, nebius, nvidia, minimax, baseten, ovhcloud, groq, fireworks, deepseek, cerebras, together, huggingface, moonshot, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, + # azure, ollama, github-copilot, or a named provider defined + # under the top-level `providers:` section. + model: string # Required: model identifier + description: string # Optional: human-readable summary of the model's purpose or strengths + temperature: float # Optional: 0.0–2.0 (provider-dependent; e.g. Anthropic caps at 1.0) + max_tokens: integer # Optional: response length limit + top_p: float # Optional: 0.0–1.0 + frequency_penalty: float # Optional: -2.0–2.0 + presence_penalty: float # Optional: -2.0–2.0 + base_url: string # Optional: custom API endpoint + token_key: string # Optional: env var for API token + thinking_budget: string|int # Optional: reasoning effort + task_budget: int|object # Optional: total task token budget (Anthropic) + parallel_tool_calls: boolean # Optional: allow parallel tool calls + track_usage: boolean # Optional: track token usage + routing: [list] # Optional: rule-based model routing + capabilities: # Optional: override attachment capabilities + image: boolean # Optional: whether the model accepts image attachments + pdf: boolean # Optional: whether the model accepts PDF attachments + cost: # Optional: explicit token pricing (USD per 1M tokens) + input: float # Optional: price per 1M input tokens + output: float # Optional: price per 1M output tokens + cache_read: float # Optional: price per 1M cached input tokens + cache_write: float # Optional: price per 1M cache-write tokens + provider_opts: # Optional: provider-specific options + key: value + title_model: string # Optional: model used for session-title generation + compaction_model: string # Optional: model used for session-compaction (summary generation) + compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9) + bypass_models_gateway: boolean # Optional: skip the models gateway for this model (implied by a custom base_url) +``` + +## Properties Reference + +| Property | Type | Required | Description | +| --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | +| `first_available` | array | ✗ | Candidate model references tried in order; selects the first whose credentials are configured. Mutually exclusive with other model settings. | +| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `nvidia`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `azure`, `ollama`, `github-copilot`, `chatgpt`, or any [named provider](../../providers/custom/index.md). | +| `model` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Model name (e.g., `gpt-4o`, `claude-sonnet-4-5`, `gemini-3.5-flash`) | +| `description` | string | ✗ | Informational, human-readable summary of the model's purpose or strengths (e.g., "fast and cheap, good for summaries"). Not sent to the model. Can be combined with `first_available` (a selector's description is kept when it resolves). | +| `temperature` | float | ✗ | Sampling randomness. Range is provider-dependent — typically `0.0–2.0` (Anthropic caps at `1.0`). `0.0` is deterministic. | +| `max_tokens` | int | ✗ | Maximum response length in tokens | +| `top_p` | float | ✗ | Nucleus sampling threshold (`0.0–1.0`) | +| `frequency_penalty` | float | ✗ | Penalize repeated tokens (`-2.0–2.0`) | +| `presence_penalty` | float | ✗ | Encourage topic diversity (`-2.0–2.0`) | +| `base_url` | string | ✗ | Custom API endpoint URL (for self-hosted or proxied endpoints) | +| `token_key` | string | ✗ | Environment variable name containing the API token (overrides provider default) | +| `thinking_budget` | string/int | ✗ | Reasoning effort control | +| `task_budget` | int/object | ✗ | Total token budget for an agentic task (forwarded to Anthropic; see [Task Budget](#task-budget)). | +| `parallel_tool_calls` | boolean | ✗ | Allow model to call multiple tools at once | +| `track_usage` | boolean | ✗ | Track and report token usage for this model | +| `routing` | array | ✗ | Rule-based routing to different models. See [Model Routing](../routing/index.md). | +| `capabilities` | object | ✗ | Override attachment capabilities for this model. See [Attachment Capability Overrides](#attachment-capability-overrides). | +| `cost` | object | ✗ | Explicit token pricing in USD per 1M tokens, overriding the built-in catalogue. See [Custom Token Pricing](#custom-token-pricing). | +| `provider_opts` | object | ✗ | Provider-specific options (see provider pages) | +| `title_model` | string | ✗ | Model used for session-title generation. Can be a named model from the `models:` section or an inline `provider/model` string. When omitted, the agent's primary model generates titles. Cannot be combined with `first_available`. | +| `compaction_model` | string | ✗ | Model used for session compaction (summary generation). Can be a named model or an inline `provider/model` string. The agent-level `compaction_model` takes precedence over this value, which in turn takes precedence over a provider-level default. When none is set, the primary model compacts. Cannot be combined with `first_available`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `compaction_threshold` | float | ✗ | Fraction of the context window at which proactive auto-compaction triggers for agents running this model. Must be greater than `0` and at most `1`. Takes precedence over the agent-level `compaction_threshold`. Cannot be combined with `first_available`. Default: `0.9`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `bypass_models_gateway` | boolean | ✗ | When `true`, this model connects directly to its provider even when a models gateway (`--models-gateway` / `DOCKER_AGENT_MODELS_GATEWAY`) is configured. Implied by a custom `base_url`. See [Gateway Bypass](#gateway-bypass). | + +## Attachment Capability Overrides + +For custom OpenAI-compatible providers, local models (Ollama, DMR), and any +model the built-in catalogue does not describe, Docker Agent cannot +auto-detect whether the endpoint accepts image or PDF attachments. When the +model is absent from the catalogue, Docker Agent logs a diagnostic and falls +back to text-only, silently dropping attachments. + +Declare `capabilities` to make the model's attachment support authoritative +and skip the catalogue lookup entirely: + +```yaml +models: + llava-local: + provider: ollama + model: llava + capabilities: + image: true # accepts image attachments + pdf: false # does not accept PDFs + + proxy-vision: + provider: vision-proxy + model: gpt-4o + capabilities: + image: true + pdf: true +``` + +| Field | Type | Description | +| ---------------------- | ------- | ------------------------------------------------- | +| `capabilities.image` | boolean | Whether the model accepts image attachments | +| `capabilities.pdf` | boolean | Whether the model accepts PDF attachments | + +The flags must match what the endpoint actually accepts. Claiming a modality +that the endpoint does not support leads to a provider-side API error. When +`capabilities` is omitted the behaviour is unchanged (catalogue lookup then +conservative text-only fallback). + +See [`examples/capability-overrides.yaml`](https://github.com/docker/docker-agent/blob/main/examples/capability-overrides.yaml) for a complete example. + +## Custom Token Pricing + +Docker Agent prices each model call from the [models.dev](https://models.dev/) +catalogue. Models the catalogue does not know — custom OpenAI-compatible +providers, local models, private deployments — are "unpriced": every call is +recorded at $0 despite consuming tokens, with only a log warning. + +Declare `cost` to price a model explicitly, in **USD per one million tokens**. +When set, it takes precedence over the catalogue and makes an uncatalogued +model priced: + +```yaml +models: + internal-gpt: + provider: internal-llm + model: gpt-4o + cost: + input: 1.25 # USD per 1M input tokens + output: 5.00 # USD per 1M output tokens + cache_read: 0.125 # USD per 1M cached input tokens + cache_write: 1.5625 # USD per 1M cache-write tokens + + # Also works for catalogued models, e.g. a negotiated enterprise discount: + discounted-sonnet: + provider: anthropic + model: claude-sonnet-4-5 + cost: + input: 2.4 + output: 12.0 +``` + +| Field | Type | Description | +| ------------------ | ----- | --------------------------------------- | +| `cost.input` | float | USD price per 1M input tokens | +| `cost.output` | float | USD price per 1M output tokens | +| `cost.cache_read` | float | USD price per 1M cached input tokens | +| `cost.cache_write` | float | USD price per 1M cache-write tokens | + +The declared prices feed per-turn cost computation, session cost tracking, the +`/model` picker, and the [`after_llm_call` hook](../hooks/index.md)'s `cost` +field. Prices must not be negative; omitted fields default to `0`. An all-zero +table means "priced, free" — distinct from omitting `cost` entirely +(unpriced). Cannot be combined with `first_available` (set it on the candidate +models instead). + +See [`examples/custom-pricing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/custom-pricing.yaml) for a complete example. + +## Delegating Session-Title Generation + +The `title_model` field lets a heavyweight primary model hand off the cheap +title-generation call to a smaller, faster model: + +```yaml +model: anthropic/claude-opus-4-7 +title_model: anthropic/claude-haiku-4-5 +``` + +The value can be a named entry from the `models` stanza or an inline +`provider/model` string. When omitted, the agent's primary model generates +titles. + +> [!WARNING] +> **Constraint** +> +> `title_model` cannot be combined with `first_available` model selection — the combination is rejected at validation time. + +## Delegating Session Compaction + +> [!TIP] +> **Full guide** +> +> For a task-oriented walkthrough of automatic vs. on-demand compaction, trimming tool results, and reading the context gauge, see [Managing Context & Compaction](../../guides/compaction/index.md). This section covers the `compaction_model` and `compaction_threshold` fields themselves. + +The `compaction_model` field lets a heavyweight primary model hand off the expensive +compaction (summary generation) call to a smaller, faster model: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast + fast: + provider: anthropic + model: claude-haiku-4-5 +``` + +The value can be a named entry from the `models` stanza or an inline +`provider/model` string. Resolution priority: an agent-level `compaction_model` +wins, then the model-level value, then a provider-level default set in the +`providers` section; when none is set, the primary model compacts. For an +agent listing several models (`model: a,b`), the first listed model that sets +a value (or whose provider sets a default) wins at that level. + +```yaml +providers: + my_anthropic: + provider: anthropic + # Default for every agent whose model uses this provider. + compaction_model: anthropic/claude-haiku-4-5 +``` + +If the compaction model has a **smaller context window** than the primary, +Docker Agent triggers compaction against the smaller window so the summary +call can always ingest the full conversation. Pair the primary with a +compaction model whose window is at least as large to keep the proactive +trigger aligned with the primary's window. + +By default the proactive trigger fires when the estimated token usage crosses +**90%** of the context window. The `compaction_threshold` field tunes that +fraction (greater than `0`, at most `1`): lower values compact earlier and +keep requests smaller, higher values compact later and keep more verbatim +history. It can be set on the model (as above, taking precedence) or on the +agent, and automatic compaction can be disabled entirely per agent with +`session_compaction: false` — see [Agent Config](../agents/index.md#properties-reference). + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast + # Compact at 80% of the window instead of the default 90%. + compaction_threshold: 0.8 +``` + +> [!WARNING] +> **Constraint** +> +> `compaction_model` cannot be combined with `first_available` model selection — the combination is rejected at validation time. + +See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) +and [`examples/compaction_threshold.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_threshold.yaml) +for complete examples. + +## Gateway Bypass + +When a models gateway (`--models-gateway` / `DOCKER_AGENT_MODELS_GATEWAY`) is configured, +models without a custom `base_url` route through it by default. Set +`bypass_models_gateway: true` on a specific model to make it connect directly +to its provider instead: + +```yaml +models: + gateway-model: + provider: openai + model: gpt-5 + + direct-model: + provider: anthropic + model: claude-sonnet-4-5 + bypass_models_gateway: true # uses ANTHROPIC_API_KEY directly +``` + +The bypassed model authenticates with the provider's own credentials +(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `token_key`, etc.) rather than the +gateway's short-lived token. The rest of the agent's models continue routing +through the gateway as before. + +Bypass is propagated transparently through router models: a bypass-flagged routing +model passes the flag to all of its routed targets automatically. + +> [!WARNING] +> **Security note** +> +> On an untrusted config, a malicious `base_url` combined with `bypass_models_gateway: true` could route provider credentials to an attacker-controlled endpoint. Only enable this on configs you control. + +> [!WARNING] +> **Constraint** +> +> `bypass_models_gateway: true` cannot be combined with `first_available` — the combination is rejected at validation time. + +See [`examples/bypass_models_gateway.yaml`](https://github.com/docker/docker-agent/blob/main/examples/bypass_models_gateway.yaml) for a complete example. + +## First Available Models + +Use `first_available` when the same agent should work with whichever provider credentials are available in the current environment. Docker Agent checks the candidates in order at load time and replaces the selector with the first candidate whose required environment variables are configured. + +```yaml +models: + smart: + first_available: + - anthropic/claude-sonnet-4-6 + - openai/gpt-5 + - google/gemini-3.5-flash + - dmr/ai/qwen3 # local fallback; no API key required + +agents: + root: + model: smart + instruction: You are a helpful assistant. +``` + +Candidates can be inline `provider/model` references or names from the same `models:` section. Local providers such as `dmr` and `ollama` do not require credentials, so they are useful as final fallbacks. + +If none of the candidates has credentials configured, Docker Agent reports the missing environment variables grouped by candidate. You only need to configure one group of credentials, not every provider in the list. + +A `first_available` model is only a selector. Except for the informational `description`, it cannot be combined with `provider`, `model`, `routing`, `token_key`, budgets, sampling options, or other model settings. Put those settings on named candidate models instead: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-6 + max_tokens: 64000 + + gpt: + provider: openai + model: gpt-5 + thinking_budget: low + + smart: + first_available: + - claude + - gpt + - dmr/ai/qwen3 +``` + +See [`examples/first_available.yaml`](https://github.com/docker/docker-agent/blob/main/examples/first_available.yaml) for a complete example. + +## Thinking Budget + +Control how much reasoning the model does before responding. This varies by provider: + +### OpenAI + +Uses effort levels as strings: + +```yaml +models: + gpt: + provider: openai + model: gpt-5.6 + thinking_budget: low # none | minimal | low | medium | high | xhigh | max (xhigh needs gpt-5.2+; none/max need gpt-5.6+; minimal dropped on gpt-5.6+) +``` + +### Anthropic + +Uses an integer token budget (1024–32768), or — on adaptive-capable models (Opus 4.6+) — `adaptive`, `adaptive/<effort>`, or a bare effort level: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 16384 # must be < max_tokens + + opus: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: adaptive # or adaptive/<effort>, or low | medium | high | xhigh | max +``` + +### Google Gemini 2.5 + +Uses an integer token budget. `0` disables, `-1` lets the model decide: + +```yaml +models: + gemini: + provider: google + model: gemini-2.5-flash + thinking_budget: -1 # dynamic (default) +``` + +### Google Gemini 3 + +Uses effort levels like OpenAI: + +```yaml +models: + gemini3: + provider: google + model: gemini-3-flash + thinking_budget: medium # minimal | low | medium | high +``` + +### Disabling Thinking + +```yaml +thinking_budget: none # or 0 +``` + +`none` and `0` both clear Docker Agent's local thinking configuration (omitting `thinking_budget` has the same effect); neither is guaranteed to reach the API as a real "off" switch: + +- **OpenAI gpt-5.6+** (Sol/Terra/Luna) is the only case with a genuine API-level `none` reasoning effort: Docker Agent sends it as-is and the model does not reason. +- **Older OpenAI reasoning models** (o-series, gpt-5 through gpt-5.5) have no such switch: `none`/`0` just clear the local config, and the model falls back to the API's own default effort and still reasons internally. Same for other always-reasoning models (Gemini 3). +- Providers with a true optional-thinking switch (Gemini 2.5, Claude, local models) are fully disabled by `none`/`0`. + +```yaml +models: + fast-responder: + provider: openai + model: gpt-5.6 + thinking_budget: none # real API-level disable on gpt-5.6+ +``` + +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for per-provider details, including AWS Bedrock and Docker Model Runner. + +## Task Budget + +**Anthropic-only.** + +`task_budget` caps the **total** number of tokens the model may spend across a +multi-step agentic task — combining thinking, tool calls, and final output +tokens. It lets long-running agents self-regulate effort without having to +choose a tight per-call `max_tokens`. + +It is forwarded to Anthropic's +[`output_config.task_budget`](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7) +request field. Docker Agent automatically attaches the required +`task-budgets-2026-03-13` beta header whenever this field is set. + +You can configure `task_budget` on **any** Claude model — Docker Agent never +gates it by model name. At the time of writing only **Claude Opus 4.7** +actually honors the field; other Claude models will reject requests that +include it. Check the Anthropic release notes linked above for the current +list of supported models. + +### Integer shorthand + +```yaml +models: + opus: + provider: anthropic + model: claude-opus-4-7 + task_budget: 128000 # total tokens for the whole task + thinking_budget: adaptive # works nicely together +``` + +### Object form + +Equivalent, and forward-compatible with future budget types: + +```yaml +models: + opus: + provider: anthropic + model: claude-opus-4-7 + task_budget: + type: tokens # only "tokens" is supported today + total: 128000 +``` + +Setting `task_budget: 0` (or omitting the field) disables the feature — the +model falls back to the provider's default behavior. + +Like other inheritable model settings, `task_budget` can also be declared on a +[provider definition](../../providers/custom/index.md) and is +inherited by every model that references that provider. + +See [`examples/task_budget.yaml`](https://github.com/docker/docker-agent/blob/main/examples/task_budget.yaml) for a complete example. + +## Interleaved Thinking + +For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. It is auto-enabled whenever a thinking budget is configured: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 8192 + # interleaved_thinking is auto-enabled when thinking_budget is set + provider_opts: + interleaved_thinking: false # disable if needed +``` + +## Thinking Display (Anthropic) + +For Anthropic Claude models, `thinking_display` controls whether thinking blocks are returned in responses when thinking is enabled. Newer Claude models (Opus 4.7+, Fable 5) hide thinking content by default (`omitted`); Docker Agent requests `summarized` thinking by default for adaptive/effort-based budgets so reasoning stays visible. Set this provider option to override: + +```yaml +models: + opus-4-7: + provider: anthropic + model: claude-opus-4-7 + thinking_budget: adaptive + provider_opts: + thinking_display: omitted # "summarized" or "omitted" ("display" on pre-4.6 models only) +``` + +`display` (full thinking blocks) is only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); newer models (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) only accept `summarized` and `omitted`, and Docker Agent rejects the configuration at startup. + +See the [Anthropic provider page](../../providers/anthropic/index.md#thinking-display) for details. + +## Custom HTTP Headers + +For OpenAI-compatible providers (`openai`, `github-copilot`, `mistral`, `xai`, +`nebius`, `nvidia`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `ollama`, and any custom provider using the OpenAI API), +`provider_opts.http_headers` adds arbitrary HTTP headers to every outgoing +request: + +```yaml +models: + my_model: + provider: openai + model: gpt-4o + provider_opts: + http_headers: + X-Request-Source: docker-agent + X-Tenant-Id: my-team +``` + +Header names are matched case-insensitively. The `github-copilot` provider +automatically sets `Copilot-Integration-Id: copilot-developer-cli` — see the +[GitHub Copilot provider page](../../providers/github-copilot/index.md) +for details. + +## Examples by Provider + +```yaml +models: + # OpenAI + gpt: + provider: openai + model: gpt-5 + + # Anthropic + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + + # Google Gemini + gemini: + provider: google + model: gemini-3.5-flash + temperature: 0.5 + + # AWS Bedrock + bedrock: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + provider_opts: + region: us-east-1 + + # OpenRouter + openrouter: + provider: openrouter + model: meta-llama/llama-3.3-70b-instruct + + # Docker Model Runner (local) + local: + provider: dmr + model: ai/qwen3 + max_tokens: 8192 +``` + +For detailed provider setup, see the [Model Providers](../../providers/overview/index.md) section. + +## Custom Endpoints + +Use `base_url` to point to custom or self-hosted endpoints: + +```yaml +models: + # Azure OpenAI + azure_gpt: + provider: openai + model: gpt-4o + base_url: https://my-resource.openai.azure.com/openai/deployments/gpt-4o + token_key: AZURE_OPENAI_API_KEY + + # Self-hosted vLLM + local_llama: + provider: openai # vLLM is OpenAI-compatible + model: meta-llama/Llama-3.2-3B-Instruct + base_url: http://localhost:8000/v1 + + # Proxy or gateway + proxied: + provider: openai + model: gpt-4o + base_url: https://proxy.internal.company.com/openai/v1 + token_key: INTERNAL_API_KEY +``` + +The `model` and `base_url` fields accept `${env.VAR}` (or `${VAR}`) references, which are substituted from the environment when the model is loaded. This keeps the model id or endpoint out of the config when it is supplied by the environment, e.g. a Docker Compose / DMR setup: + +```yaml +models: + nemotron3: + provider: dmr + model: "${env.NEMOTRON3_MODEL}" + base_url: "${env.DMR_BASE_URL}" +``` + +See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full set of fields and supported syntaxes. + +See [Local Models](../../providers/local/index.md) for more examples of custom endpoints. + +## Inheriting from Provider Definitions + +Models can reference a named provider to inherit shared defaults. Model-level settings always take precedence: + +```yaml +providers: + my_anthropic: + provider: anthropic + token_key: MY_ANTHROPIC_KEY + max_tokens: 16384 + thinking_budget: 8192 + temperature: 0.5 + +models: + claude: + provider: my_anthropic + model: claude-sonnet-4-5 + # Inherits max_tokens, thinking_budget, temperature from provider + + claude_fast: + provider: my_anthropic + model: claude-haiku-4-5 + thinking_budget: 1024 # Overrides provider default +``` + +See [Provider Definitions](../../providers/custom/index.md) for the full list of inheritable properties. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md new file mode 100644 index 000000000000..705a698cf4af --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md @@ -0,0 +1,537 @@ +--- +title: "Configuration Overview" +description: "Docker Agent uses YAML or HCL configuration files to define agents, models, tools, and their relationships." +keywords: docker agent, ai agents, configuration, yaml, configuration overview +linkTitle: "Overview" +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/configuration/overview/ +aliases: + - /ai/docker-agent/reference/config/ +--- + +_Docker Agent uses YAML or HCL configuration files to define agents, models, tools, and their relationships._ + +## File Structure + +A Docker Agent config can be written in YAML or HCL. The examples on this page use YAML; see [HCL Configuration](../hcl/index.md) for the block-based HCL syntax. + +A Docker Agent config has these main sections: + +```bash +# 1. Version — configuration schema version (optional but recommended) +version: 15 + +# 2. Metadata — optional agent metadata for distribution +metadata: + author: my-org + description: My helpful agent + version: "1.0.0" + +# 3. Models — define AI models with their parameters +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + +# 4. Agents — define AI agents with their behavior (at least one is required) +agents: + root: + model: claude + description: A helpful assistant + instruction: You are helpful. + toolsets: + - type: think + +# 5. RAG — define retrieval-augmented generation sources (optional) +rag: + docs: + docs: ["./docs"] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + +# 6. MCPs — reusable MCP server definitions (optional) +mcps: + github: + remote: + url: https://api.githubcopilot.com/mcp + transport_type: sse + +# 7. Providers — optional reusable provider definitions +providers: + my_provider: + provider: anthropic # or openai (default), google, amazon-bedrock, etc. + token_key: MY_API_KEY + max_tokens: 16384 + +# 8. Permissions — agent-level tool permission rules (optional) +# For user-wide global permissions, see ~/.config/cagent/config.yaml +permissions: + allow: ["read_*"] + deny: ["shell:cmd=sudo*"] + +# 9. Commands & Skills — reusable, named groups shared across agents (optional) +commands: + ci: + deploy: "Deploy the application" +skills: + base: [local, git] + +# 10. Toolsets — reusable, named toolset definitions shared across agents (optional) +toolsets: + fs: + type: filesystem +``` + +## Minimal Config + +The simplest possible configuration — a single agent with an inline model: + +```yaml +agents: + root: + model: openai/gpt-5 + description: A helpful assistant + instruction: You are a helpful assistant. +``` + +The same config in HCL: + +```hcl +agent "root" { + model = "openai/gpt-5" + description = "A helpful assistant" + instruction = "You are a helpful assistant." +} +``` + +## Inline vs Named Models + +Models can be referenced inline or defined in the `models` section: + +- **Inline** — quick and simple. Use `provider/model` syntax directly: `model: openai/gpt-5` +- **Named** — full control over parameters, reusable across agents: `model: my_claude` + +## Config Sections + +- [**HCL Configuration**](../hcl/index.md) — write the same agent schema in HCL using labeled blocks, heredocs, and block-based tool definitions. +- [**Agent Config**](../agents/index.md) — all agent properties: model, instruction, tools, sub-agents, hooks, and more. +- [**Model Config**](../models/index.md) — provider setup, parameters, thinking budget, and provider-specific options. +- [**Tool Config**](../tools/index.md) — built-in tools, MCP tools, Docker MCP, LSP, API tools, and tool filtering. + +## Advanced Configuration + +- [**Hooks**](../hooks/index.md) — run shell commands at lifecycle events like tool calls and session start/end. +- [**Permissions**](../permissions/index.md) — control which tools auto-approve, require confirmation, or are blocked. +- [**Sandbox Mode**](../sandbox/index.md) — run agents in an isolated Docker container for security. +- [**Structured Output**](../structured-output/index.md) — constrain agent responses to match a specific JSON schema. +- [**Flavors**](../flavors/index.md) — ship one agent file with named variants, enabled at run time as YAML patches. + +## Environment Variables + +API keys and secrets are read from environment variables — never stored in config files. See [Managing Secrets](../../guides/secrets/index.md) for all the ways to provide credentials (env files, Docker Compose secrets, the Docker Agent env file): + +| Variable | Provider | +| -------------------------- | --------------------------------------------------- | +| `OPENAI_API_KEY` | OpenAI | +| `ANTHROPIC_API_KEY` | Anthropic | +| `GOOGLE_API_KEY` / `GEMINI_API_KEY` | Google Gemini | +| `MISTRAL_API_KEY` | Mistral | +| `XAI_API_KEY` | xAI | +| `NEBIUS_API_KEY` | Nebius | +| `MINIMAX_API_KEY` | MiniMax | +| `REQUESTY_API_KEY` | Requesty | +| `OPENROUTER_API_KEY` | OpenRouter | +| `GITHUB_TOKEN` | GitHub Copilot (PAT with `copilot` scope) | +| `AZURE_API_KEY` | Azure OpenAI (override with `token_key`) | +| `AWS_BEARER_TOKEN_BEDROCK` | AWS Bedrock (or the standard AWS credentials chain) | + +**Tool Auto-Installation:** + +| Variable | Description | +| --------------------- | --------------------------------------------------------------- | +| `DOCKER_AGENT_AUTO_INSTALL` | Set to `false` to disable automatic tool installation | +| `DOCKER_AGENT_TOOLS_DIR` | Override the base directory for installed tools (default: `~/.cagent/tools/`) | + +**Runtime overrides:** + +| Variable | Description | +| ----------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `DOCKER_AGENT_DEFAULT_MODEL` | Default model used when none is specified, in `provider/model` form (e.g. `openai/gpt-5`). | +| `DOCKER_AGENT_MODELS_GATEWAY` | Route model traffic through a gateway. Equivalent to the `--models-gateway` flag. | +| `DOCKER_AGENT_HIDE_TELEMETRY_BANNER`| Set to `1` to suppress the first-run telemetry notice. | +| `DOCKER_AGENT_AUTO_UPDATE` | Set to a truthy value (`1`, `true`, `yes`, `on`) to let standalone release binaries self-update before running. See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates). | +| `DOCKER_AGENT_NO_TOKEN_EXCHANGE` | Set to `1` to stop Docker Agent from exchanging the access token stored by `docker login` for a Docker token. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). | +| `DOCKER_AGENT_HUB_LOGIN_URL` | Point the token exchange at a Docker staging environment. Ignored unless it is an HTTPS `docker.com` URL. | + +> [!NOTE] +> **Legacy `CAGENT_*` aliases** +> +> The same variables are also accepted with the legacy `CAGENT_` prefix (e.g. `CAGENT_DEFAULT_MODEL`, `CAGENT_MODELS_GATEWAY`, `CAGENT_HIDE_TELEMETRY_BANNER`) for backward compatibility. Prefer the `DOCKER_AGENT_*` form in new setups. + +> [!IMPORTANT] +> Model references are case-sensitive: `openai/gpt-5` is not the same as `openai/GPT-5`. + +## Variable Expansion in Config Fields + +Docker Agent expands `${env.VAR}` references in many config fields. This is the **canonical syntax everywhere** — prefer it for every field. Two engines back it: a full JavaScript evaluator for prompt/HTTP fields (where you also get defaults, ternaries, and tool calls), and a simpler path expander for filesystem/env fields (which additionally accepts the legacy `$VAR` / `${VAR}` / `~` shell forms). Picking `${env.VAR}` everywhere always works; the one caveat is that the path expander does not evaluate richer JS expressions. Using a shell-style `$VAR` in a JS-templated field is currently a silent no-op, so the literal string is passed through. Tracking issue: [#2615](https://github.com/docker/docker-agent/issues/2615). + +### JavaScript template literals — `${env.VAR}` + +Used wherever the agent prompt or HTTP traffic is templated. Backed by a JS evaluator, so you also get `||` defaults, ternaries, and tool calls (`${tool({...})}`). + +Applies to: + +- `agents.<name>.description` +- `agents.<name>.welcome_message` +- `agents.<name>.instruction` +- `agents.<name>.commands.*` (string form and `instruction:` field) +- `toolsets[*].instruction` +- `toolsets[*].headers` and `toolsets[*].remote.headers` (MCP, A2A, OpenAPI, fetch, API) + +For `api` toolsets, `api_config.endpoint` and `api_config.headers` are also rendered through the JS expander (the same syntax applies). + +```yaml +agents: + root: + description: "Assistant for ${env.USER || 'guest'}" + commands: + deploy: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}" + toolsets: + - type: openapi + url: https://api.example.com + headers: + Authorization: "Bearer ${env.INTERNAL_TOKEN}" +``` + +Undefined variables expand to the empty string. + +### Path & env fields — `${env.VAR}` (canonical), `$VAR` / `${VAR}` / `~` (aliases) + +Used for filesystem paths and process environment values. Backed by `os.ExpandEnv` plus tilde expansion against the current user's home directory. The canonical `${env.VAR}` form is accepted here too, so a single syntax works across every field; the bare `$VAR` / `${VAR}` shell forms remain supported as aliases. + +Applies to: + +- `agents.<name>.toolsets[*].working_dir` (MCP, LSP) +- `agents.<name>.toolsets[*].path` (memory, tasks) +- `agents.<name>.toolsets[*].env` values (MCP, shell, script, LSP) +- `agents.<name>.toolsets[*].shell.<tool>.working_dir` (script tools) +- `agents.<name>.hooks.*.working_dir` +- The `~` prefix is also accepted in any path-like field documented as such. + +```yaml +agents: + root: + toolsets: + - type: memory + path: "~/notes/${env.PROJECT}/memory.db" + - type: mcp + command: my-server + working_dir: "${env.HOME}/work" +``` + +Unlike the JS-templated fields above, these accept only a plain variable reference: richer JS expressions (e.g. `${env.VAR || 'default'}`) are **not** evaluated here, and the legacy `$VAR` / `${VAR}` forms keep working for backward compatibility. + +Hook and script-tool `env` values expand only the plain `${env.VAR}` form, resolved against the **OS process environment** (dotenv/secret-provider values are not consulted); a bare `$VAR` or `${VAR}` is passed through **literally**, so values that legitimately contain `$` (passwords, templates) are never mangled: + +```yaml +agents: + root: + hooks: + session_start: + - type: command + command: ./notify.sh + working_dir: "~/scripts" # ~, $VAR, ${VAR}, ${env.VAR} all work + env: + API_TOKEN: "${env.NOTIFY_TOKEN}" # expanded + PASSWORD: "pa$$word" # kept literal +``` + +Model definitions follow the same rule. The `models.<name>.model` and `models.<name>.base_url` fields are expanded when the provider is built, accepting both `${env.VAR}` and `${VAR}`. This is useful when the model id or endpoint is injected by the environment (for example a Docker Compose / DMR setup that exports the model reference as a variable): + +```yaml +models: + nemotron3: + provider: dmr + model: "${env.NEMOTRON3_MODEL}" # resolved from the environment at load time + base_url: "${DMR_BASE_URL}" # ${VAR} is accepted as well +``` + +`token_key` is **not** expanded: it already names the environment variable that holds the API token, so its value is used as a key rather than substituted. An unset variable in `model` or `base_url` is reported as an error instead of dialing with an empty value. + +### Quick reference + +| Field | `${env.X}` | `$X` / `${X}` | `~` | +| --------------------------------------------- | :--------: | :-----------: | :-: | +| `description`, `welcome_message` | ✓ | ✗ | ✗ | +| `instruction` (agent and toolset) | ✓ | ✗ | ✗ | +| `commands.*` | ✓ | ✗ | ✗ | +| `headers`, `remote.headers`, `api_config.headers` | ✓ | ✗ | ✗ | +| `models.*.model`, `models.*.base_url` | ✓ | ✓ | ✗ | +| `working_dir`, `path` (toolset, script tool, hook) | ✓ | ✓ | ✓ | +| `env` values (toolset) | ✓ | ✓ | ✗ | +| `env` values (hook, script tool) | ✓ | literal | ✗ | + +The `~` prefix is meaningful only in path-like fields (`working_dir`, `path`). In hook and script-tool `env` values, "literal" means a bare `$X` / `${X}` is passed to the process unchanged — only `${env.X}` is substituted there, so values containing `$` survive intact. + +Prefer `${env.X}` everywhere. The bare `$X` / `${X}` and `~` forms are accepted only in path and `env` value fields, where they remain supported for backward compatibility. + +## Validation + +Docker Agent validates your configuration at startup: + +- Local `sub_agents` must reference agents defined in the config (external OCI references like `myorg/agent:tag` are pulled from registries automatically; pin them to a digest with `@sha256:…` to avoid a per-run registry lookup) +- Named model references must exist in the `models` section +- Provider names must be valid (`openai`, `anthropic`, `google`, `dmr`, etc.) +- Required environment variables (API keys) must be set +- Tool-specific fields are validated (e.g., `path` is only valid for `memory`) + +## JSON Schema + +For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema](https://github.com/docker/docker-agent/blob/main/agent-schema.json). Add this to the top of your YAML file: + +```bash +# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json +``` + +## Config Versioning + +Docker Agent configs are versioned. The current version is `15`. Add the version at the top of your config: + +```yaml +version: 15 + +agents: + root: + model: openai/gpt-5 + # ... +``` + +When you load an older config, Docker Agent automatically migrates it to the latest schema. It's recommended to include the version to ensure consistent behavior. + +If you use a config key that requires a newer schema version, Docker Agent will fail with a strict-parse error and include a hint like: + +```text +hint: this key is supported by config version 12; update the top-level 'version' field (currently 11) +``` + +Bump the `version` field as directed to enable the new key. + +## Metadata Section + +Optional metadata for agent distribution via OCI registries: + +```yaml +metadata: + author: my-org + license: Apache-2.0 + description: A helpful coding assistant + readme: | # Displayed in registries + This agent helps with coding tasks. + version: "1.0.0" + tags: [coding, review] +``` + +| Field | Description | +| ------------- | ------------------------------------------ | +| `author` | Author or organization name | +| `license` | License identifier (e.g., Apache-2.0, MIT) | +| `description` | Short description for the agent | +| `readme` | Longer markdown description | +| `version` | Semantic version string | +| `tags` | Tags for categorization and discovery | + +See [Agent Distribution](../../concepts/distribution/index.md) for publishing agents to registries. + +## Reusable MCP Servers (`mcps:`) + +The top-level `mcps:` section defines named MCP server configurations that agents can reference with `toolsets: [{type: mcp, ref: <name>}]`. This avoids repeating the same command / URL / headers across agents and keeps credentials in one place. + +```yaml +mcps: + github: + remote: + url: https://api.githubcopilot.com/mcp + transport_type: sse + playwright: + command: npx + args: ["-y", "@modelcontextprotocol/server-playwright"] + +agents: + root: + model: openai/gpt-5 + toolsets: + - type: mcp + ref: github # reuse the definition above + - type: mcp + ref: playwright +``` + +An `mcps` entry accepts every field a regular `type: mcp` toolset accepts (command/args/env, `remote` with `url`/`transport_type`/`headers`/`oauth`, `tools` filter, `instruction`, `defer`, …) — the `type: mcp` is implicit. See the [Tool Config](../tools/index.md) page for all options and the [Remote MCP Servers](../../features/remote-mcp/index.md) guide for remote setups. + +## Reusable Toolsets (`toolsets:`) + +The top-level `toolsets:` map defines named toolset configurations that agents can reference by name through `use_toolsets:`. This avoids repeating the same toolset definition across multiple agents — the same pattern as `mcps:` for MCP servers and `commands:` / `skills:` for reusable prompt groups. + +Any toolset type is supported, including ones that reference MCP or RAG definitions. Shared toolsets are resolved before the MCP/RAG pass, so they can contain `{type: mcp, ref: <name>}` references. + +```yaml +toolsets: + fs: # a named shared toolset + type: filesystem + docs: + type: fetch + allowed_domains: + - docker.com + +agents: + root: + model: openai/gpt-5 + # Pull in shared toolsets by name; inline toolsets come first. + use_toolsets: [fs, docs] + toolsets: + - type: think + + reviewer: + model: openai/gpt-5 + # Reuse the same filesystem toolset without copying its definition. + use_toolsets: [fs] +``` + +Inline `toolsets:` entries listed directly on the agent take precedence in ordering (they come first) and are always included alongside referenced ones. + +See [`examples/shared-toolsets.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shared-toolsets.yaml) for a complete example. + +## Reusable Commands & Skills (`commands:` / `skills:`) + +The top-level `commands:` and `skills:` sections define named, reusable groups that agents pull in by name through `use_commands:` / `use_skills:`. This avoids repeating the same command set or skill configuration across agents. Each group value uses the exact same format as an agent's own `commands` / `skills` field. + +Referenced groups are merged into the agent during config loading. An agent's own inline `commands` / `skills` entries take precedence on name conflicts. + +```yaml +commands: + ci: # a named command group + deploy: "Deploy the application" + test: "Run the test suite" +skills: + base: [local, git] # a named skill group + +agents: + root: + model: openai/gpt-5 + use_commands: [ci] # reuse the "ci" command group + use_skills: [base] # reuse the "base" skill group + commands: + lint: "Run the linter" # inline command, merged in (wins on conflict) + reviewer: + model: openai/gpt-5 + use_commands: [ci] # same group, reused without duplication +``` + +See [`examples/shared-commands-skills.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shared-commands-skills.yaml) for a complete example. + +## Custom Providers Section + +Define reusable provider configurations with shared defaults. Providers can wrap any provider type — not just OpenAI-compatible endpoints: + +```yaml +providers: + # OpenAI-compatible custom endpoint + azure: + api_type: openai_chatcompletions + base_url: https://my-resource.openai.azure.com/openai/deployments/gpt-4o + token_key: AZURE_OPENAI_API_KEY + + # Anthropic with shared model defaults + team_anthropic: + provider: anthropic + token_key: TEAM_ANTHROPIC_KEY + max_tokens: 32768 + thinking_budget: 16384 + +models: + azure_gpt: + provider: azure + model: gpt-4o + + claude: + provider: team_anthropic + model: claude-sonnet-4-5 + # Inherits max_tokens, thinking_budget from provider + +agents: + root: + model: claude +``` + +| Field | Description | +| --------------------- | ---------------------------------------------------------------------------------------- | +| `provider` | Underlying provider type: `openai` (default), `anthropic`, `google`, `amazon-bedrock`, etc. | +| `api_type` | API schema: `openai_chatcompletions` (default) or `openai_responses`. OpenAI-only. | +| `base_url` | Base URL for the API endpoint. Required for OpenAI-compatible providers. | +| `token_key` | Environment variable name for the API token. | +| `temperature` | Default sampling temperature. | +| `max_tokens` | Default maximum response tokens. | +| `thinking_budget` | Default reasoning effort/budget. | +| `task_budget` | Default total token budget for an agentic task (Anthropic; honored by Claude Opus 4.7 today). | +| `top_p` | Default top-p sampling parameter. | +| `frequency_penalty` | Default frequency penalty. | +| `presence_penalty` | Default presence penalty. | +| `parallel_tool_calls` | Enable parallel tool calls by default. | +| `track_usage` | Track token usage by default. | +| `provider_opts` | Provider-specific options. | + +See [Provider Definitions](../../providers/custom/index.md) for more details. + +## Reusable YAML (anchors & aliases) + +YAML anchors (`&name`), aliases (`*name`) and merge keys (`<<`) are part of the YAML spec, and Docker Agent's config parser supports them. Use them to declare a value once and reuse it elsewhere in the same file, instead of copy-pasting the same block across agents. + +This complements the named-reuse sections above (`mcps:`, `commands:` / `skills:`, `providers:`). Reach for anchors when you want to share something those sections don't cover, such as an instruction string or a block of agent settings. + +Reuse a value verbatim with an anchor and an alias: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Coordinator. + instruction: &house_rules | + You are part of the Acme engineering team. + Cite the files you looked at and keep changes minimal. + reviewer: + model: anthropic/claude-sonnet-4-5 + description: Reviews code changes. + instruction: *house_rules # the same instruction, declared once +``` + +Compose a block with a merge key (`<<`), then override individual fields: + +```yaml +agents: + reviewer: &specialist + model: anthropic/claude-sonnet-4-5 + description: Reviews code changes. + instruction: | + You are a meticulous software professional. + toolsets: + - type: filesystem + documenter: + <<: *specialist # inherit model, instruction, toolsets + description: Writes documentation. # then override one field +``` + +> [!WARNING] +> **Where anchors can live** +> +> An anchor has to sit on a real value inside a known section (for example a real agent, model, or MCP entry, as above). Parking anchors in a separate top-level block such as `defaults:` or `prompts:` fails, because the parser rejects unknown top-level keys. + +> [!WARNING] +> **Overriding merged keys** +> +> Overriding a key that a `<<` merge already set works only in the `agents:` section, as shown above. Every other section (`models:`, `mcps:`, `providers:`, `rag:`) is parsed strictly and reports the override as a duplicate key. There, use `<<` only to add new fields, or use the named-reuse sections above when you need per-entry overrides. + +Anchors are for static reuse within a single file, not dynamic values or cross-file composition. For environment-specific settings, see [Variable Expansion in Config Fields](#variable-expansion-in-config-fields), which substitutes `${env.VAR}` at load time. Templating tags such as `!include` are not acted on: the tag is ignored and its argument is kept as a plain string, so no other file is loaded. Circular aliases are not detected, so keep references acyclic. + +See [`examples/yaml-anchors.yaml`](https://github.com/docker/docker-agent/blob/main/examples/yaml-anchors.yaml) for a complete example. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md new file mode 100644 index 000000000000..c49f5df5501b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md @@ -0,0 +1,314 @@ +--- +title: "Permissions" +description: "Control which tools can execute automatically, require confirmation, or are blocked entirely." +keywords: docker agent, ai agents, configuration, yaml, permissions +weight: 70 +canonical: https://docs.docker.com/ai/docker-agent/configuration/permissions/ +--- + +_Control which tools can execute automatically, require confirmation, or are blocked entirely._ + +## Overview + +Permissions provide fine-grained control over tool execution. You can configure which tools are auto-approved (run without asking), which require user confirmation, and which are completely blocked. + +> [!NOTE] +> **Evaluation Order** +> +> Permissions are evaluated in this order: **Deny → Allow → Ask**. Deny patterns take priority, then allow patterns, and anything else falls through to the session's [safety mode](#safety-modes). + +## Safety Modes + +Every session runs in a **safety mode** that decides what happens when no permission rule matched a tool call. The runtime labels each call `safe` (safe-listed shell command such as `ls` or `git status`, or a read-only-annotated tool), `destructive` (destructive shell command such as `rm -rf`, or a destructive-annotated tool), or `unknown` — and the mode gates on that label: + +| Mode | safe | destructive | unknown | +| ---- | ---- | ----------- | ------- | +| `strict` | ask | ask | ask | +| `balanced` | **allow** | ask | ask | +| `restricted` | **allow** | deny | deny | +| `autonomous` | **allow** | **allow** | **allow** | + +- **`strict`** prompts for every tool call, read-only ones included. Only an `allow:` rule silences a prompt. +- **`balanced`** runs safe calls silently and asks about everything else. +- **`restricted`** is the fail-closed profile for unattended/headless runs: safe calls run silently and everything else is **denied without asking** — the mode's fallback never prompts. Custom rules still win: an `allow:` rule can approve a destructive/unknown call, a `deny:` rule always blocks, and session-scoped `ask:` rules still prompt (as can a `preempt_yolo` hook). Restricted is defense in depth against unwanted tool calls, not a security boundary — for real isolation use [sandbox mode](../sandbox/index.md). +- **`autonomous`** is the legacy `--yolo` behavior: everything runs. Only `deny:` rules, session-scoped `ask:` rules, and `preempt_yolo` hooks still gate. + +Pick a mode with the `--safety` flag (`docker-agent run --safety balanced ...`), the `safety_policy` field on session create (`POST /api/sessions`) or mid-session (`PATCH /api/sessions/:id/safety-policy`), or escalate directly from a confirmation prompt (`B` switches to balanced, `A` to autonomous; the `restricted` fallback never prompts, so the mode is only selected via flag/config/API). Sessions that never choose a mode keep the historical default: read-only tools auto-approve, everything else asks. + +### Declarative Safety Defaults + +Safety modes can also be declared as **defaults** in YAML, at four scopes: + +| Scope | Location | Owner | +| ----- | -------- | ----- | +| Alias | `aliases.<name>.safety` in `~/.config/cagent/config.yaml` (or `docker agent alias add ... --safety <mode>`) | User | +| Global settings | `settings.safety` in `~/.config/cagent/config.yaml` | User | +| Per-agent | `agents.<name>.safety` in the agent YAML | Agent author | +| Config-wide | `runtime.safety` in the agent YAML | Agent author | + +```yaml +# Agent YAML (author-declared defaults) +runtime: + safety: balanced # config-wide default for new sessions + +agents: + root: + safety: strict # overrides runtime.safety for this agent +``` + +All four fields accept only the four canonical modes — `strict`, `balanced`, `restricted`, `autonomous` (yes, an author may declare `autonomous`) — and any other value fails loading with an error naming the field. The legacy spellings remain as aliases for `autonomous`: `settings.YOLO`, the alias `yolo` option, and the `--yolo` flag. When both are set at the same scope, `safety` wins over the legacy `YOLO`/`yolo`. + +For a **new** root session the first source in this order wins: + +1. explicit `--safety` flag +2. explicit `--yolo` flag +3. alias `safety`/`yolo` option +4. `settings.safety`/`settings.YOLO` (user config) +5. selected agent's `agents.<name>.safety` +6. `runtime.safety` +7. the historical default (read-only tools auto-approve, everything else asks) + +**Resuming a session never re-applies defaults**: the stored mode is kept unless you pass an explicit `--safety` or `--yolo` flag for that run. Agent switches, handoffs, and delegated sub-agent sessions inherit the active session's mode rather than resetting it. + +Sessions created through the API (`POST /api/sessions`) without a `safety_policy` receive the author-declared defaults (5–6) when their first run starts — the earliest point the agent configuration is loaded. If the server restarts before that first run, the session keeps the historical unset default (7). + +> [!WARNING] +> **Trust: author defaults never outrank you.** `runtime.safety` and `agents.<name>.safety` are written by the agent's author — which may be a config you pulled from a URL or an OCI registry. They only fill the gap when you expressed no preference: any user-owned source (CLI flag, alias option, user settings) always takes precedence, and a resumed session keeps its stored mode. Still, an author default of `autonomous` means a fresh session runs every tool call unprompted — review third-party configs before running them, or pin your own floor with `settings.safety` / `--safety`. + +**Custom rules always win over the mode**, with one asymmetry: `ask:` rules written in an agent's YAML (or global config) are agent-author advisories and yield to a user-chosen `balanced`/`restricted`/`autonomous` mode (under `restricted` they resolve to the mode's allow-or-deny verdict rather than introducing a prompt), while `ask:` rules granted at the session level (interactive "always ask" decisions, the session permissions API) always prompt. + +## Permission Levels + +Permissions can be defined at two levels: + +| Level | Location | Scope | +| ----- | -------- | ----- | +| **Agent-level** | Agent YAML config (`permissions:` section) | Applies to that specific agent config | +| **Global (user-level)** | `~/.config/cagent/config.yaml` under `settings.permissions` | Applies to every agent you run | + +Hooks follow the same user-config pattern: agent-level hooks live under `agents.<name>.hooks`, and global hooks live under `settings.hooks`. See [Hooks](../hooks/index.md#global-user-level-hooks). + +Both levels use the same `allow`/`ask`/`deny` pattern syntax. When both are present, they are **merged** at startup -- patterns from both sources are combined into a single checker. See [Merging Behavior](#merging-behavior) for details. + +## Agent-Level Configuration + +```yaml +agents: + root: + model: openai/gpt-4o + description: Agent with permission controls + instruction: You are a helpful assistant. + +permissions: + # Auto-approve these tools (no confirmation needed) + allow: + - "read_file" + - "read_*" # Glob patterns + - "shell:cmd=ls*" # With argument matching + + # Always ask before running these tools, even if an allow pattern would match + ask: + - "shell:cmd=git push*" + - "write_file:path=/home/user/important/*" + + # Block these tools entirely + deny: + - "shell:cmd=sudo*" + - "shell:cmd=rm*-rf*" + - "dangerous_tool" +``` + +The three lists are evaluated in order `deny` → `allow` → `ask`, so an `ask:` entry lets you add a confirmation layer on top of an otherwise-allowed tool. + +## Global Permissions + +Global permissions let you enforce rules across **all** agents, regardless of which agent config you run. Define them in your user config file: + +```yaml +# ~/.config/cagent/config.yaml +settings: + permissions: + deny: + - "shell:cmd=sudo*" + - "shell:cmd=rm*-rf*" + allow: + - "read_*" + - "shell:cmd=ls*" + - "shell:cmd=cat*" +``` + +This is useful for setting personal safety guardrails that apply everywhere -- for example, always blocking `sudo` or always auto-approving read-only tools -- without relying on each agent config to include those rules. + +### Merging Behavior + +When both global and agent-level permissions are present, they are merged into a single set of patterns before evaluation. The merge works as follows: + +- **Deny patterns from either source block the tool.** A global deny cannot be overridden by an agent-level allow, and vice versa. +- **Allow patterns from either source auto-approve the tool** (as long as no deny pattern matches). +- **Ask patterns from either source force confirmation** (as long as no deny or allow pattern matches). + +The evaluation order remains the same after merging: **Deny > Allow > Ask > default Ask**. + +> [!TIP] +> **Example: Global deny + agent allow** +> +> If your global config denies `shell:cmd=sudo*` and an agent config allows `shell:cmd=sudo apt update`, the deny wins. Deny patterns always take priority regardless of source. + +## Pattern Syntax + +Permissions support glob-style patterns with optional argument matching: + +### Simple Patterns + +| Pattern | Matches | +| -------------- | ------------------------------ | +| `shell` | Exact match for `shell` tool | +| `read_*` | Any tool starting with `read_` | +| `github_*` | Any GitHub MCP tool | +| `*` | All tools | + +### Argument Matching + +You can match tools based on their argument values using `tool:arg=pattern` syntax: + +```yaml +permissions: + allow: + # Allow shell only when cmd starts with "ls" or "cat" + - "shell:cmd=ls*" + - "shell:cmd=cat*" + + # Allow edit_file only in specific directory + - "edit_file:path=/home/user/safe/*" + + deny: + # Block shell with sudo + - "shell:cmd=sudo*" + + # Block writes to system directories + - "write_file:path=/etc/*" + - "write_file:path=/usr/*" +``` + +> [!NOTE] +> **Colons inside argument values are preserved.** Only the `:key=` token boundaries between +> argument conditions split a pattern — colons that appear inside a value are treated as +> ordinary characters and do not start a new condition. Check a tool’s actual argument names +> (and whether they accept a string or a list) before writing an argument-matching pattern. + +### Multiple Argument Conditions + +Chain multiple argument conditions with colons. All conditions must match: + +```yaml +permissions: + allow: + # Allow shell with ls in current directory + - "shell:cmd=ls*:cwd=." + + deny: + # Block shell with rm -rf anywhere + - "shell:cmd=rm*:cmd=*-rf*" +``` + +## Glob Pattern Rules + +Patterns follow filepath.Match semantics with some extensions: + +- `*` — matches any sequence of characters (including spaces) +- `?` — matches any single character +- `[abc]` — matches any character in the set +- `[a-z]` — matches any character in the range + +Matching is **case-insensitive**. + +> [!TIP] +> **Trailing Wildcards** +> +> Trailing wildcards like `sudo*` match any characters including spaces, so `sudo*` matches `sudo rm -rf /`. + +## Decision Types + +| Decision | Behavior | +| --------- | --------------------------------------------------- | +| **Allow** | Tool executes immediately without user confirmation | +| **Ask** | User must confirm before tool executes (default) | +| **Deny** | Tool is blocked and returns an error to the agent | + +## Examples + +### Read-Only Agent + +Allow all read operations, block all writes: + +```yaml +permissions: + allow: + - "read_file" + - "read_multiple_files" + - "list_directory" + - "directory_tree" + - "search_files_content" + deny: + - "write_file" + - "edit_file" + - "shell" +``` + +### Safe Shell Agent + +Allow specific safe commands, block dangerous ones: + +```yaml +permissions: + allow: + - "shell:cmd=ls*" + - "shell:cmd=cat*" + - "shell:cmd=grep*" + - "shell:cmd=find*" + - "shell:cmd=head*" + - "shell:cmd=tail*" + - "shell:cmd=wc*" + deny: + - "shell:cmd=sudo*" + - "shell:cmd=rm*" + - "shell:cmd=mv*" + - "shell:cmd=chmod*" + - "shell:cmd=chown*" +``` + +### MCP Tool Permissions + +Control MCP tools by their qualified names: + +```yaml +permissions: + allow: + # Allow all GitHub read operations + - "github_get_*" + - "github_list_*" + - "github_search_*" + deny: + # Block destructive GitHub operations + - "github_delete_*" + - "github_close_*" +``` + +## Combining with Hooks + +Permissions work alongside [hooks](../hooks/index.md). The evaluation order is: + +1. Run **`preempt_yolo` pre_tool_use hooks** — security-critical checks that no mode or allow rule can bypass +2. Check **deny** patterns — if matched, tool is blocked +3. Check **allow** patterns — if matched, tool is auto-approved +4. Check **ask** patterns — if matched, the user is prompted directly, skipping the default `pre_tool_use` lane +5. If no rule matched, apply the **[safety mode](#safety-modes)** to the call's safety label — may auto-approve (or, under `restricted`, deny) +6. On a mode "ask", run **pre_tool_use hooks** — hooks can allow, deny, or ask +7. If no decision, **ask user** for confirmation + +Default-lane hooks only see calls the mode routed to "ask"; they cannot override deny decisions or explicit `ask:` rules. + +> [!WARNING] +> **Security Note** +> +> Permissions are enforced client-side. They help prevent accidental operations but should not be relied upon as a security boundary for untrusted agents. For stronger isolation, use [sandbox mode](../sandbox/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md new file mode 100644 index 000000000000..54c187bbf63f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md @@ -0,0 +1,170 @@ +--- +title: "Model Routing" +description: "Route requests to different models based on the content of user messages." +keywords: docker agent, ai agents, configuration, yaml, model routing +weight: 100 +canonical: https://docs.docker.com/ai/docker-agent/configuration/routing/ +--- + +_Route requests to different models based on the content of user messages._ + +## Overview + +Model routing lets you define a "router" model that automatically selects the best underlying model based on the user's message. This is useful for cost optimization, specialized handling, or load balancing across models. + +> [!NOTE] +> **How It Works** +> +> Docker Agent uses NLP-based text similarity (via Bleve full-text search) to match user messages against example phrases you define. The route with the best-matching examples wins, and that model handles the request. + +## Configuration + +Add `routing` rules to any model definition. The model's `provider`/`model` fields become the fallback when no route matches: + +```yaml +models: + smart_router: + # Fallback model when no routing rule matches + provider: openai + model: gpt-5-mini + + # Routing rules + routing: + - model: anthropic/claude-sonnet-4-5 + examples: + - "Write a detailed technical document" + - "Help me architect this system" + - "Review this code for security issues" + - "Explain this complex algorithm" + + - model: openai/gpt-5 + examples: + - "Generate some creative ideas" + - "Write a story about" + - "Help me brainstorm" + - "Come up with names for" + + - model: openai/gpt-5-mini + examples: + - "What time is it" + - "Convert this to JSON" + - "Simple math calculation" + - "Translate this word" + +agents: + root: + model: smart_router + description: Assistant with intelligent model routing + instruction: You are a helpful assistant. +``` + +## Routing Rules + +Each routing rule has: + +| Field | Type | Required | Description | +| ---------- | ------ | -------- | ------------------------------------------------------------- | +| `model` | string | ✓ | Target model (inline format or reference to `models` section) | +| `examples` | array | ✓ | Example phrases that should route to this model | + +## Matching Behavior + +The router: + +1. Extracts the last user message from the conversation +2. Searches all examples using full-text search +3. Aggregates match scores by route (best score per route wins) +4. Selects the route with the highest overall score +5. Falls back to the base model if no good match is found + +> [!TIP] +> **Writing Good Examples** +> +> - Use diverse phrasing that captures the intent +> - Include keywords users actually use +> - Add 5-10 examples per route for best results +> - Examples don't need to be exact matches — the router uses semantic similarity + +## Use Cases + +### Cost Optimization + +Route simple queries to cheaper models: + +```yaml +models: + cost_optimizer: + provider: openai + model: gpt-5-mini # Cheap fallback + routing: + - model: anthropic/claude-sonnet-4-5 + examples: + - "Complex analysis" + - "Detailed research" + - "Multi-step reasoning" +``` + +### Specialized Models + +Route coding tasks to code-specialized models: + +```yaml +models: + task_router: + provider: openai + model: gpt-5-mini # General fallback + routing: + - model: anthropic/claude-sonnet-4-5 + examples: + - "Write code" + - "Debug this function" + - "Review my implementation" + - "Fix this bug" + - model: openai/gpt-5 + examples: + - "Write a blog post" + - "Help me with writing" + - "Summarize this document" +``` + +### Load Balancing + +Distribute load across equivalent models from different providers: + +```yaml +models: + load_balancer: + provider: openai + model: gpt-5-mini + routing: + - model: anthropic/claude-sonnet-4-5 + examples: + - "First request pattern" + - "Another request type" + - model: google/gemini-2.5-flash + examples: + - "Different request pattern" + - "Alternative query style" +``` + +## Debugging + +Enable debug logging to see routing decisions: + +```bash +$ docker agent run config.yaml --debug +``` + +Look for log entries like: + +```text +"Rule-based router selected model" router=smart_router selected_model=anthropic/claude-sonnet-4-5 +"Route matched" model=anthropic/claude-sonnet-4-5 score=2.45 +``` + +> [!WARNING] +> **Limitations** +> +> - Routing only considers the last user message, not full conversation context +> - Very short messages may not match well — consider your fallback carefully +> - Each routed model creates a separate provider connection diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md new file mode 100644 index 000000000000..ec8cf9540d50 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md @@ -0,0 +1,286 @@ +--- +title: "Sandbox Mode" +description: "Run agents in an isolated sandbox VM managed by sbx." +keywords: docker agent, sbx, ai agents, configuration, yaml, sandbox mode +weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/configuration/sandbox/ +--- + +_Run agents in an isolated sandbox VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/)._ + +## Overview + +Sandbox mode is Docker Agent's integration with +[`sbx`](https://docs.docker.com/ai/sandboxes/), Docker's sandbox product. `sbx` +provides the runtime, CLI, and VM; Docker Agent is one of its built-in agents. +The `--sandbox` flag asks `sbx` to create or reuse a VM and launches Docker +Agent inside it. + +All shell, filesystem, and process activity happens inside that VM, so a +misbehaving agent cannot touch files outside the mounted working directory or +reach long-lived host state. Docker Agent does not implement the sandbox or +start a raw `docker run` container; it orchestrates the installed `sbx` CLI. + +> [!NOTE] +> **Requirements** +> +> Install and configure the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/) before +> using `--sandbox`. + +## Usage + +Enable sandbox mode with the `--sandbox` flag on the `docker agent run` command: + +```bash +docker agent run --sandbox agent.yaml +``` + +Docker Agent asks `sbx` to launch or reuse a sandbox VM, mounts the current +working directory, and runs the agent inside it. + +## Flags + +| Flag | Default | Description | +| ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `--sandbox` | `false` | Enable sandbox mode. | +| `--template` | `docker/docker-agent-sbx-templates:latest` | OCI image used as the sandbox template. Passed to `sbx create -t`. See [Sandbox templates](#sandbox-templates). | +| `--no-kit` | `false` | Disable the [auto-kit](#auto-kit) — do not stage skills or prompt files into the sandbox. | + +```bash +# Use a custom template image +docker agent run --sandbox --template myorg/custom-agent-template:latest agent.yaml + +# Run without staging skills / prompt files into the sandbox +docker agent run --sandbox --no-kit agent.yaml +``` + +### Always sandbox a given agent + +Add `--sandbox` to an [alias](../../features/cli/index.md#docker-agent-alias) so the +sandbox path is taken automatically whenever that alias is invoked: + +```bash +docker agent alias add safe-coder myorg/coder --sandbox +docker agent run safe-coder +``` + +An explicit `--sandbox=false` on the command line still wins, so you can opt +out of the sandbox for a single run without touching the alias. + +### Bake the default into the agent config + +Agent authors can declare a sandbox default in the YAML itself. Any caller of +the agent then gets the sandbox path automatically, without having to know +(or remember) to pass `--sandbox`: + +```yaml +# agent.yaml +runtime: + sandbox: true + +agents: + root: + model: openai/gpt-4o + description: A helpful assistant + instruction: You are a helpful assistant. + toolsets: + - type: shell +``` + +```bash +docker agent run agent.yaml # runs in a sandbox automatically +``` + +The rule is the same as for aliases: an explicit `--sandbox=false` on the +CLI overrides the config default, so you can debug an agent on the host +without editing its YAML. + +### Declare a network allowlist + +The runner already opens the [tool install hosts](#network-allowlist) and +the [models gateway](#how-it-works) automatically, but agents that talk +to endpoints those resolvers can't infer (custom MCP servers, third-party +APIs, registries not covered by the aqua resolver) would still see a 403 +from the sandbox proxy on first contact. + +Declare those hosts in `runtime.network_allowlist` and they are unioned +with the inferred set, so the agent can reach them on its first request: + +```yaml +# agent.yaml +runtime: + sandbox: true + network_allowlist: + - api.example.com + - registry.npmjs.org +``` + +Each entry is a hostname with an optional `:port` suffix. Commas and +whitespace are rejected to keep a single entry from smuggling several +rules into the policy engine. The runner prints the resulting allowlist +before launch so you can audit exactly which hosts the run opens up. + +### Persist your own allowlist + +For hosts you keep needing across agents (a corporate proxy, a +self-hosted registry, ...) `docker agent sandbox allow` writes the +entry into `~/.config/cagent/config.yaml` once and unions it with the +inferred and agent-declared sets on every subsequent `--sandbox` run: + +```bash +# I just got a `Blocked by network policy` 403 on api.example.com. +docker agent sandbox allow api.example.com + +# See what's currently persisted. +docker agent sandbox list + +# Drop a host you no longer need. +docker agent sandbox deny api.example.com +``` + +When the kit's per-toolset host resolver fails (the `! using fallback +host set` line in the launch summary), the runner now prints a hint +pointing at this command so you can turn the missing host into a +one-line, persistent fix instead of relying on the wider conservative +fallback host set. + +## Sandbox templates + +A sandbox template is the OCI image the sandbox VM boots from. It determines +the base OS and the tools available inside the VM, including whether the +`docker-agent` binary is already there. `--template` (or `-t` on `sbx +create`) selects it. + +### The default template + +`--template` defaults to `docker/docker-agent-sbx-templates:latest`, the +template this repository's own CI builds and publishes from the most recent +`v*` release — see [The repo-published templates](#the-repo-published-templates) +for what it contains and the other available tags. + +### The repo-published templates + +This repository's own CI builds and publishes the sandbox template — from +the `template` stage of the +[`Dockerfile`](https://github.com/docker/docker-agent/blob/main/Dockerfile) — +as `docker/docker-agent-sbx-templates`: + +| Tag | Built from | Use it when | +| --------- | ------------------------------ | ------------------------------------------------------------------- | +| `:latest` | The most recent `v*` release | You want the newest Docker Agent template with release stability (the default). | +| `:edge` | The current `main` branch | You want today's `main` build and can tolerate lower stability. | + +(Each release also publishes a matching version-pinned tag, e.g. +`docker/docker-agent-sbx-templates:1.2.3`.) + +`:latest` is the default. Reach for `:edge` only when you specifically +need an unreleased fix or feature and can tolerate the occasional breakage. +For reproducible runs, pin to a digest instead of a tag, e.g. +`docker/docker-agent-sbx-templates@sha256:...`. + +Select one with `--template`: + +```bash +$ docker agent run --sandbox --template docker/docker-agent-sbx-templates:edge agent.yaml +``` + +Or point the [`sbx`](https://docs.docker.com/ai/sandboxes/) CLI at it +directly, without going through Docker Agent: + +```bash +$ sbx create -t docker/docker-agent-sbx-templates:latest +``` + +> [!TIP] +> The [`sbx` documentation](https://docs.docker.com/ai/sandboxes/) covers the +> sandbox CLI and runtime independently of Docker Agent. + +### What they contain + +The `template` stage in this repository's +[`Dockerfile`](https://github.com/docker/docker-agent/blob/main/Dockerfile) +layers onto `docker/sandbox-templates:shell-docker` and adds: + +- The `docker-agent` binary. +- `vim` and `tmux`, for interactive debugging inside the VM. +- The **`docker-mcp`** Docker CLI plugin, installed at `~/.docker/cli-plugins/docker-mcp`. + +The image carries the label `com.docker.sandboxes.flavor=docker-agent-docker` +so sandbox tooling can identify it. + +## Example + +```yaml +# agent.yaml +agents: + root: + model: openai/gpt-4o + description: Agent with sandboxed shell + instruction: You are a helpful assistant. + toolsets: + - type: shell +``` + +```bash +docker agent run --sandbox agent.yaml +``` + +## How It Works + +1. `--sandbox` tells Docker Agent to invoke the installed `sbx` CLI. +2. A new sandbox VM is created from the image passed via `--template`. +3. The current working directory is mounted into the VM; the agent binary is copied in. +4. The [auto-kit](#auto-kit) is staged on the host and bind-mounted read-only into the VM, so the agent sees its skills and prompt files inside the sandbox. +5. The default-deny network proxy is opened for the configured [models gateway](../../features/cli/index.md#runtime-configuration-flags) and any package hosts the auto-installer needs for the agent's MCP/LSP toolsets. +6. All tools (shell, filesystem, background jobs, etc.) run inside the VM. +7. When the session ends, Docker Agent exits but does not stop or remove the sandbox VM; both the VM and the kit are kept around so subsequent runs from the same workspace can reuse them. A fresh sandbox is created only when the mount set has changed. + +### What the default template includes + +The default template (`docker/docker-agent-sbx-templates:latest`) is built +from this repository's own `Dockerfile` — see +[What they contain](#what-they-contain) for the exact contents, including +the `docker-mcp` CLI plugin. + +## Auto-Kit + +The sandbox VM has its own filesystem and `$HOME` — none of the host's `~/.agents/skills/`, `~/.claude/skills/`, project-level `.agents/skills/`, or prompt files like `AGENTS.md` and `CLAUDE.md` are visible inside it. To bridge that gap, Docker Agent automatically builds a **kit**: a self-contained directory staged on the host before the sandbox starts and bind-mounted read-only into the VM at the same path. + +The kit is built whenever `--sandbox` is used with an agent reference. It is opt-out via `--no-kit`. + +### What gets staged + +For the agent referenced on the command line, the kit collects: + +- **Local [skills](../../features/skills/index.md)** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/`, `.github/skills/` and `.agents/skills/`) is copied under `<kit>/skills/<skill-name>/`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. +- **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Files that already live under the working directory are left alone (the live workspace mount surfaces them); files outside it (e.g. an `AGENTS.md` in `$HOME`) are copied under `<kit>/prompt_files/`. +- **A manifest** — `<kit>/manifest.json` records what was staged. The on-disk copy is sanitised so it cannot be used to map the host filesystem from inside the sandbox. + +Before launch, Docker Agent prints a summary of what was staged so you can see exactly which skills and prompt files the agent will have access to inside the sandbox. + +### Secret redaction + +Every text file copied into the kit is run through [portcullis](https://github.com/docker/portcullis), which redacts secrets that match its detection patterns (API keys, tokens, …) in the staged copy. The kit's printed summary marks files as `(redacted)` whenever at least one secret was replaced. Detection is best-effort — portcullis recognises common secret formats but novel or obfuscated tokens may slip through, so the kit is not a substitute for keeping secrets out of skill sources in the first place. + +### Network allowlist + +The sandbox templates ship with a default-deny network proxy that allows the major model providers but blocks `*.docker.com` and every package-registry / source host the auto-installer reaches for. When the agent declares MCP or LSP toolsets that have a `command` and an installable `version`, the kit build resolves each toolset's package against the [aqua](https://aquaproj.github.io/) registry and computes the minimal set of hosts the in-sandbox auto-installer will need (Go module proxy + toolchain bootstrap for `go_install` packages, GitHub release hosts for `github_release` packages, …). Those hosts, `models.dev` (needed so the in-sandbox agent can resolve model metadata such as context limits, pricing, and capabilities — without it the first catalog lookup fails with a `403 Blocked by network policy` error), and the configured [`--models-gateway`](../../features/cli/index.md#runtime-configuration-flags) — are then allow-listed on the sandbox proxy. If a per-toolset registry lookup fails, a conservative fallback union is used so the run can still succeed; the affected toolsets are surfaced in the printed summary. + +### Caching + +Kits are stored under the Docker Agent cache directory (`~/Library/Caches/cagent/sandbox-kits/<hash>` on macOS) keyed by a content hash of the agent reference. Reusing the same agent across runs reuses the same kit directory in place; disk usage is bounded by the number of distinct agents you have run. Kits are deliberately kept on disk between runs because the reused sandbox VM holds a hard reference to the kit's bind-mount path — deleting it would leave the sandbox un-startable. + +### Disabling the kit + +Pass `--no-kit` to skip the kit build entirely. The agent then runs without any host-side skills or external prompt files visible inside the sandbox, and the network allowlist falls back to the template defaults. Useful for debugging the sandbox itself, or for agents that don't depend on host skills. + +```bash +docker agent run --sandbox --no-kit agent.yaml +``` + +> [!WARNING] +> **Limitations** +> +> - Sandboxes are reused across runs from the same workspace; if the required mount set changes (e.g. a new kit is staged), the previous sandbox is removed and a fresh one is created. +> - Only the working directory, the agent config directory, and (when staged) the kit directory are mounted; other host files are not visible to the agent. +> - Network egress is constrained by the sandbox backend's default-deny policy plus the per-run allowlist described above. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md new file mode 100644 index 000000000000..9dc4c9e30343 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md @@ -0,0 +1,250 @@ +--- +title: "Structured Output" +description: "Force the agent to respond with JSON matching a specific schema." +keywords: docker agent, ai agents, configuration, yaml, structured output +weight: 90 +canonical: https://docs.docker.com/ai/docker-agent/configuration/structured-output/ +--- + +_Force the agent to respond with JSON matching a specific schema._ + +## Overview + +Structured output constrains the agent's responses to match a predefined JSON schema. This is useful for building agents that need to produce machine-readable output for downstream processing, API responses, or integration with other systems. + +> [!NOTE] +> **When to Use** +> +> - Building API endpoints that need consistent JSON responses +> - Data extraction and transformation pipelines +> - Agents that feed into other automated systems +> - Ensuring predictable output format for parsing + +## Configuration + +```yaml +agents: + analyzer: + model: openai/gpt-4o + description: Code analyzer that outputs structured results + instruction: | + Analyze the provided code and identify issues. + Return your findings in the structured format. + structured_output: + name: analysis_result + description: Code analysis findings + strict: true + schema: + type: object + properties: + issues: + type: array + items: + type: object + properties: + severity: + type: string + enum: ["error", "warning", "info"] + line: + type: integer + message: + type: string + required: ["severity", "line", "message"] + summary: + type: string + required: ["issues", "summary"] +``` + +## Properties + +| Property | Type | Required | Description | +| ------------- | ------- | -------- | ----------------------------------------------------------------- | +| `name` | string | ✓ | Name identifier for the output schema | +| `description` | string | ✗ | Description of what the output represents | +| `strict` | boolean | ✗ | Enforce strict schema adherence — `native` mode only (default: `false`) | +| `schema` | object | ✓ | JSON Schema defining the output structure | +| `mode` | string | ✗ | Enforcement mode: `native` (default) or `tool` (see [Modes](#modes)) | + +## Modes + +### `native` (default) + +The schema is passed to the provider's native structured-output support (OpenAI JSON mode, Gemini JSON mode, ...). Omitting `mode` keeps this behavior. + +### `tool` + +```yaml +structured_output: + mode: tool + name: analysis_result + schema: + type: object + properties: + summary: + type: string + required: ["summary"] +``` + +In tool mode nothing is sent to the provider's native structured-output API. Instead, the runtime exposes an internal tool named `__structured_output__` whose parameters are exactly the configured schema. The model works normally — including calling other tools — and delivers its final answer by calling that tool, alone, as the only tool call of its response. The runtime validates the arguments against the schema: + +- A valid call ends the turn; the validated (compacted) JSON becomes the final assistant message. +- Invalid JSON gets a detailed tool error so the model can correct itself and retry. +- If the model answers in plain text instead, the runtime injects a transient system reminder and retries (at most 2 reminders), then fails with a `structured_output_failed` error. + +Tool-mode validation applies the full JSON Schema, including `additionalProperties` — unexpected fields are rejected when the schema forbids them. External `$ref` references (`http(s)://`, `file://`, cross-document) are rejected when the schema is compiled; only same-document references starting with `#` (e.g. `#/definitions/item`) are allowed. The `strict` flag has no effect in tool mode. + +Fork-mode skills (`context: fork`) run as exempt sub-sessions: the skill produces its own plain-text answer for the calling agent and is not required to call the output tool. The parent agent still delivers its final answer through the tool. + +Use tool mode when the model must combine tool use with a schema-constrained final answer, or when the provider has no native structured-output support. See [`examples/structured-output-tool-mode.yaml`](https://github.com/docker/docker-agent/blob/main/examples/structured-output-tool-mode.yaml). + +## Schema Format + +The schema follows [JSON Schema](https://json-schema.org/) specification. Common schema types: + +### Simple Object + +```yaml +schema: + type: object + properties: + name: + type: string + count: + type: integer + active: + type: boolean + required: ["name", "count"] +``` + +### Array of Objects + +```yaml +schema: + type: object + properties: + items: + type: array + items: + type: object + properties: + id: + type: string + value: + type: number + required: ["id", "value"] + required: ["items"] +``` + +### Enum Values + +```yaml +schema: + type: object + properties: + status: + type: string + enum: ["pending", "approved", "rejected"] + priority: + type: string + enum: ["low", "medium", "high", "critical"] + required: ["status"] +``` + +## Strict Mode + +`strict` only applies to `native` mode: it is passed to the provider's structured-output API. Tool mode ignores it and always validates against the full schema instead. When `strict: true`, the model is constrained to only produce output that exactly matches the schema. This provides stronger guarantees but may limit the model's flexibility. + +- **`strict: false` (default)** — model aims to match the schema but may include additional fields or slight variations. +- **`strict: true`** — model output is constrained to exactly match the schema. Stronger guarantees. + +## Provider Support + +Structured output support varies by provider: + +| Provider | Support | Notes | +| ------------- | ---------- | --------------------------------------- | +| OpenAI | ✓ Full | Native JSON mode with schema validation | +| Anthropic | ✓ Full | Tool-based structured output | +| Google Gemini | ✓ Full | Native JSON mode | +| AWS Bedrock | ✓ Partial | Depends on underlying model | +| DMR | ⚠️ Limited | Depends on model capabilities | + +## Example: Data Extraction Agent + +```yaml +agents: + extractor: + model: openai/gpt-4o + description: Extract structured data from text + instruction: | + Extract contact information from the provided text. + Return all found contacts in the structured format. + structured_output: + name: contacts + description: Extracted contact information + strict: true + schema: + type: object + properties: + contacts: + type: array + items: + type: object + properties: + name: + type: string + description: Full name of the contact + email: + type: string + description: Email address + phone: + type: string + description: Phone number + company: + type: string + description: Company or organization + required: ["name"] + total_found: + type: integer + description: Total number of contacts found + required: ["contacts", "total_found"] +``` + +## Example: Classification Agent + +```yaml +agents: + classifier: + model: anthropic/claude-sonnet-4-5 + description: Classify support tickets + instruction: | + Classify the support ticket into the appropriate category + and priority level based on its content. + structured_output: + name: ticket_classification + strict: true + schema: + type: object + properties: + category: + type: string + enum: + ["billing", "technical", "account", "feature_request", "other"] + priority: + type: string + enum: ["low", "medium", "high", "urgent"] + confidence: + type: number + minimum: 0 + maximum: 1 + description: Confidence score between 0 and 1 + reasoning: + type: string + description: Brief explanation for the classification + required: ["category", "priority", "confidence"] +``` + +> [!WARNING] +> **Tool Limitations** +> +> When using native structured output, the agent typically cannot use tools since its response format is constrained to the schema. Design your agent workflow accordingly — native structured output agents work best for single-turn analysis or extraction tasks. Use `mode: tool` when the agent needs to call tools before producing its schema-constrained final answer. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md new file mode 100644 index 000000000000..ff25b1f45ba0 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md @@ -0,0 +1,518 @@ +--- +title: "Tool Configuration" +description: "Complete reference for configuring built-in tools, MCP tools, and Docker-based tools." +keywords: docker agent, ai agents, configuration, yaml, tool configuration +linkTitle: "Tool Config" +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/configuration/tools/ +aliases: + - /ai/docker-agent/reference/toolsets/ +--- + +_Complete reference for configuring built-in tools, MCP tools, and Docker-based tools._ + +## Built-in Tools + +Built-in tools are included with Docker Agent and require no external dependencies. Add them to your agent's `toolsets` list by `type`. Each tool's dedicated page covers its full configuration options, available operations, and examples. + +| Type | Description | Page | +| --- | --- | --- | +| `filesystem` | Read, write, list, search, navigate | [Filesystem](../../tools/filesystem/index.md) | +| `git` | Read-only repository inspection (status, log, branches, show, blame) | [Git](../../tools/git/index.md) | +| `shell` | Execute shell commands synchronously | [Shell](../../tools/shell/index.md) | +| `background_jobs` | Run and manage long-running shell commands | [Background Jobs](../../tools/background-jobs/index.md) | +| `scheduler` | Schedule instructions to run at a time or on a recurring interval | [Scheduler](../../tools/scheduler/index.md) | +| `think` | Reasoning scratchpad | [Think](../../tools/think/index.md) | +| `plan` | Shared persistent scratchpad for multi-agent collaboration | [Plan](../../tools/plan/index.md) | +| `session_plan` | Per-session markdown plan for the draft-review-execute workflow | [Session Plan](../../tools/session_plan/index.md) | +| `session_context` | Reference a previous session as context (read-only) | [Session Context](../../tools/session_context/index.md) | +| `todo` | Task list management | [Todo](../../tools/todo/index.md) | +| `memory` | Persistent key-value storage (SQLite) | [Memory](../../tools/memory/index.md) | +| `tasks` | Persistent task database shared across sessions | [Tasks](../../tools/tasks/index.md) | +| `fetch` | HTTP `GET` requests with text/markdown/html output | [Fetch](../../tools/fetch/index.md) | +| `script` | Custom shell scripts as tools | [Script](../../tools/script/index.md) | +| `lsp` | Language Server Protocol integration | [LSP](../../tools/lsp/index.md) | +| `api` | Custom HTTP API tools | [API](../../tools/api/index.md) | +| `openapi` | Import every operation of an OpenAPI 3.x document as tools | [OpenAPI](../../tools/openapi/index.md) | +| `rag` | Retrieval-augmented generation over indexed sources | [RAG](../../tools/rag/index.md) | +| `model_picker` | Let the agent pick between several models per turn | [Model Picker](../../tools/model-picker/index.md) | +| `user_prompt` | Interactive user input | [User Prompt](../../tools/user-prompt/index.md) | +| `open_url` | Open a fixed URL in the user's default browser | [Open URL](../../tools/open-url/index.md) | +| `transfer_task` | Delegate to sub-agents (auto-enabled) | [Transfer Task](../../tools/transfer-task/index.md) | +| `background_agents` | Parallel sub-agent dispatch | [Background Agents](../../tools/background-agents/index.md) | +| `webhook` | Reliable notifications to a configured destination, with retries (Slack, Discord, Telegram, IFTTT, Teams, …) | [Webhook](../../tools/webhook/index.md) | +| `handoff` | Local conversation handoff to another agent in the same config (auto-enabled by `handoffs:`) | [Handoff](../../tools/handoff/index.md) | +| `a2a` | A2A remote agent connection | [A2A](../../tools/a2a/index.md) | +| `mcp_catalog` | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | [MCP Catalog](../../tools/mcp-catalog/index.md) | + +**Example:** + +```yaml +toolsets: + - type: filesystem + - type: shell + - type: background_jobs + - type: think + - type: todo + - type: memory + path: ./dev.db +``` + +## MCP Tools + +Extend agents with external tools via the [Model Context Protocol](https://modelcontextprotocol.io/). For a standalone overview of the `mcp` toolset see the [MCP tool page](../../tools/mcp/index.md). + +> [!TIP] +> **Reusable MCP definitions** +> +> Repeated MCP server definitions can be hoisted into the top-level `mcps:` section and referenced by name with `{type: mcp, ref: <name>}`. See [Reusable MCP Servers](../overview/index.md#reusable-mcp-servers-mcps). + +### Docker MCP (Recommended) + +Run MCP servers as secure Docker containers via the [MCP Gateway](https://github.com/docker/mcp-gateway): + +```yaml +toolsets: + - type: mcp + ref: docker:duckduckgo # web search + - type: mcp + ref: docker:github-official # GitHub integration +``` + +Browse available tools at the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp). + +| Property | Type | Description | +| ------------- | ------ | ---------------------------------------------------------------- | +| `ref` | string | Docker MCP reference (`docker:name`) | +| `tools` | array | Optional: only expose these tools | +| `instruction` | string | Custom instructions injected into the agent's context | +| `config` | any | MCP server-specific configuration (passed during initialization) | +| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../overview/index.md#variable-expansion-in-config-fields)). | + +### Local MCP (stdio) + +Run MCP servers as local processes communicating over stdin/stdout: + +```yaml +toolsets: + - type: mcp + command: python + args: ["-m", "mcp_server"] + tools: ["search", "fetch"] + env: + API_KEY: value +``` + +| Property | Type | Description | +| --- | --- | --- | +| `command` | string | Command to execute the MCP server | +| `args` | array | Command arguments | +| `tools` | array | Optional: only expose these tools | +| `env` | object | Environment variables (key-value pairs) | +| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../overview/index.md#variable-expansion-in-config-fields)). | +| `instruction` | string | Custom instructions injected into the agent's context | +| `version` | string | Package reference for [auto-installing](#auto-installing-tools) the command binary | + +### Remote MCP (Streamable HTTP / SSE) + +Connect to MCP servers over the network: + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp-server.example.com" + transport_type: "streamable" + headers: + Authorization: "Bearer your-token" + # Optional: allow OAuth helper requests to reach private/internal IPs. + allow_private_ips: true + tools: ["search_web", "fetch_url"] +``` + +| Property | Type | Description | +| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| `remote.url` | string | URL of the MCP server. Accepts `https://`, `http://`, and `unix://` (Unix domain socket) schemes. | +| `remote.transport_type` | string | `streamable` or `sse` | +| `remote.headers` | object | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. `${env.VAR}` reads an environment variable; `${headers.NAME}` forwards a header from the caller's incoming request (useful when Docker Agent runs as an API server). | +| `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | + +## Auto-Installing Tools + +When configuring MCP or LSP tools that require a binary command, Docker Agent can **automatically download and install** the command if it's not already available on your system. This uses the [aqua registry](https://github.com/aquaproj/aqua-registry) — a curated index of CLI tool packages. + +### How It Works + +1. When a toolset with a `command` is loaded, Docker Agent checks if the command is available in your `PATH` +2. If not found, it checks the Docker Agent tools directory (`~/.cagent/tools/bin/`) +3. If still not found, it looks up the command in the aqua registry and installs it automatically + +### Explicit Package Reference + +Use the `version` property to specify exactly which package to install: + +```yaml +toolsets: + - type: mcp + command: gopls + version: "golang/tools@v0.21.0" + args: ["mcp"] + - type: lsp + command: rust-analyzer + version: "rust-lang/rust-analyzer@2024-01-01" + file_types: [".rs"] +``` + +The format is `owner/repo` or `owner/repo@version`. When a version is omitted, the latest release is used. + +### Automatic Detection + +If the `version` property is not set, Docker Agent tries to auto-detect the package from the command name by searching the aqua registry: + +```yaml +toolsets: + - type: mcp + command: gopls # auto-detected as golang/tools + args: ["mcp"] +``` + +### Checksum Verification + +Where the aqua registry includes a checksum manifest, downloaded binaries are verified against it before installation. Verification behaviour depends on the checksum type advertised: + +- **Strong checksums (sha256, sha512, etc.)** — verified before the binary is installed. If the downloaded archive does not match, the install is aborted and an error is returned (fails closed). +- **Unsupported or weak checksum types (e.g. md5, sha1)** — skipped with a warning; installation proceeds without verification. +- **No manifest** — if no checksum is advertised in the registry entry, the binary is installed without verification. + +### version_overrides Resolution + +The auto-installer correctly resolves **`version_overrides`** entries in the aqua registry. Many common tools (for example, `fzf`) keep their package configuration — including download URLs and checksums — under `version_overrides` rather than at the top level of their registry entry. These tools previously failed to install silently; they are now handled correctly. + +### Disabling Auto-Install + +**Per toolset** — set `version` to `"false"` or `"off"`: + +```yaml +toolsets: + - type: mcp + command: my-custom-server + version: "false" +``` + +**Globally** — set the `DOCKER_AGENT_AUTO_INSTALL` environment variable: + +```bash +export DOCKER_AGENT_AUTO_INSTALL=false +``` + +### Environment Variables + +| Variable | Default | Description | +| ---------------------------- | ------------------ | ------------------------------------------------ | +| `DOCKER_AGENT_AUTO_INSTALL` | (enabled) | Set to `false` to disable all auto-installation | +| `DOCKER_AGENT_TOOLS_DIR` | `~/.cagent/tools/` | Base directory for installed tools | +| `GITHUB_TOKEN` | — | GitHub token to raise API rate limits (optional) | + +Installed binaries are placed in `~/.cagent/tools/bin/` and cached so they are only downloaded once. + +> [!TIP] +> Auto-install supports both Go packages (via `go install`) and GitHub release binaries (via archive download). The aqua registry metadata determines which method is used. + +## Toolset Lifecycle + +Long-running toolsets — local MCP servers (stdio), remote MCP servers (Streamable HTTP / SSE), and LSP servers — are managed by a single supervisor that can auto-reconnect them when they crash, time out, or drop their session. The `lifecycle` block on the toolset lets you tune that supervisor per toolset. It applies to every `type: mcp` and `type: lsp` toolset. + +The simplest knob is `profile`, which picks a preset: + +| Profile | Auto-restart | Use case | +| --- | --- | --- | +| `resilient` | Yes | Default. Exponential backoff on disconnect; the agent keeps running if the toolset is unavailable. Matches the historical Docker Agent behaviour. | +| `strict` | No | Fail-fast. Marks the toolset as required. Intended for CI / headless runs where a missing dependency should be a hard error. | +| `best-effort` | No | Single attempt, no retries. Good for experimental MCPs whose flakiness should not amplify into a restart loop. | + +```yaml +toolsets: + - type: mcp + ref: docker:duckduckgo + lifecycle: + profile: resilient # default; shown here for clarity + + - type: lsp + command: gopls + file_types: [".go"] + lifecycle: + profile: strict + + - type: mcp + ref: docker:openbnb-airbnb + lifecycle: + profile: best-effort +``` + +### Tuning the defaults + +Any field set on `lifecycle` overrides the profile preset, so you can mix-and-match: pick a profile and only override the knobs you care about. + +```yaml +toolsets: + - type: mcp + command: ["docker", "mcp", "gateway"] + lifecycle: + profile: resilient + max_restarts: 10 # keep trying longer than the default of 5 + backoff: + initial: 500ms + max: 1m + multiplier: 2 + jitter: 0.2 # 20% random offset to avoid thundering-herd retries +``` + +| Property | Type | Description | +| --- | --- | --- | +| `profile` | string | One of `resilient` (default), `strict`, `best-effort`. Picks defaults for every other field. | +| `restart` | string | When the supervisor should reconnect after a disconnect: `never`, `on_failure` (default), or `always`. For **remote** MCP toolsets (Streamable HTTP / SSE), `on_failure` is automatically promoted to `always` so idle-timeout closes reconnect gracefully — `never` is still honored. | +| `max_restarts` | int | Maximum consecutive restart attempts before the toolset is marked `Failed`. `0` uses the profile default (5); `-1` means unlimited. | +| `backoff.initial` | duration | First wait between attempts (Go duration: `500ms`, `1s`, …). Default: `1s`. | +| `backoff.max` | duration | Cap on the wait between attempts. Default: `32s`. | +| `backoff.multiplier` | number | Multiplier applied each attempt. Default: `2`. | +| `backoff.jitter` | number | Fraction (0..1) of the computed delay applied as a uniform random offset. `0` disables jitter (default). | +| `required` | boolean | Marks the toolset as critical. Today this is informational; a future eager-startup phase will refuse to start the agent when a required toolset cannot reach Ready. Defaults to `true` under `strict`, `false` otherwise. | +| `startup_timeout` | duration | Cap on the initial connect+initialize duration. Enforced since v1.94.0: on expiry the toolset stays stopped and the runtime retries on the next turn. | +| `call_timeout` | duration | Cap on an individual tool call, including one reconnect-retry. Enforced: on expiry the call is cancelled and surfaced to the model as a tool error; cancellation is propagated to the server. `0`/unset means no timeout — opt-in only, no profile default. | + +> [!NOTE] +> **`required` is not yet enforced** +> +> The schema validates this field and the supervisor stores it, but no code path acts on it yet. It is documented now so config files written today keep working when the planned eager-startup phase lands. Picking the `strict` profile is forward-compatible — it will start enforcing `required=true` automatically. + +### Inspecting and restarting toolsets at runtime + +The TUI exposes the supervisor through two slash commands: + +- `/tools` — the unified tools dialog. Its top section lists every toolset on the current agent with its lifecycle state (`Stopped`, `Starting`, `Ready`, `Degraded`, `Restarting`, `Failed`), restart count, and last error; its bottom section lists every tool the agent can call, grouped by category. Use this to answer both "what can the agent do?" and "is anything degraded?" with one command. +- `/toolset-restart <name>` — force the supervisor to reconnect the named toolset. Useful after completing OAuth, when a remote MCP server has been redeployed, or when an LSP like `gopls` is stuck. + +See the [TUI reference](../../features/tui/index.md) for the full list of slash commands. + +See [`examples/lifecycle.yaml`](https://github.com/docker/docker-agent/blob/main/examples/lifecycle.yaml) for a complete lifecycle configuration example. + +## TOON-Encoded Tool Outputs + +Many MCP servers return verbose JSON responses that consume a lot of context budget. The `toon` field on a toolset transparently re-encodes matching tools' JSON output as [TOON](https://github.com/alpkeskin/gotoon) — a compact, model-friendly key/value format — before the result is shown to the model. + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + toon: ".*" # toonify every tool from this MCP server + - type: mcp + command: my-server + toon: "list_.*,get_.*" # only toonify list_/get_ tools +``` + +| Property | Type | Description | +| -------- | ------ | ----------- | +| `toon` | string | Comma-delimited list of regular expressions matching tool names whose JSON output should be re-encoded as TOON. Non-JSON outputs and non-matching tools are passed through untouched. | + +When a tool's output is not valid JSON, it is returned unchanged — TOON encoding is best-effort and never breaks tools that emit plain text. + +> [!NOTE] +> **When to use TOON** +> +> TOON typically yields 30-60% smaller payloads than equivalent JSON for MCP tools that return arrays of records (issue lists, search results, file listings, …). It works best when the schema is regular; one-off responses with deeply nested or heterogeneous shapes may benefit less. + +## Per-Toolset Model Routing + +The `model` field on a toolset overrides which LLM is invoked for the **next turn** after a tool from that toolset returns — letting you process simple tool results (file reads, knowledge-base lookups, shell stdout) with a cheaper or faster model while keeping the agent's primary model for reasoning. + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + fast: + provider: anthropic + model: claude-haiku-4-5 + +agents: + root: + model: primary + toolsets: + - type: filesystem + model: fast # process file reads with the fast model + - type: shell + model: fast # ditto for shell stdout + - type: mcp + ref: docker:github-official + model: openai/gpt-4o-mini # inline provider/model also works +``` + +| Property | Type | Description | +| -------- | ------ | ----------- | +| `model` | string | Model used for the LLM turn that processes tool results from this toolset. Either a name from the `models:` section or an inline `provider/model` (e.g. `openai/gpt-4o-mini`). The override is **one-shot**: subsequent turns return to the agent's primary model. | + +When multiple tool calls in a single turn come from toolsets with different `model` overrides, the runtime picks the override of the **first** tool call that has one set. See [`examples/per_tool_model_routing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/per_tool_model_routing.yaml) for a complete configuration. + +## Tool Filtering + +Toolsets may expose many tools. Use the `tools` property to whitelist only the ones your agent needs. This works for any toolset type — not just MCP: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + tools: ["list_issues", "create_issue", "get_pull_request"] + - type: filesystem + tools: ["read_file", "search_files_content"] + - type: shell + tools: ["shell"] +``` + +> [!TIP] +> Filtering tools improves agent performance — fewer tools means less confusion for the model about which tool to use. + +## Tool Instructions + +Add context-specific instructions that get injected when a toolset is loaded: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + instruction: | + Use these tools to manage GitHub issues. + Always check for existing issues before creating new ones. + Label new issues with 'triage' by default. +``` + +By default, the `instruction:` field **replaces** the toolset's built-in instructions (if any). To keep the built-in guidance and add your own rules on top, include the `{ORIGINAL_INSTRUCTIONS}` placeholder anywhere in your instruction text. At runtime it expands to the toolset's default instructions: + +```yaml +toolsets: + # Enrich: keep built-in instructions, then add your own rules + - type: filesystem + instruction: | + {ORIGINAL_INSTRUCTIONS} + + ## Project-specific rules + - Never modify files outside the `src/` directory. + - Always create a backup before overwriting a file. + + # Enrich: prepend your rules before the built-in instructions + - type: shell + instruction: | + Important: only run commands inside the project root. + {ORIGINAL_INSTRUCTIONS} + + # Replace: omit the placeholder to discard built-in instructions entirely + - type: mcp + ref: docker:github-official + instruction: | + Only read GitHub issues. Never create, edit, or close anything. +``` + +Three patterns at a glance: + +| Pattern | Description | +| --- | --- | +| `{ORIGINAL_INSTRUCTIONS}` then your text | Append your rules after the defaults | +| Your text then `{ORIGINAL_INSTRUCTIONS}` | Prepend your rules before the defaults | +| No placeholder | Replace the defaults entirely | + +See [`examples/toolset_instructions.yaml`](https://github.com/docker/docker-agent/blob/main/examples/toolset_instructions.yaml) for a complete example. + +## Deferred Tool Loading + +Load tools on-demand to speed up agent startup. When a toolset is deferred, its tools are registered lazily — the tool server process is not started until the agent first calls one of its tools. This is useful for large toolsets (e.g., an MCP server with hundreds of tools) where startup time matters. + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + defer: true + - type: mcp + ref: docker:slack + defer: true + - type: filesystem +``` + +Or defer specific tools within a toolset: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + defer: + - "list_issues" + - "search_repos" +``` + +When `defer` is a list of tool names, only those specific tools are deferred; all other tools in the toolset load eagerly. Setting `defer: true` defers the entire toolset. + +### Tool Discovery with `search_tool` + +When an entire toolset is deferred (`defer: true`), the deferred toolset exposes two built-in tools to the agent: + +- **`search_tool`** — Discover available deferred tools by keyword. The search uses **fuzzy matching** against both tool names and descriptions: all characters of the query must appear in the target string in order (but not necessarily adjacently), so a query like `"crfil"` matches `"create_file"`. Returns a list of matching tool names with descriptions. +- **`add_tool`** — Activate a discovered tool by name so it becomes available for use. + +These tools let the agent browse a large toolset on-demand without activating every tool upfront. + +See [`examples/deferred.yaml`](https://github.com/docker/docker-agent/blob/main/examples/deferred.yaml) for a complete example. + +## Combined Example + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Full-featured developer assistant + instruction: You are an expert developer. + toolsets: + # Built-in tools + - type: filesystem + - type: shell + - type: think + - type: todo + - type: memory + path: ./dev.db + - type: user_prompt + # LSP for code intelligence + - type: lsp + command: gopls + file_types: [".go"] + # Custom scripts + - type: script + shell: + run_tests: + description: Run the test suite + cmd: task test + lint: + description: Run the linter + cmd: task lint + # Custom API tool + - type: api + api_config: + name: get_status + method: GET + endpoint: "https://api.example.com/status" + instruction: Check service health + # Docker MCP tools + - type: mcp + ref: docker:github-official + tools: ["list_issues", "create_issue"] + - type: mcp + ref: docker:duckduckgo + # Remote MCP + - type: mcp + remote: + url: "https://internal-api.example.com/mcp" + transport_type: "streamable" + headers: + Authorization: "Bearer ${env.INTERNAL_TOKEN}" +``` + +> [!WARNING] +> **Toolset Order Matters** +> +> If multiple toolsets provide a tool with the same name, the first one wins. Order your toolsets intentionally. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md new file mode 100644 index 000000000000..92a050df6d03 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md @@ -0,0 +1,134 @@ +--- +title: "User Settings" +description: "Full reference for the global settings block in ~/.config/cagent/config.yaml: theme, layout, YOLO, sound, snapshots, permissions, hooks, keybindings, and how they interact with agent config and CLI flags." +keywords: docker agent, ai agents, configuration, yaml, user settings, user config +linkTitle: "User Settings" +weight: 110 +canonical: https://docs.docker.com/ai/docker-agent/configuration/user-settings/ +--- + +_Full reference for the global settings block in your user config file._ + +## Where Settings Live + +Docker Agent reads a single user-level config file, independent of any agent YAML: + +```text +~/.config/cagent/config.yaml +``` + +The `settings:` block inside it holds preferences that apply to every agent you run — appearance, behavior, notifications, and a few global safety defaults. Everything under `settings:` is optional; an unset field falls back to the documented default. + +```yaml +# ~/.config/cagent/config.yaml +settings: + theme: dracula + lean: false + sound: true +``` + +You rarely need to hand-edit this file. Most fields are managed from the TUI's `/settings` dialog (**Appearance**, **Behavior**, **Notifications** tabs) — press <kbd>Enter</kbd> there to apply and persist a change. A few fields (`permissions`, `hooks`, `keybindings`) have no dialog UI and are only set by editing the file directly. + +> [!NOTE] +> This page documents `settings:`. The user config file also has top-level sections outside `settings:` — `aliases:`, `providers:`, `board:`, `credential_helper:`, `sandbox_allowlist:` — which are not covered here. + +## Settings Reference + +| Setting | Type | Default | Description | +| --- | --- | --- | --- | +| `hide_tool_results` | boolean | `false` | Hide tool call results in the TUI by default. Mirrors the `--hide-tool-results` flag and the <kbd>Ctrl</kbd>+<kbd>O</kbd> toggle. | +| `expand_thinking` | boolean | `false` | Start new sessions with thinking/tool blocks expanded instead of collapsed. | +| `split_diff_view` | boolean | `true` | Render file-edit diffs side-by-side instead of unified. | +| `render_images` | boolean | `true` | Render images in the TUI using the Kitty graphics protocol. Applies to both tool-result images and Markdown images in agent responses. Automatically disabled when the terminal does not support Kitty. | +| `theme` | string | `default` | Theme name, loaded from a built-in theme or `~/.cagent/themes/<name>.yaml`. The special value `auto` follows the terminal's light/dark background. See [Theming](../../features/tui/index.md#theming). | +| `theme_dark` | string | `default` | Theme applied when `theme: auto` and the terminal background is dark. | +| `theme_light` | string | `default-light` | Theme applied when `theme: auto` and the terminal background is light. | +| `YOLO` | boolean | `false` | Auto-approve all tool calls globally, across every agent you run. Mirrors the `--yolo` flag and the `/yolo` command. Legacy alias for `safety: autonomous`; when both are set, `safety` wins. | +| `safety` | string | _unset_ | Default [safety mode](../permissions/index.md#safety-modes) for new sessions: `strict`, `balanced`, `restricted`, or `autonomous` (any other value fails config loading). Wins over the legacy `YOLO` flag. Applied when no explicit `--safety`/`--yolo` flag and no alias safety option was given; wins over the agent YAML's `agents.<name>.safety` / `runtime.safety` defaults. Never changes the mode of a resumed session. | +| `lean` | boolean | `false` | Make the [lean TUI](../../features/tui/index.md#lean-tui) (simplified, minimal-chrome interface) the default for interactive runs instead of the full TUI. | +| `tab_title_max_length` | int | `20` | Maximum display length for tab titles; longer titles are truncated with an ellipsis. | +| `restore_tabs` | boolean | `false` | Restore previously open tabs when launching the TUI. | +| `sound` | boolean | `false` | Play a notification sound on task success or failure. | +| `sound_threshold` | int | `10` | Minimum duration in seconds a task must run before a success sound plays (failures always play). | +| `snapshot` | boolean | `false` | Enable automatic shadow-git snapshots at turn boundaries globally. See [Snapshots](../../features/snapshots/index.md). | +| `cache_stable_prompts` | boolean | `false` | Keep changing trusted context (date, environment info, dynamic prompt files) out of the frozen system prefix and append chronological updates instead, improving prompt-cache hit rates on long sessions. | +| `warn_on_cache_miss` | boolean | `false` | Warn when a model call after the first one in a session reports no cached input tokens (a prompt-cache miss). Managed from the **Notifications** tab of `/settings`. | +| `busy_send_mode` | string | `steer` | What happens to a message sent while the agent is working: `steer` injects it into the ongoing stream; `queue` holds it until the current turn ends. | +| `interrupt_confirmation` | string | `always` | Controls how the <kbd>Esc</kbd> key interrupts a running stream: `always` (default) shows a confirmation dialog; `double-tap` requires pressing <kbd>Esc</kbd> twice within 1 second; `none` interrupts immediately without confirmation. Managed from the **Behavior** tab of `/settings`. | +| `permissions` | object | _unset_ | Global tool-permission rules (`allow` / `ask` / `deny`), merged with agent-level and session-level permissions. See [Permissions](../permissions/index.md#global-permissions). | +| `hooks` | object | _unset_ | Global lifecycle hooks applied to every agent, additive with agent-config and CLI hooks. See [Global (user-level) hooks](../hooks/index.md#global-user-level-hooks). | +| `keybindings` | array | _unset_ | Remap TUI keyboard shortcuts. See [Custom Keybindings](../../features/tui/index.md#custom-keybindings) for the full list of actions and syntax. | +| `layout` | object | _unset_ | Sidebar position and section visibility. See [Layout Settings](#layout-settings) below. | + +## Layout Settings + +`layout` customizes the TUI's sidebar. The zero value (an omitted `layout:` block, or any field left out) is the default: sidebar on the right, every section visible, normal spacing. + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `sidebar_position` | string | `right` | `right`, `left`, `top`, or `bottom`. Left/right keep a full vertical sidebar; top/bottom render a compact horizontal band. | +| `section_spacing` | string | `normal` | `compact`, `normal`, or `relaxed` — the number of blank lines between sidebar sections. | +| `hide_session_path` | boolean | `false` | Hide the working-directory (session path) line, including its git branch. | +| `hide_usage` | boolean | `false` | Hide the token-usage section. | +| `hide_agents` | boolean | `false` | Hide the Agents section. | +| `active_agents_only` | boolean | `false` | Show only agents active in the current session in the Agents section (and the top/bottom band), instead of the whole configured team. Ignored while the Agents section is hidden. | +| `hide_tools` | boolean | `false` | Hide the Tools section. | +| `hide_todos` | boolean | `false` | Hide the Todos section. | + +```yaml +settings: + layout: + sidebar_position: left + section_spacing: compact + hide_usage: true +``` + +## Complete Example + +```yaml +# ~/.config/cagent/config.yaml +settings: + theme: auto + theme_dark: dracula + theme_light: default-light + lean: false + expand_thinking: false + split_diff_view: true + render_images: true + hide_tool_results: false + sound: true + sound_threshold: 10 + snapshot: true + cache_stable_prompts: true + warn_on_cache_miss: true + busy_send_mode: queue + interrupt_confirmation: double-tap + restore_tabs: true + tab_title_max_length: 24 + layout: + sidebar_position: right + section_spacing: normal + permissions: + deny: + - "shell:cmd=sudo*" + allow: + - "read_*" + hooks: + session_start: + - type: command + command: "~/.config/cagent/hooks/session-start.sh" + keybindings: + - action: "commands" + keys: ["f2", "ctrl+k"] +``` + +## Precedence Rules + +User settings are a **low-priority** source: they establish defaults, and anything more specific wins. + +- **CLI flags over user settings — except plain boolean flags going from `true` to `false`.** Where a `docker agent run` flag mirrors a setting, passing the flag for a specific run takes precedence over the setting for that run only, and the flag never modifies the saved user config file. This holds cleanly for `--lean` / `lean`, `--theme` / `theme`, and the safety flags `--safety` / `--yolo` (see below), which track whether the flag was explicitly passed on the command line. `--hide-tool-results` / `hide_tool_results` doesn't: it's a plain boolean with no "was this explicitly set" tracking, so passing `--hide-tool-results=false` cannot turn a saved `hide_tool_results: true` setting off for that run — the saved `true` wins and is reapplied on top of the flag. Passing the flag to turn it *on* works as expected regardless of the saved setting. +- **Safety has its own, fully-specified chain.** For a **new** session the first source in this order wins: explicit `--safety` flag > explicit `--yolo` flag > alias `safety`/`yolo` option > `settings.safety`/`settings.YOLO` > the agent YAML's `agents.<name>.safety` > the agent YAML's `runtime.safety` > the built-in default (read-only tools auto-approve, everything else asks). At each scope the `safety` field wins over the legacy `YOLO`/`yolo` boolean. Your settings therefore beat anything an agent author declared in YAML — an agent config loaded from a file, URL, or OCI registry can never override your `settings.safety`, alias option, or CLI flag. An explicit `--yolo=false` suppresses a saved `YOLO: true` / alias `yolo` for that run (other settings and YAML defaults still apply). **Resumed sessions keep their stored mode**: settings and alias defaults never touch them; only an explicit `--safety` or `--yolo` flag overrides a resume. See [Safety Modes](../permissions/index.md#safety-modes). +- **Aliases sit between CLI flags and user settings.** An [alias](../../features/cli/index.md#docker-agent-alias) (`docker agent alias add ...`) can bundle its own `yolo`, `safety`, `model`, `hide_tool_results`, and `sandbox` defaults; those apply when the corresponding flag was not explicitly passed, the same way user settings do, but are resolved after user settings so an alias's own choices take priority over your global defaults. +- **Permissions are merged, not overridden.** Global `settings.permissions` and an agent's own `permissions:` are combined into a single set of `deny` → `allow` → `ask` patterns before evaluation — a global deny always blocks, regardless of what the agent config allows. See [Merging Behavior](../permissions/index.md#merging-behavior). +- **Hooks are additive, not overridden.** For a given lifecycle event, hooks from the agent config, `settings.hooks`, `hooks.d/` drop-ins, and `--hook-*` CLI flags **all** run, in that order. Global hooks cannot be suppressed by an individual agent. +- **Everything else is a plain default.** Fields with no CLI or agent-config equivalent (`sound`, `sound_threshold`, `restore_tabs`, `tab_title_max_length`, `split_diff_view`, `render_images`, `cache_stable_prompts`, `warn_on_cache_miss`, `busy_send_mode`, `keybindings`, `layout`) only ever come from `settings:` (or the `/settings` dialog that writes it) — there is nothing to override them per run. diff --git a/_vendor/github.com/docker/docker-agent/docs/demo.gif b/_vendor/github.com/docker/docker-agent/docs/demo.gif new file mode 100644 index 000000000000..03d4bfc0ec7a Binary files /dev/null and b/_vendor/github.com/docker/docker-agent/docs/demo.gif differ diff --git a/_vendor/github.com/docker/docker-agent/docs/features/_index.md b/_vendor/github.com/docker/docker-agent/docs/features/_index.md new file mode 100644 index 000000000000..70959847b98c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/_index.md @@ -0,0 +1,5 @@ +--- +title: "Features" +description: "Interfaces and features: TUI, CLI, API server, protocols, and more." +weight: 50 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md b/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md new file mode 100644 index 000000000000..a09f5b006536 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md @@ -0,0 +1,106 @@ +--- +title: "A2A Protocol" +description: "Expose Docker Agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks." +keywords: docker agent, ai agents, features, a2a protocol +weight: 60 +canonical: https://docs.docker.com/ai/docker-agent/features/a2a/ +aliases: + - /ai/docker-agent/integrations/a2a/ +--- + +_Expose Docker Agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks._ + +## Overview + +The `docker agent serve a2a` command starts an A2A server that exposes your agents using the [A2A protocol](https://a2a-protocol.org/latest/). This enables communication between Docker Agent and other agent frameworks that support A2A. + +> [!WARNING] +> **Early support** +> +> A2A support is functional but still evolving. Tool calls, artifacts, and memory features have limited A2A integration. See limitations below. + +## Usage + +```bash +# Start A2A server for an agent +$ docker agent serve a2a ./agent.yaml + +# Specify a custom address +$ docker agent serve a2a ./agent.yaml --listen 127.0.0.1:9000 + +# Use an agent from an OCI registry +$ docker agent serve a2a myorg/agent:tag +``` + +## Flags + +| Flag | Default | Description | +| --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | +| `-l, --listen <addr>` | `127.0.0.1:8082` | Address to listen on. | +| `-a, --agent <name>` | (first agent) | Name of the agent to expose when the config contains multiple agents. Defaults to the team's first agent. | +| `-s, --session-db <path>` | `<data-dir>/session.db` | Path to the SQLite session database. | +| `--working-dir <path>` | current dir | Working directory the agent runs in. | +| `--env-from-file <file>` | (none) | Load additional environment variables from a `.env` file (repeatable). | +| `--models-gateway <url>` | (none) | Route all provider traffic through a models gateway URL. | +| `--code-mode-tools` | `false` | Expose tools as a single "code" toolset that accepts a JavaScript snippet to run. | +| `--hook-pre-tool-use <cmd>` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks](../../configuration/hooks/index.md). | +| `--hook-post-tool-use <cmd>` | (none) | Add a post-tool-use hook (repeatable). | +| `--hook-session-start <cmd>` | (none) | Add a session-start hook (repeatable). | +| `--hook-session-end <cmd>` | (none) | Add a session-end hook (repeatable). | +| `--hook-on-user-input <cmd>` | (none) | Add an on-user-input hook (repeatable). | +| `--hook-stop <cmd>` | (none) | Add a stop hook, fired when the model finishes responding (repeatable). | +| `--auth-token <token>` | (none) | Bearer token required for agent-card and invocation requests. | +| `--cors-origin <origins>` | (none) | Allowed browser origins, comma-separated; empty disables CORS. | +| `--insecure-no-auth` | `false` | Allow an unauthenticated non-loopback listener (unsafe). | +| `--safety <policy>` | `restricted` | Tool safety policy; `autonomous` is permitted only through this explicit CLI flag. | + +## Authentication and network exposure + +Loopback listeners may run without authentication. Non-loopback listeners require +`--auth-token` unless `--insecure-no-auth` explicitly acknowledges the exposure. +Clients must send `Authorization: Bearer <token>` for both agent-card discovery +and JSON-RPC invocation. Configure browser access with `--cors-origin`; it accepts +comma-separated literal origins or `~`-prefixed regular expressions and permits +credentials only for matching origins. + +```bash +$ docker agent serve a2a ./agent.yaml --auth-token "$A2A_TOKEN" \ + --cors-origin http://localhost:3000 +``` + +## Tool safety and migration + +A2A sessions default to the `restricted` tool safety policy. Precedence is the +`--safety` flag, then agent YAML, then runtime YAML. YAML may select `strict`, +`balanced`, or `restricted`; `safety: autonomous` stops startup and directs the +operator to `--safety autonomous`. That CLI flag is the only deliberate opt-in +to autonomous tool execution. + +Existing deployments should choose an explicit policy before upgrading. Migration +027 labels pre-existing sessions as `run`, so they cannot be resumed through +`/invoke`; clients must start new A2A contexts. An A2A context ID that collides +with another session is rejected without changing that session. + +Downgrading to a binary that predates migration 027 fails because the session +database has a newer schema (`ErrNewerDatabase`). Restore an older database, or +use a binary that includes the migration. Revert changes without removing the +migration catalogue entry. + +## Features + +- **Auto port selection** — Picks an available port if not specified +- **Agent card** — Provides standard A2A agent metadata +- **Full Docker Agent features** — Supports all tools, models, and gateway features +- **Multiple sources** — Load agents from files or OCI registries + +> [!TIP] +> **See also** +> +> For exposing agents via MCP instead, see [MCP Mode](../mcp-mode/index.md). For stdio-based integration, see [ACP](../acp/index.md). For the HTTP API, see [API Server](../api-server/index.md). + +## Current Limitations + +- Tool calls are handled internally, not exposed as separate A2A events +- A2A artifact support not yet integrated +- A2A memory features not yet integrated +- Multi-agent (sub-agent) scenarios need further work diff --git a/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md new file mode 100644 index 000000000000..52b6dff515ef --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md @@ -0,0 +1,117 @@ +--- +title: "ACP (Agent Client Protocol)" +description: "Expose Docker Agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools." +keywords: docker agent, ai agents, features, acp (agent client protocol) +linkTitle: "ACP" +weight: 70 +canonical: https://docs.docker.com/ai/docker-agent/features/acp/ +aliases: + - /ai/docker-agent/integrations/acp/ +--- + +_Expose Docker Agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools._ + +## Overview + +The `docker agent serve acp` command starts an ACP server that communicates over **stdio** (standard input/output). This makes it ideal for integration with editors, IDEs, and other tools that spawn agent processes — the host sends JSON-RPC messages to Docker Agent's stdin and reads responses from stdout. + +ACP is built on the [ACP Go SDK](https://github.com/coder/acp-go-sdk) and provides a standardized way for client applications to interact with AI agents. + +> [!NOTE] +> **ACP vs A2A vs MCP** +> +> **ACP** connects an agent to a *host application* (IDE, CLI tool) via stdio. **A2A** connects *agents to other agents* over HTTP. **MCP** exposes agents as *tools* for other MCP clients. Choose based on your integration target. + +## Usage + +```bash +# Start ACP server on stdio +$ docker agent serve acp ./agent.yaml + +# With a multi-agent team config +$ docker agent serve acp ./team.yaml + +# From an OCI registry +$ docker agent serve acp myorg/agent:tag + +# With a custom session database +$ docker agent serve acp ./agent.yaml --session-db ./my-sessions.db +``` + +## How It Works + +1. The host application spawns `docker agent serve acp agent.yaml` as a child process +2. Communication happens over **stdin/stdout** using the ACP protocol +3. The host sends user messages, Docker Agent processes them through the agent +4. Agent responses, tool calls, and events stream back to the host +5. Sessions are persisted in a SQLite database for continuity + +```bash +# Conceptual flow: +Host Application + └── spawns: docker agent serve acp agent.yaml + ├── stdin ← JSON-RPC requests from host + └── stdout → JSON-RPC responses to host +``` + +## Features + +- **Stdio transport** — No network ports needed; ideal for subprocess integration +- **Session persistence** — SQLite-backed sessions survive process restarts +- **Full agent support** — All Docker Agent features work: tools, multi-agent, model fallbacks +- **Multi-agent configs** — Team configurations with sub-agents work transparently +- **Filesystem operations** — Agents can read/write files relative to the host's working directory + +## CLI Flags + +```bash +docker agent serve acp <agent-file>|<registry-ref> [flags] +``` + +| Flag | Default | Description | +| --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `-s, --session-db <path>` | `<data-dir>/session.db` | Path to the SQLite session database. | +| `--working-dir <path>` | current dir | Working directory the agent runs in. | +| `--env-from-file <file>` | (none) | Load additional environment variables from a `.env` file (repeatable). | +| `--models-gateway <url>` | (none) | Route all provider traffic through a models gateway URL. | +| `--code-mode-tools` | `false` | Expose tools as a single "code" toolset that accepts a JavaScript snippet to run. | +| `--hook-pre-tool-use <cmd>` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks](../../configuration/hooks/index.md). | +| `--hook-post-tool-use <cmd>` | (none) | Add a post-tool-use hook (repeatable). | +| `--hook-session-start <cmd>` | (none) | Add a session-start hook (repeatable). | +| `--hook-session-end <cmd>` | (none) | Add a session-end hook (repeatable). | +| `--hook-on-user-input <cmd>` | (none) | Add an on-user-input hook (repeatable). | +| `--hook-stop <cmd>` | (none) | Add a stop hook, fired when the model finishes responding (repeatable). | + +## Integration Example + +A host application would spawn Docker Agent as a subprocess and communicate via the ACP protocol: + +```javascript +// Pseudocode for an IDE extension +const child = spawn("docker", ["agent", "serve", "acp", "./agent.yaml"]); + +// Send a message to the agent +child.stdin.write( + JSON.stringify({ + jsonrpc: "2.0", + method: "agent/run", + params: { message: "Explain this code" }, + }), +); + +// Read responses +child.stdout.on("data", (data) => { + const response = JSON.parse(data); + // Handle agent response, tool calls, etc. +}); +``` + +> [!TIP] +> **When to use ACP** +> +> Use ACP when building **IDE integrations**, **editor plugins**, or any tool that wants to embed a Docker Agent agent as a subprocess. For HTTP-based integrations, use the [API Server](../api-server/index.md) instead. + +> [!NOTE] +> **See also** +> +> For HTTP-based agent access, see the [API Server](../api-server/index.md). For agent-to-agent communication, see [A2A Protocol](../a2a/index.md). For exposing agents as MCP tools, see [MCP Mode](../mcp-mode/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md new file mode 100644 index 000000000000..2c1bc999702c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md @@ -0,0 +1,394 @@ +--- +title: "API Server" +description: "Expose your agents via an HTTP API for programmatic access, web frontends, and integrations." +keywords: docker agent, ai agents, features, api server +weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/features/api-server/ +--- + +_Expose your agents via an HTTP API for programmatic access, web frontends, and integrations._ + +## Overview + +The `docker agent serve api` command starts an HTTP server that exposes your agents through a REST-style API with Server-Sent Events (SSE) streaming. Use it to build web UIs, integrate with CI/CD pipelines, or connect agents to other services. + +```bash +# Start the API server +$ docker agent serve api agent.yaml + +# Custom listen address +$ docker agent serve api agent.yaml --listen 0.0.0.0:8080 + +# With session persistence +$ docker agent serve api agent.yaml --session-db ./sessions.db + +# Auto-refresh from OCI registry every 10 minutes +$ docker agent serve api myorg/coder --pull-interval 10 +``` + +> [!TIP] +> **When to use API server vs. chat server** +> +> Use the **API server** when you want full control over sessions, agent execution, tool-call confirmations, and streamed runtime events — this is Docker Agent's native protocol. Use the [Chat Server](../chat-server/index.md) when you want to plug Docker Agent into existing OpenAI-compatible tooling (chat UIs, IDE integrations, OpenAI SDK clients) instead. + +## Endpoints + +All endpoints are under the `/api` prefix. + +### Agents + +| Method | Path | Description | +| ------ | ----------------- | --------------------------------- | +| `GET` | `/api/agents` | List all available agents | +| `GET` | `/api/agents/:id` | Get an agent's full configuration | + +Each agent entry in the `GET /api/agents` response contains: + +| Field | Type | Description | +| ------------ | --------------- | --------------------------------------------------------------------------------------------- | +| `name` | string | Agent identifier (config filename without `.yaml`). | +| `description`| string | The root agent's `description` field. | +| `multi` | boolean | `true` when the config defines more than one agent. | +| `commands` | array of string | Sorted list of named command keys defined on the root agent. Omitted when no commands exist. | + +### Sessions + +| Method | Path | Description | +| -------- | ----------------------------------- | ------------------------------------------------------- | +| `GET` | `/api/sessions` | List all sessions | +| `POST` | `/api/sessions` | Create a new session. Accepts an optional `title` field — when set, it is stored and LLM title generation is skipped. | +| `GET` | `/api/sessions/:id` | Get a session by ID (messages, tokens, permissions) | +| `GET` | `/api/sessions/:id/status` | Lightweight runtime state (streaming, title, agent, tokens). Requires an attached runtime. | +| `GET` | `/api/sessions/:id/snapshot` | Full state in one call (stored fields + runtime state + `last_event_seq`) for gapless resync — see [Reconnecting without gaps](#reconnecting-without-gaps). | +| `GET` | `/api/sessions/:id/events` | Live session event stream (SSE) with sequence numbers and replay. Available for a run attached via [`--listen`](#listen), or once a session has raised at least one out-of-band event (e.g. a background job's elicitation, answered via `POST .../elicitation`), which creates a session-scoped event log on demand carrying such out-of-band events — see [Session event stream](#session-event-stream-and-reconnection) for what each kind of log contains. | +| `DELETE` | `/api/sessions/:id` | Delete a session | +| `PATCH` | `/api/sessions/:id/title` | Update session title | +| `PATCH` | `/api/sessions/:id/permissions` | Update session permissions | +| `POST` | `/api/sessions/:id/fork` | Fork a session at a user message — creates a new session with messages `[0, message_index)` of the parent (see [Session Forking](#session-forking)) | +| `POST` | `/api/sessions/:id/messages` | Append a message directly to a session's history (bypasses the model). Returns `409 Conflict` while the session has an active run (see [Agent Execution](#agent-execution)). | +| `PATCH` | `/api/sessions/:id/messages/:msg_id` | Update an existing message by ID. Returns `409 Conflict` while the session has an active run. | +| `POST` | `/api/sessions/:id/resume` | Resume a paused session (after tool confirmation) | +| `POST` | `/api/sessions/:id/tools/toggle` | Toggle auto-approve (YOLO) mode | +| `POST` | `/api/sessions/:id/elicitation` | Respond to an MCP tool elicitation request. Pass the `elicitation_id` from the `elicitation_request` event to target a specific concurrent request; omitted, it resolves the sole pending one. | +| `POST` | `/api/sessions/:id/steer` | Inject messages into a running turn (pre-empts current) | +| `POST` | `/api/sessions/:id/followup` | Enqueue messages to run after the current turn finishes (supports an `Idempotency-Key` — see [Idempotent follow-ups](#idempotent-follow-ups)). | +| `GET` | `/api/sessions/:id/models` | List available models for the session's current agent | + +### Agent Execution + +| Method | Path | Description | +| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------ | +| `POST` | `/api/sessions/:id/agent/:agent` | Run the root agent for a session (SSE stream) | +| `POST` | `/api/sessions/:id/agent/:agent/:name` | Run a specific named agent (SSE stream) | +| `GET` | `/api/agents/:id/:agent_name/tools/count` | Count tools currently available to `:agent_name` (accounts for deferred toolsets). | + +**Path parameters:** + +- **`:agent`** — The agent identifier, which is the **config filename without the `.yaml` extension**. This must match the filename passed to `docker agent serve api`. For example, if you start the server with `docker agent serve api my-assistant.yaml`, the agent identifier is `my-assistant`. When serving a directory of YAML files, each file becomes a separate agent identified by its filename without the extension. +- **`:name`** _(optional)_ — The name of a specific sub-agent defined in a multi-agent configuration. If omitted, the request targets the `root` agent. For example, in a config that defines agents named `root`, `coder`, and `reviewer`, use `/api/sessions/:id/agent/my-config/coder` to run the `coder` sub-agent directly. + +**Examples:** + +```bash +# Single-agent config: my-assistant.yaml +# Start: docker agent serve api my-assistant.yaml +# Run the root agent: +curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-assistant \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role": "user", "content": "Hello!"}]}' + +# Multi-agent config: team.yaml (defines agents: root, coder, reviewer) +# Start: docker agent serve api team.yaml +# Run the root agent: +curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/team \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role": "user", "content": "Review this PR"}]}' + +# Run a specific sub-agent (reviewer): +curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/team/reviewer \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role": "user", "content": "Review this PR"}]}' +``` + +### Health + +| Method | Path | Description | +| ------ | ----------- | ----------------------------------------- | +| `GET` | `/api/ping` | Health check — returns `{"status": "ok"}` | + +### OAuth + +| Method | Path | Description | +| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/api/mcp-oauth/callback` | Deliver an OAuth deeplink callback to a pending unmanaged OAuth flow. Success path: `?state=<state>&code=<code>`; authorization-server error path: `?state=<state>&error=<error>&error_description=<desc>`. Returns 400 if `state` is missing or neither `code` nor `error` is provided; 404 if no flow is awaiting that `state`. See [Remote MCP OAuth](../remote-mcp/index.md) for details. | + +## Streaming Responses + +The agent execution endpoints (`POST /api/sessions/:id/agent/:agent`) return **Server-Sent Events (SSE)**. The request body is a JSON object with a `messages` array and an optional `model` field. Setting `model` applies a persistent per-agent override on the session before the turn starts (subsequent turns reuse it). An empty or omitted `model` leaves the existing override untouched. (Each event is a JSON object representing a runtime event — remember that `:agent` is the config filename without the `.yaml` extension.): + +```bash +# Send a message and stream the response +# (assuming the server was started with: docker agent serve api my-agent.yaml) +$ curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-agent \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role": "user", "content": "Hello!"}]}' + +# Same call, but switch the agent's model for this turn (and persist it): +$ curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-agent \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role":"user","content":"Hello!"}],"model":"openai/gpt-4o"}' + +# Response (SSE stream): +data: {"type":"stream_started","session_id":"...","agent":"root"} +data: {"type":"agent_choice","content":"Hello! How","agent":"root"} +data: {"type":"agent_choice","content":" can I help","agent":"root"} +data: {"type":"agent_choice","content":" you today?","agent":"root"} +data: {"type":"stream_stopped","session_id":"...","agent":"root"} +``` + +Event types include: + +- `stream_started` / `stream_stopped` — Agent execution lifecycle +- `agent_choice` — Streamed text content (partial responses) +- `tool_call` — Agent requesting tool execution +- `tool_call_confirmation` — Tool call waiting for user approval +- `tool_call_response` — Tool execution result +- `plan_changed` — A shared plan was created, updated, or deleted through the plan toolset. The payload carries the plan's `scope`, `name`, `action`, and `version` — never its content. Shared plans are deliberately process-global: every active stream served by the same process subscribes to the same shared plan notifier and receives the event regardless of which session performed the mutation, and the payload does not identify the mutating session (read the plan's `author` metadata for collaborative attribution). +- `error` — Error during execution + +## Typical Workflow + +1. **List agents** — `GET /api/agents` to discover available agents +2. **Create session** — `POST /api/sessions` to start a conversation +3. **Send message** — `POST /api/sessions/:id/agent/:agent` with user messages +4. **Stream response** — Read SSE events as the agent processes +5. **Handle confirmations** — If a tool call needs approval, `POST /api/sessions/:id/resume` +6. **Continue** — Send follow-up messages to the same session + +```bash +# 1. List available agents +$ curl http://localhost:8080/api/agents +[{"name":"my-agent","multi":false,"description":"A helpful assistant","commands":["deploy","review"]}] + +# 2. Create a session +$ curl -X POST http://localhost:8080/api/sessions \ + -H "Content-Type: application/json" -d '{}' +{"id":"abc-123","title":"","created_at":"..."} + +# Create a session with a pre-supplied title (skips LLM title generation) +$ curl -X POST http://localhost:8080/api/sessions \ + -H "Content-Type: application/json" -d '{"title":"deploy check"}' +{"id":"def-456","title":"deploy check","created_at":"..."} +# title preserved; LLM title generation skipped + +# 3. Run the agent with a message +$ curl -N -X POST http://localhost:8080/api/sessions/abc-123/agent/my-agent \ + -H "Content-Type: application/json" \ + -d '{"messages":[{"role":"user","content":"What files are in the current directory?"}]}' +``` + +## CLI Flags + +```bash +docker agent serve api <agent-file>|<agents-dir> [flags] +``` + +| Flag | Default | Description | +| ------------------ | ---------------- | ------------------------------------------------ | +| `-l, --listen` | `127.0.0.1:8080` | Address to listen on | +| `--auth-token` | (none) | Bearer token required for all API requests. Leave empty to disable authentication (safe when listening on loopback interfaces only). Recommended when `--listen` binds to a network-reachable interface. | +| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size in bytes. Requests whose body exceeds this limit are rejected with HTTP 413 (Request Entity Too Large) — see [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large) if you hit this. | +| `--session-workingdir-root` | (none — unrestricted) | Confine the `working_dir` accepted by `POST /api/sessions` to this directory: after resolving symlinks, the requested directory must be the root or one of its descendants. By default any clean host directory is accepted — the intended behaviour for local single-user daemons that open arbitrary workspaces — but raw values containing `..` are always rejected. Set a root whenever the API serves callers that must not reach arbitrary host paths (multi-user or network-exposed deployments). | +| `-s, --session-db` | `session.db` | Path to the SQLite session database | +| `--pull-interval` | `0` (disabled) | Auto-pull OCI reference every N minutes | +| `--fake` | (none) | Replay AI responses from cassette file (testing) | +| `--record` | (none) | Record AI API interactions to cassette file. Routes through `--models-gateway` when one is configured. | +| `--mcp-oauth-redirect-uri` | (none) | Public HTTPS URL advertised as the OAuth `redirect_uri` for unmanaged MCP OAuth flows. When set, Docker Agent drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | + +> [!NOTE] +> **What `--max-request-size` does and doesn't cover** +> +> This is a finite, process-wide cap on one serialized inbound HTTP request body — it isn't a model context-window limit, and raising it doesn't increase what a provider/model accepts or how large a local attachment/prompt file can be. A larger cap also means the server buffers more memory per request from an unauthenticated or malicious client, so weigh that against your deployment's exposure. If a reverse proxy or gateway sits in front of this server, it may enforce its own, lower cap regardless of this flag. See [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large) for full diagnosis. + +> [!TIP] +> **Live profiling (advanced)** +> +> For production diagnostics, set the `CAGENT_PPROF_ADDR` environment variable (or the hidden `--pprof-addr` flag) to a TCP address such as `127.0.0.1:6060`. Docker Agent will start a Go pprof HTTP server at `/debug/pprof/`, which you can query with `go tool pprof`. Use a loopback address — a non-loopback binding logs a security warning. This flag is intentionally hidden from `--help`. + +> [!TIP] +> **Multi-agent configs** +> +> You can point `docker agent serve api` at a directory containing multiple agent YAML files. Each becomes a separate agent accessible via `/api/agents`. Combine with `--pull-interval` to auto-refresh agents from an OCI registry. + +## Session Persistence + +Sessions are stored in a SQLite database (default: `session.db` in the current directory). This means: + +- Sessions survive server restarts +- Multiple server instances can share a database +- Use `--session-db` to specify a custom path + +## Tool Call Approval + +By default, tool calls require approval. In the API workflow: + +1. Agent makes a tool call → server emits a `tool_call_confirmation` event +2. Client reviews and sends `POST /api/sessions/:id/resume` with the decision +3. Execution continues based on approval/denial + +Toggle auto-approve with `POST /api/sessions/:id/tools/toggle` for automated workflows. + +## Driving a running TUI with `--listen` {#listen} + +The same session API can be exposed by an **interactive run** so an external +process can drive it — send follow-up prompts, observe progress, read the +title — without scraping the terminal. Start a normal run and add `--listen`: + +```bash +# Expose this run's control plane on a TCP port... +$ docker agent run agent.yaml --listen 127.0.0.1:8080 + +# ...or on a unix socket (no port to allocate; access is gated by file +# permissions). npipe:// (Windows) and fd:// are also accepted. +$ docker agent run agent.yaml --listen unix:///tmp/my-run.sock +``` + +The run keeps its interactive TUI; the control plane runs alongside it. A +follow-up delivered over HTTP is processed exactly as if it had been typed +into the TUI: it starts a turn even when the agent is idle, generates the +session title on the first turn, and streams the resulting events to both the +terminal and every connected API client. + +```bash +# Send a follow-up to the attached run (SID is the --session id): +$ curl -X POST http://127.0.0.1:8080/api/sessions/$SID/followup \ + -H 'Content-Type: application/json' \ + -d '{"messages":[{"content":"Now add tests"}]}' +``` + +> [!NOTE] +> **Discovering a run** +> +> Each run started with `--listen` writes a discovery record to `<data-dir>/runs/<pid>.json` containing its address and session id, so a supervising process can find a live run by session id, pid, or address. + +> [!WARNING] +> **This control plane has a fixed 1 MiB request-body cap and no built-in authentication** +> +> Unlike the standalone `docker agent serve api` process above, an attached run's `--listen` control plane exposes neither `--max-request-size` nor `--auth-token`: every request is capped at a fixed, non-configurable 1 MiB body (returning HTTP 413 above it — see [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large)), and there is no bearer token to require. If you need a configurable cap, built-in bearer auth, or a network-reachable listener, run a standalone `docker agent serve api` deployment instead. Otherwise, keep `--listen` on loopback, a unix socket, or behind an authenticating reverse proxy. + +## Session event stream and reconnection + +`GET /api/sessions/:id/events` is a **Server-Sent Events** stream of the +session's runtime events — `stream_started`, `agent_choice`, `tool_call`, +`session_title`, `token_usage`, `stream_stopped`, and so on. Unlike the +per-request stream returned by the agent-execution endpoint, it is +session-scoped and survives across turns, so a client can watch a session for +its whole lifetime. It is available for a run attached via +[`--listen`](#listen), and — since a session-scoped event log is created on +demand the first time a session raises an out-of-band event, such as an +`elicitation_request` from a background job — for any API-created session +that has produced at least one (see the +[Sessions endpoint table](#sessions) above). The two kinds of log differ in +coverage: a `--listen` run feeds its full runtime event stream into the log, +while an on-demand log for an API-created session carries the session's +out-of-band events — not necessarily all ordinary turn events, which flow on +the per-request SSE stream of the [agent-execution](#agent-execution) +request that runs the turn. + +Each event carries a monotonic **sequence number** in the SSE `id:` field, and +the server buffers recent events. This makes the stream resumable: + +- **Resume after a drop** — reconnect with the standard `Last-Event-ID` header + (sent automatically by browser `EventSource` clients) or a `?since=<seq>` + query parameter. Buffered events newer than that point are replayed before + live tailing resumes, so nothing is missed. +- **Gap signal** — if the resume point has already fallen out of the buffer, the + server sends a single `{"type":"gap"}` event (with no id) before the replay. + The client should re-fetch the snapshot to resync, then continue tailing. +- **End of session** — when the session is ended server-side (for example via + `DELETE /api/sessions/:id`) the server sends a terminal + `{"type":"session_exited"}` event and closes the stream; a client that + receives it should stop. A stream that closes **without** `session_exited` is + a dropped connection — including the run process itself exiting — so reconnect + with the last id; if the run is gone the reconnection simply fails. + +### Reconnecting without gaps + +`GET /api/sessions/:id/snapshot` returns the session's full state in one +response — stored fields (messages, tokens, permissions), live runtime state +(`streaming`, current `agent`), and `last_event_seq`: the sequence number of +the most recent event. Pair it with the event stream for an exact, gapless +resync: + +```bash +# 1. Read the full state and the stream position it corresponds to. +$ SEQ=$(curl -s http://127.0.0.1:8080/api/sessions/$SID/snapshot | jq .last_event_seq) + +# 2. Tail everything that happens after that point (replaying anything that +# occurred between the two calls). +$ curl -N "http://127.0.0.1:8080/api/sessions/$SID/events?since=$SEQ" +``` + +This snapshot-then-tail pattern lets a client (or a client that just +restarted) rebuild a session's state and keep it correct without polling. + +### Waiting for readiness + +`GET /api/sessions/:id/status` reports a session's runtime state. Add +`?wait=<duration>` (e.g. `?wait=10s`) to block until that specific session's +runtime is attached and ready to accept follow-ups, then return its status, or +`503` on timeout. This is session-scoped, unlike `GET /api/ready`, which fires +as soon as any session is ready. + +## Session Forking + +`POST /api/sessions/:id/fork` creates a new session whose history is a copy of the parent up to (but **excluding**) a specified user message. This lets a client "branch" a conversation — e.g. rewind to an earlier question and try a different prompt — without losing the shared history that came before. + +**Request body:** + +```json +{ "user_message_index": 1 } +``` + +`user_message_index` is a **0-based ordinal** that counts only user-role messages in the parent's flat, user-visible message list. The targeted user message is **excluded** from the fork so clients can prefill it into their chat input for the user to edit and resubmit. + +**Example:** + +```bash +# Fork a session before the second user message (ordinal 1) +$ curl -X POST http://localhost:8080/api/sessions/$SID/fork \ + -H 'Content-Type: application/json' \ + -d '{"user_message_index": 1}' +# Returns: api.SessionResponse for the new forked session +# New session title: "<parent title> (fork 1)", "(fork 2)", etc. +``` + +**Validation:** + +- Out-of-range ordinals (negative, or at/past the user-message count) return `400 Bad Request`. +- An ordinal that resolves to a user message inside a sub-session returns `400 Bad Request`. A sub-session is a nested session created when a multi-agent config delegates work to a child agent; its messages are embedded within the parent session's message list and cannot be used as a fork boundary. + +## Idempotent follow-ups + +`POST /api/sessions/:id/followup` accepts an optional `Idempotency-Key` +header, making the request safe to retry after a network timeout. A repeat +with a key already seen for the session is acknowledged without delivering the +follow-up again: + +```bash +$ curl -X POST http://127.0.0.1:8080/api/sessions/$SID/followup \ + -H 'Content-Type: application/json' \ + -H 'Idempotency-Key: 7f3a-...' \ + -d '{"messages":[{"content":"Ship it"}]}' +# => {"status":"queued_streaming","duplicate":false} +# A retry with the same key => {"status":"duplicate","duplicate":true} +``` + +The response `status` is `queued_streaming` (a turn is running or starting), +`queued_idle` (delivered to an idle headless session, runs on the next turn), +or `duplicate`. + +> [!NOTE] +> **See also** +> +> For interactive use, see the [Terminal UI](../tui/index.md). For agent-to-agent communication, see [A2A Protocol](../a2a/index.md) and [ACP](../acp/index.md). For MCP integration, see [MCP Mode](../mcp-mode/index.md). For an OpenAI-compatible chat-completions API, see the [Chat Server](../chat-server/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/features/board/index.md b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md new file mode 100644 index 000000000000..176966a7e59c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md @@ -0,0 +1,97 @@ +--- +title: "Kanban Board" +description: "Orchestrate multiple agents from a Kanban TUI: each card runs an agent in a tmux session on an isolated git worktree." +keywords: docker agent, ai agents, features, board, kanban, orchestration +linkTitle: "Kanban Board" +weight: 15 +canonical: https://docs.docker.com/ai/docker-agent/features/board/ +--- + +_Board is a Kanban TUI for orchestrating agents. Each card launches an agent +in a tmux session on an isolated git worktree, and moving a card forward +through the pipeline sends the destination column's prompt to its agent._ + +## Launching the board + +```bash +$ docker agent board +``` + +Requirements: `tmux` and `git` must be installed. + +## How it works + +- **Cards run agents.** Creating a card (`n`) launches `docker agent run` in + a dedicated tmux session, working in a fresh git worktree branched from the + project's upstream default branch. The card's title, running/idle status, + and failures are mirrored live from the agent's control plane. +- **Startup phases.** While an agent is coming up its card moves through three + intermediate statuses before reaching **running**: `starting` (tmux session + created, process booting, no worktree yet) → `loading` (worktree present; + agent loading config, models, and tools) → `attaching` (control-plane socket + bound; board waiting for the first snapshot). +- **Columns are a pipeline.** The default pipeline is + Dev → Review → Push → Done, and it's fully customizable: manage columns + from the board (`c`) or in the config file. Moving a card forward (`]`) + sends the destination column's prompt to the card's agent; moving it back + (`[`) sends nothing. +- **Attach anytime.** Press `enter` (or double-click a card) to attach your + terminal to the agent's session and interact with it directly; `ctrl+q` + detaches and returns to the board. +- **Everything is recoverable.** Quitting the board leaves agents running in + tmux; restarting it reattaches to them. If an agent process dies, the board + relaunches it and resumes the same conversation and worktree. An agent that + keeps crashing at startup turns its card red instead of relaunching + forever: attach to it (`enter`) to read the error output, then move the + card forward to relaunch it, or delete it. + +## Key bindings + +| Key | Action | +| ------------- | --------------------------------------------------- | +| `n` | Create a card (project + prompt) | +| `enter` | Attach to the card's agent (`ctrl+q` detaches) | +| `d` | View the card's worktree diff | +| `o` | Open the card's worktree in `$DOCKER_AGENT_BOARD_EDITOR` (`code`) | +| `s` | Open an interactive shell in the card's worktree | +| `[` / `]` | Move the card back / forward | +| `1`-`9` | Move the card to column N | +| `x` | Delete the card, its session, worktree, and branch | +| `p` | Manage projects (add, edit, reorder, remove) | +| `c` | Manage columns (add, edit, reorder, remove) | +| `e` | Edit the selected column's prompt | +| `←↓↑→` `hjkl` | Navigate | +| mouse | Click selects, double-click attaches, drag moves, wheel scrolls | +| `?` | Help | +| `q` | Quit (agents keep running) | + +## Configuration + +Everything is configured in the global config file +(`~/.config/cagent/config.yaml`) or through the TUI itself (`p` for projects, +`c` for columns, `e` for column prompts): + +```yaml +board: + projects: + - name: my-app + path: /Users/me/src/my-app + agent: coder # any agent ref; defaults to the built-in agent + columns: + - id: dev + name: Dev + emoji: 🔨 + - id: review + name: Review + emoji: 🔍 + prompt: Review the local changes and fix any issues you find. + - id: done + name: Done + emoji: ✅ +``` + +Omitting `columns` keeps the default pipeline. Column `id`s identify a +column across renames (cards remember the column they are in by id); when +omitted, the id is derived from the column's name. When a card enters a +column with a `prompt`, that prompt is delivered to the card's agent as its +next message. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md b/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md new file mode 100644 index 000000000000..6b9957568064 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md @@ -0,0 +1,255 @@ +--- +title: "Chat Server" +description: "Expose your agents through an OpenAI-compatible Chat Completions API so any tool that already speaks OpenAI can drive a Docker Agent agent." +keywords: docker agent, ai agents, features, chat server +weight: 90 +canonical: https://docs.docker.com/ai/docker-agent/features/chat-server/ +--- + +_Expose your agents through an OpenAI-compatible Chat Completions API so any tool that already speaks OpenAI can drive a Docker Agent agent._ + +## Overview + +The `docker agent serve chat` command starts an HTTP server that exposes one or +more agents through an **OpenAI-compatible Chat Completions API** at +`/v1/chat/completions` and `/v1/models`. Any client that already speaks the +OpenAI protocol — for example +[Open WebUI](https://github.com/open-webui/open-webui), `curl`, the OpenAI +Python SDK, or LangChain — can drive a Docker Agent agent without any custom +integration. + +```bash +# Single agent — exposed as the model `root` +$ docker agent serve chat agent.yaml + +# Multi-agent config — every agent in the team becomes a model +$ docker agent serve chat ./team.yaml + +# Pick a specific agent from a multi-agent config +$ docker agent serve chat ./team.yaml --agent reviewer + +# Run an agent straight from the registry +$ docker agent serve chat myorg/agent:tag --listen 127.0.0.1:9090 + +# Require a Bearer token, sourced from an env var +$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN +``` + +> [!TIP] +> **When to use chat server vs. API server** +> +> Use the **chat server** when you want to plug Docker Agent into existing OpenAI-compatible tooling (chat UIs, IDE integrations, OpenAI SDK clients). Use the [API server](../api-server/index.md) when you want full control over sessions, agent execution, tool-call confirmations, and streamed runtime events. + +## Endpoints + +The OpenAI-compatible endpoints live under the `/v1` prefix to match the +OpenAI API surface. The OpenAPI specification is served at the top level so it +can be discovered without authentication. + +| Method | Path | Description | +| ------ | ---------------------- | ---------------------------------------------------------------------- | +| `GET` | `/v1/models` | List the agents that this server exposes as models | +| `POST` | `/v1/chat/completions` | Send messages and receive a completion (regular or streaming) | +| `GET` | `/openapi.json` | OpenAPI specification for the chat server | + +The model identifier in `POST /v1/chat/completions` is the **agent name**. +For a single-agent config that's typically `root`; for a multi-agent config, +each named agent becomes its own selectable model. + +## Quick Start + +```bash +# 1. Start the server +$ docker agent serve chat agent.yaml +Listening on 127.0.0.1:8083 +OpenAI-compatible chat completions endpoint: http://127.0.0.1:8083/v1/chat/completions + +# 2. List exposed agents (models) +$ curl http://127.0.0.1:8083/v1/models +{"object":"list","data":[{"id":"root","object":"model","owned_by":"docker-agent"}]} + +# 3. Send a chat request +$ curl http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "root", + "messages": [{"role": "user", "content": "Hello!"}] + }' +``` + +### Streaming + +Set `"stream": true` in the request body to receive a Server-Sent Events +(SSE) stream of OpenAI-format `chat.completion.chunk` deltas: + +```bash +$ curl -N http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "root", + "stream": true, + "messages": [{"role": "user", "content": "Stream a poem"}] + }' +``` + +### Drive it from the OpenAI Python SDK + +Because the wire format is OpenAI-compatible, point any OpenAI client at the +chat server's `base_url` and use the agent name as the model: + +```python +from openai import OpenAI + +client = OpenAI( + base_url="http://127.0.0.1:8083/v1", + api_key="not-needed-when-no-api-key-flag", # required by the SDK, ignored if no auth +) + +resp = client.chat.completions.create( + model="root", + messages=[{"role": "user", "content": "Hello!"}], +) +print(resp.choices[0].message.content) +``` + +## Server-side Conversation Caching + +By default the server is **stateless**: every request must contain the full +message history, exactly like OpenAI's API. Enable server-side caching by +setting `--conversations-max` to a positive value, then send a stable +`X-Conversation-Id` header on each request: + +```bash +$ docker agent serve chat agent.yaml --conversations-max 100 --conversation-ttl 30m +``` + +```bash +$ curl http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -H 'X-Conversation-Id: my-thread-1' \ + -d '{ + "model": "root", + "messages": [{"role": "user", "content": "Remember my name is Alice"}] + }' + +$ curl http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -H 'X-Conversation-Id: my-thread-1' \ + -d '{ + "model": "root", + "messages": [{"role": "user", "content": "What is my name?"}] + }' +``` + +Cached conversations are evicted after `--conversation-ttl` of inactivity, or +when the cache hits `--conversations-max` items (oldest entries are evicted +first). + +### Failure-safe caching + +When a request fails — for example because the model returns an error or the `--request-timeout` expires — the conversation cache is **not updated**. The server clones the cached session before processing each request and only commits the updated session when the turn completes successfully. This means: + +- A failed turn leaves the conversation in the same state it was before the request. +- Clients can safely retry with the same `X-Conversation-Id` after a failure. +- Transient errors do not corrupt the conversation history. + +## Authentication + +The chat server defaults to loopback binding. A non-loopback `--listen` address requires `--api-key`, `--api-key-env`, or the explicit `--insecure-no-auth` override. An environment variable selected by `--api-key-env` must be set and non-empty. + +To require a Bearer +token, pass `--api-key` (literal value) or `--api-key-env` (name of an +environment variable that holds the value): + +```bash +$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN +``` + +Clients must then send an `Authorization: Bearer <token>` header on every +request to `/v1/*`. Both `/v1/models` and `/v1/chat/completions` are +protected once a key is set. + +> [!WARNING] +> **Public exposure** +> +> The default listen address is `127.0.0.1:8083`. Non-loopback binding is rejected unless `--api-key`, `--api-key-env`, or `--insecure-no-auth` is supplied. Use the insecure override only behind a trusted authentication boundary. + +## Tool safety + +The chat server resolves its safety policy in this order: `--safety`, agent configuration, runtime configuration, then `restricted`. Cached conversations retain the more restrictive of their prior policy and the server policy, so a continuation cannot regain permissions after the server policy becomes stricter. + +## CORS + +CORS is **disabled by default**. To allow a browser-based client to call the +server, set `--cors-origin` to the exact origin (scheme + host + port) that +should be allowed: + +```bash +$ docker agent serve chat agent.yaml --cors-origin https://my-ui.example.com +``` + +## CLI Flags + +```bash +docker agent serve chat <agent-file>|<registry-ref> [flags] +``` + +| Flag | Default | Description | +| ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | +| `-a, --agent <name>` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate model. | +| `-l, --listen <addr>` | `127.0.0.1:8083` | Address to listen on. | +| `--cors-origin <origin>` | (none) | Allowed CORS origin (e.g. `https://example.com`). Empty disables CORS. | +| `--api-key <token>` | (none) | Required Bearer token clients must present (`Authorization: Bearer <token>`). Empty disables auth. | +| `--api-key-env <name>` | (none) | Read the required API key from this non-empty environment variable. | +| `--insecure-no-auth` | `false` | Permit unauthenticated non-loopback binding. Use only behind a trusted authentication boundary. | +| `--safety <policy>` | `restricted` | Tool safety policy. CLI value overrides agent/runtime configuration. | +| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size in bytes. Requests whose body exceeds this limit are rejected with HTTP 413 (Request Entity Too Large) — see [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large) if you hit this. | +| `--request-timeout <dur>` | `5m` | Per-request timeout (covers model + tool calls + streaming). | +| `--conversations-max <n>` | `0` | Cache up to N conversations server-side, keyed by `X-Conversation-Id`. `0` disables — clients must resend history. | +| `--conversation-ttl <dur>` | `30m` | Idle TTL after which a cached conversation is evicted. | +| `--max-idle-runtimes <n>` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. | + +All [runtime configuration flags](../cli/index.md#runtime-configuration-flags) +(`--working-dir`, `--env-from-file`, `--models-gateway`, `--hook-*`, …) are +also accepted. + +> [!NOTE] +> **What `--max-request-size` does and doesn't cover** +> +> This is a finite, process-wide cap on one serialized inbound HTTP request body — it isn't a model context-window limit, and raising it doesn't increase what a provider/model accepts or how large a local attachment/prompt file can be. A larger cap also means the server buffers more memory per request from an unauthenticated or malicious client, so weigh that against your deployment's exposure. If a reverse proxy or gateway sits in front of this server, it may enforce its own, lower cap regardless of this flag. See [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large) for full diagnosis. + +## Image Inputs + +Messages can include OpenAI-style `image_url` content parts alongside `text`: + +```json +{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}} +``` + +A `data:` URL embeds the image bytes directly in the JSON body, so its base64-encoded size counts toward `--max-request-size` above like any other request content. A remote `http(s)://` URL is passed through to the selected model provider rather than fetched by the chat server itself — whether it works depends on that provider and model: some accept a remote URL directly, others only accept `data:` URLs, and a provider/model without image support drops the part. Don't assume a remote image URL will be fetched or rendered universally; verify against the specific provider/model you've configured. + +## Open WebUI Integration + +Open WebUI can talk to any OpenAI-compatible endpoint. To plug Docker Agent +in: + +1. Start the chat server, optionally with auth: + + ```bash + $ docker agent serve chat agent.yaml \ + --listen 127.0.0.1:8083 \ + --cors-origin http://localhost:3000 \ + --api-key-env OPEN_WEBUI_TOKEN + ``` + +2. In Open WebUI, add an OpenAI-compatible connection: + + - **API Base URL:** `http://127.0.0.1:8083/v1` + - **API Key:** the value of `OPEN_WEBUI_TOKEN` + +3. Each agent in your config appears as a selectable model. + +> [!NOTE] +> **See also** +> +> For the Docker Agent–native HTTP API (sessions, tool-call confirmation, runtime events), see the [API Server](../api-server/index.md). For full CLI flag documentation, see the [CLI Reference](../cli/index.md#docker-agent-serve-chat). diff --git a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md new file mode 100644 index 000000000000..41db671d409d --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md @@ -0,0 +1,840 @@ +--- +title: "CLI Reference" +description: "Complete reference for all Docker Agent command-line commands and flags." +keywords: docker agent, ai agents, features, cli reference +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/features/cli/ +aliases: + - /ai/docker-agent/reference/cli/ +--- + +_Complete reference for all Docker Agent command-line commands and flags._ + +> [!TIP] +> **No config needed** +> +> Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a built-in default agent that is perfect for quick experimentation. + +## Commands + +### `docker agent run` + +Launch the interactive TUI with an agent configuration (`.yaml`, `.yml`, or `.hcl`). + +```bash +$ docker agent run [config] [message...] [flags] +``` + +| Flag | Description | +| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `-a, --agent <name>` | Run a specific agent from the config | +| `--yolo` | Auto-approve tool calls (unless explicitly denied). Legacy alias for `--safety autonomous`. | +| `--safety <mode>` | Safety mode for tool approval: `strict` (ask for everything), `balanced` (auto-approve safe calls), `restricted` (auto-approve safe calls, deny the rest — fail-closed for unattended runs), or `autonomous` (approve everything). Wins over `--yolo` when both are given. Without the flag, the mode falls back to alias/user-config defaults, then the agent YAML's `agents.<name>.safety` / `runtime.safety`; a resumed session keeps its stored mode unless `--safety`/`--yolo` is passed explicitly. See [Safety Modes](../../configuration/permissions/index.md#safety-modes). | +| `--model <ref>` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. | +| `--session <id>` | Resume a previous session. Supports relative refs (`-1` = newest by creation time, `-2` = second-newest, … — creation order, not last-used). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. | +| `-s, --session-db <path>` | Path to the SQLite session database (default: `<data-dir>/session.db`, so `~/.cagent/session.db` unless `--data-dir` is set) | +| `--session-read-only` | Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. | +| `--prompt-file <path>` | Include file contents as additional system context (repeatable) | +| `--attach <path>` | Attach an image file to the initial message | +| `--dry-run` | Initialize the agent without executing anything (useful for validating a config) | +| `--remote <addr>` | Use a remote runtime at the given address instead of running the agent locally. Mutually exclusive with `--sandbox`, `--worktree`, `--worktree-pr`, `--worktree-base`, `--session`, `--session-db`, `--record`, and `--fake` — a remote runtime owns its own session storage and execution environment, so these local-only concerns don't apply. | +| `--listen <addr>` | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. Hidden from `docker agent run --help` — like `debug`, it's a stable but advanced/automation-oriented flag rather than a day-to-day one. See the [API Server](../api-server/index.md#listen) guide for the full walkthrough. | +| `--session-workingdir-root <path>` | Confine the `working_dir` of sessions created through the `--listen` control plane to this directory and its descendants (default: no restriction — any clean host directory is accepted, though raw values containing `..` are rejected). Recommended when the control plane is reachable by other users. Hidden from `--help`, like `--listen`. | +| `--lean` | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Like the full TUI, displays an ASCII art banner on startup when the chat is empty. | +| `--app-name <name>` | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications). | +| `--sidebar` | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`). | +| `--disable-commands <list>` | Hide and disable specific slash commands in the TUI. Accepts a comma-separated list of command names (leading slash optional, case-insensitive). E.g. `--disable-commands="/cost,/eval,/model"`. | +| `--theme <name>` | Preselect a TUI theme by name, or `auto` to follow the terminal's light/dark background (overrides the theme from user config; ignored outside the interactive TUI) | +| `--on-event <type>=<cmd>` | Run a shell command when an event of the given type fires (`*=<cmd>` matches any event). Repeatable. | +| `--json` | Output results as newline-delimited JSON (use with `--exec`) | +| `--hide-tool-calls` | Hide tool calls in the output | +| `--hide-tool-results` | Hide tool call results in the output | +| `--sandbox` | Run the agent in sandbox mode using `sbx` (see [Sandbox](../../configuration/sandbox/index.md)) | +| `--template <image>` | Template image for the sandbox (default: `docker/docker-agent-sbx-templates:latest`) | +| `--no-kit` | Disable the [auto-kit](../../configuration/sandbox/index.md#auto-kit): do not stage skills or prompt files into the sandbox | +| `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to the built-in `default` and `coder` agents plus any agent configs found in `~/.agents`). Arrow keys navigate; `?` toggles the YAML preview panel; `l` (or mouse-click) toggles the **Lean Mode** checkbox to launch in the lean TUI; `b` (or clicking **[ Open Board ]**) opens the Kanban board (`docker agent board`) instead of running an agent; Enter confirms. Not available in `--exec` or non-TTY modes. | +| `-w, --worktree [name]` | Run the agent in a fresh git worktree of the working directory, isolating its changes from your checkout. Optionally name it (`--worktree=my-feature`); otherwise a name is generated. Requires the working directory to be inside a git repository. Every tool (the shell included) runs inside the worktree. Combine with `--working-dir` to branch from another repository, and with `--session` to resume into the same worktree later. Cannot be combined with `--remote` or `--sandbox`. When the session ends, a clean worktree is removed automatically; one with work prompts to keep or remove (never in `--exec`). | +| `--worktree-base <ref>` | Branch the `--worktree` from `<ref>` (a branch, tag, commit, or remote-tracking ref like `origin/main`) instead of the current `HEAD`. A remote-tracking ref is fetched first so the worktree starts from the latest remote state. Requires `--worktree`; cannot be combined with `--worktree-pr`, `--remote`, or `--sandbox`. | +| `--worktree-pr <number\|url>` | Run the agent in a git worktree checked out on an existing GitHub pull request (PR number, `#123`, or PR URL). Continues the PR's branch so commits push back to it. Requires the [GitHub CLI](https://cli.github.com/) (`gh`). Cannot be combined with `--worktree`, `--remote`, or `--sandbox`. | +| `--working-dir <path>` | Set the working directory for the session (applies to tools and relative paths) | +| `--env-from-file <path>` | Load environment variables from file (repeatable) | +| `--flavor <name>` | Enable a config flavor, a YAML patch defined under the config's `flavors` section (repeatable, applied in order). See [Flavors](../../configuration/flavors/index.md). | +| `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally) | +| `--models-gateway <addr>` | Route model traffic through a gateway. Also reads `DOCKER_AGENT_MODELS_GATEWAY` (legacy `CAGENT_MODELS_GATEWAY`) env var. | +| `--hook-pre-tool-use <cmd>` | Add a pre-tool-use hook command (repeatable). See [Hooks](../../configuration/hooks/index.md). | +| `--hook-post-tool-use <cmd>` | Add a post-tool-use hook command (repeatable) | +| `--hook-session-start <cmd>` | Add a session-start hook command (repeatable) | +| `--hook-session-end <cmd>` | Add a session-end hook command (repeatable) | +| `--hook-on-user-input <cmd>` | Add an on-user-input hook command (repeatable) | +| `--hook-stop <cmd>` | Add a stop hook command, fired when the model finishes responding (repeatable) | +| `--fake <path>` | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | +| `--fake-stream [ms]` | When replaying with `--fake`, simulate streaming with a delay between chunks (defaults to 15ms when given without a value). | +| `--record [path]` | Record AI API interactions to a cassette file and generate a TUI e2e test from the session (auto-generates filename if no path given). Routes through `--models-gateway` when one is configured. | +| `-d, --debug` | Enable debug logging | +| `--log-file <path>` | Custom debug log location | +| `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | + +```bash +# Examples +$ docker agent run agent.yaml +$ docker agent run agent.yaml "Fix the bug in auth.go" +$ docker agent run agent.yaml -a developer --yolo +$ docker agent run agent.yaml --model anthropic/claude-sonnet-4-5 +$ docker agent run agent.yaml --model "dev=openai/gpt-4o,reviewer=anthropic/claude-sonnet-4-5" +$ docker agent run agent.yaml --session -1 # resume last session +$ docker agent run agent.yaml --session -1 --session-read-only # review last session without sending messages +$ docker agent run agent.yaml --prompt-file ./context.md # include file as context + +# Add hooks from the command line +$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh" +$ docker agent run agent.yaml --hook-pre-tool-use "./scripts/validate.sh" --hook-post-tool-use "./scripts/log.sh" + +# Queue multiple messages (processed in sequence) +$ docker agent run agent.yaml "question 1" "question 2" "question 3" + +# Customize TUI display +$ docker agent run agent.yaml --app-name "My Project" +$ docker agent run agent.yaml --sidebar=false +$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model" + +# Browse and pick an agent interactively +$ docker agent run --agent-picker +$ docker agent run --agent-picker=myorg/coder,myorg/researcher +``` + +> [!TIP] +> **Lean, inline TUI** +> +> Pass `--lean` to get a lightweight TUI that renders inline in your terminal (no alternate screen). Like the full TUI, it displays an ASCII art banner on startup when the chat is empty, and supports the same slash commands and streaming output, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted. + +> [!TIP] +> **Isolate a run in a git worktree** +> +> When the working directory is inside a git repository, `--worktree` creates a fresh [git worktree](https://git-scm.com/docs/git-worktree) and points the session at it, so the agent's edits land on a separate branch and never touch your checkout. Every tool — the shell included — runs inside the worktree. The worktree is stored under `<data-dir>/worktrees/<name>` on a branch named `worktree-<name>`. + +```bash +# Run in an isolated worktree with a generated name (e.g. "focused_turing") +$ docker agent run agent.yaml --worktree +$ docker agent run agent.yaml -w "Refactor the auth package" + +# Give the worktree (and its branch) an explicit name +$ docker agent run agent.yaml --worktree=auth-refactor + +# Branch the worktree from another ref instead of the current HEAD. +# A remote-tracking ref is fetched first, so the worktree starts from the +# latest remote state. +$ docker agent run agent.yaml --worktree=auth-refactor --worktree-base origin/main + +# Resume a worktree run later: the session remembers its worktree, so you +# don't pass --worktree again (which would fail — the worktree already exists). +$ docker agent run agent.yaml --worktree=auth-refactor # first run, creates it +$ docker agent run agent.yaml --session -1 # resumes into the same worktree + +# Check out an existing GitHub pull request to continue it (requires gh) +$ docker agent run agent.yaml --worktree-pr 123 +$ docker agent run agent.yaml --worktree-pr https://github.com/owner/repo/pull/123 +``` + +With `--worktree-pr`, the PR's head branch is checked out tracking its remote (via the [GitHub CLI](https://cli.github.com/)), so commits made during the run push straight back to the pull request. The worktree is stored under `<data-dir>/worktrees/pr-<number>`. + +When the interactive session ends, the worktree is cleaned up based on its state: + +- **Clean** (no uncommitted changes, untracked files, or new commits): the worktree and its branch are removed automatically. +- **Has work** (uncommitted changes, untracked files, or new commits): you're prompted to keep or remove it. Keeping preserves the directory and branch so you can return later; removing discards the worktree, its branch, and all that work. +- **Non-interactive runs** (`--exec`): the worktree is never cleaned up — it's left in place for inspection. + +A worktree is only ever removed if `--worktree` created it for this run; a pre-existing worktree is never touched. + +A kept worktree can be resumed: pass `--session` (a relative ref like `-1`, or the session id) and the run reattaches to the same worktree directory and branch automatically. Don't re-pass `--worktree` on resume — that would try to create a new worktree and fail because it already exists. + +### `docker agent run --exec` + +Run an agent in non-interactive (headless) mode. No TUI — output goes to stdout. + +```bash +$ docker agent run --exec [config] [message...] [flags] +``` + +```bash +# One-shot task +$ docker agent run --exec agent.yaml "Create a Dockerfile for a Python Flask app" + +# With auto-approve +$ docker agent run --exec agent.yaml --yolo "Set up CI/CD pipeline" + +# Multi-turn conversation +$ docker agent run --exec agent.yaml "question 1" "question 2" "question 3" +``` + +### `docker agent new` + +Interactively generate a new agent configuration file. + +```bash +$ docker agent new [flags] + +# Examples +$ docker agent new +$ docker agent new --model openai/gpt-5 +$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15 +``` + +### `docker agent getting-started` + +Run a short (about 2 minutes), skippable interactive tour inside the chat UI: sending messages, approving tool calls, the command palette (<kbd>Ctrl</kbd>+<kbd>K</kbd>), slash commands, and how agents are configured. Aliased as `docker agent tour`. Requires an interactive terminal. + +```bash +$ docker agent getting-started +``` + +Replay it anytime with this command, or with the `/getting-started` slash command inside a running TUI session. + +### `docker agent models` + +List models available for use with `--model`. By default only shows models for providers you have credentials for. Aliases: `docker agent models list`, `docker agent models ls`. + +```bash +$ docker agent models [flags] +``` + +| Flag | Default | Description | +| ---------------------- | ------- | ---------------------------------------------------------------------------------- | +| `-p, --provider <id>` | (none) | Filter models by provider name (e.g. `openai`, `anthropic`, `dmr`, `ollama`, …). | +| `--format <fmt>` | `table` | Output format: `table` or `json`. | +| `-a, --all` | `false` | Include models from all providers, not just those you have credentials for. | + +```bash +# Examples +$ docker agent models # only providers you can use +$ docker agent models --all # every provider the catalog knows about +$ docker agent models --provider openai +$ docker agent models --format json | jq +``` + +When a models gateway is configured (`--models-gateway`, `DOCKER_AGENT_MODELS_GATEWAY`, or the user config), the command first queries the gateway's `/v1/models` endpoint. A non-empty response is authoritative for the models routed through the gateway: the listing shows the models the gateway serves (`--provider` filters within it), alongside any custom providers you have configured, which serve their models from their own endpoints rather than through the gateway. If the gateway cannot be queried or serves no usable model (endpoint not implemented, empty list, invalid response, timeout, missing authentication), the command falls back to the providers you have configured directly — provider API keys, provider aliases, and custom providers — plus the model catalog; a failure of one source never prevents the others from being listed. The Docker Desktop token is only sent (and required) when the gateway targets a trusted Docker URL. + +### `docker agent toolsets` + +List the built-in toolset types available for use in an agent configuration. Each type can be referenced under `toolsets:` in an agent YAML file. Use this to discover what's available without leaving the terminal. + +```bash +$ docker agent toolsets [flags] +``` + +| Flag | Default | Description | +| ---------------- | ------- | --------------------------------- | +| `--format <fmt>` | `table` | Output format: `table` or `json`. | + +```bash +# Examples +$ docker agent toolsets # human-readable table +$ docker agent toolsets --format json | jq # machine-readable (type, summary, docs URL) +``` + +### `docker agent setup` + +Set up a model interactively. Four paths: + +- **Built-in cloud provider**: pick a provider Docker Agent already knows (Anthropic, OpenAI, Google, Groq, Hugging Face, ...) and connect it. Credentials vary by provider: most take an API key or token, stored in the Docker Agent env file `~/.config/cagent/.env`, while `chatgpt` signs in with your ChatGPT account in the browser. +- **Local model**: check Docker Model Runner and pull a model. No API key needed. +- **Custom OpenAI-compatible endpoint**: register an endpoint that is not built in (vLLM, LiteLLM, a corporate gateway, ...) with its base URL, API format, and API key variable, saved to your [user configuration](../../providers/custom/index.md#global-providers-user-configuration) so its models work everywhere via `--model <name>/<model>`. +- **Claude Code harness**: use a Claude subscription through the official `claude` CLI. The wizard checks that the CLI is installed and logged in, offers to run `claude auth login --claudeai` (only after you confirm), and writes a ready-to-run `claude-code-agent.yaml`. See [Coding Harnesses](../harnesses/index.md). + +Ends with the exact command to start chatting. Secret values are never printed, and Docker Agent never reads or copies the Claude CLI's credentials. + +The wizard is also offered automatically when an interactive run finds no usable model (decline-able; set `DOCKER_AGENT_NO_SETUP=1` to suppress the offer). + +```bash +$ docker agent setup +``` + +### `docker agent doctor` + +Diagnose the model and credential setup. Reports which model providers have credentials and where each credential comes from (shell environment, env file, Docker Desktop, …), whether Docker Model Runner is reachable and which models are pulled, and which model the `auto` selection would pick. Secret values are never printed. Exits with a non-zero status when an issue would prevent an agent from running, which makes it usable in scripts and CI. + +```bash +$ docker agent doctor [agent-file|registry-ref] [flags] +``` + +With an agent file, also lists the environment variables that file requires (model credentials and tool secrets such as `GITHUB_PERSONAL_ACCESS_TOKEN`), whether each one is set, and from which source. When the file declares a [`claude-code` harness](../harnesses/index.md) agent, the doctor additionally checks that the official `claude` CLI is installed and logged in, reporting its version and safe login metadata (auth method, API provider, subscription type — never your email, organization, or tokens); a missing or logged-out CLI is reported as an issue with the `claude auth login --claudeai` remediation. + +| Flag | Default | Description | +| ------------------------ | ------- | -------------------------------------------------------------- | +| `--json` | `false` | Output the full report in JSON format (for scripting). | +| `--env-from-file <file>` | (none) | Also check variables supplied by an env file. | +| `--models-gateway <url>` | (none) | Diagnose against a models gateway (credentials come from it). | + +```bash +# Examples +$ docker agent doctor # credential, DMR, and auto-selection state +$ docker agent doctor ./agent.yaml # also check that file's requirements +$ docker agent doctor --json | jq .issues +``` + +### `docker agent serve api` + +Start the HTTP API server for programmatic access. The argument can be a single agent file, a registry reference, or a directory — when given a directory, every `.yaml`/`.yml`/`.hcl` file in it is exposed as a separate entry under `/api/agents`. + +```bash +$ docker agent serve api <agent-file>|<agents-dir>|<registry-ref> [flags] +``` + +| Flag | Default | Description | +| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- | +| `-l, --listen <addr>` | `127.0.0.1:8080` | Address to listen on. | +| `--auth-token <token>` | (none) | Bearer token required for all API requests. When set, every request must include `Authorization: Bearer <token>`. Leave empty to disable authentication (safe when listening on loopback interfaces only). | +| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size. Requests exceeding this limit are rejected with HTTP 413 — see [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large). | +| `--session-workingdir-root <path>` | (none) | Confine the `working_dir` of sessions created via `POST /api/sessions` to this directory and its descendants (symlinks are resolved before the check). Unrestricted by default — any clean host directory is accepted (raw values containing `..` are rejected), as local single-user daemons rely on. Recommended for multi-user or network-exposed deployments. | +| `-s, --session-db <path>` | `session.db` | Path to the SQLite session database (relative paths resolve against the working directory). | +| `--pull-interval <minutes>`| `0` | Periodically re-pull OCI/URL references and refresh the agent definition. `0` disables auto-pull. | +| `--fake <path>` | (none) | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | +| `--record [path]` | (none) | Record AI API interactions to a cassette file. Routes through `--models-gateway` when one is configured. | +| `--mcp-oauth-redirect-uri <url>` | (none) | OAuth redirect URI for the unmanaged MCP OAuth flow in server mode. When set, the runtime drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | + +> **Diagnostics:** Set `CAGENT_PPROF_ADDR=127.0.0.1:6060` (or `--pprof-addr`, a hidden flag) to start a live Go pprof server at `/debug/pprof/`. Use a loopback address; a non-loopback binding logs a security warning. + +All [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--env-from-file`, `--models-gateway`, `--hook-*`, …) are also accepted. + +```bash +# Examples +$ docker agent serve api agent.yaml +$ docker agent serve api agent.yaml --listen :8080 +$ docker agent serve api ./agents/ # directory of agent YAML/HCL configs +$ docker agent serve api ociReference --pull-interval 10 # auto-refresh +``` + +See [API Server](../api-server/index.md) for the full HTTP API reference. + +### `docker agent serve mcp` + +Expose agents as MCP tools for use in Claude Desktop, Claude Code, or other MCP clients. Defaults to stdio transport; use `--http` to start a streaming HTTP server instead. + +```bash +$ docker agent serve mcp <config> [flags] +``` + +| Flag | Default | Description | +| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | +| `-a, --agent <name>` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate tool. | +| `--tool-name <name>` | (agent name) | Override the MCP tool identifier clients call; only valid when exposing a single agent. | +| `--http` | `false` | Use streaming HTTP transport instead of stdio. | +| `--safety <policy>` | `restricted` | HTTP MCP safety policy; no effect on stdio or `--attach`. | +| `--auth-token <token>` | (none) | Required Bearer token for HTTP MCP requests. | +| `--insecure-no-auth` | `false` | Permit unauthenticated non-loopback HTTP MCP binding. | +| `-l, --listen <addr>` | `127.0.0.1:8081` | Address to listen on (only used with `--http`). | +| `--mcp-keepalive <dur>`| `0` (disabled) | Interval between MCP keep-alive pings (e.g. `30s`). | +| `--attach [target]` | (none) | Attach to a running TUI run by pid, address, or session id; given without a value, selects the most recent run. | + +All [runtime configuration flags](#runtime-configuration-flags) are also accepted. + +```bash +# Examples +$ docker agent serve mcp agent.yaml # stdio transport +$ docker agent serve mcp agent.yaml --http --listen 127.0.0.1:9090 # streaming HTTP +$ docker agent serve mcp agent.yaml --working-dir /path/to/project +$ docker agent serve mcp myorg/coder +``` + +See [MCP Mode](../mcp-mode/index.md) for detailed setup. + +### `docker agent serve a2a` + +Start an A2A (Agent-to-Agent) protocol server. + +```bash +$ docker agent serve a2a <config> [flags] +``` + +| Flag | Default | Description | +| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------ | +| `-a, --agent <name>` | (team default) | Name of the agent to run. Defaults to the team's first agent if not specified. | +| `-l, --listen <addr>` | `127.0.0.1:8082` | Address to listen on. | +| `-s, --session-db <path>` | `<data-dir>/session.db` | Path to the SQLite session database. | + +All [runtime configuration flags](#runtime-configuration-flags) are also accepted. + +```bash +# Examples +$ docker agent serve a2a agent.yaml +$ docker agent serve a2a agent.yaml --listen 127.0.0.1:9000 +$ docker agent serve a2a myorg/agent:tag +``` + +### `docker agent serve acp` + +Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol. + +```bash +$ docker agent serve acp <config> [flags] +``` + +| Flag | Default | Description | +| ------------------------- | --------------------------- | ------------------------------------------------- | +| `-s, --session-db <path>` | `<data-dir>/session.db` | Path to the SQLite session database. | + +All [runtime configuration flags](#runtime-configuration-flags) are also accepted. + +```bash +# Examples +$ docker agent serve acp agent.yaml +$ docker agent serve acp ./team.yaml +$ docker agent serve acp myorg/agent:tag +``` + +See [ACP](../acp/index.md) for details on the Agent Client Protocol. + +### `docker agent serve chat` + +Start an HTTP server that exposes one or more agents through an **OpenAI-compatible Chat Completions API** at `/v1/chat/completions` and `/v1/models`. This lets any tool that already speaks the OpenAI protocol — for example [Open WebUI](https://github.com/open-webui/open-webui), `curl`, the OpenAI Python SDK, or LangChain — drive a Docker Agent agent without any custom integration. + +```bash +$ docker agent serve chat <config> [flags] +``` + +| Flag | Default | Description | +| ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | +| `-a, --agent <name>` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate model. | +| `-l, --listen <addr>` | `127.0.0.1:8083` | Address to listen on. | +| `--cors-origin <origin>` | (none) | Allowed CORS origin (e.g. `https://example.com`). Empty disables CORS. | +| `--api-key <token>` | (none) | Required Bearer token clients must present (`Authorization: Bearer <token>`). Empty disables auth. | +| `--api-key-env <name>` | (none) | Read the required API key from this non-empty environment variable. | +| `--insecure-no-auth` | `false` | Permit unauthenticated non-loopback binding. | +| `--safety <policy>` | `restricted` | Tool safety policy; CLI value overrides agent/runtime configuration. | +| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size. Requests exceeding this limit are rejected with HTTP 413 — see [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large). | +| `--request-timeout <dur>` | `5m` | Per-request timeout (covers model + tool calls + streaming). | +| `--conversations-max <n>` | `0` | Cache up to N conversations server-side, keyed by `X-Conversation-Id`. `0` disables — clients must resend history. | +| `--conversation-ttl <dur>` | `30m` | Idle TTL after which a cached conversation is evicted. | +| `--max-idle-runtimes <n>` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. | + +```bash +# Examples +$ docker agent serve chat agent.yaml +$ docker agent serve chat ./team.yaml --agent reviewer +$ docker agent serve chat myorg/agent:tag --listen 127.0.0.1:9090 +$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN + +# Drive it from any OpenAI-compatible client +$ curl http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}' +``` + +See [Chat Server](../chat-server/index.md) for the full feature reference. + +### `docker agent board` + +Launch a full-screen Kanban TUI for orchestrating multiple agents at once. Each card runs an agent in its own tmux session on an isolated git worktree; moving a card forward through the pipeline (Dev → Review → Push → Done) delivers the destination column's prompt to that card's agent. Projects and column prompts are stored in the global config file (`~/.config/cagent/config.yaml`) and can be managed from the TUI. + +```bash +$ docker agent board +``` + +Takes no arguments or flags. Requires `tmux` and `git` to be installed. + +See [Kanban Board](../board/index.md) for key bindings, configuration, and workflow details. + +### `docker agent share push` / `docker agent share pull` + +Share agents via OCI registries. + +```bash +# Push an agent +$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest + +# Pull an agent +$ docker agent share pull docker.io/username/my-agent:latest + +# Force pull, overwriting the local copy +$ docker agent share pull docker.io/username/my-agent:latest --force +``` + +| Flag | Applies to | Description | +| ---------- | ---------- | ---------------------------------------------------------- | +| `--force` | `pull` | Force pull even if the configuration already exists locally | + +See [Agent Distribution](../../concepts/distribution/index.md) for full registry workflow details. + +### `docker agent sessions diff` + +Compare two recorded sessions and report the first point where the agent behaved +differently — the triage answer when a task that worked yesterday does not work +today. + +```bash +$ docker agent sessions diff <session-a> <session-b> [flags] +``` + +```console +$ docker agent sessions diff -1 -2 +Comparing a1b2c3d4 (7 turns) against e5f6a7b8 (9 turns) + +❌ First divergence at turn 3 (after 3 matching turn(s)). + a1b2c3d4 called: + read_file({"path":"pkg/cache/cache.go"}) + e5f6a7b8 called: + search_files_content({"query":"persistToDisk","path":"."}) + +Everything after this point is downstream of the divergence and is not compared. +``` + +Session references accept a full ID, a unique ID prefix, or a relative form such +as `-1` for the most recent run. + +| Flag | Default | Description | +| ----------------------- | ----------------------- | ------------------------------------------------ | +| `-s, --session-db` | `<data-dir>/session.db` | Path to the session database | +| `--json` | `false` | Emit the comparison as JSON | +| `--fail-on-divergence` | `false` | Exit non-zero when the two sessions diverge | + +Comparison is over the sequence of tool calls, not the assistant's prose: model +output is nondeterministic, so two runs of the same task almost always word +things differently while doing the same work. Turns taken by delegated +sub-agents are included in sequence. Reporting stops at the first divergence — +everything after it is downstream of that difference. + +This locates *where* two runs diverged, not *why*. Re-running a session against +a different model while holding the environment fixed is a separate, unbuilt +feature. + +### `docker agent eval` + +Run agent evaluations against a directory of recorded sessions. + +```bash +$ docker agent eval <agent-file>|<registry-ref> [<eval-dir>|./evals] [flags] +``` + +| Flag | Default | Description | +| ------------------- | ------------------------------------ | -------------------------------------------------------------------------- | +| `-c, --concurrency` | num CPUs | Number of concurrent evaluation runs | +| `--judge-model` | `anthropic/claude-opus-5` | Model for LLM-as-a-judge relevance scoring (format: `provider/model`) | +| `--output <dir>` | `<eval-dir>/results` | Directory for results, logs, and session databases | +| `--only <pattern>` | (all) | Only run evals with file names matching these patterns (repeatable) | +| `--base-image` | (default) | Custom base image for eval containers | +| `--container-runtime` | `docker` | Container runtime executable for building and running evaluations (e.g. `podman`) | +| `--keep-containers` | `false` | Keep containers after evaluation (don't remove with `--rm`) | +| `-e, --env` | (none) | Environment variables to pass to container (`KEY` or `KEY=VALUE`, repeatable) | +| `--repeat <n>` | `1` | Number of times to repeat each evaluation (useful for computing baselines) | +| `--baseline <file>` | (none) | Compare against a previously saved run JSON (`<output>/<run>.json`) and exit non-zero on regression | +| `--regression-tolerance <n>` | `0` | How far an aggregate quality rate may fall before `--baseline` reports a regression (0–1) | + +All [runtime configuration flags](#runtime-configuration-flags) are also accepted. + +```bash +# Examples +$ docker agent eval agent.yaml # use ./evals +$ docker agent eval agent.yaml ./my-evals # custom directory +$ docker agent eval agent.yaml -c 8 # 8 concurrent evaluations +$ docker agent eval agent.yaml --keep-containers # keep containers for debugging +$ docker agent eval agent.yaml --only "auth*" # only run matching evals +$ docker agent eval agent.yaml --repeat 5 # repeat each eval 5 times +$ docker agent eval agent.yaml --container-runtime podman # use a Docker-compatible runtime such as Podman +``` + +See [Evaluation](../evaluation/index.md) for details on creating eval sessions and interpreting results. + +### `docker agent version` + +Print the version and commit hash for your `docker-agent` install. + +```bash +$ docker agent version +docker agent version v1.54.0 +Commit: 1737035c +``` + +### `docker agent alias` + +Manage agent aliases for quick access. + +```bash +# List aliases +$ docker agent alias ls + +# List aliases as JSON +$ docker agent alias list --json + +# Add an alias +$ docker agent alias add pirate /path/to/pirate.yaml +$ docker agent alias add other ociReference + +# Add an alias with runtime options +$ docker agent alias add yolo-coder myorg/coder --yolo +$ docker agent alias add careful-coder myorg/coder --safety balanced +$ docker agent alias add fast-coder myorg/coder --model openai/gpt-4o-mini +$ docker agent alias add safe-coder myorg/coder --sandbox +$ docker agent alias add turbo myorg/coder --yolo --model anthropic/claude-sonnet-4-5 + +# Use an alias +$ docker agent run pirate +$ docker agent run yolo-coder +``` + +**Alias Options:** Aliases can include runtime options that apply automatically when used: + +- `--yolo` — Auto-approve tool calls (unless explicitly denied) when running the alias. Legacy alias for `--safety autonomous`. +- `--safety <mode>` — Default [safety mode](../../configuration/permissions/index.md#safety-modes) (`strict`, `balanced`, `restricted`, or `autonomous`) when running the alias. Wins over the alias's `yolo` option; both are stored declaratively in the user config (`aliases.<name>.safety` / `aliases.<name>.yolo`), so you can also edit them there by hand. +- `--model <ref>` — Override the model for the alias +- `--hide-tool-results` — Hide tool call results in the TUI when running the alias +- `--sandbox` — Always run the alias inside a [Docker sandbox](../../configuration/sandbox/index.md) + +Alias safety options are defaults for new sessions: an explicit `--safety`/`--yolo` on the command line wins over them, they win over `settings.safety`/`settings.YOLO` and over anything declared in the agent YAML, and they never change the mode of a resumed session. + +When listing aliases, options are shown in brackets: + +```bash +$ docker agent alias ls +Registered aliases (3): + + fast-coder → myorg/coder [model=openai/gpt-4o-mini] + turbo → myorg/coder [yolo, model=anthropic/claude-sonnet-4-5] + yolo-coder → myorg/coder [yolo] + +Run an alias with: docker agent run <alias> +``` + +Pass `--json` to output aliases as a JSON array instead of the formatted table. Each entry includes the alias `name` and its options: + +```bash +$ docker agent alias list --json +[ + { + "name": "fast-coder", + "path": "myorg/coder", + "model": "openai/gpt-4o-mini" + }, + { + "name": "turbo", + "path": "myorg/coder", + "yolo": true, + "model": "anthropic/claude-sonnet-4-5" + }, + { + "name": "yolo-coder", + "path": "myorg/coder", + "yolo": true + } +] +``` + +JSON output is sorted by name and omits false/zero-valued fields. This is useful for scripting and automation. + +> [!TIP] +> **Override alias options** +> +> Command-line flags override alias options. For example, `docker agent run yolo-coder --yolo=false` disables yolo mode even though the alias has it enabled. + +> [!TIP] +> **Set a default agent** +> +> Create a `default` alias to customize what `docker agent` starts with no arguments: +> +> ```console +> $ docker agent alias add default /my/default/agent.yaml +> ``` +> +> Then simply run `docker agent` — it will launch that agent automatically. + +### `docker agent sandbox` + +Manage settings shared by every [`--sandbox`](../../configuration/sandbox/index.md) run — today, the persistent network allowlist that turns a `Blocked by network policy` 403 into a one-line, durable fix: + +```bash +# Allow a host on every subsequent --sandbox run. +$ docker agent sandbox allow api.example.com + +# Or several at once. +$ docker agent sandbox allow api.example.com registry.npmjs.org:443 + +# See what's persisted in ~/.config/cagent/config.yaml. +$ docker agent sandbox list + +# Drop a host you no longer need. +$ docker agent sandbox deny api.example.com +``` + +Entries are unioned with the gateway, the kit-resolved tool install hosts, and any `runtime.network_allowlist` declared by the agent. The launch summary lists every source separately so you can see which holes were punched by which layer. + +### `docker agent plans` + +Manage the plans agents collaborate on, from the host — without starting a session. Two plan systems are covered: + +- **Shared plans** — the named, versioned documents of the [plan toolset](../../tools/plan/index.md). Fully manageable: create, update, set status, export, delete. +- **Session plans** — the single per-session plan of the "draft, review, execute" workflow. Read-only here (`list`, `get`, `export`); they belong to their session and are changed from within it. A mutation aimed at a session plan fails with an `unsupported` error explaining what to do instead. + +```bash +$ docker agent plans <subcommand> [flags] +``` + +| Subcommand | Description | +| ---------- | ----------- | +| `list [--session <id>]` | List shared plans with scope, name, status, version, updated time, and title. With `--session`, that session's plan is listed first when it exists. Plans that exist but cannot be read are reported as warnings on stderr (in the `warnings` field with `--json`), so they are never mistaken for missing. | +| `get <name>` | Print a plan. Content goes to stdout and a concise metadata line goes to stderr, so `> file` captures the content alone (use `export` for a byte-exact copy). `get --session <id>` prints a session's plan; the name is then omitted (`--scope shared\|session` disambiguates explicitly, and `--session` alone implies session scope). | +| `create <name> --file <path>` | Create a new shared plan with content from `--file` (required — the CLI never prompts; `--file -` reads stdin). Create-only: an existing name fails with a version conflict instead of overwriting. `--title`, `--author`, and `--status` set metadata. | +| `update <name> --file <path>` | Replace the content of an existing shared plan (never creates). Omitted `--title`/`--author`/`--status` flags preserve the current values; passing them (even empty) overwrites. | +| `status <name> <status>` | Set a shared plan's free-form status without touching its body (bumps the version). | +| `export <name> --output <path>` | Write a plan's content, byte-exact, to a file (parents created, atomic write). An existing destination is refused (`invalid_argument`) and left untouched; add `--force` to replace an existing regular file atomically. Works for both scopes: `export --session <id> --output <path>`. | +| `delete <name>` | Delete a shared plan. A `--force` delete also recovers a corrupt plan. | + +Plan content passed via `--file` (a regular file, or stdin with `--file -`) is capped at 10 MiB — the same limit the plan storage itself enforces — and a directory or non-regular file (device, named pipe) is rejected up front; violations fail with an `invalid_argument` error. + +**Concurrency guard:** every mutation (`update`, `status`, `delete`) requires exactly one of two mutually exclusive flags — the CLI is headless and never prompts: + +- `--expected-version <n>` — the version you last read (from `get` or `list`; must be ≥ 1). When the plan changed in the meantime the command fails with a version conflict, reports the current version, leaves the plan untouched, and exits with code **3** (all other failures exit with 1). +- `--force` — deliberately write without the optimistic-lock guard (last writer wins). + +`create` takes no guard: it is inherently create-only and conflicts (exit code 3) when the name already exists. + +**JSON output:** every subcommand accepts `--json`. Success documents go to stdout with a top-level `"schema_version": "1"` marker and stable service-model keys (`plans`, `plan`, `export`, `deleted`) whose fields are snake_case (`updated_at`, `session_id`, `bytes_written`; a zero/unknown `updated_at` is omitted); empty plan lists encode as `[]`, and no prose or ANSI is mixed in. Failures print a single JSON object to stderr: + +```json +{"schema_version":"1","error":{"code":"conflict","message":"...","scope":"shared","name":"p","expected_version":1,"current_version":2}} +``` + +with `code` one of `conflict` (including `expected_version` and `current_version`), `not_found`, `invalid_argument`, `unsupported`, `corrupt`, `storage`, or `error`; `scope`, `name`, and `op` are included where the failure carries them. Validation performed before a subcommand runs is covered too: a missing required flag, a violated `--expected-version`/`--force` group rule, and wrong positional arguments are reported as the same JSON object (code `invalid_argument`) whenever `--json` is present. One residual: flags are parsed left-to-right and parsing stops at the first unknown flag or invalid flag value, so such an error is reported as JSON only when `--json` appears before it on the command line; errors raised before a `plans` subcommand is resolved at all (e.g. an unknown subcommand) also remain plain text. + +```bash +# Examples +$ docker agent plans list +$ docker agent plans list --json | jq '.plans[].name' +$ docker agent plans create release --file ./plan.md --title "Release plan" --status draft +$ cat plan.md | docker agent plans create release --file - +$ docker agent plans get release > plan.md # content only; metadata on stderr +$ docker agent plans update release --file ./plan.md --expected-version 1 +$ docker agent plans status release done --expected-version 2 +$ docker agent plans export release --output ./plan.md +$ docker agent plans export release --output ./plan.md --force # replace an existing file +$ docker agent plans delete release --expected-version 3 +$ docker agent plans delete scratch --force +$ docker agent plans get --session <session-id> # a session's plan +$ docker agent plans export --session <session-id> --output ./session-plan.md +``` + +Plans live under the data directory (`~/.cagent/plans/` and `~/.cagent/session_plans/` by default), so `--data-dir` selects which store the commands operate on. + +### `docker agent debug` + +Troubleshooting subcommands for inspecting how an agent config resolves and generating diagnostic output — useful when a config isn't behaving the way you expect. `debug` doesn't appear in `docker agent --help` (it's a diagnostic surface, not a day-to-day command), but every subcommand below is stable and fully supported. + +```bash +$ docker agent debug <subcommand> [flags] +``` + +| Subcommand | Description | +| ---------- | ----------- | +| `config <agent-file>` | Print the fully-resolved, canonical form of an agent's configuration (defaults applied, references resolved). | +| `toolsets <agent-file>` | List every toolset each agent in the config exposes, with each tool's name and description. | +| `skills <agent-file>` | List the skills discovered for each agent, marking forked skills. | +| `title <agent-file> <question>` | Generate a session title for `<question>` using the same title-generation path the TUI uses (including any configured `title_model`), without starting a session. See [Session Titles](../sessions/index.md#session-titles). | +| `auth` | Print parsed Docker authentication info from the token in use (source, subject, issuer, expiry, username/email). Add `--json` for machine-readable output. | +| `oauth list` | List stored MCP OAuth tokens (resource, scope, expiry, redacted access token). Add `--json` for machine-readable output. | +| `oauth remove <resource-url>` | Remove a stored MCP OAuth token. | +| `oauth login <agent-file> <mcp-name>` | Perform an interactive OAuth login for a remote MCP server declared in the config, by its name or URL. See [Remote MCP Servers](../remote-mcp/index.md). | + +```bash +# Examples +$ docker agent debug config agent.yaml +$ docker agent debug toolsets agent.yaml +$ docker agent debug skills agent.yaml +$ docker agent debug title agent.yaml "How do I configure a fallback model?" +$ docker agent debug auth --json +$ docker agent debug oauth list +$ docker agent debug oauth login agent.yaml github +``` + +> [!WARNING] +> **`debug auth --json` prints the full bearer token** +> +> The text output of `debug auth` truncates the token to a short preview, but `--json` includes the complete, unredacted JWT in its `token` field. Never paste `debug auth --json` output into logs, issue trackers, or bug reports — anyone with that token can act as you against Docker. Use the plain-text output (or redact the `token` field yourself) when sharing diagnostic output. + +The `Source` field says where the token came from: `docker desktop`, or `minted from the stored access token` when it was obtained by exchanging the access token `docker login` stored. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). + +The `config`, `toolsets`, `skills`, and `title` subcommands also accept [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--models-gateway`, …); `title` additionally accepts `--model` to override the model used to resolve the config before generating the title. + +### `docker agent completion` + +Generate a shell completion script for `bash`, `zsh`, `fish`, or `powershell`. + +```bash +$ docker agent completion <bash|zsh|fish|powershell> + +# Examples +# Bash: load for the current session +$ source <(docker agent completion bash) + +# Zsh: install permanently (adjust the path for your $fpath) +$ docker agent completion zsh > "${fpath[1]}/_docker-agent" +``` + +Run `docker agent completion <shell> --help` for shell-specific installation instructions. + +### Self-update + +When installed from a standalone GitHub release binary, Docker Agent can opt in to updating itself. It's disabled by default; set `DOCKER_AGENT_AUTO_UPDATE` to a truthy value (`1`, `true`, `yes`, `on`) to enable it for a command or a shell session: + +```bash +$ DOCKER_AGENT_AUTO_UPDATE=1 docker agent run +``` + +When enabled, every command checks the latest GitHub release before running. If a newer release exists, an interactive session asks whether to install it; a non-interactive session (CI, piped input) proceeds automatically. On yes, Docker Agent downloads the asset for your OS/architecture, verifies its checksum, replaces the current binary, and re-executes with the same arguments. The whole mechanism is fail-safe: any failure at any step falls back to running the current binary. Self-update never triggers for `version`, `help`, `--help`/`-h` (including per-subcommand help), `completion`, or the Docker CLI plugin metadata handshake. + +See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates) for the full walkthrough. Docker Desktop and Homebrew installs already manage updates and don't need this. + +## Global Flags + +These flags are available on every `docker agent` command: + +| Flag | Description | +| ------------------------- | -------------------------------------------------------------------------------------- | +| `-d, --debug` | Enable debug logging (default location: `~/.cagent/cagent.debug.log`) | +| `--log-file <path>` | Custom debug log location (only used with `--debug`) | +| `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | +| `--cache-dir <path>` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) | +| `--config-dir <path>` | Override the config directory (default: `~/.config/cagent`). Also reads `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) env var. | +| `--data-dir <path>` | Override the data directory (default: `~/.cagent`; holds `session.db`, worktrees, plans, …) | +| `--help` | Show help for any command | + +### OpenTelemetry environment variables + +When `--otel` is enabled, the standard [OTel SDK env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) are honored (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, etc.). Two additional Docker Agent-specific variables control GenAI instrumentation: + +| Variable | Default | Description | +| -------- | ------- | ----------- | +| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | Set to `true` to capture prompt text, model responses, tool arguments, and tool results as span attributes. Off by default because these fields may contain PII. | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | (dual-emit) | Set to `gen_ai_latest_experimental` to emit only the spec-defined `gen_ai.*` keys from the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). The default dual-emit mode emits both `gen_ai.*` and legacy keys so existing dashboards continue working. | + +## Runtime Configuration Flags + +These flags are accepted by every command that loads an agent (`run`, `run --exec`, `new`, `eval`, `serve api`, `serve mcp`, `serve a2a`, `serve acp`, `serve chat`). They are listed once here to avoid repetition in the per-command tables above. + +| Flag | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `--working-dir <path>` | Set the working directory for the session (applies to tools and relative paths). | +| `--env-from-file <path>` | Load environment variables from file (repeatable). | +| `--flavor <name>` | Enable a config flavor, a YAML patch defined under the config's `flavors` section (repeatable, applied in order). See [Flavors](../../configuration/flavors/index.md). | +| `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally). | +| `--models-gateway <addr>` | Route model traffic through a gateway. Reads `DOCKER_AGENT_MODELS_GATEWAY` (legacy `CAGENT_MODELS_GATEWAY`) env var. | +| `--hook-pre-tool-use <cmd>` | Add a pre-tool-use hook command (repeatable). See [Hooks](../../configuration/hooks/index.md). | +| `--hook-post-tool-use <cmd>` | Add a post-tool-use hook command (repeatable). | +| `--hook-session-start <cmd>` | Add a session-start hook command (repeatable). | +| `--hook-session-end <cmd>` | Add a session-end hook command (repeatable). | +| `--hook-on-user-input <cmd>` | Add an on-user-input hook command (repeatable). | +| `--hook-stop <cmd>` | Add a stop hook command, fired when the model finishes responding (repeatable). | +| `--mcp-oauth-redirect-uri <url>` | Public HTTPS URL to advertise as the OAuth `redirect_uri` for MCP servers running in unmanaged OAuth mode. When set, docker-agent drives PKCE and the code exchange in-process instead of expecting the client to. See [Remote MCP](../remote-mcp/index.md) for details. | + +## Agent References + +Commands that accept a config support multiple reference types: + +| Type | Example | +| ------------- | ------------------------------------------- | +| Local file | `./agent.yaml` | +| OCI registry | `docker.io/username/agent:latest` | +| Hub shorthand | `myorg/agent:tag` | +| Alias | `pirate` (after `docker agent alias add`) | +| Default | (no argument) — uses project config or built-in default agent | + +> [!NOTE] +> **Debugging** +> +> Having issues? See [Troubleshooting](../../community/troubleshooting/index.md) for debug mode, log analysis, and common solutions. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md new file mode 100644 index 000000000000..80a55978a991 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md @@ -0,0 +1,66 @@ +--- +title: "Code Mode" +description: "Let an agent write JavaScript that orchestrates several tool calls in one turn instead of calling tools one at a time." +keywords: docker agent, ai agents, features, code mode +weight: 115 +canonical: https://docs.docker.com/ai/docker-agent/features/code-mode/ +--- + +_Let an agent write JavaScript that orchestrates several tool calls in one turn instead of calling tools one at a time._ + +## What Code Mode Is + +By default, a model calls one tool at a time: it emits a tool call, waits for the result, then decides what to call next. For a task that chains many tool calls together — "list every open issue, then for each one fetch its comments, then summarize" — that means one model round-trip per step. + +**Code Mode** replaces the agent's individual tools with a single tool, `run_tools_with_javascript`, that runs a JavaScript script. Every tool the agent would otherwise call directly is exposed to that script as a plain JavaScript function (synchronous — no `await`/`async` needed). The model writes a script that calls as many of them as it needs, combines and filters the results, and returns a single string — all in one tool call. + +## Enabling Code Mode + +Set `code_mode_tools: true` on an agent: + +```yaml +# examples/code_mode.yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Demonstrates the use of Code Mode with tools + instruction: Use your tool to help the user with their github requests. + code_mode_tools: true + commands: + demo: How many issues in docker/docker-agent have a number that is prime? + toolsets: + - type: mcp + ref: docker:github-official +``` + +Every toolset configured on the agent (the GitHub MCP server here) is wrapped: the model no longer sees the individual GitHub tools, only `run_tools_with_javascript`, with each wrapped tool documented as TypeScript interfaces, type aliases, and function declarations inside its description. + +To force Code Mode for every agent in a run regardless of their individual config, use the `--code-mode-tools` CLI flag (or the equivalent `--code-mode-tools` [runtime configuration flag](../cli/index.md#runtime-configuration-flags), accepted by `run`, `run --exec`, `serve api`, `serve mcp`, and the other commands that load an agent): + +```bash +$ docker agent run agent.yaml --code-mode-tools +``` + +## When It Helps + +Code Mode is worth enabling when an agent's task typically needs **many tool calls chained together**, especially with conditional logic or filtering in between — for example, paging through a large result set, cross-referencing several API calls, or reducing a large payload down to the few fields the model actually needs before it ever sees them. Each of those becomes one model turn instead of many, which cuts both latency and token spend on tool-call/response round-trips. + +It is not a general-purpose replacement for direct tool calls: for an agent that mostly makes one or two independent tool calls per turn, Code Mode adds the overhead of writing and reasoning about a script for no real benefit. + +## Limits & Security Notes + +- **One string result.** The script must return a string; use `console.*` inside the script to print debug information if something doesn't behave as expected — it comes back as `stdout`/`stderr` alongside the result. +- **Failures are diagnosable.** If the script throws or returns unexpectedly, the response includes the tool calls it made before failing (name, arguments, and result or error), so the model can see what happened and adjust the script on the next attempt. +- **Not every tool is wrapped.** Tools in the `todo` category are excluded from the script environment and stay directly callable as ordinary tools — Code Mode does not replace them. +- **The script runs in an embedded, sandboxed JS engine** ([goja](https://github.com/dop251/goja)), not Node.js or a browser: there is no filesystem, network, or process access beyond the tool functions injected into it. + +## Interaction With Permissions and Tool Approval + +[Permissions](../../configuration/permissions/index.md) and interactive tool-call approval are enforced when the **runtime dispatches a tool call requested by the model** — which, with Code Mode enabled, is only `run_tools_with_javascript` itself. The individual tool calls a script makes from inside that JavaScript are invoked directly and do **not** go through a second round of permission checks or approval prompts. + +In practice this means enabling `code_mode_tools` collapses the approval granularity from "one prompt per tool call" down to "one prompt for the whole script". Treat that single approval as authorizing everything the script's toolset could do: + +> [!WARNING] +> **Coarser approval granularity** +> +> Approving a `run_tools_with_javascript` call approves every tool it might invoke internally, including ones that would otherwise need a separate `ask` or be blocked by a `deny` pattern under [Permissions](../../configuration/permissions/index.md). If an agent's toolset includes anything destructive, consider whether Code Mode's coarser granularity is acceptable for that agent before enabling it. Delegating to a separate, non-Code-Mode agent isn't a way out either: [handoff](../../tools/handoff/index.md) and [transfer_task](../../tools/transfer-task/index.md) are themselves wrapped like any other tool once `code_mode_tools` is on, but they have no code-mode-compatible handler — the model's script gets `tool "handoff" is not available in code mode` if it tries to call them. This only rules out the model *choosing* to delegate from inside the script: a configured `force_handoff` target on the agent still runs deterministically after the agent's turn naturally stops, regardless of Code Mode, since it's applied by the runtime outside the tool-call dispatch path Code Mode replaces. Keep `code_mode_tools` off any agent whose model needs to hand off or transfer to one that holds a destructive toolset. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md new file mode 100644 index 000000000000..c90701dec2e4 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md @@ -0,0 +1,311 @@ +--- +title: "Evaluation" +description: "Measure agent quality with automated evaluations — tool call accuracy, response relevance, output size, and more." +keywords: docker agent, ai agents, features, evaluation +weight: 100 +canonical: https://docs.docker.com/ai/docker-agent/features/evaluation/ +aliases: + - /ai/docker-agent/evals/ +--- + +_Measure agent quality with automated evaluations — tool call accuracy, response relevance, output size, and more._ + +## Overview + +The `docker agent eval` command runs your agent against a set of recorded sessions and scores the results. Each eval session captures a user question, the expected tool calls, and criteria the response must satisfy. Docker Agent replays the question, compares the agent's behavior to expectations, and produces a report. + +> [!NOTE] +> **Container runtime required** +> +> Evaluations run inside containers for isolation. Each eval gets a clean environment with optional setup scripts. A running Docker-compatible container CLI/runtime is required: Docker Desktop or Docker Engine by default, or another Docker-compatible runtime such as Podman selected with `--container-runtime`. + +## Quick Start + +```bash +# Run evaluations for an agent +$ docker agent eval agent.yaml + +# Specify a custom evals directory +$ docker agent eval agent.yaml ./my-evals + +# Run with 8 concurrent evaluations +$ docker agent eval agent.yaml -c 8 + +# Only run evals matching a pattern +$ docker agent eval agent.yaml --only "auth*" + +# Repeat each eval 5 times to compute a baseline +$ docker agent eval agent.yaml --repeat 5 + +# Repeat a specific eval 5 times +$ docker agent eval agent.yaml --only "auth*" --repeat 5 + +# Use a Docker-compatible runtime such as Podman +$ docker agent eval agent.yaml --container-runtime podman +``` + +## Eval Directory Structure + +By default, Docker Agent looks for eval sessions in an `evals/` directory next to your agent config: + +```bash +my-agent/ +├── agent.yaml +└── evals/ + ├── 41b179a2-....json # Eval session 1 + ├── 5d83e247-....json # Eval session 2 + └── results/ # Output (auto-created) + ├── adjective-noun-1234.json + ├── adjective-noun-1234.log + ├── adjective-noun-1234.db + └── adjective-noun-1234-sessions.json +``` + +## Eval Session Format + +Each eval file is a JSON session that captures a complete conversation. The key fields for evaluation are the user message, the expected tool calls (recorded from a real session), and optional eval criteria: + +```json +{ + "id": "41b179a2-ed19-4ae2-a45d-95775aaa90f7", + "title": "Counting Files in Local Folder", + "messages": [ + { + "message": { + "message": { + "role": "user", + "content": "How many files in the local folder?" + } + } + }, + { + "message": { + "agent_name": "root", + "message": { + "role": "assistant", + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "name": "list_directory", + "arguments": "{\"path\":\"./\"}" + } + } + ] + } + } + }, + { + "message": { + "agent_name": "root", + "message": { + "role": "assistant", + "content": "There are 2 files in the local folder..." + } + } + } + ], + "evals": { + "relevance": [ + "The response mentions exactly 2 files", + "The response lists README.md and agent.yaml" + ], + "size": "S", + "working_dir": "my-project", + "setup": "echo 'hello' > test.txt" + } +} +``` + +## Eval Criteria + +The `evals` object inside each session controls what gets scored: + +| Field | Type | Description | +| ------------- | -------- | ----------------------------------------------------------------------------------------- | +| `relevance` | string[] | Statements that must be true about the agent's response. Scored by an LLM judge. | +| `size` | string | Expected response size: `S`, `M`, `L`, or `XL`. Compared against actual output length. | +| `working_dir` | string | Subdirectory under `evals/working_dirs/` to mount as the container's working directory. | +| `setup` | string | Shell script to run in the container before the agent executes (e.g., create test files). | + +## Scoring Metrics + +Docker Agent evaluates agents across three dimensions: + +| Metric | How It's Measured | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| **Tool Calls (F1)** | F1 score between the expected tool call sequence (from the recorded session) and the actual tool calls made by the agent. | +| **Relevance** | An LLM judge (configurable via `--judge-model`) evaluates whether each relevance statement is satisfied by the response. | +| **Size** | Whether the response length matches the expected size category (S/M/L/XL). | + +## Serve-safety verification and rollback + +When changing an agent served over MCP HTTP, chat, or A2A, add an evaluation that attempts an approval-requiring tool call and verifies the resolved safety policy and authentication behavior. Run the evaluation with the same explicit `--safety` setting used in deployment. If a rollout must be reversed, stop the affected listener, restore the prior agent configuration and explicit safety flag, then restart only after confirming non-loopback listeners still require authentication. Do not restore an unauthenticated network listener as a rollback shortcut. + +## Creating Eval Sessions + +The easiest way to create eval sessions is from real conversations: + +1. Run your agent interactively: `docker agent run agent.yaml` +2. Have a conversation that tests the behavior you care about +3. Use the `/eval` slash command in the TUI to save the session as an eval file +4. Edit the generated JSON to add `evals` criteria (relevance, size, etc.) + +> [!TIP] +> Start with tool call scoring (automatic from recorded sessions), then add relevance criteria for the responses you care most about. + +## CLI Flags + +```bash +$ docker agent eval <agent-file>|<registry-ref> [<eval-dir>|./evals] +``` + +| Flag | Default | Description | +| ------------------- | --------------------------- | ----------------------------------------------------------------- | +| `-c, --concurrency` | num CPUs | Number of concurrent evaluation runs | +| `--judge-model` | `anthropic/claude-opus-5` | Model for LLM-as-a-judge relevance scoring | +| `--output` | `<eval-dir>/results` | Directory for results, logs, and session databases | +| `--only` | (all) | Only run evals with file names matching these patterns | +| `--base-image` | (default) | Custom base image for eval containers (see [Custom Base Images](#custom-base-images)) | +| `--container-runtime` | `docker` | Container runtime executable for building and running evaluations (e.g. `podman`) | +| `--keep-containers` | `false` | Keep containers after evaluation (don't remove with `--rm`) | +| `-e, --env` | (none) | Environment variables to pass to container (`KEY` or `KEY=VALUE`) | +| `--repeat` | `1` | Number of times to repeat each evaluation (useful for computing baselines) | +| `--baseline` | (none) | Compare against a previously saved run JSON and exit non-zero on regression (see [Regression gate](#regression-gate)) | +| `--regression-tolerance` | `0` | How far an aggregate quality rate may fall before `--baseline` reports a regression (0–1) | + +### Regression gate + +`--baseline` compares the run against a previous one and exits non-zero when +quality regressed, so an eval suite can gate CI: + +```console +$ docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json +``` + +The baseline is the run JSON written by a previous invocation — +`<output>/<run-name>.json` — so there is no separate artifact to produce. + +Four rules decide the verdict, and they are worth knowing before wiring this +into CI: + +- **The tolerance governs aggregate rates only.** An LLM judge does not return + the same score twice, so without a tolerance the gate flaps. `--regression-tolerance 0.05` + lets an aggregate rate fall five points before it counts. +- **An evaluation that passed and now fails always gates**, regardless of the + tolerance. That transition is the signal the gate exists to catch, so it is + never absorbed. +- **Cost is reported but never gates.** A provider price change is not a quality + regression. +- **An added *failing* evaluation gates** via the aggregate rate, even though no + existing evaluation regressed. A suite that got worse should say so — but it + means committing a known-failing eval needs a tolerance bump or a fix. + +A baseline that carries no evaluations, or a run that produced none (an +`--only` pattern that matched nothing), is rejected rather than reported as +passing: a gate that cannot fail is worse than no gate. + +### Provider Credentials + +Eval containers are isolated from your host environment. Dedicated model +provider API keys (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) are +forwarded into eval containers automatically, so most provider setups work +without extra flags. + +> [!WARNING] +> **`GITHUB_TOKEN` and `GH_TOKEN` are not forwarded automatically** +> +> GitHub tokens are broad credentials (git, `gh`, CI, packages), not dedicated +> model API keys, so for security reasons Docker Agent does not forward them +> into eval containers — even when they are set in your shell or in +> `~/.config/cagent/.env`. If your agent uses the `github-copilot` provider, +> pass the token explicitly by name: +> +> ```bash +> docker agent eval agent.yaml ./evals -e GITHUB_TOKEN +> ``` +> +> When using a custom env file, both flags are required: +> +> ```bash +> docker agent eval agent.yaml ./evals \ +> --env-from-file /path/to/secrets.env \ +> -e GITHUB_TOKEN +> ``` + +Note that the LLM judge runs on the host, not inside the eval container. If +the token is not forwarded, judge validation can succeed while every +evaluated agent run fails to authenticate. + +### Custom Base Images + +When `--base-image` is set, the eval harness builds a derived image on top of your base image at evaluation time. Two things happen automatically: + +1. **The docker-agent binary is injected** — it is copied from `docker/docker-agent:edge` into the derived image at build time, so you don't need to include it in your base image. +2. **The entrypoint is overridden** — Docker Agent replaces your base image's entrypoint with its own `/run.sh` wrapper. + +Your base image therefore only needs to provide the runtime environment: language runtimes, installed dependencies, test fixtures, the appropriate working directory, and so on. Any `ENTRYPOINT` or `CMD` defined in your base image is ignored. + +## Output + +After a run completes, Docker Agent produces: + +- **Console summary** — Pass/fail status per eval with metric breakdowns +- **JSON results** — Full structured results for programmatic analysis +- **SQLite database** — Complete sessions for detailed investigation and debugging +- **Sessions JSON** — Exported session data for analysis +- **Log file** — Debug-level log of the entire evaluation run + +> [!TIP] +> **Debugging Failed Evals** +> +> Use `--keep-containers` to preserve containers after evaluation. You can then inspect them with your selected runtime's `exec` command (`docker exec` by default, `podman exec` with `--container-runtime podman`) to understand why an eval failed. The session database (`.db` file) contains the full conversation history for each eval. + +```bash +$ docker agent eval demo.yaml ./evals + + ✓ Counting Files in Local Folder + ✓ tool calls ✓ relevance 2/2 + ✓ Checking the Content of README.md File + ✓ tool calls ✓ relevance 1/1 + +✅ Tool Calls: 100.0% avg F1 (2 evals) +✅ Relevance: 3/3 passed (100.0%) + +Total Cost: $0.012345 +Total Time: 12s + +Sessions DB: ./evals/results/happy-panda-1234.db +Sessions JSON: ./evals/results/happy-panda-1234-sessions.json +Log: ./evals/results/happy-panda-1234.log +``` + +## Example + +Here's a minimal evaluation setup: + +```yaml +# agent.yaml +agents: + root: + model: openai/gpt-4o + description: Test agent + instruction: You know how to read/write and list files. + toolsets: + - type: filesystem +``` + +```bash +# Create evals from interactive sessions +$ docker agent run agent.yaml +# ... have conversations, then use /eval to save them + +# Run the evaluations +$ docker agent eval agent.yaml ./evals +``` + +> [!NOTE] +> **See also** +> +> Use `/eval` in the [TUI](../tui/index.md) to create eval sessions from conversations. See the [CLI Reference](../cli/index.md) for all `docker agent eval` flags. Example eval configs are in [examples/eval](https://github.com/docker/docker-agent/tree/main/examples/eval) on GitHub. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md new file mode 100644 index 000000000000..b091bfea3ec9 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md @@ -0,0 +1,287 @@ +--- +title: "Coding Harnesses" +description: "Delegate coding tasks to external AI coding CLIs (Claude Code, Codex, opencode) as sub-agents." +keywords: docker agent, ai agents, features, coding harnesses +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/features/harnesses/ +--- + +_Delegate coding tasks to external AI coding CLIs (Claude Code, Codex, opencode) as sub-agents._ + +## Overview + +A **harness** agent delegates its work to an external coding CLI — `claude` (Claude Code), `codex` (OpenAI Codex), `opencode`, or `pi` — instead of calling a model API directly. The external CLI drives the coding loop while Docker Agent provides orchestration, hooks, permissions, and distribution. + +This pattern gives you the best of both worlds: + +- **External CLI strengths** — deep IDE integration, specialized coding workflows, CLI-native tool access +- **Docker Agent strengths** — multi-agent coordination, hook-based auditing and policy enforcement, permission controls, OCI distribution, and the full agent config schema + +> [!NOTE] +> **When to use harnesses** +> +> Use a harness when you want a Claude Code / Codex / opencode session to act as a sub-agent inside a larger Docker Agent workflow — for example, an orchestrator that plans work and delegates coding tasks to specialized harness agents. + +## Prerequisites + +The external CLI must be installed and available on `PATH` before starting Docker Agent: + +| Harness type | Required binary | Install | +| --- | --- | --- | +| `claude-code` | `claude` | [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code) | +| `codex` | `codex` | [github.com/openai/codex](https://github.com/openai/codex) | +| `opencode` | `opencode` | [opencode.ai](https://opencode.ai) | +| `pi` | `pi` | Refer to the `pi` CLI documentation for installation instructions. | + +Docker Agent will report an error at session start if the required binary is not found. The `claude-code` harness additionally needs the CLI to be logged in — see [Authentication](#authentication-claude-subscription-no-api-key) below. + +## Configuration + +Add a `harness:` block to any agent definition to make it harness-backed: + +```yaml +agents: + coder: + description: A Claude Code harness agent + harness: + type: claude-code +``` + +Harness agents do **not** need a `model:` field — the external CLI manages its own model selection. + +### Field Reference + +| Field | Applies to | Type | Description | +| --- | --- | --- | --- | +| `type` | all | string | **Required.** One of `claude-code`, `codex`, `opencode`, `pi` | +| `model` | all | string | Optional model override forwarded to the CLI. When omitted, the CLI uses its own default model. | +| `effort` | `claude-code` | string | Reasoning effort: `low` \| `medium` \| `high` \| `xhigh` \| `max` — forwarded as `--effort`. When omitted, Claude Code uses its own default. | +| `agent` | `opencode` | string | opencode agent profile name | +| `thinking` | `opencode` | boolean | Enable extended thinking — forwarded as `--thinking` | + +### Claude Code + +```yaml +agents: + coder: + description: Claude Code coding agent + harness: + type: claude-code + model: claude-sonnet-4-5 # optional: alias (sonnet, opus, haiku) or full model ID + effort: high # low | medium | high | xhigh | max +``` + +- `model` accepts whatever the `claude` CLI accepts for `--model`: an alias + like `sonnet`, `opus`, or `haiku`, or a full model ID like + `claude-sonnet-4-5`. Omit it to use Claude Code's own default model. This is + **not** a Docker Agent `provider/model` reference — the harness model never + goes through Docker Agent's model providers or routing. +- `effort` is forwarded as `--effort` and must be one of `low`, `medium`, + `high`, `xhigh`, or `max`. Omit it to use Claude Code's own default. + +#### Authentication (Claude subscription, no API key) + +The `claude-code` harness runs the official CLI with the CLI's **own login**. +A Claude (claude.ai) subscription sign-in is all it needs — no +`ANTHROPIC_API_KEY` and no Docker Agent model credential are required for the +harness agent itself. Log in once: + +```bash +$ claude auth login --claudeai # interactive, opens a browser +$ claude auth status --text # verify the login +``` + +The login is stored per OS user by the CLI (in its own configuration and, on +macOS, the keychain) and is found via `HOME` and the process environment. Run +the login **as the same OS user and environment that run `docker agent`** — a +login made under another user, container, or `sudo` context is invisible to +the harness. Docker Agent never reads, copies, or stores the CLI's tokens; it +only launches `claude`, which authenticates itself. + +If the CLI is not logged in when a harness agent runs, the `claude` subprocess +fails at session start and the agent reports a harness error — Docker Agent +never opens a browser or starts a login on its own. Diagnose and fix with: + +```bash +$ docker agent doctor ./agent.yaml # checks install + login for claude-code harness files +$ docker agent setup # pick "Claude Code harness" to be walked through it +``` + +`docker agent doctor <file>` probes the CLI only when the file declares a +`claude-code` harness, and reports installation, version, and safe login +metadata (auth method, API provider, subscription type — never your email, +organization, or tokens). `docker agent setup` offers to run the official +`claude auth login --claudeai` for you (only after you confirm) and writes a +ready-to-run `claude-code-agent.yaml`. + +> [!WARNING] +> **The harness bypasses Claude Code's permission prompts** +> +> Docker Agent runs the CLI non-interactively with its own tools and passes +> `--dangerously-skip-permissions`: Claude Code edits files and runs commands +> without asking. Only point a harness agent at a repository you trust, and +> prefer isolation — `docker agent run --worktree` runs it on an isolated git +> worktree, keeping its changes off your checkout (a worktree with work, or +> from a non-interactive run, is kept for inspection per the normal cleanup +> rules). `docker agent run --sandbox` does not automatically carry the +> `claude` CLI or its login into the sandbox, so it cannot isolate the +> harness unless the sandbox image is separately provisioned and +> authenticated. + +### Codex + +```yaml +agents: + coder: + description: Codex coding agent + harness: + type: codex + model: o4-mini # optional model override +``` + +### opencode + +```yaml +agents: + coder: + description: opencode coding agent + harness: + type: opencode + agent: my-profile # optional agent profile + thinking: true # enable extended thinking +``` + +## What Does NOT Work + +Harness agents bypass the Docker Agent model pipeline entirely. As a result: + +- **Docker Agent toolsets are inactive.** The external CLI provides its own tools — filesystem, shell, etc. Any `toolsets:` defined on a harness agent are silently ignored. +- **`model:` routing is unavailable.** The harness CLI manages model selection; Docker Agent's `models:` configuration and routing rules do not apply to harness agents. +- **Token usage tracking depends on the external CLI.** Docker Agent records usage when the CLI reports it (Claude Code and Codex both report usage data). If the CLI does not emit usage data, the session will show zero token usage. + +> [!WARNING] +> **No Docker Agent toolsets inside a harness** +> +> Do not configure `toolsets:` on a harness agent — they are silently ignored. If you need Docker Agent toolsets alongside external coding capabilities, use a standard sub-agent with `transfer_task` rather than a harness. + +## Hook Behavior + +Hooks work normally on harness agents, including `before_llm_call` and `after_llm_call`. `before_llm_call` runs before the prompt is forwarded to the external CLI and can block or rewrite the run; `after_llm_call` fires after the CLI returns its final response. + +The `model_id` field in hook payloads is set to the harness label (e.g. `claude-code`) rather than a canonical `provider/model` string. This applies to `before_llm_call`, `after_llm_call`, and any other event that carries `model_id`. + +See [Hooks](../../configuration/hooks/index.md) for the full hook reference. + +## Recipe: Root Harness Agent + +The simplest setup: a single root agent that hands everything to Claude Code. +No `models:` section, no API key — the CLI's subscription login does the work. +This is exactly the file `docker agent setup` generates for the Claude Code +harness path (as `claude-code-agent.yaml`). + +```yaml +# claude-code-agent.yaml +agents: + root: + description: Claude Code running on your Claude subscription + harness: + type: claude-code + effort: medium # low | medium | high | xhigh | max; omit for the Claude Code default + # model: claude-sonnet-4-5 # optional; omit for the Claude Code default +``` + +```bash +$ docker agent run claude-code-agent.yaml +$ docker agent doctor claude-code-agent.yaml # verify the CLI is installed and logged in +``` + +## Recipe: Orchestrator + Harness Sub-Agents (Sequential) + +An orchestrator plans the work and delegates to specialized harness agents one at a time. Each coding agent runs in its own sub-session and reports results back. + +```yaml +# examples/coding_harnesses.yaml + +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + +agents: + root: + model: claude + description: Orchestrator that plans and delegates coding tasks + instruction: | + You are a project orchestrator. Break down coding requests into + focused tasks and delegate each task to the most appropriate + coding agent. Collect results and synthesize a final summary. + sub_agents: + - claude-coder + - codex-coder + + claude-coder: + description: Claude Code specialist for complex refactors + harness: + type: claude-code + model: claude-sonnet-4-5 + effort: xhigh + + codex-coder: + description: Codex specialist for code generation + harness: + type: codex +``` + +Only the orchestrator's `model: claude` needs an Anthropic API key — the +`claude-coder` harness agent authenticates through the CLI's own subscription +login. + +The root agent calls `transfer_task` to send work to a harness sub-agent, waits for the result, and continues. See the [full example on GitHub](https://github.com/docker/docker-agent/blob/main/examples/coding_harnesses.yaml). + +## Recipe: Parallel Harness Dispatch + +Combine the `background_agents` toolset with harness sub-agents to dispatch multiple coding tasks simultaneously: + +```yaml +# examples/coding_harness_background_agents.yaml + +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + +agents: + root: + model: claude + description: Orchestrator that fans out coding tasks in parallel + instruction: | + Use background agents to run multiple coding tasks at once. + Dispatch all tasks, then collect results when each finishes. + sub_agents: + - claude-coder + - codex-coder + toolsets: + - type: background_agents + + claude-coder: + description: Frontend specialist (Claude Code) + harness: + type: claude-code + effort: medium + + codex-coder: + description: Backend specialist (Codex) + harness: + type: codex +``` + +The orchestrator calls `run_background_agent` for each task, monitors progress with `list_background_agents`, and collects results with `view_background_agent`. See the [full example on GitHub](https://github.com/docker/docker-agent/blob/main/examples/coding_harness_background_agents.yaml). + +For the general background agents reference, see [Background Agents](../../tools/background-agents/index.md). + +## See Also + +- [Multi-Agent Systems](../../concepts/multi-agent/index.md) — orchestration patterns +- [Background Agents](../../tools/background-agents/index.md) — parallel task dispatch +- [Hooks](../../configuration/hooks/index.md) — auditing and policy enforcement +- [Agent Configuration](../../configuration/agents/index.md) — full agent schema reference diff --git a/_vendor/github.com/docker/docker-agent/docs/features/mcp-mode/index.md b/_vendor/github.com/docker/docker-agent/docs/features/mcp-mode/index.md new file mode 100644 index 000000000000..9e3ae0bf69eb --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/mcp-mode/index.md @@ -0,0 +1,134 @@ +--- +title: "MCP Mode" +description: "Expose your Docker Agent agents as MCP tools for use in Claude Desktop, Claude Code, and other MCP-compatible applications." +keywords: docker agent, ai agents, features, mcp mode +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/features/mcp-mode/ +--- + +_Expose your Docker Agent agents as MCP tools for use in Claude Desktop, Claude Code, and other MCP-compatible applications._ + +## Why MCP Mode? + +The `docker agent serve mcp` command makes your agents available to any application that supports the [Model Context Protocol](https://modelcontextprotocol.io/). This means you can: + +- Use custom agents directly within **Claude Desktop** or **Claude Code** +- Share specialized agents across different applications +- Build reusable agent teams consumable from any MCP client +- Integrate domain-specific agents into existing workflows + +> [!NOTE] +> **What is MCP?** +> +> The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools. See also [Remote MCP Servers](../remote-mcp/index.md) for connecting to cloud services. + +## Basic Usage + +```bash +# Expose a local config (stdio transport, the default) +$ docker agent serve mcp ./agent.yaml + +# Expose from a registry +$ docker agent serve mcp myorg/agent:tag + +# Set the working directory +$ docker agent serve mcp ./agent.yaml --working-dir /path/to/project +``` + +## Transports + +By default, `serve mcp` uses the stdio transport — ideal for clients that spawn the server as a subprocess (Claude Desktop, Claude Code, Cursor, …). + +To expose the MCP server over streaming HTTP instead, pass `--http`: + +```bash +# Streaming HTTP transport on the default 127.0.0.1:8081 +$ docker agent serve mcp ./agent.yaml --http + +# Override the listen address / port; non-loopback HTTP requires authentication +$ docker agent serve mcp ./agent.yaml --http --listen 0.0.0.0:9090 --auth-token "$MCP_BEARER_TOKEN" +``` + +| Flag | Default | Description | +| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ | +| `--http` | `false` | Use streaming HTTP transport instead of stdio. | +| `-l`, `--listen` | `127.0.0.1:8081` | Address to listen on when `--http` is enabled. | +| `-a`, `--agent` | all agents | Expose a single named agent instead of every agent in the config. | +| `--tool-name` | (none) | Override the MCP tool identifier clients call (defaults to agent name); only valid when exposing one agent. | +| `--auth-token` | (none) | Require this Bearer token for HTTP requests. Required for non-loopback HTTP unless explicitly overridden. | +| `--insecure-no-auth` | `false` | Permit unauthenticated non-loopback HTTP. Use only behind a trusted authentication boundary. | +| `--safety` | `restricted` | Tool safety policy for HTTP requests. CLI value overrides agent/runtime configuration. | +| `--mcp-keepalive` | `0` | Interval between MCP keep-alive pings (e.g. `30s`); `0` disables keep-alive. | + +Runtime configuration flags such as `--working-dir`, `--env-from-file`, `--models-gateway`, and hook flags are also available — see the [CLI reference](../cli/index.md). + +## HTTP security + +HTTP MCP defaults to loopback binding. A non-loopback `--listen` address requires `--auth-token`; use `--insecure-no-auth` only when a trusted reverse proxy or network boundary authenticates clients. The safety policy is resolved in this order: `--safety`, agent configuration, runtime configuration, then `restricted`. These HTTP-only flags do not affect stdio or `--attach` operation. + +## Using with Claude Desktop + +Add a configuration to your Claude Desktop MCP settings file: + +- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` + +```json +{ + "mcpServers": { + "myagent": { + "command": "/usr/local/bin/docker", + "args": [ + "agent", + "serve", + "mcp", + "myorg/coder", + "--working-dir", + "/home/user/projects" + ], + "env": { + "ANTHROPIC_API_KEY": "your_key_here", + "OPENAI_API_KEY": "your_key_here" + } + } + } +} +``` + +Restart Claude Desktop after updating the configuration. + +## Using with Claude Code + +```bash +$ claude mcp add --transport stdio myagent \ + --env OPENAI_API_KEY=$OPENAI_API_KEY \ + --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ + -- docker agent serve mcp myorg/agent:tag --working-dir $(pwd) +``` + +## Multi-Agent in MCP Mode + +When you expose a multi-agent configuration via MCP, each agent becomes a separate tool in the MCP client: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Main coordinator + sub_agents: [designer, engineer] + designer: + model: openai/gpt-5-mini + description: UI/UX design specialist + engineer: + model: anthropic/claude-sonnet-4-5 + description: Software engineer +``` + +All three agents (`root`, `designer`, `engineer`) appear as separate tools in Claude Desktop or Claude Code. + +## Troubleshooting + +- **Agents not appearing:** Verify the `docker-agent` binary path and restart the MCP client +- **Permission errors:** Ensure `docker-agent` has execute permissions (`chmod +x`) +- **Missing API keys:** Pass all required keys in the `env` section +- **Working directory issues:** Verify the `--working-dir` path exists and is accessible diff --git a/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md new file mode 100644 index 000000000000..564233bd57c7 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md @@ -0,0 +1,308 @@ +--- +title: "Remote MCP Servers" +description: "Connect Docker Agent to cloud services via remote MCP servers with built-in OAuth authentication." +keywords: docker agent, ai agents, features, remote mcp servers +weight: 120 +canonical: https://docs.docker.com/ai/docker-agent/features/remote-mcp/ +--- + +_Connect Docker Agent to cloud services via remote MCP servers with built-in OAuth authentication._ + +## Overview + +Docker Agent supports connecting to remote MCP servers over **Streamable HTTP**, **SSE** (Server-Sent Events), and **Unix domain sockets**. Streamable HTTP is the current recommended transport for most hosted MCP servers. Many popular services offer MCP endpoints with OAuth — Docker Agent handles the authentication flow automatically. + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp.linear.app/mcp" + transport_type: "streamable" +``` + +## Unix Domain Sockets + +Use a `unix://` URL to connect to an MCP server listening on a local Unix socket. This is useful when running Docker Agent inside a container and exposing an MCP server from the host via a bind-mounted socket: + +```yaml +toolsets: + - type: mcp + remote: + url: "unix:///tmp/mcp-notify.sock" + transport_type: "streamable" +``` + +The path after `unix://` is the absolute path to the socket file. Configured `headers` are forwarded over the socket connection. OAuth discovery is not supported for Unix socket URLs. + +> [!TIP] +> **OAuth flow** +> +> When you connect to a remote MCP server that requires OAuth, Docker Agent opens your browser automatically for authentication. Tokens are cached for subsequent sessions. + +> [!TIP] +> **Cancelling the authorization dialog** +> +> If you dismiss the OAuth authorization dialog, the request is cancelled cleanly — no repeated prompts appear. The agent will report that authorization was declined. To try again, simply re-enable the server or repeat the request that triggered the flow. + +## Configuration + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp.example.com/mcp" + transport_type: "streamable" # or "sse" for legacy servers + headers: + Authorization: "Bearer ${env.MY_TOKEN}" # resolved per request + # Optional: use only for trusted internal/private MCP or OAuth endpoints. + allow_private_ips: true +``` + +For full configuration details, see the [Tool Config](../../configuration/tools/index.md) page. + +Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk. + +> [!NOTE] +> **Headers forwarded during OAuth discovery** +> +> Configured `headers` are forwarded to OAuth protected-resource-metadata discovery requests directed at the MCP server's own host — not to third-party authorization servers. This allows services like Grafana Cloud that require a routing header (e.g. `X-Grafana-URL`) on the discovery request to scope the OAuth flow correctly. Headers are never sent to a different host than the one in `remote.url`. + +> [!NOTE] +> **Per-request header template expansion** +> +> Header values in `remote.headers` support `${env.VAR}` and `${headers.NAME}` placeholders. Both are resolved on every outbound HTTP request (not just once at initialization), so short-lived credentials and forwarded caller headers always reflect the latest values: +> +> - `${env.VAR}` — reads the named environment variable. Useful for credentials stored in a secret manager that rotates them in-process. +> - `${headers.NAME}` — forwards the named header from the caller's incoming HTTP request. Only meaningful when Docker Agent is running as an API server (`docker agent serve api`) and a client passes authentication headers that the upstream MCP server also accepts. + +> [!NOTE] +> **Automatic reconnection after idle timeouts** +> +> Remote MCP connections (Streamable HTTP / SSE) automatically reconnect after the server closes an idle connection — no configuration needed. Services like Notion and Linear close idle connections periodically; Docker Agent detects the clean close and reconnects with exponential backoff. To tune reconnect behaviour or disable reconnection entirely, use the [`lifecycle` block](../../configuration/tools/index.md#toolset-lifecycle). + +> [!NOTE] +> **Automatic recovery from revoked or rotated OAuth tokens** +> +> If a remote MCP server rejects the cached token with a `401 invalid_token` error (for example, because the token was revoked or rotated server-side), Docker Agent handles the failure automatically: +> +> - **Silent refresh:** when a refresh token is available, Docker Agent silently exchanges it for a new access token and replays the request — no user interaction required. +> - **Re-authentication prompt:** when the refresh token is absent or has also expired, the toolset transitions to a "needs re-auth" state and surfaces an OAuth prompt on your next message (exactly like the first-time flow). +> +> Either way, the agent never burns 5 reconnect attempts on an auth failure — it fails fast and either refreshes silently or defers to interactive re-auth. If you want to trigger re-auth immediately without waiting for the next message, run `/toolset-restart <name>` from the TUI. + +### OAuth for servers without Dynamic Client Registration + +Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — no configuration is needed, Docker Agent handles the flow for you. + +For servers that do **not** support DCR, Docker Agent falls back automatically: + +1. **Interactive credential prompt**: Docker Agent presents a dialog asking for your `client_id` (required) and optionally a `client_secret`. This covers servers that require pre-registered app credentials but don't advertise them via DCR. +2. **Explicit `oauth:` block** (recommended when you know the credentials in advance): add the block described below to skip the interactive prompt and supply credentials directly in config. + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp.example.com/mcp" + transport_type: "streamable" + oauth: + clientId: "my-app-client-id" + clientSecret: "my-app-client-secret" # optional (public clients may omit) + callbackPort: 8765 # optional; picks a free port otherwise + scopes: # optional; server-specific + - read + - write +``` + +| Field | Type | Required | Description | +| -------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------ | +| `clientId` | string | ✗ | OAuth client ID registered with the remote MCP server. When omitted, Docker Agent uses Dynamic Client Registration or prompts interactively. | +| `clientSecret` | string | ✗ | OAuth client secret. Requires `clientId`. Omit for public clients using PKCE. | +| `callbackPort` | integer | ✗ | Local port to receive the OAuth redirect. If omitted, Docker Agent picks a random free port. | +| `scopes` | array[string] | ✗ | Scopes to request during the authorization step. Values are server-specific. | +| `callbackRedirectURL` | string | ✗ | Custom OAuth redirect URI. Useful when the auth server requires HTTPS or a pre-registered URL. The literal placeholder `${callbackPort}` is replaced with the actual local callback port. See below. | + +Secrets should be stored in a credential helper or environment variable rather than committed — see [Secrets](../../guides/secrets/index.md) for interpolation patterns. + +> [!TIP] +> The `oauth:` block also works **without** `clientId`. Use it to pin the callback port, request specific scopes, or set a custom redirect URL while still letting Docker Agent obtain the client ID via Dynamic Client Registration (or the interactive prompt). + +### Custom redirect URI (`callbackRedirectURL`) + +Some authorization servers require the OAuth `redirect_uri` to be HTTPS or to match a URL that was pre-registered during app creation — neither of which plays nicely with a locally-bound loopback address such as `http://127.0.0.1:8765/callback`. + +To work around this, set `callbackRedirectURL` to a public URL that redirects back to the local callback server. The literal placeholder `${callbackPort}` is substituted with the actual port the local callback server is listening on (either `callbackPort` when set, or the randomly-assigned port otherwise). + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp.example.com/mcp" + transport_type: "streamable" + oauth: + clientId: "my-app-client-id" + callbackPort: 8765 + # Advertise this URL to the authorization server. The external + # service at redirect.example.com is expected to 302-redirect the + # browser to http://127.0.0.1:8765/callback preserving the query + # string (code, state, …). + callbackRedirectURL: "https://redirect.example.com/cb?port=${callbackPort}" +``` + +The local callback server still listens on the loopback interface on `callbackPort`; only the `redirect_uri` advertised to the authorization server changes. + +**Validation rules:** + +- The URL must be absolute (scheme + host) once `${callbackPort}` has been substituted. +- Only `http` and `https` schemes are accepted. +- `http` is only allowed when the host is a loopback address (`127.0.0.1`, `::1`, `localhost`); any other host must use `https` to avoid exposing the authorization `code` on the wire (RFC 8252 §7.3). + +### Unmanaged OAuth flow (server mode) + +When running `docker agent serve api` (no local browser, no callback server), the runtime delegates the OAuth dance to the connected client via an MCP elicitation. There are two sub-behaviors, selected by the `--mcp-oauth-redirect-uri` flag: + +- **`--mcp-oauth-redirect-uri=<URL>` set** (recommended for hosts like Docker Desktop): the runtime generates `state` + PKCE + (optional) Dynamic Client Registration in-process, builds the full authorize URL, and emits an elicitation whose `Meta` includes: + + | Key | Value | + | ---------------------------- | ---------------------------------------------------------------- | + | `docker-agent/type` | `"oauth_flow"` | + | `docker-agent/server_url` | The MCP server URL (for display / favicon) | + | `docker-agent/authorize_url` | The full URL the client should open in the user's browser | + | `docker-agent/state` | The `state` value the client must echo back when replying | + | `auth_server` | Issuer of the authorization server | + | `auth_server_metadata` | RFC 8414 authorization-server metadata document | + | `resource_metadata` | RFC 9728 protected-resource metadata document | + + The client opens the browser at the URL provided in the `docker-agent/authorize_url` meta field, receives the OAuth callback at whatever endpoint the configured `redirect_uri` resolves to (typically a host-controlled bouncer that 302s into a deeplink), and replies to the elicitation with `accept` and `Content = {"code": "...", "state": "..."}`. The runtime verifies the `state`, exchanges the `code` at the token endpoint (using the same `redirect_uri` for RFC 6749 §4.1.3 binding), stores the token, and replays the original MCP request with `Authorization: Bearer ...`. + +- **Flag not set** (client-driven): the runtime emits the elicitation meta below and expects the client to drive the OAuth flow itself (PKCE, DCR, token exchange) and reply with `Content = {"access_token": "...", "refresh_token": "...", ...}`: + + | Key | Value | + | ---------------------------- | ---------------------------------------------------------------- | + | `docker-agent/type` | `"oauth_flow"` | + | `docker-agent/server_url` | The MCP server URL (for display / favicon) | + | `auth_server` | Issuer of the authorization server | + | `auth_server_metadata` | RFC 8414 authorization-server metadata document | + | `resource_metadata` | RFC 9728 protected-resource metadata document | + +The client-driven `{access_token, ...}` reply shape is still accepted on the `--mcp-oauth-redirect-uri` path too: a client that prefers to do the exchange itself can ignore the `docker-agent/authorize_url`/`docker-agent/state` keys. + +A per-toolset `callbackRedirectURL` (in the YAML) overrides the runtime-wide `--mcp-oauth-redirect-uri` for that toolset. + +> [!WARNING] +> **Security note** +> +> The `POST /api/mcp-oauth/callback` route is open by default (no auth required) when `--auth-token` is unset. State values are 128-bit opaque tokens, so brute-force is infeasible, but a state value that leaks (e.g. via debug logs or a compromised host) could be exploited by an attacker to inject a code. Set `--auth-token` when `docker agent serve api` listens on a network-reachable interface. When set, `--auth-token` enforces Bearer-token authentication on all API routes including this callback endpoint. + +## Project Management & Collaboration + +| Service | URL | Transport | Description | +| ---------- | ---------------------------------- | --------- | ------------------------------------- | +| Asana | `https://mcp.asana.com/sse` | sse | Task and project management | +| Atlassian | `https://mcp.atlassian.com/v1/mcp/authv2` | streamable | Jira, Confluence integration | +| Linear | `https://mcp.linear.app/mcp` | streamable | Issue tracking and project management | +| Monday.com | `https://mcp.monday.com/sse` | sse | Work management platform | +| Intercom | `https://mcp.intercom.com/sse` | sse | Customer communication platform | + +## Development & Infrastructure + +| Service | URL | Transport | Description | +| ------------------------ | ---------------------------------------------- | ---------- | --------------------------------- | +| GitHub | `https://api.githubcopilot.com/mcp` | sse | Version control and collaboration | +| Buildkite | `https://mcp.buildkite.com/mcp` | streamable | CI/CD platform | +| Netlify | `https://netlify-mcp.netlify.app/mcp` | streamable | Web hosting and deployment | +| Vercel | `https://mcp.vercel.com/` | sse | Web deployment platform | +| Cloudflare Bindings | `https://bindings.mcp.cloudflare.com/sse` | sse | Edge computing resources | +| Cloudflare Observability | `https://observability.mcp.cloudflare.com/sse` | sse | Monitoring and analytics | +| Grafbase | `https://api.grafbase.com/mcp` | streamable | GraphQL backend platform | +| Neon | `https://mcp.neon.tech/sse` | sse | Serverless Postgres database | +| Prisma | `https://mcp.prisma.io/mcp` | streamable | Database ORM and toolkit | +| Sentry | `https://mcp.sentry.dev/sse` | sse | Error tracking and monitoring | + +## Content & Media + +| Service | URL | Transport | Description | +| ---------- | ------------------------------------------------- | ---------- | --------------------------------- | +| Canva | `https://mcp.canva.com/mcp` | streamable | Design and graphics platform | +| Miro | `https://mcp.miro.com/` | streamable | Collaborative whiteboard platform (Enterprise plan required; see [official docs](https://developers.miro.com/docs/miro-mcp)) | +| Cloudinary | `https://asset-management.mcp.cloudinary.com/sse` | sse | Media management and optimization | +| InVideo | `https://mcp.invideo.io/sse` | sse | Video creation platform | +| Webflow | `https://mcp.webflow.com/sse` | sse | Website builder and CMS | +| Wix | `https://mcp.wix.com/sse` | sse | Website builder platform | +| Notion | `https://mcp.notion.com/mcp` | streamable | Documentation and knowledge base | + +## Communication & Voice + +| Service | URL | Transport | Description | +| ----------- | ----------------------------------- | ---------- | --------------------------- | +| Fireflies | `https://api.fireflies.ai/mcp` | streamable | Meeting transcription | +| Listenetic | `https://mcp.listenetic.com/v1/mcp` | streamable | Audio intelligence platform | +| Carbonvoice | `https://mcp.carbonvoice.app` | sse | Voice communication tools | +| Telnyx | `https://api.telnyx.com/v2/mcp` | streamable | Communications platform | +| Dialer | `https://getdialer.app/sse` | sse | Phone communication tools | + +## Storage & File Management + +| Service | URL | Transport | Description | +| ------- | ----------------------------------- | --------- | ------------------------ | +| Box | `https://mcp.box.com` | sse | Cloud content management | +| Egnyte | `https://mcp-server.egnyte.com/sse` | sse | Enterprise file sharing | + +## Business & Finance + +| Service | URL | Transport | Description | +| ------------- | ----------------------------------------- | ---------- | -------------------------- | +| PayPal | `https://mcp.paypal.com/sse` | sse | Payment processing | +| Plaid | `https://api.dashboard.plaid.com/mcp/sse` | sse | Financial data integration | +| Square | `https://mcp.squareup.com/sse` | sse | Payment processing | +| Close | `https://mcp.close.com/mcp` | streamable | CRM platform | +| Dodo Payments | `https://mcp.dodopayments.com/sse` | sse | Payment processing | + +## Analytics & Data + +| Service | URL | Transport | Description | +| ----------- | --------------------------------------- | ---------- | ------------------------------ | +| ThoughtSpot | `https://agent.thoughtspot.app/mcp` | streamable | Analytics and BI platform | +| Meta Ads | `https://mcp.pipeboard.co/meta-ads-mcp` | streamable | Facebook advertising analytics | + +## Utilities & Tools + +| Service | URL | Transport | Description | +| ------------- | ---------------------------------- | ---------- | ------------------------------- | +| Apify | `https://mcp.apify.com` | sse | Web scraping and automation | +| SimpleScraper | `https://mcp.simplescraper.io/mcp` | streamable | Web scraping tool | +| GlobalPing | `https://mcp.globalping.dev/sse` | sse | Network diagnostics | +| Jam | `https://mcp.jam.dev/mcp` | streamable | Bug reporting and collaboration | + +## Example: Multi-Service Agent + +Combine multiple remote MCP servers in a single agent: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + instruction: | + You help manage projects and deployments. + toolsets: + - type: mcp + remote: + url: "https://mcp.linear.app/mcp" + transport_type: "streamable" + instruction: Use Linear for issue tracking. + - type: mcp + remote: + url: "https://api.githubcopilot.com/mcp" + transport_type: "sse" + instruction: Use GitHub for code and PRs. + - type: mcp + remote: + url: "https://mcp.vercel.com/" + transport_type: "sse" + instruction: Use Vercel for deployments. +``` + +> [!NOTE] +> **Growing list** +> +> This list is updated as more services add MCP support. If a service you use isn't listed, check their documentation — many providers are adding MCP endpoints regularly. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md b/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md new file mode 100644 index 000000000000..dd264814b476 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md @@ -0,0 +1,135 @@ +--- +title: "Sessions" +description: "How Docker Agent stores conversations, resumes them across runs, and tracks their token cost." +keywords: docker agent, ai agents, features, sessions +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/features/sessions/ +--- + +_How Docker Agent stores conversations, resumes them across runs, and tracks their token cost._ + +## What a Session Is + +Every `docker agent run` creates or resumes a **session**: the record of a conversation, including every message, tool call, sub-agent run, and cost. Sessions are what makes `/undo`, `/sessions`, `--session <id>`, and cost tracking possible — the agent itself is stateless between runs, but the session is not. + +A session is only persisted to disk once it has content (the first message added), so a run you cancel before sending anything never leaves an empty session behind. + +## Where Sessions Are Stored + +Sessions live in a SQLite database, `session.db`, under the [data directory](../cli/index.md#global-flags) (`~/.cagent` by default): + +```bash +$ ls ~/.cagent/session.db +``` + +Override the location with `-s`/`--session-db`, or by overriding the data directory itself with `--data-dir`: + +```bash +# Use a project-local session database instead of the global one +$ docker agent run agent.yaml --session-db ./sessions.db +``` + +## Resuming a Session + +Pass `--session <id>` to continue a previous conversation instead of starting a new one: + +```bash +# Resume by explicit session ID +$ docker agent run agent.yaml --session 3f9c1e2a-... + +# Resume the most recently created session +$ docker agent run agent.yaml --session -1 + +# Resume the session created before that one +$ docker agent run agent.yaml --session -2 +``` + +`--session` accepts two kinds of reference: + +- **A relative offset** (`-1`, `-2`, …): sessions are ordered by **creation time**, newest first — `-1` is the most recently *created* session, `-2` the one created before it, and so on. This is creation order, not last-used order: resuming an older session with `--session <id>` does not make it the new `-1`; the next `-1` still resolves to whichever session was created most recently. A relative offset that has no matching session (for example `-1` with an empty database) is an error. +- **An explicit ID**: if a session with that ID already exists, it is resumed. If it doesn't exist yet, docker agent **creates it with that ID** instead of failing. This lets a supervisor (for example a board or a script) choose a session ID up front and reuse it across runs — the first run creates the session, later runs resume it. + +## Read-Only Sessions + +Add `--session-read-only` to open a session for viewing without sending new messages — useful for reviewing a past conversation without accidentally continuing it: + +```bash +$ docker agent run agent.yaml --session -1 --session-read-only +``` + +`--session-read-only` requires the TUI: it cannot be combined with `--exec`, since there would be nothing to display without one. + +## Browsing Sessions in the TUI + +Press `/sessions` to open the session browser: search and filter past conversations, see which ones were started in the current working directory ("This workspace") versus elsewhere ("Other locations"), and restore one with <kbd>Enter</kbd>. Restoring a session reopens it in its original working directory. See [Session Management](../tui/index.md#session-management) in the Terminal UI docs for the full set of session-browser and session-title features (starring, branching by editing a past message, and so on). + +### Tabs + +<kbd>Ctrl</kbd>+<kbd>T</kbd> opens a new tab running an additional agent session alongside the current one; <kbd>Ctrl</kbd>+<kbd>N</kbd>/<kbd>Ctrl</kbd>+<kbd>P</kbd> cycle between tabs and <kbd>Ctrl</kbd>+<kbd>W</kbd> closes the current one. By default, tabs are not restored the next time you launch the TUI. Set `restore_tabs: true` in your user config to reopen the same tabs (and their sessions) on the next launch: + +```yaml +# ~/.config/cagent/config.yaml +settings: + restore_tabs: true +``` + +## Session Titles + +Docker Agent auto-generates a short title for each session from your first message, using a one-shot call to the agent's own model. Point that call at a smaller, cheaper model instead with `title_model` on a model definition: + +```yaml +# examples/title_model.yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + # Generate session titles with the cheaper Haiku model instead of Sonnet. + title_model: fast + fast: + provider: anthropic + model: claude-haiku-4-5 + +agents: + root: + model: primary + description: An assistant that generates session titles with a cheaper model. + instruction: You are a helpful assistant. +``` + +When `title_model` is omitted, title generation reuses the agent's own model. Set or regenerate a title from inside the TUI with `/title` (see [Session Title Editing](../tui/index.md#session-title-editing)) — regenerating sends every user message in the session so far, not just the first — or generate one from the command line without starting a session at all: + +```bash +$ docker agent debug title agent.yaml "How do I configure a fallback model?" +``` + +See [`docker agent debug title`](../cli/index.md#docker-agent-debug) for details. + +## Usage & Cost Tracking + +Every tracked model call — the main conversation turns and compaction calls — updates the session's cumulative input/output token counts and cost. Check them at any time with `/cost` in the TUI, or disable tracking per-model with `track_usage: false` if you don't want a model's calls counted (for example, a free local model). Auxiliary one-shot calls the runtime makes on your behalf, such as automatic session-title generation, call the model directly and are not folded into this total. + +Cost is computed from the [models.dev](https://models.dev/) pricing catalogue by default. For a custom endpoint, a private deployment, or a negotiated enterprise rate the catalogue doesn't know about, declare pricing explicitly with a model's `cost:` block: + +```yaml +# examples/custom-pricing.yaml +models: + internal-gpt: + provider: internal-llm + model: gpt-4o + cost: + input: 1.25 # USD per 1M input tokens + output: 5.00 # USD per 1M output tokens + cache_read: 0.125 # USD per 1M cached input tokens + cache_write: 1.5625 # USD per 1M cache-write tokens +``` + +An all-zero `cost:` table means "priced, free" — distinct from a model with no `cost:` at all, which falls back to the catalogue (and bills $0 for models the catalogue doesn't know). + +> [!NOTE] +> **Cost never decreases** +> +> A session's cumulative cost is a running total updated after every *tracked* model call — the same main conversation turns and compaction calls described above. Compacting the conversation (manually with `/compact`, or automatically — see the agent's `session_compaction`/`compaction_threshold` fields in the [Agent Config reference](../../configuration/agents/index.md)) reshapes the message history sent back to the model, but never touches this running total. Auxiliary one-shot calls such as automatic session-title generation are not tracked and are not reflected in this total: `/cost` covers everything the session's tracked calls have spent, not literally every model call the runtime makes on your behalf. + +## Resuming Into a Worktree + +A session created during a `--worktree` run remembers which worktree it used. Resuming it with `--session` reattaches to the same worktree directory and branch automatically — you don't need to pass `--worktree` again. See [`--worktree`](../cli/index.md#docker-agent-run) in the CLI reference for the full worktree lifecycle. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md b/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md new file mode 100644 index 000000000000..bba760387a0a --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md @@ -0,0 +1,378 @@ +--- +title: "Skills" +description: "Skills provide specialized instructions that agents can load on demand when a task matches a skill's description." +keywords: docker agent, ai agents, features, skills +weight: 110 +canonical: https://docs.docker.com/ai/docker-agent/features/skills/ +--- + +_Skills provide specialized instructions that agents can load on demand when a task matches a skill's description._ + +## How Skills Work + +1. Docker Agent scans standard directories for `SKILL.md` files +2. Skill metadata (name, description) is injected into the agent's system prompt +3. When a user request matches a skill, the agent reads the full instructions +4. The agent follows the skill's detailed instructions to complete the task + +## Enabling Skills + +```yaml +agents: + root: + model: openai/gpt-4o + instruction: You are a helpful assistant. + skills: true + toolsets: + - type: filesystem # required for reading skill files +``` + +> [!TIP] +> Skills are perfect for encoding team-specific workflows (PR review, deployment, coding standards) that apply across projects. + +## Filtering Skills + +The `skills` field also accepts a list, letting you restrict the agent to a specific subset of skills instead of exposing every discovered one. List items are classified automatically: + +- `"local"` or any `http://` / `https://` URL → a **source** to load skills from +- any other string → the **name** of a skill to include + +When only names are given, local sources are used by default. + +```yaml +agents: + # Load every discovered local skill (same as `skills: true`). + full: + skills: true + + # Load local skills, but only expose "commit" and "poem". + scoped: + skills: + - commit + - poem + + # Combine an explicit source with a name filter. + remote_filtered: + skills: + - https://skills.example.com + - commit + + # Disable skills entirely. + none: + skills: false +``` + +A name that doesn't match any discovered skill is logged as a warning at startup but is otherwise ignored. + +## Inline Skills + +Instead of (or alongside) loading skills from files and URLs, you can define skills directly in the agent config. An inline skill is a mapping item in the `skills` list, freely mixed with the string items above: + +```yaml +agents: + root: + model: openai/gpt-4o + instruction: You are a helpful assistant. + skills: + - name: changelog + description: Write a concise changelog entry from a diff or description. + instructions: | + Produce a single changelog entry in Keep a Changelog style. + Pick the right category (Added, Changed, Fixed, Removed) and write + one imperative sentence summarising the user-visible change. + + # A fork-mode inline skill runs in an isolated sub-agent. + - name: triage + description: Triage a bug report in an isolated context. + context: fork + instructions: | + Restate the problem, list likely root causes most-probable-first, + and propose the smallest reproduction and next concrete action. + + # Inline skills mix freely with sources and name filters. + - local + toolsets: + - type: filesystem +``` + +Inline skills carry their body in the config itself, so they need no `SKILL.md` file and require no filesystem source. They are **always exposed** — the name filter only applies to file- and URL-based skills. Because inline skills travel inside the agent YAML, they also work in `--sandbox` mode without any kit staging, and they can be shared with the agent via `share push`. + +### Inline Skill Fields + +| Field | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------- | +| `name` | Yes | Skill identifier used by `read_skill` / `run_skill` and the `/<name>` command | +| `description` | Yes | Short description shown to the agent for skill matching | +| `instructions` | Yes | The skill body (what a `SKILL.md` would contain below its frontmatter) | +| `context` | No | Set to `fork` to run the skill as an isolated sub-agent | +| `model` | No | Override the model used while running a fork-mode skill | +| `allowed_tools` | No | For a fork-mode skill, restricts the sub-session to the parent tools whose names match an entry (glob or exact). See [Scoping a fork skill's tools](#scoping-a-fork-skills-tools). | +| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`](../../configuration/overview/index.md#reusable-toolsets-toolsets) to expose in the sub-session on top of the inherited tools. | + +> [!NOTE] +> **Inline vs. file-based skills** +> +> Inline skills support the subset of the SKILL.md format that fits in YAML. They cannot bundle supporting files (no `read_skill_file`) or use `` !`command` `` expansion. For skills that need bundled resources or executable helpers, use a `SKILL.md` directory instead. + +## SKILL.md Format + +<!-- yaml-lint:skip --> +```yaml +--- +name: create-dockerfile +description: Create optimized Dockerfiles for applications +license: Apache-2.0 +metadata: + author: my-org + version: "1.0" +--- + +# Creating Dockerfiles + +When asked to create a Dockerfile: + +1. Analyze the application type and language +2. Use multi-stage builds for compiled languages +3. Minimize image size by using slim base images +4. Follow security best practices (non-root user, etc.) +``` + +### Frontmatter Fields + +| Field | Required | Description | +| ---------------- | -------- | --------------------------------------------------------------------------- | +| `name` | Yes | Unique skill identifier | +| `description` | Yes | Short description shown to the agent for skill matching | +| `context` | No | Set to `fork` to run the skill as an isolated sub-agent (see below) | +| `model` | No | Override the model used while running the skill as a sub-agent (fork only) | +| `allowed-tools` | No | For a fork-mode skill, restricts the sub-session to the parent tools whose names match an entry (YAML list or comma-separated string). See [Scoping a fork skill's tools](#scoping-a-fork-skills-tools). | +| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`](../../configuration/overview/index.md#reusable-toolsets-toolsets) to expose in the sub-session (YAML list or comma-separated string). | +| `license` | No | License identifier (e.g. `Apache-2.0`) | +| `compatibility` | No | Free-text compatibility notes | +| `metadata` | No | Arbitrary key-value pairs (e.g. `author`, `version`) | + +## Running a Skill as a Sub-Agent + +By default, when an agent invokes a skill it reads the instructions inline into its own conversation. For complex, multi-step skills this can consume a large portion of the agent's context window and pollute the parent conversation with intermediate tool calls. + +Adding `context: fork` to the SKILL.md frontmatter tells the agent to run the skill in an **isolated sub-agent** instead: + +<!-- yaml-lint:skip --> +```yaml +--- +name: bump-go-dependencies +description: Update Go module dependencies one by one +context: fork +--- + +# Bump Dependencies + +1. List outdated deps +2. Update each one, run tests, commit or revert +3. Produce a summary table +``` + +When the agent encounters a task that matches a `context: fork` skill, it uses the `run_skill` tool instead of `read_skill`. This: + +- **Spawns a child session** with the skill content as the system prompt and the caller's task as the user message +- **Isolates the context window** — the sub-agent has its own conversation history, so lengthy tool-call chains don't eat into the parent's token budget +- **Folds the result** — only the sub-agent's final answer is returned to the parent as the tool result +- **Inherits the parent's model and tools** — the sub-agent can use all tools available to the parent agent (scope this with `allowed_tools` / `toolsets`, see [Scoping a fork skill's tools](#scoping-a-fork-skills-tools)) + +> [!TIP] +> **When to use context: fork** +> +> Use `context: fork` for skills that involve many steps, heavy tool usage, or that should not clutter the main conversation — for example dependency bumping, large refactors, or code generation pipelines. + +### Overriding the model for a fork skill + +Fork skills can declare a `model` field in their frontmatter to use a +different model than the parent agent for the duration of the sub-session. +This is useful when a skill is best handled by a faster, cheaper, or more +specialised model — for example a powerful reasoning model for refactors, +or a fast model for routine bookkeeping work. The override only applies +while the skill is running; the parent agent keeps its own model. + +The `model` value accepts either a named model from the agent config or +an inline `provider/model` reference (and the same comma-separated alloy +syntax as the rest of the agent config): + +<!-- yaml-lint:skip --> +```yaml +--- +name: bump-go-dependencies +description: Update Go module dependencies one by one +context: fork +model: openai/gpt-4o-mini +--- + +# Bump Dependencies + +1. ... +``` + +If the model reference cannot be resolved (unknown name, missing +credentials, runtime not configured for model switching, …) the skill +falls back to the agent's currently-active model (its configured +default, or any override the user previously set via the model picker) +and a warning is logged. + +When the skill completes, the agent's previous model is restored — but +only if no one else changed the model in the meantime. If the user +switches the model via the TUI model picker while the fork skill is +running, their choice is preserved (the deferred restore becomes a +no-op). + +### Scoping a fork skill's tools + +By default a fork skill inherits the parent agent's entire tool set. Two +optional fields let you scope what the sub-session can use. Both apply +**only to fork-mode skills** and work the same whether the skill is +inline or loaded from a `SKILL.md` file. + +`allowed_tools` (frontmatter: `allowed-tools`) is an **allow-list** over +the inherited tools: only tools whose names match an entry are kept, +everything else is hidden from the sub-session. Entries support glob +patterns (e.g. `read_*`) and otherwise match exactly. This is the +Claude-Code-compatible `allowed-tools` field, now enforced for fork +skills rather than merely recorded. + +`toolsets` references reusable [top-level toolsets](../../configuration/overview/index.md#reusable-toolsets-toolsets) +by name. The referenced toolsets are exposed in the sub-session **in +addition to** the inherited tools, and they bypass the `allowed_tools` +filter (the skill explicitly asked for them). + +```yaml +toolsets: + web: + type: fetch + +agents: + root: + model: openai/gpt-4o + instruction: You are a helpful assistant. + toolsets: + - type: filesystem + - type: shell + skills: + # Inherits the parent tools but is restricted to read-only filesystem + # access while it runs — shell and write tools are hidden. + - name: audit + description: Review the repository layout without modifying anything. + context: fork + allowed_tools: + - read_file + - list_directory + - directory_tree + instructions: Inspect the repository structure and summarise it. + + # Brings in the top-level `web` toolset on top of the parent's tools. + - name: research + description: Research a topic using web fetches in an isolated context. + context: fork + toolsets: + - web + instructions: Research the requested topic and summarise with links. +``` + +The equivalent in a `SKILL.md` file uses frontmatter lists: + +<!-- yaml-lint:skip --> +```yaml +--- +name: research +description: Research a topic using web fetches +context: fork +allowed-tools: + - fetch +toolsets: + - web +--- +``` + +> [!NOTE] +> **Fork only** +> +> Both fields are rejected by config validation when set on a non-fork skill, and a `toolsets` entry that doesn't resolve to a top-level toolset is a load-time error. + +## Search Paths + +Skills are discovered from these locations (later overrides earlier): + +### Global + +| Path | Search Type | +| ------------------- | --------------------------------------- | +| `~/.codex/skills/` | Recursive (searches all subdirectories) | +| `~/.claude/skills/` | Flat (immediate children only) | +| `~/.agents/skills/` | Recursive (searches all subdirectories) | + +### Project (from git root to current directory) + +| Path | Search Type | +| ----------------- | ------------------------------------------ | +| `.claude/skills/` | Flat (cwd only) | +| `.github/skills/` | Flat (each directory from git root to cwd) | +| `.agents/skills/` | Flat (each directory from git root to cwd) | + +## Invoking Skills + +Skills can be invoked in multiple ways: + +- **Automatic:** The agent detects when your request matches a skill's description and loads it automatically +- **Explicit:** Reference the skill name in your prompt: "Use the create-dockerfile skill to..." +- **Slash command:** Use `/{skill-name}` to invoke a skill directly + +```bash +# In the TUI, invoke skill directly: +/create-dockerfile + +# Or mention it in your message: +"Create a dockerfile for my Python app (use the create-dockerfile skill)" +``` + +## Precedence + +When multiple skills share the same name: + +1. Global skills load first +2. Project skills load next, from git root toward current directory +3. Skills closer to the current directory override those further away +4. At the same directory level, `.agents/skills/` overrides `.github/skills/` + +## Skills in Sandbox Mode + +When you run an agent with [`--sandbox`](../../configuration/sandbox/index.md), the sandbox VM has its own filesystem with no access to your host's skill directories. Docker Agent handles this transparently via the [auto-kit](../../configuration/sandbox/index.md#auto-kit): every discovered local skill is staged into a per-agent kit on the host, run through best-effort secret redaction (see the [auto-kit](../../configuration/sandbox/index.md#secret-redaction) docs), and bind-mounted read-only into the sandbox so the agent sees the same skills inside the VM as on the host. No configuration is required — use `--no-kit` only if you explicitly want to run the sandbox without any host skills. + +## Creating a Skill + +```bash +# Create the skill directory +$ mkdir -p ~/.agents/skills/create-dockerfile + +# Write the SKILL.md file +$ cat > ~/.agents/skills/create-dockerfile/SKILL.md << 'EOF' +--- +name: create-dockerfile +description: Create optimized Dockerfiles for applications +--- + +# Creating Dockerfiles + +When asked to create a Dockerfile: + +1. Analyze the application type and language +2. Use multi-stage builds for compiled languages +3. Use slim base images to minimize size +4. Run as non-root user for security +EOF +``` + +The skill will automatically be available to any agent with skills enabled (`skills: true`, or a list that targets its name — see [Filtering Skills](#filtering-skills)). + +> [!NOTE] +> **See also** +> +> Skills are enabled in the [Agent Config](../../configuration/agents/index.md) with the `skills` property (boolean or list). For tool-based capabilities, see [Tools](../../concepts/tools/index.md). +> +> Example configs: [`examples/skills_inline.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_inline.yaml) (inline skill definition), [`examples/skills_fork_toolsets.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_fork_toolsets.yaml) (scoping a fork skill's tools), [`examples/skills_filter.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_filter.yaml) (filtering which skills load). diff --git a/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md b/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md new file mode 100644 index 000000000000..bc624bf89123 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md @@ -0,0 +1,112 @@ +--- +title: "Snapshots" +description: "Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history." +keywords: docker agent, ai agents, features, snapshots +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/features/snapshots/ +--- + +_Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history._ + +## Overview + +When snapshots are enabled, Docker Agent records the state of your working +directory as the agent runs. Each checkpoint is stored in a **shadow git +repository** kept under the Docker Agent data directory — completely separate +from your project's own `.git`. This lets you: + +- **Review** exactly which files an agent touched on a given turn. +- **Undo** the most recent change with `/undo`. +- **Reset** the workspace back to any earlier checkpoint — or all the way to + its pre-agent state. + +Snapshots only ever touch files on disk. They never write commits to your +repository, never move your `HEAD`, and never appear in `git log` or +`git status`. + +> [!NOTE] +> **Git repositories only** +> +> The snapshot machinery is a no-op outside a git worktree. It needs a git +> repository to scope which files belong to your project and to mirror the +> repository's ignore rules. + +## Enabling Snapshots + +The simplest way is to enable snapshots globally for every agent in your user +config: + +```yaml +# ~/.config/cagent/config.yaml +settings: + snapshot: true +``` + +Omit `snapshot` or set it to `false` to leave automatic snapshots off. + +You can also wire the [`snapshot` built-in hook](../../configuration/hooks/index.md#available-built-ins) +into a single agent instead of enabling it globally: + +```yaml +hooks: + turn_start: + - type: builtin + command: snapshot + turn_end: + - type: builtin + command: snapshot + session_end: + - type: builtin + command: snapshot +``` + +Manually configured snapshot hooks always run, even when `settings.snapshot` +is unset. See [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) +for a complete configuration. + +## Using Snapshots in the TUI + +When snapshots are enabled, the [TUI](../tui/index.md) +exposes two slash commands: + +- **`/undo`** restores files from the most recent snapshot (one step back). +- **`/snapshots`** opens a dialog listing every captured snapshot and the + number of files in each. Use <kbd>↑</kbd>/<kbd>↓</kbd> (or + <kbd>j</kbd>/<kbd>k</kbd>) to highlight an entry, then press <kbd>r</kbd> to + reset the workspace to that point. Pick `<original>` to revert every snapshot + and bring the workspace back to its pre-agent state. <kbd>Esc</kbd> closes the + dialog without changing anything. + +Neither command removes messages from the session transcript — they only touch +files on disk. Both commands (and their command-palette entries) are hidden +when snapshots are turned off. + +## How It Works + +- **Shadow repository.** The first time a snapshot is taken for a worktree, + Docker Agent initializes a separate shadow git directory under the data + directory (`~/.cagent/snapshot/...` by default), keyed by a hash of the + worktree path. The shadow repo stores tree objects only — it never writes + commits and never touches your source repository's `.git`. +- **Ignore rules are mirrored.** Before each capture, the source repository's + `.gitignore` and `info/exclude` rules are mirrored into the shadow repo so + ignored files never appear in snapshots. +- **Large files are skipped.** Newly-added files larger than 2 MiB are excluded + from snapshots to keep the shadow repo small. +- **Checkpoints only on change.** A checkpoint is recorded only when files + actually changed, so a final no-op model response does not hide the last + meaningful snapshot. +- **Scoped to the working directory.** Snapshot operations are scoped to the + agent's working directory within the worktree, so a sub-directory agent only + captures and restores files under that directory. +- **Garbage collection.** Wiring `snapshot` into `session_end` (or enabling it + globally) runs `git gc` against the shadow repo so old, unreferenced objects + are pruned over time. + +## See Also + +- [Hooks](../../configuration/hooks/index.md) — the `snapshot` + built-in and the events it can run on. +- [Terminal UI](../tui/index.md) — the `/undo` and + `/snapshots` commands. +- [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) — a complete snapshot hook configuration. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md new file mode 100644 index 000000000000..5a06b6ebbc88 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md @@ -0,0 +1,591 @@ +--- +title: "Terminal UI (TUI)" +description: "Docker Agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more." +keywords: docker agent, ai agents, features, terminal ui (tui) +linkTitle: "Terminal UI" +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/features/tui/ +--- + +_Docker Agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more._ + +![Docker Agent TUI in action showing an interactive agent session](../../demo.gif) + +## Launching the TUI + +Both the full TUI and the lean TUI display a centered ASCII art Docker Agent banner on startup when the chat is empty. The banner is automatically hidden once the agent starts responding or when a custom welcome message is configured. + +```bash +# Launch with a config +$ docker agent run agent.yaml + +# Start with an initial message +$ docker agent run agent.yaml "Help me refactor this code" + +# Auto-approve all tool calls +$ docker agent run agent.yaml --yolo + +# Enable debug logging +$ docker agent run agent.yaml --debug + +# Override the application name shown in the status bar and window title +$ docker agent run agent.yaml --app-name "My Project" + +# Preselect a color theme +$ docker agent run agent.yaml --theme dracula + +# Hide the sidebar (cannot be re-enabled via Ctrl+B) +$ docker agent run agent.yaml --sidebar=false + +# Disable specific slash commands +$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model" + +# Open in read-only mode to review a past session without sending new messages +$ docker agent run agent.yaml --session -1 --session-read-only + +# Use the lean TUI for this run +$ docker agent run agent.yaml --lean +``` + +### Lean TUI + +The lean TUI uses a simplified terminal interface with minimal chrome. To make it the default for interactive runs, set `lean` in your user config: + +```yaml +# ~/.config/cagent/config.yaml +settings: + lean: true +``` + +Omit `lean` or set it to `false` to keep the full TUI as the default. You can still use `--lean` for a single run, or `--lean=false` to use the full TUI when `settings.lean` is enabled. See [User Settings](../../configuration/user-settings/index.md) for the full precedence rules between flags and user config. + +The lean TUI supports **steering** and **follow-ups** while the agent is running. Press <kbd>Enter</kbd> to steer the active turn, or <kbd>Alt</kbd>+<kbd>Enter</kbd> to queue the message as a separate turn after the current one finishes. Pending messages appear with muted styling at the end of the live stream. + +The lean TUI supports a focused set of slash commands: `/new`, `/compact`, `/model`, `/effort`, `/clear`, `/help`, `/exit` (alias: `/quit`), plus any agent-defined commands. Type `/model` (or `/model <provider/model>`) to switch the active model inline — the command opens a fuzzy-searchable list of available models. + +## Slash Commands + +Type `/` during a session to see available commands, or press <kbd>Ctrl</kbd>+<kbd>K</kbd> for the command palette: + +| Command | Description | +| ------------------ | ------------------------------------------------------------------------------------ | +| `/new` | Start a new conversation | +| `/clear` | Clear the current conversation (keep session, drop messages) | +| `/compact` | Summarize and compact the conversation history | +| `/fork` | Fork the current session into a new branch | +| `/copy` | Copy the entire conversation to clipboard | +| `/copy-last` | Copy only the last assistant message to clipboard | +| `/undo` | Restore file changes from the latest snapshot (only when snapshots are enabled) | +| `/snapshots` | List captured snapshots (only when snapshots are enabled) | +| `/export` | Export the session as HTML | +| `/sessions` | Browse and load past sessions | +| `/plans` | Browse and manage plans: every [shared plan](../../tools/plan/index.md) plus the current session's [session plan](../../tools/session_plan/index.md). Filter, open a detail view, refresh, export to a file, and — for shared plans — set status, edit/create in `$VISUAL`/`$EDITOR`, and delete, all guarded against concurrent edits. Not available in the lean TUI | +| `/model` | Change the model for the current agent | +| `/effort` | Set the current model's reasoning-effort level (`/effort <none\|minimal\|low\|medium\|high\|xhigh\|max>`, or `/effort` alone to pick from the supported levels; reasoning models only). Press <kbd>Tab</kbd> after `/effort` and a space to complete a level the current model supports | +| `/settings` | Manage appearance, behavior, and notification preferences | +| `/yolo` | Toggle automatic tool call approval | +| `/title` | Set or regenerate session title | +| `/attach` | Attach a file to your message | +| `/shell` | Open a shell | +| `/star` | Star/unstar the current session | +| `/context` | Show a context-window breakdown: estimated tokens per category (system prompt, tool definitions, prompt files, messages, tool results, compaction summary), a team-level **Live sessions** view (the current session plus every running sub-agent session with its agent, short session ID, and context budget), plus a per-file inventory of attached files and prompt files. When a compaction has occurred, the dialog also displays the verbatim text of the most recent compaction summary. When a dedicated `compaction_model` caps the effective limit below the primary model's own window, a second line reads "compaction cap: `<model>` • `<N>` tokens" — Live-sessions rows are silent on the cap, and the sidebar shows a minimal ⚠ capped marker without repeating the model or the figure (the `/context` header is the authoritative source of the model + number). Use the arrow keys to select a row: press <kbd>Enter</kbd> on a live session to explicitly compact it, or <kbd>d</kbd> on an attached file to drop it | +| `/drop` | Remove an attached file from the session context (`/drop <path>`, or `/drop` alone to review and drop from the `/context` dialog). Press <kbd>Tab</kbd> after `/drop` and a space to complete an attached file's path | +| `/cost` | Show cost breakdown for this session. Includes a **By Agent** section (alongside **By Model**) showing cumulative cost per agent; unattributed usage and compaction spend appear in their own buckets. | +| `/eval` | Create an evaluation report | +| `/pause` | Pause/resume the runtime loop. While the agent is mid-request, the resize handle shows "Pausing…" until the in-flight request completes; once the loop is blocked the indicator changes to "⏸ Paused". Run `/pause` again to resume. | +| `/tools` | Show every toolset (with lifecycle state) and the tools they expose | +| `/skills` | List skills available to the current agent | +| `/toolset-restart` | Force a supervisor-driven reconnect of the named toolset (`/toolset-restart <name>`). Press <kbd>Tab</kbd> after `/toolset-restart` and a space to complete a toolset name; non-restartable toolsets are shown dimmed and cannot be selected. | +| `/permissions` | Inspect and edit tool permission rules | +| `/speak` | Voice input via system speech-to-text (macOS only) | +| `/exit` | Exit the application (aliases: `/quit`, `/q`) | + +Slash commands (both built-in and named) execute immediately when entered. Regular chat messages sent while the agent is working are steered into the ongoing stream by default: the agent picks them up mid-turn (they appear in the transcript at the point the agent sees them) without breaking the stream. Prefer the previous end-of-turn behavior? Switch **While agent is working** to `Queue` on the **Behavior** tab of `/settings`; queued messages are processed in order once the stream stops. + +Agent-defined commands (prompts, URL links, agent-switching shortcuts) are configured under `commands:` in the agent YAML — see [Custom Commands](../../configuration/commands/index.md) for the full reference, including how to hide commands with `--disable-commands`. + +### Agents Panel + +The sidebar's **Agents** section lists every agent in the team and has two display modes selectable via **Sidebar info mode** in `/settings`: + +- **Compact** (default) — The current agent is shown as a focus **card** (rendered in place at its position in the list) with its name, a wrapped description, its full `provider/model`, and a thinking line. Every other agent is shown as a compact **two-line row** — line 1 is the shortcut/spinner, the agent name (in its accent color), and a right-aligned thinking **gauge**; line 2 is the indented full `provider/model` and, once the agent has run, its latest **context usage** as a right-aligned percentage of its context window. +- **Detailed** — Each agent is shown as a responsive card with labeled **Effort**, **Context**, and **Cost** metrics on a single line (or split across lines at narrow sidebar widths), making cumulative per-agent cost visible at a glance across the team. + +Agents are separated by a blank line so rows stay visually distinct. The effort **gauge** is the only visual language for thinking; the focus card and the Agent Inspector spell out the exact level alongside it. Left-click any agent to switch to it. + +On large teams the roster can be trimmed to the agents that matter right now: enable **Active agents only** (nested under **Agents** in `/settings` → Appearance → Sidebar sections, off by default) to list only agents active in the current session — the selected or working agent, participants of an in-flight transfer, and any agent with recorded participation (usage or attributed cost, including agents restored with a reloaded session). The filter also applies to the top/bottom band, is purely presentational — <kbd>Ctrl</kbd>+<kbd>number</kbd> shortcuts keep their original team positions and agent cycling still walks the whole team — and is unavailable while the Agents section itself is hidden. + +#### Agent inspector + +Open a read-only **Agent Inspector** to inspect any agent's full configuration combined with its live state. The instruction/system prompt is deliberately omitted; everything else the agent declares is shown: + +- **Right-click any agent** (card or row) to open the inspector without switching to it. +- **<kbd>Ctrl</kbd>+left-click any agent** does the same — a fallback for terminals that don't forward right-clicks. +- **Left-click** always switches to the agent. + +The title is rendered in the agent's accent color. Sections appear in this order, and any empty section is omitted: + +- **Description** — the agent's wrapped description. +- **Live state** — a `● current agent` line when the inspected agent is the one currently running. +- **Model / Fallback / Thinking** — the `provider/model`, any fallback models, and the gauge + value thinking line (omitted for models with no selectable thinking, e.g. harness-backed agents). +- **Context** — the agent's latest known context usage, e.g. `Context: 12.8K of 128.0K tokens (10%)` (a bare token count when the context limit is unknown; omitted until the agent has run). Sub-agent and background-agent runs are accounted for. When a dedicated `compaction_model` caps the effective limit below the primary model's own window, the token-usage line also shows a short "⚠ capped" marker (see `/context` for the model and figure). +- **Cost** — the agent's cumulative cost across all runs in the session tree. Repeated session snapshots are not double-counted. Omitted until the agent has run. +- **Sub-agents (N) / Handoffs (N) / Skills (N)** — compact, inline, comma-separated lists wrapped to the dialog width. +- **Limits** — the configured per-agent limits that are set, e.g. `Limits: max-iter 50 · history 40 · max-tool-calls 5`. +- **Options** — the enabled option flags, e.g. `Options: add-date · add-environment-info · redact-secrets`. +- **Toolsets (N)** — one line per toolset with a status marker, its name, kind, and tool count, followed by the indented tool names. +- **Commands (N)** — the slash commands the agent defines, each with its description. + +Each toolset carries a single-width status marker reflecting its **live** lifecycle: `●` started (serving), `○` stopped (not yet started), or `⚠` error. The tools listed under a toolset are the **live** tool names when it has started; for a toolset that has not started, the inspector instead shows its declared `tools:` allow-list prefixed with `declared:` (and shows nothing when the toolset declares no allow-list and therefore serves every tool). This lets you see both what an agent is configured with and what is actually running, even before the agent has been used. + +The dialog scrolls when the content is long; press <kbd>Esc</kbd> to close it. Remote runtimes (which hold no local team config) degrade gracefully — the config-derived sections are simply omitted. + +Model identifiers on line 2 are truncated **from the left** (e.g. `…claude-sonnet-4-6`) only when they overflow, so the informative tail (variant/version) is preserved. As the sidebar narrows the model keeps its own line, and near the minimum width line 1's gauge collapses to a single cell to keep the name readable. + +The thinking state of each model is shown with a gauge + value on the card and a gauge or badge on the row (no `✻` glyph): + +| Model state | Card line | Row badge | +| ---------------------- | ------------------------------ | ---------------------- | +| Effort level | `thinking ▰▰▰▰▱▱ high` | `▰▰▰▰▱▱` (effort gauge) | +| Adaptive budget | `thinking auto adaptive` | `auto` | +| Token budget | `thinking ◉ 8.2K tokens` | `◉ 8.2K` | +| Disabled (capable) | `thinking ▱▱▱▱▱▱ off` (dimmed) | `▱▱▱▱▱▱` (empty gauge) | +| Not reasoning-capable | _(omitted)_ | _(omitted)_ | + +The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` empty) so the badge column stays aligned. It maps the six selectable levels one-to-one onto filled-cell counts — `minimal` → `▰▱▱▱▱▱`, `low` → `▰▰▱▱▱▱`, `medium` → `▰▰▰▱▱▱`, `high` → `▰▰▰▰▱▱`, `xhigh` → `▰▰▰▰▰▱`, `max` → `▰▰▰▰▰▰` — so the cell count alone is lossless, with a low→high color ramp as a secondary cue. A capable-but-disabled model shows a dim empty gauge (`▱▱▱▱▱▱` `off`), adaptive budgets show `auto`, and token budgets keep `◉ <count>`. The same gauge + value renders on the focus card, the Agent Inspector, and the row. + +Harness-backed agents (e.g. `claude-code`) show the harness type as their model and no thinking gauge. Press **Shift+Tab** to cycle the current model's thinking-effort level; a `✻ Thinking: <level>` toast confirms the change (useful when the sidebar is hidden). + +### Agent Delegation Feedback + +When a parent agent calls `transfer_task` to delegate work to a sub-agent, the TUI provides live visual feedback in both the sidebar and the chat. + +**Sidebar — Transfer box:** As soon as the delegation starts, an animated **Transfer** box appears below the agent roster, showing the direction of the handoff with a traveling dot: + +```text +╭─ Transfer ─────────────────╮ +│ parent ●──────► child │ +╰────────────────────────────╯ +``` + +The box stays visible for at least 1.5 seconds. Once the sub-agent produces its first message, reasoning, or tool output, the box hides (still honoring the minimum window) to keep the sidebar focused on the active agent. If the sub-agent is slow or silent, the box hides after a 3-second maximum cutoff. The header shows a `↔` marker while any delegation is still in flight, even after the box hides. + +**Sidebar — Return box:** When the sub-agent finishes and control returns to the parent, a brief **Return** box animates the reverse direction for up to 1.5 seconds, then disappears: + +```text +╭─ Return ───────────────────╮ +│ child ●──────► parent │ +╰────────────────────────────╯ +``` + +**Chat — return transition:** Alongside the sidebar Return animation, the chat shows a one-line static transition between the two agent badges: + +```text +[child] returned control to [parent] +``` + +This transition is not persisted — it does not reappear when you reload the session. + +### Context-Usage Gauge + +The context percentage shown in the sidebar token-usage section, and the fill bar in the lean TUI status line, both color-escalate as the active session approaches the auto-compaction threshold: + +| State | Color | Trigger | +| ------- | ------ | ------- | +| Normal | (default) | Usage below 75% of the compaction threshold | +| Warning | Orange | Usage at or above 75% of the compaction threshold | +| Critical | Red | Usage at or above 95% of the compaction threshold | + +While a compaction is running the percentage is replaced by a **"compacting…"** indicator; token counts remain visible in the lean TUI status line. + +The thresholds are proportional to the agent's configured `compaction_threshold` (default `0.9`), so a custom value keeps a predictable visual runway. See [Compaction Threshold](../../configuration/models/index.md#delegating-session-compaction) for configuration details. + +Clicking the token/context part of the sidebar's usage reading (the glyph, token count, context percentage — or the "compacting…" marker — and the `⚠ capped` marker) opens the `/context` dialog with the full breakdown. Clicking the cost part (the `$` figure and the sub-session count) opens the `/cost` dialog instead. The "Token Usage" section title itself is not clickable. + +### Thinking and Tool Details + +Reasoning/thinking blocks are collapsed by default and carry a `Thinking` header badge. When collapsed, the TUI shows a short preview and compact tool summaries. Expand a block to see the full thinking content and the real tool renderers, including detailed tool output such as file edit diffs. + +To start new sessions with thinking/tool blocks expanded by default, set `expand_thinking` in your user config: + +```yaml +# ~/.config/cagent/config.yaml +settings: + expand_thinking: true +``` + +Set it to `false` or omit it to keep the default collapsed behavior. See [User Settings](../../configuration/user-settings/index.md) for the full settings reference. + +### Mermaid Diagrams + +The TUI renders Mermaid diagram blocks inline rather than displaying raw syntax. When an assistant message contains a fenced code block tagged ` ```mermaid `, the TUI parses the diagram and draws an ASCII representation directly in the conversation: + +| Diagram type | Support | +| ---------------------------------------------- | ------------------------------------------------- | +| `graph` / `flowchart` | ✅ Rendered inline | +| `sequenceDiagram` | ✅ Rendered inline | +| `stateDiagram` / `stateDiagram-v2` | ✅ Rendered inline (supports `direction TD/TB/BT/LR/RL`) | +| Other types (`classDiagram`, `erDiagram`, …) | Falls back to a syntax-highlighted code block | + +Mermaid rendering works in both the full TUI and the lean TUI. Unsupported or syntactically invalid diagram blocks are displayed as ordinary fenced code blocks — no configuration is required and there is no way to disable it. + +### LaTeX Math Rendering + +The TUI renders LaTeX math expressions as terminal-friendly Unicode text. When an assistant message contains inline math (delimited by `$…$`) or display math (delimited by `$$…$$`), the TUI converts supported LaTeX commands to their Unicode equivalents and displays them directly in the conversation. + +Supported features include: + +- Greek letters (`\alpha`, `\beta`, `\gamma`, …) +- Mathematical operators (`\times`, `\div`, `\pm`, `\oplus`, …) +- Relations (`\le`, `\ge`, `\approx`, `\equiv`, …) +- Set operators (`\cap`, `\cup`, `\subset`, `\in`, …) +- Calculus symbols (`\int`, `\sum`, `\prod`, `\partial`, `\nabla`, …) +- Arrows and logic (`\to`, `\implies`, `\forall`, `\exists`, …) +- Superscripts and subscripts (e.g., `x^2`, `a_i`) +- Fractions (`\frac{a}{b}`), square roots (`\sqrt{x}`), and matrices +- Common functions (`\sin`, `\cos`, `\log`, `\lim`, …) + +Unsupported or syntactically invalid LaTeX expressions fall back to displaying the raw source. LaTeX rendering works in both the full TUI and the lean TUI, requires no configuration, and cannot be disabled. + +### Markdown Images + +The TUI fetches and renders images referenced in agent responses using the Kitty graphics protocol. When an assistant message contains a standard Markdown image reference, the TUI downloads the image in the background and displays it inline at the point of the reference. While the image is loading a placeholder is shown; once loaded, the message re-renders with the image in place. + +Only `http://`, `https://`, and `data:image/…;base64,…` URIs are resolved. `file://`, `sandbox://`, and any other URI scheme are rejected as a security measure against prompt-injection attacks that could otherwise read local files. Bare relative paths (e.g. `./output.png`, used for agent-generated images) are read via the local filesystem. Images that fail to load are silently dropped — the surrounding message text is unaffected. Image rendering requires a terminal that supports the Kitty graphics protocol; it is automatically disabled when the terminal does not support it. You can also disable it explicitly via `render_images: false` in `~/.config/cagent/config.yaml` or the **Render images** toggle in `/settings`. + +### Snapshots, `/undo`, and `/snapshots` + +Enable shadow-git snapshots globally in `~/.config/cagent/config.yaml`: + +```yaml +settings: + snapshot: true +``` + +When enabled, Docker Agent records filesystem snapshots at turn boundaries. The TUI exposes two slash commands that operate on those snapshots: + +- **`/undo`** restores files from the most recent snapshot (one step back). +- **`/snapshots`** opens a dialog showing how many snapshots have been captured and the number of files in each one. Use <kbd>↑</kbd>/<kbd>↓</kbd> (or <kbd>j</kbd>/<kbd>k</kbd>) to highlight an entry, then press <kbd>r</kbd> to reset the workspace to that point. Pick `<original>` to revert every snapshot and bring the workspace back to its pre-agent state. <kbd>Esc</kbd> closes the dialog without changing anything. + +Neither command removes messages from the session transcript — they only touch files on disk. Both commands (and the matching command-palette entries) are hidden when snapshots are turned off. Omit `snapshot` or set it to `false` to leave automatic snapshots off; agents can still configure snapshot hooks manually. + +See [Snapshots](../snapshots/index.md) for how the shadow-git machinery works and how to wire it per-agent. + +## File Attachments + +Attach file contents to your messages using the `@` trigger: + +1. Type `@` to open the file completion menu +2. Start typing to filter files (respects `.gitignore`) +3. Select a file to insert the reference + +```bash +# In the chat input: +Explain what the code in @pkg/agent/agent.go does +``` + +The agent receives the full file contents in a structured `<attachments>` block, while the UI shows just the reference. + +For large or frequently-reused documents, or for getting content to an agent over the API or chat server instead of the TUI, see [Choosing a Large-Input Strategy](../../guides/headless/index.md#choosing-a-large-input-strategy). + +Attached files are also recorded on the session so sub-agents spawned by task transfer can read them. To review what is attached, open `/context`: the dialog lists every attached file (and resolved prompt file) with a per-file token estimate and, when a compaction has occurred, displays the verbatim text of the most recent compaction summary. Use <kbd>↑</kbd>/<kbd>↓</kbd> to select an attached file and press <kbd>d</kbd> (or <kbd>x</kbd>/<kbd>Del</kbd>) to drop it, or run `/drop <path>` directly — press <kbd>Tab</kbd> after `/drop` and a space to complete the path from the currently attached files. Dropping stops sharing the file with sub-agents and skills; content already inlined in earlier messages stays in the conversation until compaction, and the file can always be re-attached with `@` or `/attach`. + +### Team Context Budgets and Targeted Compaction + +The `/context` dialog also shows a **Live sessions** section: the current session plus every currently running sub-agent session (foreground children spawned by task transfer and long-running `run_background_agent` tasks). Each row shows the agent name, a short session ID (so two concurrent runs of the same agent stay distinguishable), and that session's context budget: used tokens, context limit, and percentage, or an explicit "limit unknown" reading when the model's window cannot be resolved. Live-sessions rows do not repeat the compaction-cap wording themselves — the dialog's header line is the sole authority on which model, if any, caps the effective limit. + +When a compaction has occurred, the dialog displays the verbatim text of the most recent compaction summary below the file inventory, under a "Latest compaction summary" section. This shows exactly what was summarized, preserving hard newlines and soft-wrapping long lines to the dialog width. + +Select a live session with <kbd>↑</kbd>/<kbd>↓</kbd> and press <kbd>Enter</kbd> to explicitly compact it. Cross-agent compaction happens only on this explicit request: no idle-triggered automatic compaction is added, and the existing automatic threshold and overflow-recovery compaction of sub-agent sessions is unchanged. The request is queued onto the target session's own run loop and executes at the next safe point between model turns, so it cannot corrupt an in-flight turn. The dialog closes and a notification confirms the request; a second notification reports the outcome (compacted, skipped, or failed) with the agent's name. Selecting the main row runs the same compaction as `/compact`. `/compact` itself keeps compacting the current root session. Remote runtimes do not expose live-session tracking, so the section is omitted there. + +## Runtime Model Switching + +Change the AI model during a session with `/model` or <kbd>Ctrl</kbd>+<kbd>M</kbd>. Model switching works in both the full TUI and the lean TUI. + +1. Press <kbd>Ctrl</kbd>+<kbd>M</kbd> (full TUI) or type `/model` (both TUIs) +2. Select from config models or type a custom `provider/model` +3. The model switch is saved with the session and restored on reload + +When a models gateway is configured (`--models-gateway`) and it exposes an OpenAI-style `/v1/models` endpoint, the picker lists the models actually served by the gateway (merged with the models defined in the agent config). When the gateway doesn't expose `/v1/models`, the picker falls back to the regular catalog. + +The picker's catalog entries come from [models.dev](https://models.dev) and are cached locally for a day. Press <kbd>Ctrl</kbd>+<kbd>R</kbd> in the picker to force model discovery to run again, including a refetch of the models.dev catalog. + +> [!TIP] +> Use model switching to try a more capable model for complex tasks, or a cheaper one for simple queries — without modifying your YAML config. + +## Editable Messages + +Edit any previous user message to branch the conversation. Hover a past user message and click **✎ edit** (or select it with the keyboard and press <kbd>e</kbd>) to modify it — the agent will re-process from that point, while the original session history is preserved. This is great for exploring alternative approaches without losing your work. + +Hovering a user or assistant message also reveals a **⎘ copy** button that copies the message text to the clipboard (<kbd>c</kbd> when a message is selected). + +## Error Recovery + +When an agent turn fails (fatal model error, hook block, loop detection, tool-setup failure), the TUI displays the error in the message stream and persists it to the session store. Errors survive a reload and are shown exactly where they occurred, making them visible in shared or remote sessions. + +Each error message includes a clickable **↻ retry** button. Clicking it resumes the conversation from the point of failure — without retyping your last message. This lets you recover from transient failures (rate limits, network blips, model API errors) in one click. + +## Session Management + +Docker Agent automatically saves your sessions. Use `/sessions` to browse past conversations: + +- **Browse** past sessions with search and filtering. The search matches against session **titles** and **session IDs** (full UUIDs, dash-less variants, and partial fragments all resolve correctly — useful when jumping back to a session from a copied ID or log). +- **Workspace grouping**: sessions are grouped by **git repository root** (worktree-aware) — sessions from any subdirectory or linked worktree of the same repository are grouped together under "This workspace", and the header shows the repository root path. Sessions outside the current repository appear under "Other locations" with their originating directory. Press <kbd>Ctrl</kbd>+<kbd>G</kbd> in the browser to cycle between all, current-workspace only, and other-directory views. Restoring a session reopens it in its original directory, so the label always matches where a restore will land. +- **Star** important sessions with `/star` +- **Branch** conversations by editing any previous user message — preserving the original session history +- **Resume** sessions with `docker agent run config.yaml --session <id>` +- **Relative refs**: `--session -1` for the last session, `-2` for the one before + +### Session Title Editing + +Customize session titles to make them more meaningful and easier to find. By default, Docker Agent auto-generates titles based on your first message, but you can override or regenerate them at any time. + +**Using the `/title` command:** + +```bash +/title # Regenerate title using AI (based on recent messages) +/title My Custom Title # Set a specific title +``` + +**Using the sidebar:** + +1. Click the pencil icon (✎) next to the session title in the sidebar +2. Type your new title +3. Press <kbd>Enter</kbd> to save, or <kbd>Escape</kbd> to cancel + +> [!NOTE] +> Manually set titles are preserved and won’t be overwritten by auto-generation. Title changes are persisted immediately to the session. + +## Keyboard Shortcuts + +| Shortcut | Action | +| ---------- | ----------------------------------------------- | +| Ctrl+K | Open command palette | +| Ctrl+M | Switch model | +| Ctrl+R | Reverse history search (search previous inputs) | +| Ctrl+G | Cancel reverse history search | +| Ctrl+S | Cycle to next agent in the team | +| Shift+Tab | Cycle the current model's thinking-effort level (shows a `✻ Thinking: <level>` toast) | +| Ctrl+1 – 9 | Switch directly to agent _N_ in the team list | +| Ctrl+T | Open a new tab (additional agent session) | +| Ctrl+W | Close the current tab | +| Ctrl+N | Next tab | +| Ctrl+P | Previous tab | +| Ctrl+B | Toggle the sidebar (full-UI mode only; disabled when --sidebar=false) | +| Ctrl+Y | Toggle YOLO mode (auto-approve tool calls) | +| Ctrl+O | Toggle hide tool results | +| Ctrl+Z | Suspend TUI to background (resume with `fg`) | +| Ctrl+X | Clear queued messages | +| Escape | Cancel current operation | +| Enter | Send message (or steer while the agent is running) | +| Alt+Enter | Queue a follow-up turn while the agent is running | +| Shift+Enter | Insert a newline | +| Up/Down | Navigate message history | + +Press <kbd>Ctrl</kbd>+<kbd>H</kbd> to view the complete list of all available keyboard shortcuts. + +### Custom Keybindings + +You can remap the shortcuts above by adding a `keybindings` list to the `settings` block of your `~/.config/cagent/config.yaml` (see [User Settings](../../configuration/user-settings/index.md#settings-reference) for the field reference). Each entry maps an action to one or more key combinations in [Bubbles key format](https://github.com/charmbracelet/bubbles) (for example `ctrl+q`, `alt+enter`, `f2`). Unlisted actions keep their defaults. + +This is the recommended way to replace the `Ctrl+J` newline fallback, which conflicts with common editor/terminal shortcuts (for example inside VS Code). + +```yaml +settings: + keybindings: + # Insert a newline with Alt+Enter instead of Ctrl+J. Shift+Enter still + # works automatically on terminals that report it. + - action: "editor_newline" + keys: ["alt+enter"] + # Allow several keys for one action. + - action: "commands" + keys: ["f2", "ctrl+k"] + - action: "quit" + keys: ["ctrl+q"] +``` + +**Valid actions:** + +| Action | Default | Description | +| -------------------------- | ------------ | -------------------------------------- | +| `editor_send` | `enter` | Send the current message | +| `editor_newline` | `ctrl+j` | Insert a newline in the input | +| `quit` | `ctrl+c` | Quit (opens the exit confirmation) | +| `switch_focus` | `tab` | Switch focus between panels | +| `commands` | `ctrl+k` | Open the command palette | +| `help` | `ctrl+h` | Show the help dialog | +| `toggle_yolo` | `ctrl+y` | Toggle YOLO mode | +| `toggle_hide_tool_results` | `ctrl+o` | Toggle hiding tool results | +| `cycle_agent` | `ctrl+s` | Cycle to the next agent | +| `model_picker` | `ctrl+m` | Open the model picker | +| `clear_queue` | `ctrl+x` | Clear queued messages | +| `suspend` | `ctrl+z` | Suspend the TUI | +| `toggle_sidebar` | `ctrl+b` | Toggle the sidebar | +| `edit_external` | `ctrl+g` | Edit input in an external editor | +| `history_search` | `ctrl+r` | Incremental history search | + +`Shift+Enter` for newline is detected from your terminal's capabilities and is always available where supported, independent of `editor_newline`. + +Invalid entries are ignored with a warning (visible with `--debug`) so a bad config never breaks the TUI: unknown actions, empty or malformed keys, and keys that would collide with another action are dropped while every other binding keeps working. + +## History Search + +Press <kbd>Ctrl</kbd>+<kbd>R</kbd> to enter incremental history search mode. Start typing to filter through your previous inputs. Press <kbd>Enter</kbd> to select a match, or <kbd>Escape</kbd> to cancel. + +## Settings + +Run `/settings` to open the settings dialog. Use <kbd>Tab</kbd> to switch between **Appearance**, **Behavior**, and **Notifications**. + +> [!TIP] +> **Full settings reference** +> +> This section covers the `/settings` dialog. For the complete list of `settings:` fields (including ones with no dialog UI, like `permissions`, `hooks`, and `keybindings`) and how they interact with CLI flags and aliases, see [User Settings](../../configuration/user-settings/index.md). + +The **Appearance** tab selects the theme and customizes the layout. Layout changes show a live schematic preview and apply immediately to the UI behind the dialog: + +- **Sidebar position**: `Right` (default), `Left`, `Top`, or `Bottom`. Left/right keep the full vertical sidebar next to the chat; top/bottom render it as a compact horizontal band above or below the chat (session title, working directory, token usage, plus a one-line summary of the current agent and its model; in multi-agent configurations all team agents are listed by name after the current agent). +- **Sidebar info mode**: `Compact` (default) or `Detailed`. Controls how the Agents panel renders agent rows — see [Agents Panel](#agents-panel) for details. Persisted as `settings.layout.sidebar_info_mode: detailed`; compact is the default and omitted from the config. +- **Section spacing**: `Compact`, `Normal` (default), or `Relaxed`, the number of blank lines between the sidebar sections (1, 2, or 3). +- **Sidebar sections**: toggle the visibility of the **Session path** (the working directory line, including its git branch) and the **Token usage**, **Agents**, **Tools**, and **Todos** sections. The session title is always shown. + +Appearance also controls split-diff rendering, expanded thinking, and whether tool results are hidden by default. Select **Theme** to open the theme picker. + +The **Behavior** tab controls busy-message handling, the auto-approve default, tab restoration, automatic snapshots, lean UI, and the maximum tab-title length. Restore-tabs and lean-UI changes take effect on the next launch. Enabling auto-approve requires confirmation. + +The **Notifications** tab enables completion sounds and sets the minimum task duration before a sound plays. + +Press <kbd>Enter</kbd> to apply and persist, or <kbd>Escape</kbd> to cancel and restore the previous layout. The settings are saved globally in `~/.config/cagent/config.yaml`: + +```yaml +# ~/.config/cagent/config.yaml +settings: + busy_send_mode: queue # steer (default), queue + layout: + sidebar_position: left # right (default), left, top, bottom + sidebar_info_mode: detailed # compact (default, omitted), detailed + section_spacing: compact # normal (default), compact, relaxed + hide_session_path: false + hide_usage: true + hide_agents: false + active_agents_only: false # true to filter to session-active agents + hide_tools: false + hide_todos: false +``` + +## Theming + +Customize the TUI appearance with built-in or custom themes: + +```bash +# Open Settings and select Theme under Appearance +/settings +``` + +### Built-in Themes + +`default`, `default-light`, `catppuccin-latte`, `catppuccin-mocha`, `dracula`, `gruvbox-dark`, `gruvbox-light`, `nord`, `one-dark`, `solarized-dark`, `tokyo-night` + +### Auto Theme (match the terminal) + +The special theme `auto` follows the terminal's light/dark background instead of naming a fixed theme. Select **Auto (match terminal)** from **Settings → Appearance → Theme**, pass `--theme auto`, or set it in your user config: + +```yaml +settings: + theme: auto + theme_dark: default # optional, theme used on dark backgrounds (default: default) + theme_light: default-light # optional, theme used on light backgrounds (default: default-light) +``` + +At startup the terminal background is queried (OSC 11) to pick the dark or light theme of the pair; non-interactive runs (pipes, CI) fall back to the dark theme. In terminals that report appearance changes (DEC mode 2031 — Ghostty, kitty, contour, …), flipping the OS or terminal appearance while Docker Agent is running switches the theme live. Terminals without that mode re-sync when the window regains focus. + +### Custom Themes + +Create theme files in `~/.cagent/themes/` as YAML. Theme files are **partial overrides** — you only need to specify the colors you want to change. Any omitted keys fall back to the built-in default theme values. + +```yaml +# ~/.cagent/themes/my-theme.yaml +name: "My Custom Theme" + +colors: + # Backgrounds + background: "#1a1a2e" + background_alt: "#16213e" + + # Text colors + text_bright: "#ffffff" + text_primary: "#e8e8e8" + text_secondary: "#b0b0b0" + text_muted: "#707070" + + # Accent colors + accent: "#4fc3f7" + brand: "#1d96f3" + + # Status colors + success: "#4caf50" + error: "#f44336" + warning: "#ff9800" + info: "#00bcd4" + +# Optional: Customize syntax highlighting colors +chroma: + comment: "#6a9955" + keyword: "#569cd6" + literal_string: "#ce9178" + +# Optional: Customize markdown rendering colors +markdown: + heading: "#4fc3f7" + link: "#569cd6" + code: "#ce9178" +``` + +### Applying Themes + +**In user config** (`~/.config/cagent/config.yaml`, see [User Settings](../../configuration/user-settings/index.md) for the full reference): + +```yaml +settings: + theme: my-theme # References ~/.cagent/themes/my-theme.yaml +``` + +**At launch:** Pass `--theme <name>` to `docker agent run` to preselect a theme for that session. This overrides `settings.theme` in your config but is not saved. Invalid theme names print an error at startup listing the available options. Has no effect in `--exec` mode. `--theme auto` enables the [auto theme](#auto-theme-match-the-terminal) for the session. + +**At runtime:** Open `/settings`, select **Theme** on the Appearance tab, and choose from the available themes. Your selection is saved globally in `~/.config/cagent/config.yaml` under `settings.theme` and persists across sessions. + +> [!TIP] +> **Hot Reload** +> +> Custom themes auto-reload when you save changes to the file — no restart needed. This makes it easy to tweak colors in real-time. + +> [!WARNING] +> **Partial overrides** +> +> All user themes are applied on top of the `default` theme. If you want to customize a built-in theme (e.g., `dracula`), copy its full YAML from the [built-in themes on GitHub](https://github.com/docker/docker-agent/tree/main/pkg/tui/styles/themes) into `~/.cagent/themes/` and edit the copy. Otherwise, omitted values will use `default` colors, not the original theme's colors. + +## Tool Permissions + +When an agent calls a tool, Docker Agent shows a confirmation dialog by default. You can: + +- **Approve once** — Allow this specific call +- **Always allow** — Permanently approve this tool/command for the session +- **Deny** — Reject the tool call + +**Granular permissions:** The permission system supports pattern-based matching. When you “Always allow” a specific tool command, only that exact pattern is auto-approved — other commands from the same tool still require confirmation. This lets you auto-approve safe, read-only operations while maintaining control over destructive ones. + +> [!TIP] +> **YOLO mode** +> +> Use `--yolo` or the `/yolo` command to auto-approve all tool calls. You can also toggle this mid-session. For aliases, set `--yolo` when creating the alias: `docker agent alias add fast myorg/coder --yolo`. + +## Notifications + +The TUI displays transient notification banners for agent warnings, errors, and other runtime events. Notifications auto-dismiss after a short delay unless the mouse is hovering over them — hovering pauses the timer so you have time to read the message. + +| Interaction | Behaviour | +| ----------- | --------- | +| Hover | Pauses auto-dismiss; the notification stays visible until the mouse moves away | +| Click | Copies the notification text to the clipboard | +| × (close) | Dismisses immediately; the glyph turns red when hovered | + +Hint text in the top-left corner of the notification border shows the available actions at a glance. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/_index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/_index.md new file mode 100644 index 000000000000..46eeae898947 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/_index.md @@ -0,0 +1,5 @@ +--- +title: "Getting Started" +description: "Install Docker Agent and build your first agent." +weight: 10 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md new file mode 100644 index 000000000000..43e52344c5b8 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md @@ -0,0 +1,150 @@ +--- +title: "Installation" +description: "Get Docker Agent running on your system in minutes." +keywords: docker agent, ai agents, getting started, installation +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/getting-started/installation/ +--- + +_Get Docker Agent running on your system in minutes._ + +## Prerequisites + +- An API key for at least one AI provider (OpenAI, Anthropic, Google, etc.) +- **Optional:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) — for running containerized MCP tools and Docker Model Runner + +## Docker Desktop (Pre-installed) + +Starting with [Docker Desktop 4.63](https://docs.docker.com/desktop/release-notes/#4630), **Docker Agent is already available**. No separate installation needed — just open a terminal and run: + +```bash +$ docker agent version +``` + +> [!TIP] +> Docker Desktop bundles Docker Agent and keeps it up to date. This is the easiest way to get started, especially if you want to use Docker MCP tools and Docker Model Runner. + +## Homebrew (macOS / Linux) + +Install Docker Agent using [Homebrew](https://brew.sh/): + +```bash +# Install +$ brew install docker-agent + +# Verify +$ docker-agent version +``` + +You can also install Docker Agent as a docker CLI plugin, by copying the `docker-agent` binary in `~/.docker/cli-plugins`. You can then run `docker agent version`. + +## Download Binary Releases + +Download [prebuilt binary releases](https://github.com/docker/docker-agent/releases) for Windows, macOS, and Linux from the GitHub Releases page. + +### macOS / Linux + +```bash +# Download the latest release +OS=$(uname -s | tr '[:upper:]' '[:lower:]') +ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64;; aarch64) ARCH=arm64;; esac +curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-${OS}-${ARCH}" -o docker-agent +chmod +x docker-agent +sudo mv docker-agent /usr/local/bin/ +docker-agent version + +# or alternatively, instead of moving to /usr/local/bin: +mkdir -p ~/.docker/cli-plugins +sudo mv docker-agent ~/.docker/cli-plugins +docker agent version +``` + +### Windows + +Download `docker-agent-windows-amd64.exe` from the [releases page](https://github.com/docker/docker-agent/releases), rename it to `docker-agent.exe` and add it to your PATH. Alternatively you can move it to `~/.docker/cli-plugins` + +## Optional Self-Updates + +When Docker Agent is installed from a standalone GitHub release binary, you can opt in to automatic self-updates by setting `DOCKER_AGENT_AUTO_UPDATE` to a truthy value (`1`, `true`, `yes`, or `on`): + +```bash +# Enable for one command +DOCKER_AGENT_AUTO_UPDATE=1 docker agent run + +# Or enable for the current shell session +export DOCKER_AGENT_AUTO_UPDATE=1 +docker agent run +``` + +With self-updates enabled, Docker Agent checks the latest GitHub release before normal commands run. If a newer release exists and your session is interactive, Docker Agent asks whether you want to install it or keep running your current version. When the answer is yes (or the session is non-interactive, such as CI or piped input, in which case the update proceeds automatically), it downloads the asset for your OS and architecture, verifies the release-provided SHA-256 digest/checksum, replaces the current binary, and restarts the command with the same arguments. + +Self-updates are fail-safe: if checking, downloading, verifying, installing, or restarting fails, Docker Agent keeps running the current binary. Version/help/completion commands and Docker CLI plugin metadata handshakes do not trigger self-updates. + +> [!NOTE] +> **Package-manager installs** +> +> Docker Desktop and Homebrew already manage Docker Agent updates. Prefer those update mechanisms when you installed Docker Agent that way. Self-updates are mainly intended for standalone release binaries. + +## Build from Source + +For the latest features, or to contribute, build from source: + +### Prerequisites + +- [Go 1.26](https://go.dev/dl/) or higher +- [Task](https://taskfile.dev/installation/) (build tool) +- [golangci-lint](https://golangci-lint.run/docs/welcome/install/local/) (for linting) + +```bash +# Clone the repository +git clone https://github.com/docker/docker-agent.git +cd docker-agent + +# Build the binary +task build + +# The binary is at ./bin/docker-agent +./bin/docker-agent --help +``` + +> [!TIP] +> **Building on Windows** +> +> On Windows, use `task build-local` instead of `task build`. This builds the binary inside a Docker container using Docker Buildx, which avoids issues with Windows-specific toolchain setup and CGo cross-compilation. The output goes to the `./dist` directory. + +## Set Up API Keys + +Docker Agent needs API keys for the model providers you want to use. Set them as environment variables: + +```bash +# Pick one (or more) depending on your provider +export OPENAI_API_KEY="sk-..." # OpenAI +export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic +export GOOGLE_API_KEY="AI..." # Google Gemini (or GEMINI_API_KEY) +export GITHUB_TOKEN="ghp-..." # GitHub Copilot (PAT with copilot scope) +export MISTRAL_API_KEY="..." # Mistral +export OPENROUTER_API_KEY="..." # OpenRouter +``` + +See [Configuration Overview](../../configuration/overview/index.md#environment-variables) for the full list of supported providers and environment variables. + +> [!NOTE] +> You only need the key(s) for the provider(s) you configure in your agent YAML. If you use Docker Model Runner (DMR), no API key is needed — models run locally. + +## Verify Installation + +```bash +# Check the version +$ docker agent version + +# Run the default agent +$ docker agent run + +# Or run an agent from an OCI registry +$ docker agent run myorg/agent:tag +``` + +## What's Next? + +- [**Quick Start**](../quickstart/index.md) — create and run your first agent in under 5 minutes. +- [**Troubleshooting**](../../community/troubleshooting/index.md) — something not working? Debug mode, common issues, and solutions. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md new file mode 100644 index 000000000000..0ade379b873c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md @@ -0,0 +1,74 @@ +--- +title: "Introduction" +description: "Docker Agent is a multi-agent runtime that lets you build, run, and share AI agents with a YAML or HCL config — no glue code required." +keywords: docker agent, ai agents, getting started, introduction +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/getting-started/introduction/ +--- + +_Docker Agent is a multi-agent runtime that lets you build, run, and share AI agents with a YAML or HCL config — no glue code required._ + +## What is Docker Agent? + +Docker Agent is an open-source tool from Docker that orchestrates AI +agents with specialized capabilities and tools. Instead of writing +code to wire up LLMs, tools, and workflows, you **declare** your +agents in YAML or HCL — their model, personality, tools, and how they +collaborate — and Docker Agent handles the rest. + +- **Multi-Agent Architecture** — build hierarchical teams of agents that specialize in different tasks and delegate work to each other. +- **Rich Tool Ecosystem** — built-in tools for files, shell, memory, and todos. Extend with any MCP server from [Docker's MCP catalog](https://hub.docker.com/u/mcp). +- **Multi-Model Support** — OpenAI, Anthropic, Google Gemini, AWS Bedrock, Docker Model Runner, and reusable provider definitions with shared defaults. +- **Package & Share** — push agents to OCI registries and pull them anywhere, just like Docker images. +- **Multiple Interfaces** — interactive TUI, headless CLI, HTTP API server, MCP mode, and A2A protocol support. +- **Security-First Design** — tool confirmation prompts, containerized MCP tools via Docker, client isolation, and resource scoping. + +## Why Docker Agent? + +After spending years building AI agents using various frameworks, the +Docker team kept asking the same questions: + +- **How do we make building agents less of a hassle?** — Most agents + use the same building blocks. Docker Agent provides them out of the + box. +- **Can we reuse those building blocks?** — Declarative YAML or HCL + configs mean you can mix and match agents, models, and tools without + rewriting code. +- **How can we share agents easily?** — Push agents to any OCI + registry and run them anywhere with a single command. + +Docker Agent is built in the open so the community can make use of +this work and contribute to its future. + +## How it works + +At its core, Docker Agent follows a simple loop: + +1. **You define agents** in YAML or HCL — their model, instructions, tools, and sub-agents. +2. **You run an agent** via the TUI, CLI, or API. +3. **The agent processes your request** — calling tools, delegating to sub-agents, and reasoning step by step. +4. **Results stream back in real-time** via an event-driven architecture. + +```yaml +# A minimal agent definition +agents: + root: + model: openai/gpt-5 + description: A helpful assistant + instruction: You are a helpful assistant. + toolsets: + - type: think +``` + +```bash +# Run it +$ docker agent run agent.yaml +``` + +> [!TIP] +> Jump straight to the [Quick Start](../quickstart/index.md) if you want to build your first agent right away. + +## What's next? + +- [**Installation**](../installation/index.md) — install Docker Agent on macOS, Linux, or Windows. +- [**Quick Start**](../quickstart/index.md) — build your first agent in under 5 minutes. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md new file mode 100644 index 000000000000..f3f9056a829d --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md @@ -0,0 +1,156 @@ +--- +title: "Quick Start" +description: "Get up and running with Docker Agent in under 5 minutes. Pick whichever path suits you best." +keywords: docker agent, ai agents, getting started, quick start +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/getting-started/quickstart/ +aliases: + - /ai/docker-agent/tutorial/ +--- + +_Get up and running with Docker Agent in under 5 minutes. Pick whichever path suits you best._ + +## Option A: Run the Default Agent + +The fastest way to try Docker Agent — no config file needed: + +```bash +# Launch the default agent with the interactive TUI +$ docker agent run +``` + +This starts a general-purpose assistant with sensible defaults. Just start chatting. + +> [!NOTE] +> This needs a model: a cloud provider API key, or a local model pulled through Docker Model Runner. [Set Up a Model](../set-up-a-model/index.md) walks through both paths. + +## Option B: Run an Agent from a Registry + +Run an agent shared through any OCI-compatible registry — no local YAML needed: + +```bash +$ docker agent run myorg/agent:tag +``` + +## Option C: Generate a Config Interactively + +Use the `docker agent new` command to scaffold a config file through prompts: + +```bash +# Interactive wizard +$ docker agent new + +# Or specify options directly +$ docker agent new --model openai/gpt-5 + +# Override iteration limits +$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15 +``` + +This generates an `agent.yaml` in the current directory. Then run it: + +```bash +$ docker agent run agent.yaml +``` + +## Option D: Write Your Own Config + +Create an `agent.yaml` by hand for full control. Here's a minimal example: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A helpful coding assistant + instruction: | + You are an expert software developer. Help users write + clean, efficient code. Explain your reasoning. + toolsets: + - type: filesystem + - type: shell + - type: think +``` + +This gives your agent: + +- **Claude Sonnet 4.5** as the underlying model +- **Filesystem access** to read and write files +- **Shell access** to run commands +- **Think tool** for step-by-step reasoning + +This config needs `ANTHROPIC_API_KEY` set. See [Set Up a Model](../set-up-a-model/index.md) for where to put it, or use a local `dmr/...` model that needs no key. + +```bash +# Launch the interactive terminal UI +$ docker agent run agent.yaml +``` + +> [!TIP] +> **Prefer HCL?** +> +> You can write the same config as `agent.hcl` using labeled blocks and heredocs. See [HCL Configuration](../../configuration/hcl/index.md). + +## Try It Out + +Once your agent is running, try asking it to: + +- _"List the files in the current directory"_ +- _"Create a Python script that fetches weather data"_ +- _"Explain what the code in main.go does"_ + +> [!TIP] +> Add `--yolo` to auto-approve all tool calls: `docker agent run agent.yaml --yolo` + +## Take the Interactive Tour + +Prefer to learn by doing? Run: + +```bash +$ docker agent getting-started +``` + +This launches a short, scripted tour inside the chat UI: sending messages, approving tool calls, the command palette, and slash commands. It's skippable at any point with <kbd>Esc</kbd>, and you can replay it later with the same command or the `/getting-started` slash command. + +## Non-Interactive Mode + +Use `docker agent run --exec` for one-shot tasks: + +```bash +# Ask a single question +$ docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app" + +# Pipe input +$ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?" +``` + +## Add More Power + +Give your agent persistent memory and web search: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Research assistant with memory + instruction: | + You are a research assistant. Search the web for information, + remember important findings, and provide thorough analysis. + toolsets: + - type: think + - type: memory + path: ./research.db + - type: mcp + ref: docker:duckduckgo +``` + +> [!NOTE] +> **Docker MCP Tools** +> +> The `ref: docker:duckduckgo` syntax runs the DuckDuckGo MCP server in a Docker container. This is the recommended way to use MCP tools — secure, isolated, and easy to configure. Requires Docker Desktop. + +## What's Next? + +- [**Understand Agents**](../../concepts/agents/index.md) — learn how agents work and what you can configure. +- [**Multi-Agent Systems**](../../concepts/multi-agent/index.md) — build teams of collaborating agents. +- [**Configuration Reference**](../../configuration/overview/index.md) — full reference for all YAML and HCL options. +- [**Troubleshooting**](../../community/troubleshooting/index.md) — something not working? Debug tips and common fixes. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/set-up-a-model/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/set-up-a-model/index.md new file mode 100644 index 000000000000..bff584def8d3 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/set-up-a-model/index.md @@ -0,0 +1,276 @@ +--- +title: "Set Up a Model" +description: "Make a model available to Docker Agent: connect a cloud provider, run a local model with Docker Model Runner, or register a custom OpenAI-compatible endpoint." +keywords: docker agent, ai agents, getting started, set up a model, api key, local model, docker model runner, custom endpoint +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/getting-started/set-up-a-model/ +--- + +_Most agents need a model to think with: connect a built-in cloud provider, run a model locally with Docker Model Runner, or register a custom OpenAI-compatible endpoint. This page walks through each path end to end — plus the exception: agents that delegate to the Claude Code CLI on a Claude subscription, which need no model at all._ + +## Pick a Path + +| | Built-in cloud provider (Path A) | Local model (Path B) | +| ------------- | ------------------------------------------------ | ---------------------------------------- | +| You need | An account and a credential (usually an API key) | Docker Desktop with Model Runner enabled | +| Cost | Pay per token | Free once the model is downloaded | +| Your data | Sent to the provider | Never leaves your machine | +| Model quality | Frontier models (Claude, GPT-5, Gemini) | Open models sized to your hardware | + +You can set up both. When you don't name a model, Docker Agent's `auto` selection picks the first cloud provider with a configured credential and falls back to a locally pulled Docker Model Runner model. + +Two more paths cover the remaining cases: if your models sit behind your own OpenAI-compatible endpoint (vLLM, LiteLLM, a corporate gateway), register it with its base URL as a [custom endpoint](#path-c-custom-openai-compatible-endpoint) (Path C); and if you have a **Claude subscription**, the [Claude Code harness](#path-d-claude-code-harness-claude-subscription) (Path D) runs the official `claude` CLI as the agent, with no API key and no local model required. + +> [!TIP] +> **Prefer a wizard?** +> +> `docker agent setup` walks through the same choices interactively: pick a built-in provider and store its credential, check Docker Model Runner and pull a local model, register a custom OpenAI-compatible endpoint, or set up the Claude Code harness. This page is the manual version. See the [CLI reference](../../features/cli/index.md#docker-agent-setup). + +## Path A: Built-in Cloud Provider + +Docker Agent ships built-in support for many cloud providers: Anthropic, OpenAI, Google Gemini, Groq, Hugging Face, AWS Bedrock, GitHub Copilot, and more. You pick these by name instead of registering a custom provider. The providers `docker agent setup` lists — Groq and Hugging Face among them — come with a predefined endpoint, so setting the provider's credential is enough; some other built-in aliases need manual configuration, such as Azure OpenAI with your resource endpoint as `base_url`. The credential is usually an API key, but not always: Hugging Face uses the `HF_TOKEN` token, GitHub Copilot a `GITHUB_TOKEN`, AWS Bedrock your AWS credentials, and `chatgpt` signs in with your ChatGPT account in the browser via `docker agent setup`, with no key to paste. The steps below show the API-key flow that most providers follow. + +### 1. Get an API key + +Create a key in your provider's console: + +| Provider | Environment variable | Get a key at | +| ------------- | -------------------- | ------------------------------------------------------------------- | +| Anthropic | `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com/settings/keys) | +| OpenAI | `OPENAI_API_KEY` | [platform.openai.com](https://platform.openai.com/api-keys) | +| Google Gemini | `GOOGLE_API_KEY` | [aistudio.google.com](https://aistudio.google.com/apikey) | + +Every other provider with an API key works the same way. See [Model Providers](../../providers/overview/index.md) for the full list, each provider's credential variable, and the exceptions noted above. + +### 2. Store the key + +The fastest option is an environment variable in your shell: + +```bash +$ export ANTHROPIC_API_KEY=sk-ant-... +``` + +That lasts for the current shell session. To set a key up once, use any other built-in secret source: + +```bash +# Env file, passed at run time +$ echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env +$ docker agent run --env-from-file .env + +# Docker Agent env file, read automatically on every run +# (`docker agent setup` writes it for you with owner-only permissions) +$ echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.config/cagent/.env +$ chmod 600 ~/.config/cagent/.env +``` + +The entry name must match the environment variable the provider expects. [Managing Secrets](../../guides/secrets/index.md) covers every source (Docker Compose secrets, credential helpers, 1Password references) and the order they are checked in. + +> [!IMPORTANT] +> Keys never go in `agent.yaml`. If you use an env file, add it to `.gitignore`. + +### 3. Verify + +`docker agent doctor` shows whether the key is visible and where it comes from: + +```bash +$ docker agent doctor +``` + +```text +User configuration + ~/.config/cagent/config.yaml: ok + +Model provider credentials + PROVIDER STATUS CREDENTIAL SOURCE + anthropic found ANTHROPIC_API_KEY environment + openai not set OPENAI_API_KEY - + ... + +Docker Model Runner + Status: not installed (https://docs.docker.com/ai/model-runner/get-started/) + +Model auto-selection + auto -> anthropic/claude-sonnet-4-6 + +No issues found. +``` + +### 4. Run + +```bash +$ docker agent run +``` + +With no config file, the default agent picks the provider you configured. To name a model explicitly, use `--model` or the `model` field in your config: + +```bash +$ docker agent run --model anthropic/claude-sonnet-4-5 +``` + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A helpful coding assistant + instruction: You are an expert software developer. +``` + +## Path B: Local Model (Docker Model Runner) + +Docker Model Runner (DMR) runs open models on your own machine: no API key, no per-token cost, and prompts never leave your computer. + +### 1. Install Docker Model Runner + +Model Runner ships with [Docker Desktop](https://www.docker.com/products/docker-desktop/) (enable it under **Settings > AI**) and is also available for Docker Engine. Check that it responds: + +```bash +$ docker model status +``` + +If the command is missing or fails, follow the [Model Runner get-started guide](https://docs.docker.com/ai/model-runner/get-started/). + +### 2. Pull a model + +```bash +$ docker model pull ai/qwen3 +``` + +`ai/qwen3` is the model Docker Agent reaches for by default, but any model from the [Docker Hub `ai` catalog](https://hub.docker.com/u/ai) works. Pick one sized for your machine's memory. List what you have locally: + +```bash +$ docker model ls +``` + +### 3. Verify + +```bash +$ docker agent doctor +``` + +```text +User configuration + ~/.config/cagent/config.yaml: ok + +Model provider credentials + PROVIDER STATUS CREDENTIAL SOURCE + anthropic not set ANTHROPIC_API_KEY - + ... + +Docker Model Runner + Status: reachable, 1 model(s) pulled: + - ai/qwen3:latest + +Model auto-selection + auto -> dmr/ai/qwen3:latest + +No issues found. +``` + +### 4. Run + +```bash +$ docker agent run --model dmr/ai/qwen3 +``` + +Or in your config: + +```yaml +agents: + root: + model: dmr/ai/qwen3 + description: A local assistant + instruction: You are a helpful assistant. +``` + +When no cloud key is configured, bare `docker agent run` auto-selects a pulled local model, so after `docker model pull` you can run with no flags at all. The [Docker Model Runner provider page](../../providers/dmr/index.md) covers context size, runtime flags, and other tuning options. + +## Path C: Custom OpenAI-compatible Endpoint + +If your models are served from your own endpoint (vLLM, LiteLLM, a corporate gateway, an API proxy), register it as a custom provider: you supply its base URL, the API format, and the environment variable holding its API key, if it needs one. Built-in providers such as Groq or Hugging Face don't need this; use [Path A](#path-a-built-in-cloud-provider) and set their credential instead. + +The interactive wizard is the quickest way: + +```bash +$ docker agent setup # pick "Custom OpenAI-compatible endpoint" +``` + +Or define the provider once in your user configuration (`~/.config/cagent/config.yaml`): + +```yaml +providers: + myprovider: + base_url: https://llm.corp.example.com/v1 + api_type: openai_chatcompletions + token_key: MYPROVIDER_API_KEY +``` + +Its models then work with every command: + +```bash +$ docker agent models --provider myprovider +$ docker agent run --model myprovider/<model> +``` + +See [Provider Definitions](../../providers/custom/index.md#global-providers-user-configuration) for the full reference, including per-agent-file providers and gateway behavior. + +## Path D: Claude Code Harness (Claude Subscription) + +If you already pay for a Claude subscription, an agent can delegate its work to +the official Claude Code CLI instead of calling a model API. This is an +**external CLI, not provider API access**: Docker Agent launches `claude`, +which authenticates with its own subscription login — no `ANTHROPIC_API_KEY`, +no Docker Model Runner, and no token ever passes through Docker Agent. + +### 1. Install and log in + +Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code), then +log in **as the same OS user and environment that run `docker agent`**: + +```bash +$ claude auth login --claudeai # interactive, opens a browser +$ claude auth status --text # verify +``` + +### 2. Create a harness agent + +`docker agent setup` (pick "Claude Code harness") generates this file for you, +or write it yourself: + +```yaml +# claude-code-agent.yaml +agents: + root: + description: Claude Code running on your Claude subscription + harness: + type: claude-code + effort: medium # low | medium | high | xhigh | max; omit for the Claude Code default +``` + +### 3. Verify and run + +```bash +$ docker agent doctor claude-code-agent.yaml # checks the CLI is installed and logged in +$ docker agent run claude-code-agent.yaml +``` + +The harness runs the CLI non-interactively and bypasses Claude Code's +permission prompts, so use it in a repository you trust — see the security +notes and full field reference in [Coding Harnesses](../../features/harnesses/index.md). + +## Check Your Setup Anytime + +`docker agent doctor` reports which providers have credentials (and from which source), whether Docker Model Runner is reachable and which models are pulled, and which model `auto` would pick. Secret values are never printed. + +```bash +$ docker agent doctor # credential, DMR, and auto-selection state +$ docker agent doctor ./agent.yaml # also check that file's requirements +``` + +It exits non-zero when something would block a run, which makes it usable as a CI preflight. See the [CLI reference](../../features/cli/index.md#docker-agent-doctor). + +## What's Next? + +- [**Quick Start**](../quickstart/index.md) — run your first agent now that a model is available. +- [**Models**](../../concepts/models/index.md) — inline vs. named models, fallbacks, and `auto` selection. +- [**Managing Secrets**](../../guides/secrets/index.md) — every way to store credentials, compared. +- [**Troubleshooting**](../../community/troubleshooting/index.md#missing-credentials-or-model-errors) — decode "no model available" and credential errors. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/_index.md b/_vendor/github.com/docker/docker-agent/docs/guides/_index.md new file mode 100644 index 000000000000..3e7b3780ad13 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/_index.md @@ -0,0 +1,5 @@ +--- +title: "Guides" +description: "Practical guides for building and running agents." +weight: 70 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md new file mode 100644 index 000000000000..67027ff65c03 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md @@ -0,0 +1,149 @@ +--- +title: "Managing Context & Compaction" +description: "How to keep long Docker Agent sessions from filling the model's context window: automatic and on-demand compaction, trimming tool results, and reading the context gauge." +keywords: docker agent, ai agents, guides, context window, compaction, session compaction +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/guides/compaction/ +--- + +_How to keep long-running sessions from filling the model's context window._ + +## Why long sessions fill the context window + +Every model has a fixed context window — a maximum number of tokens it can read per request. As a session grows, the system prompt, tool definitions, prompt files, and the full message history (including every tool call and its result) all count against that budget. A long-running agent — one that reads many files, runs many commands, or just keeps chatting for a while — eventually approaches the limit. Once a request no longer fits, the model provider rejects it and the session stalls. + +Docker Agent addresses this with **compaction**: replacing older parts of the conversation with a compact AI-generated summary, freeing up room for the session to keep going. This guide covers the levers you have — automatic compaction, on-demand compaction, and trimming individual tool results — and how to read the context gauge so you know where a session stands. + +## Let Docker Agent compact automatically + +By default, every agent proactively compacts its own session once estimated token usage crosses **90%** of the model's context window: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A long-running research assistant + instruction: You are a helpful assistant. +``` + +No configuration is required to get this behavior — it's on by default. Three fields let you tune it: + +| Field | Where | Description | +| --- | --- | --- | +| `session_compaction` | agent | Set to `false` to disable automatic compaction entirely for this agent (both the proactive threshold trigger and the post-overflow auto-recovery). The manual `/compact` command still works. Default: `true`. | +| `compaction_threshold` | agent or model | Fraction of the context window (greater than `0`, at most `1`) at which proactive compaction fires. A value set on the model takes precedence over the agent-level value. Default: `0.9`. | +| `compaction_model` | agent, model, or provider | Delegate the compaction (summary-generation) call to a different, usually cheaper and faster, model. The agent-level value wins, then the model-level value, then the provider-level default. | + +Lower the threshold to compact earlier and keep individual requests smaller and cheaper; raise it to keep more verbatim history in context before the first summary happens: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + # Compact at 80% of the window instead of the default 90%. + compaction_threshold: 0.8 +``` + +Compaction itself is a model call — feeding the full conversation to a model and asking for a summary — and it's the most expensive call in a session simply because it's the one that runs when the context is largest. There's rarely a reason to spend your primary reasoning model on it. Point `compaction_model` at something smaller instead; every other call still runs on the primary model: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast + fast: + provider: anthropic + model: claude-haiku-4-5 +``` + +> [!IMPORTANT] +> **Context window mismatch** +> +> If `compaction_model` has a **smaller** context window than the primary model, Docker Agent triggers compaction against the smaller window so the summary call can always ingest the full conversation. Pair the primary model with a compaction model whose window is at least as large to keep the proactive trigger aligned with the primary model's window. +> +> The `/context` header and the sidebar's context gauge surface this cap when it applies: the `/context` header shows a second line reading "compaction cap: `<model>` • `<N>` tokens", and the sidebar shows a short "⚠ capped" marker. Live-sessions rows do not carry cap wording; the sidebar marker deliberately doesn't repeat the model name or figure — the `/context` header is the sole authority on why the reported limit is smaller than the primary model's own window. + +Disable compaction only when you specifically want a session to keep full, unabridged history and are willing to risk hitting the context limit: + +```yaml +agents: + archivist: + model: anthropic/claude-sonnet-4-5 + description: An assistant that never auto-compacts its sessions. + instruction: You keep full conversation history and never lose context. + session_compaction: false +``` + +See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) and [`examples/compaction_threshold.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_threshold.yaml) for complete configurations, and [Delegating Session Compaction](../../configuration/models/index.md#delegating-session-compaction) in the Model Config reference for the full field-level details. + +## Compact on demand + +You don't have to wait for the automatic threshold. Two TUI commands give you direct control: + +- **`/compact`** — summarize and compact the current session's history right now, regardless of how full the context window is. Useful before starting a new phase of work that doesn't need the earlier detail. +- **`/context`** — open a context-window breakdown: estimated tokens per category (system prompt, tool definitions, prompt files, messages, tool results, compaction summary), a **Live sessions** view listing the current session plus every running sub-agent session with its own context budget, and a per-file inventory of attachments and prompt files. When a compaction has occurred, the dialog also displays the verbatim text of the most recent compaction summary, preserving hard newlines and soft-wrapping long lines to the dialog width. + +From `/context`, select any live session with the arrow keys and press <kbd>Enter</kbd> to explicitly compact it — including a sub-agent's session, not just the main one. This is the only way cross-agent compaction happens: there's no idle-triggered automatic compaction of sub-agent sessions, so a long-running background agent stays under your control. The request is queued onto the target session's own run loop and applied at the next safe point between model turns, so it never corrupts an in-flight turn. + +```bash +$ docker agent run agent.yaml +# ... work for a while ... +# Type /context to see the current breakdown, or /compact to summarize now +``` + +## Trim tool results to save room + +Compaction deals with the whole conversation at once. For sessions dominated by a few oversized tool results — a full build log, a large file dump — three agent-level fields let you cap the damage before it ever reaches compaction: + +| Field | What it bounds | Behavior | +| --- | --- | --- | +| `max_tool_result_tokens` | Each tool result, as it's added to the session | Oversized results are truncated **middle-out**: the head and tail are kept (usually the most informative parts) and the removed middle is replaced with a truncation marker. | +| `max_old_tool_call_tokens` | The total budget for **old** tool call arguments and results | Once older tool calls exceed the budget, their content is replaced wholesale with a placeholder — freeing context space without touching recent, still-relevant calls. | +| `num_history_items` | The number of non-system conversation messages kept in history | A message-**count** limit, not a token budget. The oldest non-protected messages are dropped first once the count is exceeded; **system and user messages are always protected** and are never counted against or removed by this limit, so the assembled history can exceed `num_history_items` and every user message survives even a long single-turn agentic loop. | + +`max_tool_result_tokens` and `max_old_tool_call_tokens` are approximated as `len/4` tokens (the industry rule-of-thumb of ~4 characters per token); `num_history_items` counts messages, not tokens. All three are disabled by default (`0`). Set a positive value to enable them: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: An assistant whose tool results are capped at ~2000 tokens each. + instruction: | + You are a helpful assistant with shell access. Very large command + outputs are truncated in the middle — the beginning and end are + always preserved, and a marker shows where content was removed. + max_tool_result_tokens: 2000 + toolsets: + - type: shell +``` + +> [!TIP] +> **Use both together** +> +> `max_tool_result_tokens` bounds each result the moment it's recorded; `max_old_tool_call_tokens` reclaims space from calls that are no longer fresh. Combine them on tool-heavy agents (shell, filesystem) to keep the session lean well before it approaches the compaction threshold. + +See [`examples/max_tool_result_tokens.yaml`](https://github.com/docker/docker-agent/blob/main/examples/max_tool_result_tokens.yaml) for a complete example, and [Agent Config](../../configuration/agents/index.md#properties-reference) for the full field reference. + +## Read the context gauge + +The TUI's sidebar token-usage section (and the fill bar in the [lean TUI](../../features/tui/index.md#lean-tui) status line) color-escalates as a session approaches its compaction threshold, so you can see trouble coming before a request fails: + +| State | Color | Trigger | +| --- | --- | --- | +| Normal | (default) | Usage below 75% of the compaction threshold | +| Warning | Orange | Usage at or above 75% of the compaction threshold | +| Critical | Red | Usage at or above 95% of the compaction threshold | + +While a compaction is running, the percentage is replaced by a **"compacting…"** indicator; token counts remain visible in the lean TUI status line. The thresholds scale with the agent's configured `compaction_threshold` (default `0.9`), so a custom value keeps a predictable visual runway — for example, a `compaction_threshold: 0.8` session turns orange at 60% usage (75% of 0.8) instead of 67.5%. + +Open `/context` at any time for the full per-category breakdown behind that percentage. + +## What happens to cost across compaction + +Compaction summarizes history, but it never resets what a session has actually cost you. Session cost tracking is **monotonic across compaction**: the running total only ever goes up, even though the summarized conversation itself is now smaller. Check `/cost` to see the current breakdown at any point, before or after a compaction has run. + +## Related: deferred tool loading + +Compaction and result trimming manage context that's already in the session. If large toolsets are inflating your **starting** context instead — many MCP servers, hundreds of tools — look at [deferred tool loading](../../configuration/tools/index.md#deferred-tool-loading), which registers a toolset's tools lazily instead of eagerly at startup. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md new file mode 100644 index 000000000000..909729e16f3c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md @@ -0,0 +1,650 @@ +--- +title: "Go SDK" +description: "Use Docker Agent as a Go library to embed AI agents in your applications." +keywords: docker agent, ai agents, guides, go sdk +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/guides/go-sdk/ +--- + +_Use Docker Agent as a Go library to embed AI agents in your applications._ + +## Overview + +Docker Agent can be used as a Go library, allowing you to build AI agents directly into your Go applications. This gives you full programmatic control over agent creation, tool integration, and execution. + +> [!NOTE] +> **Import Path** +> +> ```go +> import "github.com/docker/docker-agent/pkg/..." +> ``` + +## Core Packages + +| Package | Purpose | +| ---------------------- | ---------------------------------------- | +| `pkg/agent` | Agent creation and configuration | +| `pkg/runtime` | Agent execution and event streaming | +| `pkg/session` | Conversation state management | +| `pkg/team` | Multi-agent team composition | +| `pkg/tools` | Tool interface and utilities | +| `pkg/tools/builtin` | Built-in tools (shell, filesystem, etc.) | +| `pkg/model/provider/*` | Model provider clients | +| `pkg/config/latest` | Configuration types | +| `pkg/environment` | Environment and secrets | +| `pkg/embeddedchat` | Headless chat session for embedding the agent runtime in a custom UI | +| `pkg/tui/components/toolconfirm` | Tool-confirmation policy: `Decision` enum, `BuildPermissionPattern`, key bindings, and rejection-reason presets. Share this instead of copying the permission-pattern logic. | +| `pkg/tui/service` | `StaticSessionState` — a `SessionStateReader` with conservative fixed values, for rendering message/tool views outside the full TUI app. Replaces hand-rolled nine-method stubs. | +| `pkg/tui/animation` | `Stopper` / `StopView` — animation lifecycle contract. Call `StopAnimation` on views removed from the UI to prevent leaked tick subscriptions. | +| `pkg/tui/components/transcript` | Embedded transcript view with read-only `Messages()` accessor for observing conversation structure in host tests and persistence layers. | + +## Embedding TUI Components + +When building custom UIs on top of Docker Agent's TUI primitives, four packages define the contracts that keep the runtime and the UI in sync: + +- **`pkg/tui/components/toolconfirm`** — import this package for the permission-decision policy rather than copying the pattern-building logic. The `Decision` enum, `BuildPermissionPattern` helper, and rejection-reason presets are the canonical source of truth: whatever pattern is shown to the user in the confirmation dialog is exactly the pattern granted to the runtime. +- **`pkg/tui/service`** — use `StaticSessionState` as a stub `SessionStateReader` when rendering individual message or tool views outside the full TUI app. It returns conservative fixed values for all nine interface methods, eliminating the need for hand-rolled stubs. +- **`pkg/tui/animation`** — implement `animation.Stopper` on any view that owns a tick-based animation. Call `StopAnimation` whenever a view is removed from the UI hierarchy to prevent leaked `time.Tick` subscriptions from firing against a dead view. +- **`pkg/tui/components/transcript`** — embed the transcript view for displaying conversation history. Use the `Messages()` method to read the current slice of transcript messages (treat as read-only — mutations desync renders). This is useful for host-side tests asserting on chat history, and for persistence layers that need to snapshot conversation state. + +## Headless Embedded Chat (`pkg/embeddedchat`) + +`pkg/embeddedchat` is a thin wrapper around the Docker Agent runtime that lets you drive an agent from your own UI instead of running Docker Agent's Bubble Tea application. It handles runtime construction, event projection, and conversation state, exposing a simple `Send` / `Confirm` / `Restart` / `Close` API. + +### Creating a session + +```go +import ( + "context" + "fmt" + "strings" + + dagentcfg "github.com/docker/docker-agent/pkg/config" + dagentruntime "github.com/docker/docker-agent/pkg/runtime" + "github.com/docker/docker-agent/pkg/embeddedchat" +) + +chat, err := embeddedchat.New(ctx, embeddedchat.Config{ + // AgentSource can be a file path, raw YAML bytes, or an OCI reference. + AgentSource: dagentcfg.NewBytesSource("agent", []byte(agentYAML)), +}) +if err != nil { + return err +} +defer chat.Close() +``` + +### Sending a message and reading events + +`Send` appends the user message to the conversation and returns a channel of `Event` values. Drain the channel until it closes. + +```go +events, err := chat.Send(ctx, "Hello! What can you do?") +if err != nil { + return err +} + +var response strings.Builder +for ev := range events { + switch { + case ev.Text != "": + response.WriteString(ev.Text) + case ev.Tool != nil && ev.Tool.NeedsConfirmation: + // Approve the pending tool call (use ResumeApproveSession to allow all). + if err := chat.Confirm(ctx, dagentruntime.ResumeApprove()); err != nil { + return err + } + case ev.Tool != nil && ev.Tool.Finished: + fmt.Printf("[tool %s finished]\n", ev.Tool.Def.Name) + case ev.Err != nil: + fmt.Printf("error: %v\n", ev.Err) + case ev.Done: + fmt.Println("\n[turn complete]") + } +} +fmt.Print(response.String()) +``` + +### Restarting the conversation + +To start a fresh conversation without recreating the runtime: + +```go +if err := chat.Restart(); err != nil { + return err +} +``` + +### Event types + +| Field | When set | +| -------------- | ------------------------------------------------------------------------ | +| `Text` | Assistant text delta; accumulate into a string for the full reply. | +| `Tool` | A tool call started, needs confirmation, or finished. | +| `Tool.NeedsConfirmation` | Runtime is blocked until `Confirm` is called. | +| `Tool.Finished` | Tool call completed; `Tool.IsError` is true if it errored. | +| `Err` | A user-facing runtime error; no further content events follow. | +| `Done` | Clean end of turn; no more events. | +| `RuntimeEvent` | The original `runtime.Event` for callers that need the full stream. | + +For advanced use (custom elicitation, raw event inspection), call `chat.Runtime()` to access the underlying `runtime.Runtime` directly. + +> [!WARNING] +> **Breaking change: `Runtime.ResumeElicitation` (#3584)** +> +> `Runtime.ResumeElicitation` gained an `elicitationID` parameter so responses can +> be correlated with a specific concurrent elicitation request (needed once +> multiple background jobs can be eliciting input at the same time). It is +> declared **variadic** (`elicitationID ...string`) specifically so existing +> *callers* of the 3-argument form keep compiling unchanged — `rt.ResumeElicitation(ctx, action, content)` +> still works and falls back to resolving the sole pending request. +> +> If you implement your own `runtime.Runtime` (rather than embedding +> `runtime.LocalRuntime`/`runtime.RemoteRuntime`), you do need to update your +> method's signature to match, and also add an `OnElicitationRequest(handler +> func(runtime.Event))` method (a no-op is fine if your runtime never raises +> elicitations) — both are required interface methods, matching the existing +> no-op-able pattern already used by `OnToolsChanged`/`OnBackgroundEvent`. + +## Optional Provider Build Tags + +By default Docker Agent includes all four cloud providers (OpenAI, Anthropic, Google, Amazon Bedrock). When embedding Docker Agent in your own binary you can compile out unneeded providers — together with their transitive SDK dependencies — to reduce binary size. + +Each provider is gated by a negative build tag prefixed `docker_agent_` to avoid collisions with your own project's tags: + +| Build tag | Provider dropped | Major dependency removed | +| ---------------------------- | ------------------------ | ------------------------------------------------- | +| `docker_agent_no_openai` | OpenAI | `github.com/openai/openai-go` | +| `docker_agent_no_anthropic` | Anthropic | `github.com/anthropics/anthropic-sdk-go` (partial — see note) | +| `docker_agent_no_google` | Google / Vertex AI | `google.golang.org/genai`, Vertex auth stack, and indirectly the Anthropic and OpenAI SDKs via Vertex Model Garden | +| `docker_agent_no_bedrock` | Amazon Bedrock | `github.com/aws/aws-sdk-go-v2` stack (the largest provider dependency tree) | + +To build without Bedrock and OpenAI: + +```bash +go build -tags 'docker_agent_no_bedrock docker_agent_no_openai' ./... +``` + +Requesting a model whose provider was compiled out fails at construction time with a clear `"not compiled into this build"` error. The `dmr` (Docker Model Runner) provider and the rule-based router are always compiled in. + +> [!WARNING] +> **Anthropic + Google dependency** +> +> The Google provider's Vertex Model Garden support also imports the Anthropic SDK, so the Anthropic dependency is only fully removed when _both_ `docker_agent_no_anthropic` and `docker_agent_no_google` are set. + +## RAG Toolset (opt-out) + +The RAG toolset (`type: rag`) is included in `NewDefaultToolsetRegistry()` (from `pkg/teamloader/toolsets`) and `loaderdefaults.Opts()` (from `pkg/teamloader/defaults`, using the conventional import alias `loaderdefaults`). + +The underlying tree-sitter code parser uses cgo, but build-tag guards in `pkg/rag/treesitter` mean importing the package is safe regardless of `CGO_ENABLED`: with `CGO_ENABLED=0` the parser stub compiles in and returns a runtime error on first use rather than failing at compile time. + +If you want to exclude the RAG toolset from your binary entirely — surfacing a load-time warning on the agent rather than a deferred runtime error from the `!cgo` stub — remove it from the registry before passing it to `teamloader.Load`: + +```go +import ( + "github.com/docker/docker-agent/pkg/teamloader" + loadertoolsets "github.com/docker/docker-agent/pkg/teamloader/toolsets" +) + +// Opt out of the RAG toolset; a config that declares type: rag attaches +// a load-time warning to the agent instead of failing at document processing. +creators := loadertoolsets.DefaultToolsetCreators() +delete(creators, "rag") +registry := teamloader.NewToolsetRegistry(creators) +``` + +Pass the custom registry via `teamloader.WithToolsetRegistry(registry)` when calling `teamloader.Load`. Note that `teamloader.Load()` does not return an error for unknown toolset types — the failure is recorded as a load-time warning and can be retrieved with `agent.DrainWarnings()`; it is also surfaced via logging and TUI notifications. + +## Registering Custom Built-in Themes + +When embedding Docker Agent, you can contribute your own built-in themes via `styles.RegisterBuiltinThemes`. Registered themes integrate seamlessly with the existing theme picker, `/theme` command, and `settings.theme` config key — they behave exactly like Docker Agent's own bundled themes. + +```go +import ( + "embed" + + "github.com/docker/docker-agent/pkg/tui/styles" +) + +//go:embed themes/*.yaml +var brandThemes embed.FS + +// Call at startup, before applying any persisted theme: +if err := styles.RegisterBuiltinThemes(brandThemes); err != nil { + return err +} +``` + +Each theme file lives at `themes/<name>.yaml` inside the embedded filesystem and is a **partial override** — only the colors you want to change are required; everything else falls back to `DefaultTheme()`. + +```yaml +# themes/brand.yaml +name: Brand +colors: + accent: "#FF6A00" + background: "#1A0F0A" +``` + +If `name:` is omitted, Docker Agent uses the filename stem as the display name in the theme picker (e.g. `brand` from `themes/brand.yaml`). + +To replace Docker Agent's default theme entirely, ship the file as `themes/default.yaml` — it masks the bundled default while inheriting any colors you don't set. + +**Semantics:** + +- Registered sources take precedence over bundled themes; a registered ref overrides a bundled theme of the same name. +- Among multiple registered sources, last-registered wins on a collision. +- `RegisterBuiltinThemes` validates eagerly (nil fs, missing `themes/` dir) so errors surface at registration time, not at picker time. + +## MCP OAuth Token Persistence + +By default, MCP OAuth tokens are stored in-memory only and are not persisted across process restarts. The CLI registers a keyring-backed store automatically at startup; when embedding Docker Agent as a library you must do this yourself if you want tokens to survive restarts. + +Call `keyringstore.Register()` **before** any MCP toolset is initialised to enable the OS keyring-backed token store: + +```go +import "github.com/docker/docker-agent/pkg/tools/mcp/keyringstore" + +func main() { + // Must be called before teamloader.Load() on configs with remote MCP + // toolsets; calling it after the store is created panics. + keyringstore.Register() + // ... rest of your startup code +} +``` + +> [!WARNING] +> **Call order matters** +> +> If `keyringstore.Register()` is called after the default token store has already been lazily initialised, Docker Agent panics. The store is initialised when any remote MCP toolset is constructed — which happens inside `teamloader.Load()`. Always call `keyringstore.Register()` before calling `teamloader.Load()` on a config that includes remote MCP toolsets. + +If you do not need persistent OAuth tokens (for example, in short-lived batch jobs or tests), omit the call and tokens will be kept in-memory for the process lifetime. + +## JavaScript Command Expressions (opt-in) + +Slash-command instructions can embed `${...}` JavaScript expressions (`${args[0]}`, `${args.join(" ")}`, `${tool({...})}`). Evaluating them requires the goja JavaScript engine, which is deliberately kept out of `pkg/runtime`'s import graph so code-built embedders don't link it by default. + +The CLI, `teamloader.Load()`, `pkg/cli.Run()` and `embeddedchat/defaults` enable it automatically. If you build teams in code, call `runtime.ResolveCommand` (or `cli.PrepareUserMessage`) directly **and** use `${...}` expressions in commands, register the evaluator yourself: + +```go +import "github.com/docker/docker-agent/pkg/runtime/jscommands" + +func main() { + jscommands.Register() + // ... rest of your startup code +} +``` + +Without the registration, `${...}` expressions are left unexpanded and a warning naming the fix is logged; everything else about command resolution (including the legacy `!tool(...)` syntax) works as usual. + +## Basic Example + +Create a simple agent and run it: + +```go +package main + +import ( + "context" + "fmt" + "log" + "os/signal" + "syscall" + + "github.com/docker/docker-agent/pkg/agent" + "github.com/docker/docker-agent/pkg/config/latest" + "github.com/docker/docker-agent/pkg/environment" + "github.com/docker/docker-agent/pkg/model/provider/openai" + "github.com/docker/docker-agent/pkg/runtime" + "github.com/docker/docker-agent/pkg/session" + "github.com/docker/docker-agent/pkg/team" +) + +func main() { + ctx, cancel := signal.NotifyContext(context.Background(), + syscall.SIGINT, syscall.SIGTERM) + defer cancel() + + if err := run(ctx); err != nil { + log.Fatal(err) + } +} + +func run(ctx context.Context) error { + // Create model provider + llm, err := openai.NewClient( + ctx, + &latest.ModelConfig{ + Provider: "openai", + Model: "gpt-4o", + }, + environment.NewDefaultProvider(), + ) + if err != nil { + return err + } + + // Create agent + assistant := agent.New( + "root", + "You are a helpful assistant.", + agent.WithModel(llm), + agent.WithDescription("A helpful assistant"), + ) + + // Create team and runtime + t := team.New(team.WithAgents(assistant)) + rt, err := runtime.New(t) + if err != nil { + return err + } + + // Run with a user message + sess := session.New( + session.WithUserMessage("What is 2 + 2?"), + ) + + messages, err := rt.Run(ctx, sess) + if err != nil { + return err + } + + // Print the response + fmt.Println(messages[len(messages)-1].Message.Content) + return nil +} +``` + +## Custom Tools + +Define custom tools for your agent: + +```go +package main + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/docker/docker-agent/pkg/tools" +) + +// Define the tool's input schema +type AddNumbersArgs struct { + A int `json:"a"` + B int `json:"b"` +} + +// Implement the tool handler +func addNumbers(_ context.Context, toolCall tools.ToolCall) (*tools.ToolCallResult, error) { + var args AddNumbersArgs + if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args); err != nil { + return nil, err + } + + result := args.A + args.B + return tools.ResultSuccess(fmt.Sprintf("%d", result)), nil +} + +func main() { + // Create the tool definition + addTool := tools.Tool{ + Name: "add", + Category: "math", + Description: "Add two numbers together", + Parameters: tools.MustSchemaFor[AddNumbersArgs](), + Handler: addNumbers, + } + + // Use with an agent + calculator := agent.New( + "root", + "You are a calculator. Use the add tool for arithmetic.", + agent.WithModel(llm), + agent.WithTools(addTool), + ) + // ... +} +``` + +## Streaming Responses + +Process events as they happen: + +```go +func runStreaming(ctx context.Context, rt runtime.Runtime, sess *session.Session) error { + events := rt.RunStream(ctx, sess) + + for event := range events { + switch e := event.(type) { + case *runtime.StreamStartedEvent: + fmt.Println("Stream started") + + case *runtime.AgentChoiceEvent: + // Print response chunks as they arrive + fmt.Print(e.Content) + + case *runtime.ToolCallEvent: + fmt.Printf("\n[Tool call: %s]\n", e.ToolCall.Function.Name) + + case *runtime.ToolCallConfirmationEvent: + // Auto-approve tool calls + rt.Resume(ctx, runtime.ResumeRequest{ + Type: runtime.ResumeTypeApproveSession, + }) + + case *runtime.ToolCallResponseEvent: + fmt.Printf("[Tool response: %s]\n", e.Response) + + case *runtime.StreamStoppedEvent: + fmt.Println("\nStream stopped") + + case *runtime.ErrorEvent: + return fmt.Errorf("error: %s", e.Error) + } + } + + return nil +} +``` + +## Multi-Agent Teams + +Create agents that delegate to sub-agents: + +```go +package main + +import ( + "github.com/docker/docker-agent/pkg/agent" + "github.com/docker/docker-agent/pkg/team" + "github.com/docker/docker-agent/pkg/tools/builtin" +) + +func createTeam(llm provider.Provider) *team.Team { + // Create a child agent + researcher := agent.New( + "researcher", + "You research topics thoroughly.", + agent.WithModel(llm), + agent.WithDescription("Research specialist"), + ) + + // Create root agent with sub-agents + coordinator := agent.New( + "root", + "You coordinate research tasks.", + agent.WithModel(llm), + agent.WithDescription("Team coordinator"), + agent.WithSubAgents(researcher), + agent.WithToolSets(builtin.NewTransferTaskTool()), + ) + + return team.New(team.WithAgents(coordinator, researcher)) +} +``` + +## Built-in Tools + +Use Docker Agent's built-in tools: + +```go +import ( + "github.com/docker/docker-agent/pkg/config" + "github.com/docker/docker-agent/pkg/tools/builtin" +) + +func createAgentWithBuiltinTools(llm provider.Provider) *agent.Agent { + // Runtime config for tools that need it + rtConfig := &config.RuntimeConfig{ + Config: config.Config{ + WorkingDir: "/path/to/workdir", + }, + } + + return agent.New( + "root", + "You are a developer assistant.", + agent.WithModel(llm), + agent.WithToolSets( + // Shell tool for running commands + builtin.NewShellTool(os.Environ(), rtConfig), + // Filesystem tools + builtin.NewFilesystemTool(rtConfig.Config.WorkingDir), + // Think tool for reasoning + builtin.NewThinkTool(), + // Todo tool for task tracking + builtin.NewTodoTool(), + ), + ) +} +``` + +## HTTP Middleware / Transport Wrappers + +Use `options.WithHTTPTransportWrapper` to inject HTTP middleware into the transport chain of all provider clients built by Docker Agent. This is useful for request tracing, injecting custom headers, collecting metrics, or any other cross-cutting concern at the HTTP layer. + +```go +import ( + "net/http" + + "github.com/docker/docker-agent/pkg/model/provider/options" +) + +type headerTransport struct { + base http.RoundTripper +} + +func (t *headerTransport) RoundTrip(req *http.Request) (*http.Response, error) { + req = req.Clone(req.Context()) + req.Header.Set("X-Request-Source", "my-app") + return t.base.RoundTrip(req) +} + +// Example: add a custom header to every outbound LLM request +wrapper := options.WithHTTPTransportWrapper( + func(base http.RoundTripper) http.RoundTripper { + return &headerTransport{base: base} + }, +) + +client, err := openai.NewClient(ctx, &latest.ModelConfig{ + Provider: "openai", + Model: "gpt-4o", +}, env, wrapper) +``` + +The wrapper receives the already-instrumented transport (OpenTelemetry, SSE decompression, Desktop proxy support) as its `base` argument, so wrapping it preserves all built-in behaviour. + +**Supported providers:** Anthropic, OpenAI, Gemini (GeminiAPI backend), Bedrock. Works in both direct and gateway/proxy mode. + +> [!WARNING] +> **Vertex AI not supported** +> +> Vertex AI uses an ADC-managed HTTP client that Docker Agent cannot intercept. When a transport wrapper is set, Docker Agent falls back to the GeminiAPI backend instead of Vertex AI — a debug message is logged. + +In **gateway mode** the wrapper is called on every LLM request because gateway clients are rebuilt each call for short-lived auth tokens. In **direct mode** it is called once at client construction. Rate-limit responses (HTTP 429) are classified as non-retryable by the runtime and cause the model chain to skip to the next fallback, so wrappers that track per-request outcomes will observe these as failures rather than retried calls. + +Returning `nil` from your wrapper function is not allowed; Docker Agent logs a warning and keeps the original transport instead. + +## Using Different Providers + +```go +import ( + "github.com/docker/docker-agent/pkg/model/provider/anthropic" + "github.com/docker/docker-agent/pkg/model/provider/gemini" + "github.com/docker/docker-agent/pkg/model/provider/openai" +) + +// OpenAI +openaiClient, _ := openai.NewClient(ctx, &latest.ModelConfig{ + Provider: "openai", + Model: "gpt-4o", +}, env) + +// Anthropic +anthropicClient, _ := anthropic.NewClient(ctx, &latest.ModelConfig{ + Provider: "anthropic", + Model: "claude-sonnet-4-5", +}, env) + +// Google Gemini +geminiClient, _ := gemini.NewClient(ctx, &latest.ModelConfig{ + Provider: "google", + Model: "gemini-3.5-flash", +}, env) +``` + +## Session Options + +```go +import "github.com/docker/docker-agent/pkg/session" + +sess := session.New( + // Set a title for the session + session.WithTitle("Code Review Task"), + + // Add user message + session.WithUserMessage("Review this code for bugs"), + + // Limit iterations + session.WithMaxIterations(20), +) +``` + +## Error Handling + +```go +messages, err := rt.Run(ctx, sess) +if err != nil { + if errors.Is(err, context.Canceled) { + // User cancelled + log.Println("Operation cancelled") + return nil + } + if errors.Is(err, context.DeadlineExceeded) { + // Timeout + log.Println("Operation timed out") + return nil + } + // Other error + return fmt.Errorf("runtime error: %w", err) +} + +// Check for errors in the event stream +for event := range rt.RunStream(ctx, sess) { + if errEvent, ok := event.(*runtime.ErrorEvent); ok { + return fmt.Errorf("stream error: %s", errEvent.Error) + } +} +``` + +## Complete Example + +See the [examples/golibrary](https://github.com/docker/docker-agent/tree/main/examples/golibrary) directory for complete working examples: + +- `simple/` — Basic agent with no tools +- `tool/` — Custom tool implementation +- `stream/` — Streaming event handling +- `multi/` — Multi-agent with sub-agents +- `builtintool/` — Using built-in tools diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md new file mode 100644 index 000000000000..76a87bd4d505 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md @@ -0,0 +1,225 @@ +--- +title: "Running Agents Headless & in CI" +description: "Run Docker Agent without a TUI: structured JSON output, event hooks, sandboxed CI isolation, and a GitHub Actions example." +keywords: docker agent, ai agents, guides, headless, ci, github actions, sandbox +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/guides/headless/ +--- + +_Run Docker Agent without a TUI: structured JSON output, event hooks, sandboxed CI isolation, and a GitHub Actions example._ + +## `--exec` Mode Basics + +`--exec` runs an agent without the interactive TUI: output goes to stdout and the process exits when the conversation is done. It's the mode to use in scripts, CI, and any context without a terminal. + +```bash +# One-shot task, message as an argument +$ docker agent run --exec agent.yaml "Summarize the open issues in this repo" + +# Pipe the message via stdin instead +$ echo "Summarize the open issues in this repo" | docker agent run --exec agent.yaml - + +# Multiple messages are processed as a multi-turn conversation, in order +$ docker agent run --exec agent.yaml "question 1" "question 2" "question 3" +``` + +See [`docker agent run --exec`](../../features/cli/index.md#docker-agent-run---exec) for the full flag reference. + +## Choosing a Large-Input Strategy + +Docker Agent has several unrelated mechanisms for getting a large document, file, or dataset in front of an agent. Which one fits depends on whether the content is local to the machine running Docker Agent, how often it needs to be revisited, and whether you're driving the agent through the CLI/TUI or over one of the HTTP servers: + +| You have… | Use… | Notes | +| --- | --- | --- | +| A file on disk, for one interactive turn | `@path` or `/attach` in the TUI (see [File Attachments](../../features/tui/index.md#file-attachments)), `--attach` at startup (seeds an interactive TUI run just as readily as `--exec`), or `/attach` under `--exec` | Read from the local filesystem and inlined into the message once it clears a local admission check. That never crosses Docker Agent's own inbound HTTP boundary for a local (non-`--remote`) run or for the *first* message of a `--remote` run — but a locally resolved attachment added to a *later* message on a remote run does cross it; see the remote-runtime row below. The admission check itself, and how a rejection is reported, differ by entry point; see the read-time limits below. | +| Instructions/context every agent turn should see | `add_prompt_files` in the agent config, or `--prompt-file` on the CLI (see [Prompt Files](../../configuration/agents/index.md#prompt-files)) | Re-read from disk **in full** on every turn and injected as instruction context; local, not an HTTP upload, and not subject to the attachment inlining checks above — memory and the model's context window are the practical ceilings. | +| A one-off piece of text for a **local** headless run | stdin, without `--remote` (see [`--exec` Mode Basics](#--exec-mode-basics) above) | The piped text becomes the message directly; it never crosses Docker Agent's own inbound HTTP boundary and has no size cap of its own, though Docker Agent may still send it onward to a model/provider over HTTP. | +| A one-off piece of text driving a **remote** runtime | stdin with `docker agent run --remote ... -` | The CLI serializes that stdin text into a native API run request sent to whichever Docker Agent server the `--remote` address points at — a `serve api` process or another run's [`--listen`](../../features/api-server/index.md#listen) control plane, never `serve chat` — so it's measured against that server's own limit: `serve api`'s configurable `--max-request-size`, or a `--listen` control plane's fixed, non-configurable 1 MiB cap. See the HTTP body limit below. That *initial* request carries only message text: conversion currently drops any attachment resolved locally (`@path`/`/attach`, `--attach`) for the first message before it's sent. A *later* message to the same remote run — sent while the agent is still busy, via the default steer behavior or an explicit follow-up (Alt+Enter) — does forward a locally resolved attachment as part of that native API request, so it counts toward the same limit and can 413 like any other oversized request. Client-side `--prompt-file` values are **not** forwarded to a remote runtime either way; prompt files configured on the agent itself (`add_prompt_files`) still resolve, but on the server's filesystem. | +| A document collection you'll query repeatedly, or one too large to inline at all | The [`rag` toolset](../../tools/rag/index.md) | Indexed once in the background; each query retrieves only the relevant chunks into context, instead of the whole collection. | +| An OpenAI-compatible client driving Docker Agent over HTTP | [Chat Server](../../features/chat-server/index.md) | Accepts OpenAI-style `text` and [`image_url`](../../features/chat-server/index.md#image-inputs) content parts. The whole request travels as a single HTTP body capped by that server's `--max-request-size`; a data URL's bytes count toward it, while a remote `http(s)://` image URL is passed to the provider rather than fetched by the chat server, and works only if that provider/model supports it. | +| A native integration driving Docker Agent's own session/control protocol | [API Server](../../features/api-server/index.md) | Supports the documented session, run, and event-streaming flows over a single capped HTTP body; see the note below on the upload contract this does *not* provide. | +| A supervisor process driving an already-running interactive session | An attached run's [`--listen`](../../features/api-server/index.md#listen) control plane | Exposes the same session/follow-up/event-streaming API as the API server, but with a fixed, non-configurable 1 MiB request-body cap and no `--auth-token` — there's no `--max-request-size` or `--auth-token` flag for this surface. Keep it on loopback, a unix socket, or behind an authenticating reverse proxy if it must be reachable from elsewhere. | + +Three independent ceilings apply, and hitting one says nothing about the others: + +1. **The HTTP body limit** — applies to any request reaching one of Docker Agent's three inbound HTTP surfaces: `docker agent serve api`, `docker agent serve chat`, or an interactive run's [`--listen`](../../features/api-server/index.md#listen) control plane. `docker agent run --remote ... -` builds a native run request from stdin and sends it to whichever of `serve api` or a `--listen` control plane the remote address points at — never `serve chat`, which speaks a different protocol. `serve api` and `serve chat` each enforce their own `--max-request-size` (1 MiB default, configurable) and return `413 Request Entity Too Large` above it; a `--listen` control plane enforces the same 1 MiB default but exposes no `--max-request-size` flag (or `--auth-token`) to change it — it's fixed, and reducing the request is the only remedy. See [Troubleshooting: HTTP 413](../../community/troubleshooting/index.md#http-413-request-body-too-large) for how to diagnose and resolve it. Local (non-`--remote`) stdin and prompt files never cross this boundary; a locally resolved `@path`/`/attach`/`--attach` attachment doesn't either for a remote run's initial message, but one added to a later steer or follow-up message on that same remote run does — see the remote-runtime row above. +2. **Local read-time limits, which differ by path** — the TUI and non-TUI (CLI/`--exec`) message assembly don't share one text/binary rule. The TUI (both `/attach` and a typed `@path` reference) runs every file reference through one flat size ceiling *before* it looks at the file's type; non-TUI assembly — the CLI's `--attach` flag and `--exec`'s own `/attach` parsing — inlines text up to its own ceiling and hands supported binary files (images, PDFs) to a separate path with a higher cap, so a binary file that's fine for `--attach`/`--exec` can still be too big for the TUI's flatter, lower ceiling. Either way an oversized file is rejected rather than silently truncated or allowed to exhaust memory, but whether you're actually told about it depends on the surface: only the interactive TUI's `/attach` command shows a visible error notification (with a file-picker fallback), while a bare `@path` reference is only checked speculatively as you type — a rejection there is logged at debug level only, and the reference is left as plain text in your message with no on-screen notice. Outside the interactive TUI, neither the CLI's `--attach` flag nor `--exec`'s `/attach` (which reuses the same non-TUI assembly and rejection path as `--attach`, not the TUI's notification flow) prints anything about a rejected attachment in normal run output — the message just falls back to text-only, and the reason is visible only in the debug log when `--debug` is enabled. Prompt files (`add_prompt_files`/`--prompt-file`) have no equivalent guard — they're read in full on every turn regardless of size, so memory and the model's context window are what actually bound them. +3. **Model/provider context and media limits** — even content that clears the first two layers still has to fit the model's token/context window, and binary attachments (images, PDF, audio, video) only work if the model declares support for that media type (see [Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides)). Exceeding the context window is a separate failure from either limit above — see [Context Window Exceeded](../../community/troubleshooting/index.md#context-window-exceeded). + +> [!NOTE] +> **No file-upload endpoint** +> +> None of Docker Agent's three inbound HTTP surfaces — the API server, the chat server, or an attached run's `--listen` control plane — exposes a multipart file-upload endpoint, and none of them fetches a remote URL on your behalf — the chat server's `image_url` support only ever passes a remote URL through to the provider (see the table above). Content reaches an agent either locally (`@path`/`/attach`, prompt files, `rag`) or embedded directly in the HTTP message body those servers already document; there is no separate attachment channel over any of them. + +## Structured Output for Machines + +Two independent things make an `--exec` run's output easy to parse: how the transcript is emitted, and what shape the model's own answer takes. + +**`--json`** switches the transcript itself from human-readable text to newline-delimited JSON: one JSON object per runtime event (messages, tool calls, tool results, errors, …), instead of formatted text interleaved with tool-call boxes. Pipe it into `jq` or any NDJSON-aware log processor: + +```bash +$ docker agent run --exec agent.yaml --json "List the 5 largest files in this repo" | jq -c 'select(.type == "agent_choice")' +``` + +**`structured_output`** constrains the *model's own response* to a JSON schema you define on the agent, independent of `--json`. Use it when downstream code needs the model's answer in a predictable shape (a list of findings, a classification, …) rather than free-form prose. See [Structured Output](../../configuration/structured-output/index.md) for the full field reference — combine it with `--json` in `--exec` to get both a parseable transcript and a schema-validated final answer. + +## Reacting to Events + +`--on-event <type>=<cmd>` runs a shell command whenever an event of the given type fires, with the event's JSON payload piped to the command's stdin. Use `*=<cmd>` to match every event type. The flag is repeatable. + +> [!WARNING] +> **`--on-event` does nothing under `--exec`** +> +> Event hooks are installed on the interactive App's event bus. A `docker agent run --exec` run returns before that wiring happens, so `--on-event` is silently a no-op there — no error, no hook ever runs. Use `--on-event` with a normal interactive run or `--lean` (which still installs hooks; it just skips the alternate screen). For a headless `--exec` run, get the same effect by parsing the `--json` NDJSON stream yourself and shelling out on the events you care about — for example `stream_stopped`, which fires when a turn ends normally. + +```bash +# Post a Slack notification when the agent finishes a turn (interactive or --lean only) +$ docker agent run agent.yaml --lean --on-event stream_stopped="./notify-slack.sh" "Fix the failing test" + +# Log every event to a file for later inspection +$ docker agent run agent.yaml --lean --on-event "*=cat >> events.ndjson" "Fix the failing test" + +# Headless equivalent: capture the --json NDJSON stream, then react to it yourself +$ docker agent run --exec agent.yaml --json "Fix the failing test" | tee events.ndjson +$ jq -e 'select(.type == "stream_stopped")' events.ndjson >/dev/null && ./notify-slack.sh +``` + +Hooks run asynchronously and are never waited on: each is spawned detached from the run's own context, and the process exits (`os.Exit`) as soon as the run finishes without waiting for, or signaling, any hook subprocess still in flight. A hook's own failure is logged but never fails the run — and, independent of that, its fate at process exit is unspecified: it may keep running as an orphaned process, or it may be torn down by whatever supervises the job (a CI runner tearing down its container, a shell killing its process group, …), depending on your environment rather than on anything docker-agent guarantees. Don't rely on `--on-event` for anything that must demonstrably finish before the process exits; have the hook script itself detach (e.g. `nohup`/`disown`) and/or write its own completion marker if you need proof it ran. + +## Running Unattended in CI + +Interactively, the TUI prompts for confirmation before a tool call runs unless it's covered by an `allow` permission pattern. There's no one to answer that prompt in CI, so an unattended `--exec` run needs an explicit policy for what may run without asking — otherwise every tool call the model attempts is rejected outright (there's no stdin to prompt, so `--exec` without one just answers "no" on your behalf; see [`--json`'s auto-reject behavior](#structured-output-for-machines) above). + +Two different questions come up here, and it's worth keeping them separate: + +- **What is allowed to run without asking?** — the safety mode (`--safety strict|balanced|restricted|autonomous`, with `--yolo` as the legacy spelling of `autonomous`) and permission allow-lists answer this. +- **What happens if the model runs something it shouldn't have?** — only `--sandbox` answers that one. The rest of this section explains why, and treats that distinction as the whole point. + +### `--sandbox`: the isolation boundary + +For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/): a misbehaving or successfully-prompt-injected agent can't touch anything outside the mounted working directory or reach other host/CI state, regardless of which command it runs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How It Works](../../configuration/sandbox/index.md#how-it-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior. + +```bash +$ docker agent run --sandbox --exec agent.yaml --json "Fix the failing test" +``` + +Because the blast radius is contained by the VM boundary, `--sandbox` also makes unattended operation reasonable in CI — and it defaults to exactly that: unless you already passed a `--yolo` or `--safety` flag of your own, `--sandbox` injects `--yolo` for the agent process it runs inside the VM, so the command above already runs unattended with no confirmation prompts. Passing `--yolo` explicitly (`--sandbox --yolo --exec ...`) is equivalent and can make the intent clearer in a script, but it's optional. To keep confirmation prompts even inside the sandbox, select a stricter mode (`--sandbox --safety strict`) or opt out of the legacy default with `--yolo=false` — `--sandbox` only fills in `--yolo` when neither safety flag was set. + +If your CI provider already runs each job in its own disposable VM or container — many hosted runners do — and nothing on the runner matters once the job ends, that may already give you an isolation boundary on its own. `--sandbox` still gives you the same guarantee independent of the CI provider, and starts to matter as soon as the agent runs on a persistent self-hosted runner, a long-lived container, or your own workstation. + +### Defense in depth, not a boundary: permissions and shell command matching + +Permission allow-lists (`permissions.allow` on the agent, or `settings.permissions.allow` globally — see [Permissions](../../configuration/permissions/index.md)) and the balanced safety mode's shell classifier (see [Safety modes](../../configuration/permissions/index.md#safety-modes)) narrow what runs without asking. Used well, they cut down how often you're prompted and catch obviously destructive calls before they run. They are **not** a security boundary: + +- Both work by matching the shell command **string** (or, for `permissions`, the tool's arguments). The classifier's safe-list refuses to vouch for any command carrying shell metacharacters (`;`, `&`, `|`, `<`, `>`, backticks, `$(`, newlines — spaced or not), so `ls && rm -rf ~`, `grep foo|rm -rf /`, and `grep x > /etc/passwd` all fall through to a confirmation instead of inheriting a safe verdict. But string matching still can't reason about what a command actually *does* — see the next point. +- Command-string and argument matching in general can't reason about what a command actually does; a dynamically built string, an unusual quoting form, or a wrapper script can slip past any fixed set of patterns. + +For unattended runs, the `restricted` safety mode packages this stance as a fail-closed default: classifier-safe calls run, every other unmatched call is **denied outright** instead of falling through to a confirmation prompt nobody will answer. Pair it with an allow-list scoped to what the job actually needs — explicit `allow` rules still win over the mode, so the job's known-good commands run even when the classifier can't vouch for them: + +```yaml +# agent.yaml — the allow-list overrides restricted's deny for these calls +permissions: + allow: + - "shell:cmd=go test*" + - "shell:cmd=go build*" +``` + +```bash +# Safe and allow-listed calls run; every other call is denied without prompting +$ docker agent run --exec --safety restricted agent.yaml --json "Fix the failing test" +``` + +Like the allow-list itself, `restricted` is defense in depth, not a security boundary: it narrows what runs unattended, but only `--sandbox` contains what a misbehaving agent can do with the calls that are allowed. + +Treat permissions and the balanced/restricted modes as a way to reduce prompt fatigue and catch the obvious cases, paired with least-privilege CI credentials — never as the reason a CI job is safe to run unattended. For that, use `--sandbox`. + +> [!WARNING] +> **`--yolo` without `--sandbox` runs untrusted, unattended code with no boundary** +> +> A CI job is exactly the environment where a runaway or misled agent does the most damage before anyone notices — no one is at the keyboard to catch a bad `shell` call before it runs, and, per above, a permission allow-list or the shell classifier can't be trusted to catch everything either. If you can't add `--sandbox`, prefer `--safety restricted` with a permission allow-list scoped to what the job actually needs over blanket `--yolo`, and budget for the credentials and blast radius of the agent's toolsets as if the job itself were compromised — see [`examples/permissions.yaml`](https://github.com/docker/docker-agent/blob/main/examples/permissions.yaml) for a worked allow/deny list. + +> [!NOTE] +> **A worktree is not a security boundary either** +> +> [`--worktree`](../../features/cli/index.md#docker-agent-run) isolates *which branch and checkout* the agent modifies — it gives the agent its own working directory and branch so your primary checkout stays untouched — but the shell toolset still runs as a native process on the host, and the worktree shares the repository's underlying object store with the rest of your checkouts. It's checkout isolation, not a security boundary. Only `--sandbox` provides that. + +## Providing Secrets in CI + +Never put provider API keys or MCP tokens in the agent config file. Inject them as environment variables from your CI provider's secret store, or via `--env-from-file` with a file materialized at job start. See [Managing Secrets](../secrets/index.md) for every supported method, including Docker Compose secrets and 1Password references — both of which map cleanly onto CI secret stores. + +## Disabling Telemetry + +Docker Agent's anonymous usage telemetry is enabled by default. In CI you may want it off: + +```bash +$ TELEMETRY_ENABLED=false docker agent run --exec agent.yaml "..." +``` + +See [Telemetry](../../community/telemetry/index.md) for exactly what is (and isn't) collected. + +## Example: GitHub Actions + +A bare OCI registry reference (`myorg/coder`) has no local config you control, so a security-sensitive CI job should check in a small agent config instead. This example runs a checked-in review agent non-interactively against the repository being built: + +```yaml +# .github/agents/review-agent.yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Reviews the changes in a pull request for bugs and security issues + instruction: Review the changes in this PR for bugs and security issues. + toolsets: + - type: shell +``` + +```yaml +# .github/workflows/agent-review.yml +name: Agent code review +on: + pull_request: + +permissions: + contents: read + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Install docker-agent + run: | + curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-linux-amd64" -o docker-agent + chmod +x docker-agent + sudo mv docker-agent /usr/local/bin/ + + - name: Run the review agent + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + TELEMETRY_ENABLED: "false" + run: | + docker-agent run --exec --yolo .github/agents/review-agent.yaml --json \ + "Review the changes in this PR for bugs and security issues" \ + | tee agent-events.ndjson + + - name: Upload transcript + if: always() + uses: actions/upload-artifact@v4 + with: + name: agent-events + path: agent-events.ndjson +``` + +This job auto-approves every shell call the review agent makes (`--yolo`) rather than trying to allow-list every `git`/`grep`/`cat` invocation a code review might need — the read surface for "review this diff" is open-ended, and a fixed pattern list is exactly the kind of shell-matching boundary the [previous section](#defense-in-depth-not-a-boundary-permissions-and-shell-command-matching) says not to rely on. If your CI environment has `sbx` installed and configured (GitHub-hosted `ubuntu-latest` does not ship it out of the box), add `--sandbox` and get a real isolation boundary around that `--yolo`: + +```bash +$ docker-agent run --sandbox --exec --yolo .github/agents/review-agent.yaml --json "..." +``` + +Without `--sandbox`, this workflow's safety instead rests on least-privilege secrets (only `ANTHROPIC_API_KEY` is injected — no repo-write token), the top-level `permissions: contents: read` block and `persist-credentials: false` on the checkout step (which together mean the job never holds a write-capable `GITHUB_TOKEN` and never persists one to disk for `git` to pick up), and the job running on a GitHub-hosted, ephemeral runner that's discarded after the job. + +This example omits the GitHub MCP toolset (`docker:github-official`) shown in earlier revisions of this guide: that server requires a `GITHUB_PERSONAL_ACCESS_TOKEN` this workflow doesn't provide, and — because the toolset above has no `name:` field — its tools would be exposed under their raw MCP names (`get_file_contents`, `search_code`, …) rather than a `github_*`-style qualified name, so permission patterns written against that prefix wouldn't match anything anyway. If your review agent needs GitHub API access, add the toolset back with an explicit `name: github`, wire `GITHUB_PERSONAL_ACCESS_TOKEN` through `env:` from a repository secret, and write any `permissions` patterns against the tool names it actually exposes (`github_get_*` only works once the toolset carries that `name:`). + +Swap the model, toolsets, and provider secret for your own — the shape (checkout, install the binary, run `--exec` with `--json` against a checked-in config, upload the transcript) generalizes to any CI provider that can run a shell step. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md new file mode 100644 index 000000000000..26fe93547132 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md @@ -0,0 +1,247 @@ +--- +title: "Managing Secrets" +description: "How to securely provide API keys and credentials to Docker Agent using environment variables, env files, Docker Compose secrets, and 1Password references." +keywords: docker agent, ai agents, guides, managing secrets +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/guides/secrets/ +--- + +_How to securely provide API keys and credentials to Docker Agent._ + +## Overview + +Docker Agent needs API keys to talk to model providers (OpenAI, Anthropic, etc.) and MCP tool servers (GitHub, Slack, etc.). These keys are **never stored in config files**. Instead, Docker Agent resolves them at runtime through a chain of secret providers, checked in order (see `pkg/environment/default.go`): + +| Priority | Provider | Description | +| --- | --- | --- | +| 1 | [Environment variables](#environment-variables) | `export OPENAI_API_KEY=sk-...` | +| 2 | [Docker Compose secrets](#docker-compose-secrets) | Files in `/run/secrets/` | +| 3 | [Docker Agent env file](#docker-agent-env-file) | `~/.config/cagent/.env`, written by `docker agent setup` | +| 4 | [Credential helper](#credential-helper) | Custom command declared in `~/.config/cagent/config.yaml` under `credential_helper:` | +| 5 | [Docker Desktop](#docker-desktop) | Secrets stored by the Docker Desktop backend (no setup on a Desktop install) | + +The first provider that has a value wins. You can mix and match — for example, use environment variables for one key and the Docker Agent env file for another. + +> [!NOTE] +> Older Docker Agent versions could also read secrets from the macOS Keychain and the `pass` password manager. These sources are no longer consulted: migrate any keys stored there to one of the sources above, e.g. by re-running `docker agent setup`. + +Whatever provider returns the value, if that value looks like a [1Password secret reference](#1password-references) (it starts with `op://`), Docker Agent resolves it through the `op` CLI before handing it to a model provider or tool. + +When Docker Agent runs an agent with `--sandbox` and a Docker AI gateway is configured, the sandbox proxy authenticates gateway requests itself: it injects your Docker login token into HTTPS requests to the gateway host (docker.com domains only). The token never enters the sandbox — inside it, `DOCKER_TOKEN` is a proxy-managed placeholder. + +## Environment Variables + +The simplest approach. Set variables in your shell before running Docker Agent: + +```bash +export OPENAI_API_KEY=sk-... +export ANTHROPIC_API_KEY=sk-ant-... +docker agent run agent.yaml +``` + +Common variables: + +| Variable | Provider | +| --- | --- | +| `OPENAI_API_KEY` | OpenAI | +| `ANTHROPIC_API_KEY` | Anthropic | +| `GOOGLE_API_KEY` | Google Gemini | +| `MISTRAL_API_KEY` | Mistral | +| `OPENROUTER_API_KEY` | OpenRouter | +| `XAI_API_KEY` | xAI | +| `NEBIUS_API_KEY` | Nebius | + +MCP tools may require additional variables. For example, the GitHub MCP server needs `GITHUB_PERSONAL_ACCESS_TOKEN`. These are passed to tools via the `env` field in your config: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + env: + GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_PERSONAL_ACCESS_TOKEN +``` + +## Env Files + +For convenience, you can store secrets in a `.env` file and pass it to Docker Agent with `--env-from-file`: + +```bash +# .env +OPENAI_API_KEY=sk-... +ANTHROPIC_API_KEY=sk-ant-... +GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... +``` + +```bash +docker agent run agent.yaml --env-from-file .env +``` + +The file format supports: + +- `KEY=VALUE` pairs, one per line +- Comments starting with `#` +- Quoted values: `KEY="value with spaces"` +- Blank lines are ignored + +> [!IMPORTANT] +> Add `.env` to your `.gitignore` to avoid committing secrets to version control. + +## Docker Agent env file + +A `.env` file (same format as above) at `~/.config/cagent/.env` is read automatically on every run — no `--env-from-file` flag needed. It is where [`docker agent setup`](../../features/cli/index.md#docker-agent-setup) stores API keys when you choose the env-file location, and you can edit it by hand: + +```bash +# ~/.config/cagent/.env +OPENAI_API_KEY=sk-... +``` + +The file is created with owner-only permissions (`0600`), but the values are stored in plain text. + +## Docker Compose Secrets + +When running Docker Agent in a container with Docker Compose, you can use [Compose secrets](https://docs.docker.com/compose/how-tos/use-secrets/) to inject credentials securely. Compose mounts secrets as files under `/run/secrets/`, and Docker Agent reads from this location automatically. + +### From a file + +Store each secret in its own file, then reference it in `compose.yaml`: + +```bash +echo -n "sk-ant-your-key-here" > .anthropic_api_key +``` + +```yaml +# compose.yaml +services: + agent: + image: docker/docker-agent + command: run --exec /app/agent.yaml "Hello!" + secrets: + - ANTHROPIC_API_KEY + volumes: + - ./agent.yaml:/app/agent.yaml:ro + +secrets: + ANTHROPIC_API_KEY: + file: ./.anthropic_api_key +``` + +Docker Compose mounts the file as `/run/secrets/ANTHROPIC_API_KEY`. Docker Agent picks it up with no extra configuration. + +### From a host environment variable + +In CI/CD pipelines, secrets are often injected as environment variables. Compose can forward these to `/run/secrets/`: + +```yaml +secrets: + ANTHROPIC_API_KEY: + environment: "ANTHROPIC_API_KEY" +``` + +### Multiple secrets + +```yaml +services: + agent: + image: docker/docker-agent + command: run --exec /app/agent.yaml "Summarize my GitHub issues" + secrets: + - ANTHROPIC_API_KEY + - GITHUB_PERSONAL_ACCESS_TOKEN + volumes: + - ./agent.yaml:/app/agent.yaml:ro + +secrets: + ANTHROPIC_API_KEY: + file: ./.anthropic_api_key + GITHUB_PERSONAL_ACCESS_TOKEN: + file: ./.github_token +``` + +### Why use Compose secrets over environment variables? + +| Aspect | Environment Variables | Compose Secrets | +| --- | --- | --- | +| Storage | In memory, visible via `docker inspect` | Mounted as tmpfs files under `/run/secrets/` | +| Visibility | Shown in process list and inspect output | Not exposed in `docker inspect` | +| Best for | Development | Production and CI/CD | + +## Credential Helper + +Docker Agent can shell out to an external credential helper you define in your user config. This is useful when your organisation already has a secrets daemon you want to reuse (HashiCorp Vault, 1Password CLI, `bitwarden-cli`, etc.). + +Declare the helper in `~/.config/cagent/config.yaml`: + +```yaml +# ~/.config/cagent/config.yaml +credential_helper: + command: op + args: ["read", "op://Personal/docker-agent"] +``` + +The command is invoked with the variable name appended as the final argument, and must print the secret value to stdout. + +## Docker Desktop + +On machines where Docker Desktop is installed, Docker Agent queries Docker Desktop's backend for secrets stored against your signed-in Docker account. This is transparent — no extra configuration — and it is how signed-in Docker users get provider API keys without setting any environment variables. + +## Docker Authentication + +Routing model traffic through the [Docker models gateway](../../configuration/models/index.md) needs a Docker token. Docker Desktop hands out one that is valid for 15 minutes and cannot be renewed by Docker Agent, so when Desktop has nothing usable to offer — it is signed out, not running, or its own refresh is stuck — Docker Agent exchanges the long-lived access token that `docker login` left in your credential store for a fresh Docker token, the same exchange `docker login` itself performs. Signing in with `docker login` is therefore enough; Docker Desktop is not required. + +Only Docker access tokens are exchanged — the `dckr_…` secrets `docker login` stores — never an account password, and the exchange goes to Docker Hub over HTTPS. The resulting bearer token is cached in a private file under Docker Agent's cache directory so sibling processes reuse it instead of minting their own, and it stops being used within seconds of a `docker logout` or an account switch. Run `docker agent debug auth` to see which token is in use and where it came from. + +Set `DOCKER_AGENT_NO_TOKEN_EXCHANGE=1` to opt out: Docker Agent then relies on Docker Desktop alone. + +## 1Password References + +Any secret value resolved through the chain above can be a **1Password secret reference** instead of the literal secret. If the value starts with `op://`, Docker Agent resolves it by invoking the [1Password CLI](https://developer.1password.com/docs/cli/) (`op read <reference>`) and uses the result. + +This works with every provider — most commonly an environment variable or env file: + +```bash +export OPENAI_API_KEY="op://Personal/OpenAI/api-key" +docker agent run agent.yaml +``` + +References follow the `op://<vault>/<item>/<field>` format. Make sure the `op` CLI is installed and you are signed in (`op signin`) so that non-interactive reads succeed. + +> [!WARNING] +> **Behaviour when resolution fails** +> +> If the value starts with `op://` but the `op` CLI is not installed, or the reference cannot be read (not signed in, wrong path, locked vault), Docker Agent logs a warning and uses an **empty value** — it never forwards the raw `op://` reference to a model provider or tool. Resolved references (and deterministic failures) are cached for the lifetime of the run; transient failures such as a cancelled lookup are not cached, so a later attempt can retry. + +## Choosing a Method + +| Method | Best for | Setup effort | +| --- | --- | --- | +| Environment variables | Quick local development, scripts | Low | +| Env files | Team projects, multiple keys | Low | +| Docker Agent env file | Keys used across all projects, written by `docker agent setup` | Low | +| Docker Compose secrets | Containerized deployments, CI/CD | Medium | +| Credential helper | Reusing an existing secrets daemon (Vault, 1Password CLI, ...) | Medium | +| 1Password references (`op://`) | Teams already using 1Password | Low | + +You can combine methods. For example, store long-lived provider keys in the Docker Agent env file and pass project-specific MCP tokens via env files. + +## Preventing Secret Leaks + +Provider keys live in the secret store and are passed to Docker Agent through the chain above — the agent itself never receives them as input. But the **content of a conversation** can still leak credentials: a user pasting a token, a tool returning a config file with embedded keys, a transcript dumped into a prompt. + +For that defense-in-depth case, set `redact_secrets: true` on an agent. It scrubs detected secrets out of: + +- the arguments of every outgoing tool call (before the tool sees them), +- every outgoing chat message (before the model provider sees them), and +- every tool's output (before it reaches event consumers, the persisted session file, the `post_tool_use` hook input, or the next LLM call). + +```yaml +agents: + root: + model: openai/gpt-5 + description: A helpful assistant + instruction: You are a helpful assistant. + redact_secrets: true + toolsets: + - type: shell +``` + +The ruleset covers GitHub PATs, AWS / GCP / Azure credentials, Stripe / Slack / GitLab / Hugging Face tokens, JWTs, PEM-encoded private keys, Docker Hub PATs, and many others. Each detected span is replaced with the literal `[REDACTED]`. See the [Redacting Secrets](../../configuration/agents/index.md#redacting-secrets) section in the agent configuration reference for the full picture and important caveats about false negatives. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md new file mode 100644 index 000000000000..fbdef06dee3b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md @@ -0,0 +1,363 @@ +--- +title: "Thinking / Reasoning" +description: "Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner." +keywords: docker agent, ai agents, guides, thinking / reasoning +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/guides/thinking/ +--- + +_Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner._ + +## What Is Thinking? + +Several modern models support an extended reasoning phase that happens before they produce visible output. During this phase the model plans, evaluates options, and works through the problem — internally, not shown in the response by default. This typically improves accuracy on complex tasks like coding, math, and multi-step planning, at the cost of higher token usage and latency. + +Docker Agent exposes this through a single `thinking_budget` field on any named model. The value format differs slightly by provider, but the semantics are the same: higher effort means more thorough reasoning. + +> [!NOTE] +> **Think tool vs. thinking budget** +> +> The [think tool](../../tools/think/index.md) is a scratchpad for models that lack native reasoning. If your model supports `thinking_budget`, you do not need the think tool. + +## Quick Reference + +| Provider | Format | Values | Default | +| ------------------- | ---------- | --------------------------------------------------------------------------------------- | ------------------ | +| OpenAI | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; `xhigh` on gpt-5.2+, `none`/`max` on gpt-5.6+ only, `minimal` dropped on gpt-5.6+ | `medium` (API default) | +| Anthropic | int or str | 1024–32768 tokens, or `minimal`–`max`, `adaptive`, `adaptive/<effort>`, `none` | off | +| Gemini 2.5 | int | `0` (off), `-1` (dynamic), or token count (max 24576 / 32768) | `-1` (dynamic) | +| Gemini 3 | string | `minimal`, `low`, `medium`, `high` | API default (model-dependent) | +| AWS Bedrock | int or str | 1024–32768 tokens (`minimal`–`max` mapped to tokens); `adaptive`, `adaptive/<effort>` for Opus 4.6+ (rejected by older Claude models) | off | +| Docker Model Runner | int or str | token count, `minimal`–`max` (mapped to tokens), `adaptive` (unlimited), `none` | engine default | + +String values are case-insensitive. The full set of accepted strings is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `adaptive`, and `adaptive/<effort>` — but each provider only honors the subset listed above. Unsupported values either fail at request time (OpenAI) or are mapped/ignored as described per provider below. + +> `thinking_budget` is only applied by the providers listed above. Other OpenAI-compatible providers (xAI, Mistral, Ollama, …) currently ignore it — see [xAI and Mistral](#xai-grok-and-mistral). + +## OpenAI + +OpenAI reasoning models (o-series, gpt-5, gpt-5-mini, gpt-5.6 family) use a string effort level that maps to their `reasoning_effort` API parameter. The `xhigh` level requires gpt-5.2+; `none` and `max` require gpt-5.6+ (Sol/Terra/Luna); `minimal` is dropped on gpt-5.6+. + +```yaml +models: + gpt-thinker: + provider: openai + model: gpt-5.6 + thinking_budget: high # none | minimal | low | medium | high | xhigh | max +``` + +**Effort levels:** + +| Level | Description | +| --------- | -------------------------------------------------------- | +| `none` | No reasoning. Sent as-is on gpt-5.6+ (a real API value); on older models it just disables the local `thinking_budget` (the API's own default still applies). | +| `minimal` | Fastest; lightest reasoning pass. Not accepted on gpt-5.6+ (dropped from the API). | +| `low` | Quick reasoning for straightforward tasks. | +| `medium` | Balanced default. | +| `high` | More thorough; recommended for complex tasks. | +| `xhigh` | Near-maximum effort; slower but most accurate. Requires gpt-5.2+. | +| `max` | Maximum effort. Requires gpt-5.6+. | + +Token counts, `adaptive`, and `adaptive/<effort>` are rejected with a configuration error at request time. `xhigh` is only supported by gpt-5.2 and later minor versions (e.g. gpt-5.2, gpt-5.4-mini); `none` and `max` are only supported by gpt-5.6 and later (Sol/Terra/Luna); `minimal` is not accepted on gpt-5.6+. Older models (o1, o3-mini) only accept `low`/`medium`/`high` — sending an unsupported level returns an API error. + +> [!WARNING] +> **Tokens and max_tokens** +> +> Older OpenAI reasoning models always reason internally — even with `thinking_budget: none` there are hidden reasoning tokens that count against `max_tokens`. On gpt-5.6+ (Sol/Terra/Luna), `none` is a real API value that genuinely disables reasoning. Docker Agent automatically raises the output-token floor for its internal low-effort calls (e.g. title generation) so hidden reasoning cannot starve visible text output. + +## Anthropic + +Anthropic Claude supports two thinking modes: a **token budget** (older models) and **adaptive / effort-based** thinking (newer models). + +### Token budget (Claude 4 and earlier) + +Set an explicit number of thinking tokens (1024–32768). This must be less than `max_tokens`: + +```yaml +models: + claude-thinker: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 16384 # tokens reserved for internal reasoning +``` + +Docker Agent auto-adjusts `max_tokens` when you set a thinking budget but leave `max_tokens` at its default. If you set `max_tokens` explicitly, it must be greater than `thinking_budget`. + +### Adaptive thinking (Opus 4.6+ and Sonnet 4.6) + +Newer Claude models support adaptive thinking, where the model decides how much to think. **Claude Opus 4.6, 4.7, 4.8, and Sonnet 4.6 only support adaptive thinking** — they reject token-based budgets. Use `adaptive`, `adaptive/<effort>`, or a bare effort level — on Anthropic, a bare effort level like `high` is shorthand for adaptive thinking at that effort: + +```yaml +models: + claude-adaptive: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: adaptive # model decides effort (defaults to high) + + claude-adaptive-low: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: low # same as adaptive/low + + claude-adaptive-max: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: adaptive/max # adaptive/low | adaptive/medium | adaptive/high | adaptive/xhigh | adaptive/max +``` + +**Adaptive effort levels and per-model support:** + +| Level | Opus 4.5 | Sonnet 4.5 / Haiku | Sonnet 4.6 | Opus 4.6 | Opus 4.7 / 4.8 | Fable 5 | Mythos 5 | Mythos preview | +| --------- | :------: | :----------------: | :--------: | :------: | :------------: | :-----: | :------: | :------------: | +| `low` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| `medium` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| `high` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| `xhigh` | — | — | — | — | ✓ | ✓ | ✓ | — | +| `max` | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + +`minimal` is treated as `low` (bare form only). `high` is the default when `adaptive` is used without an effort level. + +> [!WARNING] +> **Effort strings require adaptive-capable models** +> +> Every string effort value on Anthropic is sent as adaptive thinking (`output_config.effort`), which only newer Claude models (Opus 4.6+, Sonnet 4.6) accept. For older models like Sonnet 4.5, use an integer token budget instead. Conversely, models that _only_ support adaptive thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6) automatically have token budgets coerced to `adaptive` (a warning is logged). + +### Disabling thinking + +```yaml +thinking_budget: none # or 0 +``` + +### Interleaved thinking + +Interleaved thinking lets the model reason between tool calls — useful for complex agentic tasks. Docker Agent auto-enables it whenever a thinking budget is configured on a Claude model, so you only need to set it explicitly to turn it off: + +```yaml +models: + claude-interleaved: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 16384 + # interleaved_thinking is auto-enabled; disable it explicitly if needed: + provider_opts: + interleaved_thinking: false +``` + +> [!NOTE] +> **Temperature and top_p** +> +> When extended thinking is enabled, Anthropic requires `temperature=1.0`. Docker Agent automatically suppresses any `temperature` or `top_p` settings you have configured — they are silently ignored while thinking is active. + +### Thinking display + +Newer Claude models (Opus 4.7+, Fable 5) hide thinking content by default at the API level. To keep reasoning visible, Docker Agent requests `summarized` thinking whenever adaptive/effort-based thinking is used without an explicit `thinking_display`. Use `thinking_display` in `provider_opts` to override: + +```yaml +models: + opus-47: + provider: anthropic + model: claude-opus-4-7 + thinking_budget: adaptive + provider_opts: + thinking_display: omitted # summarized | omitted (display: pre-4.6 models only) +``` + +| Value | Behavior | +| ------------ | ------------------------------------------------------------------------------------- | +| `summarized` | Thinking blocks returned with a text summary (Docker Agent default for adaptive thinking). | +| `display` | Full thinking blocks returned for display. Pre-4.6 token-thinking models only — rejected by Opus/Sonnet 4.6+, Sonnet 5, and Fable 5 (Docker Agent fails fast with a configuration error). | +| `omitted` | Thinking blocks hidden — only the signature is returned. | + +Full thinking tokens are billed regardless of `thinking_display`. + +### Task budget (Anthropic) + +`task_budget` caps total tokens across an entire multi-step agentic task (thinking + tool calls + output combined): + +```yaml +models: + opus-bounded: + provider: anthropic + model: claude-opus-4-7 + thinking_budget: adaptive + task_budget: 128000 # total token ceiling for the whole task +``` + +See the [Anthropic provider page](../../providers/anthropic/index.md#task-budget) for details. + +## Google Gemini + +Gemini 2.5 and Gemini 3 use different formats. + +### Gemini 2.5 (token budget) + +```yaml +models: + gemini-off: + provider: google + model: gemini-2.5-flash + thinking_budget: 0 # disable thinking + + gemini-dynamic: + provider: google + model: gemini-2.5-flash + thinking_budget: -1 # let the model decide (default) + + gemini-fixed: + provider: google + model: gemini-2.5-flash + thinking_budget: 8192 # fixed token budget (max 24576 for Flash, 32768 for Pro) +``` + +### Gemini 3 (level-based) + +```yaml +models: + gemini3-flash: + provider: google + model: gemini-3-flash + thinking_budget: medium # minimal | low | medium | high + + gemini3-pro: + provider: google + model: gemini-3-pro + thinking_budget: high # low | high (Pro supports fewer levels) +``` + +## AWS Bedrock (Claude) + +Bedrock Claude uses a token budget like Anthropic. String effort levels (`minimal`–`max`) are mapped automatically: + +| Effort level | Token budget | +| ------------ | ------------ | +| `minimal` | 1,024 | +| `low` | 2,048 | +| `medium` | 8,192 | +| `high` | 16,384 | +| `xhigh`/`max`| 32,768 | + +```yaml +models: + bedrock-claude-thinker: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + thinking_budget: 8192 # or use an effort level: medium + provider_opts: + region: us-east-1 + + bedrock-claude-interleaved: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + thinking_budget: high + provider_opts: + region: us-east-1 + # interleaved_thinking is auto-enabled when thinking_budget is set +``` + +**Claude Opus 4.6+ on Bedrock requires adaptive thinking** — these models reject `thinking.type=enabled` (token budgets). Configure them with `adaptive` or `adaptive/<effort>`; Docker Agent auto-coerces token budgets and effort levels on these models with a warning: + +```yaml +models: + bedrock-opus-adaptive: + provider: amazon-bedrock + model: global.anthropic.claude-opus-4-8 + thinking_budget: adaptive/high + provider_opts: + region: us-east-1 +``` + +> [!WARNING] +> **Bedrock thinking requirements** +> +> Bedrock Claude requires token-based `thinking_budget` values to be ≥ 1024 and less than `max_tokens`. Docker Agent logs a warning and ignores the budget if either condition is violated. Interleaved thinking requires the `interleaved-thinking-2025-05-14` beta header, which Docker Agent adds automatically; it is auto-enabled whenever a token thinking budget is set on a Bedrock-hosted Claude model (adaptive thinking interleaves on its own). + +## Docker Model Runner (local models) + +For local models, `thinking_budget` is forwarded to the inference engine. Both token counts and effort strings work; effort strings map to the same token scale as Bedrock (`minimal`=1024 … `xhigh`/`max`=32768), and `adaptive` means unlimited: + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + thinking_budget: medium # llama.cpp: reasoning-budget=8192; vLLM: thinking_token_budget=8192 +``` + +- **llama.cpp**: sent as `reasoning-budget` at model-configure time. +- **vLLM**: sent as `thinking_token_budget` on each request. +- **MLX / SGLang**: no reasoning-budget knob; the value is silently ignored. + +See the [Docker Model Runner provider page](../../providers/dmr/index.md) for details. + +## xAI (Grok) and Mistral + +xAI and Mistral run through Docker Agent's OpenAI-compatible client, but the `reasoning_effort` parameter is only sent for OpenAI reasoning model names (o-series, gpt-5). **Setting `thinking_budget` on Grok or Mistral models currently has no effect** — the value is accepted by config validation but never sent to the API. + +Grok and Mistral reasoning models (e.g. `grok-3-mini`, `magistral`) manage reasoning on their own; for non-reasoning models, consider the [think tool](../../tools/think/index.md) instead. + +## Disabling Thinking + +Use `none` or `0` to disable thinking on any provider: + +```yaml +models: + fast-model: + provider: openai + model: gpt-5-mini + thinking_budget: none + + gemini-no-think: + provider: google + model: gemini-2.5-flash + thinking_budget: 0 +``` + +`none` and `0` clear Docker Agent's thinking configuration — no thinking parameter is sent. Models that always reason (OpenAI o-series, gpt-5 through gpt-5.5, Gemini 3) then fall back to the API's default behavior and still reason internally; gpt-5.6+ (Sol/Terra/Luna) sends `none` as a real API value that genuinely disables reasoning. Models with optional thinking (Gemini 2.5, Claude, local models) are also fully disabled. + +## Choosing an Effort Level + +| Task complexity | Recommended level | +| -------------------------------- | ----------------------- | +| Simple factual Q&A | `none` / `minimal` | +| General-purpose chat | `low` / `medium` | +| Coding, debugging, analysis | `medium` / `high` | +| Complex reasoning, planning | `high` / `xhigh` | +| Research, difficult math/logic | `xhigh` / `max` | +| Long agentic tasks (Anthropic) | `adaptive` | + +## Changing Thinking Level at Runtime + +While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config, or type `/effort <level>` to jump straight to a specific level (e.g. `/effort high`). Running `/effort` without an argument opens a picker listing the levels the current model supports: + +- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → xhigh → max → none` on gpt-5.6+ (no `minimal`), `none → low → medium → high → max → none` on Anthropic Opus 4.6 and Sonnet 4.6, and `none → low → medium → high → xhigh → max → none` on Anthropic Opus 4.7+, Fable 5, and Mythos 5. For older Anthropic models (e.g. Sonnet 4.5) that only accept token budgets, effort-string cycling has no effect — use an integer `thinking_budget` in your YAML config instead. +- The current level is shown in the sidebar next to the model name (e.g. `openai/gpt-5 • high`). +- This applies as a session override — it is **not** saved to the config file. The next session starts from the level defined in your YAML. +- For models that don't support reasoning, and for remote runtimes, Shift+Tab is a no-op and an informational message is displayed. +- `/effort` only accepts levels the current model supports; requesting an unsupported level shows the model's supported list. Like Shift+Tab, it is unavailable for non-reasoning models and remote runtimes. +- Press <kbd>Tab</kbd> after `/effort` and a space to complete a level from the current model's supported range; it lists the same levels the picker shows (and, like the picker, offers no candidates for non-reasoning models or remote runtimes). + +## Sharing Thinking Config Across Models + +Define a provider with a default `thinking_budget` and all models that reference it inherit it: + +```yaml +providers: + deep-anthropic: + provider: anthropic + thinking_budget: adaptive/high + max_tokens: 32768 + +models: + claude-smart: + provider: deep-anthropic + model: claude-opus-4-6 # inherits thinking_budget: adaptive/high + + claude-faster: + provider: deep-anthropic + model: claude-opus-4-6 + thinking_budget: low # overrides to adaptive/low +``` + +## Full Example + +See [`examples/thinking_budget.yaml`](https://github.com/docker/docker-agent/blob/main/examples/thinking_budget.yaml) for a runnable config covering all providers. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md new file mode 100644 index 000000000000..bde25ee34a7c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md @@ -0,0 +1,477 @@ +--- +title: "Tips & Best Practices" +description: "Expert guidance for building effective, efficient, and secure agents." +keywords: docker agent, ai agents, guides, tips & best practices +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/guides/tips/ +aliases: + - /ai/docker-agent/best-practices/ +--- + +_Expert guidance for building effective, efficient, and secure agents._ + +## Configuration Tips + +### Auto Mode for Quick Start + +Don't have a config file? Docker Agent can automatically detect your available API keys and use an appropriate model: + +```bash +# Automatically uses the best available provider +$ docker agent run + +# Provider priority: Anthropic → OpenAI → Google → Mistral → Amazon Bedrock → DMR +``` + +The special `auto` model value also works in configs: + +```yaml +agents: + root: + model: auto # Uses best available provider + description: Adaptive assistant + instruction: You are a helpful assistant. +``` + +### Environment Variable Interpolation + +Commands support JavaScript template literal syntax for environment variables: + +```yaml +agents: + root: + model: openai/gpt-4o + description: Deployment assistant + instruction: You help with deployments. + commands: + # Simple variable + greet: "Hello ${env.USER}!" + + # With default value + deploy: "Deploy to ${env.ENV || 'staging'}" + + # Multiple variables + release: "Release ${env.PROJECT} v${env.VERSION || '1.0.0'}" +``` + +### Model Aliases Are Auto-Pinned + +Docker Agent automatically resolves model aliases to their latest pinned versions. This ensures reproducible behavior: + +```yaml +# You write: +model: anthropic/claude-sonnet-4-5 + +# docker-agent resolves to: +# anthropic/claude-sonnet-4-5-20250929 (or latest available) +``` + +To use a specific version, specify it explicitly in your config. + +## Performance Tips + +### Defer Tools for Faster Startup + +Large MCP toolsets can slow down agent startup. Use `defer` to load tools on-demand: + +```yaml +agents: + root: + model: openai/gpt-4o + description: Multi-tool assistant + instruction: You have many tools available. + toolsets: + - type: mcp + ref: docker:github-official + defer: true + - type: mcp + ref: docker:slack + defer: true + - type: mcp + ref: docker:linear + defer: true +``` + +Or defer specific tools within a toolset: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + defer: + - "list_issues" + - "search_repos" + - type: mcp + ref: docker:slack + defer: + - "list_channels" +``` + +### Filter MCP Tools + +Many MCP servers expose dozens of tools. Filter to only what you need: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + # Only expose these specific tools + tools: + - list_issues + - create_issue + - get_pull_request + - create_pull_request +``` + +Fewer tools means faster tool selection and less confusion for the model. + +### Set max_iterations + +Always set `max_iterations` for agents with powerful tools to prevent infinite loops: + +```yaml +agents: + developer: + model: anthropic/claude-sonnet-4-5 + description: Development assistant + instruction: You are a developer. + max_iterations: 30 # Reasonable limit for development tasks + toolsets: + - type: filesystem + - type: shell +``` + +Typical values: 20-30 for development agents, 10-15 for simple tasks. + +## Reliability Tips + +### Use Fallback Models + +Configure fallback models for resilience against provider outages or rate limits: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Reliable assistant + instruction: You are a helpful assistant. + fallback: + models: + # Different provider for resilience + - openai/gpt-4o + # Cheaper model as last resort + - openai/gpt-4o-mini + retries: 2 # Retry 5xx errors twice + cooldown: 1m # Stick with fallback for 1 min after rate limit +``` + +**Best practices for fallback chains:** + +- Use different providers for true redundancy +- Order by preference (best first) +- Include a cheaper/faster model as last resort + +### Use Think Tool for Non-Reasoning Models + +The `think` tool provides a reasoning scratchpad for models that lack built-in thinking capabilities: + +```yaml +toolsets: + - type: think # Useful for models without native reasoning +``` + +The agent uses it as a scratchpad for planning and decision-making. If your model already supports a [thinking budget](../../configuration/models/index.md#thinking-budget) (e.g., Claude with extended thinking, OpenAI o-series, Gemini with thinking enabled), you don't need this tool — the model can reason internally. + +## Security Tips + +### Use --yolo Mode Carefully + +The `--yolo` flag auto-approves all tool calls without confirmation: + +```bash +# Auto-approve everything (use with caution!) +$ docker agent run agent.yaml --yolo +``` + +**When it's appropriate:** + +- CI/CD pipelines with controlled inputs +- Automated testing +- Agents with only safe, read-only tools + +**When to avoid:** + +- Interactive sessions with untested prompts +- Agents with shell or filesystem write access +- Any situation where unreviewed actions could cause harm + +### Combine Permissions with Sandbox + +For defense in depth, use both permissions and [sandbox mode](../../configuration/sandbox/index.md): + +```yaml +agents: + secure_dev: + model: anthropic/claude-sonnet-4-5 + description: Secure development assistant + instruction: You are a secure coding assistant. + toolsets: + - type: filesystem + - type: shell + +permissions: + allow: + - "read_*" + - "shell:cmd=go*" + - "shell:cmd=npm*" + deny: + - "shell:cmd=sudo*" + - "shell:cmd=rm*-rf*" +``` + +```bash +# Run with sandbox enabled +docker-agent run --sandbox agent.yaml +``` + +### Set Global Permission Guardrails + +Use [global permissions](../../configuration/permissions/index.md#global-permissions) in your user config to enforce safety rules across every agent: + +```yaml +# ~/.config/cagent/config.yaml +settings: + permissions: + deny: + - "shell:cmd=sudo*" + - "shell:cmd=rm*-rf*" + - "shell:cmd=git push --force*" + allow: + - "read_*" + - "shell:cmd=ls*" + - "shell:cmd=cat*" +``` + +These rules merge with any agent-level permissions. Deny patterns from your global config cannot be overridden by agent configs, so you can trust that dangerous commands stay blocked regardless of which agent you run. + +### Use Hooks for Audit Logging + +Log all tool calls for compliance or debugging: + +```yaml +agents: + audited: + model: openai/gpt-4o + description: Audited assistant + instruction: You are a helpful assistant. + hooks: + post_tool_use: + - matcher: "*" + hooks: + - type: command + command: "./scripts/audit-log.sh" +``` + +## Multi-Agent Tips + +### Handoffs vs Sub-Agents + +Understand the difference between `sub_agents` and `handoffs`: + +- **`sub_agents` (transfer_task)** — delegates a task to a child in a sub-session, waits for the result, then continues. Hierarchical: the parent remains in control. + + ```yaml + sub_agents: [researcher, writer] + ``` + +- **`handoffs` (peer-to-peer)** — hands off the entire conversation to another agent in the same session. The active agent switches and sees the full history. Agents can form cycles. + + ```yaml + handoffs: + - specialist + - summarizer + ``` + +See [Multi-Agent Systems](../../concepts/multi-agent/index.md) for a detailed comparison. + +### Give Sub-Agents Clear Descriptions + +The root agent uses descriptions to decide which sub-agent to delegate to: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Technical lead + instruction: Delegate to specialists based on the task. + sub_agents: [frontend, backend, devops] + + frontend: + model: openai/gpt-4o + # Good: specific and actionable + description: | + Frontend specialist. Handles React, TypeScript, CSS, + UI components, and browser-related issues. + + backend: + model: openai/gpt-4o + # Good: clear domain boundaries + description: | + Backend specialist. Handles APIs, databases, + server logic, and Go/Python code. + + devops: + model: openai/gpt-4o + description: | + DevOps specialist. Handles CI/CD, Docker, Kubernetes, + infrastructure, and deployment pipelines. +``` + +## Debugging Tips + +### Enable Debug Logging + +Use the `--debug` flag to see detailed execution logs: + +```bash +# Default log location: ~/.cagent/cagent.debug.log +$ docker agent run agent.yaml --debug + +# Custom log location +$ docker agent run agent.yaml --debug --log-file ./debug.log +``` + +### Check Token Usage + +Use the `/cost` command during a session to see token consumption: + +```text +/cost + +Token Usage: + Input: 12,456 tokens + Output: 3,789 tokens + Total: 16,245 tokens +``` + +### Compact Long Sessions + +If a session gets too long, use `/compact` to summarize and reduce context: + +```text +/compact + +Session compacted. Summary generated and history trimmed. +``` + +## More Tips + +### User-Defined Default Model + +Set your preferred default model in `~/.config/cagent/config.yaml`: + +```yaml +settings: + default_model: anthropic/claude-sonnet-4-5 +``` + +This model is used by the built-in default agent when you run `docker agent run` without a config argument and no project-level `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` exists. + +### Get Desktop Notifications with Hooks + +Long-running agents shouldn't require staring at the terminal. Add [global hooks](../../configuration/hooks/index.md#global-user-level-hooks) to your user config so every agent notifies you when it needs attention or finishes: + +```yaml +# ~/.config/cagent/config.yaml +settings: + hooks: + # Agent is waiting for your input (question, approval prompt, ...) + on_user_input: + - type: command + command: osascript -e 'display notification "Agent needs your input" with title "docker-agent"' + + # Agent finished responding + stop: + - type: command + command: osascript -e 'display notification "Task finished" with title "docker-agent"' +``` + +On Linux, replace `osascript` with `notify-send`: + +```yaml +command: notify-send "docker-agent" "Agent needs your input" +``` + +Hooks inherit Docker Agent's environment, so this works as-is from a desktop terminal. In detached contexts (SSH, tmux started outside your desktop session, containers), `notify-send` needs the session's `DISPLAY` and `DBUS_SESSION_BUS_ADDRESS` to reach the notification daemon, and fails silently without them. Pass them with the per-hook `env` option: + +```yaml +on_user_input: + - type: command + command: notify-send "docker-agent" "Agent needs your input" + env: + DISPLAY: ":0" + DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/1000/bus" +``` + +To also get alerted on errors and warnings, hook the `notification` event and read the message from the JSON payload on stdin: + +```yaml +settings: + hooks: + notification: + - type: command + timeout: 10 + command: | + MESSAGE=$(cat | jq -r '.notification_message // "Agent error"') + osascript -e "display notification \"$MESSAGE\" with title \"docker-agent\"" +``` + +If a sound is enough, set `settings: { sound: true }` instead — Docker Agent plays a failure sound when a task errors, and a success sound when a task that ran longer than `sound_threshold` seconds (default 10) completes. + +See the [Hooks documentation](../../configuration/hooks/index.md) for the full list of events, their payloads, and per-hook options (`env`, `working_dir`, `timeout`). + +### GitHub PR Reviewer Example + +Use Docker Agent as a GitHub Actions PR reviewer: + +```yaml +# .github/workflows/pr-review.yml +name: PR Review +on: + pull_request: + types: [opened, synchronize] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run docker-agent review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Install docker-agent + curl -fsSL https://get.docker-agent.dev | sh + + # Run the review + docker agent run --exec reviewer.yaml --yolo \ + "Review PR #${{ github.event.pull_request.number }}" +``` + +With a simple reviewer agent: + +```yaml +# reviewer.yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: PR reviewer + instruction: | + Review pull requests for code quality, bugs, and security issues. + Be constructive and specific in your feedback. + toolsets: + - type: mcp + ref: docker:github-official + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/_index.md b/_vendor/github.com/docker/docker-agent/docs/providers/_index.md new file mode 100644 index 000000000000..22c440cfe7a5 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/_index.md @@ -0,0 +1,5 @@ +--- +title: "Model Providers" +description: "Model providers supported by Docker Agent." +weight: 60 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md new file mode 100644 index 000000000000..69c8041f1d35 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md @@ -0,0 +1,241 @@ +--- +title: "Anthropic" +description: "Use Claude Sonnet 4, Claude Sonnet 4.5, and other Anthropic models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, anthropic +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/providers/anthropic/ +--- + +_Use Claude Sonnet 4, Claude Sonnet 4.5, and other Anthropic models with Docker Agent._ + +## Setup + +```bash +# Set your API key +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +### Workload Identity Federation (no API key) + +Authenticate with short-lived tokens minted from your own OIDC identity +provider instead of a long-lived API key. See Anthropic's +[Workload Identity Federation guide](https://platform.claude.com/docs/en/build-with-claude/workload-identity-federation) +to provision a Federation Rule, then configure Docker Agent with a typed +`auth:` block: + +```yaml +providers: + anthropic-wif: + provider: anthropic + auth: + type: workload_identity_federation + workload_identity_federation: + federation_rule_id: fdrl_REPLACE_ME + organization_id: 00000000-0000-0000-0000-000000000000 + # Optional: only required for target_type=SERVICE_ACCOUNT rules. + service_account_id: svac_REPLACE_ME + identity_token: + # Pick exactly one of: file, env, command, url + file: /var/run/secrets/anthropic.com/token + +models: + claude: + provider: anthropic-wif + model: claude-sonnet-4-5 +``` + +`identity_token` accepts four mutually exclusive sources: + +| Source | When to use | +| --------- | ------------------------------------------------------------------------------------------------------------------------ | +| `file` | Kubernetes projected service-account tokens, SPIFFE/SPIRE helpers, Vault sidecars — anything that rotates a file on disk | +| `env` | The token is already exported in an environment variable | +| `command` | Shell out to a CLI on every refresh (`gcloud auth print-identity-token`, `az account get-access-token`, ...) | +| `url` | Fetch from an HTTP(S) endpoint (cloud metadata servers, GitHub Actions OIDC token URL, ...) | + +For `url`, both the URL and any header values support `${env.VAR}` expansion +against the runtime environment (the legacy `${VAR}` form is also accepted), +which lets you wire the GitHub Actions OIDC +token endpoint without putting secrets in YAML: + +```yaml +identity_token: + url: ${env.ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://api.anthropic.com + headers: + Authorization: bearer ${env.ACTIONS_ID_TOKEN_REQUEST_TOKEN} + response_field: value +``` + +`auth:` is mutually exclusive with `--gateway`. Token-refresh failures are +surfaced through the normal error path with a clear `anthropic workload +identity federation: failed to refresh identity token from <kind> source +(federation_rule=fdrl_…): ...` message in the TUI. + +A complete walkthrough of all four sources lives in +[`examples/anthropic_wif.yaml`](https://github.com/docker/docker-agent/blob/main/examples/anthropic_wif.yaml). + +## Configuration + +### Inline + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 +``` + +### Named Model + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 +``` + +## Available Models + +| Model ID | Description | +| ------------------- | --------------------------------------------------- | +| `claude-opus-5` | Highest-capability Opus model; full effort ladder (low–max) | +| `claude-opus-4-7` | Previous Opus flagship; supports task budget | +| `claude-sonnet-4-5` | Most capable Sonnet; supports extended thinking | +| `claude-sonnet-4-0` | Previous Sonnet generation, still supported | +| `claude-haiku-4-5` | Fast and inexpensive, good for tight loops | + +## Thinking Budget + +Anthropic accepts either an integer token budget or a string effort value. Thinking is off unless you set `thinking_budget`; when set, interleaved thinking is auto-enabled. + +**Token budget** (1024–32768; works on all extended-thinking Claude models): + +```yaml +models: + claude-deep: + provider: anthropic + model: claude-sonnet-4-5 + thinking_budget: 16384 # must be < max_tokens +``` + +**Adaptive / effort-based** (Claude Opus 4.6+, Sonnet 4.6 — every string value is sent as adaptive thinking via `output_config.effort`): + +```yaml +models: + opus-adaptive: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: adaptive # model decides effort (defaults to high) + + opus-effort: + provider: anthropic + model: claude-opus-4-6 + thinking_budget: high # low | medium | high | xhigh | max (same as adaptive/<effort>) +``` + +On models that reject token-based thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6), an integer budget is automatically coerced to `adaptive` with a logged warning. See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for the full cross-provider reference. + +## Interleaved Thinking + +Auto-enabled whenever a thinking budget is configured on a Claude model. Allows tool calls during model reasoning for more integrated problem-solving: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + provider_opts: + interleaved_thinking: false # disable if needed +``` + +## Task Budget + +`task_budget` caps the **total** number of tokens the model may spend across a +multi-step agentic task — combined thinking, tool calls, and final output. It +is forwarded as +[`output_config.task_budget`](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7) +and is ideal for letting long-running agents self-regulate effort without +tightening `max_tokens` on every call. + +Docker Agent automatically attaches the required `task-budgets-2026-03-13` +beta header whenever this field is set. You can configure `task_budget` on +**any** Claude model — Docker Agent never gates it by model name. At the time +of writing, only **Claude Opus 4.7** actually honors the field; other Claude +models (Sonnet 4.5, Opus 4.5 / 4.6, etc.) are expected to reject requests +that include it. Check the Anthropic release notes linked above for the +current list of supported models. + +```yaml +models: + opus: + provider: anthropic + model: claude-opus-4-7 + task_budget: 128000 # integer shorthand → { type: tokens, total: 128000 } + thinking_budget: adaptive +``` + +Object form (forward-compatible with future budget types): + +```yaml + opus: + provider: anthropic + model: claude-opus-4-7 + task_budget: + type: tokens + total: 128000 +``` + +See the full schema on the [Model Configuration](../../configuration/models/index.md#task-budget) page. + +## Server-Side Fallbacks + +When the primary model refuses a request (e.g. Claude Fable 5's safety +classifiers ending the turn with stop reason `refusal`), Anthropic can retry +the request with backup models in a single round trip. Set `fallbacks` in +`provider_opts` to a list of model IDs, in priority order: + +```yaml +models: + fable: + provider: anthropic + model: claude-fable-5 + provider_opts: + fallbacks: + - claude-opus-4-8 + - claude-sonnet-4-6 +``` + +Docker Agent automatically attaches the required +`server-side-fallback-2026-06-01` beta header and forwards the option as +`fallbacks: [{"model": "..."}]`. The response's `model` field reports which +model actually served the request. + +Fallback models receive the exact same request as the primary model +(thinking configuration, task budget, beta features, ...), so list only +models that accept the same request shape. Not available on Bedrock, Vertex +AI, or the Message Batches API. + +## Thinking Display + +Controls whether thinking blocks are returned in responses when thinking is enabled. Newer Claude models (Opus 4.7+, Fable 5) hide thinking content by default (`omitted`); Docker Agent counters this by requesting `summarized` thinking whenever an adaptive/effort-based budget is used without an explicit `thinking_display`, so reasoning stays visible in the UI. Set `thinking_display` in `provider_opts` to override: + +```yaml +models: + claude-opus-4-7: + provider: anthropic + model: claude-opus-4-7 + thinking_budget: adaptive + provider_opts: + thinking_display: omitted # "summarized" or "omitted" ("display" on pre-4.6 models only) +``` + +Valid values: + +- `summarized`: thinking blocks are returned with summarized thinking text (Docker Agent's default for adaptive/effort-based budgets). +- `display`: thinking blocks are returned for display. Only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); models from the adaptive-thinking generation onward (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) reject it, and Docker Agent fails fast with a configuration error instead of sending a request the API would refuse. +- `omitted`: thinking blocks are returned with an empty thinking field; the signature is still returned for multi-turn continuity. Useful to reduce time-to-first-text-token when streaming. + +Note: `thinking_display` applies to both `thinking_budget` with token counts and adaptive/effort-based budgets. For token-count budgets no default is applied (the API already defaults to `summarized`). Full thinking tokens are billed regardless of the `thinking_display` value. + +> [!NOTE] +> Anthropic thinking budget values below 1024 or greater than or equal to `max_tokens` are ignored (a warning is logged). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md new file mode 100644 index 000000000000..f36428484838 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md @@ -0,0 +1,91 @@ +--- +title: "Baseten" +description: "Use Baseten AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, baseten +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/providers/baseten/ +--- + +_Use Baseten AI models with Docker Agent._ + +## Overview + +Baseten provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Baseten as an alias provider. + +## Setup + +1. Get an API key from [Baseten](https://www.baseten.co/) +2. Set the environment variable: + + ```bash + export BASETEN_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Baseten: + +```yaml +agents: + root: + model: baseten/deepseek-ai/DeepSeek-V3.1 + description: Assistant using Baseten + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + baseten_model: + provider: baseten + model: deepseek-ai/DeepSeek-V3.1 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: baseten_model + description: Assistant using Baseten + instruction: You are a helpful assistant. +``` + +## Available Models + +Baseten hosts various open models through its Model APIs. Check the [Baseten documentation](https://docs.baseten.co/) for the current model catalog. + +| Model | Description | +| ------------------------------ | ------------------------------ | +| `deepseek-ai/DeepSeek-V3.1` | DeepSeek V3.1 model | +| `moonshotai/Kimi-K2.5` | Moonshot Kimi K2.5 model | +| `openai/gpt-oss-120b` | GPT-OSS 120B model | +| `zai-org/GLM-5` | GLM-5 model | + +## How It Works + +Baseten is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://inference.baseten.co/v1` +- **Token Variable:** `BASETEN_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: baseten/deepseek-ai/DeepSeek-V3.1 + description: Code assistant using DeepSeek + instruction: | + You are an expert programmer using DeepSeek V3.1. + Write clean, well-documented code. + Follow best practices for the language being used. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md new file mode 100644 index 000000000000..f7e190a08602 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md @@ -0,0 +1,175 @@ +--- +title: "AWS Bedrock" +description: "Access Claude, Nova, Llama, and more through AWS infrastructure with enterprise-grade security and compliance." +keywords: docker agent, ai agents, model providers, llm, aws bedrock +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/providers/bedrock/ +--- + +_Access Claude, Nova, Llama, and more through AWS infrastructure with enterprise-grade security and compliance._ + +## Prerequisites + +- AWS account with Bedrock enabled in your region +- Model access granted in the [Bedrock Console](https://console.aws.amazon.com/bedrock/) (some models require approval) +- AWS credentials configured (see authentication below) + +## Configuration + +```yaml +models: + bedrock-claude: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + max_tokens: 64000 + provider_opts: + region: us-east-1 +``` + +## Authentication + +### Option 1: Bedrock API Key (Simplest) + +```bash +export AWS_BEARER_TOKEN_BEDROCK="your-key" +``` + +```yaml +models: + bedrock: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + token_key: AWS_BEARER_TOKEN_BEDROCK # env var name + provider_opts: + region: us-east-1 +``` + +### Option 2: AWS Credentials (Default) + +Uses the standard AWS SDK credential chain: env vars → shared credentials → config → IAM roles. + +```yaml +models: + bedrock: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + provider_opts: + profile: my-aws-profile + region: us-east-1 +``` + +### With IAM Role Assumption + +```yaml +models: + bedrock: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + provider_opts: + role_arn: "arn:aws:iam::123456789012:role/BedrockAccessRole" + external_id: "my-external-id" +``` + +## Provider Options + +| Option | Type | Default | Description | +| ------------------------ | ------ | ---------------------- | ------------------------------------ | +| `region` | string | us-east-1 | AWS region | +| `profile` | string | — | AWS profile name | +| `role_arn` | string | — | IAM role ARN for assume role | +| `role_session_name` | string | docker-agent-bedrock-session | Session name for assumed role | +| `external_id` | string | — | External ID for role assumption | +| `endpoint_url` | string | — | Custom endpoint (VPC/testing) | +| `interleaved_thinking` | bool | auto | Allow reasoning between tool calls (Claude); auto-enabled when a thinking budget is set on a Claude model; adds the required beta header automatically | +| `disable_prompt_caching` | bool | false | Disable automatic prompt caching | + +## Inference Profiles + +Use inference profile prefixes for optimal routing: + +| Prefix | Routes To | +| --------- | ---------------------------------------- | +| `global.` | All commercial AWS regions (recommended) | +| `us.` | US regions only | +| `eu.` | EU regions only (GDPR compliance) | +| `apac.` | Asia Pacific regions only | + +> [!TIP] +> **Inference profiles** +> +> Use `global.` prefix on model IDs for automatic cross-region routing. Use `eu.` prefix for GDPR compliance. + +## Thinking Budget (Claude on Bedrock) + +Bedrock Claude models support extended thinking — an internal reasoning phase before the model produces its response. Set `thinking_budget` to a token count (1024–32768) or an effort level string that maps automatically: + +| Effort level | Token budget | +| ------------ | ------------ | +| `minimal` | 1,024 | +| `low` | 2,048 | +| `medium` | 8,192 | +| `high` | 16,384 | +| `xhigh`/`max`| 32,768 | + +```yaml +models: + bedrock-claude-thinking: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + thinking_budget: 8192 # tokens, or use an effort string like "medium" + max_tokens: 16384 # must be > thinking_budget + provider_opts: + region: us-east-1 +``` + +`thinking_budget` must be ≥ 1024 and less than `max_tokens`. Values outside this range are logged as a warning and ignored. + +### Adaptive thinking (Opus 4.6+) + +Newer Claude Opus models (4.6, 4.7, 4.8) **reject token-based thinking** — Bedrock returns a `ValidationException` asking for `thinking.type=adaptive`. For these models, use adaptive thinking: + +```yaml +models: + bedrock-opus-adaptive: + provider: amazon-bedrock + model: global.anthropic.claude-opus-4-8 + thinking_budget: adaptive/high # adaptive | adaptive/low | adaptive/medium | adaptive/high | adaptive/xhigh | adaptive/max + provider_opts: + region: us-east-1 +``` + +Docker Agent recognizes these models (including Bedrock-style IDs) and transparently coerces a configured token budget or effort level to adaptive thinking, logging a warning — so `thinking_budget: 32768` on Opus 4.8 won't fail, but `adaptive` or `adaptive/<effort>` is the recommended configuration. On older models that still use token-based thinking (e.g. Sonnet 4.5), `adaptive` is forwarded as-is and rejected by Bedrock — use a token count or effort level there instead. + +> [!NOTE] +> **Temperature and top_p** +> +> Bedrock Claude suppresses `temperature` and `top_p` while extended thinking is active — Anthropic requires `temperature=1.0` internally. + +## Interleaved Thinking (Claude on Bedrock) + +Interleaved thinking lets the model reason between tool calls, not just at the start. This is useful for complex agentic tasks. Enable it alongside a thinking budget: + +```yaml +models: + bedrock-claude-interleaved: + provider: amazon-bedrock + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 + thinking_budget: high + provider_opts: + region: us-east-1 + # interleaved_thinking is auto-enabled when thinking_budget is set +``` + +Docker Agent auto-enables `interleaved_thinking` whenever a thinking budget is configured on a Bedrock-hosted Claude model and automatically adds the `interleaved-thinking-2025-05-14` beta header. If you set `interleaved_thinking: false` while a thinking budget is active, a warning is logged because the budget may be ignored by Bedrock without the beta header. + +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for a full cross-provider overview. + +## Prompt Caching + +Automatically enabled for supported models to reduce latency and costs. System prompts, tool definitions, and recent messages are cached with a 5-minute TTL. + +```bash +# Disable if needed +provider_opts: + disable_prompt_caching: true +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md new file mode 100644 index 000000000000..bf0dba14c912 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md @@ -0,0 +1,103 @@ +--- +title: "Cerebras" +description: "Use Cerebras models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, cerebras +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/providers/cerebras/ +--- + +_Use Cerebras models with Docker Agent._ + +## Overview + +[Cerebras](https://www.cerebras.ai/) serves open-weight models such as GPT-OSS +and GLM through an OpenAI-compatible API on its wafer-scale hardware, delivering +some of the highest tokens/sec available. That speed makes it a strong fit for +latency-sensitive coding workflows. Docker Agent includes built-in support for +Cerebras as an alias provider. + +## Setup + +1. Create an API key from the [Cerebras Cloud console](https://cloud.cerebras.ai/). +2. Set the environment variable: + + ```bash + export CEREBRAS_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Cerebras: + +```yaml +agents: + root: + model: cerebras/gpt-oss-120b + description: Assistant using Cerebras + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + cerebras_model: + provider: cerebras + model: gpt-oss-120b + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: cerebras_model + description: Assistant using Cerebras + instruction: You are a helpful assistant. +``` + +## Available Models + +Cerebras hosts a curated set of open-weight models. Check the +[Cerebras models documentation](https://inference-docs.cerebras.ai/models/overview) +for current model IDs, context limits, and pricing. + +| Model | Description | +| --- | --- | +| `gpt-oss-120b` | Open-weight GPT-OSS reasoning model with tool calling | +| `zai-glm-4.7` | Z.AI GLM-4.7 reasoning model with tool calling | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. Cerebras may serve additional models not in the built-in catalog; those +> still work but resolve to default capability metadata locally. + +## How It Works + +Cerebras is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.cerebras.ai/v1` +- **Token Variable:** `CEREBRAS_API_KEY` + +Because Cerebras fronts open-weight models whose chat templates may only accept +a single leading system message, Docker Agent coalesces its per-source system +messages (agent instruction plus each toolset's instructions) into one before +sending the request. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: cerebras/gpt-oss-120b + description: Fast code assistant using Cerebras + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md new file mode 100644 index 000000000000..ed50250056b5 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md @@ -0,0 +1,128 @@ +--- +title: "ChatGPT (OpenAI account)" +description: "Use your ChatGPT Plus/Pro/Business subscription with Docker Agent by signing in with your OpenAI account, no API key needed." +keywords: docker agent, ai agents, model providers, llm, chatgpt, openai, codex, subscription +weight: 55 +canonical: https://docs.docker.com/ai/docker-agent/providers/chatgpt/ +--- + +_Use your ChatGPT subscription with Docker Agent by signing in with your OpenAI account. No API key needed._ + +## Overview + +The `chatgpt` provider authenticates with a ChatGPT account (the same +"Sign in with ChatGPT" flow used by OpenAI's Codex CLI) instead of an +`OPENAI_API_KEY`. Usage is billed against your ChatGPT Plus, Pro, or +Business plan rather than pay-per-token API credits. + +Under the hood, Docker Agent talks to the ChatGPT Codex backend +(`https://chatgpt.com/backend-api/codex`), which serves the `gpt-5` model +family over the OpenAI Responses API. GPT-5.6 (Sol/Terra/Luna) is served +there too; GPT-5.2 and GPT-5.3-Codex are deprecated for ChatGPT sign-in. + +## Prerequisites + +- A paid **ChatGPT** subscription (Plus, Pro, or Business). +- A browser on the machine running the sign-in (the OAuth flow uses a + fixed `localhost:1455` callback). + +## Sign In + +```bash +docker agent setup +``` + +Pick **chatgpt** in the provider list: instead of asking for an API key, the +wizard opens your browser on the ChatGPT sign-in page and stores the +resulting OAuth credential in the Docker Agent config directory +(`~/.config/cagent/chatgpt-auth.json`, owner-only permissions). The access +token is refreshed automatically; you only need to sign in again if the +refresh token is revoked. + +Related commands: + +```bash +docker agent doctor # the chatgpt row shows the credential state +rm ~/.config/cagent/chatgpt-auth.json # sign out (remove the stored sign-in) +``` + +## Configuration + +### Inline + +```yaml +agents: + root: + model: chatgpt/gpt-5.6 + instruction: You are a helpful assistant. +``` + +### Named model + +```yaml +models: + gpt: + provider: chatgpt + model: gpt-5.6 + thinking_budget: medium + +agents: + root: + model: gpt +``` + +## Available Models + +The Codex backend serves the models available to your ChatGPT plan, +typically: + +| Model | Best For | +| -------------------- | -------------------------------------- | +| `gpt-5.6` | Alias for `gpt-5.6-sol`; general purpose, strong reasoning | +| `gpt-5.6-sol` | Frontier model, most capable | +| `gpt-5.6-terra` | Everyday workhorse | +| `gpt-5.6-luna` | High-volume, cost-efficient | +| `gpt-5.2` | Deprecated for ChatGPT sign-in | +| `gpt-5.2-codex` | Deprecated for ChatGPT sign-in | + +The effort picker exposes Low/Medium/High/XHigh/Max on the GPT-5.6 family +(no Minimal). + +## How It Works + +- **Auth:** the `docker agent setup` sign-in runs an OAuth 2.0 + authorization-code + PKCE flow against `auth.openai.com`. The stored login + is exposed to credential checks (doctor, `first_available`, auto model + selection) as the virtual `CHATGPT_OAUTH_TOKEN` variable. +- **API:** requests go to the Responses API only; the backend has no Chat + Completions endpoint, so `api_type` is pinned automatically. +- **Request shape:** the backend requires stateless requests (`store: false`) + and a top-level `instructions` field, so Docker Agent moves system messages + there. Client-side sampling parameters (`temperature`, `top_p`, + `max_tokens`) are not supported by the backend and are dropped. + +## Setting the Token Explicitly + +`CHATGPT_OAUTH_TOKEN` can also be set like any other credential (shell +environment, `--env-from-file`, ...). An explicitly set value takes +precedence over the stored sign-in. This is useful for short-lived CI runs +with a pre-minted access token, but note that such a token expires and is not +refreshed. + +## ChatGPT Subscription vs. OpenAI API Key + +| | `chatgpt` | `openai` | +| --- | --- | --- | +| Credential | ChatGPT account sign-in | `OPENAI_API_KEY` | +| Billing | Included in the ChatGPT plan (rate-limited) | Pay per token | +| Models | `gpt-5` family served by the Codex backend | Full OpenAI API catalog | +| Sampling controls (`temperature`, ...) | Not supported | Supported | +| Embeddings / reranking | Not supported | Supported | + +When both credentials are configured, automatic model selection prefers +`openai`; pin `--model chatgpt/gpt-5.6` (or use a named model) to use the +subscription. + +> [!NOTE] +> Use of the Codex backend is governed by OpenAI's terms for ChatGPT and +> Codex. Sign-in is per user; do not share the stored credential. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md new file mode 100644 index 000000000000..558d8c6e03b0 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md @@ -0,0 +1,115 @@ +--- +title: "Cloudflare AI Gateway" +description: "Use Cloudflare AI Gateway models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, cloudflare ai gateway +weight: 60 +canonical: https://docs.docker.com/ai/docker-agent/providers/cloudflare-ai-gateway/ +--- + +_Use Cloudflare AI Gateway models with Docker Agent._ + +## Overview + +[Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) is a +single OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, +Workers AI and more, with caching, rate limiting and observability. Docker Agent +includes built-in support for AI Gateway as an alias provider. + +The alias sends your token in the standard `Authorization: Bearer` header, so it +works out of the box with a gateway that has **authentication disabled** (the +default), typically to route to your own Workers AI models through a gateway you +own. See [Authentication](#authentication) below for the unified-billing / +authenticated-gateway caveat. + +## Setup + +The gateway endpoint is account- and gateway-scoped, so its base URL is resolved +from your account ID and gateway ID. Three environment variables are required: + +```bash +export CLOUDFLARE_ACCOUNT_ID=your-account-id +export CLOUDFLARE_GATEWAY_ID=your-gateway-id +export CLOUDFLARE_API_TOKEN=your-api-token +``` + +Create a gateway from the +[AI Gateway dashboard](https://dash.cloudflare.com/?to=/:account/ai/ai-gateway) +and an API token with the appropriate permissions. + +## Usage + +AI Gateway model IDs use the gateway's `provider/model` form (for example +`workers-ai/@cf/meta/llama-3.1-8b-instruct` or `openai/gpt-4o`); the gateway +routes each request to the underlying provider. + +### Inline Syntax + +```yaml +agents: + root: + model: cloudflare-ai-gateway/workers-ai/@cf/meta/llama-3.1-8b-instruct + description: Assistant using Cloudflare AI Gateway + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + cloudflare_model: + provider: cloudflare-ai-gateway + model: "workers-ai/@cf/meta/llama-3.1-8b-instruct" + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: cloudflare_model + description: Assistant using Cloudflare AI Gateway + instruction: You are a helpful assistant. +``` + +## Available Models + +AI Gateway exposes models from many providers behind one endpoint. Check the +[AI Gateway documentation](https://developers.cloudflare.com/ai-gateway/) for +the current provider list, model IDs, and how billing works. + +> Model IDs are case-sensitive and must be passed exactly as the gateway lists +> them, including the `provider/` prefix. + +## How It Works + +Cloudflare AI Gateway is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://gateway.ai.cloudflare.com/v1/${CLOUDFLARE_ACCOUNT_ID}/${CLOUDFLARE_GATEWAY_ID}/compat` +- **Token Variable:** `CLOUDFLARE_API_TOKEN` + +The base URL is templated: `${CLOUDFLARE_ACCOUNT_ID}` and +`${CLOUDFLARE_GATEWAY_ID}` are substituted from the environment when the provider +is built, so both must be set in addition to `CLOUDFLARE_API_TOKEN`. Because the +gateway can route to open-weight models with strict chat templates, Docker Agent +coalesces consecutive system messages into a single leading one for this +provider. + +## Authentication + +Docker Agent authenticates by sending `CLOUDFLARE_API_TOKEN` in the standard +`Authorization: Bearer` header. On the `.../compat` endpoint that header is +treated as the **provider** key, so this alias works when: + +- the gateway has **authentication disabled** (the default), and +- the routed models accept that token as their provider key, which is the case + for **Workers AI** models (`workers-ai/@cf/...`). + +A gateway with **authentication enabled** (required for +[unified billing](https://developers.cloudflare.com/ai-gateway/features/unified-billing/)) +instead expects the token in Cloudflare's `cf-aig-authorization` header. The +alias does not send that header, and custom `provider_opts.http_headers` values +are not environment-expanded, so an authenticated gateway is **not supported out +of the box** today. For that setup, use an unauthenticated gateway, or configure +a [custom provider](../custom/index.md) against the +Cloudflare AI Gateway REST API. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md new file mode 100644 index 000000000000..68477296aee6 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md @@ -0,0 +1,91 @@ +--- +title: "Cloudflare Workers AI" +description: "Use Cloudflare Workers AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, cloudflare workers ai +weight: 70 +canonical: https://docs.docker.com/ai/docker-agent/providers/cloudflare-workers-ai/ +--- + +_Use Cloudflare Workers AI models with Docker Agent._ + +## Overview + +[Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) runs +open-weight models (Llama, Mistral, Qwen, Gemma, and more) on Cloudflare's +global edge network through an OpenAI-compatible endpoint. No separate provider +accounts are needed for the supported models. Docker Agent includes built-in +support for Workers AI as an alias provider. + +## Setup + +Workers AI is account-scoped, so its base URL is resolved from your account ID. +Two environment variables are required: + +```bash +export CLOUDFLARE_ACCOUNT_ID=your-account-id +export CLOUDFLARE_API_TOKEN=your-api-token +``` + +Create an API token with the `Workers AI` permission from the +[Cloudflare dashboard](https://dash.cloudflare.com/profile/api-tokens). Your +account ID is shown on the Workers AI page. + +## Usage + +Workers AI model IDs use the `@cf/...` form (for example +`@cf/meta/llama-3.1-8b-instruct`). + +### Inline Syntax + +```yaml +agents: + root: + model: cloudflare-workers-ai/@cf/meta/llama-3.1-8b-instruct + description: Assistant using Cloudflare Workers AI + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + cloudflare_model: + provider: cloudflare-workers-ai + model: "@cf/meta/llama-3.1-8b-instruct" + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: cloudflare_model + description: Assistant using Cloudflare Workers AI + instruction: You are a helpful assistant. +``` + +## Available Models + +Check the +[Workers AI models catalog](https://developers.cloudflare.com/workers-ai/models/) +for the current list, IDs, and pricing. + +| Model | Description | +| --- | --- | +| `@cf/meta/llama-3.1-8b-instruct` | Meta Llama 3.1 8B Instruct | +| `@cf/mistralai/mistral-small-3.1-24b-instruct` | Mistral Small 3.1 24B Instruct | +| `@cf/qwen/qwen2.5-coder-32b-instruct` | Qwen 2.5 Coder 32B Instruct | + +## How It Works + +Cloudflare Workers AI is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1` +- **Token Variable:** `CLOUDFLARE_API_TOKEN` + +The base URL is templated: `${CLOUDFLARE_ACCOUNT_ID}` is substituted from the +environment when the provider is built, so `CLOUDFLARE_ACCOUNT_ID` must be set in +addition to `CLOUDFLARE_API_TOKEN`. Because Workers AI serves open-weight models +with strict chat templates, Docker Agent coalesces consecutive system messages +into a single leading one for this provider. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md new file mode 100644 index 000000000000..427585502d7b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md @@ -0,0 +1,315 @@ +--- +title: "Provider Definitions" +description: "Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more." +keywords: docker agent, ai agents, model providers, llm, provider definitions +weight: 280 +canonical: https://docs.docker.com/ai/docker-agent/providers/custom/ +--- + +_Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more._ + +## Overview + +The `providers` section in your agent YAML lets you define named provider configurations that models can reference. This is useful for: + +- **Grouping shared defaults** — Set temperature, max_tokens, thinking_budget once and share across models +- **Custom endpoints** — Connect to self-hosted models, API proxies, or gateways +- **Centralizing credentials** — Define token_key once for all models using a provider +- **Any provider type** — Works with OpenAI, Anthropic, Google, Bedrock, and any OpenAI-compatible API + +> [!NOTE] +> **Works with any provider** +> +> The `providers` section supports all provider types: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, and any built-in alias. When the `provider` field is not set, it defaults to `openai` for backward compatibility. + +## Configuration + +### OpenAI-compatible endpoint + +```yaml +providers: + my_gateway: + base_url: https://api.example.com/v1 + token_key: MY_API_KEY + +models: + my_model: + provider: my_gateway + model: gpt-4o + +agents: + root: + model: my_model + instruction: You are a helpful assistant. +``` + +### Anthropic with shared defaults + +```yaml +providers: + my_anthropic: + provider: anthropic + token_key: MY_ANTHROPIC_KEY + max_tokens: 16384 + thinking_budget: 8192 + +models: + claude_smart: + provider: my_anthropic + model: claude-sonnet-4-5 + # Inherits max_tokens: 16384, thinking_budget: 8192 + + claude_fast: + provider: my_anthropic + model: claude-haiku-4-5 + thinking_budget: 1024 # Overrides provider default + +agents: + root: + model: claude_smart + instruction: You are a helpful assistant. +``` + +### Google with shared temperature + +```yaml +providers: + my_google: + provider: google + temperature: 0.3 + +models: + gemini: + provider: my_google + model: gemini-2.5-flash + # Inherits temperature: 0.3 + +agents: + root: + model: gemini + instruction: You are a helpful assistant. +``` + +## Provider Properties + +| Property | Type | Description | Default | +| --------------------- | ---------- | ------------------------------------------------------------------------------------- | ------------------------ | +| `provider` | string | Underlying provider type: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, etc. | `openai` | +| `api_type` | string | API schema: `openai_chatcompletions` or `openai_responses`. Only for OpenAI-compatible providers. When omitted, the API type is selected automatically based on the model name: newer models (gpt-4.1, o-series, gpt-5, Codex) default to `openai_responses`; all others default to `openai_chatcompletions`. | `auto (model-dependent)` | +| `base_url` | string | Base URL for the API endpoint. Required for OpenAI-compatible providers, optional for native providers. | — | +| `token_key` | string | Environment variable name containing the API token. | — | +| `unload_api` | string | Optional path (or absolute URL) to the provider's model-unload endpoint. Used by the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook to release model resources between agent switches. Relative paths resolve against `base_url`'s scheme + host; absolute URLs are used verbatim. Today only Docker Model Runner ships a provider that calls this endpoint; cloud providers don't implement the underlying interface and the hook silently skips them. | — | +| `temperature` | float | Default sampling temperature (0.0–2.0). | — | +| `max_tokens` | int | Default maximum response tokens. | — | +| `top_p` | float | Default nucleus sampling threshold (0.0–1.0). | — | +| `frequency_penalty` | float | Default frequency penalty (-2.0–2.0). | — | +| `presence_penalty` | float | Default presence penalty (-2.0–2.0). | — | +| `parallel_tool_calls` | boolean | Whether to enable parallel tool calls by default. | — | +| `track_usage` | boolean | Whether to track token usage by default. | — | +| `thinking_budget` | string/int | Default reasoning effort/budget. | — | +| `task_budget` | int/object | Default total token budget for an agentic task (forwarded to Anthropic; honored by Claude Opus 4.7 today). Integer shorthand or `{type: tokens, total: N}`. | — | +| `compaction_model` | string | Default model used for session compaction (summary generation) by agents whose model uses this provider. Named model or inline `provider/model` string. Agent-level and model-level `compaction_model` take precedence. | — | +| `provider_opts` | object | Provider-specific options passed through to the client. | — | + +## Default Inheritance + +Models referencing a provider inherit all its defaults. Model-level settings always take precedence: + +```yaml +providers: + my_anthropic: + provider: anthropic + token_key: MY_ANTHROPIC_KEY + max_tokens: 16384 + temperature: 0.7 + thinking_budget: high + +models: + # Inherits everything from provider + claude_default: + provider: my_anthropic + model: claude-sonnet-4-5 + + # Overrides temperature and thinking_budget, inherits the rest + claude_custom: + provider: my_anthropic + model: claude-sonnet-4-5 + temperature: 0.2 + thinking_budget: low +``` + +`compaction_model` works slightly differently: it is not merged into the model +but resolved per agent, with the agent-level `compaction_model` winning over +the model-level one, which wins over the provider-level default. + +## Shorthand Syntax + +Once a provider is defined, you can use the shorthand `provider_name/model` syntax: + +```yaml +agents: + root: + model: my_gateway/gpt-4o-mini # uses the provider's defaults + researcher: + model: my_anthropic/claude-sonnet-4-5 # uses anthropic provider defaults +``` + +## API Types + +Only applicable for OpenAI-compatible providers (when `provider` is `openai` or unset): + +- **`openai_chatcompletions`** — Standard OpenAI Chat Completions API. Works with most OpenAI-compatible endpoints. +- **`openai_responses`** — OpenAI Responses API. For newer models that require the Responses API format. + +> If `api_type` is not set, Docker Agent automatically selects the API type based on the model name. You only need to set `api_type` explicitly to override the detected default. + +## Examples + +### vLLM / Ollama + +```yaml +providers: + local_llm: + base_url: http://localhost:8000/v1 + +agents: + root: + model: local_llm/llama-3.1-8b +``` + +> [!NOTE] +> **Reasoning tokens from OpenAI-compatible providers** +> +> Models that stream reasoning under `delta.reasoning` (e.g. Qwen3 served via OVHcloud AI Endpoints, OpenRouter, or a self-hosted vLLM / SGLang deployment) are fully supported. Docker Agent reads both the `delta.reasoning_content` and `delta.reasoning` fields from the stream, so thinking blocks are captured and shown in the TUI regardless of which field the server uses. + +### API Router (Requesty, LiteLLM) + +```yaml +providers: + router: + base_url: https://router.requesty.ai/v1 + token_key: REQUESTY_API_KEY + +agents: + root: + model: router/anthropic/claude-sonnet-4-5 +``` + +### Azure OpenAI + +```yaml +models: + azure_model: + provider: azure + model: gpt-4o + base_url: https://your-llm.openai.azure.com + provider_opts: + api_version: 2024-12-01-preview +``` + +### Anthropic Team Setup + +```yaml +providers: + team_anthropic: + provider: anthropic + token_key: TEAM_ANTHROPIC_KEY + max_tokens: 32768 + thinking_budget: high + temperature: 0.5 + +models: + architect: + provider: team_anthropic + model: claude-sonnet-4-5 + + reviewer: + provider: team_anthropic + model: claude-haiku-4-5 + thinking_budget: low # faster reviews + +agents: + root: + model: architect + sub_agents: [code_reviewer] + code_reviewer: + model: reviewer +``` + +### Multi-Provider with Shared Defaults + +```yaml +providers: + fast_openai: + base_url: https://api.openai.com/v1 + token_key: OPENAI_API_KEY + temperature: 0.3 + max_tokens: 8192 + + smart_anthropic: + provider: anthropic + token_key: ANTHROPIC_API_KEY + max_tokens: 64000 + thinking_budget: high + +agents: + root: + model: smart_anthropic/claude-sonnet-4-5 + sub_agents: [helper] + helper: + model: fast_openai/gpt-4o-mini +``` + +## Global Providers (User Configuration) + +Providers defined in an agent file only apply to that file. To make a custom +provider available to every command (`docker agent run`, `new`, `models`, ...), +define it once in your user configuration (`~/.config/cagent/config.yaml`) +under the same `providers` key: + +```yaml +# ~/.config/cagent/config.yaml +providers: + myprovider: + base_url: https://llm.corp.example.com/v1 + api_type: openai_chatcompletions + token_key: MYPROVIDER_API_KEY +``` + +The easiest way to register one is the interactive wizard: + +```bash +docker agent setup +# pick "3. Custom OpenAI-compatible endpoint", then enter the base URL, +# API format, and the environment variable holding the API key +``` + +Once registered, the provider works everywhere: + +```bash +docker agent models --provider myprovider # list the endpoint's models +docker agent new --model myprovider/mymodel # build agents with it +docker agent run --model myprovider/mymodel # chat with it +``` + +Global providers are merged into every loaded agent configuration; when an +agent file defines a provider with the same name, the agent file wins. Note +that automatic model selection (`model: auto`) never picks a custom provider, +so reference its models explicitly with `--model <name>/<model>` or +`default_model`. + +## How It Works + +When you reference a provider: + +1. The provider's `provider` field determines which API client to use (defaults to `openai`) +2. The provider's `base_url` and `token_key` are applied to the model (if not already set on the model) +3. All model-level defaults (temperature, max_tokens, thinking_budget, etc.) are inherited (model settings take precedence) +4. For OpenAI-compatible providers, the `api_type` is stored in `provider_opts.api_type` +5. The model is used with the appropriate API client + +A provider with a `base_url` implies `bypass_models_gateway: true` for every +model that references it: user-chosen endpoints are never routed through a +configured models gateway, and such models authenticate with the provider's +own credentials (`token_key`). See +[Gateway Bypass](../../configuration/models/index.md#gateway-bypass). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md new file mode 100644 index 000000000000..e62710a4f413 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md @@ -0,0 +1,96 @@ +--- +title: "DeepSeek" +description: "Use DeepSeek models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, deepseek +weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/providers/deepseek/ +--- + +_Use DeepSeek models with Docker Agent._ + +## Overview + +[DeepSeek](https://www.deepseek.com/) serves its frontier chat and reasoning +models through an OpenAI-compatible API, with strong price/performance on coding +and reasoning tasks. Docker Agent includes built-in support for DeepSeek as an +alias provider. + +## Setup + +1. Create an API key from the [DeepSeek Platform](https://platform.deepseek.com/api_keys). +2. Set the environment variable: + + ```bash + export DEEPSEEK_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use DeepSeek: + +```yaml +agents: + root: + model: deepseek/deepseek-chat + description: Assistant using DeepSeek + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + deepseek_model: + provider: deepseek + model: deepseek-chat + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: deepseek_model + description: Assistant using DeepSeek + instruction: You are a helpful assistant. +``` + +## Available Models + +DeepSeek exposes a small, vendor-controlled model lineup. Check the +[DeepSeek models documentation](https://api-docs.deepseek.com/quick_start/pricing) +for current model IDs, context limits, and pricing. + +| Model | Description | +| --- | --- | +| `deepseek-chat` | DeepSeek-V3, general-purpose chat and tool calling | +| `deepseek-reasoner` | DeepSeek-R1, extended-reasoning model | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +DeepSeek is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.deepseek.com/v1` +- **Token Variable:** `DEEPSEEK_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: deepseek/deepseek-chat + description: Code assistant using DeepSeek-V3 + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md new file mode 100644 index 000000000000..65b0528bec80 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md @@ -0,0 +1,253 @@ +--- +title: "Docker Model Runner" +description: "Run AI models locally with Docker — no API keys, no costs, full data privacy." +keywords: docker agent, ai agents, model providers, llm, docker model runner +weight: 90 +canonical: https://docs.docker.com/ai/docker-agent/providers/dmr/ +--- + +_Run AI models locally with Docker — no API keys, no costs, full data privacy._ + +## Overview + +Docker Model Runner (DMR) lets you run open-source AI models directly on your machine. Models run in Docker, so there's no API key needed and no data leaves your computer. + +Docker Agent automatically discovers models you have already pulled from DMR. When no model is explicitly configured, auto-selection prefers a locally-installed model (choosing the model specified via the `model:` key in the agent YAML if it is already pulled locally, or otherwise the first available non-embedding model) rather than always defaulting to `ai/qwen3:latest` and triggering a pull prompt. + +> [!TIP] +> **No API key needed** +> +> DMR runs models locally — your data never leaves your machine. Great for development, sensitive data, or offline use. + +## Prerequisites + +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the Model Runner feature enabled +- Verify with: `docker model status --json` + +## Configuration + +### Inline + +```yaml +agents: + root: + model: dmr/ai/qwen3 +``` + +### Named Model + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + max_tokens: 8192 +``` + +## Available Models + +Any model available through Docker Model Runner can be used. Common options: + +| Model | Description | +| ------------- | ----------------------------------------------------- | +| `ai/qwen3` | Qwen 3 — versatile, good for coding and general tasks | +| `ai/llama3.2` | Llama 3.2 — Meta's open-source model | + +## Runtime Flags + +Pass flags to the underlying inference runtime (e.g., llama.cpp) using `provider_opts.runtime_flags`: + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + max_tokens: 8192 + provider_opts: + runtime_flags: ["--threads", "8"] +``` + +Runtime flags also accept a single string: + +```yaml +provider_opts: + runtime_flags: "--threads 8" +``` + +Use only flags your Model Runner backend allows (see `docker model configure --help` and backend docs). **Do not** put sampling parameters (`temperature`, `top_p`, penalties) in `runtime_flags` — set them on the model (`temperature`, `top_p`, etc.); they are sent **per request** via the OpenAI-compatible chat API. + +## Context size + +`max_tokens` controls the **maximum output tokens** per chat completion request. To set the engine's **total context window**, use `provider_opts.context_size`: + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + max_tokens: 4096 # max output tokens (per-request) + provider_opts: + context_size: 32768 # total context window (sent via _configure) +``` + +If `context_size` is omitted, Model Runner uses its default. `max_tokens` is **not** used as the context window. + +Docker Agent's auto-compaction scales its summary and keep-tail token budgets proportionally to `context_size`. This ensures compaction works correctly even for small context windows — for example, an 8k-token local model will not have its session history wiped during compaction. + +## Thinking / reasoning budget + +When using the **llama.cpp** backend, `thinking_budget` is sent as structured `llamacpp.reasoning-budget` on `_configure` (maps to `--reasoning-budget`). String efforts use the same token mapping as other providers; `adaptive` maps to unlimited (`-1`). + +When using the **vLLM** backend, `thinking_budget` is sent as `thinking_token_budget` in each chat completion request. Effort levels map to token counts using the same scale as other providers; `adaptive` maps to unlimited (`-1`). + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + thinking_budget: medium # llama.cpp: reasoning-budget=8192; vLLM: thinking_token_budget=8192 +``` + +On **MLX** and **SGLang** backends, `thinking_budget` is silently ignored — those engines do not currently expose a per-request reasoning token budget knob. + +## vLLM-specific configuration + +When running a model on the **vLLM** backend, additional engine-level settings can be passed via `provider_opts` and are forwarded to model-runner's `_configure` endpoint: + +- `gpu_memory_utilization` — fraction of GPU memory (0.0–1.0) vLLM may use. Values outside this range are rejected. +- `hf_overrides` — map of Hugging Face config overrides applied when vLLM loads the model. + +```yaml +models: + vllm-local: + provider: dmr + model: ai/some-model-safetensors + provider_opts: + gpu_memory_utilization: 0.9 + hf_overrides: + max_model_len: 8192 + dtype: bfloat16 +``` + +`hf_overrides` keys (including nested ones) must match `^[a-zA-Z_][a-zA-Z0-9_]*$` — the same rule model-runner enforces server-side to block injection via flags. Invalid keys are rejected at client creation time so you fail fast instead of after a round-trip. + +These options are ignored on non-vLLM backends. + +## Keeping models resident in memory (`keep_alive`) + +By default model-runner unloads idle models after a few minutes. Override the idle timeout via `provider_opts.keep_alive`: + +```yaml +models: + sticky: + provider: dmr + model: ai/qwen3 + provider_opts: + keep_alive: "30m" # duration string + # keep_alive: "0" # unload immediately after each request + # keep_alive: "-1" # keep loaded forever +``` + +Accepted values: any Go duration string (`"30s"`, `"5m"`, `"1h"`, `"2h30m"`), `"0"` (immediate unload), or `"-1"` (never unload). Invalid values are rejected before the configure request is sent. + +## Unloading models on agent switch + +In multi-agent setups where two DMR models can't fit in GPU memory simultaneously, wire the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook into each agent's `on_agent_switch` chain. Every time the active agent transfers control, the runtime POSTs to the engine's `_unload` endpoint to free the previous model's resources before the next one is loaded: + +```yaml +agents: + coder: + model: qwen3-large + handoffs: [reviewer] + hooks: + on_agent_switch: + - type: builtin + command: unload + reviewer: + model: qwen3-coder + handoffs: [coder] + hooks: + on_agent_switch: + - type: builtin + command: unload +``` + +The unload URL is derived from `base_url` by replacing the trailing `/v1` segment (e.g. `http://127.0.0.1:12434/engines/llama.cpp/v1/` → `http://127.0.0.1:12434/engines/llama.cpp/_unload`). Override it explicitly via the provider-level `unload_api` field when running against a non-standard model-runner deployment: + +```yaml +providers: + my_dmr: + provider: dmr + base_url: http://model-runner.docker.internal/engines/v1 + unload_api: /engines/_unload # default; absolute URLs also work + +models: + big: + provider: my_dmr + model: ai/qwen3 +``` + +Unload errors are logged and swallowed — a stuck or unreachable engine never blocks an agent transfer (each call is bounded to 10 s). Pair this with [`keep_alive`](#keeping-models-resident-in-memory-keep_alive) only when you want the model to *also* survive idle periods within a single agent's run; the hook controls **between-agent** unloads independently. + +> [!WARNING] +> **Single-tenant assumption** +> +> The `_unload` endpoint is engine-level: it evicts the model from DMR's memory regardless of who is using it. If two concurrent sessions on the same runtime (e.g. an API server serving multiple users) hit the same agent, switching away in session A will yank the model out from under session B's in-flight request, which then has to wait for a reload. Wire `unload` only when the agents using these models are not run concurrently — typically a single TUI/CLI session. + +See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml) for the full example. + +## Operating mode (`mode`) + +Model-runner normally infers the backend mode from the request path. You can pin it explicitly via `provider_opts.mode`: + +```yaml +provider_opts: + mode: embedding # one of: completion, embedding, reranking, image-generation +``` + +Most agents don't need this — leave it unset unless you know you need it. + +## Raw runtime flags (`raw_runtime_flags`) + +`runtime_flags` (a list) is the preferred way to pass flags. If you have a pre-built command-line string you'd rather ship verbatim, use `raw_runtime_flags` instead: + +```yaml +provider_opts: + raw_runtime_flags: "--threads 8 --batch-size 512" +``` + +Model-runner parses the string with shell-style word splitting. `runtime_flags` and `raw_runtime_flags` are mutually exclusive — setting both is an error. + +## Speculative Decoding + +Use a smaller draft model to predict tokens ahead for faster inference: + +```yaml +models: + fast-local: + provider: dmr + model: ai/qwen3:14B + max_tokens: 8192 + provider_opts: + speculative_draft_model: ai/qwen3:0.6B-F16 + speculative_num_tokens: 16 + speculative_acceptance_rate: 0.8 +``` + +## Custom Endpoint + +If `base_url` is omitted, Docker Agent auto-discovers the DMR endpoint. To set manually: + +```yaml +models: + local: + provider: dmr + model: ai/qwen3 + base_url: http://127.0.0.1:12434/engines/llama.cpp/v1 +``` + +## Troubleshooting + +- **Plugin not found:** Ensure Docker Model Runner is enabled in Docker Desktop. Docker Agent will fall back to the default URL. +- **Endpoint empty:** Verify the Model Runner is running with `docker model status --json`. +- **Performance:** Use `runtime_flags` to tune GPU layers (`--ngl`) and thread count (`--threads`). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md new file mode 100644 index 000000000000..9644653071f8 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md @@ -0,0 +1,102 @@ +--- +title: "Fireworks AI" +description: "Use Fireworks AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, fireworks ai +weight: 100 +canonical: https://docs.docker.com/ai/docker-agent/providers/fireworks/ +--- + +_Use Fireworks AI models with Docker Agent._ + +## Overview + +[Fireworks AI](https://fireworks.ai/) is a fast inference host for open-weight +models, serving Kimi K2, Llama, Qwen, DeepSeek, GLM and others through an +OpenAI-compatible API. Docker Agent includes built-in support for Fireworks AI +as an alias provider. + +## Setup + +1. Create an API key from the [Fireworks dashboard](https://fireworks.ai/account/api-keys). +2. Set the environment variable: + + ```bash + export FIREWORKS_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Fireworks AI: + +```yaml +agents: + root: + model: fireworks/accounts/fireworks/models/kimi-k2-instruct + description: Assistant using Fireworks AI + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + fireworks_model: + provider: fireworks + model: accounts/fireworks/models/kimi-k2-instruct + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: fireworks_model + description: Assistant using Fireworks AI + instruction: You are a helpful assistant. +``` + +## Available Models + +Fireworks serves a broad, changing catalog of open-weight models. Model IDs use +the `accounts/fireworks/models/<name>` form. Check the +[Fireworks model library](https://fireworks.ai/models) for current IDs, context +limits, and pricing. + +| Model | Description | +| --- | --- | +| `accounts/fireworks/models/kimi-k2-instruct` | Kimi K2, large open MoE chat and tool-calling model | +| `accounts/fireworks/models/llama-v3p3-70b-instruct` | Llama 3.3 70B instruct | +| `accounts/fireworks/models/qwen3-235b-a22b` | Qwen 3 235B MoE | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +Fireworks AI is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.fireworks.ai/inference/v1` +- **Token Variable:** `FIREWORKS_API_KEY` + +Because Fireworks fronts open-weight models whose chat templates may reject more +than one leading system message, Docker Agent coalesces its per-source system +messages into a single one for this provider. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: fireworks/accounts/fireworks/models/kimi-k2-instruct + description: Code assistant using Kimi K2 on Fireworks AI + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md new file mode 100644 index 000000000000..3e4e7c3cd3e5 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md @@ -0,0 +1,161 @@ +--- +title: "GitHub Copilot" +description: "Use GitHub Copilot's hosted models (GPT-4o, Claude, Gemini, and more) with Docker Agent through your GitHub subscription." +keywords: docker agent, ai agents, model providers, llm, github copilot +weight: 110 +canonical: https://docs.docker.com/ai/docker-agent/providers/github-copilot/ +--- + +_Use GitHub Copilot's hosted models with Docker Agent through your existing GitHub subscription._ + +## Overview + +GitHub Copilot exposes an OpenAI-compatible Chat Completions API at +`https://api.githubcopilot.com`. Docker Agent ships with built-in support for +it as the `github-copilot` provider, so any user with a paid GitHub Copilot +subscription can reuse their entitlement from Docker Agent. + +## Prerequisites + +- An active **GitHub Copilot** subscription (Individual, Business, or Enterprise). +- A **personal access token** with the `copilot` scope, exported as `GITHUB_TOKEN`. + +```bash +export GITHUB_TOKEN="ghp_..." +``` + +## Running Evals + +Eval cases (`docker agent eval`) run in isolated containers. Unlike dedicated +provider API keys, `GITHUB_TOKEN` and `GH_TOKEN` are **not** forwarded into +eval containers automatically, because a GitHub token grants far broader +access than a model API key. Pass the token explicitly: + +```bash +docker agent eval agent.yaml ./evals -e GITHUB_TOKEN +``` + +See [Evaluation](../../features/evaluation/index.md#provider-credentials) +for details, including behavior with `--env-from-file`. + +## Configuration + +### Inline + +```yaml +agents: + root: + model: github-copilot/gpt-4o + instruction: You are a helpful assistant. +``` + +### Named model + +```yaml +models: + copilot: + provider: github-copilot + model: gpt-4o + temperature: 0.7 + max_tokens: 4000 + +agents: + root: + model: copilot +``` + +## Available Models + +The exact set of models you can call depends on your Copilot plan. The most +commonly available ones today are: + +| Model | Best For | +| ------------------------ | ----------------------------------- | +| `gpt-4o` | Multimodal, balanced performance | +| `gpt-4o-mini` | Fast and cheap | +| `claude-sonnet-4` | Strong coding and analysis | +| `gemini-2.5-pro` | Google's flagship, large context | +| `o3-mini` | Reasoning-focused | + +Check the +[GitHub Copilot documentation](https://docs.github.com/en/copilot) +for the current model list. + +## `Copilot-Integration-Id` Header + +GitHub's Copilot API rejects requests that don't carry a +`Copilot-Integration-Id` header with a `Bad Request` error. Docker Agent +automatically sends `copilot-developer-cli` for the `github-copilot` +provider, so PAT-based usage works out of the box. + +We specifically chose `copilot-developer-cli` (instead of, say, +`vscode-chat`) because it is the integration id accepted by the Copilot +API for **both** OAuth tokens and Personal Access Tokens. Most +Docker Agent users authenticate with a PAT exported as `GITHUB_TOKEN`, +and `vscode-chat` is rejected for those tokens. + +If you need to send a different integration id — for example if your +organization allows-lists a specific value — you can override it via +`provider_opts.http_headers`: + +```yaml +models: + copilot: + provider: github-copilot + model: gpt-4o + provider_opts: + http_headers: + Copilot-Integration-Id: my-custom-integration +``` + +Header names are matched case-insensitively, so `copilot-integration-id` +works too. + +## Chat Completions vs. Responses API + +GitHub Copilot proxies OpenAI models behind two endpoints: the legacy +`/chat/completions` and the newer `/responses`. Newer models (the `gpt-5` +family, Codex variants, etc.) are only served via `/responses` and reject +`/chat/completions` with a `400 Bad Request`. Docker Agent auto-selects the +right endpoint per model, so no configuration is needed in the common case. + +If you ever need to force one or the other, set `api_type` explicitly: + +```yaml +models: + copilot: + provider: github-copilot + model: gpt-5 + provider_opts: + api_type: openai_responses # or openai_chatcompletions +``` + +## Custom HTTP Headers + +`provider_opts.http_headers` is a generic escape hatch that works for any +OpenAI-compatible provider, not just GitHub Copilot. Every key/value pair +is added to every outgoing request: + +```yaml +models: + my_model: + provider: openai + model: gpt-4o + provider_opts: + http_headers: + X-Request-Source: docker-agent + X-Tenant-Id: my-team +``` + +## How It Works + +GitHub Copilot is implemented as a built-in alias in Docker Agent: + +- **API type:** OpenAI-compatible (Chat Completions) +- **Base URL:** `https://api.githubcopilot.com` +- **Token variable:** `GITHUB_TOKEN` +- **Default headers:** `Copilot-Integration-Id: copilot-developer-cli` + +This means the same client as OpenAI is used, so every OpenAI feature +supported by Docker Agent (tool calling, structured output, multimodal +inputs, etc.) is available when the underlying model supports it. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md new file mode 100644 index 000000000000..efbb27817169 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md @@ -0,0 +1,174 @@ +--- +title: "Google Gemini" +description: "Use Gemini 2.5 Flash, Gemini 3 Pro, and other Google models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, google gemini +weight: 120 +canonical: https://docs.docker.com/ai/docker-agent/providers/google/ +--- + +_Use Gemini 2.5 Flash, Gemini 3 Pro, and other Google models with Docker Agent._ + +## Setup + +Docker Agent reads the first credential it finds from these environment variables (see `pkg/model/provider/gemini/client.go`): + +| Variable | Purpose | +| --------------------------- | ----------------------------------------------------------------------------------- | +| `GOOGLE_API_KEY` | Primary Gemini API key. | +| `GEMINI_API_KEY` | Alternative name for the Gemini API key (also used by the official Google SDK). | +| `GOOGLE_GENAI_USE_VERTEXAI` | When set (any value), routes through Vertex AI instead of the Gemini Developer API. | +| `GOOGLE_CLOUD_PROJECT` | GCP project used when `GOOGLE_GENAI_USE_VERTEXAI` is set or for Vertex AI Model Garden. | +| `GOOGLE_CLOUD_LOCATION` | GCP region for Vertex AI (defaults to the SDK default). | + +```bash +# Gemini Developer API +export GOOGLE_API_KEY="AI..." # or GEMINI_API_KEY + +# Vertex AI (no API key; uses Application Default Credentials) +gcloud auth application-default login +export GOOGLE_GENAI_USE_VERTEXAI=1 +export GOOGLE_CLOUD_PROJECT="my-gcp-project" +export GOOGLE_CLOUD_LOCATION="us-central1" +``` + +## Configuration + +### Inline + +```yaml +agents: + root: + model: google/gemini-3.5-flash +``` + +### Named Model + +```yaml +models: + gemini: + provider: google + model: gemini-3.5-flash + temperature: 0.5 +``` + +## Available Models + +| Model | Best For | +| ------------------ | ------------------------------- | +| `gemini-3-pro` | Most capable Gemini model | +| `gemini-3-flash` | Fast, efficient, good balance | +| `gemini-2.5-flash` | Fast inference, cost-effective | +| `gemini-2.5-pro` | Strong reasoning, large context | + +## Thinking Budget + +Gemini supports two approaches depending on the model version: + +> [!WARNING] +> **Different thinking formats** +> +> Gemini 2.5 uses **token-based** budgets (integers). Gemini 3 uses **level-based** budgets (strings like `low`, `high`). Make sure you use the right format for your model version. + +### Gemini 2.5 (Token-based) + +```yaml +models: + gemini-no-thinking: + provider: google + model: gemini-2.5-flash + thinking_budget: 0 # disable thinking + + gemini-dynamic: + provider: google + model: gemini-2.5-flash + thinking_budget: -1 # dynamic (model decides) — default + + gemini-fixed: + provider: google + model: gemini-2.5-flash + thinking_budget: 8192 # fixed token budget +``` + +### Gemini 3 (Level-based) + +```yaml +models: + gemini-3-pro: + provider: google + model: gemini-3-pro + thinking_budget: high # default for Pro: low | high + + gemini-3-flash: + provider: google + model: gemini-3-flash + thinking_budget: medium # default for Flash: minimal | low | medium | high +``` + +## Built-in Tools (Grounding) + +Gemini models support built-in tools that let the model access Google Search and Google Maps +directly during generation. Enable them via `provider_opts`: + +```yaml +models: + gemini-grounded: + provider: google + model: gemini-2.5-flash + provider_opts: + google_search: true + google_maps: true + code_execution: true +``` + +| Option | Description | +| ---------------- | ---------------------------------------------------- | +| `google_search` | Enables Google Search grounding for up-to-date info | +| `google_maps` | Enables Google Maps grounding for location queries | +| `code_execution` | Enables server-side code execution for computations | + +## Vertex AI Model Garden + +You can use non-Gemini models (e.g. Claude, Llama) hosted on Google Cloud's +[Vertex AI Model Garden](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models) +through the `google` provider. When a `publisher` is specified in `provider_opts`, +requests are routed through the appropriate Vertex AI endpoint instead of the +Gemini SDK: + +- **Anthropic Claude** (`publisher: anthropic`) uses the Anthropic-native + `:rawPredict` / `:streamRawPredict` endpoints. Claude models on Vertex AI do + not support the OpenAI `/chat/completions` path. +- **Other publishers** (e.g. `meta`, `mistral`) use Vertex AI's + OpenAI-compatible `/chat/completions` endpoint. + +### Authentication + +Vertex AI uses Google Cloud Application Default Credentials (ADC). Make sure you +are authenticated: + +```bash +gcloud auth application-default login +``` + +### Configuration + +```yaml +models: + claude-on-vertex: + provider: google + model: claude-sonnet-4-20250514 + provider_opts: + project: my-gcp-project # GCP project ID (or set GOOGLE_CLOUD_PROJECT) + location: us-east5 # GCP region (or set GOOGLE_CLOUD_LOCATION) + publisher: anthropic # Model publisher (anthropic, meta, etc.) +``` + +| Option | Description | +| ----------- | ------------------------------------------------------------------------------------ | +| `project` | GCP project ID. Falls back to `GOOGLE_CLOUD_PROJECT` env var | +| `location` | GCP region (e.g. `us-east5`, `us-central1`). Falls back to `GOOGLE_CLOUD_LOCATION` | +| `publisher` | Model publisher (e.g. `anthropic`, `meta`, `mistral`). Must not be `google` | + +> [!NOTE] +> **Gemini models on Vertex AI** +> +> Setting `publisher: google` (or omitting `publisher`) uses the native Gemini SDK path. The Model Garden endpoint is only used for non-Google publishers. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md new file mode 100644 index 000000000000..4c7d3945581c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md @@ -0,0 +1,99 @@ +--- +title: "Groq" +description: "Use Groq fast-inference models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, groq +weight: 130 +canonical: https://docs.docker.com/ai/docker-agent/providers/groq/ +--- + +_Use Groq models with Docker Agent._ + +## Overview + +[Groq](https://groq.com/) serves open-weight models on its LPU inference engine +through an OpenAI-compatible API, with a focus on very low latency. Docker Agent +includes built-in support for Groq as an alias provider. + +## Setup + +1. Create an API key from the [Groq Console](https://console.groq.com/keys). +2. Set the environment variable: + + ```bash + export GROQ_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Groq: + +```yaml +agents: + root: + model: groq/llama-3.3-70b-versatile + description: Assistant using Groq + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + groq_model: + provider: groq + model: llama-3.3-70b-versatile + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: groq_model + description: Assistant using Groq + instruction: You are a helpful assistant. +``` + +## Available Models + +Groq hosts a rotating catalogue of open-weight models. Check the +[Groq models documentation](https://console.groq.com/docs/models) for current +model IDs, context limits, and rate limits. + +| Model | Description | +| --- | --- | +| `llama-3.3-70b-versatile` | Llama 3.3 70B, reliable general-purpose chat and tool calling | +| `llama-3.1-8b-instant` | Llama 3.1 8B, fastest and cheapest | +| `openai/gpt-oss-120b` | GPT-OSS 120B, strong reasoning and tool calling | +| `openai/gpt-oss-20b` | GPT-OSS 20B, compact reasoning model | +| `qwen/qwen3-32b` | Qwen3 32B, reasoning and tool calling | +| `meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout MoE | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +Groq is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.groq.com/openai/v1` +- **Token Variable:** `GROQ_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: groq/llama-3.3-70b-versatile + description: Code assistant using Llama 3.3 + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md new file mode 100644 index 000000000000..8b5860100a71 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md @@ -0,0 +1,101 @@ +--- +title: "Hugging Face" +description: "Use Hugging Face Inference Providers with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, hugging face +weight: 140 +canonical: https://docs.docker.com/ai/docker-agent/providers/huggingface/ +--- + +_Use Hugging Face Inference Providers with Docker Agent._ + +## Overview + +[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index) +routes requests to open models (Llama, Qwen, DeepSeek, Kimi, GLM and others) +across many backends through a single OpenAI-compatible endpoint. Docker Agent +includes built-in support for Hugging Face as an alias provider. + +## Setup + +1. Create a token from the [Hugging Face token settings](https://huggingface.co/settings/tokens). +2. Set the environment variable: + + ```bash + export HF_TOKEN=your-token + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Hugging Face: + +```yaml +agents: + root: + model: huggingface/meta-llama/Llama-3.3-70B-Instruct + description: Assistant using Hugging Face Inference Providers + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + huggingface_model: + provider: huggingface + model: meta-llama/Llama-3.3-70B-Instruct + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: huggingface_model + description: Assistant using Hugging Face Inference Providers + instruction: You are a helpful assistant. +``` + +## Available Models + +Hugging Face routes to a broad, changing catalog of open-weight models. Check the +[Hugging Face models page](https://huggingface.co/models?inference_provider=all) +for current model IDs, context limits, and pricing. + +| Model | Description | +| --- | --- | +| `meta-llama/Llama-3.3-70B-Instruct` | Llama 3.3 70B, general-purpose chat and tool calling | +| `Qwen/Qwen3-235B-A22B` | Qwen3 235B mixture-of-experts instruct model | +| `deepseek-ai/DeepSeek-V3.2` | DeepSeek, strong coding and reasoning | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +Hugging Face is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://router.huggingface.co/v1` +- **Token Variable:** `HF_TOKEN` + +Because Hugging Face fronts open-weight models whose chat templates may reject +more than one leading system message, Docker Agent coalesces its per-source +system messages into a single one for this provider. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct + description: Code assistant using Qwen3 Coder on Hugging Face + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md new file mode 100644 index 000000000000..c4122a108cdd --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md @@ -0,0 +1,223 @@ +--- +title: "Local Models (Ollama, vLLM, LocalAI)" +description: "Run Docker Agent with locally hosted models for privacy, offline use, or cost savings." +keywords: docker agent, ai agents, model providers, llm, local models, ollama, vllm, localai, offline models +linkTitle: "Local Models" +weight: 150 +canonical: https://docs.docker.com/ai/docker-agent/providers/local/ +aliases: + - /ai/docker-agent/local-models/ + - /ai/docker-agent/providers/ollama/ +--- + +_Run Docker Agent with locally hosted models for privacy, offline use, or cost savings._ + +## Overview + +Docker Agent can connect to any OpenAI-compatible local model server. This guide covers the most popular options: + +- **Ollama** — Easy-to-use local model runner +- **vLLM** — High-performance inference server +- **LocalAI** — OpenAI-compatible API for various backends + +> [!TIP] +> **Docker Model Runner** +> +> For the easiest local model experience, consider [Docker Model Runner](../dmr/index.md) which is built into Docker Desktop and requires no additional setup. + +## Ollama + +Ollama is a popular tool for running LLMs locally. Docker Agent includes a built-in `ollama` alias for easy configuration. + +### Setup + +1. Install Ollama from [ollama.ai](https://ollama.ai/) +2. Pull a model: + + ```bash + ollama pull llama3.2 + ollama pull qwen2.5-coder + ``` + +3. Start the Ollama server (usually runs automatically): + + ```bash + ollama serve + ``` + +### Configuration + +Use the built-in `ollama` alias: + +```yaml +agents: + root: + model: ollama/llama3.2 + description: Local assistant + instruction: You are a helpful assistant. +``` + +The `ollama` alias automatically uses: + +- **Base URL:** `http://localhost:11434/v1` +- **API Type:** OpenAI-compatible +- **No API key required** + +### Custom Port or Host + +If Ollama runs on a different host or port: + +```yaml +models: + my_ollama: + provider: ollama + model: llama3.2 + base_url: http://192.168.1.100:11434/v1 + +agents: + root: + model: my_ollama + description: Remote Ollama assistant + instruction: You are a helpful assistant. +``` + +### Popular Ollama Models + +| Model | Size | Best For | +| ---------------- | ---- | --------------------- | +| `llama3.2` | 3B | General purpose, fast | +| `llama3.1` | 8B | Better reasoning | +| `qwen2.5-coder` | 7B | Code generation | +| `mistral` | 7B | General purpose | +| `codellama` | 7B | Code tasks | +| `deepseek-coder` | 6.7B | Code generation | + +## vLLM + +vLLM is a high-performance inference server optimized for throughput. + +### Setup + +```bash +# Install vLLM +pip install vllm + +# Start the server +python -m vllm.entrypoints.openai.api_server \ + --model meta-llama/Llama-3.2-3B-Instruct \ + --port 8000 +``` + +### Configuration + +```yaml +providers: + vllm: + api_type: openai_chatcompletions + base_url: http://localhost:8000/v1 + +agents: + root: + model: vllm/meta-llama/Llama-3.2-3B-Instruct + description: vLLM-powered assistant + instruction: You are a helpful assistant. +``` + +## LocalAI + +LocalAI provides an OpenAI-compatible API that works with various backends. + +### Setup + +```bash +# Run with Docker +docker run -p 8080:8080 --name local-ai \ + -v ./models:/models \ + localai/localai:latest-cpu +``` + +### Configuration + +```yaml +providers: + localai: + api_type: openai_chatcompletions + base_url: http://localhost:8080/v1 + +agents: + root: + model: localai/gpt4all-j + description: LocalAI assistant + instruction: You are a helpful assistant. +``` + +## Generic Custom Provider + +For any OpenAI-compatible server: + +```yaml +providers: + my_server: + api_type: openai_chatcompletions + base_url: http://localhost:8000/v1 + # token_key: MY_API_KEY # if auth required + +agents: + root: + model: my_server/model-name + description: Custom server assistant + instruction: You are a helpful assistant. +``` + +## Performance Tips + +> [!NOTE] +> **Local Model Considerations** +> +> - **Memory:** Larger models need more RAM/VRAM. A 7B model typically needs 8-16GB RAM. +> - **GPU:** GPU acceleration dramatically improves speed. Check your server's GPU support. +> - **Context length:** Local models often have smaller context windows than cloud models. +> - **Tool calling:** Not all local models support function/tool calling. Test your model's capabilities. + +## Example: Offline Development Agent + +```yaml +agents: + developer: + model: ollama/qwen2.5-coder + description: Offline code assistant + instruction: | + You are a software developer working offline. + Focus on code quality and clear explanations. + max_iterations: 20 + toolsets: + - type: filesystem + - type: shell + - type: think + - type: todo +``` + +## Troubleshooting + +### Connection Refused + +Ensure your model server is running and accessible: + +```bash +curl http://localhost:11434/v1/models # Ollama +curl http://localhost:8000/v1/models # vLLM +``` + +### Model Not Found + +Verify the model is downloaded/available: + +```bash +ollama list # List available Ollama models +``` + +### Slow Responses + +- Check if GPU acceleration is enabled +- Try a smaller model +- Reduce `max_tokens` in your config diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md new file mode 100644 index 000000000000..e6eeac606e38 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md @@ -0,0 +1,92 @@ +--- +title: "MiniMax" +description: "Use MiniMax AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, minimax +weight: 160 +canonical: https://docs.docker.com/ai/docker-agent/providers/minimax/ +--- + +_Use MiniMax AI models with Docker Agent._ + +## Overview + +MiniMax provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for MiniMax as an alias provider. + +## Setup + +1. Get an API key from [MiniMax](https://www.minimaxi.com/) +2. Set the environment variable: + + ```bash + export MINIMAX_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use MiniMax: + +```yaml +agents: + root: + model: minimax/MiniMax-M2.5 + description: Assistant using MiniMax + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + minimax_model: + provider: minimax + model: MiniMax-M2.5 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: minimax_model + description: Assistant using MiniMax + instruction: You are a helpful assistant. +``` + +## Available Models + +Check the [MiniMax documentation](https://www.minimaxi.com/document/introduction) for the current model catalog. + +| Model | Description | +| ------------------------ | ----------------------------------------------- | +| `MiniMax-M2.5` | Peak performance, 204K context | +| `MiniMax-M2.5-highspeed` | Same as M2.5 but faster (~100 tps) | +| `MiniMax-M2.1` | Multi-language programming capabilities | +| `MiniMax-M2.1-highspeed` | Faster variant of M2.1 (~100 tps) | +| `MiniMax-M2` | Agentic capabilities, advanced reasoning | + +## How It Works + +MiniMax is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai`) +- **Base URL:** `https://api.minimax.io/v1` +- **Token Variable:** `MINIMAX_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: minimax/MiniMax-M2.5 + description: Code assistant using MiniMax + instruction: | + You are an expert programmer using MiniMax M2.5. + Write clean, well-documented code. + Follow best practices for the language being used. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md new file mode 100644 index 000000000000..7e40916d53c6 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md @@ -0,0 +1,106 @@ +--- +title: "Mistral" +description: "Use Mistral AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, mistral +weight: 170 +canonical: https://docs.docker.com/ai/docker-agent/providers/mistral/ +--- + +_Use Mistral AI models with Docker Agent._ + +## Overview + +Mistral AI provides powerful language models through an OpenAI-compatible API. Docker Agent includes built-in support for Mistral as an alias provider. + +## Setup + +1. Get an API key from [Mistral Console](https://console.mistral.ai/) +2. Set the environment variable: + + ```bash + export MISTRAL_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Mistral: + +```yaml +agents: + root: + model: mistral/mistral-large-latest + description: Assistant using Mistral + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + mistral: + provider: mistral + model: mistral-large-latest + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: mistral + description: Assistant using Mistral + instruction: You are a helpful assistant. +``` + +## Available Models + +| Model | Description | Context | +| ----------------------- | --------------------------------- | ------- | +| `mistral-large-latest` | Most capable Mistral model | 128K | +| `mistral-medium-latest` | Balanced performance and cost | 128K | +| `mistral-small-latest` | Fast and cost-effective (default) | 128K | +| `codestral-latest` | Optimized for code generation | 32K | +| `open-mistral-nemo` | Open-weight model | 128K | +| `ministral-8b-latest` | Compact 8B parameter model | 128K | +| `ministral-3b-latest` | Smallest Mistral model | 128K | + +Check the [Mistral Models documentation](https://docs.mistral.ai/getting-started/models/) for the latest available models. + +## Auto-Detection + +When you run `docker agent run` without specifying a config and no project-level `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` exists, Docker Agent automatically detects available providers. If `MISTRAL_API_KEY` is set and higher-priority providers (OpenAI, Anthropic, Google) are not available, Mistral will be used with `mistral-small-latest` as the default model. + +## Extended Thinking + +Docker Agent's `thinking_budget` field is **not applied** to Mistral models: the underlying OpenAI-compatible client only sends `reasoning_effort` for OpenAI reasoning model names (o-series, gpt-5). Setting `thinking_budget` on a Mistral model passes config validation but has no effect on the request. + +Mistral reasoning models (e.g. `magistral`) reason on their own without configuration. For non-reasoning models, use the [think tool](../../tools/think/index.md) instead. + +## How It Works + +Mistral is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.mistral.ai/v1` +- **Token Variable:** `MISTRAL_API_KEY` + +This means Mistral uses the same client as OpenAI, making it fully compatible with all OpenAI features supported by Docker Agent. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: mistral/codestral-latest + description: Expert code assistant + instruction: | + You are an expert programmer using Codestral. + Write clean, efficient, well-documented code. + Explain your reasoning when helpful. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md new file mode 100644 index 000000000000..f370592b492d --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md @@ -0,0 +1,97 @@ +--- +title: "Moonshot AI" +description: "Use Moonshot AI (Kimi) models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, moonshot ai +weight: 180 +canonical: https://docs.docker.com/ai/docker-agent/providers/moonshot/ +--- + +_Use Moonshot AI (Kimi) models with Docker Agent._ + +## Overview + +[Moonshot AI](https://www.moonshot.ai/) serves its Kimi model family through an +OpenAI-compatible API. The Kimi K2 models have strong momentum for coding and +agentic tasks. Docker Agent includes built-in support for Moonshot AI as an +alias provider. + +## Setup + +1. Create an API key from the [Moonshot AI console](https://platform.moonshot.ai/console/api-keys). +2. Set the environment variable: + + ```bash + export MOONSHOT_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Moonshot AI: + +```yaml +agents: + root: + model: moonshot/kimi-k2-0905-preview + description: Assistant using Moonshot AI + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + moonshot_model: + provider: moonshot + model: kimi-k2-0905-preview + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: moonshot_model + description: Assistant using Moonshot AI + instruction: You are a helpful assistant. +``` + +## Available Models + +Moonshot AI exposes a vendor-controlled Kimi model lineup. Check the +[Moonshot API documentation](https://platform.moonshot.ai/docs/api) for current +model IDs, context limits, and pricing. + +| Model | Description | +| --- | --- | +| `kimi-k2-0905-preview` | Kimi K2, general-purpose chat, coding, and tool calling | +| `kimi-k2-turbo-preview` | Kimi K2 optimized for higher throughput | +| `kimi-k2-thinking` | Kimi K2 extended-reasoning model | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +Moonshot AI is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.moonshot.ai/v1` +- **Token Variable:** `MOONSHOT_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: moonshot/kimi-k2-0905-preview + description: Code assistant using Kimi K2 + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md new file mode 100644 index 000000000000..deadbaaea4b3 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md @@ -0,0 +1,90 @@ +--- +title: "Nebius" +description: "Use Nebius AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, nebius +weight: 190 +canonical: https://docs.docker.com/ai/docker-agent/providers/nebius/ +--- + +_Use Nebius AI models with Docker Agent._ + +## Overview + +Nebius provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Nebius as an alias provider. + +## Setup + +1. Get an API key from [Nebius AI](https://nebius.ai/) +2. Set the environment variable: + + ```bash + export NEBIUS_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Nebius: + +```yaml +agents: + root: + model: nebius/deepseek-ai/DeepSeek-V3 + description: Assistant using Nebius + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + nebius_model: + provider: nebius + model: deepseek-ai/DeepSeek-V3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: nebius_model + description: Assistant using Nebius + instruction: You are a helpful assistant. +``` + +## Available Models + +Nebius hosts various open models. Check the [Nebius documentation](https://nebius.ai/docs) for the current model catalog. + +| Model | Description | +| ----------------------------------- | ------------------------------- | +| `deepseek-ai/DeepSeek-V3` | DeepSeek V3 model | +| `Qwen/Qwen2.5-72B-Instruct` | Qwen 2.5 72B instruction-tuned | +| `meta-llama/Llama-3.3-70B-Instruct` | Llama 3.3 70B instruction-tuned | + +## How It Works + +Nebius is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.studio.nebius.com/v1` +- **Token Variable:** `NEBIUS_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: nebius/deepseek-ai/DeepSeek-V3 + description: Code assistant using DeepSeek + instruction: | + You are an expert programmer using DeepSeek V3. + Write clean, well-documented code. + Follow best practices for the language being used. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md new file mode 100644 index 000000000000..330dad99f0bd --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md @@ -0,0 +1,115 @@ +--- +title: "NVIDIA NIM" +description: "Use NVIDIA NIM models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, nvidia, nim, nemotron +weight: 290 +canonical: https://docs.docker.com/ai/docker-agent/providers/nvidia/ +--- + +_Use NVIDIA NIM models with Docker Agent._ + +## Overview + +NVIDIA provides access to Nemotron and many other open-weight models through +[build.nvidia.com](https://build.nvidia.com/) (with a free tier) via an +OpenAI-compatible API. Docker Agent includes built-in support for NVIDIA as an +alias provider. The same alias also works against a self-hosted +[NVIDIA NIM](https://docs.nvidia.com/nim/) deployment by overriding `base_url`. + +## Setup + +1. Get an API key from [build.nvidia.com](https://build.nvidia.com/) +2. Set the environment variable: + + ```bash + export NVIDIA_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use NVIDIA NIM: + +```yaml +agents: + root: + model: nvidia/nvidia/nemotron-3-super-120b-a12b + description: Assistant using NVIDIA NIM + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + nemotron: + provider: nvidia + model: nvidia/nemotron-3-super-120b-a12b + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: nemotron + description: Assistant using NVIDIA NIM + instruction: You are a helpful assistant. +``` + +## Available Models + +NVIDIA NIM hosts Nemotron alongside many other open models (Llama, Qwen, +DeepSeek, Mistral, ...). Check the [NVIDIA API catalog](https://build.nvidia.com/) +for the current model list. + +| Model | Description | +| -------------------------------------------- | ---------------------------------- | +| `nvidia/nemotron-3-super-120b-a12b` | Nemotron 3 Super, reasoning + tool calling | +| `nvidia/nemotron-3-nano-30b-a3b` | Nemotron 3 Nano, smaller/faster | +| `meta/llama-3.3-70b-instruct` | Llama 3.3 70B instruction-tuned | +| `qwen/qwen3-coder-480b-a35b-instruct` | Qwen3 Coder, code-focused | + +## On-Prem / Self-Hosted NIM + +For self-hosted NIM deployments, point `base_url` at your own endpoint instead +of the hosted `integrate.api.nvidia.com` API: + +```yaml +models: + local_nim: + provider: nvidia + model: meta/llama-3.3-70b-instruct + base_url: http://localhost:8000/v1 +``` + +## How It Works + +NVIDIA is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://integrate.api.nvidia.com/v1` +- **Token Variable:** `NVIDIA_API_KEY` + +Because NIM fronts open-weight models whose chat templates often only accept +a single system message, Docker Agent coalesces the agent instruction and any +toolset instructions into one leading system message before sending the +request. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: nvidia/nvidia/nemotron-3-super-120b-a12b + description: Code assistant using Nemotron + instruction: | + You are an expert programmer using NVIDIA Nemotron. + Write clean, well-documented code. + Follow best practices for the language being used. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md new file mode 100644 index 000000000000..abd11c54fbe8 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md @@ -0,0 +1,138 @@ +--- +title: "OpenAI" +description: "Use GPT-5.6, GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, openai +weight: 200 +canonical: https://docs.docker.com/ai/docker-agent/providers/openai/ +--- + +_Use GPT-5.6, GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with Docker Agent._ + +## Setup + +```bash +# Set your API key +export OPENAI_API_KEY="sk-..." +``` + +> [!TIP] +> No API key? A ChatGPT Plus/Pro/Business subscription can be used instead +> through the [`chatgpt` provider](../chatgpt/index.md): sign in once with +> `docker agent setup` (pick chatgpt). + +## Configuration + +### Inline + +```yaml +agents: + root: + model: openai/gpt-5.6 +``` + +### Named Model + +```yaml +models: + gpt: + provider: openai + model: gpt-5.6 + max_tokens: 4000 +``` + +## Available Models + +| Model | Best For | +| ---------------- | ----------------------------------------------------- | +| `gpt-5.6` | Alias for `gpt-5.6-sol`; tracks the flagship model | +| `gpt-5.6-sol` | Frontier model, most capable, complex reasoning | +| `gpt-5.6-terra` | Everyday workhorse; successor to the `-mini` tier | +| `gpt-5.6-luna` | High-volume, cost-efficient; successor to `-nano` tier | +| `gpt-5` | Previous-generation flagship | +| `gpt-5-mini` | Previous-generation fast, cost-effective model | +| `gpt-4o` | Multimodal, balanced performance | +| `gpt-4o-mini` | Cheapest, fast for simple tasks | + +Starting with GPT-5.6, OpenAI renamed the `-mini`/`-nano` size tiers to `-terra`/`-luna` (with `-sol` denoting the frontier tier previously left unsuffixed). + +Find more model names at [modelnames.ai](https://modelnames.ai/) or in the [official OpenAI docs](https://platform.openai.com/docs/models). + +## Thinking Budget + +OpenAI reasoning models (o-series, gpt-5, gpt-5-mini, gpt-5.6 family) support extended thinking through the `reasoning_effort` API parameter. Set `thinking_budget` to control the effort level: + +```yaml +models: + gpt-thinker: + provider: openai + model: gpt-5.6 + thinking_budget: high # none | minimal | low | medium | high | xhigh | max +``` + +**Effort levels:** + +| Level | Description | +| --------- | -------------------------------------------------------- | +| `none` | No reasoning. On `gpt-5.6`+ this is a real API value that is sent as-is; on older models it just disables the local `thinking_budget` (the API's own default still applies). | +| `minimal` | Fastest; lightest reasoning pass. Not accepted on `gpt-5.6`+ (dropped from the API). | +| `low` | Quick reasoning for straightforward tasks. | +| `medium` | Balanced default. | +| `high` | More thorough; recommended for complex tasks. | +| `xhigh` | Near-maximum effort; slower but most accurate. Requires `gpt-5.2`+. | +| `max` | Maximum effort. Requires `gpt-5.6`+ (Sol/Terra/Luna). | + +Token counts, `adaptive`, and `adaptive/<effort>` are rejected with a configuration error at request time. Older models (o1, o3-mini) only accept `low`/`medium`/`high`; `xhigh` requires `gpt-5.2`+; `none` and `max` require `gpt-5.6`+; `minimal` is not accepted on `gpt-5.6`+. + +> [!WARNING] +> **Hidden reasoning tokens** +> +> OpenAI reasoning models always produce hidden reasoning tokens that count against `max_tokens` — even with `thinking_budget: none` on older models. Docker Agent automatically raises the output-token floor for its internal low-effort calls so reasoning cannot starve visible text output. + +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for a cross-provider overview. + +> [!TIP] +> **Custom endpoints** +> +> Use `base_url` for proxies and OpenAI-compatible services. See [Custom Providers](../custom/index.md) for full setup. + +## Custom Endpoint + +Use `base_url` to connect to OpenAI-compatible APIs: + +```yaml +models: + custom: + provider: openai + model: gpt-5-mini + base_url: https://your-proxy.example.com/v1 +``` + +## WebSocket Transport + +For OpenAI Responses API models (gpt-4.1+, o-series, gpt-5), you can use WebSocket streaming instead of the default SSE (Server-Sent Events): + +```yaml +models: + fast-gpt: + provider: openai + model: gpt-4.1 + provider_opts: + transport: websocket # Use WebSocket instead of SSE +``` + +### Benefits + +- **~40% faster** for workflows with 20+ tool calls +- **Persistent connection** reduces per-turn overhead +- **Server-side caching** of connection state +- **Automatic fallback** to SSE if WebSocket fails + +### Requirements + +- Only works with Responses API models: `gpt-4.1+`, `o1`, `o3`, `o4`, `gpt-5` +- NOT compatible with the `--models-gateway` flag (automatically falls back to SSE when a gateway is configured) +- Requires `OPENAI_API_KEY` environment variable + +### Example + +See [`examples/websocket_transport.yaml`](https://github.com/docker/docker-agent/blob/main/examples/websocket_transport.yaml) for a complete example. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md new file mode 100644 index 000000000000..69199c31f557 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md @@ -0,0 +1,160 @@ +--- +title: "OpenCode Go" +description: "Use OpenCode Go models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, opencode go +weight: 210 +canonical: https://docs.docker.com/ai/docker-agent/providers/opencode-go/ +--- + +_Use OpenCode Go models with Docker Agent._ + +## Overview + +[OpenCode Go](https://opencode.ai/docs/go) is a low-cost subscription service ($5 first month, then $10/month) that provides reliable access to popular open-source coding models. It serves models through both OpenAI-compatible and Anthropic-compatible APIs from globally distributed endpoints. + +Docker Agent includes built-in support for OpenCode Go as an alias provider. + +## Setup + +1. Subscribe to OpenCode Go at [opencode.ai/auth](https://opencode.ai/auth) +2. Copy your API key from the console +3. Set the environment variable: + + ```bash + export OPENCODE_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use OpenCode Go: + +```yaml +agents: + root: + model: opencode-go/deepseek-v4-flash + description: Assistant using OpenCode Go + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + my_model: + provider: opencode-go + model: deepseek-v4-pro + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: my_model + description: Assistant using OpenCode Go + instruction: You are a helpful assistant. +``` + +## Available Models + +You can retrieve the full, up-to-date model list at any time: + +```bash +curl https://opencode.ai/zen/go/v1/models +``` + +### OpenAI-Compatible + +These models use the `/v1/chat/completions` endpoint and work directly with the `opencode-go` alias: + +| Model | Description | +| ------------------- | ------------------------------------- | +| `deepseek-v4-flash` | Fast and cost-effective DeepSeek model | +| `deepseek-v4-pro` | Most capable DeepSeek model | +| `kimi-k2.7-code` | Kimi K2.7 optimized for code | +| `kimi-k2.6` | Kimi K2.6 model | +| `kimi-k2.5` | Kimi K2.5 model | +| `glm-5.2` | GLM 5.2 flagship model | +| `glm-5.1` | GLM 5.1 model | +| `glm-5` | GLM 5 model | +| `mimo-v2.5` | MiMo V2.5 efficient model | +| `mimo-v2.5-pro` | MiMo V2.5 Pro model | +| `mimo-v2-pro` | MiMo V2 Pro model | +| `mimo-v2-omni` | MiMo V2 Omni model | +| `hy3-preview` | HY3 preview model | + +### Anthropic-Compatible + +These models use the `/v1/messages` endpoint and require a [custom provider definition](../custom/index.md): + +| Model | Description | +| ----------------- | ------------------------ | +| `minimax-m3` | MiniMax M3 model | +| `minimax-m2.7` | MiniMax M2.7 model | +| `minimax-m2.5` | MiniMax M2.5 model | +| `qwen3.7-max` | Qwen 3.7 Max model | +| `qwen3.7-plus` | Qwen 3.7 Plus model | +| `qwen3.6-plus` | Qwen 3.6 Plus model | +| `qwen3.5-plus` | Qwen 3.5 Plus model | + +To use an Anthropic-compatible model, define a custom provider: + +```yaml +providers: + opengo-ant: + provider: anthropic + base_url: https://opencode.ai/zen/go + token_key: OPENCODE_API_KEY + +models: + qwen: + provider: opengo-ant + model: qwen3.7-max + +agents: + root: + model: qwen + description: Assistant using Qwen through OpenCode Go + instruction: You are a helpful assistant. +``` + +## How It Works + +OpenCode Go is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://opencode.ai/zen/go/v1` +- **Token Variable:** `OPENCODE_API_KEY` + +This means OpenCode Go uses the same client as OpenAI, making it fully compatible with all OpenAI features supported by Docker Agent. + +For Anthropic-compatible models (MiniMax, Qwen), Docker Agent uses a custom provider pointing to the Anthropic client at `https://opencode.ai/zen/go` with the same token. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: opencode-go/deepseek-v4-flash + description: Expert code assistant + instruction: | + You are an expert programmer using DeepSeek V4 Flash. + Write clean, efficient, well-documented code. + Explain your reasoning when helpful. + toolsets: + - type: filesystem + - type: shell + - type: think +``` + +## Usage Limits + +OpenCode Go subscriptions include the following limits: + +- **5-hour rolling limit** — $12 of usage +- **Weekly limit** — $30 of usage +- **Monthly limit** — $60 of usage + +Limits are defined as dollar values. More expensive models allow fewer requests per limit period. You can also [add Zen balance](https://opencode.ai/auth) to continue usage beyond the limits. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md new file mode 100644 index 000000000000..dc765cfd43f1 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md @@ -0,0 +1,224 @@ +--- +title: "OpenCode Zen" +description: "Use OpenCode Zen models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, opencode zen +weight: 220 +canonical: https://docs.docker.com/ai/docker-agent/providers/opencode-zen/ +--- + +_Use OpenCode Zen models with Docker Agent._ + +## Overview + +[OpenCode Zen](https://opencode.ai/docs/zen) is a curated gateway of tested and verified AI models provided by the OpenCode team. It offers pay-per-use access to a wide range of models — from GPT and Claude to open-source models — all through a single API key. Several free models are also available. + +Docker Agent includes built-in support for OpenCode Zen as an alias provider for OpenAI-compatible models. Anthropic and Google models are supported via custom provider definitions. + +## Setup + +1. Sign in to [OpenCode Zen](https://opencode.ai/auth), add billing information, and copy your API key +2. Set the environment variable: + + ```bash + export OPENCODE_API_KEY=your-api-key + ``` + +3. Verify available models: + + ```bash + curl https://opencode.ai/zen/v1/models + ``` + +## Usage + +### Inline Syntax + +The simplest way to use OpenCode Zen with a free model: + +```yaml +agents: + root: + model: opencode-zen/deepseek-v4-flash-free + description: Assistant using OpenCode Zen (free) + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + zen_model: + provider: opencode-zen + model: gpt-5.5 + temperature: 0.7 + max_tokens: 16384 + +agents: + root: + model: zen_model + description: Assistant using OpenCode Zen + instruction: You are a helpful assistant. +``` + +## Available Models + +### Free Models + +These models are available at no cost: + +| Model | Description | +| ------------------------- | ---------------------------------- | +| `deepseek-v4-flash-free` | Free DeepSeek V4 Flash | +| `mimo-v2.5-free` | Free MiMo V2.5 model | +| `qwen3.6-plus-free` | Free Qwen 3.6 Plus model | +| `minimax-m3-free` | Free MiniMax M3 model | +| `nemotron-3-ultra-free` | Free Nemotron 3 Ultra model | +| `north-mini-code-free` | Free North Mini Code model | +| `big-pickle` | Free stealth model | + +### OpenAI-Compatible (Chat Completions) + +These models use the `/v1/chat/completions` endpoint and work directly with the `opencode-zen` alias: + +| Model | Description | +| --------------------- | ---------------------------------- | +| `deepseek-v4-pro` | DeepSeek V4 Pro model | +| `deepseek-v4-flash` | Fast DeepSeek V4 model | +| `glm-5.2` | GLM 5.2 model | +| `glm-5.1` | GLM 5.1 model | +| `glm-5` | GLM 5 model | +| `kimi-k2.6` | Kimi K2.6 model | +| `kimi-k2.5` | Kimi K2.5 model | +| `minimax-m2.7` | MiniMax M2.7 model | +| `minimax-m2.5` | MiniMax M2.5 model | +| `grok-build-0.1` | Grok Build 0.1 model | + +### OpenAI-Compatible (Responses API) + +These models use the `/v1/responses` endpoint and are auto-detected by Docker Agent based on the model name: + +| Model | Description | +| ---------------------- | --------------------------------- | +| `gpt-5.5` | Latest GPT model | +| `gpt-5.5-pro` | GPT 5.5 Pro, highest capability | +| `gpt-5.4` | GPT 5.4 model | +| `gpt-5.4-pro` | GPT 5.4 Pro model | +| `gpt-5.4-mini` | GPT 5.4 Mini model | +| `gpt-5.4-nano` | GPT 5.4 Nano, fastest | +| `gpt-5.3-codex` | GPT 5.3 Codex for coding | +| `gpt-5.3-codex-spark` | GPT 5.3 Codex Spark | +| `gpt-5.2` | GPT 5.2 model | +| `gpt-5.2-codex` | GPT 5.2 Codex | +| `gpt-5.1` | GPT 5.1 model | +| `gpt-5.1-codex` | GPT 5.1 Codex | +| `gpt-5.1-codex-max` | GPT 5.1 Codex Max | +| `gpt-5.1-codex-mini` | GPT 5.1 Codex Mini | +| `gpt-5` | GPT 5 model | +| `gpt-5-codex` | GPT 5 Codex | +| `gpt-5-nano` | GPT 5 Nano | + +### Anthropic-Compatible (Messages API) + +These models use the `/v1/messages` endpoint and require a [custom provider definition](../custom/index.md): + +| Model | Description | +| ----------------------- | ----------------------------- | +| `claude-fable-5` | Claude Fable 5 model | +| `claude-opus-4-8` | Claude Opus 4.8 model | +| `claude-opus-4-7` | Claude Opus 4.7 model | +| `claude-opus-4-6` | Claude Opus 4.6 model | +| `claude-opus-4-5` | Claude Opus 4.5 model | +| `claude-opus-4-1` | Claude Opus 4.1 model | +| `claude-sonnet-4-6` | Claude Sonnet 4.6 model | +| `claude-sonnet-4-5` | Claude Sonnet 4.5 model | +| `claude-sonnet-4` | Claude Sonnet 4 model | +| `claude-haiku-4-5` | Claude Haiku 4.5 model | +| `qwen3.7-max` | Qwen 3.7 Max model | +| `qwen3.7-plus` | Qwen 3.7 Plus model | +| `qwen3.6-plus` | Qwen 3.6 Plus model | +| `qwen3.5-plus` | Qwen 3.5 Plus model | + +To use an Anthropic-compatible model: + +```yaml +providers: + opencode-zen-claude: + provider: anthropic + base_url: https://opencode.ai/zen + token_key: OPENCODE_API_KEY + +models: + claude: + provider: opencode-zen-claude + model: claude-sonnet-4-5 + +agents: + root: + model: claude + description: Assistant using Claude through OpenCode Zen + instruction: You are a helpful assistant. +``` + +### Google-Compatible + +These models require a [custom provider definition](../custom/index.md) with a Google-compatible client: + +| Model | Description | +| ------------------- | ------------------------ | +| `gemini-3.5-flash` | Gemini 3.5 Flash model | +| `gemini-3.1-pro` | Gemini 3.1 Pro model | +| `gemini-3-flash` | Gemini 3 Flash model | + +To use a Google model: + +```yaml +providers: + opencode-zen-gemini: + provider: google + base_url: https://opencode.ai/zen + token_key: OPENCODE_API_KEY + +models: + gemini: + provider: opencode-zen-gemini + model: gemini-3.5-flash + +agents: + root: + model: gemini + description: Assistant using Gemini through OpenCode Zen + instruction: You are a helpful assistant. +``` + +## How It Works + +OpenCode Zen is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (auto-detects Responses API for GPT models, Chat Completions for others) +- **Base URL:** `https://opencode.ai/zen/v1` +- **Token Variable:** `OPENCODE_API_KEY` + +The same API key works for both OpenCode Go and OpenCode Zen — they are part of the same platform. Zen uses a pay-per-use billing model, while Go uses a fixed subscription. + +For Anthropic-compatible models, Docker Agent uses a custom provider pointing to the Anthropic client at `https://opencode.ai/zen` with the same token. For Google models, a custom provider points to the Google client at `https://opencode.ai/zen` (the Google SDK appends its own `/v1beta/models/...` path segment). + +### Differences from OpenCode Go + +| Aspect | OpenCode Zen | OpenCode Go | +|--------|-------------|-------------| +| Billing | Pay-per-use | $10/month subscription | +| Models | GPT-5.x, Claude, Gemini, open-source | Open-source only | +| Free models | Yes (7 models) | No | +| Base URL | `https://opencode.ai/zen/v1` | `https://opencode.ai/zen/go/v1` | + +## Usage Limits and Pricing + +OpenCode Zen uses a pay-per-use model. See the [OpenCode Zen documentation](https://opencode.ai/docs/zen) for current pricing. Automatic top-up and monthly usage limits are available from the console. + +You can retrieve the full model catalog at any time: + +```bash +curl https://opencode.ai/zen/v1/models +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md new file mode 100644 index 000000000000..b01d40211ef8 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md @@ -0,0 +1,88 @@ +--- +title: "OpenRouter" +description: "Use OpenRouter models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, openrouter +weight: 230 +canonical: https://docs.docker.com/ai/docker-agent/providers/openrouter/ +--- + +_Use OpenRouter models with Docker Agent._ + +## Overview + +OpenRouter provides access to models from many providers through an OpenAI-compatible API. Docker Agent includes built-in support for OpenRouter as an alias provider. + +## Setup + +1. Get an API key from [OpenRouter](https://openrouter.ai/settings/keys) +2. Set the environment variable: + + ```bash + export OPENROUTER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use OpenRouter: + +```yaml +agents: + root: + model: openrouter/meta-llama/llama-3.3-70b-instruct + description: Assistant using OpenRouter + instruction: You are a helpful assistant. +``` + +OpenRouter model IDs usually include the upstream provider name, such as `anthropic/claude-sonnet-4-5` or `meta-llama/llama-3.3-70b-instruct`. Docker Agent splits only the first slash, so the full upstream model ID is preserved. + +### Named Model + +For more control over parameters: + +```yaml +models: + openrouter_llama: + provider: openrouter + model: meta-llama/llama-3.3-70b-instruct + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: openrouter_llama + description: Assistant using OpenRouter + instruction: You are a helpful assistant. +``` + +## Pricing and Model Metadata + +Docker Agent fetches OpenRouter model metadata from [models.dev](https://models.dev/), including pricing per 1M input/output tokens, cache pricing when available, context limits, output limits, and modalities. This powers cost tracking and the model picker in the same way as other first-class providers. + +If models.dev is unavailable, Docker Agent falls back to its embedded catalog snapshot. + +## How It Works + +OpenRouter is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai`) +- **Base URL:** `https://openrouter.ai/api/v1` +- **Token Variable:** `OPENROUTER_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: openrouter/meta-llama/llama-3.3-70b-instruct + description: Code assistant using OpenRouter + instruction: | + You are an expert programmer. + Write clean, maintainable code. + Explain trade-offs when helpful. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md new file mode 100644 index 000000000000..662ca2a43043 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md @@ -0,0 +1,104 @@ +--- +title: "Model Providers" +description: "Docker Agent supports multiple AI model providers. Choose the right one for your use case, or use multiple providers in the same configuration." +keywords: docker agent, ai agents, model providers, llm +linkTitle: "Overview" +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/providers/overview/ +aliases: + - /ai/docker-agent/model-providers/ +--- + +_Docker Agent supports multiple AI model providers. Choose the right one for your use case, or use multiple providers in the same configuration._ + +## Supported Providers + +- [**OpenAI**](../openai/index.md) — GPT-5, GPT-5-mini, GPT-4o. The most widely used AI models. +- [**Anthropic**](../anthropic/index.md) — Claude Sonnet 4.5, Claude Opus 4.7. Excellent for coding and analysis. +- [**Google Gemini**](../google/index.md) — Gemini 2.5 Flash, Gemini 3 Pro. Fast and cost-effective. +- [**AWS Bedrock**](../bedrock/index.md) — access Claude, Nova, Llama, and more through AWS infrastructure. +- [**Docker Model Runner**](../dmr/index.md) — run models locally with Docker. No API keys, no costs. +- [**Local Models**](../local/index.md) — run Ollama, vLLM, or LocalAI locally. No API key required. +- [**Provider Definitions**](../custom/index.md) — define reusable provider configurations with shared defaults for any provider type. + +## Quick Comparison + +| Provider | Key | Local? | Strengths | +| ------------------- | ---------------- | ------ | ----------------------------------------------------- | +| OpenAI | `openai` | No | Broad model selection, tool calling, multimodal | +| Anthropic | `anthropic` | No | Strong coding, extended thinking, large context | +| Google | `google` | No | Fast inference, competitive pricing, multimodal | +| AWS Bedrock | `amazon-bedrock` | No | Enterprise features, multiple models, AWS integration | +| Docker Model Runner | `dmr` | Yes | No API costs, data privacy, offline capable | +| Local Models (Ollama / vLLM) | `ollama` / custom | Yes | No API costs, full data privacy, any OpenAI-compatible server | + +## Additional Built-in Providers + +Docker Agent also includes built-in aliases for these providers: + +| Provider | Alias | API Key / Env Variable | +| -------------- | ---------------- | ----------------------------------- | +| ChatGPT (OpenAI account) | [`chatgpt`](../chatgpt/index.md) | None (sign in via `docker agent setup`) | +| OpenCode Zen | `opencode-zen` | `OPENCODE_API_KEY` | +| OpenCode Go | `opencode-go` | `OPENCODE_API_KEY` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | +| xAI (Grok) | `xai` | `XAI_API_KEY` | +| Nebius | `nebius` | `NEBIUS_API_KEY` | +| NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` | +| MiniMax | `minimax` | `MINIMAX_API_KEY` | +| Baseten | `baseten` | `BASETEN_API_KEY` | +| OVHcloud | `ovhcloud` | `OVH_AI_ENDPOINTS_ACCESS_TOKEN` | +| Groq | `groq` | `GROQ_API_KEY` | +| Fireworks AI | `fireworks` | `FIREWORKS_API_KEY` | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | +| Together AI | `together` | `TOGETHER_API_KEY` | +| Hugging Face | `huggingface` | `HF_TOKEN` | +| Cloudflare Workers AI | `cloudflare-workers-ai` | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` | +| Moonshot AI | `moonshot` | `MOONSHOT_API_KEY` | +| Vercel AI Gateway | `vercel` | `AI_GATEWAY_API_KEY` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID` | +| Requesty | `requesty` | `REQUESTY_API_KEY` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | +| Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` | +| [Ollama](../local/index.md) | `ollama` | None (local; optional `base_url`) | +| GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` (PAT with `copilot` scope) | + +```bash +# Use built-in providers inline +agents: + root: + model: mistral/mistral-large-latest +``` + +> [!TIP] +> **Multi-provider teams** +> +> Use expensive models for complex reasoning and cheaper/local models for routine tasks. See the example below. + +## Using Multiple Providers + +Different agents can use different providers in the same configuration: + +```yaml +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + gpt: + provider: openai + model: gpt-5 + local: + provider: dmr + model: ai/qwen3 + +agents: + root: + model: claude # coordinator uses Claude + sub_agents: [coder, helper] + coder: + model: gpt # coder uses GPT-5 + helper: + model: local # helper runs locally for free +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md new file mode 100644 index 000000000000..53298c8d57ac --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md @@ -0,0 +1,108 @@ +--- +title: "OVHcloud" +description: "Use OVHcloud AI Endpoints models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, ovhcloud +weight: 240 +canonical: https://docs.docker.com/ai/docker-agent/providers/ovhcloud/ +--- + +_Use OVHcloud AI Endpoints models with Docker Agent._ + +## Overview + +[OVHcloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) serves open-weight +models through an OpenAI-compatible API, hosted in the EU. Docker Agent includes +built-in support for OVHcloud as an alias provider. + +## Setup + +1. Create an access token from the + [OVHcloud AI Endpoints portal](https://endpoints.ai.cloud.ovh.net/). +2. Set the environment variable: + + ```bash + export OVH_AI_ENDPOINTS_ACCESS_TOKEN=your-access-token + ``` + +## Usage + +### Inline Syntax + +```yaml +agents: + root: + model: ovhcloud/Qwen3.5-397B-A17B + description: Assistant using OVHcloud + instruction: You are a helpful assistant. +``` + +### Named Model + +```yaml +models: + ovhcloud_model: + provider: ovhcloud + model: Qwen3.5-397B-A17B + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: ovhcloud_model + description: Assistant using OVHcloud + instruction: You are a helpful assistant. +``` + +## Available Models + +OVHcloud hosts a rotating catalogue of open-weight models. Check the +[AI Endpoints catalogue](https://endpoints.ai.cloud.ovh.net/) for current model +IDs, context limits, and free-tier availability. + +| Model | Description | +| --- | --- | +| `Qwen3.5-397B-A17B` | Large Qwen3.5 MoE — strong general, coding, and reasoning | +| `Qwen3-32B` | Mid-size Qwen3 — fast, tool-calling, reasoning | +| `Qwen3.6-27B` | Compact Qwen3.6 — fast and efficient | +| `Qwen3.5-9B` | Small Qwen3.5 — lightweight, free-tier friendly | +| `Qwen3-Coder-30B-A3B-Instruct` | Qwen3 Coder MoE — optimised for code generation | +| `Meta-Llama-3_3-70B-Instruct` | Llama 3.3 70B — reliable general-purpose chat | +| `Mistral-Small-3.2-24B-Instruct-2506` | Compact, fast, tool-calling | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +OVHcloud is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` +- **Token Variable:** `OVH_AI_ENDPOINTS_ACCESS_TOKEN` + +Docker Agent automatically coalesces consecutive system messages into one for +OVHcloud, because some OVHcloud models return an empty stream when a request +carries more than one system message. + +## Free tier + +OVHcloud offers rate-limited free access to several models. Under heavy +rate-limiting the endpoint may return an empty response; Docker Agent surfaces +this as a warning rather than failing. For sustained use, an access token with a +paid plan avoids the free-tier request-rate cap. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: ovhcloud/Qwen3.5-397B-A17B + description: Code assistant using Qwen3.5 + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md new file mode 100644 index 000000000000..8dda71006171 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md @@ -0,0 +1,101 @@ +--- +title: "Together AI" +description: "Use Together AI models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, together ai +weight: 250 +canonical: https://docs.docker.com/ai/docker-agent/providers/together/ +--- + +_Use Together AI models with Docker Agent._ + +## Overview + +[Together AI](https://www.together.ai/) is one of the largest hosts of open +models, serving Llama, Qwen, DeepSeek, Kimi, GLM and others through an +OpenAI-compatible API. Docker Agent includes built-in support for Together AI as +an alias provider. + +## Setup + +1. Create an API key from the [Together AI settings](https://api.together.ai/settings/api-keys). +2. Set the environment variable: + + ```bash + export TOGETHER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use Together AI: + +```yaml +agents: + root: + model: together/meta-llama/Llama-3.3-70B-Instruct-Turbo + description: Assistant using Together AI + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + together_model: + provider: together + model: meta-llama/Llama-3.3-70B-Instruct-Turbo + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: together_model + description: Assistant using Together AI + instruction: You are a helpful assistant. +``` + +## Available Models + +Together AI serves a broad, changing catalog of open-weight models. Check the +[Together AI model library](https://docs.together.ai/docs/serverless-models) for +current model IDs, context limits, and pricing. + +| Model | Description | +| --- | --- | +| `meta-llama/Llama-3.3-70B-Instruct-Turbo` | Llama 3.3 70B, general-purpose chat and tool calling | +| `Qwen/Qwen3-235B-A22B-Instruct-2507-tput` | Qwen3 235B mixture-of-experts instruct model | +| `deepseek-ai/DeepSeek-V3` | DeepSeek-V3, strong coding and reasoning | + +> Model IDs are case-sensitive and must be passed exactly as the catalogue lists +> them. + +## How It Works + +Together AI is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.together.xyz/v1` +- **Token Variable:** `TOGETHER_API_KEY` + +Because Together AI fronts open-weight models whose chat templates may reject +more than one leading system message, Docker Agent coalesces its per-source +system messages into a single one for this provider. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: together/Qwen/Qwen3-235B-A22B-Instruct-2507-tput + description: Code assistant using Qwen3 on Together AI + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md new file mode 100644 index 000000000000..f2278690bb23 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md @@ -0,0 +1,109 @@ +--- +title: "Vercel AI Gateway" +description: "Use Vercel AI Gateway models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, vercel ai gateway +weight: 260 +canonical: https://docs.docker.com/ai/docker-agent/providers/vercel/ +--- + +_Use Vercel AI Gateway models with Docker Agent._ + +## Overview + +[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) is a single, unified +OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, Google, +xAI and more at list price with no markup, plus provider routing and failover. +It lets you reach many providers with one API key. Docker Agent includes +built-in support for Vercel AI Gateway as an alias provider. + +## Setup + +1. Create an API key from the [Vercel AI Gateway dashboard](https://vercel.com/docs/ai-gateway). +2. Set the environment variable: + + ```bash + export AI_GATEWAY_API_KEY=your-api-key + ``` + +## Usage + +Vercel AI Gateway model IDs use a `creator/model` form (for example +`openai/gpt-5.6-sol` or `anthropic/claude-sonnet-4.5`); the gateway routes each +request to the underlying provider. The gateway lists explicit variant slugs +only (`openai/gpt-5.6-sol`, `-terra`, `-luna`) — there is no unsuffixed +`openai/gpt-5.6` alias on the gateway. + +### Inline Syntax + +The simplest way to use Vercel AI Gateway: + +```yaml +agents: + root: + model: vercel/openai/gpt-5.6-sol + description: Assistant using Vercel AI Gateway + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + vercel_model: + provider: vercel + model: openai/gpt-5.6-sol + max_tokens: 8192 + +agents: + root: + model: vercel_model + description: Assistant using Vercel AI Gateway + instruction: You are a helpful assistant. +``` + +## Available Models + +Vercel AI Gateway exposes models from many providers behind one endpoint. Check +the [Vercel AI Gateway documentation](https://vercel.com/docs/ai-gateway) for +the current model list, IDs, and pricing. + +| Model | Description | +| --- | --- | +| `openai/gpt-5.6-sol` | OpenAI GPT-5.6 Sol (frontier) routed through the gateway | +| `openai/gpt-5.6-terra` | OpenAI GPT-5.6 Terra (workhorse) routed through the gateway | +| `openai/gpt-5.6-luna` | OpenAI GPT-5.6 Luna (high-volume) routed through the gateway | +| `anthropic/claude-sonnet-4.5` | Anthropic Claude Sonnet routed through the gateway | +| `google/gemini-2.5-flash` | Google Gemini routed through the gateway | + +> Model IDs are case-sensitive and must be passed exactly as the gateway lists +> them, including the `creator/` prefix. + +## How It Works + +Vercel AI Gateway is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://ai-gateway.vercel.sh/v1` +- **Token Variable:** `AI_GATEWAY_API_KEY` + +Because the gateway can route to open-weight models with strict chat templates, +Docker Agent coalesces consecutive system messages into a single leading one for +this provider. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: vercel/anthropic/claude-sonnet-4.5 + description: Code assistant via Vercel AI Gateway + instruction: | + You are an expert programmer. + Write clean, well-documented code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md new file mode 100644 index 000000000000..638e5018826b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md @@ -0,0 +1,99 @@ +--- +title: "xAI (Grok)" +description: "Use xAI's Grok models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, xai (grok) +weight: 270 +canonical: https://docs.docker.com/ai/docker-agent/providers/xai/ +--- + +_Use xAI's Grok models with Docker Agent._ + +## Overview + +xAI provides the Grok family of models through an OpenAI-compatible API. Docker Agent includes built-in support for xAI as an alias provider. + +## Setup + +1. Get an API key from [xAI Console](https://console.x.ai/) +2. Set the environment variable: + + ```bash + export XAI_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +The simplest way to use xAI: + +```yaml +agents: + root: + model: xai/grok-3 + description: Assistant using Grok + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + grok: + provider: xai + model: grok-3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: grok + description: Assistant using Grok + instruction: You are a helpful assistant. +``` + +## Available Models + +| Model | Description | Context | +| ------------------ | ---------------------------------- | ------- | +| `grok-3` | Latest and most capable Grok model | 131K | +| `grok-3-fast` | Faster variant with lower latency | 131K | +| `grok-3-mini` | Compact model for simpler tasks | 131K | +| `grok-3-mini-fast` | Fast variant of the mini model | 131K | +| `grok-2` | Previous generation model | 128K | +| `grok-vision` | Vision-capable model | 32K | + +Check the [xAI documentation](https://docs.x.ai/docs) for the latest available models. + +## Extended Thinking + +Docker Agent's `thinking_budget` field is **not applied** to xAI models: the underlying OpenAI-compatible client only sends `reasoning_effort` for OpenAI reasoning model names (o-series, gpt-5). Setting `thinking_budget` on a Grok model passes config validation but has no effect on the request. + +Grok reasoning models (e.g. `grok-3-mini`) reason on their own without configuration. For non-reasoning models, use the [think tool](../../tools/think/index.md) instead. + +## How It Works + +xAI is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai_chatcompletions`) +- **Base URL:** `https://api.x.ai/v1` +- **Token Variable:** `XAI_API_KEY` + +## Example: Research Assistant + +```yaml +agents: + researcher: + model: xai/grok-3 + description: Research assistant with real-time knowledge + instruction: | + You are a research assistant using Grok. + Provide well-researched, factual responses. + Cite sources when available. + toolsets: + - type: mcp + ref: docker:duckduckgo + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/_index.md b/_vendor/github.com/docker/docker-agent/docs/tools/_index.md new file mode 100644 index 000000000000..ca9847f9a25d --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/_index.md @@ -0,0 +1,5 @@ +--- +title: "Built-in Tools" +description: "Built-in toolsets agents can use out of the box." +weight: 40 +--- diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md new file mode 100644 index 000000000000..f07a9fe62435 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md @@ -0,0 +1,43 @@ +--- +title: "A2A Tool" +description: "Connect to remote agents via the Agent-to-Agent protocol." +keywords: docker agent, ai agents, tools, toolsets, a2a tool +linkTitle: "A2A" +weight: 60 +canonical: https://docs.docker.com/ai/docker-agent/tools/a2a/ +--- + +_Connect to remote agents via the Agent-to-Agent protocol._ + +## Overview + +The A2A tool connects to a remote agent exposed over the A2A (Agent-to-Agent) protocol. Unlike [`handoff`](../handoff/index.md), which only targets local agents declared in the same config, `a2a` reaches out to an agent running on the network. + +## Configuration + +```yaml +toolsets: + - type: a2a + url: "http://localhost:8080/a2a" + # Optional: custom tool name (defaults to a sanitized form of the URL / agent card name) + name: research_agent + # Optional: custom HTTP headers (typically for auth) + headers: + Authorization: "Bearer ${env.A2A_TOKEN}" + X-Tenant: "acme" +``` + +The `Authorization` header shown above authenticates to endpoints served with `docker agent serve a2a --auth-token`. + +## Properties + +| Property | Type | Required | Description | +| ---------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `url` | string | ✓ | A2A server endpoint URL (must include scheme). | +| `name` | string | ✗ | Tool name registered for the remote agent. Defaults to a name derived from the server's agent card. | +| `headers` | map\[string\]string | ✗ | Extra HTTP headers sent with every request (useful for `Authorization`, tenant selection, tracing, \u2026). | + +> [!TIP] +> **See also** +> +> For full details on the A2A protocol and serving agents as A2A endpoints, see [A2A Protocol](../../features/a2a/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md new file mode 100644 index 000000000000..73e802bd5b89 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md @@ -0,0 +1,252 @@ +--- +title: "API Tool" +description: "Create custom tools that call HTTP APIs." +keywords: docker agent, ai agents, tools, toolsets, api tool +linkTitle: "API" +weight: 240 +canonical: https://docs.docker.com/ai/docker-agent/tools/api/ +--- + +_Create custom tools that call HTTP APIs._ + +## Overview + +The API tool type lets you define custom tools that make HTTP requests to external APIs. This is useful for integrating agents with REST APIs, webhooks, or any HTTP-based service without writing code. + +> [!NOTE] +> **When to Use** +> +> - Integrating with REST APIs that don't have an MCP server +> - Simple HTTP operations (GET, POST) +> - Quick prototyping before building a full MCP server + +## Configuration + +```yaml +agents: + assistant: + model: openai/gpt-4o + description: Assistant with API access + instruction: You can look up weather information. + toolsets: + - type: api + api_config: + name: get_weather + method: GET + endpoint: "https://api.weather.example/v1/current?city=${city}" + instruction: Get current weather for a city + args: + city: + type: string + description: City name to get weather for + required: ["city"] + headers: + Authorization: "Bearer ${env.WEATHER_API_KEY}" +``` + +## Properties + +The `api` toolset accepts the following toolset-level fields in addition to the `api_config` block: + +| Property | Type | Required | Description | +| ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api_config` | object | ✓ | The HTTP tool definition. See the table below. | +| `timeout` | int | ✗ | HTTP client timeout in seconds (default: `30`). Applies to every call the generated tool makes. | +| `allow_private_ips` | boolean | ✗ | Opt in to dialling **non-public** IP addresses (loopback, RFC1918, link-local — including the cloud-metadata endpoint at `169.254.169.254` — multicast and the unspecified address). Set to `true` only when the configured endpoint legitimately targets internal services. See [Reaching internal services](#reaching-internal-services). | + +### `api_config` + +| Property | Type | Required | Description | +| --------------- | ------ | -------- | ------------------------------------------------ | +| `name` | string | ✓ | Tool name (how the agent references it) | +| `method` | string | ✓ | HTTP method: `GET` or `POST` | +| `endpoint` | string | ✓ | URL endpoint (supports `${param}` interpolation) | +| `instruction` | string | ✗ | Description shown to the agent | +| `args` | object | ✗ | Parameter definitions (JSON Schema properties) | +| `required` | array | ✗ | List of required parameter names | +| `headers` | object | ✗ | HTTP headers to include. Values support `${env.VAR}` and `${headers.NAME}` placeholders (the latter forwards a header from the caller's incoming request, useful when docker agent is itself exposed as an HTTP server). | +| `output_schema` | object | ✗ | JSON Schema for the response. Used by MCP / Code Mode consumers; tool responses are still returned to the model as raw strings. | + +## HTTP Methods + +### GET Requests + +For GET requests, parameters are interpolated into the URL: + +```yaml +toolsets: + - type: api + api_config: + name: search_users + method: GET + endpoint: "https://api.example.com/users?q=${query}&limit=${limit}" + instruction: Search for users by name + args: + query: + type: string + description: Search query + limit: + type: integer + description: Maximum results (default 10) + required: ["query"] +``` + +### POST Requests + +For POST requests, parameters are sent as JSON in the request body: + +```yaml +toolsets: + - type: api + api_config: + name: create_task + method: POST + endpoint: "https://api.example.com/tasks" + instruction: Create a new task + args: + title: + type: string + description: Task title + description: + type: string + description: Task description + priority: + type: string + enum: ["low", "medium", "high"] + description: Task priority + required: ["title"] + headers: + Content-Type: "application/json" + Authorization: "Bearer ${env.API_TOKEN}" +``` + +## URL Interpolation + +Use `${param}` syntax to insert parameter values into URLs: + +```yaml +endpoint: "https://api.example.com/users/${user_id}/posts/${post_id}" +``` + +Parameter values are inserted as strings by the template expansion. Add URL encoding in the template when needed (for example, `${encodeURIComponent(city)}`). + +## Headers + +Headers can include environment variables: + +```yaml +headers: + Authorization: "Bearer ${env.API_KEY}" + X-Custom-Header: "static-value" + Content-Type: "application/json" +``` + +## Output Schema + +Optionally document the expected response format: + +```yaml +toolsets: + - type: api + api_config: + name: get_user + method: GET + endpoint: "https://api.example.com/users/${id}" + instruction: Get user details by ID + args: + id: + type: string + description: User ID + required: ["id"] + output_schema: + type: object + properties: + id: + type: string + name: + type: string + email: + type: string + created_at: + type: string +``` + +## Example: GitHub API + +```yaml +agents: + github_assistant: + model: openai/gpt-4o + description: Assistant that can query GitHub + instruction: You can look up GitHub repositories and users. + toolsets: + - type: api + api_config: + name: get_repo + method: GET + endpoint: "https://api.github.com/repos/${owner}/${repo}" + instruction: Get information about a GitHub repository + args: + owner: + type: string + description: Repository owner (user or org) + repo: + type: string + description: Repository name + required: ["owner", "repo"] + headers: + Accept: "application/vnd.github.v3+json" + Authorization: "Bearer ${env.GITHUB_TOKEN}" + + - type: api + api_config: + name: get_user + method: GET + endpoint: "https://api.github.com/users/${username}" + instruction: Get information about a GitHub user + args: + username: + type: string + description: GitHub username + required: ["username"] + headers: + Accept: "application/vnd.github.v3+json" +``` + +## Limitations + +- Only supports GET and POST methods +- Response body is limited to 1MB +- Default 30-second timeout per request (override with the `timeout` field) +- Only HTTP and HTTPS URLs are supported +- No support for file uploads or multipart forms +- By default, requests to non-public IP ranges (loopback, RFC1918, link-local, the cloud-metadata endpoint, multicast, the unspecified address) are refused at dial time — even when DNS for an otherwise-public host resolves there. Set `allow_private_ips: true` to disable that check. + +## Reaching internal services + +```yaml +toolsets: + - type: api + timeout: 60 + allow_private_ips: true + api_config: + name: get_local_status + method: GET + endpoint: "http://localhost:8080/health" + instruction: Check the local service health +``` + +> [!WARNING] +> **SSRF** +> +> Setting `allow_private_ips: true` re-exposes the SSRF surface for this tool. Only enable it when the configured `endpoint` is a trusted internal service — a prompt-injected agent cannot redirect the call elsewhere because the endpoint is fixed in config, but redirects from the configured host can still reach unexpected places. + +> [!TIP] +> **For Complex APIs** +> +> For APIs that need authentication flows, pagination, or complex request/response handling, consider using an MCP server instead. The API tool is best for simple, stateless HTTP operations. + +> [!WARNING] +> **Security** +> +> API keys and tokens in headers are visible in debug logs. Use environment variables (`${env.VAR}`) rather than hardcoding secrets in configuration files. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md new file mode 100644 index 000000000000..0c6afbfaaed9 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md @@ -0,0 +1,120 @@ +--- +title: "Background Agents Tool" +description: "Dispatch work to sub-agents concurrently and collect results asynchronously." +keywords: docker agent, ai agents, tools, toolsets, background agents tool +linkTitle: "Background Agents" +weight: 90 +canonical: https://docs.docker.com/ai/docker-agent/tools/background-agents/ +--- + +_Dispatch work to sub-agents concurrently and collect results asynchronously._ + +## Overview + +The background agents tool lets an orchestrator dispatch work to sub-agents concurrently and collect results asynchronously. Unlike [transfer_task](../transfer-task/index.md) (which blocks until the sub-agent finishes), background agent tasks run in parallel — the orchestrator can start several tasks, do other work, and check on them later. + +## Available Tools + +| Tool | Description | +| ------------------------ | --------------------------------------------------------------- | +| `run_background_agent` | Start a sub-agent task in the background; returns a task ID | +| `list_background_agents` | List all background tasks with their status and runtime | +| `view_background_agent` | View live output or final result of a task by ID | +| `stop_background_agent` | Cancel a running task by ID | + +### `run_background_agent` parameters + +| Parameter | Type | Required | Description | +| ----------------- | ------ | -------- | --------------------------------------------------------------------------- | +| `agent` | string | ✓ | Name of the sub-agent to run. Must be listed under the caller's `sub_agents`. | +| `task` | string | ✓ | Clear, concise description of the task the sub-agent should achieve. | +| `expected_output` | string | ✗ | Optional description of the result format the caller expects. | + +`run_background_agent` returns a **task ID** string. Tools run by the sub-agent inherit the parent session's permissions. Because background tasks run non-interactively, any tool call that would normally prompt the user for approval will be automatically denied. To allow background agents to run mutating tools, you must explicitly approve them in the parent session (e.g. via YOLO mode or explicit allow rules). + +Background delegation shares the same runtime guards as `transfer_task`: delegation cycles are rejected and chains are capped at 10 nested delegations. See [Delegation Limits](../transfer-task/index.md#delegation-limits). + +### `view_background_agent` and `stop_background_agent` parameters + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | -------------------------------------------------------------- | +| `task_id` | string | ✓ | Task ID returned by `run_background_agent` or `list_background_agents`. | + +`list_background_agents` takes no parameters. + +## Configuration + +```yaml +toolsets: + - type: background_agents +``` + +No configuration options. Requires the agent to have `sub_agents` configured so the background tasks have agents to dispatch to. + +## Example + +```yaml +agents: + coordinator: + model: openai/gpt-4o + description: Orchestrates parallel research + instruction: Fan out research tasks and synthesize results. + sub_agents: [researcher] + toolsets: + - type: background_agents + - type: think + + researcher: + model: openai/gpt-4o + description: Web researcher + instruction: Research topics thoroughly. + toolsets: + - type: mcp + ref: docker:duckduckgo +``` + +> [!TIP] +> **When to Use** +> +> Use `background_agents` when your orchestrator needs to fan out work to multiple specialists in parallel — for example, researching several topics simultaneously or running independent code analyses side by side. + +In the TUI, each background task's token usage is accounted for live: the sidebar's Agents panel shows the sub-agent's context usage percentage on its roster row, the Agent Inspector shows its exact token counts, and the task's cost joins the session total. + +## Using Harness Sub-Agents + +Background agents work equally well with [harness-backed sub-agents](../../features/harnesses/index.md) — sub-agents driven by external coding CLIs such as Claude Code or Codex. This lets you dispatch multiple independent coding tasks in parallel: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Orchestrator that fans out coding tasks + instruction: | + Dispatch the frontend and backend tasks in parallel, + then collect results and produce a summary. + sub_agents: + - claude-coder + - codex-coder + toolsets: + - type: background_agents + + claude-coder: + description: Frontend specialist (Claude Code) + harness: + type: claude-code + effort: medium + + codex-coder: + description: Backend specialist (Codex) + harness: + type: codex +``` + +The orchestrator calls `run_background_agent` for each coding task, then uses `list_background_agents` and `view_background_agent` to collect results when they finish. + +> [!NOTE] +> **Harness toolsets are ignored** +> +> Harness agents use the external CLI's own tools — any `toolsets:` configured on the harness agent are silently ignored. See [Coding Harnesses](../../features/harnesses/index.md) for details and caveats. + +See [`examples/coding_harness_background_agents.yaml`](https://github.com/docker/docker-agent/blob/main/examples/coding_harness_background_agents.yaml) for a complete configuration. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md new file mode 100644 index 000000000000..8a7a3915e678 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md @@ -0,0 +1,89 @@ +--- +title: "Background Jobs Tool" +description: "Run and manage long-running shell commands." +keywords: docker agent, ai agents, tools, toolsets, background jobs, shell +linkTitle: "Background Jobs" +weight: 21 +canonical: https://docs.docker.com/ai/docker-agent/tools/background-jobs/ +--- + +_Run and manage long-running shell commands._ + +## Overview + +The `background_jobs` toolset starts shell commands that should keep running while the agent continues with other work, such as local servers, file watchers, long builds, or test suites. It returns a job ID immediately, captures combined stdout/stderr up to 10 MB per job, and terminates all running jobs when the agent session ends. + +Use the [`shell`](../shell/index.md) toolset for short synchronous commands. Add both toolsets when an agent needs both synchronous commands and long-running processes. + +## Configuration + +```yaml +toolsets: + - type: shell + - type: background_jobs +``` + +### Options + +| Property | Type | Description | +| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `env` | object | Environment variables to set for all background job commands. | +| `recall` | boolean | Let `run_background_job` expose a `recall` parameter so jobs can steer the agent when they finish (see [Background job recall](#background-job-recall)). Default `false`. | + +### Custom Environment Variables + +```yaml +toolsets: + - type: background_jobs + env: + MY_VAR: "value" + PATH: "${env.PATH}:/custom/bin" +``` + +### Background job recall + +Set `recall: true` to let the `run_background_job` tool expose a `recall` boolean parameter: + +```yaml +toolsets: + - type: background_jobs + recall: true +``` + +When the agent starts a background job with `recall: true`, Docker Agent sends a steering message back into the running agent loop after the job finishes. The message contains a short completion sentence and the job output, so the agent can react without polling `view_background_job`. + +Use recall for finite background work where completion matters (for example, a long build or test suite). Avoid it for servers and watchers that are expected to run until stopped. See [`examples/shell_recall.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shell_recall.yaml) for a complete configuration. + +## Available Tools + +The background jobs toolset exposes five tools: + +| Tool Name | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------- | +| `run_background_job` | Start a command asynchronously and return a job ID immediately. Use for servers/watchers/etc. | +| `list_background_jobs` | List all background jobs with their status, runtime, and metadata. | +| `view_background_job` | View the buffered output and status of a specific background job by ID. | +| `stop_background_job` | Stop a running background job. Child processes are terminated too. | +| `wait_background_job` | Block until a job finishes and return its exit code and output. Safe on already-finished jobs. | + +### `run_background_job` parameters + +| Parameter | Type | Required | Description | +| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `cmd` | string | ✓ | The shell command to execute in the background. | +| `cwd` | string | ✗ | Working directory to run the command in (default: `.`). | +| `recall` | boolean | ✗ | Only available when the `background_jobs` toolset has `recall: true`. When true, send a steering message with the job output when it finishes. | + +`view_background_job` and `stop_background_job` each take a single required `job_id` string returned by `run_background_job` or `list_background_jobs`. + +### `wait_background_job` parameters + +| Parameter | Type | Required | Description | +| --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| `job_id` | string | ✓ | Job ID returned by `run_background_job` or `list_background_jobs`. | +| `timeout` | integer | ✗ | Maximum seconds to wait (default: `60`). If the job is still running when the limit fires, the tool returns the current output with a notice and the job continues in the background. | + +> [!WARNING] +> **Safety** +> +> Background jobs run shell commands with the same access as the agent process. Stop servers and watchers when they are no longer needed, and use [Sandbox Mode](../../configuration/sandbox/index.md) for additional isolation. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md new file mode 100644 index 000000000000..fa793a54ac07 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md @@ -0,0 +1,173 @@ +--- +title: "Fetch Tool" +description: "Read content from HTTP/HTTPS URLs." +keywords: docker agent, ai agents, tools, toolsets, fetch tool +linkTitle: "Fetch" +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/tools/fetch/ +--- + +_Read content from HTTP/HTTPS URLs._ + +## Overview + +The fetch tool lets agents retrieve content from one or more HTTP/HTTPS URLs. It is **read-only** — only `GET` requests are supported. The tool respects `robots.txt`, limits response size (1 MB per URL), and can return content as plain text, Markdown (converted from HTML), or raw HTML. + +> [!NOTE] +> **GET only** +> +> The fetch tool does **not** support `POST`, `PUT`, `DELETE` or other methods, and does not expose request bodies or per-call custom headers (the toolset can still attach static [credential headers](#custom-headers) to every request). To call REST endpoints with other verbs, use the [API tool](../api/index.md) or an [OpenAPI toolset](../openapi/index.md). + +## Configuration + +```yaml +toolsets: + - type: fetch +``` + +### Options + +| Property | Type | Default | Description | +| ------------------- | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `timeout` | int | `30` | Default request timeout in seconds (overridable per tool call). | +| `allowed_domains` | array[string] | _none_ | Allow-list of hosts the tool may fetch. When set, every URL whose host is **not** in the list is rejected before any network call is made. Mutually exclusive with `blocked_domains`. | +| `blocked_domains` | array[string] | _none_ | Deny-list of hosts the tool must not fetch. URLs whose host matches one of these patterns are rejected before any network call (including `robots.txt`) is made. Mutually exclusive with `allowed_domains`. | +| `allow_private_ips` | boolean | `false` | Opt in to dialling **non-public** IP addresses (loopback, RFC1918, link-local — including the cloud-metadata endpoint at `169.254.169.254` — multicast, and the unspecified address). Required to reach `localhost` / internal services. See [SSRF protection](#ssrf-protection-and-reaching-localhost) below. | +| `headers` | map[string]string | _none_ | Static HTTP headers attached to **every** request the toolset issues (including `robots.txt`). Values support `${env.VAR}` for secrets. Caller-supplied entries override the default `User-Agent` and the format-driven `Accept` header. Headers are stripped on cross-host redirects so credentials never leak to a third-party host. See [Custom headers](#custom-headers) below. | + +### Domain matching + +Domain patterns in `allowed_domains` and `blocked_domains` use the following rules (case-insensitive): + +- **Bare domain** — `example.com` matches the host `example.com` _and_ any subdomain such as `docs.example.com`. It does **not** match unrelated hosts that share a suffix (e.g. `badexample.com`). +- **Leading dot** — `.example.com` matches **only** strict subdomains (`docs.example.com`, `a.b.example.com`), not the apex `example.com`. +- **Wildcard glob** — `*.example.com` is an alias for the leading-dot form; the apex is excluded. The `*` is only valid as a leading `*.` token (entries like `foo.*`, `*.*.example.com`, or a bare `*` are rejected at config-load time). +- **IP literal** — IP addresses are matched exactly (`169.254.169.254`). +- **CIDR range** — `169.254.0.0/16`, `10.0.0.0/8`, `::1/128`, `fc00::/7`. Matches when the URL's host parses as an IP inside the network. Hostname hosts never match a CIDR pattern. Malformed CIDRs are rejected at config-load time. +- **Trailing dots** in FQDN-form URLs (`http://example.com./`) are stripped before matching, so they cannot bypass a deny-list entry. + +The lists are mutually exclusive: a single fetch toolset may set either `allowed_domains` or `blocked_domains`, but not both. + +When a list is configured, every redirect target is re-checked against the same list. A request to an allowed origin that redirects to a forbidden host is rejected before any data is read from the redirect. + +> [!WARNING] +> **Limitations** +> +> Matching is purely string-based on the URL host. It does **not** perform DNS resolution and does **not** normalise alternative IP encodings (decimal `2852039166`, hex `0xa9.0xfe.0xa9.0xfe`, octal, etc. IPv4-mapped IPv6 addresses ARE normalized to their IPv4 form). If you need to deny access to a specific IP, also list its alternative encodings, or block at the network layer. + +### Custom Timeout + +```yaml +toolsets: + - type: fetch + timeout: 60 +``` + +### Custom headers + +Attach static headers — typically credentials — to every request. Values support `${env.VAR}` interpolation so secrets stay out of YAML, and headers are dropped on cross-host redirects so a redirect chain cannot leak them to a third-party host: + +```yaml +toolsets: + - type: fetch + allowed_domains: + - docs.internal.example.com + headers: + Authorization: "Bearer ${env.INTERNAL_DOCS_TOKEN}" + X-Internal-Client: "docker-agent" +``` + +> [!WARNING] +> **Pair credential headers with an allow-list** +> +> When `headers` carries credentials (e.g. `Authorization`), set `allowed_domains` to the specific hosts that should receive them. Stdlib already strips a small allow-list (`Authorization`, `Cookie`, `WWW-Authenticate`) on cross-domain redirects, and the fetch tool additionally strips every operator-supplied header on cross-host redirects — but an allow-list is the strongest guarantee against accidental exfiltration. + +### Restrict to specific domains + +```yaml +toolsets: + - type: fetch + allowed_domains: + - docker.com # docker.com and *.docker.com + - github.com # github.com and *.github.com + - .githubusercontent.com # only subdomains, e.g. raw.githubusercontent.com +``` + +### Block sensitive hosts + +```yaml +toolsets: + - type: fetch + blocked_domains: + - 169.254.169.254 # cloud metadata endpoint (literal IP) + - 169.254.0.0/16 # entire link-local range (CIDR) + - 10.0.0.0/8 # RFC1918 private range + - "*.internal.example.com" # any subdomain (wildcard) + - internal.example.com # internal corporate hostname +``` + +> [!NOTE] +> **Already blocked by default** +> +> You do **not** need to add loopback, RFC1918, link-local (incl. `169.254.169.254`), multicast or the unspecified address to `blocked_domains` to be safe — the fetch tool already refuses connections to those ranges at dial time, after DNS resolution. The example above is only useful if you also want to reject those hosts _before_ any network call (and to surface a clearer error message to the agent), or if you have set `allow_private_ips: true` and want to deny a specific subset. + +### SSRF protection and reaching localhost + +By default, the fetch tool refuses connections to **non-public IP addresses** — even when DNS for an otherwise-public host resolves to one of them (so DNS rebinding is also blocked). The check happens at dial time, after DNS resolution, and rejects: + +- **Loopback** — `127.0.0.0/8`, `::1` (this is what blocks `http://localhost/...` and `http://127.0.0.1/...`) +- **RFC1918 private ranges** — `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` +- **Link-local** — `169.254.0.0/16` (IPv4, including the cloud-metadata endpoint `169.254.169.254`) and `fe80::/10` (IPv6) +- **Multicast** and the **unspecified** address (`0.0.0.0`, `::`) +- **IPv4-mapped IPv6** — addresses like `::ffff:127.0.0.1` or `::ffff:169.254.169.254` are normalized to their IPv4 form and blocked accordingly + +This is the default because LLM-driven fetches are a classic Server-Side Request Forgery (SSRF) vector: a prompt-injected URL can otherwise reach internal services, cloud metadata, or admin interfaces on the host running the agent. + +If an agent legitimately needs to call **localhost** or an **internal service**, opt in with `allow_private_ips: true`: + +```yaml +toolsets: + - type: fetch + allow_private_ips: true + allowed_domains: + - localhost + - 127.0.0.1 + - 10.0.0.0/8 # internal corporate range +``` + +> [!WARNING] +> **Pair with an allow-list** +> +> Setting `allow_private_ips: true` alone re-exposes the SSRF surface. We strongly recommend combining it with an `allowed_domains` entry that restricts the tool to the specific internal hosts or CIDRs the agent actually needs (e.g. `localhost`, `127.0.0.1`, or your internal CIDR). +> +> **Note:** `allowed_domains` is checked _before_ DNS resolution (string-based on hostname), while the SSRF check happens _after_ DNS resolution (on the resolved IP). This means `allowed_domains` and `blocked_domains` are evaluated independently of `allow_private_ips` and continue to apply. A public hostname in `allowed_domains` that resolves to a private IP will still be blocked unless `allow_private_ips: true` is set. + +## Tool Interface + +The toolset exposes a single tool, `fetch`, with the following parameters: + +| Parameter | Type | Required | Description | +| --------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| `urls` | array[string] | ✓ | One or more HTTP/HTTPS URLs to fetch (all via `GET`). | +| `format` | string | ✓ | Output format: `text`, `markdown`, or `html`. HTML responses are converted to text/markdown when requested. | +| `timeout` | integer | ✗ | Per-call request timeout in seconds. Overrides the toolset default. Valid range: `1`–`300`. | + +Responses are capped at **1 MB** per URL. Hosts that disallow the agent's user-agent via `robots.txt` are skipped with a clear error. + +> [!TIP] +> **Fetch vs. API Tool** +> +> Use `fetch` when the agent needs to read arbitrary public URLs at runtime. Use the [API tool](../api/index.md) to expose specific, structured HTTP endpoints (including non-`GET` verbs) as named tools. + +## Domain Filtering + +The `allowed_domains`, `blocked_domains`, and `allow_private_ips` options let you control which hosts the fetch tool may reach. The complete reference is in the [Options](#options) table and [Domain matching](#domain-matching) section above. + +**Key points:** + +- `allowed_domains` — allow-list; only listed hosts (and their subdomains for bare-domain entries) are reachable +- `blocked_domains` — deny-list; mutually exclusive with `allowed_domains` (a config error is thrown if both are set) +- `allow_private_ips` — defaults to `false`; set to `true` to reach loopback / RFC-1918 / link-local addresses +- The same `allow_private_ips` flag is also supported on `api`, `openapi`, `a2a`, and remote `mcp` toolsets + +See [`examples/fetch_domain_filtering.yaml`](https://github.com/docker/docker-agent/blob/main/examples/fetch_domain_filtering.yaml) for a complete filtering example, and [`examples/remote_mcp_allow_private_ips.yaml`](https://github.com/docker/docker-agent/blob/main/examples/remote_mcp_allow_private_ips.yaml) for the equivalent pattern on remote MCP toolsets. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md new file mode 100644 index 000000000000..19b0be53e1c2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md @@ -0,0 +1,145 @@ +--- +title: "Filesystem Tool" +description: "Read, write, list, search, and navigate files and directories." +keywords: docker agent, ai agents, tools, toolsets, filesystem tool +linkTitle: "Filesystem" +weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/tools/filesystem/ +--- + +_Read, write, list, search, and navigate files and directories._ + +## Overview + +The filesystem tool gives agents the ability to explore codebases, read and edit files, create new files, search across files, and navigate directory structures. + +### Path resolution + +Paths are resolved relative to the **working directory** (the directory where the agent session started, or the directory specified with `--workdir`): + +- **Relative paths** (e.g., `src/main.go`, `../README.md`) are joined with the working directory. +- **Absolute paths** must match the host operating system: + - Unix/Linux/macOS: `/home/user/project/file.txt` + - Windows: `C:\Users\user\project\file.txt` or `C:/Users/user/project/file.txt` +- **Home directory expansion**: paths starting with `~` or `~/` expand to the user's home directory. + +When a file is not found, error messages include the resolved absolute path to help diagnose incorrect base directories or path formats. + +> [!IMPORTANT] +> Agents must use paths appropriate for the host OS. A Windows absolute path like `C:\file.txt` on a Unix system (or vice versa) is rejected with a clear error message. + +### Empty directory detection + +When `list_directory` encounters an empty directory or a directory where all entries are hidden by ignore patterns (e.g., only a `.git` folder when `ignore_vcs: true`), it explicitly reports the state: + +- **Empty directory**: "Directory is empty: /path/to/dir" +- **All entries ignored**: "Directory has no visible entries (N hidden by ignore patterns): /path/to/dir" + +This helps agents distinguish between an empty directory and a tool failure, avoiding unnecessary retries with shell commands. + +## Available Tools + +| Tool | Description | +| ---------------------- | ------------------------------------------------------------------------- | +| `read_file` | Read the contents of a file (whole file, or a line range of a text file) | +| `read_multiple_files` | Read several files in one call (more efficient than multiple `read_file`) | +| `write_file` | Create or overwrite a file with new content | +| `edit_file` | Make line-based edits (find-and-replace) in an existing file. Each edit must specify a non-empty `oldText` to match and replace; empty `oldText` values are rejected with an error. | +| `list_directory` | List files and directories at a given path (explicitly reports empty directories) | +| `directory_tree` | Recursive tree view of a directory | +| `create_directory` | Create a new directory (creates parent directories as needed) | +| `remove_directory` | Remove an empty directory | +| `search_files_content` | Search for text or regex patterns across files | + +## edit_file Validation + +The `edit_file` tool applies a sequence of find-and-replace edits to a file in memory, then writes the result back atomically. Each edit must provide a non-empty `oldText` value: + +- **Valid**: `{"oldText": "line one", "newText": "LINE ONE"}` +- **Invalid**: `{"oldText": "", "newText": "INJECTED"}` — rejected with error + +An empty `oldText` is never a meaningful edit: Go's `strings.Contains(s, "")` is always `true`, and `strings.Replace(s, "", new, 1)` silently inserts at offset 0. Without validation, this would prepend content to the file while still reporting success. The tool now returns an explicit error ("oldText must not be empty") when an edit has an empty `oldText`, and no changes are written to disk. + +When a sequence contains multiple edits and a later one is rejected, the entire operation fails and the file is left untouched — edits are applied in memory and only written once at the end, so partial application is not possible. + +## Configuration + +```yaml +toolsets: + - type: filesystem +``` + +### Options + +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `ignore_vcs` | boolean | `true` | When `true` (default), `.git` directories and `.gitignore` patterns are excluded from listings and searches. Set to `false` to include them. | +| `post_edit` | array | `[]` | Commands to run after editing files matching a path pattern | +| `post_edit[].path` | string | — | Glob pattern for files (e.g., `*.go`, `src/*/*.ts`) | +| `post_edit[].cmd` | string | — | Command to run (use `${file}` for the edited file path) | +| `allow_list` | array | `[]` | Directories the tools may access. Empty = unrestricted (default). | +| `deny_list` | array | `[]` | Directories the tools must not access. Takes precedence over `allow_list`. | + +### Path access control + +By default the filesystem tools are unrestricted: relative paths resolve +from the working directory, but absolute paths and `..` traversals can +reach anywhere the agent process can. Configure `allow_list` and/or +`deny_list` to sandbox the toolset. + +Entries in either list are expanded as follows: + +- `"."` — the agent's working directory +- `"~"` or `"~/..."` — the user's home directory +- `"$VAR"` / `"${VAR}"` / `"${env.VAR}"` — environment variable expansion +- absolute paths — used as-is +- relative paths — anchored at the working directory + +Symlinks are resolved before the containment check, so a symlink inside an +allowed root cannot be used to escape it. When an `allow_list` is set, +each entry is opened as a Go [`*os.Root`](https://pkg.go.dev/os#Root) so +that the kernel's rooted-lookup semantics also reject `..` and symlink +escapes at I/O time, not just at resolve time. + +```yaml +toolsets: + - type: filesystem + # Restrict every operation to the working directory and the user's + # home folder, then carve credentials out of the home folder. + allow_list: + - "." + - "~" + deny_list: + - "~/.ssh" + - "~/.aws" +``` + +When the path supplied by the agent is rejected, the tool returns a +structured error rather than performing any filesystem I/O. This makes the +restriction visible to the model so it can adjust its plan. + +### Post-Edit Hooks + +Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). Use `${file}` as a placeholder for the absolute path of the edited file. + +```yaml +toolsets: + - type: filesystem + ignore_vcs: false + post_edit: + - path: "*.go" + cmd: "gofmt -w ${file}" + - path: "*.ts" + cmd: "prettier --write ${file}" + - path: "src/*/*.py" + cmd: "black ${file}" +``` + +| Property | Type | Description | +| --- | --- | --- | +| `path` | string | Glob pattern matched against the file path. `*.go` matches any `.go` file; `src/*/*.ts` matches `.ts` files inside `src/`. | +| `cmd` | string | Shell command to run. `${file}` expands to the absolute path of the just-edited file. | + +Post-edit commands run with the same working directory as the agent. If a command exits non-zero, the error is logged and surfaced to the model as a warning, but the edit is not rolled back. + +See [`examples/post_edit.yaml`](https://github.com/docker/docker-agent/blob/main/examples/post_edit.yaml) for a complete example. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md new file mode 100644 index 000000000000..9568b7508dfa --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md @@ -0,0 +1,100 @@ +--- +title: "Git Tool" +description: "Read-only inspection of the working git repository." +keywords: docker agent, ai agents, tools, toolsets, git tool +linkTitle: "Git" +weight: 125 +canonical: https://docs.docker.com/ai/docker-agent/tools/git/ +--- + +_Read-only inspection of the working git repository._ + +## Overview + +The git toolset gives an agent structured, **read-only** access to the working repository — status, history, branches, a commit's changes, and line-level authorship. It is implemented with go-git, so it needs **no `git` binary**. + +Compared with running `git` through the `shell` tool, the git toolset returns clean, structured output the model can read reliably, is **safe by construction** (no command can modify the repository), and works even when `shell` is disabled or no `git` binary is installed. + +> [!NOTE] +> The git toolset is read-only. To stage, commit, or check out, use the [`shell`](../shell/index.md) tool. + +## Configuration + +```yaml +toolsets: + - type: git +``` + +No configuration options. The repository is opened at the agent's working directory; a subdirectory still resolves to the repository root. + +> [!WARNING] +> **The repository is discovered by walking up parent directories.** If the working +> directory is not itself a repository but an ancestor is (for example a +> home directory tracked as dotfiles), the toolset resolves to that ancestor and +> `git_show` / `git_blame` can expose its full history and file contents. The +> filesystem toolset's allow/deny lists do **not** apply here. Only enable this +> toolset where the surrounding repository is safe to read. + +> [!NOTE] +> **Performance.** go-git is pure Go, which costs speed on large repositories: +> `git_status` rehashes the whole worktree, and `git_blame` scales with history +> depth times file size — its 400-line output cap is applied *after* the full +> computation, so it does not make blaming a large file cheaper. + +## Tools + +| Tool | Description | +| --- | --- | +| `git_status` | Current branch and changed files (staged / unstaged / untracked). | +| `git_log` | Recent commits (hash, date, author, subject). | +| `git_branches` | Local branches, current one marked with `*`. | +| `git_show` | A commit's metadata, message, and changed files with +/- counts. | +| `git_blame` | Line-by-line authorship for a file. | + +### `git_log` + +| Parameter | Required | Description | +| --- | --- | --- | +| `limit` | No | Maximum number of commits to return (default 20). | +| `path` | No | Only show commits that touch this path. | + +### `git_show` + +| Parameter | Required | Description | +| --- | --- | --- | +| `ref` | No | Commit hash or revision to show (default HEAD). | + +### `git_blame` + +| Parameter | Required | Description | +| --- | --- | --- | +| `path` | Yes | File path to blame, relative to the repository root. | +| `rev` | No | Commit or revision to blame at (default HEAD). | + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini + description: A code review assistant + instruction: | + Review the working changes: check git_status, then git_show the latest + commit, and summarize what changed. + toolsets: + - type: git + - type: filesystem +``` + +Example `git_status` output: + +```text +On branch master +1 changed file(s) [XY = staged/worktree; M=modified A=added D=deleted R=renamed ?=untracked]: + M main.go +``` + +> [!TIP] +> **When to use** +> +> Use the git toolset whenever the agent needs repository context — before editing, to review recent history, or to find who last touched a line — without exposing the writable `shell` surface. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md new file mode 100644 index 000000000000..4375be03daac --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md @@ -0,0 +1,63 @@ +--- +title: "Handoff Tool" +description: "Hand off the active conversation to another local agent defined in the same config." +keywords: docker agent, ai agents, tools, toolsets, handoff tool +linkTitle: "Handoff" +weight: 70 +canonical: https://docs.docker.com/ai/docker-agent/tools/handoff/ +--- + +_Hand off the active conversation to another local agent defined in the same config._ + +## Overview + +The `handoff` tool lets an agent transfer control of the **current conversation** to another agent in the **same config file**. Unlike [`transfer_task`](../transfer-task/index.md), which delegates a sub-task and collects the result, `handoff` rewires the session so the receiving agent continues the conversation directly with the user. + +This is the core mechanism for **handoffs routing** — a pattern where a router agent classifies the user's request and hands it off to a specialist, which then owns the rest of the session. + +> [!NOTE] +> **Local only** +> +> The `handoff` tool only targets agents declared in the **same** config file by their local name. It does **not** open network connections. To delegate to a remote agent over the network, use the [A2A toolset](../a2a/index.md) instead. + +## Configuration + +The tool is enabled implicitly when an agent declares a non-empty `handoffs:` list. You do **not** add `- type: handoff` under `toolsets:` — it is not a toolset type. + +```yaml +agents: + router: + model: openai/gpt-4o + description: Routes questions to the right specialist + instruction: | + Classify the user's question and hand off to the most appropriate + specialist. If unsure, ask a clarifying question first. + handoffs: [billing, support] + + billing: + model: openai/gpt-4o + description: Billing specialist + instruction: Answer billing questions. + + support: + model: openai/gpt-4o + description: Technical support specialist + instruction: Help with technical issues. +``` + +The router agent automatically gets a `handoff` tool it can call to switch the conversation to `billing` or `support`. + +## Tool Interface + +The `handoff` tool takes a single parameter: + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------------------- | +| `agent` | string | ✓ | The local name of the agent to hand off the conversation to. | + +Only names listed in the current agent's `handoffs:` field are valid targets. + +> [!TIP] +> **See also** +> +> For sub-task delegation (caller stays in control, waits for the result), see [Transfer Task](../transfer-task/index.md). For remote agent connections over the network, see the [A2A toolset](../a2a/index.md). For the broader pattern, see [Handoffs Routing](../../concepts/multi-agent/index.md#handoffs-routing). diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md new file mode 100644 index 000000000000..b2d97b7227b6 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md @@ -0,0 +1,227 @@ +--- +title: "LSP Tool" +description: "Connect to Language Server Protocol servers for code intelligence." +keywords: docker agent, ai agents, tools, toolsets, lsp tool +linkTitle: "LSP" +weight: 220 +canonical: https://docs.docker.com/ai/docker-agent/tools/lsp/ +--- + +_Connect to Language Server Protocol servers for code intelligence._ + +## Overview + +The LSP tool connects your agent to any Language Server Protocol (LSP) server, providing comprehensive code intelligence capabilities like go-to-definition, find references, diagnostics, and more. + +> [!NOTE] +> **What is LSP?** +> +> The [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) is a standard for providing language features like autocomplete, go-to-definition, and diagnostics. Most programming languages have LSP servers available. + +## Available Tools + +The LSP toolset provides these tools to the agent: + +| Tool | Description | Read-Only | +| ----------------------- | --------------------------------------------- | --------- | +| `lsp_workspace` | Get workspace info and available capabilities | ✓ | +| `lsp_hover` | Get type info and documentation for a symbol | ✓ | +| `lsp_definition` | Find where a symbol is defined | ✓ | +| `lsp_references` | Find all references to a symbol | ✓ | +| `lsp_document_symbols` | List all symbols in a file | ✓ | +| `lsp_workspace_symbols` | Search symbols across the workspace | ✓ | +| `lsp_diagnostics` | Get errors and warnings for a file | ✓ | +| `lsp_code_actions` | Get available quick fixes and refactorings | ✓ | +| `lsp_rename` | Rename a symbol across the workspace | ✗ | +| `lsp_format` | Format a file | ✗ | +| `lsp_call_hierarchy` | Find incoming/outgoing calls | ✓ | +| `lsp_type_hierarchy` | Find supertypes/subtypes | ✓ | +| `lsp_implementations` | Find interface implementations | ✓ | +| `lsp_signature_help` | Get function signature at call site | ✓ | +| `lsp_inlay_hints` | Get type annotations and parameter names | ✓ | + +## Configuration + +```yaml +agents: + developer: + model: anthropic/claude-sonnet-4-5 + description: Code developer with LSP support + instruction: You are a software developer. + toolsets: + - type: lsp + command: gopls + args: [] + file_types: [".go"] + - type: filesystem + - type: shell +``` + +## Properties + +| Property | Type | Required | Description | +| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `command` | string | ✓ | LSP server executable command | +| `args` | array | ✗ | Command-line arguments for the LSP server | +| `env` | object | ✗ | Environment variables for the LSP process | +| `file_types` | array | ✗ | File extensions this LSP handles (e.g., `[".go", ".mod"]`) | +| `working_dir` | string | ✗ | Working directory for the LSP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. | +| `version` | string | ✗ | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary | + +## Common LSP Servers + +Here are configurations for popular languages: + +### Go (gopls) + +```yaml +toolsets: + - type: lsp + command: gopls + version: "golang/tools@v0.21.0" # optional: auto-install if not in PATH + file_types: [".go"] +``` + +If your Go module lives in a subdirectory (e.g. a monorepo where `go.mod` is under `./backend`), set `working_dir` so `gopls` is started from the module root: + +```yaml +toolsets: + - type: lsp + command: gopls + file_types: [".go"] + working_dir: ./backend # gopls must be started from the module root +``` + +### TypeScript/JavaScript (typescript-language-server) + +```yaml +toolsets: + - type: lsp + command: typescript-language-server + args: ["--stdio"] + file_types: [".ts", ".tsx", ".js", ".jsx"] +``` + +### Python (pylsp) + +```yaml +toolsets: + - type: lsp + command: pylsp + file_types: [".py"] +``` + +### Rust (rust-analyzer) + +```yaml +toolsets: + - type: lsp + command: rust-analyzer + file_types: [".rs"] +``` + +### C/C++ (clangd) + +```yaml +toolsets: + - type: lsp + command: clangd + file_types: [".c", ".cpp", ".h", ".hpp"] +``` + +## Multiple LSP Servers + +You can configure multiple LSP servers for different file types: + +```yaml +agents: + polyglot: + model: anthropic/claude-sonnet-4-5 + description: Multi-language developer + instruction: You are a full-stack developer. + toolsets: + - type: lsp + command: gopls + file_types: [".go"] + - type: lsp + command: typescript-language-server + args: ["--stdio"] + file_types: [".ts", ".tsx", ".js", ".jsx"] + - type: lsp + command: pylsp + file_types: [".py"] + - type: filesystem + - type: shell +``` + +## Workflow Instructions + +The LSP tool includes built-in instructions that guide the agent on how to use it effectively. The agent learns to: + +1. Start with `lsp_workspace` to understand available capabilities +2. Use `lsp_workspace_symbols` to find relevant code +3. Use `lsp_references` before modifying any symbol +4. Check `lsp_diagnostics` after every code change +5. Apply `lsp_format` after edits are complete + +> [!TIP] +> **Best Practice** +> +> Always include the `filesystem` tool alongside LSP. The agent needs filesystem access to read and write code files, while LSP provides intelligence about the code. + +## Capability Detection + +Not all LSP servers support all features. During the `initialize` handshake, Docker Agent reads the server's `ServerCapabilities` and **filters out the `lsp_*` tools the server does not advertise**. The model never sees, for example, `lsp_inlay_hints` against a server that doesn't support it, so it can't waste a turn calling a tool that would only fail. + +The agent uses `lsp_workspace` to discover what's available: + +```text +Workspace Information: +- Root: /path/to/project +- Server: gopls v0.14.0 +- File types: .go + +Available Capabilities: +- Hover: Yes +- Go to Definition: Yes +- Find References: Yes +- Rename: Yes +- Code Actions: Yes +- Formatting: Yes +- Call Hierarchy: Yes +- Type Hierarchy: Yes +... +``` + +## Auto-Restart and Lifecycle + +LSP toolsets are managed by the same supervisor as MCP toolsets, so a crashed `gopls` (or any other language server) is reconnected automatically with exponential backoff. Use the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block to tune the policy per toolset — for example, mark `gopls` as `strict` if your CI flow requires it to be available, or use `/toolset-restart gopls` from the TUI to force a reconnect when the server gets stuck. + +```yaml +toolsets: + - type: lsp + command: gopls + file_types: [".go"] + lifecycle: + profile: resilient # default: auto-restart on crash with exponential backoff +``` + +## Position Format + +All LSP tools use **1-based** line and character positions: + +- Line 1 is the first line of the file +- Character 1 is the first character on a line + +```json +{ + "file": "/path/to/file.go", + "line": 42, + "character": 15 +} +``` + +> [!TIP] +> **Auto-Installation** +> +> Docker Agent can automatically download and install LSP servers if they are not found in your PATH. Use the `version` property to specify a package, or let Docker Agent auto-detect it from the command name. See [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools) for details. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md new file mode 100644 index 000000000000..d395a3ef6de7 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md @@ -0,0 +1,113 @@ +--- +title: "MCP Catalog Tool" +description: "Let the agent discover and activate remote MCP servers from the Docker MCP Catalog on demand." +keywords: docker agent, ai agents, tools, toolsets, mcp catalog tool +linkTitle: "MCP Catalog" +weight: 120 +canonical: https://docs.docker.com/ai/docker-agent/tools/mcp-catalog/ +--- + +_Let the agent discover and activate remote MCP servers from the Docker MCP Catalog on demand._ + +## Overview + +The `mcp_catalog` toolset gives an agent access to a curated subset of the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp) — every server in this subset is reachable over the **streamable-http** transport, so Docker Agent can talk to it directly without the MCP gateway or a local subprocess. + +Servers are **not** active by default. Instead, the toolset exposes a small set of meta-tools the agent uses to search, enable, and disable servers as a turn unfolds. Tools from un-enabled servers stay hidden, so the prompt is not flooded with hundreds of tool definitions the agent will never use. + +> [!NOTE] +> **When to use it** +> +> Use `mcp_catalog` when you want the agent to _decide at runtime_ which third-party services it needs (Notion, Stripe, Brave Search, …) instead of pinning that decision in YAML up front. For a fixed set of servers, declare each one with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) directly — the catalog adds an extra layer of meta-tools that pure `type: mcp` entries do not need. + +## Configuration + +```yaml +toolsets: + - type: mcp_catalog +``` + +The catalog is embedded in the `docker-agent` binary and refreshed with each release. By default every server in the embedded subset is offered. + +### Restricting the offered servers + +Two optional lists narrow what the toolset offers, so an agent sees a focused, predictable menu instead of the full catalog: + +- **`allowed_servers`** — when non-empty, **only** these catalog server ids are searchable and enableable; every other entry is hidden. +- **`blocked_servers`** — removes individual ids from the offered set. It is applied **after** `allowed_servers`, so a server listed in both is blocked (block wins over allow). + +Both take server ids (the `id` field returned by `search_remote_mcp_servers`). An empty or omitted list disables that filter. + +```yaml +toolsets: + - type: mcp_catalog + allowed_servers: + - docker-docs + - microsoft-learn + - hugging-face + blocked_servers: + - gitmcp +``` + +## Meta-Tools + +Up to five tools are exposed to the model. The disable / reset-auth pair only appears once at least one server is enabled, so the meta-tool surface stays minimal until the agent activates something. + +| Tool | When visible | Description | +| ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `search_remote_mcp_servers` | Always | Case-insensitive fuzzy search over id, title, description, category and tags. Returns id, auth requirements (`oauth` / `none`) and URL. | +| `enable_remote_mcp_server` | Always | Activate a server by id. **Blocks** until the connection (and any required OAuth handshake) completes; on success the server's tools are immediately live and the model continues with the user's original request in the same turn. | +| `list_remote_mcp_servers` | Always | Show currently enabled servers and their connection state. | +| `disable_remote_mcp_server` | After first enable | Stop a server and remove its tools from the active set. | +| `reset_remote_mcp_server_auth` | After first enable | Drop persisted OAuth credentials so the next enable triggers a fresh authorization flow. No-op for `none` servers. | + +### Workflow + +1. The agent calls `search_remote_mcp_servers` with a keyword matching the user's intent (`"notion"`, `"stripe"`, `"docs"`, `"browser"`, `"grafana"`, …). +2. It picks a matching server id and calls `enable_remote_mcp_server`. **`enable` blocks** until the MCP handshake (and any required OAuth flow) completes: + - on success the server's tools are available **in the same turn** — the agent goes straight to the user's original request, no re-ask required; + - on failure (user dismissed the authorization dialog, server refused) the tool returns an error result naming the specific reason so the agent can recover instead of pretending the server is connected. +3. It uses the newly activated tools as it would any other. +4. When done, it calls `disable_remote_mcp_server` to remove the server from the active set. + +## Authentication + +The catalog only includes servers Docker Agent can authenticate itself, so there are two auth flavours: + +- **`oauth`** — `enable_remote_mcp_server` surfaces an authorization URL through the elicitation pipeline (the same one used by YAML-declared remote MCP toolsets) and blocks until the user either authorizes or cancels. Once the user authorizes, tokens are persisted in the OS keyring and re-used on subsequent runs. Use `reset_remote_mcp_server_auth` to wipe them. If the user dismisses the dialog, `enable` returns an error result naming the decline so the agent can ask whether to retry. +- **`none`** — No authentication. The server is reachable as soon as it is enabled. + +Servers that require a caller-provided API key are intentionally excluded from the catalog. To use one, declare it explicitly with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) and supply the key via an environment variable. + +## Example + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Agent that can on-demand connect to remote MCP servers from the Docker MCP Catalog. + instruction: | + You can discover and activate remote MCP servers on demand. + Use search_remote_mcp_servers to find a server matching the + user's intent, then enable_remote_mcp_server to activate it. + Be conservative: enable only the servers you actually need for + the task at hand. Disable a server with disable_remote_mcp_server + once you are done with it. + toolsets: + - type: mcp_catalog +``` + +A complete, runnable configuration lives in [`examples/mcp_catalog.yaml`](https://github.com/docker/docker-agent/blob/main/examples/mcp_catalog.yaml). A curated, allow/block-listed variant lives in [`examples/mcp_catalog_filtered.yaml`](https://github.com/docker/docker-agent/blob/main/examples/mcp_catalog_filtered.yaml). + +## Notes and Limitations + +- **Streamable-http only.** The catalog deliberately excludes servers that require a local subprocess or the MCP gateway — declare those with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) instead. +- **Catalog membership changes between releases.** The set of available servers is updated with each Docker Agent release as integrations are added or removed. Servers present in one release may not appear in the next. +- **Blocking enable.** DNS, TCP, MCP handshake and any OAuth flow happen synchronously inside `enable_remote_mcp_server` so the agent gets a deterministic result in the same turn. On startup, however, the runtime probes tools non-interactively (`mcp.WithoutInteractivePrompts`); OAuth-pending servers fail fast there and are silently deferred to the next interactive turn — including the sidebar-only tool-count pass, where a dialog would be impossible. +- **No prompt discovery.** MCP prompt lookups (`/prompts`) walk YAML-declared `mcp` toolsets directly; prompts exposed by servers activated through the catalog are not surfaced. Tools — the primary interface — work fine. +- **Frozen at build time.** The list of servers is embedded in the binary. New entries land with each Docker Agent release. + +> [!TIP] +> **Pair with permissions** +> +> Because the agent decides which third-party services to talk to, this toolset works best with explicit [permissions](../../configuration/permissions/index.md) on the surrounding tools (filesystem writes, shell commands) so a misrouted server cannot exfiltrate data unnoticed. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md new file mode 100644 index 000000000000..b1acb0cca7ea --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md @@ -0,0 +1,309 @@ +--- +title: "MCP Tool" +description: "Extend agents with external tools via the Model Context Protocol." +keywords: docker agent, ai agents, tools, toolsets, mcp tool +linkTitle: "MCP" +weight: 130 +canonical: https://docs.docker.com/ai/docker-agent/tools/mcp/ +aliases: + - /ai/docker-agent/integrations/mcp/ +--- + +_Extend agents with external tools via the Model Context Protocol (MCP)._ + +## Overview + +The `mcp` toolset connects your agent to any MCP server — a process or remote service that exposes tools, resources, and prompts over the [Model Context Protocol](https://modelcontextprotocol.io/). Three flavours are supported: + +| Flavour | Transport | Best for | +| --- | --- | --- | +| **Docker MCP** | Container via the [MCP Gateway](https://github.com/docker/mcp-gateway) | Curated, sandboxed servers from the [Docker MCP Catalog](https://hub.docker.com/u/mcp) | +| **Local stdio** | Subprocess over stdin/stdout | Custom or community MCP servers run from a binary or `npx`/`pip` package | +| **Remote** | Streamable HTTP or SSE | Cloud services with hosted MCP endpoints (Linear, Notion, Atlassian, …) | + +> [!NOTE] +> **What is MCP?** +> +> The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools. Docker Agent can both _use_ MCP servers (this page) and _expose_ agents as MCP servers — see [MCP Mode](../../features/mcp-mode/index.md). + +## Docker MCP (Recommended) + +Run MCP servers as secure Docker containers via the MCP Gateway. The `ref: docker:<name>` syntax pulls a curated definition from the Docker MCP Catalog: + +```yaml +toolsets: + - type: mcp + ref: docker:duckduckgo # web search + - type: mcp + ref: docker:github-official # GitHub integration + tools: ["list_issues", "create_issue"] +``` + +Browse available servers at the [Docker MCP Catalog](https://hub.docker.com/u/mcp). + +| Property | Type | Description | +| ------------- | ------ | ---------------------------------------------------------------- | +| `ref` | string | Docker MCP reference (`docker:name`) or a name from the [reusable `mcps:`](../../configuration/overview/index.md#reusable-mcp-servers-mcps) block. | +| `tools` | array | Optional whitelist — only expose these tools to the model. | +| `instruction` | string | Custom instructions injected into the agent's context. | +| `config` | any | MCP server-specific configuration passed during initialization. | +| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | + +## Local MCP (stdio) + +Run MCP servers as local processes communicating over stdin/stdout: + +```yaml +toolsets: + - type: mcp + command: python + args: ["-m", "mcp_server"] + tools: ["search", "fetch"] + env: + API_KEY: value +``` + +| Property | Type | Description | +| ------------- | ------ | ----------- | +| `command` | string | Command to execute the MCP server. | +| `args` | array | Command arguments. | +| `tools` | array | Optional whitelist — only expose these tools. | +| `env` | object | Environment variables (key-value pairs). | +| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | +| `instruction` | string | Custom instructions injected into the agent's context. | +| `version` | string | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary. | + +> [!TIP] +> **Auto-installation** +> +> If the `command` is not in your `PATH`, Docker Agent looks it up in the [aqua registry](https://github.com/aquaproj/aqua-registry) and installs it for you. Use `version: "false"` to opt out, or set `DOCKER_AGENT_AUTO_INSTALL=false` globally. See [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools). + +## Remote MCP (Streamable HTTP / SSE) + +Connect to MCP servers over the network. OAuth flows (including [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)) are handled automatically — Docker Agent opens your browser when authentication is required and caches tokens for subsequent sessions. Tokens are refreshed silently when they expire or are revoked server-side; if a silent refresh is not possible, the OAuth prompt reappears on the next message. + +```yaml +toolsets: + - type: mcp + remote: + url: "https://mcp.linear.app/mcp" + transport_type: "streamable" # or "sse" for legacy servers + headers: + Authorization: "Bearer ${env.LINEAR_TOKEN}" + # Optional: allow OAuth helper requests to reach private/internal IPs. + allow_private_ips: false + tools: ["search_issues", "create_issue"] +``` + +| Property | Type | Description | +| ----------------------- | ------- | ----------- | +| `remote.url` | string | Base URL of the MCP server. | +| `remote.transport_type` | string | `streamable` or `sse`. | +| `remote.headers` | object | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. See [Remote MCP Servers](../../features/remote-mcp/index.md#per-request-header-template-expansion) for details. | +| `remote.oauth` | object | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers](../../features/remote-mcp/index.md#oauth-for-servers-without-dynamic-client-registration). | +| `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | + +For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers](../../features/remote-mcp/index.md). + +## MCP Prompts + +MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `/prompts` endpoint. Docker Agent discovers these at toolset startup and registers them as **slash commands** in the TUI, so you can invoke them directly from the input box. + +```text +# Type / to see available prompts alongside built-in commands +/review # invoke an MCP prompt named "review" +/summarize My text here # invoke with the first argument filled in +``` + +**How it works:** + +- Each MCP prompt appears in the command palette (accessible via <kbd>Ctrl</kbd>+<kbd>K</kbd>) under the **MCP Prompts** category. +- Typing `/<prompt-name>` in the input box invokes the prompt immediately. +- If the prompt declares arguments and you provide text after the slash command, that text is mapped to the first declared argument. +- If a required argument is missing, Docker Agent opens the argument input dialog before running the prompt. +- When no argument is needed or all required arguments are supplied, the prompt runs immediately. + +> [!NOTE] +> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`ref: docker:<name>`) are not currently surfaced. + +## Embedded Resources + +MCP tool results can include embedded resources — images, PDFs, and text files returned directly in the tool response. Docker Agent preserves these as attachments and forwards them to the model as native content blocks: + +- **Anthropic** — images become `image` blocks in the `tool_result`; PDFs and other documents become `document` blocks. +- **OpenAI** — images are forwarded as `input_image` data URIs; PDFs as `input_file` data URIs in the tool result content. +- **Bedrock** and **Gemini** — receive equivalent provider-native representations. + +No configuration is required. When an MCP server returns an embedded resource alongside its text output, the resource is automatically attached and sent to the model on the next turn. This is useful for MCP servers that generate charts, export PDFs, or return binary data as part of their responses. + +## Reusable Definitions (`mcps:`) + +Repeated MCP server configurations can be hoisted into the top-level `mcps:` section and referenced by name with `{type: mcp, ref: <name>}`: + +```yaml +mcps: + github: + remote: + url: https://api.githubcopilot.com/mcp + transport_type: sse + playwright: + command: npx + args: ["-y", "@modelcontextprotocol/server-playwright"] + +agents: + root: + model: openai/gpt-5 + toolsets: + - type: mcp + ref: github + - type: mcp + ref: playwright +``` + +See [Reusable MCP Servers](../../configuration/overview/index.md#reusable-mcp-servers-mcps) for the full reference. + +## Common Options + +These properties apply to every MCP toolset regardless of flavour: + +### Tool filtering + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + tools: ["list_issues", "create_issue", "get_pull_request"] +``` + +Whitelisting tools improves model accuracy — fewer choices means less confusion. + +### Deferred loading + +Skip the toolset's startup cost until its tools are actually called: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + defer: true + # Or defer specific tools within a toolset: + - type: mcp + ref: docker:slack + defer: ["list_channels", "search_messages"] +``` + +### Custom instructions + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + instruction: | + Use these tools to manage GitHub issues. + Always check for existing issues before creating new ones. + Label new issues with 'triage' by default. +``` + +### TOON-encoded outputs + +Re-encode verbose JSON outputs as the compact [TOON](https://github.com/alpkeskin/gotoon) format to save context budget. Typically yields 30–60% smaller payloads on list/search tools. + +`toon` is a regex string that is matched against tool names. Any tool whose name matches the pattern has its JSON output transparently re-encoded as TOON before it is shown to the model. The re-encoding reduces schema verbosity, which is especially useful when a model struggles with large or repetitive tool output. + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + toon: ".*" # toonify every tool from this server + - type: mcp + command: my-server + toon: "list_.*,get_.*" # only toonify list_/get_ tools +``` + +The value is a comma-separated list of regexes (or a single regex). A tool name must match at least one pattern to be re-encoded. Setting `toon: ".*"` re-encodes all tools from that toolset. + +See [`examples/github-toon.yaml`](https://github.com/docker/docker-agent/blob/main/examples/github-toon.yaml) for a practical example using the GitHub MCP server. + +### Per-toolset model routing + +Process tool results from this toolset with a different (typically cheaper / faster) model. The override is one-shot — subsequent turns return to the agent's primary model: + +```yaml +toolsets: + - type: mcp + ref: docker:github-official + model: openai/gpt-4o-mini +``` + +See [Per-Toolset Model Routing](../../configuration/tools/index.md#per-toolset-model-routing). + +### Lifecycle (auto-restart, profiles) + +Local stdio and remote MCP servers are supervised: crashed servers reconnect automatically with exponential backoff. **Remote** MCP servers (Streamable HTTP / SSE) also reconnect after idle/clean connection closes — services like Notion and Linear periodically close idle connections, and Docker Agent reconnects transparently. Tune the policy with the `lifecycle` block: + +```yaml +toolsets: + - type: mcp + ref: docker:duckduckgo + lifecycle: + profile: resilient # default; auto-restart with backoff + - type: mcp + command: docker + args: ["mcp", "gateway"] + lifecycle: + profile: strict # fail-fast: required, no retries +``` + +See [Toolset Lifecycle](../../configuration/tools/index.md#toolset-lifecycle) for all profiles and tuning knobs, and [`/toolset-restart`](../../features/tui/index.md) to force a reconnect from the TUI. + +## Combined Example + +```yaml +mcps: + github: + remote: + url: https://api.githubcopilot.com/mcp + transport_type: sse + +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Full-featured developer assistant + instruction: You are an expert developer. + toolsets: + # Docker MCP catalog entry + - type: mcp + ref: docker:duckduckgo + + # Reusable definition from the top-level mcps: block + - type: mcp + ref: github + tools: ["list_issues", "create_issue"] + toon: "list_.*" + + # Local stdio server with auto-install + - type: mcp + command: gopls + version: "golang/tools@v0.21.0" + args: ["mcp"] + + # Remote MCP with OAuth (handled automatically) + - type: mcp + remote: + url: "https://mcp.linear.app/mcp" + transport_type: "streamable" + instruction: Use Linear for issue tracking. +``` + +> [!WARNING] +> **Toolset order matters** +> +> If multiple toolsets provide a tool with the same name, the first one wins: the duplicate from the later toolset is ignored and a warning identifies both toolsets. Order your toolsets intentionally. To keep both tools callable, give the MCP toolset a unique `name:` (its tools are then exposed as `<name>_<tool>`) or restrict the overlapping toolset with its `tools:` filter. + +## See Also + +- [Tool Configuration](../../configuration/tools/index.md) — full reference for every toolset type, plus shared options (lifecycle, TOON, model routing, …). +- [Reusable MCP Servers](../../configuration/overview/index.md#reusable-mcp-servers-mcps) — the top-level `mcps:` block. +- [Remote MCP Servers](../../features/remote-mcp/index.md) — catalog of public remote MCP endpoints + OAuth recipes. +- [MCP Mode](../../features/mcp-mode/index.md) — expose your own agents as MCP tools to Claude Desktop, Claude Code, etc. +- [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools) — automatic installation of MCP server binaries. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md new file mode 100644 index 000000000000..1e5671a304ea --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md @@ -0,0 +1,59 @@ +--- +title: "Memory Tool" +description: "Persistent key-value storage backed by SQLite for cross-session recall." +keywords: docker agent, ai agents, tools, toolsets, memory tool +linkTitle: "Memory" +weight: 100 +canonical: https://docs.docker.com/ai/docker-agent/tools/memory/ +--- + +_Persistent key-value storage backed by SQLite for cross-session recall._ + +## Overview + +The memory tool provides persistent key-value storage backed by SQLite. Data survives across sessions, allowing agents to remember facts, user preferences, project context, and past decisions. Memories can be organized with categories and searched by keyword. + +By default, the database is stored at `~/.cagent/memory/<config-name>/memory.db`, where `<config-name>` is derived from the loaded configuration (typically the YAML file name) and falls back to `default` when unavailable. When the agent is loaded from an OCI reference (e.g. `docker/my-agent:latest`), characters that are reserved in filesystem paths (such as `:`) are sanitised in the `<config-name>` segment — the agent's display name elsewhere is unchanged. Agents declared in the same configuration share this database by default; set an explicit `path` per toolset to isolate them. + +## Available Tools + +| Tool | Description | +| ----------------- | -------------------------------------------------------------------------------- | +| `add_memory` | Store a new memory with optional category | +| `get_memories` | Retrieve all stored memories | +| `delete_memory` | Delete a specific memory by ID | +| `search_memories` | Search memories by keywords and/or category (more efficient than `get_memories`) | +| `update_memory` | Update an existing memory's content and/or category by ID | + +## Configuration + +```yaml +toolsets: + - type: memory +``` + +### Options + +| Property | Type | Default | Description | +| -------- | ------ | ----------------------------------------- | -------------------------------- | +| `path` | string | `~/.cagent/memory/<config-name>/memory.db` | Path to the SQLite database file | + +### Custom Database Path + +```yaml +toolsets: + - type: memory + path: ./agent_memory.db +``` + +## Categories + +Memories support an optional `category` field for organization and filtering. Common categories include: + +- `preference` — User preferences and settings +- `fact` — Factual information about the project or user +- `project` — Project-specific context +- `decision` — Past decisions and their rationale + +> [!TIP] +> Memory is especially useful for long-running assistants that need to recall information across conversations — like coding preferences, project conventions, or context discovered during previous sessions. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md new file mode 100644 index 000000000000..0c0d4613021c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md @@ -0,0 +1,73 @@ +--- +title: "Model Picker Tool" +description: "Let the agent pick between several models per turn." +keywords: docker agent, ai agents, tools, toolsets, model picker tool +linkTitle: "Model Picker" +weight: 200 +canonical: https://docs.docker.com/ai/docker-agent/tools/model-picker/ +--- + +_Let the agent pick between several models per turn._ + +## Overview + +The model picker tool gives an agent the ability to dynamically choose which model to use for each turn of the conversation. This is useful when you want the agent to route different types of requests to different models — for example, using a fast, inexpensive model for simple queries and a more capable model for complex reasoning tasks. + +## Configuration + +```yaml +toolsets: + - type: model_picker + models: + - openai/gpt-5-mini + - anthropic/claude-sonnet-4-5 + - openai/gpt-5 +``` + +### Options + +| Property | Type | Required | Description | +| -------- | -------------- | -------- | ------------------------------------------------------------ | +| `models` | array[string] | ✓ | List of model references the agent can choose from. Use `provider/model` format. | + +## How It Works + +When the model picker toolset is enabled, the agent gets two tools: `change_model` to switch to one of the configured models, and `revert_model` to return to its default model. The agent decides which model to use based on the complexity of the task, cost considerations, or other factors you describe in its instruction. + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini # Default model + instruction: | + You are a helpful assistant. For simple questions, use gpt-5-mini. + For complex reasoning or coding tasks, switch to claude-sonnet-4-5 or gpt-5. + toolsets: + - type: model_picker + models: + - openai/gpt-5-mini + - anthropic/claude-sonnet-4-5 + - openai/gpt-5 +``` + +> [!TIP] +> **Cost optimization** +> +> The model picker tool is particularly useful for cost optimization: let the agent use a cheap model by default and only escalate to expensive models when necessary. + +## Tool Interface + +The toolset exposes two tools: + +### `change_model` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | --------------------------------------------------------------------------- | +| `model` | string | ✓ | The model to switch to. Must be one of the configured models. | + +### `revert_model` + +Takes no parameters. Reverts the agent to its original/default model. + +The switch takes effect immediately: the next inference call — including the remainder of the current agentic loop — uses the new model. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md new file mode 100644 index 000000000000..b2a97dd44b36 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md @@ -0,0 +1,95 @@ +--- +title: "Open URL Tool" +description: "Open a fixed URL in the user's default browser." +keywords: docker agent, ai agents, tools, toolsets, open url tool +linkTitle: "Open URL" +weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/tools/open-url/ +--- + +_Open a fixed URL in the user's default browser._ + +## Overview + +The `open_url` toolset exposes a single, argument-less tool that opens a URL +baked into the toolset definition in the user's default browser. The model +never supplies the URL — it just calls the tool by name. Launching the browser +is cross-platform: Docker Agent uses `open` on macOS, `xdg-open` on Linux, and +`rundll32` on Windows. + +> [!NOTE] +> **When to Use** +> +> - Letting an agent open a dashboard, documentation page, or deep link on demand +> - Deep-linking into a desktop app via a custom URI scheme (e.g. `docker-desktop://`) +> - Any "take me there" action where the destination is fixed and known up front + +## Configuration + +```yaml +agents: + assistant: + model: openai/gpt-4o + description: Assistant that can open the dashboard + instruction: When the user asks to see the dashboard, call open_dashboard. + toolsets: + - type: open_url + name: open_dashboard + url: https://example.com/dashboard +``` + +## Properties + +| Property | Type | Required | Description | +| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | +| `url` | string | ✓ | URL to open. Supports `${env.VAR}` interpolation. Any scheme the OS can dispatch is allowed. | +| `name` | string | ✗ | Tool name the agent references. Defaults to `open_url`. Use a descriptive name when configuring several. | + +## Multiple URLs + +Add one toolset entry per destination, each with its own `name`: + +```yaml +toolsets: + - type: open_url + name: open_dashboard + url: https://example.com/dashboard + - type: open_url + name: open_docs + url: https://docs.example.com/${env.DOCS_VERSION} +``` + +## URL Interpolation + +The `url` field supports `${env.VAR}` placeholders, expanded at call time +against the runtime environment: + +```yaml +toolsets: + - type: open_url + name: open_docs + url: https://docs.example.com/${env.DOCS_VERSION} +``` + +## Custom URI Schemes + +Any scheme the operating system knows how to dispatch works, including deep +links into desktop applications: + +```yaml +toolsets: + - type: open_url + name: open_in_docker_desktop + url: docker-desktop://dashboard/apps +``` + +## Limitations + +- The URL must include a scheme (e.g. `https://`); bare paths are rejected. +- URLs that look like a command-line flag (starting with `-`) are refused to + prevent argument injection into the platform `open` helper. +- The tool opens the URL on the **host** running Docker Agent; in headless or + remote environments where no browser/launcher is available, the call fails + gracefully and reports the error to the agent. + +See [`examples/open_url.yaml`](https://github.com/docker/docker-agent/blob/main/examples/open_url.yaml) for a complete configuration. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md new file mode 100644 index 000000000000..56c0c30561cc --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md @@ -0,0 +1,83 @@ +--- +title: "OpenAPI Tool" +description: "Automatically generate tools from an OpenAPI specification." +keywords: docker agent, ai agents, tools, toolsets, openapi tool +linkTitle: "OpenAPI" +weight: 230 +canonical: https://docs.docker.com/ai/docker-agent/tools/openapi/ +--- + +_Automatically generate tools from an OpenAPI specification._ + +## Overview + +The OpenAPI tool fetches an OpenAPI 3.x specification from a URL and creates one tool per API operation. Each endpoint's parameters, request body, and description are translated into a callable tool that the agent can invoke directly. + +## Configuration + +```yaml +toolsets: + - type: openapi + url: "https://petstore3.swagger.io/api/v3/openapi.json" +``` + +### With custom headers + +Pass custom headers to every HTTP request made by the generated tools (for example, for authentication): + +```yaml +toolsets: + - type: openapi + url: "https://api.example.com/openapi.json" + headers: + Authorization: "Bearer ${env.API_TOKEN}" + X-Custom-Header: "my-value" +``` + +### Custom timeout + +Override the default 30-second HTTP timeout (applies both to fetching the spec and to the generated tool calls): + +```yaml +toolsets: + - type: openapi + url: "https://api.example.com/openapi.json" + timeout: 60 +``` + +### Reaching internal services + +By default the OpenAPI tool refuses connections to non-public IP addresses, blocking SSRF attempts even when DNS resolves an otherwise-public host to an internal range. Opt in with `allow_private_ips` when the spec or its `servers` entries legitimately target localhost or your internal network: + +```yaml +toolsets: + - type: openapi + url: "http://localhost:8080/openapi.json" + allow_private_ips: true +``` + +## Properties + +| Property | Type | Required | Description | +| ------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `url` | string | ✓ | URL of the OpenAPI specification (JSON format). Supports `${env.VAR}` interpolation. | +| `headers` | map[string]string | ✗ | Custom HTTP headers sent with every request — both the spec fetch and every generated tool call. Values support `${env.VAR}` and `${headers.NAME}` placeholders (the latter forwards a header from the caller's incoming request when docker agent is exposed as a server). | +| `timeout` | int | ✗ | HTTP client timeout in seconds (default: `30`). Applies to both the spec fetch and the generated tools' requests. | +| `allow_private_ips` | boolean | ✗ | Opt in to dialling **non-public** IP addresses (loopback, RFC1918, link-local — including the cloud-metadata endpoint at `169.254.169.254` — multicast and the unspecified address). Set to `true` only when the spec or its servers legitimately target internal services. By default such addresses are refused at dial time, after DNS resolution, so DNS rebinding cannot bypass the check. | + +## How it works + +1. The spec is fetched from the configured `url` at startup. +2. Each operation (GET, POST, PUT, …) becomes a separate tool named after its `operationId` (or `method_path` when no `operationId` is set). +3. Path and query parameters are exposed as tool parameters. Request body properties are prefixed with `body_`. +4. Read-only operations (GET, HEAD, OPTIONS) are annotated accordingly. +5. Responses are returned as text; errors include the HTTP status code. + +## Limits + +- The OpenAPI spec must be **10 MB or less**. +- Individual API responses are truncated at **1 MB**. + +## Example + +See the full [Pet Store example](https://github.com/docker/docker-agent/blob/main/examples/openapi-petstore.yaml) for a working agent configuration. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md new file mode 100644 index 000000000000..3f27b0198939 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md @@ -0,0 +1,166 @@ +--- +title: "Plan Tool" +description: "Shared persistent scratchpad for multi-agent collaboration." +keywords: docker agent, ai agents, tools, toolsets, plan tool +linkTitle: "Plan" +weight: 150 +canonical: https://docs.docker.com/ai/docker-agent/tools/plan/ +--- + +_Shared persistent scratchpad for multi-agent collaboration._ + +## Overview + +The plan tool gives agents a shared, persistent scratchpad of named documents. Any agent in a multi-agent config that loads the `plan` toolset can read and write the same plans, and those plans survive across sessions. This makes it straightforward to wire a planner agent that sketches work and one or more executor agents that consume it without any custom tool wiring. + +Plans are stored as JSON files in the Docker Agent data directory (`~/.cagent/plans/` by default). Agents that share a process serialize on a single mutex, and every write or delete additionally holds an advisory lock on a sentinel file in the plans directory, so writers in *separate* Docker Agent processes are serialized too: concurrent edits can never silently overwrite each other, and a stale revision always fails with a deterministic version conflict. Writes are atomic (temp file + rename), so a reader never observes partial content. + +## Configuration + +```yaml +toolsets: + - type: plan +``` + +No additional options are required. All agents that include `type: plan` in their toolsets share the same plans. + +## Available Tools + +| Tool | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------- | +| `write_plan` | Create or update a shared plan by name. Replaces the entire plan content — read it first to preserve what you want to keep. Each write bumps the revision number. | +| `read_plan` | Read a shared plan by name, including its title, content, author, status, revision number, and last-updated timestamp. | +| `list_plans` | List all shared plans with their name, title, author, status, revision, and last-updated timestamp. | +| `delete_plan` | Delete a shared plan by name. | +| `update_plan_from_file` | Create or update a plan, taking the new content from a file on disk instead of inline. Use it with `export_plan_to_file` to edit a large plan without re-sending its whole body. | +| `export_plan_to_file` | Write a plan's content to a file. The content goes to disk and is **not** returned as tool output, so materialising a plan costs no tokens. | +| `set_plan_status` | Set a plan's free-form status without rewriting its body. The plan must already exist. | +| `get_plan_status` | Read a plan's status and current revision without fetching its body. | + +### Cheap edits with file-based revisions + +Re-sending a whole plan on every revision is expensive. The file-based tools let +an agent edit a plan without paying input-token cost for its body: + +1. `export_plan_to_file` writes the current plan content to a path. The content + is written to disk and is **not** returned. +2. The agent edits that file in place with its filesystem tools. +3. `update_plan_from_file` commits the file's new contents as the next revision. + +### Free-form status + +Each plan carries a free-form `status` string. There is no fixed vocabulary: +define your own in the system prompt (e.g. `idle`, `in-progress`, `blocked`, +`done`, `canceled`). Read and write it independently of the body with +`get_plan_status` and `set_plan_status`, or pass `status` to `write_plan` and +`update_plan_from_file`. The TUI surfaces the status next to the plan title. + +### Optimistic locking + +When several sessions edit the same plan, concurrent writes could silently +overwrite each other. Every read returns a `revision` number; pass the value you +last read as `last_known_revision` to `write_plan`, `update_plan_from_file`, +`set_plan_status`, or `delete_plan`. If the plan changed since (its current +revision no longer matches), the write is rejected with a version-conflict +error and the caller should re-read the plan and retry. The revision check and +the write happen under the storage's cross-process file lock, so the conflict +is detected reliably even when the competing writer runs in a different Docker +Agent process. Omit `last_known_revision` to write unconditionally (last +writer wins). + +### Plan Names + +Plan names must match the pattern `[a-z0-9][a-z0-9_-]*` (lowercase letters, digits, `-`, `_`). This is enforced structurally so two different inputs can never collapse onto the same file and path-traversal is impossible by construction. + +### Plan Fields + +Each plan document contains: + +| Field | Description | +| ---------- | --------------------------------------------------------- | +| `name` | The plan's unique slug name | +| `title` | A short human-readable title (optional) | +| `content` | The full Markdown or free-form plan text | +| `author` | Free-form label identifying who last wrote the plan | +| `status` | Free-form lifecycle label (optional), e.g. `in-progress` | +| `revision` | Monotonically increasing version counter, bumped on every write | +| `updatedAt`| ISO 8601 timestamp of the last write | + +## Example + +Two agents collaborate on a shared plan — the architect drafts it and the builder refines it: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Coordinator + instruction: | + Route work between the architect and the builder. + handoffs: [architect, builder] + + architect: + model: anthropic/claude-sonnet-4-5 + description: Drafts high-level plans + instruction: | + Use list_plans and read_plan to inspect existing plans, then write_plan + to create or revise one. Always read before writing. When done, hand off + to the builder. + toolsets: + - type: plan + handoffs: [builder] + + builder: + model: openai/gpt-4o + description: Adds implementation steps to plans + instruction: | + Read the architect's plan with read_plan, then use write_plan to append + concrete implementation steps. Always read before writing. When done, + hand off back to root. + toolsets: + - type: plan + handoffs: [root] +``` + +See [`examples/shared_plan.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shared_plan.yaml) for a complete working example. + +## Error Handling + +- `read_plan` returns a distinct "not found" error when a plan does not exist, as opposed to any other I/O error, so callers can tell "plan missing" from "plan unreadable." +- `list_plans` skips corrupt entries but reports them in a `warnings` field so an agent can detect and recover from a bad state (e.g., by calling `delete_plan`). +- `delete_plan` can remove a corrupt plan to recover from a bad state. + +## Managing plans from the host + +Shared plans can also be inspected and managed outside a session with the [`docker agent plans`](../../features/cli/index.md#docker-agent-plans) command group: list, get, create, update, set status, export, and delete — with the same optimistic-locking semantics as the tools (`--expected-version` guards a write and a stale version fails with exit code 3; `--force` writes unconditionally). Session plans (the per-session "draft, review, execute" plan) can be listed, read, and exported through the same commands but stay owned by their session and cannot be mutated from the host. + +```bash +$ docker agent plans list +$ docker agent plans get release > plan.md +$ docker agent plans update release --file ./plan.md --expected-version 1 +``` + +### The `/plans` browser in the TUI + +Inside the full-screen TUI, the `/plans` slash command (also in the <kbd>Ctrl</kbd>+<kbd>K</kbd> command palette) opens a plan browser over the same store the agents use, so changes made by agents mid-session appear immediately. The list shows every shared plan plus the current session's [session plan](../session_plan/index.md), with each plan's scope, identity (name, or session ID for the session plan), status, version (`-` for the unversioned session plan), last update time, and title. + +Keybindings: + +| Key | Action | +| --- | ------ | +| <kbd>↑</kbd>/<kbd>↓</kbd>, mouse | Navigate; <kbd>Enter</kbd> or double-click opens a detail view with the full metadata and scrollable markdown content | +| <kbd>/</kbd> | Filter by name, title, status, or scope (<kbd>Esc</kbd> leaves filter mode) | +| <kbd>r</kbd> | Refresh from storage | +| <kbd>x</kbd> | Export the selected plan to `<name>.md` (shared) or `session-plan-<short-id>.md` (session) in the session's working directory. An existing file is never overwritten — the export fails with a notification instead | +| <kbd>s</kbd> | Set a shared plan's free-form status via a small input dialog | +| <kbd>e</kbd> | Edit a shared plan's content in `$VISUAL`/`$EDITOR` | +| <kbd>n</kbd> | Create a new shared plan: pick a name, then draft the content in `$VISUAL`/`$EDITOR` (an empty draft aborts) | +| <kbd>d</kbd> | Delete a shared plan after a confirmation that names the plan and its version | +| <kbd>Esc</kbd> | Close the detail view / the browser | + +Every mutation is guarded by the version shown on screen (the same optimistic locking as `last_known_revision`): if an agent changed the plan in the meantime, the write is rejected, a notification reports the current version, the newer content is left intact and re-read into the browser, and an edit draft is kept in a temp file so nothing is lost. Session plans are read-only here — status, edit, and delete report why instead of attempting the write. The browser also refreshes live when agents in the same process write, re-status, or delete plans (and when this session's agent updates its session plan); in the lean TUI, which has no overlays, `/plans` is unavailable. + +> [!TIP] +> **Plan vs. Todo vs. Tasks** +> +> Use **plan** for shared, free-form documents that multiple agents collaborate on (design docs, requirements, work items). Use [todo](../todo/index.md) for lightweight in-session task lists. Use [tasks](../tasks/index.md) for a structured, persistent task database with priorities and dependencies. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md new file mode 100644 index 000000000000..0aa77a99350f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md @@ -0,0 +1,267 @@ +--- +title: "RAG Tool" +description: "Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search." +keywords: docker agent, ai agents, tools, toolsets, rag tool +linkTitle: "RAG" +weight: 110 +canonical: https://docs.docker.com/ai/docker-agent/tools/rag/ +aliases: + - /ai/docker-agent/rag/ +--- + +_Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search._ + +## Overview + +The `rag` toolset lets agents search through your documents to find relevant information before responding. Knowledge bases are declared once at the top of the config under `rag:` and then referenced from any agent via `type: rag, ref: <name>`. Docker Agent supports: + +- **Background indexing** — Files are indexed automatically and re-indexed on change +- **Multiple strategies** — Semantic embeddings, BM25 keyword search, and LLM-enhanced search +- **Hybrid search** — Combine strategies with result fusion for best results +- **Reranking** — Re-score results with specialized models for improved relevance + +RAG is the strategy to reach for when a document collection is too large to inline directly, or gets queried repeatedly across turns/sessions — see [Choosing a Large-Input Strategy](../../guides/headless/index.md#choosing-a-large-input-strategy) for how it compares to `@`/`/attach` attachments and prompt files. + +## Quick Start + +```yaml +rag: + my_docs: + tool: + description: "Technical documentation" + docs: [./documents, ./some-doc.md] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + database: ./docs.db + vector_dimensions: 1536 + +agents: + root: + model: openai/gpt-4o + instruction: | + You have access to a knowledge base. Use it to answer questions. + toolsets: + - type: rag + ref: my_docs +``` + +## Retrieval Strategies + +### Chunked Embeddings (Semantic Search) + +Uses embedding models to find semantically similar content. Best for understanding intent, synonyms, and paraphrasing. + +```yaml +strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + database: ./vector.db + vector_dimensions: 1536 + similarity_metric: cosine_similarity + threshold: 0.5 + limit: 10 + embedding_batch_size: 50 + chunking: + size: 1000 + overlap: 100 +``` + +### Semantic Embeddings (LLM-Enhanced) + +Uses an LLM to generate semantic summaries of each chunk before embedding, capturing meaning and intent. Best for code search and understanding implementations. + +```yaml +strategies: + - type: semantic-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + chat_model: openai/gpt-4o-mini + database: ./semantic.db + ast_context: true # include AST metadata + chunking: + size: 1000 + code_aware: true # AST-aware chunking +``` + +> [!NOTE] +> **Trade-offs** +> +> Semantic embeddings provide higher quality retrieval but slower indexing (LLM call per chunk) and additional API costs. + +### BM25 (Keyword Search) + +Traditional keyword matching using the BM25 algorithm. Best for exact terms, technical jargon, and code identifiers. + +```yaml +strategies: + - type: bm25 + database: ./bm25.db + k1: 1.5 # term frequency saturation + b: 0.75 # length normalization + threshold: 0.3 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +## Hybrid Search + +Combine multiple strategies for best results. Strategies run in parallel and results are fused together: + +```yaml +rag: + hybrid: + docs: [./docs] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + database: ./vector.db + vector_dimensions: 1536 + limit: 20 + chunking: { size: 1000, overlap: 100 } + - type: bm25 + database: ./bm25.db + limit: 15 + chunking: { size: 1000, overlap: 100 } + results: + fusion: + strategy: rrf # Reciprocal Rank Fusion + k: 60 + deduplicate: true + limit: 5 +``` + +## Fusion Strategies + +| Strategy | Best For | Description | +| ---------- | --------------------------------- | ------------------------------------------------------------------ | +| `rrf` | General use (recommended) | Reciprocal Rank Fusion — rank-based, no score normalization needed | +| `weighted` | Known performance characteristics | Weight strategies differently (e.g., embeddings: 0.7, BM25: 0.3) | +| `max` | Same scoring scale | Takes the maximum score from any strategy | + +## Reranking + +Re-score retrieved documents with a specialized model to improve relevance: + +```yaml +results: + reranking: + model: openai/gpt-4o-mini + top_k: 10 # only rerank top 10 + threshold: 0.3 # minimum score after reranking + criteria: | + Prioritize official documentation over blog posts. + Prefer recent information and practical examples. + limit: 5 +``` + +Supported reranking providers: **DMR** (native `/rerank` endpoint), **OpenAI**, **Anthropic**, **Gemini**. + +## Code-Aware Chunking + +For source code, enable AST-based chunking to keep functions and methods intact: + +```yaml +chunking: + size: 2000 + code_aware: true # Uses tree-sitter for AST-based chunking +``` + +> [!NOTE] +> **Language Support** +> +> Currently supports Go (`.go`) files. More languages will be added. Falls back to plain text chunking for unsupported file types. + +## Debugging RAG + +Enable debug logging to see retrieval details: + +```bash +$ docker agent run config.yaml --debug --log-file debug.log +``` + +Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Strategy]`, `[RRF Fusion]`, `[Reranker]`. + +**Permanent model errors abort early.** If the embedding model, semantic-LLM model, or reranking model returns a permanent error (HTTP 400, 401, 404, or 429 — invalid config, bad auth, unknown model, or rate limit), Docker Agent treats the model configuration as invalid and stops immediately rather than retrying doomed requests: + +- **Indexing** — the entire indexing run is aborted after the first permanent failure (including 429). The error is surfaced in the logs so you know immediately if a model name or API key is wrong, rather than silently producing incomplete results. +- **Reranking** — a permanent error (including 429) permanently disables the reranker for the lifetime of the manager. Subsequent queries fall back to un-reranked results. Only transient errors (5xx, timeouts) fall back and retry on the next query. + +> [!TIP] +> **Examples** +> +> See the [RAG examples](https://github.com/docker/docker-agent/tree/main/examples/rag) in the GitHub repo for complete, runnable configurations. + +## Configuration Reference + +### Top-Level RAG Fields + +| Field | Type | Default | Description | +| ------------- | -------- | ------- | -------------------------------------------------------------- | +| `docs` | []string | — | Document paths/directories (shared across strategies) | +| `description` | string | — | Human-readable description of this RAG source | +| `respect_vcs` | boolean | `true` | Respect `.gitignore` files when indexing documents | +| `strategies` | []object | — | Array of retrieval strategy configurations | +| `results` | object | — | Post-processing: fusion, reranking, deduplication, final limit | + +### Chunked-Embeddings Strategy + +| Field | Type | Default | Description | +| --------------------------- | ------ | ------------------- | ------------------------------------------------------------ | +| `embedding_model` | string | — | **Required.** Embedding model reference | +| `database` | string | — | Path to local SQLite database | +| `vector_dimensions` | int | — | Embedding dimensions (e.g., 1536 for text-embedding-3-small) | +| `similarity_metric` | string | `cosine_similarity` | Similarity metric | +| `threshold` | float | `0.5` | Minimum similarity score (0–1) | +| `limit` | int | `5` | Max results from this strategy | +| `embedding_batch_size` | int | `50` | Chunks per embedding request | +| `max_embedding_concurrency` | int | `3` | Max concurrent embedding requests | +| `chunking.size` | int | `1500` | Chunk size in characters (`4000` when `code_aware` is set) | +| `chunking.overlap` | int | `75` | Overlap between chunks in characters | +| `chunking.code_aware` | bool | `false` | AST-based chunking (Go files only) | + +### Semantic-Embeddings Strategy + +| Field | Type | Default | Description | +| -------------------------- | ------ | ---------- | ------------------------------------------------------------------ | +| `embedding_model` | string | — | **Required.** Embedding model reference | +| `chat_model` | string | — | **Required.** LLM for generating semantic summaries | +| `vector_dimensions` | int | — | **Required.** Embedding dimensions | +| `database` | string | — | Path to local SQLite database | +| `semantic_prompt` | string | (built-in) | Custom prompt template (`${path}`, `${content}`, `${ast_context}`) | +| `ast_context` | bool | `false` | Include tree-sitter AST metadata in prompts | +| `threshold` | float | `0.5` | Minimum similarity score (0–1) | +| `limit` | int | `5` | Max results | +| `max_indexing_concurrency` | int | `3` | Max concurrent file indexing | +| `chunking.size` | int | `1500` | Chunk size in characters (`4000` when `code_aware` is set) | +| `chunking.overlap` | int | `75` | Overlap between chunks | +| `chunking.code_aware` | bool | `false` | AST-based chunking | + +### BM25 Strategy + +| Field | Type | Default | Description | +| ------------------ | ------ | ------- | ----------------------------------------------- | +| `database` | string | — | Path to local SQLite database | +| `k1` | float | `1.5` | Term frequency saturation (1.2–2.0 recommended) | +| `b` | float | `0.75` | Length normalization (0–1) | +| `threshold` | float | `0.0` | Minimum BM25 score | +| `limit` | int | `5` | Max results | +| `chunking.size` | int | `1500` | Chunk size in characters | +| `chunking.overlap` | int | `75` | Overlap between chunks | + +### Results (Post-Processing) + +| Field | Type | Default | Description | +| --------------------- | ------ | ------- | ----------------------------------------------------------- | +| `fusion.strategy` | string | `rrf` | Fusion method: `rrf`, `weighted`, or `max` | +| `fusion.k` | int | `60` | RRF rank constant | +| `deduplicate` | bool | `true` | Remove duplicate results | +| `limit` | int | `15` | Final number of results | +| `include_score` | bool | `false` | Include relevance scores in results | +| `return_full_content` | bool | `false` | Return full document content instead of just matched chunks | +| `reranking.model` | string | — | Reranking model reference | +| `reranking.top_k` | int | (`limit`) | Only rerank top K results. Defaults to the results `limit` when set. | +| `reranking.threshold` | float | `0.5` | Minimum relevance score after reranking | +| `reranking.criteria` | string | — | Custom relevance guidance for the reranking model | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md new file mode 100644 index 000000000000..16635f7f77f2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md @@ -0,0 +1,96 @@ +--- +title: "Scheduler Tool" +description: "Schedule instructions to run at a time or on a recurring interval." +keywords: docker agent, ai agents, tools, toolsets, scheduler tool, cron +linkTitle: "Scheduler" +weight: 135 +canonical: https://docs.docker.com/ai/docker-agent/tools/scheduler/ +--- + +_Schedule instructions to run at a time or on a recurring interval._ + +## Overview + +The scheduler toolset lets an agent make something happen at a chosen time or on a repeating cadence during a session. You give it an instruction and a schedule; when the schedule is due, the instruction is delivered back to the agent, which then carries out the action with its normal tools (`shell`, `api`, `fetch`, and so on). + +The scheduler does not run shell or API calls itself. When a schedule fires it injects the instruction into the agent loop via the runtime's recall mechanism — the same primitive [`background_jobs`](../background-jobs/index.md) uses to report completed work — and the agent decides how to act. This keeps every action under the agent's normal tools and permissions rather than adding a second, unattended +command runner. + +> [!NOTE] +> Schedules only fire while the session is running (interactive TUI or a server mode) and are not persisted across restarts. Scheduling requires a host that supports recall; if it does not, `create_schedule` returns an error. + +## Configuration + +```yaml +toolsets: + - type: scheduler +``` + +No configuration options. + +## Tools + +| Tool | Description | +| --- | --- | +| `create_schedule` | Register an instruction to run at a time or interval. | +| `list_schedules` | List active schedules with their id, spec, and next fire time. | +| `cancel_schedule` | Remove a schedule by id. | + +### `create_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `prompt` | Yes | The instruction to deliver to the agent when the schedule fires. | +| `when` | Yes | When to fire (see [Schedule specs](#schedule-specs)). | +| `name` | No | Optional human-readable label. | + +Returns the new schedule's id and its next fire time. + +### `cancel_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `id` | Yes | The id of the schedule to cancel (from `create_schedule` or `list_schedules`). | + +## Schedule specs + +The `when` argument accepts: + +| Form | Meaning | Example | +| --- | --- | --- | +| `in:<duration>` | One-shot, after a delay | `in:10m` | +| `at:<RFC3339>` | One-shot, at an absolute future time | `at:2026-07-14T09:00:00Z` | +| `every:<duration>` | Recurring, at a fixed interval | `every:1h` | +| `minutely` / `hourly` / `daily` / `weekly` | Recurring preset intervals | `hourly` | + +Durations use Go's duration syntax (`30s`, `15m`, `2h`). Preset and `every:` intervals are measured from the schedule's creation time (for example `hourly` fires every hour after it is created), not aligned to wall-clock slots. + +> [!IMPORTANT] +> **Recurring schedules have a one-minute minimum.** Every fire injects a message into the agent loop and typically costs an LLM turn, so `every:` values below `1m` are rejected — a typo such as `every:1s` in place of `every:1h` would otherwise become a runaway token burn. One-shot schedules (`in:` / `at:`) are not restricted, since they fire once. + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini + description: A monitoring assistant + instruction: | + Every 15 minutes, run `git fetch` and tell me if origin/main moved. + toolsets: + - type: scheduler + - type: shell +``` + +The agent calls: + +```text +create_schedule(prompt="Run git fetch and report if origin/main moved", when="every:15m") +``` + +Every 15 minutes it is reminded, runs the command with the `shell` tool, and reports back. + +> [!TIP] +> **When to use** +> +> Use the scheduler for recurring monitoring, timed one-shots, and unattended housekeeping loops during a long-running session. For work that should run immediately and be awaited, use [`background_jobs`](../background-jobs/index.md) instead. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md new file mode 100644 index 000000000000..b4f912705517 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md @@ -0,0 +1,64 @@ +--- +title: "Script Tool" +description: "Define custom shell scripts as named tools with typed parameters." +keywords: docker agent, ai agents, tools, toolsets, script tool +linkTitle: "Script" +weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/tools/script/ +--- + +_Define custom shell scripts as named tools with typed parameters._ + +## Overview + +The script tool lets you define custom shell scripts as named tools. Unlike the generic [shell tool](../shell/index.md) where the agent writes the command, script tools execute predefined commands — ideal for exposing safe, well-scoped operations with descriptive names. + +## Configuration + +### Simple Scripts + +```yaml +toolsets: + - type: script + shell: + run_tests: + cmd: task test + description: Run the project test suite + lint: + cmd: task lint + description: Run the linter +``` + +### Scripts with Parameters + +Use `${param}` interpolation and JSON Schema to define typed arguments: + +```yaml +toolsets: + - type: script + shell: + deploy: + cmd: ./scripts/deploy.sh ${env} + description: Deploy to an environment + args: + env: + type: string + enum: [staging, production] + required: [env] +``` + +## Properties + +| Property | Type | Description | +| --------------------------------- | ------ | ---------------------------------------------------------- | +| `shell.<name>.cmd` | string | Shell command to execute (supports `${arg}` interpolation) | +| `shell.<name>.description` | string | Description shown to the model | +| `shell.<name>.args` | object | Parameter definitions (JSON Schema properties) | +| `shell.<name>.required` | array | Required parameter names | +| `shell.<name>.env` | object | Environment variables for this script | +| `shell.<name>.working_dir` | string | Working directory for script execution | + +> [!TIP] +> **Script vs. Shell** +> +> Use the [shell tool](../shell/index.md) when the agent needs to run arbitrary commands. Use the script tool when you want to expose specific, predefined operations with clear names and typed parameters — giving the agent less freedom but more safety. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md new file mode 100644 index 000000000000..9f241bb551db --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md @@ -0,0 +1,67 @@ +--- +title: "Session Context Tool" +description: "Reference a previous session as context in the current one." +keywords: docker agent, ai agents, tools, toolsets, session context tool +linkTitle: "Session Context" +weight: 210 +canonical: https://docs.docker.com/ai/docker-agent/tools/session_context/ +--- + +_Reference a previous session as context, without manual export/import._ + +## Overview + +The `session_context` toolset lets an agent discover earlier sessions and pull one in as context for the current session. It removes the manual workaround of exporting a conversation to HTML and re-attaching it with an `@` mention. + +The tool surface is two read-only tools: + +| Tool | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------ | +| `list_sessions` | List previous sessions (most recent first) with id, title, creation time and message count. | +| `read_session` | Return the transcript of a previous session, by id or by a relative reference like `-1`. | + +The session the agent is currently running in is never listed by `list_sessions` and cannot be read by `read_session` (a circular reference returns an error). + +## Configuration + +```yaml +toolsets: + - type: session_context +``` + +No configuration options. Both tools are read-only and operate against the same session store the runtime already uses for persistence. + +Restrict the toolset to a subset of tools the standard way: + +```yaml +# An agent that may browse but never pull a full transcript into context. +toolsets: + - type: session_context + tools: + - list_sessions +``` + +## Selecting a session + +`read_session` accepts either form: + +- A concrete id returned by `list_sessions`, e.g. `read_session("a1b2c3...")`. +- A relative reference: `-1` is the most recent session, `-2` the second most recent, and so on. Relative references resolve against the same ordering `list_sessions` uses (most recent first), excluding sub-sessions. + +## Transcript size + +A long session could overflow the current context window, so `read_session` caps the rendered transcript. When a transcript is larger than the budget, the oldest messages are dropped (the most recent are usually the most useful for continuing work) and a note records how many were omitted: + +```text +[12 earlier message(s) omitted to fit the context budget; showing the most recent 8] +``` + +## Notes + +- `list_sessions` defaults to 20 sessions and is capped at 100; pass `limit` to request fewer. +- `read_session` returns an error when the session is not found, when the reference cannot be resolved, or when it points at the current session. +- Both tools are read-only: they never modify, branch, or delete sessions. + +## Example + +See [`examples/session_context.yaml`](https://github.com/docker/docker-agent/blob/main/examples/session_context.yaml) for a complete working example. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md new file mode 100644 index 000000000000..ea4c8e4970f0 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md @@ -0,0 +1,134 @@ +--- +title: "Session Plan Tool" +description: "Per-session plan tracker for the draft, review, execute workflow." +keywords: docker agent, ai agents, tools, toolsets, session plan tool +linkTitle: "Session Plan" +weight: 160 +canonical: https://docs.docker.com/ai/docker-agent/tools/session_plan/ +--- + +_Per-session plan tracker for the "draft, review, execute" workflow._ + +## Overview + +The `session_plan` toolset gives one agent a place to write a plan for the current session, signal that the plan is ready, and let the host route the next turn to an executing agent. + +Different from the [`plan` toolset](../plan/index.md) — `plan` is for shared, named plans multiple agents collaborate on over many sessions. `session_plan` is for one ephemeral plan per session, scoped to that session by ID. + +Plans live as Markdown files under: + +```text +~/.cagent/session_plans/<session-id>.md +``` + +The tool surface is three tools: + +| Tool | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------- | +| `write_session_plan` | Create or replace this session's plan as markdown. There's exactly one plan per session. | +| `read_session_plan` | Read the plan written for the current session and return it as markdown. | +| `exit_plan_mode` | Signal that the plan is ready for review. Does not switch agents on its own. | + +## Configuration + +```yaml +toolsets: + - type: session_plan +``` + +No configuration options. The plan path is derived from the session ID; the agent does not name plans. + +Restrict the toolset to a subset of tools the standard way: + +```yaml +# An agent that consumes a plan but should not be able to (re)write or finalize one. +toolsets: + - type: session_plan + tools: + - read_session_plan +``` + +## When to call exit_plan_mode + +Call `exit_plan_mode` once the plan is complete and you do not intend to change it on the next turn. It validates that a plan exists for the session and returns a "ready for review" tool result. It does **not** switch agents or solicit user approval on its own — the host application owns the next-turn routing (for example, by reading the tool result, by a UI affordance the user toggles, or by a `handoff` declared on the agent). + +This separation keeps the tool reusable across UIs: a CLI that prints tool results inline, a chat UI with a plan-mode toggle, and a server that auto-routes the next turn through a `handoff` can all consume the same signal without one stepping on another. + +## Storage and cleanup + +- Plans are markdown files written atomically (temp + rename), so concurrent readers — in this process or another — never observe a partial write. +- A best-effort sweep on first use of the toolset removes plan files older than 30 days under the plans directory. Stranded plans for long-gone sessions do not accumulate. +- The session ID identifies the file directly. There is no in-process mutex or revision counter, because two sessions cannot map to the same path. + +## Events + +A `session_plan_updated` event is emitted whenever `write_session_plan` succeeds: + +```json +{ + "type": "session_plan_updated", + "session_id": "...", + "path": "/Users/.../.cagent/session_plans/<session-id>.md", + "content": "# my plan\n...", + "agent_name": "planner" +} +``` + +Embedders that render the plan inline can subscribe and update without re-reading the file. + +## Managing session plans from the host + +A session plan belongs to its session: hosts can read and export it, never change it. + +- **CLI** — the [`docker agent plans`](../../features/cli/index.md#docker-agent-plans) command group lists, reads (`get --session <session-id>`), and exports session plans alongside shared plans. Mutations (`update`, `status`, `delete`) are refused with an `unsupported` error explaining the ownership rule. +- **TUI** — the `/plans` browser (see the [plan toolset docs](../plan/index.md#the-plans-browser-in-the-tui) for the full keybinding table) includes the **current session's** plan as the `session` scope row; plans of other sessions are never enumerated. Its identity is the session ID and its version column shows `-` — session plans have no versions. <kbd>Enter</kbd> opens the detail view (scope, session ID, update time, scrollable markdown) and <kbd>x</kbd> exports to `session-plan-<short-id>.md` in the working directory (refusing to overwrite an existing file). <kbd>e</kbd> opens the plan body in your external editor (`$VISUAL` or `$EDITOR`) for editing — the write is unguarded and last-write-wins by design. Status and delete visibly report that session plans don't support them (session plans belong to their session and carry no shared-plan metadata). The browser refreshes live on the `session_plan_updated` event, so a plan the agent just wrote appears without reopening. + +## Example + +A two-agent workflow: `root` executes, `planner` plans. `/plan` hands off to the planner; `exit_plan_mode` signals "ready", and the host decides what happens next. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Executes approved plans + instruction: | + You execute plans the planner has handed off. When you see a message + that a plan has been approved, read it with read_session_plan and work + through its steps in order. + toolsets: + - type: session_plan + tools: + - read_session_plan + - type: filesystem + - type: shell + commands: + plan: + description: "Switch to the planner" + agent: planner + + planner: + model: anthropic/claude-sonnet-4-5 + description: Investigates and writes plans for review + instruction: | + Investigate the user's request, then write the plan with + write_session_plan. Iterate with the user until the plan is complete, + then call exit_plan_mode to mark it ready for review. + toolsets: + - type: session_plan + - type: filesystem + readonly: true + - type: user_prompt +``` + +See [`examples/session_plan.yaml`](https://github.com/docker/docker-agent/blob/main/examples/session_plan.yaml) for a complete working example. + +## Error Handling + +- `read_session_plan` and `exit_plan_mode` return a "no plan written yet" error when called before `write_session_plan`. +- `write_session_plan` validates the session ID and refuses to write anything that could escape the plans directory; in practice the runtime generates UUIDs so this only triggers if an embedder supplies a hand-crafted ID. + +> [!TIP] +> **session_plan vs. plan vs. todo vs. tasks** +> +> Use **session_plan** when one agent drafts an approach for the user to review before another agent executes it (ephemeral, one per session). Use [plan](../plan/index.md) for shared, named plans multiple agents collaborate on over many sessions. Use [todo](../todo/index.md) for lightweight in-session task lists. Use [tasks](../tasks/index.md) for a structured, persistent task database with priorities and dependencies. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md new file mode 100644 index 000000000000..5da9fc8f8233 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md @@ -0,0 +1,117 @@ +--- +title: "Shell Tool" +description: "Execute arbitrary shell commands in the user's environment." +keywords: docker agent, ai agents, tools, toolsets, shell tool +linkTitle: "Shell" +weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/tools/shell/ +--- + +_Execute arbitrary shell commands in the user's environment._ + +## Overview + +The shell tool allows agents to execute arbitrary shell commands synchronously. This is one of the most powerful tools — it lets agents run builds, install dependencies, query APIs, and interact with the system. Each call runs in a fresh, isolated shell session — no state persists between calls. + +Commands have a default 30-second timeout and require user confirmation unless `--yolo` is used. For servers, watchers, and other long-running commands, add the [`background_jobs`](../background-jobs/index.md) toolset alongside `shell`. + +### Shell interpreter detection + +The shell tool automatically detects and names the resolved shell interpreter (e.g., `bash`, `zsh`, `powershell`, `pwsh`, `cmd`) in its description to the model, along with the operating system (Linux, macOS, Windows). This helps models use the correct shell syntax for the host environment. + +For example: + +- On Linux with bash: "Executes the given shell command with bash on Linux." +- On Windows with PowerShell: "Executes the given shell command with powershell on Windows. Use Windows PowerShell 5.1 syntax: chain commands with ";" (not "&&"), and avoid POSIX commands/flags like "ls -la"." + +This reduces wasted turns where models assume POSIX syntax on Windows or vice versa. + +## Configuration + +```yaml +toolsets: + - type: shell +``` + +### Options + +| Property | Type | Description | +| -------------- | ------- | --------------------------------------------------------------------------------------------------- | +| `env` | object | Environment variables to set for all shell commands | +| `safer` | boolean | Deprecated and ignored — shell commands are always classified now (see [Command classification](#command-classification)). Kept so existing YAMLs still parse. | +| `sudo_askpass` | boolean | Opt in to prompting for a `sudo` password (see [Sudo support](#sudo-support)). Default `false`. | + +### Custom Environment Variables + +```yaml +toolsets: + - type: shell + env: + MY_VAR: "value" + PATH: "${env.PATH}:/custom/bin" +``` + +### Command classification + +Every shell command is classified against an embedded taxonomy before the approval decision — no opt-in required: + +- **Destructive matches** (`rm -rf <path>`, `docker volume rm`, `mkfs`, `dd if=… of=/dev/<disk>`, …) are labelled `destructive` with a `blast_radius` (`low` / `medium` / `high`) and a `category` tag. The TUI confirmation dialog renders the blast radius with a color badge. +- **Known-safe reads** (`ls`, `cat`, `git status`, `git diff`, `docker ps`, `docker logs`, `kubectl get`, …) are labelled `safe`. +- **Everything else** is labelled `unknown`. + +The session's [safety mode](../../configuration/permissions/index.md#safety-modes) decides what each label means: `strict` asks about everything, `balanced` auto-runs safe commands and asks about destructive/unknown ones, `restricted` auto-runs safe commands and denies destructive/unknown ones without asking (fail-closed for unattended runs), `autonomous` runs everything. Custom permission rules always win over the mode. + +Compound shell (`a && b`, `a; b`, `a | b`) is never matched against the safe allowlist; any destructive segment falls through to ask. The full taxonomy lives in [`pkg/safety/safety_patterns.json`](https://github.com/docker/docker-agent/blob/main/pkg/safety/safety_patterns.json). + +See [`examples/safety_modes.yaml`](https://github.com/docker/docker-agent/blob/main/examples/safety_modes.yaml) for a full example. The legacy `safer: true` toolset flag is deprecated and ignored. + +### Sudo support + +By default a shell command has no controlling terminal, so a `sudo` command that needs a password hangs until it times out (the agent usually gives up and falls back to printing manual instructions). + +Set `sudo_askpass: true` to enable a sudo privilege escalation flow: + +```yaml +toolsets: + - type: shell + sudo_askpass: true +``` + +When enabled, `sudo` commands prompt you for your password through the host UI (the input is masked). The password is handed to `sudo` over a private, per-session socket via the standard `SUDO_ASKPASS` mechanism — it is never written to the command line, the logs, or stored by the agent. + +The bridge environment variables (`SUDO_ASKPASS`, `CAGENT_ASKPASS_SOCKET`, `CAGENT_ASKPASS_TOKEN`) are added only to commands that invoke `sudo`, but within such a command they are visible to every child process, not just `sudo`. They carry a socket path and a session token, not the password; the socket lives in a `0700` directory, so only your own user can reach it. + +Notes and limitations: + +- Unix only. The flag has no effect on Windows. +- Interactive UI only. In headless / non-interactive runs the prompt is declined automatically and `sudo` fails as before. +- Only a bare `sudo ...` invocation in a POSIX shell (`sh`, `bash`, `zsh`, ...) is handled. `sudo` called by absolute path (`/usr/bin/sudo`), via `env sudo`, from inside a nested script, or under a non-POSIX shell (e.g. `fish`) is not intercepted and behaves as before. +- Caching is `sudo`'s own. Because each shell tool call runs in a fresh shell with no controlling terminal, `sudo`'s credential cache does not persist across separate tool calls: you are prompted once per shell command that uses `sudo`. Within a single command, multiple `sudo` calls (e.g. `sudo a && sudo b`) usually share one prompt, subject to `sudo`'s own timestamp configuration. +- The prompt must be answered within the command's timeout; raise the `timeout` parameter for `sudo` commands that may wait on input. +- Prompts are serialized: if a single command runs two `sudo` calls in parallel (e.g. `sudo a & sudo b`), the second waits for the first prompt to be answered rather than opening two dialogs at once. + +## Available Tools + +The shell toolset exposes one tool: + +| Tool Name | Description | +| --------- | ---------------------------------------------------------------------------- | +| `shell` | Run a command synchronously and return its combined output when it finishes. | + +### `shell` parameters + +| Parameter | Type | Required | Description | +| --------- | ------- | -------- | ------------------------------------------------------------------------- | +| `cmd` | string | ✓ | The shell command to execute. | +| `cwd` | string | ✗ | Working directory to run the command in (default: `.`). | +| `timeout` | integer | ✗ | Per-call execution timeout in seconds (default: `30`). | + +> [!WARNING] +> **Safety** +> +> The shell tool gives agents full access to the system shell. Always set `max_iterations` on agents that use the shell tool to prevent infinite loops. A value of 20–50 is typical for development agents. Use [Sandbox Mode](../../configuration/sandbox/index.md) for additional isolation. + +> [!NOTE] +> **Tool Confirmation** +> +> By default, Docker Agent asks for user confirmation before executing shell commands. Use `--yolo` to auto-approve all tool calls. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md new file mode 100644 index 000000000000..9d399f96958b --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md @@ -0,0 +1,59 @@ +--- +title: "Tasks Tool" +description: "Persistent task database with priorities and dependencies, shared across sessions." +keywords: docker agent, ai agents, tools, toolsets, tasks tool +linkTitle: "Tasks" +weight: 180 +canonical: https://docs.docker.com/ai/docker-agent/tools/tasks/ +--- + +_Persistent task database with priorities and dependencies, shared across sessions._ + +## Overview + +The tasks tool provides a persistent task database that survives across agent sessions. Unlike the [Todo tool](../todo/index.md), which maintains an in-memory task list for the current session only, the tasks tool stores tasks in a JSON file on disk so they can be accessed and updated across multiple sessions. Tasks support priorities and dependencies — a task is _blocked_ until every task it depends on is `done`. + +## Configuration + +```yaml +toolsets: + - type: tasks + path: ./tasks.json # Optional: custom database path +``` + +### Options + +| Property | Type | Default | Description | +| -------- | ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `path` | string | `tasks.json` | Path to the JSON task database. Relative paths resolve against the agent config directory (or `--working-dir` when set). | + +## Available Tools + +The tasks toolset exposes these tools: + +| Tool Name | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `create_task` | Create a new task with a title, description (or markdown file path), optional priority, and optional dependencies. | +| `get_task` | Get full details of a single task by ID, including its effective status (`blocked` if any dependency is not `done`). | +| `update_task` | Update a task's title, description, priority, status, or dependency list. | +| `delete_task` | Delete a task by ID. Also removes it from other tasks' dependency lists. | +| `list_tasks` | List tasks sorted by priority (critical first) with blocked tasks last. Optionally filter by status or priority. | +| `next_task` | Return the highest-priority actionable task — one that is not blocked and not done. Great for "what should I work on?". | +| `add_dependency` | Add a dependency: a task is blocked until the task it depends on is `done`. | +| `remove_dependency` | Remove a dependency from a task. | + +## Example + +```yaml +agents: + root: + model: openai/gpt-4o + toolsets: + - type: tasks + path: ./project-tasks.json +``` + +> [!TIP] +> **Tasks vs. Todo** +> +> Use the **tasks** tool when you need persistence across sessions, priorities, or dependencies (e.g., long-running projects, recurring work). Use the [todo tool](../todo/index.md) for ephemeral, session-scoped task lists. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md new file mode 100644 index 000000000000..24873fcacfe3 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md @@ -0,0 +1,30 @@ +--- +title: "Think Tool" +description: "Step-by-step reasoning scratchpad for planning and decision-making." +keywords: docker agent, ai agents, tools, toolsets, think tool +linkTitle: "Think" +weight: 140 +canonical: https://docs.docker.com/ai/docker-agent/tools/think/ +--- + +_Step-by-step reasoning scratchpad for planning and decision-making._ + +## Overview + +The think tool is a reasoning scratchpad that lets agents think step-by-step before acting. The agent can write its thoughts without producing visible output to the user — ideal for planning complex tasks, breaking down problems, and reasoning through multi-step solutions. + +This is a lightweight tool with no side effects. It is most useful for models that lack built-in reasoning or thinking capabilities (e.g., smaller or older models). For models that already support native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a thinking budget — this tool is unnecessary since the model can reason internally. + +## Configuration + +```yaml +toolsets: + - type: think +``` + +No configuration options. + +> [!TIP] +> **When to use** +> +> Use the think tool with models that don't have native reasoning capabilities. If your model already supports a [thinking budget](../../configuration/models/index.md#thinking-budget), you likely don't need this tool. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md new file mode 100644 index 000000000000..7f2154379cce --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md @@ -0,0 +1,54 @@ +--- +title: "Todo Tool" +description: "Task list management for complex multi-step workflows." +keywords: docker agent, ai agents, tools, toolsets, todo tool +linkTitle: "Todo" +weight: 170 +canonical: https://docs.docker.com/ai/docker-agent/tools/todo/ +--- + +_Task list management for complex multi-step workflows._ + +## Overview + +The todo tool provides task list management. Agents can create, update, list, and track progress on tasks with status tracking (pending, in-progress, completed). Useful for complex multi-step workflows where the agent needs to stay organized and ensure all steps are completed. + +## Available Tools + +| Tool | Description | +| -------------- | ---------------------------------------- | +| `create_todo` | Create a new task | +| `create_todos` | Create multiple tasks at once | +| `update_todos` | Update status of one or more tasks | +| `list_todos` | List all current tasks with their status | + +### Task Statuses + +| Status | Description | +| ------------- | ---------------------------- | +| `pending` | Task has not been started | +| `in-progress` | Task is currently being done | +| `completed` | Task is finished | + +## Configuration + +```yaml +toolsets: + - type: todo +``` + +### Options + +| Property | Type | Default | Description | +| -------- | ------- | ------- | ----------------------------------------------------------------------- | +| `shared` | boolean | `false` | When `true`, todos are shared across all agents in a multi-agent config | + +### Shared Todos + +In multi-agent setups, enable shared todos so all agents can see and update the same task list: + +```yaml +toolsets: + - type: todo + shared: true +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md new file mode 100644 index 000000000000..9d3bc2a03a07 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md @@ -0,0 +1,73 @@ +--- +title: "Transfer Task Tool" +description: "Delegate tasks to sub-agents in multi-agent setups." +keywords: docker agent, ai agents, tools, toolsets, transfer task tool +linkTitle: "Transfer Task" +weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/tools/transfer-task/ +--- + +_Delegate tasks to sub-agents in multi-agent setups._ + +## Overview + +The `transfer_task` tool allows an agent to delegate tasks to specialized sub-agents and receive their results. This is the core mechanism for multi-agent orchestration. + +**You don't need to add it manually** — it's automatically available when an agent has `sub_agents` configured. + +## Configuration + +The tool is enabled implicitly when `sub_agents` is set: + +```yaml +agents: + coordinator: + model: openai/gpt-4o + description: Coordinates work across specialists + instruction: Analyze requests and delegate to the right specialist. + sub_agents: [developer, researcher] + + developer: + model: anthropic/claude-sonnet-4-5 + description: Expert software developer + instruction: Write clean, production-ready code. + toolsets: + - type: filesystem + - type: shell + + researcher: + model: openai/gpt-4o + description: Web researcher + instruction: Search for information online. + toolsets: + - type: mcp + ref: docker:duckduckgo +``` + +The coordinator agent automatically gets a `transfer_task` tool that can delegate to `developer` or `researcher`. + +## Tool Interface + +The `transfer_task` tool takes three parameters: + +| Parameter | Type | Required | Description | +| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------- | +| `agent` | string | ✓ | Name of the sub-agent to delegate to. Must be listed under the caller's `sub_agents`. | +| `task` | string | ✓ | Clear, concise description of the task the sub-agent should achieve. | +| `expected_output` | string | ✓ | Description of the result/format the caller expects back. | + +The call blocks until the sub-agent returns its result, which becomes the tool's response. For non-blocking parallel delegation, use [`background_agents`](../background-agents/index.md) instead. + +## Delegation Limits + +Sub-agents can have `sub_agents` of their own, so multi-level delegation chains are supported. Two runtime guards keep chains sane, applied to both `transfer_task` and `run_background_agent`: + +- **Cycles are rejected.** A delegation targeting an agent that is already part of the active delegation chain (for example `a -> b -> a`) fails with an error naming the cycle. +- **Depth is capped at 10 nested delegations.** The root agent delegating to its first sub-agent counts as depth 1; a call that would exceed the cap fails with an error stating the attempted depth. + +A rejected delegation returns a tool error to the calling agent and never starts the sub-agent. + +> [!TIP] +> **See also** +> +> For parallel task delegation, see [Background Agents](../background-agents/index.md). For multi-agent patterns, see [Multi-Agent](../../concepts/multi-agent/index.md). diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md new file mode 100644 index 000000000000..739892c93750 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md @@ -0,0 +1,186 @@ +--- +title: "User Prompt Tool" +description: "Ask the user questions and collect interactive input during agent execution." +keywords: docker agent, ai agents, tools, toolsets, user prompt tool +linkTitle: "User Prompt" +weight: 190 +canonical: https://docs.docker.com/ai/docker-agent/tools/user-prompt/ +--- + +_Ask the user questions and collect interactive input during agent execution._ + +## Overview + +The user prompt tool allows agents to ask questions and collect input from users during execution. This enables interactive workflows where the agent needs clarification, confirmation, or additional information before proceeding. + +> [!NOTE] +> **When to Use** +> +> - When the agent needs clarification before proceeding +> - Collecting credentials or configuration values +> - Presenting choices and getting user decisions +> - Confirming destructive or important actions + +## Configuration + +```yaml +agents: + assistant: + model: openai/gpt-4o + description: Interactive assistant + instruction: | + You are a helpful assistant. When you need information + from the user, use the user_prompt tool to ask them. + toolsets: + - type: user_prompt + - type: filesystem + - type: shell +``` + +## Tool Interface + +The `user_prompt` tool takes these parameters: + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------- | +| `message` | string | ✓ | The question or prompt to display. | +| `title` | string | ✗ | Optional title for the dialog window in the TUI. Defaults to `"Question"` when not provided. | +| `schema` | object | ✗ | JSON Schema defining the expected response structure (object or primitive). | + +## Response Format + +The tool returns a JSON response: + +```json +{ + "action": "accept", + "content": { + "field1": "user value", + "field2": true + } +} +``` + +### Action Values + +| Action | Meaning | +| --------- | ------------------------------------------ | +| `accept` | User provided a response (check `content`) | +| `decline` | User declined to answer | +| `cancel` | User cancelled the prompt | + +## Schema Examples + +### Simple String Input + +```json +{ + "type": "string", + "title": "API Key", + "description": "Enter your API key" +} +``` + +### Multiple Choice + +```json +{ + "type": "string", + "enum": ["development", "staging", "production"], + "title": "Environment", + "description": "Select the target environment" +} +``` + +### Boolean Confirmation + +```json +{ + "type": "boolean", + "title": "Confirm", + "description": "Are you sure you want to proceed?" +} +``` + +### Object with Multiple Fields + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Your username" + }, + "password": { + "type": "string", + "description": "Your password" + }, + "remember": { + "type": "boolean", + "description": "Remember credentials" + } + }, + "required": ["username", "password"] +} +``` + +### Number Input + +```json +{ + "type": "integer", + "title": "Port Number", + "description": "Enter the port number (1024-65535)", + "minimum": 1024, + "maximum": 65535 +} +``` + +## Example Usage + +Here's how an agent might use the user prompt tool: + +```text +Agent: I need to deploy this application. Let me ask which environment to target. + +[Calls user_prompt with message: "Which environment should I deploy to?" + and schema with enum: ["development", "staging", "production"]] + +User selects: "staging" + +Agent: Great, I'll deploy to staging. Let me confirm this action. + +[Calls user_prompt with message: "Deploy to staging? This will replace the current version." + and schema with type: "boolean"] + +User confirms: true + +Agent: Deploying to staging... +``` + +## UI Presentation + +How the prompt appears depends on the interface: + +- **TUI**: Displays an interactive dialog with appropriate input controls +- **CLI (exec mode)**: Prints the prompt and reads from stdin +- **API/MCP**: Returns an elicitation request to the client + +> [!TIP] +> **Best Practice** +> +> Provide clear, concise messages. Include context about why you're asking and what the information will be used for. Use schemas with descriptions to guide users on expected input format. + +## Handling Responses + +The agent should handle all possible actions: + +- **accept**: Process the `content` and continue +- **decline**: Acknowledge and try an alternative approach or explain what's needed +- **cancel**: Stop the current operation gracefully + +> [!WARNING] +> **Context Requirement** +> +> The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations). diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md new file mode 100644 index 000000000000..ded710754192 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md @@ -0,0 +1,143 @@ +--- +title: "Webhook Tool" +description: "Reliable outbound notifications to Slack, Discord, Telegram, IFTTT, and more." +keywords: docker agent, ai agents, tools, toolsets, webhook, slack, discord, telegram, ifttt, notifications +linkTitle: "Webhook" +weight: 145 +canonical: https://docs.docker.com/ai/docker-agent/tools/webhook/ +--- + +_Reliable outbound notifications to Slack, Discord, Telegram, IFTTT, and more._ + +## Overview + +The webhook toolset delivers a notification to a destination **you configure**. The +agent supplies only the message text: it never sees or chooses the URL, because a +webhook URL is itself a credential (Slack and Mattermost embed a secret path, +Discord a token, IFTTT a key, Telegram a bot token). + +This is not a general HTTP client — that is the [`api`](../api/index.md) toolset. +The webhook toolset owns *delivery*: + +- **At-least-once delivery.** Transient failures (`429`, `5xx`, network errors) are + retried with exponential backoff, honouring the server's `Retry-After`. A `4xx` + is permanent and fails immediately without wasting retries. +- **Non-blocking.** The call returns as soon as the notification is queued, so a + slow or retrying endpoint never stalls the agent's turn. The agent is messaged + back **only if delivery ultimately fails**. +- **Storm protection.** An identical message to the same destination inside a short + window is suppressed, and notifications are rate limited, so a looping agent + cannot flood a channel. +- **Provider-shaped payloads.** Each service's wire format is applied for you. + +## Configuration + +The destination lives in `webhook_config`. Use `${env.VAR}` for anything secret — +values are expanded at call time and never stored in the config file. + +```yaml +toolsets: + - type: webhook + webhook_config: + provider: slack + url: ${env.SLACK_WEBHOOK_URL} +``` + +| Field | Required | Description | +| --- | --- | --- | +| `url` | Yes | Webhook endpoint. Usually embeds a secret — prefer `${env.VAR}`. | +| `provider` | No | Payload shape (default `generic`). | +| `headers` | No | Extra headers, for endpoints authenticating with a token. | +| `chat_id` | No | Destination chat — required for `provider: telegram`. | + +`timeout` on the toolset (seconds) overrides the per-request HTTP timeout. + +## Providers + +| Provider | Payload sent | Where the secret lives | +| --- | --- | --- | +| `slack`, `mattermost`, `rocketchat`, `googlechat`, `teams`, `generic` | `{"text": message}` | secret webhook URL | +| `discord` | `{"content": message}` | token in the webhook URL | +| `ifttt` | `{"value1": message, "value2": …, "value3": …}` | key in the webhook URL | +| `telegram` | `{"chat_id": …, "text": message}` | bot token in the URL, plus `chat_id` | + +Aliases are accepted: `msteams`/`microsoft_teams` → `teams`, `google_chat`/`gchat` +→ `googlechat`, `rocket.chat` → `rocketchat`. + +### Per-service examples + +```yaml +# Slack / Mattermost / Rocket.Chat — the URL is the credential +toolsets: + - type: webhook + webhook_config: + provider: slack + url: ${env.SLACK_WEBHOOK_URL} +``` + +```yaml +# Discord — the token is part of the webhook URL +toolsets: + - type: webhook + webhook_config: + provider: discord + url: ${env.DISCORD_WEBHOOK_URL} +``` + +```yaml +# Telegram — bot token in the URL, chat_id selects the destination chat +toolsets: + - type: webhook + webhook_config: + provider: telegram + url: https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage + chat_id: "123456789" +``` + +```yaml +# IFTTT — the key is part of the trigger URL +toolsets: + - type: webhook + webhook_config: + provider: ifttt + url: https://maker.ifttt.com/trigger/build_failed/with/key/${env.IFTTT_KEY} +``` + +```yaml +# Generic endpoint authenticating with a bearer token +toolsets: + - type: webhook + webhook_config: + provider: generic + url: https://alerts.example.com/notify + headers: + Authorization: Bearer ${env.ALERTS_TOKEN} +``` + +## `send_webhook` + +| Parameter | Required | Description | +| --- | --- | --- | +| `message` | Yes | The message text to deliver. | +| `value2`, `value3` | No | Extra IFTTT data fields (`provider: ifttt`). | + +Returns immediately once queued. On success nothing further happens; if delivery +ultimately fails, the agent receives a message saying so. + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini + instruction: If a check fails, notify the team with send_webhook. + toolsets: + - type: webhook + webhook_config: + provider: slack + url: ${env.SLACK_WEBHOOK_URL} +``` + +> [!NOTE] +> Requests to non-public addresses are refused (the SSRF-safe HTTP client), and the +> configured URL is never echoed back to the model or into error messages. diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md b/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md index a42fab303a5e..ee97a8ddb79d 100644 --- a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md +++ b/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md @@ -7,12 +7,12 @@ attestations can provide valuable information from the build process, including, but not limited to: [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain), [SLSA Provenance](https://slsa.dev/provenance), build logs, etc. -This document describes the current custom format used to store attestations, -which is designed to be compatible with current registry implementations today. -In the future, we may support exporting attestations in additional formats. +This document describes the formats used to store attestations. BuildKit stores +attestations as OCI artifacts when OCI media types are enabled. Set the image +exporter option `oci-artifact=false` to use the legacy attestation image +manifest format. -Attestations are stored as manifest objects in the image index, similar in -style to OCI artifacts. +Attestations are stored as manifest objects in the image index. ## Properties @@ -21,12 +21,18 @@ style to OCI artifacts. Attestation manifests are attached to the root image index object, under a separate [OCI image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md). Each attestation manifest can contain multiple [attestation blobs](#attestation-blob), -with all the of the attestations in a manifest applying to a single platform +with all of the attestations in a manifest applying to a single platform manifest. All properties of standard OCI and Docker manifests continue to apply. -The image `config` descriptor will point to a valid [image config](https://github.com/opencontainers/image-spec/blob/main/config.md), -however, it will not contain attestation-specific details, and should be +When OCI artifact storage is enabled, the manifest `artifactType` is set to +`application/vnd.docker.attestation.manifest.v1+json`, the `subject` descriptor +points to the target image manifest, and the `config` descriptor uses the OCI +empty JSON descriptor. + +When `oci-artifact=false` is set, the image `config` descriptor will point to a +valid [image config](https://github.com/opencontainers/image-spec/blob/main/config.md). +The image config will not contain attestation-specific details, and should be ignored as it is only included for compatibility purposes. Each image layer in `layers` will contain a descriptor for a single @@ -62,7 +68,7 @@ The contents of each layer will be a blob dependent on its `mediaType`. ```json { - "_type": "https://in-toto.io/Statement/v0.1", + "_type": "https://in-toto.io/Statement/v1", "subject": [ { "name": "<NAME>", @@ -79,6 +85,10 @@ The contents of each layer will be a blob dependent on its `mediaType`. target manifest described in the [Attestation Manifest Descriptor](#attestation-manifest-descriptor), or some object within. +BuildKit limits each attestation file read from a build result to 80 MiB +before wrapping it as an in-toto statement. This protects exporters from +unbounded reads of frontend-provided attestation files. + ### Attestation Manifest Descriptor Attestation manifests are attached to the root [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md), @@ -160,10 +170,12 @@ This attestation manifest contains one attestation that is an in-toto attestatio { "mediaType": "application/vnd.oci.image.manifest.v1+json", "schemaVersion": 2, + "artifactType": "application/vnd.docker.attestation.manifest.v1+json", "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "digest": "sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3", - "size": 123 + "mediaType": "application/vnd.oci.empty.v1+json", + "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", + "size": 2, + "data": "e30=" }, "layers": [ { @@ -174,22 +186,11 @@ This attestation manifest contains one attestation that is an in-toto attestatio "in-toto.io/predicate-type": "https://spdx.dev/Document" } } - ] -} -``` - -#### Image config (`sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3`): - -```json -{ - "architecture": "unknown", - "os": "unknown", - "config": {}, - "rootfs": { - "type": "layers", - "diff_ids": [ - "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a" - ] + ], + "subject": { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827", + "size": 1234 } } ``` @@ -200,7 +201,7 @@ Attestation body containing the SBOM data listing the packages used during the b ```json { - "_type": "https://in-toto.io/Statement/v0.1", + "_type": "https://in-toto.io/Statement/v1", "predicateType": "https://spdx.dev/Document", "subject": [ { diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md b/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md index 0053e1e12d28..082227ff9c4f 100644 --- a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md +++ b/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md @@ -180,9 +180,21 @@ field for every step. } ``` -BuildKit sets the `builderPlatform` of the build machine. Note that this is not -necessarily the platform of the build result that can be determined from the -`in-toto` subject field. +BuildKit sets the `builderPlatform` of the build machine. This is not +necessarily the platform of the build result, which is recorded separately in +`targetPlatform`. + +### `buildDefinition.internalParameters.targetPlatform` + +* Ref: https://slsa.dev/spec/v1.1/provenance#internalParameters +* Included with `mode=min` and `mode=max`. + +The `targetPlatform` is the platform associated with this build result, for +example `linux/arm64`. It is set even when the request does not specify a +platform. For a multi-platform build, each result's provenance contains its +own target platform. For binary artifacts, this value describes the declared +result platform; BuildKit does not inspect the output binary to determine its +architecture. ### `buildDefinition.resolvedDependencies` diff --git a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md b/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md index a1d62f5033d4..bba3961d2a2f 100644 --- a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md +++ b/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md @@ -7,7 +7,8 @@ list of global settings followed by a series of sections for specific areas of daemon configuration. The file path is `/etc/buildkit/buildkitd.toml` for rootful mode, -`~/.config/buildkit/buildkitd.toml` for rootless mode. +`~/.config/buildkit/buildkitd.toml` for rootless mode. A different path can be +set with the `--config` flag or the `BUILDKITD_CONFIG` environment variable. The following is a complete `buildkitd.toml` configuration example. Note that some configuration options are only useful in edge cases. @@ -17,6 +18,9 @@ Note that some configuration options are only useful in edge cases. root = "/var/lib/buildkit" # insecure-entitlements allows insecure entitlements, disabled by default. insecure-entitlements = [ "network.host", "security.insecure", "device" ] +# proxyNetwork enables proxy network enforcement for all builds, disabled by default. +# It can also be enabled with buildkitd --proxy-network. +proxyNetwork = true # provenanceEnvDir is the directory where extra config is loaded that is added # to the provenance of builds: # slsa v0.2: invocation.environment.* @@ -61,9 +65,36 @@ provenanceEnvDir = "/etc/buildkit/provenance.d" [history] # maxAge is the maximum age of history entries to keep, in seconds. maxAge = 172800 - # maxEntries is the maximum number of history entries to keep. + # maxEntries is the maximum number of history entries to keep. When the + # history section is omitted, the default is 50. If only maxAge is set, + # all entries older than maxAge are removed. + # Setting this value to 0 prevents recording new build history, including + # active-build events. Existing records remain available until normal GC. maxEntries = 50 +[compaction] + # Opt-in metadata database maintenance, independent of cache GC. + enabled = false + # Committed write transactions between automatic eligibility checks. + writesPerCheck = 10000 + # Database size is sampled at most every five minutes after committed writes. + # Initial minimum database size for growth-triggered eligibility checks. + sizeWatermark = 134217728 + # After compaction, grow the next size watermark from the compacted size by + # this percentage. + sizeGrowthPercent = 100 + # Either threshold can trigger compaction, subject to the percentage floor. + minReclaimBytes = 268435456 + # Percentage of the database file estimated to be reclaimable. + minReclaimPercent = 30 + # Minimum reclaimable percentage, even when minReclaimBytes is reached. + minReclaimPercentFloor = 10 + # Wait for no active transactions and this interval without database activity. + idleTimeout = "1m" + # Cancel this many attempts for arriving writers, then let the next copy finish. + # Writers may wait for the full copy duration. Zero forces the first attempt. + maxRetry = 3 + [worker.oci] enabled = true # platforms is manually configure platforms, detected automatically if unset. @@ -156,6 +187,8 @@ provenanceEnvDir = "/etc/buildkit/provenance.d" cniPoolSize = 16 # defaultCgroupParent sets the parent cgroup of all containers. defaultCgroupParent = "buildkit" + # hypervIsolation enables Hyper-V isolation for Windows containers. + hypervIsolation = false [worker.containerd.labels] "foo" = "bar" @@ -212,19 +245,31 @@ provenanceEnvDir = "/etc/buildkit/provenance.d" [system] # how often buildkit scans for changes in the supported emulated platforms platformsCacheMaxAge = "1h" - + # maxRegistryConcurrency sets the maximum number of concurrent connections + # per registry. If unset, the default concurrency limit is used. + maxRegistryConcurrency = 4 + # sessionAuthTimeout sets the timeout for daemon-side authentication + # round-trips with the buildx client session (resolving credentials and + # fetching auth tokens from the session). Can be a duration string + # (e.g. "60s") or a bare integer treated as seconds. If unset, the default + # timeout of 60s is used. A value of zero or less disables the timeout + # entirely. + sessionAuthTimeout = "60s" # optional signed cache configuration for GitHub Actions backend -[ghacache.sign] -# command that signs the payload in stdin and outputs the signature to stdout. Normally you want cosign to produce the signature bytes. -cmd = "" -[ghacache.verify] -required = false -[ghacache.verify.policy] -timestampThreshold = 1 -tlogThreshold = 1 -# cetificate properties that need to match. Simple wildcards (*) are supported. -certificateIssuer = "" -subjectAlternativeName = "" -buildSignerURI = "" +# [cache.gha.sign] +# # command that signs the payload in stdin and outputs the signature to stdout. +# # Normally you want cosign to produce the signature bytes. +# command = "" +# +# [cache.gha.verify] +# required = false +# +# [cache.gha.verify.policy] +# timestampThreshold = 1 +# tlogThreshold = 1 +# # certificate properties that need to match. Simple wildcards (*) are supported. +# certificateIssuer = "" +# subjectAlternativeName = "" +# buildSignerURI = "" ``` diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md index 9ab5189743e4..5026981a4ae1 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md @@ -710,7 +710,7 @@ The available `[OPTIONS]` for the `RUN` instruction are: | Option | Minimum Dockerfile version | |---------------------------------|----------------------------| -| [`--device`](#run---device) | 1.14-labs | +| [`--device`](#run---device) | 1.27 | | [`--mount`](#run---mount) | 1.2 | | [`--network`](#run---network) | 1.3 | | [`--security`](#run---security) | 1.20 | @@ -731,8 +731,7 @@ The cache for `RUN` instructions can be invalidated by [`ADD`](#add) and [`COPY` ### RUN --device > [!NOTE] -> Not yet available in stable syntax, use [`docker/dockerfile:1-labs`](#syntax) -> version. It also needs BuildKit 0.20.0 or later. +> This option needs BuildKit 0.20.0 or later. ```dockerfile RUN --device=name,[required] @@ -804,7 +803,7 @@ In this example we use the `--device` flag to run `llama.cpp` inference using an NVIDIA GPU device through CDI: ```dockerfile -# syntax=docker/dockerfile:1-labs +# syntax=docker/dockerfile:1 FROM scratch AS model ADD https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf /model.gguf @@ -884,6 +883,15 @@ performance. Your build should work with any contents of the cache directory as another build may overwrite the files or GC may clean it if more storage space is needed. +> [!NOTE] +> Cache mounts are stored in the builder's local storage. They are not +> included in [exported build cache](https://docs.docker.com/build/cache/backends/) +> (`--cache-to`), and are not restored by `--cache-from`. If each build runs +> on a new builder (e.g. on CI runners that provision a fresh machine +> for each job), cache mounts start empty on every build. For a workaround on +> GitHub Actions, see +> [Cache mounts](https://docs.docker.com/build/ci/github-actions/cache/#cache-mounts). + #### Example: cache Go packages ```dockerfile @@ -938,6 +946,23 @@ an environment variable by setting the `env` option. | `uid` | User ID for secret file. Default `0`. | | `gid` | Group ID for secret file. Default `0`. | +> [!NOTE] +> On Windows containers, the secret is delivered as a single-file, read-only +> bind mount (there is no `tmpfs`). An explicit `target` is required because +> there is no default `/run/secrets/` location, e.g. +> `--mount=type=secret,id=mysecret,target=C:/path/to/secret`. Use forward +> slashes in the target: the Dockerfile escape character (default `\`) otherwise +> consumes the backslashes during parsing. The `mode`, `uid`, and `gid` options +> are not supported on Windows and are ignored. The secret is written to a +> temporary file restricted (via an explicit ACL) to SYSTEM, the Administrators +> group, and the BuildKit daemon account, then removed after the step; it is +> written in clear text, so consider BitLocker for at-rest encryption. Because +> the file is not granted to the container's default user, the `RUN` step must +> execute as an administrator (e.g. `USER ContainerAdministrator`) to read the +> secret. The secret value is not persisted in the image; however, an empty +> placeholder directory may remain at the `target` path in the resulting +> layer, which is an inherent property of Windows bind mounts. + #### Example: access to S3 ```dockerfile @@ -1459,9 +1484,9 @@ ADD arr[[]0].txt /dest/ #### Adding local tar archives When using a local tar archive as the source for `ADD`, and the archive is in a -recognized compression format (`gzip`, `bzip2` or `xz`, or uncompressed), the -archive is decompressed and extracted into the specified destination. Local tar -archives are extracted by default, see the [`ADD --unpack` flag]. +recognized compression format (`gzip`, `bzip2`, `xz` or `zstd`, or +uncompressed), the archive is decompressed and extracted into the specified +destination. Local tar archives are extracted by default, see the [`ADD --unpack` flag]. When a directory is extracted, it has the same behavior as `tar -x`. The result is the union of: @@ -1502,6 +1527,12 @@ If your URL files are protected using authentication, you need to use `RUN wget` `RUN curl` or use another tool from within the container as the `ADD` instruction doesn't support authentication. +##### Secrets + +You can use the `HTTP_AUTH_HEADER_<host>` and `HTTP_AUTH_TOKEN_<host>` secrets +to set credentials for remote sources. For more information, see +[Build secrets](https://docs.docker.com/build/building/secrets/#http-authentication-for-add). + #### Adding files from a Git repository To use a Git repository as the source for `ADD`, you can reference the @@ -1633,9 +1664,10 @@ ADD [--unpack=<bool>] <src> ... <dir> ``` The `--unpack` flag controls whether or not to automatically unpack tar -archives (including compressed formats like `gzip` or `bzip2`) when adding them -to the image. Local tar archives are unpacked by default, whereas remote tar -archives (where `src` is a URL) are downloaded without unpacking. +archives (including compressed formats like `gzip`, `bzip2`, `xz` or `zstd`) +when adding them to the image. Local tar archives are unpacked by default, +whereas remote tar archives (where `src` is a URL) are downloaded without +unpacking. ```dockerfile # syntax=docker/dockerfile:1 @@ -1881,11 +1913,16 @@ Sets ownership of copied files. Without this flag, files are created with UID and GID of 0. The flag accepts usernames, group names, UIDs, or GIDs in any combination. -If you specify only a user, the GID is set to the same numeric value as the UID. +If you omit the group, either as `--chown=<user>` or `--chown=<user>:`, a +username uses the primary GID from its `/etc/passwd` entry. A numeric UID uses +the same numeric value for the GID, without looking up `/etc/passwd`. For example, +`--chown=1000:` sets both the UID and GID to 1000, even if that user's primary +GID in `/etc/passwd` is different. ```dockerfile COPY --chown=55:mygroup files* /somedir/ COPY --chown=bin files* /somedir/ +COPY --chown=bin: files* /somedir/ COPY --chown=1 files* /somedir/ COPY --chown=10:11 files* /somedir/ COPY --chown=myuser:mygroup --chmod=644 files* /somedir/ @@ -1894,7 +1931,9 @@ COPY --chown=myuser:mygroup --chmod=644 files* /somedir/ When using names instead of numeric IDs, BuildKit resolves them using `/etc/passwd` and `/etc/group` in the container's root filesystem. If these files are missing or don't contain the specified names, the build fails. -Numeric IDs don't require this lookup. +Numeric IDs don't require this lookup. When combined with +[`--link`](#copy---link), files are copied into an empty filesystem, so names +can't be resolved and `--chown` must use numeric IDs. The `--chown` flag is not supported when building Windows containers. @@ -1967,6 +2006,13 @@ path, using `--link` is always recommended. The performance of `--link` is equivalent or better than the default behavior and, it creates much better conditions for cache reuse. +When copying a path into a subdirectory, `--link` will always copy from the +root of the filesystem. When copying a directory, the existing mode is +overridden with the new mode from the copied path. If you need a specific mode +for a directory, such as the more permissive `/tmp` directory, you may need to +either avoid using `--link`, unroll the copy into its base components, or use +`--chmod` to ensure the overwriting directory contains the same permissions. + ### COPY --parents ```dockerfile @@ -2062,8 +2108,8 @@ COPY --exclude=*.txt hom* /mydir/ ``` You can specify the `--exclude` option multiple times for a `COPY` instruction. -Multiple `--excludes` are files matching its patterns not to be copied, -even if the files paths match the pattern specified in `<src>`. +Files matching any of the specified `--exclude` patterns are not copied, +even if their paths match the pattern specified in `<src>`. To add all files starting with "hom", excluding files with either `.txt` or `.md` extensions: ```dockerfile @@ -2720,6 +2766,7 @@ RUN echo "I'm building for $TARGETPLATFORM" | `BUILDKIT_BUILD_NAME` | String | Override the build name shown in [`buildx history` command](https://docs.docker.com/reference/cli/docker/buildx/history/) and [Docker Desktop Builds view](https://docs.docker.com/desktop/use-desktop/builds/). | | `BUILDKIT_CACHE_MOUNT_NS` | String | Set optional cache ID namespace. | | `BUILDKIT_CONTEXT_KEEP_GIT_DIR` | Bool | Trigger Git context to keep the `.git` directory. | +| `BUILDKIT_GIT_ADVICE` | Bool | Show Git advice messages from BuildKit-managed Git operations. Defaults to `false`. | | `BUILDKIT_INLINE_CACHE`[^2] | Bool | Inline cache metadata to image config or not. | | `BUILDKIT_MULTI_PLATFORM` | Bool | Opt into deterministic output regardless of multi-platform output or not. | | `BUILDKIT_SANDBOX_HOSTNAME` | String | Set the hostname (default `buildkitsandbox`) | diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md index 06043ea15a09..396be3e27134 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md @@ -28,6 +28,12 @@ image built externally is prone to breaking, since working directory may change upstream without warning, resulting in a completely different directory hierarchy for your build. +> [!NOTE] +> +> `WORKDIR` does not perform shell expansion. Paths beginning with `~` or +> `~username` are treated as literal directory names and are not resolved to a +> user's home directory. + ## Examples ❌ Bad: this assumes that `WORKDIR` in the base image is `/` diff --git a/_vendor/github.com/moby/moby/api/docs/CHANGELOG.md b/_vendor/github.com/moby/moby/api/docs/CHANGELOG.md index ca727e0d22ea..442bf2986a68 100644 --- a/_vendor/github.com/moby/moby/api/docs/CHANGELOG.md +++ b/_vendor/github.com/moby/moby/api/docs/CHANGELOG.md @@ -13,6 +13,37 @@ keywords: "API, Docker, rcli, REST, documentation" will be rejected. --> +## v1.56 API changes + +* `GET /containers/json` now supports an `annotation` filter to filter + containers by annotation, either by key (`annotation=key`) or by key and + value (`annotation="key=value"`), similar to the existing `label` filter. +* `POST /containers/create` now supports `HostConfig.Umask` to set the initial + umask for a Unix container. When set, the daemon includes the value in the OCI + process configuration for the container's entrypoint, exec processes, and + healthchecks. When omitted, the runtime's default behavior applies. + +## v1.55 API changes + +* `GET /images/{name}/attestations` is a new endpoint that returns the in-toto + attestation statements attached to an image. The `platform` query parameter + selects the image variant (defaults to the daemon's host platform); it is + declared as a repeatable parameter for forward compatibility, but only one + value is currently accepted. The `type` query parameter may be repeated to + filter the returned statements by in-toto predicate type URI; if omitted, + all statements are returned. The `statement` query parameter (default + `false`) controls whether the verbatim statement body is included; when + omitted or `false`, each entry contains only the descriptor and predicate + type, and statement blobs are not read. The response is a JSON array of + `AttestationStatement` objects. +* `POST /containers/{id}/update` now supports per-device blkio resource + settings through the `BlkioWeightDevice`, `BlkioDeviceReadBps`, + `BlkioDeviceWriteBps`, `BlkioDeviceReadIOps`, and `BlkioDeviceWriteIOps` + fields. These fields were previously present in the request schema but were + ignored by the daemon. Omit a field or set it to `null` to leave the current + per-device rules unchanged. Set it to an empty array to clear the current + per-device rules for that resource type. + ## v1.54 API changes * `GET /images/json` now supports an `identity` query parameter. When set, diff --git a/_vendor/github.com/moby/moby/api/docs/v1.24.md b/_vendor/github.com/moby/moby/api/docs/v1.24.md index 2d374a4a8484..bec30bb0b344 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.24.md +++ b/_vendor/github.com/moby/moby/api/docs/v1.24.md @@ -1095,6 +1095,7 @@ Start the container `id` - **204** – no error - **304** – container already started +- **400** – bad parameter, including an invalid checkpoint ID - **404** – no such container - **500** – server error diff --git a/_vendor/github.com/moby/moby/api/docs/v1.25.yaml b/_vendor/github.com/moby/moby/api/docs/v1.25.yaml index ea8d12a0e18b..ba97ed5add71 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.25.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.25.yaml @@ -685,7 +685,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -871,9 +871,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2055,6 +2057,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2114,6 +2140,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2258,7 +2291,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2499,7 +2532,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: @@ -2543,7 +2576,7 @@ paths: - `health`=(`starting`|`healthy`|`unhealthy`|`none`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -2674,11 +2707,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2837,7 +2870,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -2857,26 +2890,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2889,7 +2922,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3132,14 +3165,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3161,7 +3194,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3208,14 +3241,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3240,23 +3273,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3313,7 +3346,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -3338,14 +3371,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3364,16 +3397,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3395,7 +3428,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3489,14 +3522,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3520,18 +3553,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3557,20 +3590,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3584,26 +3621,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3617,22 +3656,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3646,6 +3687,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -3653,16 +3696,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3677,6 +3720,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -3686,7 +3731,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -3695,14 +3740,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3743,20 +3788,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3771,6 +3816,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -3781,16 +3828,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3800,6 +3847,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -3807,16 +3856,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3826,6 +3875,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -3911,22 +3962,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3976,22 +4027,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4023,7 +4074,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4033,14 +4084,14 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4056,20 +4107,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4089,6 +4140,8 @@ paths: description: "If the container is running, kill it before removing it." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4096,24 +4149,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveHead" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4136,20 +4189,20 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4176,27 +4229,27 @@ paths: - "application/x-tar" - "application/octet-stream" responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4237,7 +4290,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4251,7 +4304,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4264,7 +4317,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4299,7 +4352,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4395,14 +4448,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4411,10 +4467,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4423,6 +4481,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4434,9 +4493,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4467,9 +4526,9 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4485,13 +4544,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4531,7 +4590,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -4611,14 +4670,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4637,7 +4696,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4667,11 +4726,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4695,13 +4754,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4743,21 +4802,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4787,7 +4846,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4798,15 +4857,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4835,7 +4894,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4869,7 +4928,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4911,7 +4970,7 @@ paths: (or `0`), all unused images are pruned. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4925,7 +4984,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4938,7 +4997,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -4956,9 +5015,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4976,7 +5035,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5175,7 +5234,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5188,7 +5247,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5225,7 +5284,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5238,12 +5297,12 @@ paths: produces: - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" example: "OK" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5257,18 +5316,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5330,7 +5389,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5370,7 +5429,7 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5403,7 +5462,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5482,7 +5541,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5518,12 +5577,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5547,20 +5606,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -5577,9 +5637,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5606,22 +5666,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5692,13 +5752,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -5729,17 +5789,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5768,7 +5828,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5812,11 +5872,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5834,7 +5894,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -5868,7 +5928,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5897,11 +5957,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5946,15 +6006,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5971,17 +6031,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5996,6 +6056,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6012,7 +6074,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6026,7 +6088,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6038,7 +6100,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6095,7 +6157,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6120,11 +6182,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" @@ -6140,13 +6202,13 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6156,6 +6218,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6167,7 +6231,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6180,19 +6244,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6269,17 +6333,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6315,17 +6379,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6365,7 +6429,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6375,7 +6439,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6387,7 +6451,7 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6433,7 +6497,7 @@ paths: Description: "command line arguments" Settable: null Value: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6444,7 +6508,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6473,7 +6537,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6495,9 +6559,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6557,15 +6621,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6581,15 +6645,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6610,9 +6674,9 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6633,9 +6697,9 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6653,9 +6717,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6671,6 +6735,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -6685,13 +6751,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6716,29 +6782,31 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6761,15 +6829,15 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6784,13 +6852,13 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6811,13 +6879,13 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6843,7 +6911,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -6885,7 +6953,7 @@ paths: UpdatedAt: "2016-08-15T16:32:09.623207604Z" Version: Index: 51 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6898,21 +6966,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 406: + "406": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6951,17 +7019,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -6973,17 +7041,32 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -6996,13 +7079,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7018,17 +7101,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7067,7 +7150,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7077,7 +7160,7 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7103,9 +7186,9 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7115,13 +7198,13 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7145,7 +7228,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7159,19 +7242,19 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "server error or node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7242,15 +7325,15 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7265,13 +7348,13 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7289,15 +7372,15 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ImageDeleteResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7348,8 +7431,8 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "X-Registry-Auth" in: "header" @@ -7369,23 +7452,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7441,7 +7524,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7559,7 +7642,7 @@ paths: Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7584,15 +7667,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7610,7 +7693,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7624,7 +7707,7 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7646,7 +7729,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7656,15 +7739,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 406: + "406": description: "server error or node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7688,7 +7771,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -7700,15 +7783,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 406: + "406": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7725,13 +7808,13 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.26.yaml b/_vendor/github.com/moby/moby/api/docs/v1.26.yaml index 46af01c0033d..0bd9c7ec754e 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.26.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.26.yaml @@ -685,7 +685,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -871,9 +871,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2059,6 +2061,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2118,6 +2144,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2262,7 +2295,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2503,7 +2536,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: @@ -2547,7 +2580,7 @@ paths: - `health`=(`starting`|`healthy`|`unhealthy`|`none`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -2678,11 +2711,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2841,7 +2874,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -2861,26 +2894,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2893,7 +2926,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3137,14 +3170,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3166,7 +3199,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3213,14 +3246,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3245,23 +3278,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3318,7 +3351,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -3343,14 +3376,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3369,16 +3402,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3400,7 +3433,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3494,14 +3527,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3525,18 +3558,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3562,20 +3595,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3589,26 +3626,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3622,22 +3661,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3651,6 +3692,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -3658,16 +3701,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3682,6 +3725,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -3691,7 +3736,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -3700,14 +3745,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3749,20 +3794,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3777,6 +3822,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -3787,16 +3834,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3806,6 +3853,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -3813,16 +3862,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3832,6 +3881,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -3917,22 +3968,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3982,22 +4033,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4029,7 +4080,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4039,14 +4090,14 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4062,20 +4113,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4095,6 +4146,8 @@ paths: description: "If the container is running, kill it before removing it." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4102,24 +4155,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveHead" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4142,20 +4195,20 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4182,27 +4235,27 @@ paths: - "application/x-tar" - "application/octet-stream" responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4243,7 +4296,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4257,7 +4310,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4270,7 +4323,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4305,7 +4358,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4401,14 +4454,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4417,10 +4473,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4429,6 +4487,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4440,9 +4499,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4473,13 +4532,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4495,13 +4554,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4541,7 +4600,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -4621,14 +4680,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4647,7 +4706,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4677,11 +4736,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4705,13 +4764,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4753,21 +4812,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4797,7 +4856,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4808,15 +4867,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4845,7 +4904,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4879,7 +4938,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4921,7 +4980,7 @@ paths: (or `0`), all unused images are pruned. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4935,7 +4994,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4948,7 +5007,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -4966,9 +5025,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4986,7 +5045,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5186,7 +5245,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5199,7 +5258,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5236,7 +5295,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5249,12 +5308,12 @@ paths: produces: - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" example: "OK" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5268,18 +5327,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5341,7 +5400,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5381,7 +5440,7 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5414,7 +5473,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5493,7 +5552,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5529,12 +5588,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5558,20 +5617,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -5588,9 +5648,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5617,22 +5677,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5703,13 +5763,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -5740,17 +5800,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5779,7 +5839,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5823,11 +5883,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5845,7 +5905,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -5879,7 +5939,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5908,11 +5968,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5957,15 +6017,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5982,17 +6042,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6007,6 +6067,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6023,7 +6085,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6037,7 +6099,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6049,7 +6111,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6106,7 +6168,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6131,11 +6193,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" @@ -6151,13 +6213,13 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6167,6 +6229,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6178,7 +6242,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6191,19 +6255,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6280,17 +6344,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6326,17 +6390,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6376,7 +6440,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6386,7 +6450,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6398,7 +6462,7 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6444,7 +6508,7 @@ paths: Description: "command line arguments" Settable: null Value: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6455,7 +6519,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6484,7 +6548,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6506,9 +6570,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6568,15 +6632,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6592,15 +6656,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6621,9 +6685,9 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6644,9 +6708,9 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6662,13 +6726,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6719,6 +6783,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -6727,9 +6793,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6745,6 +6811,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -6759,13 +6827,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6790,29 +6858,31 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6835,15 +6905,15 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6858,13 +6928,13 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6885,13 +6955,13 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6917,7 +6987,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -6959,7 +7029,7 @@ paths: UpdatedAt: "2016-08-15T16:32:09.623207604Z" Version: Index: 51 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6972,21 +7042,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 406: + "406": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7025,17 +7095,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7047,17 +7117,32 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7070,13 +7155,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7092,17 +7177,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7141,7 +7226,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7151,7 +7236,7 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7177,9 +7262,9 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7189,13 +7274,13 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7219,7 +7304,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7233,19 +7318,19 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "server error or node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7316,15 +7401,15 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7339,13 +7424,13 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7363,15 +7448,15 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ImageDeleteResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7422,8 +7507,8 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "X-Registry-Auth" in: "header" @@ -7443,23 +7528,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7515,7 +7600,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7633,7 +7718,7 @@ paths: Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7658,15 +7743,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7684,7 +7769,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7698,7 +7783,7 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7720,7 +7805,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7730,15 +7815,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 406: + "406": description: "server error or node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7762,7 +7847,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -7774,15 +7859,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 406: + "406": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7799,13 +7884,13 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7821,13 +7906,13 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.27.yaml b/_vendor/github.com/moby/moby/api/docs/v1.27.yaml index ef80c44db719..dbb746138399 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.27.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.27.yaml @@ -720,7 +720,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -884,9 +884,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -1976,7 +1978,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2139,6 +2141,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2194,6 +2220,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2338,7 +2371,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2571,7 +2604,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: @@ -2614,7 +2647,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -2745,11 +2778,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2908,7 +2941,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -2928,26 +2961,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2960,7 +2993,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3203,14 +3236,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3232,7 +3265,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3279,14 +3312,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3311,23 +3344,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3384,7 +3417,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -3409,14 +3442,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3435,16 +3468,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3472,7 +3505,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3568,14 +3601,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3599,18 +3632,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3636,20 +3669,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3663,26 +3700,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3696,22 +3735,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3725,6 +3766,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -3732,16 +3775,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3756,6 +3799,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -3765,7 +3810,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -3774,14 +3819,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3823,20 +3868,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3851,6 +3896,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -3861,16 +3908,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3880,6 +3927,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -3887,16 +3936,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3906,6 +3955,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -3991,22 +4042,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4056,22 +4107,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4103,7 +4154,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4113,14 +4164,14 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4136,27 +4187,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or use -f" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4181,6 +4232,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4188,24 +4241,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveHead" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4228,20 +4281,20 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4268,27 +4321,27 @@ paths: - "application/x-tar" - "application/octet-stream" responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4321,7 +4374,7 @@ paths: - "application/json" operationId: "ContainerPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4335,7 +4388,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4348,7 +4401,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4383,7 +4436,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4478,14 +4531,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4494,10 +4550,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4506,6 +4564,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4517,9 +4576,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4550,13 +4609,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4572,13 +4631,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4618,7 +4677,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -4698,14 +4757,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4724,7 +4783,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4754,11 +4813,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4782,13 +4841,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4830,21 +4889,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4874,7 +4933,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4885,15 +4944,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4922,7 +4981,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -4956,7 +5015,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4997,7 +5056,7 @@ paths: (or `0`), all unused images are pruned. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5011,7 +5070,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5024,7 +5083,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -5042,9 +5101,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5062,7 +5121,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5262,7 +5321,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5275,7 +5334,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5312,7 +5371,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5325,12 +5384,12 @@ paths: produces: - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" example: "OK" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5344,18 +5403,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5417,7 +5476,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5457,11 +5516,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5495,7 +5554,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5574,7 +5633,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5610,12 +5669,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5639,20 +5698,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -5669,9 +5729,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5698,22 +5758,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5784,13 +5844,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -5821,17 +5881,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5860,7 +5920,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5904,11 +5964,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5926,7 +5986,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -5960,7 +6020,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5990,11 +6050,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6039,15 +6099,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6064,17 +6124,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6089,6 +6149,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6097,7 +6159,7 @@ paths: - "application/json" operationId: "VolumePrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6111,7 +6173,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6123,7 +6185,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6183,7 +6245,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6208,11 +6270,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" @@ -6228,13 +6290,13 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6244,6 +6306,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6255,7 +6319,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6268,19 +6332,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6361,17 +6425,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6407,17 +6471,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6449,7 +6513,7 @@ paths: - "application/json" operationId: "NetworkPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6459,7 +6523,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6471,7 +6535,7 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6517,7 +6581,7 @@ paths: Description: "command line arguments" Settable: null Value: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6528,7 +6592,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6557,7 +6621,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6579,9 +6643,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6641,15 +6705,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6665,15 +6729,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6694,13 +6758,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6721,13 +6785,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6743,13 +6807,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6800,6 +6864,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -6808,9 +6874,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6826,6 +6892,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -6840,13 +6908,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6871,33 +6939,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -6920,19 +6990,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -6947,17 +7017,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -6978,17 +7048,17 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7014,7 +7084,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -7056,15 +7126,15 @@ paths: UpdatedAt: "2016-08-15T16:32:09.623207604Z" Version: Index: 51 - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7077,21 +7147,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7130,17 +7200,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7152,17 +7222,32 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7175,13 +7260,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7197,17 +7282,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7246,7 +7331,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7256,11 +7341,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7286,13 +7371,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7302,17 +7387,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7336,7 +7421,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7350,23 +7435,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7437,19 +7522,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7464,17 +7549,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7492,23 +7577,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ImageDeleteResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7559,8 +7644,8 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "X-Registry-Auth" in: "header" @@ -7580,27 +7665,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7656,7 +7741,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7773,11 +7858,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7802,19 +7887,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7832,7 +7917,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7846,11 +7931,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7872,7 +7957,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7882,15 +7967,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7914,7 +7999,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -7926,15 +8011,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7951,17 +8036,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7977,17 +8062,17 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.28.yaml b/_vendor/github.com/moby/moby/api/docs/v1.28.yaml index 57fa2ddeacf1..fd68b8545a11 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.28.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.28.yaml @@ -726,7 +726,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -890,9 +890,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2017,7 +2019,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2192,6 +2194,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2247,6 +2273,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2418,7 +2451,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2658,7 +2691,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: @@ -2703,7 +2736,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -2834,11 +2867,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -2997,7 +3030,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -3017,26 +3050,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3049,7 +3082,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3292,14 +3325,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3321,7 +3354,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3368,14 +3401,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3400,23 +3433,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3473,7 +3506,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -3500,14 +3533,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3526,16 +3559,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3563,7 +3596,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3659,14 +3692,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3690,18 +3723,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3727,20 +3760,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3754,26 +3791,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3787,22 +3826,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3816,6 +3857,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -3823,16 +3866,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3847,6 +3890,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -3856,7 +3901,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -3865,14 +3910,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3913,20 +3958,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3941,6 +3986,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -3951,16 +3998,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3970,6 +4017,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -3977,16 +4026,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3996,6 +4045,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -4081,22 +4132,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4146,22 +4197,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4193,7 +4244,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4203,14 +4254,14 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4226,27 +4277,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4271,6 +4322,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4278,24 +4331,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4315,22 +4368,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4355,27 +4409,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4417,7 +4471,7 @@ paths: - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4431,7 +4485,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4444,7 +4498,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4479,7 +4533,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4578,14 +4632,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4594,10 +4651,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4606,6 +4665,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4617,9 +4677,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4650,13 +4710,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4672,13 +4732,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4718,7 +4778,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -4799,14 +4859,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4824,7 +4884,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -4854,11 +4914,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4882,13 +4942,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4930,21 +4990,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4975,7 +5035,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -4986,15 +5046,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5023,7 +5083,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -5057,7 +5117,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5099,7 +5159,7 @@ paths: - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5113,7 +5173,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5126,7 +5186,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -5144,9 +5204,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5164,7 +5224,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5363,7 +5423,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5375,7 +5435,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5412,7 +5472,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5422,9 +5482,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -5436,7 +5497,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5450,18 +5511,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5523,7 +5584,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5563,11 +5624,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5601,7 +5662,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5680,7 +5741,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5716,12 +5777,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5745,20 +5806,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -5775,9 +5837,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5804,22 +5866,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5890,13 +5952,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -5927,17 +5989,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5966,7 +6028,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6010,11 +6072,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6032,7 +6094,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -6066,7 +6128,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6096,11 +6158,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6145,15 +6207,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6170,17 +6232,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6195,6 +6257,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6211,7 +6275,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6225,7 +6289,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6237,7 +6301,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6297,7 +6361,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6322,11 +6386,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" @@ -6347,13 +6411,13 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6363,6 +6427,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6374,7 +6440,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6387,19 +6453,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6480,17 +6546,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6526,17 +6592,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6575,7 +6641,7 @@ paths: - `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6585,7 +6651,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6597,7 +6663,7 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6643,7 +6709,7 @@ paths: Description: "command line arguments" Settable: null Value: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6663,7 +6729,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6692,7 +6758,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6714,9 +6780,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6776,15 +6842,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6800,15 +6866,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6829,13 +6895,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6856,13 +6922,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6884,13 +6950,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6941,6 +7007,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -6949,9 +7017,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6967,6 +7035,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -6981,13 +7051,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7012,33 +7082,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7061,19 +7133,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7088,17 +7160,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7119,17 +7191,17 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7155,7 +7227,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -7197,15 +7269,15 @@ paths: UpdatedAt: "2016-08-15T16:32:09.623207604Z" Version: Index: 51 - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7218,21 +7290,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7271,17 +7343,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7293,17 +7365,32 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7316,13 +7403,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7338,17 +7425,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7387,7 +7474,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7397,11 +7484,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7427,13 +7514,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7443,17 +7530,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7477,7 +7564,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7491,23 +7578,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7586,19 +7673,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7613,17 +7700,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7641,23 +7728,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7716,15 +7803,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -7743,27 +7830,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7819,7 +7906,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7936,11 +8023,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7965,19 +8052,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7995,7 +8082,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8009,11 +8096,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8035,7 +8122,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8045,15 +8132,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8077,7 +8164,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -8089,15 +8176,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8114,17 +8201,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8140,17 +8227,17 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.29.yaml b/_vendor/github.com/moby/moby/api/docs/v1.29.yaml index ebec0c4c606e..5a8888a80a8f 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.29.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.29.yaml @@ -732,7 +732,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -896,9 +896,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2038,7 +2040,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2213,6 +2215,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2268,6 +2294,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2451,7 +2484,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2691,7 +2724,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: @@ -2736,7 +2769,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -2867,11 +2900,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3030,7 +3063,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -3050,26 +3083,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3082,7 +3115,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3325,14 +3358,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3354,7 +3387,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3401,14 +3434,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3433,23 +3466,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3506,7 +3539,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -3533,14 +3566,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3559,16 +3592,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3596,7 +3629,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3692,14 +3725,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3723,18 +3756,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3760,20 +3793,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3787,26 +3824,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3820,22 +3859,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3849,6 +3890,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -3856,16 +3899,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3880,6 +3923,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -3889,7 +3934,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -3898,14 +3943,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3946,20 +3991,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3974,6 +4019,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -3984,16 +4031,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4003,6 +4050,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -4010,16 +4059,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4029,6 +4078,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -4114,22 +4165,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4179,22 +4230,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4226,7 +4277,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4236,14 +4287,14 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4259,27 +4310,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4304,6 +4355,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4311,24 +4364,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4348,22 +4401,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4388,27 +4442,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4450,7 +4504,7 @@ paths: - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4464,7 +4518,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4477,7 +4531,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4512,7 +4566,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4611,14 +4665,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4627,10 +4684,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4639,6 +4698,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4650,9 +4710,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4683,13 +4743,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4705,13 +4765,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4751,7 +4811,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -4832,14 +4892,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4857,7 +4917,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -4887,11 +4947,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4915,13 +4975,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4963,21 +5023,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5008,7 +5068,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -5019,15 +5079,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5056,7 +5116,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -5090,7 +5150,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5132,7 +5192,7 @@ paths: - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5146,7 +5206,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5159,7 +5219,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -5177,9 +5237,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5197,7 +5257,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5396,7 +5456,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5408,7 +5468,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5445,7 +5505,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5455,9 +5515,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -5469,7 +5530,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5483,18 +5544,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5556,7 +5617,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5596,11 +5657,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5634,7 +5695,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5713,7 +5774,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5749,12 +5810,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5778,20 +5839,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -5808,9 +5870,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5837,22 +5899,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5923,13 +5985,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -5960,17 +6022,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5999,7 +6061,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6043,11 +6105,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6065,7 +6127,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -6099,7 +6161,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6129,11 +6191,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6178,15 +6240,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6203,17 +6265,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6228,6 +6290,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6244,7 +6308,7 @@ paths: Available filters: type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6258,7 +6322,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6270,7 +6334,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6333,7 +6397,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6359,11 +6423,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" @@ -6384,13 +6448,13 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6400,6 +6464,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6411,7 +6477,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6424,19 +6490,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6521,17 +6587,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6567,17 +6633,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6616,7 +6682,7 @@ paths: - `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6626,7 +6692,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6638,7 +6704,7 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6684,7 +6750,7 @@ paths: Description: "command line arguments" Settable: null Value: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6704,7 +6770,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6733,7 +6799,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6755,9 +6821,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6817,15 +6883,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6841,15 +6907,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6870,13 +6936,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6897,13 +6963,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6925,13 +6991,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6982,6 +7048,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -6990,9 +7058,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7008,6 +7076,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -7022,13 +7092,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7053,33 +7123,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7102,19 +7174,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7129,17 +7201,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7160,17 +7232,17 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7196,7 +7268,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -7238,15 +7310,15 @@ paths: UpdatedAt: "2016-08-15T16:32:09.623207604Z" Version: Index: 51 - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7259,21 +7331,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7312,17 +7384,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7334,17 +7406,32 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7357,13 +7444,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7379,17 +7466,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7428,7 +7515,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7438,11 +7525,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7468,13 +7555,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7484,17 +7571,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7519,7 +7606,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7533,23 +7620,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7629,19 +7716,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7661,17 +7748,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7689,23 +7776,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7764,15 +7851,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -7791,27 +7878,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7867,7 +7954,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7984,11 +8071,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8013,19 +8100,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8048,27 +8135,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8123,7 +8210,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8137,11 +8224,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8166,7 +8253,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8176,15 +8263,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8208,7 +8295,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -8220,15 +8307,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8245,17 +8332,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8271,17 +8358,17 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.30.yaml b/_vendor/github.com/moby/moby/api/docs/v1.30.yaml index 099f08b2d2d3..16b01b6aa29e 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.30.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.30.yaml @@ -733,7 +733,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -905,9 +905,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2174,7 +2176,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2393,6 +2395,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2448,6 +2474,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2631,7 +2664,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -2948,7 +2981,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -3079,11 +3112,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3242,7 +3275,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -3262,26 +3295,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3294,7 +3327,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3550,14 +3583,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3579,7 +3612,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3626,14 +3659,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3658,23 +3691,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3731,7 +3764,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -3758,14 +3791,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3784,16 +3817,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3821,7 +3854,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3917,14 +3950,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3948,18 +3981,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -3985,20 +4018,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4012,26 +4049,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4045,22 +4084,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4074,6 +4115,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -4081,16 +4124,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4105,6 +4148,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -4114,7 +4159,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -4123,14 +4168,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4172,20 +4217,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4200,6 +4245,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -4210,16 +4257,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4229,6 +4276,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -4236,16 +4285,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4255,6 +4304,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -4340,22 +4391,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4405,22 +4456,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4452,7 +4503,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4462,18 +4513,18 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4501,27 +4552,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4546,6 +4597,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4553,24 +4606,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4590,22 +4643,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4630,27 +4684,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4693,7 +4747,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4707,7 +4761,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4720,7 +4774,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4755,7 +4809,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4854,14 +4908,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4870,10 +4927,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4882,6 +4941,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4893,9 +4953,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4926,13 +4986,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4948,13 +5008,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4994,7 +5054,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -5075,14 +5135,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5100,7 +5160,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -5130,11 +5190,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5158,13 +5218,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5206,21 +5266,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5251,7 +5311,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -5262,15 +5322,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5299,7 +5359,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -5333,7 +5393,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5376,7 +5436,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5390,7 +5450,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5403,7 +5463,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -5421,9 +5481,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5441,7 +5501,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5645,7 +5705,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5657,7 +5717,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5694,7 +5754,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5704,9 +5764,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -5718,7 +5779,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5732,18 +5793,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5811,7 +5872,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5851,11 +5912,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5890,7 +5951,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5969,7 +6030,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6005,12 +6066,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6034,20 +6095,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -6064,9 +6126,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6093,22 +6155,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6179,13 +6241,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -6216,17 +6278,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6255,7 +6317,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6299,11 +6361,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6321,7 +6383,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -6355,7 +6417,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6385,11 +6447,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6434,15 +6496,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6459,17 +6521,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6484,6 +6546,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6501,7 +6565,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6515,7 +6579,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6532,7 +6596,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6589,7 +6653,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6615,15 +6679,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6644,17 +6708,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6664,6 +6728,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6675,7 +6741,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6688,19 +6754,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6785,17 +6851,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6831,17 +6897,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6881,7 +6947,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6891,7 +6957,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6903,13 +6969,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6929,7 +6995,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6958,7 +7024,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6980,9 +7046,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7042,15 +7108,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7066,15 +7132,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7095,13 +7161,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7122,13 +7188,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7150,13 +7216,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7207,6 +7273,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -7215,9 +7283,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7233,6 +7301,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -7247,13 +7317,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7278,33 +7348,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7327,19 +7399,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7354,17 +7426,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7385,21 +7457,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7425,7 +7497,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -7482,15 +7554,15 @@ paths: -----END CERTIFICATE----- CertIssuerSubject: "MBMxETAPBgNVBAMTCHN3YXJtLWNh" CertIssuerPublicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7503,21 +7575,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7566,17 +7638,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7588,10 +7660,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -7605,11 +7688,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7623,13 +7710,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7645,17 +7732,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7694,7 +7781,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7704,11 +7791,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7734,13 +7821,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7750,17 +7837,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7785,7 +7872,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7799,23 +7886,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7904,19 +7991,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7936,17 +8023,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7964,23 +8051,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8039,15 +8126,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -8066,27 +8153,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8142,7 +8229,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8259,11 +8346,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8288,19 +8375,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8323,27 +8410,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8398,7 +8485,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8412,11 +8499,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8441,7 +8528,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8451,15 +8538,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8483,7 +8570,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -8496,15 +8583,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8521,17 +8608,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8547,21 +8634,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8590,7 +8677,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8604,11 +8691,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8622,7 +8709,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -8633,7 +8719,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8643,15 +8729,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8675,7 +8761,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -8688,15 +8774,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8713,17 +8799,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8739,21 +8825,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8783,7 +8869,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -8844,14 +8930,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.31.yaml b/_vendor/github.com/moby/moby/api/docs/v1.31.yaml index 164b454e5c63..f458ef9cf714 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.31.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.31.yaml @@ -733,7 +733,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -905,9 +905,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2203,7 +2205,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2422,6 +2424,30 @@ definitions: - "shutdown" - "failed" - "rejected" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2477,6 +2503,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -2660,7 +2693,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -3021,7 +3054,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -3152,11 +3185,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3315,7 +3348,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -3335,26 +3368,26 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 406: + "406": description: "impossible to attach" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3367,7 +3400,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3623,14 +3656,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3652,7 +3685,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3699,14 +3732,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3731,23 +3764,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3804,7 +3837,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -3831,14 +3864,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3857,16 +3890,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -3894,7 +3927,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -3990,14 +4023,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4021,18 +4054,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -4058,20 +4091,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4085,26 +4122,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4118,22 +4157,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4147,6 +4188,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -4154,16 +4197,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4178,6 +4221,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -4187,7 +4232,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -4196,14 +4241,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4245,20 +4290,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4273,6 +4318,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -4283,16 +4330,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4302,6 +4349,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -4309,16 +4358,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4328,6 +4377,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -4413,22 +4464,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4478,22 +4529,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4525,7 +4576,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -4535,18 +4586,18 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4574,27 +4625,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4619,6 +4670,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -4626,24 +4679,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4663,22 +4716,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4703,27 +4757,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4766,7 +4820,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -4780,7 +4834,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4793,7 +4847,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -4828,7 +4882,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4927,14 +4981,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -4943,10 +5000,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -4955,6 +5014,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -4966,9 +5026,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -4999,13 +5059,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5017,7 +5077,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5026,7 +5086,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5042,13 +5102,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5088,7 +5148,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -5169,14 +5229,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5194,7 +5254,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -5224,11 +5284,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5252,13 +5312,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5300,21 +5360,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5345,7 +5405,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -5356,15 +5416,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5393,7 +5453,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -5427,7 +5487,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5470,7 +5530,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5484,7 +5544,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5497,7 +5557,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -5515,9 +5575,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5535,7 +5595,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5739,7 +5799,7 @@ paths: - "State" - "Healthy" SystemTime: "2015-03-10T11:11:23.730591467-07:00" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5751,7 +5811,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5788,7 +5848,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5798,9 +5858,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -5812,7 +5873,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5826,18 +5887,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5907,7 +5968,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5947,11 +6008,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5986,7 +6047,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6065,7 +6126,7 @@ paths: UsageData: Size: 0 RefCount: 0 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6101,12 +6162,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6130,20 +6191,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -6160,9 +6222,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6189,22 +6251,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6275,13 +6337,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -6312,17 +6374,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6351,7 +6413,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6395,11 +6457,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6417,7 +6479,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -6452,7 +6514,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6482,11 +6544,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6531,15 +6593,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6556,17 +6618,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6581,6 +6643,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -6598,7 +6662,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6612,7 +6676,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6629,7 +6693,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6686,7 +6750,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6712,15 +6776,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6745,17 +6809,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6765,6 +6829,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -6776,7 +6842,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -6789,19 +6855,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6886,17 +6952,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6932,17 +6998,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6982,7 +7048,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6992,7 +7058,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7004,13 +7070,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7030,7 +7096,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7059,7 +7125,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7081,9 +7147,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7143,15 +7209,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7167,15 +7233,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7196,13 +7262,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7223,13 +7289,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7251,13 +7317,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7308,6 +7374,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -7316,9 +7384,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7334,6 +7402,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -7348,13 +7418,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7379,33 +7449,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7428,19 +7500,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7455,17 +7527,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7486,21 +7558,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7526,7 +7598,7 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: allOf: @@ -7583,15 +7655,15 @@ paths: -----END CERTIFICATE----- CertIssuerSubject: "MBMxETAPBgNVBAMTCHN3YXJtLWNh" CertIssuerPublicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7604,21 +7676,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7667,17 +7739,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7689,10 +7761,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -7706,11 +7789,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -7724,13 +7811,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7746,17 +7833,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7795,7 +7882,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7805,11 +7892,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7835,13 +7922,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7851,17 +7938,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -7886,7 +7973,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -7900,23 +7987,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8005,19 +8092,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8037,17 +8124,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8065,23 +8152,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8140,15 +8227,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -8167,27 +8254,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8243,7 +8330,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8360,11 +8447,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8389,19 +8476,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8424,27 +8511,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8499,7 +8586,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8529,11 +8616,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8558,7 +8645,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8568,15 +8655,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8605,7 +8692,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -8626,15 +8713,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8651,17 +8738,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8677,21 +8764,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8720,7 +8807,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8734,11 +8821,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8752,7 +8839,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -8763,7 +8849,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8773,15 +8859,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8805,7 +8891,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -8818,15 +8904,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8843,17 +8929,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8869,21 +8955,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8913,7 +8999,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -8974,14 +9060,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9024,13 +9110,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.32.yaml b/_vendor/github.com/moby/moby/api/docs/v1.32.yaml index 6e05d83f7bb6..833beeb59875 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.32.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.32.yaml @@ -799,7 +799,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -971,9 +971,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2665,7 +2667,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2879,6 +2881,29 @@ definitions: - "failed" - "rejected" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2936,6 +2961,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3132,7 +3164,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4138,7 +4170,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4236,7 +4267,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4367,11 +4398,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4530,7 +4561,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4550,22 +4581,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4578,7 +4609,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4831,14 +4862,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4860,7 +4891,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4907,14 +4938,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4939,23 +4970,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5012,7 +5043,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5039,14 +5070,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5065,16 +5096,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5102,7 +5133,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5198,14 +5229,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5229,18 +5260,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5266,20 +5297,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5293,26 +5328,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5326,22 +5363,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5355,6 +5394,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5362,16 +5403,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5386,6 +5427,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5395,7 +5438,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5404,14 +5447,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5452,20 +5495,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5480,6 +5523,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5490,16 +5535,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5509,6 +5554,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5516,16 +5563,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5535,6 +5582,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5620,22 +5669,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5685,22 +5734,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5732,7 +5781,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5742,18 +5791,18 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5781,27 +5830,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5826,6 +5875,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5833,24 +5884,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5870,22 +5921,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5910,27 +5962,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5973,7 +6025,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5987,7 +6039,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6000,7 +6052,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6035,7 +6087,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6134,14 +6186,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6150,10 +6205,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -6162,6 +6219,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6173,9 +6231,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6206,13 +6264,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6224,7 +6282,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6233,7 +6291,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6249,13 +6307,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6300,7 +6358,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6381,14 +6439,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6406,7 +6464,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6436,11 +6494,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6464,13 +6522,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6512,21 +6570,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6557,7 +6615,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6568,15 +6626,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6605,7 +6663,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6639,7 +6697,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6682,7 +6740,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6696,7 +6754,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6709,7 +6767,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6727,9 +6785,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6747,11 +6805,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6763,7 +6821,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6800,7 +6858,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6810,9 +6868,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6824,7 +6883,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6838,18 +6897,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6919,7 +6978,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6959,11 +7018,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6998,7 +7057,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7077,7 +7136,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7113,12 +7172,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7142,20 +7201,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7172,9 +7232,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7201,22 +7261,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7287,13 +7347,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7324,17 +7384,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7363,7 +7423,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7407,11 +7467,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7429,7 +7489,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7464,7 +7524,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7494,11 +7554,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7543,15 +7603,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7568,17 +7628,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7593,6 +7653,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7610,7 +7672,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7624,7 +7686,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7641,7 +7703,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7698,7 +7760,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7724,15 +7786,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7757,17 +7819,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7777,6 +7839,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7788,7 +7852,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7801,19 +7865,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7898,17 +7962,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7944,17 +8008,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7994,7 +8058,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8004,7 +8068,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8016,13 +8080,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8042,7 +8106,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8071,7 +8135,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8093,9 +8157,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8155,15 +8219,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8179,15 +8243,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8208,13 +8272,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8235,13 +8299,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8263,13 +8327,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8320,6 +8384,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8328,9 +8394,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8346,6 +8412,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8360,13 +8428,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8391,33 +8459,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8440,19 +8510,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8467,17 +8537,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8498,21 +8568,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8538,19 +8608,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8563,21 +8633,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8626,17 +8696,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8648,10 +8718,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8665,11 +8746,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8683,13 +8768,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8705,17 +8790,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8754,7 +8839,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8764,11 +8849,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8794,13 +8879,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8810,17 +8895,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8845,7 +8930,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8859,23 +8944,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8964,19 +9049,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8996,17 +9081,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9024,23 +9109,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9099,15 +9184,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9126,27 +9211,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9202,7 +9287,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9319,11 +9404,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9348,19 +9433,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9383,27 +9468,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9458,7 +9543,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9488,11 +9573,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9517,7 +9602,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9527,15 +9612,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9564,7 +9649,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9585,15 +9670,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9610,17 +9695,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9636,21 +9721,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9679,7 +9764,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9693,11 +9778,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9711,7 +9796,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9722,7 +9806,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9732,15 +9816,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9764,7 +9848,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9777,15 +9861,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9802,17 +9886,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9828,21 +9912,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9872,7 +9956,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -9933,14 +10017,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9983,13 +10067,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.33.yaml b/_vendor/github.com/moby/moby/api/docs/v1.33.yaml index 9ba99a65161c..480e5a52bc11 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.33.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.33.yaml @@ -803,7 +803,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -975,9 +975,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2669,7 +2671,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2883,6 +2885,29 @@ definitions: - "failed" - "rejected" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2940,6 +2965,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3136,7 +3168,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4142,7 +4174,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4240,7 +4271,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4371,11 +4402,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4534,7 +4565,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4554,22 +4585,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4582,7 +4613,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4835,14 +4866,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4864,7 +4895,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4911,14 +4942,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4943,23 +4974,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5016,7 +5047,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5043,14 +5074,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5069,16 +5100,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5106,7 +5137,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5202,14 +5233,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5233,18 +5264,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5270,20 +5301,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5297,26 +5332,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5330,22 +5367,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5359,6 +5398,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5366,16 +5407,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5390,6 +5431,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5399,7 +5442,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5408,14 +5451,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5456,20 +5499,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5484,6 +5527,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5494,16 +5539,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5513,6 +5558,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5520,16 +5567,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5539,6 +5586,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5624,22 +5673,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5689,22 +5738,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5736,7 +5785,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5746,18 +5795,18 @@ paths: description: "Exit code of the container" type: "integer" x-nullable: false - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5785,27 +5834,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5830,6 +5879,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5837,24 +5888,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5874,22 +5925,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5914,27 +5966,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5977,7 +6029,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -5991,7 +6043,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6004,7 +6056,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6039,7 +6091,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6138,14 +6190,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6154,10 +6209,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -6166,6 +6223,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6177,9 +6235,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6210,13 +6268,13 @@ paths: Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. type: "string" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6228,7 +6286,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6237,7 +6295,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6253,13 +6311,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6304,7 +6362,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6385,14 +6443,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6410,7 +6468,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6440,11 +6498,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6468,13 +6526,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6516,21 +6574,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6561,7 +6619,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6572,15 +6630,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6609,7 +6667,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6643,7 +6701,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6686,7 +6744,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6700,7 +6758,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6713,7 +6771,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6731,9 +6789,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6751,11 +6809,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6767,7 +6825,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6804,7 +6862,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6814,9 +6872,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6828,7 +6887,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6842,18 +6901,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6923,7 +6982,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6963,11 +7022,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7006,7 +7065,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7085,7 +7144,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7121,12 +7180,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7150,20 +7209,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7180,9 +7240,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7209,22 +7269,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7295,13 +7355,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7332,17 +7392,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7371,7 +7431,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7415,11 +7475,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7437,7 +7497,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7472,7 +7532,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7502,11 +7562,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7551,15 +7611,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7576,17 +7636,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7601,6 +7661,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7618,7 +7680,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7632,7 +7694,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7649,7 +7711,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7706,7 +7768,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7732,15 +7794,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7765,17 +7827,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7785,6 +7847,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7796,7 +7860,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7809,19 +7873,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7906,17 +7970,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7952,17 +8016,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8002,7 +8066,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8012,7 +8076,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8024,13 +8088,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8050,7 +8114,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8079,7 +8143,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8101,9 +8165,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8163,15 +8227,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8187,15 +8251,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8216,13 +8280,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8243,13 +8307,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8271,13 +8335,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8328,6 +8392,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8336,9 +8402,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8354,6 +8420,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8368,13 +8436,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8399,33 +8467,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8448,19 +8518,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8475,17 +8545,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8506,21 +8576,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8546,19 +8616,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8571,21 +8641,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8634,17 +8704,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8656,10 +8726,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8673,11 +8754,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8691,13 +8776,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8713,17 +8798,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8762,7 +8847,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8772,11 +8857,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8802,13 +8887,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8818,17 +8903,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8853,7 +8938,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8867,23 +8952,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8972,19 +9057,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9004,17 +9089,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9032,23 +9117,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9107,15 +9192,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9134,27 +9219,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9210,7 +9295,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9327,11 +9412,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9356,19 +9441,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9391,27 +9476,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9466,7 +9551,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9496,11 +9581,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9525,7 +9610,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9535,15 +9620,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9572,7 +9657,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9593,15 +9678,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9618,17 +9703,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9644,21 +9729,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9687,7 +9772,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9701,11 +9786,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9719,7 +9804,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9730,7 +9814,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9740,15 +9824,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9772,7 +9856,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9785,15 +9869,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9810,17 +9894,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9836,21 +9920,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9880,7 +9964,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -9941,14 +10025,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9991,13 +10075,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.34.yaml b/_vendor/github.com/moby/moby/api/docs/v1.34.yaml index 9791708705cb..fb15fcf37c88 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.34.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.34.yaml @@ -813,7 +813,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -985,9 +985,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2679,7 +2681,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2893,6 +2895,29 @@ definitions: - "failed" - "rejected" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2950,6 +2975,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3164,7 +3196,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4170,7 +4202,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4268,7 +4299,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4399,11 +4430,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4562,7 +4593,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4582,22 +4613,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4610,7 +4641,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4863,14 +4894,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4892,7 +4923,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4939,14 +4970,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4971,23 +5002,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5044,7 +5075,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5071,14 +5102,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5097,16 +5128,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5134,7 +5165,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5230,14 +5261,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5261,18 +5292,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5298,20 +5329,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5325,26 +5360,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5358,22 +5395,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5387,6 +5426,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5394,16 +5435,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5418,6 +5459,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5427,7 +5470,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5436,14 +5479,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5484,20 +5527,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5512,6 +5555,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5522,16 +5567,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5541,6 +5586,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5548,16 +5595,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5567,6 +5614,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5652,22 +5701,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5717,22 +5766,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5764,7 +5813,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5781,18 +5830,18 @@ paths: Message: description: "Details of an error" type: "string" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5820,27 +5869,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5865,6 +5914,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5872,24 +5923,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5909,22 +5960,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5949,27 +6001,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6012,7 +6064,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6026,7 +6078,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6039,7 +6091,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6074,7 +6126,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6173,14 +6225,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6189,10 +6244,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -6201,6 +6258,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6212,9 +6270,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6250,13 +6308,13 @@ paths: type: "string" default: "" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6268,7 +6326,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6277,7 +6335,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6293,13 +6351,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6344,7 +6402,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6425,14 +6483,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6450,7 +6508,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6480,11 +6538,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6508,13 +6566,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6556,21 +6614,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6601,7 +6659,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6612,15 +6670,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6649,7 +6707,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6683,7 +6741,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6726,7 +6784,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6740,7 +6798,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6753,7 +6811,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6771,9 +6829,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6791,11 +6849,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6807,7 +6865,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6844,7 +6902,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6854,9 +6912,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6868,7 +6927,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6882,18 +6941,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6963,7 +7022,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7003,11 +7062,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7046,7 +7105,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7125,7 +7184,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7161,12 +7220,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7190,20 +7249,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7220,9 +7280,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7249,22 +7309,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7335,13 +7395,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7372,17 +7432,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7411,7 +7471,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7455,11 +7515,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7477,7 +7537,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7512,7 +7572,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7542,11 +7602,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7591,15 +7651,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7616,17 +7676,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7641,6 +7701,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7658,7 +7720,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7672,7 +7734,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7689,7 +7751,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7746,7 +7808,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7772,15 +7834,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7805,17 +7867,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7825,6 +7887,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7836,7 +7900,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7849,19 +7913,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7946,17 +8010,17 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7992,17 +8056,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8042,7 +8106,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8052,7 +8116,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8064,13 +8128,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8090,7 +8154,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8119,7 +8183,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8141,9 +8205,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8203,15 +8267,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8227,15 +8291,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8256,13 +8320,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8283,13 +8347,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8311,13 +8375,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8368,6 +8432,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8376,9 +8442,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8394,6 +8460,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8408,13 +8476,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8439,33 +8507,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8488,19 +8558,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8515,17 +8585,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8546,21 +8616,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8586,19 +8656,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8611,21 +8681,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8674,17 +8744,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8696,10 +8766,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8713,11 +8794,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8731,13 +8816,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8753,17 +8838,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8802,7 +8887,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8812,11 +8897,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8842,13 +8927,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8858,17 +8943,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8893,7 +8978,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8907,23 +8992,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9012,19 +9097,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9044,17 +9129,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9072,23 +9157,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9147,15 +9232,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9174,27 +9259,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9250,7 +9335,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9367,11 +9452,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9396,19 +9481,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9431,27 +9516,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9506,7 +9591,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9536,11 +9621,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9565,7 +9650,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9575,15 +9660,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9612,7 +9697,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9633,15 +9718,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9658,17 +9743,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9684,21 +9769,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9727,7 +9812,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9741,11 +9826,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9759,7 +9844,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9770,7 +9854,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9780,15 +9864,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9812,7 +9896,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9825,15 +9909,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9850,17 +9934,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9876,21 +9960,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9920,7 +10004,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -9981,14 +10065,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10031,13 +10115,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.35.yaml b/_vendor/github.com/moby/moby/api/docs/v1.35.yaml index 03bb17201a93..5543fb1f710d 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.35.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.35.yaml @@ -814,7 +814,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -982,9 +982,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2676,7 +2678,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2897,6 +2899,29 @@ definitions: - "failed" - "rejected" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2954,6 +2979,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3168,7 +3200,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4174,7 +4206,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4272,7 +4303,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4403,11 +4434,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4566,7 +4597,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4586,22 +4617,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4614,7 +4645,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4867,14 +4898,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4896,7 +4927,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4943,14 +4974,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4975,23 +5006,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5053,7 +5084,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5080,14 +5111,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5106,16 +5137,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5143,7 +5174,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5239,14 +5270,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5270,18 +5301,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5307,20 +5338,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5334,26 +5369,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5367,22 +5404,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5396,6 +5435,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5403,16 +5444,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5427,6 +5468,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5436,7 +5479,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5445,14 +5488,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5493,20 +5536,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5521,6 +5564,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5531,16 +5576,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5550,6 +5595,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5557,16 +5604,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5576,6 +5623,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5661,22 +5710,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5726,22 +5775,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5773,7 +5822,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5790,18 +5839,18 @@ paths: Message: description: "Details of an error" type: "string" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5829,27 +5878,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5874,6 +5923,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5881,24 +5932,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5918,22 +5969,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5958,27 +6010,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6021,7 +6073,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6035,7 +6087,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6048,7 +6100,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6083,7 +6135,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6182,14 +6234,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6198,10 +6253,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -6210,6 +6267,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6221,9 +6279,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6259,13 +6317,13 @@ paths: type: "string" default: "" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6277,7 +6335,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6286,7 +6344,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6302,13 +6360,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6353,7 +6411,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6434,14 +6492,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6459,7 +6517,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6489,11 +6547,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6517,13 +6575,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6565,21 +6623,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6610,7 +6668,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6621,15 +6679,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6658,7 +6716,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6692,7 +6750,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6735,7 +6793,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6749,7 +6807,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6762,7 +6820,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6780,9 +6838,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6800,11 +6858,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6816,7 +6874,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6875,7 +6933,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6885,9 +6943,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6899,7 +6958,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6913,18 +6972,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6994,7 +7053,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7034,11 +7093,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7077,7 +7136,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7156,7 +7215,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7192,12 +7251,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7221,20 +7280,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7251,9 +7311,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7280,22 +7340,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7369,13 +7429,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7406,17 +7466,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7445,7 +7505,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7489,11 +7549,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7511,7 +7571,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7546,7 +7606,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7576,11 +7636,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7625,15 +7685,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7650,17 +7710,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7675,6 +7735,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7692,7 +7754,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7706,7 +7768,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7723,7 +7785,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7780,7 +7842,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7806,15 +7868,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7839,17 +7901,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7859,6 +7921,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7870,7 +7934,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7883,19 +7947,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7980,17 +8044,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8026,17 +8090,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8076,7 +8140,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8086,7 +8150,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8098,13 +8162,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8124,7 +8188,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8153,7 +8217,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8175,9 +8239,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8237,15 +8301,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8261,15 +8325,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8290,13 +8354,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8317,13 +8381,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8345,13 +8409,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8402,6 +8466,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8410,9 +8476,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8428,6 +8494,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8442,13 +8510,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8473,33 +8541,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8522,19 +8592,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8549,17 +8619,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8580,21 +8650,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8620,19 +8690,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8645,21 +8715,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8708,17 +8778,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8730,10 +8800,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8747,11 +8828,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8765,13 +8850,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8787,17 +8872,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8836,7 +8921,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8846,11 +8931,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8876,13 +8961,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8892,17 +8977,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8927,7 +9012,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8941,23 +9026,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9046,19 +9131,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9078,17 +9163,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9106,23 +9191,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9181,15 +9266,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9208,27 +9293,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9284,7 +9369,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9401,11 +9486,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9430,19 +9515,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9465,27 +9550,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9540,7 +9625,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9570,11 +9655,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9599,7 +9684,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9609,15 +9694,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9646,7 +9731,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9667,15 +9752,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9692,17 +9777,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9718,21 +9803,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9761,7 +9846,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9775,11 +9860,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9793,7 +9878,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9804,7 +9888,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9814,15 +9898,15 @@ paths: type: "string" example: ID: "ktnbjxoalbkvbvedmg1urrz8h" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9846,7 +9930,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9859,15 +9943,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9884,17 +9968,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9910,21 +9994,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9954,7 +10038,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -10015,14 +10099,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10065,13 +10149,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.36.yaml b/_vendor/github.com/moby/moby/api/docs/v1.36.yaml index ab036218c8e6..895e8817fe30 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.36.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.36.yaml @@ -818,7 +818,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -986,9 +986,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2693,7 +2695,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2914,6 +2916,29 @@ definitions: - "failed" - "rejected" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2971,6 +2996,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3185,7 +3217,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4195,7 +4227,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4293,7 +4324,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4424,11 +4455,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4588,7 +4619,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4610,22 +4641,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4638,7 +4669,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4893,14 +4924,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4922,7 +4953,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4971,14 +5002,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5003,23 +5034,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5081,7 +5112,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5110,14 +5141,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5136,16 +5167,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5173,7 +5204,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5269,14 +5300,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5300,18 +5331,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5337,20 +5368,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5364,26 +5399,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5397,22 +5434,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5426,6 +5465,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5433,16 +5474,16 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5457,6 +5498,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5466,7 +5509,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5477,14 +5520,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5526,20 +5569,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5554,6 +5597,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5564,16 +5609,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5583,6 +5628,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5590,16 +5637,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5609,6 +5656,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5694,22 +5743,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5759,22 +5808,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5806,7 +5855,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5825,18 +5874,18 @@ paths: Message: description: "Details of an error" type: "string" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5864,27 +5913,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5909,6 +5958,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5916,24 +5967,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5953,22 +6004,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5993,27 +6045,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6056,7 +6108,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6071,7 +6123,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6084,7 +6136,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6119,7 +6171,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6218,14 +6270,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6234,10 +6289,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values. [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)" @@ -6246,6 +6303,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6257,9 +6315,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6295,13 +6353,13 @@ paths: type: "string" default: "" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6313,7 +6371,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6323,7 +6381,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6339,13 +6397,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6390,7 +6448,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6471,14 +6529,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6496,7 +6554,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6526,11 +6584,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6554,13 +6612,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6602,21 +6660,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6647,7 +6705,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6658,15 +6716,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6695,7 +6753,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6730,7 +6788,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6773,7 +6831,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6788,7 +6846,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6801,7 +6859,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6820,9 +6878,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6840,11 +6898,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6856,7 +6914,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6916,7 +6974,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6926,9 +6984,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6940,7 +6999,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6954,18 +7013,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7035,7 +7094,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7076,11 +7135,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7119,7 +7178,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7199,7 +7258,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7235,12 +7294,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7264,20 +7323,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7294,9 +7354,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7323,22 +7383,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7412,13 +7472,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7449,17 +7509,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7488,7 +7548,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7537,11 +7597,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7559,7 +7619,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7595,7 +7655,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7625,11 +7685,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7674,15 +7734,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7699,17 +7759,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7724,6 +7784,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7741,7 +7803,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7756,7 +7818,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7773,7 +7835,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7830,7 +7892,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7856,15 +7918,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7889,17 +7951,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7909,6 +7971,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7920,7 +7984,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7934,19 +7998,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8031,17 +8095,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8077,17 +8141,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8127,7 +8191,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8138,7 +8202,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8150,13 +8214,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8176,7 +8240,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8206,7 +8270,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8228,9 +8292,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8290,15 +8354,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8314,15 +8378,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8343,13 +8407,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8370,13 +8434,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8398,13 +8462,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8455,6 +8519,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8463,9 +8529,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8481,6 +8547,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8495,13 +8563,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8526,33 +8594,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8575,19 +8645,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8602,17 +8672,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8633,21 +8703,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8673,19 +8743,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8698,21 +8768,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8761,17 +8831,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8783,10 +8853,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8800,11 +8881,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8818,13 +8903,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8840,17 +8925,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8889,7 +8974,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8900,11 +8985,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8930,13 +9015,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8946,17 +9031,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8981,7 +9066,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -8996,23 +9081,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9101,19 +9186,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9133,17 +9218,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9161,23 +9246,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9236,15 +9321,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9263,27 +9348,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9339,7 +9424,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9456,11 +9541,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9485,19 +9570,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9520,27 +9605,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9595,7 +9680,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9625,11 +9710,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9654,19 +9739,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9695,7 +9780,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9716,15 +9801,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9741,17 +9826,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9767,21 +9852,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9810,7 +9895,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9824,11 +9909,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9842,7 +9927,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9853,19 +9937,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9889,7 +9973,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9902,15 +9986,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9927,17 +10011,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9953,21 +10037,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9997,7 +10081,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -10059,14 +10143,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10109,13 +10193,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.37.yaml b/_vendor/github.com/moby/moby/api/docs/v1.37.yaml index 71c292576d64..19c36c63839a 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.37.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.37.yaml @@ -822,7 +822,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -989,9 +989,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2696,7 +2698,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2919,6 +2921,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -2976,6 +3001,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3191,7 +3223,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4215,7 +4247,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4313,7 +4344,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4444,11 +4475,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4608,7 +4639,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4630,22 +4661,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4658,7 +4689,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4913,14 +4944,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4942,7 +4973,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4991,14 +5022,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5023,23 +5054,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5101,7 +5132,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5130,14 +5161,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5156,16 +5187,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5193,7 +5224,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5289,14 +5320,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5320,18 +5351,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5357,20 +5388,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5384,26 +5419,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5417,22 +5454,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5446,6 +5485,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5453,23 +5494,23 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5484,6 +5525,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5493,7 +5536,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5504,14 +5547,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5553,20 +5596,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5581,6 +5624,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5591,16 +5636,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5610,6 +5655,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5617,16 +5664,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5636,6 +5683,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5721,22 +5770,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5786,22 +5835,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5833,7 +5882,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5852,18 +5901,18 @@ paths: Message: description: "Details of an error" type: "string" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5891,27 +5940,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5936,6 +5985,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5943,24 +5994,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5980,22 +6031,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6020,27 +6072,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6083,7 +6135,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6098,7 +6150,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6111,7 +6163,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6146,7 +6198,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6245,14 +6297,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6261,10 +6316,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -6284,6 +6341,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6295,9 +6353,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6338,13 +6396,13 @@ paths: type: "string" default: "" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6356,7 +6414,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6366,7 +6424,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6382,13 +6440,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6433,7 +6491,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6514,14 +6572,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6539,7 +6597,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6569,11 +6627,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6597,13 +6655,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6645,21 +6703,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6690,7 +6748,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6701,15 +6759,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6738,7 +6796,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6773,7 +6831,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6816,7 +6874,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6831,7 +6889,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6844,7 +6902,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6863,9 +6921,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6883,11 +6941,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6899,7 +6957,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6959,7 +7017,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6969,9 +7027,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -6983,7 +7042,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6997,18 +7056,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7078,7 +7137,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7119,11 +7178,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7162,7 +7221,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7242,7 +7301,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7278,12 +7337,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7307,20 +7366,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7337,9 +7397,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7366,22 +7426,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7455,13 +7515,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7492,17 +7552,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7531,7 +7591,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7580,11 +7640,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7602,7 +7662,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7638,7 +7698,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7668,11 +7728,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7717,15 +7777,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7742,17 +7802,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7767,6 +7827,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7784,7 +7846,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7799,7 +7861,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7816,7 +7878,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7873,7 +7935,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7899,15 +7961,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7932,17 +7994,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7952,6 +8014,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -7963,7 +8027,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -7977,19 +8041,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8074,17 +8138,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8120,17 +8184,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8170,7 +8234,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8181,7 +8245,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8193,13 +8257,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8219,7 +8283,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8249,7 +8313,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8271,9 +8335,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8333,15 +8397,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8357,15 +8421,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8386,13 +8450,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8413,13 +8477,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8441,13 +8505,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8498,6 +8562,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8506,9 +8572,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8524,6 +8590,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8538,13 +8606,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8569,33 +8637,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8618,19 +8688,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8645,17 +8715,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8676,21 +8746,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8716,19 +8786,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8741,21 +8811,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8804,17 +8874,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8826,10 +8896,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8843,11 +8924,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8861,13 +8946,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8883,17 +8968,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8932,7 +9017,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8943,11 +9028,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8973,13 +9058,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8989,17 +9074,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9024,7 +9109,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9039,23 +9124,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9144,19 +9229,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9176,17 +9261,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9204,23 +9289,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9279,15 +9364,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9306,27 +9391,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9382,7 +9467,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9499,11 +9584,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9528,19 +9613,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9563,27 +9648,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9638,7 +9723,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9668,11 +9753,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9697,19 +9782,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9738,7 +9823,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9759,15 +9844,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9784,17 +9869,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9810,21 +9895,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9853,7 +9938,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9867,11 +9952,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9885,7 +9970,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9896,19 +9980,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9932,7 +10016,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -9945,15 +10029,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9970,17 +10054,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9996,21 +10080,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10040,7 +10124,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -10102,14 +10186,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10152,13 +10236,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.38.yaml b/_vendor/github.com/moby/moby/api/docs/v1.38.yaml index 5ebc08b5b3e8..f0b377432c82 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.38.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.38.yaml @@ -819,7 +819,7 @@ definitions: SecurityOpt: type: "array" description: "A list of string values to customize labels for MLS - systems, such as SELinux." + systems, such as SELinux." items: type: "string" StorageOpt: @@ -996,9 +996,11 @@ definitions: type: "string" default: "SIGTERM" StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 + x-nullable: true Shell: description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell." type: "array" @@ -2726,7 +2728,7 @@ definitions: description: "Amount of time to wait for the container to terminate before forcefully killing it." type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -2969,6 +2971,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -3026,6 +3051,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -3241,7 +3273,7 @@ definitions: properties: Mode: description: "The mode of resolution to use for internal load balancing - between tasks." + between tasks." type: "string" enum: - "vip" @@ -4261,7 +4293,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -4359,7 +4390,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -4490,11 +4521,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4653,7 +4684,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -4675,22 +4706,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4703,7 +4734,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -4964,14 +4995,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -4993,7 +5024,7 @@ paths: description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows." operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5042,14 +5073,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5074,23 +5105,23 @@ paths: Note: This endpoint works only for containers with the `json-file` or `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5152,7 +5183,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -5181,14 +5212,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5207,16 +5238,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5244,7 +5275,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -5340,14 +5371,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5371,18 +5402,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -5408,20 +5439,24 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" schema: $ref: "#/definitions/ErrorResponse" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5435,26 +5470,28 @@ paths: in: "query" description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`." type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5468,22 +5505,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5497,6 +5536,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -5504,23 +5545,23 @@ paths: description: "Send a POSIX signal to a container, defaulting to killing to the container." operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5535,6 +5576,8 @@ paths: description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)" type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -5544,7 +5587,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -5555,14 +5598,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5603,20 +5646,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5631,6 +5674,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -5641,16 +5686,16 @@ paths: Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5660,6 +5705,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -5667,16 +5714,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5686,6 +5733,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -5771,22 +5820,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5836,22 +5885,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5883,7 +5932,7 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: type: "object" @@ -5902,18 +5951,18 @@ paths: Message: description: "Details of an error" type: "string" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5941,27 +5990,27 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5986,6 +6035,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -5993,24 +6044,24 @@ paths: description: "A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path." operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: type: "string" description: "TODO" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6030,22 +6081,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6070,27 +6122,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6133,7 +6185,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6148,7 +6200,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6161,7 +6213,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" @@ -6196,7 +6248,7 @@ paths: SharedSize: 0 Labels: {} Containers: 5 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6295,14 +6347,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -6311,10 +6366,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -6334,6 +6391,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -6345,9 +6403,9 @@ paths: - name: "networkmode" in: "query" description: "Sets the networking mode for the run commands during - build. Supported standard values are: `bridge`, `host`, `none`, and - `container:<name|id>`. Any other value is taken as a custom network's - name to which this container should connect to." + build. Supported standard values are: `bridge`, `host`, `none`, and + `container:<name|id>`. Any other value is taken as a custom network's + name to which this container should connect to." type: "string" - name: "Content-type" in: "header" @@ -6398,13 +6456,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6416,7 +6474,7 @@ paths: - "application/json" operationId: "BuildPrune" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6426,7 +6484,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6442,13 +6500,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6493,7 +6551,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Image" @@ -6574,14 +6632,14 @@ paths: Layers: - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6599,7 +6657,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -6629,11 +6687,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6657,13 +6715,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6705,21 +6763,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6750,7 +6808,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -6761,15 +6819,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6798,7 +6856,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -6833,7 +6891,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6876,7 +6934,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -6891,7 +6949,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6904,7 +6962,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -6923,9 +6981,9 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6943,11 +7001,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6959,7 +7017,7 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7019,7 +7077,7 @@ paths: MinAPIVersion: "1.12" BuildTime: "2016-06-14T07:09:13.444803460+00:00" Experimental: true - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7029,9 +7087,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -7043,7 +7102,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7057,18 +7116,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7138,7 +7197,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7179,11 +7238,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7222,7 +7281,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7302,7 +7361,7 @@ paths: UsageData: Size: 10920104 RefCount: 2 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7338,12 +7397,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7367,20 +7426,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -7397,9 +7457,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7426,22 +7486,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7515,13 +7575,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -7552,17 +7612,17 @@ paths: description: "Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance." operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7591,7 +7651,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7640,11 +7700,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7662,7 +7722,7 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: type: "object" @@ -7698,7 +7758,7 @@ paths: o: "size=100m,uid=1000" type: "tmpfs" Warnings: [] - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7728,11 +7788,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7777,15 +7837,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7802,17 +7862,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7827,6 +7887,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: post: @@ -7844,7 +7906,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7859,7 +7921,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7876,7 +7938,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -7933,7 +7995,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7959,15 +8021,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7992,17 +8054,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8012,6 +8074,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -8023,7 +8087,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -8037,19 +8101,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8134,17 +8198,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8180,17 +8244,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8230,7 +8294,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8241,7 +8305,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8253,13 +8317,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8279,7 +8343,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -8309,7 +8373,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8331,9 +8395,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8393,15 +8457,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8417,15 +8481,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8446,13 +8510,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8473,13 +8537,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8501,13 +8565,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8558,6 +8622,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -8566,9 +8632,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8584,6 +8650,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -8598,13 +8666,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8629,33 +8697,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8678,19 +8748,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8705,17 +8775,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8736,21 +8806,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8776,19 +8846,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8801,21 +8871,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8864,17 +8934,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8886,10 +8956,21 @@ paths: type: "object" properties: ListenAddr: - description: "Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP)." + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: - description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. type: "string" DataPathAddr: description: | @@ -8903,11 +8984,15 @@ paths: type: "string" RemoteAddrs: - description: "Addresses of manager nodes already participating in the swarm." - type: "string" + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -8921,13 +9006,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8943,17 +9028,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -8992,7 +9077,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9003,11 +9088,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9033,13 +9118,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9049,17 +9134,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9084,7 +9169,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -9099,23 +9184,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9204,19 +9289,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9236,17 +9321,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9264,23 +9349,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9339,15 +9424,15 @@ paths: in: "query" type: "string" description: "If the X-Registry-Auth header is not specified, this - parameter indicates where to find registry authorization credentials. The - valid values are `spec` and `previous-spec`." + parameter indicates where to find registry authorization credentials. The + valid values are `spec` and `previous-spec`." default: "spec" - name: "rollback" in: "query" type: "string" description: "Set to this parameter to `previous` to cause a - server-side rollback to the previous service spec. The supplied spec will be - ignored in this case." + server-side rollback to the previous service spec. The supplied spec will be + ignored in this case." - name: "X-Registry-Auth" in: "header" description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)" @@ -9366,27 +9451,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9442,7 +9527,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9559,11 +9644,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9588,19 +9673,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9623,27 +9708,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9698,7 +9783,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9728,11 +9813,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9757,19 +9842,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9798,7 +9883,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -9819,15 +9904,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9844,17 +9929,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9870,21 +9955,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9913,7 +9998,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9927,11 +10012,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9945,7 +10030,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -9956,19 +10040,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9992,7 +10076,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -10005,15 +10089,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10030,17 +10114,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10056,21 +10140,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10100,7 +10184,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -10162,14 +10246,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10212,13 +10296,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.39.yaml b/_vendor/github.com/moby/moby/api/docs/v1.39.yaml index 5ab447c339a9..ac1dd1921588 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.39.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.39.yaml @@ -1171,10 +1171,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1275,9 +1274,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1358,10 +1358,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1526,36 +1525,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1835,11 +1830,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } ImageInspect: description: | @@ -3716,7 +3710,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4012,6 +4006,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4069,6 +4086,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5544,7 +5568,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -5674,7 +5697,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerSummary" @@ -5805,11 +5828,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -5963,7 +5986,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -5985,22 +6008,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6013,7 +6036,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6238,14 +6261,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6269,7 +6292,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6320,14 +6343,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6353,23 +6376,23 @@ paths: `journald` logging driver. operationId: "ContainerLogs" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6433,7 +6456,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -6462,14 +6485,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6488,16 +6511,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6536,7 +6559,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6632,14 +6655,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6665,18 +6688,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -6702,18 +6725,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6730,24 +6757,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6761,22 +6790,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6790,6 +6821,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -6799,23 +6832,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6831,6 +6864,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -6842,7 +6877,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -6853,14 +6888,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6901,20 +6936,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6929,6 +6964,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -6942,16 +6979,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6961,6 +6998,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -6968,16 +7007,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6987,6 +7026,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -7090,22 +7131,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7162,22 +7203,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7212,22 +7253,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7255,20 +7296,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -7277,7 +7318,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7302,6 +7343,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -7312,7 +7355,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -7320,18 +7363,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7351,22 +7394,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7391,27 +7435,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7467,7 +7511,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7482,7 +7526,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7495,13 +7539,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7603,14 +7647,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -7619,10 +7666,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -7642,6 +7691,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -7707,13 +7757,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7752,7 +7802,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7767,7 +7817,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7783,13 +7833,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7842,18 +7892,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7871,7 +7921,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -7901,11 +7951,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7931,13 +7981,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7983,21 +8033,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8028,7 +8078,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -8039,15 +8089,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8076,7 +8126,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -8111,7 +8161,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8154,7 +8204,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8169,7 +8219,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8184,7 +8234,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -8203,13 +8253,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8227,11 +8277,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8243,11 +8293,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8257,9 +8307,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -8274,7 +8325,7 @@ paths: Docker-Experimental: type: "boolean" description: "If the server is running with experimental mode enabled" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8288,18 +8339,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8369,7 +8420,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8410,11 +8461,11 @@ paths: image: "alpine" name: "my-container" time: 1461943101 - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8453,7 +8504,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8560,7 +8611,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8596,12 +8647,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8630,20 +8681,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -8660,9 +8712,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8689,22 +8741,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8789,13 +8841,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -8828,17 +8880,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8867,7 +8919,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8916,11 +8968,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8938,11 +8990,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8972,11 +9024,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8995,15 +9047,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9020,17 +9072,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9045,6 +9097,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -9063,7 +9117,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9078,7 +9132,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9097,7 +9151,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9154,7 +9208,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9183,15 +9237,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9216,17 +9270,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9236,6 +9290,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -9247,7 +9303,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -9261,19 +9317,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9369,17 +9425,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9415,17 +9471,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9467,7 +9523,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9478,7 +9534,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9490,13 +9546,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9519,7 +9575,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9551,7 +9607,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9576,9 +9632,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9645,15 +9701,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9671,15 +9727,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9704,13 +9760,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9733,13 +9789,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9763,13 +9819,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9829,6 +9885,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -9837,9 +9895,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9857,6 +9915,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -9873,13 +9933,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9906,33 +9966,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9955,19 +10017,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -9982,17 +10044,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10013,21 +10075,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10055,19 +10117,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10080,21 +10142,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10174,17 +10236,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10199,7 +10261,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -10233,6 +10297,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -10246,13 +10311,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10270,17 +10335,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10321,7 +10386,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10332,11 +10397,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10362,13 +10427,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10378,17 +10443,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10416,7 +10481,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -10431,23 +10496,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10541,19 +10606,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10573,17 +10638,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10601,23 +10666,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10717,27 +10782,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10795,7 +10860,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10912,11 +10977,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10944,19 +11009,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10981,27 +11046,27 @@ paths: - "application/vnd.docker.raw-stream" - "application/json" responses: - 101: + "101": description: "logs returned as a stream" schema: type: "string" format: "binary" - 200: + "200": description: "logs returned as a string in response body" schema: type: "string" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11059,7 +11124,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11089,11 +11154,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11121,19 +11186,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11162,7 +11227,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -11183,15 +11248,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11208,17 +11273,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11234,21 +11299,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11282,7 +11347,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11296,11 +11361,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11317,7 +11382,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -11328,19 +11392,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11364,7 +11428,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -11377,15 +11441,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11402,17 +11466,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11428,21 +11492,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11478,7 +11542,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: type: "object" @@ -11542,14 +11606,14 @@ paths: Variant: "" Features: - "" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11595,13 +11659,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.40.yaml b/_vendor/github.com/moby/moby/api/docs/v1.40.yaml index 240f6d3de8d3..9693ebfe59d9 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.40.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.40.yaml @@ -1234,10 +1234,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1338,9 +1337,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1421,10 +1421,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1589,36 +1588,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1898,11 +1893,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } ImageInspect: description: | @@ -3808,7 +3802,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4141,6 +4135,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4198,6 +4215,13 @@ definitions: type: "integer" DesiredState: $ref: "#/definitions/TaskState" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5688,7 +5712,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -5970,7 +5993,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6103,11 +6126,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6270,7 +6293,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -6292,22 +6315,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6320,7 +6343,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6556,14 +6579,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6587,7 +6610,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6638,14 +6661,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6671,7 +6694,7 @@ paths: `journald` logging driver. operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -6680,14 +6703,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6748,7 +6771,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -6777,14 +6800,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6803,16 +6826,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6851,7 +6874,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6947,14 +6970,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6980,18 +7003,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7017,18 +7040,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7045,24 +7072,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7076,22 +7105,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7105,6 +7136,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7114,23 +7147,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7146,6 +7179,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7157,7 +7192,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7168,14 +7203,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7217,20 +7252,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7245,6 +7280,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7258,16 +7295,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7277,6 +7314,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7284,16 +7323,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7303,6 +7342,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -7406,22 +7447,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7478,22 +7519,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7528,22 +7569,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7571,20 +7612,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -7593,7 +7634,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7618,6 +7659,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -7628,7 +7671,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -7636,18 +7679,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7667,22 +7710,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7707,27 +7751,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7783,7 +7827,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -7798,7 +7842,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7811,13 +7855,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7919,14 +7963,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -7935,10 +7982,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -7958,6 +8007,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8039,13 +8089,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8084,7 +8134,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8099,7 +8149,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8115,13 +8165,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8166,10 +8216,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8186,18 +8238,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8215,7 +8267,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8245,11 +8297,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8275,13 +8327,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8327,21 +8379,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8372,7 +8424,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -8383,15 +8435,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8420,7 +8472,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -8455,7 +8507,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8498,7 +8550,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8513,7 +8565,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8528,7 +8580,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -8547,13 +8599,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8571,11 +8623,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8587,11 +8639,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8601,9 +8653,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -8624,7 +8677,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8642,7 +8695,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -8663,7 +8716,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8677,18 +8730,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8758,15 +8811,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8805,7 +8858,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -8912,7 +8965,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8948,12 +9001,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8982,20 +9035,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9012,9 +9066,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9041,22 +9095,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9142,13 +9196,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9182,17 +9236,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9221,7 +9275,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9270,11 +9324,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9292,11 +9346,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9326,11 +9380,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9349,15 +9403,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9374,17 +9428,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9399,6 +9453,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -9417,7 +9473,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9432,7 +9488,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9451,7 +9507,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9508,7 +9564,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9541,15 +9597,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9574,17 +9630,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9594,6 +9650,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -9605,7 +9663,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -9619,19 +9677,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9728,17 +9786,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9775,17 +9833,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9828,7 +9886,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9839,7 +9897,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9851,13 +9909,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9880,7 +9938,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -9899,7 +9957,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9924,9 +9982,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9981,15 +10039,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10007,15 +10065,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10040,13 +10098,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10069,13 +10127,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10099,13 +10157,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10153,6 +10211,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -10161,9 +10221,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10181,6 +10241,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -10197,13 +10259,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10230,33 +10292,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10280,19 +10344,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10307,17 +10371,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10338,21 +10402,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10380,19 +10444,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10405,21 +10469,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10508,17 +10572,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10534,7 +10598,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -10568,6 +10634,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -10581,13 +10648,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10605,17 +10672,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10656,7 +10723,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10667,11 +10734,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10698,13 +10765,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10714,17 +10781,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10752,7 +10819,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -10767,23 +10834,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10877,19 +10944,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10909,17 +10976,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10937,23 +11004,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11050,23 +11117,23 @@ paths: `json-file` or `journald` logging drivers. operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11121,7 +11188,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11238,11 +11305,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11270,19 +11337,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11304,23 +11371,23 @@ paths: `json-file` or `journald` logging drivers. operationId: "TaskLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11375,7 +11442,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11405,11 +11472,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11437,19 +11504,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11478,7 +11545,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -11499,15 +11566,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11524,17 +11591,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11550,21 +11617,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11598,7 +11665,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11612,11 +11679,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11633,7 +11700,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -11644,19 +11710,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11680,7 +11746,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -11693,15 +11759,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11718,17 +11784,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11744,21 +11810,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11794,18 +11860,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11848,13 +11914,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.41.yaml b/_vendor/github.com/moby/moby/api/docs/v1.41.yaml index fbbc8b5f80d5..d77c0a47da73 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.41.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.41.yaml @@ -1265,10 +1265,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1369,9 +1368,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1452,10 +1452,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1620,36 +1619,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1929,11 +1924,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } ImageInspect: description: | @@ -3935,7 +3929,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4306,6 +4300,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4369,6 +4386,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5942,7 +5966,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6224,7 +6247,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6357,11 +6380,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6546,7 +6569,7 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: type: "object" @@ -6568,22 +6591,22 @@ paths: application/json: Id: "e90e34656806" Warnings: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6596,7 +6619,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6832,14 +6855,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6863,7 +6886,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -6914,14 +6937,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6947,7 +6970,7 @@ paths: `journald` logging driver. operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -6956,14 +6979,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7024,7 +7047,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7053,14 +7076,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7079,16 +7102,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7133,7 +7156,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7229,14 +7252,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7269,18 +7292,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7306,18 +7329,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7334,24 +7361,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7365,22 +7394,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7394,6 +7425,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7403,23 +7436,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7435,6 +7468,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7446,7 +7481,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7457,14 +7492,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7506,20 +7541,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7534,6 +7569,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7547,16 +7584,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7566,6 +7603,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7573,16 +7612,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7592,6 +7631,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -7695,22 +7736,22 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7767,22 +7808,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7817,22 +7858,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7860,20 +7901,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -7882,7 +7923,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7907,6 +7948,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -7917,7 +7960,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -7925,18 +7968,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7956,22 +7999,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7996,27 +8040,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8072,7 +8116,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8087,7 +8131,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8100,13 +8144,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8208,14 +8252,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8224,10 +8271,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8247,6 +8296,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8328,13 +8378,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8373,7 +8423,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8388,7 +8438,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8404,13 +8454,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8455,10 +8505,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8475,18 +8527,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8504,7 +8556,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8534,11 +8586,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8564,13 +8616,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8616,21 +8668,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8661,7 +8713,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -8672,15 +8724,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8709,7 +8761,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -8744,7 +8796,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8787,7 +8839,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8802,7 +8854,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8817,7 +8869,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -8836,13 +8888,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8860,11 +8912,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8876,11 +8928,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8890,9 +8942,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -8913,7 +8966,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8931,7 +8984,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -8952,7 +9005,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8966,18 +9019,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9049,15 +9102,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9096,7 +9149,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9203,7 +9256,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9239,12 +9292,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9273,20 +9326,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9303,9 +9357,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9332,22 +9386,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9433,13 +9487,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9473,17 +9527,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9512,7 +9566,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9561,11 +9615,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9583,11 +9637,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9617,11 +9671,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9640,15 +9694,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9665,17 +9719,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9690,6 +9744,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -9708,7 +9764,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9723,7 +9779,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9742,7 +9798,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9799,7 +9855,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9832,15 +9888,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9865,17 +9921,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9885,6 +9941,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -9896,7 +9954,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -9910,19 +9968,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10027,17 +10085,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10074,17 +10132,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10127,7 +10185,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10138,7 +10196,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10150,13 +10208,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10179,7 +10237,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10198,7 +10256,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10223,9 +10281,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10280,15 +10338,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10306,15 +10364,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10339,13 +10397,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10368,13 +10426,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10398,13 +10456,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10452,6 +10510,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -10460,9 +10520,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10480,6 +10540,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -10496,13 +10558,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10529,33 +10591,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10579,19 +10643,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10606,17 +10670,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10637,21 +10701,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10679,19 +10743,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10704,21 +10768,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10807,17 +10871,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10833,7 +10897,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -10867,6 +10933,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -10880,13 +10947,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10904,17 +10971,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10955,7 +11022,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10966,11 +11033,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10997,13 +11064,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11013,17 +11080,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11056,7 +11123,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -11071,23 +11138,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11181,19 +11248,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11213,17 +11280,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11241,23 +11308,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11354,23 +11421,23 @@ paths: `json-file` or `journald` logging drivers. operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11425,7 +11492,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11542,11 +11609,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11574,19 +11641,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11608,23 +11675,23 @@ paths: `json-file` or `journald` logging drivers. operationId: "TaskLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11679,7 +11746,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11709,11 +11776,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11741,19 +11808,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11782,7 +11849,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -11803,15 +11870,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11828,17 +11895,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11854,21 +11921,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11902,7 +11969,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11916,11 +11983,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11937,7 +12004,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -11948,19 +12014,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11984,7 +12050,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -11997,15 +12063,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12022,17 +12088,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12048,21 +12114,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12098,18 +12164,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12152,13 +12218,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.42.yaml b/_vendor/github.com/moby/moby/api/docs/v1.42.yaml index 23c5d120f5d8..44042b7a09ce 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.42.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.42.yaml @@ -1269,10 +1269,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1373,9 +1372,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1456,10 +1456,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1624,36 +1623,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1933,11 +1928,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } ImageInspect: description: | @@ -3947,7 +3941,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4318,6 +4312,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4381,6 +4398,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5935,7 +5959,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6456,7 +6479,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6589,11 +6612,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6777,26 +6800,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6809,7 +6832,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7044,14 +7067,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7075,7 +7098,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7126,14 +7149,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7162,7 +7185,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7171,14 +7194,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7239,7 +7262,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7268,14 +7291,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7294,16 +7317,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7348,7 +7371,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7444,14 +7467,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7484,18 +7507,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7521,18 +7544,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7549,24 +7576,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7585,22 +7614,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7619,6 +7650,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7628,23 +7661,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7660,6 +7693,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7671,7 +7706,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7682,14 +7717,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7730,20 +7765,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7758,6 +7793,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7771,16 +7808,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7790,6 +7827,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7797,16 +7836,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7816,6 +7855,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -7921,22 +7962,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7993,22 +8034,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8058,22 +8099,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8101,20 +8142,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8123,7 +8164,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8148,6 +8189,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8158,7 +8201,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8166,18 +8209,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8197,22 +8240,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8237,27 +8281,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8313,7 +8357,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8328,7 +8372,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8341,13 +8385,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8454,14 +8498,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8470,10 +8517,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8493,6 +8542,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8574,13 +8624,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8619,7 +8669,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8634,7 +8684,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8650,13 +8700,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8701,10 +8751,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8736,18 +8788,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8765,7 +8817,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8795,11 +8847,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8825,13 +8877,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8877,21 +8929,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8922,7 +8974,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -8933,15 +8985,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8970,7 +9022,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9005,7 +9057,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9048,7 +9100,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9063,7 +9115,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9078,7 +9130,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9097,13 +9149,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9121,11 +9173,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9137,11 +9189,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9151,9 +9203,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9191,7 +9244,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9209,7 +9262,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9237,7 +9290,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9251,18 +9304,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9334,15 +9387,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9381,7 +9434,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9488,7 +9541,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9534,12 +9587,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9568,20 +9621,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9598,9 +9652,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9627,22 +9681,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9738,13 +9792,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9788,17 +9842,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9827,7 +9881,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9876,11 +9930,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9898,11 +9952,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9932,11 +9986,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9955,15 +10009,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9982,21 +10036,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10038,17 +10092,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10063,6 +10117,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10082,7 +10138,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10097,7 +10153,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10116,7 +10172,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10173,7 +10229,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10206,15 +10262,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10239,17 +10295,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10259,6 +10315,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10270,7 +10328,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -10284,19 +10342,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10401,17 +10459,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10448,17 +10506,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10501,7 +10559,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10512,7 +10570,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10524,13 +10582,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10553,7 +10611,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10572,7 +10630,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10597,9 +10655,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10654,15 +10712,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10680,15 +10738,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10713,13 +10771,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10742,13 +10800,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10772,13 +10830,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10826,6 +10884,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -10834,9 +10894,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10854,6 +10914,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -10870,13 +10932,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10903,33 +10965,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10953,19 +11017,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10980,17 +11044,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11011,21 +11075,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11053,19 +11117,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11078,21 +11142,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11181,17 +11245,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11207,7 +11271,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11241,6 +11307,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11254,13 +11321,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11278,17 +11345,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11329,7 +11396,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11340,11 +11407,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11371,13 +11438,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11387,17 +11454,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11430,7 +11497,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -11445,23 +11512,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11555,19 +11622,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11587,17 +11654,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11615,23 +11682,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11731,23 +11798,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11802,7 +11869,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11919,11 +11986,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11951,19 +12018,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11988,23 +12055,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12059,7 +12126,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12089,11 +12156,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12121,19 +12188,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12162,7 +12229,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12183,15 +12250,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12208,17 +12275,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12234,21 +12301,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12282,7 +12349,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12296,11 +12363,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12317,7 +12384,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12328,19 +12394,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12364,7 +12430,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12377,15 +12443,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12402,17 +12468,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12428,21 +12494,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12478,18 +12544,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12532,13 +12598,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.43.yaml b/_vendor/github.com/moby/moby/api/docs/v1.43.yaml index 01a6e0780862..9dfea14dc0a0 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.43.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.43.yaml @@ -1276,10 +1276,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1380,9 +1379,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1463,10 +1463,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1631,36 +1630,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1940,11 +1935,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -3978,7 +3972,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4349,6 +4343,29 @@ definitions: - "remove" - "orphaned" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4412,6 +4429,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5968,7 +5992,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6489,7 +6512,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6622,11 +6645,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6810,26 +6833,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6842,7 +6865,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7077,14 +7100,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7108,7 +7131,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7159,14 +7182,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7195,7 +7218,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7204,14 +7227,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7272,7 +7295,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7286,14 +7309,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7312,16 +7335,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7366,7 +7389,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7462,14 +7485,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7502,18 +7525,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7539,18 +7562,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7567,24 +7594,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7603,22 +7632,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7637,6 +7668,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7646,23 +7679,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7678,6 +7711,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7689,7 +7724,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7700,14 +7735,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7748,20 +7783,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7776,6 +7811,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7789,16 +7826,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7808,6 +7845,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7815,16 +7854,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7834,6 +7873,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -7939,22 +7980,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8011,22 +8052,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8076,22 +8117,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8119,20 +8160,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8141,7 +8182,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8166,6 +8207,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8176,7 +8219,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8184,18 +8227,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8215,22 +8258,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8255,27 +8299,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8331,7 +8375,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8346,7 +8390,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8359,13 +8403,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8472,14 +8516,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8488,10 +8535,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8511,6 +8560,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8592,13 +8642,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8637,7 +8687,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8652,7 +8702,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8668,13 +8718,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8719,10 +8769,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8754,18 +8806,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8783,7 +8835,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8813,11 +8865,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8843,13 +8895,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8895,21 +8947,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8940,7 +8992,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -8951,15 +9003,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8988,7 +9040,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9023,7 +9075,7 @@ paths: is_automated: false name: "vgauthier/sshd" star_count: 0 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9066,7 +9118,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9081,7 +9133,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9096,7 +9148,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9115,13 +9167,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9139,11 +9191,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9155,11 +9207,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9169,9 +9221,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9209,7 +9262,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9227,7 +9280,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9255,7 +9308,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9269,18 +9322,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9352,15 +9405,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9399,7 +9452,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9506,7 +9559,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9552,12 +9605,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9586,20 +9639,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9616,9 +9670,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9645,22 +9699,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9756,13 +9810,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9806,17 +9860,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9845,7 +9899,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9894,11 +9948,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9916,11 +9970,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9950,11 +10004,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9973,15 +10027,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10000,21 +10054,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10056,17 +10110,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10081,6 +10135,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10100,7 +10156,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10115,7 +10171,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10134,7 +10190,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10191,7 +10247,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10224,15 +10280,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10257,17 +10313,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10277,6 +10333,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10288,7 +10346,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -10302,19 +10360,19 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10419,17 +10477,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10466,17 +10524,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10519,7 +10577,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10530,7 +10588,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10542,13 +10600,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10571,7 +10629,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10590,7 +10648,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10615,9 +10673,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10672,15 +10730,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10698,15 +10756,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10731,13 +10789,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10760,13 +10818,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10790,13 +10848,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10844,6 +10902,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -10852,9 +10912,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10872,6 +10932,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -10888,13 +10950,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10921,33 +10983,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10971,19 +11035,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10998,17 +11062,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11029,21 +11093,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11071,19 +11135,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11096,21 +11160,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11199,17 +11263,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11225,7 +11289,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11259,6 +11325,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11272,13 +11339,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11296,17 +11363,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11347,7 +11414,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11358,11 +11425,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11389,13 +11456,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11405,17 +11472,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11448,7 +11515,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: type: "object" @@ -11463,23 +11530,23 @@ paths: example: ID: "ak7w3gjqoa3kuz8xcpnyy0pvl" Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11573,19 +11640,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11605,17 +11672,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11633,23 +11700,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11749,23 +11816,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11820,7 +11887,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11937,11 +12004,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11969,19 +12036,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12006,23 +12073,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12077,7 +12144,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12107,11 +12174,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12139,19 +12206,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12180,7 +12247,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12201,15 +12268,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12226,17 +12293,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12252,21 +12319,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12300,7 +12367,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12314,11 +12381,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12335,7 +12402,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12346,19 +12412,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12382,7 +12448,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12395,15 +12461,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12420,17 +12486,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12446,21 +12512,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12496,18 +12562,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12550,13 +12616,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.44.yaml b/_vendor/github.com/moby/moby/api/docs/v1.44.yaml index e3505ca603e9..20f3d2830db3 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.44.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.44.yaml @@ -1292,10 +1292,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1399,9 +1398,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1482,10 +1482,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1650,36 +1649,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1968,11 +1963,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4030,7 +4024,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4439,6 +4433,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4483,6 +4500,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6107,7 +6131,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6628,7 +6651,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6761,11 +6784,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6950,26 +6973,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6982,7 +7005,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7217,14 +7240,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7248,7 +7271,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7299,14 +7322,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7335,7 +7358,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7344,14 +7367,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7412,7 +7435,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7426,14 +7449,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7452,16 +7475,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7506,7 +7529,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7602,14 +7625,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7642,18 +7665,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7679,18 +7702,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7707,24 +7734,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7743,22 +7772,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7777,6 +7808,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7786,23 +7819,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7818,6 +7851,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7829,7 +7864,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7840,14 +7875,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7888,20 +7923,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7916,6 +7951,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7929,16 +7966,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7948,6 +7985,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7955,16 +7994,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7974,6 +8013,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8079,22 +8120,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8151,22 +8192,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8216,22 +8257,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8259,20 +8300,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8281,7 +8322,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8306,6 +8347,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8316,7 +8359,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8324,18 +8367,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8355,22 +8398,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8395,27 +8439,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8471,7 +8515,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8486,7 +8530,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8499,13 +8543,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8613,14 +8657,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8629,10 +8676,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8652,6 +8701,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8733,13 +8783,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8778,7 +8828,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8793,7 +8843,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8809,13 +8859,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8860,10 +8910,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8895,18 +8947,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8924,7 +8976,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8954,11 +9006,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8984,13 +9036,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9036,21 +9088,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9081,7 +9133,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9092,15 +9144,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9129,7 +9181,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9172,7 +9224,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9219,7 +9271,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9234,7 +9286,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9249,7 +9301,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9268,13 +9320,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9292,11 +9344,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9308,11 +9360,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9322,9 +9374,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9362,7 +9415,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9380,7 +9433,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9408,7 +9461,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9422,18 +9475,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9505,15 +9558,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9552,7 +9605,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9658,7 +9711,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9700,12 +9753,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9734,20 +9787,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9764,9 +9818,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9793,22 +9847,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9904,13 +9958,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9954,17 +10008,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9993,7 +10047,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10042,11 +10096,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10064,11 +10118,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10098,11 +10152,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10121,15 +10175,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10148,21 +10202,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10204,17 +10258,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10229,6 +10283,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10248,7 +10304,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10263,7 +10319,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10282,7 +10338,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10339,7 +10395,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10372,15 +10428,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10405,17 +10461,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10425,6 +10481,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10436,7 +10494,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -10450,21 +10508,21 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10564,21 +10622,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10616,17 +10674,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10669,7 +10727,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10680,7 +10738,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10692,13 +10750,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10721,7 +10779,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10740,7 +10798,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10765,9 +10823,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10822,15 +10880,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10848,15 +10906,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10881,13 +10939,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10910,13 +10968,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10940,13 +10998,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10994,6 +11052,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11002,9 +11062,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11022,6 +11082,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11038,13 +11100,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11071,33 +11133,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11121,19 +11185,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11148,17 +11212,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11179,21 +11243,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11221,19 +11285,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11246,21 +11310,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11349,17 +11413,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11375,7 +11439,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11409,6 +11475,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11422,13 +11489,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11446,17 +11513,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11497,7 +11564,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11508,11 +11575,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11539,13 +11606,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11555,17 +11622,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11598,27 +11665,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11712,19 +11779,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11744,17 +11811,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11772,23 +11839,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11888,23 +11955,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11959,7 +12026,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12076,11 +12143,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12108,19 +12175,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12145,23 +12212,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12216,7 +12283,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12246,11 +12313,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12278,19 +12345,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12319,7 +12386,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12340,15 +12407,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12365,17 +12432,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12391,21 +12458,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12439,7 +12506,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12453,11 +12520,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12474,7 +12541,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12485,19 +12551,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12521,7 +12587,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12534,15 +12600,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12559,17 +12625,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12585,21 +12651,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12635,18 +12701,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12689,13 +12755,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.45.yaml b/_vendor/github.com/moby/moby/api/docs/v1.45.yaml index fea80197bc5f..d6315733b3fe 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.45.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.45.yaml @@ -1293,10 +1293,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1400,9 +1399,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1483,10 +1483,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1651,36 +1650,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1969,11 +1964,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4016,7 +4010,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4425,6 +4419,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4469,6 +4486,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6093,7 +6117,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6614,7 +6637,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6747,11 +6770,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6936,26 +6959,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -6968,7 +6991,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7203,14 +7226,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7234,7 +7257,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7285,14 +7308,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7321,7 +7344,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7330,14 +7353,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7398,7 +7421,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7412,14 +7435,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7438,16 +7461,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7492,7 +7515,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7588,14 +7611,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7628,18 +7651,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7665,18 +7688,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7693,24 +7720,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7729,22 +7758,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7763,6 +7794,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7772,23 +7805,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7804,6 +7837,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7815,7 +7850,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7826,14 +7861,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7874,20 +7909,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7902,6 +7937,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -7915,16 +7952,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7934,6 +7971,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -7941,16 +7980,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7960,6 +7999,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8065,22 +8106,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8137,22 +8178,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8202,22 +8243,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8245,20 +8286,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8267,7 +8308,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8292,6 +8333,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8302,7 +8345,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8310,18 +8353,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8341,22 +8384,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8381,27 +8425,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8457,7 +8501,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8472,7 +8516,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8485,13 +8529,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8599,14 +8643,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8615,10 +8662,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8638,6 +8687,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8719,13 +8769,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8764,7 +8814,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8779,7 +8829,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8795,13 +8845,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8846,10 +8896,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -8881,18 +8933,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8910,7 +8962,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -8940,11 +8992,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8970,13 +9022,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9022,21 +9074,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9067,7 +9119,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9078,15 +9130,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9115,7 +9167,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9157,7 +9209,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9199,7 +9251,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9214,7 +9266,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9229,7 +9281,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9248,13 +9300,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9272,11 +9324,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9288,11 +9340,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9302,9 +9354,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9342,7 +9395,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9360,7 +9413,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9388,7 +9441,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9402,18 +9455,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9485,15 +9538,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9532,7 +9585,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9638,7 +9691,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9680,12 +9733,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9714,20 +9767,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9744,9 +9798,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9773,22 +9827,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9884,13 +9938,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -9934,17 +9988,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9973,7 +10027,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10022,11 +10076,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10044,11 +10098,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10078,11 +10132,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10101,15 +10155,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10128,21 +10182,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10184,17 +10238,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10209,6 +10263,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10228,7 +10284,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10243,7 +10299,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10262,7 +10318,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10319,7 +10375,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10352,15 +10408,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10385,17 +10441,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10405,6 +10461,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10416,7 +10474,7 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "No error" schema: type: "object" @@ -10430,21 +10488,21 @@ paths: example: Id: "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30" Warning: "" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10544,21 +10602,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10596,17 +10654,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10649,7 +10707,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10660,7 +10718,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10672,13 +10730,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10701,7 +10759,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10720,7 +10778,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10745,9 +10803,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10802,15 +10860,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10828,15 +10886,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10861,13 +10919,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10890,13 +10948,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10920,13 +10978,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10974,6 +11032,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -10982,9 +11042,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11002,6 +11062,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11018,13 +11080,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11051,33 +11113,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11101,19 +11165,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11128,17 +11192,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11159,21 +11223,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11201,19 +11265,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11226,21 +11290,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11329,17 +11393,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11355,7 +11419,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11389,6 +11455,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11402,13 +11469,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11426,17 +11493,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11477,7 +11544,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11488,11 +11555,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11519,13 +11586,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11535,17 +11602,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11578,27 +11645,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11692,19 +11759,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11724,17 +11791,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11752,23 +11819,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11868,23 +11935,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11939,7 +12006,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12056,11 +12123,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12088,19 +12155,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12125,23 +12192,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12196,7 +12263,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12226,11 +12293,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12258,19 +12325,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12299,7 +12366,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12320,15 +12387,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12345,17 +12412,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12371,21 +12438,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12419,7 +12486,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12433,11 +12500,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12454,7 +12521,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12465,19 +12531,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12501,7 +12567,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12514,15 +12580,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12539,17 +12605,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12565,21 +12631,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12615,18 +12681,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12669,13 +12735,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.46.yaml b/_vendor/github.com/moby/moby/api/docs/v1.46.yaml index 2c865ada523e..8fc24acb4356 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.46.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.46.yaml @@ -1308,10 +1308,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1415,9 +1414,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1503,10 +1503,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1678,36 +1677,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1996,11 +1991,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4062,7 +4056,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4478,6 +4472,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4522,6 +4539,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6204,7 +6228,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6725,7 +6748,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -6868,11 +6891,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7057,26 +7080,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7089,7 +7112,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7324,14 +7347,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7355,7 +7378,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7406,14 +7429,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7442,7 +7465,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7451,14 +7474,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7519,7 +7542,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7533,14 +7556,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7559,16 +7582,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7613,7 +7636,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7709,14 +7732,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7749,18 +7772,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7786,18 +7809,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7814,24 +7841,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7850,22 +7879,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7884,6 +7915,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -7893,23 +7926,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7925,6 +7958,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -7936,7 +7971,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -7947,14 +7982,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7995,20 +8030,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8023,6 +8058,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8036,16 +8073,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8055,6 +8092,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8062,16 +8101,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8081,6 +8120,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8186,22 +8227,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8258,22 +8299,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8323,22 +8364,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8366,20 +8407,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8388,7 +8429,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8413,6 +8454,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8423,7 +8466,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8431,18 +8474,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8462,22 +8505,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8502,27 +8546,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8578,7 +8622,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8593,7 +8637,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8606,13 +8650,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8720,14 +8764,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8736,10 +8783,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8759,6 +8808,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8840,13 +8890,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8885,7 +8935,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8900,7 +8950,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8916,13 +8966,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8967,10 +9017,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9002,18 +9054,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9031,7 +9083,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9061,11 +9113,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9091,13 +9143,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9156,21 +9208,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9201,7 +9253,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9212,15 +9264,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9249,7 +9301,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9291,7 +9343,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9333,7 +9385,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9348,7 +9400,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9363,7 +9415,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9382,13 +9434,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9406,11 +9458,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9422,11 +9474,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9436,9 +9488,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9476,7 +9529,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9494,7 +9547,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9522,7 +9575,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9536,18 +9589,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9619,15 +9672,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9666,7 +9719,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9772,7 +9825,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9814,12 +9867,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9848,20 +9901,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -9878,9 +9932,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9907,22 +9961,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10018,13 +10072,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10068,17 +10122,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10107,7 +10161,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10156,11 +10210,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10178,11 +10232,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10212,11 +10266,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10235,15 +10289,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10262,21 +10316,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10318,17 +10372,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10343,6 +10397,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10362,7 +10418,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10377,7 +10433,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10396,7 +10452,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10453,7 +10509,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10486,15 +10542,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10519,17 +10575,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10539,6 +10595,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10550,25 +10608,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10663,21 +10721,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10715,17 +10773,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10768,7 +10826,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10779,7 +10837,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10791,13 +10849,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10820,7 +10878,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10839,7 +10897,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10864,9 +10922,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10921,15 +10979,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10947,15 +11005,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10980,13 +11038,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11009,13 +11067,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11039,13 +11097,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11093,6 +11151,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11101,9 +11161,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11121,6 +11181,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11137,13 +11199,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11170,33 +11232,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11220,19 +11284,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11247,17 +11311,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11278,21 +11342,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11320,19 +11384,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11345,21 +11409,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11448,17 +11512,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11474,7 +11538,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11508,6 +11574,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11521,13 +11588,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11545,17 +11612,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11596,7 +11663,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11607,11 +11674,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11638,13 +11705,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11654,17 +11721,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11697,27 +11764,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11812,19 +11879,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11844,17 +11911,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11872,23 +11939,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11989,23 +12056,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12060,7 +12127,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12177,11 +12244,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12209,19 +12276,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12246,23 +12313,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12317,7 +12384,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12347,11 +12414,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12379,19 +12446,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12420,7 +12487,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12441,15 +12508,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12466,17 +12533,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12492,21 +12559,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12540,7 +12607,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12554,11 +12621,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12575,7 +12642,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12586,19 +12652,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12622,7 +12688,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12635,15 +12701,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12660,17 +12726,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12686,21 +12752,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12736,18 +12802,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12790,13 +12856,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.47.yaml b/_vendor/github.com/moby/moby/api/docs/v1.47.yaml index 5a191881716c..4561a2d254f6 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.47.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.47.yaml @@ -1308,10 +1308,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1415,9 +1414,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1503,10 +1503,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1678,36 +1677,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -1996,11 +1991,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4080,7 +4074,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4496,6 +4490,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4540,6 +4557,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6226,7 +6250,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -6755,7 +6778,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -6861,7 +6884,7 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -7004,11 +7027,11 @@ paths: GlobalIPv6PrefixLen: 0 MacAddress: "02:42:ac:11:00:05" Mounts: [] - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7193,26 +7216,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7225,7 +7248,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7460,14 +7483,14 @@ paths: Mode: "ro,Z" RW: false Propagation: "" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7491,7 +7514,7 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7542,14 +7565,14 @@ paths: - "pts/0" - "00:00:00" - "sleep 10" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7578,7 +7601,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -7587,14 +7610,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7655,7 +7678,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -7669,14 +7692,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7695,16 +7718,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7749,7 +7772,7 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: type: "object" @@ -7845,14 +7868,14 @@ paths: periods: 0 throttled_periods: 0 throttled_time: 0 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7885,18 +7908,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -7922,18 +7945,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7950,24 +7977,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7986,22 +8015,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8020,6 +8051,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8029,23 +8062,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8061,6 +8094,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8072,7 +8107,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: type: "object" @@ -8083,14 +8118,14 @@ paths: type: "array" items: type: "string" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8131,20 +8166,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8159,6 +8194,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8172,16 +8209,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8191,6 +8228,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8198,16 +8237,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8217,6 +8256,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8322,22 +8363,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8394,22 +8435,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8459,22 +8500,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8502,20 +8543,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8524,7 +8565,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8549,6 +8590,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8559,7 +8602,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8567,18 +8610,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8598,22 +8641,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8638,27 +8682,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8714,7 +8758,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -8729,7 +8773,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8742,13 +8786,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8861,14 +8905,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -8877,10 +8924,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -8900,6 +8949,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -8981,13 +9031,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9026,7 +9076,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9041,7 +9091,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9057,13 +9107,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9108,10 +9158,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9143,18 +9195,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9172,7 +9224,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9202,11 +9254,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9232,13 +9284,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9297,21 +9349,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9342,7 +9394,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9353,15 +9405,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9390,7 +9442,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9432,7 +9484,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9474,7 +9526,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9489,7 +9541,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9504,7 +9556,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9523,13 +9575,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9547,11 +9599,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9563,11 +9615,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9577,9 +9629,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9617,7 +9670,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9635,7 +9688,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -9663,7 +9716,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9677,18 +9730,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9760,15 +9813,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9807,7 +9860,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -9913,7 +9966,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9955,12 +10008,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9989,20 +10042,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" tags: ["Image"] @@ -10019,9 +10073,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10048,22 +10102,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10159,13 +10213,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10209,17 +10263,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10248,7 +10302,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10297,11 +10351,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10319,11 +10373,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10353,11 +10407,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10376,15 +10430,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10403,21 +10457,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10459,17 +10513,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10484,6 +10538,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10503,7 +10559,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10518,7 +10574,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10537,7 +10593,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10597,7 +10653,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10630,15 +10686,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10663,17 +10719,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10683,6 +10739,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -10694,25 +10752,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10813,21 +10871,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10865,17 +10923,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10918,7 +10976,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10929,7 +10987,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10941,13 +10999,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10970,7 +11028,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -10989,7 +11047,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11014,9 +11072,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11071,15 +11129,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11097,15 +11155,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11130,13 +11188,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11159,13 +11217,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11189,13 +11247,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11243,6 +11301,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11251,9 +11311,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11271,6 +11331,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11287,13 +11349,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11320,33 +11382,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11370,19 +11434,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11397,17 +11461,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11428,21 +11492,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11470,19 +11534,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11495,21 +11559,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11598,17 +11662,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11624,7 +11688,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -11658,6 +11724,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -11671,13 +11738,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11695,17 +11762,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11746,7 +11813,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -11757,11 +11824,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11788,13 +11855,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11804,17 +11871,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11847,27 +11914,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11962,19 +12029,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11994,17 +12061,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12022,23 +12089,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12139,23 +12206,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12210,7 +12277,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12327,11 +12394,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12359,19 +12426,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12396,23 +12463,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12467,7 +12534,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12497,11 +12564,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12529,19 +12596,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12570,7 +12637,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -12591,15 +12658,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12616,17 +12683,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12642,21 +12709,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12690,7 +12757,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12704,11 +12771,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12725,7 +12792,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -12736,19 +12802,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IdResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12772,7 +12838,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -12785,15 +12851,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12810,17 +12876,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12836,21 +12902,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12886,18 +12952,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12940,13 +13006,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.48.yaml b/_vendor/github.com/moby/moby/api/docs/v1.48.yaml index 862481900a9d..21b8aee9077f 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.48.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.48.yaml @@ -1358,10 +1358,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1465,9 +1464,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1553,10 +1553,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1728,36 +1727,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -2046,11 +2041,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4219,7 +4213,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4635,6 +4629,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4679,6 +4696,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5889,10 +5913,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7264,7 +7287,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -7818,7 +7840,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -7924,17 +7946,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8119,26 +8141,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8151,18 +8173,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8186,18 +8208,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8226,7 +8248,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8235,14 +8257,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8303,7 +8325,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8317,14 +8339,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8343,16 +8365,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8397,18 +8419,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8441,18 +8463,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8478,18 +8500,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8506,24 +8532,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8542,22 +8570,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8576,6 +8606,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8585,23 +8617,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8617,6 +8649,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8628,18 +8662,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8680,20 +8714,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8708,6 +8742,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8721,16 +8757,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8740,6 +8776,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8747,16 +8785,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8766,6 +8804,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8871,22 +8911,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8943,22 +8983,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9008,22 +9048,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9051,20 +9091,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -9073,7 +9113,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9098,6 +9138,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -9108,7 +9150,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -9116,18 +9158,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9147,22 +9189,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9187,27 +9230,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9263,7 +9306,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9278,7 +9321,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9291,13 +9334,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9410,14 +9453,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9426,10 +9472,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9449,6 +9497,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9530,13 +9579,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9594,7 +9643,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9609,7 +9658,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9625,13 +9674,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9682,10 +9731,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9717,18 +9768,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9752,7 +9803,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9782,11 +9833,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9826,13 +9877,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9891,21 +9942,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9936,7 +9987,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9947,15 +9998,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9984,7 +10035,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10026,7 +10077,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10068,7 +10119,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10083,7 +10134,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10098,7 +10149,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -10117,13 +10168,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10141,11 +10192,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10157,11 +10208,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10171,9 +10222,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10211,7 +10263,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10229,7 +10281,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10257,7 +10309,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10271,18 +10323,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10354,15 +10406,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10401,7 +10453,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10507,7 +10559,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10549,12 +10601,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10593,20 +10645,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10633,9 +10686,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10672,22 +10725,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10784,13 +10837,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10833,17 +10886,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10872,7 +10925,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10921,11 +10974,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10943,11 +10996,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10977,11 +11030,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11000,15 +11053,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11027,21 +11080,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11083,17 +11136,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11108,6 +11161,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11127,7 +11182,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11142,7 +11197,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11161,7 +11216,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11221,7 +11276,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11254,15 +11309,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11287,17 +11342,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11307,6 +11362,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11318,25 +11375,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11435,21 +11492,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11488,17 +11545,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11541,7 +11598,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11552,7 +11609,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11564,13 +11621,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11593,7 +11650,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11612,7 +11669,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11637,9 +11694,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11694,15 +11751,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11720,15 +11777,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11753,13 +11810,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11782,13 +11839,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11812,13 +11869,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11866,6 +11923,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11874,9 +11933,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11894,6 +11953,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11910,13 +11971,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11943,33 +12004,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11993,19 +12056,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12020,17 +12083,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12051,21 +12114,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12093,19 +12156,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12118,21 +12181,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12221,17 +12284,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12247,7 +12310,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12281,6 +12346,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12294,13 +12360,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12318,17 +12384,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12369,7 +12435,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12380,11 +12446,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12411,13 +12477,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12427,17 +12493,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12470,27 +12536,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12585,19 +12651,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12617,17 +12683,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12645,23 +12711,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12762,23 +12828,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12833,7 +12899,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12950,11 +13016,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12982,19 +13048,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13019,23 +13085,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13090,7 +13156,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13120,11 +13186,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13152,19 +13218,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13193,7 +13259,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13214,15 +13280,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13239,17 +13305,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13265,21 +13331,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13313,7 +13379,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13327,11 +13393,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13348,7 +13414,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13359,19 +13424,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13395,7 +13460,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13408,15 +13473,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13433,17 +13498,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13459,21 +13524,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13509,18 +13574,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13563,13 +13628,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.49.yaml b/_vendor/github.com/moby/moby/api/docs/v1.49.yaml index 369784be2281..6428d9cc8fc0 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.49.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.49.yaml @@ -1358,10 +1358,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1465,9 +1464,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1553,10 +1553,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1728,36 +1727,32 @@ definitions: "AttachStdin": false "AttachStdout": false "AttachStderr": false - "ExposedPorts": { - "80/tcp": {}, + "ExposedPorts": + "80/tcp": {} "443/tcp": {} - } "Tty": false "OpenStdin": false "StdinOnce": false "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] "Cmd": ["/bin/sh"] - "Healthcheck": { - "Test": ["string"], - "Interval": 0, - "Timeout": 0, - "Retries": 0, - "StartPeriod": 0, + "Healthcheck": + "Test": ["string"] + "Interval": 0 + "Timeout": 0 + "Retries": 0 + "StartPeriod": 0 "StartInterval": 0 - } "ArgsEscaped": true "Image": "" - "Volumes": { - "/app/data": {}, + "Volumes": + "/app/data": {} "/app/config": {} - } "WorkingDir": "/public/" "Entrypoint": [] "OnBuild": [] - "Labels": { - "com.example.some-label": "some-value", + "Labels": + "com.example.some-label": "some-value" "com.example.some-other-label": "some-other-value" - } "StopSignal": "SIGTERM" "Shell": ["/bin/sh", "-c"] @@ -2046,11 +2041,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4219,7 +4213,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4635,6 +4629,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4679,6 +4696,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5889,10 +5913,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7264,7 +7287,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -7818,7 +7840,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -7924,17 +7946,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8119,26 +8141,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8151,18 +8173,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8186,18 +8208,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8226,7 +8248,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8235,14 +8257,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8303,7 +8325,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8317,14 +8339,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8343,16 +8365,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8397,18 +8419,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8441,18 +8463,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8478,18 +8500,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8506,24 +8532,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8542,22 +8570,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8576,6 +8606,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8585,23 +8617,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8617,6 +8649,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8628,18 +8662,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8680,20 +8714,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8708,6 +8742,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8721,16 +8757,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8740,6 +8776,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8747,16 +8785,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8766,6 +8804,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8871,22 +8911,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8943,22 +8983,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9008,22 +9048,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9051,20 +9091,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -9073,7 +9113,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9098,6 +9138,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -9108,7 +9150,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -9116,18 +9158,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9147,22 +9189,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9187,27 +9230,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9263,7 +9306,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9278,7 +9321,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9291,13 +9334,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9410,14 +9453,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9426,10 +9472,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9449,6 +9497,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9530,13 +9579,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9594,7 +9643,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9609,7 +9658,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9625,13 +9674,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9682,10 +9731,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9717,18 +9768,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9773,7 +9824,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9803,11 +9854,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9847,13 +9898,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9912,21 +9963,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9957,7 +10008,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9968,15 +10019,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10005,7 +10056,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10047,7 +10098,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10089,7 +10140,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10104,7 +10155,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10119,7 +10170,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -10138,13 +10189,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10162,11 +10213,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10178,11 +10229,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10192,9 +10243,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10232,7 +10284,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10250,7 +10302,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10278,7 +10330,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10292,18 +10344,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10375,15 +10427,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10422,7 +10474,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10528,7 +10580,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10570,12 +10622,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10614,20 +10666,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10654,9 +10707,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10693,22 +10746,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10805,13 +10858,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10854,17 +10907,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10893,7 +10946,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10942,11 +10995,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10964,11 +11017,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10998,11 +11051,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11021,15 +11074,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11048,21 +11101,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11104,17 +11157,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11129,6 +11182,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11148,7 +11203,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11163,7 +11218,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11182,7 +11237,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11242,7 +11297,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11275,15 +11330,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11308,17 +11363,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11328,6 +11383,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11339,25 +11396,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11456,21 +11513,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11509,17 +11566,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11562,7 +11619,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11573,7 +11630,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11585,13 +11642,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11614,7 +11671,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11633,7 +11690,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11658,9 +11715,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11715,15 +11772,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11741,15 +11798,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11774,13 +11831,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11803,13 +11860,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11833,13 +11890,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11887,6 +11944,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11895,9 +11954,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11915,6 +11974,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11931,13 +11992,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11964,33 +12025,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12014,19 +12077,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12041,17 +12104,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12072,21 +12135,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12114,19 +12177,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12139,21 +12202,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12242,17 +12305,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12268,7 +12331,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12302,6 +12367,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12315,13 +12381,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12339,17 +12405,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12390,7 +12456,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12401,11 +12467,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12432,13 +12498,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12448,17 +12514,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12491,27 +12557,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12606,19 +12672,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12638,17 +12704,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12666,23 +12732,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12783,23 +12849,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12854,7 +12920,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12971,11 +13037,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13003,19 +13069,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13040,23 +13106,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13111,7 +13177,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13141,11 +13207,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13173,19 +13239,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13214,7 +13280,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13235,15 +13301,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13260,17 +13326,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13286,21 +13352,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13334,7 +13400,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13348,11 +13414,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13369,7 +13435,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13380,19 +13445,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13416,7 +13481,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13429,15 +13494,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13454,17 +13519,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13480,21 +13545,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13530,18 +13595,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13584,13 +13649,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.50.yaml b/_vendor/github.com/moby/moby/api/docs/v1.50.yaml index 00bf9c931fe7..0375f825abf6 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.50.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.50.yaml @@ -1358,10 +1358,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1465,9 +1464,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1500,10 +1500,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Env: description: | A list of environment variables to set inside the container in the @@ -1873,11 +1872,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4063,7 +4061,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4479,6 +4477,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4523,6 +4544,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5733,10 +5761,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7094,7 +7121,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -7648,7 +7674,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -7754,17 +7780,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7949,26 +7975,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7981,18 +8007,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8016,18 +8042,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8056,7 +8082,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8065,14 +8091,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8133,7 +8159,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8147,14 +8173,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8173,16 +8199,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8227,18 +8253,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8271,18 +8297,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8308,18 +8334,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8336,24 +8366,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8372,22 +8404,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8406,6 +8440,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8415,23 +8451,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8447,6 +8483,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8458,18 +8496,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8510,20 +8548,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8538,6 +8576,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8551,16 +8591,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8570,6 +8610,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8577,16 +8619,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8596,6 +8638,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8701,22 +8745,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8773,22 +8817,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8838,22 +8882,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8881,20 +8925,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8903,7 +8947,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8928,6 +8972,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8938,7 +8984,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8946,18 +8992,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8977,22 +9023,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9017,27 +9064,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9093,7 +9140,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9108,7 +9155,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9121,13 +9168,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9240,14 +9287,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9256,10 +9306,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9279,6 +9331,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9360,13 +9413,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9424,7 +9477,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9439,7 +9492,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9455,13 +9508,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9512,10 +9565,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9547,18 +9602,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9603,7 +9658,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9633,11 +9688,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9677,13 +9732,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9742,21 +9797,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9787,7 +9842,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9798,15 +9853,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9830,9 +9885,10 @@ paths: in: "query" description: | Select platform-specific content to delete. - Multiple values are accepted. + Repeat the parameter to select multiple platforms. Each platform is a OCI platform encoded as a JSON string. type: "array" + collectionFormat: "multi" items: # This should be OCIPlatform # but $ref is not supported for array in query in Swagger 2.0 @@ -9847,7 +9903,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9889,7 +9945,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9931,7 +9987,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9946,7 +10002,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9961,7 +10017,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -9980,13 +10036,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10004,11 +10060,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10020,11 +10076,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10034,9 +10090,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10074,7 +10131,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10092,7 +10149,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10120,7 +10177,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10134,18 +10191,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10217,15 +10274,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10264,7 +10321,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10370,7 +10427,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10412,12 +10469,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10456,20 +10513,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10496,9 +10554,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10535,22 +10593,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10647,13 +10705,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10696,17 +10754,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10735,7 +10793,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10784,11 +10842,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10806,11 +10864,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10840,11 +10898,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10863,15 +10921,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10890,21 +10948,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10946,17 +11004,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10971,6 +11029,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -10990,7 +11050,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11005,7 +11065,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11024,7 +11084,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11084,7 +11144,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11117,15 +11177,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11150,17 +11210,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11170,6 +11230,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11181,25 +11243,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11298,21 +11360,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11351,17 +11413,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11404,7 +11466,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11415,7 +11477,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11427,13 +11489,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11456,7 +11518,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11475,7 +11537,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11500,9 +11562,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11557,15 +11619,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11583,15 +11645,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11616,13 +11678,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11645,13 +11707,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11675,13 +11737,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11729,6 +11791,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11737,9 +11801,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11757,6 +11821,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11773,13 +11839,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11806,33 +11872,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11856,19 +11924,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11883,17 +11951,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11914,21 +11982,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11956,19 +12024,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11981,21 +12049,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12084,17 +12152,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12110,7 +12178,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12144,6 +12214,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12157,13 +12228,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12181,17 +12252,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12232,7 +12303,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12243,11 +12314,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12274,13 +12345,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12290,17 +12361,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12333,27 +12404,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12448,19 +12519,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12480,17 +12551,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12508,23 +12579,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12625,23 +12696,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12696,7 +12767,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12813,11 +12884,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12845,19 +12916,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12882,23 +12953,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12953,7 +13024,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12983,11 +13054,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13015,19 +13086,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13056,7 +13127,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13077,15 +13148,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13102,17 +13173,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13128,21 +13199,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13176,7 +13247,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13190,11 +13261,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13211,7 +13282,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13222,19 +13292,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13258,7 +13328,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13271,15 +13341,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13296,17 +13366,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13322,21 +13392,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13372,18 +13442,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13426,13 +13496,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.51.yaml b/_vendor/github.com/moby/moby/api/docs/v1.51.yaml index bed52c65710a..aa1e1cdcfdd9 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.51.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.51.yaml @@ -1361,10 +1361,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1468,9 +1467,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1503,10 +1503,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Env: description: | A list of environment variables to set inside the container in the @@ -1878,11 +1877,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } FilesystemChange: description: | @@ -4082,7 +4080,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4498,6 +4496,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4542,6 +4563,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -5752,10 +5780,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7115,7 +7142,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -7669,7 +7695,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -7775,17 +7801,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -7970,26 +7996,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8002,18 +8028,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8037,18 +8063,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8077,7 +8103,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8086,14 +8112,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8154,7 +8180,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8168,14 +8194,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8194,16 +8220,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8248,18 +8274,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8292,18 +8318,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8329,18 +8355,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8357,24 +8387,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8393,22 +8425,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8427,6 +8461,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8436,23 +8472,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8468,6 +8504,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8479,18 +8517,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8531,20 +8569,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8559,6 +8597,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8572,16 +8612,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8591,6 +8631,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8598,16 +8640,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8617,6 +8659,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -8722,22 +8766,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8794,22 +8838,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8859,22 +8903,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8902,20 +8946,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -8924,7 +8968,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8949,6 +8993,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -8959,7 +9005,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -8967,18 +9013,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8998,22 +9044,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9038,27 +9085,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9114,7 +9161,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9129,7 +9176,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9142,13 +9189,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9261,14 +9308,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9277,10 +9327,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9300,6 +9352,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9381,13 +9434,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9445,7 +9498,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9460,7 +9513,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9476,13 +9529,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9533,10 +9586,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9568,18 +9623,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9624,7 +9679,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9654,11 +9709,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9698,13 +9753,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9763,21 +9818,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9808,7 +9863,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -9819,15 +9874,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9851,9 +9906,10 @@ paths: in: "query" description: | Select platform-specific content to delete. - Multiple values are accepted. + Repeat the parameter to select multiple platforms. Each platform is a OCI platform encoded as a JSON string. type: "array" + collectionFormat: "multi" items: # This should be OCIPlatform # but $ref is not supported for array in query in Swagger 2.0 @@ -9868,7 +9924,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -9910,7 +9966,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9952,7 +10008,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9967,7 +10023,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9982,7 +10038,7 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: type: "object" @@ -10001,13 +10057,13 @@ paths: application/json: Status: "Login Succeeded" IdentityToken: "9cbaf023786cd7..." - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10025,11 +10081,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10041,11 +10097,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10055,9 +10111,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10095,7 +10152,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10113,7 +10170,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10141,7 +10198,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10155,18 +10212,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10238,15 +10295,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10285,7 +10342,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10391,7 +10448,7 @@ paths: CreatedAt: "2021-06-28T13:31:03.002625487Z" LastUsedAt: "2021-07-07T22:02:32.773909517Z" UsageCount: 26 - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10433,12 +10490,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10477,20 +10534,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10517,9 +10575,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10556,22 +10614,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10668,13 +10726,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10717,17 +10775,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10756,7 +10814,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10805,11 +10863,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10827,11 +10885,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10861,11 +10919,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10884,15 +10942,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10911,21 +10969,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -10967,17 +11025,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10992,6 +11050,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11011,7 +11071,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11026,7 +11086,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11045,7 +11105,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11105,7 +11165,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11138,15 +11198,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Network" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11171,17 +11231,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11191,6 +11251,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11202,25 +11264,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11319,21 +11381,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11372,17 +11434,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11425,7 +11487,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11436,7 +11498,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11448,13 +11510,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11477,7 +11539,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11496,7 +11558,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11521,9 +11583,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11578,15 +11640,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11604,15 +11666,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11637,13 +11699,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11666,13 +11728,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11696,13 +11758,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11750,6 +11812,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11758,9 +11822,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11778,6 +11842,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11794,13 +11860,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11827,33 +11893,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11877,19 +11945,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11904,17 +11972,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11935,21 +12003,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11977,19 +12045,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12002,21 +12070,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12105,17 +12173,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12131,7 +12199,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12165,6 +12235,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12178,13 +12249,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12202,17 +12273,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12253,7 +12324,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12264,11 +12335,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12295,13 +12366,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12311,17 +12382,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12354,27 +12425,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12469,19 +12540,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12501,17 +12572,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12529,23 +12600,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12646,23 +12717,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12717,7 +12788,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12834,11 +12905,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12866,19 +12937,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12903,23 +12974,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12974,7 +13045,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13004,11 +13075,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13036,19 +13107,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13077,7 +13148,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13098,15 +13169,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13123,17 +13194,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13149,21 +13220,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13197,7 +13268,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13211,11 +13282,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13232,7 +13303,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13243,19 +13313,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13279,7 +13349,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13292,15 +13362,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13317,17 +13387,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13343,21 +13413,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13393,18 +13463,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13447,13 +13517,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.52.yaml b/_vendor/github.com/moby/moby/api/docs/v1.52.yaml index 8e2a794726ec..99413a54fcad 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.52.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.52.yaml @@ -1370,10 +1370,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1470,9 +1469,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1505,10 +1505,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Env: description: | A list of environment variables to set inside the container in the @@ -1735,11 +1734,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } Storage: description: | @@ -4284,7 +4282,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4723,6 +4721,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -4767,6 +4788,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6053,10 +6081,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7405,7 +7432,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -7959,7 +7985,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -8065,17 +8091,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8259,26 +8285,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8291,18 +8317,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8326,18 +8352,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8366,7 +8392,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8375,14 +8401,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8443,7 +8469,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8457,14 +8483,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8483,16 +8509,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8537,18 +8563,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8581,18 +8607,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8618,18 +8644,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8646,24 +8676,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8682,22 +8714,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8716,6 +8750,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8725,23 +8761,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8757,6 +8793,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -8768,18 +8806,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8820,20 +8858,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8848,6 +8886,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -8861,16 +8901,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8880,6 +8920,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -8887,16 +8929,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8906,6 +8948,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -9011,22 +9055,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9083,22 +9127,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9148,22 +9192,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9191,20 +9235,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -9213,7 +9257,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9238,6 +9282,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -9248,7 +9294,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -9256,18 +9302,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9287,22 +9333,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9327,27 +9374,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9403,7 +9450,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9418,7 +9465,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9431,13 +9478,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9550,14 +9597,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9566,10 +9616,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9589,6 +9641,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9670,13 +9723,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9725,7 +9778,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9740,7 +9793,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9756,13 +9809,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9813,10 +9866,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -9848,18 +9903,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9904,7 +9959,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -9934,11 +9989,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9978,13 +10033,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10043,21 +10098,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10088,7 +10143,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -10099,15 +10154,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10131,9 +10186,10 @@ paths: in: "query" description: | Select platform-specific content to delete. - Multiple values are accepted. + Repeat the parameter to select multiple platforms. Each platform is a OCI platform encoded as a JSON string. type: "array" + collectionFormat: "multi" items: # This should be OCIPlatform # but $ref is not supported for array in query in Swagger 2.0 @@ -10148,7 +10204,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10190,7 +10246,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10232,7 +10288,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10247,7 +10303,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10262,17 +10318,17 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: $ref: "#/definitions/AuthResponse" - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10290,11 +10346,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10306,11 +10362,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10320,9 +10376,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10360,7 +10417,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10378,7 +10435,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10406,7 +10463,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10420,18 +10477,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10504,15 +10561,15 @@ paths: - "application/x-ndjson" - "application/json-seq" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10551,7 +10608,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10565,7 +10622,7 @@ paths: $ref: "#/definitions/VolumesDiskUsage" BuildCacheUsage: $ref: "#/definitions/BuildCacheDiskUsage" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10613,12 +10670,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10660,20 +10717,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10703,9 +10761,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10745,22 +10803,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10857,13 +10915,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -10906,17 +10964,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10945,7 +11003,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10994,11 +11052,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11016,11 +11074,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11050,11 +11108,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11073,15 +11131,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11100,21 +11158,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11156,17 +11214,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11181,6 +11239,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11200,7 +11260,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11215,7 +11275,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11234,7 +11294,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11294,7 +11354,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11327,15 +11387,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/NetworkInspect" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11360,17 +11420,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11380,6 +11440,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11391,25 +11453,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11508,21 +11570,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11546,17 +11608,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11589,7 +11651,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11600,7 +11662,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11612,13 +11674,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11641,7 +11703,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11660,7 +11722,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11685,9 +11747,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11742,15 +11804,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11768,15 +11830,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11801,13 +11863,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11830,13 +11892,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11860,13 +11922,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11914,6 +11976,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -11922,9 +11986,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11942,6 +12006,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -11958,13 +12024,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11991,33 +12057,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12041,19 +12109,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12068,17 +12136,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12099,21 +12167,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12141,19 +12209,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12166,21 +12234,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12269,17 +12337,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12295,7 +12363,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12329,6 +12399,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12342,13 +12413,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12366,17 +12437,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12417,7 +12488,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12428,11 +12499,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12459,13 +12530,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12475,17 +12546,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12518,27 +12589,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12633,19 +12704,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12665,17 +12736,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12693,23 +12764,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12810,23 +12881,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12881,7 +12952,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -12998,11 +13069,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13030,19 +13101,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13067,23 +13138,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13138,7 +13209,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13168,11 +13239,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13200,19 +13271,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13241,7 +13312,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13262,15 +13333,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13287,17 +13358,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13313,21 +13384,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13361,7 +13432,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13375,11 +13446,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13396,7 +13467,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13407,19 +13477,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13443,7 +13513,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13456,15 +13526,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13481,17 +13551,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13507,21 +13577,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13557,18 +13627,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13611,13 +13681,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.53.yaml b/_vendor/github.com/moby/moby/api/docs/v1.53.yaml index 2a0cb0d7cd9c..15ad3ac182de 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.53.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.53.yaml @@ -1370,10 +1370,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1470,9 +1469,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1505,10 +1505,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Env: description: | A list of environment variables to set inside the container in the @@ -1735,11 +1734,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } Storage: description: | @@ -4530,7 +4528,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4969,6 +4967,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -5013,6 +5034,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6299,10 +6327,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7653,7 +7680,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -8207,7 +8233,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -8313,17 +8339,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8507,26 +8533,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8539,18 +8565,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8574,18 +8600,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8614,7 +8640,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8623,14 +8649,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8691,7 +8717,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8705,14 +8731,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8731,16 +8757,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8785,18 +8811,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8829,18 +8855,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8866,18 +8892,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8894,24 +8924,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8930,22 +8962,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8964,6 +8998,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8973,23 +9009,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9005,6 +9041,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -9016,18 +9054,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9068,20 +9106,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9096,6 +9134,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -9109,16 +9149,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9128,6 +9168,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -9135,16 +9177,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9154,6 +9196,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -9259,22 +9303,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9331,22 +9375,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9396,22 +9440,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9439,20 +9483,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -9461,7 +9505,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9486,6 +9530,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -9496,7 +9542,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -9504,18 +9550,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9535,22 +9581,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9575,27 +9622,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9651,7 +9698,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9666,7 +9713,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9679,13 +9726,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9798,14 +9845,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9814,10 +9864,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9837,6 +9889,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9918,13 +9971,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9973,7 +10026,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9988,7 +10041,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10004,13 +10057,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10061,10 +10114,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10096,18 +10151,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10152,7 +10207,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -10182,11 +10237,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10226,13 +10281,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10291,21 +10346,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10336,7 +10391,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -10347,15 +10402,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10379,9 +10434,10 @@ paths: in: "query" description: | Select platform-specific content to delete. - Multiple values are accepted. + Repeat the parameter to select multiple platforms. Each platform is a OCI platform encoded as a JSON string. type: "array" + collectionFormat: "multi" items: # This should be OCIPlatform # but $ref is not supported for array in query in Swagger 2.0 @@ -10396,7 +10452,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10438,7 +10494,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10480,7 +10536,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10495,7 +10551,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10510,17 +10566,17 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: $ref: "#/definitions/AuthResponse" - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10538,11 +10594,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10554,11 +10610,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10568,9 +10624,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10608,7 +10665,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10626,7 +10683,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10654,7 +10711,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10668,18 +10725,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10753,15 +10810,15 @@ paths: - "application/x-ndjson" - "application/json-seq" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10800,7 +10857,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10814,7 +10871,7 @@ paths: $ref: "#/definitions/VolumesDiskUsage" BuildCacheUsage: $ref: "#/definitions/BuildCacheDiskUsage" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10862,12 +10919,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10909,20 +10966,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10952,9 +11010,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10994,22 +11052,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11106,13 +11164,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -11155,17 +11213,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11194,7 +11252,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11243,11 +11301,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11265,11 +11323,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11299,11 +11357,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11322,15 +11380,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11349,21 +11407,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11405,17 +11463,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11430,6 +11488,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11449,7 +11509,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11464,7 +11524,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11483,7 +11543,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11543,7 +11603,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11576,15 +11636,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/NetworkInspect" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11609,17 +11669,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11629,6 +11689,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11640,25 +11702,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11757,21 +11819,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11795,17 +11857,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11838,7 +11900,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11849,7 +11911,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11861,13 +11923,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11890,7 +11952,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11909,7 +11971,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11934,9 +11996,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11991,15 +12053,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12017,15 +12079,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12050,13 +12112,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12079,13 +12141,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12109,13 +12171,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12163,6 +12225,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -12171,9 +12235,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12191,6 +12255,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -12207,13 +12273,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12240,33 +12306,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12290,19 +12358,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12317,17 +12385,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12348,21 +12416,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12390,19 +12458,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12415,21 +12483,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12518,17 +12586,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12544,7 +12612,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12578,6 +12648,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12591,13 +12662,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12615,17 +12686,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12666,7 +12737,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12677,11 +12748,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12708,13 +12779,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12724,17 +12795,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12767,27 +12838,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12882,19 +12953,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12914,17 +12985,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12942,23 +13013,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13059,23 +13130,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13130,7 +13201,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13247,11 +13318,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13279,19 +13350,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13316,23 +13387,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13387,7 +13458,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13417,11 +13488,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13449,19 +13520,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13490,7 +13561,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13511,15 +13582,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13536,17 +13607,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13562,21 +13633,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13610,7 +13681,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13624,11 +13695,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13645,7 +13716,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13656,19 +13726,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13692,7 +13762,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13705,15 +13775,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13730,17 +13800,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13756,21 +13826,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13806,18 +13876,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13863,13 +13933,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.54.yaml b/_vendor/github.com/moby/moby/api/docs/v1.54.yaml index bb2ad6dc60a5..b20d578f071b 100644 --- a/_vendor/github.com/moby/moby/api/docs/v1.54.yaml +++ b/_vendor/github.com/moby/moby/api/docs/v1.54.yaml @@ -1370,10 +1370,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Tty: description: | Attach standard streams to a TTY, including `stdin` if it is not closed. @@ -1470,9 +1469,10 @@ definitions: example: "SIGTERM" x-nullable: true StopTimeout: - description: "Timeout to stop a container in seconds." + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default is used. type: "integer" - default: 10 x-nullable: true Shell: description: | @@ -1505,10 +1505,9 @@ definitions: enum: - {} default: {} - example: { - "80/tcp": {}, + example: + "80/tcp": {} "443/tcp": {} - } Env: description: | A list of environment variables to set inside the container in the @@ -1735,11 +1734,10 @@ definitions: x-nullable: false additionalProperties: type: "string" - example: { - "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged", - "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff", + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" - } Storage: description: | @@ -1835,13 +1833,6 @@ definitions: compatibility. x-nullable: true $ref: "#/definitions/OCIDescriptor" - Identity: - description: |- - Identity holds information about the identity and origin of the image. - This is trusted information verified by the daemon and cannot be modified - by tagging an image to a different name. - x-nullable: true - $ref: "#/definitions/Identity" Manifests: description: | Manifests is a list of image manifests available in this image. It @@ -1857,6 +1848,13 @@ definitions: x-nullable: true items: $ref: "#/definitions/ImageManifestSummary" + Identity: + description: |- + Identity holds information about the identity and origin of the image. + This is trusted information verified by the daemon and cannot be modified + by tagging an image to a different name. + x-nullable: true + $ref: "#/definitions/Identity" RepoTags: description: | List of image names/tags in the local image cache that reference this @@ -4530,7 +4528,7 @@ definitions: forcefully killing it. type: "integer" format: "int64" - HealthCheck: + Healthcheck: $ref: "#/definitions/HealthConfig" Hosts: type: "array" @@ -4969,6 +4967,29 @@ definitions: PortStatus: $ref: "#/definitions/PortStatus" + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + Task: type: "object" properties: @@ -5013,6 +5034,13 @@ definitions: the JobIteration of the Service this Task was created for. Absent if the Task was created for a Replicated or Global Service. $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" example: ID: "0kzzo1i0y4jz6027t0k7aezc7" Version: @@ -6299,10 +6327,9 @@ definitions: items: $ref: "#/definitions/ContainerBlkioStatEntry" example: - io_service_bytes_recursive: [ - {"major": 254, "minor": 0, "op": "read", "value": 7593984}, - {"major": 254, "minor": 0, "op": "write", "value": 100} - ] + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} io_serviced_recursive: null io_queue_recursive: null io_service_time_recursive: null @@ -7653,7 +7680,6 @@ definitions: description: | List of ID's and addresses of other managers in the swarm. type: "array" - default: null x-nullable: true items: $ref: "#/definitions/PeerNode" @@ -8207,7 +8233,7 @@ definitions: type: "object" x-nullable: true x-omitempty: true - required: ["Platform", "Containers", "Size", "UnpackedSize"] + required: ["Platform", "Containers", "Size"] properties: Platform: $ref: "#/definitions/OCIPlatform" @@ -8320,17 +8346,17 @@ paths: - `volume`=(`<volume name>` or `<mount point destination>`) type: "string" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/ContainerSummary" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8514,26 +8540,26 @@ paths: required: true responses: - 201: + "201": description: "Container created successfully" schema: $ref: "#/definitions/ContainerCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8546,18 +8572,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerInspectResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8581,18 +8607,18 @@ paths: is not supported on Windows. operationId: "ContainerTop" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerTopResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8621,7 +8647,7 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ContainerLogs" responses: - 200: + "200": description: | logs returned as a stream in response body. For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). @@ -8630,14 +8656,14 @@ paths: schema: type: "string" format: "binary" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8698,7 +8724,7 @@ paths: operationId: "ContainerChanges" produces: ["application/json"] responses: - 200: + "200": description: "The list of changes" schema: type: "array" @@ -8712,14 +8738,14 @@ paths: Kind: 1 - Path: "/test" Kind: 1 - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8738,16 +8764,16 @@ paths: produces: - "application/octet-stream" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8792,18 +8818,18 @@ paths: operationId: "ContainerStats" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ContainerStatsResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8836,18 +8862,18 @@ paths: consumes: - "application/octet-stream" produces: - - "text/plain" + - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "cannot resize container" schema: $ref: "#/definitions/ErrorResponse" @@ -8873,18 +8899,22 @@ paths: summary: "Start a container" operationId: "ContainerStart" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already started" - 404: + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8901,24 +8931,26 @@ paths: single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/stop: post: summary: "Stop a container" operationId: "ContainerStop" responses: - 204: + "204": description: "no error" - 304: + "304": description: "container already stopped" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8937,22 +8969,24 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/restart: post: summary: "Restart a container" operationId: "ContainerRestart" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -8971,6 +9005,8 @@ paths: in: "query" description: "Number of seconds to wait before killing the container" type: "integer" + produces: + - "application/json" tags: ["Container"] /containers/{id}/kill: post: @@ -8980,23 +9016,23 @@ paths: container. operationId: "ContainerKill" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is not running" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9012,6 +9048,8 @@ paths: Signal to send to the container as an integer or string (e.g. `SIGINT`). type: "string" default: "SIGKILL" + produces: + - "application/json" tags: ["Container"] /containers/{id}/update: post: @@ -9023,18 +9061,18 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "The container has been updated." schema: $ref: "#/definitions/ContainerUpdateResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9075,20 +9113,20 @@ paths: summary: "Rename a container" operationId: "ContainerRename" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "name already in use" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9103,6 +9141,8 @@ paths: required: true description: "New name for the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/pause: post: @@ -9116,16 +9156,16 @@ paths: suspended, and subsequently resumed. operationId: "ContainerPause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9135,6 +9175,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/unpause: post: @@ -9142,16 +9184,16 @@ paths: description: "Resume a container which has been paused." operationId: "ContainerUnpause" responses: - 204: + "204": description: "no error" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9161,6 +9203,8 @@ paths: required: true description: "ID or name of the container" type: "string" + produces: + - "application/json" tags: ["Container"] /containers/{id}/attach: post: @@ -9266,22 +9310,22 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9338,22 +9382,22 @@ paths: summary: "Attach to a container via a websocket" operationId: "ContainerAttachWebsocket" responses: - 101: + "101": description: "no error, hints proxy about hijacking" - 200: + "200": description: "no error, no upgrade header found" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9403,22 +9447,22 @@ paths: operationId: "ContainerWait" produces: ["application/json"] responses: - 200: + "200": description: "The container has exit." schema: $ref: "#/definitions/ContainerWaitResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9446,20 +9490,20 @@ paths: summary: "Remove a container" operationId: "ContainerDelete" responses: - 204: + "204": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "conflict" schema: $ref: "#/definitions/ErrorResponse" @@ -9468,7 +9512,7 @@ paths: message: | You cannot remove a running container: c2ada9df5af8. Stop the container before attempting removal or force remove - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9493,6 +9537,8 @@ paths: description: "Remove the specified link associated with the container." type: "boolean" default: false + produces: + - "application/json" tags: ["Container"] /containers/{id}/archive: head: @@ -9503,7 +9549,7 @@ paths: about the path. operationId: "ContainerArchiveInfo" responses: - 200: + "200": description: "no error" headers: X-Docker-Container-Path-Stat: @@ -9511,18 +9557,18 @@ paths: description: | A base64 - encoded JSON object with some filesystem header information about the path - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9542,22 +9588,23 @@ paths: summary: "Get an archive of a filesystem resource in a container" description: "Get a tar archive of a resource in the filesystem of container id." operationId: "ContainerArchive" - produces: ["application/x-tar"] + produces: + - "application/x-tar" responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Container or path does not exist" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9582,27 +9629,27 @@ paths: operationId: "PutContainerArchive" consumes: ["application/x-tar", "application/octet-stream"] responses: - 200: + "200": description: "The content was extracted successfully" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "not a directory" - 403: + "403": description: "Permission denied, the volume or container rootfs is marked as read-only." schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such container or path does not exist inside the container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9658,7 +9705,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -9673,7 +9720,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9686,13 +9733,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "Summary image data for the images matching the query" schema: type: "array" items: $ref: "#/definitions/ImageSummary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9810,14 +9857,17 @@ paths: in: "query" description: "Set memory limit for build." type: "integer" + format: "int64" - name: "memswap" in: "query" description: "Total memory (memory + swap). Set as `-1` to disable swap." type: "integer" + format: "int64" - name: "cpushares" in: "query" description: "CPU shares (relative weight)." type: "integer" + format: "int64" - name: "cpusetcpus" in: "query" description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." @@ -9826,10 +9876,12 @@ paths: in: "query" description: "The length of a CPU period in microseconds." type: "integer" + format: "int64" - name: "cpuquota" in: "query" description: "Microseconds of CPU time that the container can get in a CPU period." type: "integer" + format: "int64" - name: "buildargs" in: "query" description: > @@ -9849,6 +9901,7 @@ paths: in: "query" description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." type: "integer" + format: "int64" - name: "squash" in: "query" description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" @@ -9930,13 +9983,13 @@ paths: - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) - `2` is [BuildKit](https://github.com/moby/buildkit) responses: - 200: + "200": description: "no error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -9985,7 +10038,7 @@ paths: - `shared` - `private` responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10000,7 +10053,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10016,13 +10069,13 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 404: + "404": description: "repository does not exist or no read access" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10073,10 +10126,12 @@ paths: Apply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10108,18 +10163,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/ImageInspect" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10164,7 +10219,7 @@ paths: operationId: "ImageHistory" produces: ["application/json"] responses: - 200: + "200": description: "List of image layers" schema: type: "array" @@ -10194,11 +10249,11 @@ paths: - "scratch:latest" Size: 0 Comment: "Imported from -" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10238,13 +10293,13 @@ paths: consumes: - "application/octet-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10303,21 +10358,21 @@ paths: or tag already exists, it will be overwritten. operationId: "ImageTag" responses: - 201: + "201": description: "No error" - 400: + "400": description: "Bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10348,7 +10403,7 @@ paths: operationId: "ImageDelete" produces: ["application/json"] responses: - 200: + "200": description: "The image was deleted successfully" schema: type: "array" @@ -10359,15 +10414,15 @@ paths: - Untagged: "3e2f21a89f" - Deleted: "3e2f21a89f" - Deleted: "53b4f83ac9" - 404: + "404": description: "No such image" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Conflict" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10391,9 +10446,10 @@ paths: in: "query" description: | Select platform-specific content to delete. - Multiple values are accepted. + Repeat the parameter to select multiple platforms. Each platform is a OCI platform encoded as a JSON string. type: "array" + collectionFormat: "multi" items: # This should be OCIPlatform # but $ref is not supported for array in query in Swagger 2.0 @@ -10408,7 +10464,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -10450,7 +10506,7 @@ paths: is_automated: false name: "postgres" star_count: 12408 - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10492,7 +10548,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -10507,7 +10563,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10522,17 +10578,17 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "An identity token was generated successfully." schema: $ref: "#/definitions/AuthResponse" - 204: + "204": description: "No error" - 401: + "401": description: "Auth error" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10550,11 +10606,11 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/SystemInfo" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10566,11 +10622,11 @@ paths: operationId: "SystemVersion" produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/SystemVersion" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10580,9 +10636,10 @@ paths: summary: "Ping" description: "This is a dummy endpoint you can use to test if the server is accessible." operationId: "SystemPing" - produces: ["text/plain"] + produces: + - "text/plain" responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10620,7 +10677,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10638,7 +10695,7 @@ paths: operationId: "SystemPingHead" produces: ["text/plain"] responses: - 200: + "200": description: "no error" schema: type: "string" @@ -10666,7 +10723,7 @@ paths: Pragma: type: "string" default: "no-cache" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10680,18 +10737,18 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10765,15 +10822,15 @@ paths: - "application/x-ndjson" - "application/json-seq" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/EventMessage" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10812,7 +10869,7 @@ paths: summary: "Get data usage information" operationId: "SystemDataUsage" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -10826,7 +10883,7 @@ paths: $ref: "#/definitions/VolumesDiskUsage" BuildCacheUsage: $ref: "#/definitions/BuildCacheDiskUsage" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10874,12 +10931,12 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -10921,20 +10978,21 @@ paths: produces: - "application/x-tar" responses: - 200: + "200": description: "no error" schema: type: "string" format: "binary" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" parameters: - name: "names" in: "query" - description: "Image names to filter by" + description: "Image names to filter by. Repeat the parameter for multiple images." type: "array" + collectionFormat: "multi" items: type: "string" - name: "platform" @@ -10964,9 +11022,9 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11006,22 +11064,22 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 404: + "404": description: "no such container" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such container: c2ada9df5af8" - 409: + "409": description: "container is paused" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11118,13 +11176,13 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "No error" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Container is stopped or paused" schema: $ref: "#/definitions/ErrorResponse" @@ -11167,17 +11225,17 @@ paths: if `tty` was specified as part of creating and starting the exec instance. operationId: "ExecResize" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11206,7 +11264,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11255,11 +11313,11 @@ paths: user: "1000" Running: false Pid: 42000 - 404: + "404": description: "No such exec instance" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11277,11 +11335,11 @@ paths: operationId: "VolumeList" produces: ["application/json"] responses: - 200: + "200": description: "Summary volume data that matches the query" schema: $ref: "#/definitions/VolumeListResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11311,11 +11369,11 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 201: + "201": description: "The volume was created successfully" schema: $ref: "#/definitions/Volume" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11334,15 +11392,15 @@ paths: operationId: "VolumeInspect" produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/Volume" - 404: + "404": description: "No such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11361,21 +11419,21 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such volume" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -11417,17 +11475,17 @@ paths: description: "Instruct the driver to remove the volume." operationId: "VolumeDelete" responses: - 204: + "204": description: "The volume was removed" - 404: + "404": description: "No such volume or volume driver" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "Volume is in use and cannot be removed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11442,6 +11500,8 @@ paths: description: "Force the removal of the volume" type: "boolean" default: false + produces: + - "application/json" tags: ["Volume"] /volumes/prune: @@ -11461,7 +11521,7 @@ paths: - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11476,7 +11536,7 @@ paths: description: "Disk space reclaimed in bytes" type: "integer" format: "int64" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11495,7 +11555,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: type: "array" @@ -11555,7 +11615,7 @@ paths: Config: [] Containers: {} Options: {} - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11588,15 +11648,15 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "No error" schema: $ref: "#/definitions/NetworkInspect" - 404: + "404": description: "Network not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11621,17 +11681,17 @@ paths: summary: "Remove a network" operationId: "NetworkDelete" responses: - 204: + "204": description: "No error" - 403: + "403": description: "operation not supported for pre-defined networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such network" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11641,6 +11701,8 @@ paths: description: "Network ID or name" required: true type: "string" + produces: + - "application/json" tags: ["Network"] /networks/create: @@ -11652,25 +11714,25 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "Network created successfully" schema: $ref: "#/definitions/NetworkCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: | Forbidden operation. This happens when trying to create a network named after a pre-defined network, or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "plugin not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11769,21 +11831,21 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "Operation forbidden" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11807,17 +11869,17 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "No error" - 403: + "403": description: "Operation not supported for swarm scoped networks" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "Network or container not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11850,7 +11912,7 @@ paths: - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. type: "string" responses: - 200: + "200": description: "No error" schema: type: "object" @@ -11861,7 +11923,7 @@ paths: type: "array" items: type: "string" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11873,13 +11935,13 @@ paths: description: "Returns information about installed plugins." produces: ["application/json"] responses: - 200: + "200": description: "No error" schema: type: "array" items: $ref: "#/definitions/Plugin" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11902,7 +11964,7 @@ paths: summary: "Get plugin privileges" operationId: "GetPluginPrivileges" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -11921,7 +11983,7 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -11946,9 +12008,9 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12003,15 +12065,15 @@ paths: summary: "Inspect a plugin" operationId: "PluginInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12029,15 +12091,15 @@ paths: summary: "Remove a plugin" operationId: "PluginDelete" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Plugin" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12062,13 +12124,13 @@ paths: summary: "Enable a plugin" operationId: "PluginEnable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12091,13 +12153,13 @@ paths: summary: "Disable a plugin" operationId: "PluginDisable" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin is not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12121,13 +12183,13 @@ paths: summary: "Upgrade a plugin" operationId: "PluginUpgrade" responses: - 204: + "204": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12175,6 +12237,8 @@ paths: Description: "" Value: - "/dev/cpu_dma_latency" + produces: + - "application/json" tags: ["Plugin"] /plugins/create: post: @@ -12183,9 +12247,9 @@ paths: consumes: - "application/x-tar" responses: - 204: + "204": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12203,6 +12267,8 @@ paths: schema: type: "string" format: "binary" + produces: + - "application/json" tags: ["Plugin"] /plugins/{name}/push: post: @@ -12219,13 +12285,13 @@ paths: required: true type: "string" responses: - 200: + "200": description: "no error" - 404: + "404": description: "plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" @@ -12252,33 +12318,35 @@ paths: type: "string" example: ["DEBUG=1"] responses: - 204: + "204": description: "No error" - 404: + "404": description: "Plugin not installed" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" tags: ["Plugin"] /nodes: get: summary: "List nodes" operationId: "NodeList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Node" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12302,19 +12370,19 @@ paths: summary: "Inspect a node" operationId: "NodeInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Node" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12329,17 +12397,17 @@ paths: summary: "Delete a node" operationId: "NodeDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12360,21 +12428,21 @@ paths: summary: "Update a node" operationId: "NodeUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such node" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12402,19 +12470,19 @@ paths: summary: "Inspect swarm" operationId: "SwarmInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Swarm" - 404: + "404": description: "no such swarm" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12427,21 +12495,21 @@ paths: - "application/json" - "text/plain" responses: - 200: + "200": description: "no error" schema: description: "The node ID" type: "string" example: "7v2t30z9blmxuhnyo6s4cpenp" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12530,17 +12598,17 @@ paths: summary: "Join an existing swarm" operationId: "SwarmJoin" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is already part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12556,7 +12624,9 @@ paths: description: | Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking - interface used for the VXLAN Tunnel Endpoint (VTEP). + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. type: "string" AdvertiseAddr: description: | @@ -12590,6 +12660,7 @@ paths: JoinToken: description: "Secret token for joining this swarm." type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] example: ListenAddr: "0.0.0.0:2377" AdvertiseAddr: "192.168.1.1:2377" @@ -12603,13 +12674,13 @@ paths: summary: "Leave a swarm" operationId: "SwarmLeave" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12627,17 +12698,17 @@ paths: summary: "Update a swarm" operationId: "SwarmUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12678,7 +12749,7 @@ paths: consumes: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "object" @@ -12689,11 +12760,11 @@ paths: type: "string" example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12720,13 +12791,13 @@ paths: example: UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" responses: - 200: + "200": description: "no error" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12736,17 +12807,17 @@ paths: summary: "List services" operationId: "ServiceList" responses: - 200: + "200": description: "no error" schema: type: "array" items: $ref: "#/definitions/Service" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12779,27 +12850,27 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/ServiceCreateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 403: + "403": description: "network is not eligible for services" schema: $ref: "#/definitions/ErrorResponse" - 409: + "409": description: "name conflicts with an existing service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12894,19 +12965,19 @@ paths: summary: "Inspect a service" operationId: "ServiceInspect" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Service" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12926,17 +12997,17 @@ paths: summary: "Delete a service" operationId: "ServiceDelete" responses: - 200: + "200": description: "no error" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -12954,23 +13025,23 @@ paths: consumes: ["application/json"] produces: ["application/json"] responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/ServiceUpdateResponse" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13071,23 +13142,23 @@ paths: - "application/vnd.docker.multiplexed-stream" operationId: "ServiceLogs" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such service" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such service: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13142,7 +13213,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13259,11 +13330,11 @@ paths: Gateway: "10.255.0.1" Addresses: - "10.255.0.5/16" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13291,19 +13362,19 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Task" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13328,23 +13399,23 @@ paths: - "application/vnd.docker.raw-stream" - "application/vnd.docker.multiplexed-stream" responses: - 200: + "200": description: "logs returned as a stream in response body" schema: type: "string" format: "binary" - 404: + "404": description: "no such task" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such task: c2ada9df5af8" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13399,7 +13470,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13429,11 +13500,11 @@ paths: Name: "app-dev.crt" Labels: foo: "bar" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13461,19 +13532,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13502,7 +13573,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Secret" @@ -13523,15 +13594,15 @@ paths: OptionA: "value for driver option A" OptionB: "value for driver option B" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13548,17 +13619,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "secret not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13574,21 +13645,21 @@ paths: summary: "Update a Secret" operationId: "SecretUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such secret" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13622,7 +13693,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: type: "array" @@ -13636,11 +13707,11 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "server.conf" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13657,7 +13728,6 @@ paths: - `id=<config id>` - `label=<key> or label=<key>=value` - `name=<config name>` - - `names=<config name>` tags: ["Config"] /configs/create: post: @@ -13668,19 +13738,19 @@ paths: produces: - "application/json" responses: - 201: + "201": description: "no error" schema: $ref: "#/definitions/IDResponse" - 409: + "409": description: "name conflicts with an existing object" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13704,7 +13774,7 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "no error" schema: $ref: "#/definitions/Config" @@ -13717,15 +13787,15 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13742,17 +13812,17 @@ paths: produces: - "application/json" responses: - 204: + "204": description: "no error" - 404: + "404": description: "config not found" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13768,21 +13838,21 @@ paths: summary: "Update a Config" operationId: "ConfigUpdate" responses: - 200: + "200": description: "no error" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 404: + "404": description: "no such config" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" - 503: + "503": description: "node is not part of a swarm" schema: $ref: "#/definitions/ErrorResponse" @@ -13818,18 +13888,18 @@ paths: produces: - "application/json" responses: - 200: + "200": description: "descriptor and platform information" schema: $ref: "#/definitions/DistributionInspect" - 401: + "401": description: "Failed authentication or no image found" schema: $ref: "#/definitions/ErrorResponse" examples: application/json: message: "No such image: someimage (tag: latest)" - 500: + "500": description: "Server error" schema: $ref: "#/definitions/ErrorResponse" @@ -13875,13 +13945,13 @@ paths: produces: - "application/vnd.docker.raw-stream" responses: - 101: + "101": description: "no error, hijacking successful" - 400: + "400": description: "bad parameter" schema: $ref: "#/definitions/ErrorResponse" - 500: + "500": description: "server error" schema: $ref: "#/definitions/ErrorResponse" diff --git a/_vendor/github.com/moby/moby/api/docs/v1.55.yaml b/_vendor/github.com/moby/moby/api/docs/v1.55.yaml new file mode 100644 index 000000000000..fcfd3c627ac5 --- /dev/null +++ b/_vendor/github.com/moby/moby/api/docs/v1.55.yaml @@ -0,0 +1,14065 @@ +# A Swagger 2.0 (a.k.a. OpenAPI) definition of the Engine API. +# +# This is used for generating API documentation and the types used by the +# client/server. See api/README.md for more information. +# +# Some style notes: +# - This file is used by ReDoc, which allows GitHub Flavored Markdown in +# descriptions. +# - There is no maximum line length, for ease of editing and pretty diffs. +# - operationIds are in the format "NounVerb", with a singular noun. + +swagger: "2.0" +schemes: + - "http" + - "https" +produces: + - "application/json" + - "text/plain" +consumes: + - "application/json" + - "text/plain" +basePath: "/v1.55" +info: + title: "Docker Engine API" + version: "1.55" + x-logo: + url: "https://docs.docker.com/assets/images/logo-docker-main.png" + description: | + The Engine API is an HTTP API served by Docker Engine. It is the API the + Docker client uses to communicate with the Engine, so everything the Docker + client can do can be done with the API. + + Most of the client's commands map directly to API endpoints (e.g. `docker ps` + is `GET /containers/json`). The notable exception is running containers, + which consists of several API calls. + + # Errors + + The API uses standard HTTP status codes to indicate the success or failure + of the API call. The body of the response will be JSON in the following + format: + + ``` + { + "message": "page not found" + } + ``` + + # Versioning + + The API is usually changed in each release, so API calls are versioned to + ensure that clients don't break. To lock to a specific version of the API, + you prefix the URL with its version, for example, call `/v1.30/info` to use + the v1.30 version of the `/info` endpoint. If the API version specified in + the URL is not supported by the daemon, a HTTP `400 Bad Request` error message + is returned. + + If you omit the version-prefix, the current version of the API is used. + For example, calling `/info` is the same as calling `/v1.55/info`. Using the + API without a version-prefix is deprecated and will be removed in a future release. + + Engine releases in the near future should support this version of the API, + so your client will continue to work even if it is talking to a newer Engine. + + The API uses an open schema model, which means the server may add extra properties + to responses. Likewise, the server will ignore any extra query parameters and + request body properties. When you write clients, you need to ignore additional + properties in responses to ensure they do not break when talking to newer + daemons. + + + # Authentication + + Authentication for registries is handled client side. The client has to send + authentication details to various endpoints that need to communicate with + registries, such as `POST /images/(name)/push`. These are sent as + `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) + (JSON) string with the following structure: + + ``` + { + "username": "string", + "password": "string", + "serveraddress": "string" + } + ``` + + The `serveraddress` is a domain/IP without a protocol. Throughout this + structure, double quotes are required. + + If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), + you can just pass this instead of credentials: + + ``` + { + "identitytoken": "9cbaf023786cd7..." + } + ``` + +# The tags on paths define the menu sections in the ReDoc documentation, so +# the usage of tags must make sense for that: +# - They should be singular, not plural. +# - There should not be too many tags, or the menu becomes unwieldy. For +# example, it is preferable to add a path to the "System" tag instead of +# creating a tag with a single path in it. +# - The order of tags in this list defines the order in the menu. +tags: + # Primary objects + - name: "Container" + x-displayName: "Containers" + description: | + Create and manage containers. + - name: "Image" + x-displayName: "Images" + - name: "Network" + x-displayName: "Networks" + description: | + Networks are user-defined networks that containers can be attached to. + See the [networking documentation](https://docs.docker.com/network/) + for more information. + - name: "Volume" + x-displayName: "Volumes" + description: | + Create and manage persistent storage that can be attached to containers. + - name: "Exec" + x-displayName: "Exec" + description: | + Run new commands inside running containers. Refer to the + [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) + for more information. + + To exec a command in a container, you first need to create an exec instance, + then start it. These two API endpoints are wrapped up in a single command-line + command, `docker exec`. + + # Swarm things + - name: "Swarm" + x-displayName: "Swarm" + description: | + Engines can be clustered together in a swarm. Refer to the + [swarm mode documentation](https://docs.docker.com/engine/swarm/) + for more information. + - name: "Node" + x-displayName: "Nodes" + description: | + Nodes are instances of the Engine participating in a swarm. Swarm mode + must be enabled for these endpoints to work. + - name: "Service" + x-displayName: "Services" + description: | + Services are the definitions of tasks to run on a swarm. Swarm mode must + be enabled for these endpoints to work. + - name: "Task" + x-displayName: "Tasks" + description: | + A task is a container running on a swarm. It is the atomic scheduling unit + of swarm. Swarm mode must be enabled for these endpoints to work. + - name: "Secret" + x-displayName: "Secrets" + description: | + Secrets are sensitive data that can be used by services. Swarm mode must + be enabled for these endpoints to work. + - name: "Config" + x-displayName: "Configs" + description: | + Configs are application configurations that can be used by services. Swarm + mode must be enabled for these endpoints to work. + # System things + - name: "Plugin" + x-displayName: "Plugins" + - name: "System" + x-displayName: "System" + +definitions: + ImageHistoryResponseItem: + type: "object" + x-go-name: HistoryResponseItem + title: "HistoryResponseItem" + description: "individual image layer information in response to ImageHistory operation" + required: [Id, Created, CreatedBy, Tags, Size, Comment] + properties: + Id: + type: "string" + x-nullable: false + Created: + type: "integer" + format: "int64" + x-nullable: false + CreatedBy: + type: "string" + x-nullable: false + Tags: + type: "array" + items: + type: "string" + Size: + type: "integer" + format: "int64" + x-nullable: false + Comment: + type: "string" + x-nullable: false + PortSummary: + type: "object" + description: | + Describes a port-mapping between the container and the host. + required: [PrivatePort, Type] + properties: + IP: + type: "string" + format: "ip-address" + description: "Host IP address that the container's port is mapped to" + x-go-type: + type: Addr + import: + package: net/netip + PrivatePort: + type: "integer" + format: "uint16" + x-nullable: false + description: "Port on the container" + PublicPort: + type: "integer" + format: "uint16" + description: "Port exposed on the host" + Type: + type: "string" + x-nullable: false + enum: ["tcp", "udp", "sctp"] + example: + PrivatePort: 8080 + PublicPort: 80 + Type: "tcp" + + MountType: + description: |- + The mount type. Available types: + + - `bind` a mount of a file or directory from the host into the container. + - `cluster` a Swarm cluster volume. + - `image` an OCI image. + - `npipe` a named pipe from the host into the container. + - `tmpfs` a `tmpfs`. + - `volume` a docker volume with the given `Name`. + type: "string" + enum: + - "bind" + - "cluster" + - "image" + - "npipe" + - "tmpfs" + - "volume" + example: "volume" + + MountPoint: + type: "object" + description: | + MountPoint represents a mount point configuration inside the container. + This is used for reporting the mountpoints in use by a container. + properties: + Type: + description: | + The mount type: + + - `bind` a mount of a file or directory from the host into the container. + - `cluster` a Swarm cluster volume. + - `image` an OCI image. + - `npipe` a named pipe from the host into the container. + - `tmpfs` a `tmpfs`. + - `volume` a docker volume with the given `Name`. + allOf: + - $ref: "#/definitions/MountType" + example: "volume" + Name: + description: | + Name is the name reference to the underlying data defined by `Source` + e.g., the volume name. + type: "string" + example: "myvolume" + Source: + description: | + Source location of the mount. + + For volumes, this contains the storage location of the volume (within + `/var/lib/docker/volumes/`). For bind-mounts, and `npipe`, this contains + the source (host) part of the bind-mount. For `tmpfs` mount points, this + field is empty. + type: "string" + example: "/var/lib/docker/volumes/myvolume/_data" + Destination: + description: | + Destination is the path relative to the container root (`/`) where + the `Source` is mounted inside the container. + type: "string" + example: "/usr/share/nginx/html/" + Driver: + description: | + Driver is the volume driver used to create the volume (if it is a volume). + type: "string" + example: "local" + Mode: + description: | + Mode is a comma separated list of options supplied by the user when + creating the bind/volume mount. + + The default is platform-specific (`"z"` on Linux, empty on Windows). + type: "string" + example: "z" + RW: + description: | + Whether the mount is mounted writable (read-write). + type: "boolean" + example: true + Propagation: + description: | + Propagation describes how mounts are propagated from the host into the + mount point, and vice-versa. Refer to the [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) + for details. This field is not used on Windows. + type: "string" + example: "" + + DeviceMapping: + type: "object" + description: "A device mapping between the host and container" + properties: + PathOnHost: + type: "string" + PathInContainer: + type: "string" + CgroupPermissions: + type: "string" + example: + PathOnHost: "/dev/deviceName" + PathInContainer: "/dev/deviceName" + CgroupPermissions: "mrw" + + DeviceRequest: + type: "object" + description: "A request for devices to be sent to device drivers" + properties: + Driver: + description: | + The name of the device driver to use for this request. + + Note that if this is specified the capabilities are ignored when + selecting a device driver. + type: "string" + example: "nvidia" + Count: + type: "integer" + example: -1 + DeviceIDs: + type: "array" + items: + type: "string" + example: + - "0" + - "1" + - "GPU-fef8089b-4820-abfc-e83e-94318197576e" + Capabilities: + description: | + A list of capabilities; an OR list of AND lists of capabilities. + + Note that if a driver is specified the capabilities have no effect on + selecting a driver as the driver name is used directly. + + Note that if no driver is specified the capabilities are used to + select a driver with the required capabilities. + type: "array" + items: + type: "array" + items: + type: "string" + example: + # gpu AND nvidia AND compute + - ["gpu", "nvidia", "compute"] + Options: + description: | + Driver-specific options, specified as a key/value pairs. These options + are passed directly to the driver. + type: "object" + additionalProperties: + type: "string" + + ThrottleDevice: + type: "object" + properties: + Path: + description: "Device path" + type: "string" + Rate: + description: "Rate" + type: "integer" + format: "int64" + minimum: 0 + + Mount: + type: "object" + properties: + Target: + description: "Container path." + type: "string" + Source: + description: |- + Mount source (e.g. a volume name, a host path). The source cannot be + specified when using `Type=tmpfs`. For `Type=bind`, the source path + must either exist, or the `CreateMountpoint` must be set to `true` to + create the source path on the host if missing. + + For `Type=npipe`, the pipe must exist prior to creating the container. + type: "string" + Type: + description: | + The mount type. Available types: + + - `bind` Mounts a file or directory from the host into the container. The `Source` must exist prior to creating the container. + - `cluster` a Swarm cluster volume + - `image` Mounts an image. + - `npipe` Mounts a named pipe from the host into the container. The `Source` must exist prior to creating the container. + - `tmpfs` Create a tmpfs with the given options. The mount `Source` cannot be specified for tmpfs. + - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed. + allOf: + - $ref: "#/definitions/MountType" + ReadOnly: + description: "Whether the mount should be read-only." + type: "boolean" + Consistency: + description: "The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`." + type: "string" + BindOptions: + description: "Optional configuration for the `bind` type." + type: "object" + properties: + Propagation: + description: "A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`." + type: "string" + enum: + - "private" + - "rprivate" + - "shared" + - "rshared" + - "slave" + - "rslave" + NonRecursive: + description: "Disable recursive bind mount." + type: "boolean" + default: false + CreateMountpoint: + description: "Create mount point on host if missing" + type: "boolean" + default: false + ReadOnlyNonRecursive: + description: | + Make the mount non-recursively read-only, but still leave the mount recursive + (unless NonRecursive is set to `true` in conjunction). + + Added in v1.44, before that version all read-only mounts were + non-recursive by default. To match the previous behaviour this + will default to `true` for clients on versions prior to v1.44. + type: "boolean" + default: false + ReadOnlyForceRecursive: + description: "Raise an error if the mount cannot be made recursively read-only." + type: "boolean" + default: false + VolumeOptions: + description: "Optional configuration for the `volume` type." + type: "object" + properties: + NoCopy: + description: "Populate volume with data from the target." + type: "boolean" + default: false + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + DriverConfig: + description: "Map of driver specific options" + type: "object" + properties: + Name: + description: "Name of the driver to use to create the volume." + type: "string" + Options: + description: "key/value map of driver specific options." + type: "object" + additionalProperties: + type: "string" + Subpath: + description: "Source path inside the volume. Must be relative without any back traversals." + type: "string" + example: "dir-inside-volume/subdirectory" + ImageOptions: + description: "Optional configuration for the `image` type." + type: "object" + properties: + Subpath: + description: "Source path inside the image. Must be relative without any back traversals." + type: "string" + example: "dir-inside-image/subdirectory" + TmpfsOptions: + description: "Optional configuration for the `tmpfs` type." + type: "object" + properties: + SizeBytes: + description: "The size for the tmpfs mount in bytes." + type: "integer" + format: "int64" + Mode: + description: | + The permission mode for the tmpfs mount in an integer. + The value must not be in octal format (e.g. 755) but rather + the decimal representation of the octal value (e.g. 493). + type: "integer" + Options: + description: | + The options to be passed to the tmpfs mount. An array of arrays. + Flag options should be provided as 1-length arrays. Other types + should be provided as as 2-length arrays, where the first item is + the key and the second the value. + type: "array" + items: + type: "array" + minItems: 1 + maxItems: 2 + items: + type: "string" + example: + [["noexec"]] + + RestartPolicy: + description: | + The behavior to apply when the container exits. The default is not to + restart. + + An ever increasing delay (double the previous delay, starting at 100ms) is + added before each restart to prevent flooding the server. + type: "object" + properties: + Name: + type: "string" + description: | + - Empty string means not to restart + - `no` Do not automatically restart + - `always` Always restart + - `unless-stopped` Restart always except when the user has manually stopped the container + - `on-failure` Restart only when the container exit code is non-zero + enum: + - "" + - "no" + - "always" + - "unless-stopped" + - "on-failure" + MaximumRetryCount: + type: "integer" + description: | + If `on-failure` is used, the number of times to retry before giving up. + + Resources: + description: "A container's resources (cgroups config, ulimits, etc)" + type: "object" + properties: + # Applicable to all platforms + CpuShares: + description: | + An integer value representing this container's relative CPU weight + versus other containers. + type: "integer" + Memory: + description: "Memory limit in bytes." + type: "integer" + format: "int64" + default: 0 + # Applicable to UNIX platforms + CgroupParent: + description: | + Path to `cgroups` under which the container's `cgroup` is created. If + the path is not absolute, the path is considered to be relative to the + `cgroups` path of the init process. Cgroups are created if they do not + already exist. + type: "string" + BlkioWeight: + description: "Block IO weight (relative weight)." + type: "integer" + minimum: 0 + maximum: 1000 + BlkioWeightDevice: + description: | + Block IO weight (relative device weight) in the form: + + ``` + [{"Path": "device_path", "Weight": weight}] + ``` + type: "array" + items: + type: "object" + properties: + Path: + type: "string" + Weight: + type: "integer" + minimum: 0 + BlkioDeviceReadBps: + description: | + Limit read rate (bytes per second) from a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceWriteBps: + description: | + Limit write rate (bytes per second) to a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceReadIOps: + description: | + Limit read rate (IO per second) from a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceWriteIOps: + description: | + Limit write rate (IO per second) to a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + CpuPeriod: + description: "The length of a CPU period in microseconds." + type: "integer" + format: "int64" + CpuQuota: + description: | + Microseconds of CPU time that the container can get in a CPU period. + type: "integer" + format: "int64" + CpuRealtimePeriod: + description: | + The length of a CPU real-time period in microseconds. Set to 0 to + allocate no time allocated to real-time tasks. + type: "integer" + format: "int64" + CpuRealtimeRuntime: + description: | + The length of a CPU real-time runtime in microseconds. Set to 0 to + allocate no time allocated to real-time tasks. + type: "integer" + format: "int64" + CpusetCpus: + description: | + CPUs in which to allow execution (e.g., `0-3`, `0,1`). + type: "string" + example: "0-3" + CpusetMems: + description: | + Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only + effective on NUMA systems. + type: "string" + Devices: + description: "A list of devices to add to the container." + type: "array" + items: + $ref: "#/definitions/DeviceMapping" + DeviceCgroupRules: + description: "a list of cgroup rules to apply to the container" + type: "array" + items: + type: "string" + example: "c 13:* rwm" + DeviceRequests: + description: | + A list of requests for devices to be sent to device drivers. + type: "array" + items: + $ref: "#/definitions/DeviceRequest" + MemoryReservation: + description: "Memory soft limit in bytes." + type: "integer" + format: "int64" + MemorySwap: + description: | + Total memory limit (memory + swap). Set as `-1` to enable unlimited + swap. + type: "integer" + format: "int64" + MemorySwappiness: + description: | + Tune a container's memory swappiness behavior. Accepts an integer + between 0 and 100. + type: "integer" + format: "int64" + minimum: 0 + maximum: 100 + NanoCpus: + description: "CPU quota in units of 10<sup>-9</sup> CPUs." + type: "integer" + format: "int64" + OomKillDisable: + description: "Disable OOM Killer for the container." + type: "boolean" + Init: + description: | + Run an init inside the container that forwards signals and reaps + processes. This field is omitted if empty, and the default (as + configured on the daemon) is used. + type: "boolean" + x-nullable: true + PidsLimit: + description: | + Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` + to not change. + type: "integer" + format: "int64" + x-nullable: true + Ulimits: + description: | + A list of resource limits to set in the container. For example: + + ``` + {"Name": "nofile", "Soft": 1024, "Hard": 2048} + ``` + type: "array" + items: + type: "object" + properties: + Name: + description: "Name of ulimit" + type: "string" + Soft: + description: "Soft limit" + type: "integer" + Hard: + description: "Hard limit" + type: "integer" + # Applicable to Windows + CpuCount: + description: | + The number of usable CPUs (Windows only). + + On Windows Server containers, the processor resource controls are + mutually exclusive. The order of precedence is `CPUCount` first, then + `CPUShares`, and `CPUPercent` last. + type: "integer" + format: "int64" + CpuPercent: + description: | + The usable percentage of the available CPUs (Windows only). + + On Windows Server containers, the processor resource controls are + mutually exclusive. The order of precedence is `CPUCount` first, then + `CPUShares`, and `CPUPercent` last. + type: "integer" + format: "int64" + IOMaximumIOps: + description: "Maximum IOps for the container system drive (Windows only)" + type: "integer" + format: "int64" + IOMaximumBandwidth: + description: | + Maximum IO in bytes per second for the container system drive + (Windows only). + type: "integer" + format: "int64" + + Limit: + description: | + An object describing a limit on resources which can be requested by a task. + type: "object" + properties: + NanoCPUs: + type: "integer" + format: "int64" + example: 4000000000 + MemoryBytes: + type: "integer" + format: "int64" + example: 8272408576 + Pids: + description: | + Limits the maximum number of PIDs in the container. Set `0` for unlimited. + type: "integer" + format: "int64" + default: 0 + example: 100 + + ResourceObject: + description: | + An object describing the resources which can be advertised by a node and + requested by a task. + type: "object" + properties: + NanoCPUs: + type: "integer" + format: "int64" + example: 4000000000 + MemoryBytes: + type: "integer" + format: "int64" + example: 8272408576 + GenericResources: + $ref: "#/definitions/GenericResources" + + GenericResources: + description: | + User-defined resources can be either Integer resources (e.g, `SSD=3`) or + String resources (e.g, `GPU=UUID1`). + type: "array" + items: + type: "object" + properties: + NamedResourceSpec: + type: "object" + properties: + Kind: + type: "string" + Value: + type: "string" + DiscreteResourceSpec: + type: "object" + properties: + Kind: + type: "string" + Value: + type: "integer" + format: "int64" + example: + - DiscreteResourceSpec: + Kind: "SSD" + Value: 3 + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID1" + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID2" + + HealthConfig: + description: | + A test to perform to check that the container is healthy. + Healthcheck commands should be side-effect free. + type: "object" + properties: + Test: + description: | + The test to perform. Possible values are: + + - `[]` inherit healthcheck from image or parent image + - `["NONE"]` disable healthcheck + - `["CMD", args...]` exec arguments directly + - `["CMD-SHELL", command]` run command with system's default shell + + A non-zero exit code indicates a failed healthcheck: + - `0` healthy + - `1` unhealthy + - `2` reserved (treated as unhealthy) + - other values: error running probe + type: "array" + items: + type: "string" + Interval: + description: | + The time to wait between checks in nanoseconds. It should be 0 or at + least 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + Timeout: + description: | + The time to wait before considering the check to have hung. It should + be 0 or at least 1000000 (1 ms). 0 means inherit. + + If the health check command does not complete within this timeout, + the check is considered failed and the health check process is + forcibly terminated without a graceful shutdown. + type: "integer" + format: "int64" + Retries: + description: | + The number of consecutive failures needed to consider a container as + unhealthy. 0 means inherit. + type: "integer" + StartPeriod: + description: | + Start period for the container to initialize before starting + health-retries countdown in nanoseconds. It should be 0 or at least + 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + StartInterval: + description: | + The time to wait between checks in nanoseconds during the start period. + It should be 0 or at least 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + + Health: + description: | + Health stores information about the container's healthcheck results. + type: "object" + x-nullable: true + properties: + Status: + description: | + Status is one of `none`, `starting`, `healthy` or `unhealthy` + + - "none" Indicates there is no healthcheck + - "starting" Starting indicates that the container is not yet ready + - "healthy" Healthy indicates that the container is running correctly + - "unhealthy" Unhealthy indicates that the container has a problem + type: "string" + enum: + - "none" + - "starting" + - "healthy" + - "unhealthy" + example: "healthy" + FailingStreak: + description: "FailingStreak is the number of consecutive failures" + type: "integer" + example: 0 + Log: + type: "array" + description: | + Log contains the last few results (oldest first) + items: + $ref: "#/definitions/HealthcheckResult" + + HealthcheckResult: + description: | + HealthcheckResult stores information about a single run of a healthcheck probe + type: "object" + x-nullable: true + properties: + Start: + description: | + Date and time at which this check started in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "date-time" + example: "2020-01-04T10:44:24.496525531Z" + End: + description: | + Date and time at which this check ended in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2020-01-04T10:45:21.364524523Z" + ExitCode: + description: | + ExitCode meanings: + + - `0` healthy + - `1` unhealthy + - `2` reserved (considered unhealthy) + - other values: error running probe + type: "integer" + example: 0 + Output: + description: "Output from last check" + type: "string" + + HostConfig: + description: "Container configuration that depends on the host we are running on" + allOf: + - $ref: "#/definitions/Resources" + - type: "object" + properties: + # Applicable to all platforms + Binds: + type: "array" + description: | + A list of volume bindings for this container. Each volume binding + is a string in one of these forms: + + - `host-src:container-dest[:options]` to bind-mount a host path + into the container. Both `host-src`, and `container-dest` must + be an _absolute_ path. + - `volume-name:container-dest[:options]` to bind-mount a volume + managed by a volume driver into the container. `container-dest` + must be an _absolute_ path. + + `options` is an optional, comma-delimited list of: + + - `nocopy` disables automatic copying of data from the container + path to the volume. The `nocopy` flag only applies to named volumes. + - `[ro|rw]` mounts a volume read-only or read-write, respectively. + If omitted or set to `rw`, volumes are mounted read-write. + - `[z|Z]` applies SELinux labels to allow or deny multiple containers + to read and write to the same volume. + - `z`: a _shared_ content label is applied to the content. This + label indicates that multiple containers can share the volume + content, for both reading and writing. + - `Z`: a _private unshared_ label is applied to the content. + This label indicates that only the current container can use + a private volume. Labeling systems such as SELinux require + proper labels to be placed on volume content that is mounted + into a container. Without a label, the security system can + prevent a container's processes from using the content. By + default, the labels set by the host operating system are not + modified. + - `[[r]shared|[r]slave|[r]private]` specifies mount + [propagation behavior](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). + This only applies to bind-mounted volumes, not internal volumes + or named volumes. Mount propagation requires the source mount + point (the location where the source directory is mounted in the + host operating system) to have the correct propagation properties. + For shared volumes, the source mount point must be set to `shared`. + For slave volumes, the mount must be set to either `shared` or + `slave`. + items: + type: "string" + ContainerIDFile: + type: "string" + description: "Path to a file where the container ID is written" + example: "" + LogConfig: + type: "object" + description: "The logging configuration for this container" + properties: + Type: + description: |- + Name of the logging driver used for the container or "none" + if logging is disabled. + type: "string" + enum: + - "local" + - "json-file" + - "syslog" + - "journald" + - "gelf" + - "fluentd" + - "awslogs" + - "splunk" + - "etwlogs" + - "none" + Config: + description: |- + Driver-specific configuration options for the logging driver. + type: "object" + additionalProperties: + type: "string" + example: + "max-file": "5" + "max-size": "10m" + NetworkMode: + type: "string" + description: | + Network mode to use for this container. Supported standard values + are: `bridge`, `host`, `none`, and `container:<name|id>`. Any + other value is taken as a custom network's name to which this + container should connect to. + PortBindings: + $ref: "#/definitions/PortMap" + RestartPolicy: + $ref: "#/definitions/RestartPolicy" + AutoRemove: + type: "boolean" + description: | + Automatically remove the container when the container's process + exits. This has no effect if `RestartPolicy` is set. + VolumeDriver: + type: "string" + description: "Driver that this container uses to mount volumes." + VolumesFrom: + type: "array" + description: | + A list of volumes to inherit from another container, specified in + the form `<container name>[:<ro|rw>]`. + items: + type: "string" + Mounts: + description: | + Specification for mounts to be added to the container. + type: "array" + items: + $ref: "#/definitions/Mount" + ConsoleSize: + type: "array" + description: | + Initial console size, as an `[height, width]` array. + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + Annotations: + type: "object" + description: | + Arbitrary non-identifying metadata attached to container and + provided to the runtime when the container is started. + additionalProperties: + type: "string" + + # Applicable to UNIX platforms + CapAdd: + type: "array" + description: | + A list of kernel capabilities to add to the container. Conflicts + with option 'Capabilities'. + items: + type: "string" + CapDrop: + type: "array" + description: | + A list of kernel capabilities to drop from the container. Conflicts + with option 'Capabilities'. + items: + type: "string" + CgroupnsMode: + type: "string" + enum: + - "private" + - "host" + description: | + cgroup namespace mode for the container. Possible values are: + + - `"private"`: the container runs in its own private cgroup namespace + - `"host"`: use the host system's cgroup namespace + + If not specified, the daemon default is used, which can either be `"private"` + or `"host"`, depending on daemon version, kernel support and configuration. + Dns: + type: "array" + description: "A list of DNS servers for the container to use." + items: + type: "string" + format: "ip-address" + x-go-type: + type: Addr + import: + package: net/netip + DnsOptions: + type: "array" + description: "A list of DNS options." + items: + type: "string" + DnsSearch: + type: "array" + description: "A list of DNS search domains." + items: + type: "string" + ExtraHosts: + type: "array" + description: | + A list of hostnames/IP mappings to add to the container's `/etc/hosts` + file. Specified in the form `["hostname:IP"]`. + items: + type: "string" + GroupAdd: + type: "array" + description: | + A list of additional groups that the container process will run as. + items: + type: "string" + IpcMode: + type: "string" + description: | + IPC sharing mode for the container. Possible values are: + + - `"none"`: own private IPC namespace, with /dev/shm not mounted + - `"private"`: own private IPC namespace + - `"shareable"`: own private IPC namespace, with a possibility to share it with other containers + - `"container:<name|id>"`: join another (shareable) container's IPC namespace + - `"host"`: use the host system's IPC namespace + + If not specified, daemon default is used, which can either be `"private"` + or `"shareable"`, depending on daemon version and configuration. + Cgroup: + type: "string" + description: "Cgroup to use for the container." + Links: + type: "array" + description: | + A list of links for the container in the form `container_name:alias`. + items: + type: "string" + OomScoreAdj: + type: "integer" + description: | + An integer value containing the score given to the container in + order to tune OOM killer preferences. + example: 500 + PidMode: + type: "string" + description: | + Set the PID (Process) Namespace mode for the container. It can be + either: + + - `"container:<name|id>"`: joins another container's PID namespace + - `"host"`: use the host's PID namespace inside the container + Privileged: + type: "boolean" + description: |- + Gives the container full access to the host. + PublishAllPorts: + type: "boolean" + description: | + Allocates an ephemeral host port for all of a container's + exposed ports. + + Ports are de-allocated when the container stops and allocated when + the container starts. The allocated port might be changed when + restarting the container. + + The port is selected from the ephemeral port range that depends on + the kernel. For example, on Linux the range is defined by + `/proc/sys/net/ipv4/ip_local_port_range`. + ReadonlyRootfs: + type: "boolean" + description: "Mount the container's root filesystem as read only." + SecurityOpt: + type: "array" + description: | + A list of string values to customize labels for MLS systems, such + as SELinux. + items: + type: "string" + StorageOpt: + type: "object" + description: | + Storage driver options for this container, in the form `{"size": "120G"}`. + additionalProperties: + type: "string" + Tmpfs: + type: "object" + description: | + A map of container directories which should be replaced by tmpfs + mounts, and their corresponding mount options. For example: + + ``` + { "/run": "rw,noexec,nosuid,size=65536k" } + ``` + additionalProperties: + type: "string" + UTSMode: + type: "string" + description: "UTS namespace to use for the container." + UsernsMode: + type: "string" + description: | + Sets the usernamespace mode for the container when usernamespace + remapping option is enabled. + ShmSize: + type: "integer" + format: "int64" + description: | + Size of `/dev/shm` in bytes. If omitted, the system uses 64MB. + minimum: 0 + Sysctls: + type: "object" + x-nullable: true + description: |- + A list of kernel parameters (sysctls) to set in the container. + + This field is omitted if not set. + additionalProperties: + type: "string" + example: + "net.ipv4.ip_forward": "1" + Runtime: + type: "string" + x-nullable: true + description: |- + Runtime to use with this container. + # Applicable to Windows + Isolation: + type: "string" + description: | + Isolation technology of the container. (Windows only) + enum: + - "default" + - "process" + - "hyperv" + - "" + MaskedPaths: + type: "array" + description: | + The list of paths to be masked inside the container (this overrides + the default set of paths). + items: + type: "string" + example: + - "/proc/asound" + - "/proc/acpi" + - "/proc/kcore" + - "/proc/keys" + - "/proc/latency_stats" + - "/proc/timer_list" + - "/proc/timer_stats" + - "/proc/sched_debug" + - "/proc/scsi" + - "/sys/firmware" + - "/sys/devices/virtual/powercap" + ReadonlyPaths: + type: "array" + description: | + The list of paths to be set as read-only inside the container + (this overrides the default set of paths). + items: + type: "string" + example: + - "/proc/bus" + - "/proc/fs" + - "/proc/irq" + - "/proc/sys" + - "/proc/sysrq-trigger" + + ContainerConfig: + description: | + Configuration for a container that is portable between hosts. + type: "object" + properties: + Hostname: + description: | + The hostname to use for the container, as a valid RFC 1123 hostname. + type: "string" + example: "439f4e91bd1d" + Domainname: + description: | + The domain name to use for the container. + type: "string" + User: + description: |- + Commands run as this user inside the container. If omitted, commands + run as the user specified in the image the container was started from. + + Can be either user-name or UID, and optional group-name or GID, + separated by a colon (`<user-name|UID>[<:group-name|GID>]`). + type: "string" + example: "123:456" + AttachStdin: + description: "Whether to attach to `stdin`." + type: "boolean" + default: false + AttachStdout: + description: "Whether to attach to `stdout`." + type: "boolean" + default: true + AttachStderr: + description: "Whether to attach to `stderr`." + type: "boolean" + default: true + ExposedPorts: + description: | + An object mapping ports to an empty object in the form: + + `{"<port>/<tcp|udp|sctp>": {}}` + type: "object" + x-nullable: true + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "80/tcp": {} + "443/tcp": {} + Tty: + description: | + Attach standard streams to a TTY, including `stdin` if it is not closed. + type: "boolean" + default: false + OpenStdin: + description: "Open `stdin`" + type: "boolean" + default: false + StdinOnce: + description: "Close `stdin` after one attached client disconnects" + type: "boolean" + default: false + Env: + description: | + A list of environment variables to set inside the container in the + form `["VAR=value", ...]`. A variable without `=` is removed from the + environment, rather than to have an empty value. + type: "array" + items: + type: "string" + example: + - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + Cmd: + description: | + Command to run specified as a string or an array of strings. + type: "array" + items: + type: "string" + example: ["/bin/sh"] + Healthcheck: + $ref: "#/definitions/HealthConfig" + ArgsEscaped: + description: "Command is already escaped (Windows only)" + type: "boolean" + default: false + example: false + x-nullable: true + Image: + description: | + The name (or reference) of the image to use when creating the container, + or which was used when the container was created. + type: "string" + example: "example-image:1.0" + Volumes: + description: | + An object mapping mount point paths inside the container to empty + objects. + type: "object" + additionalProperties: + type: "object" + enum: + - {} + default: {} + WorkingDir: + description: "The working directory for commands to run in." + type: "string" + example: "/public/" + Entrypoint: + description: | + The entry point for the container as a string or an array of strings. + + If the array consists of exactly one empty string (`[""]`) then the + entry point is reset to system default (i.e., the entry point used by + docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). + type: "array" + items: + type: "string" + example: [] + NetworkDisabled: + description: "Disable networking for the container." + type: "boolean" + x-nullable: true + OnBuild: + description: | + `ONBUILD` metadata that were defined in the image's `Dockerfile`. + type: "array" + x-nullable: true + items: + type: "string" + example: [] + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + StopSignal: + description: | + Signal to stop a container as a string or unsigned integer. + type: "string" + example: "SIGTERM" + x-nullable: true + StopTimeout: + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default (`default-stop-timeout`) is used. + type: "integer" + x-nullable: true + Shell: + description: | + Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. + type: "array" + x-nullable: true + items: + type: "string" + example: ["/bin/sh", "-c"] + + ImageConfig: + description: | + Configuration of the image. These fields are used as defaults + when starting a container from the image. + type: "object" + properties: + User: + description: "The user that commands are run as inside the container." + type: "string" + example: "web:web" + ExposedPorts: + description: | + An object mapping ports to an empty object in the form: + + `{"<port>/<tcp|udp|sctp>": {}}` + type: "object" + x-nullable: true + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "80/tcp": {} + "443/tcp": {} + Env: + description: | + A list of environment variables to set inside the container in the + form `["VAR=value", ...]`. A variable without `=` is removed from the + environment, rather than to have an empty value. + type: "array" + items: + type: "string" + example: + - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + Cmd: + description: | + Command to run specified as a string or an array of strings. + type: "array" + items: + type: "string" + example: ["/bin/sh"] + Healthcheck: + $ref: "#/definitions/HealthConfig" + ArgsEscaped: + description: "Command is already escaped (Windows only)" + type: "boolean" + default: false + example: false + x-nullable: true + Volumes: + description: | + An object mapping mount point paths inside the container to empty + objects. + type: "object" + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "/app/data": {} + "/app/config": {} + WorkingDir: + description: "The working directory for commands to run in." + type: "string" + example: "/public/" + Entrypoint: + description: | + The entry point for the container as a string or an array of strings. + + If the array consists of exactly one empty string (`[""]`) then the + entry point is reset to system default (i.e., the entry point used by + docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). + type: "array" + items: + type: "string" + example: [] + OnBuild: + description: | + `ONBUILD` metadata that were defined in the image's `Dockerfile`. + type: "array" + x-nullable: true + items: + type: "string" + example: [] + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + StopSignal: + description: | + Signal to stop a container as a string or unsigned integer. + type: "string" + example: "SIGTERM" + x-nullable: true + Shell: + description: | + Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. + type: "array" + x-nullable: true + items: + type: "string" + example: ["/bin/sh", "-c"] + + NetworkingConfig: + description: | + NetworkingConfig represents the container's networking configuration for + each of its interfaces. + It is used for the networking configs specified in the `docker create` + and `docker network connect` commands. + type: "object" + properties: + EndpointsConfig: + description: | + A mapping of network name to endpoint configuration for that network. + The endpoint configuration can be left empty to connect to that + network with no particular endpoint configuration. + type: "object" + additionalProperties: + $ref: "#/definitions/EndpointSettings" + example: + # putting an example here, instead of using the example values from + # /definitions/EndpointSettings, because EndpointSettings contains + # operational data returned when inspecting a container that we don't + # accept here. + EndpointsConfig: + isolated_nw: + IPAMConfig: + IPv4Address: "172.20.30.33" + IPv6Address: "2001:db8:abcd::3033" + LinkLocalIPs: + - "169.254.34.68" + - "fe80::3468" + MacAddress: "02:42:ac:12:05:02" + Links: + - "container_1" + - "container_2" + Aliases: + - "server_x" + - "server_y" + database_nw: {} + + NetworkSettings: + description: "NetworkSettings exposes the network settings in the API" + type: "object" + properties: + SandboxID: + description: SandboxID uniquely represents a container's network stack. + type: "string" + example: "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3" + SandboxKey: + description: SandboxKey is the full path of the netns handle + type: "string" + example: "/var/run/docker/netns/8ab54b426c38" + Ports: + $ref: "#/definitions/PortMap" + Networks: + description: | + Information about all networks that the container is connected to. + type: "object" + additionalProperties: + $ref: "#/definitions/EndpointSettings" + + Address: + description: Address represents an IPv4 or IPv6 IP address. + type: "object" + properties: + Addr: + description: IP address. + type: "string" + PrefixLen: + description: Mask length of the IP address. + type: "integer" + + PortMap: + description: | + PortMap describes the mapping of container ports to host ports, using the + container's port-number and protocol as key in the format `<port>/<protocol>`, + for example, `80/udp`. + + If a container's port is mapped for multiple protocols, separate entries + are added to the mapping table. + type: "object" + additionalProperties: + type: "array" + x-nullable: true + items: + $ref: "#/definitions/PortBinding" + example: + "443/tcp": + - HostIp: "127.0.0.1" + HostPort: "4443" + "80/tcp": + - HostIp: "0.0.0.0" + HostPort: "80" + - HostIp: "0.0.0.0" + HostPort: "8080" + "80/udp": + - HostIp: "0.0.0.0" + HostPort: "80" + "53/udp": + - HostIp: "0.0.0.0" + HostPort: "53" + "2377/tcp": null + + PortBinding: + description: | + PortBinding represents a binding between a host IP address and a host + port. + type: "object" + properties: + HostIp: + description: "Host IP address that the container's port is mapped to." + type: "string" + example: "127.0.0.1" + x-go-type: + type: Addr + import: + package: net/netip + HostPort: + description: "Host port number that the container's port is mapped to." + type: "string" + example: "4443" + + DriverData: + description: | + Information about the storage driver used to store the container's and + image's filesystem. + type: "object" + required: [Name, Data] + properties: + Name: + description: "Name of the storage driver." + type: "string" + x-nullable: false + example: "overlay2" + Data: + description: | + Low-level storage metadata, provided as key/value pairs. + + This information is driver-specific, and depends on the storage-driver + in use, and should be used for informational purposes only. + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" + "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" + + Storage: + description: | + Information about the storage used by the container. + type: "object" + properties: + RootFS: + description: | + Information about the storage used for the container's root filesystem. + type: "object" + x-nullable: true + $ref: "#/definitions/RootFSStorage" + + RootFSStorage: + description: | + Information about the storage used for the container's root filesystem. + type: "object" + x-go-name: RootFSStorage + properties: + Snapshot: + description: | + Information about the snapshot used for the container's root filesystem. + type: "object" + x-nullable: true + $ref: "#/definitions/RootFSStorageSnapshot" + + RootFSStorageSnapshot: + description: | + Information about a snapshot backend of the container's root filesystem. + type: "object" + x-go-name: RootFSStorageSnapshot + properties: + Name: + description: "Name of the snapshotter." + type: "string" + x-nullable: false + + FilesystemChange: + description: | + Change in the container's filesystem. + type: "object" + required: [Path, Kind] + properties: + Path: + description: | + Path to file or directory that has changed. + type: "string" + x-nullable: false + Kind: + $ref: "#/definitions/ChangeType" + + ChangeType: + description: | + Kind of change + + Can be one of: + + - `0`: Modified ("C") + - `1`: Added ("A") + - `2`: Deleted ("D") + type: "integer" + format: "uint8" + enum: [0, 1, 2] + x-nullable: false + + ImageInspect: + description: | + Information about an image in the local image cache. + type: "object" + properties: + Id: + description: | + ID is the content-addressable ID of an image. + + This identifier is a content-addressable digest calculated from the + image's configuration (which includes the digests of layers used by + the image). + + Note that this digest differs from the `RepoDigests` below, which + holds digests of image manifests that reference the image. + type: "string" + x-nullable: false + example: "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710" + Descriptor: + description: | + Descriptor is an OCI descriptor of the image target. + In case of a multi-platform image, this descriptor points to the OCI index + or a manifest list. + + This field is only present if the daemon provides a multi-platform image store. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + x-nullable: true + $ref: "#/definitions/OCIDescriptor" + Manifests: + description: | + Manifests is a list of image manifests available in this image. It + provides a more detailed view of the platform-specific image manifests or + other image-attached data like build attestations. + + Only available if the daemon provides a multi-platform image store + and the `manifests` option is set in the inspect request. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + type: "array" + x-nullable: true + items: + $ref: "#/definitions/ImageManifestSummary" + Identity: + description: |- + Identity holds information about the identity and origin of the image. + This is trusted information verified by the daemon and cannot be modified + by tagging an image to a different name. + x-nullable: true + $ref: "#/definitions/Identity" + RepoTags: + description: | + List of image names/tags in the local image cache that reference this + image. + + Multiple image tags can refer to the same image, and this list may be + empty if no tags reference the image, in which case the image is + "untagged", in which case it can still be referenced by its ID. + type: "array" + items: + type: "string" + example: + - "example:1.0" + - "example:latest" + - "example:stable" + - "internal.registry.example.com:5000/example:1.0" + RepoDigests: + description: | + List of content-addressable digests of locally available image manifests + that the image is referenced from. Multiple manifests can refer to the + same image. + + These digests are usually only available if the image was either pulled + from a registry, or if the image was pushed to a registry, which is when + the manifest is generated and its digest calculated. + type: "array" + items: + type: "string" + example: + - "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb" + - "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578" + Comment: + description: | + Optional message that was set when committing or importing the image. + type: "string" + x-nullable: true + example: "" + Created: + description: | + Date and time at which the image was created, formatted in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + + This information is only available if present in the image, + and omitted otherwise. + type: "string" + format: "dateTime" + x-nullable: true + example: "2022-02-04T21:20:12.497794809Z" + Author: + description: | + Name of the author that was specified when committing the image, or as + specified through MAINTAINER (deprecated) in the Dockerfile. + type: "string" + x-nullable: true + example: "" + Config: + $ref: "#/definitions/ImageConfig" + Architecture: + description: | + Hardware CPU architecture that the image runs on. + type: "string" + x-nullable: false + example: "arm" + Variant: + description: | + CPU architecture variant (presently ARM-only). + type: "string" + x-nullable: true + example: "v7" + Os: + description: | + Operating System the image is built to run on. + type: "string" + x-nullable: false + example: "linux" + OsVersion: + description: | + Operating System version the image is built to run on (especially + for Windows). + type: "string" + example: "" + x-nullable: true + Size: + description: | + Total size of the image including all layers it is composed of. + type: "integer" + format: "int64" + x-nullable: false + example: 1239828 + GraphDriver: + x-nullable: true + $ref: "#/definitions/DriverData" + RootFS: + description: | + Information about the image's RootFS, including the layer IDs. + type: "object" + required: [Type] + properties: + Type: + type: "string" + x-nullable: false + example: "layers" + Layers: + type: "array" + items: + type: "string" + example: + - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" + - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" + Metadata: + description: | + Additional metadata of the image in the local cache. This information + is local to the daemon, and not part of the image itself. + type: "object" + properties: + LastTagTime: + description: | + Date and time at which the image was last tagged in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + + This information is only available if the image was tagged locally, + and omitted otherwise. + type: "string" + format: "dateTime" + example: "2022-02-28T14:40:02.623929178Z" + x-nullable: true + + Identity: + description: |- + Identity holds information about the identity and origin of the image. + This is trusted information verified by the daemon and cannot be modified + by tagging an image to a different name. + type: "object" + properties: + Signature: + description: |- + Signature contains the properties of verified signatures for the image. + type: "array" + items: + $ref: "#/definitions/SignatureIdentity" + Pull: + description: |- + Pull contains remote location information if image was created via pull. + If image was pulled via mirror, this contains the original repository location. + After successful push this images also contains the pushed repository location. + type: "array" + items: + $ref: "#/definitions/PullIdentity" + Build: + description: |- + Build contains build reference information if image was created via build. + type: "array" + items: + $ref: "#/definitions/BuildIdentity" + + BuildIdentity: + description: |- + BuildIdentity contains build reference information if image was created via build. + type: "object" + properties: + Ref: + description: |- + Ref is the identifier for the build request. This reference can be used to + look up the build details in BuildKit history API. + type: "string" + CreatedAt: + description: |- + CreatedAt is the time when the build ran. + type: "string" + format: "date-time" + + PullIdentity: + description: |- + PullIdentity contains remote location information if image was created via pull. + If image was pulled via mirror, this contains the original repository location. + type: "object" + properties: + Repository: + description: |- + Repository is the remote repository location the image was pulled from. + type: "string" + + SignatureIdentity: + description: |- + SignatureIdentity contains the properties of verified signatures for the image. + type: "object" + properties: + Name: + description: |- + Name is a textual description summarizing the type of signature. + type: "string" + Timestamps: + description: |- + Timestamps contains a list of verified signed timestamps for the signature. + type: "array" + items: + $ref: "#/definitions/SignatureTimestamp" + KnownSigner: + description: |- + KnownSigner is an identifier for a special signer identity that is known to the implementation. + $ref: "#/definitions/KnownSignerIdentity" + DockerReference: + description: |- + DockerReference is the Docker image reference associated with the signature. + This is an optional field only present in older hashedrecord signatures. + type: "string" + Signer: + description: |- + Signer contains information about the signer certificate used to sign the image. + $ref: "#/definitions/SignerIdentity" + SignatureType: + description: |- + SignatureType is the type of signature format. E.g. "bundle-v0.3" or "hashedrecord". + $ref: "#/definitions/SignatureType" + Error: + description: |- + Error contains error information if signature verification failed. + Other fields will be empty in this case. + type: "string" + Warnings: + description: |- + Warnings contains any warnings that occurred during signature verification. + For example, if there was no internet connectivity and cached trust roots were used. + Warning does not indicate a failed verification but may point to configuration issues. + type: "array" + items: + type: "string" + + SignatureTimestamp: + description: |- + SignatureTimestamp contains information about a verified signed timestamp for an image signature. + type: "object" + properties: + Type: + $ref: "#/definitions/SignatureTimestampType" + URI: + type: "string" + Timestamp: + type: "string" + format: "date-time" + + SignatureTimestampType: + description: |- + SignatureTimestampType is the type of timestamp used in the signature. + type: "string" + enum: + - "Tlog" + - "TimestampAuthority" + + SignatureType: + description: |- + SignatureType is the type of signature format. + type: "string" + enum: + - "bundle-v0.3" + - "simplesigning-v1" + + KnownSignerIdentity: + description: |- + KnownSignerIdentity is an identifier for a special signer identity that is known to the implementation. + type: "string" + enum: + - "DHI" + + SignerIdentity: + description: |- + SignerIdentity contains information about the signer certificate used to sign the image. + type: "object" + properties: + CertificateIssuer: + type: "string" + description: |- + CertificateIssuer is the certificate issuer. + SubjectAlternativeName: + type: "string" + description: |- + SubjectAlternativeName is the certificate subject alternative name. + Issuer: + type: "string" + description: |- + The OIDC issuer. Should match `iss` claim of ID token or, in the case of + a federated login like Dex it should match the issuer URL of the + upstream issuer. The issuer is not set the extensions are invalid and + will fail to render. + BuildSignerURI: + type: "string" + description: |- + Reference to specific build instructions that are responsible for signing. + BuildSignerDigest: + type: "string" + description: |- + Immutable reference to the specific version of the build instructions that is responsible for signing. + RunnerEnvironment: + type: "string" + description: |- + Specifies whether the build took place in platform-hosted cloud infrastructure or customer/self-hosted infrastructure. + SourceRepositoryURI: + type: "string" + description: |- + Source repository URL that the build was based on. + SourceRepositoryDigest: + type: "string" + description: |- + Immutable reference to a specific version of the source code that the build was based upon. + SourceRepositoryRef: + type: "string" + description: |- + Source Repository Ref that the build run was based upon. + SourceRepositoryIdentifier: + type: "string" + description: |- + Immutable identifier for the source repository the workflow was based upon. + SourceRepositoryOwnerURI: + type: "string" + description: |- + Source repository owner URL of the owner of the source repository that the build was based on. + SourceRepositoryOwnerIdentifier: + type: "string" + description: |- + Immutable identifier for the owner of the source repository that the workflow was based upon. + BuildConfigURI: + type: "string" + description: |- + Build Config URL to the top-level/initiating build instructions. + BuildConfigDigest: + type: "string" + description: |- + Immutable reference to the specific version of the top-level/initiating build instructions. + BuildTrigger: + type: "string" + description: |- + Event or action that initiated the build. + RunInvocationURI: + type: "string" + description: |- + Run Invocation URL to uniquely identify the build execution. + SourceRepositoryVisibilityAtSigning: + type: "string" + description: |- + Source repository visibility at the time of signing the certificate. + + ImageSummary: + type: "object" + x-go-name: "Summary" + required: + - Id + - ParentId + - RepoTags + - RepoDigests + - Created + - Size + - SharedSize + - Labels + - Containers + properties: + Id: + description: | + ID is the content-addressable ID of an image. + + This identifier is a content-addressable digest calculated from the + image's configuration (which includes the digests of layers used by + the image). + + Note that this digest differs from the `RepoDigests` below, which + holds digests of image manifests that reference the image. + type: "string" + x-nullable: false + example: "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710" + ParentId: + description: | + ID of the parent image. + + Depending on how the image was created, this field may be empty and + is only set for images that were built/created locally. This field + is empty if the image was pulled from an image registry. + type: "string" + x-nullable: false + example: "" + RepoTags: + description: | + List of image names/tags in the local image cache that reference this + image. + + Multiple image tags can refer to the same image, and this list may be + empty if no tags reference the image, in which case the image is + "untagged", in which case it can still be referenced by its ID. + type: "array" + x-nullable: false + items: + type: "string" + example: + - "example:1.0" + - "example:latest" + - "example:stable" + - "internal.registry.example.com:5000/example:1.0" + RepoDigests: + description: | + List of content-addressable digests of locally available image manifests + that the image is referenced from. Multiple manifests can refer to the + same image. + + These digests are usually only available if the image was either pulled + from a registry, or if the image was pushed to a registry, which is when + the manifest is generated and its digest calculated. + type: "array" + x-nullable: false + items: + type: "string" + example: + - "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb" + - "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578" + Created: + description: | + Date and time at which the image was created as a Unix timestamp + (number of seconds since EPOCH). + type: "integer" + x-nullable: false + example: "1644009612" + Size: + description: | + Total size of the image including all layers it is composed of. + type: "integer" + format: "int64" + x-nullable: false + example: 172064416 + SharedSize: + description: | + Total size of image layers that are shared between this image and other + images. + + This size is not calculated by default. `-1` indicates that the value + has not been set / calculated. + type: "integer" + format: "int64" + x-nullable: false + example: 1239828 + Labels: + description: "User-defined key/value metadata." + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Containers: + description: | + Number of containers using this image. Includes both stopped and running + containers. + + `-1` indicates that the value has not been set / calculated. + x-nullable: false + type: "integer" + example: 2 + Manifests: + description: | + Manifests is a list of manifests available in this image. + It provides a more detailed view of the platform-specific image manifests + or other image-attached data like build attestations. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + type: "array" + x-nullable: false + x-omitempty: true + items: + $ref: "#/definitions/ImageManifestSummary" + Descriptor: + description: | + Descriptor is an OCI descriptor of the image target. + In case of a multi-platform image, this descriptor points to the OCI index + or a manifest list. + + This field is only present if the daemon provides a multi-platform image store. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + x-nullable: true + $ref: "#/definitions/OCIDescriptor" + + ImagesDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/image" + description: | + represents system data usage for image resources. + properties: + ActiveCount: + description: | + Count of active images. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all images. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing unused images. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by images. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of image summaries. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Summary + + AuthConfig: + type: "object" + properties: + username: + type: "string" + password: + type: "string" + serveraddress: + type: "string" + example: + username: "hannibal" + password: "xxxx" + serveraddress: "https://index.docker.io/v1/" + + AuthResponse: + description: | + An identity token was generated successfully. + type: "object" + required: [Status] + properties: + Status: + description: "The status of the authentication" + type: "string" + example: "Login Succeeded" + x-nullable: false + IdentityToken: + description: "An opaque token used to authenticate a user after a successful login" + type: "string" + example: "9cbaf023786cd7..." + x-nullable: false + + ProcessConfig: + type: "object" + properties: + privileged: + type: "boolean" + user: + type: "string" + tty: + type: "boolean" + entrypoint: + type: "string" + arguments: + type: "array" + items: + type: "string" + + Volume: + type: "object" + required: [Name, Driver, Mountpoint, Labels, Scope, Options] + x-nullable: false + properties: + Name: + type: "string" + description: "Name of the volume." + x-nullable: false + example: "tardis" + Driver: + type: "string" + description: "Name of the volume driver used by the volume." + x-nullable: false + example: "custom" + Mountpoint: + type: "string" + description: "Mount path of the volume on the host." + x-nullable: false + example: "/var/lib/docker/volumes/tardis" + CreatedAt: + type: "string" + format: "dateTime" + description: "Date/Time the volume was created." + example: "2016-06-07T20:31:11.853781916Z" + Status: + type: "object" + description: | + Low-level details about the volume, provided by the volume driver. + Details are returned as a map with key/value pairs: + `{"key":"value","key2":"value2"}`. + + The `Status` field is optional, and is omitted if the volume driver + does not support this feature. + additionalProperties: + type: "object" + example: + hello: "world" + Labels: + type: "object" + description: "User-defined key/value metadata." + x-nullable: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Scope: + type: "string" + description: | + The level at which the volume exists. Either `global` for cluster-wide, + or `local` for machine level. + default: "local" + x-nullable: false + enum: ["local", "global"] + example: "local" + ClusterVolume: + $ref: "#/definitions/ClusterVolume" + Options: + type: "object" + description: | + The driver specific options used when creating the volume. + additionalProperties: + type: "string" + example: + device: "tmpfs" + o: "size=100m,uid=1000" + type: "tmpfs" + UsageData: + type: "object" + x-nullable: true + x-go-name: "UsageData" + required: [Size, RefCount] + description: | + Usage details about the volume. This information is used by the + `GET /system/df` endpoint, and omitted in other endpoints. + properties: + Size: + type: "integer" + format: "int64" + default: -1 + description: | + Amount of disk space used by the volume (in bytes). This information + is only available for volumes created with the `"local"` volume + driver. For volumes created with other volume drivers, this field + is set to `-1` ("not available") + x-nullable: false + RefCount: + type: "integer" + format: "int64" + default: -1 + description: | + The number of containers referencing this volume. This field + is set to `-1` if the reference-count is not available. + x-nullable: false + + VolumesDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/volume" + description: | + represents system data usage for volume resources. + properties: + ActiveCount: + description: | + Count of active volumes. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all volumes. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive volumes. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by volumes. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of volumes. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Volume + + VolumeCreateRequest: + description: "Volume configuration" + type: "object" + title: "VolumeConfig" + x-go-name: "CreateRequest" + properties: + Name: + description: | + The new volume's name. If not specified, Docker generates a name. + type: "string" + x-nullable: false + example: "tardis" + Driver: + description: "Name of the volume driver to use." + type: "string" + default: "local" + x-nullable: false + example: "custom" + DriverOpts: + description: | + A mapping of driver options and values. These options are + passed directly to the driver and are driver specific. + type: "object" + additionalProperties: + type: "string" + example: + device: "tmpfs" + o: "size=100m,uid=1000" + type: "tmpfs" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + ClusterVolumeSpec: + $ref: "#/definitions/ClusterVolumeSpec" + + VolumeListResponse: + type: "object" + title: "VolumeListResponse" + x-go-name: "ListResponse" + description: "Volume list response" + properties: + Volumes: + type: "array" + description: "List of volumes" + items: + $ref: "#/definitions/Volume" + Warnings: + type: "array" + description: | + Warnings that occurred when fetching the list of volumes. + items: + type: "string" + example: [] + + Network: + type: "object" + properties: + Name: + description: | + Name of the network. + type: "string" + example: "my_network" + x-omitempty: false + Id: + description: | + ID that uniquely identifies a network on a single machine. + type: "string" + x-go-name: "ID" + x-omitempty: false + example: "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99" + Created: + description: | + Date and time at which the network was created in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-omitempty: false + x-go-type: + type: Time + import: + package: time + hints: + nullable: false + example: "2016-10-19T04:33:30.360899459Z" + Scope: + description: | + The level at which the network exists (e.g. `swarm` for cluster-wide + or `local` for machine level) + type: "string" + x-omitempty: false + example: "local" + Driver: + description: | + The name of the driver used to create the network (e.g. `bridge`, + `overlay`). + type: "string" + x-omitempty: false + example: "overlay" + EnableIPv4: + description: | + Whether the network was created with IPv4 enabled. + type: "boolean" + x-omitempty: false + example: true + EnableIPv6: + description: | + Whether the network was created with IPv6 enabled. + type: "boolean" + x-omitempty: false + example: false + IPAM: + description: | + The network's IP Address Management. + $ref: "#/definitions/IPAM" + x-nullable: false + x-omitempty: false + Internal: + description: | + Whether the network is created to only allow internal networking + connectivity. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + Attachable: + description: | + Whether a global / swarm scope network is manually attachable by regular + containers from workers in swarm mode. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + Ingress: + description: | + Whether the network is providing the routing-mesh for the swarm cluster. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + ConfigFrom: + $ref: "#/definitions/ConfigReference" + x-nullable: false + x-omitempty: false + ConfigOnly: + description: | + Whether the network is a config-only network. Config-only networks are + placeholder networks for network configurations to be used by other + networks. Config-only networks cannot be used directly to run containers + or services. + type: "boolean" + x-omitempty: false + x-nullable: false + default: false + Options: + description: | + Network-specific options uses when creating the network. + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + example: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + Labels: + description: | + Metadata specific to the network being created. + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Peers: + description: | + List of peer nodes for an overlay network. This field is only present + for overlay networks, and omitted for other network types. + type: "array" + x-omitempty: true + items: + $ref: "#/definitions/PeerInfo" + + NetworkSummary: + description: "Network list response item" + x-go-name: Summary + type: "object" + allOf: + - $ref: "#/definitions/Network" + + NetworkInspect: + description: 'The body of the "get network" http response message.' + x-go-name: Inspect + type: "object" + allOf: + - $ref: "#/definitions/Network" + properties: + Containers: + description: | + Contains endpoints attached to the network. + type: "object" + x-omitempty: false + additionalProperties: + $ref: "#/definitions/EndpointResource" + example: + 19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c: + Name: "test" + EndpointID: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a" + MacAddress: "02:42:ac:13:00:02" + IPv4Address: "172.19.0.2/16" + IPv6Address: "" + Services: + description: | + List of services using the network. This field is only present for + swarm scope networks, and omitted for local scope networks. + type: "object" + x-omitempty: true + additionalProperties: + x-go-type: + type: ServiceInfo + hints: + nullable: false + Status: + description: > + provides runtime information about the network + such as the number of allocated IPs. + $ref: "#/definitions/NetworkStatus" + + NetworkStatus: + description: > + provides runtime information about the network + such as the number of allocated IPs. + type: "object" + x-go-name: Status + properties: + IPAM: + $ref: "#/definitions/IPAMStatus" + + ServiceInfo: + x-nullable: false + x-omitempty: false + description: > + represents service parameters with the list of service's tasks + type: "object" + properties: + VIP: + type: "string" + x-omitempty: false + x-go-type: + type: Addr + import: + package: net/netip + Ports: + type: "array" + x-omitempty: false + items: + type: "string" + LocalLBIndex: + type: "integer" + format: "int" + x-omitempty: false + x-go-type: + type: int + Tasks: + type: "array" + x-omitempty: false + items: + $ref: "#/definitions/NetworkTaskInfo" + + NetworkTaskInfo: + x-nullable: false + x-omitempty: false + x-go-name: Task + description: > + carries the information about one backend task + type: "object" + properties: + Name: + type: "string" + x-omitempty: false + EndpointID: + type: "string" + x-omitempty: false + EndpointIP: + type: "string" + x-omitempty: false + x-go-type: + type: Addr + import: + package: net/netip + Info: + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + + ConfigReference: + x-nullable: false + x-omitempty: false + description: | + The config-only network source to provide the configuration for + this network. + type: "object" + properties: + Network: + description: | + The name of the config-only network that provides the network's + configuration. The specified network must be an existing config-only + network. Only network names are allowed, not network IDs. + type: "string" + x-omitempty: false + example: "config_only_network_01" + + IPAM: + type: "object" + x-nullable: false + x-omitempty: false + properties: + Driver: + description: "Name of the IPAM driver to use." + type: "string" + default: "default" + example: "default" + Config: + description: | + List of IPAM configuration options, specified as a map: + + ``` + {"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>} + ``` + type: "array" + items: + $ref: "#/definitions/IPAMConfig" + Options: + description: "Driver-specific options, specified as a map." + type: "object" + additionalProperties: + type: "string" + example: + foo: "bar" + + IPAMConfig: + type: "object" + properties: + Subnet: + type: "string" + example: "172.20.0.0/16" + IPRange: + type: "string" + example: "172.20.10.0/24" + Gateway: + type: "string" + example: "172.20.10.11" + AuxiliaryAddresses: + type: "object" + additionalProperties: + type: "string" + + IPAMStatus: + type: "object" + x-nullable: false + x-omitempty: false + properties: + Subnets: + type: "object" + additionalProperties: + $ref: "#/definitions/SubnetStatus" + example: + "172.16.0.0/16": + IPsInUse: 3 + DynamicIPsAvailable: 65533 + "2001:db8:abcd:0012::0/96": + IPsInUse: 5 + DynamicIPsAvailable: 4294967291 + x-go-type: + type: SubnetStatuses + kind: map + + SubnetStatus: + type: "object" + x-nullable: false + x-omitempty: false + properties: + IPsInUse: + description: > + Number of IP addresses in the subnet that are in use or reserved and + are therefore unavailable for allocation, saturating at 2<sup>64</sup> - 1. + type: integer + format: uint64 + x-omitempty: false + DynamicIPsAvailable: + description: > + Number of IP addresses within the network's IPRange for the subnet + that are available for allocation, saturating at 2<sup>64</sup> - 1. + type: integer + format: uint64 + x-omitempty: false + + EndpointResource: + type: "object" + description: > + contains network resources allocated and used for a + container in a network. + properties: + Name: + type: "string" + x-omitempty: false + example: "container_1" + EndpointID: + type: "string" + x-omitempty: false + example: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a" + MacAddress: + type: "string" + x-omitempty: false + example: "02:42:ac:13:00:02" + x-go-type: + type: HardwareAddr + IPv4Address: + type: "string" + x-omitempty: false + example: "172.19.0.2/16" + x-go-type: + type: Prefix + import: + package: net/netip + IPv6Address: + type: "string" + x-omitempty: false + example: "" + x-go-type: + type: Prefix + import: + package: net/netip + + PeerInfo: + description: > + represents one peer of an overlay network. + type: "object" + x-nullable: false + properties: + Name: + description: + ID of the peer-node in the Swarm cluster. + type: "string" + x-omitempty: false + example: "6869d7c1732b" + IP: + description: + IP-address of the peer-node in the Swarm cluster. + type: "string" + x-omitempty: false + example: "10.133.77.91" + x-go-type: + type: Addr + import: + package: net/netip + + NetworkCreateResponse: + description: "OK response to NetworkCreate operation" + type: "object" + title: "NetworkCreateResponse" + x-go-name: "CreateResponse" + required: [Id, Warning] + properties: + Id: + description: "The ID of the created network." + type: "string" + x-nullable: false + example: "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d" + Warning: + description: "Warnings encountered when creating the container" + type: "string" + x-nullable: false + example: "" + + BuildInfo: + type: "object" + properties: + id: + type: "string" + stream: + type: "string" + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + aux: + $ref: "#/definitions/ImageID" + + BuildCache: + type: "object" + description: | + BuildCache contains information about a build cache record. + properties: + ID: + type: "string" + description: | + Unique ID of the build cache record. + example: "ndlpt0hhvkqcdfkputsk4cq9c" + Parents: + description: | + List of parent build cache record IDs. + type: "array" + items: + type: "string" + x-nullable: true + example: ["hw53o5aio51xtltp5xjp8v7fx"] + Type: + type: "string" + description: | + Cache record type. + example: "regular" + # see https://github.com/moby/buildkit/blob/fce4a32258dc9d9664f71a4831d5de10f0670677/client/diskusage.go#L75-L84 + enum: + - "internal" + - "frontend" + - "source.local" + - "source.git.checkout" + - "exec.cachemount" + - "regular" + Description: + type: "string" + description: | + Description of the build-step that produced the build cache. + example: "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache" + InUse: + type: "boolean" + description: | + Indicates if the build cache is in use. + example: false + Shared: + type: "boolean" + description: | + Indicates if the build cache is shared. + example: true + Size: + description: | + Amount of disk space used by the build cache (in bytes). + type: "integer" + example: 51 + CreatedAt: + description: | + Date and time at which the build cache was created in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + LastUsedAt: + description: | + Date and time at which the build cache was last used in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-nullable: true + example: "2017-08-09T07:09:37.632105588Z" + UsageCount: + type: "integer" + example: 26 + + BuildCacheDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/build" + description: | + represents system data usage for build cache resources. + properties: + ActiveCount: + description: | + Count of active build cache records. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all build cache records. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive build cache records. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by build cache records. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of build cache records. + type: "array" + x-omitempty: true + items: + x-go-type: + type: CacheRecord + + ImageID: + type: "object" + description: "Image ID or Digest" + properties: + ID: + type: "string" + example: + ID: "sha256:85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c" + + CreateImageInfo: + type: "object" + properties: + id: + type: "string" + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + + PushImageInfo: + type: "object" + properties: + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + + DeviceInfo: + type: "object" + description: | + DeviceInfo represents a device that can be used by a container. + properties: + Source: + type: "string" + example: "cdi" + description: | + The origin device driver. + ID: + type: "string" + example: "vendor.com/gpu=0" + description: | + The unique identifier for the device within its source driver. + For CDI devices, this would be an FQDN like "vendor.com/gpu=0". + + NRIInfo: + description: | + Information about the Node Resource Interface (NRI). + + This field is only present if NRI is enabled. + type: "object" + x-nullable: true + properties: + Info: + description: | + Information about NRI, provided as "label" / "value" pairs. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["plugin-path", "/opt/docker/nri/plugins"] + + ErrorDetail: + type: "object" + properties: + code: + type: "integer" + message: + type: "string" + + ProgressDetail: + type: "object" + properties: + current: + type: "integer" + total: + type: "integer" + + ErrorResponse: + description: "Represents an error." + type: "object" + required: ["message"] + properties: + message: + description: "The error message." + type: "string" + x-nullable: false + example: + message: "Something went wrong." + + IDResponse: + description: "Response to an API call that returns just an Id" + type: "object" + x-go-name: "IDResponse" + required: ["Id"] + properties: + Id: + description: "The id of the newly created object." + type: "string" + x-nullable: false + + NetworkConnectRequest: + description: | + NetworkConnectRequest represents the data to be used to connect a container to a network. + type: "object" + x-go-name: "ConnectRequest" + required: ["Container"] + properties: + Container: + type: "string" + description: "The ID or name of the container to connect to the network." + x-nullable: false + example: "3613f73ba0e4" + EndpointConfig: + $ref: "#/definitions/EndpointSettings" + x-nullable: true + + NetworkDisconnectRequest: + description: | + NetworkDisconnectRequest represents the data to be used to disconnect a container from a network. + type: "object" + x-go-name: "DisconnectRequest" + required: ["Container"] + properties: + Container: + type: "string" + description: "The ID or name of the container to disconnect from the network." + x-nullable: false + example: "3613f73ba0e4" + Force: + type: "boolean" + description: "Force the container to disconnect from the network." + default: false + x-nullable: false + x-omitempty: false + example: false + + EndpointSettings: + description: "Configuration for a network endpoint." + type: "object" + properties: + # Configurations + IPAMConfig: + $ref: "#/definitions/EndpointIPAMConfig" + Links: + type: "array" + items: + type: "string" + example: + - "container_1" + - "container_2" + MacAddress: + description: | + MAC address for the endpoint on this network. The network driver might ignore this parameter. + type: "string" + example: "02:42:ac:11:00:04" + x-go-type: + type: HardwareAddr + Aliases: + type: "array" + items: + type: "string" + example: + - "server_x" + - "server_y" + DriverOpts: + description: | + DriverOpts is a mapping of driver options and values. These options + are passed directly to the driver and are driver specific. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + GwPriority: + description: | + This property determines which endpoint will provide the default + gateway for a container. The endpoint with the highest priority will + be used. If multiple endpoints have the same priority, endpoints are + lexicographically sorted based on their network name, and the one + that sorts first is picked. + type: "integer" + format: "int64" + example: + - 10 + + # Operational data + NetworkID: + description: | + Unique ID of the network. + type: "string" + example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a" + EndpointID: + description: | + Unique ID for the service endpoint in a Sandbox. + type: "string" + example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b" + Gateway: + description: | + Gateway address for this network. + type: "string" + example: "172.17.0.1" + IPAddress: + description: | + IPv4 address. + type: "string" + example: "172.17.0.4" + x-go-type: + type: Addr + import: + package: net/netip + IPPrefixLen: + description: | + Mask length of the IPv4 address. + type: "integer" + example: 16 + IPv6Gateway: + description: | + IPv6 gateway address. + type: "string" + example: "2001:db8:2::100" + x-go-type: + type: Addr + import: + package: net/netip + GlobalIPv6Address: + description: | + Global IPv6 address. + type: "string" + example: "2001:db8::5689" + x-go-type: + type: Addr + import: + package: net/netip + GlobalIPv6PrefixLen: + description: | + Mask length of the global IPv6 address. + type: "integer" + format: "int64" + example: 64 + DNSNames: + description: | + List of all DNS names an endpoint has on a specific network. This + list is based on the container name, network aliases, container short + ID, and hostname. + + These DNS names are non-fully qualified but can contain several dots. + You can get fully qualified DNS names by appending `.<network-name>`. + For instance, if container name is `my.ctr` and the network is named + `testnet`, `DNSNames` will contain `my.ctr` and the FQDN will be + `my.ctr.testnet`. + type: array + items: + type: string + example: ["foobar", "server_x", "server_y", "my.ctr"] + + EndpointIPAMConfig: + description: | + EndpointIPAMConfig represents an endpoint's IPAM configuration. + type: "object" + x-nullable: true + properties: + IPv4Address: + type: "string" + example: "172.20.30.33" + x-go-type: + type: Addr + import: + package: net/netip + IPv6Address: + type: "string" + example: "2001:db8:abcd::3033" + x-go-type: + type: Addr + import: + package: net/netip + LinkLocalIPs: + type: "array" + items: + type: "string" + x-go-type: + type: Addr + import: + package: net/netip + example: + - "169.254.34.68" + - "fe80::3468" + + PluginMount: + type: "object" + x-go-name: "Mount" + x-nullable: false + required: [Name, Description, Settable, Source, Destination, Type, Options] + properties: + Name: + type: "string" + x-nullable: false + example: "some-mount" + Description: + type: "string" + x-nullable: false + example: "This is a mount that's used by the plugin." + Settable: + type: "array" + items: + type: "string" + Source: + type: "string" + example: "/var/lib/docker/plugins/" + Destination: + type: "string" + x-nullable: false + example: "/mnt/state" + Type: + type: "string" + x-nullable: false + example: "bind" + Options: + type: "array" + items: + type: "string" + example: + - "rbind" + - "rw" + + PluginDevice: + type: "object" + x-go-name: "Device" + required: [Name, Description, Settable, Path] + x-nullable: false + properties: + Name: + type: "string" + x-nullable: false + Description: + type: "string" + x-nullable: false + Settable: + type: "array" + items: + type: "string" + Path: + type: "string" + example: "/dev/fuse" + + PluginEnv: + type: "object" + x-go-name: "Env" + x-nullable: false + required: [Name, Description, Settable, Value] + properties: + Name: + x-nullable: false + type: "string" + Description: + x-nullable: false + type: "string" + Settable: + type: "array" + items: + type: "string" + Value: + type: "string" + + PluginPrivilege: + description: | + Describes a permission the user has to accept upon installing + the plugin. + type: "object" + x-go-name: "Privilege" + properties: + Name: + type: "string" + example: "network" + Description: + type: "string" + Value: + type: "array" + items: + type: "string" + example: + - "host" + + Plugin: + description: "A plugin for the Engine API" + type: "object" + x-go-name: "Plugin" + required: [Settings, Enabled, Config, Name] + properties: + Id: + type: "string" + example: "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078" + Name: + type: "string" + x-nullable: false + example: "tiborvass/sample-volume-plugin" + Enabled: + description: + True if the plugin is running. False if the plugin is not running, + only installed. + type: "boolean" + x-nullable: false + example: true + Settings: + description: "user-configurable settings for the plugin." + type: "object" + x-go-name: "Settings" + x-nullable: false + required: [Args, Devices, Env, Mounts] + properties: + Mounts: + type: "array" + items: + $ref: "#/definitions/PluginMount" + Env: + type: "array" + items: + type: "string" + example: + - "DEBUG=0" + Args: + type: "array" + items: + type: "string" + Devices: + type: "array" + items: + $ref: "#/definitions/PluginDevice" + PluginReference: + description: "plugin remote reference used to push/pull the plugin" + type: "string" + x-go-name: "PluginReference" + x-nullable: false + example: "localhost:5000/tiborvass/sample-volume-plugin:latest" + Config: + description: "The config of a plugin." + type: "object" + x-go-name: "Config" + x-nullable: false + required: + - Description + - Documentation + - Interface + - Entrypoint + - WorkDir + - Network + - Linux + - PidHost + - PropagatedMount + - IpcHost + - Mounts + - Env + - Args + properties: + Description: + type: "string" + x-nullable: false + example: "A sample volume plugin for Docker" + Documentation: + type: "string" + x-nullable: false + example: "https://docs.docker.com/engine/extend/plugins/" + Interface: + description: "The interface between Docker and the plugin" + x-nullable: false + type: "object" + x-go-name: "Interface" + required: [Types, Socket] + properties: + Types: + type: "array" + items: + type: "string" + x-go-type: + type: "CapabilityID" + example: + - "docker.volumedriver/1.0" + Socket: + type: "string" + x-nullable: false + example: "plugins.sock" + ProtocolScheme: + type: "string" + example: "some.protocol/v1.0" + description: "Protocol to use for clients connecting to the plugin." + enum: + - "" + - "moby.plugins.http/v1" + Entrypoint: + type: "array" + items: + type: "string" + example: + - "/usr/bin/sample-volume-plugin" + - "/data" + WorkDir: + type: "string" + x-nullable: false + example: "/bin/" + User: + type: "object" + x-go-name: "User" + x-nullable: false + properties: + UID: + type: "integer" + format: "uint32" + example: 1000 + GID: + type: "integer" + format: "uint32" + example: 1000 + Network: + type: "object" + x-go-name: "NetworkConfig" + x-nullable: false + required: [Type] + properties: + Type: + x-nullable: false + type: "string" + example: "host" + Linux: + type: "object" + x-go-name: "LinuxConfig" + x-nullable: false + required: [Capabilities, AllowAllDevices, Devices] + properties: + Capabilities: + type: "array" + items: + type: "string" + example: + - "CAP_SYS_ADMIN" + - "CAP_SYSLOG" + AllowAllDevices: + type: "boolean" + x-nullable: false + example: false + Devices: + type: "array" + items: + $ref: "#/definitions/PluginDevice" + PropagatedMount: + type: "string" + x-nullable: false + example: "/mnt/volumes" + IpcHost: + type: "boolean" + x-nullable: false + example: false + PidHost: + type: "boolean" + x-nullable: false + example: false + Mounts: + type: "array" + items: + $ref: "#/definitions/PluginMount" + Env: + type: "array" + items: + $ref: "#/definitions/PluginEnv" + example: + - Name: "DEBUG" + Description: "If set, prints debug messages" + Settable: null + Value: "0" + Args: + type: "object" + x-go-name: "Args" + x-nullable: false + required: [Name, Description, Settable, Value] + properties: + Name: + x-nullable: false + type: "string" + example: "args" + Description: + x-nullable: false + type: "string" + example: "command line arguments" + Settable: + type: "array" + items: + type: "string" + Value: + type: "array" + items: + type: "string" + rootfs: + type: "object" + x-go-name: "RootFS" + properties: + type: + type: "string" + example: "layers" + diff_ids: + type: "array" + items: + type: "string" + example: + - "sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887" + - "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8" + + ObjectVersion: + description: | + The version number of the object such as node, service, etc. This is needed + to avoid conflicting writes. The client must send the version number along + with the modified specification when updating these objects. + + This approach ensures safe concurrency and determinism in that the change + on the object may not be applied if the version number has changed from the + last read. In other words, if two update requests specify the same base + version, only one of the requests can succeed. As a result, two separate + update requests that happen at the same time will not unintentionally + overwrite each other. + type: "object" + properties: + Index: + type: "integer" + format: "uint64" + example: 373531 + + NodeSpec: + type: "object" + properties: + Name: + description: "Name for the node." + type: "string" + example: "my-node" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Role: + description: "Role of the node." + type: "string" + enum: + - "worker" + - "manager" + example: "manager" + Availability: + description: "Availability of the node." + type: "string" + enum: + - "active" + - "pause" + - "drain" + example: "active" + example: + Availability: "active" + Name: "node-name" + Role: "manager" + Labels: + foo: "bar" + + Node: + type: "object" + properties: + ID: + type: "string" + example: "24ifsmvkjbyhk" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + description: | + Date and time at which the node was added to the swarm in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + UpdatedAt: + description: | + Date and time at which the node was last updated in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2017-08-09T07:09:37.632105588Z" + Spec: + $ref: "#/definitions/NodeSpec" + Description: + $ref: "#/definitions/NodeDescription" + Status: + $ref: "#/definitions/NodeStatus" + ManagerStatus: + $ref: "#/definitions/ManagerStatus" + + NodeDescription: + description: | + NodeDescription encapsulates the properties of the Node as reported by the + agent. + type: "object" + properties: + Hostname: + type: "string" + example: "bf3067039e47" + Platform: + $ref: "#/definitions/Platform" + Resources: + $ref: "#/definitions/ResourceObject" + Engine: + $ref: "#/definitions/EngineDescription" + TLSInfo: + $ref: "#/definitions/TLSInfo" + + Platform: + description: | + Platform represents the platform (Arch/OS). + type: "object" + properties: + Architecture: + description: | + Architecture represents the hardware architecture (for example, + `x86_64`). + type: "string" + example: "x86_64" + OS: + description: | + OS represents the Operating System (for example, `linux` or `windows`). + type: "string" + example: "linux" + + EngineDescription: + description: "EngineDescription provides information about an engine." + type: "object" + properties: + EngineVersion: + type: "string" + example: "17.06.0" + Labels: + type: "object" + additionalProperties: + type: "string" + example: + foo: "bar" + Plugins: + type: "array" + items: + type: "object" + properties: + Type: + type: "string" + Name: + type: "string" + example: + - Type: "Log" + Name: "awslogs" + - Type: "Log" + Name: "fluentd" + - Type: "Log" + Name: "gcplogs" + - Type: "Log" + Name: "gelf" + - Type: "Log" + Name: "journald" + - Type: "Log" + Name: "json-file" + - Type: "Log" + Name: "splunk" + - Type: "Log" + Name: "syslog" + - Type: "Network" + Name: "bridge" + - Type: "Network" + Name: "host" + - Type: "Network" + Name: "ipvlan" + - Type: "Network" + Name: "macvlan" + - Type: "Network" + Name: "null" + - Type: "Network" + Name: "overlay" + - Type: "Volume" + Name: "local" + - Type: "Volume" + Name: "localhost:5000/vieux/sshfs:latest" + - Type: "Volume" + Name: "vieux/sshfs:latest" + + TLSInfo: + description: | + Information about the issuer of leaf TLS certificates and the trusted root + CA certificate. + type: "object" + properties: + TrustRoot: + description: | + The root CA certificate(s) that are used to validate leaf TLS + certificates. + type: "string" + CertIssuerSubject: + description: + The base64-url-safe-encoded raw subject bytes of the issuer. + type: "string" + CertIssuerPublicKey: + description: | + The base64-url-safe-encoded raw public key bytes of the issuer. + type: "string" + example: + TrustRoot: | + -----BEGIN CERTIFICATE----- + MIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0 + MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf + 3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO + PQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz + pxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H + -----END CERTIFICATE----- + CertIssuerSubject: "MBMxETAPBgNVBAMTCHN3YXJtLWNh" + CertIssuerPublicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==" + + NodeStatus: + description: | + NodeStatus represents the status of a node. + + It provides the current status of the node, as seen by the manager. + type: "object" + properties: + State: + $ref: "#/definitions/NodeState" + Message: + type: "string" + example: "" + Addr: + description: "IP address of the node." + type: "string" + example: "172.17.0.2" + + NodeState: + description: "NodeState represents the state of a node." + type: "string" + enum: + - "unknown" + - "down" + - "ready" + - "disconnected" + example: "ready" + + ManagerStatus: + description: | + ManagerStatus represents the status of a manager. + + It provides the current status of a node's manager component, if the node + is a manager. + x-nullable: true + type: "object" + properties: + Leader: + type: "boolean" + default: false + example: true + Reachability: + $ref: "#/definitions/Reachability" + Addr: + description: | + The IP address and port at which the manager is reachable. + type: "string" + example: "10.0.0.46:2377" + + Reachability: + description: "Reachability represents the reachability of a node." + type: "string" + enum: + - "unknown" + - "unreachable" + - "reachable" + example: "reachable" + + SwarmSpec: + description: "User modifiable swarm configuration." + type: "object" + properties: + Name: + description: "Name of the swarm." + type: "string" + example: "default" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.corp.type: "production" + com.example.corp.department: "engineering" + Orchestration: + description: "Orchestration configuration." + type: "object" + x-nullable: true + properties: + TaskHistoryRetentionLimit: + description: | + The number of historic tasks to keep per instance or node. If + negative, never remove completed or failed tasks. + type: "integer" + format: "int64" + example: 10 + Raft: + description: "Raft configuration." + type: "object" + properties: + SnapshotInterval: + description: "The number of log entries between snapshots." + type: "integer" + format: "uint64" + example: 10000 + KeepOldSnapshots: + description: | + The number of snapshots to keep beyond the current snapshot. + type: "integer" + format: "uint64" + LogEntriesForSlowFollowers: + description: | + The number of log entries to keep around to sync up slow followers + after a snapshot is created. + type: "integer" + format: "uint64" + example: 500 + ElectionTick: + description: | + The number of ticks that a follower will wait for a message from + the leader before becoming a candidate and starting an election. + `ElectionTick` must be greater than `HeartbeatTick`. + + A tick currently defaults to one second, so these translate + directly to seconds currently, but this is NOT guaranteed. + type: "integer" + example: 3 + HeartbeatTick: + description: | + The number of ticks between heartbeats. Every HeartbeatTick ticks, + the leader will send a heartbeat to the followers. + + A tick currently defaults to one second, so these translate + directly to seconds currently, but this is NOT guaranteed. + type: "integer" + example: 1 + Dispatcher: + description: "Dispatcher configuration." + type: "object" + x-nullable: true + properties: + HeartbeatPeriod: + description: | + The delay for an agent to send a heartbeat to the dispatcher. + type: "integer" + format: "int64" + example: 5000000000 + CAConfig: + description: "CA configuration." + type: "object" + x-nullable: true + properties: + NodeCertExpiry: + description: "The duration node certificates are issued for." + type: "integer" + format: "int64" + example: 7776000000000000 + ExternalCAs: + description: | + Configuration for forwarding signing requests to an external + certificate authority. + type: "array" + items: + type: "object" + properties: + Protocol: + description: | + Protocol for communication with the external CA (currently + only `cfssl` is supported). + type: "string" + enum: + - "cfssl" + default: "cfssl" + URL: + description: | + URL where certificate signing requests should be sent. + type: "string" + Options: + description: | + An object with key/value pairs that are interpreted as + protocol-specific options for the external CA driver. + type: "object" + additionalProperties: + type: "string" + CACert: + description: | + The root CA certificate (in PEM format) this external CA uses + to issue TLS certificates (assumed to be to the current swarm + root CA certificate if not provided). + type: "string" + SigningCACert: + description: | + The desired signing CA certificate for all swarm node TLS leaf + certificates, in PEM format. + type: "string" + SigningCAKey: + description: | + The desired signing CA key for all swarm node TLS leaf certificates, + in PEM format. + type: "string" + ForceRotate: + description: | + An integer whose purpose is to force swarm to generate a new + signing CA certificate and key, if none have been specified in + `SigningCACert` and `SigningCAKey` + format: "uint64" + type: "integer" + EncryptionConfig: + description: "Parameters related to encryption-at-rest." + type: "object" + properties: + AutoLockManagers: + description: | + If set, generate a key and use it to lock data stored on the + managers. + type: "boolean" + example: false + TaskDefaults: + description: "Defaults for creating tasks in this cluster." + type: "object" + properties: + LogDriver: + description: | + The log driver to use for tasks created in the orchestrator if + unspecified by a service. + + Updating this value only affects new tasks. Existing tasks continue + to use their previously configured log driver until recreated. + type: "object" + properties: + Name: + description: | + The log driver to use as a default for new tasks. + type: "string" + example: "json-file" + Options: + description: | + Driver-specific options for the selected log driver, specified + as key/value pairs. + type: "object" + additionalProperties: + type: "string" + example: + "max-file": "10" + "max-size": "100m" + + # The Swarm information for `GET /info`. It is the same as `GET /swarm`, but + # without `JoinTokens`. + ClusterInfo: + description: | + ClusterInfo represents information about the swarm as is returned by the + "/info" endpoint. Join-tokens are not included. + x-nullable: true + type: "object" + properties: + ID: + description: "The ID of the swarm." + type: "string" + example: "abajmipo7b4xz5ip2nrla6b11" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + description: | + Date and time at which the swarm was initialised in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + UpdatedAt: + description: | + Date and time at which the swarm was last updated in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2017-08-09T07:09:37.632105588Z" + Spec: + $ref: "#/definitions/SwarmSpec" + TLSInfo: + $ref: "#/definitions/TLSInfo" + RootRotationInProgress: + description: | + Whether there is currently a root CA rotation in progress for the swarm + type: "boolean" + example: false + DataPathPort: + description: | + DataPathPort specifies the data path port number for data traffic. + Acceptable port range is 1024 to 49151. + If no port is set or is set to 0, the default port (4789) is used. + type: "integer" + format: "uint32" + default: 4789 + example: 4789 + DefaultAddrPool: + description: | + Default Address Pool specifies default subnet pools for global scope + networks. + type: "array" + items: + type: "string" + format: "CIDR" + example: ["10.10.0.0/16", "20.20.0.0/16"] + SubnetSize: + description: | + SubnetSize specifies the subnet size of the networks created from the + default subnet pool. + type: "integer" + format: "uint32" + maximum: 29 + default: 24 + example: 24 + + JoinTokens: + description: | + JoinTokens contains the tokens workers and managers need to join the swarm. + type: "object" + properties: + Worker: + description: | + The token workers can use to join the swarm. + type: "string" + example: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx" + Manager: + description: | + The token managers can use to join the swarm. + type: "string" + example: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" + + Swarm: + type: "object" + allOf: + - $ref: "#/definitions/ClusterInfo" + - type: "object" + properties: + JoinTokens: + $ref: "#/definitions/JoinTokens" + + TaskSpec: + description: "User modifiable task configuration." + type: "object" + properties: + PluginSpec: + type: "object" + description: | + Plugin spec for the service. *(Experimental release only.)* + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + properties: + Name: + description: "The name or 'alias' to use for the plugin." + type: "string" + Remote: + description: "The plugin image reference to use." + type: "string" + Disabled: + description: "Disable the plugin once scheduled." + type: "boolean" + PluginPrivilege: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + ContainerSpec: + type: "object" + description: | + Container spec for the service. + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + properties: + Image: + description: "The image name to use for the container" + type: "string" + Labels: + description: "User-defined key/value data." + type: "object" + additionalProperties: + type: "string" + Command: + description: "The command to be run in the image." + type: "array" + items: + type: "string" + Args: + description: "Arguments to the command." + type: "array" + items: + type: "string" + Hostname: + description: | + The hostname to use for the container, as a valid + [RFC 1123](https://tools.ietf.org/html/rfc1123) hostname. + type: "string" + Env: + description: | + A list of environment variables in the form `VAR=value`. + type: "array" + items: + type: "string" + Dir: + description: "The working directory for commands to run in." + type: "string" + User: + description: "The user inside the container." + type: "string" + Groups: + type: "array" + description: | + A list of additional groups that the container process will run as. + items: + type: "string" + Privileges: + type: "object" + description: "Security options for the container" + properties: + CredentialSpec: + type: "object" + description: "CredentialSpec for managed service account (Windows only)" + properties: + Config: + type: "string" + example: "0bt9dmxjvjiqermk6xrop3ekq" + description: | + Load credential spec from a Swarm Config with the given ID. + The specified config must also be present in the Configs + field with the Runtime property set. + + <p><br /></p> + + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + File: + type: "string" + example: "spec.json" + description: | + Load credential spec from this file. The file is read by + the daemon, and must be present in the `CredentialSpecs` + subdirectory in the docker data directory, which defaults + to `C:\ProgramData\Docker\` on Windows. + + For example, specifying `spec.json` loads + `C:\ProgramData\Docker\CredentialSpecs\spec.json`. + + <p><br /></p> + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + Registry: + type: "string" + description: | + Load credential spec from this value in the Windows + registry. The specified registry value must be located in: + + `HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs` + + <p><br /></p> + + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + SELinuxContext: + type: "object" + description: "SELinux labels of the container" + properties: + Disable: + type: "boolean" + description: "Disable SELinux" + User: + type: "string" + description: "SELinux user label" + Role: + type: "string" + description: "SELinux role label" + Type: + type: "string" + description: "SELinux type label" + Level: + type: "string" + description: "SELinux level label" + Seccomp: + type: "object" + description: "Options for configuring seccomp on the container" + properties: + Mode: + type: "string" + enum: + - "default" + - "unconfined" + - "custom" + Profile: + description: "The custom seccomp profile as a json object" + type: "string" + AppArmor: + type: "object" + description: "Options for configuring AppArmor on the container" + properties: + Mode: + type: "string" + enum: + - "default" + - "disabled" + NoNewPrivileges: + type: "boolean" + description: "Configuration of the no_new_privs bit in the container" + + TTY: + description: "Whether a pseudo-TTY should be allocated." + type: "boolean" + OpenStdin: + description: "Open `stdin`" + type: "boolean" + ReadOnly: + description: "Mount the container's root filesystem as read only." + type: "boolean" + Mounts: + description: | + Specification for mounts to be added to containers created as part + of the service. + type: "array" + items: + $ref: "#/definitions/Mount" + StopSignal: + description: "Signal to stop the container." + type: "string" + StopGracePeriod: + description: | + Amount of time to wait for the container to terminate before + forcefully killing it. + type: "integer" + format: "int64" + Healthcheck: + $ref: "#/definitions/HealthConfig" + Hosts: + type: "array" + description: | + A list of hostname/IP mappings to add to the container's `hosts` + file. The format of extra hosts is specified in the + [hosts(5)](http://man7.org/linux/man-pages/man5/hosts.5.html) + man page: + + IP_address canonical_hostname [aliases...] + items: + type: "string" + DNSConfig: + description: | + Specification for DNS related configurations in resolver configuration + file (`resolv.conf`). + type: "object" + properties: + Nameservers: + description: "The IP addresses of the name servers." + type: "array" + items: + type: "string" + Search: + description: "A search list for host-name lookup." + type: "array" + items: + type: "string" + Options: + description: | + A list of internal resolver variables to be modified (e.g., + `debug`, `ndots:3`, etc.). + type: "array" + items: + type: "string" + Secrets: + description: | + Secrets contains references to zero or more secrets that will be + exposed to the service. + type: "array" + items: + type: "object" + properties: + File: + description: | + File represents a specific target that is backed by a file. + type: "object" + properties: + Name: + description: | + Name represents the final filename in the filesystem. + type: "string" + UID: + description: "UID represents the file UID." + type: "string" + GID: + description: "GID represents the file GID." + type: "string" + Mode: + description: "Mode represents the FileMode of the file." + type: "integer" + format: "uint32" + SecretID: + description: | + SecretID represents the ID of the specific secret that we're + referencing. + type: "string" + SecretName: + description: | + SecretName is the name of the secret that this references, + but this is just provided for lookup/display purposes. The + secret in the reference will be identified by its ID. + type: "string" + OomScoreAdj: + type: "integer" + format: "int64" + description: | + An integer value containing the score given to the container in + order to tune OOM killer preferences. + example: 0 + Configs: + description: | + Configs contains references to zero or more configs that will be + exposed to the service. + type: "array" + items: + type: "object" + properties: + File: + description: | + File represents a specific target that is backed by a file. + + <p><br /><p> + + > **Note**: `Configs.File` and `Configs.Runtime` are mutually exclusive + type: "object" + properties: + Name: + description: | + Name represents the final filename in the filesystem. + type: "string" + UID: + description: "UID represents the file UID." + type: "string" + GID: + description: "GID represents the file GID." + type: "string" + Mode: + description: "Mode represents the FileMode of the file." + type: "integer" + format: "uint32" + Runtime: + description: | + Runtime represents a target that is not mounted into the + container but is used by the task + + <p><br /><p> + + > **Note**: `Configs.File` and `Configs.Runtime` are mutually + > exclusive + type: "object" + ConfigID: + description: | + ConfigID represents the ID of the specific config that we're + referencing. + type: "string" + ConfigName: + description: | + ConfigName is the name of the config that this references, + but this is just provided for lookup/display purposes. The + config in the reference will be identified by its ID. + type: "string" + Isolation: + type: "string" + description: | + Isolation technology of the containers running the service. + (Windows only) + enum: + - "default" + - "process" + - "hyperv" + - "" + Init: + description: | + Run an init inside the container that forwards signals and reaps + processes. This field is omitted if empty, and the default (as + configured on the daemon) is used. + type: "boolean" + x-nullable: true + Sysctls: + description: | + Set kernel namedspaced parameters (sysctls) in the container. + The Sysctls option on services accepts the same sysctls as the + are supported on containers. Note that while the same sysctls are + supported, no guarantees or checks are made about their + suitability for a clustered environment, and it's up to the user + to determine whether a given sysctl will work properly in a + Service. + type: "object" + additionalProperties: + type: "string" + # This option is not used by Windows containers + CapabilityAdd: + type: "array" + description: | + A list of kernel capabilities to add to the default set + for the container. + items: + type: "string" + example: + - "CAP_NET_RAW" + - "CAP_SYS_ADMIN" + - "CAP_SYS_CHROOT" + - "CAP_SYSLOG" + CapabilityDrop: + type: "array" + description: | + A list of kernel capabilities to drop from the default set + for the container. + items: + type: "string" + example: + - "CAP_NET_RAW" + Ulimits: + description: | + A list of resource limits to set in the container. For example: `{"Name": "nofile", "Soft": 1024, "Hard": 2048}`" + type: "array" + items: + type: "object" + properties: + Name: + description: "Name of ulimit" + type: "string" + Soft: + description: "Soft limit" + type: "integer" + Hard: + description: "Hard limit" + type: "integer" + NetworkAttachmentSpec: + description: | + Read-only spec type for non-swarm containers attached to swarm overlay + networks. + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + type: "object" + properties: + ContainerID: + description: "ID of the container represented by this task" + type: "string" + Resources: + description: | + Resource requirements which apply to each individual container created + as part of the service. + type: "object" + properties: + Limits: + description: "Define resources limits." + $ref: "#/definitions/Limit" + Reservations: + description: "Define resources reservation." + $ref: "#/definitions/ResourceObject" + SwapBytes: + description: | + Amount of swap in bytes - can only be used together with a memory limit. + If not specified, the default behaviour is to grant a swap space twice + as big as the memory limit. + Set to -1 to enable unlimited swap. + type: "integer" + format: "int64" + minimum: -1 + x-nullable: true + x-omitempty: true + MemorySwappiness: + description: | + Tune the service's containers' memory swappiness (0 to 100). + If not specified, defaults to the containers' OS' default, generally 60, + or whatever value was predefined in the image. + Set to -1 to unset a previously set value. + type: "integer" + format: "int64" + minimum: -1 + maximum: 100 + x-nullable: true + x-omitempty: true + RestartPolicy: + description: | + Specification for the restart policy which applies to containers + created as part of this service. + type: "object" + properties: + Condition: + description: "Condition for restart." + type: "string" + enum: + - "none" + - "on-failure" + - "any" + Delay: + description: "Delay between restart attempts." + type: "integer" + format: "int64" + MaxAttempts: + description: | + Maximum attempts to restart a given container before giving up + (default value is 0, which is ignored). + type: "integer" + format: "int64" + default: 0 + Window: + description: | + Windows is the time window used to evaluate the restart policy + (default value is 0, which is unbounded). + type: "integer" + format: "int64" + default: 0 + Placement: + type: "object" + properties: + Constraints: + description: | + An array of constraint expressions to limit the set of nodes where + a task can be scheduled. Constraint expressions can either use a + _match_ (`==`) or _exclude_ (`!=`) rule. Multiple constraints find + nodes that satisfy every expression (AND match). Constraints can + match node or Docker Engine labels as follows: + + node attribute | matches | example + ---------------------|--------------------------------|----------------------------------------------- + `node.id` | Node ID | `node.id==2ivku8v2gvtg4` + `node.hostname` | Node hostname | `node.hostname!=node-2` + `node.role` | Node role (`manager`/`worker`) | `node.role==manager` + `node.platform.os` | Node operating system | `node.platform.os==windows` + `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` + `node.labels` | User-defined node labels | `node.labels.security==high` + `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-24.04` + + `engine.labels` apply to Docker Engine labels like operating system, + drivers, etc. Swarm administrators add `node.labels` for operational + purposes by using the [`node update endpoint`](#operation/NodeUpdate). + + type: "array" + items: + type: "string" + example: + - "node.hostname!=node3.corp.example.com" + - "node.role!=manager" + - "node.labels.type==production" + - "node.platform.os==linux" + - "node.platform.arch==x86_64" + Preferences: + description: | + Preferences provide a way to make the scheduler aware of factors + such as topology. They are provided in order from highest to + lowest precedence. + type: "array" + items: + type: "object" + properties: + Spread: + type: "object" + properties: + SpreadDescriptor: + description: | + label descriptor, such as `engine.labels.az`. + type: "string" + example: + - Spread: + SpreadDescriptor: "node.labels.datacenter" + - Spread: + SpreadDescriptor: "node.labels.rack" + MaxReplicas: + description: | + Maximum number of replicas for per node (default value is 0, which + is unlimited) + type: "integer" + format: "int64" + default: 0 + Platforms: + description: | + Platforms stores all the platforms that the service's image can + run on. This field is used in the platform filter for scheduling. + If empty, then the platform filter is off, meaning there are no + scheduling restrictions. + type: "array" + items: + $ref: "#/definitions/Platform" + ForceUpdate: + description: | + A counter that triggers an update even if no relevant parameters have + been changed. + type: "integer" + format: "uint64" + Runtime: + description: | + Runtime is the type of runtime specified for the task executor. + type: "string" + Networks: + description: "Specifies which networks the service should attach to." + type: "array" + items: + $ref: "#/definitions/NetworkAttachmentConfig" + LogDriver: + description: | + Specifies the log driver to use for tasks created from this spec. If + not present, the default one for the swarm will be used, finally + falling back to the engine default if not specified. + type: "object" + properties: + Name: + type: "string" + Options: + type: "object" + additionalProperties: + type: "string" + + TaskState: + type: "string" + enum: + - "new" + - "allocated" + - "pending" + - "assigned" + - "accepted" + - "preparing" + - "ready" + - "starting" + - "running" + - "complete" + - "shutdown" + - "failed" + - "rejected" + - "remove" + - "orphaned" + + ContainerStatus: + type: "object" + description: "represents the status of a container." + properties: + ContainerID: + type: "string" + PID: + type: "integer" + ExitCode: + type: "integer" + + PortStatus: + type: "object" + description: "represents the port status of a task's host ports whose service has published host ports" + properties: + Ports: + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + + TaskStatus: + type: "object" + description: "represents the status of a task." + properties: + Timestamp: + type: "string" + format: "dateTime" + State: + $ref: "#/definitions/TaskState" + Message: + type: "string" + Err: + type: "string" + ContainerStatus: + $ref: "#/definitions/ContainerStatus" + PortStatus: + $ref: "#/definitions/PortStatus" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + + Task: + type: "object" + properties: + ID: + description: "The ID of the task." + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Name: + description: "Name of the task." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Spec: + $ref: "#/definitions/TaskSpec" + ServiceID: + description: "The ID of the service this task is part of." + type: "string" + Slot: + type: "integer" + NodeID: + description: "The ID of the node that this task is on." + type: "string" + AssignedGenericResources: + $ref: "#/definitions/GenericResources" + Status: + $ref: "#/definitions/TaskStatus" + DesiredState: + $ref: "#/definitions/TaskState" + JobIteration: + description: | + If the Service this Task belongs to is a job-mode service, contains + the JobIteration of the Service this Task was created for. Absent if + the Task was created for a Replicated or Global Service. + $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" + example: + ID: "0kzzo1i0y4jz6027t0k7aezc7" + Version: + Index: 71 + CreatedAt: "2016-06-07T21:07:31.171892745Z" + UpdatedAt: "2016-06-07T21:07:31.376370513Z" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:31.290032978Z" + State: "running" + Message: "started" + ContainerStatus: + ContainerID: "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035" + PID: 677 + DesiredState: "running" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.10/16" + AssignedGenericResources: + - DiscreteResourceSpec: + Kind: "SSD" + Value: 3 + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID1" + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID2" + + ServiceSpec: + description: "User modifiable configuration for a service." + type: object + properties: + Name: + description: "Name of the service." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + TaskTemplate: + $ref: "#/definitions/TaskSpec" + Mode: + description: "Scheduling mode for the service." + type: "object" + properties: + Replicated: + type: "object" + properties: + Replicas: + type: "integer" + format: "int64" + Global: + type: "object" + ReplicatedJob: + description: | + The mode used for services with a finite number of tasks that run + to a completed state. + type: "object" + properties: + MaxConcurrent: + description: | + The maximum number of replicas to run simultaneously. + type: "integer" + format: "int64" + default: 1 + TotalCompletions: + description: | + The total number of replicas desired to reach the Completed + state. If unset, will default to the value of `MaxConcurrent` + type: "integer" + format: "int64" + GlobalJob: + description: | + The mode used for services which run a task to the completed state + on each valid node. + type: "object" + UpdateConfig: + description: "Specification for the update strategy of the service." + type: "object" + properties: + Parallelism: + description: | + Maximum number of tasks to be updated in one iteration (0 means + unlimited parallelism). + type: "integer" + format: "int64" + Delay: + description: "Amount of time between updates, in nanoseconds." + type: "integer" + format: "int64" + FailureAction: + description: | + Action to take if an updated task fails to run, or stops running + during the update. + type: "string" + enum: + - "continue" + - "pause" + - "rollback" + Monitor: + description: | + Amount of time to monitor each updated task for failures, in + nanoseconds. + type: "integer" + format: "int64" + MaxFailureRatio: + description: | + The fraction of tasks that may fail during an update before the + failure action is invoked, specified as a floating point number + between 0 and 1. + type: "number" + default: 0 + Order: + description: | + The order of operations when rolling out an updated task. Either + the old task is shut down before the new task is started, or the + new task is started before the old task is shut down. + type: "string" + enum: + - "stop-first" + - "start-first" + RollbackConfig: + description: "Specification for the rollback strategy of the service." + type: "object" + properties: + Parallelism: + description: | + Maximum number of tasks to be rolled back in one iteration (0 means + unlimited parallelism). + type: "integer" + format: "int64" + Delay: + description: | + Amount of time between rollback iterations, in nanoseconds. + type: "integer" + format: "int64" + FailureAction: + description: | + Action to take if an rolled back task fails to run, or stops + running during the rollback. + type: "string" + enum: + - "continue" + - "pause" + Monitor: + description: | + Amount of time to monitor each rolled back task for failures, in + nanoseconds. + type: "integer" + format: "int64" + MaxFailureRatio: + description: | + The fraction of tasks that may fail during a rollback before the + failure action is invoked, specified as a floating point number + between 0 and 1. + type: "number" + default: 0 + Order: + description: | + The order of operations when rolling back a task. Either the old + task is shut down before the new task is started, or the new task + is started before the old task is shut down. + type: "string" + enum: + - "stop-first" + - "start-first" + Networks: + description: | + Specifies which networks the service should attach to. + + Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. + type: "array" + items: + $ref: "#/definitions/NetworkAttachmentConfig" + + EndpointSpec: + $ref: "#/definitions/EndpointSpec" + + EndpointPortConfig: + type: "object" + properties: + Name: + type: "string" + Protocol: + type: "string" + enum: + - "tcp" + - "udp" + - "sctp" + TargetPort: + description: "The port inside the container." + type: "integer" + PublishedPort: + description: "The port on the swarm hosts." + type: "integer" + PublishMode: + description: | + The mode in which port is published. + + <p><br /></p> + + - "ingress" makes the target port accessible on every node, + regardless of whether there is a task for the service running on + that node or not. + - "host" bypasses the routing mesh and publish the port directly on + the swarm node where that service is running. + + type: "string" + enum: + - "ingress" + - "host" + default: "ingress" + example: "ingress" + + EndpointSpec: + description: "Properties that can be configured to access and load balance a service." + type: "object" + properties: + Mode: + description: | + The mode of resolution to use for internal load balancing between tasks. + type: "string" + enum: + - "vip" + - "dnsrr" + default: "vip" + Ports: + description: | + List of exposed ports that this service is accessible on from the + outside. Ports can only be provided if `vip` resolution mode is used. + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + + Service: + type: "object" + properties: + ID: + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ServiceSpec" + Endpoint: + type: "object" + properties: + Spec: + $ref: "#/definitions/EndpointSpec" + Ports: + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + VirtualIPs: + type: "array" + items: + type: "object" + properties: + NetworkID: + type: "string" + Addr: + type: "string" + UpdateStatus: + description: "The status of a service update." + type: "object" + properties: + State: + type: "string" + enum: + - "updating" + - "paused" + - "completed" + StartedAt: + type: "string" + format: "dateTime" + CompletedAt: + type: "string" + format: "dateTime" + Message: + type: "string" + ServiceStatus: + description: | + The status of the service's tasks. Provided only when requested as + part of a ServiceList operation. + type: "object" + properties: + RunningTasks: + description: | + The number of tasks for the service currently in the Running state. + type: "integer" + format: "uint64" + example: 7 + DesiredTasks: + description: | + The number of tasks for the service desired to be running. + For replicated services, this is the replica count from the + service spec. For global services, this is computed by taking + count of all tasks for the service with a Desired State other + than Shutdown. + type: "integer" + format: "uint64" + example: 10 + CompletedTasks: + description: | + The number of tasks for a job that are in the Completed state. + This field must be cross-referenced with the service type, as the + value of 0 may mean the service is not in a job mode, or it may + mean the job-mode service has no tasks yet Completed. + type: "integer" + format: "uint64" + JobStatus: + description: | + The status of the service when it is in one of ReplicatedJob or + GlobalJob modes. Absent on Replicated and Global mode services. The + JobIteration is an ObjectVersion, but unlike the Service's version, + does not need to be sent with an update request. + type: "object" + properties: + JobIteration: + description: | + JobIteration is a value increased each time a Job is executed, + successfully or otherwise. "Executed", in this case, means the + job as a whole has been started, not that an individual Task has + been launched. A job is "Executed" when its ServiceSpec is + updated. JobIteration can be used to disambiguate Tasks belonging + to different executions of a job. Though JobIteration will + increase with each subsequent execution, it may not necessarily + increase by 1, and so JobIteration should not be used to + $ref: "#/definitions/ObjectVersion" + LastExecution: + description: | + The last time, as observed by the server, that this job was + started. + type: "string" + format: "dateTime" + example: + ID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Version: + Index: 19 + CreatedAt: "2016-06-07T21:05:51.880065305Z" + UpdatedAt: "2016-06-07T21:07:29.962229872Z" + Spec: + Name: "hopeful_cori" + TaskTemplate: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ForceUpdate: 0 + Mode: + Replicated: + Replicas: 1 + UpdateConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Mode: "vip" + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + Endpoint: + Spec: + Mode: "vip" + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + VirtualIPs: + - + NetworkID: "4qvuz4ko70xaltuqbt8956gd1" + Addr: "10.255.0.2/16" + - + NetworkID: "4qvuz4ko70xaltuqbt8956gd1" + Addr: "10.255.0.3/16" + + ImageDeleteResponseItem: + type: "object" + x-go-name: "DeleteResponse" + properties: + Untagged: + description: "The image ID of an image that was untagged" + type: "string" + Deleted: + description: "The image ID of an image that was deleted" + type: "string" + + ServiceCreateResponse: + type: "object" + description: | + contains the information returned to a client on the + creation of a new service. + properties: + ID: + description: "The ID of the created service." + type: "string" + x-nullable: false + example: "ak7w3gjqoa3kuz8xcpnyy0pvl" + Warnings: + description: | + Optional warning message. + + FIXME(thaJeztah): this should have "omitempty" in the generated type. + type: "array" + x-nullable: true + items: + type: "string" + example: + - "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" + + ServiceUpdateResponse: + type: "object" + properties: + Warnings: + description: "Optional warning messages" + type: "array" + items: + type: "string" + example: + Warnings: + - "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" + + ContainerInspectResponse: + type: "object" + title: "ContainerInspectResponse" + x-go-name: "InspectResponse" + properties: + Id: + description: |- + The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes). + type: "string" + x-go-name: "ID" + minLength: 64 + maxLength: 64 + pattern: "^[0-9a-fA-F]{64}$" + example: "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf" + Created: + description: |- + Date and time at which the container was created, formatted in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-nullable: true + example: "2025-02-17T17:43:39.64001363Z" + Path: + description: |- + The path to the command being run + type: "string" + example: "/bin/sh" + Args: + description: "The arguments to the command being run" + type: "array" + items: + type: "string" + example: + - "-c" + - "exit 9" + State: + $ref: "#/definitions/ContainerState" + Image: + description: |- + The ID (digest) of the image that this container was created from. + type: "string" + example: "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782" + ResolvConfPath: + description: |- + Location of the `/etc/resolv.conf` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf" + HostnamePath: + description: |- + Location of the `/etc/hostname` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname" + HostsPath: + description: |- + Location of the `/etc/hosts` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts" + LogPath: + description: |- + Location of the file used to buffer the container's logs. Depending on + the logging-driver used for the container, this field may be omitted. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + x-nullable: true + example: "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log" + Name: + description: |- + The name associated with this container. + + For historic reasons, the name may be prefixed with a forward-slash (`/`). + type: "string" + example: "/funny_chatelet" + RestartCount: + description: |- + Number of times the container was restarted since it was created, + or since daemon was started. + type: "integer" + example: 0 + Driver: + description: |- + The storage-driver used for the container's filesystem (graph-driver + or snapshotter). + type: "string" + example: "overlayfs" + Platform: + description: |- + The platform (operating system) for which the container was created. + + This field was introduced for the experimental "LCOW" (Linux Containers + On Windows) features, which has been removed. In most cases, this field + is equal to the host's operating system (`linux` or `windows`). + type: "string" + example: "linux" + ImageManifestDescriptor: + $ref: "#/definitions/OCIDescriptor" + description: |- + OCI descriptor of the platform-specific manifest of the image + the container was created from. + + Note: Only available if the daemon provides a multi-platform + image store. + MountLabel: + description: |- + SELinux mount label set for the container. + type: "string" + example: "" + ProcessLabel: + description: |- + SELinux process label set for the container. + type: "string" + example: "" + AppArmorProfile: + description: |- + The AppArmor profile set for the container. + type: "string" + example: "" + ExecIDs: + description: |- + IDs of exec instances that are running in the container. + type: "array" + items: + type: "string" + x-nullable: true + example: + - "b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca" + - "3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4" + HostConfig: + $ref: "#/definitions/HostConfig" + GraphDriver: + $ref: "#/definitions/DriverData" + x-nullable: true + Storage: + $ref: "#/definitions/Storage" + x-nullable: true + SizeRw: + description: |- + The size of files that have been created or changed by this container. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "122880" + SizeRootFs: + description: |- + The total size of all files in the read-only layers from the image + that the container uses. These layers can be shared between containers. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "1653948416" + Mounts: + description: |- + List of mounts used by the container. + type: "array" + items: + $ref: "#/definitions/MountPoint" + Config: + $ref: "#/definitions/ContainerConfig" + NetworkSettings: + $ref: "#/definitions/NetworkSettings" + + ContainerSummary: + type: "object" + properties: + Id: + description: |- + The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes). + type: "string" + x-go-name: "ID" + minLength: 64 + maxLength: 64 + pattern: "^[0-9a-fA-F]{64}$" + example: "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf" + Names: + description: |- + The names associated with this container. Most containers have a single + name, but when using legacy "links", the container can have multiple + names. + + For historic reasons, names are prefixed with a forward-slash (`/`). + type: "array" + items: + type: "string" + example: + - "/funny_chatelet" + Image: + description: |- + The name or ID of the image used to create the container. + + This field shows the image reference as was specified when creating the container, + which can be in its canonical form (e.g., `docker.io/library/ubuntu:latest` + or `docker.io/library/ubuntu@sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`), + short form (e.g., `ubuntu:latest`)), or the ID(-prefix) of the image (e.g., `72297848456d`). + + The content of this field can be updated at runtime if the image used to + create the container is untagged, in which case the field is updated to + contain the the image ID (digest) it was resolved to in its canonical, + non-truncated form (e.g., `sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`). + type: "string" + example: "docker.io/library/ubuntu:latest" + ImageID: + description: |- + The ID (digest) of the image that this container was created from. + type: "string" + example: "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782" + ImageManifestDescriptor: + $ref: "#/definitions/OCIDescriptor" + x-nullable: true + description: | + OCI descriptor of the platform-specific manifest of the image + the container was created from. + + Note: Only available if the daemon provides a multi-platform + image store. + + This field is not populated in the `GET /system/df` endpoint. + Command: + description: "Command to run when starting the container" + type: "string" + example: "/bin/bash" + Created: + description: |- + Date and time at which the container was created as a Unix timestamp + (number of seconds since EPOCH). + type: "integer" + format: "int64" + example: "1739811096" + Ports: + description: |- + Port-mappings for the container. + type: "array" + items: + $ref: "#/definitions/PortSummary" + SizeRw: + description: |- + The size of files that have been created or changed by this container. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "122880" + SizeRootFs: + description: |- + The total size of all files in the read-only layers from the image + that the container uses. These layers can be shared between containers. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "1653948416" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.vendor: "Acme" + com.example.license: "GPL" + com.example.version: "1.0" + State: + description: | + The state of this container. + type: "string" + enum: + - "created" + - "running" + - "paused" + - "restarting" + - "exited" + - "removing" + - "dead" + example: "running" + Status: + description: |- + Additional human-readable status of this container (e.g. `Exit 0`) + type: "string" + example: "Up 4 days" + HostConfig: + type: "object" + description: |- + Summary of host-specific runtime information of the container. This + is a reduced set of information in the container's "HostConfig" as + available in the container "inspect" response. + properties: + NetworkMode: + description: |- + Networking mode (`host`, `none`, `container:<id>`) or name of the + primary network the container is using. + + This field is primarily for backward compatibility. The container + can be connected to multiple networks for which information can be + found in the `NetworkSettings.Networks` field, which enumerates + settings per network. + type: "string" + example: "mynetwork" + Annotations: + description: |- + Arbitrary key-value metadata attached to the container. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + io.kubernetes.docker.type: "container" + io.kubernetes.sandbox.id: "3befe639bed0fd6afdd65fd1fa84506756f59360ec4adc270b0fdac9be22b4d3" + NetworkSettings: + description: |- + Summary of the container's network settings + type: "object" + properties: + Networks: + type: "object" + description: |- + Summary of network-settings for each network the container is + attached to. + additionalProperties: + $ref: "#/definitions/EndpointSettings" + Mounts: + type: "array" + description: |- + List of mounts used by the container. + items: + $ref: "#/definitions/MountPoint" + Health: + type: "object" + description: |- + Summary of health status + + Added in v1.52, before that version all container summary not include Health. + After this attribute introduced, it includes containers with no health checks configured, + or containers that are not running with none + properties: + Status: + type: "string" + description: |- + the health status of the container + enum: + - "none" + - "starting" + - "healthy" + - "unhealthy" + example: "healthy" + FailingStreak: + description: "FailingStreak is the number of consecutive failures" + type: "integer" + example: 0 + + ContainersDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/container" + description: | + represents system data usage information for container resources. + properties: + ActiveCount: + description: | + Count of active containers. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all containers. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive containers. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by containers. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of container summaries. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Summary + + Driver: + description: "Driver represents a driver (network, logging, secrets)." + type: "object" + required: [Name] + properties: + Name: + description: "Name of the driver." + type: "string" + x-nullable: false + example: "some-driver" + Options: + description: "Key/value map of driver-specific options." + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + OptionA: "value for driver-specific option A" + OptionB: "value for driver-specific option B" + + SecretSpec: + type: "object" + properties: + Name: + description: "User-defined name of the secret." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Data: + description: | + Data is the data to store as a secret, formatted as a standard base64-encoded + ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. + It must be empty if the Driver field is set, in which case the data is + loaded from an external secret store. The maximum allowed size is 500KB, + as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize). + + This field is only used to _create_ a secret, and is not returned by + other endpoints. + type: "string" + example: "" + Driver: + description: | + Name of the secrets driver used to fetch the secret's value from an + external secret store. + $ref: "#/definitions/Driver" + Templating: + description: | + Templating driver, if applicable + + Templating controls whether and how to evaluate the config payload as + a template. If no driver is set, no templating is used. + $ref: "#/definitions/Driver" + + Secret: + type: "object" + properties: + ID: + type: "string" + example: "blt1owaxmitz71s9v5zh81zun" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" + UpdatedAt: + type: "string" + format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" + Spec: + $ref: "#/definitions/SecretSpec" + + ConfigSpec: + type: "object" + properties: + Name: + description: "User-defined name of the config." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Data: + description: | + Data is the data to store as a config, formatted as a standard base64-encoded + ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. + The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). + type: "string" + Templating: + description: | + Templating driver, if applicable + + Templating controls whether and how to evaluate the config payload as + a template. If no driver is set, no templating is used. + $ref: "#/definitions/Driver" + + Config: + type: "object" + properties: + ID: + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ConfigSpec" + + ContainerState: + description: | + ContainerState stores container's running state. It's part of ContainerJSONBase + and will be returned by the "inspect" command. + type: "object" + x-nullable: true + properties: + Status: + description: | + String representation of the container state. Can be one of "created", + "running", "paused", "restarting", "removing", "exited", or "dead". + type: "string" + enum: ["created", "running", "paused", "restarting", "removing", "exited", "dead"] + example: "running" + Running: + description: | + Whether this container is running. + + Note that a running container can be _paused_. The `Running` and `Paused` + booleans are not mutually exclusive: + + When pausing a container (on Linux), the freezer cgroup is used to suspend + all processes in the container. Freezing the process requires the process to + be running. As a result, paused containers are both `Running` _and_ `Paused`. + + Use the `Status` field instead to determine if a container's state is "running". + type: "boolean" + example: true + Paused: + description: "Whether this container is paused." + type: "boolean" + example: false + Restarting: + description: "Whether this container is restarting." + type: "boolean" + example: false + OOMKilled: + description: | + Whether a process within this container has been killed because it ran + out of memory since the container was last started. + type: "boolean" + example: false + Dead: + type: "boolean" + example: false + Pid: + description: "The process ID of this container" + type: "integer" + example: 1234 + ExitCode: + description: "The last exit code of this container" + type: "integer" + example: 0 + Error: + type: "string" + StartedAt: + description: "The time when this container was last started." + type: "string" + example: "2020-01-06T09:06:59.461876391Z" + FinishedAt: + description: "The time when this container last exited." + type: "string" + example: "2020-01-06T09:07:59.461876391Z" + Health: + $ref: "#/definitions/Health" + + ContainerCreateResponse: + description: "OK response to ContainerCreate operation" + type: "object" + title: "ContainerCreateResponse" + x-go-name: "CreateResponse" + required: [Id, Warnings] + properties: + Id: + description: "The ID of the created container" + type: "string" + x-nullable: false + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + Warnings: + description: "Warnings encountered when creating the container" + type: "array" + x-nullable: false + items: + type: "string" + example: [] + + ContainerUpdateResponse: + type: "object" + title: "ContainerUpdateResponse" + x-go-name: "UpdateResponse" + description: |- + Response for a successful container-update. + properties: + Warnings: + type: "array" + description: |- + Warnings encountered when updating the container. + items: + type: "string" + example: ["Published ports are discarded when using host network mode"] + + ContainerStatsResponse: + description: | + Statistics sample for a container. + type: "object" + x-go-name: "StatsResponse" + title: "ContainerStatsResponse" + properties: + id: + description: | + ID of the container for which the stats were collected. + type: "string" + x-nullable: true + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + name: + description: | + Name of the container for which the stats were collected. + type: "string" + x-nullable: true + example: "boring_wozniak" + os_type: + description: | + OSType is the OS of the container ("linux" or "windows") to allow + platform-specific handling of stats. + type: "string" + x-nullable: true + example: "linux" + read: + description: | + Date and time at which this sample was collected. + The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + with nano-seconds. + type: "string" + format: "date-time" + example: "2025-01-16T13:55:22.165243637Z" + cpu_stats: + $ref: "#/definitions/ContainerCPUStats" + memory_stats: + $ref: "#/definitions/ContainerMemoryStats" + networks: + description: | + Network statistics for the container per interface. + + This field is omitted if the container has no networking enabled. + x-nullable: true + additionalProperties: + $ref: "#/definitions/ContainerNetworkStats" + example: + eth0: + rx_bytes: 5338 + rx_dropped: 0 + rx_errors: 0 + rx_packets: 36 + tx_bytes: 648 + tx_dropped: 0 + tx_errors: 0 + tx_packets: 8 + eth5: + rx_bytes: 4641 + rx_dropped: 0 + rx_errors: 0 + rx_packets: 26 + tx_bytes: 690 + tx_dropped: 0 + tx_errors: 0 + tx_packets: 9 + pids_stats: + $ref: "#/definitions/ContainerPidsStats" + blkio_stats: + $ref: "#/definitions/ContainerBlkioStats" + num_procs: + description: | + The number of processors on the system. + + This field is Windows-specific and always zero for Linux containers. + type: "integer" + format: "uint32" + example: 16 + storage_stats: + $ref: "#/definitions/ContainerStorageStats" + preread: + description: | + Date and time at which this first sample was collected. This field + is not propagated if the "one-shot" option is set. If the "one-shot" + option is set, this field may be omitted, empty, or set to a default + date (`0001-01-01T00:00:00Z`). + + The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + with nano-seconds. + type: "string" + format: "date-time" + example: "2025-01-16T13:55:21.160452595Z" + precpu_stats: + $ref: "#/definitions/ContainerCPUStats" + + ContainerBlkioStats: + description: | + BlkioStats stores all IO service stats for data read and write. + + This type is Linux-specific and holds many fields that are specific to cgroups v1. + On a cgroup v2 host, all fields other than `io_service_bytes_recursive` + are omitted or `null`. + + This type is only populated on Linux and omitted for Windows containers. + type: "object" + x-go-name: "BlkioStats" + x-nullable: true + properties: + io_service_bytes_recursive: + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_serviced_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_queue_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_service_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_wait_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_merged_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + sectors_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + example: + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} + io_serviced_recursive: null + io_queue_recursive: null + io_service_time_recursive: null + io_wait_time_recursive: null + io_merged_recursive: null + io_time_recursive: null + sectors_recursive: null + + ContainerBlkioStatEntry: + description: | + Blkio stats entry. + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "BlkioStatEntry" + x-nullable: true + properties: + major: + type: "integer" + format: "uint64" + example: 254 + minor: + type: "integer" + format: "uint64" + example: 0 + op: + type: "string" + example: "read" + value: + type: "integer" + format: "uint64" + example: 7593984 + + ContainerCPUStats: + description: | + CPU related info of the container + type: "object" + x-go-name: "CPUStats" + x-nullable: true + properties: + cpu_usage: + $ref: "#/definitions/ContainerCPUUsage" + system_cpu_usage: + description: | + System Usage. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 5 + online_cpus: + description: | + Number of online CPUs. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint32" + x-nullable: true + example: 5 + throttling_data: + $ref: "#/definitions/ContainerThrottlingData" + + ContainerCPUUsage: + description: | + All CPU stats aggregated since container inception. + type: "object" + x-go-name: "CPUUsage" + x-nullable: true + properties: + total_usage: + description: | + Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows). + type: "integer" + format: "uint64" + example: 29912000 + percpu_usage: + description: | + Total CPU time (in nanoseconds) consumed per core (Linux). + + This field is Linux-specific when using cgroups v1. It is omitted + when using cgroups v2 and Windows containers. + type: "array" + x-nullable: true + items: + type: "integer" + format: "uint64" + example: 29912000 + + usage_in_kernelmode: + description: | + Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), + or time spent (in 100's of nanoseconds) by all container processes in + kernel mode (Windows). + + Not populated for Windows containers using Hyper-V isolation. + type: "integer" + format: "uint64" + example: 21994000 + usage_in_usermode: + description: | + Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), + or time spent (in 100's of nanoseconds) by all container processes in + kernel mode (Windows). + + Not populated for Windows containers using Hyper-V isolation. + type: "integer" + format: "uint64" + example: 7918000 + + ContainerPidsStats: + description: | + PidsStats contains Linux-specific stats of a container's process-IDs (PIDs). + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "PidsStats" + x-nullable: true + properties: + current: + description: | + Current is the number of PIDs in the cgroup. + type: "integer" + format: "uint64" + x-nullable: true + example: 5 + limit: + description: | + Limit is the hard limit on the number of pids in the cgroup. + A "Limit" of 0 means that there is no limit. + type: "integer" + format: "uint64" + x-nullable: true + example: "18446744073709551615" + + ContainerThrottlingData: + description: | + CPU throttling stats of the container. + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "ThrottlingData" + x-nullable: true + properties: + periods: + description: | + Number of periods with throttling active. + type: "integer" + format: "uint64" + example: 0 + throttled_periods: + description: | + Number of periods when the container hit its throttling limit. + type: "integer" + format: "uint64" + example: 0 + throttled_time: + description: | + Aggregated time (in nanoseconds) the container was throttled for. + type: "integer" + format: "uint64" + example: 0 + + ContainerMemoryStats: + description: | + Aggregates all memory stats since container inception on Linux. + Windows returns stats for commit and private working set only. + type: "object" + x-go-name: "MemoryStats" + properties: + usage: + description: | + Current `res_counter` usage for memory. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + max_usage: + description: | + Maximum usage ever recorded. + + This field is Linux-specific and only supported on cgroups v1. + It is omitted when using cgroups v2 and for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + stats: + description: | + All the stats exported via memory.stat. + + The fields in this object differ between cgroups v1 and v2. + On cgroups v1, fields such as `cache`, `rss`, `mapped_file` are available. + On cgroups v2, fields such as `file`, `anon`, `inactive_file` are available. + + This field is Linux-specific and omitted for Windows containers. + type: "object" + additionalProperties: + type: "integer" + format: "uint64" + x-nullable: true + example: + { + "active_anon": 1572864, + "active_file": 5115904, + "anon": 1572864, + "anon_thp": 0, + "file": 7626752, + "file_dirty": 0, + "file_mapped": 2723840, + "file_writeback": 0, + "inactive_anon": 0, + "inactive_file": 2510848, + "kernel_stack": 16384, + "pgactivate": 0, + "pgdeactivate": 0, + "pgfault": 2042, + "pglazyfree": 0, + "pglazyfreed": 0, + "pgmajfault": 45, + "pgrefill": 0, + "pgscan": 0, + "pgsteal": 0, + "shmem": 0, + "slab": 1180928, + "slab_reclaimable": 725576, + "slab_unreclaimable": 455352, + "sock": 0, + "thp_collapse_alloc": 0, + "thp_fault_alloc": 1, + "unevictable": 0, + "workingset_activate": 0, + "workingset_nodereclaim": 0, + "workingset_refault": 0 + } + failcnt: + description: | + Number of times memory usage hits limits. + + This field is Linux-specific and only supported on cgroups v1. + It is omitted when using cgroups v2 and for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + limit: + description: | + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 8217579520 + commitbytes: + description: | + Committed bytes. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + commitpeakbytes: + description: | + Peak committed bytes. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + privateworkingset: + description: | + Private working set. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + + ContainerNetworkStats: + description: | + Aggregates the network stats of one container + type: "object" + x-go-name: "NetworkStats" + x-nullable: true + properties: + rx_bytes: + description: | + Bytes received. Windows and Linux. + type: "integer" + format: "uint64" + example: 5338 + rx_packets: + description: | + Packets received. Windows and Linux. + type: "integer" + format: "uint64" + example: 36 + rx_errors: + description: | + Received errors. Not used on Windows. + + This field is Linux-specific and always zero for Windows containers. + type: "integer" + format: "uint64" + example: 0 + rx_dropped: + description: | + Incoming packets dropped. Windows and Linux. + type: "integer" + format: "uint64" + example: 0 + tx_bytes: + description: | + Bytes sent. Windows and Linux. + type: "integer" + format: "uint64" + example: 1200 + tx_packets: + description: | + Packets sent. Windows and Linux. + type: "integer" + format: "uint64" + example: 12 + tx_errors: + description: | + Sent errors. Not used on Windows. + + This field is Linux-specific and always zero for Windows containers. + type: "integer" + format: "uint64" + example: 0 + tx_dropped: + description: | + Outgoing packets dropped. Windows and Linux. + type: "integer" + format: "uint64" + example: 0 + endpoint_id: + description: | + Endpoint ID. Not used on Linux. + + This field is Windows-specific and omitted for Linux containers. + type: "string" + x-nullable: true + instance_id: + description: | + Instance ID. Not used on Linux. + + This field is Windows-specific and omitted for Linux containers. + type: "string" + x-nullable: true + + ContainerStorageStats: + description: | + StorageStats is the disk I/O stats for read/write on Windows. + + This type is Windows-specific and omitted for Linux containers. + type: "object" + x-go-name: "StorageStats" + x-nullable: true + properties: + read_count_normalized: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + read_size_bytes: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + write_count_normalized: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + write_size_bytes: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + + ContainerTopResponse: + type: "object" + x-go-name: "TopResponse" + title: "ContainerTopResponse" + description: |- + Container "top" response. + properties: + Titles: + description: "The ps column titles" + type: "array" + items: + type: "string" + example: + Titles: + - "UID" + - "PID" + - "PPID" + - "C" + - "STIME" + - "TTY" + - "TIME" + - "CMD" + Processes: + description: |- + Each process running in the container, where each process + is an array of values corresponding to the titles. + type: "array" + items: + type: "array" + items: + type: "string" + example: + Processes: + - + - "root" + - "13642" + - "882" + - "0" + - "17:03" + - "pts/0" + - "00:00:00" + - "/bin/bash" + - + - "root" + - "13735" + - "13642" + - "0" + - "17:06" + - "pts/0" + - "00:00:00" + - "sleep 10" + + ContainerWaitResponse: + description: "OK response to ContainerWait operation" + type: "object" + x-go-name: "WaitResponse" + title: "ContainerWaitResponse" + required: [StatusCode] + properties: + StatusCode: + description: "Exit code of the container" + type: "integer" + format: "int64" + x-nullable: false + Error: + $ref: "#/definitions/ContainerWaitExitError" + + ContainerWaitExitError: + description: "container waiting error, if any" + type: "object" + x-go-name: "WaitExitError" + properties: + Message: + description: "Details of an error" + type: "string" + + SystemVersion: + type: "object" + description: | + Response of Engine API: GET "/version" + properties: + Platform: + type: "object" + required: [Name] + properties: + Name: + type: "string" + Components: + type: "array" + description: | + Information about system components + items: + type: "object" + x-go-name: ComponentVersion + required: [Name, Version] + properties: + Name: + description: | + Name of the component + type: "string" + example: "Engine" + Version: + description: | + Version of the component + type: "string" + x-nullable: false + example: "27.0.1" + Details: + description: | + Key/value pairs of strings with additional information about the + component. These values are intended for informational purposes + only, and their content is not defined, and not part of the API + specification. + + These messages can be printed by the client as information to the user. + type: "object" + x-nullable: true + Version: + description: "The version of the daemon" + type: "string" + example: "27.0.1" + ApiVersion: + description: | + The default (and highest) API version that is supported by the daemon + type: "string" + example: "1.47" + MinAPIVersion: + description: | + The minimum API version that is supported by the daemon + type: "string" + example: "1.24" + GitCommit: + description: | + The Git commit of the source code that was used to build the daemon + type: "string" + example: "48a66213fe" + GoVersion: + description: | + The version Go used to compile the daemon, and the version of the Go + runtime in use. + type: "string" + example: "go1.22.7" + Os: + description: | + The operating system that the daemon is running on ("linux" or "windows") + type: "string" + example: "linux" + Arch: + description: | + Architecture of the daemon, as returned by the Go runtime (`GOARCH`). + + A full list of possible values can be found in the [Go documentation](https://go.dev/doc/install/source#environment). + type: "string" + example: "amd64" + KernelVersion: + description: | + The kernel version (`uname -r`) that the daemon is running on. + + This field is omitted when empty. + type: "string" + example: "6.8.0-31-generic" + Experimental: + description: | + Indicates if the daemon is started with experimental features enabled. + + This field is omitted when empty / false. + type: "boolean" + example: true + BuildTime: + description: | + The date and time that the daemon was compiled. + type: "string" + example: "2020-06-22T15:49:27.000000000+00:00" + + SystemInfo: + type: "object" + properties: + ID: + description: | + Unique identifier of the daemon. + + <p><br /></p> + + > **Note**: The format of the ID itself is not part of the API, and + > should not be considered stable. + type: "string" + example: "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS" + Containers: + description: "Total number of containers on the host." + type: "integer" + example: 14 + ContainersRunning: + description: | + Number of containers with status `"running"`. + type: "integer" + example: 3 + ContainersPaused: + description: | + Number of containers with status `"paused"`. + type: "integer" + example: 1 + ContainersStopped: + description: | + Number of containers with status `"stopped"`. + type: "integer" + example: 10 + Images: + description: | + Total number of images on the host. + + Both _tagged_ and _untagged_ (dangling) images are counted. + type: "integer" + example: 508 + Driver: + description: "Name of the storage driver in use." + type: "string" + example: "overlay2" + DriverStatus: + description: | + Information specific to the storage driver, provided as + "label" / "value" pairs. + + This information is provided by the storage driver, and formatted + in a way consistent with the output of `docker info` on the command + line. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["Backing Filesystem", "extfs"] + - ["Supports d_type", "true"] + - ["Native Overlay Diff", "true"] + DockerRootDir: + description: | + Root directory of persistent Docker state. + + Defaults to `/var/lib/docker` on Linux, and `C:\ProgramData\docker` + on Windows. + type: "string" + example: "/var/lib/docker" + Plugins: + $ref: "#/definitions/PluginsInfo" + MemoryLimit: + description: "Indicates if the host has memory limit support enabled." + type: "boolean" + example: true + SwapLimit: + description: "Indicates if the host has memory swap limit support enabled." + type: "boolean" + example: true + CpuCfsPeriod: + description: | + Indicates if CPU CFS(Completely Fair Scheduler) period is supported by + the host. + type: "boolean" + example: true + CpuCfsQuota: + description: | + Indicates if CPU CFS(Completely Fair Scheduler) quota is supported by + the host. + type: "boolean" + example: true + CPUShares: + description: | + Indicates if CPU Shares limiting is supported by the host. + type: "boolean" + example: true + CPUSet: + description: | + Indicates if CPUsets (cpuset.cpus, cpuset.mems) are supported by the host. + + See [cpuset(7)](https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt) + type: "boolean" + example: true + PidsLimit: + description: "Indicates if the host kernel has PID limit support enabled." + type: "boolean" + example: true + OomKillDisable: + description: "Indicates if OOM killer disable is supported on the host." + type: "boolean" + IPv4Forwarding: + description: "Indicates IPv4 forwarding is enabled." + type: "boolean" + example: true + Debug: + description: | + Indicates if the daemon is running in debug-mode / with debug-level + logging enabled. + type: "boolean" + example: true + NFd: + description: | + The total number of file Descriptors in use by the daemon process. + + This information is only returned if debug-mode is enabled. + type: "integer" + example: 64 + NGoroutines: + description: | + The number of goroutines that currently exist. + + This information is only returned if debug-mode is enabled. + type: "integer" + example: 174 + SystemTime: + description: | + Current system-time in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + format with nano-seconds. + type: "string" + example: "2017-08-08T20:28:29.06202363Z" + LoggingDriver: + description: | + The logging driver to use as a default for new containers. + type: "string" + CgroupDriver: + description: | + The driver to use for managing cgroups. + type: "string" + enum: ["cgroupfs", "systemd", "none"] + default: "cgroupfs" + example: "cgroupfs" + CgroupVersion: + description: | + The version of the cgroup. + type: "string" + enum: ["1", "2"] + default: "1" + example: "1" + NEventsListener: + description: "Number of event listeners subscribed." + type: "integer" + example: 30 + KernelVersion: + description: | + Kernel version of the host. + + On Linux, this information obtained from `uname`. On Windows this + information is queried from the <kbd>HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\</kbd> + registry value, for example _"10.0 14393 (14393.1198.amd64fre.rs1_release_sec.170427-1353)"_. + type: "string" + example: "6.8.0-31-generic" + OperatingSystem: + description: | + Name of the host's operating system, for example: "Ubuntu 24.04 LTS" + or "Windows Server 2016 Datacenter" + type: "string" + example: "Ubuntu 24.04 LTS" + OSVersion: + description: | + Version of the host's operating system + + <p><br /></p> + + > **Note**: The information returned in this field, including its + > very existence, and the formatting of values, should not be considered + > stable, and may change without notice. + type: "string" + example: "24.04" + OSType: + description: | + Generic type of the operating system of the host, as returned by the + Go runtime (`GOOS`). + + Currently returned values are "linux" and "windows". A full list of + possible values can be found in the [Go documentation](https://go.dev/doc/install/source#environment). + type: "string" + example: "linux" + Architecture: + description: | + Hardware architecture of the host, as returned by the operating system. + This is equivalent to the output of `uname -m` on Linux. + + Unlike `Arch` (from `/version`), this reports the machine's native + architecture, which can differ from the Go runtime architecture when + running a binary compiled for a different architecture (for example, + a 32-bit binary running on 64-bit hardware). + type: "string" + example: "x86_64" + NCPU: + description: | + The number of logical CPUs usable by the daemon. + + The number of available CPUs is checked by querying the operating + system when the daemon starts. Changes to operating system CPU + allocation after the daemon is started are not reflected. + type: "integer" + example: 4 + MemTotal: + description: | + Total amount of physical memory available on the host, in bytes. + type: "integer" + format: "int64" + example: 2095882240 + + IndexServerAddress: + description: | + Address / URL of the index server that is used for image search, + and as a default for user authentication for Docker Hub and Docker Cloud. + default: "https://index.docker.io/v1/" + type: "string" + example: "https://index.docker.io/v1/" + RegistryConfig: + $ref: "#/definitions/RegistryServiceConfig" + GenericResources: + $ref: "#/definitions/GenericResources" + HttpProxy: + description: | + HTTP-proxy configured for the daemon. This value is obtained from the + [`HTTP_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable. + Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL + are masked in the API response. + + Containers do not automatically inherit this configuration. + type: "string" + example: "http://xxxxx:xxxxx@proxy.corp.example.com:8080" + HttpsProxy: + description: | + HTTPS-proxy configured for the daemon. This value is obtained from the + [`HTTPS_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable. + Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL + are masked in the API response. + + Containers do not automatically inherit this configuration. + type: "string" + example: "https://xxxxx:xxxxx@proxy.corp.example.com:4443" + NoProxy: + description: | + Comma-separated list of domain extensions for which no proxy should be + used. This value is obtained from the [`NO_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) + environment variable. + + Containers do not automatically inherit this configuration. + type: "string" + example: "*.local, 169.254/16" + Name: + description: "Hostname of the host." + type: "string" + example: "node5.corp.example.com" + Labels: + description: | + User-defined labels (key/value metadata) as set on the daemon. + + <p><br /></p> + + > **Note**: When part of a Swarm, nodes can both have _daemon_ labels, + > set through the daemon configuration, and _node_ labels, set from a + > manager node in the Swarm. Node labels are not included in this + > field. Node labels can be retrieved using the `/nodes/(id)` endpoint + > on a manager node in the Swarm. + type: "array" + items: + type: "string" + example: ["storage=ssd", "production"] + ExperimentalBuild: + description: | + Indicates if experimental features are enabled on the daemon. + type: "boolean" + example: true + ServerVersion: + description: | + Version string of the daemon. + type: "string" + example: "27.0.1" + Runtimes: + description: | + List of [OCI compliant](https://github.com/opencontainers/runtime-spec) + runtimes configured on the daemon. Keys hold the "name" used to + reference the runtime. + + The Docker daemon relies on an OCI compliant runtime (invoked via the + `containerd` daemon) as its interface to the Linux kernel namespaces, + cgroups, and SELinux. + + The default runtime is `runc`, and automatically configured. Additional + runtimes can be configured by the user and will be listed here. + type: "object" + additionalProperties: + $ref: "#/definitions/Runtime" + default: + runc: + path: "runc" + example: + runc: + path: "runc" + runc-master: + path: "/go/bin/runc" + custom: + path: "/usr/local/bin/my-oci-runtime" + runtimeArgs: ["--debug", "--systemd-cgroup=false"] + DefaultRuntime: + description: | + Name of the default OCI runtime that is used when starting containers. + + The default can be overridden per-container at create time. + type: "string" + default: "runc" + example: "runc" + Swarm: + $ref: "#/definitions/SwarmInfo" + LiveRestoreEnabled: + description: | + Indicates if live restore is enabled. + + If enabled, containers are kept running when the daemon is shutdown + or upon daemon start if running containers are detected. + type: "boolean" + default: false + example: false + Isolation: + description: | + Represents the isolation technology to use as a default for containers. + The supported values are platform-specific. + + If no isolation value is specified on daemon start, on Windows client, + the default is `hyperv`, and on Windows server, the default is `process`. + + This option is currently not used on other platforms. + default: "default" + type: "string" + enum: + - "default" + - "hyperv" + - "process" + - "" + InitBinary: + description: | + Name and, optional, path of the `docker-init` binary. + + If the path is omitted, the daemon searches the host's `$PATH` for the + binary and uses the first result. + type: "string" + example: "docker-init" + ContainerdCommit: + $ref: "#/definitions/Commit" + RuncCommit: + $ref: "#/definitions/Commit" + InitCommit: + $ref: "#/definitions/Commit" + SecurityOptions: + description: | + List of security features that are enabled on the daemon, such as + apparmor, seccomp, SELinux, user-namespaces (userns), rootless and + no-new-privileges. + + Additional configuration options for each security feature may + be present, and are included as a comma-separated list of key/value + pairs. + type: "array" + items: + type: "string" + example: + - "name=apparmor" + - "name=seccomp,profile=default" + - "name=selinux" + - "name=userns" + - "name=rootless" + ProductLicense: + description: | + Reports a summary of the product license on the daemon. + + If a commercial license has been applied to the daemon, information + such as number of nodes, and expiration are included. + type: "string" + example: "Community Engine" + DefaultAddressPools: + description: | + List of custom default address pools for local networks, which can be + specified in the daemon.json file or dockerd option. + + Example: a Base "10.10.0.0/16" with Size 24 will define the set of 256 + 10.10.[0-255].0/24 address pools. + type: "array" + items: + type: "object" + properties: + Base: + description: "The network address in CIDR format" + type: "string" + example: "10.10.0.0/16" + Size: + description: "The network pool size" + type: "integer" + example: "24" + FirewallBackend: + $ref: "#/definitions/FirewallInfo" + DiscoveredDevices: + description: | + List of devices discovered by device drivers. + + Each device includes information about its source driver, kind, name, + and additional driver-specific attributes. + type: "array" + items: + $ref: "#/definitions/DeviceInfo" + NRI: + $ref: "#/definitions/NRIInfo" + Warnings: + description: | + List of warnings / informational messages about missing features, or + issues related to the daemon configuration. + + These messages can be printed by the client as information to the user. + type: "array" + items: + type: "string" + example: + - "WARNING: No memory limit support" + CDISpecDirs: + description: | + List of directories where (Container Device Interface) CDI + specifications are located. + + These specifications define vendor-specific modifications to an OCI + runtime specification for a container being created. + + An empty list indicates that CDI device injection is disabled. + + Note that since using CDI device injection requires the daemon to have + experimental enabled. For non-experimental daemons an empty list will + always be returned. + type: "array" + items: + type: "string" + example: + - "/etc/cdi" + - "/var/run/cdi" + Containerd: + $ref: "#/definitions/ContainerdInfo" + + ContainerdInfo: + description: | + Information for connecting to the containerd instance that is used by the daemon. + This is included for debugging purposes only. + type: "object" + x-nullable: true + properties: + Address: + description: "The address of the containerd socket." + type: "string" + example: "/run/containerd/containerd.sock" + Namespaces: + description: | + The namespaces that the daemon uses for running containers and + plugins in containerd. These namespaces can be configured in the + daemon configuration, and are considered to be used exclusively + by the daemon, Tampering with the containerd instance may cause + unexpected behavior. + + As these namespaces are considered to be exclusively accessed + by the daemon, it is not recommended to change these values, + or to change them to a value that is used by other systems, + such as cri-containerd. + type: "object" + properties: + Containers: + description: | + The default containerd namespace used for containers managed + by the daemon. + + The default namespace for containers is "moby", but will be + suffixed with the `<uid>.<gid>` of the remapped `root` if + user-namespaces are enabled and the containerd image-store + is used. + type: "string" + default: "moby" + example: "moby" + Plugins: + description: | + The default containerd namespace used for plugins managed by + the daemon. + + The default namespace for plugins is "plugins.moby", but will be + suffixed with the `<uid>.<gid>` of the remapped `root` if + user-namespaces are enabled and the containerd image-store + is used. + type: "string" + default: "plugins.moby" + example: "plugins.moby" + + FirewallInfo: + description: | + Information about the daemon's firewalling configuration. + + This field is currently only used on Linux, and omitted on other platforms. + type: "object" + x-nullable: true + properties: + Driver: + description: | + The name of the firewall backend driver. + type: "string" + example: "nftables" + Info: + description: | + Information about the firewall backend, provided as + "label" / "value" pairs. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["ReloadedAt", "2025-01-01T00:00:00Z"] + + # PluginsInfo is a temp struct holding Plugins name + # registered with docker daemon. It is used by Info struct + PluginsInfo: + description: | + Available plugins per type. + + <p><br /></p> + + > **Note**: Only unmanaged (V1) plugins are included in this list. + > V1 plugins are "lazily" loaded, and are not returned in this list + > if there is no resource using the plugin. + type: "object" + properties: + Volume: + description: "Names of available volume-drivers, and network-driver plugins." + type: "array" + items: + type: "string" + example: ["local"] + Network: + description: "Names of available network-drivers, and network-driver plugins." + type: "array" + items: + type: "string" + example: ["bridge", "host", "ipvlan", "macvlan", "null", "overlay"] + Authorization: + description: "Names of available authorization plugins." + type: "array" + items: + type: "string" + example: ["img-authz-plugin", "hbm"] + Log: + description: "Names of available logging-drivers, and logging-driver plugins." + type: "array" + items: + type: "string" + example: ["awslogs", "fluentd", "gcplogs", "gelf", "journald", "json-file", "splunk", "syslog"] + + + RegistryServiceConfig: + description: | + RegistryServiceConfig stores daemon registry services configuration. + type: "object" + x-nullable: true + properties: + InsecureRegistryCIDRs: + description: | + List of IP ranges of insecure registries, using the CIDR syntax + ([RFC 4632](https://tools.ietf.org/html/4632)). Insecure registries + accept un-encrypted (HTTP) and/or untrusted (HTTPS with certificates + from unknown CAs) communication. + + By default, local registries (`::1/128` and `127.0.0.0/8`) are configured as + insecure. All other registries are secure. Communicating with an + insecure registry is not possible if the daemon assumes that registry + is secure. + + This configuration override this behavior, insecure communication with + registries whose resolved IP address is within the subnet described by + the CIDR syntax. + + Registries can also be marked insecure by hostname. Those registries + are listed under `IndexConfigs` and have their `Secure` field set to + `false`. + + > **Warning**: Using this option can be useful when running a local + > registry, but introduces security vulnerabilities. This option + > should therefore ONLY be used for testing purposes. For increased + > security, users should add their CA to their system's list of trusted + > CAs instead of enabling this option. + type: "array" + items: + type: "string" + example: ["::1/128", "127.0.0.0/8"] + IndexConfigs: + type: "object" + additionalProperties: + $ref: "#/definitions/IndexInfo" + example: + "127.0.0.1:5000": + "Name": "127.0.0.1:5000" + "Mirrors": [] + "Secure": false + "Official": false + "[2001:db8:a0b:12f0::1]:80": + "Name": "[2001:db8:a0b:12f0::1]:80" + "Mirrors": [] + "Secure": false + "Official": false + "docker.io": + Name: "docker.io" + Mirrors: ["https://hub-mirror.corp.example.com:5000/"] + Secure: true + Official: true + "registry.internal.corp.example.com:3000": + Name: "registry.internal.corp.example.com:3000" + Mirrors: [] + Secure: false + Official: false + Mirrors: + description: | + List of registry URLs that act as a mirror for the official + (`docker.io`) registry. + + type: "array" + items: + type: "string" + example: + - "https://hub-mirror.corp.example.com:5000/" + - "https://[2001:db8:a0b:12f0::1]/" + + IndexInfo: + description: + IndexInfo contains information about a registry. + type: "object" + x-nullable: true + properties: + Name: + description: | + Name of the registry, such as "docker.io". + type: "string" + example: "docker.io" + Mirrors: + description: | + List of mirrors, expressed as URIs. + type: "array" + items: + type: "string" + example: + - "https://hub-mirror.corp.example.com:5000/" + - "https://registry-2.docker.io/" + - "https://registry-3.docker.io/" + Secure: + description: | + Indicates if the registry is part of the list of insecure + registries. + + If `false`, the registry is insecure. Insecure registries accept + un-encrypted (HTTP) and/or untrusted (HTTPS with certificates from + unknown CAs) communication. + + > **Warning**: Insecure registries can be useful when running a local + > registry. However, because its use creates security vulnerabilities + > it should ONLY be enabled for testing purposes. For increased + > security, users should add their CA to their system's list of + > trusted CAs instead of enabling this option. + type: "boolean" + example: true + Official: + description: | + Indicates whether this is an official registry (i.e., Docker Hub / docker.io) + type: "boolean" + example: true + + Runtime: + description: | + Runtime describes an [OCI compliant](https://github.com/opencontainers/runtime-spec) + runtime. + + The runtime is invoked by the daemon via the `containerd` daemon. OCI + runtimes act as an interface to the Linux kernel namespaces, cgroups, + and SELinux. + type: "object" + properties: + path: + description: | + Name and, optional, path, of the OCI executable binary. + + If the path is omitted, the daemon searches the host's `$PATH` for the + binary and uses the first result. + type: "string" + example: "/usr/local/bin/my-oci-runtime" + runtimeArgs: + description: | + List of command-line arguments to pass to the runtime when invoked. + type: "array" + x-nullable: true + items: + type: "string" + example: ["--debug", "--systemd-cgroup=false"] + status: + description: | + Information specific to the runtime. + + While this API specification does not define data provided by runtimes, + the following well-known properties may be provided by runtimes: + + `org.opencontainers.runtime-spec.features`: features structure as defined + in the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec/blob/main/features.md), + in a JSON string representation. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + "org.opencontainers.runtime-spec.features": "{\"ociVersionMin\":\"1.0.0\",\"ociVersionMax\":\"1.1.0\",\"...\":\"...\"}" + + Commit: + description: | + Commit holds the Git-commit (SHA1) that a binary was built from, as + reported in the version-string of external tools, such as `containerd`, + or `runC`. + type: "object" + properties: + ID: + description: "Actual commit ID of external tool." + type: "string" + example: "cfb82a876ecc11b5ca0977d1733adbe58599088a" + + SwarmInfo: + description: | + Represents generic information about swarm. + type: "object" + properties: + NodeID: + description: "Unique identifier of for this node in the swarm." + type: "string" + default: "" + example: "k67qz4598weg5unwwffg6z1m1" + NodeAddr: + description: | + IP address at which this node can be reached by other nodes in the + swarm. + type: "string" + default: "" + example: "10.0.0.46" + LocalNodeState: + $ref: "#/definitions/LocalNodeState" + ControlAvailable: + type: "boolean" + default: false + example: true + Error: + type: "string" + default: "" + RemoteManagers: + description: | + List of ID's and addresses of other managers in the swarm. + type: "array" + x-nullable: true + items: + $ref: "#/definitions/PeerNode" + example: + - NodeID: "71izy0goik036k48jg985xnds" + Addr: "10.0.0.158:2377" + - NodeID: "79y6h1o4gv8n120drcprv5nmc" + Addr: "10.0.0.159:2377" + - NodeID: "k67qz4598weg5unwwffg6z1m1" + Addr: "10.0.0.46:2377" + Nodes: + description: "Total number of nodes in the swarm." + type: "integer" + x-nullable: true + example: 4 + Managers: + description: "Total number of managers in the swarm." + type: "integer" + x-nullable: true + example: 3 + Cluster: + $ref: "#/definitions/ClusterInfo" + + LocalNodeState: + description: "Current local status of this node." + type: "string" + default: "" + enum: + - "" + - "inactive" + - "pending" + - "active" + - "error" + - "locked" + example: "active" + + PeerNode: + description: "Represents a peer-node in the swarm" + type: "object" + properties: + NodeID: + description: "Unique identifier of for this node in the swarm." + type: "string" + Addr: + description: | + IP address and ports at which this node can be reached. + type: "string" + + NetworkAttachmentConfig: + description: | + Specifies how a service should be attached to a particular network. + type: "object" + properties: + Target: + description: | + The target network for attachment. Must be a network name or ID. + type: "string" + Aliases: + description: | + Discoverable alternate names for the service on this network. + type: "array" + items: + type: "string" + DriverOpts: + description: | + Driver attachment options for the network target. + type: "object" + additionalProperties: + type: "string" + + EventActor: + description: | + Actor describes something that generates events, like a container, network, + or a volume. + type: "object" + properties: + ID: + description: "The ID of the object emitting the event" + type: "string" + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + Attributes: + description: | + Various key/value attributes of the object, depending on its type. + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-label-value" + image: "alpine:latest" + name: "my-container" + + EventMessage: + description: | + EventMessage represents the information an event contains. + type: "object" + title: "SystemEventsResponse" + properties: + Type: + description: "The type of object emitting the event" + type: "string" + enum: ["builder", "config", "container", "daemon", "image", "network", "node", "plugin", "secret", "service", "volume"] + example: "container" + Action: + description: "The type of event" + type: "string" + example: "create" + Actor: + $ref: "#/definitions/EventActor" + scope: + description: | + Scope of the event. Engine events are `local` scope. Cluster (Swarm) + events are `swarm` scope. + type: "string" + enum: ["local", "swarm"] + time: + description: "Timestamp of event" + type: "integer" + format: "int64" + example: 1629574695 + timeNano: + description: "Timestamp of event, with nanosecond accuracy" + type: "integer" + format: "int64" + example: 1629574695515050031 + + OCIDescriptor: + type: "object" + x-go-name: Descriptor + description: | + A descriptor struct containing digest, media type, and size, as defined in + the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md). + properties: + mediaType: + description: | + The media type of the object this schema refers to. + type: "string" + example: "application/vnd.oci.image.manifest.v1+json" + digest: + description: | + The digest of the targeted content. + type: "string" + example: "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96" + size: + description: | + The size in bytes of the blob. + type: "integer" + format: "int64" + example: 424 + urls: + description: |- + List of URLs from which this object MAY be downloaded. + type: "array" + items: + type: "string" + format: "uri" + x-nullable: true + annotations: + description: |- + Arbitrary metadata relating to the targeted content. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + "com.docker.official-images.bashbrew.arch": "amd64" + "org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8" + "org.opencontainers.image.base.name": "scratch" + "org.opencontainers.image.created": "2025-01-27T00:00:00Z" + "org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79" + "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base" + "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu" + "org.opencontainers.image.version": "24.04" + data: + type: string + x-nullable: true + description: |- + Data is an embedding of the targeted content. This is encoded as a base64 + string when marshalled to JSON (automatically, by encoding/json). If + present, Data can be used directly to avoid fetching the targeted content. + example: null + platform: + $ref: "#/definitions/OCIPlatform" + artifactType: + description: |- + ArtifactType is the IANA media type of this artifact. + type: "string" + x-nullable: true + example: null + + OCIPlatform: + type: "object" + x-go-name: Platform + x-nullable: true + description: | + Describes the platform which the image in the manifest runs on, as defined + in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). + properties: + architecture: + description: | + The CPU architecture, for example `amd64` or `ppc64`. + type: "string" + example: "arm" + os: + description: | + The operating system, for example `linux` or `windows`. + type: "string" + example: "windows" + os.version: + description: | + Optional field specifying the operating system version, for example on + Windows `10.0.19041.1165`. + type: "string" + example: "10.0.19041.1165" + os.features: + description: | + Optional field specifying an array of strings, each listing a required + OS feature (for example on Windows `win32k`). + type: "array" + items: + type: "string" + example: + - "win32k" + variant: + description: | + Optional field specifying a variant of the CPU, for example `v7` to + specify ARMv7 when architecture is `arm`. + type: "string" + example: "v7" + + DistributionInspect: + type: "object" + x-go-name: DistributionInspect + title: "DistributionInspectResponse" + required: [Descriptor, Platforms] + description: | + Describes the result obtained from contacting the registry to retrieve + image metadata. + properties: + Descriptor: + $ref: "#/definitions/OCIDescriptor" + Platforms: + type: "array" + description: | + An array containing all platforms supported by the image. + items: + $ref: "#/definitions/OCIPlatform" + + ClusterVolume: + type: "object" + description: | + Options and information specific to, and only present on, Swarm CSI + cluster volumes. + properties: + ID: + type: "string" + description: | + The Swarm ID of this volume. Because cluster volumes are Swarm + objects, they have an ID, unlike non-cluster volumes. This ID can + be used to refer to the Volume instead of the name. + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ClusterVolumeSpec" + Info: + type: "object" + description: | + Information about the global status of the volume. + properties: + CapacityBytes: + type: "integer" + format: "int64" + description: | + The capacity of the volume in bytes. A value of 0 indicates that + the capacity is unknown. + VolumeContext: + type: "object" + description: | + A map of strings to strings returned from the storage plugin when + the volume is created. + additionalProperties: + type: "string" + VolumeID: + type: "string" + description: | + The ID of the volume as returned by the CSI storage plugin. This + is distinct from the volume's ID as provided by Docker. This ID + is never used by the user when communicating with Docker to refer + to this volume. If the ID is blank, then the Volume has not been + successfully created in the plugin yet. + AccessibleTopology: + type: "array" + description: | + The topology this volume is actually accessible from. + items: + $ref: "#/definitions/Topology" + PublishStatus: + type: "array" + description: | + The status of the volume as it pertains to its publishing and use on + specific nodes + items: + type: "object" + properties: + NodeID: + type: "string" + description: | + The ID of the Swarm node the volume is published on. + State: + type: "string" + description: | + The published state of the volume. + * `pending-publish` The volume should be published to this node, but the call to the controller plugin to do so has not yet been successfully completed. + * `published` The volume is published successfully to the node. + * `pending-node-unpublish` The volume should be unpublished from the node, and the manager is awaiting confirmation from the worker that it has done so. + * `pending-controller-unpublish` The volume is successfully unpublished from the node, but has not yet been successfully unpublished on the controller. + enum: + - "pending-publish" + - "published" + - "pending-node-unpublish" + - "pending-controller-unpublish" + PublishContext: + type: "object" + description: | + A map of strings to strings returned by the CSI controller + plugin when a volume is published. + additionalProperties: + type: "string" + + ClusterVolumeSpec: + type: "object" + description: | + Cluster-specific options used to create the volume. + properties: + Group: + type: "string" + description: | + Group defines the volume group of this volume. Volumes belonging to + the same group can be referred to by group name when creating + Services. Referring to a volume by group instructs Swarm to treat + volumes in that group interchangeably for the purpose of scheduling. + Volumes with an empty string for a group technically all belong to + the same, emptystring group. + AccessMode: + type: "object" + description: | + Defines how the volume is used by tasks. + properties: + Scope: + type: "string" + description: | + The set of nodes this volume can be used on at one time. + - `single` The volume may only be scheduled to one node at a time. + - `multi` the volume may be scheduled to any supported number of nodes at a time. + default: "single" + enum: ["single", "multi"] + x-nullable: false + Sharing: + type: "string" + description: | + The number and way that different tasks can use this volume + at one time. + - `none` The volume may only be used by one task at a time. + - `readonly` The volume may be used by any number of tasks, but they all must mount the volume as readonly + - `onewriter` The volume may be used by any number of tasks, but only one may mount it as read/write. + - `all` The volume may have any number of readers and writers. + default: "none" + enum: ["none", "readonly", "onewriter", "all"] + x-nullable: false + MountVolume: + type: "object" + description: | + Options for using this volume as a Mount-type volume. + + Either MountVolume or BlockVolume, but not both, must be + present. + properties: + FsType: + type: "string" + description: | + Specifies the filesystem type for the mount volume. + Optional. + MountFlags: + type: "array" + description: | + Flags to pass when mounting the volume. Optional. + items: + type: "string" + BlockVolume: + type: "object" + description: | + Options for using this volume as a Block-type volume. + Intentionally empty. + Secrets: + type: "array" + description: | + Swarm Secrets that are passed to the CSI storage plugin when + operating on this volume. + items: + type: "object" + description: | + One cluster volume secret entry. Defines a key-value pair that + is passed to the plugin. + properties: + Key: + type: "string" + description: | + Key is the name of the key of the key-value pair passed to + the plugin. + Secret: + type: "string" + description: | + Secret is the swarm Secret object from which to read data. + This can be a Secret name or ID. The Secret data is + retrieved by swarm and used as the value of the key-value + pair passed to the plugin. + AccessibilityRequirements: + type: "object" + description: | + Requirements for the accessible topology of the volume. These + fields are optional. For an in-depth description of what these + fields mean, see the CSI specification. + properties: + Requisite: + type: "array" + description: | + A list of required topologies, at least one of which the + volume must be accessible from. + items: + $ref: "#/definitions/Topology" + Preferred: + type: "array" + description: | + A list of topologies that the volume should attempt to be + provisioned in. + items: + $ref: "#/definitions/Topology" + CapacityRange: + type: "object" + description: | + The desired capacity that the volume should be created with. If + empty, the plugin will decide the capacity. + properties: + RequiredBytes: + type: "integer" + format: "int64" + description: | + The volume must be at least this big. The value of 0 + indicates an unspecified minimum + LimitBytes: + type: "integer" + format: "int64" + description: | + The volume must not be bigger than this. The value of 0 + indicates an unspecified maximum. + Availability: + type: "string" + description: | + The availability of the volume for use in tasks. + - `active` The volume is fully available for scheduling on the cluster + - `pause` No new workloads should use the volume, but existing workloads are not stopped. + - `drain` All workloads using this volume should be stopped and rescheduled, and no new ones should be started. + default: "active" + x-nullable: false + enum: + - "active" + - "pause" + - "drain" + + Topology: + description: | + A map of topological domains to topological segments. For in depth + details, see documentation for the Topology object in the CSI + specification. + type: "object" + properties: + Segments: + type: "object" + additionalProperties: + type: "string" + + AttestationStatement: + x-go-name: "AttestationStatement" + description: | + AttestationStatement is a single in-toto statement attached to an image. + type: "object" + required: ["Descriptor", "PredicateType"] + properties: + Descriptor: + $ref: "#/definitions/OCIDescriptor" + PredicateType: + description: The in-toto predicate type URI of this statement. + type: "string" + example: "https://slsa.dev/provenance/v0.2" + Statement: + description: | + The verbatim in-toto statement JSON. Only included when the caller + opts in via the `statement=true` query parameter; otherwise absent. + type: "object" + x-nullable: true + ImageManifestSummary: + x-go-name: "ManifestSummary" + description: | + ImageManifestSummary represents a summary of an image manifest. + type: "object" + required: ["ID", "Descriptor", "Available", "Size", "Kind"] + properties: + ID: + description: | + ID is the content-addressable ID of an image and is the same as the + digest of the image manifest. + type: "string" + example: "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f" + Descriptor: + $ref: "#/definitions/OCIDescriptor" + Available: + description: Indicates whether all the child content (image config, layers) is fully available locally. + type: "boolean" + example: true + Size: + type: "object" + x-nullable: false + required: ["Content", "Total"] + properties: + Total: + type: "integer" + format: "int64" + example: 8213251 + description: | + Total is the total size (in bytes) of all the locally present + data (both distributable and non-distributable) that's related to + this manifest and its children. + This equal to the sum of [Content] size AND all the sizes in the + [Size] struct present in the Kind-specific data struct. + For example, for an image kind (Kind == "image") + this would include the size of the image content and unpacked + image snapshots ([Size.Content] + [ImageData.Size.Unpacked]). + Content: + description: | + Content is the size (in bytes) of all the locally present + content in the content store (e.g. image config, layers) + referenced by this manifest and its children. + This only includes blobs in the content store. + type: "integer" + format: "int64" + example: 3987495 + Kind: + type: "string" + example: "image" + enum: + - "image" + - "attestation" + - "unknown" + description: | + The kind of the manifest. + + kind | description + -------------|----------------------------------------------------------- + image | Image manifest that can be used to start a container. + attestation | Attestation manifest produced by the Buildkit builder for a specific image manifest. + ImageData: + description: | + The image data for the image manifest. + This field is only populated when Kind is "image". + type: "object" + x-nullable: true + x-omitempty: true + required: ["Platform", "Containers", "Size"] + properties: + Platform: + $ref: "#/definitions/OCIPlatform" + description: | + OCI platform of the image. This will be the platform specified in the + manifest descriptor from the index/manifest list. + If it's not available, it will be obtained from the image config. + Identity: + description: | + Identity holds information about the identity and origin of this image. + For image list responses, this can duplicate Build/Pull fields across + image manifests, because those parts are image-level metadata. + x-nullable: true + $ref: "#/definitions/Identity" + Containers: + description: | + The IDs of the containers that are using this image. + type: "array" + items: + type: "string" + example: ["ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430", "abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"] + Size: + type: "object" + x-nullable: false + required: ["Unpacked"] + properties: + Unpacked: + type: "integer" + format: "int64" + example: 3987495 + description: | + Unpacked is the size (in bytes) of the locally unpacked + (uncompressed) image content that's directly usable by the containers + running this image. + It's independent of the distributable content - e.g. + the image might still have an unpacked data that's still used by + some container even when the distributable/compressed content is + already gone. + AttestationData: + description: | + The image data for the attestation manifest. + This field is only populated when Kind is "attestation". + type: "object" + x-nullable: true + x-omitempty: true + required: ["For"] + properties: + For: + description: | + The digest of the image manifest that this attestation is for. + type: "string" + example: "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f" + +paths: + /containers/json: + get: + summary: "List containers" + description: | + Returns a list of containers. For details on the format, see the + [inspect endpoint](#operation/ContainerInspect). + + Note that it uses a different, smaller representation of a container + than inspecting a single container. For example, the list of linked + containers is not propagated . + operationId: "ContainerList" + produces: + - "application/json" + parameters: + - name: "all" + in: "query" + description: | + Return all containers. By default, only running containers are shown. + type: "boolean" + default: false + - name: "limit" + in: "query" + description: | + Return this number of most recently created containers, including + non-running ones. + type: "integer" + - name: "size" + in: "query" + description: | + Return the size of container as fields `SizeRw` and `SizeRootFs`. + type: "boolean" + default: false + - name: "filters" + in: "query" + description: | + Filters to process on the container list, encoded as JSON (a + `map[string][]string`). For example, `{"status": ["paused"]}` will + only return paused containers. + + Available filters: + + - `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`) + - `before`=(`<container id>` or `<container name>`) + - `expose`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) + - `exited=<int>` containers with exit code of `<int>` + - `health`=(`starting`|`healthy`|`unhealthy`|`none`) + - `id=<ID>` a container's ID + - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only) + - `is-task=`(`true`|`false`) + - `label=key` or `label="key=value"` of a container label + - `name=<name>` a container's name + - `network`=(`<network id>` or `<network name>`) + - `publish`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) + - `since`=(`<container id>` or `<container name>`) + - `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`) + - `volume`=(`<volume name>` or `<mount point destination>`) + type: "string" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/ContainerSummary" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /containers/create: + post: + summary: "Create a container" + operationId: "ContainerCreate" + consumes: + - "application/json" + - "application/octet-stream" + produces: + - "application/json" + parameters: + - name: "name" + in: "query" + description: | + Assign the specified name to the container. Must match + `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`. + type: "string" + pattern: "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$" + - name: "platform" + in: "query" + description: | + Platform in the format `os[/arch[/variant]]` used for image lookup. + + When specified, the daemon checks if the requested image is present + in the local image cache with the given OS and Architecture, and + otherwise returns a `404` status. + + If the option is not set, the host's native OS and Architecture are + used to look up the image in the image cache. However, if no platform + is passed and the given image does exist in the local image cache, + but its OS or architecture does not match, the container is created + with the available image, and a warning is added to the `Warnings` + field in the response, for example; + + WARNING: The requested image's platform (linux/arm64/v8) does not + match the detected host platform (linux/amd64) and no + specific platform was requested + + type: "string" + default: "" + - name: "body" + in: "body" + description: "Container to create" + schema: + allOf: + - $ref: "#/definitions/ContainerConfig" + - type: "object" + properties: + HostConfig: + $ref: "#/definitions/HostConfig" + NetworkingConfig: + $ref: "#/definitions/NetworkingConfig" + example: + Hostname: "" + Domainname: "" + User: "" + AttachStdin: false + AttachStdout: true + AttachStderr: true + Tty: false + OpenStdin: false + StdinOnce: false + Env: + - "FOO=bar" + - "BAZ=quux" + Cmd: + - "date" + Entrypoint: "" + Image: "ubuntu" + Labels: + com.example.vendor: "Acme" + com.example.license: "GPL" + com.example.version: "1.0" + Volumes: + /volumes/data: {} + WorkingDir: "" + NetworkDisabled: false + ExposedPorts: + 22/tcp: {} + StopSignal: "SIGTERM" + StopTimeout: 10 + HostConfig: + Binds: + - "/tmp:/tmp" + Links: + - "redis3:redis" + Memory: 0 + MemorySwap: 0 + MemoryReservation: 0 + NanoCpus: 500000 + CpuPercent: 80 + CpuShares: 512 + CpuPeriod: 100000 + CpuRealtimePeriod: 1000000 + CpuRealtimeRuntime: 10000 + CpuQuota: 50000 + CpusetCpus: "0,1" + CpusetMems: "0,1" + MaximumIOps: 0 + MaximumIOBps: 0 + BlkioWeight: 300 + BlkioWeightDevice: + - {} + BlkioDeviceReadBps: + - {} + BlkioDeviceReadIOps: + - {} + BlkioDeviceWriteBps: + - {} + BlkioDeviceWriteIOps: + - {} + DeviceRequests: + - Driver: "nvidia" + Count: -1 + DeviceIDs": ["0", "1", "GPU-fef8089b-4820-abfc-e83e-94318197576e"] + Capabilities: [["gpu", "nvidia", "compute"]] + Options: + property1: "string" + property2: "string" + MemorySwappiness: 60 + OomKillDisable: false + OomScoreAdj: 500 + PidMode: "" + PidsLimit: 0 + PortBindings: + 22/tcp: + - HostPort: "11022" + PublishAllPorts: false + Privileged: false + ReadonlyRootfs: false + Dns: + - "8.8.8.8" + DnsOptions: + - "" + DnsSearch: + - "" + VolumesFrom: + - "parent" + - "other:ro" + CapAdd: + - "NET_ADMIN" + CapDrop: + - "MKNOD" + GroupAdd: + - "newgroup" + RestartPolicy: + Name: "" + MaximumRetryCount: 0 + AutoRemove: true + NetworkMode: "bridge" + Devices: [] + Ulimits: + - {} + LogConfig: + Type: "json-file" + Config: {} + SecurityOpt: [] + StorageOpt: {} + CgroupParent: "" + VolumeDriver: "" + ShmSize: 67108864 + NetworkingConfig: + EndpointsConfig: + isolated_nw: + IPAMConfig: + IPv4Address: "172.20.30.33" + IPv6Address: "2001:db8:abcd::3033" + LinkLocalIPs: + - "169.254.34.68" + - "fe80::3468" + Links: + - "container_1" + - "container_2" + Aliases: + - "server_x" + - "server_y" + database_nw: {} + + required: true + responses: + "201": + description: "Container created successfully" + schema: + $ref: "#/definitions/ContainerCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such image" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: c2ada9df5af8" + "409": + description: "conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /containers/{id}/json: + get: + summary: "Inspect a container" + description: "Return low-level information about a container." + operationId: "ContainerInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerInspectResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "size" + in: "query" + type: "boolean" + default: false + description: "Return the size of container as fields `SizeRw` and `SizeRootFs`" + tags: ["Container"] + /containers/{id}/top: + get: + summary: "List processes running inside a container" + description: | + On Unix systems, this is done by running the `ps` command. This endpoint + is not supported on Windows. + operationId: "ContainerTop" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerTopResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "ps_args" + in: "query" + description: "The arguments to pass to `ps`. For example, `aux`" + type: "string" + default: "-ef" + tags: ["Container"] + /containers/{id}/logs: + get: + summary: "Get container logs" + description: | + Get `stdout` and `stderr` logs from a container. + + Note: This endpoint works only for containers with the `json-file` or + `journald` logging driver. + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + operationId: "ContainerLogs" + responses: + "200": + description: | + logs returned as a stream in response body. + For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). + Note that unlike the attach endpoint, the logs endpoint does not + upgrade the connection and does not set Content-Type. + schema: + type: "string" + format: "binary" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "until" + in: "query" + description: "Only return logs before this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Container"] + /containers/{id}/changes: + get: + summary: "Get changes on a container’s filesystem" + description: | + Returns which files in a container's filesystem have been added, deleted, + or modified. The `Kind` of modification can be one of: + + - `0`: Modified ("C") + - `1`: Added ("A") + - `2`: Deleted ("D") + operationId: "ContainerChanges" + produces: ["application/json"] + responses: + "200": + description: "The list of changes" + schema: + type: "array" + items: + $ref: "#/definitions/FilesystemChange" + examples: + application/json: + - Path: "/dev" + Kind: 0 + - Path: "/dev/kmsg" + Kind: 1 + - Path: "/test" + Kind: 1 + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + tags: ["Container"] + /containers/{id}/export: + get: + summary: "Export a container" + description: "Export the contents of a container as a tarball." + operationId: "ContainerExport" + produces: + - "application/octet-stream" + responses: + "200": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + tags: ["Container"] + /containers/{id}/stats: + get: + summary: "Get container stats based on resource usage" + description: | + This endpoint returns a live stream of a container’s resource usage + statistics. + + The `precpu_stats` is the CPU statistic of the *previous* read, and is + used to calculate the CPU usage percentage. It is not an exact copy + of the `cpu_stats` field. + + If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is + nil then for compatibility with older daemons the length of the + corresponding `cpu_usage.percpu_usage` array should be used. + + On a cgroup v2 host, the following fields are not set + * `blkio_stats`: all fields other than `io_service_bytes_recursive` + * `cpu_stats`: `cpu_usage.percpu_usage` + * `memory_stats`: `max_usage` and `failcnt` + Also, `memory_stats.stats` fields are incompatible with cgroup v1. + + To calculate the values shown by the `stats` command of the docker cli tool + the following formulas can be used: + * used_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1) + * used_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2) + * available_memory = `memory_stats.limit` + * Memory usage % = `(used_memory / available_memory) * 100.0` + * cpu_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage` + * system_cpu_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage` + * number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus` + * CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0` + operationId: "ContainerStats" + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerStatsResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "stream" + in: "query" + description: | + Stream the output. If false, the stats will be output once and then + it will disconnect. + type: "boolean" + default: true + - name: "one-shot" + in: "query" + description: | + Only get a single stat instead of waiting for 2 cycles. Must be used + with `stream=false`. + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/resize: + post: + summary: "Resize a container TTY" + description: "Resize the TTY for a container." + operationId: "ContainerResize" + consumes: + - "application/octet-stream" + produces: + - "application/json" + responses: + "200": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "cannot resize container" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "h" + in: "query" + required: true + description: "Height of the TTY session in characters" + type: "integer" + - name: "w" + in: "query" + required: true + description: "Width of the TTY session in characters" + type: "integer" + tags: ["Container"] + /containers/{id}/start: + post: + summary: "Start a container" + operationId: "ContainerStart" + responses: + "204": + description: "no error" + "304": + description: "container already started" + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container. Format is a + single character `[a-Z]` or `ctrl-<value>` where `<value>` is one + of: `a-z`, `@`, `^`, `[`, `,` or `_`. + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/stop: + post: + summary: "Stop a container" + operationId: "ContainerStop" + responses: + "204": + description: "no error" + "304": + description: "container already stopped" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + - name: "t" + in: "query" + description: "Number of seconds to wait before killing the container" + type: "integer" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/restart: + post: + summary: "Restart a container" + operationId: "ContainerRestart" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + - name: "t" + in: "query" + description: "Number of seconds to wait before killing the container" + type: "integer" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/kill: + post: + summary: "Kill a container" + description: | + Send a POSIX signal to a container, defaulting to killing to the + container. + operationId: "ContainerKill" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "container is not running" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + default: "SIGKILL" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/update: + post: + summary: "Update a container" + description: | + Change various configuration options of a container without having to + recreate it. + operationId: "ContainerUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "The container has been updated." + schema: + $ref: "#/definitions/ContainerUpdateResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "update" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/Resources" + - type: "object" + properties: + RestartPolicy: + $ref: "#/definitions/RestartPolicy" + example: + BlkioWeight: 300 + CpuShares: 512 + CpuPeriod: 100000 + CpuQuota: 50000 + CpuRealtimePeriod: 1000000 + CpuRealtimeRuntime: 10000 + CpusetCpus: "0,1" + CpusetMems: "0" + Memory: 314572800 + MemorySwap: 514288000 + MemoryReservation: 209715200 + RestartPolicy: + MaximumRetryCount: 4 + Name: "on-failure" + tags: ["Container"] + /containers/{id}/rename: + post: + summary: "Rename a container" + operationId: "ContainerRename" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "name already in use" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "name" + in: "query" + required: true + description: "New name for the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/pause: + post: + summary: "Pause a container" + description: | + Use the freezer cgroup to suspend all processes in a container. + + Traditionally, when suspending a process the `SIGSTOP` signal is used, + which is observable by the process being suspended. With the freezer + cgroup the process is unaware, and unable to capture, that it is being + suspended, and subsequently resumed. + operationId: "ContainerPause" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/unpause: + post: + summary: "Unpause a container" + description: "Resume a container which has been paused." + operationId: "ContainerUnpause" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/attach: + post: + summary: "Attach to a container" + description: | + Attach to a container to read its output or send it input. You can attach + to the same container multiple times and you can reattach to containers + that have been detached. + + Either the `stream` or `logs` parameter must be `true` for this endpoint + to do anything. + + See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) + for more details. + + ### Hijacking + + This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, + and `stderr` on the same socket. + + This is the response from the daemon for an attach request: + + ``` + HTTP/1.1 200 OK + Content-Type: application/vnd.docker.raw-stream + + [STREAM] + ``` + + After the headers and two new lines, the TCP connection can now be used + for raw, bidirectional communication between the client and server. + + To hint potential proxies about connection hijacking, the Docker client + can also optionally send connection upgrade headers. + + For example, the client sends this request to upgrade the connection: + + ``` + POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1 + Upgrade: tcp + Connection: Upgrade + ``` + + The Docker daemon will respond with a `101 UPGRADED` response, and will + similarly follow with the raw stream: + + ``` + HTTP/1.1 101 UPGRADED + Content-Type: application/vnd.docker.raw-stream + Connection: Upgrade + Upgrade: tcp + + [STREAM] + ``` + + ### Stream format + + When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), + the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream + and the stream over the hijacked connected is multiplexed to separate out + `stdout` and `stderr`. The stream consists of a series of frames, each + containing a header and a payload. + + The header contains the information which the stream writes (`stdout` or + `stderr`). It also contains the size of the associated frame encoded in + the last four bytes (`uint32`). + + It is encoded on the first eight bytes like this: + + ```go + header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} + ``` + + `STREAM_TYPE` can be: + + - 0: `stdin` (is written on `stdout`) + - 1: `stdout` + - 2: `stderr` + + `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size + encoded as big endian. + + Following the header is the payload, which is the specified number of + bytes of `STREAM_TYPE`. + + The simplest way to implement this protocol is the following: + + 1. Read 8 bytes. + 2. Choose `stdout` or `stderr` depending on the first byte. + 3. Extract the frame size from the last four bytes. + 4. Read the extracted size and output it on the correct output. + 5. Goto 1. + + ### Stream format when using a TTY + + When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), + the stream is not multiplexed. The data exchanged over the hijacked + connection is simply the raw data from the process PTY and client's + `stdin`. + + operationId: "ContainerAttach" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "101": + description: "no error, hints proxy about hijacking" + "200": + description: "no error, no upgrade header found" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container.Format is a single + character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, + `@`, `^`, `[`, `,` or `_`. + type: "string" + - name: "logs" + in: "query" + description: | + Replay previous logs from the container. + + This is useful for attaching to a container that has started and you + want to output everything since the container started. + + If `stream` is also enabled, once all the previous output has been + returned, it will seamlessly transition into streaming current + output. + type: "boolean" + default: false + - name: "stream" + in: "query" + description: | + Stream attached streams from the time the request was made onwards. + type: "boolean" + default: false + - name: "stdin" + in: "query" + description: "Attach to `stdin`" + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Attach to `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Attach to `stderr`" + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/attach/ws: + get: + summary: "Attach to a container via a websocket" + operationId: "ContainerAttachWebsocket" + responses: + "101": + description: "no error, hints proxy about hijacking" + "200": + description: "no error, no upgrade header found" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container.Format is a single + character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, + `@`, `^`, `[`, `,`, or `_`. + type: "string" + - name: "logs" + in: "query" + description: "Return logs" + type: "boolean" + default: false + - name: "stream" + in: "query" + description: "Return stream" + type: "boolean" + default: false + - name: "stdin" + in: "query" + description: "Attach to `stdin`" + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Attach to `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Attach to `stderr`" + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/wait: + post: + summary: "Wait for a container" + description: "Block until a container stops, then returns the exit code." + operationId: "ContainerWait" + produces: ["application/json"] + responses: + "200": + description: "The container has exit." + schema: + $ref: "#/definitions/ContainerWaitResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "condition" + in: "query" + description: | + Wait until a container state reaches the given condition. + + Defaults to `not-running` if omitted or empty. + type: "string" + enum: + - "not-running" + - "next-exit" + - "removed" + default: "not-running" + tags: ["Container"] + /containers/{id}: + delete: + summary: "Remove a container" + operationId: "ContainerDelete" + responses: + "204": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "conflict" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: | + You cannot remove a running container: c2ada9df5af8. Stop the + container before attempting removal or force remove + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "v" + in: "query" + description: "Remove anonymous volumes associated with the container." + type: "boolean" + default: false + - name: "force" + in: "query" + description: "If the container is running, kill it before removing it." + type: "boolean" + default: false + - name: "link" + in: "query" + description: "Remove the specified link associated with the container." + type: "boolean" + default: false + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/archive: + head: + summary: "Get information about files in a container" + description: | + A response header `X-Docker-Container-Path-Stat` is returned, containing + a base64 - encoded JSON object with some filesystem header information + about the path. + operationId: "ContainerArchiveInfo" + responses: + "200": + description: "no error" + headers: + X-Docker-Container-Path-Stat: + type: "string" + description: | + A base64 - encoded JSON object with some filesystem header + information about the path + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Container or path does not exist" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Resource in the container’s filesystem to archive." + type: "string" + tags: ["Container"] + get: + summary: "Get an archive of a filesystem resource in a container" + description: "Get a tar archive of a resource in the filesystem of container id." + operationId: "ContainerArchive" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Container or path does not exist" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Resource in the container’s filesystem to archive." + type: "string" + tags: ["Container"] + put: + summary: "Extract an archive of files or folders to a directory in a container" + description: | + Upload a tar archive to be extracted to a path in the filesystem of container id. + `path` parameter is asserted to be a directory. If it exists as a file, 400 error + will be returned with message "not a directory". + operationId: "PutContainerArchive" + consumes: ["application/x-tar", "application/octet-stream"] + responses: + "200": + description: "The content was extracted successfully" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "not a directory" + "403": + description: "Permission denied, the volume or container rootfs is marked as read-only." + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such container or path does not exist inside the container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Path to a directory in the container to extract the archive’s contents into. " + type: "string" + - name: "noOverwriteDirNonDir" + in: "query" + description: | + If `1`, `true`, or `True` then it will be an error if unpacking the + given content would cause an existing directory to be replaced with + a non-directory and vice versa. + type: "string" + - name: "copyUIDGID" + in: "query" + description: | + If `1`, `true`, then it will copy UID/GID maps to the dest file or + dir + type: "string" + - name: "inputStream" + in: "body" + required: true + description: | + The input stream must be a tar archive compressed with one of the + following algorithms: `identity` (no compression), `gzip`, `bzip2`, + or `xz`. + schema: + type: "string" + format: "binary" + tags: ["Container"] + /containers/prune: + post: + summary: "Delete stopped containers" + produces: + - "application/json" + operationId: "ContainerPrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ContainerPruneResponse" + properties: + ContainersDeleted: + description: "Container IDs that were deleted" + type: "array" + items: + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /images/json: + get: + summary: "List Images" + description: "Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image." + operationId: "ImageList" + produces: + - "application/json" + responses: + "200": + description: "Summary image data for the images matching the query" + schema: + type: "array" + items: + $ref: "#/definitions/ImageSummary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "all" + in: "query" + description: "Show all images. Only images from a final layer (no children) are shown by default." + type: "boolean" + default: false + - name: "filters" + in: "query" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the images list. + + Available filters: + + - `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + - `dangling=true` + - `label=key` or `label="key=value"` of an image label + - `reference`=(`<image-name>[:<tag>]`) + - `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + - `until=<timestamp>` + type: "string" + - name: "shared-size" + in: "query" + description: "Compute and show shared size as a `SharedSize` field on each image." + type: "boolean" + default: false + - name: "digests" + in: "query" + description: "Show digest information as a `RepoDigests` field on each image." + type: "boolean" + default: false + - name: "manifests" + in: "query" + description: "Include `Manifests` in the image summary." + type: "boolean" + default: false + - name: "identity" + in: "query" + description: "Include `Identity` in each manifest summary. Requires `manifests=1`." + type: "boolean" + default: false + tags: ["Image"] + /build: + post: + summary: "Build an image" + description: | + Build an image from a tar archive with a `Dockerfile` in it. + + The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/). + + The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output. + + The build is canceled if the client drops the connection by quitting or being killed. + operationId: "ImageBuild" + consumes: + - "application/octet-stream" + produces: + - "application/json" + parameters: + - name: "inputStream" + in: "body" + description: "A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz." + schema: + type: "string" + format: "binary" + - name: "dockerfile" + in: "query" + description: "Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`." + type: "string" + default: "Dockerfile" + - name: "t" + in: "query" + description: "A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters." + type: "string" + - name: "extrahosts" + in: "query" + description: "Extra hosts to add to /etc/hosts" + type: "string" + - name: "remote" + in: "query" + description: "A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball." + type: "string" + - name: "q" + in: "query" + description: "Suppress verbose build output." + type: "boolean" + default: false + - name: "nocache" + in: "query" + description: "Do not use the cache when building the image." + type: "boolean" + default: false + - name: "cachefrom" + in: "query" + description: "JSON array of images used for build cache resolution." + type: "string" + - name: "pull" + in: "query" + description: "Attempt to pull the image even if an older image exists locally." + type: "string" + - name: "rm" + in: "query" + description: "Remove intermediate containers after a successful build." + type: "boolean" + default: true + - name: "forcerm" + in: "query" + description: "Always remove intermediate containers, even upon failure." + type: "boolean" + default: false + - name: "memory" + in: "query" + description: "Set memory limit for build." + type: "integer" + format: "int64" + - name: "memswap" + in: "query" + description: "Total memory (memory + swap). Set as `-1` to disable swap." + type: "integer" + format: "int64" + - name: "cpushares" + in: "query" + description: "CPU shares (relative weight)." + type: "integer" + format: "int64" + - name: "cpusetcpus" + in: "query" + description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." + type: "string" + - name: "cpuperiod" + in: "query" + description: "The length of a CPU period in microseconds." + type: "integer" + format: "int64" + - name: "cpuquota" + in: "query" + description: "Microseconds of CPU time that the container can get in a CPU period." + type: "integer" + format: "int64" + - name: "buildargs" + in: "query" + description: > + JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker + uses the buildargs as the environment context for commands run via the `Dockerfile` RUN + instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for + passing secret values. + + + For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the + query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded. + + + [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) + type: "string" + - name: "shmsize" + in: "query" + description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." + type: "integer" + format: "int64" + - name: "squash" + in: "query" + description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" + type: "boolean" + - name: "labels" + in: "query" + description: "Arbitrary key/value labels to set on the image, as a JSON map of string pairs." + type: "string" + - name: "networkmode" + in: "query" + description: | + Sets the networking mode for the run commands during build. Supported + standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. + Any other value is taken as a custom network's name or ID to which this + container should connect to. + type: "string" + - name: "Content-type" + in: "header" + type: "string" + enum: + - "application/x-tar" + default: "application/x-tar" + - name: "X-Registry-Config" + in: "header" + description: | + This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to. + + The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example: + + ``` + { + "docker.example.com": { + "username": "janedoe", + "password": "hunter2" + }, + "https://index.docker.io/v1/": { + "username": "mobydock", + "password": "conta1n3rize14" + } + } + ``` + + Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. + type: "string" + - name: "platform" + in: "query" + description: "Platform in the format os[/arch[/variant]]" + type: "string" + default: "" + - name: "target" + in: "query" + description: "Target build stage" + type: "string" + default: "" + - name: "outputs" + in: "query" + description: | + BuildKit output configuration in the format of a stringified JSON array of objects. + Each object must have two top-level properties: `Type` and `Attrs`. + The `Type` property must be set to 'moby'. + The `Attrs` property is a map of attributes for the BuildKit output configuration. + See https://docs.docker.com/build/exporters/oci-docker/ for more information. + + Example: + + ``` + [{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}] + ``` + type: "string" + default: "" + - name: "version" + in: "query" + type: "string" + default: "1" + enum: ["1", "2"] + description: | + Version of the builder backend to use. + + - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) + - `2` is [BuildKit](https://github.com/moby/buildkit) + responses: + "200": + description: "no error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /build/prune: + post: + summary: "Delete builder cache" + produces: + - "application/json" + operationId: "BuildPrune" + parameters: + - name: "reserved-space" + in: "query" + description: "Amount of disk space in bytes to keep for cache" + type: "integer" + format: "int64" + - name: "max-used-space" + in: "query" + description: "Maximum amount of disk space allowed to keep for cache" + type: "integer" + format: "int64" + - name: "min-free-space" + in: "query" + description: "Target amount of free disk space after pruning" + type: "integer" + format: "int64" + - name: "all" + in: "query" + type: "boolean" + description: "Remove all types of build cache" + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the list of build cache objects. + + Available filters: + + - `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time. + - `id=<id>` + - `parent=<id>` + - `type=<string>` + - `description=<string>` + - `inuse` + - `shared` + - `private` + responses: + "200": + description: "No error" + schema: + type: "object" + title: "BuildPruneResponse" + properties: + CachesDeleted: + type: "array" + items: + description: "ID of build cache object" + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /images/create: + post: + summary: "Create an image" + description: "Pull or import an image." + operationId: "ImageCreate" + consumes: + - "text/plain" + - "application/octet-stream" + produces: + - "application/json" + responses: + "200": + description: "no error" + "404": + description: "repository does not exist or no read access" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "fromImage" + in: "query" + description: | + Name of the image to pull. If the name includes a tag or digest, specific behavior applies: + + - If only `fromImage` includes a tag, that tag is used. + - If both `fromImage` and `tag` are provided, `tag` takes precedence. + - If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored. + - If neither a tag nor digest is specified, all tags are pulled. + type: "string" + - name: "fromSrc" + in: "query" + description: "Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image." + type: "string" + - name: "repo" + in: "query" + description: "Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image." + type: "string" + - name: "tag" + in: "query" + description: "Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled." + type: "string" + - name: "message" + in: "query" + description: "Set commit message for imported image." + type: "string" + - name: "inputImage" + in: "body" + description: "Image content if the value `-` has been specified in fromSrc query parameter" + schema: + type: "string" + required: false + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "changes" + in: "query" + description: | + Apply `Dockerfile` instructions to the image that is created, + for example: `changes=ENV DEBUG=true`. + Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. + + Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + type: "array" + collectionFormat: "multi" + items: + type: "string" + - name: "platform" + in: "query" + description: | + Platform in the format os[/arch[/variant]]. + + When used in combination with the `fromImage` option, the daemon checks + if the given image is present in the local image cache with the given + OS and Architecture, and otherwise attempts to pull the image. If the + option is not set, the host's native OS and Architecture are used. + If the given image does not exist in the local image cache, the daemon + attempts to pull the image with the host's native OS and Architecture. + If the given image does exists in the local image cache, but its OS or + architecture does not match, a warning is produced. + + When used with the `fromSrc` option to import an image from an archive, + this option sets the platform information for the imported image. If + the option is not set, the host's native OS and Architecture are used + for the imported image. + type: "string" + default: "" + tags: ["Image"] + /images/{name}/json: + get: + summary: "Inspect an image" + description: "Return low-level information about an image." + operationId: "ImageInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/ImageInspect" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: someimage (tag: latest)" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + - name: "manifests" + in: "query" + description: |- + Include Manifests in the image summary. + + The `manifests` and `platform` options are mutually exclusive, and + an error is produced if both are set. + type: "boolean" + default: false + required: false + - name: "platform" + type: "string" + in: "query" + description: |- + JSON-encoded OCI platform to select the platform-variant. + If omitted, it defaults to any locally available platform, + prioritizing the daemon's host platform. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to show inspect. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + The `platform` and `manifests` options are mutually exclusive, and + an error is produced if both are set. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/{name}/attestations: + get: + summary: "Get attestation statements for an image" + description: | + Return the in-toto attestation statements attached to the image for the + given platform. The daemon locates the attestation manifest(s) that + reference the matching platform image manifest, reads their statement + layers, and returns the verbatim statement JSON together with layer + metadata. + + If the image has no attestations an empty array is returned. + operationId: "ImageAttestations" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/AttestationStatement" + "400": + description: "Bad parameter (e.g. malformed `platform` value)" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such image, or no manifest found for the requested platform" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + "501": + description: | + The daemon's image backend does not support attestations. This + is returned by the legacy (graphdriver) image store, which does + not preserve OCI image indexes. + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: |- + JSON-encoded OCI platform to select the image variant whose + attestations to return. + If omitted, the daemon's default (host) platform is used. + + Only one platform value is currently accepted; passing more than + one returns an error. The parameter is declared as an array so the + wire shape can accept multiple values in the future without an + API version bump. + + Example: `{"os": "linux", "architecture": "amd64"}` + required: false + - name: "type" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: |- + In-toto predicate type URI to filter returned statements. May be + repeated to accept any of several predicate types. If omitted, all + statements are returned. + + Example: `type=https://slsa.dev/provenance/v0.2&type=https://spdx.dev/Document` + required: false + - name: "statement" + type: "boolean" + in: "query" + description: |- + Include the verbatim in-toto statement body in each returned + entry. Defaults to false; when omitted or false, only the + descriptor and predicate type are returned and statement blobs + are not read. + default: false + required: false + tags: ["Image"] + /images/{name}/history: + get: + summary: "Get the history of an image" + description: "Return parent layers of an image." + operationId: "ImageHistory" + produces: ["application/json"] + responses: + "200": + description: "List of image layers" + schema: + type: "array" + items: + $ref: "#/definitions/ImageHistoryResponseItem" + examples: + application/json: + - Id: "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710" + Created: 1398108230 + CreatedBy: "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /" + Tags: + - "ubuntu:lucid" + - "ubuntu:10.04" + Size: 182964289 + Comment: "" + - Id: "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8" + Created: 1398108222 + CreatedBy: "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/" + Tags: [] + Size: 0 + Comment: "" + - Id: "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158" + Created: 1371157430 + CreatedBy: "" + Tags: + - "scratch12:latest" + - "scratch:latest" + Size: 0 + Comment: "Imported from -" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant. + If omitted, it defaults to any locally available platform, + prioritizing the daemon's host platform. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to show the history for. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/{name}/push: + post: + summary: "Push an image" + description: | + Push an image to a registry. + + If you wish to push an image on to a private registry, that image must + already have a tag which references the registry. For example, + `registry.example.com/myimage:latest`. + + The push is cancelled if the HTTP connection is closed. + operationId: "ImagePush" + consumes: + - "application/octet-stream" + responses: + "200": + description: "No error" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + Name of the image to push. For example, `registry.example.com/myimage`. + The image must be present in the local image store with the same name. + + The name should be provided without tag; if a tag is provided, it + is ignored. For example, `registry.example.com/myimage:latest` is + considered equivalent to `registry.example.com/myimage`. + + Use the `tag` parameter to specify the tag to push. + type: "string" + required: true + - name: "tag" + in: "query" + description: | + Tag of the image to push. For example, `latest`. If no tag is provided, + all tags of the given image that are present in the local image store + are pushed. + type: "string" + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant to push. + If not provided, all available variants will attempt to be pushed. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to push to the registry. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + required: true + tags: ["Image"] + /images/{name}/tag: + post: + summary: "Tag an image" + description: | + Create a tag that refers to a source image. + + This creates an additional reference (tag) to the source image. The tag + can include a different repository name and/or tag. If the repository + or tag already exists, it will be overwritten. + operationId: "ImageTag" + responses: + "201": + description: "No error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID to tag." + type: "string" + required: true + - name: "repo" + in: "query" + description: "The repository to tag in. For example, `someuser/someimage`." + type: "string" + - name: "tag" + in: "query" + description: "The name of the new tag." + type: "string" + tags: ["Image"] + /images/{name}: + delete: + summary: "Remove an image" + description: | + Remove an image, along with any untagged parent images that were + referenced by that image. + + Images can't be removed if they have descendant images, are being + used by a running container or are being used by a build. + operationId: "ImageDelete" + produces: ["application/json"] + responses: + "200": + description: "The image was deleted successfully" + schema: + type: "array" + items: + $ref: "#/definitions/ImageDeleteResponseItem" + examples: + application/json: + - Untagged: "3e2f21a89f" + - Deleted: "3e2f21a89f" + - Deleted: "53b4f83ac9" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "force" + in: "query" + description: "Remove the image even if it is being used by stopped containers or has other tags" + type: "boolean" + default: false + - name: "noprune" + in: "query" + description: "Do not delete untagged parent images" + type: "boolean" + default: false + - name: "platforms" + in: "query" + description: | + Select platform-specific content to delete. + Repeat the parameter to select multiple platforms. + Each platform is a OCI platform encoded as a JSON string. + type: "array" + collectionFormat: "multi" + items: + # This should be OCIPlatform + # but $ref is not supported for array in query in Swagger 2.0 + # $ref: "#/definitions/OCIPlatform" + type: "string" + tags: ["Image"] + /images/search: + get: + summary: "Search images" + description: "Search for an image on Docker Hub." + operationId: "ImageSearch" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + type: "object" + title: "ImageSearchResponseItem" + properties: + description: + type: "string" + is_official: + type: "boolean" + is_automated: + description: | + Whether this repository has automated builds enabled. + + <p><br /></p> + + > **Deprecated**: This field is deprecated and will always be "false". + type: "boolean" + example: false + name: + type: "string" + star_count: + type: "integer" + examples: + application/json: + - description: "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!" + is_official: true + is_automated: false + name: "alpine" + star_count: 10093 + - description: "Busybox base image." + is_official: true + is_automated: false + name: "Busybox base image." + star_count: 3037 + - description: "The PostgreSQL object-relational database system provides reliability and data integrity." + is_official: true + is_automated: false + name: "postgres" + star_count: 12408 + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "term" + in: "query" + description: "Term to search" + type: "string" + required: true + - name: "limit" + in: "query" + description: "Maximum number of results to return" + type: "integer" + - name: "filters" + in: "query" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + + - `is-official=(true|false)` + - `stars=<number>` Matches images that has at least 'number' stars. + type: "string" + tags: ["Image"] + /images/prune: + post: + summary: "Delete unused images" + produces: + - "application/json" + operationId: "ImagePrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), prune only + unused *and* untagged images. When set to `false` + (or `0`), all unused images are pruned. + - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ImagePruneResponse" + properties: + ImagesDeleted: + description: "Images that were deleted" + type: "array" + items: + $ref: "#/definitions/ImageDeleteResponseItem" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /auth: + post: + summary: "Check auth configuration" + description: | + Validate credentials for a registry and, if available, get an identity + token for accessing the registry without password. + operationId: "SystemAuth" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "An identity token was generated successfully." + schema: + $ref: "#/definitions/AuthResponse" + "204": + description: "No error" + "401": + description: "Auth error" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "authConfig" + in: "body" + description: "Authentication to check" + schema: + $ref: "#/definitions/AuthConfig" + tags: ["System"] + /info: + get: + summary: "Get system information" + operationId: "SystemInfo" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/SystemInfo" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /version: + get: + summary: "Get version" + description: "Returns the version of Docker that is running and various information about the system that Docker is running on." + operationId: "SystemVersion" + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/SystemVersion" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /_ping: + get: + summary: "Ping" + description: "This is a dummy endpoint you can use to test if the server is accessible." + operationId: "SystemPing" + produces: + - "text/plain" + responses: + "200": + description: "no error" + schema: + type: "string" + example: "OK" + headers: + Api-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: | + Default version of docker image builder + + The default on Linux is version "2" (BuildKit), but the daemon + can be configured to recommend version "1" (classic Builder). + Windows does not yet support BuildKit for native Windows images, + and uses "1" (classic builder) as a default. + + This value is a recommendation as advertised by the daemon, and + it is up to the client to choose which builder to use. + default: "2" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + headers: + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + tags: ["System"] + head: + summary: "Ping" + description: "This is a dummy endpoint you can use to test if the server is accessible." + operationId: "SystemPingHead" + produces: ["text/plain"] + responses: + "200": + description: "no error" + schema: + type: "string" + example: "(empty)" + headers: + Api-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: "Default version of docker image builder" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /commit: + post: + summary: "Create a new image from a container" + operationId: "ImageCommit" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "containerConfig" + in: "body" + description: "The container configuration" + schema: + $ref: "#/definitions/ContainerConfig" + - name: "container" + in: "query" + description: "The ID or name of the container to commit" + type: "string" + - name: "repo" + in: "query" + description: "Repository name for the created image" + type: "string" + - name: "tag" + in: "query" + description: "Tag name for the create image" + type: "string" + - name: "comment" + in: "query" + description: "Commit message" + type: "string" + - name: "author" + in: "query" + description: "Author of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`)" + type: "string" + - name: "pause" + in: "query" + description: "Whether to pause the container before committing" + type: "boolean" + default: true + - name: "changes" + in: "query" + description: "`Dockerfile` instructions to apply while committing" + type: "string" + tags: ["Image"] + /events: + get: + summary: "Monitor events" + description: | + Stream real-time events from the server. + + Various objects within Docker report events when something happens to them. + + Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune` + + Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune` + + Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune` + + Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune` + + The Docker daemon reports these events: `reload` + + Services report these events: `create`, `update`, and `remove` + + Nodes report these events: `create`, `update`, and `remove` + + Secrets report these events: `create`, `update`, and `remove` + + Configs report these events: `create`, `update`, and `remove` + + The Builder reports `prune` events + + operationId: "SystemEvents" + produces: + - "application/jsonl" + - "application/x-ndjson" + - "application/json-seq" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/EventMessage" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "since" + in: "query" + description: "Show events created since this timestamp then stream new events." + type: "string" + - name: "until" + in: "query" + description: "Show events created until this timestamp then stop streaming." + type: "string" + - name: "filters" + in: "query" + description: | + A JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters: + + - `config=<string>` config name or ID + - `container=<string>` container name or ID + - `daemon=<string>` daemon name or ID + - `event=<string>` event type + - `image=<string>` image name or ID + - `label=<string>` image or container label + - `network=<string>` network name or ID + - `node=<string>` node ID + - `plugin`=<string> plugin name or ID + - `scope`=<string> local or swarm + - `secret=<string>` secret name or ID + - `service=<string>` service name or ID + - `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config` + - `volume=<string>` volume name + type: "string" + tags: ["System"] + /system/df: + get: + summary: "Get data usage information" + operationId: "SystemDataUsage" + responses: + "200": + description: "no error" + schema: + type: "object" + title: "SystemDataUsageResponse" + properties: + ImageUsage: + $ref: "#/definitions/ImagesDiskUsage" + ContainerUsage: + $ref: "#/definitions/ContainersDiskUsage" + VolumeUsage: + $ref: "#/definitions/VolumesDiskUsage" + BuildCacheUsage: + $ref: "#/definitions/BuildCacheDiskUsage" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "type" + in: "query" + description: | + Object types, for which to compute and return data. + type: "array" + collectionFormat: multi + items: + type: "string" + enum: ["container", "image", "volume", "build-cache"] + - name: "verbose" + in: "query" + description: | + Show detailed information on space usage. + type: "boolean" + default: false + tags: ["System"] + /images/{name}/get: + get: + summary: "Export an image" + description: | + Get a tarball containing all images and metadata for a repository. + + If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced. + + ### Image tarball format + + An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content). + + Additionally, includes the manifest.json file associated with a backwards compatible docker save format. + + If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs. + + ```json + { + "hello-world": { + "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1" + } + } + ``` + operationId: "ImageGet" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + schema: + type: "string" + format: "binary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform describing a platform which will be used + to select a platform-specific image to be saved if the image is + multi-platform. + If not provided, the full multi-platform image will be saved. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/get: + get: + summary: "Export several images" + description: | + Get a tarball containing all images and metadata for several image + repositories. + + For each value of the `names` parameter: if it is a specific name and + tag (e.g. `ubuntu:latest`), then only that image (and its parents) are + returned; if it is an image ID, similarly only that image (and its parents) + are returned and there would be no names referenced in the 'repositories' + file for this image ID. + + For details on the format, see the [export image endpoint](#operation/ImageGet). + operationId: "ImageGetAll" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + schema: + type: "string" + format: "binary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "names" + in: "query" + description: "Image names to filter by. Repeat the parameter for multiple images." + type: "array" + collectionFormat: "multi" + items: + type: "string" + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform(s) which will be used to select the + platform-specific image(s) to be saved if the image is + multi-platform. If not provided, the full multi-platform image + will be saved. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/load: + post: + summary: "Import images" + description: | + Load a set of images and tags into a repository. + + For details on the format, see the [export image endpoint](#operation/ImageGet). + operationId: "ImageLoad" + consumes: + - "application/x-tar" + produces: + - "application/json" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "imagesTarball" + in: "body" + description: "Tar archive containing images" + schema: + type: "string" + format: "binary" + - name: "quiet" + in: "query" + description: "Suppress progress details during load." + type: "boolean" + default: false + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform(s) which will be used to select the + platform-specific image(s) to load if the image is + multi-platform. If not provided, the full multi-platform image + will be loaded. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /containers/{id}/exec: + post: + summary: "Create an exec instance" + description: "Run a command inside a running container." + operationId: "ContainerExec" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "container is paused" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "execConfig" + in: "body" + description: "Exec configuration" + schema: + type: "object" + title: "ExecConfig" + properties: + AttachStdin: + type: "boolean" + description: "Attach to `stdin` of the exec command." + AttachStdout: + type: "boolean" + description: "Attach to `stdout` of the exec command." + AttachStderr: + type: "boolean" + description: "Attach to `stderr` of the exec command." + ConsoleSize: + type: "array" + description: "Initial console size, as an `[height, width]` array." + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + DetachKeys: + type: "string" + description: | + Override the key sequence for detaching a container. Format is + a single character `[a-Z]` or `ctrl-<value>` where `<value>` + is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. + Tty: + type: "boolean" + description: "Allocate a pseudo-TTY." + Env: + description: | + A list of environment variables in the form `["VAR=value", ...]`. + type: "array" + items: + type: "string" + Cmd: + type: "array" + description: "Command to run, as a string or array of strings." + items: + type: "string" + Privileged: + type: "boolean" + description: "Runs the exec process with extended privileges." + default: false + User: + type: "string" + description: | + The user, and optionally, group to run the exec process inside + the container. Format is one of: `user`, `user:group`, `uid`, + or `uid:gid`. + WorkingDir: + type: "string" + description: | + The working directory for the exec process inside the container. + example: + AttachStdin: false + AttachStdout: true + AttachStderr: true + DetachKeys: "ctrl-p,ctrl-q" + Tty: false + Cmd: + - "date" + Env: + - "FOO=bar" + - "BAZ=quux" + required: true + - name: "id" + in: "path" + description: "ID or name of container" + type: "string" + required: true + tags: ["Exec"] + /exec/{id}/start: + post: + summary: "Start an exec instance" + description: | + Starts a previously set up exec instance. If detach is true, this endpoint + returns immediately after starting the command. Otherwise, it sets up an + interactive session with the command. + operationId: "ExecStart" + consumes: + - "application/json" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "200": + description: "No error" + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Container is stopped or paused" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "execStartConfig" + in: "body" + schema: + type: "object" + title: "ExecStartConfig" + properties: + Detach: + type: "boolean" + description: "Detach from the command." + example: false + Tty: + type: "boolean" + description: "Allocate a pseudo-TTY." + example: true + ConsoleSize: + type: "array" + description: "Initial console size, as an `[height, width]` array." + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + tags: ["Exec"] + /exec/{id}/resize: + post: + summary: "Resize an exec instance" + description: | + Resize the TTY session used by an exec instance. This endpoint only works + if `tty` was specified as part of creating and starting the exec instance. + operationId: "ExecResize" + responses: + "200": + description: "No error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + - name: "h" + in: "query" + required: true + description: "Height of the TTY session in characters" + type: "integer" + - name: "w" + in: "query" + required: true + description: "Width of the TTY session in characters" + type: "integer" + tags: ["Exec"] + /exec/{id}/json: + get: + summary: "Inspect an exec instance" + description: "Return low-level information about an exec instance." + operationId: "ExecInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ExecInspectResponse" + properties: + CanRemove: + type: "boolean" + DetachKeys: + type: "string" + ID: + type: "string" + Running: + type: "boolean" + ExitCode: + type: "integer" + ProcessConfig: + $ref: "#/definitions/ProcessConfig" + OpenStdin: + type: "boolean" + OpenStderr: + type: "boolean" + OpenStdout: + type: "boolean" + ContainerID: + type: "string" + Pid: + type: "integer" + description: "The system process ID for the exec process." + examples: + application/json: + CanRemove: false + ContainerID: "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126" + DetachKeys: "" + ExitCode: 2 + ID: "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b" + OpenStderr: true + OpenStdin: true + OpenStdout: true + ProcessConfig: + arguments: + - "-c" + - "exit 2" + entrypoint: "sh" + privileged: false + tty: true + user: "1000" + Running: false + Pid: 42000 + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + tags: ["Exec"] + + /volumes: + get: + summary: "List volumes" + operationId: "VolumeList" + produces: ["application/json"] + responses: + "200": + description: "Summary volume data that matches the query" + schema: + $ref: "#/definitions/VolumeListResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + JSON encoded value of the filters (a `map[string][]string`) to + process on the volumes list. Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), returns all + volumes that are not in use by a container. When set to `false` + (or `0`), only volumes that are in use by one or more + containers are returned. + - `driver=<volume-driver-name>` Matches volumes based on their driver. + - `label=<key>` or `label=<key>:<value>` Matches volumes based on + the presence of a `label` alone or a `label` and a value. + - `name=<volume-name>` Matches all or part of a volume name. + type: "string" + format: "json" + tags: ["Volume"] + + /volumes/create: + post: + summary: "Create a volume" + operationId: "VolumeCreate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "201": + description: "The volume was created successfully" + schema: + $ref: "#/definitions/Volume" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "volumeConfig" + in: "body" + required: true + description: "Volume configuration" + schema: + $ref: "#/definitions/VolumeCreateRequest" + tags: ["Volume"] + + /volumes/{name}: + get: + summary: "Inspect a volume" + operationId: "VolumeInspect" + produces: ["application/json"] + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/Volume" + "404": + description: "No such volume" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + required: true + description: "Volume name or ID" + type: "string" + tags: ["Volume"] + + put: + summary: | + "Update a volume. Valid only for Swarm cluster volumes" + operationId: "VolumeUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such volume" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "The name or ID of the volume" + type: "string" + required: true + - name: "body" + in: "body" + schema: + # though the schema for is an object that contains only a + # ClusterVolumeSpec, wrapping the ClusterVolumeSpec in this object + # means that if, later on, we support things like changing the + # labels, we can do so without duplicating that information to the + # ClusterVolumeSpec. + type: "object" + description: "Volume configuration" + properties: + Spec: + $ref: "#/definitions/ClusterVolumeSpec" + description: | + The spec of the volume to update. Currently, only Availability may + change. All other fields must remain unchanged. + - name: "version" + in: "query" + description: | + The version number of the volume being updated. This is required to + avoid conflicting writes. Found in the volume's `ClusterVolume` + field. + type: "integer" + format: "int64" + required: true + tags: ["Volume"] + + delete: + summary: "Remove a volume" + description: "Instruct the driver to remove the volume." + operationId: "VolumeDelete" + responses: + "204": + description: "The volume was removed" + "404": + description: "No such volume or volume driver" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Volume is in use and cannot be removed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + required: true + description: "Volume name or ID" + type: "string" + - name: "force" + in: "query" + description: "Force the removal of the volume" + type: "boolean" + default: false + produces: + - "application/json" + tags: ["Volume"] + + /volumes/prune: + post: + summary: "Delete unused volumes" + produces: + - "application/json" + operationId: "VolumePrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. + - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "VolumePruneResponse" + properties: + VolumesDeleted: + description: "Volumes that were deleted" + type: "array" + items: + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Volume"] + /networks: + get: + summary: "List networks" + description: | + Returns a list of networks. For details on the format, see the + [network inspect endpoint](#operation/NetworkInspect). + + Note that it uses a different, smaller representation of a network than + inspecting a single network. For example, the list of containers attached + to the network is not propagated in API versions 1.28 and up. + operationId: "NetworkList" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/NetworkSummary" + examples: + application/json: + - Name: "bridge" + Id: "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566" + Created: "2016-10-19T06:21:00.416543526Z" + Scope: "local" + Driver: "bridge" + EnableIPv4: true + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: + - + Subnet: "172.17.0.0/16" + Options: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + - Name: "none" + Id: "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794" + Created: "0001-01-01T00:00:00Z" + Scope: "local" + Driver: "null" + EnableIPv4: false + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: [] + Containers: {} + Options: {} + - Name: "host" + Id: "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e" + Created: "0001-01-01T00:00:00Z" + Scope: "local" + Driver: "host" + EnableIPv4: false + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: [] + Containers: {} + Options: {} + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + JSON encoded value of the filters (a `map[string][]string`) to process + on the networks list. + + Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), returns all + networks that are not in use by a container. When set to `false` + (or `0`), only networks that are in use by one or more + containers are returned. + - `driver=<driver-name>` Matches a network's driver. + - `id=<network-id>` Matches all or part of a network ID. + - `label=<key>` or `label=<key>=<value>` of a network label. + - `name=<network-name>` Matches all or part of a network name. + - `scope=["swarm"|"global"|"local"]` Filters networks by scope (`swarm`, `global`, or `local`). + - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. + type: "string" + tags: ["Network"] + + /networks/{id}: + get: + summary: "Inspect a network" + operationId: "NetworkInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/NetworkInspect" + "404": + description: "Network not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "verbose" + in: "query" + description: "Detailed inspect output for troubleshooting" + type: "boolean" + default: false + - name: "scope" + in: "query" + description: "Filter the network by scope (swarm, global, or local)" + type: "string" + tags: ["Network"] + + delete: + summary: "Remove a network" + operationId: "NetworkDelete" + responses: + "204": + description: "No error" + "403": + description: "operation not supported for pre-defined networks" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such network" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + produces: + - "application/json" + tags: ["Network"] + + /networks/create: + post: + summary: "Create a network" + operationId: "NetworkCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "Network created successfully" + schema: + $ref: "#/definitions/NetworkCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: | + Forbidden operation. This happens when trying to create a network named after a pre-defined network, + or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "plugin not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "networkConfig" + in: "body" + description: "Network configuration" + required: true + schema: + type: "object" + title: "NetworkCreateRequest" + required: ["Name"] + properties: + Name: + description: "The network's name." + type: "string" + example: "my_network" + Driver: + description: "Name of the network driver plugin to use." + type: "string" + default: "bridge" + example: "bridge" + Scope: + description: | + The level at which the network exists (e.g. `swarm` for cluster-wide + or `local` for machine level). + type: "string" + Internal: + description: "Restrict external access to the network." + type: "boolean" + Attachable: + description: | + Globally scoped network is manually attachable by regular + containers from workers in swarm mode. + type: "boolean" + example: true + Ingress: + description: | + Ingress network is the network which provides the routing-mesh + in swarm mode. + type: "boolean" + example: false + ConfigOnly: + description: | + Creates a config-only network. Config-only networks are placeholder + networks for network configurations to be used by other networks. + Config-only networks cannot be used directly to run containers + or services. + type: "boolean" + default: false + example: false + ConfigFrom: + description: | + Specifies the source which will provide the configuration for + this network. The specified network must be an existing + config-only network; see ConfigOnly. + $ref: "#/definitions/ConfigReference" + IPAM: + description: "Optional custom IP scheme for the network." + $ref: "#/definitions/IPAM" + EnableIPv4: + description: "Enable IPv4 on the network." + type: "boolean" + example: true + EnableIPv6: + description: "Enable IPv6 on the network." + type: "boolean" + example: true + Options: + description: "Network specific options to be used by the drivers." + type: "object" + additionalProperties: + type: "string" + example: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + tags: ["Network"] + + /networks/{id}/connect: + post: + summary: "Connect a container to a network" + description: "The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container" + operationId: "NetworkConnect" + consumes: + - "application/json" + responses: + "200": + description: "No error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: "Operation forbidden" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Network or container not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "container" + in: "body" + required: true + schema: + $ref: "#/definitions/NetworkConnectRequest" + tags: ["Network"] + + /networks/{id}/disconnect: + post: + summary: "Disconnect a container from a network" + operationId: "NetworkDisconnect" + consumes: + - "application/json" + responses: + "200": + description: "No error" + "403": + description: "Operation not supported for swarm scoped networks" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Network or container not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "container" + in: "body" + required: true + schema: + $ref: "#/definitions/NetworkDisconnectRequest" + tags: ["Network"] + /networks/prune: + post: + summary: "Delete unused networks" + produces: + - "application/json" + operationId: "NetworkPrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "NetworkPruneResponse" + properties: + NetworksDeleted: + description: "Networks that were deleted" + type: "array" + items: + type: "string" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Network"] + /plugins: + get: + summary: "List plugins" + operationId: "PluginList" + description: "Returns information about installed plugins." + produces: ["application/json"] + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/Plugin" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the plugin list. + + Available filters: + + - `capability=<capability name>` + - `enable=<true>|<false>` + tags: ["Plugin"] + + /plugins/privileges: + get: + summary: "Get plugin privileges" + operationId: "GetPluginPrivileges" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "remote" + in: "query" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + tags: + - "Plugin" + + /plugins/pull: + post: + summary: "Install a plugin" + operationId: "PluginPull" + description: | + Pulls and installs a plugin. After the plugin is installed, it can be + enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable). + produces: + - "application/json" + responses: + "204": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "remote" + in: "query" + description: | + Remote reference for plugin to install. + + The `:latest` tag is optional, and is used as the default if omitted. + required: true + type: "string" + - name: "name" + in: "query" + description: | + Local name for the pulled plugin. + + The `:latest` tag is optional, and is used as the default if omitted. + required: false + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration to use when pulling a plugin + from a registry. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + tags: ["Plugin"] + /plugins/{name}/json: + get: + summary: "Inspect a plugin" + operationId: "PluginInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Plugin" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + tags: ["Plugin"] + /plugins/{name}: + delete: + summary: "Remove a plugin" + operationId: "PluginDelete" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Plugin" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "force" + in: "query" + description: | + Disable the plugin before removing. This may result in issues if the + plugin is in use by a container. + type: "boolean" + default: false + tags: ["Plugin"] + /plugins/{name}/enable: + post: + summary: "Enable a plugin" + operationId: "PluginEnable" + responses: + "200": + description: "no error" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "timeout" + in: "query" + description: "Set the HTTP client timeout (in seconds)" + type: "integer" + default: 0 + tags: ["Plugin"] + /plugins/{name}/disable: + post: + summary: "Disable a plugin" + operationId: "PluginDisable" + responses: + "200": + description: "no error" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "force" + in: "query" + description: | + Force disable a plugin even if still in use. + required: false + type: "boolean" + tags: ["Plugin"] + /plugins/{name}/upgrade: + post: + summary: "Upgrade a plugin" + operationId: "PluginUpgrade" + responses: + "204": + description: "no error" + "404": + description: "plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "remote" + in: "query" + description: | + Remote reference to upgrade to. + + The `:latest` tag is optional, and is used as the default if omitted. + required: true + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration to use when pulling a plugin + from a registry. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + produces: + - "application/json" + tags: ["Plugin"] + /plugins/create: + post: + summary: "Create a plugin" + operationId: "PluginCreate" + consumes: + - "application/x-tar" + responses: + "204": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "query" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "tarContext" + in: "body" + description: "Path to tar containing plugin rootfs and manifest" + schema: + type: "string" + format: "binary" + produces: + - "application/json" + tags: ["Plugin"] + /plugins/{name}/push: + post: + summary: "Push a plugin" + operationId: "PluginPush" + description: | + Push a plugin to the registry. + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + responses: + "200": + description: "no error" + "404": + description: "plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Plugin"] + /plugins/{name}/set: + post: + summary: "Configure a plugin" + operationId: "PluginSet" + consumes: + - "application/json" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + type: "string" + example: ["DEBUG=1"] + responses: + "204": + description: "No error" + "404": + description: "Plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" + tags: ["Plugin"] + /nodes: + get: + summary: "List nodes" + operationId: "NodeList" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Node" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the nodes list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `id=<node id>` + - `label=<engine label>` + - `membership=`(`accepted`|`pending`)` + - `name=<node name>` + - `node.label=<node label>` + - `role=`(`manager`|`worker`)` + type: "string" + tags: ["Node"] + /nodes/{id}: + get: + summary: "Inspect a node" + operationId: "NodeInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Node" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the node" + type: "string" + required: true + tags: ["Node"] + delete: + summary: "Delete a node" + operationId: "NodeDelete" + responses: + "200": + description: "no error" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the node" + type: "string" + required: true + - name: "force" + in: "query" + description: "Force remove a node from the swarm" + default: false + type: "boolean" + tags: ["Node"] + /nodes/{id}/update: + post: + summary: "Update a node" + operationId: "NodeUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID of the node" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/NodeSpec" + - name: "version" + in: "query" + description: | + The version number of the node object being updated. This is required + to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Node"] + /swarm: + get: + summary: "Inspect swarm" + operationId: "SwarmInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Swarm" + "404": + description: "no such swarm" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /swarm/init: + post: + summary: "Initialize a new swarm" + operationId: "SwarmInit" + produces: + - "application/json" + - "text/plain" + responses: + "200": + description: "no error" + schema: + description: "The node ID" + type: "string" + example: "7v2t30z9blmxuhnyo6s4cpenp" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is already part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmInitRequest" + properties: + ListenAddr: + description: | + Listen address used for inter-manager communication, as well + as determining the networking interface used for the VXLAN + Tunnel Endpoint (VTEP). This can either be an address/port + combination in the form `192.168.1.1:4567`, or an interface + followed by a port number, like `eth0:4567`. If the port number + is omitted, the default swarm listening port is used. + type: "string" + AdvertiseAddr: + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. + type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: + `<ip|interface>`), for example, `192.168.1.1`, or an interface, + like `eth0`. If `DataPathAddr` is unspecified, the same address + as `AdvertiseAddr` is used. + + The `DataPathAddr` specifies the address that global scope + network drivers will publish towards other nodes in order to + reach the containers running on this node. Using this parameter + it is possible to separate the container data traffic from the + management traffic of the cluster. + type: "string" + DataPathPort: + description: | + DataPathPort specifies the data path port number for data traffic. + Acceptable port range is 1024 to 49151. + if no port is set or is set to 0, default port 4789 will be used. + type: "integer" + format: "uint32" + DefaultAddrPool: + description: | + Default Address Pool specifies default subnet pools for global + scope networks. + type: "array" + items: + type: "string" + example: ["10.10.0.0/16", "20.20.0.0/16"] + ForceNewCluster: + description: "Force creation of a new swarm." + type: "boolean" + SubnetSize: + description: | + SubnetSize specifies the subnet size of the networks created + from the default subnet pool. + type: "integer" + format: "uint32" + Spec: + $ref: "#/definitions/SwarmSpec" + example: + ListenAddr: "0.0.0.0:2377" + AdvertiseAddr: "192.168.1.1:2377" + DataPathPort: 4789 + DefaultAddrPool: ["10.10.0.0/8", "20.20.0.0/8"] + SubnetSize: 24 + ForceNewCluster: false + Spec: + Orchestration: {} + Raft: {} + Dispatcher: {} + CAConfig: {} + EncryptionConfig: + AutoLockManagers: false + tags: ["Swarm"] + /swarm/join: + post: + summary: "Join an existing swarm" + operationId: "SwarmJoin" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is already part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmJoinRequest" + properties: + ListenAddr: + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. + type: "string" + AdvertiseAddr: + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. + type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: + `<ip|interface>`), for example, `192.168.1.1`, or an interface, + like `eth0`. If `DataPathAddr` is unspecified, the same address + as `AdvertiseAddr` is used. + + The `DataPathAddr` specifies the address that global scope + network drivers will publish towards other nodes in order to + reach the containers running on this node. Using this parameter + it is possible to separate the container data traffic from the + management traffic of the cluster. + + type: "string" + RemoteAddrs: + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" + JoinToken: + description: "Secret token for joining this swarm." + type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] + example: + ListenAddr: "0.0.0.0:2377" + AdvertiseAddr: "192.168.1.1:2377" + DataPathAddr: "192.168.1.1" + RemoteAddrs: + - "node1:2377" + JoinToken: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" + tags: ["Swarm"] + /swarm/leave: + post: + summary: "Leave a swarm" + operationId: "SwarmLeave" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "force" + description: | + Force leave swarm, even if this is the last manager or that it will + break the cluster. + in: "query" + type: "boolean" + default: false + tags: ["Swarm"] + /swarm/update: + post: + summary: "Update a swarm" + operationId: "SwarmUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + $ref: "#/definitions/SwarmSpec" + - name: "version" + in: "query" + description: | + The version number of the swarm object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + - name: "rotateWorkerToken" + in: "query" + description: "Rotate the worker join token." + type: "boolean" + default: false + - name: "rotateManagerToken" + in: "query" + description: "Rotate the manager join token." + type: "boolean" + default: false + - name: "rotateManagerUnlockKey" + in: "query" + description: "Rotate the manager unlock key." + type: "boolean" + default: false + tags: ["Swarm"] + /swarm/unlockkey: + get: + summary: "Get the unlock key" + operationId: "SwarmUnlockkey" + consumes: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "object" + title: "UnlockKeyResponse" + properties: + UnlockKey: + description: "The swarm's unlock key." + type: "string" + example: + UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /swarm/unlock: + post: + summary: "Unlock a locked manager" + operationId: "SwarmUnlock" + consumes: + - "application/json" + produces: + - "application/json" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmUnlockRequest" + properties: + UnlockKey: + description: "The swarm's unlock key." + type: "string" + example: + UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /services: + get: + summary: "List services" + operationId: "ServiceList" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Service" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the services list. + + Available filters: + + - `id=<service id>` + - `label=<service label>` + - `mode=["replicated"|"global"]` + - `name=<service name>` + - name: "status" + in: "query" + type: "boolean" + description: | + Include service status, with count of running and desired tasks. + tags: ["Service"] + /services/create: + post: + summary: "Create a service" + operationId: "ServiceCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/ServiceCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: "network is not eligible for services" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "name conflicts with an existing service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/ServiceSpec" + - type: "object" + example: + Name: "web" + TaskTemplate: + ContainerSpec: + Image: "nginx:alpine" + Mounts: + - + ReadOnly: true + Source: "web-data" + Target: "/usr/share/nginx/html" + Type: "volume" + VolumeOptions: + DriverConfig: {} + Labels: + com.example.something: "something-value" + Hosts: ["10.10.10.10 host1", "ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"] + User: "33" + DNSConfig: + Nameservers: ["8.8.8.8"] + Search: ["example.org"] + Options: ["timeout:3"] + Secrets: + - + File: + Name: "www.example.org.key" + UID: "33" + GID: "33" + Mode: 384 + SecretID: "fpjqlhnwb19zds35k8wn80lq9" + SecretName: "example_org_domain_key" + OomScoreAdj: 0 + LogDriver: + Name: "json-file" + Options: + max-file: "3" + max-size: "10M" + Placement: {} + Resources: + Limits: + MemoryBytes: 104857600 + Reservations: {} + RestartPolicy: + Condition: "on-failure" + Delay: 10000000000 + MaxAttempts: 10 + Mode: + Replicated: + Replicas: 4 + UpdateConfig: + Parallelism: 2 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Ports: + - + Protocol: "tcp" + PublishedPort: 8080 + TargetPort: 80 + Labels: + foo: "bar" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration for pulling from private + registries. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + tags: ["Service"] + /services/{id}: + get: + summary: "Inspect a service" + operationId: "ServiceInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Service" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + - name: "insertDefaults" + in: "query" + description: "Fill empty fields with default values." + type: "boolean" + default: false + tags: ["Service"] + delete: + summary: "Delete a service" + operationId: "ServiceDelete" + responses: + "200": + description: "no error" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + tags: ["Service"] + /services/{id}/update: + post: + summary: "Update a service" + operationId: "ServiceUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ServiceUpdateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + - name: "body" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/ServiceSpec" + - type: "object" + example: + Name: "top" + TaskTemplate: + ContainerSpec: + Image: "busybox" + Args: + - "top" + OomScoreAdj: 0 + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ForceUpdate: 0 + Mode: + Replicated: + Replicas: 1 + UpdateConfig: + Parallelism: 2 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Mode: "vip" + + - name: "version" + in: "query" + description: | + The version number of the service object being updated. This is + required to avoid conflicting writes. + This version number should be the value as currently set on the + service *before* the update. You can find the current version by + calling `GET /services/{id}` + required: true + type: "integer" + - name: "registryAuthFrom" + in: "query" + description: | + If the `X-Registry-Auth` header is not specified, this parameter + indicates where to find registry authorization credentials. + type: "string" + enum: ["spec", "previous-spec"] + default: "spec" + - name: "rollback" + in: "query" + description: | + Set to this parameter to `previous` to cause a server-side rollback + to the previous service spec. The supplied spec will be ignored in + this case. + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration for pulling from private + registries. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + + tags: ["Service"] + /services/{id}/logs: + get: + summary: "Get service logs" + description: | + Get `stdout` and `stderr` logs from a service. See also + [`/containers/{id}/logs`](#operation/ContainerLogs). + + **Note**: This endpoint works only for services with the `local`, + `json-file` or `journald` logging drivers. + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + operationId: "ServiceLogs" + responses: + "200": + description: "logs returned as a stream in response body" + schema: + type: "string" + format: "binary" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such service: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the service" + type: "string" + - name: "details" + in: "query" + description: "Show service context and extra details provided to logs." + type: "boolean" + default: false + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Service"] + /tasks: + get: + summary: "List tasks" + operationId: "TaskList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Task" + example: + - ID: "0kzzo1i0y4jz6027t0k7aezc7" + Version: + Index: 71 + CreatedAt: "2016-06-07T21:07:31.171892745Z" + UpdatedAt: "2016-06-07T21:07:31.376370513Z" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:31.290032978Z" + State: "running" + Message: "started" + ContainerStatus: + ContainerID: "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035" + PID: 677 + DesiredState: "running" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.10/16" + - ID: "1yljwbmlr8er2waf8orvqpwms" + Version: + Index: 30 + CreatedAt: "2016-06-07T21:07:30.019104782Z" + UpdatedAt: "2016-06-07T21:07:30.231958098Z" + Name: "hopeful_cori" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:30.202183143Z" + State: "shutdown" + Message: "shutdown" + ContainerStatus: + ContainerID: "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213" + DesiredState: "shutdown" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.5/16" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the tasks list. + + Available filters: + + - `desired-state=(running | shutdown | accepted)` + - `id=<task id>` + - `label=key` or `label="key=value"` + - `name=<task name>` + - `node=<node id or name>` + - `service=<service name>` + tags: ["Task"] + /tasks/{id}: + get: + summary: "Inspect a task" + operationId: "TaskInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Task" + "404": + description: "no such task" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID of the task" + required: true + type: "string" + tags: ["Task"] + /tasks/{id}/logs: + get: + summary: "Get task logs" + description: | + Get `stdout` and `stderr` logs from a task. + See also [`/containers/{id}/logs`](#operation/ContainerLogs). + + **Note**: This endpoint works only for services with the `local`, + `json-file` or `journald` logging drivers. + operationId: "TaskLogs" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "200": + description: "logs returned as a stream in response body" + schema: + type: "string" + format: "binary" + "404": + description: "no such task" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such task: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID of the task" + type: "string" + - name: "details" + in: "query" + description: "Show task context and extra details provided to logs." + type: "boolean" + default: false + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Task"] + /secrets: + get: + summary: "List secrets" + operationId: "SecretList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Secret" + example: + - ID: "blt1owaxmitz71s9v5zh81zun" + Version: + Index: 85 + CreatedAt: "2017-07-20T13:55:28.678958722Z" + UpdatedAt: "2017-07-20T13:55:28.678958722Z" + Spec: + Name: "mysql-passwd" + Labels: + some.label: "some.value" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + - ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + Labels: + foo: "bar" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the secrets list. + + Available filters: + + - `id=<secret id>` + - `label=<key> or label=<key>=value` + - `name=<secret name>` matches all or part of a secret name (prefix match) + - `names=<secret name>` matches a secret name (exact match) + tags: ["Secret"] + /secrets/create: + post: + summary: "Create a secret" + operationId: "SecretCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "409": + description: "name conflicts with an existing object" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + schema: + allOf: + - $ref: "#/definitions/SecretSpec" + - type: "object" + example: + Name: "app-key.crt" + Labels: + foo: "bar" + Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + tags: ["Secret"] + /secrets/{id}: + get: + summary: "Inspect a secret" + operationId: "SecretInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Secret" + examples: + application/json: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + Labels: + foo: "bar" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + + "404": + description: "secret not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the secret" + tags: ["Secret"] + delete: + summary: "Delete a secret" + operationId: "SecretDelete" + produces: + - "application/json" + responses: + "204": + description: "no error" + "404": + description: "secret not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the secret" + tags: ["Secret"] + /secrets/{id}/update: + post: + summary: "Update a Secret" + operationId: "SecretUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such secret" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the secret" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/SecretSpec" + description: | + The spec of the secret to update. Currently, only the Labels field + can be updated. All other fields must remain unchanged from the + [SecretInspect endpoint](#operation/SecretInspect) response values. + - name: "version" + in: "query" + description: | + The version number of the secret object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Secret"] + /configs: + get: + summary: "List configs" + operationId: "ConfigList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Config" + example: + - ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "server.conf" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the configs list. + + Available filters: + + - `id=<config id>` + - `label=<key> or label=<key>=value` + - `name=<config name>` matches all or part of a config name (prefix match) + tags: ["Config"] + /configs/create: + post: + summary: "Create a config" + operationId: "ConfigCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "409": + description: "name conflicts with an existing object" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + schema: + allOf: + - $ref: "#/definitions/ConfigSpec" + - type: "object" + example: + Name: "server.conf" + Labels: + foo: "bar" + Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + tags: ["Config"] + /configs/{id}: + get: + summary: "Inspect a config" + operationId: "ConfigInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Config" + examples: + application/json: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + "404": + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + delete: + summary: "Delete a config" + operationId: "ConfigDelete" + produces: + - "application/json" + responses: + "204": + description: "no error" + "404": + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + /configs/{id}/update: + post: + summary: "Update a Config" + operationId: "ConfigUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such config" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the config" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/ConfigSpec" + description: | + The spec of the config to update. Currently, only the Labels field + can be updated. All other fields must remain unchanged from the + [ConfigInspect endpoint](#operation/ConfigInspect) response values. + - name: "version" + in: "query" + description: | + The version number of the config object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Config"] + /distribution/{name}/json: + get: + summary: "Get image information from the registry" + description: | + Return image digest and platform information by contacting the registry. + operationId: "DistributionInspect" + produces: + - "application/json" + responses: + "200": + description: "descriptor and platform information" + schema: + $ref: "#/definitions/DistributionInspect" + "401": + description: "Failed authentication or no image found" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: someimage (tag: latest)" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + tags: ["Distribution"] + /session: + post: + summary: "Initialize interactive session" + description: | + Start a new interactive session with a server. Session allows server to + call back to the client for advanced capabilities. + + > **Deprecated**: This endpoint is deprecated and will be removed in a future version. + > Server should support gRPC directly on the listening socket. + + ### Hijacking + + This endpoint hijacks the HTTP connection to HTTP2 transport that allows + the client to expose gPRC services on that connection. + + For example, the client sends this request to upgrade the connection: + + ``` + POST /session HTTP/1.1 + Upgrade: h2c + Connection: Upgrade + ``` + + The Docker daemon responds with a `101 UPGRADED` response follow with + the raw stream: + + ``` + HTTP/1.1 101 UPGRADED + Connection: Upgrade + Upgrade: h2c + ``` + operationId: "Session" + produces: + - "application/vnd.docker.raw-stream" + responses: + "101": + description: "no error, hijacking successful" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Session"] diff --git a/_vendor/github.com/moby/moby/api/docs/v1.56.yaml b/_vendor/github.com/moby/moby/api/docs/v1.56.yaml new file mode 100644 index 000000000000..8c4d51989f7f --- /dev/null +++ b/_vendor/github.com/moby/moby/api/docs/v1.56.yaml @@ -0,0 +1,14089 @@ +# A Swagger 2.0 (a.k.a. OpenAPI) definition of the Engine API. +# +# This is used for generating API documentation and the types used by the +# client/server. See api/README.md for more information. +# +# Some style notes: +# - This file is used by ReDoc, which allows GitHub Flavored Markdown in +# descriptions. +# - There is no maximum line length, for ease of editing and pretty diffs. +# - operationIds are in the format "NounVerb", with a singular noun. + +swagger: "2.0" +schemes: + - "http" + - "https" +produces: + - "application/json" + - "text/plain" +consumes: + - "application/json" + - "text/plain" +basePath: "/v1.56" +info: + title: "Docker Engine API" + version: "1.56" + x-logo: + url: "https://docs.docker.com/assets/images/logo-docker-main.png" + description: | + The Engine API is an HTTP API served by Docker Engine. It is the API the + Docker client uses to communicate with the Engine, so everything the Docker + client can do can be done with the API. + + Most of the client's commands map directly to API endpoints (e.g. `docker ps` + is `GET /containers/json`). The notable exception is running containers, + which consists of several API calls. + + # Errors + + The API uses standard HTTP status codes to indicate the success or failure + of the API call. The body of the response will be JSON in the following + format: + + ``` + { + "message": "page not found" + } + ``` + + # Versioning + + The API is usually changed in each release, so API calls are versioned to + ensure that clients don't break. To lock to a specific version of the API, + you prefix the URL with its version, for example, call `/v1.30/info` to use + the v1.30 version of the `/info` endpoint. If the API version specified in + the URL is not supported by the daemon, a HTTP `400 Bad Request` error message + is returned. + + If you omit the version-prefix, the current version of the API is used. + For example, calling `/info` is the same as calling `/v1.56/info`. Using the + API without a version-prefix is deprecated and will be removed in a future release. + + Engine releases in the near future should support this version of the API, + so your client will continue to work even if it is talking to a newer Engine. + + The API uses an open schema model, which means the server may add extra properties + to responses. Likewise, the server will ignore any extra query parameters and + request body properties. When you write clients, you need to ignore additional + properties in responses to ensure they do not break when talking to newer + daemons. + + + # Authentication + + Authentication for registries is handled client side. The client has to send + authentication details to various endpoints that need to communicate with + registries, such as `POST /images/(name)/push`. These are sent as + `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) + (JSON) string with the following structure: + + ``` + { + "username": "string", + "password": "string", + "serveraddress": "string" + } + ``` + + The `serveraddress` is a domain/IP without a protocol. Throughout this + structure, double quotes are required. + + If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), + you can just pass this instead of credentials: + + ``` + { + "identitytoken": "9cbaf023786cd7..." + } + ``` + +# The tags on paths define the menu sections in the ReDoc documentation, so +# the usage of tags must make sense for that: +# - They should be singular, not plural. +# - There should not be too many tags, or the menu becomes unwieldy. For +# example, it is preferable to add a path to the "System" tag instead of +# creating a tag with a single path in it. +# - The order of tags in this list defines the order in the menu. +tags: + # Primary objects + - name: "Container" + x-displayName: "Containers" + description: | + Create and manage containers. + - name: "Image" + x-displayName: "Images" + - name: "Network" + x-displayName: "Networks" + description: | + Networks are user-defined networks that containers can be attached to. + See the [networking documentation](https://docs.docker.com/network/) + for more information. + - name: "Volume" + x-displayName: "Volumes" + description: | + Create and manage persistent storage that can be attached to containers. + - name: "Exec" + x-displayName: "Exec" + description: | + Run new commands inside running containers. Refer to the + [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) + for more information. + + To exec a command in a container, you first need to create an exec instance, + then start it. These two API endpoints are wrapped up in a single command-line + command, `docker exec`. + + # Swarm things + - name: "Swarm" + x-displayName: "Swarm" + description: | + Engines can be clustered together in a swarm. Refer to the + [swarm mode documentation](https://docs.docker.com/engine/swarm/) + for more information. + - name: "Node" + x-displayName: "Nodes" + description: | + Nodes are instances of the Engine participating in a swarm. Swarm mode + must be enabled for these endpoints to work. + - name: "Service" + x-displayName: "Services" + description: | + Services are the definitions of tasks to run on a swarm. Swarm mode must + be enabled for these endpoints to work. + - name: "Task" + x-displayName: "Tasks" + description: | + A task is a container running on a swarm. It is the atomic scheduling unit + of swarm. Swarm mode must be enabled for these endpoints to work. + - name: "Secret" + x-displayName: "Secrets" + description: | + Secrets are sensitive data that can be used by services. Swarm mode must + be enabled for these endpoints to work. + - name: "Config" + x-displayName: "Configs" + description: | + Configs are application configurations that can be used by services. Swarm + mode must be enabled for these endpoints to work. + # System things + - name: "Plugin" + x-displayName: "Plugins" + - name: "System" + x-displayName: "System" + +definitions: + ImageHistoryResponseItem: + type: "object" + x-go-name: HistoryResponseItem + title: "HistoryResponseItem" + description: "individual image layer information in response to ImageHistory operation" + required: [Id, Created, CreatedBy, Tags, Size, Comment] + properties: + Id: + type: "string" + x-nullable: false + Created: + type: "integer" + format: "int64" + x-nullable: false + CreatedBy: + type: "string" + x-nullable: false + Tags: + type: "array" + items: + type: "string" + Size: + type: "integer" + format: "int64" + x-nullable: false + Comment: + type: "string" + x-nullable: false + PortSummary: + type: "object" + description: | + Describes a port-mapping between the container and the host. + required: [PrivatePort, Type] + properties: + IP: + type: "string" + format: "ip-address" + description: "Host IP address that the container's port is mapped to" + x-go-type: + type: Addr + import: + package: net/netip + PrivatePort: + type: "integer" + format: "uint16" + x-nullable: false + description: "Port on the container" + PublicPort: + type: "integer" + format: "uint16" + description: "Port exposed on the host" + Type: + type: "string" + x-nullable: false + enum: ["tcp", "udp", "sctp"] + example: + PrivatePort: 8080 + PublicPort: 80 + Type: "tcp" + + MountType: + description: |- + The mount type. Available types: + + - `bind` a mount of a file or directory from the host into the container. + - `cluster` a Swarm cluster volume. + - `image` an OCI image. + - `npipe` a named pipe from the host into the container. + - `tmpfs` a `tmpfs`. + - `volume` a docker volume with the given `Name`. + type: "string" + enum: + - "bind" + - "cluster" + - "image" + - "npipe" + - "tmpfs" + - "volume" + example: "volume" + + MountPoint: + type: "object" + description: | + MountPoint represents a mount point configuration inside the container. + This is used for reporting the mountpoints in use by a container. + properties: + Type: + description: | + The mount type: + + - `bind` a mount of a file or directory from the host into the container. + - `cluster` a Swarm cluster volume. + - `image` an OCI image. + - `npipe` a named pipe from the host into the container. + - `tmpfs` a `tmpfs`. + - `volume` a docker volume with the given `Name`. + allOf: + - $ref: "#/definitions/MountType" + example: "volume" + Name: + description: | + Name is the name reference to the underlying data defined by `Source` + e.g., the volume name. + type: "string" + example: "myvolume" + Source: + description: | + Source location of the mount. + + For volumes, this contains the storage location of the volume (within + `/var/lib/docker/volumes/`). For bind-mounts, and `npipe`, this contains + the source (host) part of the bind-mount. For `tmpfs` mount points, this + field is empty. + type: "string" + example: "/var/lib/docker/volumes/myvolume/_data" + Destination: + description: | + Destination is the path relative to the container root (`/`) where + the `Source` is mounted inside the container. + type: "string" + example: "/usr/share/nginx/html/" + Driver: + description: | + Driver is the volume driver used to create the volume (if it is a volume). + type: "string" + example: "local" + Mode: + description: | + Mode is a comma separated list of options supplied by the user when + creating the bind/volume mount. + + The default is platform-specific (`"z"` on Linux, empty on Windows). + type: "string" + example: "z" + RW: + description: | + Whether the mount is mounted writable (read-write). + type: "boolean" + example: true + Propagation: + description: | + Propagation describes how mounts are propagated from the host into the + mount point, and vice-versa. Refer to the [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) + for details. This field is not used on Windows. + type: "string" + example: "" + + DeviceMapping: + type: "object" + description: "A device mapping between the host and container" + properties: + PathOnHost: + type: "string" + PathInContainer: + type: "string" + CgroupPermissions: + type: "string" + example: + PathOnHost: "/dev/deviceName" + PathInContainer: "/dev/deviceName" + CgroupPermissions: "mrw" + + DeviceRequest: + type: "object" + description: "A request for devices to be sent to device drivers" + properties: + Driver: + description: | + The name of the device driver to use for this request. + + Note that if this is specified the capabilities are ignored when + selecting a device driver. + type: "string" + example: "nvidia" + Count: + type: "integer" + example: -1 + DeviceIDs: + type: "array" + items: + type: "string" + example: + - "0" + - "1" + - "GPU-fef8089b-4820-abfc-e83e-94318197576e" + Capabilities: + description: | + A list of capabilities; an OR list of AND lists of capabilities. + + Note that if a driver is specified the capabilities have no effect on + selecting a driver as the driver name is used directly. + + Note that if no driver is specified the capabilities are used to + select a driver with the required capabilities. + type: "array" + items: + type: "array" + items: + type: "string" + example: + # gpu AND nvidia AND compute + - ["gpu", "nvidia", "compute"] + Options: + description: | + Driver-specific options, specified as a key/value pairs. These options + are passed directly to the driver. + type: "object" + additionalProperties: + type: "string" + + ThrottleDevice: + type: "object" + properties: + Path: + description: "Device path" + type: "string" + Rate: + description: "Rate" + type: "integer" + format: "int64" + minimum: 0 + + Mount: + type: "object" + properties: + Target: + description: "Container path." + type: "string" + Source: + description: |- + Mount source (e.g. a volume name, a host path). The source cannot be + specified when using `Type=tmpfs`. For `Type=bind`, the source path + must either exist, or the `CreateMountpoint` must be set to `true` to + create the source path on the host if missing. + + For `Type=npipe`, the pipe must exist prior to creating the container. + type: "string" + Type: + description: | + The mount type. Available types: + + - `bind` Mounts a file or directory from the host into the container. The `Source` must exist prior to creating the container. + - `cluster` a Swarm cluster volume + - `image` Mounts an image. + - `npipe` Mounts a named pipe from the host into the container. The `Source` must exist prior to creating the container. + - `tmpfs` Create a tmpfs with the given options. The mount `Source` cannot be specified for tmpfs. + - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed. + allOf: + - $ref: "#/definitions/MountType" + ReadOnly: + description: "Whether the mount should be read-only." + type: "boolean" + Consistency: + description: "The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`." + type: "string" + BindOptions: + description: "Optional configuration for the `bind` type." + type: "object" + properties: + Propagation: + description: "A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`." + type: "string" + enum: + - "private" + - "rprivate" + - "shared" + - "rshared" + - "slave" + - "rslave" + NonRecursive: + description: "Disable recursive bind mount." + type: "boolean" + default: false + CreateMountpoint: + description: "Create mount point on host if missing" + type: "boolean" + default: false + ReadOnlyNonRecursive: + description: | + Make the mount non-recursively read-only, but still leave the mount recursive + (unless NonRecursive is set to `true` in conjunction). + + Added in v1.44, before that version all read-only mounts were + non-recursive by default. To match the previous behaviour this + will default to `true` for clients on versions prior to v1.44. + type: "boolean" + default: false + ReadOnlyForceRecursive: + description: "Raise an error if the mount cannot be made recursively read-only." + type: "boolean" + default: false + VolumeOptions: + description: "Optional configuration for the `volume` type." + type: "object" + properties: + NoCopy: + description: "Populate volume with data from the target." + type: "boolean" + default: false + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + DriverConfig: + description: "Map of driver specific options" + type: "object" + properties: + Name: + description: "Name of the driver to use to create the volume." + type: "string" + Options: + description: "key/value map of driver specific options." + type: "object" + additionalProperties: + type: "string" + Subpath: + description: "Source path inside the volume. Must be relative without any back traversals." + type: "string" + example: "dir-inside-volume/subdirectory" + ImageOptions: + description: "Optional configuration for the `image` type." + type: "object" + properties: + Subpath: + description: "Source path inside the image. Must be relative without any back traversals." + type: "string" + example: "dir-inside-image/subdirectory" + TmpfsOptions: + description: "Optional configuration for the `tmpfs` type." + type: "object" + properties: + SizeBytes: + description: "The size for the tmpfs mount in bytes." + type: "integer" + format: "int64" + Mode: + description: | + The permission mode for the tmpfs mount in an integer. + The value must not be in octal format (e.g. 755) but rather + the decimal representation of the octal value (e.g. 493). + type: "integer" + Options: + description: | + The options to be passed to the tmpfs mount. An array of arrays. + Flag options should be provided as 1-length arrays. Other types + should be provided as as 2-length arrays, where the first item is + the key and the second the value. + type: "array" + items: + type: "array" + minItems: 1 + maxItems: 2 + items: + type: "string" + example: + [["noexec"]] + + RestartPolicy: + description: | + The behavior to apply when the container exits. The default is not to + restart. + + An ever increasing delay (double the previous delay, starting at 100ms) is + added before each restart to prevent flooding the server. + type: "object" + properties: + Name: + type: "string" + description: | + - Empty string means not to restart + - `no` Do not automatically restart + - `always` Always restart + - `unless-stopped` Restart always except when the user has manually stopped the container + - `on-failure` Restart only when the container exit code is non-zero + enum: + - "" + - "no" + - "always" + - "unless-stopped" + - "on-failure" + MaximumRetryCount: + type: "integer" + description: | + If `on-failure` is used, the number of times to retry before giving up. + + Resources: + description: "A container's resources (cgroups config, ulimits, etc)" + type: "object" + properties: + # Applicable to all platforms + CpuShares: + description: | + An integer value representing this container's relative CPU weight + versus other containers. + type: "integer" + Memory: + description: "Memory limit in bytes." + type: "integer" + format: "int64" + default: 0 + # Applicable to UNIX platforms + CgroupParent: + description: | + Path to `cgroups` under which the container's `cgroup` is created. If + the path is not absolute, the path is considered to be relative to the + `cgroups` path of the init process. Cgroups are created if they do not + already exist. + type: "string" + BlkioWeight: + description: "Block IO weight (relative weight)." + type: "integer" + minimum: 0 + maximum: 1000 + BlkioWeightDevice: + description: | + Block IO weight (relative device weight) in the form: + + ``` + [{"Path": "device_path", "Weight": weight}] + ``` + type: "array" + items: + type: "object" + properties: + Path: + type: "string" + Weight: + type: "integer" + minimum: 0 + BlkioDeviceReadBps: + description: | + Limit read rate (bytes per second) from a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceWriteBps: + description: | + Limit write rate (bytes per second) to a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceReadIOps: + description: | + Limit read rate (IO per second) from a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + BlkioDeviceWriteIOps: + description: | + Limit write rate (IO per second) to a device, in the form: + + ``` + [{"Path": "device_path", "Rate": rate}] + ``` + type: "array" + items: + $ref: "#/definitions/ThrottleDevice" + CpuPeriod: + description: "The length of a CPU period in microseconds." + type: "integer" + format: "int64" + CpuQuota: + description: | + Microseconds of CPU time that the container can get in a CPU period. + type: "integer" + format: "int64" + CpuRealtimePeriod: + description: | + The length of a CPU real-time period in microseconds. Set to 0 to + allocate no time allocated to real-time tasks. + type: "integer" + format: "int64" + CpuRealtimeRuntime: + description: | + The length of a CPU real-time runtime in microseconds. Set to 0 to + allocate no time allocated to real-time tasks. + type: "integer" + format: "int64" + CpusetCpus: + description: | + CPUs in which to allow execution (e.g., `0-3`, `0,1`). + type: "string" + example: "0-3" + CpusetMems: + description: | + Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only + effective on NUMA systems. + type: "string" + Devices: + description: "A list of devices to add to the container." + type: "array" + items: + $ref: "#/definitions/DeviceMapping" + DeviceCgroupRules: + description: "a list of cgroup rules to apply to the container" + type: "array" + items: + type: "string" + example: "c 13:* rwm" + DeviceRequests: + description: | + A list of requests for devices to be sent to device drivers. + type: "array" + items: + $ref: "#/definitions/DeviceRequest" + MemoryReservation: + description: "Memory soft limit in bytes." + type: "integer" + format: "int64" + MemorySwap: + description: | + Total memory limit (memory + swap). Set as `-1` to enable unlimited + swap. + type: "integer" + format: "int64" + MemorySwappiness: + description: | + Tune a container's memory swappiness behavior. Accepts an integer + between 0 and 100. + type: "integer" + format: "int64" + minimum: 0 + maximum: 100 + NanoCpus: + description: "CPU quota in units of 10<sup>-9</sup> CPUs." + type: "integer" + format: "int64" + OomKillDisable: + description: "Disable OOM Killer for the container." + type: "boolean" + Init: + description: | + Run an init inside the container that forwards signals and reaps + processes. This field is omitted if empty, and the default (as + configured on the daemon) is used. + type: "boolean" + x-nullable: true + PidsLimit: + description: | + Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` + to not change. + type: "integer" + format: "int64" + x-nullable: true + Ulimits: + description: | + A list of resource limits to set in the container. For example: + + ``` + {"Name": "nofile", "Soft": 1024, "Hard": 2048} + ``` + type: "array" + items: + type: "object" + properties: + Name: + description: "Name of ulimit" + type: "string" + Soft: + description: "Soft limit" + type: "integer" + Hard: + description: "Hard limit" + type: "integer" + # Applicable to Windows + CpuCount: + description: | + The number of usable CPUs (Windows only). + + On Windows Server containers, the processor resource controls are + mutually exclusive. The order of precedence is `CPUCount` first, then + `CPUShares`, and `CPUPercent` last. + type: "integer" + format: "int64" + CpuPercent: + description: | + The usable percentage of the available CPUs (Windows only). + + On Windows Server containers, the processor resource controls are + mutually exclusive. The order of precedence is `CPUCount` first, then + `CPUShares`, and `CPUPercent` last. + type: "integer" + format: "int64" + IOMaximumIOps: + description: "Maximum IOps for the container system drive (Windows only)" + type: "integer" + format: "int64" + IOMaximumBandwidth: + description: | + Maximum IO in bytes per second for the container system drive + (Windows only). + type: "integer" + format: "int64" + + Limit: + description: | + An object describing a limit on resources which can be requested by a task. + type: "object" + properties: + NanoCPUs: + type: "integer" + format: "int64" + example: 4000000000 + MemoryBytes: + type: "integer" + format: "int64" + example: 8272408576 + Pids: + description: | + Limits the maximum number of PIDs in the container. Set `0` for unlimited. + type: "integer" + format: "int64" + default: 0 + example: 100 + + ResourceObject: + description: | + An object describing the resources which can be advertised by a node and + requested by a task. + type: "object" + properties: + NanoCPUs: + type: "integer" + format: "int64" + example: 4000000000 + MemoryBytes: + type: "integer" + format: "int64" + example: 8272408576 + GenericResources: + $ref: "#/definitions/GenericResources" + + GenericResources: + description: | + User-defined resources can be either Integer resources (e.g, `SSD=3`) or + String resources (e.g, `GPU=UUID1`). + type: "array" + items: + type: "object" + properties: + NamedResourceSpec: + type: "object" + properties: + Kind: + type: "string" + Value: + type: "string" + DiscreteResourceSpec: + type: "object" + properties: + Kind: + type: "string" + Value: + type: "integer" + format: "int64" + example: + - DiscreteResourceSpec: + Kind: "SSD" + Value: 3 + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID1" + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID2" + + HealthConfig: + description: | + A test to perform to check that the container is healthy. + Healthcheck commands should be side-effect free. + type: "object" + properties: + Test: + description: | + The test to perform. Possible values are: + + - `[]` inherit healthcheck from image or parent image + - `["NONE"]` disable healthcheck + - `["CMD", args...]` exec arguments directly + - `["CMD-SHELL", command]` run command with system's default shell + + A non-zero exit code indicates a failed healthcheck: + - `0` healthy + - `1` unhealthy + - `2` reserved (treated as unhealthy) + - other values: error running probe + type: "array" + items: + type: "string" + Interval: + description: | + The time to wait between checks in nanoseconds. It should be 0 or at + least 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + Timeout: + description: | + The time to wait before considering the check to have hung. It should + be 0 or at least 1000000 (1 ms). 0 means inherit. + + If the health check command does not complete within this timeout, + the check is considered failed and the health check process is + forcibly terminated without a graceful shutdown. + type: "integer" + format: "int64" + Retries: + description: | + The number of consecutive failures needed to consider a container as + unhealthy. 0 means inherit. + type: "integer" + StartPeriod: + description: | + Start period for the container to initialize before starting + health-retries countdown in nanoseconds. It should be 0 or at least + 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + StartInterval: + description: | + The time to wait between checks in nanoseconds during the start period. + It should be 0 or at least 1000000 (1 ms). 0 means inherit. + type: "integer" + format: "int64" + + Health: + description: | + Health stores information about the container's healthcheck results. + type: "object" + x-nullable: true + properties: + Status: + description: | + Status is one of `none`, `starting`, `healthy` or `unhealthy` + + - "none" Indicates there is no healthcheck + - "starting" Starting indicates that the container is not yet ready + - "healthy" Healthy indicates that the container is running correctly + - "unhealthy" Unhealthy indicates that the container has a problem + type: "string" + enum: + - "none" + - "starting" + - "healthy" + - "unhealthy" + example: "healthy" + FailingStreak: + description: "FailingStreak is the number of consecutive failures" + type: "integer" + example: 0 + Log: + type: "array" + description: | + Log contains the last few results (oldest first) + items: + $ref: "#/definitions/HealthcheckResult" + + HealthcheckResult: + description: | + HealthcheckResult stores information about a single run of a healthcheck probe + type: "object" + x-nullable: true + properties: + Start: + description: | + Date and time at which this check started in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "date-time" + example: "2020-01-04T10:44:24.496525531Z" + End: + description: | + Date and time at which this check ended in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2020-01-04T10:45:21.364524523Z" + ExitCode: + description: | + ExitCode meanings: + + - `0` healthy + - `1` unhealthy + - `2` reserved (considered unhealthy) + - other values: error running probe + type: "integer" + example: 0 + Output: + description: "Output from last check" + type: "string" + + HostConfig: + description: "Container configuration that depends on the host we are running on" + allOf: + - $ref: "#/definitions/Resources" + - type: "object" + properties: + # Applicable to all platforms + Binds: + type: "array" + description: | + A list of volume bindings for this container. Each volume binding + is a string in one of these forms: + + - `host-src:container-dest[:options]` to bind-mount a host path + into the container. Both `host-src`, and `container-dest` must + be an _absolute_ path. + - `volume-name:container-dest[:options]` to bind-mount a volume + managed by a volume driver into the container. `container-dest` + must be an _absolute_ path. + + `options` is an optional, comma-delimited list of: + + - `nocopy` disables automatic copying of data from the container + path to the volume. The `nocopy` flag only applies to named volumes. + - `[ro|rw]` mounts a volume read-only or read-write, respectively. + If omitted or set to `rw`, volumes are mounted read-write. + - `[z|Z]` applies SELinux labels to allow or deny multiple containers + to read and write to the same volume. + - `z`: a _shared_ content label is applied to the content. This + label indicates that multiple containers can share the volume + content, for both reading and writing. + - `Z`: a _private unshared_ label is applied to the content. + This label indicates that only the current container can use + a private volume. Labeling systems such as SELinux require + proper labels to be placed on volume content that is mounted + into a container. Without a label, the security system can + prevent a container's processes from using the content. By + default, the labels set by the host operating system are not + modified. + - `[[r]shared|[r]slave|[r]private]` specifies mount + [propagation behavior](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). + This only applies to bind-mounted volumes, not internal volumes + or named volumes. Mount propagation requires the source mount + point (the location where the source directory is mounted in the + host operating system) to have the correct propagation properties. + For shared volumes, the source mount point must be set to `shared`. + For slave volumes, the mount must be set to either `shared` or + `slave`. + items: + type: "string" + ContainerIDFile: + type: "string" + description: "Path to a file where the container ID is written" + example: "" + LogConfig: + type: "object" + description: "The logging configuration for this container" + properties: + Type: + description: |- + Name of the logging driver used for the container or "none" + if logging is disabled. + type: "string" + enum: + - "local" + - "json-file" + - "syslog" + - "journald" + - "gelf" + - "fluentd" + - "awslogs" + - "splunk" + - "etwlogs" + - "none" + Config: + description: |- + Driver-specific configuration options for the logging driver. + type: "object" + additionalProperties: + type: "string" + example: + "max-file": "5" + "max-size": "10m" + NetworkMode: + type: "string" + description: | + Network mode to use for this container. Supported standard values + are: `bridge`, `host`, `none`, and `container:<name|id>`. Any + other value is taken as a custom network's name to which this + container should connect to. + PortBindings: + $ref: "#/definitions/PortMap" + RestartPolicy: + $ref: "#/definitions/RestartPolicy" + AutoRemove: + type: "boolean" + description: | + Automatically remove the container when the container's process + exits. This has no effect if `RestartPolicy` is set. + VolumeDriver: + type: "string" + description: "Driver that this container uses to mount volumes." + VolumesFrom: + type: "array" + description: | + A list of volumes to inherit from another container, specified in + the form `<container name>[:<ro|rw>]`. + items: + type: "string" + Mounts: + description: | + Specification for mounts to be added to the container. + type: "array" + items: + $ref: "#/definitions/Mount" + ConsoleSize: + type: "array" + description: | + Initial console size, as an `[height, width]` array. + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + Annotations: + type: "object" + description: | + Arbitrary non-identifying metadata attached to container and + provided to the runtime when the container is started. + additionalProperties: + type: "string" + + # Applicable to UNIX platforms + CapAdd: + type: "array" + description: | + A list of kernel capabilities to add to the container. Conflicts + with option 'Capabilities'. + items: + type: "string" + CapDrop: + type: "array" + description: | + A list of kernel capabilities to drop from the container. Conflicts + with option 'Capabilities'. + items: + type: "string" + CgroupnsMode: + type: "string" + enum: + - "private" + - "host" + description: | + cgroup namespace mode for the container. Possible values are: + + - `"private"`: the container runs in its own private cgroup namespace + - `"host"`: use the host system's cgroup namespace + + If not specified, the daemon default is used, which can either be `"private"` + or `"host"`, depending on daemon version, kernel support and configuration. + Dns: + type: "array" + description: "A list of DNS servers for the container to use." + items: + type: "string" + format: "ip-address" + x-go-type: + type: Addr + import: + package: net/netip + DnsOptions: + type: "array" + description: "A list of DNS options." + items: + type: "string" + DnsSearch: + type: "array" + description: "A list of DNS search domains." + items: + type: "string" + ExtraHosts: + type: "array" + description: | + A list of hostnames/IP mappings to add to the container's `/etc/hosts` + file. Specified in the form `["hostname:IP"]`. + items: + type: "string" + GroupAdd: + type: "array" + description: | + A list of additional groups that the container process will run as. + items: + type: "string" + IpcMode: + type: "string" + description: | + IPC sharing mode for the container. Possible values are: + + - `"none"`: own private IPC namespace, with /dev/shm not mounted + - `"private"`: own private IPC namespace + - `"shareable"`: own private IPC namespace, with a possibility to share it with other containers + - `"container:<name|id>"`: join another (shareable) container's IPC namespace + - `"host"`: use the host system's IPC namespace + + If not specified, daemon default is used, which can either be `"private"` + or `"shareable"`, depending on daemon version and configuration. + Cgroup: + type: "string" + description: "Cgroup to use for the container." + Links: + type: "array" + description: | + A list of links for the container in the form `container_name:alias`. + items: + type: "string" + OomScoreAdj: + type: "integer" + description: | + An integer value containing the score given to the container in + order to tune OOM killer preferences. + example: 500 + PidMode: + type: "string" + description: | + Set the PID (Process) Namespace mode for the container. It can be + either: + + - `"container:<name|id>"`: joins another container's PID namespace + - `"host"`: use the host's PID namespace inside the container + Privileged: + type: "boolean" + description: |- + Gives the container full access to the host. + PublishAllPorts: + type: "boolean" + description: | + Allocates an ephemeral host port for all of a container's + exposed ports. + + Ports are de-allocated when the container stops and allocated when + the container starts. The allocated port might be changed when + restarting the container. + + The port is selected from the ephemeral port range that depends on + the kernel. For example, on Linux the range is defined by + `/proc/sys/net/ipv4/ip_local_port_range`. + ReadonlyRootfs: + type: "boolean" + description: "Mount the container's root filesystem as read only." + SecurityOpt: + type: "array" + description: | + A list of string values to customize labels for MLS systems, such + as SELinux. + items: + type: "string" + StorageOpt: + type: "object" + description: | + Storage driver options for this container, in the form `{"size": "120G"}`. + additionalProperties: + type: "string" + Tmpfs: + type: "object" + description: | + A map of container directories which should be replaced by tmpfs + mounts, and their corresponding mount options. For example: + + ``` + { "/run": "rw,noexec,nosuid,size=65536k" } + ``` + additionalProperties: + type: "string" + UTSMode: + type: "string" + description: "UTS namespace to use for the container." + UsernsMode: + type: "string" + description: | + Sets the usernamespace mode for the container when usernamespace + remapping option is enabled. + ShmSize: + type: "integer" + format: "int64" + description: | + Size of `/dev/shm` in bytes. If omitted, the system uses 64MB. + minimum: 0 + Sysctls: + type: "object" + x-nullable: true + description: |- + A list of kernel parameters (sysctls) to set in the container. + + This field is omitted if not set. + additionalProperties: + type: "string" + example: + "net.ipv4.ip_forward": "1" + Runtime: + type: "string" + x-nullable: true + description: |- + Runtime to use with this container. + Umask: + type: "integer" + format: "uint32" + x-nullable: true + description: |- + Set the initial umask for a Unix container. + + If omitted, the daemon does not set a umask in the OCI process + specification, and the runtime's default behavior applies. + + JSON integers are decimal. For example, use `18` for the octal + umask `0022`, and `511` for the octal umask `0777`. + # Applicable to Windows + Isolation: + type: "string" + description: | + Isolation technology of the container. (Windows only) + enum: + - "default" + - "process" + - "hyperv" + - "" + MaskedPaths: + type: "array" + description: | + The list of paths to be masked inside the container (this overrides + the default set of paths). + items: + type: "string" + example: + - "/proc/asound" + - "/proc/acpi" + - "/proc/kcore" + - "/proc/keys" + - "/proc/latency_stats" + - "/proc/timer_list" + - "/proc/timer_stats" + - "/proc/sched_debug" + - "/proc/scsi" + - "/sys/firmware" + - "/sys/devices/virtual/powercap" + ReadonlyPaths: + type: "array" + description: | + The list of paths to be set as read-only inside the container + (this overrides the default set of paths). + items: + type: "string" + example: + - "/proc/bus" + - "/proc/fs" + - "/proc/irq" + - "/proc/sys" + - "/proc/sysrq-trigger" + + ContainerConfig: + description: | + Configuration for a container that is portable between hosts. + type: "object" + properties: + Hostname: + description: | + The hostname to use for the container, as a valid RFC 1123 hostname. + type: "string" + example: "439f4e91bd1d" + Domainname: + description: | + The domain name to use for the container. + type: "string" + User: + description: |- + Commands run as this user inside the container. If omitted, commands + run as the user specified in the image the container was started from. + + Can be either user-name or UID, and optional group-name or GID, + separated by a colon (`<user-name|UID>[<:group-name|GID>]`). + type: "string" + example: "123:456" + AttachStdin: + description: "Whether to attach to `stdin`." + type: "boolean" + default: false + AttachStdout: + description: "Whether to attach to `stdout`." + type: "boolean" + default: true + AttachStderr: + description: "Whether to attach to `stderr`." + type: "boolean" + default: true + ExposedPorts: + description: | + An object mapping ports to an empty object in the form: + + `{"<port>/<tcp|udp|sctp>": {}}` + type: "object" + x-nullable: true + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "80/tcp": {} + "443/tcp": {} + Tty: + description: | + Attach standard streams to a TTY, including `stdin` if it is not closed. + type: "boolean" + default: false + OpenStdin: + description: "Open `stdin`" + type: "boolean" + default: false + StdinOnce: + description: "Close `stdin` after one attached client disconnects" + type: "boolean" + default: false + Env: + description: | + A list of environment variables to set inside the container in the + form `["VAR=value", ...]`. A variable without `=` is removed from the + environment, rather than to have an empty value. + type: "array" + items: + type: "string" + example: + - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + Cmd: + description: | + Command to run specified as a string or an array of strings. + type: "array" + items: + type: "string" + example: ["/bin/sh"] + Healthcheck: + $ref: "#/definitions/HealthConfig" + ArgsEscaped: + description: "Command is already escaped (Windows only)" + type: "boolean" + default: false + example: false + x-nullable: true + Image: + description: | + The name (or reference) of the image to use when creating the container, + or which was used when the container was created. + type: "string" + example: "example-image:1.0" + Volumes: + description: | + An object mapping mount point paths inside the container to empty + objects. + type: "object" + additionalProperties: + type: "object" + enum: + - {} + default: {} + WorkingDir: + description: "The working directory for commands to run in." + type: "string" + example: "/public/" + Entrypoint: + description: | + The entry point for the container as a string or an array of strings. + + If the array consists of exactly one empty string (`[""]`) then the + entry point is reset to system default (i.e., the entry point used by + docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). + type: "array" + items: + type: "string" + example: [] + NetworkDisabled: + description: "Disable networking for the container." + type: "boolean" + x-nullable: true + OnBuild: + description: | + `ONBUILD` metadata that were defined in the image's `Dockerfile`. + type: "array" + x-nullable: true + items: + type: "string" + example: [] + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + StopSignal: + description: | + Signal to stop a container as a string or unsigned integer. + type: "string" + example: "SIGTERM" + x-nullable: true + StopTimeout: + description: | + Timeout to stop a container in seconds. If omitted, the daemon-wide + default (`default-stop-timeout`) is used. + type: "integer" + x-nullable: true + Shell: + description: | + Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. + type: "array" + x-nullable: true + items: + type: "string" + example: ["/bin/sh", "-c"] + + ImageConfig: + description: | + Configuration of the image. These fields are used as defaults + when starting a container from the image. + type: "object" + properties: + User: + description: "The user that commands are run as inside the container." + type: "string" + example: "web:web" + ExposedPorts: + description: | + An object mapping ports to an empty object in the form: + + `{"<port>/<tcp|udp|sctp>": {}}` + type: "object" + x-nullable: true + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "80/tcp": {} + "443/tcp": {} + Env: + description: | + A list of environment variables to set inside the container in the + form `["VAR=value", ...]`. A variable without `=` is removed from the + environment, rather than to have an empty value. + type: "array" + items: + type: "string" + example: + - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + Cmd: + description: | + Command to run specified as a string or an array of strings. + type: "array" + items: + type: "string" + example: ["/bin/sh"] + Healthcheck: + $ref: "#/definitions/HealthConfig" + ArgsEscaped: + description: "Command is already escaped (Windows only)" + type: "boolean" + default: false + example: false + x-nullable: true + Volumes: + description: | + An object mapping mount point paths inside the container to empty + objects. + type: "object" + additionalProperties: + type: "object" + enum: + - {} + default: {} + example: + "/app/data": {} + "/app/config": {} + WorkingDir: + description: "The working directory for commands to run in." + type: "string" + example: "/public/" + Entrypoint: + description: | + The entry point for the container as a string or an array of strings. + + If the array consists of exactly one empty string (`[""]`) then the + entry point is reset to system default (i.e., the entry point used by + docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). + type: "array" + items: + type: "string" + example: [] + OnBuild: + description: | + `ONBUILD` metadata that were defined in the image's `Dockerfile`. + type: "array" + x-nullable: true + items: + type: "string" + example: [] + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + StopSignal: + description: | + Signal to stop a container as a string or unsigned integer. + type: "string" + example: "SIGTERM" + x-nullable: true + Shell: + description: | + Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. + type: "array" + x-nullable: true + items: + type: "string" + example: ["/bin/sh", "-c"] + + NetworkingConfig: + description: | + NetworkingConfig represents the container's networking configuration for + each of its interfaces. + It is used for the networking configs specified in the `docker create` + and `docker network connect` commands. + type: "object" + properties: + EndpointsConfig: + description: | + A mapping of network name to endpoint configuration for that network. + The endpoint configuration can be left empty to connect to that + network with no particular endpoint configuration. + type: "object" + additionalProperties: + $ref: "#/definitions/EndpointSettings" + example: + # putting an example here, instead of using the example values from + # /definitions/EndpointSettings, because EndpointSettings contains + # operational data returned when inspecting a container that we don't + # accept here. + EndpointsConfig: + isolated_nw: + IPAMConfig: + IPv4Address: "172.20.30.33" + IPv6Address: "2001:db8:abcd::3033" + LinkLocalIPs: + - "169.254.34.68" + - "fe80::3468" + MacAddress: "02:42:ac:12:05:02" + Links: + - "container_1" + - "container_2" + Aliases: + - "server_x" + - "server_y" + database_nw: {} + + NetworkSettings: + description: "NetworkSettings exposes the network settings in the API" + type: "object" + properties: + SandboxID: + description: SandboxID uniquely represents a container's network stack. + type: "string" + example: "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3" + SandboxKey: + description: SandboxKey is the full path of the netns handle + type: "string" + example: "/var/run/docker/netns/8ab54b426c38" + Ports: + $ref: "#/definitions/PortMap" + Networks: + description: | + Information about all networks that the container is connected to. + type: "object" + additionalProperties: + $ref: "#/definitions/EndpointSettings" + + Address: + description: Address represents an IPv4 or IPv6 IP address. + type: "object" + properties: + Addr: + description: IP address. + type: "string" + PrefixLen: + description: Mask length of the IP address. + type: "integer" + + PortMap: + description: | + PortMap describes the mapping of container ports to host ports, using the + container's port-number and protocol as key in the format `<port>/<protocol>`, + for example, `80/udp`. + + If a container's port is mapped for multiple protocols, separate entries + are added to the mapping table. + type: "object" + additionalProperties: + type: "array" + x-nullable: true + items: + $ref: "#/definitions/PortBinding" + example: + "443/tcp": + - HostIp: "127.0.0.1" + HostPort: "4443" + "80/tcp": + - HostIp: "0.0.0.0" + HostPort: "80" + - HostIp: "0.0.0.0" + HostPort: "8080" + "80/udp": + - HostIp: "0.0.0.0" + HostPort: "80" + "53/udp": + - HostIp: "0.0.0.0" + HostPort: "53" + "2377/tcp": null + + PortBinding: + description: | + PortBinding represents a binding between a host IP address and a host + port. + type: "object" + properties: + HostIp: + description: "Host IP address that the container's port is mapped to." + type: "string" + example: "127.0.0.1" + x-go-type: + type: Addr + import: + package: net/netip + HostPort: + description: "Host port number that the container's port is mapped to." + type: "string" + example: "4443" + + DriverData: + description: | + Information about the storage driver used to store the container's and + image's filesystem. + type: "object" + required: [Name, Data] + properties: + Name: + description: "Name of the storage driver." + type: "string" + x-nullable: false + example: "overlay2" + Data: + description: | + Low-level storage metadata, provided as key/value pairs. + + This information is driver-specific, and depends on the storage-driver + in use, and should be used for informational purposes only. + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + "MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged" + "UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff" + "WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work" + + Storage: + description: | + Information about the storage used by the container. + type: "object" + properties: + RootFS: + description: | + Information about the storage used for the container's root filesystem. + type: "object" + x-nullable: true + $ref: "#/definitions/RootFSStorage" + + RootFSStorage: + description: | + Information about the storage used for the container's root filesystem. + type: "object" + x-go-name: RootFSStorage + properties: + Snapshot: + description: | + Information about the snapshot used for the container's root filesystem. + type: "object" + x-nullable: true + $ref: "#/definitions/RootFSStorageSnapshot" + + RootFSStorageSnapshot: + description: | + Information about a snapshot backend of the container's root filesystem. + type: "object" + x-go-name: RootFSStorageSnapshot + properties: + Name: + description: "Name of the snapshotter." + type: "string" + x-nullable: false + + FilesystemChange: + description: | + Change in the container's filesystem. + type: "object" + required: [Path, Kind] + properties: + Path: + description: | + Path to file or directory that has changed. + type: "string" + x-nullable: false + Kind: + $ref: "#/definitions/ChangeType" + + ChangeType: + description: | + Kind of change + + Can be one of: + + - `0`: Modified ("C") + - `1`: Added ("A") + - `2`: Deleted ("D") + type: "integer" + format: "uint8" + enum: [0, 1, 2] + x-nullable: false + + ImageInspect: + description: | + Information about an image in the local image cache. + type: "object" + properties: + Id: + description: | + ID is the content-addressable ID of an image. + + This identifier is a content-addressable digest calculated from the + image's configuration (which includes the digests of layers used by + the image). + + Note that this digest differs from the `RepoDigests` below, which + holds digests of image manifests that reference the image. + type: "string" + x-nullable: false + example: "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710" + Descriptor: + description: | + Descriptor is an OCI descriptor of the image target. + In case of a multi-platform image, this descriptor points to the OCI index + or a manifest list. + + This field is only present if the daemon provides a multi-platform image store. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + x-nullable: true + $ref: "#/definitions/OCIDescriptor" + Manifests: + description: | + Manifests is a list of image manifests available in this image. It + provides a more detailed view of the platform-specific image manifests or + other image-attached data like build attestations. + + Only available if the daemon provides a multi-platform image store + and the `manifests` option is set in the inspect request. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + type: "array" + x-nullable: true + items: + $ref: "#/definitions/ImageManifestSummary" + Identity: + description: |- + Identity holds information about the identity and origin of the image. + This is trusted information verified by the daemon and cannot be modified + by tagging an image to a different name. + x-nullable: true + $ref: "#/definitions/Identity" + RepoTags: + description: | + List of image names/tags in the local image cache that reference this + image. + + Multiple image tags can refer to the same image, and this list may be + empty if no tags reference the image, in which case the image is + "untagged", in which case it can still be referenced by its ID. + type: "array" + items: + type: "string" + example: + - "example:1.0" + - "example:latest" + - "example:stable" + - "internal.registry.example.com:5000/example:1.0" + RepoDigests: + description: | + List of content-addressable digests of locally available image manifests + that the image is referenced from. Multiple manifests can refer to the + same image. + + These digests are usually only available if the image was either pulled + from a registry, or if the image was pushed to a registry, which is when + the manifest is generated and its digest calculated. + type: "array" + items: + type: "string" + example: + - "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb" + - "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578" + Comment: + description: | + Optional message that was set when committing or importing the image. + type: "string" + x-nullable: true + example: "" + Created: + description: | + Date and time at which the image was created, formatted in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + + This information is only available if present in the image, + and omitted otherwise. + type: "string" + format: "dateTime" + x-nullable: true + example: "2022-02-04T21:20:12.497794809Z" + Author: + description: | + Name of the author that was specified when committing the image, or as + specified through MAINTAINER (deprecated) in the Dockerfile. + type: "string" + x-nullable: true + example: "" + Config: + $ref: "#/definitions/ImageConfig" + Architecture: + description: | + Hardware CPU architecture that the image runs on. + type: "string" + x-nullable: false + example: "arm" + Variant: + description: | + CPU architecture variant (presently ARM-only). + type: "string" + x-nullable: true + example: "v7" + Os: + description: | + Operating System the image is built to run on. + type: "string" + x-nullable: false + example: "linux" + OsVersion: + description: | + Operating System version the image is built to run on (especially + for Windows). + type: "string" + example: "" + x-nullable: true + Size: + description: | + Total size of the image variant, including all layers it is composed of. + + For multi-platform images, this is the size of the platform variant + selected by the `platform` query parameter. If no platform is specified, + the daemon selects a platform as described in the `platform` parameter. + + When using the containerd image store, this includes both the image content + that's present locally and the unpacked snapshot data for the selected + variant. + + Image data may be shared between images, so this size does not indicate + how much space would be reclaimed by deleting the image. + type: "integer" + format: "int64" + x-nullable: false + example: 1239828 + GraphDriver: + x-nullable: true + $ref: "#/definitions/DriverData" + RootFS: + description: | + Information about the image's RootFS, including the layer IDs. + type: "object" + required: [Type] + properties: + Type: + type: "string" + x-nullable: false + example: "layers" + Layers: + type: "array" + items: + type: "string" + example: + - "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6" + - "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" + Metadata: + description: | + Additional metadata of the image in the local cache. This information + is local to the daemon, and not part of the image itself. + type: "object" + properties: + LastTagTime: + description: | + Date and time at which the image was last tagged in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + + This information is only available if the image was tagged locally, + and omitted otherwise. + type: "string" + format: "dateTime" + example: "2022-02-28T14:40:02.623929178Z" + x-nullable: true + + Identity: + description: |- + Identity holds information about the identity and origin of the image. + This is trusted information verified by the daemon and cannot be modified + by tagging an image to a different name. + type: "object" + properties: + Signature: + description: |- + Signature contains the properties of verified signatures for the image. + type: "array" + items: + $ref: "#/definitions/SignatureIdentity" + Pull: + description: |- + Pull contains remote location information if image was created via pull. + If image was pulled via mirror, this contains the original repository location. + After successful push this images also contains the pushed repository location. + type: "array" + items: + $ref: "#/definitions/PullIdentity" + Build: + description: |- + Build contains build reference information if image was created via build. + type: "array" + items: + $ref: "#/definitions/BuildIdentity" + + BuildIdentity: + description: |- + BuildIdentity contains build reference information if image was created via build. + type: "object" + properties: + Ref: + description: |- + Ref is the identifier for the build request. This reference can be used to + look up the build details in BuildKit history API. + type: "string" + CreatedAt: + description: |- + CreatedAt is the time when the build ran. + type: "string" + format: "date-time" + + PullIdentity: + description: |- + PullIdentity contains remote location information if image was created via pull. + If image was pulled via mirror, this contains the original repository location. + type: "object" + properties: + Repository: + description: |- + Repository is the remote repository location the image was pulled from. + type: "string" + + SignatureIdentity: + description: |- + SignatureIdentity contains the properties of verified signatures for the image. + type: "object" + properties: + Name: + description: |- + Name is a textual description summarizing the type of signature. + type: "string" + Timestamps: + description: |- + Timestamps contains a list of verified signed timestamps for the signature. + type: "array" + items: + $ref: "#/definitions/SignatureTimestamp" + KnownSigner: + description: |- + KnownSigner is an identifier for a special signer identity that is known to the implementation. + $ref: "#/definitions/KnownSignerIdentity" + DockerReference: + description: |- + DockerReference is the Docker image reference associated with the signature. + This is an optional field only present in older hashedrecord signatures. + type: "string" + Signer: + description: |- + Signer contains information about the signer certificate used to sign the image. + $ref: "#/definitions/SignerIdentity" + SignatureType: + description: |- + SignatureType is the type of signature format. E.g. "bundle-v0.3" or "hashedrecord". + $ref: "#/definitions/SignatureType" + Error: + description: |- + Error contains error information if signature verification failed. + Other fields will be empty in this case. + type: "string" + Warnings: + description: |- + Warnings contains any warnings that occurred during signature verification. + For example, if there was no internet connectivity and cached trust roots were used. + Warning does not indicate a failed verification but may point to configuration issues. + type: "array" + items: + type: "string" + + SignatureTimestamp: + description: |- + SignatureTimestamp contains information about a verified signed timestamp for an image signature. + type: "object" + properties: + Type: + $ref: "#/definitions/SignatureTimestampType" + URI: + type: "string" + Timestamp: + type: "string" + format: "date-time" + + SignatureTimestampType: + description: |- + SignatureTimestampType is the type of timestamp used in the signature. + type: "string" + enum: + - "Tlog" + - "TimestampAuthority" + + SignatureType: + description: |- + SignatureType is the type of signature format. + type: "string" + enum: + - "bundle-v0.3" + - "simplesigning-v1" + + KnownSignerIdentity: + description: |- + KnownSignerIdentity is an identifier for a special signer identity that is known to the implementation. + type: "string" + enum: + - "DHI" + + SignerIdentity: + description: |- + SignerIdentity contains information about the signer certificate used to sign the image. + type: "object" + properties: + CertificateIssuer: + type: "string" + description: |- + CertificateIssuer is the certificate issuer. + SubjectAlternativeName: + type: "string" + description: |- + SubjectAlternativeName is the certificate subject alternative name. + Issuer: + type: "string" + description: |- + The OIDC issuer. Should match `iss` claim of ID token or, in the case of + a federated login like Dex it should match the issuer URL of the + upstream issuer. The issuer is not set the extensions are invalid and + will fail to render. + BuildSignerURI: + type: "string" + description: |- + Reference to specific build instructions that are responsible for signing. + BuildSignerDigest: + type: "string" + description: |- + Immutable reference to the specific version of the build instructions that is responsible for signing. + RunnerEnvironment: + type: "string" + description: |- + Specifies whether the build took place in platform-hosted cloud infrastructure or customer/self-hosted infrastructure. + SourceRepositoryURI: + type: "string" + description: |- + Source repository URL that the build was based on. + SourceRepositoryDigest: + type: "string" + description: |- + Immutable reference to a specific version of the source code that the build was based upon. + SourceRepositoryRef: + type: "string" + description: |- + Source Repository Ref that the build run was based upon. + SourceRepositoryIdentifier: + type: "string" + description: |- + Immutable identifier for the source repository the workflow was based upon. + SourceRepositoryOwnerURI: + type: "string" + description: |- + Source repository owner URL of the owner of the source repository that the build was based on. + SourceRepositoryOwnerIdentifier: + type: "string" + description: |- + Immutable identifier for the owner of the source repository that the workflow was based upon. + BuildConfigURI: + type: "string" + description: |- + Build Config URL to the top-level/initiating build instructions. + BuildConfigDigest: + type: "string" + description: |- + Immutable reference to the specific version of the top-level/initiating build instructions. + BuildTrigger: + type: "string" + description: |- + Event or action that initiated the build. + RunInvocationURI: + type: "string" + description: |- + Run Invocation URL to uniquely identify the build execution. + SourceRepositoryVisibilityAtSigning: + type: "string" + description: |- + Source repository visibility at the time of signing the certificate. + + ImageSummary: + type: "object" + x-go-name: "Summary" + required: + - Id + - ParentId + - RepoTags + - RepoDigests + - Created + - Size + - SharedSize + - Labels + - Containers + properties: + Id: + description: | + ID is the content-addressable ID of an image. + + This identifier is a content-addressable digest calculated from the + image's configuration (which includes the digests of layers used by + the image). + + Note that this digest differs from the `RepoDigests` below, which + holds digests of image manifests that reference the image. + type: "string" + x-nullable: false + example: "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710" + ParentId: + description: | + ID of the parent image. + + Depending on how the image was created, this field may be empty and + is only set for images that were built/created locally. This field + is empty if the image was pulled from an image registry. + type: "string" + x-nullable: false + example: "" + RepoTags: + description: | + List of image names/tags in the local image cache that reference this + image. + + Multiple image tags can refer to the same image, and this list may be + empty if no tags reference the image, in which case the image is + "untagged", in which case it can still be referenced by its ID. + type: "array" + x-nullable: false + items: + type: "string" + example: + - "example:1.0" + - "example:latest" + - "example:stable" + - "internal.registry.example.com:5000/example:1.0" + RepoDigests: + description: | + List of content-addressable digests of locally available image manifests + that the image is referenced from. Multiple manifests can refer to the + same image. + + These digests are usually only available if the image was either pulled + from a registry, or if the image was pushed to a registry, which is when + the manifest is generated and its digest calculated. + type: "array" + x-nullable: false + items: + type: "string" + example: + - "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb" + - "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578" + Created: + description: | + Date and time at which the image was created as a Unix timestamp + (number of seconds since EPOCH). + type: "integer" + x-nullable: false + example: "1644009612" + Size: + description: | + Total size of the image including all layers it is composed of. + type: "integer" + format: "int64" + x-nullable: false + example: 172064416 + SharedSize: + description: | + Total size of image layers that are shared between this image and other + images. + + This size is not calculated by default. `-1` indicates that the value + has not been set / calculated. + type: "integer" + format: "int64" + x-nullable: false + example: 1239828 + Labels: + description: "User-defined key/value metadata." + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Containers: + description: | + Number of containers using this image. Includes both stopped and running + containers. + + `-1` indicates that the value has not been set / calculated. + x-nullable: false + type: "integer" + example: 2 + Manifests: + description: | + Manifests is a list of manifests available in this image. + It provides a more detailed view of the platform-specific image manifests + or other image-attached data like build attestations. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + type: "array" + x-nullable: false + x-omitempty: true + items: + $ref: "#/definitions/ImageManifestSummary" + Descriptor: + description: | + Descriptor is an OCI descriptor of the image target. + In case of a multi-platform image, this descriptor points to the OCI index + or a manifest list. + + This field is only present if the daemon provides a multi-platform image store. + + WARNING: This is experimental and may change at any time without any backward + compatibility. + x-nullable: true + $ref: "#/definitions/OCIDescriptor" + + ImagesDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/image" + description: | + represents system data usage for image resources. + properties: + ActiveCount: + description: | + Count of active images. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all images. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing unused images. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by images. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of image summaries. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Summary + + AuthConfig: + type: "object" + properties: + username: + type: "string" + password: + type: "string" + serveraddress: + type: "string" + example: + username: "hannibal" + password: "xxxx" + serveraddress: "https://index.docker.io/v1/" + + AuthResponse: + description: | + An identity token was generated successfully. + type: "object" + required: [Status] + properties: + Status: + description: "The status of the authentication" + type: "string" + example: "Login Succeeded" + x-nullable: false + IdentityToken: + description: "An opaque token used to authenticate a user after a successful login" + type: "string" + example: "9cbaf023786cd7..." + x-nullable: false + + ProcessConfig: + type: "object" + properties: + privileged: + type: "boolean" + user: + type: "string" + tty: + type: "boolean" + entrypoint: + type: "string" + arguments: + type: "array" + items: + type: "string" + + Volume: + type: "object" + required: [Name, Driver, Mountpoint, Labels, Scope, Options] + x-nullable: false + properties: + Name: + type: "string" + description: "Name of the volume." + x-nullable: false + example: "tardis" + Driver: + type: "string" + description: "Name of the volume driver used by the volume." + x-nullable: false + example: "custom" + Mountpoint: + type: "string" + description: "Mount path of the volume on the host." + x-nullable: false + example: "/var/lib/docker/volumes/tardis" + CreatedAt: + type: "string" + format: "dateTime" + description: "Date/Time the volume was created." + example: "2016-06-07T20:31:11.853781916Z" + Status: + type: "object" + description: | + Low-level details about the volume, provided by the volume driver. + Details are returned as a map with key/value pairs: + `{"key":"value","key2":"value2"}`. + + The `Status` field is optional, and is omitted if the volume driver + does not support this feature. + additionalProperties: + type: "object" + example: + hello: "world" + Labels: + type: "object" + description: "User-defined key/value metadata." + x-nullable: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Scope: + type: "string" + description: | + The level at which the volume exists. Either `global` for cluster-wide, + or `local` for machine level. + default: "local" + x-nullable: false + enum: ["local", "global"] + example: "local" + ClusterVolume: + $ref: "#/definitions/ClusterVolume" + Options: + type: "object" + description: | + The driver specific options used when creating the volume. + additionalProperties: + type: "string" + example: + device: "tmpfs" + o: "size=100m,uid=1000" + type: "tmpfs" + UsageData: + type: "object" + x-nullable: true + x-go-name: "UsageData" + required: [Size, RefCount] + description: | + Usage details about the volume. This information is used by the + `GET /system/df` endpoint, and omitted in other endpoints. + properties: + Size: + type: "integer" + format: "int64" + default: -1 + description: | + Amount of disk space used by the volume (in bytes). This information + is only available for volumes created with the `"local"` volume + driver. For volumes created with other volume drivers, this field + is set to `-1` ("not available") + x-nullable: false + RefCount: + type: "integer" + format: "int64" + default: -1 + description: | + The number of containers referencing this volume. This field + is set to `-1` if the reference-count is not available. + x-nullable: false + + VolumesDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/volume" + description: | + represents system data usage for volume resources. + properties: + ActiveCount: + description: | + Count of active volumes. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all volumes. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive volumes. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by volumes. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of volumes. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Volume + + VolumeCreateRequest: + description: "Volume configuration" + type: "object" + title: "VolumeConfig" + x-go-name: "CreateRequest" + properties: + Name: + description: | + The new volume's name. If not specified, Docker generates a name. + type: "string" + x-nullable: false + example: "tardis" + Driver: + description: "Name of the volume driver to use." + type: "string" + default: "local" + x-nullable: false + example: "custom" + DriverOpts: + description: | + A mapping of driver options and values. These options are + passed directly to the driver and are driver specific. + type: "object" + additionalProperties: + type: "string" + example: + device: "tmpfs" + o: "size=100m,uid=1000" + type: "tmpfs" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + ClusterVolumeSpec: + $ref: "#/definitions/ClusterVolumeSpec" + + VolumeListResponse: + type: "object" + title: "VolumeListResponse" + x-go-name: "ListResponse" + description: "Volume list response" + properties: + Volumes: + type: "array" + description: "List of volumes" + items: + $ref: "#/definitions/Volume" + Warnings: + type: "array" + description: | + Warnings that occurred when fetching the list of volumes. + items: + type: "string" + example: [] + + Network: + type: "object" + properties: + Name: + description: | + Name of the network. + type: "string" + example: "my_network" + x-omitempty: false + Id: + description: | + ID that uniquely identifies a network on a single machine. + type: "string" + x-go-name: "ID" + x-omitempty: false + example: "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99" + Created: + description: | + Date and time at which the network was created in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-omitempty: false + x-go-type: + type: Time + import: + package: time + hints: + nullable: false + example: "2016-10-19T04:33:30.360899459Z" + Scope: + description: | + The level at which the network exists (e.g. `swarm` for cluster-wide + or `local` for machine level) + type: "string" + x-omitempty: false + example: "local" + Driver: + description: | + The name of the driver used to create the network (e.g. `bridge`, + `overlay`). + type: "string" + x-omitempty: false + example: "overlay" + EnableIPv4: + description: | + Whether the network was created with IPv4 enabled. + type: "boolean" + x-omitempty: false + example: true + EnableIPv6: + description: | + Whether the network was created with IPv6 enabled. + type: "boolean" + x-omitempty: false + example: false + IPAM: + description: | + The network's IP Address Management. + $ref: "#/definitions/IPAM" + x-nullable: false + x-omitempty: false + Internal: + description: | + Whether the network is created to only allow internal networking + connectivity. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + Attachable: + description: | + Whether a global / swarm scope network is manually attachable by regular + containers from workers in swarm mode. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + Ingress: + description: | + Whether the network is providing the routing-mesh for the swarm cluster. + type: "boolean" + x-nullable: false + x-omitempty: false + default: false + example: false + ConfigFrom: + $ref: "#/definitions/ConfigReference" + x-nullable: false + x-omitempty: false + ConfigOnly: + description: | + Whether the network is a config-only network. Config-only networks are + placeholder networks for network configurations to be used by other + networks. Config-only networks cannot be used directly to run containers + or services. + type: "boolean" + x-omitempty: false + x-nullable: false + default: false + Options: + description: | + Network-specific options uses when creating the network. + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + example: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + Labels: + description: | + Metadata specific to the network being created. + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Peers: + description: | + List of peer nodes for an overlay network. This field is only present + for overlay networks, and omitted for other network types. + type: "array" + x-omitempty: true + items: + $ref: "#/definitions/PeerInfo" + + NetworkSummary: + description: "Network list response item" + x-go-name: Summary + type: "object" + allOf: + - $ref: "#/definitions/Network" + + NetworkInspect: + description: 'The body of the "get network" http response message.' + x-go-name: Inspect + type: "object" + allOf: + - $ref: "#/definitions/Network" + properties: + Containers: + description: | + Contains endpoints attached to the network. + type: "object" + x-omitempty: false + additionalProperties: + $ref: "#/definitions/EndpointResource" + example: + 19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c: + Name: "test" + EndpointID: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a" + MacAddress: "02:42:ac:13:00:02" + IPv4Address: "172.19.0.2/16" + IPv6Address: "" + Services: + description: | + List of services using the network. This field is only present for + swarm scope networks, and omitted for local scope networks. + type: "object" + x-omitempty: true + additionalProperties: + x-go-type: + type: ServiceInfo + hints: + nullable: false + Status: + description: > + provides runtime information about the network + such as the number of allocated IPs. + $ref: "#/definitions/NetworkStatus" + + NetworkStatus: + description: > + provides runtime information about the network + such as the number of allocated IPs. + type: "object" + x-go-name: Status + properties: + IPAM: + $ref: "#/definitions/IPAMStatus" + + ServiceInfo: + x-nullable: false + x-omitempty: false + description: > + represents service parameters with the list of service's tasks + type: "object" + properties: + VIP: + type: "string" + x-omitempty: false + x-go-type: + type: Addr + import: + package: net/netip + Ports: + type: "array" + x-omitempty: false + items: + type: "string" + LocalLBIndex: + type: "integer" + format: "int" + x-omitempty: false + x-go-type: + type: int + Tasks: + type: "array" + x-omitempty: false + items: + $ref: "#/definitions/NetworkTaskInfo" + + NetworkTaskInfo: + x-nullable: false + x-omitempty: false + x-go-name: Task + description: > + carries the information about one backend task + type: "object" + properties: + Name: + type: "string" + x-omitempty: false + EndpointID: + type: "string" + x-omitempty: false + EndpointIP: + type: "string" + x-omitempty: false + x-go-type: + type: Addr + import: + package: net/netip + Info: + type: "object" + x-omitempty: false + additionalProperties: + type: "string" + + ConfigReference: + x-nullable: false + x-omitempty: false + description: | + The config-only network source to provide the configuration for + this network. + type: "object" + properties: + Network: + description: | + The name of the config-only network that provides the network's + configuration. The specified network must be an existing config-only + network. Only network names are allowed, not network IDs. + type: "string" + x-omitempty: false + example: "config_only_network_01" + + IPAM: + type: "object" + x-nullable: false + x-omitempty: false + properties: + Driver: + description: "Name of the IPAM driver to use." + type: "string" + default: "default" + example: "default" + Config: + description: | + List of IPAM configuration options, specified as a map: + + ``` + {"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>} + ``` + type: "array" + items: + $ref: "#/definitions/IPAMConfig" + Options: + description: "Driver-specific options, specified as a map." + type: "object" + additionalProperties: + type: "string" + example: + foo: "bar" + + IPAMConfig: + type: "object" + properties: + Subnet: + type: "string" + example: "172.20.0.0/16" + IPRange: + type: "string" + example: "172.20.10.0/24" + Gateway: + type: "string" + example: "172.20.10.11" + AuxiliaryAddresses: + type: "object" + additionalProperties: + type: "string" + + IPAMStatus: + type: "object" + x-nullable: false + x-omitempty: false + properties: + Subnets: + type: "object" + additionalProperties: + $ref: "#/definitions/SubnetStatus" + example: + "172.16.0.0/16": + IPsInUse: 3 + DynamicIPsAvailable: 65533 + "2001:db8:abcd:0012::0/96": + IPsInUse: 5 + DynamicIPsAvailable: 4294967291 + x-go-type: + type: SubnetStatuses + kind: map + + SubnetStatus: + type: "object" + x-nullable: false + x-omitempty: false + properties: + IPsInUse: + description: > + Number of IP addresses in the subnet that are in use or reserved and + are therefore unavailable for allocation, saturating at 2<sup>64</sup> - 1. + type: integer + format: uint64 + x-omitempty: false + DynamicIPsAvailable: + description: > + Number of IP addresses within the network's IPRange for the subnet + that are available for allocation, saturating at 2<sup>64</sup> - 1. + type: integer + format: uint64 + x-omitempty: false + + EndpointResource: + type: "object" + description: > + contains network resources allocated and used for a + container in a network. + properties: + Name: + type: "string" + x-omitempty: false + example: "container_1" + EndpointID: + type: "string" + x-omitempty: false + example: "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a" + MacAddress: + type: "string" + x-omitempty: false + example: "02:42:ac:13:00:02" + x-go-type: + type: HardwareAddr + IPv4Address: + type: "string" + x-omitempty: false + example: "172.19.0.2/16" + x-go-type: + type: Prefix + import: + package: net/netip + IPv6Address: + type: "string" + x-omitempty: false + example: "" + x-go-type: + type: Prefix + import: + package: net/netip + + PeerInfo: + description: > + represents one peer of an overlay network. + type: "object" + x-nullable: false + properties: + Name: + description: + ID of the peer-node in the Swarm cluster. + type: "string" + x-omitempty: false + example: "6869d7c1732b" + IP: + description: + IP-address of the peer-node in the Swarm cluster. + type: "string" + x-omitempty: false + example: "10.133.77.91" + x-go-type: + type: Addr + import: + package: net/netip + + NetworkCreateResponse: + description: "OK response to NetworkCreate operation" + type: "object" + title: "NetworkCreateResponse" + x-go-name: "CreateResponse" + required: [Id, Warning] + properties: + Id: + description: "The ID of the created network." + type: "string" + x-nullable: false + example: "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d" + Warning: + description: "Warnings encountered when creating the container" + type: "string" + x-nullable: false + example: "" + + BuildInfo: + type: "object" + properties: + id: + type: "string" + stream: + type: "string" + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + aux: + $ref: "#/definitions/ImageID" + + BuildCache: + type: "object" + description: | + BuildCache contains information about a build cache record. + properties: + ID: + type: "string" + description: | + Unique ID of the build cache record. + example: "ndlpt0hhvkqcdfkputsk4cq9c" + Parents: + description: | + List of parent build cache record IDs. + type: "array" + items: + type: "string" + x-nullable: true + example: ["hw53o5aio51xtltp5xjp8v7fx"] + Type: + type: "string" + description: | + Cache record type. + example: "regular" + # see https://github.com/moby/buildkit/blob/fce4a32258dc9d9664f71a4831d5de10f0670677/client/diskusage.go#L75-L84 + enum: + - "internal" + - "frontend" + - "source.local" + - "source.git.checkout" + - "exec.cachemount" + - "regular" + Description: + type: "string" + description: | + Description of the build-step that produced the build cache. + example: "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache" + InUse: + type: "boolean" + description: | + Indicates if the build cache is in use. + example: false + Shared: + type: "boolean" + description: | + Indicates if the build cache is shared. + example: true + Size: + description: | + Amount of disk space used by the build cache (in bytes). + type: "integer" + example: 51 + CreatedAt: + description: | + Date and time at which the build cache was created in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + LastUsedAt: + description: | + Date and time at which the build cache was last used in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-nullable: true + example: "2017-08-09T07:09:37.632105588Z" + UsageCount: + type: "integer" + example: 26 + + BuildCacheDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/build" + description: | + represents system data usage for build cache resources. + properties: + ActiveCount: + description: | + Count of active build cache records. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all build cache records. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive build cache records. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by build cache records. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of build cache records. + type: "array" + x-omitempty: true + items: + x-go-type: + type: CacheRecord + + ImageID: + type: "object" + description: "Image ID or Digest" + properties: + ID: + type: "string" + example: + ID: "sha256:85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c" + + CreateImageInfo: + type: "object" + properties: + id: + type: "string" + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + + PushImageInfo: + type: "object" + properties: + errorDetail: + $ref: "#/definitions/ErrorDetail" + status: + type: "string" + progressDetail: + $ref: "#/definitions/ProgressDetail" + + DeviceInfo: + type: "object" + description: | + DeviceInfo represents a device that can be used by a container. + properties: + Source: + type: "string" + example: "cdi" + description: | + The origin device driver. + ID: + type: "string" + example: "vendor.com/gpu=0" + description: | + The unique identifier for the device within its source driver. + For CDI devices, this would be an FQDN like "vendor.com/gpu=0". + + NRIInfo: + description: | + Information about the Node Resource Interface (NRI). + + This field is only present if NRI is enabled. + type: "object" + x-nullable: true + properties: + Info: + description: | + Information about NRI, provided as "label" / "value" pairs. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["plugin-path", "/opt/docker/nri/plugins"] + + ErrorDetail: + type: "object" + properties: + code: + type: "integer" + message: + type: "string" + + ProgressDetail: + type: "object" + properties: + current: + type: "integer" + total: + type: "integer" + + ErrorResponse: + description: "Represents an error." + type: "object" + required: ["message"] + properties: + message: + description: "The error message." + type: "string" + x-nullable: false + example: + message: "Something went wrong." + + IDResponse: + description: "Response to an API call that returns just an Id" + type: "object" + x-go-name: "IDResponse" + required: ["Id"] + properties: + Id: + description: "The id of the newly created object." + type: "string" + x-nullable: false + + NetworkConnectRequest: + description: | + NetworkConnectRequest represents the data to be used to connect a container to a network. + type: "object" + x-go-name: "ConnectRequest" + required: ["Container"] + properties: + Container: + type: "string" + description: "The ID or name of the container to connect to the network." + x-nullable: false + example: "3613f73ba0e4" + EndpointConfig: + $ref: "#/definitions/EndpointSettings" + x-nullable: true + + NetworkDisconnectRequest: + description: | + NetworkDisconnectRequest represents the data to be used to disconnect a container from a network. + type: "object" + x-go-name: "DisconnectRequest" + required: ["Container"] + properties: + Container: + type: "string" + description: "The ID or name of the container to disconnect from the network." + x-nullable: false + example: "3613f73ba0e4" + Force: + type: "boolean" + description: "Force the container to disconnect from the network." + default: false + x-nullable: false + x-omitempty: false + example: false + + EndpointSettings: + description: "Configuration for a network endpoint." + type: "object" + properties: + # Configurations + IPAMConfig: + $ref: "#/definitions/EndpointIPAMConfig" + Links: + type: "array" + items: + type: "string" + example: + - "container_1" + - "container_2" + MacAddress: + description: | + MAC address for the endpoint on this network. The network driver might ignore this parameter. + type: "string" + example: "02:42:ac:11:00:04" + x-go-type: + type: HardwareAddr + Aliases: + type: "array" + items: + type: "string" + example: + - "server_x" + - "server_y" + DriverOpts: + description: | + DriverOpts is a mapping of driver options and values. These options + are passed directly to the driver and are driver specific. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + GwPriority: + description: | + This property determines which endpoint will provide the default + gateway for a container. The endpoint with the highest priority will + be used. If multiple endpoints have the same priority, endpoints are + lexicographically sorted based on their network name, and the one + that sorts first is picked. + type: "integer" + format: "int64" + example: + - 10 + + # Operational data + NetworkID: + description: | + Unique ID of the network. + type: "string" + example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a" + EndpointID: + description: | + Unique ID for the service endpoint in a Sandbox. + type: "string" + example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b" + Gateway: + description: | + Gateway address for this network. + type: "string" + example: "172.17.0.1" + IPAddress: + description: | + IPv4 address. + type: "string" + example: "172.17.0.4" + x-go-type: + type: Addr + import: + package: net/netip + IPPrefixLen: + description: | + Mask length of the IPv4 address. + type: "integer" + example: 16 + IPv6Gateway: + description: | + IPv6 gateway address. + type: "string" + example: "2001:db8:2::100" + x-go-type: + type: Addr + import: + package: net/netip + GlobalIPv6Address: + description: | + Global IPv6 address. + type: "string" + example: "2001:db8::5689" + x-go-type: + type: Addr + import: + package: net/netip + GlobalIPv6PrefixLen: + description: | + Mask length of the global IPv6 address. + type: "integer" + format: "int64" + example: 64 + DNSNames: + description: | + List of all DNS names an endpoint has on a specific network. This + list is based on the container name, network aliases, container short + ID, and hostname. + + These DNS names are non-fully qualified but can contain several dots. + You can get fully qualified DNS names by appending `.<network-name>`. + For instance, if container name is `my.ctr` and the network is named + `testnet`, `DNSNames` will contain `my.ctr` and the FQDN will be + `my.ctr.testnet`. + type: array + items: + type: string + example: ["foobar", "server_x", "server_y", "my.ctr"] + + EndpointIPAMConfig: + description: | + EndpointIPAMConfig represents an endpoint's IPAM configuration. + type: "object" + x-nullable: true + properties: + IPv4Address: + type: "string" + example: "172.20.30.33" + x-go-type: + type: Addr + import: + package: net/netip + IPv6Address: + type: "string" + example: "2001:db8:abcd::3033" + x-go-type: + type: Addr + import: + package: net/netip + LinkLocalIPs: + type: "array" + items: + type: "string" + x-go-type: + type: Addr + import: + package: net/netip + example: + - "169.254.34.68" + - "fe80::3468" + + PluginMount: + type: "object" + x-go-name: "Mount" + x-nullable: false + required: [Name, Description, Settable, Source, Destination, Type, Options] + properties: + Name: + type: "string" + x-nullable: false + example: "some-mount" + Description: + type: "string" + x-nullable: false + example: "This is a mount that's used by the plugin." + Settable: + type: "array" + items: + type: "string" + Source: + type: "string" + example: "/var/lib/docker/plugins/" + Destination: + type: "string" + x-nullable: false + example: "/mnt/state" + Type: + type: "string" + x-nullable: false + example: "bind" + Options: + type: "array" + items: + type: "string" + example: + - "rbind" + - "rw" + + PluginDevice: + type: "object" + x-go-name: "Device" + required: [Name, Description, Settable, Path] + x-nullable: false + properties: + Name: + type: "string" + x-nullable: false + Description: + type: "string" + x-nullable: false + Settable: + type: "array" + items: + type: "string" + Path: + type: "string" + example: "/dev/fuse" + + PluginEnv: + type: "object" + x-go-name: "Env" + x-nullable: false + required: [Name, Description, Settable, Value] + properties: + Name: + x-nullable: false + type: "string" + Description: + x-nullable: false + type: "string" + Settable: + type: "array" + items: + type: "string" + Value: + type: "string" + + PluginPrivilege: + description: | + Describes a permission the user has to accept upon installing + the plugin. + type: "object" + x-go-name: "Privilege" + properties: + Name: + type: "string" + example: "network" + Description: + type: "string" + Value: + type: "array" + items: + type: "string" + example: + - "host" + + Plugin: + description: "A plugin for the Engine API" + type: "object" + x-go-name: "Plugin" + required: [Settings, Enabled, Config, Name] + properties: + Id: + type: "string" + example: "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078" + Name: + type: "string" + x-nullable: false + example: "tiborvass/sample-volume-plugin" + Enabled: + description: + True if the plugin is running. False if the plugin is not running, + only installed. + type: "boolean" + x-nullable: false + example: true + Settings: + description: "user-configurable settings for the plugin." + type: "object" + x-go-name: "Settings" + x-nullable: false + required: [Args, Devices, Env, Mounts] + properties: + Mounts: + type: "array" + items: + $ref: "#/definitions/PluginMount" + Env: + type: "array" + items: + type: "string" + example: + - "DEBUG=0" + Args: + type: "array" + items: + type: "string" + Devices: + type: "array" + items: + $ref: "#/definitions/PluginDevice" + PluginReference: + description: "plugin remote reference used to push/pull the plugin" + type: "string" + x-go-name: "PluginReference" + x-nullable: false + example: "localhost:5000/tiborvass/sample-volume-plugin:latest" + Config: + description: "The config of a plugin." + type: "object" + x-go-name: "Config" + x-nullable: false + required: + - Description + - Documentation + - Interface + - Entrypoint + - WorkDir + - Network + - Linux + - PidHost + - PropagatedMount + - IpcHost + - Mounts + - Env + - Args + properties: + Description: + type: "string" + x-nullable: false + example: "A sample volume plugin for Docker" + Documentation: + type: "string" + x-nullable: false + example: "https://docs.docker.com/engine/extend/plugins/" + Interface: + description: "The interface between Docker and the plugin" + x-nullable: false + type: "object" + x-go-name: "Interface" + required: [Types, Socket] + properties: + Types: + type: "array" + items: + type: "string" + x-go-type: + type: "CapabilityID" + example: + - "docker.volumedriver/1.0" + Socket: + type: "string" + x-nullable: false + example: "plugins.sock" + ProtocolScheme: + type: "string" + example: "some.protocol/v1.0" + description: "Protocol to use for clients connecting to the plugin." + enum: + - "" + - "moby.plugins.http/v1" + Entrypoint: + type: "array" + items: + type: "string" + example: + - "/usr/bin/sample-volume-plugin" + - "/data" + WorkDir: + type: "string" + x-nullable: false + example: "/bin/" + User: + type: "object" + x-go-name: "User" + x-nullable: false + properties: + UID: + type: "integer" + format: "uint32" + example: 1000 + GID: + type: "integer" + format: "uint32" + example: 1000 + Network: + type: "object" + x-go-name: "NetworkConfig" + x-nullable: false + required: [Type] + properties: + Type: + x-nullable: false + type: "string" + example: "host" + Linux: + type: "object" + x-go-name: "LinuxConfig" + x-nullable: false + required: [Capabilities, AllowAllDevices, Devices] + properties: + Capabilities: + type: "array" + items: + type: "string" + example: + - "CAP_SYS_ADMIN" + - "CAP_SYSLOG" + AllowAllDevices: + type: "boolean" + x-nullable: false + example: false + Devices: + type: "array" + items: + $ref: "#/definitions/PluginDevice" + PropagatedMount: + type: "string" + x-nullable: false + example: "/mnt/volumes" + IpcHost: + type: "boolean" + x-nullable: false + example: false + PidHost: + type: "boolean" + x-nullable: false + example: false + Mounts: + type: "array" + items: + $ref: "#/definitions/PluginMount" + Env: + type: "array" + items: + $ref: "#/definitions/PluginEnv" + example: + - Name: "DEBUG" + Description: "If set, prints debug messages" + Settable: null + Value: "0" + Args: + type: "object" + x-go-name: "Args" + x-nullable: false + required: [Name, Description, Settable, Value] + properties: + Name: + x-nullable: false + type: "string" + example: "args" + Description: + x-nullable: false + type: "string" + example: "command line arguments" + Settable: + type: "array" + items: + type: "string" + Value: + type: "array" + items: + type: "string" + rootfs: + type: "object" + x-go-name: "RootFS" + properties: + type: + type: "string" + example: "layers" + diff_ids: + type: "array" + items: + type: "string" + example: + - "sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887" + - "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8" + + ObjectVersion: + description: | + The version number of the object such as node, service, etc. This is needed + to avoid conflicting writes. The client must send the version number along + with the modified specification when updating these objects. + + This approach ensures safe concurrency and determinism in that the change + on the object may not be applied if the version number has changed from the + last read. In other words, if two update requests specify the same base + version, only one of the requests can succeed. As a result, two separate + update requests that happen at the same time will not unintentionally + overwrite each other. + type: "object" + properties: + Index: + type: "integer" + format: "uint64" + example: 373531 + + NodeSpec: + type: "object" + properties: + Name: + description: "Name for the node." + type: "string" + example: "my-node" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Role: + description: "Role of the node." + type: "string" + enum: + - "worker" + - "manager" + example: "manager" + Availability: + description: "Availability of the node." + type: "string" + enum: + - "active" + - "pause" + - "drain" + example: "active" + example: + Availability: "active" + Name: "node-name" + Role: "manager" + Labels: + foo: "bar" + + Node: + type: "object" + properties: + ID: + type: "string" + example: "24ifsmvkjbyhk" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + description: | + Date and time at which the node was added to the swarm in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + UpdatedAt: + description: | + Date and time at which the node was last updated in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2017-08-09T07:09:37.632105588Z" + Spec: + $ref: "#/definitions/NodeSpec" + Description: + $ref: "#/definitions/NodeDescription" + Status: + $ref: "#/definitions/NodeStatus" + ManagerStatus: + $ref: "#/definitions/ManagerStatus" + + NodeDescription: + description: | + NodeDescription encapsulates the properties of the Node as reported by the + agent. + type: "object" + properties: + Hostname: + type: "string" + example: "bf3067039e47" + Platform: + $ref: "#/definitions/Platform" + Resources: + $ref: "#/definitions/ResourceObject" + Engine: + $ref: "#/definitions/EngineDescription" + TLSInfo: + $ref: "#/definitions/TLSInfo" + + Platform: + description: | + Platform represents the platform (Arch/OS). + type: "object" + properties: + Architecture: + description: | + Architecture represents the hardware architecture (for example, + `x86_64`). + type: "string" + example: "x86_64" + OS: + description: | + OS represents the Operating System (for example, `linux` or `windows`). + type: "string" + example: "linux" + + EngineDescription: + description: "EngineDescription provides information about an engine." + type: "object" + properties: + EngineVersion: + type: "string" + example: "17.06.0" + Labels: + type: "object" + additionalProperties: + type: "string" + example: + foo: "bar" + Plugins: + type: "array" + items: + type: "object" + properties: + Type: + type: "string" + Name: + type: "string" + example: + - Type: "Log" + Name: "awslogs" + - Type: "Log" + Name: "fluentd" + - Type: "Log" + Name: "gcplogs" + - Type: "Log" + Name: "gelf" + - Type: "Log" + Name: "journald" + - Type: "Log" + Name: "json-file" + - Type: "Log" + Name: "splunk" + - Type: "Log" + Name: "syslog" + - Type: "Network" + Name: "bridge" + - Type: "Network" + Name: "host" + - Type: "Network" + Name: "ipvlan" + - Type: "Network" + Name: "macvlan" + - Type: "Network" + Name: "null" + - Type: "Network" + Name: "overlay" + - Type: "Volume" + Name: "local" + - Type: "Volume" + Name: "localhost:5000/vieux/sshfs:latest" + - Type: "Volume" + Name: "vieux/sshfs:latest" + + TLSInfo: + description: | + Information about the issuer of leaf TLS certificates and the trusted root + CA certificate. + type: "object" + properties: + TrustRoot: + description: | + The root CA certificate(s) that are used to validate leaf TLS + certificates. + type: "string" + CertIssuerSubject: + description: + The base64-url-safe-encoded raw subject bytes of the issuer. + type: "string" + CertIssuerPublicKey: + description: | + The base64-url-safe-encoded raw public key bytes of the issuer. + type: "string" + example: + TrustRoot: | + -----BEGIN CERTIFICATE----- + MIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0 + MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf + 3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO + PQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz + pxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H + -----END CERTIFICATE----- + CertIssuerSubject: "MBMxETAPBgNVBAMTCHN3YXJtLWNh" + CertIssuerPublicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==" + + NodeStatus: + description: | + NodeStatus represents the status of a node. + + It provides the current status of the node, as seen by the manager. + type: "object" + properties: + State: + $ref: "#/definitions/NodeState" + Message: + type: "string" + example: "" + Addr: + description: "IP address of the node." + type: "string" + example: "172.17.0.2" + + NodeState: + description: "NodeState represents the state of a node." + type: "string" + enum: + - "unknown" + - "down" + - "ready" + - "disconnected" + example: "ready" + + ManagerStatus: + description: | + ManagerStatus represents the status of a manager. + + It provides the current status of a node's manager component, if the node + is a manager. + x-nullable: true + type: "object" + properties: + Leader: + type: "boolean" + default: false + example: true + Reachability: + $ref: "#/definitions/Reachability" + Addr: + description: | + The IP address and port at which the manager is reachable. + type: "string" + example: "10.0.0.46:2377" + + Reachability: + description: "Reachability represents the reachability of a node." + type: "string" + enum: + - "unknown" + - "unreachable" + - "reachable" + example: "reachable" + + SwarmSpec: + description: "User modifiable swarm configuration." + type: "object" + properties: + Name: + description: "Name of the swarm." + type: "string" + example: "default" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.corp.type: "production" + com.example.corp.department: "engineering" + Orchestration: + description: "Orchestration configuration." + type: "object" + x-nullable: true + properties: + TaskHistoryRetentionLimit: + description: | + The number of historic tasks to keep per instance or node. If + negative, never remove completed or failed tasks. + type: "integer" + format: "int64" + example: 10 + Raft: + description: "Raft configuration." + type: "object" + properties: + SnapshotInterval: + description: "The number of log entries between snapshots." + type: "integer" + format: "uint64" + example: 10000 + KeepOldSnapshots: + description: | + The number of snapshots to keep beyond the current snapshot. + type: "integer" + format: "uint64" + LogEntriesForSlowFollowers: + description: | + The number of log entries to keep around to sync up slow followers + after a snapshot is created. + type: "integer" + format: "uint64" + example: 500 + ElectionTick: + description: | + The number of ticks that a follower will wait for a message from + the leader before becoming a candidate and starting an election. + `ElectionTick` must be greater than `HeartbeatTick`. + + A tick currently defaults to one second, so these translate + directly to seconds currently, but this is NOT guaranteed. + type: "integer" + example: 3 + HeartbeatTick: + description: | + The number of ticks between heartbeats. Every HeartbeatTick ticks, + the leader will send a heartbeat to the followers. + + A tick currently defaults to one second, so these translate + directly to seconds currently, but this is NOT guaranteed. + type: "integer" + example: 1 + Dispatcher: + description: "Dispatcher configuration." + type: "object" + x-nullable: true + properties: + HeartbeatPeriod: + description: | + The delay for an agent to send a heartbeat to the dispatcher. + type: "integer" + format: "int64" + example: 5000000000 + CAConfig: + description: "CA configuration." + type: "object" + x-nullable: true + properties: + NodeCertExpiry: + description: "The duration node certificates are issued for." + type: "integer" + format: "int64" + example: 7776000000000000 + ExternalCAs: + description: | + Configuration for forwarding signing requests to an external + certificate authority. + type: "array" + items: + type: "object" + properties: + Protocol: + description: | + Protocol for communication with the external CA (currently + only `cfssl` is supported). + type: "string" + enum: + - "cfssl" + default: "cfssl" + URL: + description: | + URL where certificate signing requests should be sent. + type: "string" + Options: + description: | + An object with key/value pairs that are interpreted as + protocol-specific options for the external CA driver. + type: "object" + additionalProperties: + type: "string" + CACert: + description: | + The root CA certificate (in PEM format) this external CA uses + to issue TLS certificates (assumed to be to the current swarm + root CA certificate if not provided). + type: "string" + SigningCACert: + description: | + The desired signing CA certificate for all swarm node TLS leaf + certificates, in PEM format. + type: "string" + SigningCAKey: + description: | + The desired signing CA key for all swarm node TLS leaf certificates, + in PEM format. + type: "string" + ForceRotate: + description: | + An integer whose purpose is to force swarm to generate a new + signing CA certificate and key, if none have been specified in + `SigningCACert` and `SigningCAKey` + format: "uint64" + type: "integer" + EncryptionConfig: + description: "Parameters related to encryption-at-rest." + type: "object" + properties: + AutoLockManagers: + description: | + If set, generate a key and use it to lock data stored on the + managers. + type: "boolean" + example: false + TaskDefaults: + description: "Defaults for creating tasks in this cluster." + type: "object" + properties: + LogDriver: + description: | + The log driver to use for tasks created in the orchestrator if + unspecified by a service. + + Updating this value only affects new tasks. Existing tasks continue + to use their previously configured log driver until recreated. + type: "object" + properties: + Name: + description: | + The log driver to use as a default for new tasks. + type: "string" + example: "json-file" + Options: + description: | + Driver-specific options for the selected log driver, specified + as key/value pairs. + type: "object" + additionalProperties: + type: "string" + example: + "max-file": "10" + "max-size": "100m" + + # The Swarm information for `GET /info`. It is the same as `GET /swarm`, but + # without `JoinTokens`. + ClusterInfo: + description: | + ClusterInfo represents information about the swarm as is returned by the + "/info" endpoint. Join-tokens are not included. + x-nullable: true + type: "object" + properties: + ID: + description: "The ID of the swarm." + type: "string" + example: "abajmipo7b4xz5ip2nrla6b11" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + description: | + Date and time at which the swarm was initialised in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2016-08-18T10:44:24.496525531Z" + UpdatedAt: + description: | + Date and time at which the swarm was last updated in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + example: "2017-08-09T07:09:37.632105588Z" + Spec: + $ref: "#/definitions/SwarmSpec" + TLSInfo: + $ref: "#/definitions/TLSInfo" + RootRotationInProgress: + description: | + Whether there is currently a root CA rotation in progress for the swarm + type: "boolean" + example: false + DataPathPort: + description: | + DataPathPort specifies the data path port number for data traffic. + Acceptable port range is 1024 to 49151. + If no port is set or is set to 0, the default port (4789) is used. + type: "integer" + format: "uint32" + default: 4789 + example: 4789 + DefaultAddrPool: + description: | + Default Address Pool specifies default subnet pools for global scope + networks. + type: "array" + items: + type: "string" + format: "CIDR" + example: ["10.10.0.0/16", "20.20.0.0/16"] + SubnetSize: + description: | + SubnetSize specifies the subnet size of the networks created from the + default subnet pool. + type: "integer" + format: "uint32" + maximum: 29 + default: 24 + example: 24 + + JoinTokens: + description: | + JoinTokens contains the tokens workers and managers need to join the swarm. + type: "object" + properties: + Worker: + description: | + The token workers can use to join the swarm. + type: "string" + example: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx" + Manager: + description: | + The token managers can use to join the swarm. + type: "string" + example: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" + + Swarm: + type: "object" + allOf: + - $ref: "#/definitions/ClusterInfo" + - type: "object" + properties: + JoinTokens: + $ref: "#/definitions/JoinTokens" + + TaskSpec: + description: "User modifiable task configuration." + type: "object" + properties: + PluginSpec: + type: "object" + description: | + Plugin spec for the service. *(Experimental release only.)* + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + properties: + Name: + description: "The name or 'alias' to use for the plugin." + type: "string" + Remote: + description: "The plugin image reference to use." + type: "string" + Disabled: + description: "Disable the plugin once scheduled." + type: "boolean" + PluginPrivilege: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + ContainerSpec: + type: "object" + description: | + Container spec for the service. + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + properties: + Image: + description: "The image name to use for the container" + type: "string" + Labels: + description: "User-defined key/value data." + type: "object" + additionalProperties: + type: "string" + Command: + description: "The command to be run in the image." + type: "array" + items: + type: "string" + Args: + description: "Arguments to the command." + type: "array" + items: + type: "string" + Hostname: + description: | + The hostname to use for the container, as a valid + [RFC 1123](https://tools.ietf.org/html/rfc1123) hostname. + type: "string" + Env: + description: | + A list of environment variables in the form `VAR=value`. + type: "array" + items: + type: "string" + Dir: + description: "The working directory for commands to run in." + type: "string" + User: + description: "The user inside the container." + type: "string" + Groups: + type: "array" + description: | + A list of additional groups that the container process will run as. + items: + type: "string" + Privileges: + type: "object" + description: "Security options for the container" + properties: + CredentialSpec: + type: "object" + description: "CredentialSpec for managed service account (Windows only)" + properties: + Config: + type: "string" + example: "0bt9dmxjvjiqermk6xrop3ekq" + description: | + Load credential spec from a Swarm Config with the given ID. + The specified config must also be present in the Configs + field with the Runtime property set. + + <p><br /></p> + + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + File: + type: "string" + example: "spec.json" + description: | + Load credential spec from this file. The file is read by + the daemon, and must be present in the `CredentialSpecs` + subdirectory in the docker data directory, which defaults + to `C:\ProgramData\Docker\` on Windows. + + For example, specifying `spec.json` loads + `C:\ProgramData\Docker\CredentialSpecs\spec.json`. + + <p><br /></p> + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + Registry: + type: "string" + description: | + Load credential spec from this value in the Windows + registry. The specified registry value must be located in: + + `HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs` + + <p><br /></p> + + + > **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`, + > and `CredentialSpec.Config` are mutually exclusive. + SELinuxContext: + type: "object" + description: "SELinux labels of the container" + properties: + Disable: + type: "boolean" + description: "Disable SELinux" + User: + type: "string" + description: "SELinux user label" + Role: + type: "string" + description: "SELinux role label" + Type: + type: "string" + description: "SELinux type label" + Level: + type: "string" + description: "SELinux level label" + Seccomp: + type: "object" + description: "Options for configuring seccomp on the container" + properties: + Mode: + type: "string" + enum: + - "default" + - "unconfined" + - "custom" + Profile: + description: "The custom seccomp profile as a json object" + type: "string" + AppArmor: + type: "object" + description: "Options for configuring AppArmor on the container" + properties: + Mode: + type: "string" + enum: + - "default" + - "disabled" + NoNewPrivileges: + type: "boolean" + description: "Configuration of the no_new_privs bit in the container" + + TTY: + description: "Whether a pseudo-TTY should be allocated." + type: "boolean" + OpenStdin: + description: "Open `stdin`" + type: "boolean" + ReadOnly: + description: "Mount the container's root filesystem as read only." + type: "boolean" + Mounts: + description: | + Specification for mounts to be added to containers created as part + of the service. + type: "array" + items: + $ref: "#/definitions/Mount" + StopSignal: + description: "Signal to stop the container." + type: "string" + StopGracePeriod: + description: | + Amount of time to wait for the container to terminate before + forcefully killing it. + type: "integer" + format: "int64" + Healthcheck: + $ref: "#/definitions/HealthConfig" + Hosts: + type: "array" + description: | + A list of hostname/IP mappings to add to the container's `hosts` + file. The format of extra hosts is specified in the + [hosts(5)](http://man7.org/linux/man-pages/man5/hosts.5.html) + man page: + + IP_address canonical_hostname [aliases...] + items: + type: "string" + DNSConfig: + description: | + Specification for DNS related configurations in resolver configuration + file (`resolv.conf`). + type: "object" + properties: + Nameservers: + description: "The IP addresses of the name servers." + type: "array" + items: + type: "string" + Search: + description: "A search list for host-name lookup." + type: "array" + items: + type: "string" + Options: + description: | + A list of internal resolver variables to be modified (e.g., + `debug`, `ndots:3`, etc.). + type: "array" + items: + type: "string" + Secrets: + description: | + Secrets contains references to zero or more secrets that will be + exposed to the service. + type: "array" + items: + type: "object" + properties: + File: + description: | + File represents a specific target that is backed by a file. + type: "object" + properties: + Name: + description: | + Name represents the final filename in the filesystem. + type: "string" + UID: + description: "UID represents the file UID." + type: "string" + GID: + description: "GID represents the file GID." + type: "string" + Mode: + description: "Mode represents the FileMode of the file." + type: "integer" + format: "uint32" + SecretID: + description: | + SecretID represents the ID of the specific secret that we're + referencing. + type: "string" + SecretName: + description: | + SecretName is the name of the secret that this references, + but this is just provided for lookup/display purposes. The + secret in the reference will be identified by its ID. + type: "string" + OomScoreAdj: + type: "integer" + format: "int64" + description: | + An integer value containing the score given to the container in + order to tune OOM killer preferences. + example: 0 + Configs: + description: | + Configs contains references to zero or more configs that will be + exposed to the service. + type: "array" + items: + type: "object" + properties: + File: + description: | + File represents a specific target that is backed by a file. + + <p><br /><p> + + > **Note**: `Configs.File` and `Configs.Runtime` are mutually exclusive + type: "object" + properties: + Name: + description: | + Name represents the final filename in the filesystem. + type: "string" + UID: + description: "UID represents the file UID." + type: "string" + GID: + description: "GID represents the file GID." + type: "string" + Mode: + description: "Mode represents the FileMode of the file." + type: "integer" + format: "uint32" + Runtime: + description: | + Runtime represents a target that is not mounted into the + container but is used by the task + + <p><br /><p> + + > **Note**: `Configs.File` and `Configs.Runtime` are mutually + > exclusive + type: "object" + ConfigID: + description: | + ConfigID represents the ID of the specific config that we're + referencing. + type: "string" + ConfigName: + description: | + ConfigName is the name of the config that this references, + but this is just provided for lookup/display purposes. The + config in the reference will be identified by its ID. + type: "string" + Isolation: + type: "string" + description: | + Isolation technology of the containers running the service. + (Windows only) + enum: + - "default" + - "process" + - "hyperv" + - "" + Init: + description: | + Run an init inside the container that forwards signals and reaps + processes. This field is omitted if empty, and the default (as + configured on the daemon) is used. + type: "boolean" + x-nullable: true + Sysctls: + description: | + Set kernel namedspaced parameters (sysctls) in the container. + The Sysctls option on services accepts the same sysctls as the + are supported on containers. Note that while the same sysctls are + supported, no guarantees or checks are made about their + suitability for a clustered environment, and it's up to the user + to determine whether a given sysctl will work properly in a + Service. + type: "object" + additionalProperties: + type: "string" + # This option is not used by Windows containers + CapabilityAdd: + type: "array" + description: | + A list of kernel capabilities to add to the default set + for the container. + items: + type: "string" + example: + - "CAP_NET_RAW" + - "CAP_SYS_ADMIN" + - "CAP_SYS_CHROOT" + - "CAP_SYSLOG" + CapabilityDrop: + type: "array" + description: | + A list of kernel capabilities to drop from the default set + for the container. + items: + type: "string" + example: + - "CAP_NET_RAW" + Ulimits: + description: | + A list of resource limits to set in the container. For example: `{"Name": "nofile", "Soft": 1024, "Hard": 2048}`" + type: "array" + items: + type: "object" + properties: + Name: + description: "Name of ulimit" + type: "string" + Soft: + description: "Soft limit" + type: "integer" + Hard: + description: "Hard limit" + type: "integer" + NetworkAttachmentSpec: + description: | + Read-only spec type for non-swarm containers attached to swarm overlay + networks. + + <p><br /></p> + + > **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are + > mutually exclusive. PluginSpec is only used when the Runtime field + > is set to `plugin`. NetworkAttachmentSpec is used when the Runtime + > field is set to `attachment`. + type: "object" + properties: + ContainerID: + description: "ID of the container represented by this task" + type: "string" + Resources: + description: | + Resource requirements which apply to each individual container created + as part of the service. + type: "object" + properties: + Limits: + description: "Define resources limits." + $ref: "#/definitions/Limit" + Reservations: + description: "Define resources reservation." + $ref: "#/definitions/ResourceObject" + SwapBytes: + description: | + Amount of swap in bytes - can only be used together with a memory limit. + If not specified, the default behaviour is to grant a swap space twice + as big as the memory limit. + Set to -1 to enable unlimited swap. + type: "integer" + format: "int64" + minimum: -1 + x-nullable: true + x-omitempty: true + MemorySwappiness: + description: | + Tune the service's containers' memory swappiness (0 to 100). + If not specified, defaults to the containers' OS' default, generally 60, + or whatever value was predefined in the image. + Set to -1 to unset a previously set value. + type: "integer" + format: "int64" + minimum: -1 + maximum: 100 + x-nullable: true + x-omitempty: true + RestartPolicy: + description: | + Specification for the restart policy which applies to containers + created as part of this service. + type: "object" + properties: + Condition: + description: "Condition for restart." + type: "string" + enum: + - "none" + - "on-failure" + - "any" + Delay: + description: "Delay between restart attempts." + type: "integer" + format: "int64" + MaxAttempts: + description: | + Maximum attempts to restart a given container before giving up + (default value is 0, which is ignored). + type: "integer" + format: "int64" + default: 0 + Window: + description: | + Windows is the time window used to evaluate the restart policy + (default value is 0, which is unbounded). + type: "integer" + format: "int64" + default: 0 + Placement: + type: "object" + properties: + Constraints: + description: | + An array of constraint expressions to limit the set of nodes where + a task can be scheduled. Constraint expressions can either use a + _match_ (`==`) or _exclude_ (`!=`) rule. Multiple constraints find + nodes that satisfy every expression (AND match). Constraints can + match node or Docker Engine labels as follows: + + node attribute | matches | example + ---------------------|--------------------------------|----------------------------------------------- + `node.id` | Node ID | `node.id==2ivku8v2gvtg4` + `node.hostname` | Node hostname | `node.hostname!=node-2` + `node.role` | Node role (`manager`/`worker`) | `node.role==manager` + `node.platform.os` | Node operating system | `node.platform.os==windows` + `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` + `node.labels` | User-defined node labels | `node.labels.security==high` + `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-24.04` + + `engine.labels` apply to Docker Engine labels like operating system, + drivers, etc. Swarm administrators add `node.labels` for operational + purposes by using the [`node update endpoint`](#operation/NodeUpdate). + + type: "array" + items: + type: "string" + example: + - "node.hostname!=node3.corp.example.com" + - "node.role!=manager" + - "node.labels.type==production" + - "node.platform.os==linux" + - "node.platform.arch==x86_64" + Preferences: + description: | + Preferences provide a way to make the scheduler aware of factors + such as topology. They are provided in order from highest to + lowest precedence. + type: "array" + items: + type: "object" + properties: + Spread: + type: "object" + properties: + SpreadDescriptor: + description: | + label descriptor, such as `engine.labels.az`. + type: "string" + example: + - Spread: + SpreadDescriptor: "node.labels.datacenter" + - Spread: + SpreadDescriptor: "node.labels.rack" + MaxReplicas: + description: | + Maximum number of replicas for per node (default value is 0, which + is unlimited) + type: "integer" + format: "int64" + default: 0 + Platforms: + description: | + Platforms stores all the platforms that the service's image can + run on. This field is used in the platform filter for scheduling. + If empty, then the platform filter is off, meaning there are no + scheduling restrictions. + type: "array" + items: + $ref: "#/definitions/Platform" + ForceUpdate: + description: | + A counter that triggers an update even if no relevant parameters have + been changed. + type: "integer" + format: "uint64" + Runtime: + description: | + Runtime is the type of runtime specified for the task executor. + type: "string" + Networks: + description: "Specifies which networks the service should attach to." + type: "array" + items: + $ref: "#/definitions/NetworkAttachmentConfig" + LogDriver: + description: | + Specifies the log driver to use for tasks created from this spec. If + not present, the default one for the swarm will be used, finally + falling back to the engine default if not specified. + type: "object" + properties: + Name: + type: "string" + Options: + type: "object" + additionalProperties: + type: "string" + + TaskState: + type: "string" + enum: + - "new" + - "allocated" + - "pending" + - "assigned" + - "accepted" + - "preparing" + - "ready" + - "starting" + - "running" + - "complete" + - "shutdown" + - "failed" + - "rejected" + - "remove" + - "orphaned" + + ContainerStatus: + type: "object" + description: "represents the status of a container." + properties: + ContainerID: + type: "string" + PID: + type: "integer" + ExitCode: + type: "integer" + + PortStatus: + type: "object" + description: "represents the port status of a task's host ports whose service has published host ports" + properties: + Ports: + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + + TaskStatus: + type: "object" + description: "represents the status of a task." + properties: + Timestamp: + type: "string" + format: "dateTime" + State: + $ref: "#/definitions/TaskState" + Message: + type: "string" + Err: + type: "string" + ContainerStatus: + $ref: "#/definitions/ContainerStatus" + PortStatus: + $ref: "#/definitions/PortStatus" + + NetworkAttachment: + description: | + Specifies how a task is attached to a network, and the addresses the + task was assigned on that network. + type: "object" + properties: + Network: + $ref: "#/definitions/Network" + Addresses: + description: | + The IP addresses (in CIDR notation) assigned to the task on this + network. To maintain backward compatibility this field accepts CIDR + notation, but only the IP address is used. + type: "array" + items: + type: "string" + format: "cidr" + example: + Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Addresses: + - "10.255.0.10/16" + + Task: + type: "object" + properties: + ID: + description: "The ID of the task." + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Name: + description: "Name of the task." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Spec: + $ref: "#/definitions/TaskSpec" + ServiceID: + description: "The ID of the service this task is part of." + type: "string" + Slot: + type: "integer" + NodeID: + description: "The ID of the node that this task is on." + type: "string" + AssignedGenericResources: + $ref: "#/definitions/GenericResources" + Status: + $ref: "#/definitions/TaskStatus" + DesiredState: + $ref: "#/definitions/TaskState" + JobIteration: + description: | + If the Service this Task belongs to is a job-mode service, contains + the JobIteration of the Service this Task was created for. Absent if + the Task was created for a Replicated or Global Service. + $ref: "#/definitions/ObjectVersion" + NetworksAttachments: + description: | + The networks that this task is attached to, and the addresses the + task was assigned on each of them. + type: "array" + items: + $ref: "#/definitions/NetworkAttachment" + example: + ID: "0kzzo1i0y4jz6027t0k7aezc7" + Version: + Index: 71 + CreatedAt: "2016-06-07T21:07:31.171892745Z" + UpdatedAt: "2016-06-07T21:07:31.376370513Z" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:31.290032978Z" + State: "running" + Message: "started" + ContainerStatus: + ContainerID: "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035" + PID: 677 + DesiredState: "running" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.10/16" + AssignedGenericResources: + - DiscreteResourceSpec: + Kind: "SSD" + Value: 3 + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID1" + - NamedResourceSpec: + Kind: "GPU" + Value: "UUID2" + + ServiceSpec: + description: "User modifiable configuration for a service." + type: object + properties: + Name: + description: "Name of the service." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + TaskTemplate: + $ref: "#/definitions/TaskSpec" + Mode: + description: "Scheduling mode for the service." + type: "object" + properties: + Replicated: + type: "object" + properties: + Replicas: + type: "integer" + format: "int64" + Global: + type: "object" + ReplicatedJob: + description: | + The mode used for services with a finite number of tasks that run + to a completed state. + type: "object" + properties: + MaxConcurrent: + description: | + The maximum number of replicas to run simultaneously. + type: "integer" + format: "int64" + default: 1 + TotalCompletions: + description: | + The total number of replicas desired to reach the Completed + state. If unset, will default to the value of `MaxConcurrent` + type: "integer" + format: "int64" + GlobalJob: + description: | + The mode used for services which run a task to the completed state + on each valid node. + type: "object" + UpdateConfig: + description: "Specification for the update strategy of the service." + type: "object" + properties: + Parallelism: + description: | + Maximum number of tasks to be updated in one iteration (0 means + unlimited parallelism). + type: "integer" + format: "int64" + Delay: + description: "Amount of time between updates, in nanoseconds." + type: "integer" + format: "int64" + FailureAction: + description: | + Action to take if an updated task fails to run, or stops running + during the update. + type: "string" + enum: + - "continue" + - "pause" + - "rollback" + Monitor: + description: | + Amount of time to monitor each updated task for failures, in + nanoseconds. + type: "integer" + format: "int64" + MaxFailureRatio: + description: | + The fraction of tasks that may fail during an update before the + failure action is invoked, specified as a floating point number + between 0 and 1. + type: "number" + default: 0 + Order: + description: | + The order of operations when rolling out an updated task. Either + the old task is shut down before the new task is started, or the + new task is started before the old task is shut down. + type: "string" + enum: + - "stop-first" + - "start-first" + RollbackConfig: + description: "Specification for the rollback strategy of the service." + type: "object" + properties: + Parallelism: + description: | + Maximum number of tasks to be rolled back in one iteration (0 means + unlimited parallelism). + type: "integer" + format: "int64" + Delay: + description: | + Amount of time between rollback iterations, in nanoseconds. + type: "integer" + format: "int64" + FailureAction: + description: | + Action to take if an rolled back task fails to run, or stops + running during the rollback. + type: "string" + enum: + - "continue" + - "pause" + Monitor: + description: | + Amount of time to monitor each rolled back task for failures, in + nanoseconds. + type: "integer" + format: "int64" + MaxFailureRatio: + description: | + The fraction of tasks that may fail during a rollback before the + failure action is invoked, specified as a floating point number + between 0 and 1. + type: "number" + default: 0 + Order: + description: | + The order of operations when rolling back a task. Either the old + task is shut down before the new task is started, or the new task + is started before the old task is shut down. + type: "string" + enum: + - "stop-first" + - "start-first" + Networks: + description: | + Specifies which networks the service should attach to. + + Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. + type: "array" + items: + $ref: "#/definitions/NetworkAttachmentConfig" + + EndpointSpec: + $ref: "#/definitions/EndpointSpec" + + EndpointPortConfig: + type: "object" + properties: + Name: + type: "string" + Protocol: + type: "string" + enum: + - "tcp" + - "udp" + - "sctp" + TargetPort: + description: "The port inside the container." + type: "integer" + PublishedPort: + description: "The port on the swarm hosts." + type: "integer" + PublishMode: + description: | + The mode in which port is published. + + <p><br /></p> + + - "ingress" makes the target port accessible on every node, + regardless of whether there is a task for the service running on + that node or not. + - "host" bypasses the routing mesh and publish the port directly on + the swarm node where that service is running. + + type: "string" + enum: + - "ingress" + - "host" + default: "ingress" + example: "ingress" + + EndpointSpec: + description: "Properties that can be configured to access and load balance a service." + type: "object" + properties: + Mode: + description: | + The mode of resolution to use for internal load balancing between tasks. + type: "string" + enum: + - "vip" + - "dnsrr" + default: "vip" + Ports: + description: | + List of exposed ports that this service is accessible on from the + outside. Ports can only be provided if `vip` resolution mode is used. + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + + Service: + type: "object" + properties: + ID: + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ServiceSpec" + Endpoint: + type: "object" + properties: + Spec: + $ref: "#/definitions/EndpointSpec" + Ports: + type: "array" + items: + $ref: "#/definitions/EndpointPortConfig" + VirtualIPs: + type: "array" + items: + type: "object" + properties: + NetworkID: + type: "string" + Addr: + type: "string" + UpdateStatus: + description: "The status of a service update." + type: "object" + properties: + State: + type: "string" + enum: + - "updating" + - "paused" + - "completed" + StartedAt: + type: "string" + format: "dateTime" + CompletedAt: + type: "string" + format: "dateTime" + Message: + type: "string" + ServiceStatus: + description: | + The status of the service's tasks. Provided only when requested as + part of a ServiceList operation. + type: "object" + properties: + RunningTasks: + description: | + The number of tasks for the service currently in the Running state. + type: "integer" + format: "uint64" + example: 7 + DesiredTasks: + description: | + The number of tasks for the service desired to be running. + For replicated services, this is the replica count from the + service spec. For global services, this is computed by taking + count of all tasks for the service with a Desired State other + than Shutdown. + type: "integer" + format: "uint64" + example: 10 + CompletedTasks: + description: | + The number of tasks for a job that are in the Completed state. + This field must be cross-referenced with the service type, as the + value of 0 may mean the service is not in a job mode, or it may + mean the job-mode service has no tasks yet Completed. + type: "integer" + format: "uint64" + JobStatus: + description: | + The status of the service when it is in one of ReplicatedJob or + GlobalJob modes. Absent on Replicated and Global mode services. The + JobIteration is an ObjectVersion, but unlike the Service's version, + does not need to be sent with an update request. + type: "object" + properties: + JobIteration: + description: | + JobIteration is a value increased each time a Job is executed, + successfully or otherwise. "Executed", in this case, means the + job as a whole has been started, not that an individual Task has + been launched. A job is "Executed" when its ServiceSpec is + updated. JobIteration can be used to disambiguate Tasks belonging + to different executions of a job. Though JobIteration will + increase with each subsequent execution, it may not necessarily + increase by 1, and so JobIteration should not be used to + $ref: "#/definitions/ObjectVersion" + LastExecution: + description: | + The last time, as observed by the server, that this job was + started. + type: "string" + format: "dateTime" + example: + ID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Version: + Index: 19 + CreatedAt: "2016-06-07T21:05:51.880065305Z" + UpdatedAt: "2016-06-07T21:07:29.962229872Z" + Spec: + Name: "hopeful_cori" + TaskTemplate: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ForceUpdate: 0 + Mode: + Replicated: + Replicas: 1 + UpdateConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Mode: "vip" + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + Endpoint: + Spec: + Mode: "vip" + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + Ports: + - + Protocol: "tcp" + TargetPort: 6379 + PublishedPort: 30001 + VirtualIPs: + - + NetworkID: "4qvuz4ko70xaltuqbt8956gd1" + Addr: "10.255.0.2/16" + - + NetworkID: "4qvuz4ko70xaltuqbt8956gd1" + Addr: "10.255.0.3/16" + + ImageDeleteResponseItem: + type: "object" + x-go-name: "DeleteResponse" + properties: + Untagged: + description: "The image ID of an image that was untagged" + type: "string" + Deleted: + description: "The image ID of an image that was deleted" + type: "string" + + ServiceCreateResponse: + type: "object" + description: | + contains the information returned to a client on the + creation of a new service. + properties: + ID: + description: "The ID of the created service." + type: "string" + x-nullable: false + example: "ak7w3gjqoa3kuz8xcpnyy0pvl" + Warnings: + description: | + Optional warning message. + + FIXME(thaJeztah): this should have "omitempty" in the generated type. + type: "array" + x-nullable: true + items: + type: "string" + example: + - "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" + + ServiceUpdateResponse: + type: "object" + properties: + Warnings: + description: "Optional warning messages" + type: "array" + items: + type: "string" + example: + Warnings: + - "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found" + + ContainerInspectResponse: + type: "object" + title: "ContainerInspectResponse" + x-go-name: "InspectResponse" + properties: + Id: + description: |- + The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes). + type: "string" + x-go-name: "ID" + minLength: 64 + maxLength: 64 + pattern: "^[0-9a-fA-F]{64}$" + example: "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf" + Created: + description: |- + Date and time at which the container was created, formatted in + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. + type: "string" + format: "dateTime" + x-nullable: true + example: "2025-02-17T17:43:39.64001363Z" + Path: + description: |- + The path to the command being run + type: "string" + example: "/bin/sh" + Args: + description: "The arguments to the command being run" + type: "array" + items: + type: "string" + example: + - "-c" + - "exit 9" + State: + $ref: "#/definitions/ContainerState" + Image: + description: |- + The ID (digest) of the image that this container was created from. + type: "string" + example: "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782" + ResolvConfPath: + description: |- + Location of the `/etc/resolv.conf` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf" + HostnamePath: + description: |- + Location of the `/etc/hostname` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname" + HostsPath: + description: |- + Location of the `/etc/hosts` generated for the container on the + host. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + example: "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts" + LogPath: + description: |- + Location of the file used to buffer the container's logs. Depending on + the logging-driver used for the container, this field may be omitted. + + This file is managed through the docker daemon, and should not be + accessed or modified by other tools. + type: "string" + x-nullable: true + example: "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log" + Name: + description: |- + The name associated with this container. + + For historic reasons, the name may be prefixed with a forward-slash (`/`). + type: "string" + example: "/funny_chatelet" + RestartCount: + description: |- + Number of times the container was restarted since it was created, + or since daemon was started. + type: "integer" + example: 0 + Driver: + description: |- + The storage-driver used for the container's filesystem (graph-driver + or snapshotter). + type: "string" + example: "overlayfs" + Platform: + description: |- + The platform (operating system) for which the container was created. + + This field was introduced for the experimental "LCOW" (Linux Containers + On Windows) features, which has been removed. In most cases, this field + is equal to the host's operating system (`linux` or `windows`). + type: "string" + example: "linux" + ImageManifestDescriptor: + $ref: "#/definitions/OCIDescriptor" + description: |- + OCI descriptor of the platform-specific manifest of the image + the container was created from. + + Note: Only available if the daemon provides a multi-platform + image store. + MountLabel: + description: |- + SELinux mount label set for the container. + type: "string" + example: "" + ProcessLabel: + description: |- + SELinux process label set for the container. + type: "string" + example: "" + AppArmorProfile: + description: |- + The AppArmor profile set for the container. + type: "string" + example: "" + ExecIDs: + description: |- + IDs of exec instances that are running in the container. + type: "array" + items: + type: "string" + x-nullable: true + example: + - "b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca" + - "3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4" + HostConfig: + $ref: "#/definitions/HostConfig" + GraphDriver: + $ref: "#/definitions/DriverData" + x-nullable: true + Storage: + $ref: "#/definitions/Storage" + x-nullable: true + SizeRw: + description: |- + The size of files that have been created or changed by this container. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "122880" + SizeRootFs: + description: |- + The total size of all files in the read-only layers from the image + that the container uses. These layers can be shared between containers. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "1653948416" + Mounts: + description: |- + List of mounts used by the container. + type: "array" + items: + $ref: "#/definitions/MountPoint" + Config: + $ref: "#/definitions/ContainerConfig" + NetworkSettings: + $ref: "#/definitions/NetworkSettings" + + ContainerSummary: + type: "object" + properties: + Id: + description: |- + The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes). + type: "string" + x-go-name: "ID" + minLength: 64 + maxLength: 64 + pattern: "^[0-9a-fA-F]{64}$" + example: "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf" + Names: + description: |- + The names associated with this container. Most containers have a single + name, but when using legacy "links", the container can have multiple + names. + + For historic reasons, names are prefixed with a forward-slash (`/`). + type: "array" + items: + type: "string" + example: + - "/funny_chatelet" + Image: + description: |- + The name or ID of the image used to create the container. + + This field shows the image reference as was specified when creating the container, + which can be in its canonical form (e.g., `docker.io/library/ubuntu:latest` + or `docker.io/library/ubuntu@sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`), + short form (e.g., `ubuntu:latest`)), or the ID(-prefix) of the image (e.g., `72297848456d`). + + The content of this field can be updated at runtime if the image used to + create the container is untagged, in which case the field is updated to + contain the the image ID (digest) it was resolved to in its canonical, + non-truncated form (e.g., `sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`). + type: "string" + example: "docker.io/library/ubuntu:latest" + ImageID: + description: |- + The ID (digest) of the image that this container was created from. + type: "string" + example: "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782" + ImageManifestDescriptor: + $ref: "#/definitions/OCIDescriptor" + x-nullable: true + description: | + OCI descriptor of the platform-specific manifest of the image + the container was created from. + + Note: Only available if the daemon provides a multi-platform + image store. + + This field is not populated in the `GET /system/df` endpoint. + Command: + description: "Command to run when starting the container" + type: "string" + example: "/bin/bash" + Created: + description: |- + Date and time at which the container was created as a Unix timestamp + (number of seconds since EPOCH). + type: "integer" + format: "int64" + example: "1739811096" + Ports: + description: |- + Port-mappings for the container. + type: "array" + items: + $ref: "#/definitions/PortSummary" + SizeRw: + description: |- + The size of files that have been created or changed by this container. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "122880" + SizeRootFs: + description: |- + The total size of all files in the read-only layers from the image + that the container uses. These layers can be shared between containers. + + This field is omitted by default, and only set when size is requested + in the API request. + type: "integer" + format: "int64" + x-nullable: true + example: "1653948416" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.vendor: "Acme" + com.example.license: "GPL" + com.example.version: "1.0" + State: + description: | + The state of this container. + type: "string" + enum: + - "created" + - "running" + - "paused" + - "restarting" + - "exited" + - "removing" + - "dead" + example: "running" + Status: + description: |- + Additional human-readable status of this container (e.g. `Exit 0`) + type: "string" + example: "Up 4 days" + HostConfig: + type: "object" + description: |- + Summary of host-specific runtime information of the container. This + is a reduced set of information in the container's "HostConfig" as + available in the container "inspect" response. + properties: + NetworkMode: + description: |- + Networking mode (`host`, `none`, `container:<id>`) or name of the + primary network the container is using. + + This field is primarily for backward compatibility. The container + can be connected to multiple networks for which information can be + found in the `NetworkSettings.Networks` field, which enumerates + settings per network. + type: "string" + example: "mynetwork" + Annotations: + description: |- + Arbitrary key-value metadata attached to the container. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + io.kubernetes.docker.type: "container" + io.kubernetes.sandbox.id: "3befe639bed0fd6afdd65fd1fa84506756f59360ec4adc270b0fdac9be22b4d3" + NetworkSettings: + description: |- + Summary of the container's network settings + type: "object" + properties: + Networks: + type: "object" + description: |- + Summary of network-settings for each network the container is + attached to. + additionalProperties: + $ref: "#/definitions/EndpointSettings" + Mounts: + type: "array" + description: |- + List of mounts used by the container. + items: + $ref: "#/definitions/MountPoint" + Health: + type: "object" + description: |- + Summary of health status + + Added in v1.52, before that version all container summary not include Health. + After this attribute introduced, it includes containers with no health checks configured, + or containers that are not running with none + properties: + Status: + type: "string" + description: |- + the health status of the container + enum: + - "none" + - "starting" + - "healthy" + - "unhealthy" + example: "healthy" + FailingStreak: + description: "FailingStreak is the number of consecutive failures" + type: "integer" + example: 0 + + ContainersDiskUsage: + type: "object" + x-go-name: "DiskUsage" + x-go-package: "github.com/moby/moby/api/types/container" + description: | + represents system data usage information for container resources. + properties: + ActiveCount: + description: | + Count of active containers. + type: "integer" + format: "int64" + example: 1 + TotalCount: + description: | + Count of all containers. + type: "integer" + format: "int64" + example: 4 + Reclaimable: + description: | + Disk space that can be reclaimed by removing inactive containers. + type: "integer" + format: "int64" + example: 12345678 + TotalSize: + description: | + Disk space in use by containers. + type: "integer" + format: "int64" + example: 98765432 + Items: + description: | + List of container summaries. + type: "array" + x-omitempty: true + items: + x-go-type: + type: Summary + + Driver: + description: "Driver represents a driver (network, logging, secrets)." + type: "object" + required: [Name] + properties: + Name: + description: "Name of the driver." + type: "string" + x-nullable: false + example: "some-driver" + Options: + description: "Key/value map of driver-specific options." + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + OptionA: "value for driver-specific option A" + OptionB: "value for driver-specific option B" + + SecretSpec: + type: "object" + properties: + Name: + description: "User-defined name of the secret." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + Data: + description: | + Data is the data to store as a secret, formatted as a standard base64-encoded + ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. + It must be empty if the Driver field is set, in which case the data is + loaded from an external secret store. The maximum allowed size is 500KB, + as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize). + + This field is only used to _create_ a secret, and is not returned by + other endpoints. + type: "string" + example: "" + Driver: + description: | + Name of the secrets driver used to fetch the secret's value from an + external secret store. + $ref: "#/definitions/Driver" + Templating: + description: | + Templating driver, if applicable + + Templating controls whether and how to evaluate the config payload as + a template. If no driver is set, no templating is used. + $ref: "#/definitions/Driver" + + Secret: + type: "object" + properties: + ID: + type: "string" + example: "blt1owaxmitz71s9v5zh81zun" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" + UpdatedAt: + type: "string" + format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" + Spec: + $ref: "#/definitions/SecretSpec" + + ConfigSpec: + type: "object" + properties: + Name: + description: "User-defined name of the config." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Data: + description: | + Data is the data to store as a config, formatted as a standard base64-encoded + ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. + The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). + type: "string" + Templating: + description: | + Templating driver, if applicable + + Templating controls whether and how to evaluate the config payload as + a template. If no driver is set, no templating is used. + $ref: "#/definitions/Driver" + + Config: + type: "object" + properties: + ID: + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ConfigSpec" + + ContainerState: + description: | + ContainerState stores container's running state. It's part of ContainerJSONBase + and will be returned by the "inspect" command. + type: "object" + x-nullable: true + properties: + Status: + description: | + String representation of the container state. Can be one of "created", + "running", "paused", "restarting", "removing", "exited", or "dead". + type: "string" + enum: ["created", "running", "paused", "restarting", "removing", "exited", "dead"] + example: "running" + Running: + description: | + Whether this container is running. + + Note that a running container can be _paused_. The `Running` and `Paused` + booleans are not mutually exclusive: + + When pausing a container (on Linux), the freezer cgroup is used to suspend + all processes in the container. Freezing the process requires the process to + be running. As a result, paused containers are both `Running` _and_ `Paused`. + + Use the `Status` field instead to determine if a container's state is "running". + type: "boolean" + example: true + Paused: + description: "Whether this container is paused." + type: "boolean" + example: false + Restarting: + description: "Whether this container is restarting." + type: "boolean" + example: false + OOMKilled: + description: | + Whether a process within this container has been killed because it ran + out of memory since the container was last started. + type: "boolean" + example: false + Dead: + type: "boolean" + example: false + Pid: + description: "The process ID of this container" + type: "integer" + example: 1234 + ExitCode: + description: "The last exit code of this container" + type: "integer" + example: 0 + Error: + type: "string" + StartedAt: + description: "The time when this container was last started." + type: "string" + example: "2020-01-06T09:06:59.461876391Z" + FinishedAt: + description: "The time when this container last exited." + type: "string" + example: "2020-01-06T09:07:59.461876391Z" + Health: + $ref: "#/definitions/Health" + + ContainerCreateResponse: + description: "OK response to ContainerCreate operation" + type: "object" + title: "ContainerCreateResponse" + x-go-name: "CreateResponse" + required: [Id, Warnings] + properties: + Id: + description: "The ID of the created container" + type: "string" + x-nullable: false + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + Warnings: + description: "Warnings encountered when creating the container" + type: "array" + x-nullable: false + items: + type: "string" + example: [] + + ContainerUpdateResponse: + type: "object" + title: "ContainerUpdateResponse" + x-go-name: "UpdateResponse" + description: |- + Response for a successful container-update. + properties: + Warnings: + type: "array" + description: |- + Warnings encountered when updating the container. + items: + type: "string" + example: ["Published ports are discarded when using host network mode"] + + ContainerStatsResponse: + description: | + Statistics sample for a container. + type: "object" + x-go-name: "StatsResponse" + title: "ContainerStatsResponse" + properties: + id: + description: | + ID of the container for which the stats were collected. + type: "string" + x-nullable: true + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + name: + description: | + Name of the container for which the stats were collected. + type: "string" + x-nullable: true + example: "boring_wozniak" + os_type: + description: | + OSType is the OS of the container ("linux" or "windows") to allow + platform-specific handling of stats. + type: "string" + x-nullable: true + example: "linux" + read: + description: | + Date and time at which this sample was collected. + The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + with nano-seconds. + type: "string" + format: "date-time" + example: "2025-01-16T13:55:22.165243637Z" + cpu_stats: + $ref: "#/definitions/ContainerCPUStats" + memory_stats: + $ref: "#/definitions/ContainerMemoryStats" + networks: + description: | + Network statistics for the container per interface. + + This field is omitted if the container has no networking enabled. + x-nullable: true + additionalProperties: + $ref: "#/definitions/ContainerNetworkStats" + example: + eth0: + rx_bytes: 5338 + rx_dropped: 0 + rx_errors: 0 + rx_packets: 36 + tx_bytes: 648 + tx_dropped: 0 + tx_errors: 0 + tx_packets: 8 + eth5: + rx_bytes: 4641 + rx_dropped: 0 + rx_errors: 0 + rx_packets: 26 + tx_bytes: 690 + tx_dropped: 0 + tx_errors: 0 + tx_packets: 9 + pids_stats: + $ref: "#/definitions/ContainerPidsStats" + blkio_stats: + $ref: "#/definitions/ContainerBlkioStats" + num_procs: + description: | + The number of processors on the system. + + This field is Windows-specific and always zero for Linux containers. + type: "integer" + format: "uint32" + example: 16 + storage_stats: + $ref: "#/definitions/ContainerStorageStats" + preread: + description: | + Date and time at which this first sample was collected. This field + is not propagated if the "one-shot" option is set. If the "one-shot" + option is set, this field may be omitted, empty, or set to a default + date (`0001-01-01T00:00:00Z`). + + The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + with nano-seconds. + type: "string" + format: "date-time" + example: "2025-01-16T13:55:21.160452595Z" + precpu_stats: + $ref: "#/definitions/ContainerCPUStats" + + ContainerBlkioStats: + description: | + BlkioStats stores all IO service stats for data read and write. + + This type is Linux-specific and holds many fields that are specific to cgroups v1. + On a cgroup v2 host, all fields other than `io_service_bytes_recursive` + are omitted or `null`. + + This type is only populated on Linux and omitted for Windows containers. + type: "object" + x-go-name: "BlkioStats" + x-nullable: true + properties: + io_service_bytes_recursive: + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_serviced_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_queue_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_service_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_wait_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_merged_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + io_time_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + sectors_recursive: + description: | + This field is only available when using Linux containers with + cgroups v1. It is omitted or `null` when using cgroups v2. + x-nullable: true + type: "array" + items: + $ref: "#/definitions/ContainerBlkioStatEntry" + example: + io_service_bytes_recursive: + - {"major": 254, "minor": 0, "op": "read", "value": 7593984} + - {"major": 254, "minor": 0, "op": "write", "value": 100} + io_serviced_recursive: null + io_queue_recursive: null + io_service_time_recursive: null + io_wait_time_recursive: null + io_merged_recursive: null + io_time_recursive: null + sectors_recursive: null + + ContainerBlkioStatEntry: + description: | + Blkio stats entry. + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "BlkioStatEntry" + x-nullable: true + properties: + major: + type: "integer" + format: "uint64" + example: 254 + minor: + type: "integer" + format: "uint64" + example: 0 + op: + type: "string" + example: "read" + value: + type: "integer" + format: "uint64" + example: 7593984 + + ContainerCPUStats: + description: | + CPU related info of the container + type: "object" + x-go-name: "CPUStats" + x-nullable: true + properties: + cpu_usage: + $ref: "#/definitions/ContainerCPUUsage" + system_cpu_usage: + description: | + System Usage. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 5 + online_cpus: + description: | + Number of online CPUs. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint32" + x-nullable: true + example: 5 + throttling_data: + $ref: "#/definitions/ContainerThrottlingData" + + ContainerCPUUsage: + description: | + All CPU stats aggregated since container inception. + type: "object" + x-go-name: "CPUUsage" + x-nullable: true + properties: + total_usage: + description: | + Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows). + type: "integer" + format: "uint64" + example: 29912000 + percpu_usage: + description: | + Total CPU time (in nanoseconds) consumed per core (Linux). + + This field is Linux-specific when using cgroups v1. It is omitted + when using cgroups v2 and Windows containers. + type: "array" + x-nullable: true + items: + type: "integer" + format: "uint64" + example: 29912000 + + usage_in_kernelmode: + description: | + Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), + or time spent (in 100's of nanoseconds) by all container processes in + kernel mode (Windows). + + Not populated for Windows containers using Hyper-V isolation. + type: "integer" + format: "uint64" + example: 21994000 + usage_in_usermode: + description: | + Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), + or time spent (in 100's of nanoseconds) by all container processes in + kernel mode (Windows). + + Not populated for Windows containers using Hyper-V isolation. + type: "integer" + format: "uint64" + example: 7918000 + + ContainerPidsStats: + description: | + PidsStats contains Linux-specific stats of a container's process-IDs (PIDs). + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "PidsStats" + x-nullable: true + properties: + current: + description: | + Current is the number of PIDs in the cgroup. + type: "integer" + format: "uint64" + x-nullable: true + example: 5 + limit: + description: | + Limit is the hard limit on the number of pids in the cgroup. + A "Limit" of 0 means that there is no limit. + type: "integer" + format: "uint64" + x-nullable: true + example: "18446744073709551615" + + ContainerThrottlingData: + description: | + CPU throttling stats of the container. + + This type is Linux-specific and omitted for Windows containers. + type: "object" + x-go-name: "ThrottlingData" + x-nullable: true + properties: + periods: + description: | + Number of periods with throttling active. + type: "integer" + format: "uint64" + example: 0 + throttled_periods: + description: | + Number of periods when the container hit its throttling limit. + type: "integer" + format: "uint64" + example: 0 + throttled_time: + description: | + Aggregated time (in nanoseconds) the container was throttled for. + type: "integer" + format: "uint64" + example: 0 + + ContainerMemoryStats: + description: | + Aggregates all memory stats since container inception on Linux. + Windows returns stats for commit and private working set only. + type: "object" + x-go-name: "MemoryStats" + properties: + usage: + description: | + Current `res_counter` usage for memory. + + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + max_usage: + description: | + Maximum usage ever recorded. + + This field is Linux-specific and only supported on cgroups v1. + It is omitted when using cgroups v2 and for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + stats: + description: | + All the stats exported via memory.stat. + + The fields in this object differ between cgroups v1 and v2. + On cgroups v1, fields such as `cache`, `rss`, `mapped_file` are available. + On cgroups v2, fields such as `file`, `anon`, `inactive_file` are available. + + This field is Linux-specific and omitted for Windows containers. + type: "object" + additionalProperties: + type: "integer" + format: "uint64" + x-nullable: true + example: + { + "active_anon": 1572864, + "active_file": 5115904, + "anon": 1572864, + "anon_thp": 0, + "file": 7626752, + "file_dirty": 0, + "file_mapped": 2723840, + "file_writeback": 0, + "inactive_anon": 0, + "inactive_file": 2510848, + "kernel_stack": 16384, + "pgactivate": 0, + "pgdeactivate": 0, + "pgfault": 2042, + "pglazyfree": 0, + "pglazyfreed": 0, + "pgmajfault": 45, + "pgrefill": 0, + "pgscan": 0, + "pgsteal": 0, + "shmem": 0, + "slab": 1180928, + "slab_reclaimable": 725576, + "slab_unreclaimable": 455352, + "sock": 0, + "thp_collapse_alloc": 0, + "thp_fault_alloc": 1, + "unevictable": 0, + "workingset_activate": 0, + "workingset_nodereclaim": 0, + "workingset_refault": 0 + } + failcnt: + description: | + Number of times memory usage hits limits. + + This field is Linux-specific and only supported on cgroups v1. + It is omitted when using cgroups v2 and for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + limit: + description: | + This field is Linux-specific and omitted for Windows containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 8217579520 + commitbytes: + description: | + Committed bytes. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + commitpeakbytes: + description: | + Peak committed bytes. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + privateworkingset: + description: | + Private working set. + + This field is Windows-specific and omitted for Linux containers. + type: "integer" + format: "uint64" + x-nullable: true + example: 0 + + ContainerNetworkStats: + description: | + Aggregates the network stats of one container + type: "object" + x-go-name: "NetworkStats" + x-nullable: true + properties: + rx_bytes: + description: | + Bytes received. Windows and Linux. + type: "integer" + format: "uint64" + example: 5338 + rx_packets: + description: | + Packets received. Windows and Linux. + type: "integer" + format: "uint64" + example: 36 + rx_errors: + description: | + Received errors. Not used on Windows. + + This field is Linux-specific and always zero for Windows containers. + type: "integer" + format: "uint64" + example: 0 + rx_dropped: + description: | + Incoming packets dropped. Windows and Linux. + type: "integer" + format: "uint64" + example: 0 + tx_bytes: + description: | + Bytes sent. Windows and Linux. + type: "integer" + format: "uint64" + example: 1200 + tx_packets: + description: | + Packets sent. Windows and Linux. + type: "integer" + format: "uint64" + example: 12 + tx_errors: + description: | + Sent errors. Not used on Windows. + + This field is Linux-specific and always zero for Windows containers. + type: "integer" + format: "uint64" + example: 0 + tx_dropped: + description: | + Outgoing packets dropped. Windows and Linux. + type: "integer" + format: "uint64" + example: 0 + endpoint_id: + description: | + Endpoint ID. Not used on Linux. + + This field is Windows-specific and omitted for Linux containers. + type: "string" + x-nullable: true + instance_id: + description: | + Instance ID. Not used on Linux. + + This field is Windows-specific and omitted for Linux containers. + type: "string" + x-nullable: true + + ContainerStorageStats: + description: | + StorageStats is the disk I/O stats for read/write on Windows. + + This type is Windows-specific and omitted for Linux containers. + type: "object" + x-go-name: "StorageStats" + x-nullable: true + properties: + read_count_normalized: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + read_size_bytes: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + write_count_normalized: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + write_size_bytes: + type: "integer" + format: "uint64" + x-nullable: true + example: 7593984 + + ContainerTopResponse: + type: "object" + x-go-name: "TopResponse" + title: "ContainerTopResponse" + description: |- + Container "top" response. + properties: + Titles: + description: "The ps column titles" + type: "array" + items: + type: "string" + example: + Titles: + - "UID" + - "PID" + - "PPID" + - "C" + - "STIME" + - "TTY" + - "TIME" + - "CMD" + Processes: + description: |- + Each process running in the container, where each process + is an array of values corresponding to the titles. + type: "array" + items: + type: "array" + items: + type: "string" + example: + Processes: + - + - "root" + - "13642" + - "882" + - "0" + - "17:03" + - "pts/0" + - "00:00:00" + - "/bin/bash" + - + - "root" + - "13735" + - "13642" + - "0" + - "17:06" + - "pts/0" + - "00:00:00" + - "sleep 10" + + ContainerWaitResponse: + description: "OK response to ContainerWait operation" + type: "object" + x-go-name: "WaitResponse" + title: "ContainerWaitResponse" + required: [StatusCode] + properties: + StatusCode: + description: "Exit code of the container" + type: "integer" + format: "int64" + x-nullable: false + Error: + $ref: "#/definitions/ContainerWaitExitError" + + ContainerWaitExitError: + description: "container waiting error, if any" + type: "object" + x-go-name: "WaitExitError" + properties: + Message: + description: "Details of an error" + type: "string" + + SystemVersion: + type: "object" + description: | + Response of Engine API: GET "/version" + properties: + Platform: + type: "object" + required: [Name] + properties: + Name: + type: "string" + Components: + type: "array" + description: | + Information about system components + items: + type: "object" + x-go-name: ComponentVersion + required: [Name, Version] + properties: + Name: + description: | + Name of the component + type: "string" + example: "Engine" + Version: + description: | + Version of the component + type: "string" + x-nullable: false + example: "27.0.1" + Details: + description: | + Key/value pairs of strings with additional information about the + component. These values are intended for informational purposes + only, and their content is not defined, and not part of the API + specification. + + These messages can be printed by the client as information to the user. + type: "object" + x-nullable: true + Version: + description: "The version of the daemon" + type: "string" + example: "27.0.1" + ApiVersion: + description: | + The default (and highest) API version that is supported by the daemon + type: "string" + example: "1.47" + MinAPIVersion: + description: | + The minimum API version that is supported by the daemon + type: "string" + example: "1.24" + GitCommit: + description: | + The Git commit of the source code that was used to build the daemon + type: "string" + example: "48a66213fe" + GoVersion: + description: | + The version Go used to compile the daemon, and the version of the Go + runtime in use. + type: "string" + example: "go1.22.7" + Os: + description: | + The operating system that the daemon is running on ("linux" or "windows") + type: "string" + example: "linux" + Arch: + description: | + Architecture of the daemon, as returned by the Go runtime (`GOARCH`). + + A full list of possible values can be found in the [Go documentation](https://go.dev/doc/install/source#environment). + type: "string" + example: "amd64" + KernelVersion: + description: | + The kernel version (`uname -r`) that the daemon is running on. + + This field is omitted when empty. + type: "string" + example: "6.8.0-31-generic" + Experimental: + description: | + Indicates if the daemon is started with experimental features enabled. + + This field is omitted when empty / false. + type: "boolean" + example: true + BuildTime: + description: | + The date and time that the daemon was compiled. + type: "string" + example: "2020-06-22T15:49:27.000000000+00:00" + + SystemInfo: + type: "object" + properties: + ID: + description: | + Unique identifier of the daemon. + + <p><br /></p> + + > **Note**: The format of the ID itself is not part of the API, and + > should not be considered stable. + type: "string" + example: "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS" + Containers: + description: "Total number of containers on the host." + type: "integer" + example: 14 + ContainersRunning: + description: | + Number of containers with status `"running"`. + type: "integer" + example: 3 + ContainersPaused: + description: | + Number of containers with status `"paused"`. + type: "integer" + example: 1 + ContainersStopped: + description: | + Number of containers with status `"stopped"`. + type: "integer" + example: 10 + Images: + description: | + Total number of images on the host. + + Both _tagged_ and _untagged_ (dangling) images are counted. + type: "integer" + example: 508 + Driver: + description: "Name of the storage driver in use." + type: "string" + example: "overlay2" + DriverStatus: + description: | + Information specific to the storage driver, provided as + "label" / "value" pairs. + + This information is provided by the storage driver, and formatted + in a way consistent with the output of `docker info` on the command + line. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["Backing Filesystem", "extfs"] + - ["Supports d_type", "true"] + - ["Native Overlay Diff", "true"] + DockerRootDir: + description: | + Root directory of persistent Docker state. + + Defaults to `/var/lib/docker` on Linux, and `C:\ProgramData\docker` + on Windows. + type: "string" + example: "/var/lib/docker" + Plugins: + $ref: "#/definitions/PluginsInfo" + MemoryLimit: + description: "Indicates if the host has memory limit support enabled." + type: "boolean" + example: true + SwapLimit: + description: "Indicates if the host has memory swap limit support enabled." + type: "boolean" + example: true + CpuCfsPeriod: + description: | + Indicates if CPU CFS(Completely Fair Scheduler) period is supported by + the host. + type: "boolean" + example: true + CpuCfsQuota: + description: | + Indicates if CPU CFS(Completely Fair Scheduler) quota is supported by + the host. + type: "boolean" + example: true + CPUShares: + description: | + Indicates if CPU Shares limiting is supported by the host. + type: "boolean" + example: true + CPUSet: + description: | + Indicates if CPUsets (cpuset.cpus, cpuset.mems) are supported by the host. + + See [cpuset(7)](https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt) + type: "boolean" + example: true + PidsLimit: + description: "Indicates if the host kernel has PID limit support enabled." + type: "boolean" + example: true + OomKillDisable: + description: "Indicates if OOM killer disable is supported on the host." + type: "boolean" + IPv4Forwarding: + description: "Indicates IPv4 forwarding is enabled." + type: "boolean" + example: true + Debug: + description: | + Indicates if the daemon is running in debug-mode / with debug-level + logging enabled. + type: "boolean" + example: true + NFd: + description: | + The total number of file Descriptors in use by the daemon process. + + This information is only returned if debug-mode is enabled. + type: "integer" + example: 64 + NGoroutines: + description: | + The number of goroutines that currently exist. + + This information is only returned if debug-mode is enabled. + type: "integer" + example: 174 + SystemTime: + description: | + Current system-time in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + format with nano-seconds. + type: "string" + example: "2017-08-08T20:28:29.06202363Z" + LoggingDriver: + description: | + The logging driver to use as a default for new containers. + type: "string" + CgroupDriver: + description: | + The driver to use for managing cgroups. + type: "string" + enum: ["cgroupfs", "systemd", "none"] + default: "cgroupfs" + example: "cgroupfs" + CgroupVersion: + description: | + The version of the cgroup. + type: "string" + enum: ["1", "2"] + default: "1" + example: "1" + NEventsListener: + description: "Number of event listeners subscribed." + type: "integer" + example: 30 + KernelVersion: + description: | + Kernel version of the host. + + On Linux, this information obtained from `uname`. On Windows this + information is queried from the <kbd>HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\</kbd> + registry value, for example _"10.0 14393 (14393.1198.amd64fre.rs1_release_sec.170427-1353)"_. + type: "string" + example: "6.8.0-31-generic" + OperatingSystem: + description: | + Name of the host's operating system, for example: "Ubuntu 24.04 LTS" + or "Windows Server 2016 Datacenter" + type: "string" + example: "Ubuntu 24.04 LTS" + OSVersion: + description: | + Version of the host's operating system + + <p><br /></p> + + > **Note**: The information returned in this field, including its + > very existence, and the formatting of values, should not be considered + > stable, and may change without notice. + type: "string" + example: "24.04" + OSType: + description: | + Generic type of the operating system of the host, as returned by the + Go runtime (`GOOS`). + + Currently returned values are "linux" and "windows". A full list of + possible values can be found in the [Go documentation](https://go.dev/doc/install/source#environment). + type: "string" + example: "linux" + Architecture: + description: | + Hardware architecture of the host, as returned by the operating system. + This is equivalent to the output of `uname -m` on Linux. + + Unlike `Arch` (from `/version`), this reports the machine's native + architecture, which can differ from the Go runtime architecture when + running a binary compiled for a different architecture (for example, + a 32-bit binary running on 64-bit hardware). + type: "string" + example: "x86_64" + NCPU: + description: | + The number of logical CPUs usable by the daemon. + + The number of available CPUs is checked by querying the operating + system when the daemon starts. Changes to operating system CPU + allocation after the daemon is started are not reflected. + type: "integer" + example: 4 + MemTotal: + description: | + Total amount of physical memory available on the host, in bytes. + type: "integer" + format: "int64" + example: 2095882240 + + IndexServerAddress: + description: | + Address / URL of the index server that is used for image search, + and as a default for user authentication for Docker Hub and Docker Cloud. + default: "https://index.docker.io/v1/" + type: "string" + example: "https://index.docker.io/v1/" + RegistryConfig: + $ref: "#/definitions/RegistryServiceConfig" + GenericResources: + $ref: "#/definitions/GenericResources" + HttpProxy: + description: | + HTTP-proxy configured for the daemon. This value is obtained from the + [`HTTP_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable. + Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL + are masked in the API response. + + Containers do not automatically inherit this configuration. + type: "string" + example: "http://xxxxx:xxxxx@proxy.corp.example.com:8080" + HttpsProxy: + description: | + HTTPS-proxy configured for the daemon. This value is obtained from the + [`HTTPS_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable. + Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL + are masked in the API response. + + Containers do not automatically inherit this configuration. + type: "string" + example: "https://xxxxx:xxxxx@proxy.corp.example.com:4443" + NoProxy: + description: | + Comma-separated list of domain extensions for which no proxy should be + used. This value is obtained from the [`NO_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) + environment variable. + + Containers do not automatically inherit this configuration. + type: "string" + example: "*.local, 169.254/16" + Name: + description: "Hostname of the host." + type: "string" + example: "node5.corp.example.com" + Labels: + description: | + User-defined labels (key/value metadata) as set on the daemon. + + <p><br /></p> + + > **Note**: When part of a Swarm, nodes can both have _daemon_ labels, + > set through the daemon configuration, and _node_ labels, set from a + > manager node in the Swarm. Node labels are not included in this + > field. Node labels can be retrieved using the `/nodes/(id)` endpoint + > on a manager node in the Swarm. + type: "array" + items: + type: "string" + example: ["storage=ssd", "production"] + ExperimentalBuild: + description: | + Indicates if experimental features are enabled on the daemon. + type: "boolean" + example: true + ServerVersion: + description: | + Version string of the daemon. + type: "string" + example: "27.0.1" + Runtimes: + description: | + List of [OCI compliant](https://github.com/opencontainers/runtime-spec) + runtimes configured on the daemon. Keys hold the "name" used to + reference the runtime. + + The Docker daemon relies on an OCI compliant runtime (invoked via the + `containerd` daemon) as its interface to the Linux kernel namespaces, + cgroups, and SELinux. + + The default runtime is `runc`, and automatically configured. Additional + runtimes can be configured by the user and will be listed here. + type: "object" + additionalProperties: + $ref: "#/definitions/Runtime" + default: + runc: + path: "runc" + example: + runc: + path: "runc" + runc-master: + path: "/go/bin/runc" + custom: + path: "/usr/local/bin/my-oci-runtime" + runtimeArgs: ["--debug", "--systemd-cgroup=false"] + DefaultRuntime: + description: | + Name of the default OCI runtime that is used when starting containers. + + The default can be overridden per-container at create time. + type: "string" + default: "runc" + example: "runc" + Swarm: + $ref: "#/definitions/SwarmInfo" + LiveRestoreEnabled: + description: | + Indicates if live restore is enabled. + + If enabled, containers are kept running when the daemon is shutdown + or upon daemon start if running containers are detected. + type: "boolean" + default: false + example: false + Isolation: + description: | + Represents the isolation technology to use as a default for containers. + The supported values are platform-specific. + + If no isolation value is specified on daemon start, on Windows client, + the default is `hyperv`, and on Windows server, the default is `process`. + + This option is currently not used on other platforms. + default: "default" + type: "string" + enum: + - "default" + - "hyperv" + - "process" + - "" + InitBinary: + description: | + Name and, optional, path of the `docker-init` binary. + + If the path is omitted, the daemon searches the host's `$PATH` for the + binary and uses the first result. + type: "string" + example: "docker-init" + ContainerdCommit: + $ref: "#/definitions/Commit" + RuncCommit: + $ref: "#/definitions/Commit" + InitCommit: + $ref: "#/definitions/Commit" + SecurityOptions: + description: | + List of security features that are enabled on the daemon, such as + apparmor, seccomp, SELinux, user-namespaces (userns), rootless and + no-new-privileges. + + Additional configuration options for each security feature may + be present, and are included as a comma-separated list of key/value + pairs. + type: "array" + items: + type: "string" + example: + - "name=apparmor" + - "name=seccomp,profile=default" + - "name=selinux" + - "name=userns" + - "name=rootless" + ProductLicense: + description: | + Reports a summary of the product license on the daemon. + + If a commercial license has been applied to the daemon, information + such as number of nodes, and expiration are included. + type: "string" + example: "Community Engine" + DefaultAddressPools: + description: | + List of custom default address pools for local networks, which can be + specified in the daemon.json file or dockerd option. + + Example: a Base "10.10.0.0/16" with Size 24 will define the set of 256 + 10.10.[0-255].0/24 address pools. + type: "array" + items: + type: "object" + properties: + Base: + description: "The network address in CIDR format" + type: "string" + example: "10.10.0.0/16" + Size: + description: "The network pool size" + type: "integer" + example: "24" + FirewallBackend: + $ref: "#/definitions/FirewallInfo" + DiscoveredDevices: + description: | + List of devices discovered by device drivers. + + Each device includes information about its source driver, kind, name, + and additional driver-specific attributes. + type: "array" + items: + $ref: "#/definitions/DeviceInfo" + NRI: + $ref: "#/definitions/NRIInfo" + Warnings: + description: | + List of warnings / informational messages about missing features, or + issues related to the daemon configuration. + + These messages can be printed by the client as information to the user. + type: "array" + items: + type: "string" + example: + - "WARNING: No memory limit support" + CDISpecDirs: + description: | + List of directories where (Container Device Interface) CDI + specifications are located. + + These specifications define vendor-specific modifications to an OCI + runtime specification for a container being created. + + An empty list indicates that CDI device injection is disabled. + + Note that since using CDI device injection requires the daemon to have + experimental enabled. For non-experimental daemons an empty list will + always be returned. + type: "array" + items: + type: "string" + example: + - "/etc/cdi" + - "/var/run/cdi" + Containerd: + $ref: "#/definitions/ContainerdInfo" + + ContainerdInfo: + description: | + Information for connecting to the containerd instance that is used by the daemon. + This is included for debugging purposes only. + type: "object" + x-nullable: true + properties: + Address: + description: "The address of the containerd socket." + type: "string" + example: "/run/containerd/containerd.sock" + Namespaces: + description: | + The namespaces that the daemon uses for running containers and + plugins in containerd. These namespaces can be configured in the + daemon configuration, and are considered to be used exclusively + by the daemon, Tampering with the containerd instance may cause + unexpected behavior. + + As these namespaces are considered to be exclusively accessed + by the daemon, it is not recommended to change these values, + or to change them to a value that is used by other systems, + such as cri-containerd. + type: "object" + properties: + Containers: + description: | + The default containerd namespace used for containers managed + by the daemon. + + The default namespace for containers is "moby", but will be + suffixed with the `<uid>.<gid>` of the remapped `root` if + user-namespaces are enabled and the containerd image-store + is used. + type: "string" + default: "moby" + example: "moby" + Plugins: + description: | + The default containerd namespace used for plugins managed by + the daemon. + + The default namespace for plugins is "plugins.moby", but will be + suffixed with the `<uid>.<gid>` of the remapped `root` if + user-namespaces are enabled and the containerd image-store + is used. + type: "string" + default: "plugins.moby" + example: "plugins.moby" + + FirewallInfo: + description: | + Information about the daemon's firewalling configuration. + + This field is currently only used on Linux, and omitted on other platforms. + type: "object" + x-nullable: true + properties: + Driver: + description: | + The name of the firewall backend driver. + type: "string" + example: "nftables" + Info: + description: | + Information about the firewall backend, provided as + "label" / "value" pairs. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "array" + items: + type: "array" + items: + type: "string" + example: + - ["ReloadedAt", "2025-01-01T00:00:00Z"] + + # PluginsInfo is a temp struct holding Plugins name + # registered with docker daemon. It is used by Info struct + PluginsInfo: + description: | + Available plugins per type. + + <p><br /></p> + + > **Note**: Only unmanaged (V1) plugins are included in this list. + > V1 plugins are "lazily" loaded, and are not returned in this list + > if there is no resource using the plugin. + type: "object" + properties: + Volume: + description: "Names of available volume-drivers, and network-driver plugins." + type: "array" + items: + type: "string" + example: ["local"] + Network: + description: "Names of available network-drivers, and network-driver plugins." + type: "array" + items: + type: "string" + example: ["bridge", "host", "ipvlan", "macvlan", "null", "overlay"] + Authorization: + description: "Names of available authorization plugins." + type: "array" + items: + type: "string" + example: ["img-authz-plugin", "hbm"] + Log: + description: "Names of available logging-drivers, and logging-driver plugins." + type: "array" + items: + type: "string" + example: ["awslogs", "fluentd", "gcplogs", "gelf", "journald", "json-file", "splunk", "syslog"] + + + RegistryServiceConfig: + description: | + RegistryServiceConfig stores daemon registry services configuration. + type: "object" + x-nullable: true + properties: + InsecureRegistryCIDRs: + description: | + List of IP ranges of insecure registries, using the CIDR syntax + ([RFC 4632](https://tools.ietf.org/html/4632)). Insecure registries + accept un-encrypted (HTTP) and/or untrusted (HTTPS with certificates + from unknown CAs) communication. + + By default, local registries (`::1/128` and `127.0.0.0/8`) are configured as + insecure. All other registries are secure. Communicating with an + insecure registry is not possible if the daemon assumes that registry + is secure. + + This configuration override this behavior, insecure communication with + registries whose resolved IP address is within the subnet described by + the CIDR syntax. + + Registries can also be marked insecure by hostname. Those registries + are listed under `IndexConfigs` and have their `Secure` field set to + `false`. + + > **Warning**: Using this option can be useful when running a local + > registry, but introduces security vulnerabilities. This option + > should therefore ONLY be used for testing purposes. For increased + > security, users should add their CA to their system's list of trusted + > CAs instead of enabling this option. + type: "array" + items: + type: "string" + example: ["::1/128", "127.0.0.0/8"] + IndexConfigs: + type: "object" + additionalProperties: + $ref: "#/definitions/IndexInfo" + example: + "127.0.0.1:5000": + "Name": "127.0.0.1:5000" + "Mirrors": [] + "Secure": false + "Official": false + "[2001:db8:a0b:12f0::1]:80": + "Name": "[2001:db8:a0b:12f0::1]:80" + "Mirrors": [] + "Secure": false + "Official": false + "docker.io": + Name: "docker.io" + Mirrors: ["https://hub-mirror.corp.example.com:5000/"] + Secure: true + Official: true + "registry.internal.corp.example.com:3000": + Name: "registry.internal.corp.example.com:3000" + Mirrors: [] + Secure: false + Official: false + Mirrors: + description: | + List of registry URLs that act as a mirror for the official + (`docker.io`) registry. + + type: "array" + items: + type: "string" + example: + - "https://hub-mirror.corp.example.com:5000/" + - "https://[2001:db8:a0b:12f0::1]/" + + IndexInfo: + description: + IndexInfo contains information about a registry. + type: "object" + x-nullable: true + properties: + Name: + description: | + Name of the registry, such as "docker.io". + type: "string" + example: "docker.io" + Mirrors: + description: | + List of mirrors, expressed as URIs. + type: "array" + items: + type: "string" + example: + - "https://hub-mirror.corp.example.com:5000/" + - "https://registry-2.docker.io/" + - "https://registry-3.docker.io/" + Secure: + description: | + Indicates if the registry is part of the list of insecure + registries. + + If `false`, the registry is insecure. Insecure registries accept + un-encrypted (HTTP) and/or untrusted (HTTPS with certificates from + unknown CAs) communication. + + > **Warning**: Insecure registries can be useful when running a local + > registry. However, because its use creates security vulnerabilities + > it should ONLY be enabled for testing purposes. For increased + > security, users should add their CA to their system's list of + > trusted CAs instead of enabling this option. + type: "boolean" + example: true + Official: + description: | + Indicates whether this is an official registry (i.e., Docker Hub / docker.io) + type: "boolean" + example: true + + Runtime: + description: | + Runtime describes an [OCI compliant](https://github.com/opencontainers/runtime-spec) + runtime. + + The runtime is invoked by the daemon via the `containerd` daemon. OCI + runtimes act as an interface to the Linux kernel namespaces, cgroups, + and SELinux. + type: "object" + properties: + path: + description: | + Name and, optional, path, of the OCI executable binary. + + If the path is omitted, the daemon searches the host's `$PATH` for the + binary and uses the first result. + type: "string" + example: "/usr/local/bin/my-oci-runtime" + runtimeArgs: + description: | + List of command-line arguments to pass to the runtime when invoked. + type: "array" + x-nullable: true + items: + type: "string" + example: ["--debug", "--systemd-cgroup=false"] + status: + description: | + Information specific to the runtime. + + While this API specification does not define data provided by runtimes, + the following well-known properties may be provided by runtimes: + + `org.opencontainers.runtime-spec.features`: features structure as defined + in the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec/blob/main/features.md), + in a JSON string representation. + + <p><br /></p> + + > **Note**: The information returned in this field, including the + > formatting of values and labels, should not be considered stable, + > and may change without notice. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + "org.opencontainers.runtime-spec.features": "{\"ociVersionMin\":\"1.0.0\",\"ociVersionMax\":\"1.1.0\",\"...\":\"...\"}" + + Commit: + description: | + Commit holds the Git-commit (SHA1) that a binary was built from, as + reported in the version-string of external tools, such as `containerd`, + or `runC`. + type: "object" + properties: + ID: + description: "Actual commit ID of external tool." + type: "string" + example: "cfb82a876ecc11b5ca0977d1733adbe58599088a" + + SwarmInfo: + description: | + Represents generic information about swarm. + type: "object" + properties: + NodeID: + description: "Unique identifier of for this node in the swarm." + type: "string" + default: "" + example: "k67qz4598weg5unwwffg6z1m1" + NodeAddr: + description: | + IP address at which this node can be reached by other nodes in the + swarm. + type: "string" + default: "" + example: "10.0.0.46" + LocalNodeState: + $ref: "#/definitions/LocalNodeState" + ControlAvailable: + type: "boolean" + default: false + example: true + Error: + type: "string" + default: "" + RemoteManagers: + description: | + List of ID's and addresses of other managers in the swarm. + type: "array" + x-nullable: true + items: + $ref: "#/definitions/PeerNode" + example: + - NodeID: "71izy0goik036k48jg985xnds" + Addr: "10.0.0.158:2377" + - NodeID: "79y6h1o4gv8n120drcprv5nmc" + Addr: "10.0.0.159:2377" + - NodeID: "k67qz4598weg5unwwffg6z1m1" + Addr: "10.0.0.46:2377" + Nodes: + description: "Total number of nodes in the swarm." + type: "integer" + x-nullable: true + example: 4 + Managers: + description: "Total number of managers in the swarm." + type: "integer" + x-nullable: true + example: 3 + Cluster: + $ref: "#/definitions/ClusterInfo" + + LocalNodeState: + description: "Current local status of this node." + type: "string" + default: "" + enum: + - "" + - "inactive" + - "pending" + - "active" + - "error" + - "locked" + example: "active" + + PeerNode: + description: "Represents a peer-node in the swarm" + type: "object" + properties: + NodeID: + description: "Unique identifier of for this node in the swarm." + type: "string" + Addr: + description: | + IP address and ports at which this node can be reached. + type: "string" + + NetworkAttachmentConfig: + description: | + Specifies how a service should be attached to a particular network. + type: "object" + properties: + Target: + description: | + The target network for attachment. Must be a network name or ID. + type: "string" + Aliases: + description: | + Discoverable alternate names for the service on this network. + type: "array" + items: + type: "string" + DriverOpts: + description: | + Driver attachment options for the network target. + type: "object" + additionalProperties: + type: "string" + + EventActor: + description: | + Actor describes something that generates events, like a container, network, + or a volume. + type: "object" + properties: + ID: + description: "The ID of the object emitting the event" + type: "string" + example: "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743" + Attributes: + description: | + Various key/value attributes of the object, depending on its type. + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-label-value" + image: "alpine:latest" + name: "my-container" + + EventMessage: + description: | + EventMessage represents the information an event contains. + type: "object" + title: "SystemEventsResponse" + properties: + Type: + description: "The type of object emitting the event" + type: "string" + enum: ["builder", "config", "container", "daemon", "image", "network", "node", "plugin", "secret", "service", "volume"] + example: "container" + Action: + description: "The type of event" + type: "string" + example: "create" + Actor: + $ref: "#/definitions/EventActor" + scope: + description: | + Scope of the event. Engine events are `local` scope. Cluster (Swarm) + events are `swarm` scope. + type: "string" + enum: ["local", "swarm"] + time: + description: "Timestamp of event" + type: "integer" + format: "int64" + example: 1629574695 + timeNano: + description: "Timestamp of event, with nanosecond accuracy" + type: "integer" + format: "int64" + example: 1629574695515050031 + + OCIDescriptor: + type: "object" + x-go-name: Descriptor + description: | + A descriptor struct containing digest, media type, and size, as defined in + the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md). + properties: + mediaType: + description: | + The media type of the object this schema refers to. + type: "string" + example: "application/vnd.oci.image.manifest.v1+json" + digest: + description: | + The digest of the targeted content. + type: "string" + example: "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96" + size: + description: | + The size in bytes of the blob. + type: "integer" + format: "int64" + example: 424 + urls: + description: |- + List of URLs from which this object MAY be downloaded. + type: "array" + items: + type: "string" + format: "uri" + x-nullable: true + annotations: + description: |- + Arbitrary metadata relating to the targeted content. + type: "object" + x-nullable: true + additionalProperties: + type: "string" + example: + "com.docker.official-images.bashbrew.arch": "amd64" + "org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8" + "org.opencontainers.image.base.name": "scratch" + "org.opencontainers.image.created": "2025-01-27T00:00:00Z" + "org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79" + "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base" + "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu" + "org.opencontainers.image.version": "24.04" + data: + type: string + x-nullable: true + description: |- + Data is an embedding of the targeted content. This is encoded as a base64 + string when marshalled to JSON (automatically, by encoding/json). If + present, Data can be used directly to avoid fetching the targeted content. + example: null + platform: + $ref: "#/definitions/OCIPlatform" + artifactType: + description: |- + ArtifactType is the IANA media type of this artifact. + type: "string" + x-nullable: true + example: null + + OCIPlatform: + type: "object" + x-go-name: Platform + x-nullable: true + description: | + Describes the platform which the image in the manifest runs on, as defined + in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). + properties: + architecture: + description: | + The CPU architecture, for example `amd64` or `ppc64`. + type: "string" + example: "arm" + os: + description: | + The operating system, for example `linux` or `windows`. + type: "string" + example: "windows" + os.version: + description: | + Optional field specifying the operating system version, for example on + Windows `10.0.19041.1165`. + type: "string" + example: "10.0.19041.1165" + os.features: + description: | + Optional field specifying an array of strings, each listing a required + OS feature (for example on Windows `win32k`). + type: "array" + items: + type: "string" + example: + - "win32k" + variant: + description: | + Optional field specifying a variant of the CPU, for example `v7` to + specify ARMv7 when architecture is `arm`. + type: "string" + example: "v7" + + DistributionInspect: + type: "object" + x-go-name: DistributionInspect + title: "DistributionInspectResponse" + required: [Descriptor, Platforms] + description: | + Describes the result obtained from contacting the registry to retrieve + image metadata. + properties: + Descriptor: + $ref: "#/definitions/OCIDescriptor" + Platforms: + type: "array" + description: | + An array containing all platforms supported by the image. + items: + $ref: "#/definitions/OCIPlatform" + + ClusterVolume: + type: "object" + description: | + Options and information specific to, and only present on, Swarm CSI + cluster volumes. + properties: + ID: + type: "string" + description: | + The Swarm ID of this volume. Because cluster volumes are Swarm + objects, they have an ID, unlike non-cluster volumes. This ID can + be used to refer to the Volume instead of the name. + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ClusterVolumeSpec" + Info: + type: "object" + description: | + Information about the global status of the volume. + properties: + CapacityBytes: + type: "integer" + format: "int64" + description: | + The capacity of the volume in bytes. A value of 0 indicates that + the capacity is unknown. + VolumeContext: + type: "object" + description: | + A map of strings to strings returned from the storage plugin when + the volume is created. + additionalProperties: + type: "string" + VolumeID: + type: "string" + description: | + The ID of the volume as returned by the CSI storage plugin. This + is distinct from the volume's ID as provided by Docker. This ID + is never used by the user when communicating with Docker to refer + to this volume. If the ID is blank, then the Volume has not been + successfully created in the plugin yet. + AccessibleTopology: + type: "array" + description: | + The topology this volume is actually accessible from. + items: + $ref: "#/definitions/Topology" + PublishStatus: + type: "array" + description: | + The status of the volume as it pertains to its publishing and use on + specific nodes + items: + type: "object" + properties: + NodeID: + type: "string" + description: | + The ID of the Swarm node the volume is published on. + State: + type: "string" + description: | + The published state of the volume. + * `pending-publish` The volume should be published to this node, but the call to the controller plugin to do so has not yet been successfully completed. + * `published` The volume is published successfully to the node. + * `pending-node-unpublish` The volume should be unpublished from the node, and the manager is awaiting confirmation from the worker that it has done so. + * `pending-controller-unpublish` The volume is successfully unpublished from the node, but has not yet been successfully unpublished on the controller. + enum: + - "pending-publish" + - "published" + - "pending-node-unpublish" + - "pending-controller-unpublish" + PublishContext: + type: "object" + description: | + A map of strings to strings returned by the CSI controller + plugin when a volume is published. + additionalProperties: + type: "string" + + ClusterVolumeSpec: + type: "object" + description: | + Cluster-specific options used to create the volume. + properties: + Group: + type: "string" + description: | + Group defines the volume group of this volume. Volumes belonging to + the same group can be referred to by group name when creating + Services. Referring to a volume by group instructs Swarm to treat + volumes in that group interchangeably for the purpose of scheduling. + Volumes with an empty string for a group technically all belong to + the same, emptystring group. + AccessMode: + type: "object" + description: | + Defines how the volume is used by tasks. + properties: + Scope: + type: "string" + description: | + The set of nodes this volume can be used on at one time. + - `single` The volume may only be scheduled to one node at a time. + - `multi` the volume may be scheduled to any supported number of nodes at a time. + default: "single" + enum: ["single", "multi"] + x-nullable: false + Sharing: + type: "string" + description: | + The number and way that different tasks can use this volume + at one time. + - `none` The volume may only be used by one task at a time. + - `readonly` The volume may be used by any number of tasks, but they all must mount the volume as readonly + - `onewriter` The volume may be used by any number of tasks, but only one may mount it as read/write. + - `all` The volume may have any number of readers and writers. + default: "none" + enum: ["none", "readonly", "onewriter", "all"] + x-nullable: false + MountVolume: + type: "object" + description: | + Options for using this volume as a Mount-type volume. + + Either MountVolume or BlockVolume, but not both, must be + present. + properties: + FsType: + type: "string" + description: | + Specifies the filesystem type for the mount volume. + Optional. + MountFlags: + type: "array" + description: | + Flags to pass when mounting the volume. Optional. + items: + type: "string" + BlockVolume: + type: "object" + description: | + Options for using this volume as a Block-type volume. + Intentionally empty. + Secrets: + type: "array" + description: | + Swarm Secrets that are passed to the CSI storage plugin when + operating on this volume. + items: + type: "object" + description: | + One cluster volume secret entry. Defines a key-value pair that + is passed to the plugin. + properties: + Key: + type: "string" + description: | + Key is the name of the key of the key-value pair passed to + the plugin. + Secret: + type: "string" + description: | + Secret is the swarm Secret object from which to read data. + This can be a Secret name or ID. The Secret data is + retrieved by swarm and used as the value of the key-value + pair passed to the plugin. + AccessibilityRequirements: + type: "object" + description: | + Requirements for the accessible topology of the volume. These + fields are optional. For an in-depth description of what these + fields mean, see the CSI specification. + properties: + Requisite: + type: "array" + description: | + A list of required topologies, at least one of which the + volume must be accessible from. + items: + $ref: "#/definitions/Topology" + Preferred: + type: "array" + description: | + A list of topologies that the volume should attempt to be + provisioned in. + items: + $ref: "#/definitions/Topology" + CapacityRange: + type: "object" + description: | + The desired capacity that the volume should be created with. If + empty, the plugin will decide the capacity. + properties: + RequiredBytes: + type: "integer" + format: "int64" + description: | + The volume must be at least this big. The value of 0 + indicates an unspecified minimum + LimitBytes: + type: "integer" + format: "int64" + description: | + The volume must not be bigger than this. The value of 0 + indicates an unspecified maximum. + Availability: + type: "string" + description: | + The availability of the volume for use in tasks. + - `active` The volume is fully available for scheduling on the cluster + - `pause` No new workloads should use the volume, but existing workloads are not stopped. + - `drain` All workloads using this volume should be stopped and rescheduled, and no new ones should be started. + default: "active" + x-nullable: false + enum: + - "active" + - "pause" + - "drain" + + Topology: + description: | + A map of topological domains to topological segments. For in depth + details, see documentation for the Topology object in the CSI + specification. + type: "object" + properties: + Segments: + type: "object" + additionalProperties: + type: "string" + + AttestationStatement: + x-go-name: "AttestationStatement" + description: | + AttestationStatement is a single in-toto statement attached to an image. + type: "object" + required: ["Descriptor", "PredicateType"] + properties: + Descriptor: + $ref: "#/definitions/OCIDescriptor" + PredicateType: + description: The in-toto predicate type URI of this statement. + type: "string" + example: "https://slsa.dev/provenance/v0.2" + Statement: + description: | + The verbatim in-toto statement JSON. Only included when the caller + opts in via the `statement=true` query parameter; otherwise absent. + type: "object" + x-nullable: true + ImageManifestSummary: + x-go-name: "ManifestSummary" + description: | + ImageManifestSummary represents a summary of an image manifest. + type: "object" + required: ["ID", "Descriptor", "Available", "Size", "Kind"] + properties: + ID: + description: | + ID is the content-addressable ID of an image and is the same as the + digest of the image manifest. + type: "string" + example: "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f" + Descriptor: + $ref: "#/definitions/OCIDescriptor" + Available: + description: Indicates whether all the child content (image config, layers) is fully available locally. + type: "boolean" + example: true + Size: + type: "object" + x-nullable: false + required: ["Content", "Total"] + properties: + Total: + type: "integer" + format: "int64" + example: 8213251 + description: | + Total is the total size (in bytes) of all the locally present + data (both distributable and non-distributable) that's related to + this manifest and its children. + This equal to the sum of [Content] size AND all the sizes in the + [Size] struct present in the Kind-specific data struct. + For example, for an image kind (Kind == "image") + this would include the size of the image content and unpacked + image snapshots ([Size.Content] + [ImageData.Size.Unpacked]). + Content: + description: | + Content is the size (in bytes) of all the locally present + content in the content store (e.g. image config, layers) + referenced by this manifest and its children. + This only includes blobs in the content store. + type: "integer" + format: "int64" + example: 3987495 + Kind: + type: "string" + example: "image" + enum: + - "image" + - "attestation" + - "unknown" + description: | + The kind of the manifest. + + kind | description + -------------|----------------------------------------------------------- + image | Image manifest that can be used to start a container. + attestation | Attestation manifest produced by the Buildkit builder for a specific image manifest. + ImageData: + description: | + The image data for the image manifest. + This field is only populated when Kind is "image". + type: "object" + x-nullable: true + x-omitempty: true + required: ["Platform", "Containers", "Size"] + properties: + Platform: + $ref: "#/definitions/OCIPlatform" + description: | + OCI platform of the image. This will be the platform specified in the + manifest descriptor from the index/manifest list. + If it's not available, it will be obtained from the image config. + Identity: + description: | + Identity holds information about the identity and origin of this image. + For image list responses, this can duplicate Build/Pull fields across + image manifests, because those parts are image-level metadata. + x-nullable: true + $ref: "#/definitions/Identity" + Containers: + description: | + The IDs of the containers that are using this image. + type: "array" + items: + type: "string" + example: ["ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430", "abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"] + Size: + type: "object" + x-nullable: false + required: ["Unpacked"] + properties: + Unpacked: + type: "integer" + format: "int64" + example: 3987495 + description: | + Unpacked is the size (in bytes) of the locally unpacked + (uncompressed) image content that's directly usable by the containers + running this image. + It's independent of the distributable content - e.g. + the image might still have an unpacked data that's still used by + some container even when the distributable/compressed content is + already gone. + AttestationData: + description: | + The image data for the attestation manifest. + This field is only populated when Kind is "attestation". + type: "object" + x-nullable: true + x-omitempty: true + required: ["For"] + properties: + For: + description: | + The digest of the image manifest that this attestation is for. + type: "string" + example: "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f" + +paths: + /containers/json: + get: + summary: "List containers" + description: | + Returns a list of containers. For details on the format, see the + [inspect endpoint](#operation/ContainerInspect). + + Note that it uses a different, smaller representation of a container + than inspecting a single container. For example, the list of linked + containers is not propagated . + operationId: "ContainerList" + produces: + - "application/json" + parameters: + - name: "all" + in: "query" + description: | + Return all containers. By default, only running containers are shown. + type: "boolean" + default: false + - name: "limit" + in: "query" + description: | + Return this number of most recently created containers, including + non-running ones. + type: "integer" + - name: "size" + in: "query" + description: | + Return the size of container as fields `SizeRw` and `SizeRootFs`. + type: "boolean" + default: false + - name: "filters" + in: "query" + description: | + Filters to process on the container list, encoded as JSON (a + `map[string][]string`). For example, `{"status": ["paused"]}` will + only return paused containers. + + Available filters: + + - `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`) + - `annotation=key` or `annotation="key=value"` of a container annotation + - `before`=(`<container id>` or `<container name>`) + - `expose`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) + - `exited=<int>` containers with exit code of `<int>` + - `health`=(`starting`|`healthy`|`unhealthy`|`none`) + - `id=<ID>` a container's ID + - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only) + - `is-task=`(`true`|`false`) + - `label=key` or `label="key=value"` of a container label + - `name=<name>` a container's name + - `network`=(`<network id>` or `<network name>`) + - `publish`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) + - `since`=(`<container id>` or `<container name>`) + - `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`) + - `volume`=(`<volume name>` or `<mount point destination>`) + type: "string" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/ContainerSummary" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /containers/create: + post: + summary: "Create a container" + operationId: "ContainerCreate" + consumes: + - "application/json" + - "application/octet-stream" + produces: + - "application/json" + parameters: + - name: "name" + in: "query" + description: | + Assign the specified name to the container. Must match + `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`. + type: "string" + pattern: "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$" + - name: "platform" + in: "query" + description: | + Platform in the format `os[/arch[/variant]]` used for image lookup. + + When specified, the daemon checks if the requested image is present + in the local image cache with the given OS and Architecture, and + otherwise returns a `404` status. + + If the option is not set, the host's native OS and Architecture are + used to look up the image in the image cache. However, if no platform + is passed and the given image does exist in the local image cache, + but its OS or architecture does not match, the container is created + with the available image, and a warning is added to the `Warnings` + field in the response, for example; + + WARNING: The requested image's platform (linux/arm64/v8) does not + match the detected host platform (linux/amd64) and no + specific platform was requested + + type: "string" + default: "" + - name: "body" + in: "body" + description: "Container to create" + schema: + allOf: + - $ref: "#/definitions/ContainerConfig" + - type: "object" + properties: + HostConfig: + $ref: "#/definitions/HostConfig" + NetworkingConfig: + $ref: "#/definitions/NetworkingConfig" + example: + Hostname: "" + Domainname: "" + User: "" + AttachStdin: false + AttachStdout: true + AttachStderr: true + Tty: false + OpenStdin: false + StdinOnce: false + Env: + - "FOO=bar" + - "BAZ=quux" + Cmd: + - "date" + Entrypoint: "" + Image: "ubuntu" + Labels: + com.example.vendor: "Acme" + com.example.license: "GPL" + com.example.version: "1.0" + Volumes: + /volumes/data: {} + WorkingDir: "" + NetworkDisabled: false + ExposedPorts: + 22/tcp: {} + StopSignal: "SIGTERM" + StopTimeout: 10 + HostConfig: + Binds: + - "/tmp:/tmp" + Links: + - "redis3:redis" + Memory: 0 + MemorySwap: 0 + MemoryReservation: 0 + NanoCpus: 500000 + CpuPercent: 80 + CpuShares: 512 + CpuPeriod: 100000 + CpuRealtimePeriod: 1000000 + CpuRealtimeRuntime: 10000 + CpuQuota: 50000 + CpusetCpus: "0,1" + CpusetMems: "0,1" + MaximumIOps: 0 + MaximumIOBps: 0 + BlkioWeight: 300 + BlkioWeightDevice: + - {} + BlkioDeviceReadBps: + - {} + BlkioDeviceReadIOps: + - {} + BlkioDeviceWriteBps: + - {} + BlkioDeviceWriteIOps: + - {} + DeviceRequests: + - Driver: "nvidia" + Count: -1 + DeviceIDs": ["0", "1", "GPU-fef8089b-4820-abfc-e83e-94318197576e"] + Capabilities: [["gpu", "nvidia", "compute"]] + Options: + property1: "string" + property2: "string" + MemorySwappiness: 60 + OomKillDisable: false + OomScoreAdj: 500 + PidMode: "" + PidsLimit: 0 + PortBindings: + 22/tcp: + - HostPort: "11022" + PublishAllPorts: false + Privileged: false + ReadonlyRootfs: false + Dns: + - "8.8.8.8" + DnsOptions: + - "" + DnsSearch: + - "" + VolumesFrom: + - "parent" + - "other:ro" + CapAdd: + - "NET_ADMIN" + CapDrop: + - "MKNOD" + GroupAdd: + - "newgroup" + RestartPolicy: + Name: "" + MaximumRetryCount: 0 + AutoRemove: true + NetworkMode: "bridge" + Devices: [] + Ulimits: + - {} + LogConfig: + Type: "json-file" + Config: {} + SecurityOpt: [] + StorageOpt: {} + CgroupParent: "" + VolumeDriver: "" + ShmSize: 67108864 + NetworkingConfig: + EndpointsConfig: + isolated_nw: + IPAMConfig: + IPv4Address: "172.20.30.33" + IPv6Address: "2001:db8:abcd::3033" + LinkLocalIPs: + - "169.254.34.68" + - "fe80::3468" + Links: + - "container_1" + - "container_2" + Aliases: + - "server_x" + - "server_y" + database_nw: {} + + required: true + responses: + "201": + description: "Container created successfully" + schema: + $ref: "#/definitions/ContainerCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such image" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: c2ada9df5af8" + "409": + description: "conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /containers/{id}/json: + get: + summary: "Inspect a container" + description: "Return low-level information about a container." + operationId: "ContainerInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerInspectResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "size" + in: "query" + type: "boolean" + default: false + description: "Return the size of container as fields `SizeRw` and `SizeRootFs`" + tags: ["Container"] + /containers/{id}/top: + get: + summary: "List processes running inside a container" + description: | + On Unix systems, this is done by running the `ps` command. This endpoint + is not supported on Windows. + operationId: "ContainerTop" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerTopResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "ps_args" + in: "query" + description: "The arguments to pass to `ps`. For example, `aux`" + type: "string" + default: "-ef" + tags: ["Container"] + /containers/{id}/logs: + get: + summary: "Get container logs" + description: | + Get `stdout` and `stderr` logs from a container. + + Note: This endpoint works only for containers with the `json-file` or + `journald` logging driver. + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + operationId: "ContainerLogs" + responses: + "200": + description: | + logs returned as a stream in response body. + For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach). + Note that unlike the attach endpoint, the logs endpoint does not + upgrade the connection and does not set Content-Type. + schema: + type: "string" + format: "binary" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "until" + in: "query" + description: "Only return logs before this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Container"] + /containers/{id}/changes: + get: + summary: "Get changes on a container’s filesystem" + description: | + Returns which files in a container's filesystem have been added, deleted, + or modified. The `Kind` of modification can be one of: + + - `0`: Modified ("C") + - `1`: Added ("A") + - `2`: Deleted ("D") + operationId: "ContainerChanges" + produces: ["application/json"] + responses: + "200": + description: "The list of changes" + schema: + type: "array" + items: + $ref: "#/definitions/FilesystemChange" + examples: + application/json: + - Path: "/dev" + Kind: 0 + - Path: "/dev/kmsg" + Kind: 1 + - Path: "/test" + Kind: 1 + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + tags: ["Container"] + /containers/{id}/export: + get: + summary: "Export a container" + description: "Export the contents of a container as a tarball." + operationId: "ContainerExport" + produces: + - "application/octet-stream" + responses: + "200": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + tags: ["Container"] + /containers/{id}/stats: + get: + summary: "Get container stats based on resource usage" + description: | + This endpoint returns a live stream of a container’s resource usage + statistics. + + The `precpu_stats` is the CPU statistic of the *previous* read, and is + used to calculate the CPU usage percentage. It is not an exact copy + of the `cpu_stats` field. + + If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is + nil then for compatibility with older daemons the length of the + corresponding `cpu_usage.percpu_usage` array should be used. + + On a cgroup v2 host, the following fields are not set + * `blkio_stats`: all fields other than `io_service_bytes_recursive` + * `cpu_stats`: `cpu_usage.percpu_usage` + * `memory_stats`: `max_usage` and `failcnt` + Also, `memory_stats.stats` fields are incompatible with cgroup v1. + + To calculate the values shown by the `stats` command of the docker cli tool + the following formulas can be used: + * used_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1) + * used_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2) + * available_memory = `memory_stats.limit` + * Memory usage % = `(used_memory / available_memory) * 100.0` + * cpu_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage` + * system_cpu_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage` + * number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus` + * CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0` + operationId: "ContainerStats" + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ContainerStatsResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "stream" + in: "query" + description: | + Stream the output. If false, the stats will be output once and then + it will disconnect. + type: "boolean" + default: true + - name: "one-shot" + in: "query" + description: | + Only get a single stat instead of waiting for 2 cycles. Must be used + with `stream=false`. + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/resize: + post: + summary: "Resize a container TTY" + description: "Resize the TTY for a container." + operationId: "ContainerResize" + consumes: + - "application/octet-stream" + produces: + - "application/json" + responses: + "200": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "cannot resize container" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "h" + in: "query" + required: true + description: "Height of the TTY session in characters" + type: "integer" + - name: "w" + in: "query" + required: true + description: "Width of the TTY session in characters" + type: "integer" + tags: ["Container"] + /containers/{id}/start: + post: + summary: "Start a container" + operationId: "ContainerStart" + responses: + "204": + description: "no error" + "304": + description: "container already started" + "400": + description: "bad parameter, including an invalid checkpoint ID" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container. Format is a + single character `[a-Z]` or `ctrl-<value>` where `<value>` is one + of: `a-z`, `@`, `^`, `[`, `,` or `_`. + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/stop: + post: + summary: "Stop a container" + operationId: "ContainerStop" + responses: + "204": + description: "no error" + "304": + description: "container already stopped" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + - name: "t" + in: "query" + description: "Number of seconds to wait before killing the container" + type: "integer" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/restart: + post: + summary: "Restart a container" + operationId: "ContainerRestart" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + - name: "t" + in: "query" + description: "Number of seconds to wait before killing the container" + type: "integer" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/kill: + post: + summary: "Kill a container" + description: | + Send a POSIX signal to a container, defaulting to killing to the + container. + operationId: "ContainerKill" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "container is not running" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "signal" + in: "query" + description: | + Signal to send to the container as an integer or string (e.g. `SIGINT`). + type: "string" + default: "SIGKILL" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/update: + post: + summary: "Update a container" + description: | + Change various configuration options of a container without having to + recreate it. + operationId: "ContainerUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "The container has been updated." + schema: + $ref: "#/definitions/ContainerUpdateResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "update" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/Resources" + - type: "object" + properties: + RestartPolicy: + $ref: "#/definitions/RestartPolicy" + example: + BlkioWeight: 300 + CpuShares: 512 + CpuPeriod: 100000 + CpuQuota: 50000 + CpuRealtimePeriod: 1000000 + CpuRealtimeRuntime: 10000 + CpusetCpus: "0,1" + CpusetMems: "0" + Memory: 314572800 + MemorySwap: 514288000 + MemoryReservation: 209715200 + RestartPolicy: + MaximumRetryCount: 4 + Name: "on-failure" + tags: ["Container"] + /containers/{id}/rename: + post: + summary: "Rename a container" + operationId: "ContainerRename" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "name already in use" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "name" + in: "query" + required: true + description: "New name for the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/pause: + post: + summary: "Pause a container" + description: | + Use the freezer cgroup to suspend all processes in a container. + + Traditionally, when suspending a process the `SIGSTOP` signal is used, + which is observable by the process being suspended. With the freezer + cgroup the process is unaware, and unable to capture, that it is being + suspended, and subsequently resumed. + operationId: "ContainerPause" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/unpause: + post: + summary: "Unpause a container" + description: "Resume a container which has been paused." + operationId: "ContainerUnpause" + responses: + "204": + description: "no error" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/attach: + post: + summary: "Attach to a container" + description: | + Attach to a container to read its output or send it input. You can attach + to the same container multiple times and you can reattach to containers + that have been detached. + + Either the `stream` or `logs` parameter must be `true` for this endpoint + to do anything. + + See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) + for more details. + + ### Hijacking + + This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, + and `stderr` on the same socket. + + This is the response from the daemon for an attach request: + + ``` + HTTP/1.1 200 OK + Content-Type: application/vnd.docker.raw-stream + + [STREAM] + ``` + + After the headers and two new lines, the TCP connection can now be used + for raw, bidirectional communication between the client and server. + + To hint potential proxies about connection hijacking, the Docker client + can also optionally send connection upgrade headers. + + For example, the client sends this request to upgrade the connection: + + ``` + POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1 + Upgrade: tcp + Connection: Upgrade + ``` + + The Docker daemon will respond with a `101 UPGRADED` response, and will + similarly follow with the raw stream: + + ``` + HTTP/1.1 101 UPGRADED + Content-Type: application/vnd.docker.raw-stream + Connection: Upgrade + Upgrade: tcp + + [STREAM] + ``` + + ### Stream format + + When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), + the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream + and the stream over the hijacked connected is multiplexed to separate out + `stdout` and `stderr`. The stream consists of a series of frames, each + containing a header and a payload. + + The header contains the information which the stream writes (`stdout` or + `stderr`). It also contains the size of the associated frame encoded in + the last four bytes (`uint32`). + + It is encoded on the first eight bytes like this: + + ```go + header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} + ``` + + `STREAM_TYPE` can be: + + - 0: `stdin` (is written on `stdout`) + - 1: `stdout` + - 2: `stderr` + + `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size + encoded as big endian. + + Following the header is the payload, which is the specified number of + bytes of `STREAM_TYPE`. + + The simplest way to implement this protocol is the following: + + 1. Read 8 bytes. + 2. Choose `stdout` or `stderr` depending on the first byte. + 3. Extract the frame size from the last four bytes. + 4. Read the extracted size and output it on the correct output. + 5. Goto 1. + + ### Stream format when using a TTY + + When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), + the stream is not multiplexed. The data exchanged over the hijacked + connection is simply the raw data from the process PTY and client's + `stdin`. + + operationId: "ContainerAttach" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "101": + description: "no error, hints proxy about hijacking" + "200": + description: "no error, no upgrade header found" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container.Format is a single + character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, + `@`, `^`, `[`, `,` or `_`. + type: "string" + - name: "logs" + in: "query" + description: | + Replay previous logs from the container. + + This is useful for attaching to a container that has started and you + want to output everything since the container started. + + If `stream` is also enabled, once all the previous output has been + returned, it will seamlessly transition into streaming current + output. + type: "boolean" + default: false + - name: "stream" + in: "query" + description: | + Stream attached streams from the time the request was made onwards. + type: "boolean" + default: false + - name: "stdin" + in: "query" + description: "Attach to `stdin`" + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Attach to `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Attach to `stderr`" + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/attach/ws: + get: + summary: "Attach to a container via a websocket" + operationId: "ContainerAttachWebsocket" + responses: + "101": + description: "no error, hints proxy about hijacking" + "200": + description: "no error, no upgrade header found" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "detachKeys" + in: "query" + description: | + Override the key sequence for detaching a container.Format is a single + character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, + `@`, `^`, `[`, `,`, or `_`. + type: "string" + - name: "logs" + in: "query" + description: "Return logs" + type: "boolean" + default: false + - name: "stream" + in: "query" + description: "Return stream" + type: "boolean" + default: false + - name: "stdin" + in: "query" + description: "Attach to `stdin`" + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Attach to `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Attach to `stderr`" + type: "boolean" + default: false + tags: ["Container"] + /containers/{id}/wait: + post: + summary: "Wait for a container" + description: "Block until a container stops, then returns the exit code." + operationId: "ContainerWait" + produces: ["application/json"] + responses: + "200": + description: "The container has exit." + schema: + $ref: "#/definitions/ContainerWaitResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "condition" + in: "query" + description: | + Wait until a container state reaches the given condition. + + Defaults to `not-running` if omitted or empty. + type: "string" + enum: + - "not-running" + - "next-exit" + - "removed" + default: "not-running" + tags: ["Container"] + /containers/{id}: + delete: + summary: "Remove a container" + operationId: "ContainerDelete" + responses: + "204": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "conflict" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: | + You cannot remove a running container: c2ada9df5af8. Stop the + container before attempting removal or force remove + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "v" + in: "query" + description: "Remove anonymous volumes associated with the container." + type: "boolean" + default: false + - name: "force" + in: "query" + description: "If the container is running, kill it before removing it." + type: "boolean" + default: false + - name: "link" + in: "query" + description: "Remove the specified link associated with the container." + type: "boolean" + default: false + produces: + - "application/json" + tags: ["Container"] + /containers/{id}/archive: + head: + summary: "Get information about files in a container" + description: | + A response header `X-Docker-Container-Path-Stat` is returned, containing + a base64 - encoded JSON object with some filesystem header information + about the path. + operationId: "ContainerArchiveInfo" + responses: + "200": + description: "no error" + headers: + X-Docker-Container-Path-Stat: + type: "string" + description: | + A base64 - encoded JSON object with some filesystem header + information about the path + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Container or path does not exist" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Resource in the container’s filesystem to archive." + type: "string" + tags: ["Container"] + get: + summary: "Get an archive of a filesystem resource in a container" + description: "Get a tar archive of a resource in the filesystem of container id." + operationId: "ContainerArchive" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Container or path does not exist" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Resource in the container’s filesystem to archive." + type: "string" + tags: ["Container"] + put: + summary: "Extract an archive of files or folders to a directory in a container" + description: | + Upload a tar archive to be extracted to a path in the filesystem of container id. + `path` parameter is asserted to be a directory. If it exists as a file, 400 error + will be returned with message "not a directory". + operationId: "PutContainerArchive" + consumes: ["application/x-tar", "application/octet-stream"] + responses: + "200": + description: "The content was extracted successfully" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "not a directory" + "403": + description: "Permission denied, the volume or container rootfs is marked as read-only." + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such container or path does not exist inside the container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the container" + type: "string" + - name: "path" + in: "query" + required: true + description: "Path to a directory in the container to extract the archive’s contents into. " + type: "string" + - name: "noOverwriteDirNonDir" + in: "query" + description: | + If `1`, `true`, or `True` then it will be an error if unpacking the + given content would cause an existing directory to be replaced with + a non-directory and vice versa. + type: "string" + - name: "copyUIDGID" + in: "query" + description: | + If `1`, `true`, then it will copy UID/GID maps to the dest file or + dir + type: "string" + - name: "inputStream" + in: "body" + required: true + description: | + The input stream must be a tar archive compressed with one of the + following algorithms: `identity` (no compression), `gzip`, `bzip2`, + or `xz`. + schema: + type: "string" + format: "binary" + tags: ["Container"] + /containers/prune: + post: + summary: "Delete stopped containers" + produces: + - "application/json" + operationId: "ContainerPrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ContainerPruneResponse" + properties: + ContainersDeleted: + description: "Container IDs that were deleted" + type: "array" + items: + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Container"] + /images/json: + get: + summary: "List Images" + description: "Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image." + operationId: "ImageList" + produces: + - "application/json" + responses: + "200": + description: "Summary image data for the images matching the query" + schema: + type: "array" + items: + $ref: "#/definitions/ImageSummary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "all" + in: "query" + description: "Show all images. Only images from a final layer (no children) are shown by default." + type: "boolean" + default: false + - name: "filters" + in: "query" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the images list. + + Available filters: + + - `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + - `dangling=true` + - `label=key` or `label="key=value"` of an image label + - `reference`=(`<image-name>[:<tag>]`) + - `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + - `until=<timestamp>` + type: "string" + - name: "shared-size" + in: "query" + description: "Compute and show shared size as a `SharedSize` field on each image." + type: "boolean" + default: false + - name: "digests" + in: "query" + description: "Show digest information as a `RepoDigests` field on each image." + type: "boolean" + default: false + - name: "manifests" + in: "query" + description: "Include `Manifests` in the image summary." + type: "boolean" + default: false + - name: "identity" + in: "query" + description: "Include `Identity` in each manifest summary. Requires `manifests=1`." + type: "boolean" + default: false + tags: ["Image"] + /build: + post: + summary: "Build an image" + description: | + Build an image from a tar archive with a `Dockerfile` in it. + + The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/). + + The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output. + + The build is canceled if the client drops the connection by quitting or being killed. + operationId: "ImageBuild" + consumes: + - "application/octet-stream" + produces: + - "application/json" + parameters: + - name: "inputStream" + in: "body" + description: "A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz." + schema: + type: "string" + format: "binary" + - name: "dockerfile" + in: "query" + description: "Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`." + type: "string" + default: "Dockerfile" + - name: "t" + in: "query" + description: "A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters." + type: "string" + - name: "extrahosts" + in: "query" + description: "Extra hosts to add to /etc/hosts" + type: "string" + - name: "remote" + in: "query" + description: "A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball." + type: "string" + - name: "q" + in: "query" + description: "Suppress verbose build output." + type: "boolean" + default: false + - name: "nocache" + in: "query" + description: "Do not use the cache when building the image." + type: "boolean" + default: false + - name: "cachefrom" + in: "query" + description: "JSON array of images used for build cache resolution." + type: "string" + - name: "pull" + in: "query" + description: "Attempt to pull the image even if an older image exists locally." + type: "string" + - name: "rm" + in: "query" + description: "Remove intermediate containers after a successful build." + type: "boolean" + default: true + - name: "forcerm" + in: "query" + description: "Always remove intermediate containers, even upon failure." + type: "boolean" + default: false + - name: "memory" + in: "query" + description: "Set memory limit for build." + type: "integer" + format: "int64" + - name: "memswap" + in: "query" + description: "Total memory (memory + swap). Set as `-1` to disable swap." + type: "integer" + format: "int64" + - name: "cpushares" + in: "query" + description: "CPU shares (relative weight)." + type: "integer" + format: "int64" + - name: "cpusetcpus" + in: "query" + description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)." + type: "string" + - name: "cpuperiod" + in: "query" + description: "The length of a CPU period in microseconds." + type: "integer" + format: "int64" + - name: "cpuquota" + in: "query" + description: "Microseconds of CPU time that the container can get in a CPU period." + type: "integer" + format: "int64" + - name: "buildargs" + in: "query" + description: > + JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker + uses the buildargs as the environment context for commands run via the `Dockerfile` RUN + instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for + passing secret values. + + + For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the + query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded. + + + [Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) + type: "string" + - name: "shmsize" + in: "query" + description: "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB." + type: "integer" + format: "int64" + - name: "squash" + in: "query" + description: "Squash the resulting images layers into a single layer. *(Experimental release only.)*" + type: "boolean" + - name: "labels" + in: "query" + description: "Arbitrary key/value labels to set on the image, as a JSON map of string pairs." + type: "string" + - name: "networkmode" + in: "query" + description: | + Sets the networking mode for the run commands during build. Supported + standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. + Any other value is taken as a custom network's name or ID to which this + container should connect to. + type: "string" + - name: "Content-type" + in: "header" + type: "string" + enum: + - "application/x-tar" + default: "application/x-tar" + - name: "X-Registry-Config" + in: "header" + description: | + This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to. + + The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example: + + ``` + { + "docker.example.com": { + "username": "janedoe", + "password": "hunter2" + }, + "https://index.docker.io/v1/": { + "username": "mobydock", + "password": "conta1n3rize14" + } + } + ``` + + Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. + type: "string" + - name: "platform" + in: "query" + description: "Platform in the format os[/arch[/variant]]" + type: "string" + default: "" + - name: "target" + in: "query" + description: "Target build stage" + type: "string" + default: "" + - name: "outputs" + in: "query" + description: | + BuildKit output configuration in the format of a stringified JSON array of objects. + Each object must have two top-level properties: `Type` and `Attrs`. + The `Type` property must be set to 'moby'. + The `Attrs` property is a map of attributes for the BuildKit output configuration. + See https://docs.docker.com/build/exporters/oci-docker/ for more information. + + Example: + + ``` + [{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}] + ``` + type: "string" + default: "" + - name: "version" + in: "query" + type: "string" + default: "1" + enum: ["1", "2"] + description: | + Version of the builder backend to use. + + - `1` is the first generation classic (deprecated) builder in the Docker daemon (default) + - `2` is [BuildKit](https://github.com/moby/buildkit) + responses: + "200": + description: "no error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /build/prune: + post: + summary: "Delete builder cache" + produces: + - "application/json" + operationId: "BuildPrune" + parameters: + - name: "reserved-space" + in: "query" + description: "Amount of disk space in bytes to keep for cache" + type: "integer" + format: "int64" + - name: "max-used-space" + in: "query" + description: "Maximum amount of disk space allowed to keep for cache" + type: "integer" + format: "int64" + - name: "min-free-space" + in: "query" + description: "Target amount of free disk space after pruning" + type: "integer" + format: "int64" + - name: "all" + in: "query" + type: "boolean" + description: "Remove all types of build cache" + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the list of build cache objects. + + Available filters: + + - `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time. + - `id=<id>` + - `parent=<id>` + - `type=<string>` + - `description=<string>` + - `inuse` + - `shared` + - `private` + responses: + "200": + description: "No error" + schema: + type: "object" + title: "BuildPruneResponse" + properties: + CachesDeleted: + type: "array" + items: + description: "ID of build cache object" + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /images/create: + post: + summary: "Create an image" + description: "Pull or import an image." + operationId: "ImageCreate" + consumes: + - "text/plain" + - "application/octet-stream" + produces: + - "application/json" + responses: + "200": + description: "no error" + "404": + description: "repository does not exist or no read access" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "fromImage" + in: "query" + description: | + Name of the image to pull. If the name includes a tag or digest, specific behavior applies: + + - If only `fromImage` includes a tag, that tag is used. + - If both `fromImage` and `tag` are provided, `tag` takes precedence. + - If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored. + - If neither a tag nor digest is specified, all tags are pulled. + type: "string" + - name: "fromSrc" + in: "query" + description: "Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image." + type: "string" + - name: "repo" + in: "query" + description: "Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image." + type: "string" + - name: "tag" + in: "query" + description: "Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled." + type: "string" + - name: "message" + in: "query" + description: "Set commit message for imported image." + type: "string" + - name: "inputImage" + in: "body" + description: "Image content if the value `-` has been specified in fromSrc query parameter" + schema: + type: "string" + required: false + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "changes" + in: "query" + description: | + Apply `Dockerfile` instructions to the image that is created, + for example: `changes=ENV DEBUG=true`. + Note that `ENV DEBUG=true` should be URI component encoded. + Repeat the parameter to apply multiple instructions. + + Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + type: "array" + collectionFormat: "multi" + items: + type: "string" + - name: "platform" + in: "query" + description: | + Platform in the format os[/arch[/variant]]. + + When used in combination with the `fromImage` option, the daemon checks + if the given image is present in the local image cache with the given + OS and Architecture, and otherwise attempts to pull the image. If the + option is not set, the host's native OS and Architecture are used. + If the given image does not exist in the local image cache, the daemon + attempts to pull the image with the host's native OS and Architecture. + If the given image does exists in the local image cache, but its OS or + architecture does not match, a warning is produced. + + When used with the `fromSrc` option to import an image from an archive, + this option sets the platform information for the imported image. If + the option is not set, the host's native OS and Architecture are used + for the imported image. + type: "string" + default: "" + tags: ["Image"] + /images/{name}/json: + get: + summary: "Inspect an image" + description: "Return low-level information about an image." + operationId: "ImageInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/ImageInspect" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: someimage (tag: latest)" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + - name: "manifests" + in: "query" + description: |- + Include Manifests in the image summary. + + The `manifests` and `platform` options are mutually exclusive, and + an error is produced if both are set. + type: "boolean" + default: false + required: false + - name: "platform" + type: "string" + in: "query" + description: |- + JSON-encoded OCI platform to select the platform-variant. + If omitted, it defaults to any locally available platform, + prioritizing the daemon's host platform. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to show inspect. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + The `platform` and `manifests` options are mutually exclusive, and + an error is produced if both are set. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/{name}/attestations: + get: + summary: "Get attestation statements for an image" + description: | + Return the in-toto attestation statements attached to the image for the + given platform. The daemon locates the attestation manifest(s) that + reference the matching platform image manifest, reads their statement + layers, and returns the verbatim statement JSON together with layer + metadata. + + If the image has no attestations an empty array is returned. + operationId: "ImageAttestations" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/AttestationStatement" + "400": + description: "Bad parameter (e.g. malformed `platform` value)" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such image, or no manifest found for the requested platform" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + "501": + description: | + The daemon's image backend does not support attestations. This + is returned by the legacy (graphdriver) image store, which does + not preserve OCI image indexes. + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: |- + JSON-encoded OCI platform to select the image variant whose + attestations to return. + If omitted, the daemon's default (host) platform is used. + + Only one platform value is currently accepted; passing more than + one returns an error. The parameter is declared as an array so the + wire shape can accept multiple values in the future without an + API version bump. + + Example: `{"os": "linux", "architecture": "amd64"}` + required: false + - name: "type" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: |- + In-toto predicate type URI to filter returned statements. May be + repeated to accept any of several predicate types. If omitted, all + statements are returned. + + Example: `type=https://slsa.dev/provenance/v0.2&type=https://spdx.dev/Document` + required: false + - name: "statement" + type: "boolean" + in: "query" + description: |- + Include the verbatim in-toto statement body in each returned + entry. Defaults to false; when omitted or false, only the + descriptor and predicate type are returned and statement blobs + are not read. + default: false + required: false + tags: ["Image"] + /images/{name}/history: + get: + summary: "Get the history of an image" + description: "Return parent layers of an image." + operationId: "ImageHistory" + produces: ["application/json"] + responses: + "200": + description: "List of image layers" + schema: + type: "array" + items: + $ref: "#/definitions/ImageHistoryResponseItem" + examples: + application/json: + - Id: "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710" + Created: 1398108230 + CreatedBy: "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /" + Tags: + - "ubuntu:lucid" + - "ubuntu:10.04" + Size: 182964289 + Comment: "" + - Id: "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8" + Created: 1398108222 + CreatedBy: "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/" + Tags: [] + Size: 0 + Comment: "" + - Id: "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158" + Created: 1371157430 + CreatedBy: "" + Tags: + - "scratch12:latest" + - "scratch:latest" + Size: 0 + Comment: "Imported from -" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant. + If omitted, it defaults to any locally available platform, + prioritizing the daemon's host platform. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to show the history for. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/{name}/push: + post: + summary: "Push an image" + description: | + Push an image to a registry. + + If you wish to push an image on to a private registry, that image must + already have a tag which references the registry. For example, + `registry.example.com/myimage:latest`. + + The push is cancelled if the HTTP connection is closed. + operationId: "ImagePush" + consumes: + - "application/octet-stream" + responses: + "200": + description: "No error" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + Name of the image to push. For example, `registry.example.com/myimage`. + The image must be present in the local image store with the same name. + + The name should be provided without tag; if a tag is provided, it + is ignored. For example, `registry.example.com/myimage:latest` is + considered equivalent to `registry.example.com/myimage`. + + Use the `tag` parameter to specify the tag to push. + type: "string" + required: true + - name: "tag" + in: "query" + description: | + Tag of the image to push. For example, `latest`. If no tag is provided, + all tags of the given image that are present in the local image store + are pushed. + type: "string" + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant to push. + If not provided, all available variants will attempt to be pushed. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to push to the registry. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + required: true + tags: ["Image"] + /images/{name}/tag: + post: + summary: "Tag an image" + description: | + Create a tag that refers to a source image. + + This creates an additional reference (tag) to the source image. The tag + can include a different repository name and/or tag. If the repository + or tag already exists, it will be overwritten. + operationId: "ImageTag" + responses: + "201": + description: "No error" + "400": + description: "Bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID to tag." + type: "string" + required: true + - name: "repo" + in: "query" + description: "The repository to tag in. For example, `someuser/someimage`." + type: "string" + - name: "tag" + in: "query" + description: "The name of the new tag." + type: "string" + tags: ["Image"] + /images/{name}: + delete: + summary: "Remove an image" + description: | + Remove an image, along with any untagged parent images that were + referenced by that image. + + Images can't be removed if they have descendant images, are being + used by a running container or are being used by a build. + operationId: "ImageDelete" + produces: ["application/json"] + responses: + "200": + description: "The image was deleted successfully" + schema: + type: "array" + items: + $ref: "#/definitions/ImageDeleteResponseItem" + examples: + application/json: + - Untagged: "3e2f21a89f" + - Deleted: "3e2f21a89f" + - Deleted: "53b4f83ac9" + "404": + description: "No such image" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Conflict" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "force" + in: "query" + description: "Remove the image even if it is being used by stopped containers or has other tags" + type: "boolean" + default: false + - name: "noprune" + in: "query" + description: "Do not delete untagged parent images" + type: "boolean" + default: false + - name: "platforms" + in: "query" + description: | + Select platform-specific content to delete. + Repeat the parameter to select multiple platforms. + Each platform is a OCI platform encoded as a JSON string. + type: "array" + collectionFormat: "multi" + items: + # This should be OCIPlatform + # but $ref is not supported for array in query in Swagger 2.0 + # $ref: "#/definitions/OCIPlatform" + type: "string" + tags: ["Image"] + /images/search: + get: + summary: "Search images" + description: "Search for an image on Docker Hub." + operationId: "ImageSearch" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + type: "object" + title: "ImageSearchResponseItem" + properties: + description: + type: "string" + is_official: + type: "boolean" + is_automated: + description: | + Whether this repository has automated builds enabled. + + <p><br /></p> + + > **Deprecated**: This field is deprecated and will always be "false". + type: "boolean" + example: false + name: + type: "string" + star_count: + type: "integer" + examples: + application/json: + - description: "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!" + is_official: true + is_automated: false + name: "alpine" + star_count: 10093 + - description: "Busybox base image." + is_official: true + is_automated: false + name: "Busybox base image." + star_count: 3037 + - description: "The PostgreSQL object-relational database system provides reliability and data integrity." + is_official: true + is_automated: false + name: "postgres" + star_count: 12408 + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "term" + in: "query" + description: "Term to search" + type: "string" + required: true + - name: "limit" + in: "query" + description: "Maximum number of results to return" + type: "integer" + - name: "filters" + in: "query" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + + - `is-official=(true|false)` + - `stars=<number>` Matches images that has at least 'number' stars. + type: "string" + tags: ["Image"] + /images/prune: + post: + summary: "Delete unused images" + produces: + - "application/json" + operationId: "ImagePrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), prune only + unused *and* untagged images. When set to `false` + (or `0`), all unused images are pruned. + - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ImagePruneResponse" + properties: + ImagesDeleted: + description: "Images that were deleted" + type: "array" + items: + $ref: "#/definitions/ImageDeleteResponseItem" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Image"] + /auth: + post: + summary: "Check auth configuration" + description: | + Validate credentials for a registry and, if available, get an identity + token for accessing the registry without password. + operationId: "SystemAuth" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "An identity token was generated successfully." + schema: + $ref: "#/definitions/AuthResponse" + "204": + description: "No error" + "401": + description: "Auth error" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "authConfig" + in: "body" + description: "Authentication to check" + schema: + $ref: "#/definitions/AuthConfig" + tags: ["System"] + /info: + get: + summary: "Get system information" + operationId: "SystemInfo" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/SystemInfo" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /version: + get: + summary: "Get version" + description: "Returns the version of Docker that is running and various information about the system that Docker is running on." + operationId: "SystemVersion" + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/SystemVersion" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /_ping: + get: + summary: "Ping" + description: "This is a dummy endpoint you can use to test if the server is accessible." + operationId: "SystemPing" + produces: + - "text/plain" + responses: + "200": + description: "no error" + schema: + type: "string" + example: "OK" + headers: + Api-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: | + Default version of docker image builder + + The default on Linux is version "2" (BuildKit), but the daemon + can be configured to recommend version "1" (classic Builder). + Windows does not yet support BuildKit for native Windows images, + and uses "1" (classic builder) as a default. + + This value is a recommendation as advertised by the daemon, and + it is up to the client to choose which builder to use. + default: "2" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + headers: + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + tags: ["System"] + head: + summary: "Ping" + description: "This is a dummy endpoint you can use to test if the server is accessible." + operationId: "SystemPingHead" + produces: ["text/plain"] + responses: + "200": + description: "no error" + schema: + type: "string" + example: "(empty)" + headers: + Api-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: "Default version of docker image builder" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["System"] + /commit: + post: + summary: "Create a new image from a container" + operationId: "ImageCommit" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "containerConfig" + in: "body" + description: "The container configuration" + schema: + $ref: "#/definitions/ContainerConfig" + - name: "container" + in: "query" + description: "The ID or name of the container to commit" + type: "string" + - name: "repo" + in: "query" + description: "Repository name for the created image" + type: "string" + - name: "tag" + in: "query" + description: "Tag name for the create image" + type: "string" + - name: "comment" + in: "query" + description: "Commit message" + type: "string" + - name: "author" + in: "query" + description: "Author of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`)" + type: "string" + - name: "pause" + in: "query" + description: "Whether to pause the container before committing" + type: "boolean" + default: true + - name: "changes" + in: "query" + description: "`Dockerfile` instructions to apply while committing" + type: "string" + tags: ["Image"] + /events: + get: + summary: "Monitor events" + description: | + Stream real-time events from the server. + + Various objects within Docker report events when something happens to them. + + Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune` + + Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune` + + Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune` + + Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune` + + The Docker daemon reports these events: `reload` + + Services report these events: `create`, `update`, and `remove` + + Nodes report these events: `create`, `update`, and `remove` + + Secrets report these events: `create`, `update`, and `remove` + + Configs report these events: `create`, `update`, and `remove` + + The Builder reports `prune` events + + operationId: "SystemEvents" + produces: + - "application/jsonl" + - "application/x-ndjson" + - "application/json-seq" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/EventMessage" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "since" + in: "query" + description: "Show events created since this timestamp then stream new events." + type: "string" + - name: "until" + in: "query" + description: "Show events created until this timestamp then stop streaming." + type: "string" + - name: "filters" + in: "query" + description: | + A JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters: + + - `config=<string>` config name or ID + - `container=<string>` container name or ID + - `daemon=<string>` daemon name or ID + - `event=<string>` event type + - `image=<string>` image name or ID + - `label=<string>` image or container label + - `network=<string>` network name or ID + - `node=<string>` node ID + - `plugin`=<string> plugin name or ID + - `scope`=<string> local or swarm + - `secret=<string>` secret name or ID + - `service=<string>` service name or ID + - `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config` + - `volume=<string>` volume name + type: "string" + tags: ["System"] + /system/df: + get: + summary: "Get data usage information" + operationId: "SystemDataUsage" + responses: + "200": + description: "no error" + schema: + type: "object" + title: "SystemDataUsageResponse" + properties: + ImageUsage: + $ref: "#/definitions/ImagesDiskUsage" + ContainerUsage: + $ref: "#/definitions/ContainersDiskUsage" + VolumeUsage: + $ref: "#/definitions/VolumesDiskUsage" + BuildCacheUsage: + $ref: "#/definitions/BuildCacheDiskUsage" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "type" + in: "query" + description: | + Object types, for which to compute and return data. + type: "array" + collectionFormat: multi + items: + type: "string" + enum: ["container", "image", "volume", "build-cache"] + - name: "verbose" + in: "query" + description: | + Show detailed information on space usage. + type: "boolean" + default: false + tags: ["System"] + /images/{name}/get: + get: + summary: "Export an image" + description: | + Get a tarball containing all images and metadata for a repository. + + If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced. + + ### Image tarball format + + An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content). + + Additionally, includes the manifest.json file associated with a backwards compatible docker save format. + + If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs. + + ```json + { + "hello-world": { + "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1" + } + } + ``` + operationId: "ImageGet" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + schema: + type: "string" + format: "binary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or ID" + type: "string" + required: true + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform describing a platform which will be used + to select a platform-specific image to be saved if the image is + multi-platform. + If not provided, the full multi-platform image will be saved. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/get: + get: + summary: "Export several images" + description: | + Get a tarball containing all images and metadata for several image + repositories. + + For each value of the `names` parameter: if it is a specific name and + tag (e.g. `ubuntu:latest`), then only that image (and its parents) are + returned; if it is an image ID, similarly only that image (and its parents) + are returned and there would be no names referenced in the 'repositories' + file for this image ID. + + For details on the format, see the [export image endpoint](#operation/ImageGet). + operationId: "ImageGetAll" + produces: + - "application/x-tar" + responses: + "200": + description: "no error" + schema: + type: "string" + format: "binary" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "names" + in: "query" + description: "Image names to filter by. Repeat the parameter for multiple images." + type: "array" + collectionFormat: "multi" + items: + type: "string" + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform(s) which will be used to select the + platform-specific image(s) to be saved if the image is + multi-platform. If not provided, the full multi-platform image + will be saved. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /images/load: + post: + summary: "Import images" + description: | + Load a set of images and tags into a repository. + + For details on the format, see the [export image endpoint](#operation/ImageGet). + operationId: "ImageLoad" + consumes: + - "application/x-tar" + produces: + - "application/json" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "imagesTarball" + in: "body" + description: "Tar archive containing images" + schema: + type: "string" + format: "binary" + - name: "quiet" + in: "query" + description: "Suppress progress details during load." + type: "boolean" + default: false + - name: "platform" + type: "array" + items: + type: "string" + collectionFormat: "multi" + in: "query" + description: | + JSON encoded OCI platform(s) which will be used to select the + platform-specific image(s) to load if the image is + multi-platform. If not provided, the full multi-platform image + will be loaded. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` + tags: ["Image"] + /containers/{id}/exec: + post: + summary: "Create an exec instance" + description: "Run a command inside a running container." + operationId: "ContainerExec" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "404": + description: "no such container" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such container: c2ada9df5af8" + "409": + description: "container is paused" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "execConfig" + in: "body" + description: "Exec configuration" + schema: + type: "object" + title: "ExecConfig" + properties: + AttachStdin: + type: "boolean" + description: "Attach to `stdin` of the exec command." + AttachStdout: + type: "boolean" + description: "Attach to `stdout` of the exec command." + AttachStderr: + type: "boolean" + description: "Attach to `stderr` of the exec command." + ConsoleSize: + type: "array" + description: "Initial console size, as an `[height, width]` array." + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + DetachKeys: + type: "string" + description: | + Override the key sequence for detaching a container. Format is + a single character `[a-Z]` or `ctrl-<value>` where `<value>` + is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. + Tty: + type: "boolean" + description: "Allocate a pseudo-TTY." + Env: + description: | + A list of environment variables in the form `["VAR=value", ...]`. + type: "array" + items: + type: "string" + Cmd: + type: "array" + description: "Command to run, as a string or array of strings." + items: + type: "string" + Privileged: + type: "boolean" + description: "Runs the exec process with extended privileges." + default: false + User: + type: "string" + description: | + The user, and optionally, group to run the exec process inside + the container. Format is one of: `user`, `user:group`, `uid`, + or `uid:gid`. + WorkingDir: + type: "string" + description: | + The working directory for the exec process inside the container. + example: + AttachStdin: false + AttachStdout: true + AttachStderr: true + DetachKeys: "ctrl-p,ctrl-q" + Tty: false + Cmd: + - "date" + Env: + - "FOO=bar" + - "BAZ=quux" + required: true + - name: "id" + in: "path" + description: "ID or name of container" + type: "string" + required: true + tags: ["Exec"] + /exec/{id}/start: + post: + summary: "Start an exec instance" + description: | + Starts a previously set up exec instance. If detach is true, this endpoint + returns immediately after starting the command. Otherwise, it sets up an + interactive session with the command. + operationId: "ExecStart" + consumes: + - "application/json" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "200": + description: "No error" + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Container is stopped or paused" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "execStartConfig" + in: "body" + schema: + type: "object" + title: "ExecStartConfig" + properties: + Detach: + type: "boolean" + description: "Detach from the command." + example: false + Tty: + type: "boolean" + description: "Allocate a pseudo-TTY." + example: true + ConsoleSize: + type: "array" + description: "Initial console size, as an `[height, width]` array." + x-nullable: true + minItems: 2 + maxItems: 2 + items: + type: "integer" + minimum: 0 + example: [80, 64] + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + tags: ["Exec"] + /exec/{id}/resize: + post: + summary: "Resize an exec instance" + description: | + Resize the TTY session used by an exec instance. This endpoint only works + if `tty` was specified as part of creating and starting the exec instance. + operationId: "ExecResize" + responses: + "200": + description: "No error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + - name: "h" + in: "query" + required: true + description: "Height of the TTY session in characters" + type: "integer" + - name: "w" + in: "query" + required: true + description: "Width of the TTY session in characters" + type: "integer" + tags: ["Exec"] + /exec/{id}/json: + get: + summary: "Inspect an exec instance" + description: "Return low-level information about an exec instance." + operationId: "ExecInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "ExecInspectResponse" + properties: + CanRemove: + type: "boolean" + DetachKeys: + type: "string" + ID: + type: "string" + Running: + type: "boolean" + ExitCode: + type: "integer" + ProcessConfig: + $ref: "#/definitions/ProcessConfig" + OpenStdin: + type: "boolean" + OpenStderr: + type: "boolean" + OpenStdout: + type: "boolean" + ContainerID: + type: "string" + Pid: + type: "integer" + description: "The system process ID for the exec process." + examples: + application/json: + CanRemove: false + ContainerID: "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126" + DetachKeys: "" + ExitCode: 2 + ID: "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b" + OpenStderr: true + OpenStdin: true + OpenStdout: true + ProcessConfig: + arguments: + - "-c" + - "exit 2" + entrypoint: "sh" + privileged: false + tty: true + user: "1000" + Running: false + Pid: 42000 + "404": + description: "No such exec instance" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Exec instance ID" + required: true + type: "string" + tags: ["Exec"] + + /volumes: + get: + summary: "List volumes" + operationId: "VolumeList" + produces: ["application/json"] + responses: + "200": + description: "Summary volume data that matches the query" + schema: + $ref: "#/definitions/VolumeListResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + JSON encoded value of the filters (a `map[string][]string`) to + process on the volumes list. Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), returns all + volumes that are not in use by a container. When set to `false` + (or `0`), only volumes that are in use by one or more + containers are returned. + - `driver=<volume-driver-name>` Matches volumes based on their driver. + - `label=<key>` or `label=<key>:<value>` Matches volumes based on + the presence of a `label` alone or a `label` and a value. + - `name=<volume-name>` Matches all or part of a volume name. + type: "string" + format: "json" + tags: ["Volume"] + + /volumes/create: + post: + summary: "Create a volume" + operationId: "VolumeCreate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "201": + description: "The volume was created successfully" + schema: + $ref: "#/definitions/Volume" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "volumeConfig" + in: "body" + required: true + description: "Volume configuration" + schema: + $ref: "#/definitions/VolumeCreateRequest" + tags: ["Volume"] + + /volumes/{name}: + get: + summary: "Inspect a volume" + operationId: "VolumeInspect" + produces: ["application/json"] + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/Volume" + "404": + description: "No such volume" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + required: true + description: "Volume name or ID" + type: "string" + tags: ["Volume"] + + put: + summary: | + "Update a volume. Valid only for Swarm cluster volumes" + operationId: "VolumeUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such volume" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "The name or ID of the volume" + type: "string" + required: true + - name: "body" + in: "body" + schema: + # though the schema for is an object that contains only a + # ClusterVolumeSpec, wrapping the ClusterVolumeSpec in this object + # means that if, later on, we support things like changing the + # labels, we can do so without duplicating that information to the + # ClusterVolumeSpec. + type: "object" + description: "Volume configuration" + properties: + Spec: + $ref: "#/definitions/ClusterVolumeSpec" + description: | + The spec of the volume to update. Currently, only Availability may + change. All other fields must remain unchanged. + - name: "version" + in: "query" + description: | + The version number of the volume being updated. This is required to + avoid conflicting writes. Found in the volume's `ClusterVolume` + field. + type: "integer" + format: "int64" + required: true + tags: ["Volume"] + + delete: + summary: "Remove a volume" + description: "Instruct the driver to remove the volume." + operationId: "VolumeDelete" + responses: + "204": + description: "The volume was removed" + "404": + description: "No such volume or volume driver" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "Volume is in use and cannot be removed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + required: true + description: "Volume name or ID" + type: "string" + - name: "force" + in: "query" + description: "Force the removal of the volume" + type: "boolean" + default: false + produces: + - "application/json" + tags: ["Volume"] + + /volumes/prune: + post: + summary: "Delete unused volumes" + produces: + - "application/json" + operationId: "VolumePrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. + - `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "VolumePruneResponse" + properties: + VolumesDeleted: + description: "Volumes that were deleted" + type: "array" + items: + type: "string" + SpaceReclaimed: + description: "Disk space reclaimed in bytes" + type: "integer" + format: "int64" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Volume"] + /networks: + get: + summary: "List networks" + description: | + Returns a list of networks. For details on the format, see the + [network inspect endpoint](#operation/NetworkInspect). + + Note that it uses a different, smaller representation of a network than + inspecting a single network. For example, the list of containers attached + to the network is not propagated in API versions 1.28 and up. + operationId: "NetworkList" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/NetworkSummary" + examples: + application/json: + - Name: "bridge" + Id: "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566" + Created: "2016-10-19T06:21:00.416543526Z" + Scope: "local" + Driver: "bridge" + EnableIPv4: true + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: + - + Subnet: "172.17.0.0/16" + Options: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + - Name: "none" + Id: "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794" + Created: "0001-01-01T00:00:00Z" + Scope: "local" + Driver: "null" + EnableIPv4: false + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: [] + Containers: {} + Options: {} + - Name: "host" + Id: "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e" + Created: "0001-01-01T00:00:00Z" + Scope: "local" + Driver: "host" + EnableIPv4: false + EnableIPv6: false + Internal: false + Attachable: false + Ingress: false + IPAM: + Driver: "default" + Config: [] + Containers: {} + Options: {} + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + JSON encoded value of the filters (a `map[string][]string`) to process + on the networks list. + + Available filters: + + - `dangling=<boolean>` When set to `true` (or `1`), returns all + networks that are not in use by a container. When set to `false` + (or `0`), only networks that are in use by one or more + containers are returned. + - `driver=<driver-name>` Matches a network's driver. + - `id=<network-id>` Matches all or part of a network ID. + - `label=<key>` or `label=<key>=<value>` of a network label. + - `name=<network-name>` Matches all or part of a network name. + - `scope=["swarm"|"global"|"local"]` Filters networks by scope (`swarm`, `global`, or `local`). + - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. + type: "string" + tags: ["Network"] + + /networks/{id}: + get: + summary: "Inspect a network" + operationId: "NetworkInspect" + produces: + - "application/json" + responses: + "200": + description: "No error" + schema: + $ref: "#/definitions/NetworkInspect" + "404": + description: "Network not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "verbose" + in: "query" + description: "Detailed inspect output for troubleshooting" + type: "boolean" + default: false + - name: "scope" + in: "query" + description: "Filter the network by scope (swarm, global, or local)" + type: "string" + tags: ["Network"] + + delete: + summary: "Remove a network" + operationId: "NetworkDelete" + responses: + "204": + description: "No error" + "403": + description: "operation not supported for pre-defined networks" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such network" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + produces: + - "application/json" + tags: ["Network"] + + /networks/create: + post: + summary: "Create a network" + operationId: "NetworkCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "Network created successfully" + schema: + $ref: "#/definitions/NetworkCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: | + Forbidden operation. This happens when trying to create a network named after a pre-defined network, + or when trying to create an overlay network on a daemon which is not part of a Swarm cluster. + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "plugin not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "networkConfig" + in: "body" + description: "Network configuration" + required: true + schema: + type: "object" + title: "NetworkCreateRequest" + required: ["Name"] + properties: + Name: + description: "The network's name." + type: "string" + example: "my_network" + Driver: + description: "Name of the network driver plugin to use." + type: "string" + default: "bridge" + example: "bridge" + Scope: + description: | + The level at which the network exists (e.g. `swarm` for cluster-wide + or `local` for machine level). + type: "string" + Internal: + description: "Restrict external access to the network." + type: "boolean" + Attachable: + description: | + Globally scoped network is manually attachable by regular + containers from workers in swarm mode. + type: "boolean" + example: true + Ingress: + description: | + Ingress network is the network which provides the routing-mesh + in swarm mode. + type: "boolean" + example: false + ConfigOnly: + description: | + Creates a config-only network. Config-only networks are placeholder + networks for network configurations to be used by other networks. + Config-only networks cannot be used directly to run containers + or services. + type: "boolean" + default: false + example: false + ConfigFrom: + description: | + Specifies the source which will provide the configuration for + this network. The specified network must be an existing + config-only network; see ConfigOnly. + $ref: "#/definitions/ConfigReference" + IPAM: + description: "Optional custom IP scheme for the network." + $ref: "#/definitions/IPAM" + EnableIPv4: + description: "Enable IPv4 on the network." + type: "boolean" + example: true + EnableIPv6: + description: "Enable IPv6 on the network." + type: "boolean" + example: true + Options: + description: "Network specific options to be used by the drivers." + type: "object" + additionalProperties: + type: "string" + example: + com.docker.network.bridge.default_bridge: "true" + com.docker.network.bridge.enable_icc: "true" + com.docker.network.bridge.enable_ip_masquerade: "true" + com.docker.network.bridge.host_binding_ipv4: "0.0.0.0" + com.docker.network.bridge.name: "docker0" + com.docker.network.driver.mtu: "1500" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" + tags: ["Network"] + + /networks/{id}/connect: + post: + summary: "Connect a container to a network" + description: "The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container" + operationId: "NetworkConnect" + consumes: + - "application/json" + responses: + "200": + description: "No error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: "Operation forbidden" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Network or container not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "container" + in: "body" + required: true + schema: + $ref: "#/definitions/NetworkConnectRequest" + tags: ["Network"] + + /networks/{id}/disconnect: + post: + summary: "Disconnect a container from a network" + operationId: "NetworkDisconnect" + consumes: + - "application/json" + responses: + "200": + description: "No error" + "403": + description: "Operation not supported for swarm scoped networks" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "Network or container not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "Network ID or name" + required: true + type: "string" + - name: "container" + in: "body" + required: true + schema: + $ref: "#/definitions/NetworkDisconnectRequest" + tags: ["Network"] + /networks/prune: + post: + summary: "Delete unused networks" + produces: + - "application/json" + operationId: "NetworkPrune" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the prune list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. + type: "string" + responses: + "200": + description: "No error" + schema: + type: "object" + title: "NetworkPruneResponse" + properties: + NetworksDeleted: + description: "Networks that were deleted" + type: "array" + items: + type: "string" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Network"] + /plugins: + get: + summary: "List plugins" + operationId: "PluginList" + description: "Returns information about installed plugins." + produces: ["application/json"] + responses: + "200": + description: "No error" + schema: + type: "array" + items: + $ref: "#/definitions/Plugin" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the plugin list. + + Available filters: + + - `capability=<capability name>` + - `enable=<true>|<false>` + tags: ["Plugin"] + + /plugins/privileges: + get: + summary: "Get plugin privileges" + operationId: "GetPluginPrivileges" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "remote" + in: "query" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + tags: + - "Plugin" + + /plugins/pull: + post: + summary: "Install a plugin" + operationId: "PluginPull" + description: | + Pulls and installs a plugin. After the plugin is installed, it can be + enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable). + produces: + - "application/json" + responses: + "204": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "remote" + in: "query" + description: | + Remote reference for plugin to install. + + The `:latest` tag is optional, and is used as the default if omitted. + required: true + type: "string" + - name: "name" + in: "query" + description: | + Local name for the pulled plugin. + + The `:latest` tag is optional, and is used as the default if omitted. + required: false + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration to use when pulling a plugin + from a registry. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + tags: ["Plugin"] + /plugins/{name}/json: + get: + summary: "Inspect a plugin" + operationId: "PluginInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Plugin" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + tags: ["Plugin"] + /plugins/{name}: + delete: + summary: "Remove a plugin" + operationId: "PluginDelete" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Plugin" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "force" + in: "query" + description: | + Disable the plugin before removing. This may result in issues if the + plugin is in use by a container. + type: "boolean" + default: false + tags: ["Plugin"] + /plugins/{name}/enable: + post: + summary: "Enable a plugin" + operationId: "PluginEnable" + responses: + "200": + description: "no error" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "timeout" + in: "query" + description: "Set the HTTP client timeout (in seconds)" + type: "integer" + default: 0 + tags: ["Plugin"] + /plugins/{name}/disable: + post: + summary: "Disable a plugin" + operationId: "PluginDisable" + responses: + "200": + description: "no error" + "404": + description: "plugin is not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "force" + in: "query" + description: | + Force disable a plugin even if still in use. + required: false + type: "boolean" + tags: ["Plugin"] + /plugins/{name}/upgrade: + post: + summary: "Upgrade a plugin" + operationId: "PluginUpgrade" + responses: + "204": + description: "no error" + "404": + description: "plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "remote" + in: "query" + description: | + Remote reference to upgrade to. + + The `:latest` tag is optional, and is used as the default if omitted. + required: true + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration to use when pulling a plugin + from a registry. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + $ref: "#/definitions/PluginPrivilege" + example: + - Name: "network" + Description: "" + Value: + - "host" + - Name: "mount" + Description: "" + Value: + - "/data" + - Name: "device" + Description: "" + Value: + - "/dev/cpu_dma_latency" + produces: + - "application/json" + tags: ["Plugin"] + /plugins/create: + post: + summary: "Create a plugin" + operationId: "PluginCreate" + consumes: + - "application/x-tar" + responses: + "204": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "query" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "tarContext" + in: "body" + description: "Path to tar containing plugin rootfs and manifest" + schema: + type: "string" + format: "binary" + produces: + - "application/json" + tags: ["Plugin"] + /plugins/{name}/push: + post: + summary: "Push a plugin" + operationId: "PluginPush" + description: | + Push a plugin to the registry. + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + responses: + "200": + description: "no error" + "404": + description: "plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Plugin"] + /plugins/{name}/set: + post: + summary: "Configure a plugin" + operationId: "PluginSet" + consumes: + - "application/json" + parameters: + - name: "name" + in: "path" + description: | + The name of the plugin. The `:latest` tag is optional, and is the + default if omitted. + required: true + type: "string" + - name: "body" + in: "body" + schema: + type: "array" + items: + type: "string" + example: ["DEBUG=1"] + responses: + "204": + description: "No error" + "404": + description: "Plugin not installed" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + produces: + - "application/json" + tags: ["Plugin"] + /nodes: + get: + summary: "List nodes" + operationId: "NodeList" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Node" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + description: | + Filters to process on the nodes list, encoded as JSON (a `map[string][]string`). + + Available filters: + - `id=<node id>` + - `label=<engine label>` + - `membership=`(`accepted`|`pending`)` + - `name=<node name>` + - `node.label=<node label>` + - `role=`(`manager`|`worker`)` + type: "string" + tags: ["Node"] + /nodes/{id}: + get: + summary: "Inspect a node" + operationId: "NodeInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Node" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the node" + type: "string" + required: true + tags: ["Node"] + delete: + summary: "Delete a node" + operationId: "NodeDelete" + responses: + "200": + description: "no error" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the node" + type: "string" + required: true + - name: "force" + in: "query" + description: "Force remove a node from the swarm" + default: false + type: "boolean" + tags: ["Node"] + /nodes/{id}/update: + post: + summary: "Update a node" + operationId: "NodeUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such node" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID of the node" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/NodeSpec" + - name: "version" + in: "query" + description: | + The version number of the node object being updated. This is required + to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Node"] + /swarm: + get: + summary: "Inspect swarm" + operationId: "SwarmInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Swarm" + "404": + description: "no such swarm" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /swarm/init: + post: + summary: "Initialize a new swarm" + operationId: "SwarmInit" + produces: + - "application/json" + - "text/plain" + responses: + "200": + description: "no error" + schema: + description: "The node ID" + type: "string" + example: "7v2t30z9blmxuhnyo6s4cpenp" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is already part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmInitRequest" + properties: + ListenAddr: + description: | + Listen address used for inter-manager communication, as well + as determining the networking interface used for the VXLAN + Tunnel Endpoint (VTEP). This can either be an address/port + combination in the form `192.168.1.1:4567`, or an interface + followed by a port number, like `eth0:4567`. If the port number + is omitted, the default swarm listening port is used. + type: "string" + AdvertiseAddr: + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. + type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: + `<ip|interface>`), for example, `192.168.1.1`, or an interface, + like `eth0`. If `DataPathAddr` is unspecified, the same address + as `AdvertiseAddr` is used. + + The `DataPathAddr` specifies the address that global scope + network drivers will publish towards other nodes in order to + reach the containers running on this node. Using this parameter + it is possible to separate the container data traffic from the + management traffic of the cluster. + type: "string" + DataPathPort: + description: | + DataPathPort specifies the data path port number for data traffic. + Acceptable port range is 1024 to 49151. + if no port is set or is set to 0, default port 4789 will be used. + type: "integer" + format: "uint32" + DefaultAddrPool: + description: | + Default Address Pool specifies default subnet pools for global + scope networks. + type: "array" + items: + type: "string" + example: ["10.10.0.0/16", "20.20.0.0/16"] + ForceNewCluster: + description: "Force creation of a new swarm." + type: "boolean" + SubnetSize: + description: | + SubnetSize specifies the subnet size of the networks created + from the default subnet pool. + type: "integer" + format: "uint32" + Spec: + $ref: "#/definitions/SwarmSpec" + example: + ListenAddr: "0.0.0.0:2377" + AdvertiseAddr: "192.168.1.1:2377" + DataPathPort: 4789 + DefaultAddrPool: ["10.10.0.0/8", "20.20.0.0/8"] + SubnetSize: 24 + ForceNewCluster: false + Spec: + Orchestration: {} + Raft: {} + Dispatcher: {} + CAConfig: {} + EncryptionConfig: + AutoLockManagers: false + tags: ["Swarm"] + /swarm/join: + post: + summary: "Join an existing swarm" + operationId: "SwarmJoin" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is already part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmJoinRequest" + properties: + ListenAddr: + description: | + Listen address used for inter-manager communication if the node + gets promoted to manager, as well as determining the networking + interface used for the VXLAN Tunnel Endpoint (VTEP). This is + required for joining a swarm. If the port number is omitted, + the default swarm listening port is used. + type: "string" + AdvertiseAddr: + description: | + Externally reachable address advertised to other nodes. This + can either be an address/port combination in the form + `192.168.1.1:4567`, or an interface followed by a port number, + like `eth0:4567`. If the port number is omitted, the port + number from the listen address is used. If `AdvertiseAddr` is + not specified, it will be automatically detected when possible. + type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: + `<ip|interface>`), for example, `192.168.1.1`, or an interface, + like `eth0`. If `DataPathAddr` is unspecified, the same address + as `AdvertiseAddr` is used. + + The `DataPathAddr` specifies the address that global scope + network drivers will publish towards other nodes in order to + reach the containers running on this node. Using this parameter + it is possible to separate the container data traffic from the + management traffic of the cluster. + + type: "string" + RemoteAddrs: + description: | + Addresses of manager nodes already participating in the swarm. + type: "array" + items: + type: "string" + JoinToken: + description: "Secret token for joining this swarm." + type: "string" + required: [ListenAddr, RemoteAddrs, JoinToken] + example: + ListenAddr: "0.0.0.0:2377" + AdvertiseAddr: "192.168.1.1:2377" + DataPathAddr: "192.168.1.1" + RemoteAddrs: + - "node1:2377" + JoinToken: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" + tags: ["Swarm"] + /swarm/leave: + post: + summary: "Leave a swarm" + operationId: "SwarmLeave" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "force" + description: | + Force leave swarm, even if this is the last manager or that it will + break the cluster. + in: "query" + type: "boolean" + default: false + tags: ["Swarm"] + /swarm/update: + post: + summary: "Update a swarm" + operationId: "SwarmUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + $ref: "#/definitions/SwarmSpec" + - name: "version" + in: "query" + description: | + The version number of the swarm object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + - name: "rotateWorkerToken" + in: "query" + description: "Rotate the worker join token." + type: "boolean" + default: false + - name: "rotateManagerToken" + in: "query" + description: "Rotate the manager join token." + type: "boolean" + default: false + - name: "rotateManagerUnlockKey" + in: "query" + description: "Rotate the manager unlock key." + type: "boolean" + default: false + tags: ["Swarm"] + /swarm/unlockkey: + get: + summary: "Get the unlock key" + operationId: "SwarmUnlockkey" + consumes: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "object" + title: "UnlockKeyResponse" + properties: + UnlockKey: + description: "The swarm's unlock key." + type: "string" + example: + UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /swarm/unlock: + post: + summary: "Unlock a locked manager" + operationId: "SwarmUnlock" + consumes: + - "application/json" + produces: + - "application/json" + parameters: + - name: "body" + in: "body" + required: true + schema: + type: "object" + title: "SwarmUnlockRequest" + properties: + UnlockKey: + description: "The swarm's unlock key." + type: "string" + example: + UnlockKey: "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + responses: + "200": + description: "no error" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Swarm"] + /services: + get: + summary: "List services" + operationId: "ServiceList" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Service" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the services list. + + Available filters: + + - `id=<service id>` + - `label=<service label>` + - `mode=["replicated"|"global"]` + - `name=<service name>` + - name: "status" + in: "query" + type: "boolean" + description: | + Include service status, with count of running and desired tasks. + tags: ["Service"] + /services/create: + post: + summary: "Create a service" + operationId: "ServiceCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/ServiceCreateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "403": + description: "network is not eligible for services" + schema: + $ref: "#/definitions/ErrorResponse" + "409": + description: "name conflicts with an existing service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/ServiceSpec" + - type: "object" + example: + Name: "web" + TaskTemplate: + ContainerSpec: + Image: "nginx:alpine" + Mounts: + - + ReadOnly: true + Source: "web-data" + Target: "/usr/share/nginx/html" + Type: "volume" + VolumeOptions: + DriverConfig: {} + Labels: + com.example.something: "something-value" + Hosts: ["10.10.10.10 host1", "ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"] + User: "33" + DNSConfig: + Nameservers: ["8.8.8.8"] + Search: ["example.org"] + Options: ["timeout:3"] + Secrets: + - + File: + Name: "www.example.org.key" + UID: "33" + GID: "33" + Mode: 384 + SecretID: "fpjqlhnwb19zds35k8wn80lq9" + SecretName: "example_org_domain_key" + OomScoreAdj: 0 + LogDriver: + Name: "json-file" + Options: + max-file: "3" + max-size: "10M" + Placement: {} + Resources: + Limits: + MemoryBytes: 104857600 + Reservations: {} + RestartPolicy: + Condition: "on-failure" + Delay: 10000000000 + MaxAttempts: 10 + Mode: + Replicated: + Replicas: 4 + UpdateConfig: + Parallelism: 2 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Ports: + - + Protocol: "tcp" + PublishedPort: 8080 + TargetPort: 80 + Labels: + foo: "bar" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration for pulling from private + registries. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + tags: ["Service"] + /services/{id}: + get: + summary: "Inspect a service" + operationId: "ServiceInspect" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Service" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + - name: "insertDefaults" + in: "query" + description: "Fill empty fields with default values." + type: "boolean" + default: false + tags: ["Service"] + delete: + summary: "Delete a service" + operationId: "ServiceDelete" + responses: + "200": + description: "no error" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + tags: ["Service"] + /services/{id}/update: + post: + summary: "Update a service" + operationId: "ServiceUpdate" + consumes: ["application/json"] + produces: ["application/json"] + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/ServiceUpdateResponse" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID or name of service." + required: true + type: "string" + - name: "body" + in: "body" + required: true + schema: + allOf: + - $ref: "#/definitions/ServiceSpec" + - type: "object" + example: + Name: "top" + TaskTemplate: + ContainerSpec: + Image: "busybox" + Args: + - "top" + OomScoreAdj: 0 + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ForceUpdate: 0 + Mode: + Replicated: + Replicas: 1 + UpdateConfig: + Parallelism: 2 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + RollbackConfig: + Parallelism: 1 + Delay: 1000000000 + FailureAction: "pause" + Monitor: 15000000000 + MaxFailureRatio: 0.15 + EndpointSpec: + Mode: "vip" + + - name: "version" + in: "query" + description: | + The version number of the service object being updated. This is + required to avoid conflicting writes. + This version number should be the value as currently set on the + service *before* the update. You can find the current version by + calling `GET /services/{id}` + required: true + type: "integer" + - name: "registryAuthFrom" + in: "query" + description: | + If the `X-Registry-Auth` header is not specified, this parameter + indicates where to find registry authorization credentials. + type: "string" + enum: ["spec", "previous-spec"] + default: "spec" + - name: "rollback" + in: "query" + description: | + Set to this parameter to `previous` to cause a server-side rollback + to the previous service spec. The supplied spec will be ignored in + this case. + type: "string" + - name: "X-Registry-Auth" + in: "header" + description: | + A base64url-encoded auth configuration for pulling from private + registries. + + Refer to the [authentication section](#section/Authentication) for + details. + type: "string" + + tags: ["Service"] + /services/{id}/logs: + get: + summary: "Get service logs" + description: | + Get `stdout` and `stderr` logs from a service. See also + [`/containers/{id}/logs`](#operation/ContainerLogs). + + **Note**: This endpoint works only for services with the `local`, + `json-file` or `journald` logging drivers. + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + operationId: "ServiceLogs" + responses: + "200": + description: "logs returned as a stream in response body" + schema: + type: "string" + format: "binary" + "404": + description: "no such service" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such service: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID or name of the service" + type: "string" + - name: "details" + in: "query" + description: "Show service context and extra details provided to logs." + type: "boolean" + default: false + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Service"] + /tasks: + get: + summary: "List tasks" + operationId: "TaskList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Task" + example: + - ID: "0kzzo1i0y4jz6027t0k7aezc7" + Version: + Index: 71 + CreatedAt: "2016-06-07T21:07:31.171892745Z" + UpdatedAt: "2016-06-07T21:07:31.376370513Z" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:31.290032978Z" + State: "running" + Message: "started" + ContainerStatus: + ContainerID: "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035" + PID: 677 + DesiredState: "running" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.10/16" + - ID: "1yljwbmlr8er2waf8orvqpwms" + Version: + Index: 30 + CreatedAt: "2016-06-07T21:07:30.019104782Z" + UpdatedAt: "2016-06-07T21:07:30.231958098Z" + Name: "hopeful_cori" + Spec: + ContainerSpec: + Image: "redis" + Resources: + Limits: {} + Reservations: {} + RestartPolicy: + Condition: "any" + MaxAttempts: 0 + Placement: {} + ServiceID: "9mnpnzenvg8p8tdbtq4wvbkcz" + Slot: 1 + NodeID: "60gvrl6tm78dmak4yl7srz94v" + Status: + Timestamp: "2016-06-07T21:07:30.202183143Z" + State: "shutdown" + Message: "shutdown" + ContainerStatus: + ContainerID: "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213" + DesiredState: "shutdown" + NetworksAttachments: + - Network: + ID: "4qvuz4ko70xaltuqbt8956gd1" + Version: + Index: 18 + CreatedAt: "2016-06-07T20:31:11.912919752Z" + UpdatedAt: "2016-06-07T21:07:29.955277358Z" + Spec: + Name: "ingress" + Labels: + com.docker.swarm.internal: "true" + DriverConfiguration: {} + IPAMOptions: + Driver: {} + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + DriverState: + Name: "overlay" + Options: + com.docker.network.driver.overlay.vxlanid_list: "256" + IPAMOptions: + Driver: + Name: "default" + Configs: + - Subnet: "10.255.0.0/16" + Gateway: "10.255.0.1" + Addresses: + - "10.255.0.5/16" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the tasks list. + + Available filters: + + - `desired-state=(running | shutdown | accepted)` + - `id=<task id>` + - `label=key` or `label="key=value"` + - `name=<task name>` + - `node=<node id or name>` + - `service=<service name>` + tags: ["Task"] + /tasks/{id}: + get: + summary: "Inspect a task" + operationId: "TaskInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Task" + "404": + description: "no such task" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "ID of the task" + required: true + type: "string" + tags: ["Task"] + /tasks/{id}/logs: + get: + summary: "Get task logs" + description: | + Get `stdout` and `stderr` logs from a task. + See also [`/containers/{id}/logs`](#operation/ContainerLogs). + + **Note**: This endpoint works only for services with the `local`, + `json-file` or `journald` logging drivers. + operationId: "TaskLogs" + produces: + - "application/vnd.docker.raw-stream" + - "application/vnd.docker.multiplexed-stream" + responses: + "200": + description: "logs returned as a stream in response body" + schema: + type: "string" + format: "binary" + "404": + description: "no such task" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such task: c2ada9df5af8" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + description: "ID of the task" + type: "string" + - name: "details" + in: "query" + description: "Show task context and extra details provided to logs." + type: "boolean" + default: false + - name: "follow" + in: "query" + description: "Keep connection after returning logs." + type: "boolean" + default: false + - name: "stdout" + in: "query" + description: "Return logs from `stdout`" + type: "boolean" + default: false + - name: "stderr" + in: "query" + description: "Return logs from `stderr`" + type: "boolean" + default: false + - name: "since" + in: "query" + description: "Only return logs since this time, as a UNIX timestamp" + type: "integer" + default: 0 + - name: "timestamps" + in: "query" + description: "Add timestamps to every log line" + type: "boolean" + default: false + - name: "tail" + in: "query" + description: | + Only return this number of log lines from the end of the logs. + Specify as an integer or `all` to output all log lines. + type: "string" + default: "all" + tags: ["Task"] + /secrets: + get: + summary: "List secrets" + operationId: "SecretList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Secret" + example: + - ID: "blt1owaxmitz71s9v5zh81zun" + Version: + Index: 85 + CreatedAt: "2017-07-20T13:55:28.678958722Z" + UpdatedAt: "2017-07-20T13:55:28.678958722Z" + Spec: + Name: "mysql-passwd" + Labels: + some.label: "some.value" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + - ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + Labels: + foo: "bar" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the secrets list. + + Available filters: + + - `id=<secret id>` + - `label=<key> or label=<key>=value` + - `name=<secret name>` matches all or part of a secret name (prefix match) + - `names=<secret name>` matches a secret name (exact match) + tags: ["Secret"] + /secrets/create: + post: + summary: "Create a secret" + operationId: "SecretCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "409": + description: "name conflicts with an existing object" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + schema: + allOf: + - $ref: "#/definitions/SecretSpec" + - type: "object" + example: + Name: "app-key.crt" + Labels: + foo: "bar" + Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + tags: ["Secret"] + /secrets/{id}: + get: + summary: "Inspect a secret" + operationId: "SecretInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Secret" + examples: + application/json: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + Labels: + foo: "bar" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + + "404": + description: "secret not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the secret" + tags: ["Secret"] + delete: + summary: "Delete a secret" + operationId: "SecretDelete" + produces: + - "application/json" + responses: + "204": + description: "no error" + "404": + description: "secret not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the secret" + tags: ["Secret"] + /secrets/{id}/update: + post: + summary: "Update a Secret" + operationId: "SecretUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such secret" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the secret" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/SecretSpec" + description: | + The spec of the secret to update. Currently, only the Labels field + can be updated. All other fields must remain unchanged from the + [SecretInspect endpoint](#operation/SecretInspect) response values. + - name: "version" + in: "query" + description: | + The version number of the secret object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Secret"] + /configs: + get: + summary: "List configs" + operationId: "ConfigList" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Config" + example: + - ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "server.conf" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to + process on the configs list. + + Available filters: + + - `id=<config id>` + - `label=<key> or label=<key>=value` + - `name=<config name>` matches all or part of a config name (prefix match) + tags: ["Config"] + /configs/create: + post: + summary: "Create a config" + operationId: "ConfigCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + "201": + description: "no error" + schema: + $ref: "#/definitions/IDResponse" + "409": + description: "name conflicts with an existing object" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + schema: + allOf: + - $ref: "#/definitions/ConfigSpec" + - type: "object" + example: + Name: "server.conf" + Labels: + foo: "bar" + Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + tags: ["Config"] + /configs/{id}: + get: + summary: "Inspect a config" + operationId: "ConfigInspect" + produces: + - "application/json" + responses: + "200": + description: "no error" + schema: + $ref: "#/definitions/Config" + examples: + application/json: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + "404": + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + delete: + summary: "Delete a config" + operationId: "ConfigDelete" + produces: + - "application/json" + responses: + "204": + description: "no error" + "404": + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + /configs/{id}/update: + post: + summary: "Update a Config" + operationId: "ConfigUpdate" + responses: + "200": + description: "no error" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "404": + description: "no such config" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + "503": + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the config" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/ConfigSpec" + description: | + The spec of the config to update. Currently, only the Labels field + can be updated. All other fields must remain unchanged from the + [ConfigInspect endpoint](#operation/ConfigInspect) response values. + - name: "version" + in: "query" + description: | + The version number of the config object being updated. This is + required to avoid conflicting writes. + type: "integer" + format: "int64" + required: true + tags: ["Config"] + /distribution/{name}/json: + get: + summary: "Get image information from the registry" + description: | + Return image digest and platform information by contacting the registry. + operationId: "DistributionInspect" + produces: + - "application/json" + responses: + "200": + description: "descriptor and platform information" + schema: + $ref: "#/definitions/DistributionInspect" + "401": + description: "Failed authentication or no image found" + schema: + $ref: "#/definitions/ErrorResponse" + examples: + application/json: + message: "No such image: someimage (tag: latest)" + "500": + description: "Server error" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "name" + in: "path" + description: "Image name or id" + type: "string" + required: true + tags: ["Distribution"] + /session: + post: + summary: "Initialize interactive session" + description: | + Start a new interactive session with a server. Session allows server to + call back to the client for advanced capabilities. + + > **Deprecated**: This endpoint is deprecated and will be removed in a future version. + > Server should support gRPC directly on the listening socket. + + ### Hijacking + + This endpoint hijacks the HTTP connection to HTTP2 transport that allows + the client to expose gPRC services on that connection. + + For example, the client sends this request to upgrade the connection: + + ``` + POST /session HTTP/1.1 + Upgrade: h2c + Connection: Upgrade + ``` + + The Docker daemon responds with a `101 UPGRADED` response follow with + the raw stream: + + ``` + HTTP/1.1 101 UPGRADED + Connection: Upgrade + Upgrade: h2c + ``` + operationId: "Session" + produces: + - "application/vnd.docker.raw-stream" + responses: + "101": + description: "no error, hijacking successful" + "400": + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + "500": + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + tags: ["Session"] diff --git a/_vendor/modules.txt b/_vendor/modules.txt index c2756a8164d9..c51cc710d33f 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1,6 +1,7 @@ -# github.com/moby/moby/api v1.54.2 -# github.com/moby/buildkit v0.30.0 -# github.com/docker/buildx v0.34.1 -# github.com/docker/cli v29.5.1+incompatible -# github.com/docker/compose/v5 v5.1.4 +# github.com/moby/moby/api v1.56.1 +# github.com/moby/buildkit v0.34.0 +# github.com/docker/buildx v0.38.1 +# github.com/docker/cli v29.8.2+incompatible +# github.com/docker/compose/v5 v5.6.1 # github.com/docker/model-runner v1.1.36 +# github.com/docker/docker-agent v1.126.0 diff --git a/assets/api-reference/reference.css b/assets/api-reference/reference.css new file mode 100644 index 000000000000..862feee37c89 --- /dev/null +++ b/assets/api-reference/reference.css @@ -0,0 +1,596 @@ +/* Scoped reference tokens inherit Docker's palette and installed typefaces. */ +.api-reference, +.api-nav { + --api-text: var(--color-gray-800, #2c333f); + --api-muted: var(--color-gray-600, #566581); + --api-line: var(--color-gray-100, #e7eaef); + --api-surface: var(--color-background-light, #f9f9fa); + --api-paper: #fff; + --api-link: var(--color-blue-600, #0d4df2); + --api-selected: var(--color-blue-50, #f6f8fe); + --api-mono: "Roboto Mono", ui-monospace, monospace; + color: var(--api-text); +} +.dark .api-reference, +.dark .api-nav { + --api-text: var(--color-gray-100, #e7eaef); + --api-muted: var(--color-gray-300, #a9b4c6); + --api-line: var(--color-gray-800, #2c333f); + --api-surface: var(--color-gray-900, #1e2129); + --api-paper: var(--color-background-dark, #10151b); + --api-link: var(--color-blue-300, #7ba4f4); + --api-selected: #17243b; + color-scheme: dark; +} +.api-reference { + max-width: 1440px; + margin: auto; + font-size: 15px; + line-height: 1.7; + overflow-wrap: anywhere; +} +.api-reference h1 { + font-size: 32px; + font-weight: 550; + letter-spacing: -0.025em; + line-height: 1.25; + margin: 28px 0 20px; + text-wrap: balance; +} +.api-reference h2 { + font-size: 20px; + font-weight: 550; + letter-spacing: -0.015em; + line-height: 1.4; + margin: 36px 0 14px; +} +.api-reference h3, +.api-reference h4 { + font-size: 15px; + font-weight: 550; + line-height: 1.5; + margin: 20px 0 8px; +} +.api-reference p { + margin: 10px 0; + max-width: 72ch; +} +.api-reference .prose { + color: var(--api-text); + font-size: inherit; + line-height: inherit; + max-width: 72ch; +} +.api-reference .prose > :first-child { + margin-top: 0; +} +.api-reference .prose > :last-child { + margin-bottom: 0; +} +.api-reference .prose li > p { + margin: 6px 0; +} +.api-reference .prose :is(h1, h2, h3, h4, h5, h6) > a { + color: inherit; + text-decoration: none; +} +.api-reference .prose :is(h1, h2, h3, h4, h5, h6) > a:hover { + text-decoration: underline; +} +.api-overview { + max-width: 72ch; + margin: 32px 0; +} +.api-reference .api-overview .prose :is(h3, h4) { + font-size: 17px; + font-weight: 550; + line-height: 1.4; + margin: 28px 0 12px; +} +.api-reference a, +.api-nav a { + color: var(--api-link); + text-underline-offset: 3px; +} +.api-reference a:hover { + text-decoration: underline; +} +.api-reference :is(a, button, input, select, summary):focus-visible, +.api-nav a:focus-visible { + outline: 2px solid var(--api-link); + outline-offset: 4px; + border-radius: 3px; +} +.api-reference code { + font-family: var(--api-mono); + font-size: 13px; + font-weight: 400; + overflow-wrap: anywhere; +} +.api-reference .prose code::before, +.api-reference .prose code::after { + content: none; +} +.api-reference pre { + background: var(--api-surface); + color: var(--api-text); + border: 1px solid var(--api-line); + padding: 18px 20px; + border-radius: 6px; + overflow: auto; + font-family: var(--api-mono); + font-size: 13px; + line-height: 1.75; + max-height: 34rem; + margin: 14px 0; + tab-size: 2; +} +.api-reference pre code { + font: inherit; + padding: 0; + background: none; + color: inherit; +} +.api-reference summary { + cursor: pointer; + padding: 6px 0; + font-size: 13px; + color: var(--api-muted); +} +.api-reference summary::marker { + color: var(--api-muted); + font-size: 10px; +} +.api-reference summary:hover { + color: var(--api-link); +} +.api-eyebrow, +.api-label { + font-size: 13px; + font-weight: 500; + color: var(--api-muted); +} +.api-reference .api-eyebrow { + margin-top: 28px; + margin-bottom: -16px; +} +.api-lead { + font-size: 17px; + color: var(--api-muted); +} +.api-cards { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 16px; + margin: 32px 0; +} +.api-card { + display: block; + border: 1px solid var(--api-line); + border-radius: 10px; + padding: 26px; +} +.api-card:hover { + background: var(--api-selected); + border-color: var(--api-link); + text-decoration: none !important; +} +.api-card h2 { + margin: 12px 0; + color: var(--api-text); +} +.api-card p { + color: var(--api-muted); +} +.api-card > span:last-child { + display: inline-block; + margin-top: 10px; + font-size: 14px; +} +.api-crumbs { + display: flex; + flex-wrap: wrap; + gap: 8px; + align-items: center; + color: var(--api-muted); + font-size: 13px; + margin-bottom: 12px; +} +.api-crumbs a { + color: var(--api-muted); +} +.api-tools { + display: flex; + flex-wrap: wrap; + gap: 12px 24px; + align-items: center; + font-size: 13px; + padding-bottom: 20px; + border-bottom: 1px solid var(--api-line); +} +.api-tools > label { + margin-right: auto; +} +.api-reference label { + font-size: 13px; + color: var(--api-muted); +} +.api-reference select, +.api-reference input { + border: 1px solid var(--api-line); + border-radius: 6px; + background: var(--api-paper); + padding: 8px 10px; + color: var(--api-text); + font: inherit; + font-size: 14px; + max-width: 100%; +} +.api-reference select { + margin-left: 8px; +} +.api-reference input::placeholder { + color: var(--api-muted); +} +.api-connection { + max-width: 72ch; + margin: 32px 0; +} +.api-filter-label { + display: block; + margin: 16px 0 24px; +} +.api-filter-label input { + display: block; + width: 100%; + max-width: 36rem; + margin: 8px 0; +} +.api-operation-row { + display: grid; + grid-template-columns: 64px minmax(0, 1.2fr) minmax(0, 1fr); + align-items: start; + gap: 16px; + padding: 16px 8px; + border-bottom: 1px solid var(--api-line); + font-size: 14px; +} +.api-operation-row > span:last-child { + color: var(--api-muted); +} +.api-operation-row:hover { + background: var(--api-selected); + text-decoration: none !important; +} +.api-method { + display: inline-block; + font-size: 11px; + font-weight: 650; + background: var(--api-selected); + color: var(--api-link); + border-radius: 4px; + padding: 4px 8px; + line-height: 1.5; + white-space: nowrap; + width: fit-content; + flex-shrink: 0; +} +.api-method[data-method="POST"] { + background: #ebf9ee; + color: #216e4b; +} +.api-method[data-method="DELETE"] { + background: #fff0ef; + color: #ad3039; +} +.api-method[data-method="PATCH"], +.api-method[data-method="PUT"] { + background: #fff5e0; + color: #865514; +} +.dark .api-method[data-method="POST"] { + background: #173728; + color: #a9e5bd; +} +.dark .api-method[data-method="DELETE"] { + background: #3d2229; + color: #f5b6b6; +} +.dark .api-method[data-method="PATCH"], +.dark .api-method[data-method="PUT"] { + background: #392e1c; + color: #edcd96; +} +.api-signature { + display: flex; + align-items: baseline; + gap: 14px; + background: var(--api-surface); + border: 1px solid var(--api-line); + border-radius: 6px; + padding: 14px 18px; + margin: 0 0 28px; +} +.api-signature code { + font-size: 14px; +} +.api-operation-grid { + display: grid; + grid-template-columns: minmax(0, 1.35fr) minmax(0, 1fr); + gap: 40px; + align-items: start; +} +.api-reading { + min-width: 0; +} +.api-description { + margin-bottom: 32px; +} +.api-description:empty { + display: none; +} +.api-request { + position: sticky; + top: 88px; + max-height: calc(100dvh - 112px); + overflow: auto; + min-width: 0; + border: 1px solid var(--api-line); + border-radius: 8px; + padding: 20px; + background: var(--api-surface); + font-size: 13px; + line-height: 1.65; +} +.api-request-heading { + display: flex; + align-items: center; + justify-content: space-between; + gap: 16px; +} +.api-request-heading h2 { + margin: 0; + font-size: 15px; + letter-spacing: 0; +} +.api-request-heading > span { + color: var(--api-muted); + font-size: 12px; +} +.api-request > p { + color: var(--api-muted); + margin: 12px 0; +} +.api-request pre { + background: var(--api-paper); + padding: 16px; + white-space: pre-wrap; + overflow-wrap: anywhere; +} +.api-request pre code { + word-break: break-all; +} +.api-request button { + border: 1px solid var(--api-line); + background: var(--api-paper); + color: var(--api-text); + padding: 7px 12px; + border-radius: 5px; + font-size: 13px; + font-weight: 500; + cursor: pointer; +} +.api-request button:hover { + border-color: var(--api-link); + color: var(--api-link); +} +.api-source-details { + border-top: 1px solid var(--api-line); + margin-top: 16px; + padding-top: 8px; +} +.api-field { + border-top: 1px solid var(--api-line); + padding: 16px 0; + margin: 0; +} +.api-field h3 { + display: flex; + flex-wrap: wrap; + gap: 10px; + align-items: baseline; + margin: 0 0 10px; +} +.api-field h3 code, +.api-field > summary code { + color: var(--api-text); + font-weight: 500; +} +.api-field small { + font-size: 12px; + font-weight: 400; + color: var(--api-muted); +} +.api-field .api-required { + color: var(--api-text); + font-size: 12px; +} +.api-field .api-field { + border-top: 0; + border-left: 1px solid var(--api-line); + margin: 12px 0 0 4px; + padding: 0 0 0 16px; +} +.api-type, +.api-ref, +.api-constraints { + font-size: 13px; + color: var(--api-muted); +} +.api-variant { + border-top: 1px solid var(--api-line); + margin-top: 24px; + padding-top: 20px; +} +.api-variant > h3 { + display: flex; + gap: 10px; + align-items: baseline; + margin-top: 0; +} +.api-status { + border: 1px solid var(--api-line); + padding: 1px 6px; + border-radius: 4px; +} +.api-media { + color: var(--api-muted); +} +.api-schema-links { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(min(100%, 15rem), 1fr)); + gap: 0 28px; + margin: 0; + padding: 0; + list-style: none; +} +.api-schema-links li { + min-width: 0; + border-bottom: 1px solid var(--api-line); +} +.api-schema-links a { + display: flex; + align-items: center; + height: 100%; + min-height: 44px; + padding: 10px 8px; +} +.api-schema-links a:hover { + background: var(--api-selected); +} +.api-nav { + padding: 20px 8px; + font-size: 14px; + line-height: 1.5; +} +.api-nav a { + display: block; + padding: 7px 10px; + margin: 2px 0; + color: var(--api-muted); +} +.api-nav a:hover { + color: var(--api-link); + background: var(--api-selected); +} +.api-nav a[aria-current="page"] { + background: var(--api-selected); + color: var(--api-link); + font-weight: 500; + box-shadow: inset 2px 0 var(--api-link); +} +.api-nav h2 { + font-size: 16px; + font-weight: 550; + margin: 24px 10px 4px; +} +.api-nav .api-nav-version { + color: var(--api-muted); + font-size: 13px; + margin: 0 10px 16px; +} +.api-nav h3 { + font-size: 13px; + font-weight: 550; + margin: 26px 10px 8px; +} +.api-nav .api-nav-operation { + display: grid; + grid-template-columns: 42px minmax(0, 1fr); + gap: 8px; + align-items: baseline; +} +.api-nav small { + font-size: 11px; + font-weight: 600; + color: var(--api-link); +} +.api-nav small[data-method="POST"] { + color: #216e4b; +} +.api-nav small[data-method="DELETE"] { + color: #ad3039; +} +.api-nav small[data-method="PATCH"], +.api-nav small[data-method="PUT"] { + color: #865514; +} +.dark .api-nav small[data-method="POST"] { + color: #a9e5bd; +} +.dark .api-nav small[data-method="DELETE"] { + color: #f5b6b6; +} +.dark .api-nav small[data-method="PATCH"], +.dark .api-nav small[data-method="PUT"] { + color: #edcd96; +} +.api-nav .api-nav-back { + font-size: 13px; + color: var(--api-link); +} +.api-reference [hidden] { + display: none !important; +} +.api-reference[data-api-view="schema"] > .prose { + margin-bottom: 24px; +} +.api-reference[data-api-view="schema"] > .api-field { + max-width: 80ch; +} +@media (max-width: 1199px) { + .api-operation-grid { + grid-template-columns: 1fr; + gap: 28px; + } + .api-request { + position: static; + max-height: none; + overflow: visible; + grid-row: 1; + } +} +@media (max-width: 767px) { + main > div:has(> .api-reference) { + padding: 24px 20px; + } + .api-cards { + grid-template-columns: 1fr; + } + .api-reference h1 { + font-size: 28px; + } + .api-operation-row { + grid-template-columns: 56px minmax(0, 1fr); + gap: 6px 12px; + } + .api-operation-row > span:last-child { + grid-column: 2; + } + .api-tools { + gap: 14px 20px; + } + .api-tools > label { + flex-basis: 100%; + } + .api-signature { + padding: 12px; + gap: 10px; + } + .api-signature code { + font-size: 13px; + } + .api-request { + padding: 16px; + } +} diff --git a/assets/api-reference/reference.js b/assets/api-reference/reference.js new file mode 100644 index 000000000000..7c51e1843235 --- /dev/null +++ b/assets/api-reference/reference.js @@ -0,0 +1,49 @@ +document.querySelectorAll("[data-api-version]").forEach((select) => + select.addEventListener("change", () => { + location.href = select.value; + }), +); +document.querySelectorAll("[data-api-filter]").forEach((input) => + input.addEventListener("input", () => { + const term = input.value.toLocaleLowerCase(); + document.querySelectorAll("[data-api-filter-item]").forEach((row) => { + row.hidden = !row.textContent.toLocaleLowerCase().includes(term); + }); + }), +); +document.querySelectorAll("[data-api-copy]").forEach((button) => + button.addEventListener("click", async () => { + try { + await navigator.clipboard.writeText( + button.parentElement.querySelector("[data-api-copy-source]") + .textContent, + ); + button.textContent = "Copied"; + } catch { + button.textContent = "Select and copy the request"; + } + }), +); +document.querySelectorAll("[data-api-example-select]").forEach((select) => { + const update = () => + select + .closest("[data-api-examples]") + .querySelectorAll("[data-api-example]") + .forEach((example) => { + example.hidden = example.dataset.apiExample !== select.value; + }); + select.addEventListener("change", update); + update(); +}); + +document.querySelectorAll("[data-api-media-select]").forEach((select) => + select.addEventListener("change", () => { + document.querySelectorAll("[data-api-media]").forEach((variant) => { + variant.hidden = Boolean( + select.value && + variant.dataset.apiMedia && + select.value !== variant.dataset.apiMedia, + ); + }); + }), +); diff --git a/assets/css/components.css b/assets/css/components.css index a0f711f2dd8d..0e5969eec87d 100644 --- a/assets/css/components.css +++ b/assets/css/components.css @@ -127,4 +127,14 @@ @apply inline-block rounded-t-sm px-3 py-2 hover:bg-gray-100 dark:hover:bg-gray-900; @apply dark:text-gray-200; } -} \ No newline at end of file +} + +/* Mermaid blocks hold the diagram source until mermaid.js replaces it with + an SVG. Hide the source while that happens, unless rendering failed. + + Kept outside @layer components on purpose: the element also carries the + `flex` utility, and Tailwind's utilities layer outranks components + regardless of selector specificity. An unlayered rule wins over both. */ +pre.mermaid:not(:has(svg)):not([data-error]) { + display: none; +} diff --git a/assets/css/interactive-diagram.css b/assets/css/interactive-diagram.css new file mode 100644 index 000000000000..8bf11f0ef872 --- /dev/null +++ b/assets/css/interactive-diagram.css @@ -0,0 +1,561 @@ +.interactive-diagram { + --diagram-accent: var(--color-blue-500); + --diagram-accent-soft: var(--color-blue-50); + --diagram-border: var(--color-gray-200); + --diagram-structure: var(--color-gray-500); + --diagram-ink: var(--color-gray-900); + --diagram-muted: var(--color-gray-600); + --diagram-shared: var(--color-green-600); + --diagram-brokered: var(--color-violet-600); + --diagram-token-bg: var(--color-gray-900); + --diagram-token-fg: white; + overflow: hidden; + border: 1px solid var(--diagram-border); + border-radius: 0.5rem; + background: white; + color: var(--diagram-ink); +} + +.dark .interactive-diagram { + --diagram-accent: var(--color-blue-300); + --diagram-accent-soft: var(--color-blue-950); + --diagram-border: var(--color-gray-700); + --diagram-structure: var(--color-gray-600); + --diagram-ink: var(--color-gray-100); + --diagram-muted: var(--color-gray-400); + --diagram-shared: var(--color-green-400); + --diagram-brokered: var(--color-violet-300); + --diagram-token-bg: var(--color-blue-300); + --diagram-token-fg: var(--color-gray-950); + background: var(--color-gray-950); +} + +.interactive-diagram__header { + display: grid; + grid-template-columns: minmax(0, 1fr) auto; + align-items: start; + gap: 1rem; + padding: 1.25rem 1.5rem 1rem; + border-bottom: 1px solid var(--diagram-border); +} + +.interactive-diagram__header-copy { + min-width: 0; +} + +.interactive-diagram--topology .interactive-diagram__header { + grid-template-columns: minmax(0, 1fr); +} + +.interactive-diagram__title, +.interactive-diagram__description, +.interactive-diagram__step-title, +.interactive-diagram__step-body, +.interactive-diagram__state { + margin: 0; +} + +.interactive-diagram__title { + color: var(--diagram-ink); + font-size: 1rem; + font-weight: 650; +} + +.interactive-diagram__description { + margin-top: 0.25rem; + color: var(--diagram-muted); + font-size: 0.875rem; + line-height: 1.45; +} + +.interactive-diagram__stage { + overflow-x: auto; + background-color: var(--diagram-accent-soft); + background-image: + linear-gradient( + to right, + color-mix(in srgb, var(--diagram-border) 28%, transparent) 1px, + transparent 1px + ), + linear-gradient( + to bottom, + color-mix(in srgb, var(--diagram-border) 28%, transparent) 1px, + transparent 1px + ); + background-size: 24px 24px; +} + +.interactive-diagram__svg { + display: block; + width: 100%; + min-width: 680px; + height: auto; + font-family: "Roboto Flex", sans-serif; +} + +.interactive-diagram__boundary rect { + fill: color-mix(in srgb, white 72%, transparent); + stroke: var(--diagram-structure); + stroke-width: 1.5; + stroke-dasharray: 5 5; +} + +.dark .interactive-diagram__boundary rect { + fill: color-mix(in srgb, var(--color-gray-900) 82%, transparent); +} + +.interactive-diagram__boundary--sandbox rect { + stroke: color-mix(in srgb, var(--diagram-accent) 65%, var(--diagram-border)); + stroke-width: 2; +} + +.interactive-diagram__boundary-label { + fill: var(--diagram-muted); + font-family: "Roboto Mono", monospace; + font-size: 12px; + font-weight: 600; + letter-spacing: 0.045em; + text-transform: uppercase; +} + +.interactive-diagram__edge { + stroke: var(--diagram-structure); + stroke-width: 2; + stroke-dasharray: 5 7; + opacity: 0.5; + transition: + opacity 180ms ease, + stroke 180ms ease, + stroke-width 180ms ease; +} + +.interactive-diagram__svg marker path { + fill: context-stroke; +} + +.interactive-diagram__edge.is-active { + stroke: var(--diagram-accent); + stroke-width: 3; + stroke-dasharray: none; + opacity: 1; +} + +.interactive-diagram__edge--interactive { + cursor: pointer; + opacity: 0.82; +} + +.interactive-diagram__edge--shared { + stroke: var(--diagram-shared); +} + +.interactive-diagram__edge--brokered { + stroke: var(--diagram-brokered); +} + +.interactive-diagram__edge-hit { + stroke: transparent; + stroke-width: 22; + stroke-dasharray: none; + pointer-events: stroke; +} + +.interactive-diagram__edge-label rect { + fill: white; + stroke: var(--diagram-border); + stroke-width: 1; + stroke-dasharray: none; +} + +.dark .interactive-diagram__edge-label rect { + fill: var(--color-gray-900); +} + +.interactive-diagram__edge-label-text { + fill: var(--diagram-ink); + stroke: none; + font-family: "Roboto Mono", monospace; + font-size: 10.5px; + font-weight: 600; + text-anchor: middle; +} + +.interactive-diagram__edge--interactive.is-active + .interactive-diagram__edge-label + rect { + stroke: var(--diagram-accent); + stroke-width: 2; +} + +.interactive-diagram__edge--interactive:focus-visible { + outline: none; +} + +.interactive-diagram__edge--interactive:focus-visible + .interactive-diagram__edge-label + rect { + stroke: var(--color-blue-focusvisible); + stroke-width: 3; +} + +.interactive-diagram__node rect { + fill: white; + stroke: var(--diagram-structure); + stroke-width: 1.5; + transition: + fill 180ms ease, + stroke 180ms ease, + stroke-width 180ms ease; +} + +.interactive-diagram--topology .interactive-diagram__node { + cursor: pointer; + transition: opacity 180ms ease; +} + +.interactive-diagram--topology .interactive-diagram__node:focus-visible { + outline: none; +} + +.interactive-diagram--topology .interactive-diagram__node:focus-visible rect { + stroke: var(--color-blue-focusvisible); + stroke-width: 3; +} + +.dark .interactive-diagram__node rect { + fill: var(--color-gray-900); +} + +.interactive-diagram__node--context { + color: var(--diagram-muted); +} + +.interactive-diagram__node--context rect { + fill: var(--color-gray-50); + stroke-dasharray: 3 3; +} + +.dark .interactive-diagram__node--context rect { + fill: var(--color-gray-900); +} + +.interactive-diagram__node--context .interactive-diagram__node-label { + fill: var(--diagram-muted); +} + +.interactive-diagram__node--secret rect { + fill: var(--color-green-50); + stroke: var(--color-green-400); +} + +.interactive-diagram__node--shared rect { + fill: var(--color-green-50); + stroke: var(--diagram-shared); +} + +.dark .interactive-diagram__node--shared rect { + fill: var(--color-green-950); +} + +.interactive-diagram__node--restricted rect { + fill: var(--color-gray-50); + stroke-dasharray: 3 3; +} + +.dark .interactive-diagram__node--restricted rect { + fill: var(--color-gray-900); +} + +.dark .interactive-diagram__node--secret rect { + fill: var(--color-green-950); + stroke: var(--color-green-700); +} + +.interactive-diagram__node.is-active rect { + fill: var(--diagram-accent-soft); + stroke: var(--diagram-accent); + stroke-width: 3; +} + +.interactive-diagram__node.is-related rect { + stroke: var(--diagram-accent); + stroke-width: 2; +} + +.interactive-diagram--topology.has-topology-focus + .interactive-diagram__node:not(.is-active, .is-related), +.interactive-diagram--topology.has-topology-focus + .interactive-diagram__edge:not(.is-active) { + opacity: 0.22; +} + +.interactive-diagram__node-label { + fill: var(--diagram-ink); + font-size: 14px; + font-weight: 650; +} + +.interactive-diagram__node-description { + fill: var(--diagram-muted); + font-size: 11px; +} + +.interactive-diagram__token rect { + fill: var(--diagram-token-bg); + stroke: var(--diagram-token-fg); + stroke-width: 2; + filter: drop-shadow(0 2px 3px rgb(18 21 31 / 0.18)); +} + +.interactive-diagram__token-label { + fill: var(--diagram-token-fg); + font-family: "Roboto Mono", monospace; + font-size: 11px; + font-weight: 600; + text-anchor: middle; +} + +.interactive-diagram__status { + min-height: 7.5rem; + padding: 1rem 1.5rem; + border-top: 1px solid var(--diagram-border); + border-bottom: 1px solid var(--diagram-border); + background: white; +} + +.dark .interactive-diagram__status { + background: var(--color-gray-950); +} + +.interactive-diagram__step-copy { + display: grid; + grid-template-columns: 3.5rem 1fr; + gap: 0.75rem; +} + +.interactive-diagram__step-number { + color: var(--diagram-accent); + font-family: "Roboto Mono", monospace; + font-size: 0.75rem; + font-weight: 600; + letter-spacing: 0.04em; +} + +.interactive-diagram__step-title { + color: var(--diagram-ink); + font-size: 0.95rem; + font-weight: 650; +} + +.interactive-diagram__step-body { + margin-top: 0.25rem; + color: var(--diagram-muted); + font-size: 0.85rem; + line-height: 1.45; +} + +.interactive-diagram__state { + margin-top: 0.75rem; + margin-left: 4.25rem; + padding-left: 0.65rem; + border-left: 2px solid var(--diagram-accent); + color: var(--diagram-ink); + font-size: 0.78rem; + line-height: 1.45; +} + +.interactive-diagram__topology-detail { + display: grid; + min-height: 7rem; + grid-template-columns: 8.5rem minmax(0, 1fr); + gap: 1rem; + padding: 1rem 1.5rem 1.15rem; + border-top: 1px solid var(--diagram-border); + background: white; +} + +.dark .interactive-diagram__topology-detail { + background: var(--color-gray-950); +} + +.interactive-diagram__topology-category, +.interactive-diagram__topology-title, +.interactive-diagram__topology-body { + margin: 0; +} + +.interactive-diagram__topology-category { + padding-top: 0.15rem; + color: var(--diagram-accent); + font-family: "Roboto Mono", monospace; + font-size: 0.7rem; + font-weight: 650; + letter-spacing: 0.045em; + text-transform: uppercase; +} + +.interactive-diagram__topology-title { + color: var(--diagram-ink); + font-size: 0.95rem; + font-weight: 650; +} + +.interactive-diagram__topology-body { + margin-top: 0.3rem; + color: var(--diagram-muted); + font-size: 0.85rem; + line-height: 1.5; +} + +.interactive-diagram__controls { + display: grid; + grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); + align-items: center; + gap: 0.75rem; + padding: 0.8rem 1rem; +} + +.interactive-diagram__controls > .interactive-diagram__button:first-child { + justify-self: end; +} + +.interactive-diagram__controls > .interactive-diagram__button:last-child { + justify-self: start; +} + +.interactive-diagram__button { + min-height: 2.25rem; + padding: 0.4rem 0.7rem; + border: 1px solid var(--diagram-structure); + border-radius: 0.25rem; + background: transparent; + color: var(--diagram-ink); + font-size: 0.78rem; + font-weight: 600; +} + +.interactive-diagram__button:hover:not(:disabled) { + border-color: var(--diagram-accent); + background: var(--diagram-accent-soft); +} + +.interactive-diagram__button:focus-visible, +.interactive-diagram__progress-step:focus-visible { + outline: 3px solid var(--color-blue-focusvisible); + outline-offset: 2px; +} + +.interactive-diagram__button:disabled { + cursor: not-allowed; + opacity: 0.45; +} + +.interactive-diagram__progress { + display: flex; + min-width: 0; + justify-content: center; + gap: 0.45rem; +} + +.interactive-diagram__progress-step { + position: relative; + width: 1.75rem; + height: 1.75rem; + padding: 0; + border: 0; + background: transparent; +} + +.interactive-diagram__progress-step::before { + position: absolute; + top: 50%; + left: 50%; + width: 0.6rem; + height: 0.6rem; + border: 1px solid var(--diagram-structure); + border-radius: 50%; + background: transparent; + content: ""; + transform: translate(-50%, -50%); +} + +.interactive-diagram__progress-step.is-active::before { + border-color: var(--diagram-accent); + background: var(--diagram-accent); + box-shadow: 0 0 0 3px var(--color-blue-focus); +} + +.interactive-diagram__fallback { + padding: 1rem 1.5rem; +} + +.interactive-diagram.is-enhanced .interactive-diagram__fallback { + display: none; +} + +.interactive-diagram:not(.is-enhanced) .interactive-diagram__stage, +.interactive-diagram:not(.is-enhanced) .interactive-diagram__status, +.interactive-diagram:not(.is-enhanced) .interactive-diagram__topology-detail, +.interactive-diagram:not(.is-enhanced) .interactive-diagram__controls { + display: none; +} + +@media (prefers-reduced-motion: no-preference) { + .interactive-diagram__token.is-entering { + animation: interactive-diagram-token 280ms ease-out; + } + + @keyframes interactive-diagram-token { + from { + opacity: 0; + } + } +} + +@media (prefers-reduced-motion: reduce) { + .interactive-diagram__edge, + .interactive-diagram__node, + .interactive-diagram__node rect { + transition: none; + } +} + +@media (max-width: 640px) { + .interactive-diagram__header, + .interactive-diagram__status, + .interactive-diagram__topology-detail { + padding-inline: 1rem; + } + + .interactive-diagram__step-copy { + grid-template-columns: 1fr; + gap: 0.35rem; + } + + .interactive-diagram__topology-detail { + min-height: 8.5rem; + grid-template-columns: 1fr; + gap: 0.35rem; + } + + .interactive-diagram__state { + margin-left: 0; + } + + .interactive-diagram__controls { + gap: 0.25rem; + padding-inline: 0.75rem; + } + + .interactive-diagram__progress { + gap: 0.05rem; + } + + .interactive-diagram__progress-step { + width: 1.5rem; + } + + .interactive-diagram__button { + padding-inline: 0.55rem; + } +} diff --git a/assets/css/style.css b/assets/css/style.css index f63fc6f5aec2..d1a2620a8fef 100644 --- a/assets/css/style.css +++ b/assets/css/style.css @@ -42,6 +42,7 @@ @import "syntax-dark.css"; @import "syntax-light.css"; @import "components.css"; +@import "interactive-diagram.css"; @import "highlight-github-dark.css"; @variant dark (&:where(.dark, .dark *)); diff --git a/assets/css/utilities.css b/assets/css/utilities.css index b735fcef2049..819af1bf9880 100644 --- a/assets/css/utilities.css +++ b/assets/css/utilities.css @@ -208,6 +208,33 @@ } } } +@utility scrollbar-hover { + /* Firefox: hide the thumb until hover */ + scrollbar-width: thin; + scrollbar-color: transparent transparent; + &:hover { + scrollbar-color: var(--color-gray-400) transparent; + } + .dark &:hover { + scrollbar-color: var(--color-gray-600) transparent; + } + /* WebKit: reserve the track, reveal the thumb only on hover */ + &::-webkit-scrollbar { + width: 8px; + height: 8px; + } + &::-webkit-scrollbar-thumb { + border-radius: 9999px; + background-color: transparent; + } + &:hover::-webkit-scrollbar-thumb { + background-color: var(--color-gray-400); + } + .dark &:hover::-webkit-scrollbar-thumb { + background-color: var(--color-gray-600); + } +} + @utility chip { @apply border-divider-light dark:border-divider-dark inline-flex items-center gap-1 rounded-full border bg-gray-100 px-2 text-sm text-gray-800 select-none dark:bg-gray-700 dark:text-gray-200; } @@ -217,7 +244,17 @@ } @utility breadcrumbs { - font-size: 90%; + /* Absolute size so breadcrumbs render identically inside and outside prose */ + font-size: calc(var(--text-base) * 0.9); +} + +/* Guides landing: collapse section spacing into a flat list while filtering. + Grouped spacing is the static default; this only applies once the page is + being filtered, so it never affects first paint (no layout jank). */ +.guides-flat > section { + border-top-width: 0 !important; + padding-top: 0 !important; + padding-bottom: 0 !important; } @utility topbar-button { diff --git a/assets/images/learning-paths/build-cloud.png b/assets/images/learning-paths/build-cloud.png deleted file mode 100644 index b5fed6aa6844..000000000000 Binary files a/assets/images/learning-paths/build-cloud.png and /dev/null differ diff --git a/assets/images/learning-paths/compose.png b/assets/images/learning-paths/compose.png deleted file mode 100644 index 1e4d60368bfb..000000000000 Binary files a/assets/images/learning-paths/compose.png and /dev/null differ diff --git a/assets/images/learning-paths/container-supported-development.png b/assets/images/learning-paths/container-supported-development.png deleted file mode 100644 index a9e09665bbee..000000000000 Binary files a/assets/images/learning-paths/container-supported-development.png and /dev/null differ diff --git a/assets/images/learning-paths/scout.png b/assets/images/learning-paths/scout.png deleted file mode 100644 index 7577785eba79..000000000000 Binary files a/assets/images/learning-paths/scout.png and /dev/null differ diff --git a/assets/images/learning-paths/testcontainers-cloud-learning-path.png b/assets/images/learning-paths/testcontainers-cloud-learning-path.png deleted file mode 100644 index 80322e328455..000000000000 Binary files a/assets/images/learning-paths/testcontainers-cloud-learning-path.png and /dev/null differ diff --git a/assets/js/interactive-diagram.js b/assets/js/interactive-diagram.js new file mode 100644 index 000000000000..824278ef0840 --- /dev/null +++ b/assets/js/interactive-diagram.js @@ -0,0 +1,549 @@ +const svgNamespace = "http://www.w3.org/2000/svg"; + +document.querySelectorAll("[data-interactive-diagram]").forEach((root) => { + const configElement = root.querySelector("[data-interactive-diagram-config]"); + if (!configElement) return; + + let config; + try { + config = JSON.parse(configElement.textContent); + } catch { + return; + } + + const stage = root.querySelector("[data-diagram-stage]"); + if (!stage || !config.canvas || !config.nodes?.length) return; + + const state = buildDiagram(stage, config); + if (config.type === "topology") { + initializeTopology(root, stage, state, config); + } else if (config.steps?.length) { + initializeSequence(root, state, config); + } +}); + +function initializeSequence(root, state, config) { + const previousButton = root.querySelector("[data-step-previous]"); + const nextButton = root.querySelector("[data-step-next]"); + const progress = root.querySelector("[data-step-progress]"); + let currentStep = 0; + + const stepButtons = config.steps.map((step, index) => { + const button = document.createElement("button"); + button.type = "button"; + button.className = "interactive-diagram__progress-step"; + button.setAttribute("aria-label", `Show step ${index + 1}: ${step.label}`); + button.addEventListener("click", () => { + showStep(index); + }); + progress?.append(button); + return button; + }); + + function showStep(index) { + currentStep = Math.max(0, Math.min(index, config.steps.length - 1)); + const step = config.steps[currentStep]; + const activeNodes = new Set(step.activeNodes ?? []); + const activeEdges = new Set(step.activeEdges ?? []); + + state.nodes.forEach((element, id) => { + element.classList.toggle("is-active", activeNodes.has(id)); + }); + state.edges.forEach((element, id) => { + element.classList.toggle("is-active", activeEdges.has(id)); + }); + positionToken(state, config, step.token); + + setText( + root, + "[data-step-number]", + `${String(currentStep + 1).padStart(2, "0")} / ${String(config.steps.length).padStart(2, "0")}`, + ); + setText(root, "[data-step-title]", step.label); + setText(root, "[data-step-body]", step.body); + setText(root, "[data-step-state]", step.state); + + if (previousButton) previousButton.disabled = currentStep === 0; + if (nextButton) + nextButton.disabled = currentStep === config.steps.length - 1; + stepButtons.forEach((button, buttonIndex) => { + const selected = buttonIndex === currentStep; + button.classList.toggle("is-active", selected); + button.setAttribute("aria-current", selected ? "step" : "false"); + }); + } + + previousButton?.addEventListener("click", () => { + showStep(currentStep - 1); + }); + nextButton?.addEventListener("click", () => { + showStep(currentStep + 1); + }); + + root.classList.add("is-enhanced"); + showStep(0); +} + +function initializeTopology(root, stage, state, config) { + const overview = config.overview ?? { + category: "Overview", + label: config.title, + body: config.description, + }; + let pinnedItem; + + const items = [ + ...config.nodes.map((node) => ({ + ...node, + itemType: "node", + element: state.nodes.get(node.id), + })), + ...config.edges.map((edge) => ({ + ...edge, + itemType: "edge", + element: state.edges.get(edge.id), + })), + ].filter((item) => item.element); + + items.forEach((item) => { + const { element } = item; + element.setAttribute("role", "button"); + element.setAttribute("tabindex", "0"); + element.setAttribute("aria-label", `${item.label}. ${item.details}`); + element.setAttribute("aria-pressed", "false"); + + element.addEventListener("pointerenter", () => { + if (!pinnedItem) showItem(item); + }); + element.addEventListener("pointerleave", () => { + if (!pinnedItem && element !== document.activeElement) showOverview(); + }); + element.addEventListener("focus", () => { + if (!pinnedItem) showItem(item); + }); + element.addEventListener("blur", () => { + if (!pinnedItem) showOverview(); + }); + element.addEventListener("click", (event) => { + event.stopPropagation(); + if (pinnedItem?.itemType === item.itemType && pinnedItem.id === item.id) { + pinnedItem = undefined; + showOverview(); + } else { + pinnedItem = item; + showItem(item); + } + updatePressedState(); + }); + element.addEventListener("keydown", (event) => { + if (event.key === "Enter" || event.key === " ") { + event.preventDefault(); + element.dispatchEvent(new MouseEvent("click", { bubbles: true })); + } + }); + }); + + stage.addEventListener("click", () => { + pinnedItem = undefined; + updatePressedState(); + showOverview(); + }); + root.addEventListener("keydown", (event) => { + if (event.key !== "Escape") return; + pinnedItem = undefined; + updatePressedState(); + showOverview(); + }); + + function showItem(item) { + const activeNodes = new Set(); + const relatedNodes = new Set(); + const activeEdges = new Set(); + + if (item.itemType === "node") { + activeNodes.add(item.id); + config.edges.forEach((edge) => { + if (edge.from !== item.id && edge.to !== item.id) return; + activeEdges.add(edge.id); + relatedNodes.add(edge.from === item.id ? edge.to : edge.from); + }); + } else { + activeEdges.add(item.id); + activeNodes.add(item.from); + activeNodes.add(item.to); + } + + root.classList.add("has-topology-focus"); + state.nodes.forEach((element, id) => { + element.classList.toggle("is-active", activeNodes.has(id)); + element.classList.toggle("is-related", relatedNodes.has(id)); + }); + state.edges.forEach((element, id) => { + element.classList.toggle("is-active", activeEdges.has(id)); + }); + setTopologyDetail(root, item.category, item.label, item.details); + } + + function showOverview() { + root.classList.remove("has-topology-focus"); + state.nodes.forEach((element) => { + element.classList.remove("is-active", "is-related"); + }); + state.edges.forEach((element) => element.classList.remove("is-active")); + setTopologyDetail(root, overview.category, overview.label, overview.body); + } + + function updatePressedState() { + items.forEach((item) => { + const pressed = + pinnedItem?.itemType === item.itemType && pinnedItem.id === item.id; + item.element.setAttribute("aria-pressed", String(pressed)); + item.element.classList.toggle("is-pinned", pressed); + }); + } + + root.classList.add("is-enhanced"); + showOverview(); +} + +function setTopologyDetail(root, category, label, body) { + setText(root, "[data-topology-category]", category); + setText(root, "[data-topology-title]", label); + setText(root, "[data-topology-body]", body); +} + +function buildDiagram(stage, config) { + const isTopology = config.type === "topology"; + const svg = createSvgElement("svg", { + viewBox: `0 0 ${config.canvas.width} ${config.canvas.height}`, + role: isTopology ? "group" : "img", + "aria-label": config.description, + }); + svg.classList.add("interactive-diagram__svg"); + + const definitions = createSvgElement("defs"); + const marker = createSvgElement("marker", { + id: `arrow-${Math.random().toString(36).slice(2)}`, + viewBox: "0 0 10 10", + refX: "8", + refY: "5", + markerWidth: "7", + markerHeight: "7", + orient: "auto-start-reverse", + }); + marker.append(createSvgElement("path", { d: "M 0 0 L 10 5 L 0 10 z" })); + definitions.append(marker); + svg.append(definitions); + + config.boundaries?.forEach((boundary) => { + const group = createSvgElement("g"); + group.classList.add( + "interactive-diagram__boundary", + `interactive-diagram__boundary--${boundary.kind}`, + ); + group.append( + createSvgElement("rect", { + x: boundary.x, + y: boundary.y, + width: boundary.width, + height: boundary.height, + rx: "8", + }), + createSvgText( + boundary.label, + boundary.x + 16, + boundary.y + 25, + "interactive-diagram__boundary-label", + ), + ); + svg.append(group); + }); + + const nodesById = new Map(config.nodes.map((node) => [node.id, node])); + const edges = new Map(); + config.edges.forEach((edge) => { + const from = nodesById.get(edge.from); + const to = nodesById.get(edge.to); + if (!from || !to) return; + const points = edgePoints(from, to, edge.offset); + const lineAttributes = { + x1: points.x1, + y1: points.y1, + x2: points.x2, + y2: points.y2, + "marker-end": `url(#${marker.id})`, + }; + if (edge.bidirectional) { + lineAttributes["marker-start"] = `url(#${marker.id})`; + } + + if (isTopology) { + const group = createSvgElement("g"); + group.classList.add( + "interactive-diagram__edge", + "interactive-diagram__edge--interactive", + `interactive-diagram__edge--${edge.kind}`, + ); + const line = createSvgElement("line", lineAttributes); + line.classList.add("interactive-diagram__edge-line"); + const hitTarget = createSvgElement("line", { + x1: points.x1, + y1: points.y1, + x2: points.x2, + y2: points.y2, + }); + hitTarget.classList.add("interactive-diagram__edge-hit"); + group.append(line, hitTarget); + + if (edge.label) { + const labelPoint = edgeTokenPoint( + points, + edge.labelProgress ?? 0.5, + edge.labelOffset ?? 0, + ); + const labelWidth = Math.max(68, edge.label.length * 6.6 + 20); + const labelGroup = createSvgElement("g"); + labelGroup.classList.add("interactive-diagram__edge-label"); + labelGroup.append( + createSvgElement("rect", { + x: labelPoint.x - labelWidth / 2, + y: labelPoint.y - 13, + width: labelWidth, + height: 26, + rx: "13", + }), + createSvgText( + edge.label, + labelPoint.x, + labelPoint.y + 4, + "interactive-diagram__edge-label-text", + ), + ); + group.append(labelGroup); + } + svg.append(group); + edges.set(edge.id, group); + } else { + const line = createSvgElement("line", lineAttributes); + line.classList.add("interactive-diagram__edge"); + svg.append(line); + edges.set(edge.id, line); + } + }); + + const nodes = new Map(); + config.nodes.forEach((node) => { + const group = createSvgElement("g"); + group.classList.add( + "interactive-diagram__node", + `interactive-diagram__node--${node.kind}`, + ); + group.append( + createSvgElement("rect", { + x: node.x, + y: node.y, + width: node.width, + height: node.height, + rx: "7", + }), + createSvgText( + node.label, + node.x + 14, + node.y + 29, + "interactive-diagram__node-label", + ), + createSvgText( + node.description, + node.x + 14, + node.y + 51, + "interactive-diagram__node-description", + ), + ); + svg.append(group); + nodes.set(node.id, group); + }); + + let token; + let tokenRect; + let tokenText; + if (!isTopology) { + token = createSvgElement("g"); + token.classList.add("interactive-diagram__token"); + tokenRect = createSvgElement("rect", { height: "28", rx: "14" }); + tokenText = createSvgText("", 0, 0, "interactive-diagram__token-label"); + token.append(tokenRect, tokenText); + svg.append(token); + } + stage.append(svg); + + return { + nodes, + edges, + nodesById, + token, + tokenRect, + tokenText, + tokenAnimation: undefined, + }; +} + +function positionToken(state, config, tokenConfig) { + state.tokenAnimation?.remove(); + state.tokenAnimation = undefined; + + if (!tokenConfig) { + state.token.hidden = true; + return; + } + + const width = Math.max(70, tokenConfig.label.length * 7.2 + 24); + let point; + let travelStart; + if (tokenConfig.node) { + const node = state.nodesById.get(tokenConfig.node); + if (node) { + point = nodeTokenPoint(node, width, tokenConfig.placement); + } + } else if (tokenConfig.edge) { + const edge = config.edges.find( + (candidate) => candidate.id === tokenConfig.edge, + ); + const from = state.nodesById.get(edge?.from); + const to = state.nodesById.get(edge?.to); + if (from && to) { + const points = edgePoints(from, to, edge.offset); + const progress = tokenConfig.progress ?? 0.5; + const labelOffset = tokenConfig.labelOffset ?? 0; + point = edgeTokenPoint(points, progress, labelOffset); + travelStart = edgeTokenPoint(points, 0, labelOffset); + } + } + if (!point) return; + + state.token.hidden = false; + state.token.setAttribute( + "transform", + `translate(${point.x - width / 2} ${point.y - 14})`, + ); + state.tokenRect.setAttribute("width", width); + state.tokenText.setAttribute("x", width / 2); + state.tokenText.setAttribute("y", "18"); + state.tokenText.textContent = tokenConfig.label; + state.token.classList.remove("is-entering"); + if (travelStart && !prefersReducedMotion()) { + animateTokenTravel(state, travelStart, point, width); + } else { + window.requestAnimationFrame(() => + state.token.classList.add("is-entering"), + ); + } +} + +function nodeTokenPoint(node, width, placement = "bottom") { + const gap = 8; + const halfHeight = 14; + const positions = { + top: { + x: node.x + node.width / 2, + y: node.y - gap - halfHeight, + }, + right: { + x: node.x + node.width + gap + width / 2, + y: node.y + node.height / 2, + }, + bottom: { + x: node.x + node.width / 2, + y: node.y + node.height + gap + halfHeight, + }, + left: { + x: node.x - gap - width / 2, + y: node.y + node.height / 2, + }, + }; + return positions[placement] ?? positions.bottom; +} + +function edgeTokenPoint(points, progress, labelOffset) { + const dx = points.x2 - points.x1; + const dy = points.y2 - points.y1; + const length = Math.hypot(dx, dy) || 1; + return { + x: points.x1 + dx * progress - (dy / length) * labelOffset, + y: points.y1 + dy * progress + (dx / length) * labelOffset, + }; +} + +function animateTokenTravel(state, from, to, width) { + const animation = createSvgElement("animateTransform", { + attributeName: "transform", + type: "translate", + from: `${from.x - width / 2} ${from.y - 14}`, + to: `${to.x - width / 2} ${to.y - 14}`, + dur: "650ms", + calcMode: "spline", + keyTimes: "0;1", + keySplines: "0.2 0 0 1", + }); + state.token.prepend(animation); + state.tokenAnimation = animation; + if (typeof animation.beginElement === "function") { + animation.beginElement(); + window.setTimeout(() => { + animation.remove(); + if (state.tokenAnimation === animation) state.tokenAnimation = undefined; + }, 700); + } else { + animation.remove(); + state.tokenAnimation = undefined; + } +} + +function prefersReducedMotion() { + return ( + window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false + ); +} + +function edgePoints(from, to, offset = 0) { + const fromCenter = { + x: from.x + from.width / 2, + y: from.y + from.height / 2, + }; + const toCenter = { x: to.x + to.width / 2, y: to.y + to.height / 2 }; + const dx = toCenter.x - fromCenter.x; + const dy = toCenter.y - fromCenter.y; + if (Math.abs(dx) >= Math.abs(dy)) { + return { + x1: dx >= 0 ? from.x + from.width : from.x, + y1: fromCenter.y + offset, + x2: dx >= 0 ? to.x : to.x + to.width, + y2: toCenter.y + offset, + }; + } + return { + x1: fromCenter.x + offset, + y1: dy >= 0 ? from.y + from.height : from.y, + x2: toCenter.x + offset, + y2: dy >= 0 ? to.y : to.y + to.height, + }; +} + +function createSvgElement(name, attributes = {}) { + const element = document.createElementNS(svgNamespace, name); + Object.entries(attributes).forEach(([key, value]) => + element.setAttribute(key, value), + ); + return element; +} + +function createSvgText(value, x, y, className) { + const text = createSvgElement("text", { x, y }); + text.classList.add(className); + text.textContent = value; + return text; +} + +function setText(root, selector, value) { + const element = root.querySelector(selector); + if (element) element.textContent = value; +} diff --git a/assets/js/mermaid.js b/assets/js/mermaid.js index ae8f7a9b1f10..b8dab78d8ba4 100644 --- a/assets/js/mermaid.js +++ b/assets/js/mermaid.js @@ -1,19 +1,86 @@ -import mermaid from 'mermaid' +import mermaid from "mermaid"; -const isDark = () => document.documentElement.classList.contains('dark') +const SELECTOR = "pre.mermaid"; -mermaid.initialize({ - startOnLoad: false, - securityLevel: 'strict', - theme: isDark() ? 'dark' : 'default', -}) +const isDark = () => document.documentElement.classList.contains("dark"); -const render = () => { - mermaid.run({ querySelector: 'pre.mermaid' }) -} +// Rendering replaces the element content with an SVG, so the diagram source +// is captured once per element and reused for every redraw. +const sources = new WeakMap(); + +const getSource = (el) => { + let source = sources.get(el); + if (source === undefined) { + // Same treatment mermaid.run() gives element content: decode HTML + // entities, but keep <br/> tags because labels use them for line breaks. + const decoder = document.createElement("textarea"); + decoder.innerHTML = el.innerHTML; + source = decoder.value.replace(/<br\s*\/?>/gi, "<br/>").trim(); + sources.set(el, source); + } + return source; +}; + +// Incremented on every render request. A render that is no longer the latest +// stops before writing to the page, so a slow render cannot overwrite a +// newer theme. +let generation = 0; +let nextId = 0; +let renderedDark; + +const render = async () => { + const current = ++generation; + const dark = isDark(); + renderedDark = dark; -if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', render) + const elements = Array.from(document.querySelectorAll(SELECTOR)); + if (elements.length === 0) return; + + mermaid.initialize({ + startOnLoad: false, + securityLevel: "strict", + theme: dark ? "dark" : "default", + // On a syntax error, render() would otherwise leave Mermaid's error + // graphic in a temporary element at the end of <body>. The failing + // element shows its source instead (see the catch below). + suppressErrorRendering: true, + }); + + for (const el of elements) { + const source = getSource(el); + try { + // mermaid.render() returns the SVG as a string instead of writing it + // into the element, so an existing diagram stays on screen until its + // replacement is ready. + const { svg, bindFunctions } = await mermaid.render( + `mermaid-${nextId++}`, + source, + ); + if (current !== generation) return; + el.innerHTML = svg; + bindFunctions?.(el); + delete el.dataset.error; + } catch (error) { + if (current !== generation) return; + // Unhide the element so the source and the console error can be + // matched up. + el.dataset.error = ""; + console.error("Mermaid failed to render a diagram", error); + } + } +}; + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", render); } else { - render() + render(); } + +// theme.js and the header theme button both set the light/dark class on +// <html>. Redraw with the matching Mermaid theme whenever it changes. +new MutationObserver(() => { + if (isDark() !== renderedDark) render(); +}).observe(document.documentElement, { + attributes: true, + attributeFilter: ["class"], +}); diff --git a/content/_index.md b/content/_index.md index e78e0a1cc0ea..16c70ec19069 100644 --- a/content/_index.md +++ b/content/_index.md @@ -11,24 +11,18 @@ reference material for everyday development and operations tasks. ## Browse docs by area -- [Get started](/get-started/): Learn Docker basics and core concepts. +- [Get started](/get-started/): Run an application, sandbox an AI agent, or + roll out Docker. - [Guides](/guides/): Follow task-focused walkthroughs for common workflows. - [Manuals](/manuals/): Install, configure, and use Docker products. - [Reference](/reference/): Browse CLI, API, and file format documentation. -## Featured topics - -- [Docker Hardened Images](/dhi/) -- [Get started with Docker Sandboxes](/ai/sandboxes/get-started/) -- [Docker Desktop overview](/desktop/) -- [Install Docker Engine](/engine/install/) -- [Dockerfile reference](/reference/dockerfile/) -- [Docker Build overview](/build/) +{{< whats-new >}} ## Common questions -- [How do I get started with Docker?](/get-started/docker-overview/) -- [Can I run my AI agent in a sandbox?](/ai/sandboxes/get-started/) -- [What is a container?](/get-started/docker-concepts/the-basics/what-is-a-container/) +- [How do I get started with Docker?](/get-started/) +- [How do I containerize an application?](/get-started/tutorials/run-an-app/) +- [Can I run my AI agent in a sandbox?](/get-started/tutorials/run-an-agent/) - [What are Docker Hardened Images?](/dhi/) - [Why should I use Docker Compose?](/compose/) diff --git a/content/bot-detection.md b/content/bot-detection.md new file mode 100644 index 000000000000..3be15b77050d --- /dev/null +++ b/content/bot-detection.md @@ -0,0 +1,9 @@ +--- +title: Automated traffic detection +description: This page supports automated traffic detection for Docker documentation. +keywords: bot detection, automated traffic, Docker documentation +sitemap: false +layout: wide +--- + +This page is used to identify automated traffic. diff --git a/content/get-started/_index.md b/content/get-started/_index.md index e7efa9ccac6b..e161dfa35596 100644 --- a/content/get-started/_index.md +++ b/content/get-started/_index.md @@ -1,51 +1,34 @@ --- title: Get started -keywords: Docker, get started -description: Get started with Docker -layout: wide +keywords: Docker, get started, containers, AI agents, sandboxes, administration +description: Choose a tutorial to build and run an application, work with an AI agent safely, or set up Docker for your organization. +layout: get-started params: - icon: arrow-down-tray notoc: true - get-started: - - title: Get Docker - description: Choose the best installation path for your setup. - link: /get-started/get-docker/ - icon: arrow-down-tray - - title: What is Docker? - description: Learn about the Docker platform. - link: /get-started/docker-overview/ - icon: document-text - get-started2: - - title: Introduction - description: Get started with the basics and the benefits of containerizing your applications. - link: /get-started/introduction/ - icon: rocket-launch - - title: Docker concepts - description: Gain a better understanding of foundational Docker concepts. - link: /get-started/docker-concepts/the-basics/what-is-a-container/ - icon: home - - title: Docker workshop - description: Get guided through a 45-minute workshop to learn about Docker. - link: /get-started/workshop/ - icon: computer-desktop + installs: + - eyebrow: Docker + title: Install Docker + description: Get Docker Desktop or Docker Engine for your operating system. + link: /get-started/get-docker/ + - eyebrow: Docker Sandboxes + title: Install Docker Sandboxes + description: Install the sbx command to run coding agents in isolated environments. + link: /ai/sandboxes/install/ + tutorials: + - audience: New to Docker + title: Build and share a containerized application + description: Run a container and an application stack, build an image, and share it through Docker Hub. + link: /get-started/tutorials/run-an-app/ + - audience: AI developers + title: Run your coding agent in a sandbox + description: Move your existing full-autonomy coding-agent workflow into a disposable Docker Sandbox. + link: /get-started/tutorials/run-an-agent/ + - audience: Administrators + title: Roll out Docker to a pilot group + description: Invite a pilot user, apply a Docker Desktop policy, and verify the managed experience. + link: /get-started/tutorials/admin-set-up/ aliases: - /engine/get-started/ - /engine/tutorials/usingdocker/ - /guides/getting-started/get-docker-desktop/ --- - -If you're new to Docker, this section guides you through the essential resources to get started. - -Follow the guides to help you get started and learn how Docker can optimize your development workflows. - -For more advanced concepts and scenarios in Docker, see [Guides](/guides/). - -## Foundations of Docker - -Install Docker and jump into discovering what Docker is. - -{{< grid items="get-started" >}} - -Learn the foundational concepts and workflows of Docker. - -{{< grid items="get-started2" >}} diff --git a/content/get-started/docker-concepts/building-images/multi-stage-builds.md b/content/get-started/docker-concepts/building-images/multi-stage-builds.md index 49ff8cfe068e..6bdabe73c55e 100644 --- a/content/get-started/docker-concepts/building-images/multi-stage-builds.md +++ b/content/get-started/docker-concepts/building-images/multi-stage-builds.md @@ -287,7 +287,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`. - The first stage remains the same as the previous Dockerfile, providing a Java Development Kit (JDK) environment for building the application. This stage is given the name of builder. - - The second stage is a new stage named `final`. It uses a slimmer `eclipse-temurin:21.0.2_13-jre-jammy` image, containing just the Java Runtime Environment (JRE) needed to run the application. This image provides a Java Runtime Environment (JRE) which is enough for running the compiled application (JAR file). + - The second stage is a new stage named `final`. It uses a slimmer `eclipse-temurin:21.0.8_9-jre-jammy` image, containing just the Java Runtime Environment (JRE) needed to run the application. This image provides a Java Runtime Environment (JRE) which is enough for running the compiled application (JAR file). > For production use, it's highly recommended that you produce a custom JRE-like runtime using jlink. JRE images are available for all versions of Eclipse Temurin, but `jlink` allows you to create a minimal runtime containing only the necessary Java modules for your application. This can significantly reduce the size and improve the security of your final image. [Refer to this page](https://hub.docker.com/_/eclipse-temurin) for more information. @@ -333,4 +333,3 @@ Now that you have the project, you’re ready to create the `Dockerfile`. * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/) * [Base images](/build/building/base-images/) * [Spring Boot Docker](https://spring.io/guides/topicals/spring-boot-docker) - diff --git a/content/get-started/docker-concepts/running-containers/publishing-ports.md b/content/get-started/docker-concepts/running-containers/publishing-ports.md index d2766459fbf3..9f611e412754 100644 --- a/content/get-started/docker-concepts/running-containers/publishing-ports.md +++ b/content/get-started/docker-concepts/running-containers/publishing-ports.md @@ -38,6 +38,32 @@ Now, any traffic sent to port `8080` on your host machine will be forwarded to p > > When a port is published, it's published to all network interfaces by default. This means any traffic that reaches your machine can access the published application. Be mindful of publishing databases or any sensitive information. [Learn more about published ports here](/engine/network/#published-ports). + +### Publishing on a specific host IP + +By default, published ports listen on all host interfaces (`0.0.0.0` / `::`). You can +bind to a single address by putting the IP first in the publish string: + +```console +$ docker run -d -p 127.0.0.1:8080:80 nginx +``` + +The full form is `HOST_IP:HOST_PORT:CONTAINER_PORT`. + +- `HOST_IP`: Optional. The host address to bind. Use `127.0.0.1` to keep the port + local to the machine, or a specific interface IP so only that NIC accepts traffic. +- `HOST_PORT` / `CONTAINER_PORT`: Same meaning as in `HOST_PORT:CONTAINER_PORT`. + +In Compose, the same extended form works under `ports`: + +```yaml +services: + app: + image: docker/welcome-to-docker + ports: + - "127.0.0.1:8080:80" +``` + ### Publishing to ephemeral ports At times, you may want to simply publish the port but don’t care which host port is used. In these cases, you can let Docker pick the port for you. To do so, simply omit the `HOST_PORT` configuration. diff --git a/content/get-started/docker-concepts/running-containers/sharing-local-files.md b/content/get-started/docker-concepts/running-containers/sharing-local-files.md index 6f55002951b5..043be8b8c9a8 100644 --- a/content/get-started/docker-concepts/running-containers/sharing-local-files.md +++ b/content/get-started/docker-concepts/running-containers/sharing-local-files.md @@ -162,12 +162,12 @@ Using a bind mount, you can map the configuration file on your host computer to 1. You can view the mounted files inside a container by selecting the container's **Files** tab and then selecting a file inside the `/usr/local/apache2/htdocs/` directory. Then, select **Open file editor**. - ![A screenshot of Docker Desktop Dashboard showing the mounted files inside the a container](images/mounted-files.webp?border=true) + ![A screenshot of Docker Desktop Dashboard showing the mounted files inside the container](images/mounted-files.webp?border=true) 2. Delete the file on the host and verify the file is also deleted in the container. You will find that the files no longer exist under **Files** in the Docker Desktop Dashboard. - ![A screenshot of Docker Desktop Dashboard showing the deleted files inside the a container](images/deleted-files.webp?border=true) + ![A screenshot of Docker Desktop Dashboard showing the deleted files inside the container](images/deleted-files.webp?border=true) 3. Recreate the HTML file on the host system and see that file re-appears under the **Files** tab under **Containers** on the Docker Desktop Dashboard. By now, you will be able to access the site too. diff --git a/content/get-started/docker-concepts/the-basics/what-is-a-container.md b/content/get-started/docker-concepts/the-basics/what-is-a-container.md index 625e376b5e99..8279e3387e65 100644 --- a/content/get-started/docker-concepts/the-basics/what-is-a-container.md +++ b/content/get-started/docker-concepts/the-basics/what-is-a-container.md @@ -57,7 +57,7 @@ Use the following instructions to run a container. 2. Specify `welcome-to-docker` in the search input and then select the **Pull** button. - ![A screenshot of the Docker Desktop Dashboard showing the search result for welcome-to-docker Docker image ](images/search-the-docker-image.webp?border=true&w=1000&h=700) + ![A screenshot of the Docker Desktop Dashboard showing the search result for welcome-to-docker Docker image](images/search-the-docker-image.webp?border=true&w=1000&h=700) 3. Once the image is successfully pulled, select the **Run** button. diff --git a/content/get-started/docker-overview.md b/content/get-started/docker-overview.md index fe8b9cbb3178..b3df1ed752b9 100644 --- a/content/get-started/docker-overview.md +++ b/content/get-started/docker-overview.md @@ -205,4 +205,4 @@ in a separate namespace and its access is limited to that namespace. ## Next steps - [Install Docker](/get-started/get-docker.md) -- [Get started with Docker](/get-started/introduction/_index.md) +- [Build and share a containerized application](/get-started/tutorials/run-an-app.md) diff --git a/content/get-started/get-docker.md b/content/get-started/get-docker.md index 9c02b598165f..8084d5b1f15b 100644 --- a/content/get-started/get-docker.md +++ b/content/get-started/get-docker.md @@ -12,6 +12,8 @@ aliases: - /get-docker/ - /desktop/install/ - /desktop/setup/install/ + - /get-started/introduction/get-docker-desktop/ + - /getting-started/get-docker-desktop/ --- Docker is an open platform for developing, shipping, and running applications. diff --git a/content/get-started/introduction/_index.md b/content/get-started/introduction/_index.md deleted file mode 100644 index a28300d3b4ef..000000000000 --- a/content/get-started/introduction/_index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Introduction -keywords: get started, getting started, how to get started -weight: 30 -description: | - Get started with Docker. You'll learn about Docker Desktop, developing with - Docker, as well as how to build and push your first image. -summary: | - Embark on a comprehensive learning path to understand Docker and - containerization, beginning with foundational concepts and installation - procedures. Progress through hands-on exercises that cover essential Docker - commands, image creation, and container orchestration. -layout: series -params: - proficiencyLevel: Beginner - time: 15 minutes - prerequisites: None -aliases: - - /guides/getting-started/ ---- - -## About this series - -In this guide series, you will gain hands-on experience with Docker, starting -with installing and setting up Docker Desktop on your local machine. You will -learn how to run your first container, understanding the basics of -containerization and its benefits. This series guides you through building your -first Docker image, providing insights into creating efficient and reusable -images. Finally, you will explore how to publish your image on Docker Hub, -enabling you to share your work with the broader community and leverage -Docker's powerful ecosystem for collaborative development and deployment. - -## What you'll learn - -- Set up Docker Desktop -- Run your first container -- Build your first image -- Publish your image on Docker Hub diff --git a/content/get-started/introduction/build-and-push-first-image.md b/content/get-started/introduction/build-and-push-first-image.md deleted file mode 100644 index 35974b839990..000000000000 --- a/content/get-started/introduction/build-and-push-first-image.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: Build and push your first image -keywords: concepts, container, docker desktop -description: This concept page will teach you how to build and push your first image -summary: | - Learn how to build your first Docker image, a key step in containerizing your - application. We'll guide you through the process of creating an image - repository and building and pushing your image to Docker Hub. This enables - you to share your image easily within your team. -weight: 3 -aliases: - - /guides/getting-started/build-and-push-first-image/ ---- - -{{< youtube-embed 7ge1s5nAa34 >}} - -## Explanation - -Now that you've updated the [to-do list app](develop-with-containers.md), you’re ready to create a container image for the application and share it on Docker Hub. To do so, you will need to do the following: - -1. Sign in with your Docker account -2. Create an image repository on Docker Hub -3. Build the container image -4. Push the image to Docker Hub - -Before you dive into the hands-on guide, the following are a few core concepts that you should be aware of. - -### Container images - -If you’re new to container images, think of them as a standardized package that contains everything needed to run an application, including its files, configuration, and dependencies. These packages can then be distributed and shared with others. - -### Docker Hub - -To share your Docker images, you need a place to store them. This is where registries come in. While there are many registries, Docker Hub is the default and go-to registry for images. Docker Hub provides both a place for you to store your own images and to find images from others to either run or use as the bases for your own images. - -When choosing base images, Docker Hub offers two categories of trusted, Docker-maintained images: - -- [Docker Official Images (DOI)](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images) – Curated images for popular software, following best practices and regularly updated. -- [Docker Hardened Images (DHI)](/manuals/dhi/_index.md) – Minimal, secure, production-ready images with near-zero CVEs, designed to reduce attack surface and simplify compliance. DHI images are free and open source under Apache 2.0. - -In [Develop with containers](develop-with-containers.md), you used the following images that came from Docker Hub, each of which are [Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images): - -- [node](https://hub.docker.com/_/node) - provides a Node environment and is used as the base of your development efforts. This image is also used as the base for the final application image. -- [mysql](https://hub.docker.com/_/mysql) - provides a MySQL database to store the to-do list items -- [phpmyadmin](https://hub.docker.com/_/phpmyadmin) - provides phpMyAdmin, a web-based interface to the MySQL database -- [traefik](https://hub.docker.com/_/traefik) - provides Traefik, a modern HTTP reverse proxy and load balancer that routes requests to the appropriate container based on routing rules - -Explore the full catalog of trusted content on Docker Hub: -- [Docker Official Images](https://hub.docker.com/search?badges=official) – Curated images for popular software -- [Docker Hardened Images](https://hub.docker.com/hardened-images/catalog) – Security-hardened, minimal production images (also available at [dhi.io](https://dhi.io)) -- [Docker Verified Publishers](https://hub.docker.com/search?badges=verified_publisher) – Images from verified software vendors -- [Docker Sponsored Open Source](https://hub.docker.com/search?badges=open_source) – Images from sponsored OSS projects - -## Try it out - -In this hands-on guide, you'll learn how to sign in to Docker Hub and push images to Docker Hub repository. - -## Sign in with your Docker account - -To push images to Docker Hub, you will need to sign in with a Docker account. - -1. Open the Docker Dashboard. - -2. Select **Sign in** at the top-right corner. - -3. If needed, create an account and then complete the sign-in flow. - -Once you're done, you should see the **Sign in** button turn into a profile picture. - -## Create an image repository - -Now that you have an account, you can create an image repository. Just as a Git repository holds source code, an image repository stores container images. - -1. Go to [Docker Hub](https://hub.docker.com). - -2. Select **Create repository**. - -3. On the **Create repository** page, enter the following information: - - - **Repository name** - `getting-started-todo-app` - - **Short description** - feel free to enter a description if you'd like - - **Visibility** - select **Public** to allow others to pull your customized to-do app - -4. Select **Create** to create the repository. - - -## Build and push the image - -Now that you have a repository, you are ready to build and push your image. An important note is that the image you are building extends the Node image, meaning you don't need to install or configure Node, yarn, etc. You can simply focus on what makes your application unique. - -> **What is an image/Dockerfile?** -> -> Without going too deep yet, think of a container image as a single package that contains -> everything needed to run a process. In this case, it will contain a Node environment, -> the backend code, and the compiled React code. -> -> Any machine that runs a container using the image, will then be able to run the application as -> it was built without needing anything else pre-installed on the machine. -> -> A `Dockerfile` is a text-based script that provides the instruction set on how to build -> the image. For this quick start, the repository already contains the Dockerfile. - - -{{< tabs group="cli-or-vs-code" persist=true >}} -{{< tab name="CLI" >}} - -1. To get started, either clone or [download the project as a ZIP file](https://github.com/docker/getting-started-todo-app/archive/refs/heads/main.zip) to your local machine. - - ```console - $ git clone https://github.com/docker/getting-started-todo-app - ``` - - And after the project is cloned, navigate into the new directory created by the clone: - - ```console - $ cd getting-started-todo-app - ``` - -2. Build the project by running the following command, swapping out `DOCKER_USERNAME` with your username. - - ```console - $ docker build -t <DOCKER_USERNAME>/getting-started-todo-app . - ``` - - For example, if your Docker username was `mobydock`, you would run the following: - - ```console - $ docker build -t mobydock/getting-started-todo-app . - ``` - -3. To verify the image exists locally, you can use the `docker image ls` command: - - ```console - $ docker image ls - ``` - - You will see output similar to the following: - - ```console - REPOSITORY TAG IMAGE ID CREATED SIZE - mobydock/getting-started-todo-app latest 1543656c9290 2 minutes ago 1.12GB - ... - ``` - -4. To push the image, use the `docker push` command. Be sure to replace `DOCKER_USERNAME` with your username: - - ```console - $ docker push <DOCKER_USERNAME>/getting-started-todo-app - ``` - - Depending on your upload speeds, this may take a moment to push. - -{{< /tab >}} -{{< tab name="VS Code" >}} - -1. Open Visual Studio Code. Ensure you have the **Docker extension for VS Code** installed from [Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker). - - ![Screenshot of VS code extension marketplace](images/install-docker-extension.webp) - -2. In the **File** menu, select **Open Folder**. Choose **Clone Git Repository** and paste this URL: [https://github.com/docker/getting-started-todo-app](https://github.com/docker/getting-started-todo-app) - - ![Screenshot of VS code showing how to clone a repository](images/clone-the-repo.webp?border=true) - - - -3. Right-click the `Dockerfile` and select the **Build Image...** menu item. - - - ![Screenshot of VS Code showing the right-click menu and "Build Image" menu item](images/build-vscode-menu-item.webp?border=true) - -4. In the dialog that appears, enter a name of `DOCKER_USERNAME/getting-started-todo-app`, replacing `DOCKER_USERNAME` with your Docker username. - -5. After pressing **Enter**, you'll see a terminal appear where the build will occur. Once it's completed, feel free to close the terminal. - -6. Open the Docker Extension for VS Code by selecting the Docker logo in the left nav menu. - -7. Find the image you created. It'll have a name of `docker.io/DOCKER_USERNAME/getting-started-todo-app`. - -8. Expand the image to view the tags (or different versions) of the image. You should see a tag named `latest`, which is the default tag given to an image. - -9. Right-click on the **latest** item and select the **Push...** option. - - ![Screenshot of the Docker Extension and the right-click menu to push an image](images/build-vscode-push-image.webp) - -10. Press **Enter** to confirm and then watch as your image is pushed to Docker Hub. Depending on your upload speeds, it might take a moment to push the image. - - Once the upload is finished, feel free to close the terminal. - -{{< /tab >}} -{{< /tabs >}} - - -## Recap - -Before you move on, take a moment and reflect on what happened here. Within a few moments, you were able to build a container image that packages your application and push it to Docker Hub. - -Going forward, you’ll want to remember that: - -- Docker Hub is the go-to registry for finding trusted content. Docker provides a collection of trusted content, composed of Docker Official Images, Docker Verified Publishers, and Docker Sponsored Open Source Software, to use directly or as bases for your own images. - -- Docker Hub provides a marketplace to distribute your own applications. Anyone can create an account and distribute images. While you are publicly distributing the image you created, private repositories can ensure your images are accessible to only authorized users. - -> **Usage of other registries** -> -> While Docker Hub is the default registry, registries are standardized and made -> interoperable through the [Open Container Initiative](https://opencontainers.org/). This allows companies and -> organizations to run their own private registries. Quite often, trusted content -> is mirrored (or copied) from Docker Hub into these private registries. -> - - - -## Next steps - -Now that you’ve built an image, it's time to discuss why you as a developer should learn more about Docker and how it will help you in your day-to-day tasks. - -{{< button text="What's Next" url="whats-next" >}} - - diff --git a/content/get-started/introduction/develop-with-containers.md b/content/get-started/introduction/develop-with-containers.md deleted file mode 100644 index f3fd5d8f4dd6..000000000000 --- a/content/get-started/introduction/develop-with-containers.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Develop with containers -keywords: concepts, build, images, container, docker desktop -description: This concept page will teach you how to develop with containers -summary: | - Learn how to run your first container, gaining hands-on experience with - Docker's powerful features. We'll cover making real-time changes to both - backend and frontend code within the containerized environment, ensuring - seamless integration and testing. -weight: 2 -aliases: - - /guides/getting-started/develop-with-containers/ ---- - -{{< youtube-embed D0SDBrS3t9I >}} - -## Explanation - -Now that you have Docker Desktop installed, you are ready to do some application development. Specifically, you will do the following: - -1. Clone and start a development project -2. Make changes to the backend and frontend -3. See the changes immediately - -## Try it out - -In this hands-on guide, you'll learn how to develop with containers. - -## Start the project - -1. To get started, either clone or [download the project as a ZIP file](https://github.com/docker/getting-started-todo-app/archive/refs/heads/main.zip) to your local machine. - - ```console - $ git clone https://github.com/docker/getting-started-todo-app - ``` - - And after the project is cloned, navigate into the new directory created by the clone: - - ```console - $ cd getting-started-todo-app - ``` - -2. Once you have the project, start the development environment using Docker Compose. - - To start the project using the CLI, run the following command: - - ```console - $ docker compose watch - ``` - - You will see an output that shows container images being pulled down, containers starting, and more. Don't worry if you don't understand it all at this point. But, within a moment or two, things should stabilize and finish. - -3. Open your browser to [http://localhost](http://localhost) to see the application up and running. It may take a few minutes for the app to run. The app is a simple to-do application, so feel free to add an item or two, mark some as done, or even delete an item. - - ![Screenshot of the getting started to-do app after its first launch](images/develop-getting-started-app-first-launch.webp) - -### What's in the environment? - -Now that the environment is up and running, what's actually in it? At a high-level, there are several containers (or processes) that each serve a specific need for the application: - -- React frontend - a Node container that's running the React dev server, using [Vite](https://vitejs.dev/). -- Node backend - the backend provides an API that provides the ability to retrieve, create, and delete to-do items. -- MySQL database - a database to store the list of the items. -- phpMyAdmin - a web-based interface to interact with the database that is accessible at [http://db.localhost](http://db.localhost). -- Traefik proxy - [Traefik](https://traefik.io/traefik/) is an application proxy that routes requests to the right service. It sends all requests for `localhost/api/*` to the backend, requests for `localhost/*` to the frontend, and then requests for `db.localhost` to phpMyAdmin. This provides the ability to access all applications using port 80 (instead of different ports for each service). - -With this environment, you as the developer don’t need to install or configure any services, populate a database schema, configure database credentials, or anything. You only need Docker Desktop. The rest just works. - -## Make changes to the app - -With this environment up and running, you’re ready to make a few changes to the application and see how Docker helps provide a fast feedback loop. - -### Change the greeting - -The greeting at the top of the page is populated by an API call at `/api/greeting`. Currently, it always returns "Hello world!". You’ll now modify it to return one of three randomized messages (that you'll get to choose). - -1. Open the `backend/src/routes/getGreeting.js` file in a text editor on - your local machine (in the cloned project directory). This file provides - the handler for the API endpoint. Your changes will automatically sync to - the running container. - -2. Modify the variable at the top to an array of greetings. Feel free to use the following modifications or customize it to your own liking. Also, update the endpoint to send a random greeting from this list. - - ```js {linenos=table,hl_lines=["1-5",9],linenostart=1} - const GREETINGS = [ - "Whalecome!", - "All hands on deck!", - "Charting the course ahead!", - ]; - - module.exports = async (req, res) => { - res.send({ - greeting: GREETINGS[Math.floor(Math.random() * GREETINGS.length)], - }); - }; - ``` - -3. If you haven't done so yet, save the file. If you refresh your browser, you should see a new greeting. If you keep refreshing, you should see all of the messages appear. - - ![Screenshot of the to-do app with a new greeting](images/develop-app-with-greetings.webp) - -### Change the placeholder text - -When you look at the app, you'll see the placeholder text is simply "New Item". You’ll now make that a little more descriptive and fun. You’ll also make a few changes to the styling of the app too. - -1. Open the `client/src/components/AddNewItemForm.jsx` file in your local - project directory. This provides the component to add a new item to the - to-do list. - -2. Modify the `placeholder` attribute of the `Form.Control` element to whatever you'd like to display. - - ```js {linenos=table,hl_lines=[5],linenostart=33} - <Form.Control - value={newItem} - onChange={(e) => setNewItem(e.target.value)} - type="text" - placeholder="What do you need to do?" - aria-label="New item" - /> - ``` - -3. Save the file and go back to your browser. You should see the change already hot-reloaded into your browser. If you don't like it, feel free to tweak it until it looks just right. - -![Screenshot of the to-do app with an updated placeholder in the add item text field"](images/develop-app-with-updated-placeholder.webp) - -### Change the background color - -Before you consider the application finalized, you need to make the colors better. - -1. Open the `client/src/index.scss` file in your local project directory. - -2. Adjust the `background-color` attribute to any color you'd like. The provided snippet is a soft blue to go along with Docker's nautical theme. - - If you're using an IDE, you can pick a color using the integrated color pickers. Otherwise, feel free to use an online [Color Picker](https://www.w3schools.com/colors/colors_picker.asp). - - ```css {linenos=table,hl_lines=2,linenostart=3} - body { - background-color: #99bbff; - margin-top: 50px; - font-family: "Lato"; - } - ``` - - Each save should let you see the change immediately in the browser. Keep adjusting it until it's the perfect setup for you. - - ![Screenshot of the to-do app with a new placeholder and background color"](images/develop-app-with-updated-client.webp) - -And with that, you're done. Congrats on updating your website. - -## Recap - -Before you move on, take a moment and reflect on what happened here. Within a few moments, you were able to: - -- Start a complete development project with zero installation effort. The containerized environment provided the development environment, ensuring you have everything you need. You didn't have to install Node, MySQL, or any of the other dependencies directly on your machine. All you needed was Docker Desktop and a code editor. - -- Make changes and see them immediately. This was made possible because - 1. the processes running in each container are watching and responding to - file changes and 2) the files in your local project directory are shared - with the containerized environment, so edits you make locally are - automatically synced to the containers. - -Docker Desktop enables all of this and so much more. Once you start thinking with containers, you can create almost any environment and easily share it with your team. - -## Next steps - -Now that the application has been updated, you’re ready to learn about packaging it as a container image and pushing it to a registry, specifically Docker Hub. - -{{< button text="Build and push your first image" url="build-and-push-first-image" >}} diff --git a/content/get-started/introduction/get-docker-desktop.md b/content/get-started/introduction/get-docker-desktop.md deleted file mode 100644 index f310736e82c7..000000000000 --- a/content/get-started/introduction/get-docker-desktop.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Get Docker Desktop -keywords: concepts, container, docker desktop -description: This concept page will teach you download Docker Desktop and install it on Windows, Mac, and Linux -summary: | - Getting Docker Desktop up and running is the first crucial step for - developers diving into containerization, offering a seamless and - user-friendly interface for managing Docker containers. Docker Desktop - simplifies the process of building, sharing, and running applications in - containers, ensuring consistency across different environments. -weight: 1 -aliases: - - /getting-started/get-docker-desktop/ ---- - -{{< youtube-embed C2bPVhiNU-0 >}} - -## Explanation - -Docker Desktop is the all-in-one package to build images, run containers, and so much more. -This guide will walk you through the installation process, enabling you to experience Docker Desktop firsthand. - - -> **Docker Desktop terms** -> -> Commercial use of Docker Desktop in larger enterprises (more than 250 -> employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs&refAction=DocsGetDockerDesktop). - -<div class="not-prose"> -{{< card - title="Docker Desktop for Mac" - description="[Download (Apple Silicon)](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64) | [Download (Intel)](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64) | [Install instructions](/desktop/setup/install/mac-install)" - icon="/icons/AppleMac.svg" >}} - -{{< card - title="Docker Desktop for Windows" - description="[Download](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows) | [Install instructions](/desktop/setup/install/windows-install)" - icon="/icons/Windows.svg" >}} - -{{< card - title="Docker Desktop for Linux" - description="[Install instructions](/desktop/setup/install/linux/)" - icon="/icons/Linux.svg" >}} -</div> - -Once it's installed, complete the setup process and you're all set to run a Docker container. - -## Try it out - -In this hands-on guide, you will see how to run a Docker container using Docker Desktop. - -Follow the instructions to run a container using the CLI. - - -## Run your first container - -Open your CLI terminal and start a container by running the `docker run` command: - - - -```console -$ docker run -d -p 8080:80 docker/welcome-to-docker -``` - -## Access the frontend - -For this container, the frontend is accessible on port `8080`. To open the website, visit [http://localhost:8080](http://localhost:8080) in your browser. - - - - - -![Screenshot of the landing page of the Nginx web server, coming from the running container](../docker-concepts/the-basics/images/access-the-frontend.webp?border=true) - -## Manage containers using Docker Desktop - - -1. Open Docker Desktop and select the **Containers** field on the left sidebar. -2. You can view information about your container including logs, and files, and even access the shell by selecting the **Exec** tab. - - ![Screenshot of exec into the running container in Docker Desktop](images/exec-into-docker-container.webp?border=true) - - -3. Select the **Inspect** field to obtain detailed information about the container. You can perform various actions such as pause, resume, start or stop containers, or explore the **Logs**, **Bind mounts**, **Exec**, **Files**, and **Stats** tabs. - -![Screenshot of inspecting the running container in Docker Desktop](images/inspecting-container.webp?border=true) - -Docker Desktop simplifies container management for developers by streamlining the setup, configuration, and compatibility of applications across different environments, thereby addressing the pain points of environment inconsistencies and deployment challenges. - -## What's next? - -Now that you have Docker Desktop installed and ran your first container, it's time to start developing with containers. - -{{< button text="Develop with containers" url="develop-with-containers" >}} diff --git a/content/get-started/introduction/images/build-vscode-menu-item.webp b/content/get-started/introduction/images/build-vscode-menu-item.webp deleted file mode 100644 index 160be98b8f2a..000000000000 Binary files a/content/get-started/introduction/images/build-vscode-menu-item.webp and /dev/null differ diff --git a/content/get-started/introduction/images/build-vscode-push-image.webp b/content/get-started/introduction/images/build-vscode-push-image.webp deleted file mode 100644 index 75c4cef04fa2..000000000000 Binary files a/content/get-started/introduction/images/build-vscode-push-image.webp and /dev/null differ diff --git a/content/get-started/introduction/images/clone-the-repo.webp b/content/get-started/introduction/images/clone-the-repo.webp deleted file mode 100644 index dbfce9d62a30..000000000000 Binary files a/content/get-started/introduction/images/clone-the-repo.webp and /dev/null differ diff --git a/content/get-started/introduction/images/develop-app-with-greetings.webp b/content/get-started/introduction/images/develop-app-with-greetings.webp deleted file mode 100644 index 2e5ff3137a83..000000000000 Binary files a/content/get-started/introduction/images/develop-app-with-greetings.webp and /dev/null differ diff --git a/content/get-started/introduction/images/develop-app-with-updated-client.webp b/content/get-started/introduction/images/develop-app-with-updated-client.webp deleted file mode 100644 index 348e87f2dca3..000000000000 Binary files a/content/get-started/introduction/images/develop-app-with-updated-client.webp and /dev/null differ diff --git a/content/get-started/introduction/images/develop-app-with-updated-placeholder.webp b/content/get-started/introduction/images/develop-app-with-updated-placeholder.webp deleted file mode 100644 index 80dce4645ddc..000000000000 Binary files a/content/get-started/introduction/images/develop-app-with-updated-placeholder.webp and /dev/null differ diff --git a/content/get-started/introduction/images/develop-getting-started-app-first-launch.webp b/content/get-started/introduction/images/develop-getting-started-app-first-launch.webp deleted file mode 100644 index d61ee3abf80e..000000000000 Binary files a/content/get-started/introduction/images/develop-getting-started-app-first-launch.webp and /dev/null differ diff --git a/content/get-started/introduction/images/exec-into-docker-container.webp b/content/get-started/introduction/images/exec-into-docker-container.webp deleted file mode 100644 index 3da6ac9f3e57..000000000000 Binary files a/content/get-started/introduction/images/exec-into-docker-container.webp and /dev/null differ diff --git a/content/get-started/introduction/images/inspecting-container.webp b/content/get-started/introduction/images/inspecting-container.webp deleted file mode 100644 index 5c2da7f9423e..000000000000 Binary files a/content/get-started/introduction/images/inspecting-container.webp and /dev/null differ diff --git a/content/get-started/introduction/images/install-docker-extension.webp b/content/get-started/introduction/images/install-docker-extension.webp deleted file mode 100644 index 75f3659d7cc8..000000000000 Binary files a/content/get-started/introduction/images/install-docker-extension.webp and /dev/null differ diff --git a/content/get-started/introduction/whats-next.md b/content/get-started/introduction/whats-next.md deleted file mode 100644 index 57f061009fc4..000000000000 --- a/content/get-started/introduction/whats-next.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: What's next -keywords: concepts, build, images, container, docker desktop -description: Explore step-by-step guides to help you understand core Docker concepts, building images, and running containers. -aliases: - - /guides/getting-started/whats-next/ -summary: | - Now that you have set up Docker Desktop, developed with containers, and built - and pushed your first image, you are ready to take the next step and dive - deep into what a container is and how it works. -notoc: true -weight: 4 - -the-basics: -- title: What is a container? - description: Learn how to run your first container. - link: /get-started/docker-concepts/the-basics/what-is-a-container/ -- title: What is an image? - description: Learn the basics of image layers. - link: /get-started/docker-concepts/the-basics/what-is-an-image/ -- title: What is a registry? - description: Learn about container registries, explore their interoperability, and interact with registries. - link: /get-started/docker-concepts/the-basics/what-is-a-registry/ -- title: What is Docker Compose? - description: Gain a better understanding of Docker Compose. - link: /get-started/docker-concepts/the-basics/what-is-docker-compose/ - -building-images: -- title: Understanding image layers - description: Learn about the layers of container images. - link: /get-started/docker-concepts/building-images/understanding-image-layers/ -- title: Writing a Dockerfile - description: Learn how to create an image using a Dockerfile. - link: /get-started/docker-concepts/building-images/writing-a-dockerfile/ -- title: Build, tag and publish an image - description: Learn how to build, tag, and publish an image to Docker Hub or any other registry. - link: /get-started/docker-concepts/building-images/build-tag-and-publish-an-image/ -- title: Using the build cache - description: Learn about the build cache, what changes invalidate the cache, and how to effectively use the build cache. - link: /get-started/docker-concepts/building-images/using-the-build-cache/ -- title: Multi-stage builds - description: Get a better understanding of multi-stage builds and their benefits. - link: /get-started/docker-concepts/building-images/multi-stage-builds/ - -running-containers: -- title: Publishing ports - description: Understand the significance of publishing and exposing ports in Docker. - link: /get-started/docker-concepts/running-containers/publishing-ports/ -- title: Overriding container defaults - description: Learn how to override the container defaults using the `docker run` command. - link: /get-started/docker-concepts/running-containers/overriding-container-defaults/ -- title: Persisting container data - description: Learn the significance of data persistence in Docker. - link: /get-started/docker-concepts/running-containers/persisting-container-data/ -- title: Sharing local files with containers - description: Explore the various storage options available in Docker and their common usage. - link: /get-started/docker-concepts/running-containers/sharing-local-files/ -- title: Multi-container applications - description: Learn the significance of multi-container applications and how they're different from single-container applications. - link: /get-started/docker-concepts/running-containers/multi-container-applications/ ---- - -The following sections provide step-by-step guides to help you understand core Docker concepts, building images, and running containers. - -## The basics - -Get started learning the core concepts of containers, images, registries, and Docker Compose. - -{{< grid items="the-basics" >}} - -## Building images - -Craft optimized container images with Dockerfiles, build cache, and multi-stage builds. - -{{< grid items="building-images" >}} - -## Running containers - -Master essential techniques for exposing ports, overriding defaults, persisting data, sharing files, and managing multi-container applications. - -{{< grid items="running-containers" >}} diff --git a/content/get-started/resources.md b/content/get-started/resources.md index 80130b590149..d394a85e5843 100644 --- a/content/get-started/resources.md +++ b/content/get-started/resources.md @@ -9,13 +9,17 @@ Docker and the broader community of Docker experts have put together many differ ## Docker Training -Learn Docker and containerization fundamentals through self-paced, [hands-on training courses](/get-started/introduction) created by Docker experts. +Start with the [containerization tutorial](/get-started/tutorials/run-an-app.md) +for a guided introduction to running, building, and sharing containerized +applications. ## Books If books are your preferred learning style, check out these written by the [Docker Captains](https://www.docker.com/community/captains). Docker Captain is a distinction that Docker awards to select members of the community that are both experts in their field and are committed to sharing their Docker knowledge with others. * [Operational AI with Docker](https://www.amazon.com/Operational-AI-Docker-services-Kubernetes/dp/1807301095), Ajeet Singh Raina & Harsh Manvar, April 2026 +* [Docker and Kubernetes Security](https://www.dockersecurity.io/), Mohammad-Ali A'râbi, October 2025. Get 50% discount on PDF version with the code `AHOYCAPTAIN` on [buy.DockerSecurity.io](https://buy.dockersecurity.io/). +* [Docker for React.js Developers](https://www.dockerfrontend.com/), Kristiyan Velkov. Learn Docker from a front-end perspective with practical, production-ready examples for modern React.js applications. Get **30% off** with the code `DOCKER30` at [www.dockerfrontend.com](https://www.dockerfrontend.com/) or [www.kristiyanvelkov.com](https://www.kristiyanvelkov.com) * [Learn Docker in a Month of Lunches](https://www.manning.com/books/learn-docker-in-a-month-of-lunches), Elton Stoneman. Use the code `stonemanpc` for a 40% discount. * [Docker on Windows: From 101 to Production with Docker on Windows](https://www.amazon.com/Docker-Windows-Elton-Stoneman-ebook/dp/B0711Y4J9K/), Elton Stoneman * [Learn Kubernetes in a Month of Lunches](https://www.manning.com/books/learn-kubernetes-in-a-month-of-lunches), Elton Stoneman. Use the code `stonemanpc` for a 40% discount. diff --git a/content/get-started/tutorials/_index.md b/content/get-started/tutorials/_index.md new file mode 100644 index 000000000000..7eaea9b52ae8 --- /dev/null +++ b/content/get-started/tutorials/_index.md @@ -0,0 +1,8 @@ +--- +title: Tutorials +description: Follow short tutorials for running applications, working with AI agents, and administering Docker. +keywords: Docker, get started, tutorials, containers, AI agents, administration +weight: 1 +build: + render: never +--- diff --git a/content/get-started/tutorials/admin-set-up.md b/content/get-started/tutorials/admin-set-up.md new file mode 100644 index 000000000000..f36f4513754e --- /dev/null +++ b/content/get-started/tutorials/admin-set-up.md @@ -0,0 +1,88 @@ +--- +title: Roll out Docker to a pilot group +linkTitle: Pilot an organization rollout +description: Invite a pilot user, apply a Docker Desktop settings policy, and verify the managed experience before a wider deployment. +keywords: Docker, get started, administration, organization setup, pilot deployment, Settings Management +weight: 3 +--- + +Rolling out Docker across an organization changes how developers sign in and +how Docker Desktop behaves. Testing the managed experience with a small group +helps uncover access or workflow problems before they affect everyone. + +In this 15-minute tutorial, you'll invite one pilot user, apply one managed +setting to that user, and confirm that Docker Desktop receives the policy. + +## Before you start + +You need: + +- A Docker Business subscription +- Owner access to a Docker organization +- A [verified company domain](/manuals/security/authentication/single-sign-on/connect.md#step-1-add-a-domain) +- [Enforced Docker Desktop sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) +- One pilot user with Docker Desktop installed + +## Invite the pilot user + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Select **Members**, then **Invite**. +1. Select **Emails or usernames** and enter the pilot user's email address. +1. Assign the **Member** role and a Docker Desktop license, then send the + invitation. +1. Have the pilot user accept the invitation from the email or the + **Notifications Center**. + +The pilot user is now part of the organization and can receive its Docker +Desktop policies. + +## Create a pilot policy + +1. In Docker Home, select **Docker Desktop**, then **Settings Management**. +1. Select **Create a settings policy**. +1. Name the policy `Docker pilot`. +1. Apply the policy to **Specific users**, then select the pilot user. +1. Set **Automatically update components** to **Always enabled**. Leave the + other settings as **User-defined**. +1. Select **Create**. + +This policy locks one low-impact setting, making the result visible without +changing the pilot user's development workflow. + +## Apply and verify the policy + +Ask the pilot user to: + +1. Quit Docker Desktop completely. +1. Start Docker Desktop and sign in with the account that joined the + organization. +1. Open Docker Desktop settings and confirm that **Automatically update + components** is enabled and can't be changed. +1. Run a familiar development project to confirm their normal workflow still + works. + +Docker Desktop checks for policy updates when it starts and every 60 minutes +while running. Fully quitting and reopening it applies the policy without +waiting for the next check. + +## What you learned + +You added a user, targeted a policy, and verified the managed Docker +Desktop experience before applying controls across the organization. Use the +pilot's feedback to refine the policy and its deployment communication. + +## What's next + +Continue with these guides when you're ready to expand the deployment: + +- [Set up your company for success with Docker](/guides/admin-set-up/) for the + full deployment handbook +- [Manage organization members](/manuals/accounts/organization/manage/members.md) + for roles, teams, and bulk invitations +- [Configure Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) + for additional policies and deployment controls +- [Set up SSO and provisioning](/manuals/security/authentication/single-sign-on/_index.md) + for centralized identity management +- [Govern Docker Sandboxes](/manuals/ai/sandboxes/governance/_index.md) for + organization-wide agent policies diff --git a/content/get-started/tutorials/run-an-agent.md b/content/get-started/tutorials/run-an-agent.md new file mode 100644 index 000000000000..820b19f28f5a --- /dev/null +++ b/content/get-started/tutorials/run-an-agent.md @@ -0,0 +1,152 @@ +--- +title: Run your coding agent in a sandbox +linkTitle: Sandbox a coding agent +description: Move your existing AI coding agent workflow into a disposable Docker Sandbox. +keywords: Docker, get started, AI agents, coding agents, Docker Sandboxes, sbx, sandbox, YOLO mode +weight: 2 +aliases: + - /get-started/run-an-agent/ +--- + +Coding agents can work faster in full-autonomy modes that let them run commands, +install tools, and use Docker without stopping for approval. Giving an agent +that access directly on your machine also gives mistakes a wider reach. + +Docker Sandboxes change where the agent runs, not how you work with it. The +agent gets a private environment with its own operating system and Docker +daemon. Your project remains available on your host, while tools the agent +installs and system changes it makes stay inside an environment you can +discard. + +> [!NOTE] +> Familiar with containers? See [how Docker Sandboxes differ from containers][sandboxes-vs-containers]. + +[sandboxes-vs-containers]: https://www.docker.com/products/docker-sandboxes/vs-containers/ + +In this tutorial, you'll move an existing coding-agent workflow into a local +sandbox. For a cloud workflow, see +[Get started with cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md#get-started). + +## Before you start + +- Have a project directory for the agent to work with +- Have access to a [supported coding agent](/manuals/ai/sandboxes/agents/_index.md) + +You don't need Docker Desktop or Docker Engine on your host. + +## Install and sign in + +[Install Docker Sandboxes](/manuals/ai/sandboxes/install.md) for your operating +system, then sign in to Docker: + +```console +$ sbx login +``` + +## Bring your agent setup + +This step is optional. Skip it if you want to start with a clean agent setup. + +If you use agent skills on your host, preview and import them: + +```console +$ sbx skills import --dry-run +$ sbx skills import +``` + +Imported skills become available to supported agents across your sandboxes. +This feature is experimental. See +[Share agent skills](/manuals/ai/sandboxes/workflows/agent-skills.md) for +supported agents and security considerations. + +## Choose how to authenticate + +Your agent needs access to a model provider. Subscription sign-in uses OAuth, +while API keys are stored on your host and supplied to the agent through the +sandbox proxy. Choose your agent and authentication method for the preparation +steps: + +{{< sandbox-auth >}} + +If you already exported a supported API key in your shell, you can import it +instead of setting it separately: + +```console +$ sbx secret import --dry-run +$ sbx secret import +``` + +The dry run shows which exported keys `sbx` found. The import command prompts +you to confirm each key before storing it. If the dry run finds nothing, use +the `sbx secret set` command from the picker. See +[Credentials](/manuals/ai/sandboxes/configuration/credentials.md) for other +secret sources and [supported coding agents](/manuals/ai/sandboxes/agents/_index.md) +for agent-specific authentication. + +## Run your agent + +Open your project and start your preferred agent. This example uses Codex: + +```console +$ cd ~/my-project +$ sbx run --name my-project codex +``` + +Replace `codex` with another supported agent identifier, such as `claude`, +`copilot`, `cursor`, or `gemini`. + +The first time you run a sandbox, `sbx` asks you to choose a default network +policy. This policy controls which external services your sandboxes can reach. +Select **Balanced** to permit common development services and block other +destinations by default. You can change these rules later with +[`sbx policy`](/manuals/ai/sandboxes/governance/access-controls/local.md). + +The built-in integrations start coding agents in their full-autonomy mode. For +example, Codex bypasses approvals, Claude Code skips permission prompts, and +Cursor, Copilot, and Gemini use YOLO mode. You don't need to add those flags. + +Give the agent the same task you would give it on your host. Source changes +appear in your working tree, so you can inspect them with your usual tools: + +```console +$ git diff +``` + +Your project directory is the exception to the sandbox boundary. It is shared +read-write, so the agent can modify or delete its files and you can see those +changes immediately. Keep your work under version control. Tools the agent +installs and changes to the sandbox's operating system stay inside the sandbox. + +## Return or start over + +Exit the agent when you're finished. Reconnect to the same environment later: + +```console +$ sbx run --name my-project +``` + +When you want a clean environment, remove the sandbox: + +```console +$ sbx rm my-project +``` + +Removing the sandbox deletes the environment and everything installed inside +it. It doesn't delete your project directory. + +## What changed + +You kept your project, agent, skills, credentials, and prompting workflow. The +only essential change was launching the agent with `sbx run`. That moved its +full-autonomy execution into an environment you control and can throw away. + +## What's next + +Continue with the Docker Sandboxes manuals: + +- [Manage your sandboxes](/manuals/ai/sandboxes/usage.md) with day-to-day + commands +- [Configure your coding agent](/manuals/ai/sandboxes/agents/_index.md) for its + authentication and settings +- [Review the security defaults](/manuals/ai/sandboxes/security/defaults.md) for + workspace, network, and credential access diff --git a/content/get-started/tutorials/run-an-app.md b/content/get-started/tutorials/run-an-app.md new file mode 100644 index 000000000000..33dff91d92fe --- /dev/null +++ b/content/get-started/tutorials/run-an-app.md @@ -0,0 +1,220 @@ +--- +title: Build and share a containerized application +linkTitle: Containerize an application +description: Run a container and an application stack, build an image, and share it through Docker Hub. +keywords: Docker, get started, containerize application, containers, Docker Compose, images, Docker Hub +weight: 1 +aliases: + - /get-started/run-an-app/ + - /get-started/introduction/ + - /get-started/introduction/develop-with-containers/ + - /get-started/introduction/build-and-push-first-image/ + - /get-started/introduction/whats-next/ + - /guides/getting-started/ + - /guides/getting-started/develop-with-containers/ + - /guides/getting-started/build-and-push-first-image/ + - /guides/getting-started/whats-next/ + - /guides/get-started/ + - /get-started/hands-on-overview/ + - /guides/workshop/ + - /get-started/workshop/ + - /get-started/part2/ + - /get-started/02_our_app/ + - /guides/workshop/02_our_app/ + - /guides/walkthroughs/containerize-your-app/ + - /get-started/workshop/02_our_app/ + - /get-started/03_updating_app/ + - /guides/workshop/03_updating_app/ + - /get-started/workshop/03_updating_app/ + - /get-started/part3/ + - /get-started/04_sharing_app/ + - /guides/workshop/04_sharing_app/ + - /get-started/workshop/04_sharing_app/ + - /get-started/05_persisting_data/ + - /guides/workshop/05_persisting_data/ + - /get-started/workshop/05_persisting_data/ + - /guides/walkthroughs/access-local-folder/ + - /get-started/06_bind_mounts/ + - /guides/workshop/06_bind_mounts/ + - /get-started/workshop/06_bind_mounts/ + - /get-started/07_multi_container/ + - /guides/workshop/07_multi_container/ + - /get-started/workshop/07_multi_container/ + - /get-started/08_using_compose/ + - /guides/workshop/08_using_compose/ + - /get-started/workshop/08_using_compose/ + - /get-started/09_image_best/ + - /guides/workshop/09_image_best/ + - /get-started/workshop/09_image_best/ + - /get-started/11_what_next/ + - /guides/workshop/10_what_next/ + - /get-started/workshop/10_what_next/ +--- + +An application can depend on a particular runtime, libraries, database, and +supporting tools. Docker packages these dependencies with the application so +you can run it consistently without preparing each machine by hand. + +In this 15-minute tutorial, you'll run a container, start a multi-container +application, package the application as an image, and share the image through +Docker Hub. + +## Before you start + +- [Install Docker Desktop](../get-docker.md) and start it +- Install [Git](https://git-scm.com/downloads) +- Create a [Docker account](https://app.docker.com/signup) + +## Run a container + +Start with a small web application that someone else has packaged for Docker. +Docker distributes applications in images. An image is a ready-to-run package +that contains an application and everything it needs. A container is a running +instance of an image. + +Download the image from Docker Hub: + +```console +$ docker pull docker/welcome-to-docker +``` + +Start a container from the image: + +```console +$ docker run --detach --name welcome --publish 8080:80 docker/welcome-to-docker +``` + +This command runs the container in the background (`--detach`), names it +`welcome` (`--name`), and makes its web server available at port 8080 on your +machine (`--publish 8080:80`). The final argument identifies the image to run. + +Open [http://localhost:8080](http://localhost:8080) to see the application. +You downloaded an image and started one container from it. + +Remove the container before continuing: + +```console +$ docker rm --force welcome +``` + +This removes the running application. The image remains available locally, so +Docker can create another container from it later. + +## Run an application stack + +The first application needed only one container. Applications often have +several parts, such as a frontend, an API, and a database. You could start each +part with a separate `docker run` command, but you would also need to keep their +configuration and connections in sync. + +Docker Compose describes all the parts of an application in a `compose.yaml` +file and manages them together. Compose is included with Docker Desktop. + +Try it with a prepared to-do application. Clone the project and open its +directory: + +```console +$ git clone https://github.com/docker/getting-started-todo-app +$ cd getting-started-todo-app +``` + +The project's `compose.yaml` file defines five services: a frontend, an API, a +database, a database management interface, and a proxy. A service represents +one part of the application and runs in its own container. + +Start the complete development stack: + +```console +$ docker compose up --build --detach +``` + +The `docker compose up` command reads `compose.yaml` and starts its services. +The `--build` option builds the frontend and API images from the project, and +`--detach` leaves the containers running in the background. Compose also pulls +the images for the supporting services and connects the containers. + +Open [http://localhost](http://localhost), then add an item to the to-do list. + +See the containers that Compose started: + +```console +$ docker compose ps +``` + +Each row represents a container for one of the application's services. Instead +of preserving a collection of commands, the project keeps the complete stack +in one version-controlled definition. + +## Build an image + +So far, you have run a published image and used Compose to build and manage a +development stack. Next, build an image of your own that packages the to-do +application's frontend and API together. + +The repository contains a `Dockerfile`, which is a set of instructions for +building the image. Replace `<YOUR_DOCKER_USERNAME>` with your Docker username, +then run: + +```console +$ docker build --tag <YOUR_DOCKER_USERNAME>/getting-started-todo-app . +``` + +The `--tag` option gives the image a name. The username prefix identifies where +the image will be stored on Docker Hub. The final `.` tells Docker to find the +`Dockerfile` and application source in the current directory. + +Create a container from your image, as you did with the welcome image: + +```console +$ docker run --detach --name todo --publish 8080:3000 <YOUR_DOCKER_USERNAME>/getting-started-todo-app +``` + +Open [http://localhost:8080](http://localhost:8080). This time, the frontend and +API are running together from the image you built. + +## Share the image + +Images can be shared through a registry. Docker Hub is a registry for storing +images and making them available to other machines and deployment systems. + +In [Docker Home](https://app.docker.com), create a public repository named +`getting-started-todo-app` under your Docker username. + +Sign in from the command line, then push the image: + +```console +$ docker login +$ docker push <YOUR_DOCKER_USERNAME>/getting-started-todo-app +``` + +The `docker push` command uploads the image to Docker Hub. Open the repository +in Docker Home to see it. Another machine or deployment system can pull and run +the same image. + +## Clean up + +Remove the standalone container and the development stack: + +```console +$ docker rm --force todo +$ docker compose down --volumes +``` + +## What you learned + +You ran software packaged by someone else, started a multi-container +application with Compose, built your own image, and published it. An image +packages an application, a container runs that image, Compose coordinates +multiple containers, and a registry makes images available beyond one machine. + +## What's next + +Explore the concepts from this tutorial in more detail: + +- [What is a container?](../docker-concepts/the-basics/what-is-a-container.md) +- [What is an image?](../docker-concepts/the-basics/what-is-an-image.md) +- [What is Docker Compose?](../docker-concepts/the-basics/what-is-docker-compose.md) +- [What is a registry?](../docker-concepts/the-basics/what-is-a-registry.md) + +Choose a language-specific [Docker guide](/guides/) to containerize an +application of your own. diff --git a/content/get-started/workshop/02_our_app.md b/content/get-started/workshop/02_our_app.md deleted file mode 100644 index 6d1456123797..000000000000 --- a/content/get-started/workshop/02_our_app.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Containerize an application -weight: 20 -linkTitle: "Part 1: Containerize an application" -keywords: | - dockerfile example, Containerize an application, run docker file, running - docker file, how to run dockerfile, example dockerfile, how to create a docker container, - create dockerfile, simple dockerfile, creating containers -description: | - Follow this step-by-step guide to learn how to create and run a containerized - application using Docker -aliases: - - /get-started/part2/ - - /get-started/02_our_app/ - - /guides/workshop/02_our_app/ - - /guides/walkthroughs/containerize-your-app/ ---- - -For the rest of this guide, you'll be working with a simple todo -list manager that runs on Node.js. If you're not familiar with Node.js, -don't worry. This guide doesn't require any prior experience with JavaScript. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have installed a [Git client](https://git-scm.com/downloads). -- You have an IDE or a text editor to edit files. Docker recommends using [Visual Studio Code](https://code.visualstudio.com/). - -## Get the app - -Before you can run the application, you need to get the application source code onto your machine. - -1. Clone the [getting-started-app repository](https://github.com/docker/getting-started-app/tree/main) using the following command: - - ```console - $ git clone https://github.com/docker/getting-started-app.git - ``` - -2. View the contents of the cloned repository. You should see the following files and sub-directories. - - ```text - ├── getting-started-app/ - │ ├── .dockerignore - │ ├── package.json - │ ├── package-lock.json - │ ├── README.md - │ ├── spec/ - │ ├── src/ - ``` - -## Build the app's image - -To build the image, you'll need to use a Dockerfile. A Dockerfile is simply a text-based file with no file extension that contains a script of instructions. Docker uses this script to build a container image. - -1. In the `getting-started-app` directory, the same location as the - `package.json` file, create a file named `Dockerfile` with the following contents: - - ```dockerfile - # syntax=docker/dockerfile:1 - - FROM node:24-alpine - WORKDIR /app - COPY . . - RUN npm install --omit=dev - CMD ["node", "src/index.js"] - EXPOSE 3000 - ``` - This Dockerfile does the following: - - - Uses `node:24-alpine` as the base image, a lightweight Linux image with Node.js pre-installed - - Sets `/app` as the working directory - - Copies source code into the image - - Installs the necessary dependencies - - Specifies the command to start the application - - Documents that the app listens on port 3000 - -2. Build the image using the following commands: - - In the terminal, make sure you're in the `getting-started-app` directory. Replace `/path/to/getting-started-app` with the path to your `getting-started-app` directory. - - ```console - $ cd /path/to/getting-started-app - ``` - - Build the image. - - ```console - $ docker build -t getting-started . - ``` - - The `docker build` command uses the Dockerfile to build a new image. You might have noticed that Docker downloaded a lot of "layers". This is because you instructed the builder that you wanted to start from the `node:24-alpine` image. But, since you didn't have that on your machine, Docker needed to download the image. - - After Docker downloaded the image, the instructions from the Dockerfile copied in your application and used `npm` to install your application's dependencies. - - Finally, the `-t` flag tags your image. Think of this as a human-readable name for the final image. Since you named the image `getting-started`, you can refer to that image when you run a container. - - The `.` at the end of the `docker build` command tells Docker that it should look for the `Dockerfile` in the current directory. - -## Start an app container - -Now that you have an image, you can run the application in a container using the `docker run` command. - -1. Run your container using the `docker run` command and specify the name of the image you just created: - - ```console - $ docker run -d -p 127.0.0.1:3000:3000 getting-started - ``` - - The `-d` flag (short for `--detach`) runs the container in the background. - This means that Docker starts your container and returns you to the terminal - prompt. Also, it does not display logs in the terminal. - - The `-p` flag (short for `--publish`) creates a port mapping between the - host and the container. The `-p` flag takes a string value in the format of - `HOST:CONTAINER`, where `HOST` is the address on the host, and `CONTAINER` - is the port on the container. The command publishes the container's port - 3000 to `127.0.0.1:3000` (`localhost:3000`) on the host. Without the port - mapping, you wouldn't be able to access the application from the host. - -2. After a few seconds, open your web browser to [http://localhost:3000](http://localhost:3000). - You should see your app. - - ![Empty todo list](images/todo-list-empty.webp) - -3. Add an item or two and see that it works as you expect. You can mark items as complete and remove them. Your frontend is successfully storing items in the backend. - -At this point, you have a running todo list manager with a few items. - -If you take a quick look at your containers, you should see at least one container running that's using the `getting-started` image and on port `3000`. To see your containers, you can use the CLI or Docker Desktop's graphical interface. - -{{< tabs >}} -{{< tab name="CLI" >}} - -Run the `docker ps` command in a terminal to list your containers. - -```console -$ docker ps -``` - -Output similar to the following should appear. - -```console -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -df784548666d getting-started "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 127.0.0.1:3000->3000/tcp priceless_mcclintock -``` - -{{< /tab >}} -{{< tab name="Docker Desktop" >}} - -In Docker Desktop, select the **Containers** tab to see a list of your containers. - -![Docker Desktop with get-started container running](images/dashboard-two-containers.webp) - -{{< /tab >}} -{{< /tabs >}} - -## Summary - -In this section, you learned the basics about creating a Dockerfile to build an image. Once you built an image, you started a container and saw the running app. - -Related information: - -- [Dockerfile reference](/reference/dockerfile/) -- [docker CLI reference](/reference/cli/docker/) - -## Next steps - -Next, you're going to make a modification to your app and learn how to update your running application with a new image. Along the way, you'll learn a few other useful commands. - -{{< button text="Update the application" url="03_updating_app.md" >}} diff --git a/content/get-started/workshop/03_updating_app.md b/content/get-started/workshop/03_updating_app.md deleted file mode 100644 index 63c062cc3710..000000000000 --- a/content/get-started/workshop/03_updating_app.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Update the application -weight: 30 -linkTitle: "Part 2: Update the application" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop -description: Making changes to your application -aliases: - - /get-started/03_updating_app/ - - /guides/workshop/03_updating_app/ ---- - -In [part 1](./02_our_app.md), you containerized a todo application. In this part, you'll update the application and image. You'll also learn how to stop and remove a container. - -## Update the source code - -In the following steps, you'll change the "empty text" when you don't have any todo list items to "You have no todo items yet! Add one above!" - - -1. In the `src/static/js/app.js` file, update line 56 to use the new empty text. - - ```diff - - <p className="text-center">No items yet! Add one above!</p> - + <p className="text-center">You have no todo items yet! Add one above!</p> - ``` - -2. Build your updated version of the image, using the `docker build` command. - - ```console - $ docker build -t getting-started . - ``` - -3. Start a new container using the updated code. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 getting-started - ``` - -You probably saw an error like this: - -```console -docker: Error response from daemon: driver failed programming external connectivity on endpoint laughing_burnell -(bb242b2ca4d67eba76e79474fb36bb5125708ebdabd7f45c8eaf16caaabde9dd): Bind for 127.0.0.1:3000 failed: port is already allocated. -``` - -The error occurred because you aren't able to start the new container while your old container is still running. The reason is that the old container is already using the host's port 3000 and only one process on the machine (containers included) can listen to a specific port. To fix this, you need to remove the old container. - -## Remove the old container - -To remove a container, you first need to stop it. Once it has stopped, you can remove it. You can remove the old container using the CLI or Docker Desktop's graphical interface. Choose the option that you're most comfortable with. - -{{< tabs >}} -{{< tab name="CLI" >}} - -### Remove a container using the CLI - -1. Get the ID of the container by using the `docker ps` command. - - ```console - $ docker ps - ``` - -2. Use the `docker stop` command to stop the container. Replace `<the-container-id>` with the ID from `docker ps`. - - ```console - $ docker stop <the-container-id> - ``` - -3. Once the container has stopped, you can remove it by using the `docker rm` command. - - ```console - $ docker rm <the-container-id> - ``` - -> [!NOTE] -> -> You can stop and remove a container in a single command by adding the `force` flag to the `docker rm` command. For example: `docker rm -f <the-container-id>` - -{{< /tab >}} -{{< tab name="Docker Desktop" >}} - -### Remove a container using Docker Desktop - -1. Open Docker Desktop to the **Containers** view. -2. Select the trash can icon under the **Actions** column for the container that you want to delete. -3. In the confirmation dialog, select **Delete forever**. - -{{< /tab >}} -{{< /tabs >}} - -### Start the updated app container - -1. Now, start your updated app using the `docker run` command. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 getting-started - ``` - -2. Refresh your browser on [http://localhost:3000](http://localhost:3000) and you should see your updated help text. - -## Summary - -In this section, you learned how to update and rebuild an image, as well as how to stop and remove a container. - -Related information: - - [docker CLI reference](/reference/cli/docker/) - -## Next steps - -Next, you'll learn how to share images with others. - -{{< button text="Share the application" url="04_sharing_app.md" >}} diff --git a/content/get-started/workshop/04_sharing_app.md b/content/get-started/workshop/04_sharing_app.md deleted file mode 100644 index bd5c16326b4d..000000000000 --- a/content/get-started/workshop/04_sharing_app.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Share the application -weight: 40 -linkTitle: "Part 3: Share the application" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop, docker hub, sharing -description: Sharing your image you built for your example application so you can - run it else where and other developers can use it -aliases: - - /get-started/part3/ - - /get-started/04_sharing_app/ - - /guides/workshop/04_sharing_app/ ---- - -Now that you've built an image, you can share it. To share Docker images, you have to use a Docker -registry. The default registry is Docker Hub and is where all of the images you've used have come from. - -> **Docker ID** -> -> A Docker ID lets you access Docker Hub, which is the world's largest library and community for container images. Create a [Docker ID](https://hub.docker.com/signup) for free if you don't have one. - -## Create a repository - -To push an image, you first need to create a repository on Docker Hub. - -1. [Sign up](https://www.docker.com/pricing?ref=Docs&refAction=DocsSharingApp) or Sign in to [Docker Hub](https://hub.docker.com). - -2. Select the **Create Repository** button. - -3. For the repository name, use `getting-started`. Make sure the **Visibility** is **Public**. - -4. Select **Create**. - -In the following image, you can see an example Docker command from Docker Hub. This command will push to this repository. - -![Docker command with push example](images/push-command.webp) - - -## Push the image - -Let's try to push the image to Docker Hub. - -1. In the command line, run the following command: - - ```console - docker push docker/getting-started - ``` - - You'll see an error like this: - - ```console - $ docker push docker/getting-started - The push refers to repository [docker.io/docker/getting-started] - An image does not exist locally with the tag: docker/getting-started - ``` - - This failure is expected because the image isn't tagged correctly yet. - Docker is looking for an image name `docker/getting-started`, but your - local image is still named `getting-started`. - - You can confirm this by running: - - ```console - docker image ls - ``` - -2. To fix this, first sign in to Docker Hub using your Docker ID: `docker login -u YOUR-USER-NAME`. -3. Use the `docker tag` command to give the `getting-started` image a new name. Replace `YOUR-USER-NAME` with your Docker ID. - - ```console - $ docker tag getting-started YOUR-USER-NAME/getting-started - ``` - -4. Now run the `docker push` command again. If you're copying the value from - Docker Hub, you can drop the `tagname` part, as you didn't add a tag to the - image name. If you don't specify a tag, Docker uses a tag called `latest`. - - ```console - $ docker push YOUR-USER-NAME/getting-started - ``` - -## Run the image on a new instance - -Now that your image has been built and pushed into a registry, you can run your app on any machine that has Docker installed. Try pulling and running your image on another computer or a cloud instance. - -## Summary - -In this section, you learned how to share your images by pushing them to a -registry. You then went to a brand new instance and were able to run the freshly -pushed image. This is quite common in CI pipelines, where the pipeline will -create the image and push it to a registry and then the production environment -can use the latest version of the image. - -Related information: - - - [docker CLI reference](/reference/cli/docker/) - - [Multi-platform images](/manuals/build/building/multi-platform.md) - - [Docker Hub overview](/manuals/docker-hub/_index.md) - -## Next steps - -In the next section, you'll learn how to persist data in your containerized application. - -{{< button text="Persist the DB" url="05_persisting_data.md" >}} diff --git a/content/get-started/workshop/05_persisting_data.md b/content/get-started/workshop/05_persisting_data.md deleted file mode 100644 index 43501ce516c7..000000000000 --- a/content/get-started/workshop/05_persisting_data.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Persist the DB -weight: 50 -linkTitle: "Part 4: Persist the DB" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop -description: Making your DB persistent in your application -aliases: - - /get-started/05_persisting_data/ - - /guides/workshop/05_persisting_data/ ---- - -In case you didn't notice, your todo list is empty every single time -you launch the container. Why is this? In this part, you'll dive into how the container is working. - -## The container's filesystem - -When a container runs, it uses the various layers from an image for its filesystem. -Each container also gets its own "scratch space" to create/update/remove files. Any -changes won't be seen in another container, even if they're using the same image. - -### See this in practice - -To see this in action, you're going to start two containers. In one container, -you'll create a file. In the other container, you'll check whether that same -file exists. - -1. Start an Alpine container and create a new file in it. - - ```console - $ docker run --rm alpine touch greeting.txt - ``` - - > [!TIP] - > Any commands you specify after the image name (in this case, `alpine`) - > are executed inside the container. In this case, the command `touch - > greeting.txt` puts a file named `greeting.txt` on the container's filesystem. - -2. Run a new Alpine container and use the `stat` command to check whether the file exists. - - ```console - $ docker run --rm alpine stat greeting.txt - ``` - - You should see output similar to the following that indicates the file does not exist in the new container. - - ```console - stat: can't stat 'greeting.txt': No such file or directory - ``` - -The `greeting.txt` file created by the first container did not exist in the -second container. That is because the writeable "top layer" of each container -is isolated. Even though both containers shared the same underlying layers that -make up the base image, the writable layer is unique to each container. - -## Container volumes - -With the previous experiment, you saw that each container starts from the image definition each time it starts. -While containers can create, update, and delete files, those changes are lost when you remove the container -and Docker isolates all changes to that container. With volumes, you can change all of this. - -[Volumes](/manuals/engine/storage/volumes.md) provide the ability to connect specific filesystem paths of -the container back to the host machine. If you mount a directory in the container, changes in that -directory are also seen on the host machine. If you mount that same directory across container restarts, you'd see -the same files. - -There are two main types of volumes. You'll eventually use both, but you'll start with volume mounts. - -## Persist the todo data - -By default, the todo app stores its data in a SQLite database at -`/etc/todos/todo.db` in the container's filesystem. If you're not familiar with SQLite, no worries! It's simply a relational database that stores all the data in a single file. While this isn't the best for large-scale applications, -it works for small demos. You'll learn how to switch this to a different database engine later. - -With the database being a single file, if you can persist that file on the host and make it available to the -next container, it should be able to pick up where the last one left off. By creating a volume and attaching -(often called "mounting") it to the directory where you stored the data, you can persist the data. As your container -writes to the `todo.db` file, it will persist the data to the host in the volume. - -As mentioned, you're going to use a volume mount. Think of a volume mount as an opaque bucket of data. -Docker fully manages the volume, including the storage location on disk. You only need to remember the -name of the volume. - -### Create a volume and start the container - -You can create the volume and start the container using the CLI or Docker Desktop's graphical interface. - -{{< tabs >}} -{{< tab name="CLI" >}} - -1. Create a volume by using the `docker volume create` command. - - ```console - $ docker volume create todo-db - ``` - -2. Stop and remove the todo app container once again with `docker rm -f <id>`, - as it is still running without using the persistent volume. - -3. Start the todo app container, but add the `--mount` option to specify a - volume mount. Give the volume a name, and mount it to `/etc/todos` in the - container, which captures all files created at the path. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 --mount type=volume,src=todo-db,target=/etc/todos getting-started - ``` - - > [!NOTE] - > - > If you're using Git Bash, you must use different syntax for this command. - > - > ```console - > $ docker run -dp 127.0.0.1:3000:3000 --mount type=volume,src=todo-db,target=//etc/todos getting-started - > ``` - > - > For more details about Git Bash's syntax differences, see - > [Working with Git Bash](/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-commands-failing-in-git-bash). - - -{{< /tab >}} -{{< tab name="Docker Desktop" >}} - -To create a volume: - -1. Select **Volumes** in Docker Desktop. -2. In **Volumes**, select **Create**. -3. Specify `todo-db` as the volume name, and then select **Create**. - -To stop and remove the app container: - -1. Select **Containers** in Docker Desktop. -2. Select **Delete** in the **Actions** column for the container. - -To start the todo app container with the volume mounted: - -1. Select the search box at the top of Docker Desktop. -2. In the search window, select the **Images** tab. -3. In the search box, specify the image name, `getting-started`. - - > [!TIP] - > - > Use the search filter to filter images and only show **Local images**. - -4. Select your image and then select **Run**. -5. Select **Optional settings**. -6. In **Host port**, specify the port, for example, `3000`. -7. In **Host path**, specify the name of the volume, `todo-db`. -8. In **Container path**, specify `/etc/todos`. -9. Select **Run**. - -{{< /tab >}} -{{< /tabs >}} - -### Verify that the data persists - -1. Once the container starts up, open the app and add a few items to your todo list. - - ![Items added to todo list](images/items-added.webp) - - -2. Stop and remove the container for the todo app. Use Docker Desktop or `docker ps` to get the ID and then `docker rm -f <id>` to remove it. - -3. Start a new container using the previous steps. - -4. Open the app. You should see your items still in your list. - -5. Go ahead and remove the container when you're done checking out your list. - -You've now learned how to persist data. - -## Dive into the volume - -A lot of people frequently ask "Where is Docker storing my data when I use a volume?" If you want to know, -you can use the `docker volume inspect` command. - -```console -$ docker volume inspect todo-db -``` -You should see output like the following: -```console -[ - { - "CreatedAt": "2019-09-26T02:18:36Z", - "Driver": "local", - "Labels": {}, - "Mountpoint": "/var/lib/docker/volumes/todo-db/_data", - "Name": "todo-db", - "Options": {}, - "Scope": "local" - } -] -``` - -The `Mountpoint` is the actual location of the data on the disk. Note that on most machines, you will -need to have root access to access this directory from the host. - -## Summary - -In this section, you learned how to persist container data. - -Related information: - - - [docker CLI reference](/reference/cli/docker/) - - [Volumes](/manuals/engine/storage/volumes.md) - -## Next steps - -Next, you'll learn how you can develop your app more efficiently using bind mounts. - -{{< button text="Use bind mounts" url="06_bind_mounts.md" >}} diff --git a/content/get-started/workshop/06_bind_mounts.md b/content/get-started/workshop/06_bind_mounts.md deleted file mode 100644 index a664b5e7f575..000000000000 --- a/content/get-started/workshop/06_bind_mounts.md +++ /dev/null @@ -1,451 +0,0 @@ ---- -title: Use bind mounts -weight: 60 -linkTitle: "Part 5: Use bind mounts" -keywords: 'get started, setup, orientation, quickstart, intro, concepts, containers, docker desktop' -description: Using bind mounts in our application -aliases: - - /guides/walkthroughs/access-local-folder/ - - /get-started/06_bind_mounts/ - - /guides/workshop/06_bind_mounts/ ---- - -In [part 4](./05_persisting_data.md), you used a volume mount to persist the -data in your database. A volume mount is a great choice when you need somewhere -persistent to store your application data. - -A bind mount is another type of mount, which lets you share a directory from the -host's filesystem into the container. When working on an application, you can -use a bind mount to mount source code into the container. The container sees the -changes you make to the code immediately, as soon as you save a file. This means -that you can run processes in the container that watch for filesystem changes -and respond to them. - -In this chapter, you'll see how you can use bind mounts and a tool called -[nodemon](https://npmjs.com/package/nodemon) to watch for file changes, and then restart the application -automatically. There are equivalent tools in most other languages and -frameworks. - -## Quick volume type comparisons - -The following are examples of a named volume and a bind mount using `--mount`: - -- Named volume: `type=volume,src=my-volume,target=/usr/local/data` -- Bind mount: `type=bind,src=/path/to/data,target=/usr/local/data` - -The following table outlines the main differences between volume mounts and bind -mounts. - -| | Named volumes | Bind mounts | -| -------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------- | -| Host location | Docker chooses | You decide | -| Populates new volume with container contents | Yes | No | -| Supports Volume Drivers | Yes | No | - -## Trying out bind mounts - -Before looking at how you can use bind mounts for developing your application, -you can run a quick experiment to get a practical understanding of how bind mounts -work. - -1. Verify that your `getting-started-app` directory is in a directory defined in -Docker Desktop's file sharing setting. This setting defines which parts of your -filesystem you can share with containers. For details about accessing the setting, see [File sharing](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing). - - > [!NOTE] - > The **File sharing** tab is only available in Hyper-V mode, because the files are automatically shared in WSL 2 mode and Windows container mode. - -2. Open a terminal and change directory to the `getting-started-app` - directory. - -3. Run the following command to start `bash` in an `ubuntu` container with a - bind mount. - - {{< tabs >}} - {{< tab name="Mac / Linux" >}} - - ```console - $ docker run -it --mount type=bind,src=.,target=/src ubuntu bash - ``` - - {{< /tab >}} - {{< tab name="Command Prompt" >}} - - ```console - $ docker run -it --mount "type=bind,src=%cd%,target=/src" ubuntu bash - ``` - - {{< /tab >}} - {{< tab name="Git Bash" >}} - - ```console - $ docker run -it --mount type=bind,src="./",target=/src ubuntu bash - ``` - - {{< /tab >}} - {{< tab name="PowerShell" >}} - - ```console - $ docker run -it --mount "type=bind,src=.,target=/src" ubuntu bash - ``` - - {{< /tab >}} - {{< /tabs >}} - - The `--mount type=bind` option tells Docker to create a bind mount, where `src` is the - current working directory on your host machine (`getting-started-app`), and - `target` is where that directory should appear inside the container (`/src`). - -4. After running the command, Docker starts an interactive `bash` session in the - root directory of the container's filesystem. - - ```console - root@ac1237fad8db:/# pwd - / - root@ac1237fad8db:/# ls - bin dev home media opt root sbin srv tmp var - boot etc lib mnt proc run src sys usr - ``` - -5. Change directory to the `src` directory. - - This is the directory that you mounted when starting the container. Listing - the contents of this directory displays the same files as in the - `getting-started-app` directory on your host machine. - - ```console - root@ac1237fad8db:/# cd src - root@ac1237fad8db:/src# ls - Dockerfile node_modules package.json package-lock.json spec src - ``` - -6. Create a new file named `myfile.txt`. - - ```console - root@ac1237fad8db:/src# touch myfile.txt - root@ac1237fad8db:/src# ls - Dockerfile myfile.txt node_modules package.json package-lock.json spec src - ``` - -7. Open the `getting-started-app` directory on the host and observe that the - `myfile.txt` file is in the directory. - - ```text - ├── getting-started-app/ - │ ├── Dockerfile - │ ├── myfile.txt - │ ├── node_modules/ - │ ├── package.json - │ ├── package-lock.json - │ ├── spec/ - │ └── src/ - ``` - -8. From the host, delete the `myfile.txt` file. -9. In the container, list the contents of the `app` directory once more. Observe that the file is now gone. - - ```console - root@ac1237fad8db:/src# ls - Dockerfile node_modules package.json package-lock.json spec src - ``` - -10. Stop the interactive container session with `Ctrl` + `D`. - -That's all for a brief introduction to bind mounts. This procedure -demonstrated how files are shared between the host and the container, and how -changes are immediately reflected on both sides. Now you can use -bind mounts to develop software. - -## Development containers - -Using bind mounts is common for local development setups. The advantage is that the development machine doesn’t need to have all of the build tools and environments installed. With a single docker run command, Docker pulls dependencies and tools. - -### Run your app in a development container - -The following steps describe how to run a development container with a bind -mount that does the following: - -- Mount your source code into the container -- Install all dependencies -- Start `nodemon` to watch for filesystem changes - -You can use the CLI or Docker Desktop to run your container with a bind mount. - -{{< tabs >}} -{{< tab name="Mac / Linux CLI" >}} - -1. Make sure you don't have any `getting-started` containers currently running. - -2. Run the following command from the `getting-started-app` directory. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 \ - -w /app --mount type=bind,src=.,target=/app \ - node:24-alpine \ - sh -c "npm install && npm run dev" - ``` - - The following is a breakdown of the command: - - `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and - create a port mapping - - `-w /app` - sets the "working directory" or the current directory that the - command will run from - - `--mount type=bind,src=.,target=/app` - bind mount the current - directory from the host into the `/app` directory in the container - - `node:24-alpine` - the image to use. Note that this is the base image for - your app from the Dockerfile - - `sh -c "npm install && npm run dev"` - the command. You're starting a - shell using `sh` (alpine doesn't have `bash`) and running `npm install` to - install packages and then running `npm run dev` to start the development - server. If you look in the `package.json`, you'll see that the `dev` script - starts `nodemon`. - -3. You can watch the logs using `docker logs <container-id>`. You'll know you're - ready to go when you see this: - - ```console - $ docker logs -f <container-id> - nodemon -L src/index.js - [nodemon] 2.0.20 - [nodemon] to restart at any time, enter `rs` - [nodemon] watching path(s): *.* - [nodemon] watching extensions: js,mjs,json - [nodemon] starting `node src/index.js` - Using sqlite database at /etc/todos/todo.db - Listening on port 3000 - ``` - - When you're done watching the logs, exit out by hitting `Ctrl`+`C`. - -{{< /tab >}} -{{< tab name="PowerShell CLI" >}} - -1. Make sure you don't have any `getting-started` containers currently running. - -2. Run the following command from the `getting-started-app` directory. - - ```powershell - $ docker run -dp 127.0.0.1:3000:3000 ` - -w /app --mount "type=bind,src=.,target=/app" ` - node:24-alpine ` - sh -c "npm install && npm run dev" - ``` - - The following is a breakdown of the command: - - `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and - create a port mapping - - `-w /app` - sets the "working directory" or the current directory that the - command will run from - - `--mount "type=bind,src=.,target=/app"` - bind mount the current - directory from the host into the `/app` directory in the container - - `node:24-alpine` - the image to use. Note that this is the base image for - your app from the Dockerfile - - `sh -c "npm install && npm run dev"` - the command. You're starting a - shell using `sh` (alpine doesn't have `bash`) and running `npm install` to - install packages and then running `npm run dev` to start the development - server. If you look in the `package.json`, you'll see that the `dev` script - starts `nodemon`. - -3. You can watch the logs using `docker logs <container-id>`. You'll know you're - ready to go when you see this: - - ```console - $ docker logs -f <container-id> - nodemon -L src/index.js - [nodemon] 2.0.20 - [nodemon] to restart at any time, enter `rs` - [nodemon] watching path(s): *.* - [nodemon] watching extensions: js,mjs,json - [nodemon] starting `node src/index.js` - Using sqlite database at /etc/todos/todo.db - Listening on port 3000 - ``` - - When you're done watching the logs, exit out by hitting `Ctrl`+`C`. - -{{< /tab >}} -{{< tab name="Command Prompt CLI" >}} - -1. Make sure you don't have any `getting-started` containers currently running. - -2. Run the following command from the `getting-started-app` directory. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 ^ - -w /app --mount "type=bind,src=%cd%,target=/app" ^ - node:24-alpine ^ - sh -c "npm install && npm run dev" - ``` - - The following is a breakdown of the command: - - `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and - create a port mapping - - `-w /app` - sets the "working directory" or the current directory that the - command will run from - - `--mount "type=bind,src=%cd%,target=/app"` - bind mount the current - directory from the host into the `/app` directory in the container - - `node:24-alpine` - the image to use. Note that this is the base image for - your app from the Dockerfile - - `sh -c "npm install && npm run dev"` - the command. You're starting a - shell using `sh` (alpine doesn't have `bash`) and running `npm install` to - install packages and then running `npm run dev` to start the development - server. If you look in the `package.json`, you'll see that the `dev` script - starts `nodemon`. - -3. You can watch the logs using `docker logs <container-id>`. You'll know you're - ready to go when you see this: - - ```console - $ docker logs -f <container-id> - nodemon -L src/index.js - [nodemon] 2.0.20 - [nodemon] to restart at any time, enter `rs` - [nodemon] watching path(s): *.* - [nodemon] watching extensions: js,mjs,json - [nodemon] starting `node src/index.js` - Using sqlite database at /etc/todos/todo.db - Listening on port 3000 - ``` - - When you're done watching the logs, exit out by hitting `Ctrl`+`C`. - -{{< /tab >}} -{{< tab name="Git Bash CLI" >}} - -1. Make sure you don't have any `getting-started` containers currently running. - -2. Run the following command from the `getting-started-app` directory. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 \ - -w //app --mount type=bind,src="./",target=/app \ - node:24-alpine \ - sh -c "npm install && npm run dev" - ``` - - The following is a breakdown of the command: - - `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and - create a port mapping - - `-w //app` - sets the "working directory" or the current directory that the - command will run from - - `--mount type=bind,src="/.",target=/app` - bind mount the current - directory from the host into the `/app` directory in the container - - `node:24-alpine` - the image to use. Note that this is the base image for - your app from the Dockerfile - - `sh -c "npm install && npm run dev"` - the command. You're starting a - shell using `sh` (alpine doesn't have `bash`) and running `npm install` to - install packages and then running `npm run dev` to start the development - server. If you look in the `package.json`, you'll see that the `dev` script - starts `nodemon`. - -3. You can watch the logs using `docker logs <container-id>`. You'll know you're - ready to go when you see this: - - ```console - $ docker logs -f <container-id> - nodemon -L src/index.js - [nodemon] 2.0.20 - [nodemon] to restart at any time, enter `rs` - [nodemon] watching path(s): *.* - [nodemon] watching extensions: js,mjs,json - [nodemon] starting `node src/index.js` - Using sqlite database at /etc/todos/todo.db - Listening on port 3000 - ``` - - When you're done watching the logs, exit out by hitting `Ctrl`+`C`. - -{{< /tab >}} -{{< tab name="Docker Desktop" >}} - -Make sure you don't have any `getting-started` containers currently running. - -Run the image with a bind mount. - -1. Select the search box at the top of Docker Desktop. -2. In the search window, select the **Images** tab. -3. In the search box, specify the container name, `getting-started`. - - > [!TIP] - > - > Use the search filter to filter images and only show **Local images**. - -4. Select your image and then select **Run**. -5. Select **Optional settings**. -6. In **Host path**, specify the path to the `getting-started-app` directory on your host machine. -7. In **Container path**, specify `/app`. -8. Select **Run**. - -You can watch the container logs using Docker Desktop. - -1. Select **Containers** in Docker Desktop. -2. Select your container name. - -You'll know you're ready to go when you see this: - -```console -nodemon -L src/index.js -[nodemon] 2.0.20 -[nodemon] to restart at any time, enter `rs` -[nodemon] watching path(s): *.* -[nodemon] watching extensions: js,mjs,json -[nodemon] starting `node src/index.js` -Using sqlite database at /etc/todos/todo.db -Listening on port 3000 -``` - -{{< /tab >}} -{{< /tabs >}} - -### Develop your app with the development container - -Update your app on your host machine and see the changes reflected in the container. - -1. In the `src/static/js/app.js` file, on line - 109, change the "Add Item" button to simply say "Add": - - ```diff - - {submitting ? 'Adding...' : 'Add Item'} - + {submitting ? 'Adding...' : 'Add'} - ``` - - Save the file. - -2. Refresh the page in your web browser, and you should see the change reflected - almost immediately because of the bind mount. Nodemon detects the change and - restarts the server. It might take a few seconds for the Node server to - restart. If you get an error, try refreshing after a few seconds. - - ![Screenshot of updated label for Add button](images/updated-add-button.webp) - -3. Feel free to make any other changes you'd like to make. Each time you make a - change and save a file, the change is reflected in the container because of - the bind mount. When Nodemon detects a change, it restarts the app inside the - container automatically. When you're done, stop the container and build your - new image using: - - ```console - $ docker build -t getting-started . - ``` - -## Summary - -At this point, you can persist your database and see changes in your app as you develop without rebuilding the image. - -In addition to volume mounts and bind mounts, Docker also supports other mount -types and storage drivers for handling more complex and specialized use cases. - -Related information: - - - [docker CLI reference](/reference/cli/docker/) - - [Manage data in Docker](https://docs.docker.com/storage/) - -## Next steps - -In order to prepare your app for production, you need to migrate your database -from working in SQLite to something that can scale a little better. For -simplicity, you'll keep using a relational database and switch your application -to use MySQL. But, how should you run MySQL? How do you allow the containers to -talk to each other? You'll learn about that in the next section. - -{{< button text="Multi container apps" url="07_multi_container.md" >}} diff --git a/content/get-started/workshop/07_multi_container.md b/content/get-started/workshop/07_multi_container.md deleted file mode 100644 index e9ebadcafecb..000000000000 --- a/content/get-started/workshop/07_multi_container.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: Multi container apps -weight: 70 -linkTitle: "Part 6: Multi-container apps" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop -description: Using more than one container in your application -aliases: - - /get-started/07_multi_container/ - - /guides/workshop/07_multi_container/ ---- - -Up to this point, you've been working with single container apps. But, now you will add MySQL to the -application stack. The following question often arises - "Where will MySQL run? Install it in the same -container or run it separately?" In general, each container should do one thing and do it well. The following are a few reasons to run the container separately: - -- There's a good chance you'd have to scale APIs and front-ends differently than databases. -- Separate containers let you version and update versions in isolation. -- While you may use a container for the database locally, you may want to use a managed service - for the database in production. You don't want to ship your database engine with your app then. -- Running multiple processes will require a process manager (the container only starts one process), which adds complexity to container startup/shutdown. - -And there are more reasons. So, like the following diagram, it's best to run your app in multiple containers. - -![Todo App connected to MySQL container](images/multi-container.webp?w=350h=250) - - -## Container networking - -Remember that containers, by default, run in isolation and don't know anything about other processes -or containers on the same machine. So, how do you allow one container to talk to another? The answer is -networking. If you place the two containers on the same network, they can talk to each other. - -## Start MySQL - -There are two ways to put a container on a network: - - Assign the network when starting the container. - - Connect an already running container to a network. - -In the following steps, you'll create the network first and then attach the MySQL container at startup. - -1. Create the network. - - ```console - $ docker network create todo-app - ``` - -2. Start a MySQL container and attach it to the network. You're also going to define a few environment variables that the - database will use to initialize the database. To learn more about the MySQL environment variables, see the "Environment Variables" section in the [MySQL Docker Hub listing](https://hub.docker.com/_/mysql/). - - {{< tabs >}} - {{< tab name="Mac / Linux / Git Bash" >}} - - ```console - $ docker run -d \ - --network todo-app --network-alias mysql \ - -v todo-mysql-data:/var/lib/mysql \ - -e MYSQL_ROOT_PASSWORD=secret \ - -e MYSQL_DATABASE=todos \ - mysql:8.0 - ``` - - {{< /tab >}} - {{< tab name="PowerShell" >}} - - ```powershell - $ docker run -d ` - --network todo-app --network-alias mysql ` - -v todo-mysql-data:/var/lib/mysql ` - -e MYSQL_ROOT_PASSWORD=secret ` - -e MYSQL_DATABASE=todos ` - mysql:8.0 - ``` - - {{< /tab >}} - {{< tab name="Command Prompt" >}} - - ```console - $ docker run -d ^ - --network todo-app --network-alias mysql ^ - -v todo-mysql-data:/var/lib/mysql ^ - -e MYSQL_ROOT_PASSWORD=secret ^ - -e MYSQL_DATABASE=todos ^ - mysql:8.0 - ``` - - {{< /tab >}} - {{< /tabs >}} - - In the previous command, you can see the `--network-alias` flag. In a later section, you'll learn more about this flag. - - > [!TIP] - > - > You'll notice a volume named `todo-mysql-data` in the above command that is mounted at `/var/lib/mysql`, which is where MySQL stores its data. However, you never ran a `docker volume create` command. Docker recognizes you want to use a named volume and creates one automatically for you. - -3. To confirm you have the database up and running, connect to the database and verify that it connects. - - ```console - $ docker exec -it <mysql-container-id> mysql -u root -p - ``` - - When the password prompt comes up, type in `secret`. In the MySQL shell, list the databases and verify - you see the `todos` database. - - ```console - mysql> SHOW DATABASES; - ``` - - You should see output that looks like this: - - ```plaintext - +--------------------+ - | Database | - +--------------------+ - | information_schema | - | mysql | - | performance_schema | - | sys | - | todos | - +--------------------+ - 5 rows in set (0.00 sec) - ``` - -4. Exit the MySQL shell to return to the shell on your machine. - - ```console - mysql> exit - ``` - - You now have a `todos` database and it's ready for you to use. - -## Connect to MySQL - -Now that you know MySQL is up and running, you can use it. But, how do you use it? If you run -another container on the same network, how do you find the container? Remember that each container has its own IP address. - -To answer the questions above and better understand container networking, you're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container, -which ships with a lot of tools that are useful for troubleshooting or debugging networking issues. - -1. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network. - - ```console - $ docker run -it --network todo-app nicolaka/netshoot - ``` - -2. Inside the container, you're going to use the `dig` command, which is a useful DNS tool. You're going to look up - the IP address for the hostname `mysql`. - - ```console - $ dig mysql - ``` - - You should get output like the following. - - ```text - ; <<>> DiG 9.18.8 <<>> mysql - ;; global options: +cmd - ;; Got answer: - ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32162 - ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0 - - ;; QUESTION SECTION: - ;mysql. IN A - - ;; ANSWER SECTION: - mysql. 600 IN A 172.23.0.2 - - ;; Query time: 0 msec - ;; SERVER: 127.0.0.11#53(127.0.0.11) - ;; WHEN: Tue Oct 01 23:47:24 UTC 2019 - ;; MSG SIZE rcvd: 44 - ``` - - In the "ANSWER SECTION", you will see an `A` record for `mysql` that resolves to `172.23.0.2` - (your IP address will most likely have a different value). While `mysql` isn't normally a valid hostname, - Docker was able to resolve it to the IP address of the container that had that network alias. Remember, you used the - `--network-alias` earlier. - - What this means is that your app only simply needs to connect to a host named `mysql` and it'll talk to the - database. - -## Run your app with MySQL - -The todo app supports the setting of a few environment variables to specify MySQL connection settings. They are: - -- `MYSQL_HOST` - the hostname for the running MySQL server -- `MYSQL_USER` - the username to use for the connection -- `MYSQL_PASSWORD` - the password to use for the connection -- `MYSQL_DB` - the database to use once connected - -> [!NOTE] -> -> While using env vars to set connection settings is generally accepted for development, it's highly discouraged -> when running applications in production. Diogo Monica, a former lead of security at Docker, -> [wrote a fantastic blog post](https://blog.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/) -> explaining why. -> -> A more secure mechanism is to use the secret support provided by your container orchestration framework. In most cases, -> these secrets are mounted as files in the running container. You'll see many apps (including the MySQL image and the todo app) -> also support env vars with a `_FILE` suffix to point to a file containing the variable. -> -> As an example, setting the `MYSQL_PASSWORD_FILE` var will cause the app to use the contents of the referenced file -> as the connection password. Docker doesn't do anything to support these env vars. Your app will need to know to look for -> the variable and get the file contents. - -You can now start your dev-ready container. - -1. Specify each of the previous environment variables, as well as connect the container to your app network. Make sure that you are in the `getting-started-app` directory when you run this command. - - {{< tabs >}} - {{< tab name="Mac / Linux" >}} - - ```console - $ docker run -dp 127.0.0.1:3000:3000 \ - -w /app -v ".:/app" \ - --network todo-app \ - -e MYSQL_HOST=mysql \ - -e MYSQL_USER=root \ - -e MYSQL_PASSWORD=secret \ - -e MYSQL_DB=todos \ - node:24-alpine \ - sh -c "npm install && npm run dev" - ``` - - {{< /tab >}} - {{< tab name="PowerShell" >}} - In Windows, run this command in PowerShell. - - ```powershell - $ docker run -dp 127.0.0.1:3000:3000 ` - -w /app -v ".:/app" ` - --network todo-app ` - -e MYSQL_HOST=mysql ` - -e MYSQL_USER=root ` - -e MYSQL_PASSWORD=secret ` - -e MYSQL_DB=todos ` - node:24-alpine ` - sh -c "npm install && npm run dev" - ``` - - {{< /tab >}} - {{< tab name="Command Prompt" >}} - In Windows, run this command in Command Prompt. - - ```console - $ docker run -dp 127.0.0.1:3000:3000 ^ - -w /app -v "%cd%:/app" ^ - --network todo-app ^ - -e MYSQL_HOST=mysql ^ - -e MYSQL_USER=root ^ - -e MYSQL_PASSWORD=secret ^ - -e MYSQL_DB=todos ^ - node:24-alpine ^ - sh -c "npm install && npm run dev" - ``` - - {{< /tab >}} - {{< tab name="Git Bash" >}} - - ```console - $ docker run -dp 127.0.0.1:3000:3000 \ - -w //app -v "/.:/app" \ - --network todo-app \ - -e MYSQL_HOST=mysql \ - -e MYSQL_USER=root \ - -e MYSQL_PASSWORD=secret \ - -e MYSQL_DB=todos \ - node:24-alpine \ - sh -c "npm install && npm run dev" - ``` - - {{< /tab >}} - {{< /tabs >}} - -2. If you look at the logs for the container (`docker logs -f <container-id>`), you should see a message similar to the following, which indicates it's - using the mysql database. - - ```console - [nodemon] 3.1.11 - [nodemon] to restart at any time, enter `rs` - [nodemon] watching path(s): *.* - [nodemon] watching extensions: js,mjs,cjs,json - [nodemon] starting `node src/index.js` - Waiting for mysql:3306. - Connected! - Connected to mysql db at host mysql - Listening on port 3000 - ``` - -3. Open the app in your browser and add a few items to your todo list. - -4. Connect to the mysql database and prove that the items are being written to the database. Remember, the password - is `secret`. - - ```console - $ docker exec -it <mysql-container-id> mysql -p todos - ``` - - And in the mysql shell, run the following: - - ```console - mysql> select * from todo_items; - +--------------------------------------+--------------------+-----------+ - | id | name | completed | - +--------------------------------------+--------------------+-----------+ - | c906ff08-60e6-44e6-8f49-ed56a0853e85 | Do amazing things! | 0 | - | 2912a79e-8486-4bc3-a4c5-460793a575ab | Be awesome! | 0 | - +--------------------------------------+--------------------+-----------+ - ``` - - Your table will look different because it has your items. But, you should see them stored there. - -## Summary - -At this point, you have an application that now stores its data in an external database running in a separate -container. You learned a little bit about container networking and service discovery using DNS. - -Related information: - - [docker CLI reference](/reference/cli/docker/) - - [Networking overview](/manuals/engine/network/_index.md) - -## Next steps - -There's a good chance you are starting to feel a little overwhelmed with everything you need to do to start up -this application. You have to create a network, start containers, specify all of the environment variables, expose -ports, and more. That's a lot to remember and it's certainly making things harder to pass along to someone else. - -In the next section, you'll learn about Docker Compose. With Docker Compose, you can share your application stacks in a -much easier way and let others spin them up with a single, simple command. - -{{< button text="Use Docker Compose" url="08_using_compose.md" >}} diff --git a/content/get-started/workshop/08_using_compose.md b/content/get-started/workshop/08_using_compose.md deleted file mode 100644 index dbaa9fdf7ef4..000000000000 --- a/content/get-started/workshop/08_using_compose.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -title: Use Docker Compose -weight: 80 -linkTitle: "Part 7: Use Docker Compose" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop -description: Using Docker Compose for multi-container applications -aliases: - - /get-started/08_using_compose/ - - /guides/workshop/08_using_compose/ ---- - -[Docker Compose](/manuals/compose/_index.md) is a tool that helps you define and -share multi-container applications. With Compose, you can create a YAML file to define the services -and with a single command, you can spin everything up or tear it all down. - -The big advantage of using Compose is you can define your application stack in a file, keep it at the root of -your project repository (it's now version controlled), and easily enable someone else to contribute to your project. -Someone would only need to clone your repository and start the app using Compose. In fact, you might see quite a few projects -on GitHub/GitLab doing exactly this now. - -## Create the Compose file - -In the `getting-started-app` directory, create a file named `compose.yaml`. - -```text -├── getting-started-app/ -│ ├── Dockerfile -│ ├── compose.yaml -│ ├── node_modules/ -│ ├── package.json -│ ├── package-lock.json -│ ├── spec/ -│ └── src/ -``` - -## Define the app service - -In [part 6](./07_multi_container.md), you used the following command to start the application service. - -```console -$ docker run -dp 127.0.0.1:3000:3000 \ - -w /app -v ".:/app" \ - --network todo-app \ - -e MYSQL_HOST=mysql \ - -e MYSQL_USER=root \ - -e MYSQL_PASSWORD=secret \ - -e MYSQL_DB=todos \ - node:24-alpine \ - sh -c "npm install && npm run dev" -``` - -You'll now define this service in the `compose.yaml` file. - -1. Open `compose.yaml` in a text or code editor, and start by defining the name and image of the first service (or container) you want to run as part of your application. - The name will automatically become a network alias, which will be useful when defining your MySQL service. - - ```yaml - services: - app: - image: node:24-alpine - ``` - -2. Typically, you will see `command` close to the `image` definition, although there is no requirement on ordering. Add the `command` to your `compose.yaml` file. - - ```yaml - services: - app: - image: node:24-alpine - command: sh -c "npm install && npm run dev" - ``` - -3. Now migrate the `-p 127.0.0.1:3000:3000` part of the command by defining the `ports` for the service. - - ```yaml - services: - app: - image: node:24-alpine - command: sh -c "npm install && npm run dev" - ports: - - 127.0.0.1:3000:3000 - ``` - -4. Next, migrate both the working directory (`-w /app`) and the volume mapping - (`-v ".:/app"`) by using the `working_dir` and `volumes` definitions. - - One advantage of Docker Compose volume definitions is you can use relative paths from the current directory. - - ```yaml - services: - app: - image: node:24-alpine - command: sh -c "npm install && npm run dev" - ports: - - 127.0.0.1:3000:3000 - working_dir: /app - volumes: - - ./:/app - ``` - -5. Finally, you need to migrate the environment variable definitions using the `environment` key. - - ```yaml - services: - app: - image: node:24-alpine - command: sh -c "npm install && npm run dev" - ports: - - 127.0.0.1:3000:3000 - working_dir: /app - volumes: - - ./:/app - environment: - MYSQL_HOST: mysql - MYSQL_USER: root - MYSQL_PASSWORD: secret - MYSQL_DB: todos - ``` - -### Define the MySQL service - -Now, it's time to define the MySQL service. The command that you used for that container was the following: - -```console -$ docker run -d \ - --network todo-app --network-alias mysql \ - -v todo-mysql-data:/var/lib/mysql \ - -e MYSQL_ROOT_PASSWORD=secret \ - -e MYSQL_DATABASE=todos \ - mysql:8.0 -``` - -1. First define the new service and name it `mysql` so it automatically gets the network alias. Also specify the image to use as well. - - ```yaml - - services: - app: - # The app service definition - mysql: - image: mysql:8.0 - ``` - -2. Next, define the volume mapping. When you ran the container with `docker - run`, Docker created the named volume automatically. However, that doesn't - happen when running with Compose. You need to define the volume in the - top-level `volumes:` section and then specify the mountpoint in the service - config. By simply providing only the volume name, the default options are - used. - - ```yaml - services: - app: - # The app service definition - mysql: - image: mysql:8.0 - volumes: - - todo-mysql-data:/var/lib/mysql - - volumes: - todo-mysql-data: - ``` - -3. Finally, you need to specify the environment variables. - - ```yaml - services: - app: - # The app service definition - mysql: - image: mysql:8.0 - volumes: - - todo-mysql-data:/var/lib/mysql - environment: - MYSQL_ROOT_PASSWORD: secret - MYSQL_DATABASE: todos - - volumes: - todo-mysql-data: - ``` - -At this point, your complete `compose.yaml` should look like this: - - -```yaml -services: - app: - image: node:24-alpine - command: sh -c "npm install && npm run dev" - ports: - - 127.0.0.1:3000:3000 - working_dir: /app - volumes: - - ./:/app - environment: - MYSQL_HOST: mysql - MYSQL_USER: root - MYSQL_PASSWORD: secret - MYSQL_DB: todos - - mysql: - image: mysql:8.0 - volumes: - - todo-mysql-data:/var/lib/mysql - environment: - MYSQL_ROOT_PASSWORD: secret - MYSQL_DATABASE: todos - -volumes: - todo-mysql-data: -``` - -## Run the application stack - -Now that you have your `compose.yaml` file, you can start your application. - -1. Make sure no other copies of the containers are running first. Use `docker ps` to list the containers and `docker rm -f <ids>` to remove them. - -2. Start up the application stack using the `docker compose up` command. Add the - `-d` flag to run everything in the background. - - ```console - $ docker compose up -d - ``` - - When you run the previous command, you should see output like the following: - - ```plaintext - Creating network "app_default" with the default driver - Creating volume "app_todo-mysql-data" with default driver - Creating app_app_1 ... done - Creating app_mysql_1 ... done - ``` - - You'll notice that Docker Compose created the volume as well as a network. By default, Docker Compose automatically creates a network specifically for the application stack (which is why you didn't define one in the Compose file). - -3. Look at the logs using the `docker compose logs -f` command. You'll see the logs from each of the services interleaved - into a single stream. This is incredibly useful when you want to watch for timing-related issues. The `-f` flag follows the - log, so will give you live output as it's generated. - - If you have run the command already, you'll see output that looks like this: - - ```plaintext - mysql_1 | 2019-10-03T03:07:16.083639Z 0 [Note] mysqld: ready for connections. - mysql_1 | Version: '8.0.31' socket: '/var/run/mysqld/mysqld.sock' port: 3306 MySQL Community Server (GPL) - app_1 | Connected to mysql db at host mysql - app_1 | Listening on port 3000 - ``` - - The service name is displayed at the beginning of the line (often colored) to help distinguish messages. If you want to - view the logs for a specific service, you can add the service name to the end of the logs command (for example, - `docker compose logs -f app`). - -4. At this point, you should be able to open your app in your browser on [http://localhost:3000](http://localhost:3000) and see it running. - -## See the app stack in Docker Desktop Dashboard - -If you look at the Docker Desktop Dashboard, you'll see that there is a group named **getting-started-app**. This is the project name from Docker -Compose and used to group the containers together. By default, the project name is simply the name of the directory that the -`compose.yaml` was located in. - -If you expand the stack, you'll see the two containers you defined in the Compose file. The names are also a little -more descriptive, as they follow the pattern of `<service-name>-<replica-number>`. So, it's very easy to -quickly see what container is your app and which container is the mysql database. - -## Tear it all down - -When you're ready to tear it all down, simply run `docker compose down` or hit the trash can on the Docker Desktop Dashboard -for the entire app. The containers will stop and the network will be removed. - -> [!WARNING] -> -> By default, named volumes in your compose file are not removed when you run `docker compose down`. If you want to ->remove the volumes, you need to add the `--volumes` flag. -> -> The Docker Desktop Dashboard does not remove volumes when you delete the app stack. - -## Summary - -In this section, you learned about Docker Compose and how it helps you simplify -the way you define and share multi-service applications. - -Related information: - - [Compose overview](/manuals/compose/_index.md) - - [Compose file reference](/reference/compose-file/_index.md) - - [Compose CLI reference](/reference/cli/docker/compose/) - -## Next steps - -Next, you'll learn about a few best practices you can use to improve your Dockerfile. - -{{< button text="Image-building best practices" url="09_image_best.md" >}} diff --git a/content/get-started/workshop/09_image_best.md b/content/get-started/workshop/09_image_best.md deleted file mode 100644 index bcbf55de47da..000000000000 --- a/content/get-started/workshop/09_image_best.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Image-building best practices -weight: 90 -linkTitle: "Part 8: Image-building best practices" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop -description: Tips for building images for your application -aliases: - - /get-started/09_image_best/ - - /guides/workshop/09_image_best/ ---- - -## Image layering - -Using the `docker image history` command, you can see the command that was used -to create each layer within an image. - -1. Use the `docker image history` command to see the layers in the `getting-started` image you - created. - - ```console - $ docker image history getting-started - ``` - - You should get output that looks something like the following. - - ```plaintext - IMAGE CREATED CREATED BY SIZE COMMENT - a78a40cbf866 18 seconds ago /bin/sh -c #(nop) CMD ["node" "src/index.j… 0B - f1d1808565d6 19 seconds ago /bin/sh -c npm install --omit=dev 85.4MB - a2c054d14948 36 seconds ago /bin/sh -c #(nop) COPY dir:5dc710ad87c789593… 198kB - 9577ae713121 37 seconds ago /bin/sh -c #(nop) WORKDIR /app 0B - b95baba1cfdb 13 days ago /bin/sh -c #(nop) CMD ["node"] 0B - <missing> 13 days ago /bin/sh -c #(nop) ENTRYPOINT ["docker-entry… 0B - <missing> 13 days ago /bin/sh -c #(nop) COPY file:238737301d473041… 116B - <missing> 13 days ago /bin/sh -c apk add --no-cache --virtual .bui… 5.35MB - <missing> 13 days ago /bin/sh -c addgroup -g 1000 node && addu… 74.3MB - <missing> 13 days ago /bin/sh -c #(nop) ENV NODE_VERSION=12.14.1 0B - <missing> 13 days ago /bin/sh -c #(nop) CMD ["/bin/sh"] 0B - <missing> 13 days ago /bin/sh -c #(nop) ADD file:e69d441d729412d24… 5.59MB - ``` - - Each of the lines represents a layer in the image. The display here shows the base at the bottom with - the newest layer at the top. Using this, you can also quickly see the size of each layer, helping - diagnose large images. - -2. You'll notice that several of the lines are truncated. If you add the `--no-trunc` flag, you'll get the - full output. - - ```console - $ docker image history --no-trunc getting-started - ``` - -## Layer caching - -Now that you've seen the layering in action, there's an important lesson to learn to help decrease build -times for your container images. Once a layer changes, all downstream layers have to be recreated as well. - -Look at the following Dockerfile you created for the getting started app. - -```dockerfile -# syntax=docker/dockerfile:1 -FROM node:24-alpine -WORKDIR /app -COPY . . -RUN npm install --omit=dev -CMD ["node", "src/index.js"] -EXPOSE 3000 -``` - -Going back to the image history output, you see that each command in the Dockerfile becomes a new layer in the image. -You might remember that when you made a change to the image, the dependencies had to be reinstalled. It doesn't make much sense to ship around the same dependencies every time you build. - -To fix it, you need to restructure your Dockerfile to help support the caching -of the dependencies. For Node-based applications, those dependencies are defined -in the `package.json` file. You can copy only that file in first, install the -dependencies, and then copy in everything else. Then, you only recreate the -dependencies if there was a change to the `package.json`. - -1. Update the Dockerfile to copy in the `package.json` first, install dependencies, and then copy everything else in. - - ```dockerfile - # syntax=docker/dockerfile:1 - FROM node:24-alpine - WORKDIR /app - COPY package.json package-lock.json ./ - RUN npm install --omit=dev - COPY . . - CMD ["node", "src/index.js"] - ``` - -2. Build a new image using `docker build`. - - ```console - $ docker build -t getting-started . - ``` - - You should see output like the following. - - ```plaintext - [+] Building 16.1s (10/10) FINISHED - => [internal] load build definition from Dockerfile - => => transferring dockerfile: 175B - => [internal] load .dockerignore - => => transferring context: 2B - => [internal] load metadata for docker.io/library/node:24-alpine - => [internal] load build context - => => transferring context: 53.37MB - => [1/5] FROM docker.io/library/node:24-alpine - => CACHED [2/5] WORKDIR /app - => [3/5] COPY package.json package-lock.json ./ - => [4/5] RUN npm install --omit=dev - => [5/5] COPY . . - => exporting to image - => => exporting layers - => => writing image sha256:d6f819013566c54c50124ed94d5e66c452325327217f4f04399b45f94e37d25 - => => naming to docker.io/library/getting-started - ``` - -3. Now, make a change to the `src/static/index.html` file. For example, change the `<title>` to "The Awesome Todo App". - -4. Build the Docker image now using `docker build -t getting-started .` again. This time, your output should look a little different. - - ```plaintext - [+] Building 1.2s (10/10) FINISHED - => [internal] load build definition from Dockerfile - => => transferring dockerfile: 37B - => [internal] load .dockerignore - => => transferring context: 2B - => [internal] load metadata for docker.io/library/node:24-alpine - => [internal] load build context - => => transferring context: 450.43kB - => [1/5] FROM docker.io/library/node:24-alpine - => CACHED [2/5] WORKDIR /app - => CACHED [3/5] COPY package.json package-lock.json ./ - => CACHED [4/5] RUN npm install - => [5/5] COPY . . - => exporting to image - => => exporting layers - => => writing image sha256:91790c87bcb096a83c2bd4eb512bc8b134c757cda0bdee4038187f98148e2eda - => => naming to docker.io/library/getting-started - ``` - - First off, you should notice that the build was much faster. And, you'll see - that several steps are using previously cached layers. Pushing and pulling - this image and updates to it will be much faster as well. - -## Multi-stage builds - -Multi-stage builds are an incredibly powerful -tool to help use multiple stages to create an image. There are several advantages for them: - -- Separate build-time dependencies from runtime dependencies -- Reduce overall image size by shipping only what your app needs to run - -### Maven/Tomcat example - -When building Java-based applications, you need a JDK to compile the source code to Java bytecode. However, -that JDK isn't needed in production. Also, you might be using tools like Maven or Gradle to help build the app. -Those also aren't needed in your final image. Multi-stage builds help. - -```dockerfile -# syntax=docker/dockerfile:1 -FROM maven AS build -WORKDIR /app -COPY . . -RUN mvn package - -FROM tomcat -COPY --from=build /app/target/file.war /usr/local/tomcat/webapps -``` - -In this example, you use one stage (called `build`) to perform the actual Java build using Maven. In the second -stage (starting at `FROM tomcat`), you copy in files from the `build` stage. The final image is only the last stage -being created, which can be overridden using the `--target` flag. - -### React example - -When building React applications, you need a Node environment to compile the JS code (typically JSX), SASS stylesheets, -and more into static HTML, JS, and CSS. If you aren't doing server-side rendering, you don't even need a Node environment -for your production build. You can ship the static resources in a static nginx container. - -```dockerfile -# syntax=docker/dockerfile:1 -FROM node:24-alpine AS build -WORKDIR /app -COPY package* ./ -RUN npm install -COPY public ./public -COPY src ./src -RUN npm run build - -FROM nginx:alpine -COPY --from=build /app/build /usr/share/nginx/html -``` - -In the previous Dockerfile example, it uses the `node:24-alpine` image to perform the build (maximizing layer caching) and then copies the output -into an nginx container. - - - > [!Tips] - > This React example is for illustration purposes. The getting-started todo app is a `Node.js` backend application, not a React frontend. - - -## Summary - -In this section, you learned a few image building best practices, including layer caching and multi-stage builds. - -Related information: - - [Dockerfile reference](/reference/dockerfile/) - - [Dockerfile best practices](/manuals/build/building/best-practices.md) - -## Next steps - -In the next section, you'll learn about additional resources you can use to continue learning about containers. - -{{< button text="What next" url="10_what_next.md" >}} diff --git a/content/get-started/workshop/10_what_next.md b/content/get-started/workshop/10_what_next.md deleted file mode 100644 index 4d22eee73e0e..000000000000 --- a/content/get-started/workshop/10_what_next.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: What next after the Docker workshop -weight: 100 -linkTitle: "Part 9: What next" -keywords: get started, setup, orientation, quickstart, intro, concepts, containers, - docker desktop, AI, model runner, MCP, agents, hardened images, security -description: Explore what to do next after completing the Docker workshop, including securing your images, AI development, and language-specific guides. -aliases: - - /get-started/11_what_next/ - - /guides/workshop/10_what_next/ -summary: | - Now that you've completed the Docker workshop, you're ready to explore - securing your images with Docker Hardened Images, building AI-powered - applications, and diving into language-specific guides. -notoc: true - -secure-images: -- title: What are Docker Hardened Images? - description: Understand secure, minimal, production-ready base images with near-zero CVEs. - link: /dhi/explore/what/ -- title: Get started with DHI - description: Pull and run your first Docker Hardened Image in minutes. - link: /dhi/get-started/ -- title: Use hardened images - description: Learn how to use DHI in your Dockerfiles and CI/CD pipelines. - link: /dhi/how-to/use/ -- title: Explore the DHI catalog - description: Browse available hardened images, variants, and security attestations. - link: /dhi/how-to/explore/ - -ai-development: -- title: Docker Model Runner - description: Run and manage AI models locally using familiar Docker commands with OpenAI-compatible APIs. - link: /ai/model-runner/ -- title: MCP Toolkit - description: Set up, manage, and run containerized MCP servers to power your AI agents. - link: /ai/mcp-catalog-and-toolkit/toolkit/ -- title: Build AI agents with Docker Agent - description: Create teams of specialized AI agents that collaborate to solve complex problems. - link: /ai/docker-agent/ -- title: Use AI models in Compose - description: Define AI model dependencies in your Docker Compose applications. - link: /ai/compose/models-and-compose/ - -language-guides: -- title: Node.js - description: Learn how to containerize and develop Node.js applications. - link: /guides/language/nodejs/ -- title: Python - description: Build and run Python applications in containers. - link: /guides/language/python/ -- title: Java - description: Containerize Java applications with best practices. - link: /guides/language/java/ -- title: Go - description: Develop and deploy Go applications using Docker. - link: /guides/language/golang/ ---- - -Congratulations on completing the Docker workshop. You've learned how to containerize applications, work with multi-container setups, use Docker Compose, and apply image-building best practices. - -Here's what to explore next. - -## Secure your images - -Take your image-building skills to the next level with Docker Hardened Images—secure, minimal, and production-ready base images that are now free for everyone. - -{{< grid items="secure-images" >}} - -## Build with AI - -Docker makes it easy to run AI models locally and build agentic AI applications. Explore Docker's AI tools and start building AI-powered apps. - -{{< grid items="ai-development" >}} - -## Language-specific guides - -Apply what you've learned to your preferred programming language with hands-on tutorials. - -{{< grid items="language-guides" >}} diff --git a/content/get-started/workshop/_index.md b/content/get-started/workshop/_index.md deleted file mode 100644 index cc6a0beff925..000000000000 --- a/content/get-started/workshop/_index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Overview of the Docker workshop -linkTitle: Docker workshop -keywords: docker basics, how to start a docker container, container settings, setup - docker, how to setup docker, setting up docker, docker container guide, how to get - started with docker -description: Get started with the Docker basics in this workshop, You'll - learn about containers, images, and how to containerize your first application. -aliases: -- /guides/get-started/ -- /get-started/hands-on-overview/ -- /guides/workshop/ ---- - -This 45-minute workshop contains step-by-step instructions on how to get started with Docker. This workshop shows you how to: - -- Build and run an image as a container. -- Share images using Docker Hub. -- Deploy Docker applications using multiple containers with a database. -- Run applications using Docker Compose. - -> [!NOTE] -> -> For a quick introduction to Docker and the benefits of containerizing your -> applications, see [Getting started](/get-started/introduction/_index.md). - -## What is a container? - -A container is a sandboxed process running on a host machine that is isolated from all other processes running on that host machine. That isolation leverages [kernel namespaces and cgroups](https://medium.com/@saschagrunert/demystifying-containers-part-i-kernel-space-2c53d6979504), -features that have been in Linux for a long time. Docker makes these capabilities approachable and easy to use. To summarize, a container: - -- Is a runnable instance of an image. You can create, start, stop, move, or delete a container using the Docker API or CLI. -- Can be run on local machines, virtual machines, or deployed to the cloud. -- Is portable (and can be run on any OS). -- Is isolated from other containers and runs its own software, binaries, configurations, etc. - -If you're familiar with `chroot`, then think of a container as an extended version of `chroot`. The filesystem comes from the image. However, a container adds additional isolation not available when using chroot. - -## What is an image? - -A running container uses an isolated filesystem. This isolated filesystem is provided by an image, and the image must contain everything needed to run an application - all dependencies, configurations, scripts, binaries, etc. The image also contains other configurations for the container, such as environment variables, a default command to run, and other metadata. - -## Next steps - -In this section, you learned about containers and images. - -Next, you'll containerize a simple application and get hands-on with the concepts. - -{{< button text="Containerize an application" url="02_our_app.md" >}} diff --git a/content/get-started/workshop/images/dashboard-two-containers.webp b/content/get-started/workshop/images/dashboard-two-containers.webp deleted file mode 100644 index 89ca228f1fe4..000000000000 Binary files a/content/get-started/workshop/images/dashboard-two-containers.webp and /dev/null differ diff --git a/content/get-started/workshop/images/items-added.webp b/content/get-started/workshop/images/items-added.webp deleted file mode 100644 index 10c0d347b4ea..000000000000 Binary files a/content/get-started/workshop/images/items-added.webp and /dev/null differ diff --git a/content/get-started/workshop/images/multi-container.webp b/content/get-started/workshop/images/multi-container.webp deleted file mode 100644 index e8b5b9ea776f..000000000000 Binary files a/content/get-started/workshop/images/multi-container.webp and /dev/null differ diff --git a/content/get-started/workshop/images/push-command.webp b/content/get-started/workshop/images/push-command.webp deleted file mode 100644 index 0d2b25a25ba8..000000000000 Binary files a/content/get-started/workshop/images/push-command.webp and /dev/null differ diff --git a/content/get-started/workshop/images/todo-list-empty.webp b/content/get-started/workshop/images/todo-list-empty.webp deleted file mode 100644 index c4956bc64e32..000000000000 Binary files a/content/get-started/workshop/images/todo-list-empty.webp and /dev/null differ diff --git a/content/get-started/workshop/images/updated-add-button.webp b/content/get-started/workshop/images/updated-add-button.webp deleted file mode 100644 index 9003a52a8c66..000000000000 Binary files a/content/get-started/workshop/images/updated-add-button.webp and /dev/null differ diff --git a/content/guides/_index.md b/content/guides/_index.md index b5ded5dff3eb..9c4a04caaf0d 100644 --- a/content/guides/_index.md +++ b/content/guides/_index.md @@ -1,7 +1,7 @@ --- title: Docker guides linkTitle: Guides -description: Explore the Docker guides +description: Step-by-step tutorials, organized by what you're trying to do. keywords: docker, guides, tutorials, learning paths, getting started params: icon: book-open @@ -9,13 +9,17 @@ layout: landing aliases: - /guides/language/ - /language/ + - /guides/dhi-from-doi/ + - /guides/dhi-from-wolfi/ + - /guides/dhi-go-example/ + - /guides/dhi-nodejs-example/ + - /guides/dhi-python-example/ + - /guides/lab-docker-for-ai-redirect/ - /learning-paths/ --- -Explore our collection of guides to learn how Docker can optimize your -development workflows and how to use it with specific languages, frameworks, or -technologies. +Explore guides to learn how Docker can optimize your development workflows and +how to use it with specific languages, frameworks, or technologies. Can't find the guide you're looking for? Open an issue on the -[docker/docs](https://github.com/docker/docs/issues/new) repository to let us -know. +[docker/docs](https://github.com/docker/docs/issues/new) repository. diff --git a/content/guides/admin-set-up.md b/content/guides/admin-set-up.md new file mode 100644 index 000000000000..cf3b322c42d5 --- /dev/null +++ b/content/guides/admin-set-up.md @@ -0,0 +1,330 @@ +--- +title: Set up your company for success with Docker +linkTitle: Admin set up +summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company. +description: Learn how to onboard your company and take advantage of all of the Docker products and features. +keywords: admin, onboarding, deployment, organization setup, docker business, rollout +aliases: + - /guides/admin-set-up/comms-and-info-gathering/ + - /guides/admin-set-up/deploy/ + - /guides/admin-set-up/finalize-plans-and-setup/ + - /guides/admin-set-up/testing/ +params: + tags: [admin] + time: 20 minutes + image: +--- + + +Docker's tools provide a scalable, secure platform that empowers your +developers to create, ship, and run applications faster. As an administrator, +you can streamline workflows, standardize development environments, and ensure +smooth deployments across your organization. + +By configuring Docker products to suit your company's needs, you can optimize +performance, simplify user management, and maintain control over resources. +This guide helps you set up and configure Docker products to maximize +productivity and success for your team while meeting compliance and security +policies. + +## Who’s this for? + +- Administrators responsible for managing Docker environments within their + organization +- IT leaders looking to streamline development and deployment workflows +- Teams aiming to standardize application environments across multiple users +- Organizations seeking to optimize their use of Docker products for greater + scalability and efficiency +- Organizations with a + [Docker Business subscription](https://www.docker.com/pricing?ref=DocsGuides&refAction=DocsGuidesCTAClicked) + +## What you’ll learn + +- Why signing into your company's Docker organization provides access to usage + data and enhanced functionality +- How to standardize Docker Desktop versions and settings to create a consistent + baseline for all users, while allowing flexibility for advanced developers +- Strategies for implementing Docker's security configurations to meet company + IT and software development security requirements without hindering developer productivity + +## Features covered + +This guide covers the following Docker features: + +- [Organizations](/manuals/accounts/organization/_index.md): The core structure + for managing your Docker environment, grouping users, teams, and image + repositories. Your organization was created with your subscription and is + managed by one or more owners. Users signed into the organization are + assigned seats based on the purchased subscription. +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md): + By default, Docker Desktop doesn't require sign-in. You can configure + settings to enforce this and ensure your developers sign in to your + Docker organization. +- [SSO](/manuals/security/authentication/single-sign-on/_index.md): Without SSO, + user management in a Docker organization is manual. Setting + up an SSO connection between your identity provider and Docker ensures + compliance with your security policy and automates user provisioning. Adding + SCIM further automates user provisioning and de-provisioning. +- General and security settings: Configuring key settings ensures smooth + onboarding and usage of Docker products within your environment. You can also + enable security features based on your company's specific security needs. + +## Who needs to be involved + +- Docker organization owner: Must be involved in the process and is required + for several key steps +- DNS team: Needed during the SSO setup to verify the company domain +- MDM team: Responsible for distributing Docker-specific configuration files to + developer machines +- Identity Provider team: Required for configuring the identity provider and + establishing the SSO connection during setup +- Development lead: A development lead with knowledge of Docker configurations + to help establish a baseline for developer settings +- IT team: An IT representative familiar with company desktop policies to + assist with aligning Docker configuration to those policies +- Infosec: A security team member with knowledge of company development + security policies to help configure security features +- Docker testers: A small group of developers to test the new settings and + configurations before full deployment + +## Tools integration + +This guide covers integration with: + +- Okta +- Entra ID SAML 2.0 +- Azure Connect (OIDC) +- MDM solutions like Intune + +## Communication and information gathering + +### Communicate with your developers and IT teams + +Before rolling out Docker Desktop across your organization, coordinate with key stakeholders to ensure a smooth transition. + +#### Notify Docker Desktop users + +You may already have Docker Desktop users within your company. Some steps in +this onboarding process may affect how they interact with the platform. + +Communicate early with users to inform them that: + +- They'll be upgraded to a supported version of Docker Desktop as part of the subscription onboarding +- Settings will be reviewed and optimized for productivity +- They'll need to sign in to the company's Docker organization using their + business email to access subscription benefits + +#### Engage with your MDM team + +Device management solutions, such as Intune and Jamf, are commonly used for +software distribution across enterprises. These tools are typically managed by a dedicated MDM team. + +Engage with this team early in the process to: + +- Understand their requirements and lead time for deploying changes +- Coordinate the distribution of configuration files + +Several setup steps in this guide require JSON files, registry keys, or .plist +files to be distributed to developer machines. Use MDM tools to deploy these configuration files and ensure their integrity. + +### Identify Docker organizations + +Some companies may have more than one +[Docker organization](/manuals/accounts/organization/_index.md) created. These +organizations may have been created for specific purposes, or may not be +needed anymore. + +If you suspect your company has multiple Docker organizations: + +- Survey your teams to see if they have their own organizations +- Contact your Docker Support to get a list of organizations with users whose + emails match your domain name + +### Gather requirements + +[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) lets you preset numerous configuration parameters for Docker Desktop. + +Work with the following stakeholders to establish your company's baseline +configuration: + +- Docker organization owner +- Development lead +- Information security representative + +Review these areas together: + +- Security features and + [enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) + for Docker Desktop users +- Additional Docker products included in your subscriptions + +To view the parameters that can be preset, see [Configure Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in). + +### Optional: Meet with the Docker Implementation team + +The Docker Implementation team can help you set up your organization, +configure SSO, enforce sign-in, and configure Docker Desktop. + +To schedule a meeting, email successteam@docker.com. + +## Finalize plans and begin setup + +### Send finalized settings files to the MDM team + +After reaching an agreement with the relevant teams about your baseline and +security configurations as outlined in the previous section, configure Settings Management either via [Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) or with an +[`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md). + +Once the file is ready, collaborate with your MDM team to deploy your chosen +settings, along with your chosen method for [enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + +> [!IMPORTANT] +> +> Test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely. + +### Manage your organizations + +If you have more than one organization, consider either [consolidating them +into one organization](/manuals/accounts/organization/setup/orgs.md) or creating a +[Docker company](/manuals/accounts/company/_index.md) to manage multiple +organizations. + +### Begin setup + +#### Set up single sign-on and domain verification + +Single sign-on (SSO) lets developers authenticate using their identity +providers (IdPs) to access Docker. SSO is available for a whole company and all associated organizations, or an individual organization that has a Docker +Business subscription. For more information, see the +[documentation](/manuals/security/authentication/single-sign-on/_index.md). + +You can also enable [SCIM](/manuals/security/provisioning/scim/_index.md) +for further automation of provisioning and deprovisioning of users. + +#### Set up Docker product entitlements included in the subscription + +[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces +build times, both locally and in CI, by providing a dedicated remote builder +and shared cache. Powered by the cloud, developer time and local resources are +freed up so your team can focus on more important things, like innovation. +To get started, [set up a cloud builder](https://app.docker.com/build/). + +[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing +your software supply chain security. By analyzing your images, Docker Scout +compiles an inventory of components, also known as a Software Bill of Materials +(SBOM). The SBOM is matched against a continuously updated vulnerability +database to pinpoint security weaknesses. To get started, see +[Quickstart](/manuals/scout/quickstart.md). + +[Testcontainers Cloud](https://testcontainers.com/cloud/docs/) allows +developers to run containers in the cloud, removing the need to run heavy +containers on your local machine. + +[Docker Hardened Images](/manuals/dhi/_index.md) are minimal, secure, and production-ready container base and application images maintained by Docker. +Designed to reduce vulnerabilities and simplify compliance, DHIs integrate +easily into your existing Docker-based workflows with little to no retooling +required. + +#### Ensure you're running a supported version of Docker Desktop + +> [!WARNING] +> +> This step could affect the experience for users on older versions of Docker +> Desktop. + +Existing users may be running outdated or unsupported versions of +Docker Desktop. All users should update to a supported version. Docker Desktop +versions released within the past 6 months from the latest release are supported. + +Use an MDM solution to manage the version of Docker Desktop for users. Users +may also get Docker Desktop directly from Docker or through a company software +portal. + +## Testing + +### SSO and SCIM testing + +Test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email +address linked to a Docker account that is part of the verified domain. +Developers who sign in using their Docker usernames remain unaffected by the +SSO and SCIM setup. + +> [!IMPORTANT] +> +> Some users may need CLI based logins to Docker Hub, and for this they will +> need a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md). + +### Test Registry Access Management and Image Access Management + +> [!WARNING] +> +> Communicate with your users before proceeding, as this step will impact all +> existing users signing into your Docker organization. + +If you plan to use [Registry Access Management (RAM)](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md): + +1. Ensure your test developer signs in to Docker Desktop using their + organization credentials +2. Have them attempt to pull an unauthorized image or one from a disallowed + registry via the Docker CLI +3. Verify they receive an error message indicating that the registry is + restricted by the organization + +### Deploy settings and enforce sign in to test group + +Deploy the Docker settings and enforce sign-in for a small group of test users +via MDM. Have this group test their development workflows with containers on +Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement +function as expected. + +### Test Docker Build Cloud capabilities + +Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md). + +### Test Testcontainers Cloud + +Have a test developer [connect to Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) and run a container in +the cloud to verify the setup is working correctly. + +### Verify Docker Scout monitoring of repositories + +Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that +data is being properly received for the repositories where Docker Scout has +been enabled. + +### Verify access to Docker Hardened Images + +Have a test developer attempt to [pull a Docker Hardened Image](/manuals/dhi/get-started.md) to confirm that +the team has proper access and can integrate these images into their workflows. + +## Deploy your Docker setup + +> [!WARNING] +> +> Communicate with your users before proceeding, and confirm that your IT and +> MDM teams are prepared to handle any unexpected issues, as these steps will +> affect all existing users signing into your Docker organization. + +### Enforce SSO + +Enforcing SSO means that anyone who has a Docker profile with an email address +that matches your verified domain must sign in using your SSO connection. Make +sure the Identity provider groups associated with your SSO connection cover all +the developer groups that you want to have access to the Docker subscription. + +For instructions on how to enforce SSO, see [Enforce SSO](/manuals/security/authentication/single-sign-on/connect.md). + +### Deploy configuration settings and enforce sign-in to users + +Have the MDM team deploy the configuration files for Docker to all users. + +### Next steps + +Congratulations, you've successfully completed the admin implementation process +for Docker. + +To continue optimizing your Docker environment: + +- Review your [organization's usage data](/manuals/accounts/organization/insights.md) to track adoption +- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for security insights +- Explore [additional security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to enhance your configuration diff --git a/content/guides/admin-set-up/_index.md b/content/guides/admin-set-up/_index.md deleted file mode 100644 index e20eb016eecb..000000000000 --- a/content/guides/admin-set-up/_index.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Set up your company for success with Docker -linkTitle: Admin set up -summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company. -description: Learn how to onboard your company and take advantage of all of the Docker products and features. -keywords: admin, onboarding, deployment, organization setup, docker business, rollout -tags: [admin] -params: - time: 20 minutes - image: - resource_links: - - title: Overview of Administration in Docker - url: /admin/ - - title: Single sign-on - url: /security/for-admins/single-sign-on/ - - title: Enforce sign-in - url: /security/for-admins/enforce-sign-in/ - - title: Roles and permissions - url: /security/for-admins/roles-and-permissions/ - - title: Settings Management - url: /security/for-admins/hardened-desktop/settings-management/ - - title: Registry Access Management - url: /security/for-admins/hardened-desktop/registry-access-management/ - - title: Image Access Management - url: /security/for-admins/hardened-desktop/image-access-management/ - - title: Docker subscription information - url: "https://www.docker.com/pricing?ref=Docs&refAction=DocsGuidesAdminSetup" ---- - -Docker's tools provide a scalable, secure platform that empowers your -developers to create, ship, and run applications faster. As an administrator, -you can streamline workflows, standardize development environments, and ensure -smooth deployments across your organization. - -By configuring Docker products to suit your company's needs, you can optimize -performance, simplify user management, and maintain control over resources. -This guide helps you set up and configure Docker products to maximize -productivity and success for your team while meeting compliance and security -policies. - -## Who’s this for? - -- Administrators responsible for managing Docker environments within their - organization -- IT leaders looking to streamline development and deployment workflows -- Teams aiming to standardize application environments across multiple users -- Organizations seeking to optimize their use of Docker products for greater - scalability and efficiency -- Organizations with a - [Docker Business subscription](https://www.docker.com/pricing?ref=DocsGuides&refAction=DocsGuidesCTAClicked) - -## What you’ll learn - -- Why signing into your company's Docker organization provides access to usage - data and enhanced functionality -- How to standardize Docker Desktop versions and settings to create a consistent - baseline for all users, while allowing flexibility for advanced developers -- Strategies for implementing Docker's security configurations to meet company - IT and software development security requirements without hindering developer productivity - -## Features covered - -This guide covers the following Docker features: - -- [Organizations](/manuals/admin/organization/_index.md): The core structure - for managing your Docker environment, grouping users, teams, and image - repositories. Your organization was created with your subscription and is - managed by one or more owners. Users signed into the organization are - assigned seats based on the purchased subscription. -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md): - By default, Docker Desktop doesn't require sign-in. You can configure - settings to enforce this and ensure your developers sign in to your - Docker organization. -- [SSO](/manuals/enterprise/security/single-sign-on/_index.md): Without SSO, - user management in a Docker organization is manual. Setting - up an SSO connection between your identity provider and Docker ensures - compliance with your security policy and automates user provisioning. Adding - SCIM further automates user provisioning and de-provisioning. -- General and security settings: Configuring key settings ensures smooth - onboarding and usage of Docker products within your environment. You can also - enable security features based on your company's specific security needs. - -## Who needs to be involved - -- Docker organization owner: Must be involved in the process and is required - for several key steps -- DNS team: Needed during the SSO setup to verify the company domain -- MDM team: Responsible for distributing Docker-specific configuration files to - developer machines -- Identity Provider team: Required for configuring the identity provider and - establishing the SSO connection during setup -- Development lead: A development lead with knowledge of Docker configurations - to help establish a baseline for developer settings -- IT team: An IT representative familiar with company desktop policies to - assist with aligning Docker configuration to those policies -- Infosec: A security team member with knowledge of company development - security policies to help configure security features -- Docker testers: A small group of developers to test the new settings and - configurations before full deployment - -## Tools integration - -This guide covers integration with: - -- Okta -- Entra ID SAML 2.0 -- Azure Connect (OIDC) -- MDM solutions like Intune diff --git a/content/guides/admin-set-up/comms-and-info-gathering.md b/content/guides/admin-set-up/comms-and-info-gathering.md deleted file mode 100644 index 40a230c5e36c..000000000000 --- a/content/guides/admin-set-up/comms-and-info-gathering.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Communication and information gathering -description: Gather your company's requirements from key stakeholders and communicate to your developers. -keywords: admin, onboarding, stakeholders, communication, mdm, requirements -weight: 10 ---- - -## Communicate with your developers and IT teams - -Before rolling out Docker Desktop across your organization, coordinate with key stakeholders to ensure a smooth transition. - -### Notify Docker Desktop users - -You may already have Docker Desktop users within your company. Some steps in -this onboarding process may affect how they interact with the platform. - -Communicate early with users to inform them that: - -- They'll be upgraded to a supported version of Docker Desktop as part of the subscription onboarding -- Settings will be reviewed and optimized for productivity -- They'll need to sign in to the company's Docker organization using their - business email to access subscription benefits - -### Engage with your MDM team - -Device management solutions, such as Intune and Jamf, are commonly used for -software distribution across enterprises. These tools are typically managed by a dedicated MDM team. - -Engage with this team early in the process to: - -- Understand their requirements and lead time for deploying changes -- Coordinate the distribution of configuration files - -Several setup steps in this guide require JSON files, registry keys, or .plist -files to be distributed to developer machines. Use MDM tools to deploy these configuration files and ensure their integrity. - -## Identify Docker organizations - -Some companies may have more than one -[Docker organization](/manuals/admin/organization/_index.md) created. These -organizations may have been created for specific purposes, or may not be -needed anymore. - -If you suspect your company has multiple Docker organizations: - -- Survey your teams to see if they have their own organizations -- Contact your Docker Support to get a list of organizations with users whose - emails match your domain name - -## Gather requirements - -[Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) lets you preset numerous configuration parameters for Docker Desktop. - -Work with the following stakeholders to establish your company's baseline -configuration: - -- Docker organization owner -- Development lead -- Information security representative - -Review these areas together: - -- Security features and - [enforcing sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) - for Docker Desktop users -- Additional Docker products included in your subscriptions - -To view the parameters that can be preset, see [Configure Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in). - -## Optional: Meet with the Docker Implementation team - -The Docker Implementation team can help you set up your organization, -configure SSO, enforce sign-in, and configure Docker Desktop. - -To schedule a meeting, email successteam@docker.com. diff --git a/content/guides/admin-set-up/deploy.md b/content/guides/admin-set-up/deploy.md deleted file mode 100644 index 30f202417b08..000000000000 --- a/content/guides/admin-set-up/deploy.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Deploy your Docker setup -description: Deploy your Docker setup across your company. -keywords: admin, onboarding, deployment, sso, rollout, organization -weight: 40 ---- - -> [!WARNING] -> -> Communicate with your users before proceeding, and confirm that your IT and -> MDM teams are prepared to handle any unexpected issues, as these steps will -> affect all existing users signing into your Docker organization. - -## Enforce SSO - -Enforcing SSO means that anyone who has a Docker profile with an email address -that matches your verified domain must sign in using your SSO connection. Make -sure the Identity provider groups associated with your SSO connection cover all -the developer groups that you want to have access to the Docker subscription. - -For instructions on how to enforce SSO, see [Enforce SSO](/manuals/enterprise/security/single-sign-on/connect.md). - -## Deploy configuration settings and enforce sign-in to users - -Have the MDM team deploy the configuration files for Docker to all users. - -## Next steps - -Congratulations, you've successfully completed the admin implementation process -for Docker. - -To continue optimizing your Docker environment: - -- Review your [organization's usage data](/manuals/admin/insights.md) to track adoption -- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for security insights -- Explore [additional security features](/manuals/enterprise/security/_index.md) to enhance your configuration diff --git a/content/guides/admin-set-up/finalize-plans-and-setup.md b/content/guides/admin-set-up/finalize-plans-and-setup.md deleted file mode 100644 index d31ec79b3082..000000000000 --- a/content/guides/admin-set-up/finalize-plans-and-setup.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Finalize plans and begin setup -description: Collaborate with your MDM team to distribute configurations and set up SSO and Docker product trials. -keywords: admin, onboarding, mdm, settings management, sso, configuration -weight: 20 ---- - -## Send finalized settings files to the MDM team - -After reaching an agreement with the relevant teams about your baseline and -security configurations as outlined in the previous section, configure Settings Management using either the [Docker Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md) or an -[`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md). - -Once the file is ready, collaborate with your MDM team to deploy your chosen -settings, along with your chosen method for [enforcing sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). - -> [!IMPORTANT] -> -> Test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely. - -## Manage your organizations - -If you have more than one organization, consider either [consolidating them -into one organization](/manuals/admin/organization/setup/orgs.md) or creating a -[Docker company](/manuals/admin/company/_index.md) to manage multiple -organizations. - -## Begin setup - -### Set up single sign-on and domain verification - -Single sign-on (SSO) lets developers authenticate using their identity -providers (IdPs) to access Docker. SSO is available for a whole company and all associated organizations, or an individual organization that has a Docker -Business subscription. For more information, see the -[documentation](/manuals/enterprise/security/single-sign-on/_index.md). - -You can also enable [SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) -for further automation of provisioning and deprovisioning of users. - -### Set up Docker product entitlements included in the subscription - -[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces -build times, both locally and in CI, by providing a dedicated remote builder -and shared cache. Powered by the cloud, developer time and local resources are -freed up so your team can focus on more important things, like innovation. -To get started, [set up a cloud builder](https://app.docker.com/build/). - -[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing -your software supply chain security. By analyzing your images, Docker Scout -compiles an inventory of components, also known as a Software Bill of Materials -(SBOM). The SBOM is matched against a continuously updated vulnerability -database to pinpoint security weaknesses. To get started, see -[Quickstart](/manuals/scout/quickstart.md). - -[Testcontainers Cloud](https://testcontainers.com/cloud/docs/) allows -developers to run containers in the cloud, removing the need to run heavy -containers on your local machine. - -[Docker Hardened Images](/manuals/dhi/_index.md) are minimal, secure, and production-ready container base and application images maintained by Docker. -Designed to reduce vulnerabilities and simplify compliance, DHIs integrate -easily into your existing Docker-based workflows with little to no retooling -required. - -### Ensure you're running a supported version of Docker Desktop - -> [!WARNING] -> -> This step could affect the experience for users on older versions of Docker -> Desktop. - -Existing users may be running outdated or unsupported versions of -Docker Desktop. All users should update to a supported version. Docker Desktop -versions released within the past 6 months from the latest release are supported. - -Use an MDM solution to manage the version of Docker Desktop for users. Users -may also get Docker Desktop directly from Docker or through a company software -portal. diff --git a/content/guides/admin-set-up/testing.md b/content/guides/admin-set-up/testing.md deleted file mode 100644 index a51b4c087e92..000000000000 --- a/content/guides/admin-set-up/testing.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Testing -description: Test your Docker setup. -keywords: admin, onboarding, testing, sso, scim, verification -weight: 30 ---- - -## SSO and SCIM testing - -Test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email -address linked to a Docker account that is part of the verified domain. -Developers who sign in using their Docker usernames remain unaffected by the -SSO and SCIM setup. - -> [!IMPORTANT] -> -> Some users may need CLI based logins to Docker Hub, and for this they will -> need a [personal access token (PAT)](/manuals/security/access-tokens.md). - -## Test Registry Access Management and Image Access Management - -> [!WARNING] -> -> Communicate with your users before proceeding, as this step will impact all -> existing users signing into your Docker organization. - -If you plan to use [Registry Access Management (RAM)](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/enterprise/security/hardened-desktop/image-access-management.md): - -1. Ensure your test developer signs in to Docker Desktop using their - organization credentials -2. Have them attempt to pull an unauthorized image or one from a disallowed - registry via the Docker CLI -3. Verify they receive an error message indicating that the registry is - restricted by the organization - -## Deploy settings and enforce sign in to test group - -Deploy the Docker settings and enforce sign-in for a small group of test users -via MDM. Have this group test their development workflows with containers on -Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement -function as expected. - -## Test Docker Build Cloud capabilities - -Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md). - -## Test Testcontainers Cloud - -Have a test developer [connect to Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) and run a container in -the cloud to verify the setup is working correctly. - -## Verify Docker Scout monitoring of repositories - -Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that -data is being properly received for the repositories where Docker Scout has -been enabled. - -## Verify access to Docker Hardened Images - -Have a test developer attempt to [pull a Docker Hardened Image](/manuals/dhi/get-started.md) to confirm that -the team has proper access and can integrate these images into their workflows. diff --git a/content/guides/admin-user-management.md b/content/guides/admin-user-management.md new file mode 100644 index 000000000000..492cdb8e2340 --- /dev/null +++ b/content/guides/admin-user-management.md @@ -0,0 +1,198 @@ +--- +title: Mastering user and access management +summary: Simplify user access while ensuring security and efficiency in Docker. +description: A guide for managing roles, provisioning users, and optimizing Docker access with tools like SSO and activity logs. +keywords: admin, user management, roles, permissions, sso, provisioning, access control +aliases: + - /guides/admin-user-management/audit-and-monitor/ + - /guides/admin-user-management/onboard/ + - /guides/admin-user-management/setup/ +params: + tags: [admin] + featured: false + time: 20 minutes + image: +--- + + +Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage. + +## Who's this for? + +- IT teams tasked with configuring and maintaining secure user access +- Security professionals focused on enforcing secure access practices +- Project managers overseeing team collaboration and resource management + +## What you'll learn + +- How to assess and manage Docker user access and align accounts with organizational needs +- When to use team configurations for scalable access control +- How to automate and streamline user provisioning with SSO, SCIM, and JIT +- How to get the most out of Docker's monitoring tools + +## Tools integration + +This guide covers integration with: + +- Okta +- Entra ID SAML 2.0 +- Azure Connect (OIDC) + +## Setting up roles and permissions in Docker + +With the right configurations, you can ensure your developers have easy access to necessary resources while preventing unauthorized access. This page guides you through identifying Docker users so you can allocate subscription seats efficiently within your Docker organization, and assigning roles to align with your organization's structure. + +### Identify your Docker users and accounts + +Before setting up roles and permissions, it's important to have a clear understanding of who in your organization requires Docker access. Focus on gathering a comprehensive view of active users, their roles within projects, and how they interact with Docker resources. This process can be supported by tools like device management software or manual assessments. Encourage all users to update their Docker accounts to use organizational email addresses, ensuring seamless integration with your subscription. + +For steps on how you can do this, see [step 1 of onboarding your organization](/manuals/accounts/organization/setup/onboard.md). + +### Assign roles strategically + +When you invite members to join your Docker organization, you assign them a role. + +Docker's predefined roles offer flexibility for various organizational needs. Assigning roles effectively ensures a balance of accessibility and security. + +- Member: Non-administrative role. Members can view other members that are in the same organization. +- Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions. +- Owner: Full organization administrative access. Owners can manage organization repositories, teams, members, settings, and billing. + +For more information, see [Roles and permissions](/manuals/security/roles-and-permissions.md). + +#### Enhance with teams + +Teams in Docker provide a structured way to manage member access and they provide an additional level of permissions. They simplify permission management and enable consistent application of policies. + +- Organize users into teams aligned with projects, departments, or functional roles. This approach helps streamline resource allocation and ensures clarity in access control. +- Assign permissions at the team level rather than individually. For instance, a development team might have "Read & Write" access to certain repositories, while a QA team has "Read-only" access. +- As teams grow or responsibilities shift, you can easily update permissions or add new members, maintaining consistency without reconfiguring individual settings. + +For more information, see [Create and manage a team](/manuals/accounts/organization/manage/manage-a-team.md). + +#### Example scenarios + +- Development teams: Assign the member role to developers, granting access to the repositories needed for coding and testing. +- Team leads: Assign the editor role to team leads for resource management and repository control within their teams. +- Organizational oversight: Restrict the organization owner or company owner roles to a select few trusted individuals responsible for billing and security settings. + +#### Best practices + +- Apply the principle of least privilege. Assign users only the minimum permissions necessary for their roles. +- Conduct regular reviews of role assignments to ensure they align with evolving team structures and organizational responsibilities. + +## Onboarding and managing roles and permissions in Docker + +This page guides you through onboarding owners and members, and using tools like SSO and SCIM to future-proof onboarding going forward. + +### Invite owners + +When you create a Docker organization, you automatically become its sole owner. While optional, adding additional owners can significantly ease the process of onboarding and managing your organization by distributing administrative responsibilities. It also ensures continuity and prevents blockers if the primary owner is unavailable. + +For detailed information on owners, see [Roles and permissions](/manuals/security/roles-and-permissions.md). + +### Invite members and assign roles + +Members are granted controlled access to resources and enjoy enhanced organizational benefits. When you invite members to join your Docker organization, you immediately assign them a role. + +#### Benefits of inviting members + +- Enhanced visibility: Gain insights into user activity, making it easier to monitor access and enforce security policies. +- Streamlined collaboration: Help members collaborate effectively by granting access to shared resources and repositories. +- Improved resource management: Organize and track users within your organization, ensuring optimal allocation of resources. +- Access to enhanced features: Members benefit from organization-wide perks, such as increased pull limits and access to premium Docker features. +- Security control: Apply and enforce security settings at an organizational level, reducing risks associated with unmanaged accounts. + +For detailed information, see [Manage organization members](/manuals/accounts/organization/manage/members.md). + +### Future-proof user management + +A robust, future-proof approach to user management combines automated provisioning, centralized authentication, and dynamic access control. Implementing these practices ensures a scalable, secure, and efficient environment. + +#### Secure user authentication with single sign-on (SSO) + +Integrating Docker with your identity provider streamlines user access and enhances security. + +SSO: + +- Simplifies sign in, as users sign in with their organizational credentials. +- Reduces password-related vulnerabilities. +- Simplifies onboarding as it works seamlessly with SCIM and group mapping for automated provisioning. + +For more information, see the [SSO documentation](/manuals/security/authentication/single-sign-on/_index.md). + +#### Automate onboarding with SCIM and JIT provisioning + +Streamline user provisioning and role management with [SCIM](/manuals/security/provisioning/scim/_index.md) and [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md). + +With SCIM you can: + +- Sync users and roles automatically with your identity provider. +- Automate adding, updating, or removing users based on directory changes. + +With JIT provisioning you can: + +- Automatically add users upon first sign in based on [group mapping](#simplify-access-with-group-mapping). +- Reduce overhead by eliminating pre-invite steps. + +#### Simplify access with group mapping + +Group mapping automates permissions management by linking identity provider groups to Docker roles and teams. + +It also: + +- Reduces manual errors in role assignments. +- Ensures consistent access control policies. +- Help you scale permissions as teams grow or change. + +For more information on how it works, see [Group mapping](/manuals/security/provisioning/scim/group-mapping.md). + +## Monitoring and insights + +Activity logs and Insights are useful tools for user and access management in Docker. They provide visibility into user actions, team workflows, and organizational trends, helping enhance security, ensure compliance, and boost productivity. + +### Activity logs + +Activity logs track events at the organization and repository levels, offering a clear view of activities like repository changes, team updates, and billing adjustments. + +Activity logs are available for Docker Team or Docker Business plans, with data retained for three months. + +#### Key features + +- Change tracking: View what changed, who made the change, and when. +- Comprehensive reporting: Monitor critical events such as repository creation, deletion, privacy changes, and role assignments. + +#### Example scenarios + +- Audit trail for security: A repository’s privacy settings were updated unexpectedly. The activity logs reveal which user made the change and when, helping administrators address potential security risks. +- Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint. +- Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance. + +For more information, see [Activity logs](/manuals/accounts/organization/activity-logs.md). + +### Insights + +Insights provide data-driven views of Docker usage to improve team productivity and resource allocation. + +#### Key benefits + +- Standardized environments: Ensure consistent configurations and enforce best practices across teams. +- Improved visibility: Monitor metrics like Docker Desktop usage, builds, and container activity to understand team workflows and engagement. +- Optimized resources: Track license usage and feature adoption to maximize the value of your Docker subscription. + +#### Example scenarios + +- Usage trends: Identify underutilized licenses or resources, allowing reallocation to more active teams. +- Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes. +- Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency. + +For more information, see [Insights](/manuals/accounts/organization/insights.md). + +### Next steps + +Now that you've mastered user and access management in Docker, you can: + +- Review your [activity logs](/manuals/accounts/organization/activity-logs.md) regularly to maintain security awareness +- Check your [Insights dashboard](/manuals/accounts/organization/insights.md) to identify opportunities for optimization +- Explore [advanced security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to further enhance your Docker environment +- Share best practices with your team to ensure consistent adoption of security policies diff --git a/content/guides/admin-user-management/_index.md b/content/guides/admin-user-management/_index.md deleted file mode 100644 index 7fe711c9daf5..000000000000 --- a/content/guides/admin-user-management/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Mastering user and access management -summary: Simplify user access while ensuring security and efficiency in Docker. -description: A guide for managing roles, provisioning users, and optimizing Docker access with tools like SSO and activity logs. -keywords: admin, user management, roles, permissions, sso, provisioning, access control -tags: [admin] -params: - featured: false - time: 20 minutes - image: - resource_links: - - title: Overview of Administration in Docker - url: /admin/ - - title: Single sign-on - url: /security/for-admins/single-sign-on/ - - title: Onboard your organization - url: /admin/organization/setup/onboard/ - - title: Roles and permissions - url: /security/for-admins/roles-and-permissions/ - - title: Insights - url: /admin/insights/ - - title: Activity logs - url: /admin/activity-logs/ ---- - -Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage. - -## Who's this for? - -- IT teams tasked with configuring and maintaining secure user access -- Security professionals focused on enforcing secure access practices -- Project managers overseeing team collaboration and resource management - -## What you'll learn - -- How to assess and manage Docker user access and align accounts with organizational needs -- When to use team configurations for scalable access control -- How to automate and streamline user provisioning with SSO, SCIM, and JIT -- How to get the most out of Docker's monitoring tools - -## Tools integration - -This guide covers integration with: - -- Okta -- Entra ID SAML 2.0 -- Azure Connect (OIDC) diff --git a/content/guides/admin-user-management/audit-and-monitor.md b/content/guides/admin-user-management/audit-and-monitor.md deleted file mode 100644 index 5fd0df91f1e2..000000000000 --- a/content/guides/admin-user-management/audit-and-monitor.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Monitoring and insights -description: Track user actions, team workflows, and organizational trends with Activity logs and Insights to enhance security and productivity in Docker. -keywords: organizational insights, user management, access control, security, monitoring, admins -weight: 30 ---- - -Activity logs and Insights are useful tools for user and access management in Docker. They provide visibility into user actions, team workflows, and organizational trends, helping enhance security, ensure compliance, and boost productivity. - -## Activity logs - -Activity logs track events at the organization and repository levels, offering a clear view of activities like repository changes, team updates, and billing adjustments. - -Activity logs are available for Docker Team or Docker Business plans, with data retained for three months. - -### Key features - -- Change tracking: View what changed, who made the change, and when. -- Comprehensive reporting: Monitor critical events such as repository creation, deletion, privacy changes, and role assignments. - -### Example scenarios - -- Audit trail for security: A repository’s privacy settings were updated unexpectedly. The activity logs reveal which user made the change and when, helping administrators address potential security risks. -- Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint. -- Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance. - -For more information, see [Activity logs](/manuals/admin/activity-logs.md). - -## Insights - -Insights provide data-driven views of Docker usage to improve team productivity and resource allocation. - -### Key benefits - -- Standardized environments: Ensure consistent configurations and enforce best practices across teams. -- Improved visibility: Monitor metrics like Docker Desktop usage, builds, and container activity to understand team workflows and engagement. -- Optimized resources: Track license usage and feature adoption to maximize the value of your Docker subscription. - -### Example scenarios - -- Usage trends: Identify underutilized licenses or resources, allowing reallocation to more active teams. -- Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes. -- Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency. - -For more information, see [Insights](/manuals/admin/insights.md). - -## Next steps - -Now that you've mastered user and access management in Docker, you can: - -- Review your [activity logs](/manuals/admin/activity-logs.md) regularly to maintain security awareness -- Check your [Insights dashboard](/manuals/admin/insights.md) to identify opportunities for optimization -- Explore [advanced security features](/manuals/enterprise/security/_index.md) to further enhance your Docker environment -- Share best practices with your team to ensure consistent adoption of security policies diff --git a/content/guides/admin-user-management/onboard.md b/content/guides/admin-user-management/onboard.md deleted file mode 100644 index a3d0c075b03b..000000000000 --- a/content/guides/admin-user-management/onboard.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Onboarding and managing roles and permissions in Docker -description: Learn how to manage roles, invite members, and implement scalable access control in Docker for secure and efficient collaboration. -keywords: sso, scim, jit, invite members, docker hub, docker admin console, onboarding, security -weight: 20 ---- - -This page guides you through onboarding owners and members, and using tools like SSO and SCIM to future-proof onboarding going forward. - -## Invite owners - -When you create a Docker organization, you automatically become its sole owner. While optional, adding additional owners can significantly ease the process of onboarding and managing your organization by distributing administrative responsibilities. It also ensures continuity and prevents blockers if the primary owner is unavailable. - -For detailed information on owners, see [Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). - -## Invite members and assign roles - -Members are granted controlled access to resources and enjoy enhanced organizational benefits. When you invite members to join your Docker organization, you immediately assign them a role. - -### Benefits of inviting members - -- Enhanced visibility: Gain insights into user activity, making it easier to monitor access and enforce security policies. -- Streamlined collaboration: Help members collaborate effectively by granting access to shared resources and repositories. -- Improved resource management: Organize and track users within your organization, ensuring optimal allocation of resources. -- Access to enhanced features: Members benefit from organization-wide perks, such as increased pull limits and access to premium Docker features. -- Security control: Apply and enforce security settings at an organizational level, reducing risks associated with unmanaged accounts. - -For detailed information, see [Manage organization members](/manuals/admin/organization/manage/members.md). - -## Future-proof user management - -A robust, future-proof approach to user management combines automated provisioning, centralized authentication, and dynamic access control. Implementing these practices ensures a scalable, secure, and efficient environment. - -### Secure user authentication with single sign-on (SSO) - -Integrating Docker with your identity provider streamlines user access and enhances security. - -SSO: - -- Simplifies sign in, as users sign in with their organizational credentials. -- Reduces password-related vulnerabilities. -- Simplifies onboarding as it works seamlessly with SCIM and group mapping for automated provisioning. - -For more information, see the [SSO documentation](/manuals/enterprise/security/single-sign-on/_index.md). - -### Automate onboarding with SCIM and JIT provisioning - -Streamline user provisioning and role management with [SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) and [Just-in-Time (JIT) provisioning](/manuals/enterprise/security/provisioning/just-in-time.md). - -With SCIM you can: - -- Sync users and roles automatically with your identity provider. -- Automate adding, updating, or removing users based on directory changes. - -With JIT provisioning you can: - -- Automatically add users upon first sign in based on [group mapping](#simplify-access-with-group-mapping). -- Reduce overhead by eliminating pre-invite steps. - -### Simplify access with group mapping - -Group mapping automates permissions management by linking identity provider groups to Docker roles and teams. - -It also: - -- Reduces manual errors in role assignments. -- Ensures consistent access control policies. -- Help you scale permissions as teams grow or change. - -For more information on how it works, see [Group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md). diff --git a/content/guides/admin-user-management/setup.md b/content/guides/admin-user-management/setup.md deleted file mode 100644 index 7bf82efeb714..000000000000 --- a/content/guides/admin-user-management/setup.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Setting up roles and permissions in Docker -description: A guide to securely managing access and collaboration in Docker through roles and teams. -keywords: Docker roles, permissions management, access control, IT administration, team collaboration, least privilege, security, Docker Teams, role-based access -weight: 10 ---- - -With the right configurations, you can ensure your developers have easy access to necessary resources while preventing unauthorized access. This page guides you through identifying Docker users so you can allocate subscription seats efficiently within your Docker organization, and assigning roles to align with your organization's structure. - -## Identify your Docker users and accounts - -Before setting up roles and permissions, it's important to have a clear understanding of who in your organization requires Docker access. Focus on gathering a comprehensive view of active users, their roles within projects, and how they interact with Docker resources. This process can be supported by tools like device management software or manual assessments. Encourage all users to update their Docker accounts to use organizational email addresses, ensuring seamless integration with your subscription. - -For steps on how you can do this, see [step 1 of onboarding your organization](/manuals/admin/organization/setup/onboard.md). - -## Assign roles strategically - -When you invite members to join your Docker organization, you assign them a role. - -Docker's predefined roles offer flexibility for various organizational needs. Assigning roles effectively ensures a balance of accessibility and security. - -- Member: Non-administrative role. Members can view other members that are in the same organization. -- Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions. -- Owner: Full organization administrative access. Owners can manage organization repositories, teams, members, settings, and billing. - -For more information, see [Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). - -### Enhance with teams - -Teams in Docker provide a structured way to manage member access and they provide an additional level of permissions. They simplify permission management and enable consistent application of policies. - -- Organize users into teams aligned with projects, departments, or functional roles. This approach helps streamline resource allocation and ensures clarity in access control. -- Assign permissions at the team level rather than individually. For instance, a development team might have "Read & Write" access to certain repositories, while a QA team has "Read-only" access. -- As teams grow or responsibilities shift, you can easily update permissions or add new members, maintaining consistency without reconfiguring individual settings. - -For more information, see [Create and manage a team](/manuals/admin/organization/manage/manage-a-team.md). - -### Example scenarios - -- Development teams: Assign the member role to developers, granting access to the repositories needed for coding and testing. -- Team leads: Assign the editor role to team leads for resource management and repository control within their teams. -- Organizational oversight: Restrict the organization owner or company owner roles to a select few trusted individuals responsible for billing and security settings. - -### Best practices - -- Apply the principle of least privilege. Assign users only the minimum permissions necessary for their roles. -- Conduct regular reviews of role assignments to ensure they align with evolving team structures and organizational responsibilities. diff --git a/content/guides/agentic-ai.md b/content/guides/agentic-ai.md index 9fb50bf5665e..c055d50f31bf 100644 --- a/content/guides/agentic-ai.md +++ b/content/guides/agentic-ai.md @@ -5,7 +5,7 @@ keywords: AI, Docker, Model Runner, MCP Toolkit, AI agents, application developm summary: | Learn how to create AI agent applications using Docker Model Runner, and MCP Toolkit. params: - tags: [AI] + tags: [ai] time: 30 minutes --- @@ -49,11 +49,11 @@ shows how Docker ties them all together with the following tools: - [Docker Model Runner](../manuals/ai/model-runner/_index.md) lets you run LLMs locally with simple command and OpenAI-compatible APIs. - [Docker MCP Catalog and - Toolkit](../manuals/ai/mcp-catalog-and-toolkit/_index.md) helps you discover + Toolkit](../manuals/desktop/features/mcp-catalog-and-toolkit/_index.md) helps you discover and securely run external tools, like APIs and databases, using the Model Context Protocol (MCP). -- [Docker MCP Gateway](../manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) lets you orchestrate and manage MCP servers. -- [Docker Compose](/manuals/ai/compose/models-and-compose.md) is the tool that ties it all +- [Docker MCP Gateway](../manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) lets you orchestrate and manage MCP servers. +- [Docker Compose](/manuals/compose/how-tos/models-and-compose.md) is the tool that ties it all together, letting you define and run multi-container applications with a single file. @@ -337,11 +337,11 @@ that support agentic AI development: - [Docker Model Runner](../manuals/ai/model-runner/_index.md): Run and serve open-source models locally via OpenAI-compatible APIs. - [Docker MCP Catalog and - Toolkit](../manuals/ai/mcp-catalog-and-toolkit/_index.md): Launch and manage + Toolkit](../manuals/desktop/features/mcp-catalog-and-toolkit/_index.md): Launch and manage tool integrations that follow the Model Context Protocol (MCP) standard. -- [Docker MCP Gateway](../manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md): Orchestrate and manage +- [Docker MCP Gateway](../manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md): Orchestrate and manage MCP servers to connect agents to external tools and services. -- [Docker Compose](/manuals/ai/compose/models-and-compose.md): Define and run +- [Docker Compose](/manuals/compose/how-tos/models-and-compose.md): Define and run multi-container agentic AI applications with a single file, using the same workflow. diff --git a/content/guides/angular.md b/content/guides/angular.md new file mode 100644 index 000000000000..df8b2109ca51 --- /dev/null +++ b/content/guides/angular.md @@ -0,0 +1,805 @@ +--- +title: Angular language-specific guide +linkTitle: Angular +description: Containerize and develop Angular apps using Docker +keywords: getting started, angular, docker, language, Dockerfile +summary: | + This guide explains how to containerize Angular applications using Docker. +aliases: + - /guides/angular/configure-github-actions/ + - /guides/angular/containerize/ + - /guides/angular/deploy/ + - /guides/angular/develop/ + - /guides/angular/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +The Angular language-specific guide shows you how to containerize an Angular application using Docker, following best practices for creating efficient, production-ready containers. + +[Angular](https://angular.dev/) is a robust and widely adopted framework for building dynamic, enterprise-grade web applications. However, managing dependencies, environments, and deployments can become complex as applications scale. Docker streamlines these challenges by offering a consistent, isolated environment for development and production. + +> **Acknowledgment** +> +> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource essential for the community, helping developers navigate and optimize their Docker workflows. + +--- + +## What will you learn? + +In this guide, you will learn how to: + +- Containerize and run an Angular application using Docker. +- Set up a local development environment for Angular inside a container. +- Run tests for your Angular application within a Docker container. + +You'll start by containerizing an existing Angular application and work your way up to production-level deployments. + +--- + +## Prerequisites + +Before you begin, ensure you have a working knowledge of: + +- Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). +- Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. +- Familiarity with [Angular](https://angular.io/) fundamentals. +- Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +Once you've completed the Angular getting started modules, you’ll be fully prepared to containerize your own Angular application using the detailed examples and best practices outlined in this guide. + +## Containerize an Angular Application + +### Prerequisites + +Before you begin, make sure the following tools are installed and available on your system: + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +> **New to Docker?** +> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. + +--- + +### Overview + +This guide walks you through the complete process of containerizing an Angular application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. + +By the end of this guide, you will: + +- Containerize an Angular application using Docker. +- Create and optimize a Dockerfile for production builds. +- Use multi-stage builds to minimize image size. +- Serve the application efficiently with a custom Nginx configuration. +- Build secure and maintainable Docker images by following best practices. + +--- + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command +to clone the git repository: + +```console +$ git clone https://github.com/kristiyan-velkov/docker-angular-sample +``` + +--- + +### Build the Docker image + +Angular is a front-end framework that compiles into static assets, so the Dockerfile uses a multi-stage build: one stage compiles the app with Node.js, and a second minimal stage serves the static output with Nginx. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +#### Step 1: Create the Dockerfile + +Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). + +Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +> [!IMPORTANT] +> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. +> +> Official Node.js Docker Images: https://hub.docker.com/_/node + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} +Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Node.js DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/node:24-alpine3.22-dev + ``` + +In the following Dockerfile, the `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image. + +```dockerfile +# ========================================= +# Stage 1: Build the Angular Application +# ========================================= + +# Use a lightweight DHI Node.js image for building +FROM dhi.io/node:24-alpine3.22-dev AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the Angular application +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html + +# Use a non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default Nginx container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Image" >}} + +Create a file named `Dockerfile` with the following contents: + +```dockerfile +# ========================================= +# Stage 1: Build the Angular Application +# ========================================= +ARG NODE_VERSION=24.12.0-alpine +ARG NGINX_VERSION=alpine3.22 + +# Use a lightweight Node.js image for building (customizable via ARG) +FROM node:${NODE_VERSION} AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json *package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the Angular application +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html + +# Use a built-in non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default Nginx container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +> [!NOTE] +> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. +> Running as a non-root user in the final image: +> +> - Reduces the attack surface +> - Aligns with Docker’s recommendations for container hardening +> - Helps comply with stricter security policies in production environments + +{{< /tab >}} +{{< /tabs >}} + +#### Step 2: Create the compose.yaml file + +Create a file named `compose.yaml` with the following contents: + +```yaml {collapse=true,title=compose.yaml} +services: + server: + build: + context: . + ports: + - 8080:8080 +``` + +#### Step 3: Create the .dockerignore file + +The `.dockerignore` file tells Docker which files and folders to exclude when building the image. + +> [!NOTE] +> This helps: +> +> - Reduce image size +> - Speed up the build process +> - Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. +> +> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). + +Create a file named `.dockerignore` with the following contents: + +```dockerignore +# ================================ +# Node and build output +# ================================ +node_modules +dist +out-tsc +.angular +.cache +.tmp + +# ================================ +# Testing & Coverage +# ================================ +coverage +jest +cypress +cypress/screenshots +cypress/videos +reports +playwright-report +.vite +.vitepress + +# ================================ +# Environment & log files +# ================================ +*.env* +!*.env.production +*.log +*.tsbuildinfo + +# ================================ +# IDE & OS-specific files +# ================================ +.vscode +.idea +.DS_Store +Thumbs.db +*.swp + +# ================================ +# Version control & CI files +# ================================ +.git +.gitignore + +# ================================ +# Docker & local orchestration +# ================================ +Dockerfile +Dockerfile.* +.dockerignore +docker-compose.yml +docker-compose*.yml + +# ================================ +# Miscellaneous +# ================================ +*.bak +*.old +*.tmp +``` + +#### Step 4: Create the `nginx.conf` file + +To serve your Angular application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. + +Create a file named `nginx.conf` in the root of your project directory, and add the following content: + +> [!NOTE] +> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/). + +```nginx +worker_processes auto; + +pid /tmp/nginx.pid; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + client_body_temp_path /tmp/client_temp; + proxy_temp_path /tmp/proxy_temp_path; + fastcgi_temp_path /tmp/fastcgi_temp; + uwsgi_temp_path /tmp/uwsgi_temp; + scgi_temp_path /tmp/scgi_temp; + + # Logging + access_log off; + error_log /dev/stderr warn; + + # Performance + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + keepalive_requests 1000; + + # Compression + gzip on; + gzip_vary on; + gzip_proxied any; + gzip_min_length 256; + gzip_comp_level 6; + gzip_types + text/plain + text/css + text/xml + text/javascript + application/javascript + application/x-javascript + application/json + application/xml + application/xml+rss + font/ttf + font/otf + image/svg+xml; + + server { + listen 8080; + server_name localhost; + + root /usr/share/nginx/html; + index index.html; + + # Angular Routing + location / { + try_files $uri $uri/ /index.html; + } + + # Static Assets Caching + location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { + expires 1y; + access_log off; + add_header Cache-Control "public, immutable"; + } + + # Optional: Explicit asset route + location /assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + } +} +``` + +#### Step 5: Build the Angular application image + +With your custom configuration in place, you're now ready to build the Docker image for your Angular application. + +The updated setup includes: + +- The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Angular. +- Efficient multi-stage Docker build, ensuring a small and secure final image. + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-angular-sample/ +│ ├── Dockerfile +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +Now that your Dockerfile is configured, you can build the Docker image for your Angular application. + +> [!NOTE] +> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). + +Run the following command from the root of your project: + +```console +$ docker build --tag docker-angular-sample . +``` + +What this command does: + +- Uses the Dockerfile in the current directory (.) +- Packages the application and its dependencies into a Docker image +- Tags the image as docker-angular-sample so you can reference it later + +#### Step 6: View local images + +After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. + +To list all locally available Docker images, run the following command: + +```console +$ docker images +``` + +Example Output: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-angular-sample latest 34e66bdb9d40 14 seconds ago 76.4MB +``` + +This output provides key details about your images: + +- **Repository** – The name assigned to the image. +- **Tag** – A version label that helps identify different builds (e.g., latest). +- **Image ID** – A unique identifier for the image. +- **Created** – The timestamp indicating when the image was built. +- **Size** – The total disk space used by the image. + +If the build was successful, you should see `docker-angular-sample` image listed. + +--- + +### Run the containerized application + +In the previous step, you created a Dockerfile for your Angular application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. + +Inside the `docker-angular-sample` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple Angular web application. + +Press `ctrl+c` in the terminal to stop your application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-angular-sample` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see your Angular application running in the browser. + +To confirm that the container is running, use `docker ps` command: + +```console +$ docker ps +``` + +This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. + +Example Output: + +```shell +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +eb13026806d1 docker-angular-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-angular-sample-server-1 +``` + +To stop the application, run: + +```console +$ docker compose down +``` + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +## Use containers for Angular development + +### Prerequisites + +Complete [Containerize Angular application](#containerize-an-angular-application). + +--- + +### Overview + +In this section, you'll learn how to set up both production and development environments for your containerized Angular application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch. + +You’ll learn how to: + +- Configure separate containers for production and development +- Enable automatic file syncing using Compose Watch in development +- Debug and live-preview your changes in real-time without manual rebuilds + +--- + +### Automatically update services (development mode) + +Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without restarting or rebuilding containers manually. + +### Step 1: Create a development Dockerfile + +Create a file named `Dockerfile.dev` in your project root with the following content: + +```dockerfile +# ========================================= +# Stage 1: Development - Angular Application +# ========================================= + +# Define the Node.js version to use (Alpine for a small footprint) +ARG NODE_VERSION=24.12.0-alpine + +# Set the base image for development +FROM node:${NODE_VERSION} AS dev + +# Set environment variable to indicate development mode +ENV NODE_ENV=development + +# Set the working directory inside the container +WORKDIR /app + +# Copy only the dependency files first to optimize Docker caching +COPY package.json package-lock.json* ./ + +# Install dependencies using npm with caching to speed up subsequent builds +RUN --mount=type=cache,target=/root/.npm npm install + +# Copy all application source files into the container +COPY . . + +# Expose the port Angular uses for the dev server (default is 4200) +EXPOSE 4200 + +# Start the Angular dev server and bind it to all network interfaces +CMD ["npm", "start", "--", "--host=0.0.0.0"] + +``` + +This file sets up a lightweight development environment for your Angular application using the dev server. + +#### Step 2: Update your `compose.yaml` file + +Open your `compose.yaml` file and define two services: one for production (`angular-prod`) and one for development (`angular-dev`). + +Here’s an example configuration for an Angular application: + +```yaml +services: + angular-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-angular-sample + ports: + - "8080:8080" + + angular-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "4200:4200" + develop: + watch: + - action: sync + path: . + target: /app +``` + +- The `angular-prod` service builds and serves your static production app using Nginx. +- The `angular-dev` service runs your Angular development server with live reload and hot module replacement. +- `watch` triggers file sync with Compose Watch. + +> [!NOTE] +> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-angular-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 4: Start Compose Watch + +Run the following command from the project root to start the container in watch mode + +```console +$ docker compose watch angular-dev +``` + +#### Step 5: Test Compose Watch with Angular + +To verify that Compose Watch is working correctly: + +1. Open the `src/app/app.component.html` file in your text editor. + +2. Locate the following line: + + ```html + <h1>Docker Angular Sample Application</h1> + ``` + +3. Change it to: + + ```html + <h1>Hello from Docker Compose Watch</h1> + ``` + +4. Save the file. + +5. Open your browser at [http://localhost:4200](http://localhost:4200). + +You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. + +--- + +## Run Angular tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize Angular application](#containerize-an-angular-application). + +### Overview + +Testing is a critical part of the development process. In this section, you'll learn how to: + +- Run Jasmine unit tests using the Angular CLI inside a Docker container. +- Use Docker Compose to isolate your test environment. +- Ensure consistency between local and container-based testing. + +The `docker-angular-sample` project comes pre-configured with Jasmine, so you can get started quickly without extra setup. + +--- + +### Run tests during development + +The `docker-angular-sample` application includes a sample test file at the following location: + +```console +$ src/app/app.component.spec.ts +``` + +This test uses Jasmine to validate the AppComponent logic. + +#### Step 1: Update compose.yaml + +Add a new service named `angular-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated, containerized environment. + +```yaml {hl_lines="22-26",linenos=true} +services: + angular-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "5173:5173" + develop: + watch: + - action: sync + path: . + target: /app + + angular-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-angular-sample + ports: + - "8080:8080" + + angular-test: + build: + context: . + dockerfile: Dockerfile.dev + command: ["npm", "run", "test"] +``` + +The angular-test service reuses the same `Dockerfile.dev` used for [development](#use-containers-for-angular-development) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. + +After completing the previous steps, your project directory should contain the following files: + +```text +├── docker-angular-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 2: Run the tests + +To execute your test suite inside the container, run the following command from your project root: + +```console +$ docker compose run --rm angular-test +``` + +This command will: + +- Start the `angular-test` service defined in your `compose.yaml` file. +- Execute the `npm run test` script using the same environment as development. +- Automatically removes the container after tests complete, using the [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. + +You should see output similar to the following: + +```shell +Test Suites: 1 passed, 1 total +Tests: 3 passed, 3 total +Snapshots: 0 total +Time: 1.529 s +``` + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +### Summary + +In this section, you learned how to run unit tests for your Angular application inside a Docker container using Jasmine and Docker Compose. + +What you accomplished: + +- Created a `angular-test` service in `compose.yaml` to isolate test execution. +- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. +- Ran tests inside the container using `docker compose run --rm angular-test`. +- Ensured reliable, repeatable testing across environments without depending on your local machine setup. + +--- + +### Related resources + +Explore official references and best practices to sharpen your Docker testing workflow: + +- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. +- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. +- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. +- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. diff --git a/content/guides/angular/_index.md b/content/guides/angular/_index.md deleted file mode 100644 index 6f28a0f99cf9..000000000000 --- a/content/guides/angular/_index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Angular language-specific guide -linkTitle: Angular -description: Containerize and develop Angular apps using Docker -keywords: getting started, angular, docker, language, Dockerfile -summary: | - This guide explains how to containerize Angular applications using Docker. -toc_min: 1 -toc_max: 2 -languages: [js] -params: - time: 20 minutes - ---- - -The Angular language-specific guide shows you how to containerize an Angular application using Docker, following best practices for creating efficient, production-ready containers. - -[Angular](https://angular.dev/) is a robust and widely adopted framework for building dynamic, enterprise-grade web applications. However, managing dependencies, environments, and deployments can become complex as applications scale. Docker streamlines these challenges by offering a consistent, isolated environment for development and production. - -> -> **Acknowledgment** -> -> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource essential for the community, helping developers navigate and optimize their Docker workflows. - ---- - -## What will you learn? - -In this guide, you will learn how to: - -- Containerize and run an Angular application using Docker. -- Set up a local development environment for Angular inside a container. -- Run tests for your Angular application within a Docker container. -- Configure a CI/CD pipeline using GitHub Actions for your containerized app. -- Deploy the containerized Angular application to a local Kubernetes cluster for testing and debugging. - -You'll start by containerizing an existing Angular application and work your way up to production-level deployments. - ---- - -## Prerequisites - -Before you begin, ensure you have a working knowledge of: - -- Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). -- Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. -- Familiarity with [Angular](https://angular.io/) fundamentals. -- Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -Once you've completed the Angular getting started modules, you’ll be fully prepared to containerize your own Angular application using the detailed examples and best practices outlined in this guide. \ No newline at end of file diff --git a/content/guides/angular/configure-github-actions.md b/content/guides/angular/configure-github-actions.md deleted file mode 100644 index 335ea0f304d5..000000000000 --- a/content/guides/angular/configure-github-actions.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 60 -keywords: CI/CD, GitHub( Actions), Angular -description: Learn how to configure CI/CD using GitHub Actions for your Angular application. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize an Angular application](containerize.md). - -You must also have: -- A [GitHub](https://github.com/signup) account. -- A verified [Docker Hub](https://hub.docker.com/signup) account. - ---- - -## Overview - -In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically: - -- Build your Angular application inside a Docker container. -- Run tests in a consistent environment. -- Push the production-ready image to [Docker Hub](https://hub.docker.com). - ---- - -## Connect your GitHub repository to Docker Hub - -To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository. - -### Step 1: Generate Docker Hub credentials and set GitHub secrets - -1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com) - 1. Go to your **Docker Hub account → Account Settings → Security**. - 2. Generate a new Access Token with **Read/Write** permissions. - 3. Name it something like `docker-angular-sample`. - 4. Copy and save the token — you’ll need it in Step 4. - -2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/) - 1. Go to your **Docker Hub account → Create a repository**. - 2. For the Repository Name, use something descriptive — for example: `angular-sample`. - 3. Once created, copy and save the repository name — you’ll need it in Step 4. - -3. Create a new [GitHub repository](https://github.com/new) for your Angular project - -4. Add Docker Hub credentials as GitHub repository secrets - - In your newly created GitHub repository: - - 1. Navigate to: - **Settings → Secrets and variables → Actions → New repository secret**. - - 2. Add the following secrets: - - | Name | Value | - |-------------------|--------------------------------| - | `DOCKER_USERNAME` | Your Docker Hub username | - | `DOCKERHUB_TOKEN` | Your Docker Hub access token (created in Step 1) | - | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2) | - - These secrets allow GitHub Actions to authenticate securely with Docker Hub during automated workflows. - -5. Connect Your Local Project to GitHub - - Link your local project `docker-angular-sample` to the GitHub repository you just created by running the following command from your project root: - - ```console - $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git - ``` - - >[!IMPORTANT] - >Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name. - - To confirm that your local project is correctly connected to the remote GitHub repository, run: - - ```console - $ git remote -v - ``` - - You should see output similar to: - - ```console - origin https://github.com/{your-username}/{your-repository-name}.git (fetch) - origin https://github.com/{your-username}/{your-repository-name}.git (push) - ``` - - This confirms that your local repository is properly linked and ready to push your source code to GitHub. - -6. Push your source code to GitHub - - Follow these steps to commit and push your local project to your GitHub repository: - - 1. Stage all files for commit. - - ```console - $ git add -A - ``` - This command stages all changes — including new, modified, and deleted files — preparing them for commit. - - - 2. Commit the staged changes with a descriptive message. - - ```console - $ git commit -m "Initial commit" - ``` - This command creates a commit that snapshots the staged changes with a descriptive message. - - 3. Push the code to the `main` branch. - - ```console - $ git push -u origin main - ``` - This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch. - -Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically. - -> [!NOTE] -> Learn more about the Git commands used in this step: -> - [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit -> - [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes -> - [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository -> - [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs - ---- - -### Step 2: Set up the workflow - -Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub. - -1. Go to your repository on GitHub and select the **Actions** tab in the top menu. - -2. Select **Set up a workflow yourself** when prompted. - - This opens an inline editor to create a new workflow file. By default, it will be saved to: - `.github/workflows/main.yml` - - -3. Add the following workflow configuration to the new file: - -```yaml -name: CI/CD – Angular Application with Docker - -on: - push: - branches: [main] - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - -jobs: - build-test-push: - name: Build, Test, and Push Docker Image - runs-on: ubuntu-latest - - steps: - # 1. Checkout source code - - name: Checkout source code - uses: actions/checkout@{{% param "checkout_action_version" %}} - with: - fetch-depth: 0 - - # 2. Set up Docker Buildx - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - # 3. Cache Docker layers - - name: Cache Docker layers - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: | - ${{ runner.os }}-buildx- - - # 4. Cache npm dependencies - - name: Cache npm dependencies - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: ~/.npm - key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-npm- - - # 5. Extract metadata - - name: Extract metadata - id: meta - run: | - echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT" - echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT" - - # 6. Build dev Docker image - - name: Build Docker image for tests - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile.dev - tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest - load: true - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - - # 7. Run Angular tests with Jasmine - - name: Run Angular Jasmine tests inside container - run: | - docker run --rm \ - --workdir /app \ - --entrypoint "" \ - ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \ - sh -c "npm ci && npm run test -- --ci --runInBand" - env: - CI: true - NODE_ENV: test - timeout-minutes: 10 - - # 8. Log in to Docker Hub - - name: Log in to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - # 9. Build and push production image - - name: Build and push production image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile - push: true - platforms: linux/amd64,linux/arm64 - tags: | - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }} - cache-from: type=local,src=/tmp/.buildx-cache -``` - -This workflow performs the following tasks for your Angular application: -- Triggers on every `push` or `pull request` targeting the `main` branch. -- Builds a development Docker image using `Dockerfile.dev`, optimized for testing. -- Executes unit tests using Vitest inside a clean, containerized environment to ensure consistency. -- Halts the workflow immediately if any test fails — enforcing code quality. -- Caches both Docker build layers and npm dependencies for faster CI runs. -- Authenticates securely with Docker Hub using GitHub repository secrets. -- Builds a production-ready image using the `prod` stage in `Dockerfile`. -- Tags and pushes the final image to Docker Hub with both `latest` and short SHA tags for traceability. - -> [!NOTE] -> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - ---- - -### Step 3: Run the workflow - -After you've added your workflow file, it's time to trigger and observe the CI/CD process in action. - -1. Commit and push your workflow file - - - Select "Commit changes…" in the GitHub editor. - - - This push will automatically trigger the GitHub Actions pipeline. - -2. Monitor the workflow execution - - - Go to the Actions tab in your GitHub repository. - - Click into the workflow run to follow each step: **build**, **test**, and (if successful) **push**. - -3. Verify the Docker image on Docker Hub - - - After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories). - - You should see a new image under your repository with: - - Repository name: `${your-repository-name}` - - Tags include: - - `latest` – represents the most recent successful build; ideal for quick testing or deployment. - - `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability. - -> [!TIP] Protect your main branch -> To maintain code quality and prevent accidental direct pushes, enable branch protection rules: -> - Navigate to your **GitHub repo → Settings → Branches**. -> - Under Branch protection rules, click **Add rule**. -> - Specify `main` as the branch name. -> - Enable options like: -> - *Require a pull request before merging*. -> - *Require status checks to pass before merging*. -> -> This ensures that only tested and reviewed code is merged into `main` branch. ---- - -## Summary - -In this section, you set up a complete CI/CD pipeline for your containerized Angular application using GitHub Actions. - -Here's what you accomplished: - -- Created a new GitHub repository specifically for your project. -- Generated a secure Docker Hub access token and added it to GitHub as a secret. -- Defined a GitHub Actions workflow that: - - Build your application inside a Docker container. - - Run tests in a consistent, containerized environment. - - Push a production-ready image to Docker Hub if tests pass. -- Triggered and verified the workflow execution through GitHub Actions. -- Confirmed that your image was successfully published to Docker Hub. - -With this setup, your Angular application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity. - ---- - -## Related resources - -Deepen your understanding of automation and best practices for containerized apps: - -- [Introduction to GitHub Actions](/guides/gha.md) – Learn how GitHub Actions automate your workflows -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) – Set up container builds with GitHub Actions -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows -- [Compose file reference](/compose/compose-file/) – Full configuration reference for `compose.yaml` -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security - ---- - -## Next steps - -Next, learn how you can locally test and debug your Angular workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment. diff --git a/content/guides/angular/containerize.md b/content/guides/angular/containerize.md deleted file mode 100644 index 2ba56fc7c92b..000000000000 --- a/content/guides/angular/containerize.md +++ /dev/null @@ -1,529 +0,0 @@ ---- -title: Containerize an Angular Application -linkTitle: Containerize -weight: 10 -keywords: angular, node, image, initialize, build -description: Learn how to containerize an Angular application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability. - ---- - -## Prerequisites - -Before you begin, make sure the following tools are installed and available on your system: - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -> **New to Docker?** -> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. - ---- - -## Overview - -This guide walks you through the complete process of containerizing an Angular application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. - -By the end of this guide, you will: - -- Containerize an Angular application using Docker. -- Create and optimize a Dockerfile for production builds. -- Use multi-stage builds to minimize image size. -- Serve the application efficiently with a custom Nginx configuration. -- Build secure and maintainable Docker images by following best practices. - ---- - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command -to clone the git repository: - -```console -$ git clone https://github.com/kristiyan-velkov/docker-angular-sample -``` ---- - -## Build the Docker image - -Angular is a front-end framework that compiles into static assets, so the Dockerfile uses a multi-stage build: one stage compiles the app with Node.js, and a second minimal stage serves the static output with Nginx. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -### Step 1: Create the Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -> [!IMPORTANT] -> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. -> -> Official Node.js Docker Images: https://hub.docker.com/_/node - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} -Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -In the following Dockerfile, the `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image. - -```dockerfile -# ========================================= -# Stage 1: Build the Angular Application -# ========================================= - -# Use a lightweight DHI Node.js image for building -FROM dhi.io/node:24-alpine3.22-dev AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the Angular application -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html - -# Use a non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default Nginx container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` with the following contents: - -```dockerfile -# ========================================= -# Stage 1: Build the Angular Application -# ========================================= -ARG NODE_VERSION=24.12.0-alpine -ARG NGINX_VERSION=alpine3.22 - -# Use a lightweight Node.js image for building (customizable via ARG) -FROM node:${NODE_VERSION} AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json *package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the Angular application -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html - -# Use a built-in non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default Nginx container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -> [!NOTE] -> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. -> Running as a non-root user in the final image: ->- Reduces the attack surface ->- Aligns with Docker’s recommendations for container hardening ->- Helps comply with stricter security policies in production environments - -{{< /tab >}} -{{< /tabs >}} - -### Step 2: Create the compose.yaml file - -Create a file named `compose.yaml` with the following contents: - -```yaml {collapse=true,title=compose.yaml} -services: - server: - build: - context: . - ports: - - 8080:8080 -``` - -### Step 3: Create the .dockerignore file - -The `.dockerignore` file tells Docker which files and folders to exclude when building the image. - -> [!NOTE] ->This helps: ->- Reduce image size ->- Speed up the build process ->- Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. -> -> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). - -Create a file named `.dockerignore` with the following contents: - -```dockerignore -# ================================ -# Node and build output -# ================================ -node_modules -dist -out-tsc -.angular -.cache -.tmp - -# ================================ -# Testing & Coverage -# ================================ -coverage -jest -cypress -cypress/screenshots -cypress/videos -reports -playwright-report -.vite -.vitepress - -# ================================ -# Environment & log files -# ================================ -*.env* -!*.env.production -*.log -*.tsbuildinfo - -# ================================ -# IDE & OS-specific files -# ================================ -.vscode -.idea -.DS_Store -Thumbs.db -*.swp - -# ================================ -# Version control & CI files -# ================================ -.git -.gitignore - -# ================================ -# Docker & local orchestration -# ================================ -Dockerfile -Dockerfile.* -.dockerignore -docker-compose.yml -docker-compose*.yml - -# ================================ -# Miscellaneous -# ================================ -*.bak -*.old -*.tmp -``` - -### Step 4: Create the `nginx.conf` file - -To serve your Angular application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. - -Create a file named `nginx.conf` in the root of your project directory, and add the following content: - -> [!NOTE] -> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/). - - -```nginx -worker_processes auto; - -pid /tmp/nginx.pid; - -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - client_body_temp_path /tmp/client_temp; - proxy_temp_path /tmp/proxy_temp_path; - fastcgi_temp_path /tmp/fastcgi_temp; - uwsgi_temp_path /tmp/uwsgi_temp; - scgi_temp_path /tmp/scgi_temp; - - # Logging - access_log off; - error_log /dev/stderr warn; - - # Performance - sendfile on; - tcp_nopush on; - tcp_nodelay on; - keepalive_timeout 65; - keepalive_requests 1000; - - # Compression - gzip on; - gzip_vary on; - gzip_proxied any; - gzip_min_length 256; - gzip_comp_level 6; - gzip_types - text/plain - text/css - text/xml - text/javascript - application/javascript - application/x-javascript - application/json - application/xml - application/xml+rss - font/ttf - font/otf - image/svg+xml; - - server { - listen 8080; - server_name localhost; - - root /usr/share/nginx/html; - index index.html; - - # Angular Routing - location / { - try_files $uri $uri/ /index.html; - } - - # Static Assets Caching - location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { - expires 1y; - access_log off; - add_header Cache-Control "public, immutable"; - } - - # Optional: Explicit asset route - location /assets/ { - expires 1y; - add_header Cache-Control "public, immutable"; - } - } -} -``` - -### Step 5: Build the Angular application image - -With your custom configuration in place, you're now ready to build the Docker image for your Angular application. - -The updated setup includes: - -- The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Angular. -- Efficient multi-stage Docker build, ensuring a small and secure final image. - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-angular-sample/ -│ ├── Dockerfile -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -Now that your Dockerfile is configured, you can build the Docker image for your Angular application. - -> [!NOTE] -> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). - -Run the following command from the root of your project: - -```console -$ docker build --tag docker-angular-sample . -``` - -What this command does: -- Uses the Dockerfile in the current directory (.) -- Packages the application and its dependencies into a Docker image -- Tags the image as docker-angular-sample so you can reference it later - - -### Step 6: View local images - -After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. - -To list all locally available Docker images, run the following command: - -```console -$ docker images -``` - -Example Output: - -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-angular-sample latest 34e66bdb9d40 14 seconds ago 76.4MB -``` - -This output provides key details about your images: - -- **Repository** – The name assigned to the image. -- **Tag** – A version label that helps identify different builds (e.g., latest). -- **Image ID** – A unique identifier for the image. -- **Created** – The timestamp indicating when the image was built. -- **Size** – The total disk space used by the image. - -If the build was successful, you should see `docker-angular-sample` image listed. - ---- - -## Run the containerized application - -In the previous step, you created a Dockerfile for your Angular application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. - - -Inside the `docker-angular-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple Angular web application. - -Press `ctrl+c` in the terminal to stop your application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-angular-sample` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see your Angular application running in the browser. - - -To confirm that the container is running, use `docker ps` command: - -```console -$ docker ps -``` - -This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. - -Example Output: - -```shell -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -eb13026806d1 docker-angular-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-angular-sample-server-1 -``` - - -To stop the application, run: - -```console -$ docker compose down -``` - - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this guide, you learned how to containerize, build, and run an Angular application using Docker. By following best practices, you created a secure, optimized, and production-ready setup. - -What you accomplished: -- Created a multi-stage `Dockerfile` that compiles the Angular application and serves the static files using Nginx. -- Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient. -- Built your Docker image using `docker build`. -- Ran the container using `docker compose up`, both in the foreground and in detached mode. -- Verified that the app was running by visiting [http://localhost:8080](http://localhost:8080). -- Learned how to stop the containerized application using `docker compose down`. - -You now have a fully containerized Angular application, running in a Docker container, and ready for deployment across any environment with confidence and consistency. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker workflow: - -- [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds. -- [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile. -- [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images. -- [`docker compose up` CLI reference](/reference/cli/docker/compose/up/) – Start and run multi-container applications. -- [`docker compose down` CLI reference](/reference/cli/docker/compose/down/) – Stop and remove containers, networks, and volumes. - ---- - -## Next steps - -With your Angular application now containerized, you're ready to move on to the next step. - -In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine. - diff --git a/content/guides/angular/deploy.md b/content/guides/angular/deploy.md deleted file mode 100644 index f7b938449f73..000000000000 --- a/content/guides/angular/deploy.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Test your Angular deployment -linkTitle: Test your deployment -weight: 60 -keywords: deploy, kubernetes, angular -description: Learn how to deploy locally to test and debug your Kubernetes deployment - ---- - -## Prerequisites - -Before you begin, make sure you’ve completed the following: -- Complete all the previous sections of this guide, starting with [Containerize Angular application](containerize.md). -- [Enable Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -> **New to Kubernetes?** -> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work. - ---- - -## Overview - -This section guides you through deploying your containerized Angular application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster closely simulates a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production. - ---- - -## Create a Kubernetes YAML file - -Follow these steps to define your deployment configuration: - -1. In the root of your project, create a new file named: angular-sample-kubernetes.yaml - -2. Open the file in your IDE or preferred text editor. - -3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](configure-github-actions.md). - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: angular-sample - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: angular-sample - template: - metadata: - labels: - app: angular-sample - spec: - containers: - - name: angular-container - image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest - imagePullPolicy: Always - ports: - - containerPort: 8080 - resources: - limits: - cpu: "500m" - memory: "256Mi" - requests: - cpu: "250m" - memory: "128Mi" ---- -apiVersion: v1 -kind: Service -metadata: - name: angular-sample-service - namespace: default -spec: - type: NodePort - selector: - app: angular-sample - ports: - - port: 8080 - targetPort: 8080 - nodePort: 30001 -``` - -This manifest defines two key Kubernetes resources, separated by `---`: - -- Deployment - Deploys a single replica of your Angular application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow - (refer to [Automate your builds with GitHub Actions](configure-github-actions.md)). - The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production Angular app. - -- Service (NodePort) - Exposes the deployed pod to your local machine. - It forwards traffic from port `30001` on your host to port `8080` inside the container. - This lets you access the application in your browser at [http://localhost:30001](http://localhost:30001). - -> [!NOTE] -> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - ---- - -## Deploy and check your application - -Follow these steps to deploy your containerized Angular app into a local Kubernetes cluster and verify that it’s running correctly. - -### Step 1. Apply the Kubernetes configuration - -In your terminal, navigate to the directory where your `angular-sample-kubernetes.yaml` file is located, then deploy the resources using: - -```console - $ kubectl apply -f angular-sample-kubernetes.yaml -``` - -If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created: - -```shell - deployment.apps/angular-sample created - service/angular-sample-service created -``` - -This confirms that both the Deployment and the Service were successfully created and are now running inside your local cluster. - -### Step 2. Check the deployment status - -Run the following command to check the status of your deployment: - -```console - $ kubectl get deployments -``` - -You should see output similar to the following: - -```shell - NAME READY UP-TO-DATE AVAILABLE AGE - angular-sample 1/1 1 1 14s -``` - -This confirms that your pod is up and running with one replica available. - -### Step 3. Verify the service exposure - -Check if the NodePort service is exposing your app to your local machine: - -```console -$ kubectl get services -``` - -You should see something like: - -```shell -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -angular-sample-service NodePort 10.100.185.105 <none> 8080:30001/TCP 1m -``` - -This output confirms that your app is available via NodePort on port 30001. - -### Step 4. Access your app in the browser - -Open your browser and navigate to [http://localhost:30001](http://localhost:30001). - -You should see your production-ready Angular Sample application running — served by your local Kubernetes cluster. - -### Step 5. Clean up Kubernetes resources - -Once you're done testing, you can delete the deployment and service using: - -```console - $ kubectl delete -f angular-sample-kubernetes.yaml -``` - -Expected output: - -```shell - deployment.apps "angular-sample" deleted - service "angular-sample-service" deleted -``` - -This ensures your cluster stays clean and ready for the next deployment. - ---- - -## Summary - -In this section, you learned how to deploy your Angular application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud. - -What you accomplished: - -- Created a Kubernetes Deployment and NodePort Service for your Angular app -- Used `kubectl apply` to deploy the application locally -- Verified the app was running and accessible at `http://localhost:30001` -- Cleaned up your Kubernetes resources after testing - ---- - -## Related resources - -Explore official references and best practices to sharpen your Kubernetes deployment workflow: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more. -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) – Use Docker Desktop’s built-in Kubernetes support for local testing and development. -- [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line. -- [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments. -- [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic. \ No newline at end of file diff --git a/content/guides/angular/develop.md b/content/guides/angular/develop.md deleted file mode 100644 index 02c65ac6ba92..000000000000 --- a/content/guides/angular/develop.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Use containers for Angular development -linkTitle: Develop your app -weight: 30 -keywords: angular, development, node -description: Learn how to develop your Angular application locally using containers. - ---- - -## Prerequisites - -Complete [Containerize Angular application](containerize.md). - ---- - -## Overview - -In this section, you'll learn how to set up both production and development environments for your containerized Angular application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch. - -You’ll learn how to: -- Configure separate containers for production and development -- Enable automatic file syncing using Compose Watch in development -- Debug and live-preview your changes in real-time without manual rebuilds - ---- - -## Automatically update services (development mode) - -Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without restarting or rebuilding containers manually. - -## Step 1: Create a development Dockerfile - -Create a file named `Dockerfile.dev` in your project root with the following content: - -```dockerfile -# ========================================= -# Stage 1: Development - Angular Application -# ========================================= - -# Define the Node.js version to use (Alpine for a small footprint) -ARG NODE_VERSION=24.12.0-alpine - -# Set the base image for development -FROM node:${NODE_VERSION} AS dev - -# Set environment variable to indicate development mode -ENV NODE_ENV=development - -# Set the working directory inside the container -WORKDIR /app - -# Copy only the dependency files first to optimize Docker caching -COPY package.json package-lock.json* ./ - -# Install dependencies using npm with caching to speed up subsequent builds -RUN --mount=type=cache,target=/root/.npm npm install - -# Copy all application source files into the container -COPY . . - -# Expose the port Angular uses for the dev server (default is 4200) -EXPOSE 4200 - -# Start the Angular dev server and bind it to all network interfaces -CMD ["npm", "start", "--", "--host=0.0.0.0"] - -``` - -This file sets up a lightweight development environment for your Angular application using the dev server. - - -### Step 2: Update your `compose.yaml` file - -Open your `compose.yaml` file and define two services: one for production (`angular-prod`) and one for development (`angular-dev`). - -Here’s an example configuration for an Angular application: - -```yaml -services: - angular-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-angular-sample - ports: - - "8080:8080" - - angular-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "4200:4200" - develop: - watch: - - action: sync - path: . - target: /app -``` -- The `angular-prod` service builds and serves your static production app using Nginx. -- The `angular-dev` service runs your Angular development server with live reload and hot module replacement. -- `watch` triggers file sync with Compose Watch. - -> [!NOTE] -> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-angular-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 4: Start Compose Watch - -Run the following command from the project root to start the container in watch mode - -```console -$ docker compose watch angular-dev -``` - -### Step 5: Test Compose Watch with Angular - -To verify that Compose Watch is working correctly: - -1. Open the `src/app/app.component.html` file in your text editor. - -2. Locate the following line: - - ```html - <h1>Docker Angular Sample Application</h1> - ``` - -3. Change it to: - - ```html - <h1>Hello from Docker Compose Watch</h1> - ``` - -4. Save the file. - -5. Open your browser at [http://localhost:4200](http://localhost:4200). - -You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. - ---- - -## Summary - -In this section, you set up a complete development and production workflow for your Angular application using Docker and Docker Compose. - -Here’s what you accomplished: -- Created a `Dockerfile.dev` to streamline local development with hot reloading -- Defined separate `angular-dev` and `angular-prod` services in your `compose.yaml` file -- Enabled real-time file syncing using Compose Watch for a smoother development experience -- Verified that live updates work seamlessly by modifying and previewing a component - -With this setup, you're now equipped to build, run, and iterate on your Angular app entirely within containers—efficiently and consistently across environments. - ---- - -## Related resources - -Deepen your knowledge and improve your containerized development workflow with these guides: - -- [Using Compose Watch](/manuals/compose/how-tos/file-watch.md) – Automatically sync source changes during development -- [Multi-stage builds](/manuals/build/building/multi-stage.md) – Create efficient, production-ready Docker images -- [Dockerfile best practices](/build/building/best-practices/) – Write clean, secure, and optimized Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [Docker volumes](/storage/volumes/) – Persist and manage data between container runs - -## Next steps - -In the next section, you'll learn how to run unit tests for your Angular application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup. diff --git a/content/guides/angular/run-tests.md b/content/guides/angular/run-tests.md deleted file mode 100644 index 309097111465..000000000000 --- a/content/guides/angular/run-tests.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Run Angular tests in a container -linkTitle: Run your tests -weight: 40 -keywords: angular, test, jasmine -description: Learn how to run your Angular tests in a container. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize Angular application](containerize.md). - -## Overview - -Testing is a critical part of the development process. In this section, you'll learn how to: - -- Run Jasmine unit tests using the Angular CLI inside a Docker container. -- Use Docker Compose to isolate your test environment. -- Ensure consistency between local and container-based testing. - - -The `docker-angular-sample` project comes pre-configured with Jasmine, so you can get started quickly without extra setup. - ---- - -## Run tests during development - -The `docker-angular-sample` application includes a sample test file at the following location: - -```console -$ src/app/app.component.spec.ts -``` - -This test uses Jasmine to validate the AppComponent logic. - -### Step 1: Update compose.yaml - -Add a new service named `angular-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated, containerized environment. - -```yaml {hl_lines="22-26",linenos=true} -services: - angular-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "5173:5173" - develop: - watch: - - action: sync - path: . - target: /app - - angular-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-angular-sample - ports: - - "8080:8080" - - angular-test: - build: - context: . - dockerfile: Dockerfile.dev - command: ["npm", "run", "test"] - -``` - -The angular-test service reuses the same `Dockerfile.dev` used for [development](develop.md) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. - - -After completing the previous steps, your project directory should contain the following files: - -```text -├── docker-angular-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 2: Run the tests - -To execute your test suite inside the container, run the following command from your project root: - -```console -$ docker compose run --rm angular-test -``` - -This command will: -- Start the `angular-test` service defined in your `compose.yaml` file. -- Execute the `npm run test` script using the same environment as development. -- Automatically removes the container after tests complete, using the [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. - -You should see output similar to the following: - -```shell -Test Suites: 1 passed, 1 total -Tests: 3 passed, 3 total -Snapshots: 0 total -Time: 1.529 s -``` - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this section, you learned how to run unit tests for your Angular application inside a Docker container using Jasmine and Docker Compose. - -What you accomplished: -- Created a `angular-test` service in `compose.yaml` to isolate test execution. -- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. -- Ran tests inside the container using `docker compose run --rm angular-test`. -- Ensured reliable, repeatable testing across environments without depending on your local machine setup. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker testing workflow: - -- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. ---- - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Angular application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow. diff --git a/content/guides/azure-pipelines.md b/content/guides/azure-pipelines.md index 358133c1d8c7..27f218770fd7 100644 --- a/content/guides/azure-pipelines.md +++ b/content/guides/azure-pipelines.md @@ -5,7 +5,7 @@ summary: | Learn how to automate Docker image build and push using Azure Pipelines. keywords: azure pipelines, azure devops, ci/cd, docker hub, build and push, automation params: - tags: [devops] + tags: [cicd] time: 10 minutes --- @@ -175,7 +175,7 @@ stages: displayName: Build and Push Docker Image ``` -This stage executes only if the source branch is `main`. +This stage builds the image on both commit and pull request runs. The push task below runs only when the source branch is `main`. > [!TIP] > @@ -187,11 +187,11 @@ This stage executes only if the source branch is `main`. ```yaml jobs: - job: DockerJob - displayName: Build and Push - pool: - vmImage: ubuntu-latest - demands: - - docker + displayName: Build and Push + pool: + vmImage: ubuntu-latest + demands: + - docker ``` This job utilizes the latest Ubuntu VM image with Docker support, provided by Microsoft-hosted agents. It can be replaced with a custom pool for self-hosted agents if necessary. @@ -233,7 +233,7 @@ Uses a pre-configured Azure DevOps Docker registry service connection to authent #### Step 4.3: Build the Docker image ```yaml - - task: Docker@2 + - task: Docker@2 displayName: Build Docker Image inputs: command: build @@ -308,5 +308,5 @@ With this Azure Pipelines CI setup, you get: - [Azure Pipelines Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/?view=azure-devops): Comprehensive guide to configuring and managing CI/CD pipelines in Azure DevOps. - [Docker Task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/build/docker): Detailed reference for using the Docker task in Azure Pipelines to build and push images. -- [Docker Buildx Bake](/manuals/build/bake/_index.md): Explore Docker's advanced build tool for complex, multi-stage, and multi-platform build setups. See also the [Mastering Buildx Bake Guide](/guides/bake/index.md) for practical examples and best practices. -- [Docker Build Cloud](/guides/docker-build-cloud/_index.md): Learn about Docker's managed build service for faster, scalable, and multi-platform image builds in the cloud. +- [Docker Buildx Bake](/manuals/build/bake/_index.md): Explore Docker's advanced build tool for complex, multi-stage, and multi-platform build setups. See also the [Mastering Buildx Bake Guide](/guides/bake/) for practical examples and best practices. +- [Docker Build Cloud](/manuals/build-cloud/_index.md): Learn about Docker's managed build service for faster, scalable, and multi-platform image builds in the cloud. diff --git a/content/guides/bake.md b/content/guides/bake.md new file mode 100644 index 000000000000..9f70755bfa61 --- /dev/null +++ b/content/guides/bake.md @@ -0,0 +1,515 @@ +--- +title: Mastering multi-platform builds, testing, and more with Docker Buildx Bake +linkTitle: Mastering Docker Buildx Bake +description: > + Learn how to manage simple and complex build configurations with Buildx Bake. +summary: > + Learn to automate Docker builds and testing with declarative configurations using Buildx Bake. +keywords: bake, buildx, multi-platform, build configuration, hcl, automation +params: + tags: [cicd] + time: 30 minutes + image: /images/guides/bake.webp +--- + +This guide demonstrates how to simplify and automate the process of building +images, testing, and generating build artifacts using Docker Buildx Bake. By +defining build configurations in a declarative `docker-bake.hcl` file, you can +eliminate manual scripts and enable efficient workflows for complex builds, +testing, and artifact generation. + +## Assumptions + +This guide assumes that you're familiar with: + +- Docker +- [Buildx](/manuals/build/concepts/overview.md#buildx) +- [BuildKit](/manuals/build/concepts/overview.md#buildkit) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) +- [Multi-platform builds](/manuals/build/building/multi-platform.md) + +## Prerequisites + +- You have a recent version of Docker installed on your machine. +- You have Git installed for cloning repositories. +- You're using the [containerd](/manuals/desktop/features/containerd.md) image store. + +## Introduction + +This guide uses an example project to demonstrate how Docker Buildx Bake can +streamline your build and test workflows. The repository includes both a +Dockerfile and a `docker-bake.hcl` file, giving you a ready-to-use setup to try +out Bake commands. + +Start by cloning the example repository: + +```bash +git clone https://github.com/dvdksn/bakeme.git +cd bakeme +``` + +The Bake file, `docker-bake.hcl`, defines the build targets in a declarative +syntax, using targets and groups, allowing you to manage complex builds +efficiently. + +Here's what the Bake file looks like out-of-the-box: + +```hcl +target "default" { + target = "image" + tags = [ + "bakeme:latest", + ] + attest = [ + "type=provenance,mode=max", + "type=sbom", + ] + platforms = [ + "linux/amd64", + "linux/arm64", + "linux/riscv64", + ] +} +``` + +The `target` keyword defines a build target for Bake. The `default` target +defines the target to build when no specific target is specified on the command +line. Here's a quick summary of the options for the `default` target: + +- `target`: The target build stage in the Dockerfile. +- `tags`: Tags to assign to the image. +- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image. + + > [!TIP] + > The attestations provide metadata such as build provenance, which tracks + > the source of the image's build, and an SBOM (Software Bill of Materials), + > useful for security audits and compliance. + +- `platforms`: Platform variants to build. + +To execute this build, run the following command in the root of the +repository: + +```console +$ docker buildx bake +``` + +With Bake, you avoid long, hard-to-remember command-line incantations, +simplifying build configuration management by replacing manual, error-prone +scripts with a structured configuration file. + +For contrast, here's what this build command would look like without Bake: + +```console +$ docker buildx build \ + --target=image \ + --tag=bakeme:latest \ + --provenance=true \ + --sbom=true \ + --platform=linux/amd64,linux/arm64,linux/riscv64 \ + . +``` + +## Testing and linting + +Bake isn't just for defining build configurations and running builds. You can +also use Bake to run your tests, effectively using BuildKit as a task runner. +Running your tests in containers is great for ensuring reproducible results. +This section shows how to add two types of tests: + +- Unit testing with `go test`. +- Linting for style violations with `golangci-lint`. + +In Test-Driven Development (TDD) fashion, start by adding a new `test` target +to the Bake file: + +```hcl +target "test" { + target = "test" + output = ["type=cacheonly"] +} +``` + +> [!TIP] +> Using `type=cacheonly` ensures that the build output is effectively +> discarded; the layers are saved to BuildKit's cache, but Buildx will not +> attempt to load the result to the Docker Engine's image store. +> +> For test runs, you don't need to export the build output — only the test +> execution matters. + +To execute this Bake target, run `docker buildx bake test`. At this time, +you'll receive an error indicating that the `test` stage does not exist in the +Dockerfile. + +```console +$ docker buildx bake test +[+] Building 1.2s (6/6) FINISHED + => [internal] load local bake definitions +... +ERROR: failed to solve: target stage "test" could not be found +``` + +To satisfy this target, add the corresponding Dockerfile target. The `test` +stage here is based on the same base stage as the build stage. + +```dockerfile +FROM base AS test +RUN --mount=target=. \ + --mount=type=cache,target=/go/pkg/mod \ + go test . +``` + +> [!TIP] +> The [`--mount=type=cache` directive](/manuals/build/cache/optimize.md#use-cache-mounts) +> caches Go modules between builds, improving build performance by avoiding the +> need to re-download dependencies. This shared cache ensures that the same +> dependency set is available across build, test, and other stages. + +Now, running the `test` target with Bake will evaluate the unit tests for this +project. If you want to verify that it works, you can make an arbitrary change +to `main_test.go` to cause the test to fail. + +Next, to enable linting, add another target to the Bake file, named `lint`: + +```hcl +target "lint" { + target = "lint" + output = ["type=cacheonly"] +} +``` + +And in the Dockerfile, add the build stage. This stage will use the official +`golangci-lint` image on Docker Hub. + +> [!TIP] +> Because this stage relies on executing an external dependency, it's generally +> a good idea to define the version you want to use as a build argument. This +> lets you manage version upgrades in the future by collocating +> dependency versions to the beginning of the Dockerfile. + +```dockerfile {hl_lines=[2,"6-8"]} +ARG GO_VERSION="1.23" +ARG GOLANGCI_LINT_VERSION="1.61" + +#... + +FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint +RUN --mount=target=.,rw \ + golangci-lint run +``` + +Lastly, to enable running both tests simultaneously, you can use the `groups` +construct in the Bake file. A group can specify multiple targets to run with a +single invocation. + +```hcl +group "validate" { + targets = ["test", "lint"] +} +``` + +Now, running both tests is as simple as: + +```console +$ docker buildx bake validate +``` + +## Building variants + +Sometimes you need to build more than one version of a program. The following +example uses Bake to build separate "release" and "debug" variants of the +program, using [matrices](/manuals/build/bake/matrices.md). Using matrices lets +you run parallel builds with different configurations, saving time and ensuring +consistency. + +A matrix expands a single build into multiple builds, each representing a +unique combination of matrix parameters. This means you can orchestrate Bake +into building both the production and development build of your program in +parallel, with minimal configuration changes. + +The example project for this guide is set up to use a build-time option to +conditionally enable debug logging and tracing capabilities. + +- If you compile the program with `go build -tags="debug"`, the additional + logging and tracing capabilities are enabled (development mode). +- If you build without the `debug` tag, the program is compiled with a default + logger (production mode). + +Update the Bake file by adding a matrix attribute which defines the variable +combinations to build: + +```diff {title="docker-bake.hcl"} + target "default" { ++ matrix = { ++ mode = ["release", "debug"] ++ } ++ name = "image-${mode}" + target = "image" +``` + +The `matrix` attribute defines the variants to build ("release" and "debug"). +The `name` attribute defines how the matrix gets expanded into multiple +distinct build targets. In this case, the matrix attribute expands the build +into two workflows: `image-release` and `image-debug`, each using different +configuration parameters. + +Next, define a build argument named `BUILD_TAGS` which takes the value of the +matrix variable. + +```diff {title="docker-bake.hcl"} + target = "image" ++ args = { ++ BUILD_TAGS = mode ++ } + tags = [ +``` + +You'll also want to change how the image tags are assigned to these builds. +As written, both matrix paths would generate the same image tag names, and +overwrite each other. Update the `tags` attribute use a conditional operator to +set the tag depending on the matrix variable value. + +```diff {title="docker-bake.hcl"} + tags = [ +- "bakeme:latest", ++ mode == "release" ? "bakeme:latest" : "bakeme:dev" + ] +``` + +- If `mode` is `release`, the tag name is `bakeme:latest` +- If `mode` is `debug`, the tag name is `bakeme:dev` + +Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the +compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to +`-tags="debug"`, the compiler uses the `configureLogging` function in the +[`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1) +file. + +```diff {title=Dockerfile} + # build compiles the program + FROM base AS build +-ARG TARGETOS TARGETARCH ++ARG TARGETOS TARGETARCH BUILD_TAGS + ENV GOOS=$TARGETOS + ENV GOARCH=$TARGETARCH + RUN --mount=target=. \ + --mount=type=cache,target=/go/pkg/mod \ +- go build -o "/usr/bin/bakeme" . ++ go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" . +``` + +That's all. With these changes, your `docker buildx bake` command now builds +two multi-platform image variants. You can introspect the canonical build +configuration that Bake generates using the `docker buildx bake --print` +command. Running this command shows that Bake will run a `default` group with +two targets with different build arguments and image tags. + +```json {collapse=true} +{ + "group": { + "default": { + "targets": ["image-release", "image-debug"] + } + }, + "target": { + "image-debug": { + "attest": ["type=provenance,mode=max", "type=sbom"], + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "BUILD_TAGS": "debug" + }, + "tags": ["bakeme:dev"], + "target": "image", + "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] + }, + "image-release": { + "attest": ["type=provenance,mode=max", "type=sbom"], + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "BUILD_TAGS": "release" + }, + "tags": ["bakeme:latest"], + "target": "image", + "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] + } + } +} +``` + +Factoring in all of the platform variants as well, this means that the build +configuration generates 6 different images. + +```console +$ docker buildx bake +$ docker image ls --tree + +IMAGE ID DISK USAGE CONTENT SIZE USED +bakeme:dev f7cb5c08beac 49.3MB 28.9MB +├─ linux/riscv64 0eae8ba0367a 9.18MB 9.18MB +├─ linux/arm64 56561051c49a 30MB 9.89MB +└─ linux/amd64 e8ca65079c1f 9.8MB 9.8MB + +bakeme:latest 20065d2c4d22 44.4MB 25.9MB +├─ linux/riscv64 7cc82872695f 8.21MB 8.21MB +├─ linux/arm64 e42220c2b7a3 27.1MB 8.93MB +└─ linux/amd64 af5b2dd64fde 8.78MB 8.78MB +``` + +## Exporting build artifacts + +Exporting build artifacts like binaries can be useful for deploying to +environments without Docker or Kubernetes. For example, if your programs are +meant to be run on a user's local machine. + +> [!TIP] +> The techniques discussed in this section can be applied not only to build +> output like binaries, but to any type of artifacts, such as test reports. + +With programming languages like Go and Rust where the compiled binaries are +usually portable, creating alternate build targets for exporting only the +binary is trivial. All you need to do is add an empty stage in the Dockerfile +containing nothing but the binary that you want to export. + +First, let's add a quick way to build a binary for your local platform and +export it to `./build/local` on the local filesystem. + +In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set +the `output` attribute to a local filesystem path. Buildx automatically detects +that the output looks like a filepath, and exports the results to the specified +path using the [local exporter](/manuals/build/exporters/local-tar.md). + +```hcl +target "bin" { + target = "bin" + output = ["build/bin"] + platforms = ["local"] +} +``` + +Notice that this stage specifies a `local` platform. By default, if `platforms` +is unspecified, builds target the OS and architecture of the BuildKit host. If +you're using Docker Desktop, this often means builds target `linux/amd64` or +`linux/arm64`, even if your local machine is macOS or Windows, because Docker +runs in a Linux VM. Using the `local` platform forces the target platform to +match your local environment. + +Next, add the `bin` stage to the Dockerfile which copies the compiled binary +from the build stage. + +```dockerfile +FROM scratch AS bin +COPY --from=build "/usr/bin/bakeme" / +``` + +Now you can export your local platform version of the binary with `docker +buildx bake bin`. For example, on macOS, this build target generates an +executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the +standard executable format for macOS. + +```console +$ docker buildx bake bin +$ file ./build/bin/bakeme +./build/bin/bakeme: Mach-O 64-bit executable arm64 +``` + +Next, let's add a target to build all of the platform variants of the program. +To do this, you can [inherit](/manuals/build/bake/inheritance.md) the `bin` +target that you just created, and extend it by adding the desired platforms. + +```hcl +target "bin-cross" { + inherits = ["bin"] + platforms = [ + "linux/amd64", + "linux/arm64", + "linux/riscv64", + ] +} +``` + +Now, building the `bin-cross` target creates binaries for all platforms. +Subdirectories are automatically created for each variant. + +```console +$ docker buildx bake bin-cross +$ tree build/ +build/ +└── bin + ├── bakeme + ├── linux_amd64 + │ └── bakeme + ├── linux_arm64 + │ └── bakeme + └── linux_riscv64 + └── bakeme + +5 directories, 4 files +``` + +To also generate "release" and "debug" variants, you can use a matrix just like +you did with the default target. When using a matrix, you also need to +differentiate the output directory based on the matrix value, otherwise the +binary gets written to the same location for each matrix run. + +```hcl +target "bin-all" { + inherits = ["bin-cross"] + matrix = { + mode = ["release", "debug"] + } + name = "bin-${mode}" + args = { + BUILD_TAGS = mode + } + output = ["build/bin/${mode}"] +} +``` + +```console +$ rm -r ./build/ +$ docker buildx bake bin-all +$ tree build/ +build/ +└── bin + ├── debug + │ ├── linux_amd64 + │ │ └── bakeme + │ ├── linux_arm64 + │ │ └── bakeme + │ └── linux_riscv64 + │ └── bakeme + └── release + ├── linux_amd64 + │ └── bakeme + ├── linux_arm64 + │ └── bakeme + └── linux_riscv64 + └── bakeme + +10 directories, 6 files +``` + +## Conclusion + +Docker Buildx Bake streamlines complex build workflows, enabling efficient +multi-platform builds, testing, and artifact export. By integrating Buildx Bake +into your projects, you can simplify your Docker builds, make your build +configuration portable, and wrangle complex configurations. + +Experiment with different configurations and extend your Bake files to suit +your project's needs. You might consider integrating Bake into your CI/CD +pipelines to automate builds, testing, and artifact deployment. The flexibility +and power of Buildx Bake can significantly improve your development and +deployment processes. + +### Further reading + +For more information about how to use Bake, check out these resources: + +- [Bake documentation](/manuals/build/bake/_index.md) +- [Matrix targets](/manuals/build/bake/matrices.md) +- [Bake file reference](/manuals/build/bake/reference.md) +- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/bake/index.md b/content/guides/bake/index.md deleted file mode 100644 index bf03cbe7b413..000000000000 --- a/content/guides/bake/index.md +++ /dev/null @@ -1,516 +0,0 @@ ---- -title: Mastering multi-platform builds, testing, and more with Docker Buildx Bake -linkTitle: Mastering Docker Buildx Bake -description: > - Learn how to manage simple and complex build configurations with Buildx Bake. -summary: > - Learn to automate Docker builds and testing with declarative configurations using Buildx Bake. -keywords: bake, buildx, multi-platform, build configuration, hcl, automation -tags: [devops] -languages: [go] -params: - time: 30 minutes - image: /images/guides/bake.webp ---- - -This guide demonstrates how to simplify and automate the process of building -images, testing, and generating build artifacts using Docker Buildx Bake. By -defining build configurations in a declarative `docker-bake.hcl` file, you can -eliminate manual scripts and enable efficient workflows for complex builds, -testing, and artifact generation. - -## Assumptions - -This guide assumes that you're familiar with: - -- Docker -- [Buildx](/manuals/build/concepts/overview.md#buildx) -- [BuildKit](/manuals/build/concepts/overview.md#buildkit) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) -- [Multi-platform builds](/manuals/build/building/multi-platform.md) - -## Prerequisites - -- You have a recent version of Docker installed on your machine. -- You have Git installed for cloning repositories. -- You're using the [containerd](/manuals/desktop/features/containerd.md) image store. - -## Introduction - -This guide uses an example project to demonstrate how Docker Buildx Bake can -streamline your build and test workflows. The repository includes both a -Dockerfile and a `docker-bake.hcl` file, giving you a ready-to-use setup to try -out Bake commands. - -Start by cloning the example repository: - -```bash -git clone https://github.com/dvdksn/bakeme.git -cd bakeme -``` - -The Bake file, `docker-bake.hcl`, defines the build targets in a declarative -syntax, using targets and groups, allowing you to manage complex builds -efficiently. - -Here's what the Bake file looks like out-of-the-box: - -```hcl -target "default" { - target = "image" - tags = [ - "bakeme:latest", - ] - attest = [ - "type=provenance,mode=max", - "type=sbom", - ] - platforms = [ - "linux/amd64", - "linux/arm64", - "linux/riscv64", - ] -} -``` - -The `target` keyword defines a build target for Bake. The `default` target -defines the target to build when no specific target is specified on the command -line. Here's a quick summary of the options for the `default` target: - -- `target`: The target build stage in the Dockerfile. -- `tags`: Tags to assign to the image. -- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image. - - > [!TIP] - > The attestations provide metadata such as build provenance, which tracks - > the source of the image's build, and an SBOM (Software Bill of Materials), - > useful for security audits and compliance. - -- `platforms`: Platform variants to build. - -To execute this build, run the following command in the root of the -repository: - -```console -$ docker buildx bake -``` - -With Bake, you avoid long, hard-to-remember command-line incantations, -simplifying build configuration management by replacing manual, error-prone -scripts with a structured configuration file. - -For contrast, here's what this build command would look like without Bake: - -```console -$ docker buildx build \ - --target=image \ - --tag=bakeme:latest \ - --provenance=true \ - --sbom=true \ - --platform=linux/amd64,linux/arm64,linux/riscv64 \ - . -``` - -## Testing and linting - -Bake isn't just for defining build configurations and running builds. You can -also use Bake to run your tests, effectively using BuildKit as a task runner. -Running your tests in containers is great for ensuring reproducible results. -This section shows how to add two types of tests: - -- Unit testing with `go test`. -- Linting for style violations with `golangci-lint`. - -In Test-Driven Development (TDD) fashion, start by adding a new `test` target -to the Bake file: - -```hcl -target "test" { - target = "test" - output = ["type=cacheonly"] -} -``` - -> [!TIP] -> Using `type=cacheonly` ensures that the build output is effectively -> discarded; the layers are saved to BuildKit's cache, but Buildx will not -> attempt to load the result to the Docker Engine's image store. -> -> For test runs, you don't need to export the build output — only the test -> execution matters. - -To execute this Bake target, run `docker buildx bake test`. At this time, -you'll receive an error indicating that the `test` stage does not exist in the -Dockerfile. - -```console -$ docker buildx bake test -[+] Building 1.2s (6/6) FINISHED - => [internal] load local bake definitions -... -ERROR: failed to solve: target stage "test" could not be found -``` - -To satisfy this target, add the corresponding Dockerfile target. The `test` -stage here is based on the same base stage as the build stage. - -```dockerfile -FROM base AS test -RUN --mount=target=. \ - --mount=type=cache,target=/go/pkg/mod \ - go test . -``` - -> [!TIP] -> The [`--mount=type=cache` directive](/manuals/build/cache/optimize.md#use-cache-mounts) -> caches Go modules between builds, improving build performance by avoiding the -> need to re-download dependencies. This shared cache ensures that the same -> dependency set is available across build, test, and other stages. - -Now, running the `test` target with Bake will evaluate the unit tests for this -project. If you want to verify that it works, you can make an arbitrary change -to `main_test.go` to cause the test to fail. - -Next, to enable linting, add another target to the Bake file, named `lint`: - -```hcl -target "lint" { - target = "lint" - output = ["type=cacheonly"] -} -``` - -And in the Dockerfile, add the build stage. This stage will use the official -`golangci-lint` image on Docker Hub. - -> [!TIP] -> Because this stage relies on executing an external dependency, it's generally -> a good idea to define the version you want to use as a build argument. This -> lets you manage version upgrades in the future by collocating -> dependency versions to the beginning of the Dockerfile. - -```dockerfile {hl_lines=[2,"6-8"]} -ARG GO_VERSION="1.23" -ARG GOLANGCI_LINT_VERSION="1.61" - -#... - -FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint -RUN --mount=target=.,rw \ - golangci-lint run -``` - -Lastly, to enable running both tests simultaneously, you can use the `groups` -construct in the Bake file. A group can specify multiple targets to run with a -single invocation. - -```hcl -group "validate" { - targets = ["test", "lint"] -} -``` - -Now, running both tests is as simple as: - -```console -$ docker buildx bake validate -``` - -## Building variants - -Sometimes you need to build more than one version of a program. The following -example uses Bake to build separate "release" and "debug" variants of the -program, using [matrices](/manuals/build/bake/matrices.md). Using matrices lets -you run parallel builds with different configurations, saving time and ensuring -consistency. - -A matrix expands a single build into multiple builds, each representing a -unique combination of matrix parameters. This means you can orchestrate Bake -into building both the production and development build of your program in -parallel, with minimal configuration changes. - -The example project for this guide is set up to use a build-time option to -conditionally enable debug logging and tracing capabilities. - -- If you compile the program with `go build -tags="debug"`, the additional - logging and tracing capabilities are enabled (development mode). -- If you build without the `debug` tag, the program is compiled with a default - logger (production mode). - -Update the Bake file by adding a matrix attribute which defines the variable -combinations to build: - -```diff {title="docker-bake.hcl"} - target "default" { -+ matrix = { -+ mode = ["release", "debug"] -+ } -+ name = "image-${mode}" - target = "image" -``` - -The `matrix` attribute defines the variants to build ("release" and "debug"). -The `name` attribute defines how the matrix gets expanded into multiple -distinct build targets. In this case, the matrix attribute expands the build -into two workflows: `image-release` and `image-debug`, each using different -configuration parameters. - -Next, define a build argument named `BUILD_TAGS` which takes the value of the -matrix variable. - -```diff {title="docker-bake.hcl"} - target = "image" -+ args = { -+ BUILD_TAGS = mode -+ } - tags = [ -``` - -You'll also want to change how the image tags are assigned to these builds. -As written, both matrix paths would generate the same image tag names, and -overwrite each other. Update the `tags` attribute use a conditional operator to -set the tag depending on the matrix variable value. - -```diff {title="docker-bake.hcl"} - tags = [ -- "bakeme:latest", -+ mode == "release" ? "bakeme:latest" : "bakeme:dev" - ] -``` - -- If `mode` is `release`, the tag name is `bakeme:latest` -- If `mode` is `debug`, the tag name is `bakeme:dev` - -Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the -compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to -`-tags="debug"`, the compiler uses the `configureLogging` function in the -[`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1) -file. - -```diff {title=Dockerfile} - # build compiles the program - FROM base AS build --ARG TARGETOS TARGETARCH -+ARG TARGETOS TARGETARCH BUILD_TAGS - ENV GOOS=$TARGETOS - ENV GOARCH=$TARGETARCH - RUN --mount=target=. \ - --mount=type=cache,target=/go/pkg/mod \ -- go build -o "/usr/bin/bakeme" . -+ go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" . -``` - -That's all. With these changes, your `docker buildx bake` command now builds -two multi-platform image variants. You can introspect the canonical build -configuration that Bake generates using the `docker buildx bake --print` -command. Running this command shows that Bake will run a `default` group with -two targets with different build arguments and image tags. - -```json {collapse=true} -{ - "group": { - "default": { - "targets": ["image-release", "image-debug"] - } - }, - "target": { - "image-debug": { - "attest": ["type=provenance,mode=max", "type=sbom"], - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "BUILD_TAGS": "debug" - }, - "tags": ["bakeme:dev"], - "target": "image", - "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] - }, - "image-release": { - "attest": ["type=provenance,mode=max", "type=sbom"], - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "BUILD_TAGS": "release" - }, - "tags": ["bakeme:latest"], - "target": "image", - "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] - } - } -} -``` - -Factoring in all of the platform variants as well, this means that the build -configuration generates 6 different images. - -```console -$ docker buildx bake -$ docker image ls --tree - -IMAGE ID DISK USAGE CONTENT SIZE USED -bakeme:dev f7cb5c08beac 49.3MB 28.9MB -├─ linux/riscv64 0eae8ba0367a 9.18MB 9.18MB -├─ linux/arm64 56561051c49a 30MB 9.89MB -└─ linux/amd64 e8ca65079c1f 9.8MB 9.8MB - -bakeme:latest 20065d2c4d22 44.4MB 25.9MB -├─ linux/riscv64 7cc82872695f 8.21MB 8.21MB -├─ linux/arm64 e42220c2b7a3 27.1MB 8.93MB -└─ linux/amd64 af5b2dd64fde 8.78MB 8.78MB -``` - -## Exporting build artifacts - -Exporting build artifacts like binaries can be useful for deploying to -environments without Docker or Kubernetes. For example, if your programs are -meant to be run on a user's local machine. - -> [!TIP] -> The techniques discussed in this section can be applied not only to build -> output like binaries, but to any type of artifacts, such as test reports. - -With programming languages like Go and Rust where the compiled binaries are -usually portable, creating alternate build targets for exporting only the -binary is trivial. All you need to do is add an empty stage in the Dockerfile -containing nothing but the binary that you want to export. - -First, let's add a quick way to build a binary for your local platform and -export it to `./build/local` on the local filesystem. - -In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set -the `output` attribute to a local filesystem path. Buildx automatically detects -that the output looks like a filepath, and exports the results to the specified -path using the [local exporter](/manuals/build/exporters/local-tar.md). - -```hcl -target "bin" { - target = "bin" - output = ["build/bin"] - platforms = ["local"] -} -``` - -Notice that this stage specifies a `local` platform. By default, if `platforms` -is unspecified, builds target the OS and architecture of the BuildKit host. If -you're using Docker Desktop, this often means builds target `linux/amd64` or -`linux/arm64`, even if your local machine is macOS or Windows, because Docker -runs in a Linux VM. Using the `local` platform forces the target platform to -match your local environment. - -Next, add the `bin` stage to the Dockerfile which copies the compiled binary -from the build stage. - -```dockerfile -FROM scratch AS bin -COPY --from=build "/usr/bin/bakeme" / -``` - -Now you can export your local platform version of the binary with `docker -buildx bake bin`. For example, on macOS, this build target generates an -executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the -standard executable format for macOS. - -```console -$ docker buildx bake bin -$ file ./build/bin/bakeme -./build/bin/bakeme: Mach-O 64-bit executable arm64 -``` - -Next, let's add a target to build all of the platform variants of the program. -To do this, you can [inherit](/manuals/build/bake/inheritance.md) the `bin` -target that you just created, and extend it by adding the desired platforms. - -```hcl -target "bin-cross" { - inherits = ["bin"] - platforms = [ - "linux/amd64", - "linux/arm64", - "linux/riscv64", - ] -} -``` - -Now, building the `bin-cross` target creates binaries for all platforms. -Subdirectories are automatically created for each variant. - -```console -$ docker buildx bake bin-cross -$ tree build/ -build/ -└── bin - ├── bakeme - ├── linux_amd64 - │   └── bakeme - ├── linux_arm64 - │   └── bakeme - └── linux_riscv64 - └── bakeme - -5 directories, 4 files -``` - -To also generate "release" and "debug" variants, you can use a matrix just like -you did with the default target. When using a matrix, you also need to -differentiate the output directory based on the matrix value, otherwise the -binary gets written to the same location for each matrix run. - -```hcl -target "bin-all" { - inherits = ["bin-cross"] - matrix = { - mode = ["release", "debug"] - } - name = "bin-${mode}" - args = { - BUILD_TAGS = mode - } - output = ["build/bin/${mode}"] -} -``` - -```console -$ rm -r ./build/ -$ docker buildx bake bin-all -$ tree build/ -build/ -└── bin - ├── debug - │   ├── linux_amd64 - │   │   └── bakeme - │   ├── linux_arm64 - │   │   └── bakeme - │   └── linux_riscv64 - │   └── bakeme - └── release - ├── linux_amd64 - │   └── bakeme - ├── linux_arm64 - │   └── bakeme - └── linux_riscv64 - └── bakeme - -10 directories, 6 files -``` - -## Conclusion - -Docker Buildx Bake streamlines complex build workflows, enabling efficient -multi-platform builds, testing, and artifact export. By integrating Buildx Bake -into your projects, you can simplify your Docker builds, make your build -configuration portable, and wrangle complex configurations. - -Experiment with different configurations and extend your Bake files to suit -your project's needs. You might consider integrating Bake into your CI/CD -pipelines to automate builds, testing, and artifact deployment. The flexibility -and power of Buildx Bake can significantly improve your development and -deployment processes. - -### Further reading - -For more information about how to use Bake, check out these resources: - -- [Bake documentation](/manuals/build/bake/_index.md) -- [Matrix targets](/manuals/build/bake/matrices.md) -- [Bake file reference](/manuals/build/bake/reference.md) -- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/bun.md b/content/guides/bun.md new file mode 100644 index 000000000000..29c1d21ced0f --- /dev/null +++ b/content/guides/bun.md @@ -0,0 +1,251 @@ +--- +description: Containerize and develop Bun applications using Docker. +keywords: getting started, bun +title: Bun language-specific guide +summary: | + Learn how to containerize JavaScript applications with the Bun runtime. +linkTitle: Bun +aliases: + - /guides/bun/configure-ci-cd/ + - /guides/bun/containerize/ + - /guides/bun/deploy/ + - /guides/bun/develop/ +params: + tags: [languages] + time: 10 minutes +--- + +The Bun getting started guide teaches you how to create a containerized Bun application using Docker. + +> **Acknowledgment** +> +> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. + +## What will you learn? + +- Containerize and run a Bun application using Docker +- Set up a local environment to develop a Bun application using containers + +## Prerequisites + +- Basic understanding of JavaScript is assumed. +- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +After completing the Bun getting started modules, you should be able to containerize your own Bun application based on the examples and instructions provided in this guide. + +Start by containerizing an existing Bun application. + +## Containerize a Bun application + +### Prerequisites + +- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +### Overview + +For a long time, Node.js has been the de-facto runtime for server-side +JavaScript applications. Recent years have seen a rise in new alternative +runtimes in the ecosystem, including [Bun website](https://bun.sh/). Like +Node.js, Bun is a JavaScript runtime. Bun is a comparatively lightweight +runtime that is designed to be fast and efficient. + +Why develop Bun applications with Docker? Having multiple runtimes to choose +from is great. But as the number of runtimes increases, it becomes challenging +to manage the different runtimes and their dependencies consistently across +environments. This is where Docker comes in. Creating and destroying containers +on demand is a great way to manage the different runtimes and their +dependencies. Also, as it's fairly a new runtime, getting a consistent +development environment for Bun can be challenging. Docker can help you set up +a consistent development environment for Bun. + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following +command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker +``` + +You should now have the following contents in your `bun-docker` directory. + +```text +├── bun-docker/ +│ ├── compose.yml +│ ├── Dockerfile +│ ├── LICENSE +│ ├── server.js +│ └── README.md +``` + +### Create a Dockerfile + +Before creating a Dockerfile, you need to choose a base image. You can either use the [Bun Docker Official Image](https://hub.docker.com/r/oven/bun) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). + +Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) are available for Bun in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun). You can pull DHIs directly from the `dhi.io` registry. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Bun DHI as `dhi.io/bun:1`. The tag (`1`) in this example refers to the version to the latest 1.x version of Bun. + + ```console + $ docker pull dhi.io/bun:1 + ``` + +For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun). + +```dockerfile +# Use the DHI Bun image as the base image +FROM dhi.io/bun:1 + +# Set the working directory in the container +WORKDIR /app + +# Copy the current directory contents into the container at /app +COPY . . + +# Expose the port on which the API will listen +EXPOSE 3000 + +# Run the server when the container launches +CMD ["bun", "server.js"] +``` + +{{< /tab >}} +{{< tab name="Using the official image" >}} + +Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `oven/bun` as the base image. + +You can find the image on [Docker Hub](https://hub.docker.com/r/oven/bun). This is the Docker Official Image for Bun created by Oven, the company behind Bun, and it's available on Docker Hub. + +```dockerfile +# Use the official Bun image +FROM oven/bun:latest + +# Set the working directory in the container +WORKDIR /app + +# Copy the current directory contents into the container at /app +COPY . . + +# Expose the port on which the API will listen +EXPOSE 3000 + +# Run the server when the container launches +CMD ["bun", "server.js"] +``` + +{{< /tab >}} +{{< /tabs >}} + +In addition to specifying the base image, the Dockerfile also: + +- Sets the working directory in the container to `/app`. +- Copies the content of the current directory to the `/app` directory in the container. +- Exposes port 3000, where the API is listening for requests. +- And finally, starts the server when the container launches with the command `bun server.js`. + +### Run the application + +Inside the `bun-docker` directory, run the following command in a terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You will see a message `{"Status" : "OK"}` in the browser. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `bun-docker` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +## Use containers for Bun development + +### Prerequisites + +Complete [Containerize a Bun application](#containerize-a-bun-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker +``` + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. + +```yaml {hl_lines="9-12",linenos=true} +services: + server: + image: bun-server + build: + context: . + dockerfile: Dockerfile + ports: + - "3000:3000" + develop: + watch: + - action: rebuild + path: . +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Now, if you modify your `server.js` you will see the changes in real time without re-building the image. + +To test it out, open the `server.js` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:3000`. You should see the updated message. + +Press `ctrl+c` in the terminal to stop your application. + +### Summary + +In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + +- [Compose file reference](/reference/compose-file/) +- [Compose file watch](/manuals/compose/how-tos/file-watch.md) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) diff --git a/content/guides/bun/_index.md b/content/guides/bun/_index.md deleted file mode 100644 index b50e184c32e1..000000000000 --- a/content/guides/bun/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Containerize and develop Bun applications using Docker. -keywords: getting started, bun -title: Bun language-specific guide -summary: | - Learn how to containerize JavaScript applications with the Bun runtime. -linkTitle: Bun -languages: [js] -tags: [dhi] -params: - time: 10 minutes ---- - -The Bun getting started guide teaches you how to create a containerized Bun application using Docker. - -> **Acknowledgment** -> -> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. - -## What will you learn? - -* Containerize and run a Bun application using Docker -* Set up a local environment to develop a Bun application using containers -* Configure a CI/CD pipeline for a containerized Bun application using GitHub Actions -* Deploy your containerized application locally to Kubernetes to test and debug your deployment - -## Prerequisites - -- Basic understanding of JavaScript is assumed. -- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -After completing the Bun getting started modules, you should be able to containerize your own Bun application based on the examples and instructions provided in this guide. - -Start by containerizing an existing Bun application. diff --git a/content/guides/bun/configure-ci-cd.md b/content/guides/bun/configure-ci-cd.md deleted file mode 100644 index d1c5b9ddc45e..000000000000 --- a/content/guides/bun/configure-ci-cd.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Configure CI/CD for your Bun application -linkTitle: Configure CI/CD -weight: 40 -keywords: ci/cd, github actions, bun, shiny -description: Learn how to configure CI/CD using GitHub Actions for your Bun application. -aliases: -- /language/bun/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Bun application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token)for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration and commit the changes. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your Bun application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/bun/containerize.md b/content/guides/bun/containerize.md deleted file mode 100644 index 08f516c88396..000000000000 --- a/content/guides/bun/containerize.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Containerize a Bun application -linkTitle: Containerize your app -weight: 10 -keywords: bun, containerize, initialize -description: Learn how to containerize a Bun application. -aliases: - - /language/bun/containerize/ ---- - -## Prerequisites - -* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Overview - -For a long time, Node.js has been the de-facto runtime for server-side -JavaScript applications. Recent years have seen a rise in new alternative -runtimes in the ecosystem, including [Bun website](https://bun.sh/). Like -Node.js, Bun is a JavaScript runtime. Bun is a comparatively lightweight -runtime that is designed to be fast and efficient. - -Why develop Bun applications with Docker? Having multiple runtimes to choose -from is great. But as the number of runtimes increases, it becomes challenging -to manage the different runtimes and their dependencies consistently across -environments. This is where Docker comes in. Creating and destroying containers -on demand is a great way to manage the different runtimes and their -dependencies. Also, as it's fairly a new runtime, getting a consistent -development environment for Bun can be challenging. Docker can help you set up -a consistent development environment for Bun. - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following -command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker -``` - -You should now have the following contents in your `bun-docker` directory. - -```text -├── bun-docker/ -│ ├── compose.yml -│ ├── Dockerfile -│ ├── LICENSE -│ ├── server.js -│ └── README.md -``` - -## Create a Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Bun Docker Official Image](https://hub.docker.com/r/oven/bun) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) are available for Bun in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun). You can pull DHIs directly from the `dhi.io` registry. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Bun DHI as `dhi.io/bun:1`. The tag (`1`) in this example refers to the version to the latest 1.x version of Bun. - - ```console - $ docker pull dhi.io/bun:1 - ``` - -For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun). - -```dockerfile -# Use the DHI Bun image as the base image -FROM dhi.io/bun:1 - -# Set the working directory in the container -WORKDIR /app - -# Copy the current directory contents into the container at /app -COPY . . - -# Expose the port on which the API will listen -EXPOSE 3000 - -# Run the server when the container launches -CMD ["bun", "server.js"] -``` - -{{< /tab >}} -{{< tab name="Using the official image" >}} - -Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `oven/bun` as the base image. - -You can find the image on [Docker Hub](https://hub.docker.com/r/oven/bun). This is the Docker Official Image for Bun created by Oven, the company behind Bun, and it's available on Docker Hub. - -```dockerfile -# Use the official Bun image -FROM oven/bun:latest - -# Set the working directory in the container -WORKDIR /app - -# Copy the current directory contents into the container at /app -COPY . . - -# Expose the port on which the API will listen -EXPOSE 3000 - -# Run the server when the container launches -CMD ["bun", "server.js"] -``` - -{{< /tab >}} -{{< /tabs >}} - -In addition to specifying the base image, the Dockerfile also: - -- Sets the working directory in the container to `/app`. -- Copies the content of the current directory to the `/app` directory in the container. -- Exposes port 3000, where the API is listening for requests. -- And finally, starts the server when the container launches with the command `bun server.js`. - -## Run the application - -Inside the `bun-docker` directory, run the following command in a terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You will see a message `{"Status" : "OK"}` in the browser. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `bun-docker` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:3000](http://localhost:3000). - - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -## Summary - -In this section, you learned how you can containerize and run your Bun -application using Docker. - -Related information: - - - [Dockerfile reference](/reference/dockerfile.md) - - [.dockerignore file](/reference/dockerfile.md#dockerignore-file) - - [Docker Compose overview](/manuals/compose/_index.md) - - [Compose file reference](/reference/compose-file/_index.md) - - [Docker Hardened Images](/dhi/) - -## Next steps - -In the next section, you'll learn how you can develop your application using -containers. diff --git a/content/guides/bun/deploy.md b/content/guides/bun/deploy.md deleted file mode 100644 index 0093a9086196..000000000000 --- a/content/guides/bun/deploy.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Test your Bun deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, bun -description: Learn how to develop locally using Kubernetes -aliases: -- /language/bun/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a Bun application](containerize.md). -- [Turn on Kubernetes](/manuals//desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `bun-docker` directory, create a file named -`docker-kubernetes.yml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Bun application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-bun-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: bun-api - template: - metadata: - labels: - app: bun-api - spec: - containers: - - name: bun-api - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - app: bun-api - ports: - - port: 3000 - targetPort: 3000 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - - - A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your Bun application](configure-ci-cd.md). - - A NodePort service, which will route traffic from port 30001 on your host to - port 3000 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `bun-docker` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-kubernetes.yml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```text - deployment.apps/docker-bun-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-bun-demo 1/1 1 1 10s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 88m - service-entrypoint NodePort 10.105.145.223 <none> 3000:30001/TCP 83s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`. - - ```console - http://localhost:30001/ - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-kubernetes.yml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your Bun application to a fully-featured Kubernetes environment on your development machine. - -Related information: - - [Kubernetes documentation](https://kubernetes.io/docs/home/) - - [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) - - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/bun/develop.md b/content/guides/bun/develop.md deleted file mode 100644 index 7de9bd63ed7e..000000000000 --- a/content/guides/bun/develop.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Use containers for Bun development -linkTitle: Develop your app -weight: 20 -keywords: bun, local, development -description: Learn how to develop your Bun application locally. -aliases: -- /language/bun/develop/ ---- - -## Prerequisites - -Complete [Containerize a Bun application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Configuring Compose to automatically update your running Compose services as you edit and save your code - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker -``` - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. - -```yaml {hl_lines="9-12",linenos=true} -services: - server: - image: bun-server - build: - context: . - dockerfile: Dockerfile - ports: - - "3000:3000" - develop: - watch: - - action: rebuild - path: . -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Now, if you modify your `server.js` you will see the changes in real time without re-building the image. - -To test it out, open the `server.js` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:3000`. You should see the updated message. - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - - [Compose file reference](/reference/compose-file/) - - [Compose file watch](/manuals/compose/how-tos/file-watch.md) - - [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/claude-code-model-runner.md b/content/guides/claude-code-model-runner.md index 652e74d3a1ec..8ac867e70ea4 100644 --- a/content/guides/claude-code-model-runner.md +++ b/content/guides/claude-code-model-runner.md @@ -5,8 +5,8 @@ summary: | Connect Claude Code to Docker Model Runner with the Anthropic-compatible API, package `gpt-oss` with a larger context window, and inspect requests. keywords: ai, claude code, docker model runner, anthropic, local models, coding assistant -tags: [ai] params: + tags: [ai] time: 10 minutes --- diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md index 60d1fe0a312e..11fa9e075bff 100644 --- a/content/guides/claude-code-sandbox-model-runner.md +++ b/content/guides/claude-code-sandbox-model-runner.md @@ -6,8 +6,8 @@ summary: | isolated microVM that talks to a local model on your host through the Anthropic-compatible API. keywords: ai, claude code, docker model runner, docker sandboxes, sbx, anthropic, local models, coding assistant -tags: [ai] params: + tags: [ai] time: 15 minutes --- @@ -52,7 +52,7 @@ Before you start, make sure you have: - [Docker Desktop](../get-started/get-docker.md) or Docker Engine installed - [Docker Model Runner enabled](../manuals/ai/model-runner/get-started.md#enable-docker-model-runner) -- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/get-started.md#install-and-sign-in) +- [Docker Sandboxes (`sbx`) version 0.39.0 or later installed and signed in](../manuals/ai/sandboxes/install.md) If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run: @@ -88,42 +88,32 @@ $ sbx policy allow network localhost:12434 ``` For background on host access from sandboxes, see -[Accessing host services from a sandbox](../manuals/ai/sandboxes/usage.md#accessing-host-services-from-a-sandbox). +[Accessing host services from a sandbox](../manuals/ai/sandboxes/workflows/development.md#accessing-host-services-from-a-sandbox). ## Step 3: Create a Claude Code sandbox -From your project directory, create a sandbox without launching the agent: +From your project directory, create a sandbox without launching the agent. Set +`ANTHROPIC_BASE_URL` so Claude Code uses Docker Model Runner whenever the +sandbox starts: ```console $ cd ~/my-project -$ sbx create claude --name claude-dmr . +$ sbx create --name claude-dmr \ + -e ANTHROPIC_BASE_URL=http://host.docker.internal:12434 \ + claude . ``` -`sbx run` would also work, but it launches Claude Code immediately. Without -`ANTHROPIC_BASE_URL` set, Claude Code points at `api.anthropic.com` and -either prompts for OAuth or errors out before you can fix the endpoint. -Creating the sandbox first lets you write the local endpoint into it before +`sbx run` would also work, but it launches Claude Code immediately. Creating +the sandbox first lets you confirm the variable and test connectivity before the agent starts. You don't need to set an Anthropic API key or run `sbx secret set anthropic`. Docker Model Runner doesn't authenticate the local endpoint, and the sandbox proxy only injects credentials for requests bound for `api.anthropic.com`. See -[Credentials](../manuals/ai/sandboxes/security/credentials.md) for the full -list of services the proxy authenticates. - -## Step 4: Set the local endpoint inside the sandbox - -Append `ANTHROPIC_BASE_URL` to the sandbox's persistent environment file so -Claude Code reads it on every launch: - -```console -$ sbx exec -d claude-dmr bash -c "echo 'export ANTHROPIC_BASE_URL=http://host.docker.internal:12434' >> /etc/sandbox-persistent.sh" -``` - -The `bash -c` wrapper ensures the `>>` redirect runs inside the sandbox, not -on your host. For details on this approach, see -[How do I set custom environment variables inside a sandbox?](../manuals/ai/sandboxes/faq.md#how-do-i-set-custom-environment-variables-inside-a-sandbox). +[Credentials](../manuals/ai/sandboxes/configuration/credentials.md) for the full +list of services the proxy authenticates. For more ways to set variables, see +[Set environment variables](../manuals/ai/sandboxes/usage.md#set-environment-variables). To confirm the variable is set, open a shell in the sandbox: @@ -133,7 +123,7 @@ $ echo $ANTHROPIC_BASE_URL http://host.docker.internal:12434 ``` -## Step 5: Verify connectivity to Docker Model Runner +## Step 4: Verify connectivity to Docker Model Runner Still inside the sandbox shell, send a test request to the host endpoint: @@ -152,20 +142,20 @@ Type `exit` to leave the shell. For more details about the request format, see the [Anthropic-compatible API reference](../manuals/ai/model-runner/api-reference.md#anthropic-compatible-api). -## Step 6: Launch Claude Code with the local model +## Step 5: Launch Claude Code with the local model Run Claude Code in the sandbox and pass the model flag through to the agent: ```console -$ sbx run claude-dmr -- --model ai/devstral-small-2 +$ sbx run --name claude-dmr -- --model ai/devstral-small-2 ``` -Everything after `--` is forwarded to the Claude Code CLI. Because -`ANTHROPIC_BASE_URL` is set in the sandbox's persistent environment, Claude -Code routes requests to Docker Model Runner on your host instead of +Everything after `--` is forwarded to the Claude Code CLI. +`ANTHROPIC_BASE_URL` is stored with the sandbox and available to every session, +so Claude Code routes requests to Docker Model Runner on your host instead of `api.anthropic.com`. -## Step 7: Inspect Claude Code requests +## Step 6: Inspect Claude Code requests To inspect the requests Claude Code sends, run on your host: @@ -176,7 +166,7 @@ $ docker model requests --model ai/devstral-small-2 | jq . This helps you debug prompts, context usage, and compatibility issues without attaching to the sandbox. -## Step 8: Package `gpt-oss` with a larger context window +## Step 7: Package `gpt-oss` with a larger context window `ai/gpt-oss` defaults to a smaller context window than coding-focused models. To use it for repository-scale prompts, package a larger variant on @@ -191,7 +181,7 @@ Then point Claude Code at the packaged model the next time you run the sandbox: ```console -$ sbx run claude-dmr -- --model gpt-oss:32k +$ sbx run --name claude-dmr -- --model gpt-oss:32k ``` ## Clean up @@ -203,8 +193,7 @@ deleting it: $ sbx stop claude-dmr ``` -To remove the sandbox and everything inside, including the persistent -environment file: +To remove the sandbox and everything inside: ```console $ sbx rm claude-dmr diff --git a/content/guides/compose-bake.md b/content/guides/compose-bake.md new file mode 100644 index 000000000000..cad2cdfc1566 --- /dev/null +++ b/content/guides/compose-bake.md @@ -0,0 +1,402 @@ +--- +title: Building Compose projects with Bake +description: Learn how to build Docker Compose projects with Docker Buildx Bake +summary: | + This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects. +keywords: docker compose, bake, buildx, multi-service, production builds, build configuration +params: + tags: [cicd] + time: 20 minutes +--- + +This guide explores how you can use Bake to build images for Docker Compose +projects with multiple services. + +[Docker Buildx Bake](/manuals/build/bake/_index.md) is a build orchestration +tool that enables declarative configuration for your builds, much like Docker +Compose does for defining runtime stacks. For projects where Docker Compose is +used to spin up services for local development, Bake offers a way of seamlessly +extending the project with a production-ready build configuration. + +## Prerequisites + +This guide assumes that you're familiar with + +- Docker Compose +- [Multi-stage builds](/manuals/build/building/multi-stage.md) +- [Multi-platform builds](/manuals/build/building/multi-platform.md) + +## Orientation + +This guide will use the +[dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app) +repository as an example of a monorepo using Docker Compose that can be +extended with Bake. + +```console +$ git clone https://github.com/dvdksn/example-voting-app.git +$ cd example-voting-app +``` + +This repository uses Docker Compose to define the runtime configurations for +running the application, in the `compose.yaml` file. This app consists of the +following services: + +| Service | Description | +| -------- | ---------------------------------------------------------------------- | +| `vote` | A front-end web app in Python which lets you vote between two options. | +| `result` | A Node.js web app which shows the results of the voting in real time. | +| `worker` | A .NET worker which consumes votes and stores them in the database. | +| `db` | A Postgres database backed by a Docker volume. | +| `redis` | A Redis instance which collects new votes. | +| `seed` | A utility container that seeds the database with mock data. | + +The `vote`, `result`, and `worker` services are built from code in this +repository, whereas `db` and `redis` use pre-existing Postgres and Redis images +from Docker Hub. The `seed` service is a utility that invokes requests against +the front-end service to populate the database, for testing purposes. + +## Build with Compose + +When you spin up a Docker Compose project, any services that define the `build` +property are automatically built before the service is started. Here's the +build configuration for the `vote` service in the example repository: + +```yaml {title="compose.yaml"} +services: + vote: + build: + context: ./vote # Build context + target: dev # Dockerfile stage +``` + +The `vote`, `result`, and `worker` services all have a build configuration +specified. Running `docker compose up` will trigger a build of these services. + +Did you know that you can also use Compose just to build the service images? +The `docker compose build` command lets you invoke a build using the build +configuration specified in the Compose file. For example, to build the `vote` +service with this configuration, run: + +```console +$ docker compose build vote +``` + +Omit the service name to build all services at once: + +```console +$ docker compose build +``` + +The `docker compose build` command is useful when you only need to build images +without running services. + +The Compose file format supports a number of properties for defining your +build's configuration. For example, to specify the tag name for the images, set +the `image` property on the service. + +```yaml +services: + vote: + image: username/vote + build: + context: ./vote + target: dev + #... + + result: + image: username/result + build: + context: ./result + #... + + worker: + image: username/worker + build: + context: ./worker + #... +``` + +Running `docker compose build` creates three service images with fully +qualified image names that you can push to Docker Hub. + +The `build` property supports a [wide range](/reference/compose-file/build.md) +of options for configuring builds. However, building production-grade images +are often different from images used in local development. To avoid cluttering +your Compose file with build configurations that might not be desirable for +local builds, consider separating the production builds from the local builds +by using Bake to build images for release. This approach separates concerns: +using Compose for local development and Bake for production-ready builds, while +still reusing service definitions and fundamental build configurations. + +## Build with Bake + +Like Compose, Bake parses the build definition for a project from a +configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON, +and the Docker Compose YAML format. When you use Bake with multiple files, it +will find and merge all of the applicable configuration files into one unified +build configuration. The build options defined in your Compose file are +extended, or in some cases overridden, by options specified in the Bake file. + +The following section explores how you can use Bake to extend the build options +defined in your Compose file for production. + +### View the build configuration + +Bake automatically creates a build configuration from the `build` properties of +your services. Use the `--print` flag for Bake to view the build configuration +for a given Compose file. This flag evaluates the build configuration and +outputs the build definition in JSON format. + +```console +$ docker buildx bake --print +``` + +The JSON-formatted output shows the group that would be executed, and all the +targets of that group. A group is a collection of builds, and a target +represents a single build. + +```json +{ + "group": { + "default": { + "targets": [ + "vote", + "result", + "worker", + "seed" + ] + } + }, + "target": { + "result": { + "context": "result", + "dockerfile": "Dockerfile", + }, + "seed": { + "context": "seed-data", + "dockerfile": "Dockerfile", + }, + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "target": "dev", + }, + "worker": { + "context": "worker", + "dockerfile": "Dockerfile", + } + } +} +``` + +As you can see, Bake has created a `default` group that includes four targets: + +- `seed` +- `vote` +- `result` +- `worker` + +This group is created automatically from your Compose file; it includes all of +your services containing a build configuration. To build this group of services +with Bake, run: + +```console +$ docker buildx bake +``` + +### Customize the build group + +Start by redefining the default build group that Bake executes. The current +default group includes a `seed` target — a Compose service used solely to +populate the database with mock data. Since this target doesn't produce a +production image, it doesn't need to be included in the build group. + +To customize the build configuration that Bake uses, create a new file at the +root of the repository, alongside your `compose.yaml` file, named +`docker-bake.hcl`. + +```console +$ touch docker-bake.hcl +``` + +Open the Bake file and add the following configuration: + +```hcl {title=docker-bake.hcl} +group "default" { + targets = ["vote", "result", "worker"] +} +``` + +Save the file and print your Bake definition again. + +```console +$ docker buildx bake --print +``` + +The JSON output shows that the `default` group only includes the targets you +care about. + +```json +{ + "group": { + "default": { + "targets": ["vote", "result", "worker"] + } + }, + "target": { + "result": { + "context": "result", + "dockerfile": "Dockerfile", + "tags": ["username/result"] + }, + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "tags": ["username/vote"], + "target": "dev" + }, + "worker": { + "context": "worker", + "dockerfile": "Dockerfile", + "tags": ["username/worker"] + } + } +} +``` + +Here, the build configuration for each target (context, tags, etc.) is picked +up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl` +file. + +### Customize targets + +The Compose file currently defines the `dev` stage as the build target for the +`vote` service. That's appropriate for the image that you would run in local +development, because the `dev` stage includes additional development +dependencies and configurations. For the production image, however, you'll want +to target the `final` image instead. + +To modify the target stage used by the `vote` service, add the following +configuration to the Bake file: + +```hcl +target "vote" { + target = "final" +} +``` + +This overrides the `target` property specified in the Compose file with a +different value when you run the build with Bake. The other build options in +the Compose file (tag, context) remain unmodified. You can verify by inspecting +the build configuration for the `vote` target with `docker buildx bake --print +vote`: + +```json +{ + "group": { + "default": { + "targets": ["vote"] + } + }, + "target": { + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "tags": ["username/vote"], + "target": "final" + } + } +} +``` + +### Additional build features + +Production-grade builds often have different characteristics from development +builds. Here are a few examples of things you might want to add for production +images. + +Multi-platform +: For local development, you only need to build images for your local platform, +since those images are just going to run on your machine. But for images that +are pushed to a registry, it's often a good idea to build for multiple +platforms, arm64 and amd64 in particular. + +Attestations +: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests +attached to the image that describe how the image was created and what +components it contains. Attaching attestations to your images helps ensure that +your images follow software supply chain best practices. + +Annotations +: [Annotations](/manuals/build/metadata/annotations.md) provide descriptive +metadata for images. Use annotations to record arbitrary information and attach +it to your image, which helps consumers and tools understand the origin, +contents, and how to use the image. + +> [!TIP] +> Why not just define these additional build options in the Compose file +> directly? +> +> The `build` property in the Compose file format does not support all build +> features. Additionally, some features, like multi-platform builds, can +> drastically increase the time it takes to build a service. For local +> development, you're better off keeping your build step simple and fast, +> saving the bells and whistles for release builds. + +To add these properties to the images you build with Bake, update the Bake file +as follows: + +```hcl +group "default" { + targets = ["vote", "result", "worker"] +} + +target "_common" { + annotations = ["org.opencontainers.image.authors=username"] + platforms = ["linux/amd64", "linux/arm64"] + attest = [ + "type=provenance,mode=max", + "type=sbom" + ] +} + +target "vote" { + inherits = ["_common"] + target = "final" +} + +target "result" { + inherits = ["_common"] +} + +target "worker" { + inherits = ["_common"] +} +``` + +This defines a new `_common` target that defines reusable build configuration +for adding multi-platform support, annotations, and attestations to your +images. The reusable target is inherited by the build targets. + +With these changes, building the project with Bake produces three sets of +multi-platform images for the `linux/amd64` and `linux/arm64` architectures. +Each image is decorated with an author annotation, and both SBOM and provenance +attestation records. + +## Conclusions + +The pattern demonstrated in this guide provides a useful approach for managing +production-ready Docker images in projects using Docker Compose. Using Bake +gives you access to all the powerful features of Buildx and BuildKit, and also +helps separate your development and build configuration in a reasonable way. + +### Further reading + +For more information about how to use Bake, check out these resources: + +- [Bake documentation](/manuals/build/bake/_index.md) +- [Building with Bake from a Compose file](/manuals/build/bake/compose-file.md) +- [Bake file reference](/manuals/build/bake/reference.md) +- [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](/guides/bake/) +- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/compose-bake/index.md b/content/guides/compose-bake/index.md deleted file mode 100644 index c94f5a93082f..000000000000 --- a/content/guides/compose-bake/index.md +++ /dev/null @@ -1,403 +0,0 @@ ---- -title: Building Compose projects with Bake -description: Learn how to build Docker Compose projects with Docker Buildx Bake -summary: | - This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects. -keywords: docker compose, bake, buildx, multi-service, production builds, build configuration -languages: [] -tags: [devops] -params: - time: 20 minutes ---- - -This guide explores how you can use Bake to build images for Docker Compose -projects with multiple services. - -[Docker Buildx Bake](/manuals/build/bake/_index.md) is a build orchestration -tool that enables declarative configuration for your builds, much like Docker -Compose does for defining runtime stacks. For projects where Docker Compose is -used to spin up services for local development, Bake offers a way of seamlessly -extending the project with a production-ready build configuration. - -## Prerequisites - -This guide assumes that you're familiar with - -- Docker Compose -- [Multi-stage builds](/manuals/build/building/multi-stage.md) -- [Multi-platform builds](/manuals/build/building/multi-platform.md) - -## Orientation - -This guide will use the -[dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app) -repository as an example of a monorepo using Docker Compose that can be -extended with Bake. - -```console -$ git clone https://github.com/dvdksn/example-voting-app.git -$ cd example-voting-app -``` - -This repository uses Docker Compose to define the runtime configurations for -running the application, in the `compose.yaml` file. This app consists of the -following services: - -| Service | Description | -| -------- | ---------------------------------------------------------------------- | -| `vote` | A front-end web app in Python which lets you vote between two options. | -| `result` | A Node.js web app which shows the results of the voting in real time. | -| `worker` | A .NET worker which consumes votes and stores them in the database. | -| `db` | A Postgres database backed by a Docker volume. | -| `redis` | A Redis instance which collects new votes. | -| `seed` | A utility container that seeds the database with mock data. | - -The `vote`, `result`, and `worker` services are built from code in this -repository, whereas `db` and `redis` use pre-existing Postgres and Redis images -from Docker Hub. The `seed` service is a utility that invokes requests against -the front-end service to populate the database, for testing purposes. - -## Build with Compose - -When you spin up a Docker Compose project, any services that define the `build` -property are automatically built before the service is started. Here's the -build configuration for the `vote` service in the example repository: - -```yaml {title="compose.yaml"} -services: - vote: - build: - context: ./vote # Build context - target: dev # Dockerfile stage -``` - -The `vote`, `result`, and `worker` services all have a build configuration -specified. Running `docker compose up` will trigger a build of these services. - -Did you know that you can also use Compose just to build the service images? -The `docker compose build` command lets you invoke a build using the build -configuration specified in the Compose file. For example, to build the `vote` -service with this configuration, run: - -```console -$ docker compose build vote -``` - -Omit the service name to build all services at once: - -```console -$ docker compose build -``` - -The `docker compose build` command is useful when you only need to build images -without running services. - -The Compose file format supports a number of properties for defining your -build's configuration. For example, to specify the tag name for the images, set -the `image` property on the service. - -```yaml -services: - vote: - image: username/vote - build: - context: ./vote - target: dev - #... - - result: - image: username/result - build: - context: ./result - #... - - worker: - image: username/worker - build: - context: ./worker - #... -``` - -Running `docker compose build` creates three service images with fully -qualified image names that you can push to Docker Hub. - -The `build` property supports a [wide range](/reference/compose-file/build.md) -of options for configuring builds. However, building production-grade images -are often different from images used in local development. To avoid cluttering -your Compose file with build configurations that might not be desirable for -local builds, consider separating the production builds from the local builds -by using Bake to build images for release. This approach separates concerns: -using Compose for local development and Bake for production-ready builds, while -still reusing service definitions and fundamental build configurations. - -## Build with Bake - -Like Compose, Bake parses the build definition for a project from a -configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON, -and the Docker Compose YAML format. When you use Bake with multiple files, it -will find and merge all of the applicable configuration files into one unified -build configuration. The build options defined in your Compose file are -extended, or in some cases overridden, by options specified in the Bake file. - -The following section explores how you can use Bake to extend the build options -defined in your Compose file for production. - -### View the build configuration - -Bake automatically creates a build configuration from the `build` properties of -your services. Use the `--print` flag for Bake to view the build configuration -for a given Compose file. This flag evaluates the build configuration and -outputs the build definition in JSON format. - -```console -$ docker buildx bake --print -``` - -The JSON-formatted output shows the group that would be executed, and all the -targets of that group. A group is a collection of builds, and a target -represents a single build. - -```json -{ - "group": { - "default": { - "targets": [ - "vote", - "result", - "worker", - "seed" - ] - } - }, - "target": { - "result": { - "context": "result", - "dockerfile": "Dockerfile", - }, - "seed": { - "context": "seed-data", - "dockerfile": "Dockerfile", - }, - "vote": { - "context": "vote", - "dockerfile": "Dockerfile", - "target": "dev", - }, - "worker": { - "context": "worker", - "dockerfile": "Dockerfile", - } - } -} -``` - -As you can see, Bake has created a `default` group that includes four targets: - -- `seed` -- `vote` -- `result` -- `worker` - -This group is created automatically from your Compose file; it includes all of -your services containing a build configuration. To build this group of services -with Bake, run: - -```console -$ docker buildx bake -``` - -### Customize the build group - -Start by redefining the default build group that Bake executes. The current -default group includes a `seed` target — a Compose service used solely to -populate the database with mock data. Since this target doesn't produce a -production image, it doesn’t need to be included in the build group. - -To customize the build configuration that Bake uses, create a new file at the -root of the repository, alongside your `compose.yaml` file, named -`docker-bake.hcl`. - -```console -$ touch docker-bake.hcl -``` - -Open the Bake file and add the following configuration: - -```hcl {title=docker-bake.hcl} -group "default" { - targets = ["vote", "result", "worker"] -} -``` - -Save the file and print your Bake definition again. - -```console -$ docker buildx bake --print -``` - -The JSON output shows that the `default` group only includes the targets you -care about. - -```json -{ - "group": { - "default": { - "targets": ["vote", "result", "worker"] - } - }, - "target": { - "result": { - "context": "result", - "dockerfile": "Dockerfile", - "tags": ["username/result"] - }, - "vote": { - "context": "vote", - "dockerfile": "Dockerfile", - "tags": ["username/vote"], - "target": "dev" - }, - "worker": { - "context": "worker", - "dockerfile": "Dockerfile", - "tags": ["username/worker"] - } - } -} -``` - -Here, the build configuration for each target (context, tags, etc.) is picked -up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl` -file. - -### Customize targets - -The Compose file currently defines the `dev` stage as the build target for the -`vote` service. That's appropriate for the image that you would run in local -development, because the `dev` stage includes additional development -dependencies and configurations. For the production image, however, you'll want -to target the `final` image instead. - -To modify the target stage used by the `vote` service, add the following -configuration to the Bake file: - -```hcl -target "vote" { - target = "final" -} -``` - -This overrides the `target` property specified in the Compose file with a -different value when you run the build with Bake. The other build options in -the Compose file (tag, context) remain unmodified. You can verify by inspecting -the build configuration for the `vote` target with `docker buildx bake --print -vote`: - -```json -{ - "group": { - "default": { - "targets": ["vote"] - } - }, - "target": { - "vote": { - "context": "vote", - "dockerfile": "Dockerfile", - "tags": ["username/vote"], - "target": "final" - } - } -} -``` - -### Additional build features - -Production-grade builds often have different characteristics from development -builds. Here are a few examples of things you might want to add for production -images. - -Multi-platform -: For local development, you only need to build images for your local platform, -since those images are just going to run on your machine. But for images that -are pushed to a registry, it's often a good idea to build for multiple -platforms, arm64 and amd64 in particular. - -Attestations -: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests -attached to the image that describe how the image was created and what -components it contains. Attaching attestations to your images helps ensure that -your images follow software supply chain best practices. - -Annotations -: [Annotations](/manuals/build/metadata/annotations.md) provide descriptive -metadata for images. Use annotations to record arbitrary information and attach -it to your image, which helps consumers and tools understand the origin, -contents, and how to use the image. - -> [!TIP] -> Why not just define these additional build options in the Compose file -> directly? -> -> The `build` property in the Compose file format does not support all build -> features. Additionally, some features, like multi-platform builds, can -> drastically increase the time it takes to build a service. For local -> development, you're better off keeping your build step simple and fast, -> saving the bells and whistles for release builds. - -To add these properties to the images you build with Bake, update the Bake file -as follows: - -```hcl -group "default" { - targets = ["vote", "result", "worker"] -} - -target "_common" { - annotations = ["org.opencontainers.image.authors=username"] - platforms = ["linux/amd64", "linux/arm64"] - attest = [ - "type=provenance,mode=max", - "type=sbom" - ] -} - -target "vote" { - inherits = ["_common"] - target = "final" -} - -target "result" { - inherits = ["_common"] -} - -target "worker" { - inherits = ["_common"] -} -``` - -This defines a new `_common` target that defines reusable build configuration -for adding multi-platform support, annotations, and attestations to your -images. The reusable target is inherited by the build targets. - -With these changes, building the project with Bake produces three sets of -multi-platform images for the `linux/amd64` and `linux/arm64` architectures. -Each image is decorated with an author annotation, and both SBOM and provenance -attestation records. - -## Conclusions - -The pattern demonstrated in this guide provides a useful approach for managing -production-ready Docker images in projects using Docker Compose. Using Bake -gives you access to all the powerful features of Buildx and BuildKit, and also -helps separate your development and build configuration in a reasonable way. - -### Further reading - -For more information about how to use Bake, check out these resources: - -- [Bake documentation](/manuals/build/bake/_index.md) -- [Building with Bake from a Compose file](/manuals/build/bake/compose-file.md) -- [Bake file reference](/manuals/build/bake/reference.md) -- [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](/guides/bake/index.md) -- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/container-supported-development.md b/content/guides/container-supported-development.md deleted file mode 100644 index 2362df2f3d8c..000000000000 --- a/content/guides/container-supported-development.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Faster development and testing with container-supported development" -linkTitle: Container-supported dev -summary: | - Containers don't have to be just for your app. Learn how to run your app's dependent services and other debugging tools to enhance your development environment. -description: | - Use containers in your local development loop to develop and test faster… even if your main app isn't running in containers. -keywords: containers, local development, dependent services, testing, debugging, development environment -tags: [app-dev] -params: - image: images/learning-paths/container-supported-development.png - time: 20 minutes - resource_links: [] ---- - -Containers offer a consistent way to build, share, and run applications across different environments. While containers are typically used to containerize your application, they also make it incredibly easy to run essential services needed for development. Instead of installing or connecting to a remote database, you can easily launch your own database. But the possibilities don't stop there. - -With container-supported development, you use containers to enhance your development environment by emulating or running your own instances of the services your app needs. This provides faster feedback loops, less coupling with remote services, and a greater ability to test error states. - -And best of all, you can have these benefits regardless of whether the main app under development is running in containers. - -## What you'll learn - -- The meaning of container-supported development -- How to connect non-containerized applications to containerized services -- Several examples of using containers to emulate or run local instances of services -- How to use containers to add additional troubleshooting and debugging tools to your development environment - -## Who's this for? - -- Teams that want to reduce the coupling they have on shared or deployed infrastructure or remote API endpoints -- Teams that want to reduce the complexity and costs associated with using cloud services directly during development -- Developers that want to make it easier to visualize what's going on in their databases, queues, etc. -- Teams that want to reduce the complexity of setting up their development environment without impacting the development of the app itself - -## Tools integration - -Works well with Docker Compose and Testcontainers. - -## Modules - -### What is container-supported development? - -Container-supported development is the idea of using containers to enhance your development environment by running local instances or emulators of the services your application relies on. Once you're using containers, it's easy to add additional services to visualize or troubleshoot what's going on in your services. - -{{< youtube-embed pNcrto_wGi0 >}} - -### Demo: running databases locally - -With container-supported development, it's easy to run databases locally. In this demo, you'll see how to do so, as well as how to connect a non-containerized application to the database. - -{{< youtube-embed VieWeXOwKLU >}} - -> [!TIP] -> -> Learn more about running databases in containers in the [Use containerized databases](/guides/databases.md) guide. - -### Demo: mocking API endpoints - -Many APIs require data from other data endpoints. In development, this adds complexities such as the sharing of credentials, uptime/availability, and rate limiting. Instead of relying on those services directly, your application can interact with a mock API server. - -This demo will demonstrate how using WireMock can make it easy to develop and test an application, including the APIs various error states. - -{{< youtube-embed VXSmX6f8vo0 >}} - -> [!TIP] -> -> Learn more about using WireMock to mock API in the [Mocking API services with WireMock](/guides/wiremock.md) guide. - -### Demo: developing the cloud locally - -When developing apps, it's often easier to outsource aspects of the application to cloud services, such as Amazon S3. However, connecting to those services in local development introduces IAM policies, networking constraints, and provisioning complications. While these requirements are important in a production setting, they complicate development environments significantly. - -With container-supported development, you can run local instances of these services during development and testing, removing the need for complex setups. In this demo, you'll see how LocalStack makes it easy to develop and test applications entirely from the developer's workstation. - -{{< youtube-embed JtwUMvR5xlY >}} - -> [!TIP] -> -> Learn more about using LocalStack in the [Develop and test AWS Cloud applications using LocalStack](/guides/localstack.md) guide. - -### Demo: adding additional debug and troubleshooting tools - -Once you start using containers in your development environment, it becomes much easier to add additional containers to visualize the contents of the databases or message queues, seed document stores, or event publishers. In this demo, you'll see a few of these examples, as well as how you can connect multiple containers together to make testing even easier. - -{{< youtube-embed TCZX15aKSu4 >}} - -<div id="lp-survey-anchor"></div> diff --git a/content/guides/cpp.md b/content/guides/cpp.md new file mode 100644 index 000000000000..bb0d2e3b2c83 --- /dev/null +++ b/content/guides/cpp.md @@ -0,0 +1,276 @@ +--- +title: C++ language-specific guide +linkTitle: C++ +description: Containerize and develop C++ applications using Docker. +keywords: getting started, c++ +summary: | + This guide explains how to containerize C++ applications using Docker. +aliases: + - /language/cpp/ + - /guides/language/cpp/ + - /language/cpp/containerize/ + - /language/cpp/develop/ + - /language/cpp/configure-ci-cd/ + - /language/cpp/deploy/ + - /guides/cpp/configure-ci-cd/ + - /guides/cpp/containerize/ + - /guides/cpp/deploy/ + - /guides/cpp/develop/ + - /guides/cpp/multistage/ + - /guides/cpp/security/ +params: + tags: [languages] + time: 20 minutes +--- + +The C++ getting started guide teaches you how to create a containerized C++ application using Docker. In this guide, you'll learn how to: + +> **Acknowledgment** +> +> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) and [Mohammad-Ali A'râbi](https://twitter.com/MohammadAliEN) for their contribution to this guide. + +- Containerize and run a C++ application using a multi-stage Docker build +- Build and run a C++ application using Docker Compose +- Set up a local environment to develop a C++ application using containers + +After completing the C++ getting started modules, you should be able to containerize your own C++ application based on the examples and instructions provided in this guide. + +Start by containerizing an existing C++ application. + +## Create a multi-stage build for your C++ application + +### Prerequisites + +- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +### Overview + +This section walks you through creating a multi-stage Docker build for a C++ application. +A multi-stage build is a Docker feature that allows you to use different base images for different stages of the build process, +so you can optimize the size of your final image and separate build dependencies from runtime dependencies. + +The standard practice for compiled languages like C++ is to have a build stage that compiles the code and a runtime stage that runs the compiled binary, +because the build dependencies are not needed at runtime. + +### Get the sample application + +Let's use a simple C++ application that prints `Hello, World!` to the terminal. To do so, clone the sample repository to use with this guide: + +```bash +$ git clone https://github.com/dockersamples/c-plus-plus-docker.git +``` + +The example for this section is under the `hello` directory in the repository. Get inside it and take a look at the files: + +```bash +$ cd c-plus-plus-docker/hello +$ ls +``` + +You should see the following files: + +```text +Dockerfile hello.cpp +``` + +### Check the Dockerfile + +Open the `Dockerfile` in an IDE or text editor. The `Dockerfile` contains the instructions for building the Docker image. + +```Dockerfile +# Stage 1: Build stage +FROM ubuntu:latest AS build + +# Install build-essential for compiling C++ code +RUN apt-get update && apt-get install -y build-essential + +# Set the working directory +WORKDIR /app + +# Copy the source code into the container +COPY hello.cpp . + +# Compile the C++ code statically to ensure it doesn't depend on runtime libraries +RUN g++ -o hello hello.cpp -static + +# Stage 2: Runtime stage +FROM scratch + +# Copy the static binary from the build stage +COPY --from=build /app/hello /hello + +# Command to run the binary +CMD ["/hello"] +``` + +The `Dockerfile` has two stages: + +1. **Build stage**: This stage uses the `ubuntu:latest` image to compile the C++ code and create a static binary. +2. **Runtime stage**: This stage uses the `scratch` image, which is an empty image, to copy the static binary from the build stage and run it. + +### Build the Docker image + +To build the Docker image, run the following command in the `hello` directory: + +```bash +$ docker build -t hello . +``` + +The `-t` flag tags the image with the name `hello`. + +### Run the Docker container + +To run the Docker container, use the following command: + +```bash +$ docker run hello +``` + +You should see the output `Hello, World!` in the terminal. + +Because the final image uses an empty `scratch` base, it contains only the +static binary and none of the build dependencies or usual OS tools. For +example, you can't run a simple `ls` command in the container: + +```bash +$ docker run hello ls +``` + +The absence of a shell and other tools keeps the image small and reduces its +attack surface. + +## Containerize a C++ application + +### Prerequisites + +- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +### Overview + +This section walks you through containerizing and running a C++ application, using Docker Compose. + +### Get the sample application + +We're using the same sample repository that you used in the previous sections of this guide. If you haven't already cloned the repository, clone it now: + +```console +$ git clone https://github.com/dockersamples/c-plus-plus-docker.git +``` + +You should now have the following contents in your `c-plus-plus-docker` (root) +directory. + +```text +├── c-plus-plus-docker/ +│ ├── compose.yml +│ ├── Dockerfile +│ ├── LICENSE +│ ├── ok_api.cpp +│ └── README.md + +``` + +To learn more about the files in the repository, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `c-plus-plus-docker` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You will see a message `{"Status" : "OK"}` in the browser. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `c-plus-plus-docker` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for C++ development + +### Prerequisites + +Complete [Containerize a C++ application](#containerize-a-c-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/c-plus-plus-docker.git && cd c-plus-plus-docker +``` + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. + +```yaml {hl_lines="11-14",linenos=true} +services: + ok-api: + image: ok-api + build: + context: . + dockerfile: Dockerfile + ports: + - "8080:8080" + develop: + watch: + - action: rebuild + path: . +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Now, if you modify your `ok_api.cpp` you will see the changes in real time without re-building the image. + +To test it out, open the `ok_api.cpp` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at [http://localhost:8080](http://localhost:8080). You should see the updated message. + +Press `ctrl+c` in the terminal to stop your application. + +### Summary + +In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + +- [Compose file reference](/reference/compose-file/) +- [Compose file watch](/manuals/compose/how-tos/file-watch.md) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) diff --git a/content/guides/cpp/_index.md b/content/guides/cpp/_index.md deleted file mode 100644 index 85f317765e3c..000000000000 --- a/content/guides/cpp/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: C++ language-specific guide -linkTitle: C++ -description: Containerize and develop C++ applications using Docker. -keywords: getting started, c++ -summary: | - This guide explains how to containerize C++ applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/cpp/ - - /guides/language/cpp/ -languages: [cpp] -params: - time: 20 minutes ---- - -The C++ getting started guide teaches you how to create a containerized C++ application using Docker. In this guide, you'll learn how to: - -> **Acknowledgment** -> -> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) and [Mohammad-Ali A'râbi](https://twitter.com/MohammadAliEN) for their contribution to this guide. - -- Containerize and run a C++ application using a multi-stage Docker build -- Build and run a C++ application using Docker Compose -- Set up a local environment to develop a C++ application using containers -- Configure a CI/CD pipeline for a containerized C++ application using GitHub Actions -- Deploy your containerized application locally to Kubernetes to test and debug your deployment -- Use BuildKit to generate SBOM attestations during the build process - -After completing the C++ getting started modules, you should be able to containerize your own C++ application based on the examples and instructions provided in this guide. - -Start by containerizing an existing C++ application. diff --git a/content/guides/cpp/configure-ci-cd.md b/content/guides/cpp/configure-ci-cd.md deleted file mode 100644 index e2992f2243b0..000000000000 --- a/content/guides/cpp/configure-ci-cd.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Configure CI/CD for your C++ application -linkTitle: Configure CI/CD -weight: 40 -keywords: ci/cd, github actions, c++, shiny -description: Learn how to configure CI/CD using GitHub Actions for your C++ application. -aliases: - - /language/cpp/configure-ci-cd/ - - /guides/language/cpp/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a C++ application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration and commit the changes. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your C++ application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/cpp/containerize.md b/content/guides/cpp/containerize.md deleted file mode 100644 index 974ff7d3ed86..000000000000 --- a/content/guides/cpp/containerize.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Containerize a C++ application -linkTitle: Containerize -weight: 10 -keywords: C++, containerize, initialize -description: Learn how to use Docker Compose to build and run a C++ application. -aliases: - - /language/cpp/containerize/ - - /guides/language/cpp/containerize/ ---- - -## Prerequisites - -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Overview - -This section walks you through containerizing and running a C++ application, using Docker Compose. - -## Get the sample application - -We're using the same sample repository that you used in the previous sections of this guide. If you haven't already cloned the repository, clone it now: - -```console -$ git clone https://github.com/dockersamples/c-plus-plus-docker.git -``` - -You should now have the following contents in your `c-plus-plus-docker` (root) -directory. - -```text -├── c-plus-plus-docker/ -│ ├── compose.yml -│ ├── Dockerfile -│ ├── LICENSE -│ ├── ok_api.cpp -│ └── README.md - -``` - -To learn more about the files in the repository, see the following: - -- [Dockerfile](/reference/dockerfile.md) -- [.dockerignore](/reference/dockerfile.md#dockerignore-file) -- [compose.yml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `c-plus-plus-docker` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You will see a message `{"Status" : "OK"}` in the browser. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `c-plus-plus-docker` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run your C++ -application using Docker. - -Related information: - -- [Docker Compose overview](/manuals/compose/_index.md) - -## Next steps - -In the next section, you'll learn how you can develop your application using -containers. diff --git a/content/guides/cpp/deploy.md b/content/guides/cpp/deploy.md deleted file mode 100644 index 120067302ba1..000000000000 --- a/content/guides/cpp/deploy.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Test your C++ deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, c++ -description: Learn how to develop locally using Kubernetes -aliases: - - /language/cpp/deploy/ - - /guides/language/cpp/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a C++ application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `c-plus-plus-docker` directory, create a file named -`docker-kubernetes.yml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your C++ application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-c-plus-plus-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: ok-api - template: - metadata: - labels: - service: ok-api - spec: - containers: - - name: ok-api-service - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - service: ok-api - ports: - - port: 8080 - targetPort: 8080 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your C++ application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 8080 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `c-plus-plus-docker` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-kubernetes.yml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```text - deployment.apps/docker-c-plus-plus-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-c-plus-plus-demo 1/1 1 1 10s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 88m - service-entrypoint NodePort 10.105.145.223 <none> 8080:30001/TCP 83s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`. - - ```console - http://localhost:30001/ - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-kubernetes.yml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your C++ application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/cpp/develop.md b/content/guides/cpp/develop.md deleted file mode 100644 index 016eac56cefa..000000000000 --- a/content/guides/cpp/develop.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Use containers for C++ development -linkTitle: Develop your app -weight: 20 -keywords: C++, local, development -description: Learn how to develop your C++ application locally. -aliases: - - /language/cpp/develop/ - - /guides/language/cpp/develop/ ---- - -## Prerequisites - -Complete [Containerize a C++ application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Configuring Compose to automatically update your running Compose services as you edit and save your code - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/c-plus-plus-docker.git && cd c-plus-plus-docker -``` - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. - -```yaml {hl_lines="11-14",linenos=true} -services: - ok-api: - image: ok-api - build: - context: . - dockerfile: Dockerfile - ports: - - "8080:8080" - develop: - watch: - - action: rebuild - path: . -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Now, if you modify your `ok_api.cpp` you will see the changes in real time without re-building the image. - -To test it out, open the `ok_api.cpp` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at [http://localhost:8080](http://localhost:8080). You should see the updated message. - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose file watch](/manuals/compose/how-tos/file-watch.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/cpp/multistage.md b/content/guides/cpp/multistage.md deleted file mode 100644 index 4a73d6f42f0a..000000000000 --- a/content/guides/cpp/multistage.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Create a multi-stage build for your C++ application -linkTitle: Multi-stage build -weight: 5 -keywords: C++, containerize, multi-stage -description: Learn how to create a multi-stage build for a C++ application. -aliases: -- /language/cpp/multistage/ -- /guides/language/cpp/multistage/ ---- - -## Prerequisites - -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Overview - -This section walks you through creating a multi-stage Docker build for a C++ application. -A multi-stage build is a Docker feature that allows you to use different base images for different stages of the build process, -so you can optimize the size of your final image and separate build dependencies from runtime dependencies. - -The standard practice for compiled languages like C++ is to have a build stage that compiles the code and a runtime stage that runs the compiled binary, -because the build dependencies are not needed at runtime. - -## Get the sample application - -Let's use a simple C++ application that prints `Hello, World!` to the terminal. To do so, clone the sample repository to use with this guide: - -```bash -$ git clone https://github.com/dockersamples/c-plus-plus-docker.git -``` - -The example for this section is under the `hello` directory in the repository. Get inside it and take a look at the files: - -```bash -$ cd c-plus-plus-docker/hello -$ ls -``` - -You should see the following files: - -```text -Dockerfile hello.cpp -``` - -## Check the Dockerfile - -Open the `Dockerfile` in an IDE or text editor. The `Dockerfile` contains the instructions for building the Docker image. - -```Dockerfile -# Stage 1: Build stage -FROM ubuntu:latest AS build - -# Install build-essential for compiling C++ code -RUN apt-get update && apt-get install -y build-essential - -# Set the working directory -WORKDIR /app - -# Copy the source code into the container -COPY hello.cpp . - -# Compile the C++ code statically to ensure it doesn't depend on runtime libraries -RUN g++ -o hello hello.cpp -static - -# Stage 2: Runtime stage -FROM scratch - -# Copy the static binary from the build stage -COPY --from=build /app/hello /hello - -# Command to run the binary -CMD ["/hello"] -``` - -The `Dockerfile` has two stages: - -1. **Build stage**: This stage uses the `ubuntu:latest` image to compile the C++ code and create a static binary. -2. **Runtime stage**: This stage uses the `scratch` image, which is an empty image, to copy the static binary from the build stage and run it. - -## Build the Docker image - -To build the Docker image, run the following command in the `hello` directory: - -```bash -$ docker build -t hello . -``` - -The `-t` flag tags the image with the name `hello`. - -## Run the Docker container - -To run the Docker container, use the following command: - -```bash -$ docker run hello -``` - -You should see the output `Hello, World!` in the terminal. - -## Summary - -In this section, you learned how to create a multi-stage build for a C++ application. Multi-stage builds help you optimize the size of your final image and separate build dependencies from runtime dependencies. -In this example, the final image only contains the static binary and doesn't include any build dependencies. - -As the image has an empty base, the usual OS tools are also absent. So, for example, you can't run a simple `ls` command in the container: - -```bash -$ docker run hello ls -``` - -This makes the image very lightweight and secure. diff --git a/content/guides/cpp/security.md b/content/guides/cpp/security.md deleted file mode 100644 index 7318fb5af6d5..000000000000 --- a/content/guides/cpp/security.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Supply-chain security for C++ Docker images -linkTitle: Supply-chain security -weight: 60 -keywords: C++, security, multi-stage -description: Learn how to extract SBOMs from C++ Docker images. -aliases: -- /language/cpp/security/ -- /guides/language/cpp/security/ ---- - -## Prerequisites - -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. -- You have a Docker Desktop installed, with containerd enabled for pulling and storing images (it's a checkbox in **Settings** > **General**). Otherwise, if you use Docker Engine: - - You have the [Docker Scout CLI plugin](https://docs.docker.com/scout/install/) installed. To install it on Docker Engine, use the following command: - - ```bash - $ curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- - ``` - - - You have [containerd enabled](https://docs.docker.com/engine/storage/containerd/) for Docker Engine. - -## Overview - -This section walks you through extracting Software Bill of Materials (SBOMs) from a C++ Docker image using Docker Scout. SBOMs provide a detailed list of all the components in a software package, including their versions and licenses. You can use SBOMs to track the provenance of your software and ensure that it complies with your organization's security and licensing policies. - -## Generate an SBOM - -Here we will use the Docker image that we built in the [Create a multi-stage build for your C++ application](/guides/language/cpp/multistage/) guide. If you haven't already built the image, follow the steps in that guide to build the image. -The image is named `hello`. To generate an SBOM for the `hello` image, run the following command: - -```bash -$ docker scout sbom --format list hello -``` - -The command will say "No packages discovered". This is because the final image is a scratch image and doesn't have any packages. - -## Generate an SBOM attestation - -The SBOM can be generated during the build process and "attached" to the image. This is called an SBOM attestation. -To generate an SBOM attestation for the `hello` image, first let's change the Dockerfile: - -```Dockerfile -ARG BUILDKIT_SBOM_SCAN_STAGE=true - -FROM ubuntu:latest AS build - -RUN apt-get update && apt-get install -y build-essential - -WORKDIR /app - -COPY hello.cpp . - -RUN g++ -o hello hello.cpp -static - -# -------------------- -FROM scratch - -COPY --from=build /app/hello /hello - -CMD ["/hello"] -``` - -The first line `ARG BUILDKIT_SBOM_SCAN_STAGE=true` enables SBOM scanning in the build stage. -Now, build the image with the following command: - -```bash -$ docker buildx build --sbom=true -t hello:sbom . -``` - -This command will build the image and generate an SBOM attestation. You can verify that the SBOM is attached to the image by running the following command: - -```bash -$ docker scout sbom --format list hello:sbom -``` - -Docker Scout reads the SBOM attestation when one is available, so this command reports packages from the build-stage metadata instead of indexing only the final scratch image filesystem. - -## Summary - -In this section, you learned how to generate SBOM attestation for a C++ Docker image during the build process. -Image scanners that inspect only the final filesystem may not identify packages in scratch images. -Use SBOM attestations to preserve package metadata from the build. diff --git a/content/guides/databases.md b/content/guides/databases.md index 8c2e2cd9e3a6..8bbcbdefe043 100644 --- a/content/guides/databases.md +++ b/content/guides/databases.md @@ -4,10 +4,10 @@ keywords: database, mysql title: Use containerized databases summary: | Learn how to effectively run and manage databases as containers. -tags: [databases] aliases: - /guides/use-case/databases/ params: + tags: [databases] time: 20 minutes --- diff --git a/content/guides/deno.md b/content/guides/deno.md new file mode 100644 index 000000000000..929d600472a6 --- /dev/null +++ b/content/guides/deno.md @@ -0,0 +1,273 @@ +--- +description: Containerize and develop Deno applications using Docker. +keywords: getting started, deno +title: Deno language-specific guide +summary: | + Learn how to containerize JavaScript applications with the Deno runtime using Docker. +linkTitle: Deno +aliases: + - /guides/deno/configure-ci-cd/ + - /guides/deno/containerize/ + - /guides/deno/deploy/ + - /guides/deno/develop/ +params: + tags: [languages] + time: 10 minutes +--- + +The Deno getting started guide teaches you how to create a containerized Deno application using Docker. + +> **Acknowledgment** +> +> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. + +## What will you learn? + +- Containerize and run a Deno application using Docker +- Set up a local environment to develop a Deno application using containers +- Use Docker Compose to run the application. + +## Prerequisites + +- Basic understanding of JavaScript is assumed. +- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +After completing the Deno getting started modules, you should be able to containerize your own Deno application based on the examples and instructions provided in this guide. + +Start by containerizing an existing Deno application. + +## Containerize a Deno application + +### Prerequisites + +- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +### Overview + +For a long time, Node.js has been the go-to runtime for server-side JavaScript applications. However, recent years have introduced new alternative runtimes, including [Deno](https://deno.land/). Like Node.js, Deno is a JavaScript and TypeScript runtime, but it takes a fresh approach with modern security features, a built-in standard library, and native support for TypeScript. + +Why develop Deno applications with Docker? Having a choice of runtimes is exciting, but managing multiple runtimes and their dependencies consistently across environments can be tricky. This is where Docker proves invaluable. Using containers to create and destroy environments on demand simplifies runtime management and ensures consistency. Additionally, as Deno continues to grow and evolve, Docker helps establish a reliable and reproducible development environment, minimizing setup challenges and streamlining the workflow. + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following +command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno +``` + +You should now have the following contents in your `deno-docker` directory. + +```text +├── deno-docker/ +│ ├── compose.yml +│ ├── Dockerfile +│ ├── LICENSE +│ ├── server.ts +│ └── README.md +``` + +### Understand the sample application + +The sample application is a simple Deno application that uses the Oak framework to create a simple API that returns a JSON response. The application listens on port 8000 and returns a message `{"Status" : "OK"}` when you access the application in a browser. + +```typescript +// server.ts +import { Application, Router } from "https://deno.land/x/oak@v12.0.0/mod.ts"; + +const app = new Application(); +const router = new Router(); + +// Define a route that returns JSON +router.get("/", (context) => { + context.response.body = { Status: "OK" }; + context.response.type = "application/json"; +}); + +app.use(router.routes()); +app.use(router.allowedMethods()); + +console.log("Server running on http://localhost:8000"); +await app.listen({ port: 8000 }); +``` + +### Create a Dockerfile + +Before creating a Dockerfile, you need to choose a base image. You can either use the [Deno Docker Official Image](https://hub.docker.com/r/denoland/deno) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). + +Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) are available for Deno in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno). You can pull DHIs directly from the `dhi.io` registry. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Deno DHI as `dhi.io/deno:2`. The tag (`2`) in this example refers to the version to the latest 2.x version of Deno. + + ```console + $ docker pull dhi.io/deno:2 + ``` + +For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno). + +```dockerfile +# Use the DHI Deno image as the base image +FROM dhi.io/deno:2 + +# Set the working directory +WORKDIR /app + +# Copy server code into the container +COPY server.ts . + +# Set permissions (optional but recommended for security) +USER deno + +# Expose port 8000 +EXPOSE 8000 + +# Run the Deno server +CMD ["run", "--allow-net", "server.ts"] +``` + +{{< /tab >}} +{{< tab name="Using the official image" >}} + +Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `denoland/deno:latest` as the base image. + +This is the official image for Deno. This image is [available on the Docker Hub](https://hub.docker.com/r/denoland/deno). + +```dockerfile +# Use the official Deno image +FROM denoland/deno:latest + +# Set the working directory +WORKDIR /app + +# Copy server code into the container +COPY server.ts . + +# Set permissions (optional but recommended for security) +USER deno + +# Expose port 8000 +EXPOSE 8000 + +# Run the Deno server +CMD ["run", "--allow-net", "server.ts"] +``` + +{{< /tab >}} +{{< /tabs >}} + +In addition to specifying the base image, the Dockerfile also: + +- Sets the working directory in the container to `/app`. +- Copies `server.ts` into the container. +- Sets the user to `deno` to run the application as a non-root user. +- Exposes port 8000 to allow traffic to the application. +- Runs the Deno server using the `CMD` instruction. +- Uses the `--allow-net` flag to allow network access to the application. The `server.ts` file uses the Oak framework to create a simple API that listens on port 8000. + +### Run the application + +Make sure you are in the `deno-docker` directory. Run the following command in a terminal to build and run the application. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You will see a message `{"Status" : "OK"}` in the browser. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `deno-docker` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8000](http://localhost:8000). + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +## Use containers for Deno development + +### Prerequisites + +Complete [Containerize a Deno application](#containerize-a-deno-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno +``` + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. + +```yaml {hl_lines="9-12",linenos=true} +services: + server: + image: deno-server + build: + context: . + dockerfile: Dockerfile + ports: + - "8000:8000" + develop: + watch: + - action: rebuild + path: . +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Now, if you modify your `server.ts` you will see the changes in real time without re-building the image. + +To test it out, open the `server.ts` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:8000`. You should see the updated message. + +Press `ctrl+c` in the terminal to stop your application. + +### Summary + +In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + +- [Compose file reference](/reference/compose-file/) +- [Compose file watch](/manuals/compose/how-tos/file-watch.md) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) diff --git a/content/guides/deno/_index.md b/content/guides/deno/_index.md deleted file mode 100644 index f2a9dc38b715..000000000000 --- a/content/guides/deno/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Containerize and develop Deno applications using Docker. -keywords: getting started, deno -title: Deno language-specific guide -summary: | - Learn how to containerize JavaScript applications with the Deno runtime using Docker. -linkTitle: Deno -languages: [js] -tags: [dhi] -params: - time: 10 minutes ---- - -The Deno getting started guide teaches you how to create a containerized Deno application using Docker. - -> **Acknowledgment** -> -> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. - -## What will you learn? - -* Containerize and run a Deno application using Docker -* Set up a local environment to develop a Deno application using containers -* Use Docker Compose to run the application. -* Configure a CI/CD pipeline for a containerized Deno application using GitHub Actions -* Deploy your containerized application locally to Kubernetes to test and debug your deployment - -## Prerequisites - -- Basic understanding of JavaScript is assumed. -- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -After completing the Deno getting started modules, you should be able to containerize your own Deno application based on the examples and instructions provided in this guide. - -Start by containerizing an existing Deno application. diff --git a/content/guides/deno/configure-ci-cd.md b/content/guides/deno/configure-ci-cd.md deleted file mode 100644 index 8d62f21be40a..000000000000 --- a/content/guides/deno/configure-ci-cd.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Configure CI/CD for your Deno application -linkTitle: Configure CI/CD -weight: 40 -keywords: ci/cd, github actions, deno, shiny -description: Learn how to configure CI/CD using GitHub Actions for your Deno application. -aliases: -- /language/deno/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Deno application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token)for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration and commit the changes. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your Deno application. - -Related information: - - [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) - - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/deno/containerize.md b/content/guides/deno/containerize.md deleted file mode 100644 index a738c6dfba83..000000000000 --- a/content/guides/deno/containerize.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Containerize a Deno application -linkTitle: Containerize your app -weight: 10 -keywords: deno, containerize, initialize -description: Learn how to containerize a Deno application. -aliases: - - /language/deno/containerize/ ---- - -## Prerequisites - -* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Overview - -For a long time, Node.js has been the go-to runtime for server-side JavaScript applications. However, recent years have introduced new alternative runtimes, including [Deno](https://deno.land/). Like Node.js, Deno is a JavaScript and TypeScript runtime, but it takes a fresh approach with modern security features, a built-in standard library, and native support for TypeScript. - -Why develop Deno applications with Docker? Having a choice of runtimes is exciting, but managing multiple runtimes and their dependencies consistently across environments can be tricky. This is where Docker proves invaluable. Using containers to create and destroy environments on demand simplifies runtime management and ensures consistency. Additionally, as Deno continues to grow and evolve, Docker helps establish a reliable and reproducible development environment, minimizing setup challenges and streamlining the workflow. - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following -command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno -``` - -You should now have the following contents in your `deno-docker` directory. - -```text -├── deno-docker/ -│ ├── compose.yml -│ ├── Dockerfile -│ ├── LICENSE -│ ├── server.ts -│ └── README.md -``` - -## Understand the sample application - -The sample application is a simple Deno application that uses the Oak framework to create a simple API that returns a JSON response. The application listens on port 8000 and returns a message `{"Status" : "OK"}` when you access the application in a browser. - -```typescript -// server.ts -import { Application, Router } from "https://deno.land/x/oak@v12.0.0/mod.ts"; - -const app = new Application(); -const router = new Router(); - -// Define a route that returns JSON -router.get("/", (context) => { - context.response.body = { Status: "OK" }; - context.response.type = "application/json"; -}); - -app.use(router.routes()); -app.use(router.allowedMethods()); - -console.log("Server running on http://localhost:8000"); -await app.listen({ port: 8000 }); -``` - -## Create a Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Deno Docker Official Image](https://hub.docker.com/r/denoland/deno) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) are available for Deno in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno). You can pull DHIs directly from the `dhi.io` registry. - -1. Sign in to the DHI registry: - - ```console - $ docker login dhi.io - ``` - -2. Pull the Deno DHI as `dhi.io/deno:2`. The tag (`2`) in this example refers to the version to the latest 2.x version of Deno. - - ```console - $ docker pull dhi.io/deno:2 - ``` - -For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno). - -```dockerfile -# Use the DHI Deno image as the base image -FROM dhi.io/deno:2 - -# Set the working directory -WORKDIR /app - -# Copy server code into the container -COPY server.ts . - -# Set permissions (optional but recommended for security) -USER deno - -# Expose port 8000 -EXPOSE 8000 - -# Run the Deno server -CMD ["run", "--allow-net", "server.ts"] -``` - -{{< /tab >}} -{{< tab name="Using the official image" >}} - -Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `denoland/deno:latest` as the base image. - -This is the official image for Deno. This image is [available on the Docker Hub](https://hub.docker.com/r/denoland/deno). - -```dockerfile -# Use the official Deno image -FROM denoland/deno:latest - -# Set the working directory -WORKDIR /app - -# Copy server code into the container -COPY server.ts . - -# Set permissions (optional but recommended for security) -USER deno - -# Expose port 8000 -EXPOSE 8000 - -# Run the Deno server -CMD ["run", "--allow-net", "server.ts"] -``` - -{{< /tab >}} -{{< /tabs >}} - -In addition to specifying the base image, the Dockerfile also: - -- Sets the working directory in the container to `/app`. -- Copies `server.ts` into the container. -- Sets the user to `deno` to run the application as a non-root user. -- Exposes port 8000 to allow traffic to the application. -- Runs the Deno server using the `CMD` instruction. -- Uses the `--allow-net` flag to allow network access to the application. The `server.ts` file uses the Oak framework to create a simple API that listens on port 8000. - -## Run the application - -Make sure you are in the `deno-docker` directory. Run the following command in a terminal to build and run the application. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You will see a message `{"Status" : "OK"}` in the browser. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `deno-docker` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8000](http://localhost:8000). - - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -## Summary - -In this section, you learned how you can containerize and run your Deno -application using Docker. - -Related information: - - - [Dockerfile reference](/reference/dockerfile.md) - - [.dockerignore file](/reference/dockerfile.md#dockerignore-file) - - [Docker Compose overview](/manuals/compose/_index.md) - - [Compose file reference](/reference/compose-file/_index.md) - - [Docker Hardened Images](/dhi/) - -## Next steps - -In the next section, you'll learn how you can develop your application using -containers. diff --git a/content/guides/deno/deploy.md b/content/guides/deno/deploy.md deleted file mode 100644 index 7e00828ec9f1..000000000000 --- a/content/guides/deno/deploy.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Test your Deno deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, deno -description: Learn how to develop locally using Kubernetes -aliases: -- /language/deno/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a Deno application](containerize.md). -- [Turn on Kubernetes](/manuals//desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `deno-docker` directory, create a file named -`docker-kubernetes.yml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Deno application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-deno-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: deno-api - template: - metadata: - labels: - app: deno-api - spec: - containers: - - name: deno-api - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - app: deno-api - ports: - - port: 8000 - targetPort: 8000 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - - - A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your Deno application](configure-ci-cd.md). - - A NodePort service, which will route traffic from port 30001 on your host to - port 8000 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `deno-docker` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-kubernetes.yml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```text - deployment.apps/docker-deno-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-deno-demo 1/1 1 1 10s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 88m - service-entrypoint NodePort 10.105.145.223 <none> 8000:30001/TCP 83s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`. - - ```console - http://localhost:30001/ - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-kubernetes.yml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your Deno application to a fully-featured Kubernetes environment on your development machine. - -Related information: - - [Kubernetes documentation](https://kubernetes.io/docs/home/) - - [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) - - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/deno/develop.md b/content/guides/deno/develop.md deleted file mode 100644 index d717823b634d..000000000000 --- a/content/guides/deno/develop.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Use containers for Deno development -linkTitle: Develop your app -weight: 20 -keywords: deno, local, development -description: Learn how to develop your Deno application locally. -aliases: -- /language/deno/develop/ ---- - -## Prerequisites - -Complete [Containerize a Deno application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Configuring Compose to automatically update your running Compose services as you edit and save your code - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno -``` - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. - -```yaml {hl_lines="9-12",linenos=true} -services: - server: - image: deno-server - build: - context: . - dockerfile: Dockerfile - ports: - - "8000:8000" - develop: - watch: - - action: rebuild - path: . -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Now, if you modify your `server.ts` you will see the changes in real time without re-building the image. - -To test it out, open the `server.ts` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:8000`. You should see the updated message. - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - - [Compose file reference](/reference/compose-file/) - - [Compose file watch](/manuals/compose/how-tos/file-watch.md) - - [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/dex.md b/content/guides/dex.md index 0aaae8021195..b8c6b3a2f504 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -4,9 +4,8 @@ description: &desc Mocking OAuth services in testing with Dex keywords: Dex, container-supported development linktitle: Mocking OAuth services with Dex summary: *desc -tags: [app-dev, distributed-systems] -languages: [] params: + tags: [testing] time: 10 minutes --- diff --git a/content/guides/dhi-backstage.md b/content/guides/dhi-backstage.md index 01bf4f7f986a..7100da786a95 100644 --- a/content/guides/dhi-backstage.md +++ b/content/guides/dhi-backstage.md @@ -3,8 +3,8 @@ title: Secure a Backstage application with Docker Hardened Images description: Secure a Backstage developer portal using Docker Hardened Images, covering native module compilation, Socket Firewall protection, and distroless runtime images. summary: Learn how to secure a Backstage developer portal using Docker Hardened Images (DHI), handle native module compilation with better-sqlite3, add Socket Firewall protection during dependency installation, and produce a distroless runtime image using DHI customizations. keywords: docker hardened images, dhi, backstage, CNCF, developer portal, node.js, native modules, sqlite, better-sqlite3, distroless, socket firewall, dhictl, multi-stage build -tags: ["Docker Hardened Images", "dhi"] params: + tags: [security] proficiencyLevel: Intermediate time: 45 minutes prerequisites: @@ -375,10 +375,17 @@ Then create the customization: dhictl customization create --org YOUR_ORG node-backstage.yaml ``` -Monitor the build progress: +Monitor the build progress using the customization ID from the create output. +To look up the ID, run: ```console -dhictl customization build list --org YOUR_ORG YOUR_ORG/dhi-node "backstage" +dhictl customization list --org YOUR_ORG +``` + +Then monitor the build: + +```console +dhictl customization build list <customization-id> --org YOUR_ORG ``` Docker builds the customized image on its secure infrastructure and publishes it as `YOUR_ORG/dhi-node:24-alpine3.23_backstage`. @@ -430,7 +437,7 @@ docker exec -it <container-id> sh OCI runtime exec failed: exec failed: unable to start container process: ... ``` -Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container. +Use [Docker Debug](/dhi/how-to/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container. > [!NOTE] > @@ -479,5 +486,5 @@ Different scanners detect different issues. Running all three gives you the most - [Create and build a DHI](/dhi/how-to/build/) — learn how to write a DHI definition file, build images locally. - [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line. - [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages. -- [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images. -- [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell. +- [Compare images](/dhi/how-to/search-evaluate/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images. +- [Docker Debug](/dhi/how-to/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell. diff --git a/content/guides/dhi-from-doi.md b/content/guides/dhi-from-doi.md deleted file mode 100644 index d0b367753d0e..000000000000 --- a/content/guides/dhi-from-doi.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Migrate to DHI from Docker Official Images -summary: Step-by-step guide to migrate from Docker Official Images to Docker Hardened Images -keywords: docker hardened images, dhi, docker official images, migration, secure images -type: redirect -target: /dhi/migration/migrate-from-doi/ -tags: [dhi] -languages: [] -params: - time: 10 minutes - featured: true - image: /images/guides/dhi-migrate-doi.webp ---- diff --git a/content/guides/dhi-from-wolfi.md b/content/guides/dhi-from-wolfi.md deleted file mode 100644 index 166ed977de86..000000000000 --- a/content/guides/dhi-from-wolfi.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Migrate to DHI from Wolfi -summary: Step-by-step guide to migrate from Wolfi to Docker Hardened Images -keywords: docker hardened images, dhi, wolfi, migration, secure images, distroless -type: redirect -target: /dhi/migration/migrate-from-wolfi/ -tags: [dhi] -languages: [] -params: - time: 10 minutes - featured: true - image: /images/guides/dhi-migrate-wolfi.webp ---- diff --git a/content/guides/dhi-go-example.md b/content/guides/dhi-go-example.md deleted file mode 100644 index f3adf7d67b51..000000000000 --- a/content/guides/dhi-go-example.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Migrate a Go app to DHI -summary: | - Example showing how to migrate a Go application to Docker Hardened Images -keywords: docker hardened images, dhi, go, golang, migration, secure images -type: redirect -target: /dhi/migration/examples/go/ -tags: [dhi] -languages: [] -params: - time: 10 minutes - featured: true - image: /images/guides/dhi-examples-go.webp ---- diff --git a/content/guides/dhi-nodejs-example.md b/content/guides/dhi-nodejs-example.md deleted file mode 100644 index da22a6ebed23..000000000000 --- a/content/guides/dhi-nodejs-example.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Migrate a Node.js app to DHI -summary: | - Example showing how to migrate a Node.js application to Docker Hardened - Images -keywords: docker hardened images, dhi, node.js, nodejs, migration, secure images -type: redirect -target: /dhi/migration/examples/node/ -tags: [dhi] -languages: [] -params: - time: 10 minutes - featured: true - image: /images/guides/dhi-examples-nodejs.webp ---- diff --git a/content/guides/dhi-openshift.md b/content/guides/dhi-openshift.md index d347f604178b..c588f81d00a0 100644 --- a/content/guides/dhi-openshift.md +++ b/content/guides/dhi-openshift.md @@ -3,8 +3,8 @@ title: Use Docker Hardened Images with Red Hat OpenShift description: Deploy Docker Hardened Images on Red Hat OpenShift Container Platform, covering Security Context Constraints, arbitrary user ID assignment, file permissions, and best practices. summary: Learn how to deploy Docker Hardened Images (DHI) on Red Hat OpenShift, configure Security Context Constraints, handle arbitrary user ID assignment, and set file permissions for both runtime and development image variants. keywords: docker hardened images, dhi, openshift, OCP, SCC, security context constraints, non-root, distroless, containers, red hat -tags: ["Docker Hardened Images", "dhi"] params: + tags: [security] proficiencyLevel: Intermediate time: 30 minutes prerequisites: @@ -620,6 +620,6 @@ and use `COPY --chown` to transfer results. - [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide. - [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization. -- [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development). +- [Debug a container](/dhi/how-to/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development). - [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints. - [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images. diff --git a/content/guides/dhi-python-example.md b/content/guides/dhi-python-example.md deleted file mode 100644 index e45b5cd9a0b4..000000000000 --- a/content/guides/dhi-python-example.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Migrate a Python app to DHI -summary: | - Example showing how to migrate a Python application to Docker Hardened Images -keywords: docker hardened images, dhi, python, migration, secure images -type: redirect -target: /dhi/migration/examples/python/ -tags: [dhi] -languages: [] -params: - time: 10 minutes - featured: true - image: /images/guides/dhi-examples-python.webp ---- diff --git a/content/guides/dhi-vex-walkthrough.md b/content/guides/dhi-vex-walkthrough.md index 9ffbde76f822..89ceed00b706 100644 --- a/content/guides/dhi-vex-walkthrough.md +++ b/content/guides/dhi-vex-walkthrough.md @@ -7,8 +7,10 @@ summary: > Scan a Docker Hardened Image with and without VEX and audit every suppression and its justification. keywords: vex, openvex, not_affected, under_investigation, affected, cve, docker scout, dhi, vulnerability -tags: [dhi] +weight: 1 params: + tags: [security] + featured: true proficiencyLevel: Intermediate time: 25 minutes --- @@ -280,7 +282,7 @@ The justification codes have precise meanings: that addresses the CVE in this image. For the full list of justification codes, see [VEX status -reference](/manuals/dhi/core-concepts/vex.md#not_affected-justification-codes). +reference](/manuals/dhi/explore/security-concepts/vex.md#not_affected-justification-codes). Every suppression is documented, auditable, and verifiable with any VEX-enabled scanner. @@ -355,7 +357,7 @@ $ curl -s https://raw.githubusercontent.com/docker-hardened-images/advisories/ma ``` For status definitions and justification codes, see the [VEX status -reference](/manuals/dhi/core-concepts/vex.md#vex-status-reference). +reference](/manuals/dhi/explore/security-concepts/vex.md#vex-status-reference). ## What's next @@ -367,7 +369,7 @@ reference](/manuals/dhi/core-concepts/vex.md#vex-status-reference). VEX](/manuals/scout/how-tos/create-exceptions-vex.md). - VEX status reference: For status definitions, justification codes, and why DHI does not use `fixed`, see [Vulnerability Exploitability eXchange - (VEX)](/manuals/dhi/core-concepts/vex.md#vex-status-reference). + (VEX)](/manuals/dhi/explore/security-concepts/vex.md#vex-status-reference). - Browse the VEX feed directly: The raw VEX data is published at [github.com/docker-hardened-images/advisories](https://github.com/docker-hardened-images/advisories/tree/main/vex), organized by image name. diff --git a/content/guides/django.md b/content/guides/django.md index fa242ece8417..1fd72f3f9170 100644 --- a/content/guides/django.md +++ b/content/guides/django.md @@ -8,9 +8,8 @@ summary: | You'll scaffold the project with uv, create a production-ready Dockerfile using a Docker Hardened Image, then add a development stage and Compose Watch for fast iteration. -languages: [python] -tags: [dhi] params: + tags: [languages] time: 25 minutes --- diff --git a/content/guides/docker-build-cloud/_index.md b/content/guides/docker-build-cloud/_index.md deleted file mode 100644 index 2c7eca2cf459..000000000000 --- a/content/guides/docker-build-cloud/_index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Docker Build Cloud: Reclaim your time with fast, multi-architecture builds" -linkTitle: Docker Build Cloud -description: | - Learn how to build and deploy Docker images to the cloud with Docker Build - Cloud. -summary: | - Build applications up to 39x faster using cloud-based resources, shared team - cache, and native multi-architecture support. -keywords: docker build cloud, cloud builds, multi-architecture, shared cache, ci/cd, build performance -tags: [product-demo] -aliases: - - /learning-paths/docker-build-cloud/ -params: - image: images/learning-paths/build-cloud.png - time: 10 minutes - resource_links: - - title: Product page - url: https://www.docker.com/products/build-cloud/ - - title: Docker Build Cloud overview - url: /build-cloud/ - - title: Subscriptions and features - url: "https://www.docker.com/pricing?ref=Docs&refAction=DocsGuidesBuildCloud" - - title: Using Docker Build Cloud - url: /build-cloud/usage/ ---- - -<!-- vale Vale.Spelling = NO --> - -98% of developers spend up to an hour every day waiting for builds to finish -([Incredibuild: 2022 Big Dev Build Times](https://www.incredibuild.com/survey-report-2022)). -Heavy, complex builds can become a major roadblock for development teams, -slowing down both local development and CI/CD pipelines. - -<!-- vale Vale.Spelling = YES --> - -Docker Build Cloud speeds up image build times to improve developer -productivity, reduce frustrations, and help you shorten the release cycle. - -## Who’s this for? - -- Anyone who wants to tackle common causes of slow image builds: limited local - resources, slow emulation, and lack of build collaboration across a team. -- Developers working on older machines who want to build faster. -- Development teams working on the same repository who want to cut wait times - with a shared cache. -- Developers performing multi-architecture builds who don’t want to spend hours - configuring and rebuilding for emulators. - -## What you’ll learn - -- Building container images faster locally and in CI -- Accelerating builds for multi-platform images -- Reusing pre-built images to expedite workflows - -## Tools integration - -Works well with Docker Compose, GitHub Actions, and other CI solutions - -<div id="dbc-lp-survey-anchor"></div> diff --git a/content/guides/docker-build-cloud/ci.md b/content/guides/docker-build-cloud/ci.md deleted file mode 100644 index a13adb91004c..000000000000 --- a/content/guides/docker-build-cloud/ci.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Demo: Using Docker Build Cloud in CI" -description: Learn how to use Docker Build Cloud to build your app faster in CI. -keywords: docker build cloud, ci/cd, github actions, cloud builds, build performance -weight: 30 ---- - -Docker Build Cloud can significantly decrease the time it takes for your CI builds -take to run, saving you time and money. - -Since the builds run remotely, your CI runner can still use the Docker tooling CLI -without needing elevated permissions, making your builds more secure by default. - -In this demo, you will see: - -- How to integrate Docker Build Cloud into a variety of CI platforms -- How to use Docker Build Cloud in GitHub Actions to build multi-architecture images -- Speed differences between a workflow using Docker Build Cloud and a workflow running natively -- How to use Docker Build Cloud in a GitLab Pipeline - -{{< youtube-embed "wvLdInoVBGg" >}} - -<div id="dbc-lp-survey-anchor"></div> diff --git a/content/guides/docker-build-cloud/common-questions.md b/content/guides/docker-build-cloud/common-questions.md deleted file mode 100644 index eb340b4cb2fd..000000000000 --- a/content/guides/docker-build-cloud/common-questions.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Common challenges and questions -description: Explore common challenges and questions related to Docker Build Cloud. -keywords: docker build cloud, faq, troubleshooting, cloud builds, pricing -weight: 40 ---- - -### Is Docker Build Cloud a standalone product or a part of Docker Desktop? - -Docker Build Cloud is a service that can be used both with Docker Desktop and -standalone. It lets you build your container images faster, both locally and in -CI, with builds running on cloud infrastructure. The service uses a remote -build cache, ensuring fast builds anywhere and for all team members. - -When used with Docker Desktop, the [Builds view](/desktop/use-desktop/builds/) -works with Docker Build Cloud out-of-the-box. It shows information about your -builds and those initiated by your team members using the same builder, -enabling collaborative troubleshooting. - -To use Docker Build Cloud without Docker Desktop, you must -[download and install](/build-cloud/setup/#use-docker-build-cloud-without-docker-desktop) -a version of Buildx with support for Docker Build Cloud (the `cloud` driver). -If you plan on building with Docker Build Cloud using the `docker compose -build` command, you also need a version of Docker Compose that supports Docker -Build Cloud. - -### How does Docker Build Cloud work with Docker Compose? - -Docker Compose works out of the box with Docker Build Cloud. Install the Docker -Build Cloud-compatible client (buildx) and it works with both commands. - -### How many minutes are included in Docker Build Cloud Team plans? - -Pricing details for Docker Build Cloud can be found on the [pricing page](https://www.docker.com/pricing?ref=Docs&refAction=DocsGuidesBuildCloudFaq). - -### I’m a Docker personal user. Can I try Docker Build Cloud? - -Docker subscribers (Pro, Team, Business) receive a set number of minutes each -month, shared across the account, to use Build Cloud. - -If you do not have a Docker subscription, you may sign up for a free Personal -account and start a trial of Docker Build Cloud. Personal accounts are limited to a -single user. - -For teams to receive the shared cache benefit, they must either be on a Docker -Team or Docker Business subscription. - -### Does Docker Build Cloud support CI platforms? Does it work with GitHub Actions? - -Yes, Docker Build Cloud can be used with various CI platforms including GitHub -Actions, CircleCI, Jenkins, and others. It can speed up your build pipelines, -which means less time spent waiting and context switching. - -Docker Build Cloud can be used with GitHub Actions to automate your build, -test, and deployment pipeline. Docker provides a set of official GitHub Actions -that you can use in your workflows. - -Using GitHub Actions with Docker Build Cloud is straightforward. With a -one-line change in your GitHub Actions configuration, everything else stays the -same. You don't need to create new pipelines. Learn more in the [CI -documentation](/build-cloud/ci/) for Docker Build Cloud. - -<div id="dbc-lp-survey-anchor"></div> diff --git a/content/guides/docker-build-cloud/dev.md b/content/guides/docker-build-cloud/dev.md deleted file mode 100644 index 33ba82ec62b9..000000000000 --- a/content/guides/docker-build-cloud/dev.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Demo: set up and use Docker Build Cloud in development" -description: Learn how to use Docker Build Cloud for local builds. -keywords: docker build cloud, local development, cloud builds, multi-platform, build performance -weight: 20 ---- - -With Docker Build Cloud, you can easily shift the build workload from local machines -to the cloud, helping you achieve faster build times, especially for multi-platform builds. - -In this demo, you'll see: - -- How to setup the builder locally -- How to use Docker Build Cloud with Docker Compose -- How the image cache speeds up builds for others on your team - -{{< youtube-embed "oPGq2AP5OtQ" >}} - -<div id="dbc-lp-survey-anchor"></div> diff --git a/content/guides/docker-build-cloud/why.md b/content/guides/docker-build-cloud/why.md deleted file mode 100644 index cc1e5599d7ca..000000000000 --- a/content/guides/docker-build-cloud/why.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Why Docker Build Cloud? -description: Learn how Docker Build Cloud makes your builds faster. -keywords: docker build cloud, cloud builds, shared cache, multi-architecture, build performance -weight: 10 ---- - -Docker Build Cloud is a service that lets you build container images faster, -both locally and in CI. Builds run on cloud infrastructure optimally -dimensioned for your workloads, with no configuration required. The service -uses a remote build cache, ensuring fast builds anywhere and for all team -members. - -Docker Build Cloud provides several benefits over local builds: - -- Improved build speed -- Shared build cache -- Native multi-platform builds - -There’s no need to worry about managing builders or infrastructure — simply -connect to your builders and start building. Each cloud builder provisioned to -an organization is completely isolated to a single Amazon EC2 instance, with a -dedicated EBS volume for build cache and encryption in transit. That means -there are no shared processes or data between cloud builders. - -{{< youtube-embed "8AqKhEO2PQA" >}} - -<div id="dbc-lp-survey-anchor"></div> diff --git a/content/guides/docker-compose/_index.md b/content/guides/docker-compose/_index.md deleted file mode 100644 index 4b715d87b845..000000000000 --- a/content/guides/docker-compose/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Defining and running multi-container applications with Docker Compose -linkTitle: Docker Compose -summary: | - Simplify the process of defining, configuring, and running multi-container - Docker applications. -description: Learn how to use Docker Compose to define and run multi-container Docker applications. -keywords: docker compose, multi-container, compose file, services, orchestration, yaml -tags: [product-demo] -aliases: - - /learning-paths/docker-compose/ -params: - image: images/learning-paths/compose.png - time: 10 minutes - resource_links: - - title: Overview of Docker Compose CLI - url: /reference/cli/docker/compose/ - - title: Overview of Docker Compose - url: /compose/ - - title: How Compose works - url: /compose/intro/compose-application-model/ - - title: Using profiles with Compose - url: /compose/how-tos/profiles/ - - title: Control startup and shutdown order with Compose - url: /compose/how-tos/startup-order/ - - title: Compose Build Specification - url: /compose/compose-file/build/ ---- - -Developers face challenges with multi-container Docker applications, including -complex configuration, dependency management, and maintaining consistent -environments. Networking, resource allocation, data persistence, logging, and -monitoring add to the difficulty. Security concerns and troubleshooting issues -further complicate the process, requiring effective tools and practices for -efficient management. - -Docker Compose solves the problem of managing multi-container Docker -applications by providing a simple way to define, configure, and run all the -containers needed for an application using a single YAML file. This approach -helps developers to easily set up, share, and maintain consistent development, -testing, and production environments, ensuring that complex applications can be -deployed with all their dependencies and services properly configured and -orchestrated. - -## What you’ll learn - -- What Docker Compose is and what it does -- How to define services -- Use cases for Docker Compose -- How things would be different without Docker Compose - -## Who’s this for? - -- Developers and DevOps engineers who need to define, manage, and orchestrate - multi-container Docker applications efficiently across multiple environments. -- Development teams that want to increase productivity by streamlining - development workflows and reducing setup time. - -## Tools integration - -Works well with Docker CLI, CI/CD tools, and container orchestration tools. - -<div id="compose-lp-survey-anchor"></div> diff --git a/content/guides/docker-compose/common-questions.md b/content/guides/docker-compose/common-questions.md deleted file mode 100644 index ba8f00154948..000000000000 --- a/content/guides/docker-compose/common-questions.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Common challenges and questions -description: Explore common challenges and questions related to Docker Compose. -keywords: docker compose, faq, troubleshooting, environments, multi-container -weight: 30 ---- - -<!-- vale Docker.HeadingLength = NO --> - -### Do I need to maintain a separate Compose file for my development, testing, and staging environments? - -You don't necessarily need to maintain entirely separate Compose files for your -development, testing, and staging environments. You can define all your -services in a single Compose file (`compose.yaml`). You can use profiles to -group service configurations specific to each environment (`dev`, `test`, -`staging`). - -When you need to spin up an environment, you can activate the corresponding -profiles. For example, to set up the development environment: - -```console -$ docker compose --profile dev up -``` - -This command starts only the services associated with the `dev` profile, -leaving the rest inactive. - -For more information on using profiles, see [Using profiles with -Compose](/compose/how-tos/profiles/). - -### How can I enforce the database service to start up before the frontend service? - -Docker Compose ensures services start in a specific order by using the -`depends_on` property. This tells Compose to start the database service before -even attempting to launch the frontend service. This is crucial since -applications often rely on databases being ready for connections. - -However, `depends_on` only guarantees the order, not that the database is fully -initialized. For a more robust approach, especially if your application relies -on a prepared database (e.g., after migrations), consider [health -checks](/reference/compose-file/services.md#healthcheck). Here, you can -configure the frontend to wait until the database passes its health check -before starting. This ensures the database is not only up but also ready to -handle requests. - -For more information on setting the startup order of your services, see -[Control startup and shutdown order in Compose](/compose/how-tos/startup-order/). - -### Can I use Compose to build a Docker image? - -Yes, you can use Docker Compose to build Docker images. Docker Compose is a -tool for defining and running multi-container applications. Even if your -application isn't a multi-container application, Docker Compose can make it -easier to run by defining all the `docker run` options in a file. - -To use Compose, you need a `compose.yaml` file. In this file, you can specify -the build context and Dockerfile for each service. When you run the command -`docker compose up --build`, Docker Compose will build the images for each -service and then start the containers. - -For more information on building Docker images using Compose, see the [Compose -Build Specification](/compose/compose-file/build/). - -### What is the difference between Docker Compose and Dockerfile? - -A Dockerfile provides instructions to build a container image while a Compose -file defines your running containers. Quite often, a Compose file references a -Dockerfile to build an image to use for a particular service. - -### What is the difference between the `docker compose up` and `docker compose run` commands? - -The `docker compose up` command creates and starts all your services. It's -perfect for launching your development environment or running the entire -application. The `docker compose run` command focuses on individual services. -It starts a specified service along with its dependencies, allowing you to run -tests or perform one-off tasks within that container. - -<div id="compose-lp-survey-anchor"></div> diff --git a/content/guides/docker-compose/setup.md b/content/guides/docker-compose/setup.md deleted file mode 100644 index 15d168b0d0dd..000000000000 --- a/content/guides/docker-compose/setup.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Demo: set up and use Docker Compose" -description: Learn how to get started with Docker Compose. -keywords: docker compose, getting started, multi-container, demo, orchestration -weight: 20 ---- - -This Docker Compose demo shows how to orchestrate a multi-container application -environment, streamlining development and deployment processes. - -- Compare Docker Compose to the `docker run` command -- Configure a multi-container web app using a Compose file -- Run a multi-container web app using one command - -{{< youtube-embed P5RBKmOLPH4 >}} - -<div id="compose-lp-survey-anchor"></div> diff --git a/content/guides/docker-compose/why.md b/content/guides/docker-compose/why.md deleted file mode 100644 index f3ef90668a84..000000000000 --- a/content/guides/docker-compose/why.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Why Docker Compose? -description: Learn how Docker Compose can help you simplify app development. -keywords: docker compose, multi-container, yaml, services, orchestration, application -weight: 10 ---- - -Docker Compose is an essential tool for defining and running multi-container -Docker applications. Docker Compose simplifies the Docker experience, making it -easier for developers to create, manage, and deploy applications by using YAML -files to configure application services. - -Docker Compose provides several benefits: - -- Lets you define multi-container applications in a single YAML file. -- Ensures consistent environments across development, testing, and production. -- Manages the startup and linking of multiple containers effortlessly. -- Streamlines development workflows and reduces setup time. -- Ensures that each service runs in its own container, avoiding conflicts. - -{{< youtube-embed 2EqarOM2V4U >}} - -<div id="compose-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/_index.md b/content/guides/docker-scout/_index.md deleted file mode 100644 index a8bbb683ebeb..000000000000 --- a/content/guides/docker-scout/_index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Securing your software supply chain with Docker Scout -linkTitle: Docker Scout -summary: | - Enhance container security by automating vulnerability detection and - remediation. -description: | - Learn how to use Docker Scout to enhance container security by automating - vulnerability detection and remediation, ensuring compliance, and protecting - your development workflow. -keywords: docker scout, container security, vulnerability scanning, sbom, supply chain, remediation -tags: [product-demo] -aliases: - - /learning-paths/docker-scout/ -params: - image: images/learning-paths/scout.png - time: 20 minutes - resource_links: - - title: Docker Scout overview - url: /scout/ - - title: Docker Scout quickstart - url: /scout/quickstart/ - - title: Install Docker Scout - url: /scout/install/ ---- - -When container images are insecure, significant risks can arise. Around 60% of -organizations have reported experiencing at least one security breach or -vulnerability incident within a year, [resulting in operational -disruption][CSA]. These incidents often result in considerable downtime, with -44% of affected companies experiencing over an hour of downtime per event. The -financial impact is substantial, with [the average data breach cost reaching -$4.45 million][IBM]. This highlights the critical importance of maintaining -robust container security measures. - -Docker Scout enhances container security by providing automated vulnerability -detection and remediation, addressing insecure container images, and ensuring -compliance with security standards. - -[CSA]: https://cloudsecurityalliance.org/blog/2023/09/21/2023-global-cloud-threat-report-cloud-attacks-are-lightning-fast -[IBM]: https://www.ibm.com/reports/data-breach - -## What you'll learn - -- Define Secure Software Supply Chain (SSSC) -- Review SBOMs and how to use them -- Detect and monitor vulnerabilities - -## Tools integration - -Works well with Docker Desktop, GitHub Actions, Jenkins, Kubernetes, and -other CI solutions. - -## Who’s this for? - -- DevOps engineers who need to integrate automated security checks into CI/CD - pipelines to enhance the security and efficiency of their workflows. -- Developers who want to use Docker Scout to identify and remediate - vulnerabilities early in the development process, ensuring the production of - secure container images. -- Security professionals who must enforce security compliance, conduct - vulnerability assessments, and ensure the overall security of containerized - applications. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/attestations.md b/content/guides/docker-scout/attestations.md deleted file mode 100644 index fb060e703363..000000000000 --- a/content/guides/docker-scout/attestations.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Attestations -keywords: build, attestations, sbom, provenance, metadata -description: | - Introduction to SBOM and provenance attestations with Docker Build, - what they are, and why they exist -weight: 50 ---- - -{{< youtube-embed qOzcycbTs4o >}} - -[Build attestations](/manuals/build/metadata/attestations/_index.md) give you -detailed information about how an image was built and what it contains. These -attestations, generated by BuildKit during build-time, attach to the final -image as metadata, allowing you to inspect an image to see its origin, creator, -and contents. This information helps you make informed decisions about the -security and impact of the image on your supply chain. - -Docker Scout uses these attestations to evaluate the image's security and -supply chain posture, and to provide remediation recommendations for issues. If -issues are detected, such as missing or outdated attestations, Docker Scout can -guide you on how to add or update them, ensuring compliance and improving -visibility into the image's security status. - -There are two key types of attestations: - -- SBOM, which lists the software artifacts within the image. -- Provenance, which details how the image was built. - -You can create attestations by using `docker buildx build` with the -`--provenance` and `--sbom` flags. Attestations attach to the image index, -allowing you to inspect them without pulling the entire image. Docker Scout -leverages this metadata to give you more precise recommendations and better -control over your image's security. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/common-questions.md b/content/guides/docker-scout/common-questions.md deleted file mode 100644 index 4285d099d839..000000000000 --- a/content/guides/docker-scout/common-questions.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Common challenges and questions -description: Explore common challenges and questions related to Docker Scout. -keywords: docker scout, faq, container security, vulnerability scanning, troubleshooting ---- - -<!-- vale Docker.HeadingLength = NO --> - -### How is Docker Scout different from other security tools? - -Docker Scout takes a broader approach to container security compared to -third-party security tools. Third-party security tools, if they offer -remediation guidance at all, miss the mark on their limited scope of -application security posture within the software supply chain, and often -limited guidance when it comes to suggested fixes. Such tools have either -limitations on runtime monitoring or no runtime protection at all. When they do -offer runtime monitoring, it’s limited in its adherence to key policies. -Third-party security tools offer a limited scope of policy evaluation for -Docker-specific builds. By focusing on the entire software supply chain, -providing actionable guidance, and offering comprehensive runtime protection -with strong policy enforcement, Docker Scout goes beyond just identifying -vulnerabilities in your containers. It helps you build secure applications from -the ground up. - -### Can I use Docker Scout with external registries other than Docker Hub? - -You can use Scout with registries other than Docker Hub. Integrating Docker Scout -with third-party container registries enables Docker Scout to run image -analysis on those repositories so that you can get insights into the -composition of those images even if they aren't hosted on Docker Hub. - -The following container registry integrations are available: - -- Artifactory -- Amazon Elastic Container Registry -- Azure Container Registry - -Learn more about configuring Scout with your registries in [Integrating Docker Scout with third-party registries](/scout/integrations/#container-registries). - -### Does Docker Scout CLI come by default with Docker Desktop? - -Yes, the Docker Scout CLI plugin comes pre-installed with Docker Desktop. - -### Is it possible to run `docker scout` commands on a Linux system without Docker Desktop? - -If you run Docker Engine without Docker Desktop, Docker Scout doesn't come -pre-installed, but you can [install it as a standalone binary](/scout/install/). - -### How is Docker Scout using an SBOM? - -An SBOM, or software bill of materials, is a list of ingredients that make up -software components. [Docker Scout uses SBOMs](/scout/concepts/sbom/) to -determine the components that are used in a Docker image. When you analyze an -image, Docker Scout will either use the SBOM that is attached to the image (as -an attestation), or generate an SBOM on the fly by analyzing the contents of -the image. - -The SBOM is cross-referenced with the advisory database to determine if any of -the components in the image have known vulnerabilities. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/demo.md b/content/guides/docker-scout/demo.md deleted file mode 100644 index fb76b396aab9..000000000000 --- a/content/guides/docker-scout/demo.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Docker Scout demo -linkTitle: Demo -description: Learn about Docker Scout's powerful features for enhanced supply chain security. -keywords: docker scout, demo, supply chain, vulnerability scanning, container security -weight: 20 ---- - -{{< youtube-embed "TkLwJ0p46W8" >}} - -Docker Scout has powerful features for enhancing containerized application -security and ensuring a robust software supply chain. - -- Define vulnerability remediation -- Discuss why remediation is essential to maintain the security and integrity - of containerized applications -- Discuss common vulnerabilities -- Implement remediation techniques: updating base images, applying patches, - removing unnecessary packages -- Verify and validate remediation efforts using Docker Scout - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/remediation.md b/content/guides/docker-scout/remediation.md deleted file mode 100644 index e485c9cd3cf6..000000000000 --- a/content/guides/docker-scout/remediation.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Remediation -description: Learn how Docker Scout can help you improve your software quality automatically, using remediation -keywords: scout, supply chain, security, remediation, automation -weight: 60 ---- - -{{< youtube-embed jM9zLBf8M-8 >}} - -Docker Scout's [remediation feature](/manuals/scout/policy/remediation.md) -helps you address supply chain and security issues by offering tailored -recommendations based on policy evaluations. These recommendations guide you in -improving policy compliance or enhancing image metadata, allowing Docker Scout -to perform more accurate evaluations in the future. - -You can use this feature to ensure that your base images are up-to-date and -that your supply chain attestations are complete. When a violation occurs, -Docker Scout provides recommended fixes, such as updating your base image or -adding missing attestations. If there isn’t enough information to determine -compliance, Docker Scout suggests actions to help resolve the issue. - -In the Docker Scout Dashboard, you can view and act on these recommendations by -reviewing violations or compliance uncertainties. With integrations like -GitHub, you can even automate updates, directly fixing issues from the -dashboard. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/s3c.md b/content/guides/docker-scout/s3c.md deleted file mode 100644 index df6eac67a7f2..000000000000 --- a/content/guides/docker-scout/s3c.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Software supply chain security -description: Learn about software supply chain security (S3C), what it means, and why it is important. -keywords: docker scout, secure, software, supply, chain, security, sssc, sscs, s3c -aliases: - - /scout/concepts/s3c/ -weight: 30 ---- - -{{< youtube-embed YzNK6E7APv0 >}} - -The term "software supply chain" refers to the end-to-end process of developing -and delivering software, from the development to deployment and maintenance. -Software supply chain security, or "S3C" for short, is the practice for -protecting the components and processes of the supply chain. - -S3C is a fundamental change in how organizations approach software security. -Traditionally in the software industry, security and compliance has been mostly -an afterthought, left to the software delivery or release phase. With S3C, -security is integrated into the entire software development lifecycle, from the -inner loop of development and testing, to the outer loop of shipping and -monitoring. - -Following industry best practices for software supply chain conduct is -important because it helps organizations protect their software from security -threats, compliance risks, and other vulnerabilities. Implementing a software -supply chain security framework improves visibility, collaboration, and -traceability of a project across stakeholders. This helps organizations detect, -respond to, and remediate threats more effectively. - -## Securing the software supply chain - -Building a secure software supply chain involves several key steps, such as: - -- Identify the software components and dependencies you use to build and run - your applications. -- Automate security testing throughout the software development lifecycle. -- Monitor your software supply chain for security threats. -- Implement security policies that govern how software is built, and the - components it contains. - -Managing the software supply chain is a complex task, especially in the modern -day where software is built using multiple components from different sources. -Organizations need to have a clear understanding of the software components -they use, and the security risks associated with them. - -## How Docker Scout is different - -Docker Scout is a platform designed to help organizations secure their software -supply chain. It provides tools and services for identifying and managing -software assets and policies, and automated remediation of security threats. - -Unlike traditional security tools that focus on scheduled, point-in-time scans -at specific stages in the software development lifecycle, Docker Scout uses a -modern event-driven model that spans the entire software supply chain. This -means that when a new vulnerability affecting your images is disclosed, your -updated risk assessment is available within seconds, and earlier in the -development process. - -Docker Scout works by analyzing the composition of your images to create a -Software Bill of Materials (SBOM). The SBOM is cross-referenced against the -security advisories to identify CVEs that affect your images. Docker Scout -integrates with [over 20 different security -advisories](/manuals/scout/deep-dive/advisory-db-sources.md), and updates its -vulnerability database in real-time. This ensures that your security posture is -represented using the latest available information. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/sbom.md b/content/guides/docker-scout/sbom.md deleted file mode 100644 index c7c6e2fa8a3a..000000000000 --- a/content/guides/docker-scout/sbom.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Software Bill of Materials -description: Learn about Software Bill of Materials (SBOM) and how Docker Scout uses it. -keywords: scout, sbom, software bill of materials, analysis, composition -aliases: - - /scout/concepts/sbom/ -weight: 40 ---- - -{{< youtube-embed PbS4y7C7h4A >}} - -A Bill of Materials (BOM) is a list of materials, parts, and the quantities of -each needed to manufacture a product. For example, a BOM for a computer might -list the motherboard, CPU, RAM, power supply, storage devices, case, and other -components, along with the quantities of each that are needed to build the -computer. - -A Software Bill of Materials (SBOM) is a list of all the components that make -up a piece of software. This includes open source and third-party components, -as well as any custom code that has been written for the software. An SBOM is -similar to a BOM for a physical product, but for software. - -In the context of software supply chain security, SBOMs can help with -identifying and mitigating security and compliance risks in software. By -knowing exactly what components are used in a piece of software, you can -quickly identify and patch vulnerabilities in your components, or determine if -a component is licensed in a way that is incompatible with your project. - -## Contents of an SBOM - -An SBOM typically includes the following information: - -- The name of the software, such as the name of a library or framework, that - the SBOM describes. -- The version of the software. -- The license under which the software is distributed. -- A list of other components that the software depends on. - -## How Docker Scout uses SBOMs - -Docker Scout uses SBOMs to determine the components that are used in a Docker -image. When you analyze an image, Docker Scout will either use the SBOM that is -attached to the image as an attestation, or it will generate an SBOM on the fly -by analyzing the contents of the image. - -The SBOM is cross-referenced with the [advisory database](/manuals/scout/deep-dive/advisory-db-sources.md) -to determine if any of the components in the image have known vulnerabilities. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/docker-scout/why.md b/content/guides/docker-scout/why.md deleted file mode 100644 index 227702645b1c..000000000000 --- a/content/guides/docker-scout/why.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Why Docker Scout? -description: Learn how Docker Scout can help you secure your supply chain. -keywords: docker scout, supply chain security, vulnerability detection, sbom, container security -weight: 10 ---- - -{{< youtube-embed "-omsQ7Uqyc4" >}} - -Organizations face significant challenges from data breaches, -including financial losses, operational disruptions, and long-term damage to -brand reputation and customer trust. Docker Scout addresses critical problems -such as identifying insecure container images, preventing security breaches, -and reducing the risk of operational downtime due to vulnerabilities. - -Docker Scout provides several benefits: - -- Secure and trusted content -- A system of record for your Software Development Lifecycle (SDLC) -- Continuous security posture improvement - -Docker Scout offers automated vulnerability detection and remediation, helping -organizations identify and fix security issues in container images early in the -development process. It also integrates with popular development tools like -Docker Desktop and GitHub Actions, providing seamless security management and -compliance checks within existing workflows. - -<div id="scout-lp-survey-anchor"></div> diff --git a/content/guides/dotnet.md b/content/guides/dotnet.md new file mode 100644 index 000000000000..e663e8d8f65a --- /dev/null +++ b/content/guides/dotnet.md @@ -0,0 +1,915 @@ +--- +title: .NET language-specific guide +linkTitle: C# (.NET) +description: Containerize and develop .NET apps using Docker +summary: | + Learn how to containerize .NET applications using Docker. +keywords: getting started, .net +aliases: + - /language/dotnet/ + - /guides/language/dotnet/ + - /language/dotnet/develop/ + - /language/dotnet/run-tests/ + - /language/dotnet/configure-ci-cd/ + - /language/dotnet/deploy/ + - /guides/dotnet/configure-ci-cd/ + - /guides/dotnet/containerize/ + - /guides/dotnet/deploy/ + - /guides/dotnet/develop/ + - /guides/dotnet/run-tests/ +params: + tags: [languages] + time: 20 minutes + toc_min: 1 + toc_max: 2 +--- + +The .NET getting started guide teaches you how to create a containerized .NET application using Docker. In this guide, you'll learn how to: + +- Containerize and run a .NET application +- Set up a local environment to develop a .NET application using containers +- Run tests for a .NET application using containers + +After completing the .NET getting started modules, you should be able to containerize your own .NET application based on the examples and instructions provided in this guide. + +Start by containerizing an existing .NET application. + +## Containerize a .NET application + +### Prerequisites + +- You have installed the latest version of [Docker + Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this + section use a command-line based git client, but you can use any client. + +### Overview + +This section walks you through containerizing and running a .NET +application. + +### Get the sample applications + +In this guide, you will use a pre-built .NET application. The application is +similar to the application built in the Docker Blog article, [Building a +Multi-Container .NET App Using Docker +Desktop](https://www.docker.com/blog/building-multi-container-net-app-using-docker-desktop/). + +Open a terminal, change directory to a directory that you want to work in, and +run the following command to clone the repository. + +```console +$ git clone https://github.com/docker/docker-dotnet-sample +``` + +### Create Docker assets + +Now that you have an application, you can create the necessary Docker assets to containerize it. You can choose between using the official .NET images or Docker Hardened Images (DHI). + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHI images are recommended for better security—they are designed to reduce vulnerabilities and simplify compliance. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) for .NET are available in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/aspnetcore). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the .NET SDK DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/dotnet:10-sdk + ``` + +3. Pull the ASP.NET Core runtime DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/aspnetcore:10 + ``` + +Create the following files in your `docker-dotnet-sample` directory. + +```dockerfile {collapse=true,title=Dockerfile} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM dhi.io/aspnetcore:10 AS final +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +> [!NOTE] +> +> DHI runtime images already run as a non-root user (`nonroot`, UID 65532), so there's no need to create a user or specify `USER` in your Dockerfile. This reduces the attack surface and simplifies your configuration. + +```yaml {collapse=true,title=compose.yaml} +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + target: final + ports: + - 8080:8080 + +# The commented out section below is an example of how to define a PostgreSQL +# database that your application can use. `depends_on` tells Docker Compose to +# start the database before your application. The `db-data` volume persists the +# database data between container restarts. The `db-password` secret is used +# to set the database password. You must create `db/password.txt` and add +# a password of your choosing to it before running `docker compose up`. +# depends_on: +# db: +# condition: service_healthy +# db: +# image: postgres +# restart: always +# user: postgres +# secrets: +# - db-password +# volumes: +# - db-data:/var/lib/postgresql/data +# environment: +# - POSTGRES_DB=example +# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password +# expose: +# - 5432 +# healthcheck: +# test: [ "CMD", "pg_isready" ] +# interval: 10s +# timeout: 5s +# retries: 5 +# volumes: +# db-data: +# secrets: +# db-password: +# file: db/password.txt +``` + +```text {collapse=true,title=".dockerignore"} +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + +Create the following files in your `docker-dotnet-sample` directory. + +```dockerfile {collapse=true,title=Dockerfile} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final +WORKDIR /app +COPY --from=build /app . +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +```yaml {collapse=true,title=compose.yaml} +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + target: final + ports: + - 8080:8080 + +# The commented out section below is an example of how to define a PostgreSQL +# database that your application can use. `depends_on` tells Docker Compose to +# start the database before your application. The `db-data` volume persists the +# database data between container restarts. The `db-password` secret is used +# to set the database password. You must create `db/password.txt` and add +# a password of your choosing to it before running `docker compose up`. +# depends_on: +# db: +# condition: service_healthy +# db: +# image: postgres +# restart: always +# user: postgres +# secrets: +# - db-password +# volumes: +# - db-data:/var/lib/postgresql/data +# environment: +# - POSTGRES_DB=example +# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password +# expose: +# - 5432 +# healthcheck: +# test: [ "CMD", "pg_isready" ] +# interval: 10s +# timeout: 5s +# retries: 5 +# volumes: +# db-data: +# secrets: +# db-password: +# file: db/password.txt +``` + +```text {collapse=true,title=".dockerignore"} +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /tab >}} +{{< /tabs >}} + +You should now have the following contents in your `docker-dotnet-sample` +directory. + +```text +├── docker-dotnet-sample/ +│ ├── .git/ +│ ├── src/ +│ ├── .dockerignore +│ ├── compose.yaml +│ ├── Dockerfile +│ └── README.md +``` + +To learn more about the files, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `docker-dotnet-sample` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-dotnet-sample` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for .NET development + +### Prerequisites + +Complete [Containerize a .NET application](#containerize-a-net-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Adding a local database and persisting data +- Configuring Compose to automatically update your running Compose services as you edit and save your code +- Creating a development container that contains the .NET Core SDK tools and dependencies + +### Update the application + +This section uses a different branch of the `docker-dotnet-sample` repository +that contains an updated .NET application. The updated application is on the +`add-db` branch of the repository you cloned in [Containerize a .NET +application](#containerize-a-net-application). + +To get the updated code, you need to checkout the `add-db` branch. For the changes you made in [Containerize a .NET application](#containerize-a-net-application), for this section, you can stash them. In a terminal, run the following commands in the `docker-dotnet-sample` directory. + +1. Stash any previous changes. + + ```console + $ git stash -u + ``` + +2. Check out the new branch with the updated application. + + ```console + $ git checkout add-db + ``` + +In the `add-db` branch, only the .NET application has been updated. None of the Docker assets have been updated yet. + +You should now have the following in your `docker-dotnet-sample` directory. + +```text +├── docker-dotnet-sample/ +│ ├── .git/ +│ ├── src/ +│ │ ├── Data/ +│ │ ├── Models/ +│ │ ├── Pages/ +│ │ ├── Properties/ +│ │ ├── wwwroot/ +│ │ ├── appsettings.Development.json +│ │ ├── appsettings.json +│ │ ├── myWebApp.csproj +│ │ └── Program.cs +│ ├── tests/ +│ │ ├── tests.csproj +│ │ ├── UnitTest1.cs +│ │ └── Usings.cs +│ ├── .dockerignore +│ ├── .gitignore +│ ├── compose.yaml +│ ├── Dockerfile +│ └── README.md +``` + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. + +Open the `compose.yaml` file in an IDE or text editor. You'll notice it +already contains commented-out instructions for a PostgreSQL database and volume. + +Open `docker-dotnet-sample/src/appsettings.json` in an IDE or text editor. You'll +notice the connection string with all the database information. The +`compose.yaml` already contains this information, but it's commented out. +Uncomment the database instructions in the `compose.yaml` file. + +The following is the updated `compose.yaml` file. + +```yaml {hl_lines="8-33"} +services: + server: + build: + context: . + target: final + ports: + - 8080:8080 + depends_on: + db: + condition: service_healthy + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Before you run the application using Compose, notice that this Compose file uses +`secrets` and specifies a `password.txt` file to hold the database's password. +You must create this file as it's not included in the source repository. + +In the `docker-dotnet-sample` directory, create a new directory named `db` and +inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file. + +```text +example +``` + +Save and close the `password.txt` file. + +You should now have the following in your `docker-dotnet-sample` directory. + +```text +├── docker-dotnet-sample/ +│ ├── .git/ +│ ├── db/ +│ │ └── password.txt +│ ├── src/ +│ ├── tests/ +│ ├── .dockerignore +│ ├── .gitignore +│ ├── compose.yaml +│ ├── Dockerfile +│ └── README.md +``` + +Run the following command to start your application. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application with the text `Student name is`. + +The application doesn't display a name because the database is empty. For this application, you need to access the database and then add records. + +### Add records to the database + +For the sample application, you must access the database directly to create sample records. + +You can run commands inside the database container using the `docker exec` +command. Before running that command, you must get the ID of the database +container. Open a new terminal window and run the following command to list all +your running containers. + +```console +$ docker container ls +``` + +You should see output like the following. + +```console +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +cb36e310aa7e docker-dotnet-sample-server "dotnet myWebApp.dll" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-dotnet-sample-server-1 +39fdcf0aff7b postgres:18 "docker-entrypoint.s…" About a minute ago Up About a minute (healthy) 5432/tcp docker-dotnet-sample-db-1 +``` + +In the previous example, the container ID is `39fdcf0aff7b`. Run the following command to connect to the postgres database in the container. Replace the container ID with your own container ID. + +```console +$ docker exec -it 39fdcf0aff7b psql -d example -U postgres +``` + +And finally, insert a record into the database. + +```console +example=# INSERT INTO "Students" ("ID", "LastName", "FirstMidName", "EnrollmentDate") VALUES (DEFAULT, 'Whale', 'Moby', '2013-03-20'); +``` + +You should see output like the following. + +```console +INSERT 0 1 +``` + +Close the database connection and exit the container shell by running `exit`. + +```console +example=# exit +``` + +### Verify that data persists in the database + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application with the text `Student name is Moby Whale`. + +Press `ctrl+c` in the terminal to stop your application. + +In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again. + +```console +$ docker compose rm +$ docker compose up --build +``` + +Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the student name persisted, even after the containers were removed and ran again. + +Press `ctrl+c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file. + +```yaml {hl_lines="11-14"} +services: + server: + build: + context: . + target: final + ports: + - 8080:8080 + depends_on: + db: + condition: service_healthy + develop: + watch: + - action: rebuild + path: . + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Open a browser and verify that the application is running at [http://localhost:8080](http://localhost:8080). + +Any changes to the application's source files on your local machine will now be +immediately reflected in the running container. + +Open `docker-dotnet-sample/src/Pages/Index.cshtml` in an IDE or text editor and update the student name text on line 13 from `Student name is` to `Student name:`. + +```diff +- <p>Student name is @Model.StudentName</p> ++ <p>Student name: @Model.StudentName</p> +``` + +Save the changes to `Index.cshtml` and then wait a few seconds for the application to rebuild. Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the updated text appears. + +Press `ctrl+c` in the terminal to stop your application. + +### Create a development container + +At this point, when you run your containerized application, it's using the .NET runtime image. While this small image is good for production, it lacks the SDK tools and dependencies you may need when developing. Also, during development, you may not need to run `dotnet publish`. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](/manuals/build/building/multi-stage.md). + +Add a new development stage to your Dockerfile and update your `compose.yaml` file to use this stage for local development. + +The following is the updated Dockerfile. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +```Dockerfile {hl_lines="10-13"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM dhi.io/dotnet:10-sdk AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM dhi.io/aspnetcore:10 AS final +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + +```Dockerfile {hl_lines="10-13"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final +WORKDIR /app +COPY --from=build /app . +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< /tabs >}} + +The following is the updated `compose.yaml` file. + +```yaml {hl_lines=[5,15,16]} +services: + server: + build: + context: . + target: development + ports: + - 8080:8080 + depends_on: + db: + condition: service_healthy + develop: + watch: + - action: rebuild + path: . + environment: + - ASPNETCORE_ENVIRONMENT=Development + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +Your containerized application will now use the SDK image (either `dhi.io/dotnet:10-sdk` for DHI or `mcr.microsoft.com/dotnet/sdk:10.0-alpine` for official images), which includes development tools like `dotnet test`. Continue to the next section to learn how you can run `dotnet test`. + +## Run .NET tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize a .NET application](#containerize-a-net-application). + +### Overview + +Testing is an essential part of modern software development. Testing can mean a +lot of things to different development teams. There are unit tests, integration +tests and end-to-end testing. In this guide you take a look at running your unit +tests in Docker when developing and when building. + +### Run tests when developing locally + +The sample application already has an xUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests. + +Run the following command in the `docker-dotnet-sample` directory to run the tests inside a container. + +```console +$ docker compose run --build --rm server dotnet test /source/tests +``` + +You should see output that contains the following. + +```console +Starting test execution, please wait... +A total of 1 test files matched the specified pattern. + +Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) +``` + +To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). + +### Run tests when building + +To run your tests when building, you need to update your Dockerfile. You can create a new test stage that runs the tests, or run the tests in the existing build stage. For this guide, update the Dockerfile to run the tests in the build stage. + +The following is the updated Dockerfile. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +```dockerfile {hl_lines="9"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app +RUN dotnet test /source/tests + +FROM dhi.io/dotnet:10-sdk AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM dhi.io/aspnetcore:10 AS final +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + +```dockerfile {hl_lines="9"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app +RUN dotnet test /source/tests + +FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final +WORKDIR /app +COPY --from=build /app . +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< /tabs >}} + +Run the following command to build an image using the build stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target build` to target the build stage. + +```console +$ docker build -t dotnet-docker-image-test --progress=plain --no-cache --target build . +``` + +You should see output containing the following. + +```console +#11 [build 5/5] RUN dotnet test /source/tests +#11 1.564 Determining projects to restore... +#11 3.421 Restored /source/src/myWebApp.csproj (in 1.02 sec). +#11 19.42 Restored /source/tests/tests.csproj (in 17.05 sec). +#11 27.91 myWebApp -> /source/src/bin/Debug/net10.0/myWebApp.dll +#11 28.47 tests -> /source/tests/bin/Debug/net10.0/tests.dll +#11 28.49 Test run for /source/tests/bin/Debug/net10.0/tests.dll (.NETCoreApp,Version=v10.0) +#11 28.67 Microsoft (R) Test Execution Command Line Tool Version 17.3.3 (x64) +#11 28.67 Copyright (c) Microsoft Corporation. All rights reserved. +#11 28.68 +#11 28.97 Starting test execution, please wait... +#11 29.03 A total of 1 test files matched the specified pattern. +#11 32.07 +#11 32.08 Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) +#11 DONE 32.2s +``` + +### Summary + +In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image. + +Related information: + +- [docker compose run](/reference/cli/docker/compose/run/) diff --git a/content/guides/dotnet/_index.md b/content/guides/dotnet/_index.md deleted file mode 100644 index 849c17f2b636..000000000000 --- a/content/guides/dotnet/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: .NET language-specific guide -linkTitle: C# (.NET) -description: Containerize and develop .NET apps using Docker -summary: | - Learn how to containerize .NET applications using Docker. -keywords: getting started, .net -aliases: - - /language/dotnet/ - - /guides/language/dotnet/ -languages: [c-sharp] -params: - time: 20 minutes - toc_min: 1 - toc_max: 2 ---- - -The .NET getting started guide teaches you how to create a containerized .NET application using Docker. In this guide, you'll learn how to: - -- Containerize and run a .NET application -- Set up a local environment to develop a .NET application using containers -- Run tests for a .NET application using containers -- Configure a CI/CD pipeline for a containerized .NET application using GitHub Actions -- Deploy your containerized application locally to Kubernetes to test and debug your deployment - -After completing the .NET getting started modules, you should be able to containerize your own .NET application based on the examples and instructions provided in this guide. - -Start by containerizing an existing .NET application. diff --git a/content/guides/dotnet/configure-ci-cd.md b/content/guides/dotnet/configure-ci-cd.md deleted file mode 100644 index b5065330ef9f..000000000000 --- a/content/guides/dotnet/configure-ci-cd.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Configure CI/CD for your .NET application -linkTitle: Configure CI/CD -weight: 40 -keywords: .net, CI/CD -description: Learn how to Configure CI/CD for your .NET application -aliases: - - /language/dotnet/configure-ci-cd/ - - /guides/language/dotnet/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a .NET application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. In your local repository on your machine, run the following command to rename - the branch to main. - - ```console - $ git branch -M main - ``` - -8. Run the following commands to stage, commit, and then push your local - repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my first commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and test - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - target: build - load: true - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - target: final - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/dotnet/containerize.md b/content/guides/dotnet/containerize.md deleted file mode 100644 index d5126324f1dd..000000000000 --- a/content/guides/dotnet/containerize.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Containerize a .NET application -linkTitle: Containerize your app -weight: 10 -keywords: .net, containerize, initialize -description: Learn how to containerize an ASP.NET application. -aliases: -- /language/dotnet/build-images/ -- /language/dotnet/run-containers/ -- /language/dotnet/containerize/ -- /guides/language/dotnet/containerize/ ---- - -## Prerequisites - -* You have installed the latest version of [Docker - Desktop](/get-started/get-docker.md). -* You have a [git client](https://git-scm.com/downloads). The examples in this - section use a command-line based git client, but you can use any client. - -## Overview - -This section walks you through containerizing and running a .NET -application. - -## Get the sample applications - -In this guide, you will use a pre-built .NET application. The application is -similar to the application built in the Docker Blog article, [Building a -Multi-Container .NET App Using Docker -Desktop](https://www.docker.com/blog/building-multi-container-net-app-using-docker-desktop/). - -Open a terminal, change directory to a directory that you want to work in, and -run the following command to clone the repository. - -```console -$ git clone https://github.com/docker/docker-dotnet-sample -``` - -## Create Docker assets - -Now that you have an application, you can create the necessary Docker assets to containerize it. You can choose between using the official .NET images or Docker Hardened Images (DHI). - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHI images are recommended for better security—they are designed to reduce vulnerabilities and simplify compliance. - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) for .NET are available in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/aspnetcore). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the .NET SDK DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/dotnet:10-sdk - ``` - -3. Pull the ASP.NET Core runtime DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/aspnetcore:10 - ``` - -Create the following files in your `docker-dotnet-sample` directory. - -```dockerfile {collapse=true,title=Dockerfile} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app - -FROM dhi.io/aspnetcore:10 AS final -WORKDIR /app -COPY --from=build /app . -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -> [!NOTE] -> -> DHI runtime images already run as a non-root user (`nonroot`, UID 65532), so there's no need to create a user or specify `USER` in your Dockerfile. This reduces the attack surface and simplifies your configuration. - -```yaml {collapse=true,title=compose.yaml} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - target: final - ports: - - 8080:8080 - -# The commented out section below is an example of how to define a PostgreSQL -# database that your application can use. `depends_on` tells Docker Compose to -# start the database before your application. The `db-data` volume persists the -# database data between container restarts. The `db-password` secret is used -# to set the database password. You must create `db/password.txt` and add -# a password of your choosing to it before running `docker compose up`. -# depends_on: -# db: -# condition: service_healthy -# db: -# image: postgres -# restart: always -# user: postgres -# secrets: -# - db-password -# volumes: -# - db-data:/var/lib/postgresql/data -# environment: -# - POSTGRES_DB=example -# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password -# expose: -# - 5432 -# healthcheck: -# test: [ "CMD", "pg_isready" ] -# interval: 10s -# timeout: 5s -# retries: 5 -# volumes: -# db-data: -# secrets: -# db-password: -# file: db/password.txt -``` - -```text {collapse=true,title=".dockerignore"} -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` - -{{< /tab >}} -{{< tab name="Using the official .NET 10 image" >}} - -Create the following files in your `docker-dotnet-sample` directory. - -```dockerfile {collapse=true,title=Dockerfile} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app - -FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final -WORKDIR /app -COPY --from=build /app . -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -```yaml {collapse=true,title=compose.yaml} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - target: final - ports: - - 8080:8080 - -# The commented out section below is an example of how to define a PostgreSQL -# database that your application can use. `depends_on` tells Docker Compose to -# start the database before your application. The `db-data` volume persists the -# database data between container restarts. The `db-password` secret is used -# to set the database password. You must create `db/password.txt` and add -# a password of your choosing to it before running `docker compose up`. -# depends_on: -# db: -# condition: service_healthy -# db: -# image: postgres -# restart: always -# user: postgres -# secrets: -# - db-password -# volumes: -# - db-data:/var/lib/postgresql/data -# environment: -# - POSTGRES_DB=example -# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password -# expose: -# - 5432 -# healthcheck: -# test: [ "CMD", "pg_isready" ] -# interval: 10s -# timeout: 5s -# retries: 5 -# volumes: -# db-data: -# secrets: -# db-password: -# file: db/password.txt -``` - -```text {collapse=true,title=".dockerignore"} -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` - -{{< /tab >}} -{{< /tabs >}} - -You should now have the following contents in your `docker-dotnet-sample` -directory. - -```text -├── docker-dotnet-sample/ -│ ├── .git/ -│ ├── src/ -│ ├── .dockerignore -│ ├── compose.yaml -│ ├── Dockerfile -│ └── README.md -``` - -To learn more about the files, see the following: - - [Dockerfile](/reference/dockerfile.md) - - [.dockerignore](/reference/dockerfile.md#dockerignore-file) - - [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `docker-dotnet-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-dotnet-sample` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run your .NET -application using Docker. - -Related information: - - [Dockerfile reference](/reference/dockerfile.md) - - [.dockerignore file reference](/reference/dockerfile.md#dockerignore-file) - - [Docker Compose overview](/manuals/compose/_index.md) - - [Docker Hardened Images](/dhi/) - -## Next steps - -In the next section, you'll learn how you can develop your application using -Docker containers. diff --git a/content/guides/dotnet/deploy.md b/content/guides/dotnet/deploy.md deleted file mode 100644 index 0f4089ab88c5..000000000000 --- a/content/guides/dotnet/deploy.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Test your .NET deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, .net, local, development -description: Learn how to deploy your application -aliases: - - /language/dotnet/deploy/ - - /guides/language/dotnet/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize - a .NET application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker - Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your -application to a fully-featured Kubernetes environment on your development -machine. This allows you to test and debug your workloads on Kubernetes locally -before deploying. - -## Create a Kubernetes YAML file - -In your `docker-dotnet-sample` directory, create a file named -`docker-dotnet-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your .NET application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: server - name: server - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: server - strategy: {} - template: - metadata: - labels: - service: server - spec: - initContainers: - - name: wait-for-db - image: busybox:1.28 - command: - [ - "sh", - "-c", - 'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;', - ] - containers: - - image: DOCKER_USERNAME/REPO_NAME - name: server - imagePullPolicy: Always - ports: - - containerPort: 8080 - hostPort: 8080 - protocol: TCP - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: db - name: db - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: db - strategy: - type: Recreate - template: - metadata: - labels: - service: db - spec: - containers: - - env: - - name: POSTGRES_DB - value: example - - name: POSTGRES_PASSWORD - value: example - image: postgres:18 - name: db - ports: - - containerPort: 5432 - protocol: TCP - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: server - name: server - namespace: default -spec: - type: NodePort - ports: - - name: "8080" - port: 8080 - targetPort: 8080 - nodePort: 30001 - selector: - service: server -status: - loadBalancer: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: db - name: db - namespace: default -spec: - ports: - - name: "5432" - port: 5432 - targetPort: 5432 - selector: - service: db -status: - loadBalancer: {} -``` - -In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The container is - created from the image built by GitHub Actions in [Configure CI/CD for your - .NET application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 8080 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to the `docker-dotnet-sample` directory - and deploy your application to Kubernetes. - - ```console - $ kubectl apply -f docker-dotnet-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```shell - deployment.apps/db created - service/db created - deployment.apps/server created - service/server created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - db 1/1 1 1 76s - server 1/1 1 1 76s - ``` - - This indicates all of the pods are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - db ClusterIP 10.96.156.90 <none> 5432/TCP 2m8s - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 164m - server NodePort 10.102.94.225 <none> 8080:30001/TCP 2m8s - ``` - - In addition to the default `kubernetes` service, you can see your `server` service and `db` service. The `server` service is accepting traffic on port 30001/TCP. - -3. Open a browser and visit your app at `localhost:30001`. You should see your - application. - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-dotnet-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/dotnet/develop.md b/content/guides/dotnet/develop.md deleted file mode 100644 index b07c522497c8..000000000000 --- a/content/guides/dotnet/develop.md +++ /dev/null @@ -1,425 +0,0 @@ ---- -title: Use containers for .NET development -linkTitle: Develop your app -weight: 20 -keywords: .net, development -description: Learn how to develop your .NET application locally using containers. -aliases: - - /language/dotnet/develop/ - - /guides/language/dotnet/develop/ ---- - -## Prerequisites - -Complete [Containerize a .NET application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Adding a local database and persisting data -- Configuring Compose to automatically update your running Compose services as you edit and save your code -- Creating a development container that contains the .NET Core SDK tools and dependencies - -## Update the application - -This section uses a different branch of the `docker-dotnet-sample` repository -that contains an updated .NET application. The updated application is on the -`add-db` branch of the repository you cloned in [Containerize a .NET -application](containerize.md). - -To get the updated code, you need to checkout the `add-db` branch. For the changes you made in [Containerize a .NET application](containerize.md), for this section, you can stash them. In a terminal, run the following commands in the `docker-dotnet-sample` directory. - -1. Stash any previous changes. - - ```console - $ git stash -u - ``` - -2. Check out the new branch with the updated application. - - ```console - $ git checkout add-db - ``` - -In the `add-db` branch, only the .NET application has been updated. None of the Docker assets have been updated yet. - -You should now have the following in your `docker-dotnet-sample` directory. - -```text -├── docker-dotnet-sample/ -│ ├── .git/ -│ ├── src/ -│ │ ├── Data/ -│ │ ├── Models/ -│ │ ├── Pages/ -│ │ ├── Properties/ -│ │ ├── wwwroot/ -│ │ ├── appsettings.Development.json -│ │ ├── appsettings.json -│ │ ├── myWebApp.csproj -│ │ └── Program.cs -│ ├── tests/ -│ │ ├── tests.csproj -│ │ ├── UnitTest1.cs -│ │ └── Usings.cs -│ ├── .dockerignore -│ ├── .gitignore -│ ├── compose.yaml -│ ├── Dockerfile -│ └── README.md -``` - -## Add a local database and persist data - -You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. - -Open the `compose.yaml` file in an IDE or text editor. You'll notice it -already contains commented-out instructions for a PostgreSQL database and volume. - -Open `docker-dotnet-sample/src/appsettings.json` in an IDE or text editor. You'll -notice the connection string with all the database information. The -`compose.yaml` already contains this information, but it's commented out. -Uncomment the database instructions in the `compose.yaml` file. - -The following is the updated `compose.yaml` file. - -```yaml {hl_lines="8-33"} -services: - server: - build: - context: . - target: final - ports: - - 8080:8080 - depends_on: - db: - condition: service_healthy - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -> [!NOTE] -> -> To learn more about the instructions in the Compose file, see [Compose file -> reference](/reference/compose-file/). - -Before you run the application using Compose, notice that this Compose file uses -`secrets` and specifies a `password.txt` file to hold the database's password. -You must create this file as it's not included in the source repository. - -In the `docker-dotnet-sample` directory, create a new directory named `db` and -inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file. - -```text -example -``` - -Save and close the `password.txt` file. - -You should now have the following in your `docker-dotnet-sample` directory. - -```text -├── docker-dotnet-sample/ -│ ├── .git/ -│ ├── db/ -│ │ └── password.txt -│ ├── src/ -│ ├── tests/ -│ ├── .dockerignore -│ ├── .gitignore -│ ├── compose.yaml -│ ├── Dockerfile -│ └── README.md -``` - -Run the following command to start your application. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application with the text `Student name is`. - -The application doesn't display a name because the database is empty. For this application, you need to access the database and then add records. - -## Add records to the database - -For the sample application, you must access the database directly to create sample records. - -You can run commands inside the database container using the `docker exec` -command. Before running that command, you must get the ID of the database -container. Open a new terminal window and run the following command to list all -your running containers. - -```console -$ docker container ls -``` - -You should see output like the following. - -```console -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -cb36e310aa7e docker-dotnet-sample-server "dotnet myWebApp.dll" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-dotnet-sample-server-1 -39fdcf0aff7b postgres:18 "docker-entrypoint.s…" About a minute ago Up About a minute (healthy) 5432/tcp docker-dotnet-sample-db-1 -``` - -In the previous example, the container ID is `39fdcf0aff7b`. Run the following command to connect to the postgres database in the container. Replace the container ID with your own container ID. - -```console -$ docker exec -it 39fdcf0aff7b psql -d example -U postgres -``` - -And finally, insert a record into the database. - -```console -example=# INSERT INTO "Students" ("ID", "LastName", "FirstMidName", "EnrollmentDate") VALUES (DEFAULT, 'Whale', 'Moby', '2013-03-20'); -``` - -You should see output like the following. - -```console -INSERT 0 1 -``` - -Close the database connection and exit the container shell by running `exit`. - -```console -example=# exit -``` - -## Verify that data persists in the database - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application with the text `Student name is Moby Whale`. - -Press `ctrl+c` in the terminal to stop your application. - -In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again. - -```console -$ docker compose rm -$ docker compose up --build -``` - -Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the student name persisted, even after the containers were removed and ran again. - -Press `ctrl+c` in the terminal to stop your application. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file. - -```yaml {hl_lines="11-14"} -services: - server: - build: - context: . - target: final - ports: - - 8080:8080 - depends_on: - db: - condition: service_healthy - develop: - watch: - - action: rebuild - path: . - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Open a browser and verify that the application is running at [http://localhost:8080](http://localhost:8080). - -Any changes to the application's source files on your local machine will now be -immediately reflected in the running container. - -Open `docker-dotnet-sample/src/Pages/Index.cshtml` in an IDE or text editor and update the student name text on line 13 from `Student name is` to `Student name:`. - -```diff -- <p>Student name is @Model.StudentName</p> -+ <p>Student name: @Model.StudentName</p> -``` - -Save the changes to `Index.cshtml` and then wait a few seconds for the application to rebuild. Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the updated text appears. - -Press `ctrl+c` in the terminal to stop your application. - -## Create a development container - -At this point, when you run your containerized application, it's using the .NET runtime image. While this small image is good for production, it lacks the SDK tools and dependencies you may need when developing. Also, during development, you may not need to run `dotnet publish`. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](/manuals/build/building/multi-stage.md). - -Add a new development stage to your Dockerfile and update your `compose.yaml` file to use this stage for local development. - -The following is the updated Dockerfile. - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -```Dockerfile {hl_lines="10-13"} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app - -FROM dhi.io/dotnet:10-sdk AS development -COPY . /source -WORKDIR /source/src -CMD dotnet run --no-launch-profile - -FROM dhi.io/aspnetcore:10 AS final -WORKDIR /app -COPY --from=build /app . -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -{{< /tab >}} -{{< tab name="Using the official .NET 10 image" >}} - -```Dockerfile {hl_lines="10-13"} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app - -FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development -COPY . /source -WORKDIR /source/src -CMD dotnet run --no-launch-profile - -FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final -WORKDIR /app -COPY --from=build /app . -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -{{< /tab >}} -{{< /tabs >}} - -The following is the updated `compose.yaml` file. - -```yaml {hl_lines=[5,15,16]} -services: - server: - build: - context: . - target: development - ports: - - 8080:8080 - depends_on: - db: - condition: service_healthy - develop: - watch: - - action: rebuild - path: . - environment: - - ASPNETCORE_ENVIRONMENT=Development - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -Your containerized application will now use the SDK image (either `dhi.io/dotnet:10-sdk` for DHI or `mcr.microsoft.com/dotnet/sdk:10.0-alpine` for official images), which includes development tools like `dotnet test`. Continue to the next section to learn how you can run `dotnet test`. - -## Summary - -In this section, you took a look at setting up your Compose file to add a local -database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. And finally, you learned how to create a development container that contains the SDK tools and dependencies needed for development. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose file watch](/manuals/compose/how-tos/file-watch.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll learn how to run unit tests using Docker. diff --git a/content/guides/dotnet/run-tests.md b/content/guides/dotnet/run-tests.md deleted file mode 100644 index 196a7b6311c6..000000000000 --- a/content/guides/dotnet/run-tests.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Run .NET tests in a container -linkTitle: Run your tests -weight: 30 -keywords: .NET, test -description: Learn how to run your .NET tests in a container. -aliases: - - /language/dotnet/run-tests/ - - /guides/language/dotnet/run-tests/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a .NET application](containerize.md). - -## Overview - -Testing is an essential part of modern software development. Testing can mean a -lot of things to different development teams. There are unit tests, integration -tests and end-to-end testing. In this guide you take a look at running your unit -tests in Docker when developing and when building. - -## Run tests when developing locally - -The sample application already has an xUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests. - -Run the following command in the `docker-dotnet-sample` directory to run the tests inside a container. - -```console -$ docker compose run --build --rm server dotnet test /source/tests -``` - -You should see output that contains the following. - -```console -Starting test execution, please wait... -A total of 1 test files matched the specified pattern. - -Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) -``` - -To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). - -## Run tests when building - -To run your tests when building, you need to update your Dockerfile. You can create a new test stage that runs the tests, or run the tests in the existing build stage. For this guide, update the Dockerfile to run the tests in the build stage. - -The following is the updated Dockerfile. - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -```dockerfile {hl_lines="9"} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app -RUN dotnet test /source/tests - -FROM dhi.io/dotnet:10-sdk AS development -COPY . /source -WORKDIR /source/src -CMD dotnet run --no-launch-profile - -FROM dhi.io/aspnetcore:10 AS final -WORKDIR /app -COPY --from=build /app . -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -{{< /tab >}} -{{< tab name="Using the official .NET 10 image" >}} - -```dockerfile {hl_lines="9"} -# syntax=docker/dockerfile:1 - -FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build -ARG TARGETARCH -COPY . /source -WORKDIR /source/src -RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ - dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app -RUN dotnet test /source/tests - -FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development -COPY . /source -WORKDIR /source/src -CMD dotnet run --no-launch-profile - -FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final -WORKDIR /app -COPY --from=build /app . -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser -ENTRYPOINT ["dotnet", "myWebApp.dll"] -``` - -{{< /tab >}} -{{< /tabs >}} - -Run the following command to build an image using the build stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target build` to target the build stage. - -```console -$ docker build -t dotnet-docker-image-test --progress=plain --no-cache --target build . -``` - -You should see output containing the following. - -```console -#11 [build 5/5] RUN dotnet test /source/tests -#11 1.564 Determining projects to restore... -#11 3.421 Restored /source/src/myWebApp.csproj (in 1.02 sec). -#11 19.42 Restored /source/tests/tests.csproj (in 17.05 sec). -#11 27.91 myWebApp -> /source/src/bin/Debug/net10.0/myWebApp.dll -#11 28.47 tests -> /source/tests/bin/Debug/net10.0/tests.dll -#11 28.49 Test run for /source/tests/bin/Debug/net10.0/tests.dll (.NETCoreApp,Version=v10.0) -#11 28.67 Microsoft (R) Test Execution Command Line Tool Version 17.3.3 (x64) -#11 28.67 Copyright (c) Microsoft Corporation. All rights reserved. -#11 28.68 -#11 28.97 Starting test execution, please wait... -#11 29.03 A total of 1 test files matched the specified pattern. -#11 32.07 -#11 32.08 Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) -#11 DONE 32.2s -``` - -## Summary - -In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image. - -Related information: - -- [docker compose run](/reference/cli/docker/compose/run/) - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/firecrawl-sandbox-kit.md b/content/guides/firecrawl-sandbox-kit.md new file mode 100644 index 000000000000..aa19302239d8 --- /dev/null +++ b/content/guides/firecrawl-sandbox-kit.md @@ -0,0 +1,217 @@ +--- +title: Give sandboxed agents live web access with Firecrawl +linkTitle: Web access with Firecrawl +description: Add the Firecrawl kit to a Docker Sandbox so the agent can search the web, scrape pages to Markdown, and crawl sites through the sandbox proxy, with your API key kept on the host. +summary: | + Compose the Firecrawl v3 mixin onto a sandbox workload. The agent gets the + Firecrawl Python SDK and a network rule for the Firecrawl API, and the + sandbox proxy adds your API key to requests, so the key never enters the + sandbox. +keywords: ai, firecrawl, docker sandboxes, sbx, kits, mixin, web scraping, web search, crawl, credentials, agents +params: + tags: [ai] + time: 15 minutes +--- + +Agents in a Docker Sandbox run under a network policy that usually blocks most +of the web. That keeps the agent contained, but it also means the agent +can't look up documentation or read a page you point it at. +[Firecrawl](https://www.firecrawl.dev/) is a web data API that searches the +web, scrapes pages to clean Markdown, and crawls whole sites. The Firecrawl +kit gives a sandboxed agent that capability through a single API host, +without opening the rest of the web. + +In this guide, you'll learn how to: + +- Store your Firecrawl API key on the host as a sandbox secret +- Add the Firecrawl mixin to a v3 workload +- Check that the SDK, the proxy-managed credential, and the network rule work +- Call Firecrawl from inside the sandbox +- Understand the limits the sandbox network policy places on the kit + +## What the kit adds + +The Firecrawl kit is a v3 [mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md) +published as `docker.io/firecrawl/sbx-kit-firecrawl`. When you add it to a +workload, it contributes four things: + +| Capability | What it does | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `com.docker.sandbox/lifecycle@1` | An install hook that installs a pinned `firecrawl-py` release as the agent user. Sandbox creation fails if the install fails. | +| `com.docker.sandbox/credential@1` | Requests the key stored under the `firecrawl` service. The proxy adds it as `Authorization: Bearer <key>` on requests to `api.firecrawl.dev`. | +| `com.docker.sandbox/network-policy@1` | Allows `pypi.org` and `files.pythonhosted.org` during install, and `api.firecrawl.dev` at runtime. | +| `com.docker.sandbox/agent-context@1` | Adds instructions that tell the agent the SDK is available, how to call it, and which sandbox limits apply. | + +Inside the sandbox, `FIRECRAWL_API_KEY` holds the placeholder value +`proxy-managed`. The SDK sends that placeholder, and the proxy on your host +replaces it with your real key on the way out. Requests to any other host +never carry the key. + +The install hook runs against the workload's own Python, so the kit works with +any workload that ships `python3` and `pip`. Docker's sandbox workloads include +both. + +## Prerequisites + +Before you start, make sure you have: + +- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/install.md), + version 0.46 or later +- A global network policy. If you haven't set one, run + `sbx policy init balanced` +- A [Firecrawl API key](https://www.firecrawl.dev/app/api-keys). Keys start + with `fc-` + +## Step 1: Store the Firecrawl key on the host + +The kit declares a credential for the `firecrawl` service. Store your key under +that name: + +```console +$ sbx secret set firecrawl +``` + +`sbx` prompts for the value. Service secrets apply to every sandbox by +default. Use `--sandbox` to scope the secret to one sandbox instead. + +Storing the secret doesn't give the kit access to it. The first time you run +the kit, `sbx` asks you to approve sending the `firecrawl` credential to +`api.firecrawl.dev`. For how approvals work, and how to approve in advance for +unattended runs, see +[Credential bindings](../manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). + +## Step 2: Run a workload with the Firecrawl mixin + +This example uses a shell workload without a coding agent so you can try the +SDK directly. You can also add the Firecrawl mixin to another compatible v3 +workload, including one that runs a coding agent. + +From your project directory, run: + +```console +$ sbx run docker.io/docker/sbx-kit-shell:1.0.0 --name firecrawl-shell \ + --kit docker.io/firecrawl/sbx-kit-firecrawl:1.0.0 +``` + +Approve the credential request when prompted. `sbx` pulls both kits, runs the +install hook, and opens a shell in the sandbox. + +For more on combining kits, see +[Use kits](/manuals/ai/sandboxes/customize/use-kits.md#add-mixins). + +> [!NOTE] +> Built-in shortcuts such as `sbx run claude` use v2 kits, and v2 agents only +> accept v2 mixins. Firecrawl also publishes a v2 form of the kit for those +> agents. See the +> [kit repository](https://github.com/firecrawl/firecrawl-docker-sandbox#2-launch-the-sandbox-with-the-kit) +> for v2 usage. + +## Step 3: Check the kit + +Run these checks from the shell in the `firecrawl-shell` sandbox. Each one +covers a separate part of the kit. + +Check that the SDK is installed at the pinned version, in the agent user's +site-packages: + +```console +$ python3 -c "import firecrawl, importlib.metadata as m; print(m.version('firecrawl-py'), firecrawl.__file__)" +4.44.0 /home/agent/.local/lib/python3.14/site-packages/firecrawl/__init__.py +``` + +Check that the key in the sandbox is the proxy placeholder, not your real key: + +```console +$ echo "$FIRECRAWL_API_KEY" +proxy-managed +``` + +Then scrape a page to test the whole path: the SDK, the network rule, and +credential injection. This request uses Firecrawl credits: + +```console +$ python3 - <<'EOF' +from firecrawl import Firecrawl + +fc = Firecrawl() +doc = fc.scrape("https://docs.docker.com/ai/sandboxes/", formats=["markdown"]) +print(doc.markdown[:300]) +EOF +``` + +The output is the start of the page as Markdown. If the request fails with +`Unauthorized`, the proxy didn't add your key. Check that you stored the +secret under `firecrawl` and approved the kit's request. A +`PaymentRequiredError` means the request authenticated and the account is out +of credits. + +## Step 4: Use Firecrawl from the agent + +The kit's agent instructions point the agent at the SDK, so a coding agent can +use Firecrawl when a task needs current information or the contents of a URL. +The main calls are: + +```python +from firecrawl import Firecrawl + +fc = Firecrawl() # The proxy adds the API key + +fc.scrape("https://example.com", formats=["markdown"]) # One page as Markdown +fc.search("docker sandboxes kits", limit=5) # Web search results +fc.crawl("https://docs.example.com", limit=20) # Pages across a site +``` + +Each crawled page uses credits, so keep `limit` low and prefer a search +followed by a targeted scrape when the agent needs a single fact. For the full +API, including structured extraction with a schema, see the +[Firecrawl Python SDK documentation](https://docs.firecrawl.dev/sdks/python). + +## How the kit interacts with network policy + +Without organization governance, your default network policy and kit-defined +rules determine which domains the sandbox can access. Under organization +governance, organization policy controls which domains can be allowed; local +and kit-defined allow rules are inactive, while deny rules can still restrict +access. See +[Network policy precedence](/manuals/ai/sandboxes/governance/concepts.md#precedence). + +The Firecrawl kit requests access to PyPI during installation and +`api.firecrawl.dev` at runtime. Its credential declaration tells the proxy to +inject your Firecrawl key only into requests to `api.firecrawl.dev`. + +Firecrawl fetches target pages on its servers. Scraping a URL through +Firecrawl doesn't require the sandbox to have direct access to that URL. + +To see which hosts the sandbox contacted, run this on the host: + +```console +$ sbx policy log firecrawl-shell +ALLOWED REQUESTS +SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT +firecrawl-shell network api.firecrawl.dev forward domain-allowed 10:16:02 15-Oct 1 +firecrawl-shell network files.pythonhosted.org forward domain-allowed 10:15:41 15-Oct 6 +firecrawl-shell network pypi.org forward domain-allowed 10:15:40 15-Oct 4 +``` + +The scrape of `docs.docker.com` doesn't appear in this log because Firecrawl +fetches that page on its servers. The sandbox sends its request to +`api.firecrawl.dev`. + +## Clean up + +Sandboxes persist after you exit. To remove the sandbox from this guide: + +```console +$ sbx rm firecrawl-shell +``` + +Files in your workspace are unaffected. To remove the stored key, run +`sbx secret rm firecrawl`. + +## Learn more + +- [Use kits](/manuals/ai/sandboxes/customize/use-kits.md) +- [Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md) +- [Credentials](../manuals/ai/sandboxes/configuration/credentials.md) +- [Firecrawl kit source](https://github.com/firecrawl/firecrawl-docker-sandbox) +- [Firecrawl documentation](https://docs.firecrawl.dev/) diff --git a/content/guides/frameworks/laravel/_index.md b/content/guides/frameworks/laravel/_index.md deleted file mode 100644 index 4363ca51cd52..000000000000 --- a/content/guides/frameworks/laravel/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Develop and Deploy Laravel applications with Docker Compose -linkTitle: Laravel -summary: Learn how to efficiently set up Laravel development and production environments using Docker Compose. -description: A guide on using Docker Compose to manage Laravel applications for development and production, covering container configurations and service management. -keywords: laravel, php, docker compose, web framework, development, production -tags: [frameworks] -languages: [php] -aliases: - - /frameworks/laravel/ -params: - time: 30 minutes - resource_links: - - title: Laravel - url: https://laravel.com/ - - title: Docker Compose - url: /compose/ - - title: Use Compose in production - url: /compose/how-tos/production/ - - title: Repository with examples - url: https://github.com/dockersamples/laravel-docker-examples ---- - -Laravel is a popular PHP framework that allows developers to build web applications quickly and effectively. Docker Compose simplifies the management of development and production environments by defining essential services, like PHP, a web server, and a database, in a single YAML file. This guide provides a streamlined approach to setting up a robust Laravel environment using Docker Compose, focusing on simplicity and efficiency. - -> **Acknowledgment** -> -> Docker would like to thank [Sergei Shitikov](https://github.com/rw4lll) for -> his contribution to this guide. - -The demonstrated examples can be found in [this GitHub repository](https://github.com/dockersamples/laravel-docker-examples). Docker Compose offers a straightforward approach to connecting multiple containers for Laravel, though similar setups can also be achieved using tools like Docker Swarm, Kubernetes, or individual Docker containers. - -This guide is intended for educational purposes, helping developers adapt and optimize configurations for their specific use cases. Additionally, there are existing tools that support Laravel in containers: - -- [Laravel Sail](https://laravel.com/docs/12.x/sail): An official package for easily starting Laravel in Docker. -- [Laradock](https://github.com/laradock/laradock): A community project that helps run Laravel applications in Docker. - -## What you’ll learn - -- How to use Docker Compose to set up a Laravel development and production environment. -- Defining services that make Laravel development easier, including PHP-FPM, Nginx, and database containers. -- Best practices for managing Laravel environments using containerization. - -## Who’s this for? - -- Developers who work with Laravel and want to streamline environment management. -- DevOps engineers seeking efficient ways to manage and deploy Laravel applications. diff --git a/content/guides/frameworks/laravel/common-questions.md b/content/guides/frameworks/laravel/common-questions.md deleted file mode 100644 index 6fa01a3b414c..000000000000 --- a/content/guides/frameworks/laravel/common-questions.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Common Questions on Using Laravel with Docker -description: Find answers to common questions about setting up and managing Laravel environments with Docker Compose, including troubleshooting and best practices. -keywords: laravel, php, docker compose, faq, troubleshooting, best practices -weight: 40 ---- - -<!-- vale Docker.HeadingLength = NO --> - -## 1. Why should I use Docker Compose for Laravel? - -Docker Compose is a powerful tool for managing multi-container environments, particularly in development due to its simplicity. With Docker Compose, you can define and connect all necessary services for Laravel, such as PHP, Nginx, and databases, in a single configuration (`compose.*.yaml`). This setup ensures consistency across development, testing, and production environments, streamlining onboarding and reducing discrepancies between local and server setups. - -While Docker Compose is a great choice for development, tools like **Docker Swarm** or **Kubernetes** offer advanced scaling and orchestration features, which may be beneficial for complex production deployments. - -## 2. How do I debug my Laravel application with Docker Compose? - -To debug your Laravel application in a Docker environment, use **Xdebug**. In the development setup, Xdebug is installed in the `php-fpm` container to enable debugging. Ensure Xdebug is enabled in your `compose.dev.yaml` file by setting the environment variable `XDEBUG_ENABLED=true` and configuring your IDE (e.g., Visual Studio Code or PHPStorm) to connect to the remote container for debugging. - -## 3. Can I use Docker Compose with databases other than PostgreSQL? - -Yes, Docker Compose supports various database services for Laravel. While PostgreSQL is used in the examples, you can easily substitute **MySQL**, **MariaDB**, or even **SQLite**. Update the `compose.*.yaml` file to specify the required Docker image and adjust your `.env` file to reflect the new database configuration. - -## 4. How can I persist data in development and production? - -In both development and production, Docker volumes are used to persist data. For instance, in the `compose.*.yaml` file, the `postgres-data-*` volume stores PostgreSQL data, ensuring that data is retained even if the container restarts. You can also define named volumes for other services where data persistence is essential. - -## 5. What is the difference between development and production Docker configurations? - -In a development environment, Docker configurations include tools that streamline coding and debugging, such as Xdebug for debugging, and volume mounts to enable real-time code updates without requiring image rebuilds. - -In production, the configuration is optimized for performance, security, and efficiency. This setup uses multi-stage builds to keep the image lightweight and includes only essential tools, packages, and libraries. - -It’s recommended to use `alpine`-based images in production for smaller image sizes, enhancing deployment speed and security. - -Additionally, consider using [Docker Scout](/manuals/scout/_index.md) to detect and analyze vulnerabilities, especially in production environments. - -For additional information about using Docker Compose in production, see [this guide](/compose/how-tos/production/). diff --git a/content/guides/frameworks/laravel/development-setup.md b/content/guides/frameworks/laravel/development-setup.md deleted file mode 100644 index 1639612b1194..000000000000 --- a/content/guides/frameworks/laravel/development-setup.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: Laravel Development Setup with Docker Compose -description: Set up a Laravel development environment using Docker Compose. -keywords: laravel, php, docker compose, development, xdebug, php-fpm, nginx -weight: 30 ---- - -This guide demonstrates how to configure a **development** environment for a Laravel application using Docker and Docker Compose. It builds **on top of** the production image for PHP-FPM and then adds developer-focused features—like Xdebug—to streamline debugging. By basing the development container on a known production image, you keep both environments closely aligned. - -This setup includes PHP-FPM, Nginx, and PostgreSQL services (although you can easily swap PostgreSQL for another database, like MySQL or MariaDB). Everything runs in containers, so you can develop in isolation without altering your host system. - -> [!NOTE] -> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production. - -## Project structure - -```plaintext -my-laravel-app/ -├── app/ -├── bootstrap/ -├── config/ -├── database/ -├── public/ -├── docker/ -│ ├── common/ -│ │ └── php-fpm/ -│ │ └── Dockerfile -│ ├── development/ -│ │ ├── php-fpm/ -│ │ │ └── entrypoint.sh -│ │ ├── workspace/ -│ │ │ └── Dockerfile -│ │ └── nginx -│ │ ├── Dockerfile -│ │ └── nginx.conf -│ └── production/ -├── compose.dev.yaml -├── compose.prod.yaml -├── .dockerignore -├── .env -├── vendor/ -├── ... -``` - -This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable. - -The environment includes a `workspace` service, a sidecar container for tasks like building front-end assets, running Artisan commands, and other CLI tools your project may require. While this extra container may seem unusual, it’s a familiar pattern in solutions like **Laravel Sail** and **Laradock**. It also includes **Xdebug** to aid in debugging. - -## Create a Dockerfile for PHP-FPM - -This Dockerfile **extends** the production image by installing Xdebug and adjusting user permissions to ease local development. That way, your development environment stays consistent with production while still offering extra debug features and improved file mounting. - -```dockerfile -# Builds a dev-only layer on top of the production image -FROM production AS development - -# Use ARGs to define environment variables passed from the Docker build command or Docker Compose. -ARG XDEBUG_ENABLED=true -ARG XDEBUG_MODE=develop,coverage,debug,profile -ARG XDEBUG_HOST=host.docker.internal -ARG XDEBUG_IDE_KEY=DOCKER -ARG XDEBUG_LOG=/dev/stdout -ARG XDEBUG_LOG_LEVEL=0 - -USER root - -# Configure Xdebug if enabled -RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \ - pecl install xdebug && \ - docker-php-ext-enable xdebug && \ - echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ - echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ -fi - -# Add ARGs for syncing permissions -ARG UID=1000 -ARG GID=1000 - -# Create a new user with the specified UID and GID, reusing an existing group if GID exists -RUN if getent group ${GID}; then \ - group_name=$(getent group ${GID} | cut -d: -f1); \ - useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \ - else \ - groupadd -g ${GID} www && \ - useradd -m -u ${UID} -g www -s /bin/bash www; \ - group_name=www; \ - fi - -# Dynamically update php-fpm to use the new user and group -RUN sed -i "s/user = www-data/user = www/g" /usr/local/etc/php-fpm.d/www.conf && \ - sed -i "s/group = www-data/group = $group_name/g" /usr/local/etc/php-fpm.d/www.conf - - -# Set the working directory -WORKDIR /var/www - -# Copy the entrypoint script -COPY ./docker/development/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh -RUN chmod +x /usr/local/bin/entrypoint.sh - -# Switch back to the non-privileged user to run the application -USER www-data - -# Change the default command to run the entrypoint script -ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] - -# Expose port 9000 and start php-fpm server -EXPOSE 9000 -CMD ["php-fpm"] -``` - -## Create a Dockerfile for Workspace - -A workspace container provides a dedicated shell for asset compilation, Artisan/Composer commands, and other CLI tasks. This approach follows patterns from Laravel Sail and Laradock, consolidating all development tools into one container for convenience. - -```dockerfile -# docker/development/workspace/Dockerfile -# Use the official PHP CLI image as the base -FROM php:8.5-cli - -# Set environment variables for user and group ID -ARG UID=1000 -ARG GID=1000 -ARG NODE_VERSION=22.0.0 - -# Install system dependencies and build libraries -RUN apt-get update && apt-get install -y --no-install-recommends \ - curl \ - unzip \ - libpq-dev \ - libonig-dev \ - libssl-dev \ - libxml2-dev \ - libcurl4-openssl-dev \ - libicu-dev \ - libzip-dev \ - && docker-php-ext-install -j$(nproc) \ - pdo_mysql \ - pdo_pgsql \ - pgsql \ - intl \ - zip \ - bcmath \ - soap \ - && pecl install redis \ - && docker-php-ext-enable redis \ - && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ - && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Use ARG to define environment variables passed from the Docker build command or Docker Compose. -ARG XDEBUG_ENABLED -ARG XDEBUG_MODE -ARG XDEBUG_HOST -ARG XDEBUG_IDE_KEY -ARG XDEBUG_LOG -ARG XDEBUG_LOG_LEVEL - -# Configure Xdebug if enabled -RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \ - pecl install xdebug && \ - docker-php-ext-enable xdebug && \ - echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ - echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ - echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ -fi - -# If the group already exists, use it; otherwise, create the 'www' group -RUN if getent group ${GID}; then \ - useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \ - else \ - groupadd -g ${GID} www && \ - useradd -m -u ${UID} -g www -s /bin/bash www; \ - fi && \ - usermod -aG sudo www && \ - echo 'www ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers - -# Switch to the non-root user to install NVM and Node.js -USER www - -# Install NVM (Node Version Manager) as the www user -RUN export NVM_DIR="$HOME/.nvm" && \ - curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash && \ - [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && \ - nvm install ${NODE_VERSION} && \ - nvm alias default ${NODE_VERSION} && \ - nvm use default - -# Ensure NVM is available for all future shells -RUN echo 'export NVM_DIR="$HOME/.nvm"' >> /home/www/.bashrc && \ - echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> /home/www/.bashrc && \ - echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> /home/www/.bashrc - -# Set the working directory -WORKDIR /var/www - -# Override the entrypoint to avoid the default php entrypoint -ENTRYPOINT [] - -# Default command to keep the container running -CMD ["bash"] -``` - -> [!NOTE] -> If you prefer a **one-service-per-container** approach, simply omit the workspace container and run separate containers for each task. For example, you could use a dedicated `php-cli` container for your PHP scripts, and a `node` container to handle the asset building. - -## Create a Docker Compose configuration for development - -Here's the `compose.yaml` file to set up the development environment: - -```yaml -services: - web: - image: nginx:latest # Using the default Nginx image with custom configuration. - volumes: - # Mount the application code for live updates - - ./:/var/www - # Mount the Nginx configuration file - - ./docker/development/nginx/nginx.conf:/etc/nginx/nginx.conf:ro - ports: - # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine - - "80:80" - environment: - - NGINX_HOST=localhost - networks: - - laravel-development - depends_on: - php-fpm: - condition: service_started # Wait for php-fpm to start - - php-fpm: - # For the php-fpm service, we will use our common PHP-FPM Dockerfile with the development target - build: - context: . - dockerfile: ./docker/common/php-fpm/Dockerfile - target: development - args: - UID: ${UID:-1000} - GID: ${GID:-1000} - XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true} - XDEBUG_MODE: develop,coverage,debug,profile - XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal} - XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER} - XDEBUG_LOG: /dev/stdout - XDEBUG_LOG_LEVEL: 0 - env_file: - # Load the environment variables from the Laravel application - - .env - user: "${UID:-1000}:${GID:-1000}" - volumes: - # Mount the application code for live updates - - ./:/var/www - networks: - - laravel-development - depends_on: - postgres: - condition: service_started # Wait for postgres to start - - workspace: - # For the workspace service, we will also create a custom image to install and setup all the necessary stuff. - build: - context: . - dockerfile: ./docker/development/workspace/Dockerfile - args: - UID: ${UID:-1000} - GID: ${GID:-1000} - XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true} - XDEBUG_MODE: develop,coverage,debug,profile - XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal} - XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER} - XDEBUG_LOG: /dev/stdout - XDEBUG_LOG_LEVEL: 0 - tty: true # Enables an interactive terminal - stdin_open: true # Keeps standard input open for 'docker exec' - env_file: - - .env - volumes: - - ./:/var/www - networks: - - laravel-development - - postgres: - image: postgres:18 - ports: - - "${POSTGRES_PORT:-5432}:5432" - environment: - - POSTGRES_DB=app - - POSTGRES_USER=laravel - - POSTGRES_PASSWORD=secret - volumes: - - postgres-data-development:/var/lib/postgresql - networks: - - laravel-development - - redis: - image: redis:alpine - networks: - - laravel-development - -networks: - laravel-development: - -volumes: - postgres-data-development: -``` - -> [!NOTE] -> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations. You can use the `.env.example` file as a template. - -## Run your development environment - -To start the development environment, use: - -```console -$ docker compose -f compose.dev.yaml up --build -d -``` - -Run this command to build and start the development environment in detached mode. When the containers finish initializing, visit [http://localhost/](http://localhost/) to see your Laravel app in action. - -## Summary - -By building on top of the production image and adding debug tools like Xdebug, you create a Laravel development workflow that closely mirrors production. The optional workspace container simplifies tasks like asset building and running Artisan commands. If you prefer a separate container for every service (e.g., a dedicated `php-cli` and `node` container), you can skip the workspace approach. Either way, Docker Compose provides an efficient, consistent way to develop your Laravel project. diff --git a/content/guides/frameworks/laravel/prerequisites.md b/content/guides/frameworks/laravel/prerequisites.md deleted file mode 100644 index cdf6e23e1edd..000000000000 --- a/content/guides/frameworks/laravel/prerequisites.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Prerequisites for Setting Up Laravel with Docker Compose -description: Ensure you have the required tools and knowledge before setting up Laravel with Docker Compose. -keywords: laravel, php, docker compose, prerequisites, requirements, setup -weight: 10 ---- - -Before you begin setting up Laravel with Docker Compose, make sure you meet the following prerequisites: - -## Docker and Docker Compose - -You need Docker and Docker Compose installed on your system. Docker allows you to containerize applications, and Docker Compose helps you manage multi-container applications. - -- Docker: Make sure Docker is installed and running on your machine. Refer to the [Docker installation guide](/get-docker/) to install Docker. -- Docker Compose: Docker Compose is included with Docker Desktop, but you can also follow the [Docker Compose installation guide](/compose/install/) if needed. - -## Basic understanding of Docker and containers - -A fundamental understanding of Docker and how containers work will be helpful. If you're new to Docker, consider reviewing the [Docker Overview](/get-started/overview/) to familiarize yourself with containerization concepts. - -## Basic knowledge of Laravel - -This guide assumes you have a basic understanding of Laravel and PHP. Familiarity with Laravel’s command-line tools, such as [Artisan](https://laravel.com/docs/12.x/artisan), and its project structure is important for following the instructions. - -- Laravel CLI: You should be comfortable using Laravel’s command-line tool (`artisan`). -- Laravel Project Structure: Familiarize yourself with Laravel’s folder structure (`app`, `config`, `routes`, `tests`, etc.). diff --git a/content/guides/frameworks/laravel/production-setup.md b/content/guides/frameworks/laravel/production-setup.md deleted file mode 100644 index 9e04125093d7..000000000000 --- a/content/guides/frameworks/laravel/production-setup.md +++ /dev/null @@ -1,444 +0,0 @@ ---- -title: Laravel Production Setup with Docker Compose -description: Set up a production-ready environment for Laravel using Docker Compose. -keywords: laravel, php, docker compose, production, deployment, php-fpm -weight: 20 ---- - -This guide demonstrates how to set up a production-ready Laravel environment using Docker and Docker Compose. This configuration is designed for streamlined, scalable, and secure Laravel application deployments. - -> [!NOTE] -> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production. - -## Project structure - -```plaintext -my-laravel-app/ -├── app/ -├── bootstrap/ -├── config/ -├── database/ -├── public/ -├── docker/ -│ ├── common/ -│ │ └── php-fpm/ -│ │ ├── Dockerfile -│ │ └── conf.d/ -│ │ └── 20-status-path.conf -│ ├── development/ -│ ├── production/ -│ │ ├── php-fpm/ -│ │ │ └── entrypoint.sh -│ │ └── nginx -│ │ ├── Dockerfile -│ │ └── nginx.conf -├── compose.dev.yaml -├── compose.prod.yaml -├── .dockerignore -├── .env -├── vendor/ -├── ... -``` - -This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable. - -## Create a Dockerfile for PHP-FPM (production) - -For production, the `php-fpm` Dockerfile creates an optimized image with only the PHP extensions and libraries your application needs. As demonstrated in the [GitHub example](https://github.com/dockersamples/laravel-docker-examples), a single Dockerfile with multi-stage builds maintains consistency and reduces duplication between development and production. The following snippet shows only the production-related stages: - -```dockerfile -# Stage 1: Build environment and Composer dependencies -FROM php:8.5-fpm AS builder - -# Install system dependencies and PHP extensions for Laravel with MySQL/PostgreSQL support. -# Dependencies in this stage are only required for building the final image. -# Node.js and asset building are handled in the Nginx stage, not here. -RUN apt-get update && apt-get install -y --no-install-recommends \ - curl \ - unzip \ - libpq-dev \ - libonig-dev \ - libssl-dev \ - libxml2-dev \ - libcurl4-openssl-dev \ - libicu-dev \ - libzip-dev \ - && docker-php-ext-install -j$(nproc) \ - pdo_mysql \ - pdo_pgsql \ - pgsql \ - intl \ - zip \ - bcmath \ - soap \ - && pecl install redis \ - && docker-php-ext-enable redis \ - && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Set the working directory inside the container -WORKDIR /var/www - -# Copy the entire Laravel application code into the container -# ----------------------------------------------------------- -# In Laravel, `composer install` may trigger scripts -# needing access to application code. -# For example, the `post-autoload-dump` event might execute -# Artisan commands like `php artisan package:discover`. If the -# application code (including the `artisan` file) is not -# present, these commands will fail, leading to build errors. -# -# By copying the entire application code before running -# `composer install`, we ensure that all necessary files are -# available, allowing these scripts to run successfully. -# In other cases, it would be possible to copy composer files -# first, to leverage Docker's layer caching mechanism. -# ----------------------------------------------------------- -COPY . /var/www - -# Install Composer and dependencies -RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ - && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist - -# Stage 2: Production environment -FROM php:8.5-fpm AS production - -# Install only runtime libraries needed in production -# libfcgi-bin and procps are required for the php-fpm-healthcheck script -RUN apt-get update && apt-get install -y --no-install-recommends \ - libpq-dev \ - libicu-dev \ - libzip-dev \ - libfcgi-bin \ - procps \ - && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Download and install php-fpm health check script -RUN curl -o /usr/local/bin/php-fpm-healthcheck \ - https://raw.githubusercontent.com/renatomefi/php-fpm-healthcheck/master/php-fpm-healthcheck \ - && chmod +x /usr/local/bin/php-fpm-healthcheck - -# Copy the initialization script -COPY ./docker/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh -RUN chmod +x /usr/local/bin/entrypoint.sh - -# Copy the initial storage structure -COPY ./storage /var/www/storage-init - -# Copy PHP extensions and libraries from the builder stage -COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/ -COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/ -COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/ - -# Use the recommended production PHP configuration -# ----------------------------------------------------------- -# PHP provides development and production configurations. -# Here, we replace the default php.ini with the production -# version to apply settings optimized for performance and -# security in a live environment. -# ----------------------------------------------------------- -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" - -# Keep the image-provided FPM global config intact and add pool overrides separately -COPY ./docker/common/php-fpm/conf.d/*.conf /usr/local/etc/php-fpm.d/ -# Update the variables_order to include E (for ENV) -#RUN sed -i 's/variables_order = "GPCS"/variables_order = "EGPCS"/' "$PHP_INI_DIR/php.ini" - -# Copy the application code and dependencies from the build stage -COPY --from=builder /var/www /var/www - -# Set working directory -WORKDIR /var/www - -# Ensure correct permissions -RUN chown -R www-data:www-data /var/www - -# Switch to the non-privileged user to run the application -USER www-data - -# Change the default command to run the entrypoint script -ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] - -# Expose port 9000 and start php-fpm server -EXPOSE 9000 -CMD ["php-fpm"] -``` - -## Create a Dockerfile for PHP-CLI (production) - -For production, you often need a separate container to run Artisan commands, migrations, and other CLI tasks. In most cases you can run these commands by reusing existing PHP-FPM container: - -```console -$ docker compose -f compose.prod.yaml exec php-fpm php artisan route:list -``` - -If you need a separate CLI container with different extensions or strict separation of concerns, consider a php-cli Dockerfile: - -```dockerfile -# Stage 1: Build environment and Composer dependencies -FROM php:8.5-cli AS builder - -# Install system dependencies and PHP extensions required for Laravel + MySQL/PostgreSQL support -# Some dependencies are required for PHP extensions only in the build stage -RUN apt-get update && apt-get install -y --no-install-recommends \ - curl \ - unzip \ - libpq-dev \ - libonig-dev \ - libssl-dev \ - libxml2-dev \ - libcurl4-openssl-dev \ - libicu-dev \ - libzip-dev \ - && docker-php-ext-install -j$(nproc) \ - pdo_mysql \ - pdo_pgsql \ - pgsql \ - intl \ - zip \ - bcmath \ - soap \ - && pecl install redis \ - && docker-php-ext-enable redis \ - && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Set the working directory inside the container -WORKDIR /var/www - -# Copy the entire Laravel application code into the container -COPY . /var/www - -# Install Composer and dependencies -RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ - && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist - -# Stage 2: Production environment -FROM php:8.5-cli - -# Install client libraries required for php extensions in runtime -RUN apt-get update && apt-get install -y --no-install-recommends \ - libpq-dev \ - libicu-dev \ - libzip-dev \ - && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Copy PHP extensions and libraries from the builder stage -COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/ -COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/ -COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/ - -# Use the default production configuration for PHP runtime arguments -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" - -# Copy the application code and dependencies from the build stage -COPY --from=builder /var/www /var/www - -# Set working directory -WORKDIR /var/www - -# Ensure correct permissions -RUN chown -R www-data:www-data /var/www - -# Switch to the non-privileged user to run the application -USER www-data - -# Default command: Provide a bash shell to allow running any command -CMD ["bash"] -``` - -This Dockerfile is similar to the PHP-FPM Dockerfile, but it uses the `php:8.5-cli` image as the base image and sets up the container for running CLI commands. - -## Create a Dockerfile for Nginx (production) - -Nginx serves as the web server for the Laravel application. You can include static assets directly to the container. Here's an example of possible Dockerfile for Nginx: - -```dockerfile -# docker/nginx/Dockerfile -# Stage 1: Build assets -FROM debian AS builder - -# Install Node.js and build tools -RUN apt-get update && apt-get install -y --no-install-recommends \ - curl \ - nodejs \ - npm \ - && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# Set working directory -WORKDIR /var/www - -# Copy Laravel application code -COPY . /var/www - -# Install Node.js dependencies and build assets -RUN npm install && npm run build - -# Stage 2: Nginx production image -FROM nginx:alpine - -# Copy custom Nginx configuration -# ----------------------------------------------------------- -# Replace the default Nginx configuration with our custom one -# that is optimized for serving a Laravel application. -# ----------------------------------------------------------- -COPY ./docker/nginx/nginx.conf /etc/nginx/nginx.conf - -# Copy Laravel's public assets from the builder stage -# ----------------------------------------------------------- -# We only need the 'public' directory from our Laravel app. -# ----------------------------------------------------------- -COPY --from=builder /var/www/public /var/www/public - -# Set the working directory to the public folder -WORKDIR /var/www/public - -# Expose port 80 and start Nginx -EXPOSE 80 -CMD ["nginx", "-g", "daemon off;"] -``` - -This Dockerfile uses a multi-stage build to separate the asset building process from the final production image. The first stage installs Node.js and builds the assets, while the second stage sets up the Nginx production image with the optimized configuration and the built assets. - -## Create a Docker Compose configuration for production - -To bring all the services together, create a `compose.prod.yaml` file that defines the services, volumes, and networks for the production environment. Here's an example configuration: - -```yaml -services: - web: - build: - context: . - dockerfile: ./docker/production/nginx/Dockerfile - restart: unless-stopped # Automatically restart unless the service is explicitly stopped - volumes: - # Mount the 'laravel-storage' volume to '/var/www/storage' inside the container. - # ----------------------------------------------------------- - # This volume stores persistent data like uploaded files and cache. - # The ':ro' option mounts it as read-only in the 'web' service because Nginx only needs to read these files. - # The 'php-fpm' service mounts the same volume without ':ro' to allow write operations. - # ----------------------------------------------------------- - - laravel-storage-production:/var/www/storage:ro - networks: - - laravel-production - ports: - # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine. - # ----------------------------------------------------------- - # This allows external access to the Nginx web server running inside the container. - # For example, if 'NGINX_PORT' is set to '8080', accessing 'http://localhost:8080' will reach the application. - # ----------------------------------------------------------- - - "${NGINX_PORT:-80}:80" - depends_on: - php-fpm: - condition: service_healthy # Wait for php-fpm health check - - php-fpm: - # For the php-fpm service, we will create a custom image to install the necessary PHP extensions and setup proper permissions. - build: - context: . - dockerfile: ./docker/common/php-fpm/Dockerfile - target: production # Use the 'production' stage in the Dockerfile - restart: unless-stopped - volumes: - - laravel-storage-production:/var/www/storage # Mount the storage volume - env_file: - - .env - networks: - - laravel-production - healthcheck: - test: ["CMD-SHELL", "php-fpm-healthcheck || exit 1"] - interval: 10s - timeout: 5s - retries: 3 - # The 'depends_on' attribute with 'condition: service_healthy' ensures that - # this service will not start until the 'postgres' service passes its health check. - # This prevents the application from trying to connect to the database before it's ready. - depends_on: - postgres: - condition: service_healthy - - # The 'php-cli' service provides a command-line interface for running Artisan commands and other CLI tasks. - # ----------------------------------------------------------- - # This is useful for running migrations, seeders, or any custom scripts. - # It shares the same codebase and environment as the 'php-fpm' service. - # ----------------------------------------------------------- - php-cli: - build: - context: . - dockerfile: ./docker/php-cli/Dockerfile - tty: true # Enables an interactive terminal - stdin_open: true # Keeps standard input open for 'docker exec' - env_file: - - .env - networks: - - laravel-production - - postgres: - image: postgres:18 - restart: unless-stopped - user: postgres - ports: - - "${POSTGRES_PORT}:5432" - environment: - - POSTGRES_DB=${POSTGRES_DATABASE} - - POSTGRES_USER=${POSTGRES_USERNAME} - - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - volumes: - - postgres-data-production:/var/lib/postgresql - networks: - - laravel-production - # Health check for PostgreSQL - # ----------------------------------------------------------- - # Health checks allow Docker to determine if a service is operational. - # The 'pg_isready' command checks if PostgreSQL is ready to accept connections. - # This prevents dependent services from starting before the database is ready. - # ----------------------------------------------------------- - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 - - redis: - image: redis:alpine - restart: unless-stopped # Automatically restart unless the service is explicitly stopped - networks: - - laravel-production - # Health check for Redis - # ----------------------------------------------------------- - # Checks if Redis is responding to the 'PING' command. - # This ensures that the service is not only running but also operational. - # ----------------------------------------------------------- - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 10s - timeout: 5s - retries: 3 - -networks: - # Attach the service to the 'laravel-production' network. - # ----------------------------------------------------------- - # This custom network allows all services within it to communicate using their service names as hostnames. - # For example, 'php-fpm' can connect to 'postgres' by using 'postgres' as the hostname. - # ----------------------------------------------------------- - laravel-production: - -volumes: - postgres-data-production: - laravel-storage-production: -``` - -> [!NOTE] -> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations to match the Docker Compose setup. - -## Running your production environment - -To start the production environment, run: - -```console -$ docker compose -f compose.prod.yaml up --build -d -``` - -This command will build and start all the services in detached mode, providing a scalable and production-ready setup for your Laravel application. - -## Summary - -By setting up a Docker Compose environment for Laravel in production, you ensure that your application is optimized for performance, scalable, and secure. This setup makes deployments consistent and easier to manage, reducing the likelihood of errors due to differences between environments. diff --git a/content/guides/genai-claude-code-mcp.md b/content/guides/genai-claude-code-mcp.md new file mode 100644 index 000000000000..806ceb022dd7 --- /dev/null +++ b/content/guides/genai-claude-code-mcp.md @@ -0,0 +1,298 @@ +--- +description: Learn how to use Claude Code with Docker MCP Toolkit to generate production-ready Docker Compose files from natural language using the Docker Hub MCP server. +keywords: mcp, model context protocol, docker, docker desktop, claude code, docker hub, compose, automation +title: Generate Docker Compose Files with Claude Code and Docker MCP Toolkit +summary: | + This guide shows how to wire Claude Code to the Docker MCP Toolkit so it can search Docker Hub images and generate complete Docker Compose stacks from natural language. + You’ll enable the Docker Hub MCP server, connect Claude Code, verify MCP access, and create a Node.js + PostgreSQL stack with a conversational prompt. +aliases: + - /guides/use-case/genai-claude-code-mcp/ + - /guides/genai-claude-code-mcp/claude-code-mcp-guide/ +params: + tags: [ai] + time: 15 minutes +--- + +This guide introduces how to use Claude Code together with Docker MCP Toolkit so Claude can search Docker Hub in real time and generate a complete `docker-compose.yaml` from natural language. + +Instead of manually writing YAML or looking for image tags, you describe your stack once — Claude uses the Model Context Protocol (MCP) to query Docker Hub and build a production-ready Compose file. + +In this guide, you’ll learn how to: + +- Enable Docker MCP Toolkit in Docker Desktop +- Add the Docker Hub MCP server +- Connect Claude Code to the MCP Gateway (GUI or CLI) +- Verify MCP connectivity inside Claude +- Ask Claude to generate and save a Compose file for a Node.js + PostgreSQL app +- Deploy it instantly with `docker compose up` + +--- + +## Use Claude Code and Docker MCP Toolkit to generate a Docker Compose file from natural language + + +- Setup: Enable MCP Toolkit → Add Docker Hub MCP server → Connect Claude Code +- Use Claude: Describe your stack in plain English +- Automate: Claude queries Docker Hub via MCP and builds a complete `docker-compose.yaml` +- Deploy: Run `docker compose up` → Node.js + PostgreSQL live on `localhost:3000` +- Benefit: Zero YAML authoring. Zero image searching. Describe once → Claude builds it. + +Estimated time: ~15 minutes + +--- + +## 1. What you are building + +The goal is simple: use Claude Code together with the Docker MCP Toolkit to search Docker Hub images and generate a complete Docker Compose file for a Node.js and PostgreSQL setup. + +The Model Context Protocol (MCP) bridges Claude Code and Docker Desktop, giving Claude real-time access to Docker's tools. Instead of context-switching between Docker, terminal commands, and YAML editors, you describe your requirements once and Claude handles the infrastructure details. + +Why this matters: This pattern scales to complex multi-service setups, database migrations, networking, security policies — all through conversational prompts. + +--- + +## 2. Prerequisites + +Make sure you have: + +- Docker Desktop installed +- Enable Docker Desktop updated with [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/#setup) support + +- Claude Code installed + +--- + +## 3. Install the Docker Hub MCP server + +1. Open Docker Desktop +1. Select **MCP Toolkit** +1. Go to the **Catalog** tab +1. Search for **Docker Hub** +1. Select the **Docker Hub**MCP server +1. Add the MCP server, then open the **Configuration** tab +1. Enter your Docker Hub username +1. [Create a read-only personal access token](/security/access-tokens/personal-access-tokens/#create) and enter your access token under **Secrets** +1. Save the configuration + +![Docker Hub](images/genai-claude-code-mcp-catalog-docker-hub.avif "Docker Hub") + +Public images work without credentials. For private repositories, you can add your Docker Hub username and token later. + +![Docker Hub Secrets](images/genai-claude-code-mcp-dockerhub-secrets.avif "Docker Hub Secrets") + + +--- + +## 4. Connect Claude Code to Docker MCP Toolkit + +You can connect from Docker Desktop or using the CLI. + +### Option A. Connect with Docker Desktop + +1. Open **MCP Toolkit** +1. Go to the **Clients** tab +1. Locate Claude Code +1. Select **Connect** + +![Docker Connection](images/genai-claude-code-mcp-docker-connect-claude.avif) + +### Option B. Connect using the CLI + +```console +$ claude mcp add MCP_DOCKER -s user -- docker mcp gateway run +``` + +--- + +## 5. Verify MCP servers inside Claude Code + +1. Navigate to your project folder: + +```console +$ cd /path/to/project +``` + +1. Start Claude Code: + +```console +$ claude +``` + +1. In the input box, type: + +```console +/mcp +``` + +You should now see: + +- The MCP gateway (for example `MCP_DOCKER`) +- Tools provided by the Docker Hub MCP server + +![mcp-docker](images/genai-claude-code-mcp-mcp-servers.avif) + +If not, restart Claude Code or check Docker Desktop to confirm the connection. + +--- + +## 6. Create a basic Node.js app + +Claude Code generates more accurate Compose files when it can inspect a real project. Set up the application code now so the agent can bind mount it later. + +Inside project folder, create a folder named `app`: + +```console +$ mkdir app +$ cd app +$ npm init -y +$ npm install express +``` + +Create `index.js`: + +```console +const express = require("express"); +const app = express(); + +app.get("/", (req, res) => { + res.send("Node.js, Docker, and MCP Toolkit are working together!"); +}); + +app.listen(3000, () => { + console.log("Server running on port 3000"); +}); +``` + +Add a start script to `package.json`: + +```console +"scripts": { + "start": "node index.js" +} +``` + +Return to your project root (`cd ..`) once the app is ready. + +--- + +## 7. Ask Claude Code to design your Docker Compose stack + +Paste this message into Claude Code: + +```console +Using the Docker Hub MCP server: + +Search Docker Hub for an official Node.js image and a PostgreSQL image. +Choose stable, commonly used tags such as the Node LTS version and a recent major Postgres version. + +Generate a Docker Compose file (`docker-compose.yaml`) with: +- app: + - runs on port 3000 + - bind mounts the existing ./app directory into /usr/src/app + - sets /usr/src/app as the working directory and runs `npm install && npm start` +- db: running on port 5432 using a named volume + +Include: +- Environment variables for Postgres +- A shared bridge network +- Healthchecks where appropriate +- Pin the image version using the tag + index digest +``` + +Claude will search images through MCP, inspect the `app` directory, and generate a Compose file that mounts and runs your local code. + +--- + +## 8. Save the generated Docker Compose file + +Tell Claude: + +```console +Save the final Docker Compose file (docker-compose.yaml) into the current project directory. +``` + +You should see something like this: + +```console +services: + app: + image: node:<tag> + working_dir: /usr/src/app + volumes: + - .:/usr/src/app + ports: + - "3000:3000" + depends_on: + - db + networks: + - app-net + + db: + image: postgres:18 + environment: + POSTGRES_USER: example + POSTGRES_PASSWORD: example + POSTGRES_DB: appdb + volumes: + - db-data:/var/lib/postgresql + ports: + - "5432:5432" + networks: + - app-net + +volumes: + db-data: + +networks: + app-net: + driver: bridge +``` + +--- + +## 9. Run the Docker Compose stack + +From your project root: + +```console +$ docker compose up +``` + +Docker will: + +- Pull the Node and Postgres images selected through Docker Hub MCP +- Create networks and volumes +- Start the containers + +Open your browser: + +```console +http://localhost:3000 +``` +![Local Host](images/genai-claude-code-mcp-localhost.avif) + +Your Node.js app should now be running. + +--- + +## Conclusion + +By combining Claude Code with the Docker MCP Toolkit, Docker Desktop, and the Docker Hub MCP server, you can describe your stack in natural language and let MCP handle the details. This removes context switching and replaces it with a smooth, guided workflow powered by model context protocol integrations. + +--- + +### Next steps + +- Explore the 220+ MCP servers available in the [Docker MCP catalog](https://hub.docker.com/mcp) +- Connect Claude Code to your databases, internal APIs, and team tools +- Share your MCP setup with your team so everyone works consistently + +The future of development is not about switching between tools. It is about tools working together in a simple, safe, and predictable way. The Docker MCP Toolkit brings that future into your everyday workflow. + + + +## Learn more + +- [Explore the MCP Catalog](https://hub.docker.com/mcp): Discover containerized, security-hardened MCP servers +- [Get started with MCP Toolkit in Docker Desktop](https://hub.docker.com/open-desktop?url=https://open.docker.com/dashboard/mcp): Requires version 4.48 or newer to launch automatically +- [Read the MCP Horror Stories series](https://www.docker.com/blog/mcp-horror-stories-the-supply-chain-attack/): Learn about common MCP security pitfalls and how to avoid them diff --git a/content/guides/genai-claude-code-mcp/claude-code-mcp-guide.md b/content/guides/genai-claude-code-mcp/claude-code-mcp-guide.md deleted file mode 100644 index 22624c6bd3c8..000000000000 --- a/content/guides/genai-claude-code-mcp/claude-code-mcp-guide.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -description: Learn how to use Claude Code with Docker MCP Toolkit to generate production-ready Docker Compose files from natural language using the Docker Hub MCP server. -keywords: mcp, model context protocol, docker, docker desktop, claude code, docker hub, compose, automation -title: Generate Docker Compose Files with Claude Code and Docker MCP Toolkit -summary: | - This guide shows how to wire Claude Code to the Docker MCP Toolkit so it can search Docker Hub images and generate complete Docker Compose stacks from natural language. - You’ll enable the Docker Hub MCP server, connect Claude Code, verify MCP access, and create a Node.js + PostgreSQL stack with a conversational prompt. -tags: [ai] -aliases: - - /guides/use-case/genai-claude-code-mcp/ -params: - time: 15 minutes ---- - -This guide introduces how to use Claude Code together with Docker MCP Toolkit so Claude can search Docker Hub in real time and generate a complete `docker-compose.yaml` from natural language. - -Instead of manually writing YAML or looking for image tags, you describe your stack once — Claude uses the Model Context Protocol (MCP) to query Docker Hub and build a production-ready Compose file. - -In this guide, you’ll learn how to: - -- Enable Docker MCP Toolkit in Docker Desktop -- Add the Docker Hub MCP server -- Connect Claude Code to the MCP Gateway (GUI or CLI) -- Verify MCP connectivity inside Claude -- Ask Claude to generate and save a Compose file for a Node.js + PostgreSQL app -- Deploy it instantly with `docker compose up` - ---- - -## Use Claude Code and Docker MCP Toolkit to generate a Docker Compose file from natural language - - -- Setup: Enable MCP Toolkit → Add Docker Hub MCP server → Connect Claude Code -- Use Claude: Describe your stack in plain English -- Automate: Claude queries Docker Hub via MCP and builds a complete `docker-compose.yaml` -- Deploy: Run `docker compose up` → Node.js + PostgreSQL live on `localhost:3000` -- Benefit: Zero YAML authoring. Zero image searching. Describe once → Claude builds it. - -Estimated time: ~15 minutes - ---- - -## 1. What you are building - -The goal is simple: use Claude Code together with the Docker MCP Toolkit to search Docker Hub images and generate a complete Docker Compose file for a Node.js and PostgreSQL setup. - -The Model Context Protocol (MCP) bridges Claude Code and Docker Desktop, giving Claude real-time access to Docker's tools. Instead of context-switching between Docker, terminal commands, and YAML editors, you describe your requirements once and Claude handles the infrastructure details. - -Why this matters: This pattern scales to complex multi-service setups, database migrations, networking, security policies — all through conversational prompts. - ---- - -## 2. Prerequisites - -Make sure you have: - -- Docker Desktop installed -- Enable Docker Desktop updated with [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/#setup) support - -- Claude Code installed - ---- - -## 3. Install the Docker Hub MCP server - -1. Open Docker Desktop -1. Select **MCP Toolkit** -1. Go to the **Catalog** tab -1. Search for **Docker Hub** -1. Select the **Docker Hub**MCP server -1. Add the MCP server, then open the **Configuration** tab -1. Enter your Docker Hub username -1. [Create a read-only personal access token](/security/access-tokens/#create-a-personal-access-token) and enter your access token under **Secrets** -1. Save the configuration - -![Docker Hub](./Images/catalog_docker_hub.avif "Docker Hub") - -Public images work without credentials. For private repositories, you can add your Docker Hub username and token later. - -![Docker Hub Secrets](./Images/dockerhub_secrets.avif "Docker Hub Secrets") - - ---- - -## 4. Connect Claude Code to Docker MCP Toolkit - -You can connect from Docker Desktop or using the CLI. - -### Option A. Connect with Docker Desktop - -1. Open **MCP Toolkit** -1. Go to the **Clients** tab -1. Locate Claude Code -1. Select **Connect** - -![Docker Connection](./Images/docker-connect-claude.avif) - -### Option B. Connect using the CLI - -```console -$ claude mcp add MCP_DOCKER -s user -- docker mcp gateway run -``` - ---- - -## 5. Verify MCP servers inside Claude Code - -1. Navigate to your project folder: - -```console -$ cd /path/to/project -``` - -1. Start Claude Code: - -```console -$ claude -``` - -1. In the input box, type: - -```console -/mcp -``` - -You should now see: - -- The MCP gateway (for example `MCP_DOCKER`) -- Tools provided by the Docker Hub MCP server - -![mcp-docker](./Images/mcp-servers.avif) - -If not, restart Claude Code or check Docker Desktop to confirm the connection. - ---- - -## 6. Create a basic Node.js app - -Claude Code generates more accurate Compose files when it can inspect a real project. Set up the application code now so the agent can bind mount it later. - -Inside project folder, create a folder named `app`: - -```console -$ mkdir app -$ cd app -$ npm init -y -$ npm install express -``` - -Create `index.js`: - -```console -const express = require("express"); -const app = express(); - -app.get("/", (req, res) => { - res.send("Node.js, Docker, and MCP Toolkit are working together!"); -}); - -app.listen(3000, () => { - console.log("Server running on port 3000"); -}); -``` - -Add a start script to `package.json`: - -```console -"scripts": { - "start": "node index.js" -} -``` - -Return to your project root (`cd ..`) once the app is ready. - ---- - -## 7. Ask Claude Code to design your Docker Compose stack - -Paste this message into Claude Code: - -```console -Using the Docker Hub MCP server: - -Search Docker Hub for an official Node.js image and a PostgreSQL image. -Choose stable, commonly used tags such as the Node LTS version and a recent major Postgres version. - -Generate a Docker Compose file (`docker-compose.yaml`) with: -- app: - - runs on port 3000 - - bind mounts the existing ./app directory into /usr/src/app - - sets /usr/src/app as the working directory and runs `npm install && npm start` -- db: running on port 5432 using a named volume - -Include: -- Environment variables for Postgres -- A shared bridge network -- Healthchecks where appropriate -- Pin the image version using the tag + index digest -``` - -Claude will search images through MCP, inspect the `app` directory, and generate a Compose file that mounts and runs your local code. - ---- - -## 8. Save the generated Docker Compose file - -Tell Claude: - -```console -Save the final Docker Compose file (docker-compose.yaml) into the current project directory. -``` - -You should see something like this: - -```console -services: - app: - image: node:<tag> - working_dir: /usr/src/app - volumes: - - .:/usr/src/app - ports: - - "3000:3000" - depends_on: - - db - networks: - - app-net - - db: - image: postgres:18 - environment: - POSTGRES_USER: example - POSTGRES_PASSWORD: example - POSTGRES_DB: appdb - volumes: - - db-data:/var/lib/postgresql - ports: - - "5432:5432" - networks: - - app-net - -volumes: - db-data: - -networks: - app-net: - driver: bridge -``` - ---- - -## 9. Run the Docker Compose stack - -From your project root: - -```console -$ docker compose up -``` - -Docker will: - -- Pull the Node and Postgres images selected through Docker Hub MCP -- Create networks and volumes -- Start the containers - -Open your browser: - -```console -http://localhost:3000 -``` -![Local Host](./Images/Localhost.avif) - -Your Node.js app should now be running. - ---- - -## Conclusion - -By combining Claude Code with the Docker MCP Toolkit, Docker Desktop, and the Docker Hub MCP server, you can describe your stack in natural language and let MCP handle the details. This removes context switching and replaces it with a smooth, guided workflow powered by model context protocol integrations. - ---- - -### Next steps - -- Explore the 220+ MCP servers available in the [Docker MCP catalog](https://hub.docker.com/mcp) -- Connect Claude Code to your databases, internal APIs, and team tools -- Share your MCP setup with your team so everyone works consistently - -The future of development is not about switching between tools. It is about tools working together in a simple, safe, and predictable way. The Docker MCP Toolkit brings that future into your everyday workflow. - - - -## Learn more - -- [Explore the MCP Catalog](https://hub.docker.com/mcp): Discover containerized, security-hardened MCP servers -- [Get started with MCP Toolkit in Docker Desktop](https://hub.docker.com/open-desktop?url=https://open.docker.com/dashboard/mcp): Requires version 4.48 or newer to launch automatically -- [Read the MCP Horror Stories series](https://www.docker.com/blog/mcp-horror-stories-the-supply-chain-attack/): Learn about common MCP security pitfalls and how to avoid them diff --git a/content/guides/genai-leveraging-rag/image-1.png b/content/guides/genai-leveraging-rag/image-1.png deleted file mode 100644 index 31b758c53341..000000000000 Binary files a/content/guides/genai-leveraging-rag/image-1.png and /dev/null differ diff --git a/content/guides/genai-leveraging-rag/image-2.png b/content/guides/genai-leveraging-rag/image-2.png deleted file mode 100644 index 186797ce4042..000000000000 Binary files a/content/guides/genai-leveraging-rag/image-2.png and /dev/null differ diff --git a/content/guides/genai-leveraging-rag/image-3.png b/content/guides/genai-leveraging-rag/image-3.png deleted file mode 100644 index 7b700101b98c..000000000000 Binary files a/content/guides/genai-leveraging-rag/image-3.png and /dev/null differ diff --git a/content/guides/genai-leveraging-rag/image.png b/content/guides/genai-leveraging-rag/image.png deleted file mode 100644 index d44001ffc4b7..000000000000 Binary files a/content/guides/genai-leveraging-rag/image.png and /dev/null differ diff --git a/content/guides/genai-leveraging-rag/index.md b/content/guides/genai-leveraging-rag/index.md deleted file mode 100644 index b3194e7c2727..000000000000 --- a/content/guides/genai-leveraging-rag/index.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: Leveraging RAG in GenAI to teach new information -linkTitle: Leveraging RAG in GenAI -description: This guide walks through the process of setting up and utilizing a GenAI stack with Retrieval-Augmented Generation (RAG) systems and graph databases. Learn how to integrate graph databases like Neo4j with AI models for more accurate, contextually-aware responses. -keywords: Docker, GenAI, Retrieval-Augmented Generation, RAG, Graph Databases, Neo4j, AI, LLM -summary: | - This guide explains setting up a GenAI stack with Retrieval-Augmented Generation (RAG) and Neo4j, covering key concepts, deployment steps, and a case study. It also includes troubleshooting tips for optimizing AI performance with real-time data. -tags: [ai] -params: - time: 35 minutes ---- - -## Introduction - -Retrieval-Augmented Generation (RAG) is a powerful framework that enhances large language models (LLMs) by integrating information retrieval from external knowledge sources. This guide focuses on a specialized RAG implementation using graph databases like Neo4j, which excel in managing highly connected, relational data. Unlike traditional RAG setups with vector databases, combining RAG with graph databases offers better context-awareness and relationship-driven insights. - -In this guide, you will: - -* Explore the advantages of integrating graph databases into a RAG framework. -* Configure a GenAI stack with Docker, incorporating Neo4j and an AI model. -* Analyze a real-world case study that highlights the effectiveness of this approach for handling specialized queries. - -## Understanding RAG - -RAG is a hybrid framework that enhances the capabilities of large language models by integrating information retrieval. It combines three core components: - -- **Information retrieval** from an external knowledge base -- **Large Language Model (LLM)** for generating responses -- **Vector embeddings** to enable semantic search - -In a RAG system, vector embeddings are used to represent the semantic meaning of text in a way that a machine can understand and process. For instance, the words "dog" and "puppy" will have similar embeddings because they share similar meanings. By integrating these embeddings into the RAG framework, the system can combine the generative power of large language models with the ability to pull in highly relevant, contextually-aware data from external sources. - -The system operates as follows: -1. Questions get turned into mathematical patterns that capture their meaning -2. These patterns help find matching information in a database -3. The LLM generates responses that blend the model's inherent knowledge with the this extra information. - -To hold this vector information in an efficient manner, you need a special type of database. - -## Introduction to Graph databases - -Graph databases, such as Neo4j, are specifically designed for managing highly connected data. Unlike traditional relational databases, graph databases prioritize both the entities and the relationships between them, making them ideal for tasks where connections are as important as the data itself. - -Graph databases stand out for their unique approach to data storage and querying. They use nodes (or vertices) to represent entities and edges to represent the relationships between these entities. This structure allows for efficient handling of highly connected data and complex queries, which are difficult to manage in traditional database systems. - -SQL databases and graph databases differ significantly in their data models. SQL databases use a tabular structure with rows and columns, where relationships between entities are established using foreign keys. This approach works well for structured data and predefined relationships. In contrast, graph databases represent data as nodes (entities) and edges (relationships), making the representation of relationships more intuitive and flexible. This structure is particularly advantageous for complex, interconnected data. - -Another key difference lies in schema flexibility. SQL databases operate on a rigid schema, meaning any changes to the data structure, such as adding new columns or altering relationships, typically require careful planning and migration processes. Graph databases, however, are schema-optional, allowing for much greater flexibility. New nodes, edges, or properties can be introduced without disrupting existing data, enabling faster adaptation to changing requirements. - -## Practical implementation: testing RAG effectiveness - -To illustrate the power of RAG systems in practice, let's examine a real-world implementation using Apache NiFi as our subject matter. This case study demonstrates how RAG can enhance an AI's ability to provide accurate, contextual information about specialized technical topics. - -### Teaching AI about new technologies - -Apache NiFi serves as an excellent example of the limitations of traditional LLMs and how RAG can overcome them. As a relatively recent technology, many LLMs have limited or outdated knowledge about it, making it a perfect candidate for demonstrating RAG's capabilities. - -Without RAG, the LLM may provide broad responses or acknowledge its limited knowledge when asked about information that is beyond its cutoff date. The following example demonstrates this. -```text -Question: What important events happened in 2024? -RAG: Disabled -I'm happy to help! Unfortunately, I'm a large language model, I don't have access to real-time information or events that occurred after my training data cutoff in 2024. Therefore, I cannot provide you with any important events that happened in 2024. My apologize for any inconvenience this may cause. Is there anything else I can help you with? -``` - -## Setting up GenAI stack with GPU acceleration on Linux - -To set up and run the GenAI stack on a Linux host, execute one of the following commands, either for GPU or CPU powered: - -### GPU powered - -```bash -git clone https://github.com/docker/genai-stack -docker compose --profile linux-gpu up -d -mv env.example .env -nano .env -``` -In the `.env` file, make sure following lines are commented out. Set your own credentials for security - - ```txt - NEO4J_URI=neo4j://database:7687 - NEO4J_USERNAME=neo4j - NEO4J_PASSWORD=password - OLLAMA_BASE_URL=http://llm-gpu:11434 - ``` - -### CPU powered - -```bash -git clone https://github.com/docker/genai-stack -docker compose --profile linux up -d -mv env.example .env -nano .env -``` -In the `.env` file, make sure following lines are commented out. Set your own credentials for security - - ```txt - NEO4J_URI=neo4j://database:7687 - NEO4J_USERNAME=neo4j - NEO4J_PASSWORD=password - OLLAMA_BASE_URL=http://llm:11434 - ``` - -### Setting up on other platforms - -For instructions on how to set up the stack on other platforms, refer to [this page](https://github.com/docker/genai-stack). - -### Initial startup - -The first startup may take some time because the system needs to download a large language model. - -### Monitoring progress - -You can monitor the download and initialization progress by viewing the logs. Run the following command to view the logs: - -```bash -docker compose logs -``` - -Wait for specific lines in the logs indicating that the download is complete and the stack is ready. These lines typically confirm successful setup and initialization. - - ```text - pull-model-1 exited with code 0 - database-1 | 2024-12-29 09:35:53.269+0000 INFO Started. - pdf_bot-1 | You can now view your Streamlit app in your browser. - loader-1 | You can now view your Streamlit app in your browser. - bot-1 | You can now view your Streamlit app in your browser. - ``` - -You can now access the interface at [http://localhost:8501/](http://localhost:8501/) to ask questions. For example, you can try the sample question: - -When those lines appear in the logs, the web apps are ready to use. - -Since the goal is to teach AI about things it does not yet know, begin by asking it a simple question about NiFi at -[http://localhost:8501/](http://localhost:8501/). -![alt text](image.png) - -```text -Question: What is Apache Nifi? -RAG: Disabled -Hello! I'm here to help you with your question about Apache NiFi. Unfortunately, I don't know the answer to that question. I'm just an AI and my knowledge cutoff is December 2022, so I may not be familiar with the latest technologies or software. Can you please provide more context or details about Apache NiFi? Maybe there's something I can help you with related to it. -``` - -As shown, the AI does not know anything about this subject because it did not exist during the time of its training, also known as the information cutoff point. - -Now it's time to teach the AI some new tricks. First, connect to [http://localhost:8502/](http://localhost:8502/). Instead of using the "neo4j" tag, change it to the "apache-nifi" tag, then select the **Import** button. - -![alt text](image-1.png) - -After the import is successful, you can access Neo4j to verify the data. - -After logging in to [http://localhost:7474/](http://localhost:7474/) using the credentials from the `.env` file, you can run queries on Neo4j. Using the Neo4j Cypher query language, you can check for the data stored in the database. - -To count the data, run the following query: - -```text -MATCH (n) -RETURN DISTINCT labels(n) AS NodeTypes, count(*) AS Count -ORDER BY Count DESC; -``` - -To execute this query, write in the box on the top and select the blue run button. - -![alt text](image-2.png) - -Results will appear below. The information shown is downloaded from Stack Overflow and saved in the graph database. RAG will utilize this information to enhance its responses. - -You can also run the following query to visualize the data: - -```text -CALL db.schema.visualization() -``` - -To check the relationships in the database, run the following query: - -```text -CALL db.relationshipTypes() -``` - -You're ready to enable the LLM to use this information. Go back to [http://localhost:8501/](http://localhost:8501/), enable the **RAG** checkbox, and ask the same question again. The LLM will provide a more detailed answer. - -![alt text](image-3.png) - -The system delivers comprehensive, accurate information by pulling from current technical documentation. -```text -Question: What is Apache Nifi? -RAG: Enabled - -Answer: -Apache NiFi is an open-source, distributed data processing system that allows you to collect, transform, and transport data across various sources and sinks. It provides a graphical user interface for designing and managing data flows, as well as a set of APIs for integrating with other systems. -According to this Stack Overflow question, the free Neo4J JDBC driver doesn't understand SQL, only Cypher, so you would need to use a non-free BI Connector to connect to Neo4j from Apache Drill. -Additionally, this Stack Overflow question suggests that Apache POI does work in a Neo4j User Defined Function. However, there may be an unknown glitch in the standalone UDF mentioned in the initial question. -To export data from Neo4j to Excel using APOC Extended procedures, you can use apoc.export.xls.query which takes a Cypher query and exports the results to an Excel file. - -References: -How to connect and query Neo4j Database on Apache Drill? -Is a Neo4j UDF compatible with Apache POI? -``` - -Keep in mind that new questions will be added to Stack Overflow, and due to the inherent randomness in most AI models, the answers may vary and won't be identical to those in this example. - -Feel free to start over with another [Stack Overflow tag](https://stackoverflow.com/tags). To drop all data in Neo4j, you can use the following command in the Neo4j Web UI: - -```txt -MATCH (n) -DETACH DELETE n; -``` - -For optimal results, choose a tag that the LLM is not familiar with. - -### When to leverage RAG for optimal results - -Retrieval-Augmented Generation (RAG) is particularly effective in scenarios where standard Large Language Models (LLMs) fall short. The three key areas where RAG excels are knowledge limitations, business requirements, and cost efficiency. The following sections explore these aspects in more detail. - -#### Overcoming knowledge limitations - -LLMs are trained on a fixed dataset up until a certain point in time. This means they lack access to: - -* Real-time information: LLMs do not continuously update their knowledge, so they may not be aware of recent events, newly released research, or emerging technologies. -* Specialized knowledge: Many niche subjects, proprietary frameworks, or industry-specific best practices may not be well-documented in the model’s training corpus. -* Accurate contextual understanding: LLMs can struggle with nuances or evolving terminologies that frequently change within dynamic fields like finance, cybersecurity, or medical research. - -By incorporating RAG with a graph database such as Neo4j, AI models can access and retrieve the latest, relevant, and highly connected data before generating a response. This ensures that answers are up-to-date and grounded in factual information rather than inferred approximations. - -#### Addressing business and compliance needs - -Organizations in industries like healthcare, legal services, and financial analysis require their AI-driven solutions to be: - -* Accurate: Businesses need AI-generated content that is factual and relevant to their specific domain. -* Compliant: Many industries must adhere to strict regulations regarding data usage and security. -* Traceable: Enterprises often require AI responses to be auditable, meaning they need to reference source material. - -By using RAG, AI-generated answers can be sourced from trusted databases, ensuring higher accuracy and compliance with industry standards. This mitigates risks such as misinformation or regulatory violations. - -#### Enhancing cost efficiency and performance - -Training and fine-tuning large AI models can be computationally expensive and time-consuming. However, integrating RAG provides: - -* Reduced fine-tuning needs: Instead of retraining an AI model every time new data emerges, RAG allows the model to fetch and incorporate updated information dynamically. -* Better performance with smaller models: With the right retrieval techniques, even compact AI models can perform well by leveraging external knowledge efficiently. -* Lower operational costs: Instead of investing in expensive infrastructure to support large-scale retraining, businesses can optimize resources by utilizing RAG’s real-time retrieval capabilities. - -By following this guide, you now have the foundational knowledge to implement RAG with Neo4j, enabling your AI system to deliver more accurate, relevant, and insightful responses. The next step is experimentation—choose a dataset, configure your stack, and start enhancing your AI with the power of retrieval-augmented generation. \ No newline at end of file diff --git a/content/guides/genai-pdf-bot/_index.md b/content/guides/genai-pdf-bot/_index.md deleted file mode 100644 index 41c5e16626e7..000000000000 --- a/content/guides/genai-pdf-bot/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: PDF analysis and chat -description: Containerize generative AI (GenAI) apps using Docker -keywords: python, generative ai, genai, llm, neo4j, ollama, langchain -summary: | - Learn how to build a PDF bot for parsing PDF documents and generating - responses using Docker and generative AI. -tags: [ai] -aliases: - - /guides/use-case/genai-pdf-bot/ -params: - time: 20 minutes ---- - -The generative AI (GenAI) guide teaches you how to containerize an existing GenAI application using Docker. In this guide, you’ll learn how to: - -- Containerize and run a Python-based GenAI application -- Set up a local environment to run the complete GenAI stack locally for development - -Start by containerizing an existing GenAI application. diff --git a/content/guides/genai-pdf-bot/containerize.md b/content/guides/genai-pdf-bot/containerize.md deleted file mode 100644 index 93aed280e965..000000000000 --- a/content/guides/genai-pdf-bot/containerize.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: Containerize a generative AI application -linkTitle: Containerize your app -weight: 10 -keywords: python, generative ai, genai, llm, neo4j, ollama, containerize, initialize, langchain, openai -description: Learn how to containerize a generative AI (GenAI) application. -aliases: - - /guides/use-case/genai-pdf-bot/containerize/ ---- - -## Prerequisites - -> [!NOTE] -> -> GenAI applications can often benefit from GPU acceleration. Currently Docker Desktop supports GPU acceleration only on [Windows with the WSL2 backend](/manuals/desktop/features/gpu.md#using-nvidia-gpus-with-wsl2). Linux users can also access GPU acceleration using a native installation of the [Docker Engine](/manuals/engine/install/_index.md). - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md) or, if you are a Linux user and are planning to use GPU acceleration, [Docker Engine](/manuals/engine/install/_index.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -## Overview - -This section walks you through containerizing a generative AI (GenAI) application using Docker Desktop. - -> [!NOTE] -> -> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. - -## Get the sample application - -The sample application used in this guide is a modified version of the PDF Reader application from the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. The application is a full stack Python application that lets you ask questions about a PDF file. - -The application uses [LangChain](https://www.langchain.com/) for orchestration, [Streamlit](https://streamlit.io/) for the UI, [Ollama](https://ollama.ai/) to run the LLM, and [Neo4j](https://neo4j.com/) to store vectors. - -Clone the sample application. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/craig-osterhout/docker-genai-sample -``` - -You should now have the following files in your `docker-genai-sample` directory. - -```text -├── docker-genai-sample/ -│ ├── .gitignore -│ ├── app.py -│ ├── chains.py -│ ├── env.example -│ ├── requirements.txt -│ ├── util.py -│ ├── LICENSE -│ └── README.md -``` - -## Create Docker assets - -Now that you have an application, you can create the necessary Docker assets to -containerize it. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -Create the following files in your `docker-genai-sample` directory. - -```dockerfile {collapse=true,title=Dockerfile} -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -ARG PYTHON_VERSION=3.11.4 -FROM python:${PYTHON_VERSION}-slim as base - -# Prevents Python from writing pyc files. -ENV PYTHONDONTWRITEBYTECODE=1 - -# Keeps Python from buffering stdout and stderr to avoid situations where -# the application crashes without emitting any logs due to buffering. -ENV PYTHONUNBUFFERED=1 - -WORKDIR /app - -# Create a non-privileged user that the app will run under. -# See https://docs.docker.com/go/dockerfile-user-best-practices/ -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them into -# into this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - python -m pip install -r requirements.txt - -# Switch to the non-privileged user to run the application. -USER appuser - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0", "--server.port=8000"] -``` - -```yaml {collapse=true,title=compose.yaml} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - ports: - - 8000:8000 - -# The commented out section below is an example of how to define a PostgreSQL -# database that your application can use. `depends_on` tells Docker Compose to -# start the database before your application. The `db-data` volume persists the -# database data between container restarts. The `db-password` secret is used -# to set the database password. You must create `db/password.txt` and add -# a password of your choosing to it before running `docker compose up`. -# depends_on: -# db: -# condition: service_healthy -# db: -# image: postgres -# restart: always -# user: postgres -# secrets: -# - db-password -# volumes: -# - db-data:/var/lib/postgresql/data -# environment: -# - POSTGRES_DB=example -# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password -# expose: -# - 5432 -# healthcheck: -# test: [ "CMD", "pg_isready" ] -# interval: 10s -# timeout: 5s -# retries: 5 -# volumes: -# db-data: -# secrets: -# db-password: -# file: db/password.txt -``` - -```text {collapse=true,title=".dockerignore"} -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` - -You should now have the following contents in your `docker-genai-sample` -directory. - -```text -├── docker-genai-sample/ -│ ├── .dockerignore -│ ├── .gitignore -│ ├── app.py -│ ├── chains.py -│ ├── compose.yaml -│ ├── env.example -│ ├── requirements.txt -│ ├── util.py -│ ├── Dockerfile -│ ├── LICENSE -│ └── README.md -``` - -To learn more about these files, see the following: - -- [Dockerfile](../../../reference/dockerfile.md) -- [.dockerignore](../../../reference/dockerfile.md#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `docker-genai-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Docker builds and runs your application. Depending on your network connection, it may take several minutes to download all the dependencies. You'll see a message like the following in the terminal when the application is running. - -```console -server-1 | You can now view your Streamlit app in your browser. -server-1 | -server-1 | URL: http://0.0.0.0:8000 -server-1 | -``` - -Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You should see a simple Streamlit application. The application may take a few minutes to download the embedding model. While the download is in progress, **Running** appears in the top-right corner. - -The application requires a Neo4j database service and an LLM service to -function. If you have access to services that you ran outside of Docker, specify -the connection information and try it out. If you don't have the services -running, continue with this guide to learn how you can run some or all of these -services with Docker. - -In the terminal, press `ctrl`+`c` to stop the application. - -## Summary - -In this section, you learned how you can containerize and run your GenAI -application using Docker. - -## Next steps - -In the next section, you'll learn how you can run your application, database, and LLM service all locally using Docker. diff --git a/content/guides/genai-pdf-bot/develop.md b/content/guides/genai-pdf-bot/develop.md deleted file mode 100644 index 7a0dcae854ed..000000000000 --- a/content/guides/genai-pdf-bot/develop.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Use containers for generative AI development -linkTitle: Develop your app -weight: 20 -keywords: python, local, development, generative ai, genai, llm, neo4j, ollama, langchain, openai -description: Learn how to develop your generative AI (GenAI) application locally. -aliases: - - /guides/use-case/genai-pdf-bot/develop/ ---- - -## Prerequisites - -Complete [Containerize a generative AI application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment to access all the services that your generative AI (GenAI) application needs. This includes: - -- Adding a local database -- Adding a local or remote LLM service - -> [!NOTE] -> -> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. - -## Add a local database - -You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service. In addition, you'll specify an environment variables file to load the database connection information rather than manually entering the information every time. - -To run the database service: - -1. In the cloned repository's directory, rename `env.example` file to `.env`. - This file contains the environment variables that the containers will use. -2. In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. -3. In the `compose.yaml` file, add the following: - - - Add instructions to run a Neo4j database - - Specify the environment file under the server service in order to pass in the environment variables for the connection - - The following is the updated `compose.yaml` file. All comments have been removed. - - ```yaml{hl_lines=["7-23"]} - services: - server: - build: - context: . - ports: - - 8000:8000 - env_file: - - .env - depends_on: - database: - condition: service_healthy - database: - image: neo4j:5.11 - ports: - - "7474:7474" - - "7687:7687" - environment: - - NEO4J_AUTH=${NEO4J_USERNAME}/${NEO4J_PASSWORD} - healthcheck: - test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider localhost:7474 || exit 1"] - interval: 5s - timeout: 3s - retries: 5 - ``` - - > [!NOTE] - > - > To learn more about Neo4j, see the [Neo4j Official Docker Image](https://hub.docker.com/_/neo4j). - -4. Run the application. Inside the `docker-genai-sample` directory, - run the following command in a terminal. - - ```console - $ docker compose up --build - ``` - -5. Access the application. Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You should see a simple Streamlit application. Note that asking questions to a PDF will cause the application to fail because the LLM service specified in the `.env` file isn't running yet. - -6. Stop the application. In the terminal, press `ctrl`+`c` to stop the application. - -## Add a local or remote LLM service - -The sample application supports both [Ollama](https://ollama.ai/) and [OpenAI](https://openai.com/). This guide provides instructions for the following scenarios: - -- Run Ollama in a container -- Run Ollama outside of a container -- Use OpenAI - -While all platforms can use any of the previous scenarios, the performance and -GPU support may vary. You can use the following guidelines to help you choose the appropriate option: - -- Run Ollama in a container if you're on Linux, and using a native installation of the Docker Engine, or Windows 10/11, and using Docker Desktop, you - have a CUDA-supported GPU, and your system has at least 8 GB of RAM. -- Run Ollama outside of a container if you're on an Apple silicon Mac. -- Use OpenAI if the previous two scenarios don't apply to you. - -Choose one of the following options for your LLM service. - -{{< tabs >}} -{{< tab name="Run Ollama in a container" >}} - -When running Ollama in a container, you should have a CUDA-supported GPU. While you can run Ollama in a container without a supported GPU, the performance may not be acceptable. Only Linux and Windows 11 support GPU access to containers. - -To run Ollama in a container and provide GPU access: - -1. Install the prerequisites. - - For Docker Engine on Linux, install the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-container-toolkit). - - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/features/wsl/_index.md#turn-on-docker-desktop-wsl-2) -2. Add the Ollama service and a volume in your `compose.yaml`. The following is - the updated `compose.yaml`: - - ```yaml {hl_lines=["24-38"]} - services: - server: - build: - context: . - ports: - - 8000:8000 - env_file: - - .env - depends_on: - database: - condition: service_healthy - database: - image: neo4j:5.11 - ports: - - "7474:7474" - - "7687:7687" - environment: - - NEO4J_AUTH=${NEO4J_USERNAME}/${NEO4J_PASSWORD} - healthcheck: - test: - [ - "CMD-SHELL", - "wget --no-verbose --tries=1 --spider localhost:7474 || exit 1", - ] - interval: 5s - timeout: 3s - retries: 5 - ollama: - image: ollama/ollama:latest - ports: - - "11434:11434" - volumes: - - ollama_volume:/root/.ollama - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: all - capabilities: [gpu] - volumes: - ollama_volume: - ``` - - > [!NOTE] - > - > For more details about the Compose instructions, see [Turn on GPU access with Docker Compose](/manuals/compose/how-tos/gpu-support.md). - -3. Add the ollama-pull service to your `compose.yaml` file. This service uses - the `docker/genai:ollama-pull` image, based on the GenAI Stack's - [pull_model.Dockerfile](https://github.com/docker/genai-stack/blob/main/pull_model.Dockerfile). - The service will automatically pull the model for your Ollama - container. The following is the updated section of the `compose.yaml` file: - - ```yaml {hl_lines=["12-17"]} - services: - server: - build: - context: . - ports: - - 8000:8000 - env_file: - - .env - depends_on: - database: - condition: service_healthy - ollama-pull: - condition: service_completed_successfully - ollama-pull: - image: docker/genai:ollama-pull - env_file: - - .env - # ... - ``` - -{{< /tab >}} -{{< tab name="Run Ollama outside of a container" >}} - -To run Ollama outside of a container: - -1. [Install](https://github.com/jmorganca/ollama) and run Ollama on your host - machine. -2. Update the `OLLAMA_BASE_URL` value in your `.env` file to - `http://host.docker.internal:11434`. -3. Pull the model to Ollama using the following command. - ```console - $ ollama pull llama2 - ``` - -{{< /tab >}} -{{< tab name="Use OpenAI" >}} - -> [!IMPORTANT] -> -> Using OpenAI requires an [OpenAI account](https://platform.openai.com/login). OpenAI is a third-party hosted service and charges may apply. - -1. Update the `LLM` value in your `.env` file to - `gpt-3.5`. -2. Uncomment and update the `OPENAI_API_KEY` value in your `.env` file to - your [OpenAI API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-api-key). - -{{< /tab >}} -{{< /tabs >}} - -## Run your GenAI application - -At this point, you have the following services in your Compose file: - -- Server service for your main GenAI application -- Database service to store vectors in a Neo4j database -- (optional) Ollama service to run the LLM -- (optional) Ollama-pull service to automatically pull the model for the Ollama - service - -To run all the services, run the following command in your `docker-genai-sample` -directory: - -```console -$ docker compose up --build -``` - -If your Compose file has the ollama-pull service, it may take several minutes for the ollama-pull service to pull the model. The ollama-pull service will continuously update the console with its status. After pulling the model, the ollama-pull service container will stop and you can access the application. - -Once the application is running, open a browser and access the application at [http://localhost:8000](http://localhost:8000). - -Upload a PDF file, for example the [Docker CLI Cheat Sheet](https://docs.docker.com/get-started/docker_cheatsheet.pdf), and ask a question about the PDF. - -Depending on your system and the LLM service that you chose, it may take several -minutes to answer. If you are using Ollama and the performance isn't -acceptable, try using OpenAI. - -## Summary - -In this section, you learned how to set up a development environment to provide -access all the services that your GenAI application needs. - -Related information: - -- [Dockerfile reference](../../../reference/dockerfile.md) -- [Compose file reference](/reference/compose-file/_index.md) -- [Ollama Docker image](https://hub.docker.com/r/ollama/ollama) -- [Neo4j Official Docker Image](https://hub.docker.com/_/neo4j) -- [GenAI Stack demo applications](https://github.com/docker/genai-stack) - -## Next steps - -See samples of more GenAI applications in the [GenAI Stack demo applications](https://github.com/docker/genai-stack). diff --git a/content/guides/genai-video-bot/images/architecture.webp b/content/guides/genai-video-bot/images/architecture.webp deleted file mode 100644 index 05e0b3c254d6..000000000000 Binary files a/content/guides/genai-video-bot/images/architecture.webp and /dev/null differ diff --git a/content/guides/genai-video-bot/images/bot.webp b/content/guides/genai-video-bot/images/bot.webp deleted file mode 100644 index c3e8d32ff5c1..000000000000 Binary files a/content/guides/genai-video-bot/images/bot.webp and /dev/null differ diff --git a/content/guides/genai-video-bot/images/embeddings.webp b/content/guides/genai-video-bot/images/embeddings.webp deleted file mode 100644 index 13cccda60ba0..000000000000 Binary files a/content/guides/genai-video-bot/images/embeddings.webp and /dev/null differ diff --git a/content/guides/genai-video-bot/images/yt-whisper-2.webp b/content/guides/genai-video-bot/images/yt-whisper-2.webp deleted file mode 100644 index 9db9230fedbd..000000000000 Binary files a/content/guides/genai-video-bot/images/yt-whisper-2.webp and /dev/null differ diff --git a/content/guides/genai-video-bot/images/yt-whisper.webp b/content/guides/genai-video-bot/images/yt-whisper.webp deleted file mode 100644 index ef4c6f2d8075..000000000000 Binary files a/content/guides/genai-video-bot/images/yt-whisper.webp and /dev/null differ diff --git a/content/guides/genai-video-bot/index.md b/content/guides/genai-video-bot/index.md deleted file mode 100644 index a5d5b6497aca..000000000000 --- a/content/guides/genai-video-bot/index.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: GenAI video transcription and chat -linkTitle: Video transcription and chat -description: Explore a generative AI video analysis app that uses Docker, OpenAI, and Pinecone. -keywords: python, generative ai, genai, llm, whisper, pinecone, openai, whisper -summary: | - Learn how to build and deploy a generative AI video analysis and - transcription bot using Docker. -tags: [ai] -aliases: - - /guides/use-case/genai-video-bot/ -params: - time: 20 minutes ---- - -## Overview - -This guide presents a project on video transcription and analysis using a set of -technologies related to the -[GenAI Stack](https://www.docker.com/blog/introducing-a-new-genai-stack/). - -The project showcases the following technologies: - -- [Docker and Docker Compose](#docker-and-docker-compose) -- [OpenAI](#openai-api) -- [Whisper](#whisper) -- [Embeddings](#embeddings) -- [Chat completions](#chat-completions) -- [Pinecone](#pinecone) -- [Retrieval-Augmented Generation](#retrieval-augmented-generation) - -> **Acknowledgment** -> -> This guide is a community contribution. Docker would like to thank -> [David Cardozo](https://www.davidcardozo.com/) for his contribution -> to this guide. - -## Prerequisites - -- You have an [OpenAI API Key](https://platform.openai.com/api-keys). - - > [!NOTE] - > - > OpenAI is a third-party hosted service and [charges](https://openai.com/pricing) may apply. - -- You have a [Pinecone API Key](https://app.pinecone.io/). -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## About the application - -The application is a chatbot that can answer questions from a video. In -addition, it provides timestamps from the video that can help you find the sources used to answer your question. - -## Get and run the application - -1. Clone the sample application's repository. In a terminal, run the following - command. - - ```console - $ git clone https://github.com/Davidnet/docker-genai.git - ``` - - The project contains the following directories and files: - - ```text - ├── docker-genai/ - │ ├── docker-bot/ - │ ├── yt-whisper/ - │ ├── .env.example - │ ├── .gitignore - │ ├── LICENSE - │ ├── README.md - │ └── docker-compose.yaml - ``` - -2. Specify your API keys. In the `docker-genai` directory, create a text file - called `.env` and specify your API keys inside. The following is the contents of the `.env.example` file that you can refer to as an example. - - ```text - #---------------------------------------------------------------------------- - # OpenAI - #---------------------------------------------------------------------------- - OPENAI_TOKEN=your-api-key # Replace your-api-key with your personal API key - - #---------------------------------------------------------------------------- - # Pinecone - #---------------------------------------------------------------------------- - PINECONE_TOKEN=your-api-key # Replace your-api-key with your personal API key - ``` - -3. Build and run the application. In a terminal, change directory to your - `docker-genai` directory and run the following command. - - ```console - $ docker compose up --build - ``` - - Docker Compose builds and runs the application based on the services defined - in the `docker-compose.yaml` file. When the application is running, you'll - see the logs of 2 services in the terminal. - - In the logs, you'll see the services are exposed on ports `8503` and `8504`. - The two services are complimentary to each other. - - The `yt-whisper` service is running on port `8503`. This service feeds the - Pinecone database with videos that you want to archive in your knowledge - database. The following section explores this service. - -## Using the yt-whisper service - -The yt-whisper service is a YouTube video processing service that uses the OpenAI -Whisper model to generate transcriptions of videos and stores them in a Pinecone -database. The following steps show how to use the service. - -1. Open a browser and access the yt-whisper service at [http://localhost:8503](http://localhost:8503). -2. Once the application appears, in the **Youtube URL** field specify a Youtube video URL - and select **Submit**. The following example uses - [https://www.youtube.com/watch?v=yaQZFhrW0fU](https://www.youtube.com/watch?v=yaQZFhrW0fU). - - ![Submitting a video in the yt-whisper service](images/yt-whisper.webp) - - The yt-whisper service downloads the audio of the video, uses Whisper to - transcribe it into a WebVTT (`*.vtt`) format (which you can download), then - uses the text-embedding-3-small model to create embeddings, and finally - uploads those embeddings in to the Pinecone database. - - After processing the video, a video list appears in the web app that informs - you which videos have been indexed in Pinecone. It also provides a button to - download the transcript. - - ![A processed video in the yt-whisper service](images/yt-whisper-2.webp) - - You can now access the dockerbot service on port `8504` and ask questions - about the videos. - -## Using the dockerbot service - -The dockerbot service is a question-answering service that leverages both the -Pinecone database and an AI model to provide responses. The following steps show -how to use the service. - -> [!NOTE] -> -> You must process at least one video via the -> [yt-whisper service](#using-the-yt-whisper-service) before using -> the dockerbot service. - -1. Open a browser and access the service at - [http://localhost:8504](http://localhost:8504). - -2. In the **What do you want to know about your videos?** text box, ask the - Dockerbot a question about a video that was processed by the yt-whisper - service. The following example asks the question, "What is a sugar cookie?". - The answer to that question exists in the video processed in the previous - example, - [https://www.youtube.com/watch?v=yaQZFhrW0fU](https://www.youtube.com/watch?v=yaQZFhrW0fU). - - ![Asking a question to the Dockerbot](images/bot.webp) - - In this example, the Dockerbot answers the question and - provides links to the video with timestamps, which may contain more - information about the answer. - - The dockerbot service takes the question, turns it into an embedding using - the text-embedding-3-small model, queries the Pinecone database to find - similar embeddings, and then passes that context into the gpt-4-turbo-preview - to generate an answer. - -3. Select the first link to see what information it provides. Based on the - previous example, select - [https://www.youtube.com/watch?v=yaQZFhrW0fU&t=553s](https://www.youtube.com/watch?v=yaQZFhrW0fU&t=553s). - - In the example link, you can see that the section of video perfectly answers - the question, "What is a sugar cookie?". - -## Explore the application architecture - -The following image shows the application's high-level service architecture, which includes: - -- yt-whisper: A local service, ran by Docker Compose, that interacts with the - remote OpenAI and Pinecone services. -- dockerbot: A local service, ran by Docker Compose, that interacts with the - remote OpenAI and Pinecone services. -- OpenAI: A remote third-party service. -- Pinecone: A remote third-party service. - -![Application architecture diagram](images/architecture.webp) - -## Explore the technologies used and their role - -### Docker and Docker Compose - -The application uses Docker to run the application in containers, providing a -consistent and isolated environment for running it. This means the application -will operate as intended within its Docker containers, regardless of the -underlying system differences. To learn more about Docker, see the [Getting started overview](/get-started/introduction/_index.md). - -Docker Compose is a tool for defining and running multi-container applications. -Compose makes it easy to run this application with a single command, `docker -compose up`. For more details, see the [Compose overview](/manuals/compose/_index.md). - -### OpenAI API - -The OpenAI API provides an LLM service that's known for its cutting-edge AI and -machine learning technologies. In this application, OpenAI's technology is used -to generate transcriptions from audio (using the Whisper model) and to create -embeddings for text data, as well as to generate responses to user queries -(using GPT and chat completions). For more details, see -[openai.com](https://openai.com/product). - -### Whisper - -Whisper is an automatic speech recognition system developed by OpenAI, designed -to transcribe spoken language into text. In this application, Whisper is used to -transcribe the audio from YouTube videos into text, enabling further processing -and analysis of the video content. For more details, see [Introducing Whisper](https://openai.com/research/whisper). - -### Embeddings - -Embeddings are numerical representations of text or other data types, which -capture their meaning in a way that can be processed by machine learning -algorithms. In this application, embeddings are used to convert video -transcriptions into a vector format that can be queried and analyzed for -relevance to user input, facilitating efficient search and response generation -in the application. For more details, see OpenAI's -[Embeddings](https://platform.openai.com/docs/guides/embeddings) documentation. - -![Embedding diagram](images/embeddings.webp) - -### Chat completions - -Chat completion, as utilized in this application through OpenAI's API, refers to -the generation of conversational responses based on a given context or prompt. -In the application, it is used to provide intelligent, context-aware answers to -user queries by processing and integrating information from video transcriptions -and other inputs, enhancing the chatbot's interactive capabilities. For more -details, see OpenAI's -[Chat Completions API](https://platform.openai.com/docs/guides/text-generation) documentation. - -### Pinecone - -Pinecone is a vector database service optimized for similarity search, used for -building and deploying large-scale vector search applications. In this -application, Pinecone is employed to store and retrieve the embeddings of video -transcriptions, enabling efficient and relevant search functionality within the -application based on user queries. For more details, see -[pincone.io](https://www.pinecone.io/). - -### Retrieval-Augmented Generation - -Retrieval-Augmented Generation (RAG) is a technique that combines information -retrieval with a language model to generate responses based on retrieved -documents or data. In RAG, the system retrieves relevant information (in this -case, via embeddings from video transcriptions) and then uses a language model -to generate responses based on this retrieved data. For more details, see -OpenAI's cookbook for -[Retrieval Augmented Generative Question Answering with Pinecone](https://cookbook.openai.com/examples/vector_databases/pinecone/gen_qa). - -## Next steps - -Explore how to [create a PDF bot application](/guides/genai-pdf-bot/_index.md) using -generative AI, or view more GenAI samples in the -[GenAI Stack](https://github.com/docker/genai-stack) repository. diff --git a/content/guides/gha.md b/content/guides/gha.md index ec61aeeacad7..b284a2a3529c 100644 --- a/content/guides/gha.md +++ b/content/guides/gha.md @@ -5,7 +5,7 @@ summary: | Learn how to automate image build and push with GitHub Actions. keywords: github actions, ci/cd, docker hub, build and push, automation, workflows params: - tags: [devops] + tags: [cicd] time: 10 minutes --- @@ -52,7 +52,7 @@ that, you must authenticate with your Docker credentials (username and access token) as part of the GitHub Actions workflow. For instructions on how to create a Docker access token, see -[Create and manage access tokens](/manuals/security/access-tokens.md). +[Create and manage access tokens](/manuals/security/access-tokens/personal-access-tokens.md). Once you have your Docker credentials ready, add the credentials to your GitHub repository so you can use them in GitHub Actions: @@ -252,5 +252,6 @@ additional features based on your project's needs, such as ### Further reading - Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section. -- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/index.md).) -- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/guides/docker-build-cloud/_index.md). +- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/).) + +- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/manuals/build-cloud/_index.md). diff --git a/content/guides/github-sonarqube-sandbox/_index.md b/content/guides/github-sonarqube-sandbox/_index.md deleted file mode 100644 index 90d0684a2e05..000000000000 --- a/content/guides/github-sonarqube-sandbox/_index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: How to build an AI-powered code quality workflow with SonarQube and E2B -linkTitle: AI-powered code quality -summary: Build AI-powered code quality workflows using E2B sandboxes with Docker's MCP catalog to automate GitHub and SonarQube integration. -description: Learn how to create E2B sandboxes with MCP servers, analyze code quality with SonarQube, and generate quality-gated pull requests using GitHub—all through natural language interactions with Claude. -keywords: sonarqube, e2b, sandboxes, mcp, github, code quality, ai workflow, claude -tags: [devops] -params: - time: 40 minutes - image: - resource_links: - - title: E2B Documentation - url: https://e2b.dev/docs - - title: Docker MCP Catalog - url: https://hub.docker.com/mcp - - title: Sandboxes - url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/sandboxes/ ---- - -This guide demonstrates how to build an AI-powered code quality workflow using -[E2B sandboxes](https://e2b.dev/docs) with Docker’s MCP catalog. You’ll create -a system that automatically analyzes code quality issues in GitHub repositories -using SonarQube, then generate pull requests with fixes. - -## What you'll build - -You’ll build a Node.js script that spins up an E2B sandbox, connects GitHub and -SonarQube MCP servers, and uses Claude Code to analyze code quality and propose -improvements. The MCP servers are containerized and run as part of the E2B -sandbox. - -## What you'll learn - -In this guide, you'll learn: - -- How to create E2B sandboxes with multiple MCP servers -- How to configure GitHub and SonarQube MCP servers for AI workflows -- How to use Claude Code inside sandboxes to interact with external tools -- How to build automated code review workflows that create quality-gated -pull requests - -## Why use E2B sandboxes? - -Running this workflow in E2B sandboes provides several advantages over -local execution: - -- Security: AI-generated code runs in isolated containers, protecting your -local environment and credentials -- Zero setup: No need to install SonarQube, GitHub CLI, or manage dependencies -locally -- Scalability: Resource-intensive operations like code scanning run in the -cloud without consuming local resources - -## Learn more - -Read Docker's blog post: [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/). diff --git a/content/guides/github-sonarqube-sandbox/customize.md b/content/guides/github-sonarqube-sandbox/customize.md deleted file mode 100644 index 832ad51a2e14..000000000000 --- a/content/guides/github-sonarqube-sandbox/customize.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Customize a code quality check workflow -linkTitle: Customize workflow -summary: Adapt your GitHub and SonarQube workflow to focus on specific quality issues, integrate with CI/CD, and set custom thresholds. -description: Learn how to customize prompts for specific quality issues, filter by file patterns, set quality thresholds, and integrate your workflow with GitHub Actions for automated code quality checks. -keywords: sonarqube, e2b, mcp, github actions, code quality, customization, ci/cd -weight: 20 ---- - -Now that you understand the basics of automating code quality workflows with -GitHub and SonarQube in E2B sandboxes, you can customize the workflow -for your needs. - -## Focus on specific quality issues - -Modify the prompt to prioritize certain issue types: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```typescript -const prompt = `Using SonarQube and GitHub MCP tools: - -Focus only on: -- Security vulnerabilities (CRITICAL priority) -- Bugs (HIGH priority) -- Skip code smells for this iteration - -Analyze "${repoPath}" and fix the highest priority issues first.`; -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```python -prompt = f"""Using SonarQube and GitHub MCP tools: - -Focus only on: -- Security vulnerabilities (CRITICAL priority) -- Bugs (HIGH priority) -- Skip code smells for this iteration - -Analyze "{repo_path}" and fix the highest priority issues first.""" -``` - -{{< /tab >}} -{{< /tabs >}} - -## Integrate with CI/CD - -Add this workflow to GitHub Actions to run automatically on pull requests: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```yaml -name: Automated quality checks -on: - pull_request: - types: [opened, synchronize] - -jobs: - quality: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@{{% param "checkout_action_version" %}} - - uses: actions/setup-node@v5 - with: - node-version: "24" - - run: npm install - - run: npx tsx 06-quality-gated-pr.ts - env: - E2B_API_KEY: ${{ secrets.E2B_API_KEY }} - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }} - GITHUB_OWNER: ${{ github.repository_owner }} - GITHUB_REPO: ${{ github.event.repository.name }} - SONARQUBE_ORG: your-org-key -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```yaml -name: Automated quality checks -on: - pull_request: - types: [opened, synchronize] - -jobs: - quality: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@{{% param "checkout_action_version" %}} - - uses: actions/setup-python@v6 - with: - python-version: "3.14" - - run: pip install e2b python-dotenv - - run: python 06_quality_gated_pr.py - env: - E2B_API_KEY: ${{ secrets.E2B_API_KEY }} - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }} - GITHUB_OWNER: ${{ github.repository_owner }} - GITHUB_REPO: ${{ github.event.repository.name }} - SONARQUBE_ORG: your-org-key -``` - -{{< /tab >}} -{{< /tabs >}} - -## Filter by file patterns - -Target specific parts of your codebase: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```typescript -const prompt = `Analyze code quality but only consider: -- Files in src/**/*.js -- Exclude test files (*.test.js, *.spec.js) -- Exclude build artifacts in dist/ - -Focus on production code only.`; -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```python -prompt = """Analyze code quality but only consider: -- Files in src/**/*.js -- Exclude test files (*.test.js, *.spec.js) -- Exclude build artifacts in dist/ - -Focus on production code only.""" -``` - -{{< /tab >}} -{{< /tabs >}} - -## Set quality thresholds - -Define when PRs should be created: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```typescript -const prompt = `Quality gate thresholds: -- Only create PR if: - * Bug count decreases by at least 1 - * No new security vulnerabilities introduced - * Code coverage does not decrease - * Technical debt reduces by at least 15 minutes - -If changes do not meet these thresholds, explain why and skip PR creation.`; -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```python -prompt = """Quality gate thresholds: -- Only create PR if: - * Bug count decreases by at least 1 - * No new security vulnerabilities introduced - * Code coverage does not decrease - * Technical debt reduces by at least 15 minutes - -If changes do not meet these thresholds, explain why and skip PR creation.""" -``` - -{{< /tab >}} -{{< /tabs >}} - -## Next steps - -Learn how to troubleshoot common issues. diff --git a/content/guides/github-sonarqube-sandbox/troubleshoot.md b/content/guides/github-sonarqube-sandbox/troubleshoot.md deleted file mode 100644 index 6ea50554acb0..000000000000 --- a/content/guides/github-sonarqube-sandbox/troubleshoot.md +++ /dev/null @@ -1,334 +0,0 @@ ---- -title: Troubleshoot code quality workflows -linkTitle: Troubleshoot -summary: Resolve common issues with E2B sandboxes, MCP server connections, and GitHub/SonarQube integration. -description: Solutions for MCP tools not loading, authentication errors, permission issues, workflow timeouts, and other common problems when building code quality workflows with E2B. -keywords: sonarqube, e2b, mcp, troubleshooting, debugging, authentication, code quality -weight: 30 ---- - -This page covers common issues you might encounter when building code quality -workflows with E2B sandboxes and MCP servers, along with their solutions. - -If you're experiencing problems not covered here, check the -[E2B documentation](https://e2b.dev/docs). - -## MCP tools not available - -Issue: Claude reports `I don't have any MCP tools available`. - -Solution: - -1. Verify you're using the authorization header: - - ```plaintext - --header "Authorization: Bearer ${mcpToken}" - ``` - -2. Check you're waiting for MCP initialization. - - ```typescript - // typescript - await new Promise((resolve) => setTimeout(resolve, 1000)); - ``` - - ```python - # python - await asyncio.sleep(1) - ``` - -3. Ensure credentials are in both `envs` and `mcp` configuration: - - ```typescript - // typescript - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - ``` - - ```python - # python - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - ``` - -4. Verify your API tokens are valid and have proper scopes. - -## GitHub tools work but SonarQube doesn't - -Issue: GitHub MCP tools load but SonarQube tools don't appear. - -Solution: SonarQube MCP server requires GitHub to be configured simultaneously. -Always include both servers in your sandbox configuration, even if you're only -testing one. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```typescript -// Include both servers even if only using one -const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, -}); -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```python -# Include both servers even if only using one -sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, -) -``` - -{{< /tab >}} -{{< /tabs >}} - -## Claude can't access private repositories - -Issue: "I don't have access to that repository". - -Solution: - -1. Verify your GitHub token has `repo` scope (not just `public_repo`). -2. Test with a public repository first. -3. Ensure the repository owner and name are correct in your `.env`: - - {{< tabs group="language" >}} - {{< tab name="TypeScript" >}} - - ```plaintext - GITHUB_OWNER=your_github_username - GITHUB_REPO=your_repository_name - ``` - - {{< /tab >}} - {{< tab name="Python" >}} - - ```plaintext - GITHUB_OWNER=your_github_username - GITHUB_REPO=your_repository_name - ``` - - {{< /tab >}} - {{< /tabs >}} - -## Workflow times out or runs too long - -Issue: Workflow doesn't complete or Claude credits run out. - -Solutions: - -1. Use `timeoutMs: 0` (TypeScript) or `timeout_ms=0` (Python) for complex workflows to allow unlimited time: - - {{< tabs group="language" >}} - {{< tab name="TypeScript" >}} - - ```typescript - await sbx.commands.run( - `echo '${prompt}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, // No timeout - onStdout: console.log, - onStderr: console.log, - }, - ); - ``` - - {{< /tab >}} - {{< tab name="Python" >}} - - ```python - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout_ms=0, # No timeout - on_stdout=print, - on_stderr=print, - ) - ``` - - {{< /tab >}} - {{< /tabs >}} - -2. Break complex workflows into smaller, focused tasks. -3. Monitor your Anthropic API credit usage. -4. Add checkpoints in prompts: "After each step, show progress before continuing". - -## Sandbox cleanup errors - -Issue: Sandboxes aren't being cleaned up properly, leading to resource exhaustion. - -Solution: Always use proper error handling with cleanup in the `finally` block: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -```typescript -async function robustWorkflow() { - let sbx: Sandbox | undefined; - - try { - sbx = await Sandbox.betaCreate({ - // ... configuration - }); - - // ... workflow logic - } catch (error) { - console.error("Workflow failed:", error); - process.exit(1); - } finally { - if (sbx) { - console.log("Cleaning up sandbox..."); - await sbx.kill(); - } - } -} -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -```python -async def robust_workflow(): - sbx = None - - try: - sbx = await AsyncSandbox.beta_create( - # ... configuration - ) - - # ... workflow logic - - except Exception as error: - print(f"Workflow failed: {error}") - sys.exit(1) - finally: - if sbx: - print("Cleaning up sandbox...") - await sbx.kill() -``` - -{{< /tab >}} -{{< /tabs >}} - -## Environment variable not loading - -Issue: Script fails with "undefined" or "None" for environment variables. - -Solution: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -1. Ensure `dotenv` is loaded at the top of your file: - - ```typescript - import "dotenv/config"; - ``` - -2. Verify the `.env` file is in the same directory as your script. - -3. Check variable names match exactly (case-sensitive): - - ```typescript - // .env file - GITHUB_TOKEN = ghp_xxxxx; - - // In code - process.env.GITHUB_TOKEN; // Correct - process.env.github_token; // Wrong - case doesn't match - ``` - - {{< /tab >}} - {{< tab name="Python" >}} - 1. Ensure `dotenv` is loaded at the top of your file: - - ```python - from dotenv import load_dotenv - load_dotenv() - ``` - - 2. Verify the `.env` file is in the same directory as your script. - - 3. Check variable names match exactly (case-sensitive): - - ```python - # .env file - GITHUB_TOKEN=ghp_xxxxx - - # In code - os.getenv("GITHUB_TOKEN") # Correct - os.getenv("github_token") # Wrong - case doesn't match - ``` - - {{< /tab >}} - {{< /tabs >}} - -## SonarQube returns empty results - -Issue: SonarQube analysis returns no projects or issues. - -Solution: - -1. Verify your SonarCloud organization key is correct. -2. Ensure you have at least one project configured in SonarCloud. -3. Check that your SonarQube token has the necessary permissions. -4. Confirm your project has been analyzed at least once in SonarCloud. diff --git a/content/guides/github-sonarqube-sandbox/workflow.md b/content/guides/github-sonarqube-sandbox/workflow.md deleted file mode 100644 index 7268e31eb1fc..000000000000 --- a/content/guides/github-sonarqube-sandbox/workflow.md +++ /dev/null @@ -1,1588 +0,0 @@ ---- -title: Build a code quality check workflow -linkTitle: Build workflow -summary: Learn to use GitHub and SonarQube MCP servers in E2B sandboxes through progressive examples. -description: Create E2B sandboxes, discover MCP tools, test individual operations, and build complete quality-gated PR workflows. -keywords: sonarqube, e2b, mcp, github, code quality, pull requests, workflow -weight: 10 ---- - -In this section, you'll build a complete code quality automation workflow -step-by-step. You'll start by creating an E2B sandbox with GitHub and -SonarQube MCP servers, then progressively add functionality until you have a -production-ready workflow that analyzes code quality and creates pull requests. - -By working through each step sequentially, you'll learn how MCP servers work, -how to interact with them through Claude, and how to chain operations together -to build powerful automation workflows. - -## Prerequisites - -Before you begin, make sure you have: - -- E2B account with [API access](https://e2b.dev/docs/api-key) -- [Anthropic API key](https://docs.claude.com/en/api/admin-api/apikeys/get-api-key) - - > [!NOTE] - > - > This example uses Claude CLI which comes pre-installed in E2B sandboxes, but you can adapt the example to work with other AI assistants of your choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) for alternative connection methods. - -- GitHub account with: - - A repository containing code to analyze - - [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with `repo` scope -- SonarCloud account with: - - [Organization](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/resources-structure/organization) created - - [Project configured](https://docs.sonarsource.com/sonarqube-community-build/project-administration/creating-and-importing-projects) for your repository - - [User token](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/administering-tokens) generated -- Language runtime installed: - - TypeScript: [Node.js 18+](https://nodejs.org/en/download) - - Python: [Python 3.8+](https://www.python.org/downloads/) - -> [!NOTE] -> -> This guide uses Claude's `--dangerously-skip-permissions` flag to enable -> automated command execution in E2B sandboxes. This flag bypasses permission -> prompts, which is appropriate for isolated container environments like E2B -> where sandboxes are disposable and separate from your local machine. -> -> However, be aware that Claude can execute any commands within the sandbox, -> including accessing files and credentials available in that environment. Only -> use this approach with trusted code and workflows. For more information, -> see [Anthropic's guidance on container security](https://docs.anthropic.com/en/docs/claude-code/devcontainer). - -## Set up your project - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -1. Create a new directory for your workflow and initialize Node.js: - - ```bash - mkdir github-sonarqube-workflow - cd github-sonarqube-workflow - npm init -y - ``` - -2. Open `package.json` and configure it for ES modules: - - ```json - { - "name": "github-sonarqube-workflow", - "version": "1.0.0", - "description": "Automated code quality workflow using E2B, GitHub, and SonarQube", - "type": "module", - "main": "quality-workflow.ts", - "scripts": { - "start": "tsx quality-workflow.ts" - }, - "keywords": ["e2b", "github", "sonarqube", "mcp", "code-quality"], - "author": "", - "license": "MIT" - } - ``` - -3. Install required dependencies: - - ```bash - npm install e2b dotenv - npm install -D typescript tsx @types/node - ``` - -4. Create a `.env` file in your project root: - - ```bash - touch .env - ``` - -5. Add your API keys and configuration, replacing the placeholders with your actual credentials: - - ```plaintext - E2B_API_KEY=your_e2b_api_key_here - ANTHROPIC_API_KEY=your_anthropic_api_key_here - GITHUB_TOKEN=ghp_your_personal_access_token_here - GITHUB_OWNER=your_github_username - GITHUB_REPO=your_repository_name - SONARQUBE_ORG=your_sonarcloud_org_key - SONARQUBE_TOKEN=your_sonarqube_user_token - SONARQUBE_URL=https://sonarcloud.io - ``` - -6. Protect your credentials by adding `.env` to `.gitignore`: - - ```bash - echo ".env" >> .gitignore - echo "node_modules/" >> .gitignore - ``` - -{{< /tab >}} -{{< tab name="Python" >}} - -1. Create a new directory for your workflow: - - ```bash - mkdir github-sonarqube-workflow - cd github-sonarqube-workflow - ``` - -2. Create a virtual environment and activate it: - - ```bash - python3 -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate - ``` - -3. Install required dependencies: - - ```bash - pip install e2b python-dotenv - ``` - -4. Create a `.env` file in your project root: - - ```bash - touch .env - ``` - -5. Add your API keys and configuration, replacing the placeholders with your actual credentials: - - ```plaintext - E2B_API_KEY=your_e2b_api_key_here - ANTHROPIC_API_KEY=your_anthropic_api_key_here - GITHUB_TOKEN=ghp_your_personal_access_token_here - GITHUB_OWNER=your_github_username - GITHUB_REPO=your_repository_name - SONARQUBE_ORG=your_sonarcloud_org_key - SONARQUBE_TOKEN=your_sonarqube_user_token - SONARQUBE_URL=https://sonarcloud.io - ``` - -6. Protect your credentials by adding `.env` to `.gitignore`: - - ```bash - echo ".env" >> .gitignore - echo "venv/" >> .gitignore - echo "__pycache__/" >> .gitignore - ``` - -{{< /tab >}} -{{< /tabs >}} - -## Step 1: Create your first sandbox - -Let's start by creating a sandbox and verifying the MCP servers are configured correctly. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create a file named `01-test-connection.ts` in your project root: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function testConnection() { - console.log( - "Creating E2B sandbox with GitHub and SonarQube MCP servers...\n", - ); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - console.log(" Sandbox created successfully!"); - console.log(`MCP Gateway URL: ${mcpUrl}\n`); - - // Wait for MCP initialization - await new Promise((resolve) => setTimeout(resolve, 1000)); - - // Configure Claude to use the MCP gateway - console.log("Connecting Claude CLI to MCP gateway..."); - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log("\nœConnection successful! Cleaning up..."); - await sbx.kill(); -} - -testConnection().catch(console.error); -``` - -Run this script to verify your setup: - -```bash -npx tsx 01-test-connection.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create a file named `01_test_connection.py` in your project root: - -```python -import os -import asyncio -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def test_connection(): - print("Creating E2B sandbox with GitHub and SonarQube MCP servers...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - print(" Sandbox created successfully!") - print(f"MCP Gateway URL: {mcp_url}\n") - - # Wait for MCP initialization - await asyncio.sleep(1) - - # Configure Claude to use the MCP gateway - print("Connecting Claude CLI to MCP gateway...") - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print("\n Connection successful! Cleaning up...") - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(test_connection()) -``` - -Run this script to verify your setup: - -```bash -python 01_test_connection.py -``` - -{{< /tab >}} -{{< /tabs >}} - -Your output should look similar to the following example: - -```console {collapse=true} -Creating E2B sandbox with GitHub and SonarQube MCP servers... - -✓ Sandbox created successfully! -MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp - -Connecting Claude CLI to MCP gateway... -Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp to local config -Headers: { - "Authorization": "Bearer xxxxx-xxxx-xxxx" -} -File modified: /home/user/.claude.json [project: /home/user] - -✓ Connection successful! Cleaning up... -``` - -You've just learned how to create an E2B sandbox with multiple MCP servers -configured. The `betaCreate` method initializes a cloud environment -with Claude CLI and your specified MCP servers. - -## Step 2: Discover available MCP tools - -MCP servers expose tools that Claude can call. The GitHub MCP server provides -repository management tools, while SonarQube provides code analysis tools. -By listing their tools, you know what operations are possible. - -To try listing MCP tools: - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `02-list-tools.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function listTools() { - console.log("Creating sandbox...\n"); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - // Wait for MCP initialization - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - console.log("\nDiscovering available MCP tools...\n"); - - const prompt = - "List all MCP tools you have access to. For each tool, show its exact name and a brief description."; - - await sbx.commands.run( - `echo '${prompt}' | claude -p --dangerously-skip-permissions`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - await sbx.kill(); -} - -listTools().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 02-list-tools.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `02_list_tools.py`: - -```python -import os -import asyncio -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def list_tools(): - print("Creating sandbox...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - # Wait for MCP initialization - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print("\nDiscovering available MCP tools...\n") - - prompt = "List all MCP tools you have access to. For each tool, show its exact name and a brief description." - - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(list_tools()) -``` - -Run the script: - -```bash -python 02_list_tools.py -``` - -{{< /tab >}} -{{< /tabs >}} - -In the console, you should see a list of MCP tools: - -```console {collapse=true} -Creating sandbox... - -Sandbox created -Connecting to MCP gateway... - -Discovering available MCP tools... - -I have access to the following MCP tools: - -**GitHub Tools:** -1. mcp__create_repository - Create a new GitHub repository -2. mcp__list_issues - List issues in a repository -3. mcp__create_issue - Create a new issue -4. mcp__get_file_contents - Get file contents from a repository -5. mcp__create_or_update_file - Create or update files in a repository -6. mcp__create_pull_request - Create a pull request -7. mcp__create_branch - Create a new branch -8. mcp__push_files - Push multiple files in a single commit -... (30+ more GitHub tools) - -**SonarQube Tools:** -1. mcp__get_projects - List projects in organization -2. mcp__get_quality_gate_status - Get quality gate status for a project -3. mcp__list_project_issues - List quality issues in a project -4. mcp__search_issues - Search for specific quality issues -... (SonarQube analysis tools) -``` - -## Step 3: Test GitHub MCP tools - -Let's try testing GitHub using MCP tools. Start simple by listing -repository issues. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `03-test-github.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function testGitHub() { - console.log("Creating sandbox...\n"); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`; - - console.log(`\nListing issues in ${repoPath}...\n`); - - const prompt = `Using the GitHub MCP tools, list all open issues in the repository "${repoPath}". Show the issue number, title, and author for each.`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - await sbx.kill(); -} - -testGitHub().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 03-test-github.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `03_test_github.py`: - -```python -import os -import asyncio -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def test_github(): - print("Creating sandbox...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}" - - print(f"\nListing issues in {repo_path}...\n") - - prompt = f'Using the GitHub MCP tools, list all open issues in the repository "{repo_path}". Show the issue number, title, and author for each.' - - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(test_github()) -``` - -Run the script: - -```bash -python 03_test_github.py -``` - -{{< /tab >}} -{{< /tabs >}} - -You should see Claude use the GitHub MCP tools to list your repository's issues: - -```console {collapse=true} -Creating sandbox... -Connecting to MCP gateway... - -Listing issues in <your-repo>... - -Here are the first 10 open issues in the <your-repo> repository: - -1. **Issue #23577**: Update README (author: user1) -2. **Issue #23575**: release-notes for Compose v2.40.1 version (author: user2) -3. **Issue #23570**: engine-cli: fix `docker volume prune` output (author: user3) -4. **Issue #23568**: Engdocs update (author: user4) -5. **Issue #23565**: add new section (author: user5) -... (continues with more issues) -``` - -You can now send prompts to Claude and interact with GitHub through -natural language. Claude decides what tool to call based on your prompt. - -## Step 4: Test SonarQube MCP tools - -Let's analyze code quality using SonarQube MCP tools. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `04-test-sonarqube.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function testSonarQube() { - console.log("Creating sandbox...\n"); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - console.log("\nAnalyzing code quality with SonarQube...\n"); - - const prompt = `Using the SonarQube MCP tools: - 1. List all projects in my organization - 2. For the first project, show: - - Quality gate status (pass/fail) - - Number of bugs - - Number of code smells - - Number of security vulnerabilities - 3. List the top 5 most critical issues found`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - await sbx.kill(); -} - -testSonarQube().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 04-test-sonarqube.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `04_test_sonarqube.py`: - -```python -import os -import asyncio -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def test_sonarqube(): - print("Creating sandbox...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print("\nAnalyzing code quality with SonarQube...\n") - - prompt = """Using the SonarQube MCP tools: - 1. List all projects in my organization - 2. For the first project, show: - - Quality gate status (pass/fail) - - Number of bugs - - Number of code smells - - Number of security vulnerabilities - 3. List the top 5 most critical issues found""" - - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(test_sonarqube()) -``` - -Run the script: - -```bash -python 04_test_sonarqube.py -``` - -{{< /tab >}} -{{< /tabs >}} - -> [!NOTE] -> -> This script may take a few minutes to run. - -You should see Claude output SonarQube analysis results: - -```console {collapse=true} -Creating sandbox... - -Analyzing code quality with SonarQube... - -## SonarQube Analysis Results - -### 1. Projects in Your Organization - -Found **1 project**: -- **Project Name**: project-1 -- **Project Key**: project-testing - -### 2. Project Analysis - -... - -### 3. Top 5 Most Critical Issues - -Found 1 total issues (all are code smells with no critical/blocker severity): - -1. **MAJOR Severity** - test.js:2 - - **Rule**: javascript:S1854 - - **Message**: Remove this useless assignment to variable "unusedVariable" - - **Status**: OPEN - -**Summary**: The project is in good health with no bugs or vulnerabilities detected. -``` - -You can now use SonarQube MCP tools to analyze code quality through -natural language. You can retrieve quality metrics, identify issues, -and understand what code needs fixing. - -## Step 5: Create a branch and make code changes - -Now, let's teach Claude to fix code based on quality issues discovered -by SonarQube. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `05-fix-code-issue.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function fixCodeIssue() { - console.log("Creating sandbox...\n"); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`; - const branchName = `quality-fix-${Date.now()}`; - - console.log("\nFixing a code quality issue...\n"); - - const prompt = `Using GitHub and SonarQube MCP tools: - - 1. Analyze code quality in repository "${repoPath}" with SonarQube - 2. Find ONE simple issue that can be confidently fixed (like an unused variable or code smell) - 3. Create a new branch called "${branchName}" - 4. Read the file containing the issue using GitHub tools - 5. Fix the issue in the code - 6. Commit the fix to the new branch with a clear commit message - - Important: Only fix issues you're 100% confident about. Explain what you're fixing and why.`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log(`\nœCheck your repository for branch: ${branchName}`); - - await sbx.kill(); -} - -fixCodeIssue().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 05-fix-code-issue.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `05_fix_code_issue.py`: - -```python -import os -import asyncio -import time -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def fix_code_issue(): - print("Creating sandbox...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}" - branch_name = f"quality-fix-{int(time.time() * 1000)}" - - print("\nFixing a code quality issue...\n") - - prompt = f"""Using GitHub and SonarQube MCP tools: - - 1. Analyze code quality in repository "{repo_path}" with SonarQube - 2. Find ONE simple issue that can be confidently fixed (like an unused variable or code smell) - 3. Create a new branch called "{branch_name}" - 4. Read the file containing the issue using GitHub tools - 5. Fix the issue in the code - 6. Commit the fix to the new branch with a clear commit message - - Important: Only fix issues you're 100% confident about. Explain what you're fixing and why.""" - - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print(f"\n Check your repository for branch: {branch_name}") - - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(fix_code_issue()) -``` - -Run the script: - -```bash -python 05_fix_code_issue.py -``` - -{{< /tab >}} -{{< /tabs >}} - -> [!NOTE] -> -> This script may take a few minutes to run. - -Claude will analyze your repository and fix a code quality issue: - -```console {collapse=true} -Creating sandbox... - -Fixing a code quality issue... - -## Task Completed Successfully! - -I've successfully analyzed the repository and fixed a code quality issue. Here's what I did: - -### 1. Analysis -Found 1 SonarQube issues in the `<your-repo>` repository: -- **Unused variable** (MINOR severity, line 2) -- Useless assignment (MAJOR severity, line 2) -- For-of loop suggestion (MINOR severity, lines 5-7) - -### 2. Issue Fixed -**Location:** test.js:2 -**Issue:** Unused variable declaration -**SonarQube Rule:** javascript:S1481 -**What was wrong:** The line `const unusedVariable = "this is not used";` declared a variable that was never used anywhere in the function. - -### 3. Why This Fix is Safe -- The variable was only declared and assigned, never referenced -- Removing it has zero impact on functionality -- It eliminates dead code and improves code quality -- This is a textbook example of a code smell that should be removed - -### 4. Changes Made -- Created branch: `quality-fix-xxxxx` -- Removed the unused variable declaration -- Committed with a clear message explaining the fix and referencing the SonarQube rule - -**Commit SHA:** `xxxxxxxxxxxxxxxxxxxxxxxxx` -**Branch:** https://github.com/<github-org>/<your-repo>/tree/quality-fix-xxxxx - -The fix is ready for review and can be merged to improve the code quality of the repository! -``` - -You can now use GitHub and SonarQube MCP tools in the same workflow to read -files, make code changes, and commit them. - -## Step 6: Create quality-gated pull requests - -Finally, let's build the complete workflow: analyze quality, fix issues, -and create a PR only if improvements are made. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `06-quality-gated-pr.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function qualityGatedPR() { - console.log("Creating sandbox for quality-gated PR workflow...\n"); - - const sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`; - const branchName = `quality-improvements-${Date.now()}`; - - console.log("\nRunning quality-gated PR workflow...\n"); - - const prompt = `You are a code quality engineer. Using GitHub and SonarQube MCP tools: - - STEP 1: ANALYSIS - - Get current code quality status from SonarQube for "${repoPath}" - - Record the current number of bugs, code smells, and vulnerabilities - - Identify 1-3 issues that you can confidently fix - - STEP 2: FIX ISSUES - - Create branch "${branchName}" - - For each issue you're fixing: - * Read the file with the issue - * Make the fix - * Commit with a descriptive message - - Only fix issues where you're 100% confident the fix is correct - - STEP 3: VERIFICATION - - After your fixes, check if quality metrics would improve - - Calculate: Would this reduce bugs/smells/vulnerabilities? - - STEP 4: QUALITY GATE - - Only proceed if your changes improve quality - - If quality would not improve, explain why and stop - - STEP 5: CREATE PR (only if quality gate passes) - - Create a pull request from "${branchName}" to main - - Title: "Quality improvements: [describe what you fixed]" - - Description should include: - * What issues you fixed - * Before/after quality metrics - * Why these fixes improve code quality - - Add a comment with detailed SonarQube analysis - - Be thorough and explain your decisions at each step.`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log(`\n Workflow complete! Check ${repoPath} for new pull request.`); - - await sbx.kill(); -} - -qualityGatedPR().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 06-quality-gated-pr.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `06_quality_gated_pr.py`: - -```python -import os -import asyncio -import time -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def quality_gated_pr(): - print("Creating sandbox for quality-gated PR workflow...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}" - branch_name = f"quality-improvements-{int(time.time() * 1000)}" - - print("\nRunning quality-gated PR workflow...\n") - - prompt = f"""You are a code quality engineer. Using GitHub and SonarQube MCP tools: - - STEP 1: ANALYSIS - - Get current code quality status from SonarQube for "{repo_path}" - - Record the current number of bugs, code smells, and vulnerabilities - - Identify 1-3 issues that you can confidently fix - - STEP 2: FIX ISSUES - - Create branch "{branch_name}" - - For each issue you are fixing: - Read the file with the issue - Make the fix - Commit with a descriptive message - - Only fix issues where you are 100 percent confident the fix is correct - - STEP 3: VERIFICATION - - After your fixes, check if quality metrics would improve - - Calculate: Would this reduce bugs/smells/vulnerabilities? - - STEP 4: QUALITY GATE - - Only proceed if your changes improve quality - - If quality would not improve, explain why and stop - - STEP 5: CREATE PR (only if quality gate passes) - - Create a pull request from "{branch_name}" to main - - Title: "Quality improvements: [describe what you fixed]" - - Description should include: - What issues you fixed - Before/after quality metrics - Why these fixes improve code quality - - Add a comment with detailed SonarQube analysis - - Be thorough and explain your decisions at each step.""" - - await sbx.commands.run( - f"echo '{prompt.replace(chr(39), chr(39) + chr(92) + chr(39) + chr(39))}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print(f"\n Workflow complete! Check {repo_path} for new pull request.") - - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(quality_gated_pr()) -``` - -Run the script: - -```bash -python 06_quality_gated_pr.py -``` - -{{< /tab >}} -{{< /tabs >}} - -> [!NOTE] -> -> This script may take a few minutes to run. - -Claude will run the entire workflow, creating a quality improvement -and opening a PR in GitHub: - -```console {collapse=true} -Creating sandbox for quality-gated PR workflow... - -Running quality-gated PR workflow... - -## Complete - Code Quality Improvement Successfully Executed - -### Summary of Work Completed - -**Pull Request Created:** https://github.com/<github-org>/<your-repo>/pull/1 - ---- - -### STEP 1: ANALYSIS - -**Current State:** -- **Bugs:** 0 -- **Vulnerabilities:** 0 -- **Code Smells:** 1 -- **Lines of Code:** 12 -- **All Ratings:** A (Reliability, Security, Maintainability) - -**Issues Identified (all in test.js):** -1. xxxxxxxxx - Unused variable declaration (MINOR) - ---- - -### STEP 2: FIX ISSUES - -**Branch Created:** `quality-improvements-xxxxxxxx` - -**Changes Made:** -1. **Removed unused variable** (line 2) - Eliminated dead code that served no purpose -2. **Modernized loop pattern** (lines 5-7) - Converted `for (let i = 0; i < items.length; i++)` to `for (const item of items)` - -**Commit:** xxxxxxxxxx - ---- - -### STEP 3: VERIFICATION - -**Expected Impact:** -- Code Smells: 1 → 0 (100% reduction) -- Bugs: 0 → 0 (maintained) -- Vulnerabilities: 0 → 0 (maintained) -- All quality ratings maintained at A - ---- - -### STEP 4: QUALITY GATE PASSED - -**Decision Criteria Met:** -- ✅ Reduces code smells by 100% -- ✅ No new bugs or vulnerabilities introduced -- ✅ Code is more readable and maintainable -- ✅ Follows modern JavaScript best practices -- ✅ All fixes are low-risk refactorings with no behavioral changes - ---- - -### STEP 5: CREATE PR - -**Pull Request Details:** -- **Number:** #1 -- **Title:** Quality improvements: Remove unused variable and modernize for loop -- **Branch:** quality-improvements-xxxxxxxx → main -- **URL:** https://github.com/<github-org)/<your-repo>/pull/1 - -**PR Includes:** -- Comprehensive description with before/after metrics -- Detailed SonarQube analysis comment with issue breakdown -- Code comparison showing improvements -- Quality metrics table - -The pull request is now ready for review and merge! -``` - -You've now built a complete, multi-step workflow with conditional logic. -Claude analyzes quality with SonarQube, makes fixes using GitHub tools, -verifies improvements, and only creates a PR if quality actually improves. - -## Step 7: Add error handling - -Production workflows need error handling. Let's make the workflow more robust. - -{{< tabs group="language" >}} -{{< tab name="TypeScript" >}} - -Create `07-robust-workflow.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function robustWorkflow() { - let sbx: Sandbox | undefined; - - try { - console.log("Creating sandbox...\n"); - - sbx = await Sandbox.betaCreate({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, - GITHUB_TOKEN: process.env.GITHUB_TOKEN!, - SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!, - }, - mcp: { - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN!, - }, - sonarqube: { - org: process.env.SONARQUBE_ORG!, - token: process.env.SONARQUBE_TOKEN!, - url: "https://sonarcloud.io", - }, - }, - }); - - const mcpUrl = sbx.betaGetMcpUrl(); - const mcpToken = await sbx.betaGetMcpToken(); - - await new Promise((resolve) => setTimeout(resolve, 1000)); - - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { timeoutMs: 0, onStdout: console.log, onStderr: console.log }, - ); - - const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`; - - console.log("\nRunning workflow with error handling...\n"); - - const prompt = `Run a quality improvement workflow for "${repoPath}". - - ERROR HANDLING RULES: - 1. If SonarQube is unreachable, explain the error and stop gracefully - 2. If GitHub API fails, retry once, then explain and stop - 3. If no fixable issues are found, explain why and exit (this is not an error) - 4. If file modifications fail, explain which file and why - 5. At each step, check for errors before proceeding - - Run the workflow and handle any errors you encounter professionally.`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log("\n Workflow completed"); - } catch (error) { - const err = error as Error; - console.error("\n Workflow failed:", err.message); - - if (err.message.includes("403")) { - console.error("\n Check your E2B account has MCP gateway access"); - } else if (err.message.includes("401")) { - console.error("\n Check your API tokens are valid"); - } else if (err.message.includes("Credit balance")) { - console.error("\n Check your Anthropic API credit balance"); - } - - process.exit(1); - } finally { - if (sbx) { - console.log("\n Cleaning up sandbox..."); - await sbx.kill(); - } - } -} - -robustWorkflow().catch(console.error); -``` - -Run the script: - -```bash -npx tsx 07-robust-workflow.ts -``` - -{{< /tab >}} -{{< tab name="Python" >}} - -Create `07_robust_workflow.py`: - -```python -import os -import asyncio -import sys -from dotenv import load_dotenv -from e2b import AsyncSandbox - -load_dotenv() - -async def robust_workflow(): - sbx = None - - try: - print("Creating sandbox...\n") - - sbx = await AsyncSandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"), - "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"), - }, - mcp={ - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - "sonarqube": { - "org": os.getenv("SONARQUBE_ORG"), - "token": os.getenv("SONARQUBE_TOKEN"), - "url": "https://sonarcloud.io", - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - await asyncio.sleep(1) - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout=0, # Fixed: was timeout_ms - on_stdout=print, - on_stderr=print, - ) - - repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}" - - print("\nRunning workflow with error handling...\n") - - prompt = f"""Run a quality improvement workflow for "{repo_path}". - - ERROR HANDLING RULES: - 1. If SonarQube is unreachable, explain the error and stop gracefully - 2. If GitHub API fails, retry once, then explain and stop - 3. If no fixable issues are found, explain why and exit (this is not an error) - 4. If file modifications fail, explain which file and why - 5. At each step, check for errors before proceeding - - Run the workflow and handle any errors you encounter professionally.""" - - await sbx.commands.run( - f"echo '{prompt}' | claude -p --dangerously-skip-permissions", - timeout=0, - on_stdout=print, - on_stderr=print, - ) - - print("\n Workflow completed") - - except Exception as error: - print(f"\n✗ Workflow failed: {str(error)}") - - error_msg = str(error) - if "403" in error_msg: - print("\n Check your E2B account has MCP gateway access") - elif "401" in error_msg: - print("\n Check your API tokens are valid") - elif "Credit balance" in error_msg: - print("\n Check your Anthropic API credit balance") - - sys.exit(1) - - finally: - if sbx: - print("\n Cleaning up sandbox...") - await sbx.kill() - -if __name__ == "__main__": - asyncio.run(robust_workflow()) -``` - -Run the script: - -```bash -python 07_robust_workflow.py -``` - -{{< /tab >}} -{{< /tabs >}} - -Claude will run the entire workflow, and if it encounters an error, respond -with robust error messaging. - -## Next steps - -In the next section, you'll customize your workflow for your needs. diff --git a/content/guides/go-prometheus-monitoring.md b/content/guides/go-prometheus-monitoring.md new file mode 100644 index 000000000000..f5f98bb1130c --- /dev/null +++ b/content/guides/go-prometheus-monitoring.md @@ -0,0 +1,629 @@ +--- +description: Containerize a Golang application and monitor it with Prometheus and Grafana. +keywords: golang, prometheus, grafana, monitoring, containerize +title: Monitor a Golang application with Prometheus and Grafana +summary: | + Learn how to containerize a Golang application and monitor it with Prometheus and Grafana. +linkTitle: Prometheus and Grafana +aliases: + - /guides/go-prometheus-monitoring/application/ + - /guides/go-prometheus-monitoring/compose/ + - /guides/go-prometheus-monitoring/containerize/ + - /guides/go-prometheus-monitoring/develop/ +params: + tags: [observability] + time: 45 minutes +--- + + +The guide teaches you how to containerize a Golang application and monitor it with Prometheus and Grafana. + +> **Acknowledgment** +> +> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. + +## Overview + +To make sure your application is working as intended, monitoring is important. One of the most popular monitoring tools is Prometheus. Prometheus is an open-source monitoring and alerting toolkit that is designed for reliability and scalability. It collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. To visualize the metrics, you can use Grafana. Grafana is an open-source platform for monitoring and observability that allows you to query, visualize, alert on, and understand your metrics no matter where they are stored. + +In this guide, you will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus. Finally, you will visualize the metrics using Grafana. You will containerize the Golang application, and using the Docker Compose file, you will connect all the services: Golang, Prometheus, and Grafana. + +## What will you learn? + +* Create a Golang application with custom Prometheus metrics. +* Containerize a Golang application. +* Use Docker Compose to run multiple services and connect them together to monitor a Golang application with Prometheus and Grafana. +* Visualize the metrics using Grafana dashboards. + +## Prerequisites + +- A good understanding of Golang is assumed. +- You must me familiar with Prometheus and creating dashboards in Grafana. +- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +## Next steps + +You will create a Golang server and expose metrics using Prometheus. + +## Building the application + +### Prerequisites + +* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +You will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus. + +### Getting the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following +command to clone the repository: + +```console +$ git clone https://github.com/dockersamples/go-prometheus-monitoring.git +``` + +Once you cloned you will see the following content structure inside `go-prometheus-monitoring` directory, + +```text +go-prometheus-monitoring +├── CONTRIBUTING.md +├── Docker +│ ├── grafana.yml +│ └── prometheus.yml +├── dashboard.json +├── Dockerfile +├── LICENSE +├── README.md +├── compose.yaml +├── go.mod +├── go.sum +└── main.go +``` + +- **main.go** - The entry point of the application. +- **go.mod and go.sum** - Go module files. +- **Dockerfile** - Dockerfile used to build the app. +- **Docker/** - Contains the Docker Compose configuration files for Grafana and Prometheus. +- **compose.yaml** - Compose file to launch everything (Golang app, Prometheus, and Grafana). +- **dashboard.json** - Grafana dashboard configuration file. +- **Dockerfile** - Dockerfile used to build the Golang app. +- **compose.yaml** - Docker Compose file to launch everything (Golang app, Prometheus, and Grafana). +- Other files are for licensing and documentation purposes. + +### Understanding the application + +The following is the complete logic of the application you will find in `main.go`. + +```go +package main + +import ( + "strconv" + + "github.com/gin-gonic/gin" + "github.com/prometheus/client_golang/prometheus" + "github.com/prometheus/client_golang/prometheus/promhttp" +) + +// Define metrics +var ( + HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ + Name: "api_http_request_total", + Help: "Total number of requests processed by the API", + }, []string{"path", "status"}) + + HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ + Name: "api_http_request_error_total", + Help: "Total number of errors returned by the API", + }, []string{"path", "status"}) +) + +// Custom registry (without default Go metrics) +var customRegistry = prometheus.NewRegistry() + +// Register metrics with custom registry +func init() { + customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal) +} + +func main() { + router := gin.Default() + + // Register /metrics before middleware + router.GET("/metrics", PrometheusHandler()) + + router.Use(RequestMetricsMiddleware()) + router.GET("/health", func(c *gin.Context) { + c.JSON(200, gin.H{ + "message": "Up and running!", + }) + }) + router.GET("/v1/users", func(c *gin.Context) { + c.JSON(200, gin.H{ + "message": "Hello from /v1/users", + }) + }) + + router.Run(":8000") +} + +// Custom metrics handler with custom registry +func PrometheusHandler() gin.HandlerFunc { + h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{}) + return func(c *gin.Context) { + h.ServeHTTP(c.Writer, c.Request) + } +} + +// Middleware to record incoming requests metrics +func RequestMetricsMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + path := c.Request.URL.Path + c.Next() + status := c.Writer.Status() + if status < 400 { + HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() + } else { + HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() + } + } +} +``` + +In this part of the code, you have imported the required packages `gin`, `prometheus`, and `promhttp`. Then you have defined a couple of variables, `HttpRequestTotal` and `HttpRequestErrorTotal` are Prometheus counter metrics, and `customRegistry` is a custom registry that will be used to register these metrics. The name of the metric is a string that you can use to identify the metric. The help string is a string that will be shown when you query the `/metrics` endpoint to understand the metric. The reason you are using the custom registry is so avoid the default Go metrics that are registered by default by the Prometheus client. Then using the `init` function you are registering the metrics with the custom registry. + +```go +import ( + "strconv" + + "github.com/gin-gonic/gin" + "github.com/prometheus/client_golang/prometheus" + "github.com/prometheus/client_golang/prometheus/promhttp" +) + +// Define metrics +var ( + HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ + Name: "api_http_request_total", + Help: "Total number of requests processed by the API", + }, []string{"path", "status"}) + + HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ + Name: "api_http_request_error_total", + Help: "Total number of errors returned by the API", + }, []string{"path", "status"}) +) + +// Custom registry (without default Go metrics) +var customRegistry = prometheus.NewRegistry() + +// Register metrics with custom registry +func init() { + customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal) +} +``` + +In the `main` function, you have created a new instance of the `gin` framework and created three routes. You can see the health endpoint that is on path `/health` that will return a JSON with `{"message": "Up and running!"}` and the `/v1/users` endpoint that will return a JSON with `{"message": "Hello from /v1/users"}`. The third route is for the `/metrics` endpoint that will return the metrics in the Prometheus format. Then you have `RequestMetricsMiddleware` middleware, it will be called for every request made to the API. It will record the incoming requests metrics like status codes and paths. Finally, you are running the gin application on port 8000. + +```golang +func main() { + router := gin.Default() + + // Register /metrics before middleware + router.GET("/metrics", PrometheusHandler()) + + router.Use(RequestMetricsMiddleware()) + router.GET("/health", func(c *gin.Context) { + c.JSON(200, gin.H{ + "message": "Up and running!", + }) + }) + router.GET("/v1/users", func(c *gin.Context) { + c.JSON(200, gin.H{ + "message": "Hello from /v1/users", + }) + }) + + router.Run(":8000") +} +``` + +Now comes the middleware function `RequestMetricsMiddleware`. This function is called for every request made to the API. It increments the `HttpRequestTotal` counter (different counter for different paths and status codes) if the status code is less than or equal to 400. If the status code is greater than 400, it increments the `HttpRequestErrorTotal` counter (different counter for different paths and status codes). The `PrometheusHandler` function is the custom handler that will be called for the `/metrics` endpoint. It will return the metrics in the Prometheus format. + +```golang +// Custom metrics handler with custom registry +func PrometheusHandler() gin.HandlerFunc { + h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{}) + return func(c *gin.Context) { + h.ServeHTTP(c.Writer, c.Request) + } +} + +// Middleware to record incoming requests metrics +func RequestMetricsMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + path := c.Request.URL.Path + c.Next() + status := c.Writer.Status() + if status < 400 { + HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() + } else { + HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() + } + } +} +``` + +That's it, this was the complete gist of the application. Now it's time to run and test if the app is registering metrics correctly. + +### Running the application + +Make sure you are still inside `go-prometheus-monitoring` directory in the terminal, and run the following command. Install the dependencies by running `go mod tidy` and then build and run the application by running `go run main.go`. Then visit `http://localhost:8000/health` or `http://localhost:8000/v1/users`. You should see the output `{"message": "Up and running!"}` or `{"message": "Hello from /v1/users"}`. If you are able to see this then your app is successfully up and running. + + +Now, check your application's metrics by accessing the `/metrics` endpoint. +Open `http://localhost:8000/metrics` in your browser. You should see similar output to the following. + +```sh +# HELP api_http_request_error_total Total number of errors returned by the API +# TYPE api_http_request_error_total counter +api_http_request_error_total{path="/",status="404"} 1 +api_http_request_error_total{path="//v1/users",status="404"} 1 +api_http_request_error_total{path="/favicon.ico",status="404"} 1 +# HELP api_http_request_total Total number of requests processed by the API +# TYPE api_http_request_total counter +api_http_request_total{path="/health",status="200"} 2 +api_http_request_total{path="/v1/users",status="200"} 1 +``` + +In the terminal, press `ctrl` + `c` to stop the application. + +> [!Note] +> If you don't want to run the application locally, and want to run it in a Docker container, skip to next page where you create a Dockerfile and containerize the application. + +### Summary + +In this section, you learned how to create a Golang app to register metrics with Prometheus. By implementing middleware functions, you were able to increment the counters based on the request path and status codes. + +### Next steps + +In the next section, you'll learn how to containerize your application. + +## Containerize a Golang application + +Containerization helps you bundle the application and its dependencies into a single package called a container. This package can run on any platform without worrying about the environment. In this section, you will learn how to containerize a Golang application using Docker. + +To containerize a Golang application, you first need to create a Dockerfile. The Dockerfile contains instructions to build and run the application in a container. Also, when creating a Dockerfile, you can follow different sets of best practices to optimize the image size and make it more secure. + +### Creating a Dockerfile + +Create a new file named `Dockerfile` in the root directory of your Golang application. The Dockerfile contains instructions to build and run the application in a container. + +The following is a Dockerfile for a Golang application. You will also find this file in the `go-prometheus-monitoring` directory. + +```dockerfile +# Use the official Golang image as the base +FROM golang:1.24-alpine AS builder + +# Set environment variables +ENV CGO_ENABLED=0 \ + GOOS=linux \ + GOARCH=amd64 + +# Set working directory inside the container +WORKDIR /build + +# Copy go.mod and go.sum files for dependency installation +COPY go.mod go.sum ./ + +# Download dependencies +RUN go mod download + +# Copy the entire application source +COPY . . + +# Build the Go binary +RUN go build -o /app . + +# Final lightweight stage +FROM alpine:3.21 AS final + +# Copy the compiled binary from the builder stage +COPY --from=builder /app /bin/app + +# Expose the application's port +EXPOSE 8000 + +# Run the application +CMD ["bin/app"] +``` + +### Understanding the Dockerfile + +The Dockerfile consists of two stages: + +1. **Build stage**: This stage uses the official Golang image as the base and sets the necessary environment variables. It also sets the working directory inside the container, copies the `go.mod` and `go.sum` files for dependency installation, downloads the dependencies, copies the entire application source, and builds the Go binary. + + You use the `golang:1.24-alpine` image as the base image for the build stage. The `CGO_ENABLED=0` environment variable disables CGO, which is useful for building static binaries. You also set the `GOOS` and `GOARCH` environment variables to `linux` and `amd64`, respectively, to build the binary for the Linux platform. + +2. **Final stage**: This stage uses the official Alpine image as the base and copies the compiled binary from the build stage. It also exposes the application's port and runs the application. + + You use the `alpine:3.21` image as the base image for the final stage. You copy the compiled binary from the build stage to the final image. You expose the application's port using the `EXPOSE` instruction and run the application using the `CMD` instruction. + + Apart from the multi-stage build, the Dockerfile also follows best practices such as using the official images, setting the working directory, and copying only the necessary files to the final image. You can further optimize the Dockerfile by other best practices. + +### Build the Docker image and run the application + +One you have the Dockerfile, you can build the Docker image and run the application in a container. + +To build the Docker image, run the following command in the terminal: + +```console +$ docker build -t go-api:latest . +``` + +After building the image, you can run the application in a container using the following command: + +```console +$ docker run -p 8000:8000 go-api:latest +``` + +The application will start running inside the container, and you can access it at `http://localhost:8000`. You can also check the running containers using the `docker ps` command. + +```console +$ docker ps +``` + +### Summary + +In this section, you learned how to containerize a Golang application using a Dockerfile. You created a multi-stage Dockerfile to build and run the application in a container. You also learned about best practices to optimize the Docker image size and make it more secure. + +Related information: + + - [Dockerfile reference](/reference/dockerfile.md) + - [.dockerignore file](/reference/dockerfile.md#dockerignore-file) + +### Next steps + +In the next section, you will learn how to use Docker Compose to connect and run multiple services together to monitor a Golang application with Prometheus and Grafana. + +## Connecting services with Docker Compose + +Now that you have containerized the Golang application, you will use Docker Compose to connect your services together. You will connect the Golang application, Prometheus, and Grafana services together to monitor the Golang application with Prometheus and Grafana. + +### Creating a Docker Compose file + +Create a new file named `compose.yml` in the root directory of your Golang application. The Docker Compose file contains instructions to run multiple services and connect them together. + +Here is a Docker Compose file for a project that uses Golang, Prometheus, and Grafana. You will also find this file in the `go-prometheus-monitoring` directory. + +```yaml +services: + api: + container_name: go-api + build: + context: . + dockerfile: Dockerfile + image: go-api:latest + ports: + - 8000:8000 + networks: + - go-network + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8000/health"] + interval: 30s + timeout: 10s + retries: 5 + develop: + watch: + - path: . + action: rebuild + + prometheus: + container_name: prometheus + image: prom/prometheus:v2.55.0 + volumes: + - ./Docker/prometheus.yml:/etc/prometheus/prometheus.yml + ports: + - 9090:9090 + networks: + - go-network + + grafana: + container_name: grafana + image: grafana/grafana:11.3.0 + volumes: + - ./Docker/grafana.yml:/etc/grafana/provisioning/datasources/datasource.yaml + - grafana-data:/var/lib/grafana + ports: + - 3000:3000 + networks: + - go-network + environment: + - GF_SECURITY_ADMIN_USER=admin + - GF_SECURITY_ADMIN_PASSWORD=password + +volumes: + grafana-data: + +networks: + go-network: + driver: bridge +``` + +### Understanding the Docker Compose file + +The Docker Compose file consists of three services: + +- **Golang application service**: This service builds the Golang application using the Dockerfile and runs it in a container. It exposes the application's port `8000` and connects to the `go-network` network. It also defines a health check to monitor the application's health. You have also used `healthcheck` to monitor the health of the application. The health check runs every 30 seconds and retries 5 times if the health check fails. The health check uses the `curl` command to check the `/health` endpoint of the application. Apart from the health check, you have also added a `develop` section to watch the changes in the application's source code and rebuild the application using the Docker Compose Watch feature. + +- **Prometheus service**: This service runs the Prometheus server in a container. It uses the official Prometheus image `prom/prometheus:v2.55.0`. It exposes the Prometheus server on port `9090` and connects to the `go-network` network. You have also mounted the `prometheus.yml` file from the `Docker` directory which is present in the root directory of your project. The `prometheus.yml` file contains the Prometheus configuration to scrape the metrics from the Golang application. This is how you connect the Prometheus server to the Golang application. + + ```yaml + global: + scrape_interval: 10s + evaluation_interval: 10s + + scrape_configs: + - job_name: myapp + static_configs: + - targets: ["api:8000"] + ``` + + In the `prometheus.yml` file, you have defined a job named `myapp` to scrape the metrics from the Golang application. The `targets` field specifies the target to scrape the metrics from. In this case, the target is the Golang application running on port `8000`. The `api` is the service name of the Golang application in the Docker Compose file. The Prometheus server will scrape the metrics from the Golang application every 10 seconds. + +- **Grafana service**: This service runs the Grafana server in a container. It uses the official Grafana image `grafana/grafana:11.3.0`. It exposes the Grafana server on port `3000` and connects to the `go-network` network. You have also mounted the `grafana.yml` file from the `Docker` directory which is present in the root directory of your project. The `grafana.yml` file contains the Grafana configuration to add the Prometheus data source. This is how you connect the Grafana server to the Prometheus server. In the environment variables, you have set the Grafana admin user and password, which will be used to log in to the Grafana dashboard. + + ```yaml + apiVersion: 1 + datasources: + - name: Prometheus (Main) + type: prometheus + url: http://prometheus:9090 + isDefault: true + ``` + + In the `grafana.yml` file, you have defined a Prometheus data source named `Prometheus (Main)`. The `type` field specifies the type of the data source, which is `prometheus`. The `url` field specifies the URL of the Prometheus server to fetch the metrics from. In this case, the URL is `http://prometheus:9090`. `prometheus` is the service name of the Prometheus server in the Docker Compose file. The `isDefault` field specifies whether the data source is the default data source in Grafana. + +Apart from the services, the Docker Compose file also defines a volume named `grafana-data` to persist the Grafana data and a network named `go-network` to connect the services together. You have created a custom network `go-network` to connect the services together. The `driver: bridge` field specifies the network driver to use for the network. + +### Building and running the services + +Now that you have the Docker Compose file, you can build the services and run them together using Docker Compose. + +To build and run the services, run the following command in the terminal: + +```console +$ docker compose up +``` + +The `docker compose up` command builds the services defined in the Docker Compose file and runs them together. You will see the similar output in the terminal: + +```console + ✔ Network go-prometheus-monitoring_go-network Created 0.0s + ✔ Container grafana Created 0.3s + ✔ Container go-api Created 0.2s + ✔ Container prometheus Created 0.3s +Attaching to go-api, grafana, prometheus +go-api | [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached. +go-api | +go-api | [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. +go-api | - using env: export GIN_MODE=release +go-api | - using code: gin.SetMode(gin.ReleaseMode) +go-api | +go-api | [GIN-debug] GET /metrics --> main.PrometheusHandler.func1 (3 handlers) +go-api | [GIN-debug] GET /health --> main.main.func1 (4 handlers) +go-api | [GIN-debug] GET /v1/users --> main.main.func2 (4 handlers) +go-api | [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value. +go-api | Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details. +go-api | [GIN-debug] Listening and serving HTTP on :8000 +prometheus | ts=2025-03-15T05:57:06.676Z caller=main.go:627 level=info msg="No time or size retention was set so using the default time retention" duration=15d +prometheus | ts=2025-03-15T05:57:06.678Z caller=main.go:671 level=info msg="Starting Prometheus Server" mode=server version="(version=2.55.0, branch=HEAD, revision=91d80252c3e528728b0f88d254dd720f6be07cb8)" +grafana | logger=settings t=2025-03-15T05:57:06.865335506Z level=info msg="Config overridden from command line" arg="default.log.mode=console" +grafana | logger=settings t=2025-03-15T05:57:06.865337131Z level=info msg="Config overridden from Environment variable" var="GF_PATHS_DATA=/var/lib/grafana" +grafana | logger=ngalert.state.manager t=2025-03-15T05:57:07.088956839Z level=info msg="State +. +. +grafana | logger=plugin.angulardetectorsprovider.dynamic t=2025-03-15T05:57:07.530317298Z level=info msg="Patterns update finished" duration=440.489125ms +``` + +The services will start running, and you can access the Golang application at `http://localhost:8000`, Prometheus at `http://localhost:9090/health`, and Grafana at `http://localhost:3000`. You can also check the running containers using the `docker ps` command. + +```console +$ docker ps +``` + +### Summary + +In this section, you learned how to connect services together using Docker Compose. You created a Docker Compose file to run multiple services together and connect them using networks. You also learned how to build and run the services using Docker Compose. + +Related information: + + - [Docker Compose overview](/manuals/compose/_index.md) + - [Compose file reference](/reference/compose-file/_index.md) + +Next, you will learn how to develop the Golang application with Docker Compose and monitor it with Prometheus and Grafana. + +### Next steps + +In the next section, you will learn how to develop the Golang application with Docker. You will also learn how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source. + +## Developing your application + +In the last section, you saw how using Docker Compose, you can connect your services together. In this section, you will learn how to develop the Golang application with Docker. You will also see how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source. + +### Developing the application + +Now, if you make any changes to your Golang application locally, it needs to reflect in the container, right? To do that, one approach is use the `--build` flag in Docker Compose after making changes in the code. This will rebuild all the services which have the `build` instruction in the `compose.yml` file, in your case, the `api` service (Golang application). + +```console +docker compose up --build +``` + +But, this is not the best approach. This is not efficient. Every time you make a change in the code, you need to rebuild manually. This is not is not a good flow for development. + +The better approach is to use Docker Compose Watch. In the `compose.yml` file, under the service `api`, you have added the `develop` section. So, it's more like a hot reloading. Whenever you make changes to code (defined in `path`), it will rebuild the image (or restart depending on the action). This is how you can use it: + +```yaml {hl_lines="17-20",linenos=true} +services: + api: + container_name: go-api + build: + context: . + dockerfile: Dockerfile + image: go-api:latest + ports: + - 8000:8000 + networks: + - go-network + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 5 + develop: + watch: + - path: . + action: rebuild +``` + +Once you have added the `develop` section in the `compose.yml` file, you can use the following command to start the development server: + +```console +$ docker compose watch +``` + +Now, if you modify your `main.go` or any other file in the project, the `api` service will be rebuilt automatically. You will see the following output in the terminal: + +```bash +Rebuilding service(s) ["api"] after changes were detected... +[+] Building 8.1s (15/15) FINISHED docker:desktop-linux + => [api internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 704B 0.0s + => [api internal] load metadata for docker.io/library/alpine:3.17 1.1s + . + => => exporting manifest list sha256:89ebc86fd51e27c1da440dc20858ff55fe42211a1930c2d51bbdce09f430c7f1 0.0s + => => naming to docker.io/library/go-api:latest 0.0s + => => unpacking to docker.io/library/go-api:latest 0.0s + => [api] resolving provenance for metadata file 0.0s +service(s) ["api"] successfully built +``` + +### Testing the application + +Now that you have your application running, head over to the Grafana dashboard to visualize the metrics you are registering. Open your browser and navigate to `http://localhost:3000`. You will be greeted with the Grafana login page. The login credentials are the ones provided in Compose file. + +Once you are logged in, you can create a new dashboard. While creating dashboard you will notice that is default data source is `Prometheus`. This is because you have already configured the data source in the `grafana.yml` file. + +![The optional settings screen with the options specified.](../images/grafana-dash.png) + +You can use different panels to visualize the metrics. This guide doesn't go into details of Grafana. You can refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/) for more information. There is a Bar Gauge panel to visualize the total number of requests from different endpoints. You used the `api_http_request_total` and `api_http_request_error_total` metrics to get the data. + +![The optional settings screen with the options specified.](../images/grafana-panel.png) + +You created this panel to visualize the total number of requests from different endpoints to compare the successful and failed requests. For all the good requests, the bar will be green, and for all the failed requests, the bar will be red. Plus it will also show the from which endpoint the request is coming, either it's a successful request or a failed request. If you want to use this panel, you can import the `dashboard.json` file from the repository you cloned. + +### Summary + +You've come to the end of this guide. You learned how to develop the Golang application with Docker. You also saw how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you tested the application and visualized the metrics in Grafana using Prometheus as the data source. \ No newline at end of file diff --git a/content/guides/go-prometheus-monitoring/_index.md b/content/guides/go-prometheus-monitoring/_index.md deleted file mode 100644 index a295ab77a144..000000000000 --- a/content/guides/go-prometheus-monitoring/_index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: Containerize a Golang application and monitor it with Prometheus and Grafana. -keywords: golang, prometheus, grafana, monitoring, containerize -title: Monitor a Golang application with Prometheus and Grafana -summary: | - Learn how to containerize a Golang application and monitor it with Prometheus and Grafana. -linkTitle: Prometheus and Grafana -languages: [go] -params: - time: 45 minutes ---- - -The guide teaches you how to containerize a Golang application and monitor it with Prometheus and Grafana. - -> **Acknowledgment** -> -> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. - -## Overview - -To make sure your application is working as intended, monitoring is important. One of the most popular monitoring tools is Prometheus. Prometheus is an open-source monitoring and alerting toolkit that is designed for reliability and scalability. It collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. To visualize the metrics, you can use Grafana. Grafana is an open-source platform for monitoring and observability that allows you to query, visualize, alert on, and understand your metrics no matter where they are stored. - -In this guide, you will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus. Finally, you will visualize the metrics using Grafana. You will containerize the Golang application, and using the Docker Compose file, you will connect all the services: Golang, Prometheus, and Grafana. - -## What will you learn? - -* Create a Golang application with custom Prometheus metrics. -* Containerize a Golang application. -* Use Docker Compose to run multiple services and connect them together to monitor a Golang application with Prometheus and Grafana. -* Visualize the metrics using Grafana dashboards. - -## Prerequisites - -- A good understanding of Golang is assumed. -- You must me familiar with Prometheus and creating dashboards in Grafana. -- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -## Next steps - -You will create a Golang server and expose metrics using Prometheus. diff --git a/content/guides/go-prometheus-monitoring/application.md b/content/guides/go-prometheus-monitoring/application.md deleted file mode 100644 index 9845b9e127e1..000000000000 --- a/content/guides/go-prometheus-monitoring/application.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -title: Building the application -linkTitle: Understand the application -weight: 10 # -keywords: go, golang, prometheus, grafana, containerize, monitor -description: Learn how to create a Golang server to register metrics with Prometheus. ---- - -## Prerequisites - -* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -You will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus. - -## Getting the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following -command to clone the repository: - -```console -$ git clone https://github.com/dockersamples/go-prometheus-monitoring.git -``` - -Once you cloned you will see the following content structure inside `go-prometheus-monitoring` directory, - -```text -go-prometheus-monitoring -├── CONTRIBUTING.md -├── Docker -│ ├── grafana.yml -│ └── prometheus.yml -├── dashboard.json -├── Dockerfile -├── LICENSE -├── README.md -├── compose.yaml -├── go.mod -├── go.sum -└── main.go -``` - -- **main.go** - The entry point of the application. -- **go.mod and go.sum** - Go module files. -- **Dockerfile** - Dockerfile used to build the app. -- **Docker/** - Contains the Docker Compose configuration files for Grafana and Prometheus. -- **compose.yaml** - Compose file to launch everything (Golang app, Prometheus, and Grafana). -- **dashboard.json** - Grafana dashboard configuration file. -- **Dockerfile** - Dockerfile used to build the Golang app. -- **compose.yaml** - Docker Compose file to launch everything (Golang app, Prometheus, and Grafana). -- Other files are for licensing and documentation purposes. - -## Understanding the application - -The following is the complete logic of the application you will find in `main.go`. - -```go -package main - -import ( - "strconv" - - "github.com/gin-gonic/gin" - "github.com/prometheus/client_golang/prometheus" - "github.com/prometheus/client_golang/prometheus/promhttp" -) - -// Define metrics -var ( - HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ - Name: "api_http_request_total", - Help: "Total number of requests processed by the API", - }, []string{"path", "status"}) - - HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ - Name: "api_http_request_error_total", - Help: "Total number of errors returned by the API", - }, []string{"path", "status"}) -) - -// Custom registry (without default Go metrics) -var customRegistry = prometheus.NewRegistry() - -// Register metrics with custom registry -func init() { - customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal) -} - -func main() { - router := gin.Default() - - // Register /metrics before middleware - router.GET("/metrics", PrometheusHandler()) - - router.Use(RequestMetricsMiddleware()) - router.GET("/health", func(c *gin.Context) { - c.JSON(200, gin.H{ - "message": "Up and running!", - }) - }) - router.GET("/v1/users", func(c *gin.Context) { - c.JSON(200, gin.H{ - "message": "Hello from /v1/users", - }) - }) - - router.Run(":8000") -} - -// Custom metrics handler with custom registry -func PrometheusHandler() gin.HandlerFunc { - h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{}) - return func(c *gin.Context) { - h.ServeHTTP(c.Writer, c.Request) - } -} - -// Middleware to record incoming requests metrics -func RequestMetricsMiddleware() gin.HandlerFunc { - return func(c *gin.Context) { - path := c.Request.URL.Path - c.Next() - status := c.Writer.Status() - if status < 400 { - HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() - } else { - HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() - } - } -} -``` - -In this part of the code, you have imported the required packages `gin`, `prometheus`, and `promhttp`. Then you have defined a couple of variables, `HttpRequestTotal` and `HttpRequestErrorTotal` are Prometheus counter metrics, and `customRegistry` is a custom registry that will be used to register these metrics. The name of the metric is a string that you can use to identify the metric. The help string is a string that will be shown when you query the `/metrics` endpoint to understand the metric. The reason you are using the custom registry is so avoid the default Go metrics that are registered by default by the Prometheus client. Then using the `init` function you are registering the metrics with the custom registry. - -```go -import ( - "strconv" - - "github.com/gin-gonic/gin" - "github.com/prometheus/client_golang/prometheus" - "github.com/prometheus/client_golang/prometheus/promhttp" -) - -// Define metrics -var ( - HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ - Name: "api_http_request_total", - Help: "Total number of requests processed by the API", - }, []string{"path", "status"}) - - HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{ - Name: "api_http_request_error_total", - Help: "Total number of errors returned by the API", - }, []string{"path", "status"}) -) - -// Custom registry (without default Go metrics) -var customRegistry = prometheus.NewRegistry() - -// Register metrics with custom registry -func init() { - customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal) -} -``` - -In the `main` function, you have created a new instance of the `gin` framework and created three routes. You can see the health endpoint that is on path `/health` that will return a JSON with `{"message": "Up and running!"}` and the `/v1/users` endpoint that will return a JSON with `{"message": "Hello from /v1/users"}`. The third route is for the `/metrics` endpoint that will return the metrics in the Prometheus format. Then you have `RequestMetricsMiddleware` middleware, it will be called for every request made to the API. It will record the incoming requests metrics like status codes and paths. Finally, you are running the gin application on port 8000. - -```golang -func main() { - router := gin.Default() - - // Register /metrics before middleware - router.GET("/metrics", PrometheusHandler()) - - router.Use(RequestMetricsMiddleware()) - router.GET("/health", func(c *gin.Context) { - c.JSON(200, gin.H{ - "message": "Up and running!", - }) - }) - router.GET("/v1/users", func(c *gin.Context) { - c.JSON(200, gin.H{ - "message": "Hello from /v1/users", - }) - }) - - router.Run(":8000") -} -``` - -Now comes the middleware function `RequestMetricsMiddleware`. This function is called for every request made to the API. It increments the `HttpRequestTotal` counter (different counter for different paths and status codes) if the status code is less than or equal to 400. If the status code is greater than 400, it increments the `HttpRequestErrorTotal` counter (different counter for different paths and status codes). The `PrometheusHandler` function is the custom handler that will be called for the `/metrics` endpoint. It will return the metrics in the Prometheus format. - -```golang -// Custom metrics handler with custom registry -func PrometheusHandler() gin.HandlerFunc { - h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{}) - return func(c *gin.Context) { - h.ServeHTTP(c.Writer, c.Request) - } -} - -// Middleware to record incoming requests metrics -func RequestMetricsMiddleware() gin.HandlerFunc { - return func(c *gin.Context) { - path := c.Request.URL.Path - c.Next() - status := c.Writer.Status() - if status < 400 { - HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() - } else { - HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc() - } - } -} -``` - -That's it, this was the complete gist of the application. Now it's time to run and test if the app is registering metrics correctly. - -## Running the application - -Make sure you are still inside `go-prometheus-monitoring` directory in the terminal, and run the following command. Install the dependencies by running `go mod tidy` and then build and run the application by running `go run main.go`. Then visit `http://localhost:8000/health` or `http://localhost:8000/v1/users`. You should see the output `{"message": "Up and running!"}` or `{"message": "Hello from /v1/users"}`. If you are able to see this then your app is successfully up and running. - - -Now, check your application's metrics by accessing the `/metrics` endpoint. -Open `http://localhost:8000/metrics` in your browser. You should see similar output to the following. - -```sh -# HELP api_http_request_error_total Total number of errors returned by the API -# TYPE api_http_request_error_total counter -api_http_request_error_total{path="/",status="404"} 1 -api_http_request_error_total{path="//v1/users",status="404"} 1 -api_http_request_error_total{path="/favicon.ico",status="404"} 1 -# HELP api_http_request_total Total number of requests processed by the API -# TYPE api_http_request_total counter -api_http_request_total{path="/health",status="200"} 2 -api_http_request_total{path="/v1/users",status="200"} 1 -``` - -In the terminal, press `ctrl` + `c` to stop the application. - -> [!Note] -> If you don't want to run the application locally, and want to run it in a Docker container, skip to next page where you create a Dockerfile and containerize the application. - -## Summary - -In this section, you learned how to create a Golang app to register metrics with Prometheus. By implementing middleware functions, you were able to increment the counters based on the request path and status codes. - -## Next steps - -In the next section, you'll learn how to containerize your application. diff --git a/content/guides/go-prometheus-monitoring/compose.md b/content/guides/go-prometheus-monitoring/compose.md deleted file mode 100644 index c4dcbbab6122..000000000000 --- a/content/guides/go-prometheus-monitoring/compose.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Connecting services with Docker Compose -linkTitle: Connect with Compose -weight: 30 # -keywords: go, golang, prometheus, grafana, containerize, monitor -description: Learn how to connect services with Docker Compose to monitor a Golang application with Prometheus and Grafana. ---- - -Now that you have containerized the Golang application, you will use Docker Compose to connect your services together. You will connect the Golang application, Prometheus, and Grafana services together to monitor the Golang application with Prometheus and Grafana. - -## Creating a Docker Compose file - -Create a new file named `compose.yml` in the root directory of your Golang application. The Docker Compose file contains instructions to run multiple services and connect them together. - -Here is a Docker Compose file for a project that uses Golang, Prometheus, and Grafana. You will also find this file in the `go-prometheus-monitoring` directory. - -```yaml -services: - api: - container_name: go-api - build: - context: . - dockerfile: Dockerfile - image: go-api:latest - ports: - - 8000:8000 - networks: - - go-network - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8000/health"] - interval: 30s - timeout: 10s - retries: 5 - develop: - watch: - - path: . - action: rebuild - - prometheus: - container_name: prometheus - image: prom/prometheus:v2.55.0 - volumes: - - ./Docker/prometheus.yml:/etc/prometheus/prometheus.yml - ports: - - 9090:9090 - networks: - - go-network - - grafana: - container_name: grafana - image: grafana/grafana:11.3.0 - volumes: - - ./Docker/grafana.yml:/etc/grafana/provisioning/datasources/datasource.yaml - - grafana-data:/var/lib/grafana - ports: - - 3000:3000 - networks: - - go-network - environment: - - GF_SECURITY_ADMIN_USER=admin - - GF_SECURITY_ADMIN_PASSWORD=password - -volumes: - grafana-data: - -networks: - go-network: - driver: bridge -``` - -## Understanding the Docker Compose file - -The Docker Compose file consists of three services: - -- **Golang application service**: This service builds the Golang application using the Dockerfile and runs it in a container. It exposes the application's port `8000` and connects to the `go-network` network. It also defines a health check to monitor the application's health. You have also used `healthcheck` to monitor the health of the application. The health check runs every 30 seconds and retries 5 times if the health check fails. The health check uses the `curl` command to check the `/health` endpoint of the application. Apart from the health check, you have also added a `develop` section to watch the changes in the application's source code and rebuild the application using the Docker Compose Watch feature. - -- **Prometheus service**: This service runs the Prometheus server in a container. It uses the official Prometheus image `prom/prometheus:v2.55.0`. It exposes the Prometheus server on port `9090` and connects to the `go-network` network. You have also mounted the `prometheus.yml` file from the `Docker` directory which is present in the root directory of your project. The `prometheus.yml` file contains the Prometheus configuration to scrape the metrics from the Golang application. This is how you connect the Prometheus server to the Golang application. - - ```yaml - global: - scrape_interval: 10s - evaluation_interval: 10s - - scrape_configs: - - job_name: myapp - static_configs: - - targets: ["api:8000"] - ``` - - In the `prometheus.yml` file, you have defined a job named `myapp` to scrape the metrics from the Golang application. The `targets` field specifies the target to scrape the metrics from. In this case, the target is the Golang application running on port `8000`. The `api` is the service name of the Golang application in the Docker Compose file. The Prometheus server will scrape the metrics from the Golang application every 10 seconds. - -- **Grafana service**: This service runs the Grafana server in a container. It uses the official Grafana image `grafana/grafana:11.3.0`. It exposes the Grafana server on port `3000` and connects to the `go-network` network. You have also mounted the `grafana.yml` file from the `Docker` directory which is present in the root directory of your project. The `grafana.yml` file contains the Grafana configuration to add the Prometheus data source. This is how you connect the Grafana server to the Prometheus server. In the environment variables, you have set the Grafana admin user and password, which will be used to log in to the Grafana dashboard. - - ```yaml - apiVersion: 1 - datasources: - - name: Prometheus (Main) - type: prometheus - url: http://prometheus:9090 - isDefault: true - ``` - - In the `grafana.yml` file, you have defined a Prometheus data source named `Prometheus (Main)`. The `type` field specifies the type of the data source, which is `prometheus`. The `url` field specifies the URL of the Prometheus server to fetch the metrics from. In this case, the URL is `http://prometheus:9090`. `prometheus` is the service name of the Prometheus server in the Docker Compose file. The `isDefault` field specifies whether the data source is the default data source in Grafana. - -Apart from the services, the Docker Compose file also defines a volume named `grafana-data` to persist the Grafana data and a network named `go-network` to connect the services together. You have created a custom network `go-network` to connect the services together. The `driver: bridge` field specifies the network driver to use for the network. - -## Building and running the services - -Now that you have the Docker Compose file, you can build the services and run them together using Docker Compose. - -To build and run the services, run the following command in the terminal: - -```console -$ docker compose up -``` - -The `docker compose up` command builds the services defined in the Docker Compose file and runs them together. You will see the similar output in the terminal: - -```console - ✔ Network go-prometheus-monitoring_go-network Created 0.0s - ✔ Container grafana Created 0.3s - ✔ Container go-api Created 0.2s - ✔ Container prometheus Created 0.3s -Attaching to go-api, grafana, prometheus -go-api | [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached. -go-api | -go-api | [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. -go-api | - using env: export GIN_MODE=release -go-api | - using code: gin.SetMode(gin.ReleaseMode) -go-api | -go-api | [GIN-debug] GET /metrics --> main.PrometheusHandler.func1 (3 handlers) -go-api | [GIN-debug] GET /health --> main.main.func1 (4 handlers) -go-api | [GIN-debug] GET /v1/users --> main.main.func2 (4 handlers) -go-api | [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value. -go-api | Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details. -go-api | [GIN-debug] Listening and serving HTTP on :8000 -prometheus | ts=2025-03-15T05:57:06.676Z caller=main.go:627 level=info msg="No time or size retention was set so using the default time retention" duration=15d -prometheus | ts=2025-03-15T05:57:06.678Z caller=main.go:671 level=info msg="Starting Prometheus Server" mode=server version="(version=2.55.0, branch=HEAD, revision=91d80252c3e528728b0f88d254dd720f6be07cb8)" -grafana | logger=settings t=2025-03-15T05:57:06.865335506Z level=info msg="Config overridden from command line" arg="default.log.mode=console" -grafana | logger=settings t=2025-03-15T05:57:06.865337131Z level=info msg="Config overridden from Environment variable" var="GF_PATHS_DATA=/var/lib/grafana" -grafana | logger=ngalert.state.manager t=2025-03-15T05:57:07.088956839Z level=info msg="State -. -. -grafana | logger=plugin.angulardetectorsprovider.dynamic t=2025-03-15T05:57:07.530317298Z level=info msg="Patterns update finished" duration=440.489125ms -``` - -The services will start running, and you can access the Golang application at `http://localhost:8000`, Prometheus at `http://localhost:9090/health`, and Grafana at `http://localhost:3000`. You can also check the running containers using the `docker ps` command. - -```console -$ docker ps -``` - -## Summary - -In this section, you learned how to connect services together using Docker Compose. You created a Docker Compose file to run multiple services together and connect them using networks. You also learned how to build and run the services using Docker Compose. - -Related information: - - - [Docker Compose overview](/manuals/compose/_index.md) - - [Compose file reference](/reference/compose-file/_index.md) - -Next, you will learn how to develop the Golang application with Docker Compose and monitor it with Prometheus and Grafana. - -## Next steps - -In the next section, you will learn how to develop the Golang application with Docker. You will also learn how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source. diff --git a/content/guides/go-prometheus-monitoring/containerize.md b/content/guides/go-prometheus-monitoring/containerize.md deleted file mode 100644 index a628c380618f..000000000000 --- a/content/guides/go-prometheus-monitoring/containerize.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Containerize a Golang application -linkTitle: Containerize your app -weight: 20 -keywords: go, golang, containerize, initialize -description: Learn how to containerize a Golang application. ---- - -Containerization helps you bundle the application and its dependencies into a single package called a container. This package can run on any platform without worrying about the environment. In this section, you will learn how to containerize a Golang application using Docker. - -To containerize a Golang application, you first need to create a Dockerfile. The Dockerfile contains instructions to build and run the application in a container. Also, when creating a Dockerfile, you can follow different sets of best practices to optimize the image size and make it more secure. - -## Creating a Dockerfile - -Create a new file named `Dockerfile` in the root directory of your Golang application. The Dockerfile contains instructions to build and run the application in a container. - -The following is a Dockerfile for a Golang application. You will also find this file in the `go-prometheus-monitoring` directory. - -```dockerfile -# Use the official Golang image as the base -FROM golang:1.24-alpine AS builder - -# Set environment variables -ENV CGO_ENABLED=0 \ - GOOS=linux \ - GOARCH=amd64 - -# Set working directory inside the container -WORKDIR /build - -# Copy go.mod and go.sum files for dependency installation -COPY go.mod go.sum ./ - -# Download dependencies -RUN go mod download - -# Copy the entire application source -COPY . . - -# Build the Go binary -RUN go build -o /app . - -# Final lightweight stage -FROM alpine:3.21 AS final - -# Copy the compiled binary from the builder stage -COPY --from=builder /app /bin/app - -# Expose the application's port -EXPOSE 8000 - -# Run the application -CMD ["bin/app"] -``` - -## Understanding the Dockerfile - -The Dockerfile consists of two stages: - -1. **Build stage**: This stage uses the official Golang image as the base and sets the necessary environment variables. It also sets the working directory inside the container, copies the `go.mod` and `go.sum` files for dependency installation, downloads the dependencies, copies the entire application source, and builds the Go binary. - - You use the `golang:1.24-alpine` image as the base image for the build stage. The `CGO_ENABLED=0` environment variable disables CGO, which is useful for building static binaries. You also set the `GOOS` and `GOARCH` environment variables to `linux` and `amd64`, respectively, to build the binary for the Linux platform. - -2. **Final stage**: This stage uses the official Alpine image as the base and copies the compiled binary from the build stage. It also exposes the application's port and runs the application. - - You use the `alpine:3.21` image as the base image for the final stage. You copy the compiled binary from the build stage to the final image. You expose the application's port using the `EXPOSE` instruction and run the application using the `CMD` instruction. - - Apart from the multi-stage build, the Dockerfile also follows best practices such as using the official images, setting the working directory, and copying only the necessary files to the final image. You can further optimize the Dockerfile by other best practices. - -## Build the Docker image and run the application - -One you have the Dockerfile, you can build the Docker image and run the application in a container. - -To build the Docker image, run the following command in the terminal: - -```console -$ docker build -t go-api:latest . -``` - -After building the image, you can run the application in a container using the following command: - -```console -$ docker run -p 8000:8000 go-api:latest -``` - -The application will start running inside the container, and you can access it at `http://localhost:8000`. You can also check the running containers using the `docker ps` command. - -```console -$ docker ps -``` - -## Summary - -In this section, you learned how to containerize a Golang application using a Dockerfile. You created a multi-stage Dockerfile to build and run the application in a container. You also learned about best practices to optimize the Docker image size and make it more secure. - -Related information: - - - [Dockerfile reference](/reference/dockerfile.md) - - [.dockerignore file](/reference/dockerfile.md#dockerignore-file) - -## Next steps - -In the next section, you will learn how to use Docker Compose to connect and run multiple services together to monitor a Golang application with Prometheus and Grafana. diff --git a/content/guides/go-prometheus-monitoring/develop.md b/content/guides/go-prometheus-monitoring/develop.md deleted file mode 100644 index 7cf147604f5d..000000000000 --- a/content/guides/go-prometheus-monitoring/develop.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Developing your application -linkTitle: Develop your app -weight: 40 -keywords: go, golang, containerize, initialize -description: Learn how to develop the Golang application with Docker. ---- - -In the last section, you saw how using Docker Compose, you can connect your services together. In this section, you will learn how to develop the Golang application with Docker. You will also see how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source. - -## Developing the application - -Now, if you make any changes to your Golang application locally, it needs to reflect in the container, right? To do that, one approach is use the `--build` flag in Docker Compose after making changes in the code. This will rebuild all the services which have the `build` instruction in the `compose.yml` file, in your case, the `api` service (Golang application). - -```console -docker compose up --build -``` - -But, this is not the best approach. This is not efficient. Every time you make a change in the code, you need to rebuild manually. This is not is not a good flow for development. - -The better approach is to use Docker Compose Watch. In the `compose.yml` file, under the service `api`, you have added the `develop` section. So, it's more like a hot reloading. Whenever you make changes to code (defined in `path`), it will rebuild the image (or restart depending on the action). This is how you can use it: - -```yaml {hl_lines="17-20",linenos=true} -services: - api: - container_name: go-api - build: - context: . - dockerfile: Dockerfile - image: go-api:latest - ports: - - 8000:8000 - networks: - - go-network - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/health"] - interval: 30s - timeout: 10s - retries: 5 - develop: - watch: - - path: . - action: rebuild -``` - -Once you have added the `develop` section in the `compose.yml` file, you can use the following command to start the development server: - -```console -$ docker compose watch -``` - -Now, if you modify your `main.go` or any other file in the project, the `api` service will be rebuilt automatically. You will see the following output in the terminal: - -```bash -Rebuilding service(s) ["api"] after changes were detected... -[+] Building 8.1s (15/15) FINISHED docker:desktop-linux - => [api internal] load build definition from Dockerfile 0.0s - => => transferring dockerfile: 704B 0.0s - => [api internal] load metadata for docker.io/library/alpine:3.17 1.1s - . - => => exporting manifest list sha256:89ebc86fd51e27c1da440dc20858ff55fe42211a1930c2d51bbdce09f430c7f1 0.0s - => => naming to docker.io/library/go-api:latest 0.0s - => => unpacking to docker.io/library/go-api:latest 0.0s - => [api] resolving provenance for metadata file 0.0s -service(s) ["api"] successfully built -``` - -## Testing the application - -Now that you have your application running, head over to the Grafana dashboard to visualize the metrics you are registering. Open your browser and navigate to `http://localhost:3000`. You will be greeted with the Grafana login page. The login credentials are the ones provided in Compose file. - -Once you are logged in, you can create a new dashboard. While creating dashboard you will notice that is default data source is `Prometheus`. This is because you have already configured the data source in the `grafana.yml` file. - -![The optional settings screen with the options specified.](../images/grafana-dash.png) - -You can use different panels to visualize the metrics. This guide doesn't go into details of Grafana. You can refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/) for more information. There is a Bar Gauge panel to visualize the total number of requests from different endpoints. You used the `api_http_request_total` and `api_http_request_error_total` metrics to get the data. - -![The optional settings screen with the options specified.](../images/grafana-panel.png) - -You created this panel to visualize the total number of requests from different endpoints to compare the successful and failed requests. For all the good requests, the bar will be green, and for all the failed requests, the bar will be red. Plus it will also show the from which endpoint the request is coming, either it's a successful request or a failed request. If you want to use this panel, you can import the `dashboard.json` file from the repository you cloned. - -## Summary - -You've come to the end of this guide. You learned how to develop the Golang application with Docker. You also saw how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you tested the application and visualized the metrics in Grafana using Prometheus as the data source. \ No newline at end of file diff --git a/content/guides/golang.md b/content/guides/golang.md new file mode 100644 index 000000000000..5d9a1ccf00b1 --- /dev/null +++ b/content/guides/golang.md @@ -0,0 +1,1542 @@ +--- +title: Go language-specific guide +linkTitle: Go +description: Containerize Go apps using Docker +keywords: docker, getting started, go, golang, language, dockerfile +summary: | + This guide teaches you how to containerize Go applications using Docker. +aliases: + - /language/golang/ + - /guides/language/golang/ + - /get-started/golang/build-images/ + - /language/golang/build-images/ + - /get-started/golang/run-containers/ + - /language/golang/run-containers/ + - /get-started/golang/develop/ + - /language/golang/develop/ + - /get-started/golang/run-tests/ + - /language/golang/run-tests/ + - /language/golang/configure-ci-cd/ + - /language/golang/deploy/ + - /guides/golang/build-images/ + - /guides/golang/configure-ci-cd/ + - /guides/golang/deploy/ + - /guides/golang/develop/ + - /guides/golang/run-containers/ + - /guides/golang/run-tests/ +params: + tags: [languages] + time: 30 minutes +--- + +This guide will show you how to create, test, and deploy containerized Go applications using Docker. + +> **Acknowledgment** +> +> Docker would like to thank [Oliver Frolovs](https://www.linkedin.com/in/ofr/) for his contribution to this guide. + +## What will you learn? + +In this guide, you’ll learn how to: + +- Create a `Dockerfile` which contains the instructions for building a container image for a program written in Go. +- Run the image as a container in your local Docker instance and manage the container's lifecycle. +- Use multi-stage builds for building small images efficiently while keeping your Dockerfiles easy to read and maintain. +- Use Docker Compose to orchestrate running of multiple related containers together in a development environment. + +## Prerequisites + +Some basic understanding of Go and its toolchain is assumed. This isn't a Go tutorial. If you are new to the : languages:, +the [Go website](https://golang.org/) is a great place to explore, +so _go_ (pun intended) check it out! + +You also must know some basic [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container.md) as well as to +be at least vaguely familiar with the [Dockerfile format](/manuals/build/concepts/dockerfile.md). + +Your Docker set-up must have BuildKit enabled. BuildKit is enabled by default for all users on [Docker Desktop](/manuals/desktop/_index.md). +If you have installed Docker Desktop, you don’t have to manually enable BuildKit. If you are running Docker on Linux, +please check out BuildKit [getting started](/manuals/build/buildkit/_index.md#getting-started) page. + +Some familiarity with the command line is also expected. + +## What's next? + +The aim of this guide is to provide enough examples and instructions for you to containerize your own Go application and deploy it into the Cloud. + +Start by building your first Go image. + +## Build your Go image + +### Overview + +In this section you're going to build a container image. The image includes +everything you need to run your application – the compiled application binary +file, the runtime, the libraries, and all other resources required by your +application. + +### Required software + +To complete this tutorial, you need the following: + +- Docker running locally. Follow the [instructions to download and install Docker](/manuals/desktop/_index.md). +- An IDE or a text editor to edit files. [Visual Studio Code](https://code.visualstudio.com/) is a free and popular choice but you can use anything you feel comfortable with. +- A Git client. This guide uses a command-line based `git` client, but you are free to use whatever works for you. +- A command-line terminal application. The examples shown in this module are from the Linux shell, but they should work in PowerShell, Windows Command Prompt, or OS X Terminal with minimal, if any, modifications. + +### Meet the example application + +The example application is a caricature of a microservice. It is purposefully trivial to keep focus on learning the basics of containerization for Go applications. + +The application offers two HTTP endpoints: + +- It responds with a string containing a heart symbol (`<3`) to requests to `/`. +- It responds with `{"Status" : "OK"}` JSON to a request to `/health`. + +It responds with HTTP error 404 to any other request. + +The application listens on a TCP port defined by the value of environment variable `PORT`. The default value is `8080`. + +The application is stateless. + +The complete source code for the application is on GitHub: [github.com/docker/docker-gs-ping](https://github.com/docker/docker-gs-ping). You are encouraged to fork it and experiment with it as much as you like. + +To continue, clone the application repository to your local machine: + +```console +$ git clone https://github.com/docker/docker-gs-ping +``` + +The application's `main.go` file is straightforward, if you are familiar with Go: + +```go +package main + +import ( + "net/http" + "os" + + "github.com/labstack/echo/v4" + "github.com/labstack/echo/v4/middleware" +) + +func main() { + + e := echo.New() + + e.Use(middleware.Logger()) + e.Use(middleware.Recover()) + + e.GET("/", func(c echo.Context) error { + return c.HTML(http.StatusOK, "Hello, Docker! <3") + }) + + e.GET("/health", func(c echo.Context) error { + return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"}) + }) + + httpPort := os.Getenv("PORT") + if httpPort == "" { + httpPort = "8080" + } + + e.Logger.Fatal(e.Start(":" + httpPort)) +} + +// Simple implementation of an integer minimum +// Adapted from: https://gobyexample.com/testing-and-benchmarking +func IntMin(a, b int) int { + if a < b { + return a + } + return b +} +``` + +### Create a Dockerfile for the application + +To build a container image with Docker, a `Dockerfile` with build instructions is required. + +Begin your `Dockerfile` with the (optional) parser directive line that instructs BuildKit to +interpret your file according to the grammar rules for the specified version of the syntax. + +You then tell Docker what base image you would like to use for your application: + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM golang:1.19 +``` + +Docker images can be inherited from other images. Therefore, instead of creating +your own base image from scratch, you can use the official Go image that already +has all necessary tools and libraries to compile and run a Go application. + +> [!NOTE] +> +> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](/manuals/build/building/base-images.md#create-a-base-image). +> Note, however, that this isn't necessary to continue with your task at hand. + +Now that you have defined the base image for your upcoming container image, you +can begin building on top of it. + +To make things easier when running the rest of your commands, create a directory +inside the image that you're building. This also instructs Docker to use this +directory as the default destination for all subsequent commands. This way you +don't have to type out full file paths in the `Dockerfile`, the relative paths +will be based on this directory. + +```dockerfile +WORKDIR /app +``` + +Usually the very first thing you do once you’ve downloaded a project written in +Go is to install the modules necessary to compile it. Note, that the base image +has the toolchain already, but your source code isn't in it yet. + +So before you can run `go mod download` inside your image, you need to get your +`go.mod` and `go.sum` files copied into it. Use the `COPY` command to do this. + +In its simplest form, the `COPY` command takes two parameters. The first +parameter tells Docker what files you want to copy into the image. The last +parameter tells Docker where you want that file to be copied to. + +Copy the `go.mod` and `go.sum` file into your project directory `/app` which, +owing to your use of `WORKDIR`, is the current directory (`./`) inside the +image. Unlike some modern shells that appear to be indifferent to the use of +trailing slash (`/`), and can figure out what the user meant (most of the time), +Docker's `COPY` command is quite sensitive in its interpretation of the trailing +slash. + +```dockerfile +COPY go.mod go.sum ./ +``` + +> [!NOTE] +> +> If you'd like to familiarize yourself with the trailing slash treatment by the +> `COPY` command, see [Dockerfile +> reference](/reference/dockerfile.md#copy). This trailing slash can +> cause issues in more ways than you can imagine. + +Now that you have the module files inside the Docker image that you are +building, you can use the `RUN` command to run the command `go mod download` +there as well. This works exactly the same as if you were running `go` locally +on your machine, but this time these Go modules will be installed into a +directory inside the image. + +```dockerfile +RUN go mod download +``` + +At this point, you have a Go toolchain version 1.19.x and all your Go +dependencies installed inside the image. + +The next thing you need to do is to copy your source code into the image. You’ll +use the `COPY` command just like you did with your module files before. + +```dockerfile +COPY *.go ./ +``` + +This `COPY` command uses a wildcard to copy all files with `.go` extension +located in the current directory on the host (the directory where the `Dockerfile` +is located) into the current directory inside the image. + +`COPY *.go ./` only matches `.go` files in that one directory. Packages +under `pkg/` or other subdirectories are left out, so `go build` then +fails to find them. For a multi-package module, copy the module root +instead (`COPY . .`) and use a `.dockerignore` file to keep the context +small. + +Now, to compile your application, use the familiar `RUN` command: + +```dockerfile +RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping +``` + +This should be familiar. The result of that command will be a static application +binary named `docker-gs-ping` and located in the root of the filesystem of the +image that you are building. You could have put the binary into any other place +you desire inside that image, the root directory has no special meaning in this +regard. It's convenient to use it to keep the file paths short for improved +readability. + +Now, all that is left to do is to tell Docker what command to run when your +image is used to start a container. + +You do this with the `CMD` command: + +```dockerfile +CMD ["/docker-gs-ping"] +``` + +Here's the complete `Dockerfile`: + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM golang:1.19 + +# Set destination for COPY +WORKDIR /app + +# Download Go modules +COPY go.mod go.sum ./ +RUN go mod download + +# Copy the source code. Note the slash at the end, as explained in +# https://docs.docker.com/reference/dockerfile/#copy +COPY *.go ./ + +# Build +RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping + +# Optional: +# To bind to a TCP port, runtime parameters must be supplied to the docker command. +# But we can document in the Dockerfile what ports +# the application is going to listen on by default. +# https://docs.docker.com/reference/dockerfile/#expose +EXPOSE 8080 + +# Run +CMD ["/docker-gs-ping"] +``` + +The `Dockerfile` may also contain comments. They always begin with a `#` symbol, +and must be at the beginning of a line. Comments are there for your convenience +to allow documenting your `Dockerfile`. + +There is also a concept of Dockerfile directives, such as the `syntax` directive +you added. The directives must always be at the very top of the `Dockerfile`, so +when adding comments, make sure that the comments follow after any directives +that you may have used: + +```dockerfile +# syntax=docker/dockerfile:1 +# A sample microservice in Go packaged into a container image. + +FROM golang:1.19 + +# ... +``` + +### Build the image + +Now that you've created your `Dockerfile`, build an image from it. The `docker +build` command creates Docker images from the `Dockerfile` and a context. A +build context is the set of files located in the specified path or URL. The +Docker build process can access any of the files located in the context. + +The build command optionally takes a `--tag` flag. This flag is used to label +the image with a string value, which is easy for humans to read and recognize. +If you don't pass a `--tag`, Docker will use `latest` as the default value. + +Build your first Docker image. + +```console +$ docker build --tag docker-gs-ping . +``` + +The build process will print some diagnostic messages as it goes through the build steps. +The following is an example of what these messages may look like. + +```console +[+] Building 2.2s (15/15) FINISHED + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 701B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => resolve image config for docker.io/docker/dockerfile:1 1.1s + => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:39b85bbfa7536a5feceb7372a0817649ecb2724562a38360f4d6a7782a409b14 0.0s + => [internal] load build definition from Dockerfile 0.0s + => [internal] load .dockerignore 0.0s + => [internal] load metadata for docker.io/library/golang:1.19 0.7s + => [1/6] FROM docker.io/library/golang:1.19@sha256:5d947843dde82ba1df5ac1b2ebb70b203d106f0423bf5183df3dc96f6bc5a705 0.0s + => [internal] load build context 0.0s + => => transferring context: 6.08kB 0.0s + => CACHED [2/6] WORKDIR /app 0.0s + => CACHED [3/6] COPY go.mod go.sum ./ 0.0s + => CACHED [4/6] RUN go mod download 0.0s + => CACHED [5/6] COPY *.go ./ 0.0s + => CACHED [6/6] RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping 0.0s + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:ede8ff889a0d9bc33f7a8da0673763c887a258eb53837dd52445cdca7b7df7e3 0.0s + => => naming to docker.io/library/docker-gs-ping 0.0s +``` + +Your exact output will vary, but provided there aren't any errors, you should +see the word `FINISHED` in the first line of output. This means Docker has +successfully built your image named `docker-gs-ping`. + +### View local images + +To see the list of images you have on your local machine, you have two options. +One is to use the CLI and the other is to use [Docker +Desktop](/manuals/desktop/_index.md). Since you're working in the +terminal, take a look at listing images with the CLI. + +To list images, run the `docker image ls`command (or the `docker images` shorthand): + +```console +$ docker image ls + +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-gs-ping latest 7f153fbcc0a8 2 minutes ago 1.11GB +... +``` + +Your exact output may vary, but you should see the `docker-gs-ping` image with +the `latest` tag. Because you didn't specify a custom tag when you built your +image, Docker assumed that the tag would be `latest`, which is a special value. + +### Tag images + +An image name is made up of slash-separated name components. Name components may +contain lowercase letters, digits, and separators. A separator is defined as a +period, one or two underscores, or one or more dashes. A name component may not +start or end with a separator. + +An image is made up of a manifest and a list of layers. In simple terms, a tag +points to a combination of these artifacts. You can have multiple tags for the +image and, in fact, most images have multiple tags. Create a second tag +for the image you built and take a look at its layers. + +Use the `docker image tag` (or `docker tag` shorthand) command to create a new +tag for your image. This command takes two arguments; the first argument is the +source image, and the second is the new tag to create. The following command +creates a new `docker-gs-ping:v1.0` tag for the `docker-gs-ping:latest` you +built: + +```console +$ docker image tag docker-gs-ping:latest docker-gs-ping:v1.0 +``` + +The Docker `tag` command creates a new tag for the image. It doesn't create a +new image. The tag points to the same image and is another way to reference +the image. + +Now run the `docker image ls` command again to see the updated list of local +images: + +```console +$ docker image ls + +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-gs-ping latest 7f153fbcc0a8 6 minutes ago 1.11GB +docker-gs-ping v1.0 7f153fbcc0a8 6 minutes ago 1.11GB +... +``` + +You can see that you have two images that start with `docker-gs-ping`. You know +they're the same image because if you look at the `IMAGE ID` column, you can +see that the values are the same for the two images. This value is a unique +identifier Docker uses internally to identify the image. + +Remove the tag that you just created. To do this, you’ll use the +`docker image rm` command, or the shorthand `docker rmi` (which stands for +"remove image"): + +```console +$ docker image rm docker-gs-ping:v1.0 +Untagged: docker-gs-ping:v1.0 +``` + +Notice that the response from Docker tells you that the image hasn't been +removed but only untagged. + +Verify this by running the following command: + +```console +$ docker image ls +``` + +You will see that the tag `v1.0` is no longer in the list of images kept by your Docker instance. + +```text +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-gs-ping latest 7f153fbcc0a8 7 minutes ago 1.11GB +... +``` + +The tag `v1.0` has been removed but you still have the `docker-gs-ping:latest` +tag available on your machine, so the image is there. + +### Multi-stage builds + +You may have noticed that your `docker-gs-ping` image weighs in at over a +gigabyte, which is a lot for a tiny compiled Go application. You may also be +wondering what happened to the full suite of Go tools, including the compiler, +after you had built your image. + +The answer is that the full toolchain is still there, in the container image. +Not only this is inconvenient because of the large file size, but it may also +present a security risk when the container is deployed. + +These two issues can be solved by using [multi-stage builds](/manuals/build/building/multi-stage.md). + +In a nutshell, a multi-stage build can carry over the artifacts from one build stage into another, +and every build stage can be instantiated from a different base image. + +Thus, in the following example, you are going to use a full-scale official Go +image to build your application. Then you'll copy the application binary into +another image whose base is very lean and doesn't include the Go toolchain or +other optional components. + +The `Dockerfile.multistage` in the sample application's repository has the +following content: + +```dockerfile +# syntax=docker/dockerfile:1 + +# Build the application from source +FROM golang:1.19 AS build-stage + +WORKDIR /app + +COPY go.mod go.sum ./ +RUN go mod download + +COPY *.go ./ + +RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping + +# Run the tests in the container +FROM build-stage AS run-test-stage +RUN go test -v ./... + +# Deploy the application binary into a lean image +FROM gcr.io/distroless/base-debian12 AS build-release-stage + +WORKDIR / + +COPY --from=build-stage /docker-gs-ping /docker-gs-ping + +EXPOSE 8080 + +USER nonroot:nonroot + +ENTRYPOINT ["/docker-gs-ping"] +``` + +Since you have two Dockerfiles now, you have to tell Docker what Dockerfile +you'd like to use to build the image. Tag the new image with `multistage`. This +tag (like any other, apart from `latest`) has no special meaning for Docker, +it's something you chose. + +```console +$ docker build -t docker-gs-ping:multistage -f Dockerfile.multistage . +``` + +Comparing the sizes of `docker-gs-ping:multistage` and `docker-gs-ping:latest` +you see a few orders-of-magnitude difference. + +```console +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-gs-ping multistage e3fdde09f172 About a minute ago 28.1MB +docker-gs-ping latest 336a3f164d0f About an hour ago 1.11GB +``` + +This is so because the ["distroless"](https://github.com/GoogleContainerTools/distroless) +base image that you have used in the second stage of the build is very barebones and is designed for lean deployments of static binaries. + +There's much more to multi-stage builds, including the possibility of multi-architecture builds, +so feel free to check out [multi-stage builds](/manuals/build/building/multi-stage.md). This is, however, not essential for your progress here. + +## Run your Go image as a container + +### Prerequisites + +Work through the steps to containerize a Go application in [Build your Go image](#build-your-go-image). + +### Overview + +In the previous module you created a `Dockerfile` for your example application and then you created your Docker image using the command `docker build`. Now that you have the image, you can run that image and see if your application is running correctly. + +A container is a normal operating system process except that this process is isolated and has its own file system, its own networking, and its own isolated process tree separate from the host. + +To run an image inside of a container, you use the `docker run` command. It requires one parameter and that's the image name. Start your image and make sure it's running correctly. Run the following command in your terminal. + +```console +$ docker run docker-gs-ping +``` + +```text + ____ __ + / __/___/ / ___ + / _// __/ _ \/ _ \ +/___/\__/_//_/\___/ v4.10.2 +High performance, minimalist Go web framework +https://echo.labstack.com +____________________________________O/_______ + O\ +⇨ http server started on [::]:8080 +``` + +When you run this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a REST server and will run in a loop waiting for incoming requests without returning control back to the OS until you stop the container. + +Make a GET request to the server using the curl command. + +```console +$ curl http://localhost:8080/ +curl: (7) Failed to connect to localhost port 8080: Connection refused +``` + +Your curl command failed because the connection to your server was refused. +Meaning that you weren't able to connect to localhost on port 8080. This is +expected because your container is running in isolation which includes +networking. Stop the container and restart with port 8080 published on your +local network. + +To stop the container, press ctrl-c. This will return you to the terminal prompt. + +To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host_port]:[container_port]`. So if you wanted to expose port `8080` inside the container to port `3000` outside the container, you would pass `3000:8080` to the `--publish` flag. + +Start the container and expose port `8080` to port `8080` on the host. + +```console +$ docker run --publish 8080:8080 docker-gs-ping +``` + +Now, rerun the curl command. + +```console +$ curl http://localhost:8080/ +Hello, Docker! <3 +``` + +Success! You were able to connect to the application running inside of your container on port 8080. Switch back to the terminal where your container is running and you should see the `GET` request logged to the console. + +Press `ctrl-c` to stop the container. + +### Run in detached mode + +This is great so far, but your sample application is a web server and you +shouldn't have to have your terminal connected to the container. Docker can run +your container in detached mode in the background. To do this, you can use the +`--detach` or `-d` for short. Docker will start your container the same as +before but this time will detach from the container and return you to the +terminal prompt. + +```console +$ docker run -d -p 8080:8080 docker-gs-ping +d75e61fcad1e0c0eca69a3f767be6ba28a66625ce4dc42201a8a323e8313c14e +``` + +Docker started your container in the background and printed the container ID on the terminal. + +Again, make sure that your container is running. Run the same `curl` command: + +```console +$ curl http://localhost:8080/ +Hello, Docker! <3 +``` + +### List containers + +Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how the ps command is used to see a list of processes on a Linux machine. + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d75e61fcad1e docker-gs-ping "/docker-gs-ping" 41 seconds ago Up 40 seconds 0.0.0.0:8080->8080/tcp inspiring_ishizaka +``` + +The `ps` command tells you a bunch of stuff about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that are exposed, and the names of the container. + +You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You'll fix this in a minute but first you need to stop the container. To stop the container, run the `docker stop` command, passing the container's name or ID. + +```console +$ docker stop inspiring_ishizaka +inspiring_ishizaka +``` + +Now rerun the `docker ps` command to see a list of running containers. + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +### Stop, start, and name containers + +Docker containers can be started, stopped and restarted. When you stop a container, it's not removed but the status is changed to stopped and the process inside of the container is stopped. When you ran the `docker ps` command, the default output is to only show running containers. If you pass the `--all` or `-a` for short, you will see all containers on your system, including stopped containers and running containers. + +```console +$ docker ps --all + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d75e61fcad1e docker-gs-ping "/docker-gs-ping" About a minute ago Exited (2) 23 seconds ago inspiring_ishizaka +f65dbbb9a548 docker-gs-ping "/docker-gs-ping" 3 minutes ago Exited (2) 2 minutes ago wizardly_joliot +aade1bf3d330 docker-gs-ping "/docker-gs-ping" 3 minutes ago Exited (2) 3 minutes ago magical_carson +52d5ce3c15f0 docker-gs-ping "/docker-gs-ping" 9 minutes ago Exited (2) 3 minutes ago gifted_mestorf +``` + +If you’ve been following along, you should see several containers listed. These are containers that you started and stopped but haven't removed yet. + +Restart the container that you have just stopped. Locate the name of the container and replace the name of the container in the following `restart` command: + +```console +$ docker restart inspiring_ishizaka +``` + +Now, list all the containers again using the `ps` command: + +```console +$ docker ps -a + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d75e61fcad1e docker-gs-ping "/docker-gs-ping" 2 minutes ago Up 5 seconds 0.0.0.0:8080->8080/tcp inspiring_ishizaka +f65dbbb9a548 docker-gs-ping "/docker-gs-ping" 4 minutes ago Exited (2) 2 minutes ago wizardly_joliot +aade1bf3d330 docker-gs-ping "/docker-gs-ping" 4 minutes ago Exited (2) 4 minutes ago magical_carson +52d5ce3c15f0 docker-gs-ping "/docker-gs-ping" 10 minutes ago Exited (2) 4 minutes ago gifted_mestorf +``` + +Notice that the container you just restarted has been started in detached mode and has port `8080` exposed. Also, note that the status of the container is `Up X seconds`. When you restart a container, it will be started with the same flags or commands that it was originally started with. + +Stop and remove all of your containers and take a look at fixing the random naming issue. + +Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system: + +```console +$ docker stop inspiring_ishizaka +inspiring_ishizaka +``` + +Now that all of your containers are stopped, remove them. When a container is removed, it's no longer running nor is it in the stopped state. Instead, the process inside the container is terminated and the metadata for the container is removed. + +To remove a container, run the `docker rm` command passing the container name. You can pass multiple container names to the command in one command. + +Again, make sure you replace the containers names in the following command with the container names from your system: + +```console +$ docker rm inspiring_ishizaka wizardly_joliot magical_carson gifted_mestorf + +inspiring_ishizaka +wizardly_joliot +magical_carson +gifted_mestorf +``` + +Run the `docker ps --all` command again to verify that all containers are gone. + +Now, address the pesky random name issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with. Just like good naming conventions for variables in your code makes it simpler to read. So goes naming your containers. + +To name a container, you must pass the `--name` flag to the `run` command: + +```console +$ docker run -d -p 8080:8080 --name rest-server docker-gs-ping +3bbc6a3102ea368c8b966e1878a5ea9b1fc61187afaac1276c41db22e4b7f48f +``` + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3bbc6a3102ea docker-gs-ping "/docker-gs-ping" 25 seconds ago Up 24 seconds 0.0.0.0:8080->8080/tcp rest-server +``` + +Now, you can easily identify your container based on the name. + +## Use containers for Go development + +### Prerequisites + +Work through the steps of the [run your image as a container](#run-your-go-image-as-a-container) module to learn how to manage the lifecycle of your containers. + +### Introduction + +In this module, you'll take a look at running a database engine in a container and connecting it to the extended version of the example application. You are going to see some options for keeping persistent data and for wiring up the containers to talk to one another. Finally, you'll learn how to use Docker Compose to manage such multi-container local development environments effectively. + +### Local database and containers + +The database engine you are going to use is called [CockroachDB](https://www.cockroachlabs.com/product/). It is a modern, Cloud-native, distributed SQL database. + +Instead of compiling CockroachDB from the source code or using the operating system's native package manager to install CockroachDB, you are going to use the [Docker image for CockroachDB](https://hub.docker.com/r/cockroachdb/cockroach) and run it in a container. + +CockroachDB is compatible with PostgreSQL to a significant extent, and shares many conventions with the latter, particularly the default names for the environment variables. So, if you are familiar with Postgres, don't be surprised if you see some familiar environment variable names. The Go modules that work with Postgres, such as [pgx](https://pkg.go.dev/github.com/jackc/pgx), [pq](https://pkg.go.dev/github.com/lib/pq), [GORM](https://gorm.io/index.html), and [upper/db](https://upper.io/v4/) also work with CockroachDB. + +For more information on the relation between Go and CockroachDB, refer to the [CockroachDB documentation](https://www.cockroachlabs.com/docs/v20.2/build-a-go-app-with-cockroachdb.html), although this isn't necessary to continue with the present guide. + +#### Storage + +The point of a database is to have a persistent store of data. [Volumes](/manuals/engine/storage/volumes.md) are the preferred mechanism for persisting data generated by and used by Docker containers. Thus, before you start CockroachDB, create the volume for it. + +To create a managed volume, run : + +```console +$ docker volume create roach +roach +``` + +You can view the list of all managed volumes in your Docker instance with the following command: + +```console +$ docker volume list +DRIVER VOLUME NAME +local roach +``` + +#### Networking + +The example application and the database engine are going to talk to one another over the network. There are different kinds of network configuration possible, and you're going to use what's called a user-defined bridge network. It is going to provide you with a DNS lookup service so that you can refer to your database engine container by its hostname. + +The following command creates a new bridge network named `mynet`: + +```console +$ docker network create -d bridge mynet +51344edd6430b5acd121822cacc99f8bc39be63dd125a3b3cd517b6485ab7709 +``` + +As it was the case with the managed volumes, there is a command to list all networks set up in your Docker instance: + +```console +$ docker network list +NETWORK ID NAME DRIVER SCOPE +0ac2b1819fa4 bridge bridge local +51344edd6430 mynet bridge local +daed20bbecce host host local +6aee44f40a39 none null local +``` + +Your bridge network `mynet` has been created successfully. The other three networks, named `bridge`, `host`, and `none` are the default networks and they had been created by the Docker itself. While it's not relevant to this guide, you can learn more about Docker networking in the [networking overview](/manuals/engine/network/_index.md) section. + +#### Choose good names for volumes and networks + +As the saying goes, there are only two hard things in Computer Science: cache invalidation and naming things. And off-by-one errors. + +When choosing a name for a network or a managed volume, it's best to choose a name that's indicative of the intended purpose. This guide aims for brevity, so it used short, generic names. + +#### Start the database engine + +Now that the housekeeping chores are done, you can run CockroachDB in a container and attach it to the volume and network you had just created. When you run the following command, Docker will pull the image from Docker Hub and run it for you locally: + +```console +$ docker run -d \ + --name roach \ + --hostname db \ + --network mynet \ + -p 26257:26257 \ + -p 8080:8080 \ + -v roach:/cockroach/cockroach-data \ + cockroachdb/cockroach:latest-v25.4 start-single-node \ + --insecure + +# ... output omitted ... +``` + +Notice a clever use of the tag `latest-v25.4` to make sure that you're pulling the latest patch version of 25.4. The diversity of available tags depend on the image maintainer. Here, your intent was to have the latest patched version of CockroachDB while not straying too far away from the known working version as the time goes by. To see the tags available for the CockroachDB image, you can go to the [CockroachDB page on Docker Hub](https://hub.docker.com/r/cockroachdb/cockroach/tags). + +#### Configure the database engine + +Now that the database engine is live, there is some configuration to do before your application can begin using it. Fortunately, it's not a lot. You must: + +1. Create a blank database. +2. Register a new user account with the database engine. +3. Grant that new user access rights to the database. + +You can do that with the help of CockroachDB built-in SQL shell. To start the SQL shell in the same container where the database engine is running, type: + +```console +$ docker exec -it roach ./cockroach sql --insecure +``` + +1. In the SQL shell, create the database that the example application is going to use: + + ```sql + CREATE DATABASE mydb; + ``` + +2. Register a new SQL user account with the database engine. Use the username `totoro`. + + ```sql + CREATE USER totoro; + ``` + +3. Give the new user the necessary permissions: + + ```sql + GRANT ALL ON DATABASE mydb TO totoro; + ``` + +4. Type `quit` to exit the shell. + +The following is an example of interaction with the SQL shell. + +```console +$ sudo docker exec -it roach ./cockroach sql --insecure +# +# Welcome to the CockroachDB SQL shell. +# All statements must be terminated by a semicolon. +# To exit, type: \q. +# +# Server version: CockroachDB CCL v20.1.15 (x86_64-unknown-linux-gnu, built 2021/04/26 16:11:58, go1.13.9) (same version as client) +# Cluster ID: 7f43a490-ccd6-4c2a-9534-21f393ca80ce +# +# Enter \? for a brief introduction. +# +root@:26257/defaultdb> CREATE DATABASE mydb; +CREATE DATABASE + +Time: 22.985478ms + +root@:26257/defaultdb> CREATE USER totoro; +CREATE ROLE + +Time: 13.921659ms + +root@:26257/defaultdb> GRANT ALL ON DATABASE mydb TO totoro; +GRANT + +Time: 14.217559ms + +root@:26257/defaultdb> quit +oliver@hki:~$ +``` + +#### Meet the example application + +Now that you have started and configured the database engine, you can switch your attention to the application. + +The example application for this module is an extended version of `docker-gs-ping` application you've used in the previous modules. You have two options: + +- You can update your local copy of `docker-gs-ping` to match the new extended version presented in this chapter; or +- You can clone the [docker/docker-gs-ping-dev](https://github.com/docker/docker-gs-ping-dev) repository. This latter approach is recommended. + +To checkout the example application, run: + +```console +$ git clone https://github.com/docker/docker-gs-ping-dev.git +# ... output omitted ... +``` + +The application's `main.go` now includes database initialization code, as well as the code to implement a new business requirement: + +- An HTTP `POST` request to `/send` containing a `{ "value" : string }` JSON must save the value to the database. + +You also have an update for another business requirement. The requirement was: + +- The application responds with a text message containing a heart symbol ("`<3`") on requests to `/`. + +And now it's going to be: + +- The application responds with the string containing the count of messages stored in the database, enclosed in the parentheses. + + Example output: `Hello, Docker! (7)` + +The full source code listing of `main.go` follows. + +```go +package main + +import ( + "context" + "database/sql" + "fmt" + "log" + "net/http" + "os" + + "github.com/cenkalti/backoff/v4" + "github.com/cockroachdb/cockroach-go/v2/crdb" + "github.com/labstack/echo/v4" + "github.com/labstack/echo/v4/middleware" +) + +func main() { + + e := echo.New() + + e.Use(middleware.Logger()) + e.Use(middleware.Recover()) + + db, err := initStore() + if err != nil { + log.Fatalf("failed to initialize the store: %s", err) + } + defer db.Close() + + e.GET("/", func(c echo.Context) error { + return rootHandler(db, c) + }) + + e.GET("/ping", func(c echo.Context) error { + return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"}) + }) + + e.POST("/send", func(c echo.Context) error { + return sendHandler(db, c) + }) + + httpPort := os.Getenv("HTTP_PORT") + if httpPort == "" { + httpPort = "8080" + } + + e.Logger.Fatal(e.Start(":" + httpPort)) +} + +type Message struct { + Value string `json:"value"` +} + +func initStore() (*sql.DB, error) { + + pgConnString := fmt.Sprintf("host=%s port=%s dbname=%s user=%s password=%s sslmode=disable", + os.Getenv("PGHOST"), + os.Getenv("PGPORT"), + os.Getenv("PGDATABASE"), + os.Getenv("PGUSER"), + os.Getenv("PGPASSWORD"), + ) + + var ( + db *sql.DB + err error + ) + openDB := func() error { + db, err = sql.Open("postgres", pgConnString) + return err + } + + err = backoff.Retry(openDB, backoff.NewExponentialBackOff()) + if err != nil { + return nil, err + } + + if _, err := db.Exec( + "CREATE TABLE IF NOT EXISTS message (value TEXT PRIMARY KEY)"); err != nil { + return nil, err + } + + return db, nil +} + +func rootHandler(db *sql.DB, c echo.Context) error { + r, err := countRecords(db) + if err != nil { + return c.HTML(http.StatusInternalServerError, err.Error()) + } + return c.HTML(http.StatusOK, fmt.Sprintf("Hello, Docker! (%d)\n", r)) +} + +func sendHandler(db *sql.DB, c echo.Context) error { + + m := &Message{} + + if err := c.Bind(m); err != nil { + return c.JSON(http.StatusInternalServerError, err) + } + + err := crdb.ExecuteTx(context.Background(), db, nil, + func(tx *sql.Tx) error { + _, err := tx.Exec( + "INSERT INTO message (value) VALUES ($1) ON CONFLICT (value) DO UPDATE SET value = excluded.value", + m.Value, + ) + if err != nil { + return c.JSON(http.StatusInternalServerError, err) + } + return nil + }) + + if err != nil { + return c.JSON(http.StatusInternalServerError, err) + } + + return c.JSON(http.StatusOK, m) +} + +func countRecords(db *sql.DB) (int, error) { + + rows, err := db.Query("SELECT COUNT(*) FROM message") + if err != nil { + return 0, err + } + defer rows.Close() + + count := 0 + for rows.Next() { + if err := rows.Scan(&count); err != nil { + return 0, err + } + rows.Close() + } + + return count, nil +} +``` + +The repository also includes the `Dockerfile`, which is almost exactly the same as the multi-stage `Dockerfile` introduced in the previous modules. It uses the official Docker Go image to build the application and then builds the final image by placing the compiled binary into the much slimmer, distroless image. + +Regardless of whether you had updated the old example application, or checked out the new one, this new Docker image has to be built to reflect the changes to the application source code. + +#### Build the application + +You can build the image with the familiar `build` command: + +```console +$ docker build --tag docker-gs-ping-roach . +``` + +#### Run the application + +Now, run your container. This time you'll need to set some environment variables so that your application knows how to access the database. For now, you’ll do this right in the `docker run` command. Later you'll see a more convenient method with Docker Compose. + +> [!NOTE] +> +> Since you're running your CockroachDB cluster in insecure mode, the value for the password can be anything. +> +> In production, don't run in insecure mode. + +```console +$ docker run -it --rm -d \ + --network mynet \ + --name rest-server \ + -p 80:8080 \ + -e PGUSER=totoro \ + -e PGPASSWORD=myfriend \ + -e PGHOST=db \ + -e PGPORT=26257 \ + -e PGDATABASE=mydb \ + docker-gs-ping-roach +``` + +There are a few points to note about this command. + +- You map container port `8080` to host port `80` this time. Thus, for `GET` requests you can get away with literally `curl localhost`: + + ```console + $ curl localhost + Hello, Docker! (0) + ``` + + Or, if you prefer, a proper URL would work just as well: + + ```console + $ curl http://localhost/ + Hello, Docker! (0) + ``` + +- The total number of stored messages is `0` for now. This is fine, because you haven't posted anything to your application yet. +- You refer to the database container by its hostname, which is `db`. This is why you had `--hostname db` when you started the database container. + +- The actual password doesn't matter, but it must be set to something to avoid confusing the example application. +- The container you've just run is named `rest-server`. These names are useful for managing the container lifecycle: + + ```console + # Don't do this just yet, it's only an example: + $ docker container rm --force rest-server + ``` + +#### Test the application + +In the previous section, you've already tested querying your application with `GET` and it returned zero for the stored message counter. Now, post some messages to it: + +```console +$ curl --request POST \ + --url http://localhost/send \ + --header 'content-type: application/json' \ + --data '{"value": "Hello, Docker!"}' +``` + +The application responds with the contents of the message, which means it has been saved in the database: + +```json +{ "value": "Hello, Docker!" } +``` + +Send another message: + +```console +$ curl --request POST \ + --url http://localhost/send \ + --header 'content-type: application/json' \ + --data '{"value": "Hello, Oliver!"}' +``` + +And again, you get the value of the message back: + +```json +{ "value": "Hello, Oliver!" } +``` + +Run curl and see what the message counter says: + +```console +$ curl localhost +Hello, Docker! (2) +``` + +In this example, you sent two messages and the database kept them. Or has it? Stop and remove all your containers, but not the volumes, and try again. + +First, stop the containers: + +```console +$ docker container stop rest-server roach +rest-server +roach +``` + +Then, remove them: + +```console +$ docker container rm rest-server roach +rest-server +roach +``` + +Verify that they're gone: + +```console +$ docker container list --all +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +And start them again, database first: + +```console +$ docker run -d \ + --name roach \ + --hostname db \ + --network mynet \ + -p 26257:26257 \ + -p 8080:8080 \ + -v roach:/cockroach/cockroach-data \ + cockroachdb/cockroach:latest-v25.4 start-single-node \ + --insecure +``` + +And the service next: + +```console +$ docker run -it --rm -d \ + --network mynet \ + --name rest-server \ + -p 80:8080 \ + -e PGUSER=totoro \ + -e PGPASSWORD=myfriend \ + -e PGHOST=db \ + -e PGPORT=26257 \ + -e PGDATABASE=mydb \ + docker-gs-ping-roach +``` + +Lastly, query your service: + +```console +$ curl localhost +Hello, Docker! (2) +``` + +Great! The count of records from the database is correct although you haven't only stopped the containers, but you've also removed them before starting new instances. The difference is in the managed volume for CockroachDB, which you reused. The new CockroachDB container has read the database files from the disk, just as it normally would if it were running outside the container. + +#### Wind down everything + +Remember, that you're running CockroachDB in insecure mode. Now that you've built and tested your application, it's time to wind everything down before moving on. You can list the containers that you are running with the `list` command: + +```console +$ docker container list +``` + +Now that you know the container IDs, you can use `docker container stop` and `docker container rm`, as demonstrated in the previous modules. + +Stop the CockroachDB and `docker-gs-ping-roach` containers before moving on. + +### Better productivity with Docker Compose + +At this point, you might be wondering if there is a way to avoid having to deal with long lists of arguments to the `docker` command. The toy example you used in this series requires five environment variables to define the connection to the database. A real application might need many, many more. Then there is also a question of dependencies. Ideally, you want to make sure that the database is started before your application is run. And spinning up the database instance may require another Docker command with many options. But there is a better way to orchestrate these deployments for local development purposes. + +In this section, you'll create a Docker Compose file to start your `docker-gs-ping-roach` application and CockroachDB database engine with a single command. + +#### Configure Docker Compose + +In your application's directory, create a new text file named `compose.yaml` with the following content. + +```yaml +services: + docker-gs-ping-roach: + depends_on: + - roach + build: + context: . + container_name: rest-server + hostname: rest-server + networks: + - mynet + ports: + - 80:8080 + environment: + - PGUSER=${PGUSER:-totoro} + - PGPASSWORD=${PGPASSWORD:?database password not set} + - PGHOST=${PGHOST:-db} + - PGPORT=${PGPORT:-26257} + - PGDATABASE=${PGDATABASE:-mydb} + deploy: + restart_policy: + condition: on-failure + roach: + image: cockroachdb/cockroach:latest-v25.4 + container_name: roach + hostname: db + networks: + - mynet + ports: + - 26257:26257 + - 8080:8080 + volumes: + - roach:/cockroach/cockroach-data + command: start-single-node --insecure + +volumes: + roach: + +networks: + mynet: + driver: bridge +``` + +This Docker Compose configuration is super convenient as you don't have to type all the parameters to pass to the `docker run` command. You can declaratively do that in the Docker Compose file. The [Docker Compose documentation pages](/manuals/compose/_index.md) are quite extensive and include a full reference for the Docker Compose file format. + +#### The `.env` file + +Docker Compose will automatically read environment variables from a `.env` file if it's available. Since your Compose file requires `PGPASSWORD` to be set, add the following content to the `.env` file: + +```bash +PGPASSWORD=whatever +``` + +The exact value doesn't really matter for this example, because you run CockroachDB in insecure mode. Make sure you set the variable to some value to avoid getting an error. + +#### Merging Compose files + +The filename `compose.yaml` is the default filename which `docker compose` command recognizes if no `-f` flag is provided. This means you can have multiple Docker Compose files if your environment has such requirements. Furthermore, Docker Compose files are composable, so multiple files can be specified on the command line to merge parts of the configuration together. The following list shows a few examples of scenarios where such a feature would be useful: + +- Using a bind mount for the source code for local development but not when running the CI tests; +- Switching between using a pre-built image for the frontend for some API application vs creating a bind mount for source code; +- Adding additional services for integration testing; +- And many more... + +You aren't going to cover any of these advanced use cases here. + +#### Variable substitution in Docker Compose + +One of the really cool features of Docker Compose is [variable substitution](/reference/compose-file/interpolation.md). You can see some examples in the Compose file, `environment` section. By means of an example: + +- `PGUSER=${PGUSER:-totoro}` means that inside the container, the environment variable `PGUSER` shall be set to the same value as it has on the host machine where Docker Compose is run. If there is no environment variable with this name on the host machine, the variable inside the container gets the default value of `totoro`. +- `PGPASSWORD=${PGPASSWORD:?database password not set}` means that if the environment variable `PGPASSWORD` isn't set on the host, Docker Compose will display an error. This is OK, because you don't want to hard-code default values for the password. You set the password value in the `.env` file, which is local to your machine. It is always a good idea to add `.env` to `.gitignore` to prevent the secrets being checked into the version control. + +Other ways of dealing with undefined or empty values exist, as documented in the [variable substitution](/reference/compose-file/interpolation.md) section of the Docker documentation. + +#### Validating Docker Compose configuration + +Before you apply changes made to a Compose configuration file, there is an opportunity to validate the content of the configuration file with the following command: + +```console +$ docker compose config +``` + +When this command is run, Docker Compose reads the file `compose.yaml`, parses it into a data structure in memory, validates where possible, and prints back the reconstruction of that configuration file from its internal representation. If this isn't possible due to errors, Docker prints an error message instead. + +#### Build and run the application using Docker Compose + +Start your application and confirm that it's running. + +```console +$ docker compose up --build +``` + +You passed the `--build` flag so Docker will compile your image and then start it. + +> [!NOTE] +> +> Docker Compose is a useful tool, but it has its own quirks. For example, no rebuild is triggered on the update to the source code unless the `--build` flag is provided. It is a very common pitfall to edit one's source code, and forget to use the `--build` flag when running `docker compose up`. + +Since your set-up is now run by Docker Compose, it has assigned it a project name, so you get a new volume for your CockroachDB instance. This means that your application will fail to connect to the database, because the database doesn't exist in this new volume. The terminal displays an authentication error for the database: + +```text +# ... omitted output ... +rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro +roach | * +roach | * INFO: Replication was disabled for this cluster. +roach | * When/if adding nodes in the future, update zone configurations to increase the replication factor. +roach | * +roach | CockroachDB node starting at 2021-05-10 00:54:26.398177 +0000 UTC (took 3.0s) +roach | build: CCL v20.1.15 @ 2021/04/26 16:11:58 (go1.13.9) +roach | webui: http://db:8080 +roach | sql: postgresql://root@db:26257?sslmode=disable +roach | RPC client flags: /cockroach/cockroach <client cmd> --host=db:26257 --insecure +roach | logs: /cockroach/cockroach-data/logs +roach | temp dir: /cockroach/cockroach-data/cockroach-temp349434348 +roach | external I/O path: /cockroach/cockroach-data/extern +roach | store[0]: path=/cockroach/cockroach-data +roach | storage engine: rocksdb +roach | status: initialized new cluster +roach | clusterID: b7b1cb93-558f-4058-b77e-8a4ddb329a88 +roach | nodeID: 1 +rest-server exited with code 0 +rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro +rest-server | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro +rest-server | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro +rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro +rest-server | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro +rest-server | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro +rest-server exited with code 1 +# ... omitted output ... +``` + +Because of the way you set up your deployment using `restart_policy`, the failing container is being restarted every 20 seconds. So, in order to fix the problem, you need to log in to the database engine and create the user. You've done it before in [Configure the database engine](#configure-the-database-engine). + +This isn't a big deal. All you have to do is to connect to CockroachDB instance and run the three SQL commands to create the database and the user, as described in [Configure the database engine](#configure-the-database-engine). + +So, log in to the database engine from another terminal: + +```console +$ docker exec -it roach ./cockroach sql --insecure +``` + +And run the same commands as before to create the database `mydb`, the user `totoro`, and to grant that user necessary permissions. Once you do that (and the example application container is automatically restarts), the `rest-service` stops failing and restarting and the console goes quiet. + +It would have been possible to connect the volume that you had previously used, but for the purposes of this example it's more trouble than it's worth and it also provided an opportunity to show how to introduce resilience into your deployment via the `restart_policy` Compose file feature. + +#### Testing the application + +Now, test your API endpoint. In the new terminal, run the following command: + +```console +$ curl http://localhost/ +``` + +You should receive the following response: + +```json +Hello, Docker! (0) +``` + +#### Shutting down + +To stop the containers started by Docker Compose, press `ctrl+c` in the terminal where you ran `docker compose up`. To remove those containers after they've been stopped, run `docker compose down`. + +#### Detached mode + +You can run containers started by the `docker compose` command in detached mode, just as you would with the `docker` command, by using the `-d` flag. + +To start the stack, defined by the Compose file in detached mode, run: + +```console +$ docker compose up --build -d +``` + +Then, you can use `docker compose stop` to stop the containers and `docker compose down` to remove them. + +### Further exploration + +You can run `docker compose` to see what other commands are available. + +### Wrap up + +There are some tangential, yet interesting points that were purposefully not covered in this chapter. For the more adventurous reader, this section offers some pointers for further study. + +#### Persistent storage + +A managed volume isn't the only way to provide your container with persistent storage. It is highly recommended to get acquainted with available storage options and their use cases, covered in [Manage data in Docker](/manuals/engine/storage/_index.md). + +#### CockroachDB clusters + +You ran a single instance of CockroachDB, which was enough for this example. But, it's possible to run a CockroachDB cluster, which is made of multiple instances of CockroachDB, each instance running in its own container. Since CockroachDB engine is distributed by design, it would have taken surprisingly little change to your procedure to run a cluster with multiple nodes. + +Such distributed set-up offers interesting possibilities, such as applying Chaos Engineering techniques to simulate parts of the cluster failing and evaluating your application's ability to cope with such failures. + +If you are interested in experimenting with CockroachDB clusters, check out: + +- [Start a CockroachDB Cluster in Docker](https://www.cockroachlabs.com/docs/v20.2/start-a-local-cluster-in-docker-mac.html) article; and +- Documentation for Docker Compose keywords [`deploy`](/reference/compose-file/legacy-versions.md) and [`replicas`](/reference/compose-file/legacy-versions.md). + +#### Other databases + +Since you didn't run a cluster of CockroachDB instances, you might be wondering whether you could have used a non-distributed database engine. The answer is 'yes', and if you were to pick a more traditional SQL database, such as [PostgreSQL](https://www.postgresql.org/), the process described in this chapter would have been very similar. + +## Run your tests using Go test + +### Prerequisites + +Complete the [Build your Go image](#build-your-go-image) section of this guide. + +### Overview + +Testing is an essential part of modern software development. Testing can mean a +lot of things to different development teams. There are unit tests, integration +tests and end-to-end testing. In this guide you take a look at running your unit +tests in Docker when building. + +For this section, use the `docker-gs-ping` project that you cloned in [Build +your Go image](#build-your-go-image). + +### Run tests when building + +To run your tests when building, you need to add a test stage to the +`Dockerfile.multistage`. The `Dockerfile.multistage` in the sample application's +repository already has the following content: + +```dockerfile {hl_lines="15-17"} +# syntax=docker/dockerfile:1 + +# Build the application from source +FROM golang:1.19 AS build-stage + +WORKDIR /app + +COPY go.mod go.sum ./ +RUN go mod download + +COPY *.go ./ + +RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping + +# Run the tests in the container +FROM build-stage AS run-test-stage +RUN go test -v ./... + +# Deploy the application binary into a lean image +FROM gcr.io/distroless/base-debian12 AS build-release-stage + +WORKDIR / + +COPY --from=build-stage /docker-gs-ping /docker-gs-ping + +EXPOSE 8080 + +USER nonroot:nonroot + +ENTRYPOINT ["/docker-gs-ping"] +``` + +Run the following command to build an image using the `run-test-stage` stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target run-test-stage` to target the test stage. + +```console +$ docker build -f Dockerfile.multistage -t docker-gs-ping-test --progress plain --no-cache --target run-test-stage . +``` + +You should see output containing the following. + +```text +#13 [run-test-stage 1/1] RUN go test -v ./... +#13 4.915 === RUN TestIntMinBasic +#13 4.915 --- PASS: TestIntMinBasic (0.00s) +#13 4.915 === RUN TestIntMinTableDriven +#13 4.915 === RUN TestIntMinTableDriven/0,1 +#13 4.915 === RUN TestIntMinTableDriven/1,0 +#13 4.915 === RUN TestIntMinTableDriven/2,-2 +#13 4.915 === RUN TestIntMinTableDriven/0,-1 +#13 4.915 === RUN TestIntMinTableDriven/-1,0 +#13 4.915 --- PASS: TestIntMinTableDriven (0.00s) +#13 4.915 --- PASS: TestIntMinTableDriven/0,1 (0.00s) +#13 4.915 --- PASS: TestIntMinTableDriven/1,0 (0.00s) +#13 4.915 --- PASS: TestIntMinTableDriven/2,-2 (0.00s) +#13 4.915 --- PASS: TestIntMinTableDriven/0,-1 (0.00s) +#13 4.915 --- PASS: TestIntMinTableDriven/-1,0 (0.00s) +#13 4.915 PASS +``` diff --git a/content/guides/golang/_index.md b/content/guides/golang/_index.md deleted file mode 100644 index 7d63660706a7..000000000000 --- a/content/guides/golang/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Go language-specific guide -linkTitle: Go -description: Containerize Go apps using Docker -keywords: docker, getting started, go, golang, language, dockerfile -summary: | - This guide teaches you how to containerize Go applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/golang/ - - /guides/language/golang/ -languages: [go] -params: - time: 30 minutes ---- - -This guide will show you how to create, test, and deploy containerized Go applications using Docker. - -> **Acknowledgment** -> -> Docker would like to thank [Oliver Frolovs](https://www.linkedin.com/in/ofr/) for his contribution to this guide. - -## What will you learn? - -In this guide, you’ll learn how to: - -- Create a `Dockerfile` which contains the instructions for building a container image for a program written in Go. -- Run the image as a container in your local Docker instance and manage the container's lifecycle. -- Use multi-stage builds for building small images efficiently while keeping your Dockerfiles easy to read and maintain. -- Use Docker Compose to orchestrate running of multiple related containers together in a development environment. -- Configure a CI/CD pipeline for your application using [GitHub Actions](https://docs.github.com/en/actions) -- Deploy your containerized Go application. - -## Prerequisites - -Some basic understanding of Go and its toolchain is assumed. This isn't a Go tutorial. If you are new to the : languages:, -the [Go website](https://golang.org/) is a great place to explore, -so _go_ (pun intended) check it out! - -You also must know some basic [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container.md) as well as to -be at least vaguely familiar with the [Dockerfile format](/manuals/build/concepts/dockerfile.md). - -Your Docker set-up must have BuildKit enabled. BuildKit is enabled by default for all users on [Docker Desktop](/manuals/desktop/_index.md). -If you have installed Docker Desktop, you don’t have to manually enable BuildKit. If you are running Docker on Linux, -please check out BuildKit [getting started](/manuals/build/buildkit/_index.md#getting-started) page. - -Some familiarity with the command line is also expected. - -## What's next? - -The aim of this guide is to provide enough examples and instructions for you to containerize your own Go application and deploy it into the Cloud. - -Start by building your first Go image. diff --git a/content/guides/golang/build-images.md b/content/guides/golang/build-images.md deleted file mode 100644 index 2de5c21be3a0..000000000000 --- a/content/guides/golang/build-images.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: Build your Go image -linkTitle: Build images -weight: 5 -keywords: containers, images, go, golang, dockerfiles, coding, build, push, run -description: Learn how to build your first Docker image by writing a Dockerfile -aliases: - - /get-started/golang/build-images/ - - /language/golang/build-images/ - - /guides/language/golang/build-images/ ---- - -## Overview - -In this section you're going to build a container image. The image includes -everything you need to run your application – the compiled application binary -file, the runtime, the libraries, and all other resources required by your -application. - -## Required software - -To complete this tutorial, you need the following: - -- Docker running locally. Follow the [instructions to download and install Docker](/manuals/desktop/_index.md). -- An IDE or a text editor to edit files. [Visual Studio Code](https://code.visualstudio.com/) is a free and popular choice but you can use anything you feel comfortable with. -- A Git client. This guide uses a command-line based `git` client, but you are free to use whatever works for you. -- A command-line terminal application. The examples shown in this module are from the Linux shell, but they should work in PowerShell, Windows Command Prompt, or OS X Terminal with minimal, if any, modifications. - -## Meet the example application - -The example application is a caricature of a microservice. It is purposefully trivial to keep focus on learning the basics of containerization for Go applications. - -The application offers two HTTP endpoints: - -- It responds with a string containing a heart symbol (`<3`) to requests to `/`. -- It responds with `{"Status" : "OK"}` JSON to a request to `/health`. - -It responds with HTTP error 404 to any other request. - -The application listens on a TCP port defined by the value of environment variable `PORT`. The default value is `8080`. - -The application is stateless. - -The complete source code for the application is on GitHub: [github.com/docker/docker-gs-ping](https://github.com/docker/docker-gs-ping). You are encouraged to fork it and experiment with it as much as you like. - -To continue, clone the application repository to your local machine: - -```console -$ git clone https://github.com/docker/docker-gs-ping -``` - -The application's `main.go` file is straightforward, if you are familiar with Go: - -```go -package main - -import ( - "net/http" - "os" - - "github.com/labstack/echo/v4" - "github.com/labstack/echo/v4/middleware" -) - -func main() { - - e := echo.New() - - e.Use(middleware.Logger()) - e.Use(middleware.Recover()) - - e.GET("/", func(c echo.Context) error { - return c.HTML(http.StatusOK, "Hello, Docker! <3") - }) - - e.GET("/health", func(c echo.Context) error { - return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"}) - }) - - httpPort := os.Getenv("PORT") - if httpPort == "" { - httpPort = "8080" - } - - e.Logger.Fatal(e.Start(":" + httpPort)) -} - -// Simple implementation of an integer minimum -// Adapted from: https://gobyexample.com/testing-and-benchmarking -func IntMin(a, b int) int { - if a < b { - return a - } - return b -} -``` - -## Create a Dockerfile for the application - -To build a container image with Docker, a `Dockerfile` with build instructions is required. - -Begin your `Dockerfile` with the (optional) parser directive line that instructs BuildKit to -interpret your file according to the grammar rules for the specified version of the syntax. - -You then tell Docker what base image you would like to use for your application: - -```dockerfile -# syntax=docker/dockerfile:1 - -FROM golang:1.19 -``` - -Docker images can be inherited from other images. Therefore, instead of creating -your own base image from scratch, you can use the official Go image that already -has all necessary tools and libraries to compile and run a Go application. - -> [!NOTE] -> -> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](/manuals/build/building/base-images.md#create-a-base-image). -> Note, however, that this isn't necessary to continue with your task at hand. - -Now that you have defined the base image for your upcoming container image, you -can begin building on top of it. - -To make things easier when running the rest of your commands, create a directory -inside the image that you're building. This also instructs Docker to use this -directory as the default destination for all subsequent commands. This way you -don't have to type out full file paths in the `Dockerfile`, the relative paths -will be based on this directory. - -```dockerfile -WORKDIR /app -``` - -Usually the very first thing you do once you’ve downloaded a project written in -Go is to install the modules necessary to compile it. Note, that the base image -has the toolchain already, but your source code isn't in it yet. - -So before you can run `go mod download` inside your image, you need to get your -`go.mod` and `go.sum` files copied into it. Use the `COPY` command to do this. - -In its simplest form, the `COPY` command takes two parameters. The first -parameter tells Docker what files you want to copy into the image. The last -parameter tells Docker where you want that file to be copied to. - -Copy the `go.mod` and `go.sum` file into your project directory `/app` which, -owing to your use of `WORKDIR`, is the current directory (`./`) inside the -image. Unlike some modern shells that appear to be indifferent to the use of -trailing slash (`/`), and can figure out what the user meant (most of the time), -Docker's `COPY` command is quite sensitive in its interpretation of the trailing -slash. - -```dockerfile -COPY go.mod go.sum ./ -``` - -> [!NOTE] -> -> If you'd like to familiarize yourself with the trailing slash treatment by the -> `COPY` command, see [Dockerfile -> reference](/reference/dockerfile.md#copy). This trailing slash can -> cause issues in more ways than you can imagine. - -Now that you have the module files inside the Docker image that you are -building, you can use the `RUN` command to run the command `go mod download` -there as well. This works exactly the same as if you were running `go` locally -on your machine, but this time these Go modules will be installed into a -directory inside the image. - -```dockerfile -RUN go mod download -``` - -At this point, you have a Go toolchain version 1.19.x and all your Go -dependencies installed inside the image. - -The next thing you need to do is to copy your source code into the image. You’ll -use the `COPY` command just like you did with your module files before. - -```dockerfile -COPY *.go ./ -``` - -This `COPY` command uses a wildcard to copy all files with `.go` extension -located in the current directory on the host (the directory where the `Dockerfile` -is located) into the current directory inside the image. - -Now, to compile your application, use the familiar `RUN` command: - -```dockerfile -RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping -``` - -This should be familiar. The result of that command will be a static application -binary named `docker-gs-ping` and located in the root of the filesystem of the -image that you are building. You could have put the binary into any other place -you desire inside that image, the root directory has no special meaning in this -regard. It's convenient to use it to keep the file paths short for improved -readability. - -Now, all that is left to do is to tell Docker what command to run when your -image is used to start a container. - -You do this with the `CMD` command: - -```dockerfile -CMD ["/docker-gs-ping"] -``` - -Here's the complete `Dockerfile`: - -```dockerfile -# syntax=docker/dockerfile:1 - -FROM golang:1.19 - -# Set destination for COPY -WORKDIR /app - -# Download Go modules -COPY go.mod go.sum ./ -RUN go mod download - -# Copy the source code. Note the slash at the end, as explained in -# https://docs.docker.com/reference/dockerfile/#copy -COPY *.go ./ - -# Build -RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping - -# Optional: -# To bind to a TCP port, runtime parameters must be supplied to the docker command. -# But we can document in the Dockerfile what ports -# the application is going to listen on by default. -# https://docs.docker.com/reference/dockerfile/#expose -EXPOSE 8080 - -# Run -CMD ["/docker-gs-ping"] -``` - -The `Dockerfile` may also contain comments. They always begin with a `#` symbol, -and must be at the beginning of a line. Comments are there for your convenience -to allow documenting your `Dockerfile`. - -There is also a concept of Dockerfile directives, such as the `syntax` directive -you added. The directives must always be at the very top of the `Dockerfile`, so -when adding comments, make sure that the comments follow after any directives -that you may have used: - -```dockerfile -# syntax=docker/dockerfile:1 -# A sample microservice in Go packaged into a container image. - -FROM golang:1.19 - -# ... -``` - -## Build the image - -Now that you've created your `Dockerfile`, build an image from it. The `docker -build` command creates Docker images from the `Dockerfile` and a context. A -build context is the set of files located in the specified path or URL. The -Docker build process can access any of the files located in the context. - -The build command optionally takes a `--tag` flag. This flag is used to label -the image with a string value, which is easy for humans to read and recognize. -If you don't pass a `--tag`, Docker will use `latest` as the default value. - -Build your first Docker image. - -```console -$ docker build --tag docker-gs-ping . -``` - -The build process will print some diagnostic messages as it goes through the build steps. -The following is an example of what these messages may look like. - -```console -[+] Building 2.2s (15/15) FINISHED - => [internal] load build definition from Dockerfile 0.0s - => => transferring dockerfile: 701B 0.0s - => [internal] load .dockerignore 0.0s - => => transferring context: 2B 0.0s - => resolve image config for docker.io/docker/dockerfile:1 1.1s - => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:39b85bbfa7536a5feceb7372a0817649ecb2724562a38360f4d6a7782a409b14 0.0s - => [internal] load build definition from Dockerfile 0.0s - => [internal] load .dockerignore 0.0s - => [internal] load metadata for docker.io/library/golang:1.19 0.7s - => [1/6] FROM docker.io/library/golang:1.19@sha256:5d947843dde82ba1df5ac1b2ebb70b203d106f0423bf5183df3dc96f6bc5a705 0.0s - => [internal] load build context 0.0s - => => transferring context: 6.08kB 0.0s - => CACHED [2/6] WORKDIR /app 0.0s - => CACHED [3/6] COPY go.mod go.sum ./ 0.0s - => CACHED [4/6] RUN go mod download 0.0s - => CACHED [5/6] COPY *.go ./ 0.0s - => CACHED [6/6] RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping 0.0s - => exporting to image 0.0s - => => exporting layers 0.0s - => => writing image sha256:ede8ff889a0d9bc33f7a8da0673763c887a258eb53837dd52445cdca7b7df7e3 0.0s - => => naming to docker.io/library/docker-gs-ping 0.0s -``` - -Your exact output will vary, but provided there aren't any errors, you should -see the word `FINISHED` in the first line of output. This means Docker has -successfully built your image named `docker-gs-ping`. - -## View local images - -To see the list of images you have on your local machine, you have two options. -One is to use the CLI and the other is to use [Docker -Desktop](/manuals/desktop/_index.md). Since you're working in the -terminal, take a look at listing images with the CLI. - -To list images, run the `docker image ls`command (or the `docker images` shorthand): - -```console -$ docker image ls - -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-gs-ping latest 7f153fbcc0a8 2 minutes ago 1.11GB -... -``` - -Your exact output may vary, but you should see the `docker-gs-ping` image with -the `latest` tag. Because you didn't specify a custom tag when you built your -image, Docker assumed that the tag would be `latest`, which is a special value. - -## Tag images - -An image name is made up of slash-separated name components. Name components may -contain lowercase letters, digits, and separators. A separator is defined as a -period, one or two underscores, or one or more dashes. A name component may not -start or end with a separator. - -An image is made up of a manifest and a list of layers. In simple terms, a tag -points to a combination of these artifacts. You can have multiple tags for the -image and, in fact, most images have multiple tags. Create a second tag -for the image you built and take a look at its layers. - -Use the `docker image tag` (or `docker tag` shorthand) command to create a new -tag for your image. This command takes two arguments; the first argument is the -source image, and the second is the new tag to create. The following command -creates a new `docker-gs-ping:v1.0` tag for the `docker-gs-ping:latest` you -built: - -```console -$ docker image tag docker-gs-ping:latest docker-gs-ping:v1.0 -``` - -The Docker `tag` command creates a new tag for the image. It doesn't create a -new image. The tag points to the same image and is another way to reference -the image. - -Now run the `docker image ls` command again to see the updated list of local -images: - -```console -$ docker image ls - -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-gs-ping latest 7f153fbcc0a8 6 minutes ago 1.11GB -docker-gs-ping v1.0 7f153fbcc0a8 6 minutes ago 1.11GB -... -``` - -You can see that you have two images that start with `docker-gs-ping`. You know -they're the same image because if you look at the `IMAGE ID` column, you can -see that the values are the same for the two images. This value is a unique -identifier Docker uses internally to identify the image. - -Remove the tag that you just created. To do this, you’ll use the -`docker image rm` command, or the shorthand `docker rmi` (which stands for -"remove image"): - -```console -$ docker image rm docker-gs-ping:v1.0 -Untagged: docker-gs-ping:v1.0 -``` - -Notice that the response from Docker tells you that the image hasn't been -removed but only untagged. - -Verify this by running the following command: - -```console -$ docker image ls -``` - -You will see that the tag `v1.0` is no longer in the list of images kept by your Docker instance. - -```text -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-gs-ping latest 7f153fbcc0a8 7 minutes ago 1.11GB -... -``` - -The tag `v1.0` has been removed but you still have the `docker-gs-ping:latest` -tag available on your machine, so the image is there. - -## Multi-stage builds - -You may have noticed that your `docker-gs-ping` image weighs in at over a -gigabyte, which is a lot for a tiny compiled Go application. You may also be -wondering what happened to the full suite of Go tools, including the compiler, -after you had built your image. - -The answer is that the full toolchain is still there, in the container image. -Not only this is inconvenient because of the large file size, but it may also -present a security risk when the container is deployed. - -These two issues can be solved by using [multi-stage builds](/manuals/build/building/multi-stage.md). - -In a nutshell, a multi-stage build can carry over the artifacts from one build stage into another, -and every build stage can be instantiated from a different base image. - -Thus, in the following example, you are going to use a full-scale official Go -image to build your application. Then you'll copy the application binary into -another image whose base is very lean and doesn't include the Go toolchain or -other optional components. - -The `Dockerfile.multistage` in the sample application's repository has the -following content: - -```dockerfile -# syntax=docker/dockerfile:1 - -# Build the application from source -FROM golang:1.19 AS build-stage - -WORKDIR /app - -COPY go.mod go.sum ./ -RUN go mod download - -COPY *.go ./ - -RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping - -# Run the tests in the container -FROM build-stage AS run-test-stage -RUN go test -v ./... - -# Deploy the application binary into a lean image -FROM gcr.io/distroless/base-debian11 AS build-release-stage - -WORKDIR / - -COPY --from=build-stage /docker-gs-ping /docker-gs-ping - -EXPOSE 8080 - -USER nonroot:nonroot - -ENTRYPOINT ["/docker-gs-ping"] -``` - -Since you have two Dockerfiles now, you have to tell Docker what Dockerfile -you'd like to use to build the image. Tag the new image with `multistage`. This -tag (like any other, apart from `latest`) has no special meaning for Docker, -it's something you chose. - -```console -$ docker build -t docker-gs-ping:multistage -f Dockerfile.multistage . -``` - -Comparing the sizes of `docker-gs-ping:multistage` and `docker-gs-ping:latest` -you see a few orders-of-magnitude difference. - -```console -$ docker image ls -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-gs-ping multistage e3fdde09f172 About a minute ago 28.1MB -docker-gs-ping latest 336a3f164d0f About an hour ago 1.11GB -``` - -This is so because the ["distroless"](https://github.com/GoogleContainerTools/distroless) -base image that you have used in the second stage of the build is very barebones and is designed for lean deployments of static binaries. - -There's much more to multi-stage builds, including the possibility of multi-architecture builds, -so feel free to check out [multi-stage builds](/manuals/build/building/multi-stage.md). This is, however, not essential for your progress here. - -## Next steps - -In this module, you met your example application and built and container image -for it. - -In the next module, you’ll take a look at how to run your image as a container. diff --git a/content/guides/golang/configure-ci-cd.md b/content/guides/golang/configure-ci-cd.md deleted file mode 100644 index 2f1f12a57c9d..000000000000 --- a/content/guides/golang/configure-ci-cd.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Configure CI/CD for your Go application -linkTitle: Configure CI/CD -weight: 40 -keywords: go, CI/CD, local, development -description: Learn how to Configure CI/CD for your Go application -aliases: - - /language/golang/configure-ci-cd/ - - /guides/language/golang/configure-ci-cd/ ---- - -## Prerequisites - -Complete the previous sections of this guide, starting with [Build your Go image](build-images.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and push your Docker image to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration and commit the changes. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/golang/deploy.md b/content/guides/golang/deploy.md deleted file mode 100644 index 1002d6e3d1a9..000000000000 --- a/content/guides/golang/deploy.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Test your Go deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, go, local, development -description: Learn how to deploy your Go application -aliases: - - /language/golang/deploy/ - - /guides/language/golang/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Build - your Go image](build-images.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker - Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your -application to a fully-featured Kubernetes environment on your development -machine. This allows you to test and debug your workloads on Kubernetes locally -before deploying. - -## Create a Kubernetes YAML file - -In your project directory, create a file named -`docker-go-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Go application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: server - name: server - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: server - strategy: {} - template: - metadata: - labels: - service: server - spec: - initContainers: - - name: wait-for-db - image: busybox:1.28 - command: - [ - "sh", - "-c", - 'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;', - ] - containers: - - env: - - name: PGDATABASE - value: mydb - - name: PGPASSWORD - value: whatever - - name: PGHOST - value: db - - name: PGPORT - value: "5432" - - name: PGUSER - value: postgres - image: DOCKER_USERNAME/REPO_NAME - name: server - imagePullPolicy: Always - ports: - - containerPort: 8080 - hostPort: 8080 - protocol: TCP - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: db - name: db - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: db - strategy: - type: Recreate - template: - metadata: - labels: - service: db - spec: - containers: - - env: - - name: POSTGRES_DB - value: mydb - - name: POSTGRES_PASSWORD - value: whatever - - name: POSTGRES_USER - value: postgres - image: postgres:18 - name: db - ports: - - containerPort: 5432 - protocol: TCP - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: server - name: server - namespace: default -spec: - type: NodePort - ports: - - name: "8080" - port: 8080 - targetPort: 8080 - nodePort: 30001 - selector: - service: server -status: - loadBalancer: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: db - name: db - namespace: default -spec: - ports: - - name: "5432" - port: 5432 - targetPort: 5432 - selector: - service: db -status: - loadBalancer: {} -``` - -In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The container is - created from the image built by GitHub Actions in [Configure CI/CD for your - Go application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 8080 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to the project directory - and deploy your application to Kubernetes. - - ```console - $ kubectl apply -f docker-go-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```shell - deployment.apps/db created - service/db created - deployment.apps/server created - service/server created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - db 1/1 1 1 76s - server 1/1 1 1 76s - ``` - - This indicates all of the pods are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - db ClusterIP 10.96.156.90 <none> 5432/TCP 2m8s - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 164m - server NodePort 10.102.94.225 <none> 8080:30001/TCP 2m8s - ``` - - In addition to the default `kubernetes` service, you can see your `server` service and `db` service. The `server` service is accepting traffic on port 30001/TCP. - -3. Open a terminal and curl your application to verify that it's working. - - ```console - $ curl --request POST \ - --url http://localhost:30001/send \ - --header 'content-type: application/json' \ - --data '{"value": "Hello, Oliver!"}' - ``` - - You should get the following message back. - - ```json - { "value": "Hello, Oliver!" } - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-go-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/golang/develop.md b/content/guides/golang/develop.md deleted file mode 100644 index d40e6ccd18c1..000000000000 --- a/content/guides/golang/develop.md +++ /dev/null @@ -1,733 +0,0 @@ ---- -title: Use containers for Go development -linkTitle: Develop your app -weight: 20 -keywords: get started, go, golang, local, development -description: Learn how to develop your application locally. -aliases: - - /get-started/golang/develop/ - - /language/golang/develop/ - - /guides/language/golang/develop/ ---- - -## Prerequisites - -Work through the steps of the [run your image as a container](run-containers.md) module to learn how to manage the lifecycle of your containers. - -## Introduction - -In this module, you'll take a look at running a database engine in a container and connecting it to the extended version of the example application. You are going to see some options for keeping persistent data and for wiring up the containers to talk to one another. Finally, you'll learn how to use Docker Compose to manage such multi-container local development environments effectively. - -## Local database and containers - -The database engine you are going to use is called [CockroachDB](https://www.cockroachlabs.com/product/). It is a modern, Cloud-native, distributed SQL database. - -Instead of compiling CockroachDB from the source code or using the operating system's native package manager to install CockroachDB, you are going to use the [Docker image for CockroachDB](https://hub.docker.com/r/cockroachdb/cockroach) and run it in a container. - -CockroachDB is compatible with PostgreSQL to a significant extent, and shares many conventions with the latter, particularly the default names for the environment variables. So, if you are familiar with Postgres, don't be surprised if you see some familiar environment variable names. The Go modules that work with Postgres, such as [pgx](https://pkg.go.dev/github.com/jackc/pgx), [pq](https://pkg.go.dev/github.com/lib/pq), [GORM](https://gorm.io/index.html), and [upper/db](https://upper.io/v4/) also work with CockroachDB. - -For more information on the relation between Go and CockroachDB, refer to the [CockroachDB documentation](https://www.cockroachlabs.com/docs/v20.2/build-a-go-app-with-cockroachdb.html), although this isn't necessary to continue with the present guide. - -### Storage - -The point of a database is to have a persistent store of data. [Volumes](/manuals/engine/storage/volumes.md) are the preferred mechanism for persisting data generated by and used by Docker containers. Thus, before you start CockroachDB, create the volume for it. - -To create a managed volume, run : - -```console -$ docker volume create roach -roach -``` - -You can view the list of all managed volumes in your Docker instance with the following command: - -```console -$ docker volume list -DRIVER VOLUME NAME -local roach -``` - -### Networking - -The example application and the database engine are going to talk to one another over the network. There are different kinds of network configuration possible, and you're going to use what's called a user-defined bridge network. It is going to provide you with a DNS lookup service so that you can refer to your database engine container by its hostname. - -The following command creates a new bridge network named `mynet`: - -```console -$ docker network create -d bridge mynet -51344edd6430b5acd121822cacc99f8bc39be63dd125a3b3cd517b6485ab7709 -``` - -As it was the case with the managed volumes, there is a command to list all networks set up in your Docker instance: - -```console -$ docker network list -NETWORK ID NAME DRIVER SCOPE -0ac2b1819fa4 bridge bridge local -51344edd6430 mynet bridge local -daed20bbecce host host local -6aee44f40a39 none null local -``` - -Your bridge network `mynet` has been created successfully. The other three networks, named `bridge`, `host`, and `none` are the default networks and they had been created by the Docker itself. While it's not relevant to this guide, you can learn more about Docker networking in the [networking overview](/manuals/engine/network/_index.md) section. - -### Choose good names for volumes and networks - -As the saying goes, there are only two hard things in Computer Science: cache invalidation and naming things. And off-by-one errors. - -When choosing a name for a network or a managed volume, it's best to choose a name that's indicative of the intended purpose. This guide aims for brevity, so it used short, generic names. - -### Start the database engine - -Now that the housekeeping chores are done, you can run CockroachDB in a container and attach it to the volume and network you had just created. When you run the following command, Docker will pull the image from Docker Hub and run it for you locally: - -```console -$ docker run -d \ - --name roach \ - --hostname db \ - --network mynet \ - -p 26257:26257 \ - -p 8080:8080 \ - -v roach:/cockroach/cockroach-data \ - cockroachdb/cockroach:latest-v25.4 start-single-node \ - --insecure - -# ... output omitted ... -``` - -Notice a clever use of the tag `latest-v25.4` to make sure that you're pulling the latest patch version of 25.4. The diversity of available tags depend on the image maintainer. Here, your intent was to have the latest patched version of CockroachDB while not straying too far away from the known working version as the time goes by. To see the tags available for the CockroachDB image, you can go to the [CockroachDB page on Docker Hub](https://hub.docker.com/r/cockroachdb/cockroach/tags). - -### Configure the database engine - -Now that the database engine is live, there is some configuration to do before your application can begin using it. Fortunately, it's not a lot. You must: - -1. Create a blank database. -2. Register a new user account with the database engine. -3. Grant that new user access rights to the database. - -You can do that with the help of CockroachDB built-in SQL shell. To start the SQL shell in the same container where the database engine is running, type: - -```console -$ docker exec -it roach ./cockroach sql --insecure -``` - -1. In the SQL shell, create the database that the example application is going to use: - - ```sql - CREATE DATABASE mydb; - ``` - -2. Register a new SQL user account with the database engine. Use the username `totoro`. - - ```sql - CREATE USER totoro; - ``` - -3. Give the new user the necessary permissions: - - ```sql - GRANT ALL ON DATABASE mydb TO totoro; - ``` - -4. Type `quit` to exit the shell. - -The following is an example of interaction with the SQL shell. - -```console -$ sudo docker exec -it roach ./cockroach sql --insecure -# -# Welcome to the CockroachDB SQL shell. -# All statements must be terminated by a semicolon. -# To exit, type: \q. -# -# Server version: CockroachDB CCL v20.1.15 (x86_64-unknown-linux-gnu, built 2021/04/26 16:11:58, go1.13.9) (same version as client) -# Cluster ID: 7f43a490-ccd6-4c2a-9534-21f393ca80ce -# -# Enter \? for a brief introduction. -# -root@:26257/defaultdb> CREATE DATABASE mydb; -CREATE DATABASE - -Time: 22.985478ms - -root@:26257/defaultdb> CREATE USER totoro; -CREATE ROLE - -Time: 13.921659ms - -root@:26257/defaultdb> GRANT ALL ON DATABASE mydb TO totoro; -GRANT - -Time: 14.217559ms - -root@:26257/defaultdb> quit -oliver@hki:~$ -``` - -### Meet the example application - -Now that you have started and configured the database engine, you can switch your attention to the application. - -The example application for this module is an extended version of `docker-gs-ping` application you've used in the previous modules. You have two options: - -- You can update your local copy of `docker-gs-ping` to match the new extended version presented in this chapter; or -- You can clone the [docker/docker-gs-ping-dev](https://github.com/docker/docker-gs-ping-dev) repository. This latter approach is recommended. - -To checkout the example application, run: - -```console -$ git clone https://github.com/docker/docker-gs-ping-dev.git -# ... output omitted ... -``` - -The application's `main.go` now includes database initialization code, as well as the code to implement a new business requirement: - -- An HTTP `POST` request to `/send` containing a `{ "value" : string }` JSON must save the value to the database. - -You also have an update for another business requirement. The requirement was: - -- The application responds with a text message containing a heart symbol ("`<3`") on requests to `/`. - -And now it's going to be: - -- The application responds with the string containing the count of messages stored in the database, enclosed in the parentheses. - - Example output: `Hello, Docker! (7)` - -The full source code listing of `main.go` follows. - -```go -package main - -import ( - "context" - "database/sql" - "fmt" - "log" - "net/http" - "os" - - "github.com/cenkalti/backoff/v4" - "github.com/cockroachdb/cockroach-go/v2/crdb" - "github.com/labstack/echo/v4" - "github.com/labstack/echo/v4/middleware" -) - -func main() { - - e := echo.New() - - e.Use(middleware.Logger()) - e.Use(middleware.Recover()) - - db, err := initStore() - if err != nil { - log.Fatalf("failed to initialize the store: %s", err) - } - defer db.Close() - - e.GET("/", func(c echo.Context) error { - return rootHandler(db, c) - }) - - e.GET("/ping", func(c echo.Context) error { - return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"}) - }) - - e.POST("/send", func(c echo.Context) error { - return sendHandler(db, c) - }) - - httpPort := os.Getenv("HTTP_PORT") - if httpPort == "" { - httpPort = "8080" - } - - e.Logger.Fatal(e.Start(":" + httpPort)) -} - -type Message struct { - Value string `json:"value"` -} - -func initStore() (*sql.DB, error) { - - pgConnString := fmt.Sprintf("host=%s port=%s dbname=%s user=%s password=%s sslmode=disable", - os.Getenv("PGHOST"), - os.Getenv("PGPORT"), - os.Getenv("PGDATABASE"), - os.Getenv("PGUSER"), - os.Getenv("PGPASSWORD"), - ) - - var ( - db *sql.DB - err error - ) - openDB := func() error { - db, err = sql.Open("postgres", pgConnString) - return err - } - - err = backoff.Retry(openDB, backoff.NewExponentialBackOff()) - if err != nil { - return nil, err - } - - if _, err := db.Exec( - "CREATE TABLE IF NOT EXISTS message (value TEXT PRIMARY KEY)"); err != nil { - return nil, err - } - - return db, nil -} - -func rootHandler(db *sql.DB, c echo.Context) error { - r, err := countRecords(db) - if err != nil { - return c.HTML(http.StatusInternalServerError, err.Error()) - } - return c.HTML(http.StatusOK, fmt.Sprintf("Hello, Docker! (%d)\n", r)) -} - -func sendHandler(db *sql.DB, c echo.Context) error { - - m := &Message{} - - if err := c.Bind(m); err != nil { - return c.JSON(http.StatusInternalServerError, err) - } - - err := crdb.ExecuteTx(context.Background(), db, nil, - func(tx *sql.Tx) error { - _, err := tx.Exec( - "INSERT INTO message (value) VALUES ($1) ON CONFLICT (value) DO UPDATE SET value = excluded.value", - m.Value, - ) - if err != nil { - return c.JSON(http.StatusInternalServerError, err) - } - return nil - }) - - if err != nil { - return c.JSON(http.StatusInternalServerError, err) - } - - return c.JSON(http.StatusOK, m) -} - -func countRecords(db *sql.DB) (int, error) { - - rows, err := db.Query("SELECT COUNT(*) FROM message") - if err != nil { - return 0, err - } - defer rows.Close() - - count := 0 - for rows.Next() { - if err := rows.Scan(&count); err != nil { - return 0, err - } - rows.Close() - } - - return count, nil -} -``` - -The repository also includes the `Dockerfile`, which is almost exactly the same as the multi-stage `Dockerfile` introduced in the previous modules. It uses the official Docker Go image to build the application and then builds the final image by placing the compiled binary into the much slimmer, distroless image. - -Regardless of whether you had updated the old example application, or checked out the new one, this new Docker image has to be built to reflect the changes to the application source code. - -### Build the application - -You can build the image with the familiar `build` command: - -```console -$ docker build --tag docker-gs-ping-roach . -``` - -### Run the application - -Now, run your container. This time you'll need to set some environment variables so that your application knows how to access the database. For now, you’ll do this right in the `docker run` command. Later you'll see a more convenient method with Docker Compose. - -> [!NOTE] -> -> Since you're running your CockroachDB cluster in insecure mode, the value for the password can be anything. -> -> In production, don't run in insecure mode. - -```console -$ docker run -it --rm -d \ - --network mynet \ - --name rest-server \ - -p 80:8080 \ - -e PGUSER=totoro \ - -e PGPASSWORD=myfriend \ - -e PGHOST=db \ - -e PGPORT=26257 \ - -e PGDATABASE=mydb \ - docker-gs-ping-roach -``` - -There are a few points to note about this command. - -- You map container port `8080` to host port `80` this time. Thus, for `GET` requests you can get away with literally `curl localhost`: - - ```console - $ curl localhost - Hello, Docker! (0) - ``` - - Or, if you prefer, a proper URL would work just as well: - - ```console - $ curl http://localhost/ - Hello, Docker! (0) - ``` - -- The total number of stored messages is `0` for now. This is fine, because you haven't posted anything to your application yet. -- You refer to the database container by its hostname, which is `db`. This is why you had `--hostname db` when you started the database container. - -- The actual password doesn't matter, but it must be set to something to avoid confusing the example application. -- The container you've just run is named `rest-server`. These names are useful for managing the container lifecycle: - - ```console - # Don't do this just yet, it's only an example: - $ docker container rm --force rest-server - ``` - -### Test the application - -In the previous section, you've already tested querying your application with `GET` and it returned zero for the stored message counter. Now, post some messages to it: - -```console -$ curl --request POST \ - --url http://localhost/send \ - --header 'content-type: application/json' \ - --data '{"value": "Hello, Docker!"}' -``` - -The application responds with the contents of the message, which means it has been saved in the database: - -```json -{ "value": "Hello, Docker!" } -``` - -Send another message: - -```console -$ curl --request POST \ - --url http://localhost/send \ - --header 'content-type: application/json' \ - --data '{"value": "Hello, Oliver!"}' -``` - -And again, you get the value of the message back: - -```json -{ "value": "Hello, Oliver!" } -``` - -Run curl and see what the message counter says: - -```console -$ curl localhost -Hello, Docker! (2) -``` - -In this example, you sent two messages and the database kept them. Or has it? Stop and remove all your containers, but not the volumes, and try again. - -First, stop the containers: - -```console -$ docker container stop rest-server roach -rest-server -roach -``` - -Then, remove them: - -```console -$ docker container rm rest-server roach -rest-server -roach -``` - -Verify that they're gone: - -```console -$ docker container list --all -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -And start them again, database first: - -```console -$ docker run -d \ - --name roach \ - --hostname db \ - --network mynet \ - -p 26257:26257 \ - -p 8080:8080 \ - -v roach:/cockroach/cockroach-data \ - cockroachdb/cockroach:latest-v25.4 start-single-node \ - --insecure -``` - -And the service next: - -```console -$ docker run -it --rm -d \ - --network mynet \ - --name rest-server \ - -p 80:8080 \ - -e PGUSER=totoro \ - -e PGPASSWORD=myfriend \ - -e PGHOST=db \ - -e PGPORT=26257 \ - -e PGDATABASE=mydb \ - docker-gs-ping-roach -``` - -Lastly, query your service: - -```console -$ curl localhost -Hello, Docker! (2) -``` - -Great! The count of records from the database is correct although you haven't only stopped the containers, but you've also removed them before starting new instances. The difference is in the managed volume for CockroachDB, which you reused. The new CockroachDB container has read the database files from the disk, just as it normally would if it were running outside the container. - -### Wind down everything - -Remember, that you're running CockroachDB in insecure mode. Now that you've built and tested your application, it's time to wind everything down before moving on. You can list the containers that you are running with the `list` command: - -```console -$ docker container list -``` - -Now that you know the container IDs, you can use `docker container stop` and `docker container rm`, as demonstrated in the previous modules. - -Stop the CockroachDB and `docker-gs-ping-roach` containers before moving on. - -## Better productivity with Docker Compose - -At this point, you might be wondering if there is a way to avoid having to deal with long lists of arguments to the `docker` command. The toy example you used in this series requires five environment variables to define the connection to the database. A real application might need many, many more. Then there is also a question of dependencies. Ideally, you want to make sure that the database is started before your application is run. And spinning up the database instance may require another Docker command with many options. But there is a better way to orchestrate these deployments for local development purposes. - -In this section, you'll create a Docker Compose file to start your `docker-gs-ping-roach` application and CockroachDB database engine with a single command. - -### Configure Docker Compose - -In your application's directory, create a new text file named `compose.yaml` with the following content. - -```yaml -services: - docker-gs-ping-roach: - depends_on: - - roach - build: - context: . - container_name: rest-server - hostname: rest-server - networks: - - mynet - ports: - - 80:8080 - environment: - - PGUSER=${PGUSER:-totoro} - - PGPASSWORD=${PGPASSWORD:?database password not set} - - PGHOST=${PGHOST:-db} - - PGPORT=${PGPORT:-26257} - - PGDATABASE=${PGDATABASE:-mydb} - deploy: - restart_policy: - condition: on-failure - roach: - image: cockroachdb/cockroach:latest-v25.4 - container_name: roach - hostname: db - networks: - - mynet - ports: - - 26257:26257 - - 8080:8080 - volumes: - - roach:/cockroach/cockroach-data - command: start-single-node --insecure - -volumes: - roach: - -networks: - mynet: - driver: bridge -``` - -This Docker Compose configuration is super convenient as you don't have to type all the parameters to pass to the `docker run` command. You can declaratively do that in the Docker Compose file. The [Docker Compose documentation pages](/manuals/compose/_index.md) are quite extensive and include a full reference for the Docker Compose file format. - -### The `.env` file - -Docker Compose will automatically read environment variables from a `.env` file if it's available. Since your Compose file requires `PGPASSWORD` to be set, add the following content to the `.env` file: - -```bash -PGPASSWORD=whatever -``` - -The exact value doesn't really matter for this example, because you run CockroachDB in insecure mode. Make sure you set the variable to some value to avoid getting an error. - -### Merging Compose files - -The filename `compose.yaml` is the default filename which `docker compose` command recognizes if no `-f` flag is provided. This means you can have multiple Docker Compose files if your environment has such requirements. Furthermore, Docker Compose files are composable, so multiple files can be specified on the command line to merge parts of the configuration together. The following list shows a few examples of scenarios where such a feature would be useful: - -- Using a bind mount for the source code for local development but not when running the CI tests; -- Switching between using a pre-built image for the frontend for some API application vs creating a bind mount for source code; -- Adding additional services for integration testing; -- And many more... - -You aren't going to cover any of these advanced use cases here. - -### Variable substitution in Docker Compose - -One of the really cool features of Docker Compose is [variable substitution](/reference/compose-file/interpolation.md). You can see some examples in the Compose file, `environment` section. By means of an example: - -- `PGUSER=${PGUSER:-totoro}` means that inside the container, the environment variable `PGUSER` shall be set to the same value as it has on the host machine where Docker Compose is run. If there is no environment variable with this name on the host machine, the variable inside the container gets the default value of `totoro`. -- `PGPASSWORD=${PGPASSWORD:?database password not set}` means that if the environment variable `PGPASSWORD` isn't set on the host, Docker Compose will display an error. This is OK, because you don't want to hard-code default values for the password. You set the password value in the `.env` file, which is local to your machine. It is always a good idea to add `.env` to `.gitignore` to prevent the secrets being checked into the version control. - -Other ways of dealing with undefined or empty values exist, as documented in the [variable substitution](/reference/compose-file/interpolation.md) section of the Docker documentation. - -### Validating Docker Compose configuration - -Before you apply changes made to a Compose configuration file, there is an opportunity to validate the content of the configuration file with the following command: - -```console -$ docker compose config -``` - -When this command is run, Docker Compose reads the file `compose.yaml`, parses it into a data structure in memory, validates where possible, and prints back the reconstruction of that configuration file from its internal representation. If this isn't possible due to errors, Docker prints an error message instead. - -### Build and run the application using Docker Compose - -Start your application and confirm that it's running. - -```console -$ docker compose up --build -``` - -You passed the `--build` flag so Docker will compile your image and then start it. - -> [!NOTE] -> -> Docker Compose is a useful tool, but it has its own quirks. For example, no rebuild is triggered on the update to the source code unless the `--build` flag is provided. It is a very common pitfall to edit one's source code, and forget to use the `--build` flag when running `docker compose up`. - -Since your set-up is now run by Docker Compose, it has assigned it a project name, so you get a new volume for your CockroachDB instance. This means that your application will fail to connect to the database, because the database doesn't exist in this new volume. The terminal displays an authentication error for the database: - -```text -# ... omitted output ... -rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro -roach | * -roach | * INFO: Replication was disabled for this cluster. -roach | * When/if adding nodes in the future, update zone configurations to increase the replication factor. -roach | * -roach | CockroachDB node starting at 2021-05-10 00:54:26.398177 +0000 UTC (took 3.0s) -roach | build: CCL v20.1.15 @ 2021/04/26 16:11:58 (go1.13.9) -roach | webui: http://db:8080 -roach | sql: postgresql://root@db:26257?sslmode=disable -roach | RPC client flags: /cockroach/cockroach <client cmd> --host=db:26257 --insecure -roach | logs: /cockroach/cockroach-data/logs -roach | temp dir: /cockroach/cockroach-data/cockroach-temp349434348 -roach | external I/O path: /cockroach/cockroach-data/extern -roach | store[0]: path=/cockroach/cockroach-data -roach | storage engine: rocksdb -roach | status: initialized new cluster -roach | clusterID: b7b1cb93-558f-4058-b77e-8a4ddb329a88 -roach | nodeID: 1 -rest-server exited with code 0 -rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro -rest-server | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro -rest-server | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro -rest-server | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro -rest-server | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro -rest-server | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro -rest-server exited with code 1 -# ... omitted output ... -``` - -Because of the way you set up your deployment using `restart_policy`, the failing container is being restarted every 20 seconds. So, in order to fix the problem, you need to log in to the database engine and create the user. You've done it before in [Configure the database engine](#configure-the-database-engine). - -This isn't a big deal. All you have to do is to connect to CockroachDB instance and run the three SQL commands to create the database and the user, as described in [Configure the database engine](#configure-the-database-engine). - -So, log in to the database engine from another terminal: - -```console -$ docker exec -it roach ./cockroach sql --insecure -``` - -And run the same commands as before to create the database `mydb`, the user `totoro`, and to grant that user necessary permissions. Once you do that (and the example application container is automatically restarts), the `rest-service` stops failing and restarting and the console goes quiet. - -It would have been possible to connect the volume that you had previously used, but for the purposes of this example it's more trouble than it's worth and it also provided an opportunity to show how to introduce resilience into your deployment via the `restart_policy` Compose file feature. - -### Testing the application - -Now, test your API endpoint. In the new terminal, run the following command: - -```console -$ curl http://localhost/ -``` - -You should receive the following response: - -```json -Hello, Docker! (0) -``` - -### Shutting down - -To stop the containers started by Docker Compose, press `ctrl+c` in the terminal where you ran `docker compose up`. To remove those containers after they've been stopped, run `docker compose down`. - -### Detached mode - -You can run containers started by the `docker compose` command in detached mode, just as you would with the `docker` command, by using the `-d` flag. - -To start the stack, defined by the Compose file in detached mode, run: - -```console -$ docker compose up --build -d -``` - -Then, you can use `docker compose stop` to stop the containers and `docker compose down` to remove them. - -## Further exploration - -You can run `docker compose` to see what other commands are available. - -## Wrap up - -There are some tangential, yet interesting points that were purposefully not covered in this chapter. For the more adventurous reader, this section offers some pointers for further study. - -### Persistent storage - -A managed volume isn't the only way to provide your container with persistent storage. It is highly recommended to get acquainted with available storage options and their use cases, covered in [Manage data in Docker](/manuals/engine/storage/_index.md). - -### CockroachDB clusters - -You ran a single instance of CockroachDB, which was enough for this example. But, it's possible to run a CockroachDB cluster, which is made of multiple instances of CockroachDB, each instance running in its own container. Since CockroachDB engine is distributed by design, it would have taken surprisingly little change to your procedure to run a cluster with multiple nodes. - -Such distributed set-up offers interesting possibilities, such as applying Chaos Engineering techniques to simulate parts of the cluster failing and evaluating your application's ability to cope with such failures. - -If you are interested in experimenting with CockroachDB clusters, check out: - -- [Start a CockroachDB Cluster in Docker](https://www.cockroachlabs.com/docs/v20.2/start-a-local-cluster-in-docker-mac.html) article; and -- Documentation for Docker Compose keywords [`deploy`](/reference/compose-file/legacy-versions.md) and [`replicas`](/reference/compose-file/legacy-versions.md). - -### Other databases - -Since you didn't run a cluster of CockroachDB instances, you might be wondering whether you could have used a non-distributed database engine. The answer is 'yes', and if you were to pick a more traditional SQL database, such as [PostgreSQL](https://www.postgresql.org/), the process described in this chapter would have been very similar. - -## Next steps - -In this module, you set up a containerized development environment with your application and the database engine running in different containers. You also wrote a Docker Compose file which links the two containers together and provides for easy starting up and tearing down of the development environment. - -In the next module, you'll take a look at one possible approach to running functional tests in Docker. diff --git a/content/guides/golang/run-containers.md b/content/guides/golang/run-containers.md deleted file mode 100644 index 34e87c648915..000000000000 --- a/content/guides/golang/run-containers.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Run your Go image as a container -linkTitle: Run containers -weight: 10 -keywords: get started, go, golang, run, container -description: Learn how to run the image as a container. -aliases: - - /get-started/golang/run-containers/ - - /language/golang/run-containers/ - - /guides/language/golang/run-containers/ ---- - -## Prerequisites - -Work through the steps to containerize a Go application in [Build your Go image](build-images.md). - -## Overview - -In the previous module you created a `Dockerfile` for your example application and then you created your Docker image using the command `docker build`. Now that you have the image, you can run that image and see if your application is running correctly. - -A container is a normal operating system process except that this process is isolated and has its own file system, its own networking, and its own isolated process tree separate from the host. - -To run an image inside of a container, you use the `docker run` command. It requires one parameter and that's the image name. Start your image and make sure it's running correctly. Run the following command in your terminal. - -```console -$ docker run docker-gs-ping -``` - -```text - ____ __ - / __/___/ / ___ - / _// __/ _ \/ _ \ -/___/\__/_//_/\___/ v4.10.2 -High performance, minimalist Go web framework -https://echo.labstack.com -____________________________________O/_______ - O\ -⇨ http server started on [::]:8080 -``` - -When you run this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a REST server and will run in a loop waiting for incoming requests without returning control back to the OS until you stop the container. - -Make a GET request to the server using the curl command. - -```console -$ curl http://localhost:8080/ -curl: (7) Failed to connect to localhost port 8080: Connection refused -``` - -Your curl command failed because the connection to your server was refused. -Meaning that you weren't able to connect to localhost on port 8080. This is -expected because your container is running in isolation which includes -networking. Stop the container and restart with port 8080 published on your -local network. - -To stop the container, press ctrl-c. This will return you to the terminal prompt. - -To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host_port]:[container_port]`. So if you wanted to expose port `8080` inside the container to port `3000` outside the container, you would pass `3000:8080` to the `--publish` flag. - -Start the container and expose port `8080` to port `8080` on the host. - -```console -$ docker run --publish 8080:8080 docker-gs-ping -``` - -Now, rerun the curl command. - -```console -$ curl http://localhost:8080/ -Hello, Docker! <3 -``` - -Success! You were able to connect to the application running inside of your container on port 8080. Switch back to the terminal where your container is running and you should see the `GET` request logged to the console. - -Press `ctrl-c` to stop the container. - -## Run in detached mode - -This is great so far, but your sample application is a web server and you -shouldn't have to have your terminal connected to the container. Docker can run -your container in detached mode in the background. To do this, you can use the -`--detach` or `-d` for short. Docker will start your container the same as -before but this time will detach from the container and return you to the -terminal prompt. - -```console -$ docker run -d -p 8080:8080 docker-gs-ping -d75e61fcad1e0c0eca69a3f767be6ba28a66625ce4dc42201a8a323e8313c14e -``` - -Docker started your container in the background and printed the container ID on the terminal. - -Again, make sure that your container is running. Run the same `curl` command: - -```console -$ curl http://localhost:8080/ -Hello, Docker! <3 -``` - -## List containers - -Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how the ps command is used to see a list of processes on a Linux machine. - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d75e61fcad1e docker-gs-ping "/docker-gs-ping" 41 seconds ago Up 40 seconds 0.0.0.0:8080->8080/tcp inspiring_ishizaka -``` - -The `ps` command tells you a bunch of stuff about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that are exposed, and the names of the container. - -You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You'll fix this in a minute but first you need to stop the container. To stop the container, run the `docker stop` command, passing the container's name or ID. - -```console -$ docker stop inspiring_ishizaka -inspiring_ishizaka -``` - -Now rerun the `docker ps` command to see a list of running containers. - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -## Stop, start, and name containers - -Docker containers can be started, stopped and restarted. When you stop a container, it's not removed but the status is changed to stopped and the process inside of the container is stopped. When you ran the `docker ps` command, the default output is to only show running containers. If you pass the `--all` or `-a` for short, you will see all containers on your system, including stopped containers and running containers. - -```console -$ docker ps --all - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d75e61fcad1e docker-gs-ping "/docker-gs-ping" About a minute ago Exited (2) 23 seconds ago inspiring_ishizaka -f65dbbb9a548 docker-gs-ping "/docker-gs-ping" 3 minutes ago Exited (2) 2 minutes ago wizardly_joliot -aade1bf3d330 docker-gs-ping "/docker-gs-ping" 3 minutes ago Exited (2) 3 minutes ago magical_carson -52d5ce3c15f0 docker-gs-ping "/docker-gs-ping" 9 minutes ago Exited (2) 3 minutes ago gifted_mestorf -``` - -If you’ve been following along, you should see several containers listed. These are containers that you started and stopped but haven't removed yet. - -Restart the container that you have just stopped. Locate the name of the container and replace the name of the container in the following `restart` command: - -```console -$ docker restart inspiring_ishizaka -``` - -Now, list all the containers again using the `ps` command: - -```console -$ docker ps -a - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d75e61fcad1e docker-gs-ping "/docker-gs-ping" 2 minutes ago Up 5 seconds 0.0.0.0:8080->8080/tcp inspiring_ishizaka -f65dbbb9a548 docker-gs-ping "/docker-gs-ping" 4 minutes ago Exited (2) 2 minutes ago wizardly_joliot -aade1bf3d330 docker-gs-ping "/docker-gs-ping" 4 minutes ago Exited (2) 4 minutes ago magical_carson -52d5ce3c15f0 docker-gs-ping "/docker-gs-ping" 10 minutes ago Exited (2) 4 minutes ago gifted_mestorf -``` - -Notice that the container you just restarted has been started in detached mode and has port `8080` exposed. Also, note that the status of the container is `Up X seconds`. When you restart a container, it will be started with the same flags or commands that it was originally started with. - -Stop and remove all of your containers and take a look at fixing the random naming issue. - -Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system: - -```console -$ docker stop inspiring_ishizaka -inspiring_ishizaka -``` - -Now that all of your containers are stopped, remove them. When a container is removed, it's no longer running nor is it in the stopped state. Instead, the process inside the container is terminated and the metadata for the container is removed. - -To remove a container, run the `docker rm` command passing the container name. You can pass multiple container names to the command in one command. - -Again, make sure you replace the containers names in the following command with the container names from your system: - -```console -$ docker rm inspiring_ishizaka wizardly_joliot magical_carson gifted_mestorf - -inspiring_ishizaka -wizardly_joliot -magical_carson -gifted_mestorf -``` - -Run the `docker ps --all` command again to verify that all containers are gone. - -Now, address the pesky random name issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with. Just like good naming conventions for variables in your code makes it simpler to read. So goes naming your containers. - -To name a container, you must pass the `--name` flag to the `run` command: - -```console -$ docker run -d -p 8080:8080 --name rest-server docker-gs-ping -3bbc6a3102ea368c8b966e1878a5ea9b1fc61187afaac1276c41db22e4b7f48f -``` - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -3bbc6a3102ea docker-gs-ping "/docker-gs-ping" 25 seconds ago Up 24 seconds 0.0.0.0:8080->8080/tcp rest-server -``` - -Now, you can easily identify your container based on the name. - -## Next steps - -In this module, you learned how to run containers and publish ports. You also learned to manage the lifecycle of containers. You then learned the importance of naming your containers so that they're more easily identifiable. In the next module, you’ll learn how to run a database in a container and connect it to your application. diff --git a/content/guides/golang/run-tests.md b/content/guides/golang/run-tests.md deleted file mode 100644 index b4b435fd62e2..000000000000 --- a/content/guides/golang/run-tests.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Run your tests using Go test -linkTitle: Run your tests -weight: 30 -keywords: build, go, golang, test -description: How to build and run your Go tests in a container -aliases: - - /get-started/golang/run-tests/ - - /language/golang/run-tests/ - - /guides/language/golang/run-tests/ ---- - -## Prerequisites - -Complete the [Build your Go image](build-images.md) section of this guide. - -## Overview - -Testing is an essential part of modern software development. Testing can mean a -lot of things to different development teams. There are unit tests, integration -tests and end-to-end testing. In this guide you take a look at running your unit -tests in Docker when building. - -For this section, use the `docker-gs-ping` project that you cloned in [Build -your Go image](build-images.md). - -## Run tests when building - -To run your tests when building, you need to add a test stage to the -`Dockerfile.multistage`. The `Dockerfile.multistage` in the sample application's -repository already has the following content: - -```dockerfile {hl_lines="15-17"} -# syntax=docker/dockerfile:1 - -# Build the application from source -FROM golang:1.19 AS build-stage - -WORKDIR /app - -COPY go.mod go.sum ./ -RUN go mod download - -COPY *.go ./ - -RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping - -# Run the tests in the container -FROM build-stage AS run-test-stage -RUN go test -v ./... - -# Deploy the application binary into a lean image -FROM gcr.io/distroless/base-debian11 AS build-release-stage - -WORKDIR / - -COPY --from=build-stage /docker-gs-ping /docker-gs-ping - -EXPOSE 8080 - -USER nonroot:nonroot - -ENTRYPOINT ["/docker-gs-ping"] -``` - -Run the following command to build an image using the `run-test-stage` stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target run-test-stage` to target the test stage. - -```console -$ docker build -f Dockerfile.multistage -t docker-gs-ping-test --progress plain --no-cache --target run-test-stage . -``` - -You should see output containing the following. - -```text -#13 [run-test-stage 1/1] RUN go test -v ./... -#13 4.915 === RUN TestIntMinBasic -#13 4.915 --- PASS: TestIntMinBasic (0.00s) -#13 4.915 === RUN TestIntMinTableDriven -#13 4.915 === RUN TestIntMinTableDriven/0,1 -#13 4.915 === RUN TestIntMinTableDriven/1,0 -#13 4.915 === RUN TestIntMinTableDriven/2,-2 -#13 4.915 === RUN TestIntMinTableDriven/0,-1 -#13 4.915 === RUN TestIntMinTableDriven/-1,0 -#13 4.915 --- PASS: TestIntMinTableDriven (0.00s) -#13 4.915 --- PASS: TestIntMinTableDriven/0,1 (0.00s) -#13 4.915 --- PASS: TestIntMinTableDriven/1,0 (0.00s) -#13 4.915 --- PASS: TestIntMinTableDriven/2,-2 (0.00s) -#13 4.915 --- PASS: TestIntMinTableDriven/0,-1 (0.00s) -#13 4.915 --- PASS: TestIntMinTableDriven/-1,0 (0.00s) -#13 4.915 PASS -``` - -## Next steps - -In this section, you learned how to run tests when building your image. Next, -you’ll learn how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/grafana-mcp-server-gemini.md b/content/guides/grafana-mcp-server-gemini.md index eed65cfbfc64..c11c32e3c55c 100644 --- a/content/guides/grafana-mcp-server-gemini.md +++ b/content/guides/grafana-mcp-server-gemini.md @@ -5,6 +5,7 @@ title: Connect Gemini to Grafana via MCP summary: | Learn how to leverage the Model Context Protocol (MCP) to interact with Grafana dashboards and datasources directly from your terminal. params: + tags: [ai] proficiencyLevel: Intermediate time: 15 minutes --- diff --git a/content/guides/genai-claude-code-mcp/Images/catalog_docker_hub.avif b/content/guides/images/genai-claude-code-mcp-catalog-docker-hub.avif similarity index 100% rename from content/guides/genai-claude-code-mcp/Images/catalog_docker_hub.avif rename to content/guides/images/genai-claude-code-mcp-catalog-docker-hub.avif diff --git a/content/guides/genai-claude-code-mcp/Images/docker-connect-claude.avif b/content/guides/images/genai-claude-code-mcp-docker-connect-claude.avif similarity index 100% rename from content/guides/genai-claude-code-mcp/Images/docker-connect-claude.avif rename to content/guides/images/genai-claude-code-mcp-docker-connect-claude.avif diff --git a/content/guides/genai-claude-code-mcp/Images/dockerhub_secrets.avif b/content/guides/images/genai-claude-code-mcp-dockerhub-secrets.avif similarity index 100% rename from content/guides/genai-claude-code-mcp/Images/dockerhub_secrets.avif rename to content/guides/images/genai-claude-code-mcp-dockerhub-secrets.avif diff --git a/content/guides/genai-claude-code-mcp/Images/Localhost.avif b/content/guides/images/genai-claude-code-mcp-localhost.avif similarity index 100% rename from content/guides/genai-claude-code-mcp/Images/Localhost.avif rename to content/guides/images/genai-claude-code-mcp-localhost.avif diff --git a/content/guides/genai-claude-code-mcp/Images/mcp-servers.avif b/content/guides/images/genai-claude-code-mcp-mcp-servers.avif similarity index 100% rename from content/guides/genai-claude-code-mcp/Images/mcp-servers.avif rename to content/guides/images/genai-claude-code-mcp-mcp-servers.avif diff --git a/content/guides/java/images/compose-logs.webp b/content/guides/images/java-compose-logs.webp similarity index 100% rename from content/guides/java/images/compose-logs.webp rename to content/guides/images/java-compose-logs.webp diff --git a/content/guides/java/images/connect-debugger.webp b/content/guides/images/java-connect-debugger.webp similarity index 100% rename from content/guides/java/images/connect-debugger.webp rename to content/guides/images/java-connect-debugger.webp diff --git a/content/guides/java/images/debug-menu.webp b/content/guides/images/java-debug-menu.webp similarity index 100% rename from content/guides/java/images/debug-menu.webp rename to content/guides/images/java-debug-menu.webp diff --git a/content/guides/java/images/debugger-breakpoint.webp b/content/guides/images/java-debugger-breakpoint.webp similarity index 100% rename from content/guides/java/images/debugger-breakpoint.webp rename to content/guides/images/java-debugger-breakpoint.webp diff --git a/content/guides/images/mistral-vibe-sandbox-credential.jpg b/content/guides/images/mistral-vibe-sandbox-credential.jpg new file mode 100644 index 000000000000..0b4934084cc1 Binary files /dev/null and b/content/guides/images/mistral-vibe-sandbox-credential.jpg differ diff --git a/content/guides/images/mistral-vibe-sandbox-models.jpg b/content/guides/images/mistral-vibe-sandbox-models.jpg new file mode 100644 index 000000000000..6695721d562a Binary files /dev/null and b/content/guides/images/mistral-vibe-sandbox-models.jpg differ diff --git a/content/guides/images/mistral-vibe-sandbox-repair.jpg b/content/guides/images/mistral-vibe-sandbox-repair.jpg new file mode 100644 index 000000000000..2d5ed4747ea8 Binary files /dev/null and b/content/guides/images/mistral-vibe-sandbox-repair.jpg differ diff --git a/content/guides/java.md b/content/guides/java.md new file mode 100644 index 000000000000..b2958a107410 --- /dev/null +++ b/content/guides/java.md @@ -0,0 +1,796 @@ +--- +title: Java language-specific guide +linkTitle: Java +keywords: java, getting started +description: Containerize Java apps using Docker +summary: | + This guide demonstrates how to containerize Java applications using Docker. +aliases: + - /language/java/ + - /guides/language/java/ + - /language/java/build-images/ + - /language/java/run-containers/ + - /language/java/containerize/ + - /language/java/develop/ + - /language/java/run-tests/ + - /language/java/configure-ci-cd/ + - /language/java/deploy/ + - /guides/java/configure-ci-cd/ + - /guides/java/containerize/ + - /guides/java/deploy/ + - /guides/java/develop/ + - /guides/java/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +The Java getting started guide teaches you how to create a containerized Spring Boot application using Docker. In this module, you’ll learn how to: + +- Containerize and run a Spring Boot application with Maven +- Set up a local development environment to connect a database to the container, configure a debugger, and use Compose Watch for live reload +- Run your unit tests inside a container + +After completing the Java getting started modules, you should be able to containerize your own Java application based on the examples and instructions provided in this guide. + +Get started containerizing your first Java app. + +## Containerize a Java application + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). + Docker adds new features regularly and some parts of this guide may + work only with the latest version of Docker Desktop. + +* You have a [Git client](https://git-scm.com/downloads). The examples in this + section use a command-line based Git client, but you can use any client. + +### Overview + +This section walks you through containerizing and running a Java +application. + +### Get the sample applications + +Clone the sample application that you'll be using to your local development machine. Run the following command in a terminal to clone the repository. + +```console +$ git clone https://github.com/spring-projects/spring-petclinic.git +``` + +The sample application is a Spring Boot application built using Maven. For more details, see `readme.md` in the repository. + +### Create Docker assets + +Now that you have an application, you can create the necessary Docker assets to +containerize your application. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +Create a file named `Dockerfile` with the following contents. + +```dockerfile {collapse=true,title=Dockerfile} +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +################################################################################ + +# Create a stage for resolving and downloading dependencies. +FROM eclipse-temurin:21-jdk-jammy as deps + +WORKDIR /build + +# Copy the mvnw wrapper with executable permissions. +COPY --chmod=0755 mvnw mvnw +COPY .mvn/ .mvn/ + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.m2 so that subsequent builds don't have to +# re-download packages. +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests + +################################################################################ + +# Create a stage for building the application based on the stage with downloaded dependencies. +# This Dockerfile is optimized for Java applications that output an uber jar, which includes +# all the dependencies needed to run your app inside a JVM. If your app doesn't output an uber +# jar and instead relies on an application server like Apache Tomcat, you'll need to update this +# stage with the correct filename of your package and update the base image of the "final" stage +# use the relevant app server, e.g., using tomcat (https://hub.docker.com/_/tomcat/) as a base image. +FROM deps as package + +WORKDIR /build + +COPY ./src src/ +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 \ + ./mvnw package -DskipTests && \ + mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar + +################################################################################ + +# Create a stage for extracting the application into separate layers. +# Take advantage of Spring Boot's layer tools and Docker's caching by extracting +# the packaged application into separate layers that can be copied into the final stage. +# See Spring's docs for reference: +# https://docs.spring.io/spring-boot/docs/current/reference/html/container-images.html +FROM package as extract + +WORKDIR /build + +RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted + +################################################################################ + +# Create a new stage for running the application that contains the minimal +# runtime dependencies for the application. This often uses a different base +# image from the install or build stage where the necessary files are copied +# from the install stage. +# +# The example below uses eclipse-turmin's JRE image as the foundation for running the app. +# By specifying the "17-jre-jammy" tag, it will also use whatever happens to be the +# most recent version of that tag when you build your Dockerfile. +# If reproducibility is important, consider using a specific digest SHA, like +# eclipse-temurin@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4. +FROM eclipse-temurin:21-jre-jammy AS final + +# Create a non-privileged user that the app will run under. +# See https://docs.docker.com/go/dockerfile-user-best-practices/ +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser + +# Copy the executable from the "package" stage. +COPY --from=extract build/target/extracted/dependencies/ ./ +COPY --from=extract build/target/extracted/spring-boot-loader/ ./ +COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ +COPY --from=extract build/target/extracted/application/ ./ + +EXPOSE 8080 + +ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ] +``` + +> [!NOTE] +> The sample repository includes a `docker-compose.yml` file. The following instructions use the preferred `compose.yaml` filename — both are supported by Docker Compose. + +Create a file named `compose.yaml` with the following contents. + +```yaml {collapse=true,title=compose.yaml} +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + ports: + - 8080:8080 +# The commented out section below is an example of how to define a PostgreSQL +# database that your application can use. `depends_on` tells Docker Compose to +# start the database before your application. The `db-data` volume persists the +# database data between container restarts. The `db-password` secret is used +# to set the database password. You must create `db/password.txt` and add +# a password of your choosing to it before running `docker compose up`. +# depends_on: +# db: +# condition: service_healthy +# db: +# image: postgres:18 +# restart: always +# user: postgres +# secrets: +# - db-password +# volumes: +# - db-data:/var/lib/postgresql +# environment: +# - POSTGRES_DB=example +# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password +# expose: +# - 5432 +# healthcheck: +# test: [ "CMD", "pg_isready" ] +# interval: 10s +# timeout: 5s +# retries: 5 +# volumes: +# db-data: +# secrets: +# db-password: +# file: db/password.txt +``` + +Create a file named `.dockerignore` with the following contents. + +```text {collapse=true,title=".dockerignore"} +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/.next +**/.cache +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/charts +**/docker-compose* +**/compose.y*ml +**/target +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +**/vendor +LICENSE +README.md +``` + +You should now have the following three files in your `spring-petclinic` +directory. + +- [Dockerfile](/reference/dockerfile/) +- [.dockerignore](/reference/dockerfile/#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `spring-petclinic` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +The first time you build and run the app, Docker downloads dependencies and builds the app. It may take several minutes depending on your network connection. + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `spring-petclinic` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the +[Compose CLI reference](/reference/cli/docker/compose/). + +## Use containers for Java development + +### Prerequisites + +Work through the steps to containerize your application in [Containerize your app](#containerize-a-java-application). + +### Overview + +In this section, you’ll walk through setting up a local development environment +for the application you containerized in the previous section. This includes: + +- Adding a local database and persisting data +- Creating a development container to connect a debugger +- Configuring Compose to automatically update your running Compose services as + you edit and save your code + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this section, you'll update the `docker-compose.yaml` file to define a database service and a volume to persist data. Also, this particular application uses a system property to define the database type, so you'll need to update the `Dockerfile` to pass in the system property when starting the app. + +In the cloned repository's directory, open the `docker-compose.yaml` file in an IDE or text editor. Your Compose file has an example database service, but it'll require a few changes for your unique app. + +In the `docker-compose.yaml` file, you need to do the following: + +- Uncomment all of the database instructions. You'll now use a database service + instead of local storage for the data. +- Remove the top-level `secrets` element as well as the element inside the `db` + service. This example uses the environment variable for the password rather than secrets. +- Remove the `user` element from the `db` service. This example specifies the + user in the environment variable. +- Update the database environment variables. These are defined by the Postgres + image. For more details, see the + [Postgres Official Docker Image](https://hub.docker.com/_/postgres). +- Update the healthcheck test for the `db` service and specify the user. By + default, the healthcheck uses the root user instead of the `petclinic` user + you defined. +- Add the database URL as an environment variable in the `server` service. This + overrides the default value defined in + `spring-petclinic/src/main/resources/application-postgres.properties`. + +The following is the updated `docker-compose.yaml` file. All comments have been removed. + +```yaml {hl_lines="7-29"} +services: + server: + build: + context: . + ports: + - 8080:8080 + depends_on: + db: + condition: service_healthy + environment: + - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic + db: + image: postgres:18 + restart: always + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=petclinic + - POSTGRES_USER=petclinic + - POSTGRES_PASSWORD=petclinic + ports: + - 5432:5432 + healthcheck: + test: ["CMD", "pg_isready", "-U", "petclinic"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +``` + +Open the `Dockerfile` in an IDE or text editor. In the `ENTRYPOINT` instruction, +update the instruction to pass in the system property as specified in the +`spring-petclinic/src/resources/db/postgres/petclinic_db_setup_postgres.txt` +file. + +```diff +- ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ] ++ ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] +``` + +Save and close all the files. + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. Browse around the application. Navigate to **Veterinarians** and verify that the application is connected to the database by being able to list veterinarians. + +In the terminal, press `ctrl`+`c` to stop the application. + +### Dockerfile for development + +The Dockerfile you have now is great for a small, secure production image with +only the components necessary to run the application. When developing, you may +want a different image that has a different environment. + +For example, in the development image you may want to set up the image to start +the application so that you can connect a debugger to the running Java process. + +Rather than managing multiple Dockerfiles, you can add a new stage. Your +Dockerfile can then produce a final image which is ready for production as well +as a development image. + +Replace the contents of your Dockerfile with the following. + +```dockerfile {hl_lines="22-29"} +# syntax=docker/dockerfile:1 + +FROM eclipse-temurin:21-jdk-jammy as deps +WORKDIR /build +COPY --chmod=0755 mvnw mvnw +COPY .mvn/ .mvn/ +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests + +FROM deps as package +WORKDIR /build +COPY ./src src/ +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 \ + ./mvnw package -DskipTests && \ + mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar + +FROM package as extract +WORKDIR /build +RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted + +FROM extract as development +WORKDIR /build +RUN cp -r /build/target/extracted/dependencies/. ./ +RUN cp -r /build/target/extracted/spring-boot-loader/. ./ +RUN cp -r /build/target/extracted/snapshot-dependencies/. ./ +RUN cp -r /build/target/extracted/application/. ./ +ENV JAVA_TOOL_OPTIONS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000 +CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] + +FROM eclipse-temurin:21-jre-jammy AS final +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +COPY --from=extract build/target/extracted/dependencies/ ./ +COPY --from=extract build/target/extracted/spring-boot-loader/ ./ +COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ +COPY --from=extract build/target/extracted/application/ ./ +EXPOSE 8080 +ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] +``` + +Save and close the `Dockerfile`. + +In the `Dockerfile` you added a new stage labeled `development` based on the `extract` stage. In this stage, you copy the extracted files to a common directory, then run a command to start the application. In the command, you expose port 8000 and declare the debug configuration for the JVM so that you can attach a debugger. + +### Use Compose to develop locally + +The current Compose file doesn't start your development container. To do that, you must update your Compose file to target the development stage. Also, update the port mapping of the server service to provide access for the debugger. + +Open the `docker-compose.yaml` and add the following instructions into the file. + +```yaml {hl_lines=["5","8"]} +services: + server: + build: + context: . + target: development + ports: + - 8080:8080 + - 8000:8000 + depends_on: + db: + condition: service_healthy + environment: + - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic + db: + image: postgres:18 + restart: always + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=petclinic + - POSTGRES_USER=petclinic + - POSTGRES_PASSWORD=petclinic + ports: + - 5432:5432 + healthcheck: + test: ["CMD", "pg_isready", "-U", "petclinic"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +``` + +Now, start your application and to confirm that it's running. + +```console +$ docker compose up --build +``` + +Finally, test your API endpoint. Run the following curl command: + +```console +$ curl --request GET \ + --url http://localhost:8080/vets \ + --header 'content-type: application/json' +``` + +You should receive the following response: + +```json +{ + "vetList": [ + { + "id": 1, + "firstName": "James", + "lastName": "Carter", + "specialties": [], + "nrOfSpecialties": 0, + "new": false + }, + { + "id": 2, + "firstName": "Helen", + "lastName": "Leary", + "specialties": [{ "id": 1, "name": "radiology", "new": false }], + "nrOfSpecialties": 1, + "new": false + }, + { + "id": 3, + "firstName": "Linda", + "lastName": "Douglas", + "specialties": [ + { "id": 3, "name": "dentistry", "new": false }, + { "id": 2, "name": "surgery", "new": false } + ], + "nrOfSpecialties": 2, + "new": false + }, + { + "id": 4, + "firstName": "Rafael", + "lastName": "Ortega", + "specialties": [{ "id": 2, "name": "surgery", "new": false }], + "nrOfSpecialties": 1, + "new": false + }, + { + "id": 5, + "firstName": "Henry", + "lastName": "Stevens", + "specialties": [{ "id": 1, "name": "radiology", "new": false }], + "nrOfSpecialties": 1, + "new": false + }, + { + "id": 6, + "firstName": "Sharon", + "lastName": "Jenkins", + "specialties": [], + "nrOfSpecialties": 0, + "new": false + } + ] +} +``` + +### Connect a Debugger + +You’ll use the debugger that comes with the IntelliJ IDEA. You can use the community version of this IDE. Open your project in IntelliJ IDEA, go to the **Run** menu, and then **Edit Configuration**. Add a new Remote JVM Debug configuration similar to the following: + +![Java Connect a Debugger](images/java-connect-debugger.webp) + +Set a breakpoint. + +Open `src/main/java/org/springframework/samples/petclinic/vet/VetController.java` and add a breakpoint inside the `showResourcesVetList` function. + +To start your debug session, select the **Run** menu and then **Debug _NameOfYourConfiguration_**. + +![Debug menu](images/java-debug-menu.webp?w=300) + +You should now see the connection in the logs of your Compose application. + +![Compose log file](images/java-compose-logs.webp) + +You can now call the server endpoint. + +```console +$ curl --request GET --url http://localhost:8080/vets +``` + +You should have seen the code break on the marked line and now you are able to use the debugger just like you would normally. You can also inspect and watch variables, set conditional breakpoints, view stack traces and a do bunch of other stuff. + +![Debugger code breakpoint](images/java-debugger-breakpoint.webp) + +Press `ctrl+c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see +[Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `docker-compose.yaml` file in an IDE or text editor and then add the +Compose Watch instructions. The following is the updated `docker-compose.yaml` +file. + +```yaml {hl_lines="14-17"} +services: + server: + build: + context: . + target: development + ports: + - 8080:8080 + - 8000:8000 + depends_on: + db: + condition: service_healthy + environment: + - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic + develop: + watch: + - action: rebuild + path: . + db: + image: postgres:18 + restart: always + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=petclinic + - POSTGRES_USER=petclinic + - POSTGRES_PASSWORD=petclinic + ports: + - 5432:5432 + healthcheck: + test: ["CMD", "pg_isready", "-U", "petclinic"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Open a web browser and view the application at [http://localhost:8080](http://localhost:8080). You should see the Spring Pet Clinic home page. + +Any changes to the application's source files on your local machine will now be automatically reflected in the running container. + +Open `spring-petclinic/src/main/resources/templates/fragments/layout.html` in an IDE or text editor and update the `Home` navigation string by adding an exclamation mark. + +```diff +- <li th:replace="~{::menuItem ('/','home','home page','home','Home')}"> ++ <li th:replace="~{::menuItem ('/','home','home page','home','Home!')}"> + +``` + +Save the changes to `layout.html` and then you can continue developing while the container automatically rebuilds. + +After the container is rebuilt and running, refresh [http://localhost:8080](http://localhost:8080) and then verify that **Home!** now appears in the menu. + +Press `ctrl+c` in the terminal to stop Compose Watch. + +## Run your Java tests + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize a Java application](#containerize-a-java-application). + +### Overview + +Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you'll take a look at running your unit tests in Docker. + +#### Multi-stage Dockerfile for testing + +In the following example, you'll pull the testing commands into your Dockerfile. +Replace the contents of your Dockerfile with the following. + +```dockerfile {hl_lines="3-19"} +# syntax=docker/dockerfile:1 + +FROM eclipse-temurin:21-jdk-jammy as base +WORKDIR /build +COPY --chmod=0755 mvnw mvnw +COPY .mvn/ .mvn/ + +FROM base as test +WORKDIR /build +COPY ./src src/ +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 \ + ./mvnw test + +FROM base as deps +WORKDIR /build +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 \ + ./mvnw dependency:go-offline -DskipTests + +FROM deps as package +WORKDIR /build +COPY ./src src/ +RUN --mount=type=bind,source=pom.xml,target=pom.xml \ + --mount=type=cache,target=/root/.m2 \ + ./mvnw package -DskipTests && \ + mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar + +FROM package as extract +WORKDIR /build +RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted + +FROM extract as development +WORKDIR /build +RUN cp -r /build/target/extracted/dependencies/. ./ +RUN cp -r /build/target/extracted/spring-boot-loader/. ./ +RUN cp -r /build/target/extracted/snapshot-dependencies/. ./ +RUN cp -r /build/target/extracted/application/. ./ +ENV JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000" +CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] + +FROM eclipse-temurin:21-jre-jammy AS final +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +COPY --from=extract build/target/extracted/dependencies/ ./ +COPY --from=extract build/target/extracted/spring-boot-loader/ ./ +COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ +COPY --from=extract build/target/extracted/application/ ./ +EXPOSE 8080 +ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] +``` + +First, you added a new base stage. In the base stage, you added common instructions that both the test and deps stage will need. + +Next, you added a new test stage labeled `test` based on the base stage. In this +stage you copied in the necessary source files and then specified `RUN` to run +`./mvnw test`. Instead of using `CMD`, you used `RUN` to run the tests. The +reason is that the `CMD` instruction runs when the container runs, and the `RUN` +instruction runs when the image is being built. When using `RUN`, the build will +fail if the tests fail. + +Finally, you updated the deps stage to be based on the base stage and removed +the instructions that are now in the base stage. + +Run the following command to build a new image using the test stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage. + +Now, build your image and run your tests. You'll run the `docker build` command and add the `--target test` flag so that you specifically run the test build stage. + +```console +$ docker build -t java-docker-image-test --progress=plain --no-cache --target=test . +``` + +You should see output containing the following + +```console +... + +#15 101.3 [WARNING] Tests run: 45, Failures: 0, Errors: 0, Skipped: 2 +#15 101.3 [INFO] +#15 101.3 [INFO] ------------------------------------------------------------------------ +#15 101.3 [INFO] BUILD SUCCESS +#15 101.3 [INFO] ------------------------------------------------------------------------ +#15 101.3 [INFO] Total time: 01:39 min +#15 101.3 [INFO] Finished at: 2024-02-01T23:24:48Z +#15 101.3 [INFO] ------------------------------------------------------------------------ +#15 DONE 101.4s +``` diff --git a/content/guides/java/_index.md b/content/guides/java/_index.md deleted file mode 100644 index b605ffd48457..000000000000 --- a/content/guides/java/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Java language-specific guide -linkTitle: Java -keywords: java, getting started -description: Containerize Java apps using Docker -summary: | - This guide demonstrates how to containerize Java applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/java/ - - /guides/language/java/ -languages: [java] -params: - time: 20 minutes ---- - -The Java getting started guide teaches you how to create a containerized Spring Boot application using Docker. In this module, you’ll learn how to: - -- Containerize and run a Spring Boot application with Maven -- Set up a local development environment to connect a database to the container, configure a debugger, and use Compose Watch for live reload -- Run your unit tests inside a container -- Configure a CI/CD pipeline for your application using GitHub Actions -- Deploy your containerized application locally to Kubernetes to test and debug your deployment - -After completing the Java getting started modules, you should be able to containerize your own Java application based on the examples and instructions provided in this guide. - -Get started containerizing your first Java app. diff --git a/content/guides/java/configure-ci-cd.md b/content/guides/java/configure-ci-cd.md deleted file mode 100644 index ee6c0cd41bf7..000000000000 --- a/content/guides/java/configure-ci-cd.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Configure CI/CD for your Java application -linkTitle: Configure CI/CD -weight: 40 -keywords: java, CI/CD, local, development -description: Learn how to Configure CI/CD for your Java application -aliases: - - /language/java/configure-ci-cd/ - - /guides/language/java/configure-ci-cd/ ---- - -## Prerequisites - -Complete the previous sections of this guide, starting with [Containerize your app](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and push your Docker image to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - The project already has the `maven-build` workflow to build and test your Java application with Maven. If you want, you can optionally disable this workflow because you won't use it in this guide. You'll create a new, alternate workflow to build, test, and push your image. - -2. Select **New workflow**. - -3. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -4. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and test - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - target: test - load: true - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - target: final - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/java/containerize.md b/content/guides/java/containerize.md deleted file mode 100644 index 83f6fd4e938c..000000000000 --- a/content/guides/java/containerize.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -title: Containerize a Java application -linkTitle: Containerize your app -weight: 10 -keywords: java, containerize, initialize, maven, build -description: Learn how to containerize a Java application. -aliases: - - /language/java/build-images/ - - /language/java/run-containers/ - - /language/java/containerize/ - - /guides/language/java/containerize/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). - Docker adds new features regularly and some parts of this guide may - work only with the latest version of Docker Desktop. - -* You have a [Git client](https://git-scm.com/downloads). The examples in this - section use a command-line based Git client, but you can use any client. - -## Overview - -This section walks you through containerizing and running a Java -application. - -## Get the sample applications - -Clone the sample application that you'll be using to your local development machine. Run the following command in a terminal to clone the repository. - -```console -$ git clone https://github.com/spring-projects/spring-petclinic.git -``` - -The sample application is a Spring Boot application built using Maven. For more details, see `readme.md` in the repository. - -## Create Docker assets - -Now that you have an application, you can create the necessary Docker assets to -containerize your application. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -Create a file named `Dockerfile` with the following contents. - -```dockerfile {collapse=true,title=Dockerfile} -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -################################################################################ - -# Create a stage for resolving and downloading dependencies. -FROM eclipse-temurin:21-jdk-jammy as deps - -WORKDIR /build - -# Copy the mvnw wrapper with executable permissions. -COPY --chmod=0755 mvnw mvnw -COPY .mvn/ .mvn/ - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.m2 so that subsequent builds don't have to -# re-download packages. -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests - -################################################################################ - -# Create a stage for building the application based on the stage with downloaded dependencies. -# This Dockerfile is optimized for Java applications that output an uber jar, which includes -# all the dependencies needed to run your app inside a JVM. If your app doesn't output an uber -# jar and instead relies on an application server like Apache Tomcat, you'll need to update this -# stage with the correct filename of your package and update the base image of the "final" stage -# use the relevant app server, e.g., using tomcat (https://hub.docker.com/_/tomcat/) as a base image. -FROM deps as package - -WORKDIR /build - -COPY ./src src/ -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 \ - ./mvnw package -DskipTests && \ - mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar - -################################################################################ - -# Create a stage for extracting the application into separate layers. -# Take advantage of Spring Boot's layer tools and Docker's caching by extracting -# the packaged application into separate layers that can be copied into the final stage. -# See Spring's docs for reference: -# https://docs.spring.io/spring-boot/docs/current/reference/html/container-images.html -FROM package as extract - -WORKDIR /build - -RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted - -################################################################################ - -# Create a new stage for running the application that contains the minimal -# runtime dependencies for the application. This often uses a different base -# image from the install or build stage where the necessary files are copied -# from the install stage. -# -# The example below uses eclipse-turmin's JRE image as the foundation for running the app. -# By specifying the "17-jre-jammy" tag, it will also use whatever happens to be the -# most recent version of that tag when you build your Dockerfile. -# If reproducibility is important, consider using a specific digest SHA, like -# eclipse-temurin@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4. -FROM eclipse-temurin:21-jre-jammy AS final - -# Create a non-privileged user that the app will run under. -# See https://docs.docker.com/go/dockerfile-user-best-practices/ -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser - -# Copy the executable from the "package" stage. -COPY --from=extract build/target/extracted/dependencies/ ./ -COPY --from=extract build/target/extracted/spring-boot-loader/ ./ -COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ -COPY --from=extract build/target/extracted/application/ ./ - -EXPOSE 8080 - -ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ] -``` - -> [!NOTE] -> The sample repository includes a `docker-compose.yml` file. The following instructions use the preferred `compose.yaml` filename — both are supported by Docker Compose. - -Create a file named `compose.yaml` with the following contents. - -```yaml {collapse=true,title=compose.yaml} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - ports: - - 8080:8080 -# The commented out section below is an example of how to define a PostgreSQL -# database that your application can use. `depends_on` tells Docker Compose to -# start the database before your application. The `db-data` volume persists the -# database data between container restarts. The `db-password` secret is used -# to set the database password. You must create `db/password.txt` and add -# a password of your choosing to it before running `docker compose up`. -# depends_on: -# db: -# condition: service_healthy -# db: -# image: postgres:18 -# restart: always -# user: postgres -# secrets: -# - db-password -# volumes: -# - db-data:/var/lib/postgresql -# environment: -# - POSTGRES_DB=example -# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password -# expose: -# - 5432 -# healthcheck: -# test: [ "CMD", "pg_isready" ] -# interval: 10s -# timeout: 5s -# retries: 5 -# volumes: -# db-data: -# secrets: -# db-password: -# file: db/password.txt - -``` - -Create a file named `.dockerignore` with the following contents. - -```text {collapse=true,title=".dockerignore"} -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/.next -**/.cache -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/charts -**/docker-compose* -**/compose.y*ml -**/target -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -**/vendor -LICENSE -README.md -``` - -You should now have the following three files in your `spring-petclinic` -directory. - -- [Dockerfile](/reference/dockerfile/) -- [.dockerignore](/reference/dockerfile/#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `spring-petclinic` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -The first time you build and run the app, Docker downloads dependencies and builds the app. It may take several minutes depending on your network connection. - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `spring-petclinic` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the -[Compose CLI reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run a Java -application using Docker. - -## Next steps - -In the next section, you'll learn how you can develop your application using -Docker containers. diff --git a/content/guides/java/deploy.md b/content/guides/java/deploy.md deleted file mode 100644 index 663fe4fd71ca..000000000000 --- a/content/guides/java/deploy.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Test your Java deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, java -description: Learn how to develop locally using Kubernetes -aliases: - - /language/java/deploy/ - - /guides/language/java/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize your app](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your -application to a fully-featured Kubernetes environment on your development -machine. This lets you test and debug your workloads on Kubernetes locally -before deploying. - -## Create a Kubernetes YAML file - -In your `spring-petclinic` directory, create a file named -`docker-java-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Java application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-java-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: server - template: - metadata: - labels: - service: server - spec: - containers: - - name: server-service - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - service: server - ports: - - port: 8080 - targetPort: 8080 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your Java application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 8080 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `spring-petclinic` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-java-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```shell - deployment.apps/docker-java-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-java-demo 1/1 1 1 15s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 23h - service-entrypoint NodePort 10.99.128.230 <none> 8080:30001/TCP 75s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a terminal, curl the service. Note that a database wasn't deployed in - this example. - - ```console - $ curl --request GET \ - --url http://localhost:30001/actuator/health \ - --header 'content-type: application/json' - ``` - - You should get output like the following. - - ```console - {"status":"UP","groups":["liveness","readiness"]} - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-java-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/java/develop.md b/content/guides/java/develop.md deleted file mode 100644 index fd4a62a19b03..000000000000 --- a/content/guides/java/develop.md +++ /dev/null @@ -1,403 +0,0 @@ ---- -title: Use containers for Java development -linkTitle: Develop your app -weight: 20 -keywords: Java, local, development, run, -description: Learn how to develop your application locally. -aliases: - - /language/java/develop/ - - /guides/language/java/develop/ ---- - -## Prerequisites - -Work through the steps to containerize your application in [Containerize your app](containerize.md). - -## Overview - -In this section, you’ll walk through setting up a local development environment -for the application you containerized in the previous section. This includes: - -- Adding a local database and persisting data -- Creating a development container to connect a debugger -- Configuring Compose to automatically update your running Compose services as - you edit and save your code - -## Add a local database and persist data - -You can use containers to set up local services, like a database. In this section, you'll update the `docker-compose.yaml` file to define a database service and a volume to persist data. Also, this particular application uses a system property to define the database type, so you'll need to update the `Dockerfile` to pass in the system property when starting the app. - -In the cloned repository's directory, open the `docker-compose.yaml` file in an IDE or text editor. Your Compose file has an example database service, but it'll require a few changes for your unique app. - -In the `docker-compose.yaml` file, you need to do the following: - -- Uncomment all of the database instructions. You'll now use a database service - instead of local storage for the data. -- Remove the top-level `secrets` element as well as the element inside the `db` - service. This example uses the environment variable for the password rather than secrets. -- Remove the `user` element from the `db` service. This example specifies the - user in the environment variable. -- Update the database environment variables. These are defined by the Postgres - image. For more details, see the - [Postgres Official Docker Image](https://hub.docker.com/_/postgres). -- Update the healthcheck test for the `db` service and specify the user. By - default, the healthcheck uses the root user instead of the `petclinic` user - you defined. -- Add the database URL as an environment variable in the `server` service. This - overrides the default value defined in - `spring-petclinic/src/main/resources/application-postgres.properties`. - -The following is the updated `docker-compose.yaml` file. All comments have been removed. - -```yaml {hl_lines="7-29"} -services: - server: - build: - context: . - ports: - - 8080:8080 - depends_on: - db: - condition: service_healthy - environment: - - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic - db: - image: postgres:18 - restart: always - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=petclinic - - POSTGRES_USER=petclinic - - POSTGRES_PASSWORD=petclinic - ports: - - 5432:5432 - healthcheck: - test: ["CMD", "pg_isready", "-U", "petclinic"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -``` - -Open the `Dockerfile` in an IDE or text editor. In the `ENTRYPOINT` instruction, -update the instruction to pass in the system property as specified in the -`spring-petclinic/src/resources/db/postgres/petclinic_db_setup_postgres.txt` -file. - -```diff -- ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ] -+ ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] -``` - -Save and close all the files. - -Now, run the following `docker compose up` command to start your application. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple app for a pet clinic. Browse around the application. Navigate to **Veterinarians** and verify that the application is connected to the database by being able to list veterinarians. - -In the terminal, press `ctrl`+`c` to stop the application. - -## Dockerfile for development - -The Dockerfile you have now is great for a small, secure production image with -only the components necessary to run the application. When developing, you may -want a different image that has a different environment. - -For example, in the development image you may want to set up the image to start -the application so that you can connect a debugger to the running Java process. - -Rather than managing multiple Dockerfiles, you can add a new stage. Your -Dockerfile can then produce a final image which is ready for production as well -as a development image. - -Replace the contents of your Dockerfile with the following. - -```dockerfile {hl_lines="22-29"} -# syntax=docker/dockerfile:1 - -FROM eclipse-temurin:21-jdk-jammy as deps -WORKDIR /build -COPY --chmod=0755 mvnw mvnw -COPY .mvn/ .mvn/ -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests - -FROM deps as package -WORKDIR /build -COPY ./src src/ -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 \ - ./mvnw package -DskipTests && \ - mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar - -FROM package as extract -WORKDIR /build -RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted - -FROM extract as development -WORKDIR /build -RUN cp -r /build/target/extracted/dependencies/. ./ -RUN cp -r /build/target/extracted/spring-boot-loader/. ./ -RUN cp -r /build/target/extracted/snapshot-dependencies/. ./ -RUN cp -r /build/target/extracted/application/. ./ -ENV JAVA_TOOL_OPTIONS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000 -CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] - -FROM eclipse-temurin:21-jre-jammy AS final -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser -COPY --from=extract build/target/extracted/dependencies/ ./ -COPY --from=extract build/target/extracted/spring-boot-loader/ ./ -COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ -COPY --from=extract build/target/extracted/application/ ./ -EXPOSE 8080 -ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] -``` - -Save and close the `Dockerfile`. - -In the `Dockerfile` you added a new stage labeled `development` based on the `extract` stage. In this stage, you copy the extracted files to a common directory, then run a command to start the application. In the command, you expose port 8000 and declare the debug configuration for the JVM so that you can attach a debugger. - -## Use Compose to develop locally - -The current Compose file doesn't start your development container. To do that, you must update your Compose file to target the development stage. Also, update the port mapping of the server service to provide access for the debugger. - -Open the `docker-compose.yaml` and add the following instructions into the file. - -```yaml {hl_lines=["5","8"]} -services: - server: - build: - context: . - target: development - ports: - - 8080:8080 - - 8000:8000 - depends_on: - db: - condition: service_healthy - environment: - - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic - db: - image: postgres:18 - restart: always - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=petclinic - - POSTGRES_USER=petclinic - - POSTGRES_PASSWORD=petclinic - ports: - - 5432:5432 - healthcheck: - test: ["CMD", "pg_isready", "-U", "petclinic"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -``` - -Now, start your application and to confirm that it's running. - -```console -$ docker compose up --build -``` - -Finally, test your API endpoint. Run the following curl command: - -```console -$ curl --request GET \ - --url http://localhost:8080/vets \ - --header 'content-type: application/json' -``` - -You should receive the following response: - -```json -{ - "vetList": [ - { - "id": 1, - "firstName": "James", - "lastName": "Carter", - "specialties": [], - "nrOfSpecialties": 0, - "new": false - }, - { - "id": 2, - "firstName": "Helen", - "lastName": "Leary", - "specialties": [{ "id": 1, "name": "radiology", "new": false }], - "nrOfSpecialties": 1, - "new": false - }, - { - "id": 3, - "firstName": "Linda", - "lastName": "Douglas", - "specialties": [ - { "id": 3, "name": "dentistry", "new": false }, - { "id": 2, "name": "surgery", "new": false } - ], - "nrOfSpecialties": 2, - "new": false - }, - { - "id": 4, - "firstName": "Rafael", - "lastName": "Ortega", - "specialties": [{ "id": 2, "name": "surgery", "new": false }], - "nrOfSpecialties": 1, - "new": false - }, - { - "id": 5, - "firstName": "Henry", - "lastName": "Stevens", - "specialties": [{ "id": 1, "name": "radiology", "new": false }], - "nrOfSpecialties": 1, - "new": false - }, - { - "id": 6, - "firstName": "Sharon", - "lastName": "Jenkins", - "specialties": [], - "nrOfSpecialties": 0, - "new": false - } - ] -} -``` - -## Connect a Debugger - -You’ll use the debugger that comes with the IntelliJ IDEA. You can use the community version of this IDE. Open your project in IntelliJ IDEA, go to the **Run** menu, and then **Edit Configuration**. Add a new Remote JVM Debug configuration similar to the following: - -![Java Connect a Debugger](images/connect-debugger.webp) - -Set a breakpoint. - -Open `src/main/java/org/springframework/samples/petclinic/vet/VetController.java` and add a breakpoint inside the `showResourcesVetList` function. - -To start your debug session, select the **Run** menu and then **Debug _NameOfYourConfiguration_**. - -![Debug menu](images/debug-menu.webp?w=300) - -You should now see the connection in the logs of your Compose application. - -![Compose log file ](images/compose-logs.webp) - -You can now call the server endpoint. - -```console -$ curl --request GET --url http://localhost:8080/vets -``` - -You should have seen the code break on the marked line and now you are able to use the debugger just like you would normally. You can also inspect and watch variables, set conditional breakpoints, view stack traces and a do bunch of other stuff. - -![Debugger code breakpoint](images/debugger-breakpoint.webp) - -Press `ctrl+c` in the terminal to stop your application. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see -[Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `docker-compose.yaml` file in an IDE or text editor and then add the -Compose Watch instructions. The following is the updated `docker-compose.yaml` -file. - -```yaml {hl_lines="14-17"} -services: - server: - build: - context: . - target: development - ports: - - 8080:8080 - - 8000:8000 - depends_on: - db: - condition: service_healthy - environment: - - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic - develop: - watch: - - action: rebuild - path: . - db: - image: postgres:18 - restart: always - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=petclinic - - POSTGRES_USER=petclinic - - POSTGRES_PASSWORD=petclinic - ports: - - 5432:5432 - healthcheck: - test: ["CMD", "pg_isready", "-U", "petclinic"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Open a web browser and view the application at [http://localhost:8080](http://localhost:8080). You should see the Spring Pet Clinic home page. - -Any changes to the application's source files on your local machine will now be automatically reflected in the running container. - -Open `spring-petclinic/src/main/resources/templates/fragments/layout.html` in an IDE or text editor and update the `Home` navigation string by adding an exclamation mark. - -```diff -- <li th:replace="~{::menuItem ('/','home','home page','home','Home')}"> -+ <li th:replace="~{::menuItem ('/','home','home page','home','Home!')}"> - -``` - -Save the changes to `layout.html` and then you can continue developing while the container automatically rebuilds. - -After the container is rebuilt and running, refresh [http://localhost:8080](http://localhost:8080) and then verify that **Home!** now appears in the menu. - -Press `ctrl+c` in the terminal to stop Compose Watch. - -## Summary - -In this section, you took a look at running a database locally and persisting the data. You also created a development image that contains the JDK and lets you attach a debugger. Finally, you set up your Compose file to expose the debugging port and configured Compose Watch to live reload your changes. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose Watch](/manuals/compose/how-tos/file-watch.md) -- [Dockerfile reference](/reference/dockerfile/) - -## Next steps - -In the next section, you’ll take a look at how to run unit tests in Docker. diff --git a/content/guides/java/run-tests.md b/content/guides/java/run-tests.md deleted file mode 100644 index c88025ad82b6..000000000000 --- a/content/guides/java/run-tests.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Run your Java tests -linkTitle: Run your tests -weight: 30 -keywords: Java, build, test -description: How to build and run your Java tests -aliases: - - /language/java/run-tests/ - - /guides/language/java/run-tests/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Java application](containerize.md). - -## Overview - -Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you'll take a look at running your unit tests in Docker. - -### Multi-stage Dockerfile for testing - -In the following example, you'll pull the testing commands into your Dockerfile. -Replace the contents of your Dockerfile with the following. - -```dockerfile {hl_lines="3-19"} -# syntax=docker/dockerfile:1 - -FROM eclipse-temurin:21-jdk-jammy as base -WORKDIR /build -COPY --chmod=0755 mvnw mvnw -COPY .mvn/ .mvn/ - -FROM base as test -WORKDIR /build -COPY ./src src/ -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 \ - ./mvnw test - -FROM base as deps -WORKDIR /build -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 \ - ./mvnw dependency:go-offline -DskipTests - -FROM deps as package -WORKDIR /build -COPY ./src src/ -RUN --mount=type=bind,source=pom.xml,target=pom.xml \ - --mount=type=cache,target=/root/.m2 \ - ./mvnw package -DskipTests && \ - mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar - -FROM package as extract -WORKDIR /build -RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted - -FROM extract as development -WORKDIR /build -RUN cp -r /build/target/extracted/dependencies/. ./ -RUN cp -r /build/target/extracted/spring-boot-loader/. ./ -RUN cp -r /build/target/extracted/snapshot-dependencies/. ./ -RUN cp -r /build/target/extracted/application/. ./ -ENV JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000" -CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] - -FROM eclipse-temurin:21-jre-jammy AS final -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser -USER appuser -COPY --from=extract build/target/extracted/dependencies/ ./ -COPY --from=extract build/target/extracted/spring-boot-loader/ ./ -COPY --from=extract build/target/extracted/snapshot-dependencies/ ./ -COPY --from=extract build/target/extracted/application/ ./ -EXPOSE 8080 -ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ] -``` - -First, you added a new base stage. In the base stage, you added common instructions that both the test and deps stage will need. - -Next, you added a new test stage labeled `test` based on the base stage. In this -stage you copied in the necessary source files and then specified `RUN` to run -`./mvnw test`. Instead of using `CMD`, you used `RUN` to run the tests. The -reason is that the `CMD` instruction runs when the container runs, and the `RUN` -instruction runs when the image is being built. When using `RUN`, the build will -fail if the tests fail. - -Finally, you updated the deps stage to be based on the base stage and removed -the instructions that are now in the base stage. - -Run the following command to build a new image using the test stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage. - -Now, build your image and run your tests. You'll run the `docker build` command and add the `--target test` flag so that you specifically run the test build stage. - -```console -$ docker build -t java-docker-image-test --progress=plain --no-cache --target=test . -``` - -You should see output containing the following - -```console -... - -#15 101.3 [WARNING] Tests run: 45, Failures: 0, Errors: 0, Skipped: 2 -#15 101.3 [INFO] -#15 101.3 [INFO] ------------------------------------------------------------------------ -#15 101.3 [INFO] BUILD SUCCESS -#15 101.3 [INFO] ------------------------------------------------------------------------ -#15 101.3 [INFO] Total time: 01:39 min -#15 101.3 [INFO] Finished at: 2024-02-01T23:24:48Z -#15 101.3 [INFO] ------------------------------------------------------------------------ -#15 DONE 101.4s -``` - -## Next steps - -In the next section, you’ll take a look at how to set up a CI/CD pipeline using -GitHub Actions. diff --git a/content/guides/jupyter.md b/content/guides/jupyter.md index b5620cba0aa3..699f2186a6d2 100644 --- a/content/guides/jupyter.md +++ b/content/guides/jupyter.md @@ -5,11 +5,10 @@ title: Data science with JupyterLab toc_max: 2 summary: | Use Docker to run Jupyter notebooks. -tags: [data-science] -languages: [python] aliases: - /guides/use-case/jupyter/ params: + tags: [ai] time: 20 minutes --- diff --git a/content/guides/kafka.md b/content/guides/kafka.md index 78153a04f7ed..17b3dee95e2e 100644 --- a/content/guides/kafka.md +++ b/content/guides/kafka.md @@ -5,11 +5,10 @@ title: Developing event-driven applications with Kafka and Docker linktitle: Event-driven apps with Kafka summary: | This guide explains how to run Apache Kafka in Docker containers. -tags: [distributed-systems] -languages: [js] aliases: - /guides/use-case/kafka/ params: + tags: [deployment] time: 20 minutes --- diff --git a/content/guides/kube-deploy.md b/content/guides/kube-deploy.md deleted file mode 100644 index c4b535385365..000000000000 --- a/content/guides/kube-deploy.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Deploy to Kubernetes -keywords: kubernetes, pods, deployments, kubernetes services -description: Learn how to describe and deploy a simple application on Kubernetes. -aliases: - - /get-started/kube-deploy/ - - /guides/deployment-orchestration/kube-deploy/ -summary: | - Learn how to deploy and orchestrate Docker containers using Kubernetes. -tags: [deploy] -params: - time: 10 minutes ---- - -## Prerequisites - -- Download and install Docker Desktop as described in [Get Docker](/get-started/get-docker.md). -- Work through containerizing an application in [Part 2](02_our_app.md). -- Make sure that Kubernetes is turned on in Docker Desktop: - If Kubernetes isn't running, follow the instructions in [Orchestration](orchestration.md) to finish setting it up. - -## Introduction - -Now that you've demonstrated that the individual components of your application run as stand-alone containers, it's time to arrange for them to be managed by an orchestrator like Kubernetes. Kubernetes provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves. - -In order to validate that your containerized application works well on Kubernetes, you'll use Docker Desktop's built in Kubernetes environment right on your development machine to deploy your application, before handing it off to run on a full Kubernetes cluster in production. The Kubernetes environment created by Docker Desktop is _fully featured_, meaning it has all the Kubernetes features your app will enjoy on a real cluster, accessible from the convenience of your development machine. - -## Describing apps using Kubernetes YAML - -All containers in Kubernetes are scheduled as pods, which are groups of co-located containers that share some resources. Furthermore, in a realistic application you almost never create individual pods. Instead, most of your workloads are scheduled as deployments, which are scalable groups of pods maintained automatically by Kubernetes. Lastly, all Kubernetes objects can and should be described in manifests called Kubernetes YAML files. These YAML files describe all the components and configurations of your Kubernetes app, and can be used to create and destroy your app in any Kubernetes environment. - -You already wrote a basic Kubernetes YAML file in the Orchestration overview part of this tutorial. Now, you can write a slightly more sophisticated YAML file to run and manage your Todo app, the container `getting-started` image created in [Part 2](02_our_app.md) of the Quickstart tutorial. Place the following in a file called `bb.yaml`: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: bb-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - bb: web - template: - metadata: - labels: - bb: web - spec: - containers: - - name: bb-site - image: getting-started - imagePullPolicy: Never ---- -apiVersion: v1 -kind: Service -metadata: - name: bb-entrypoint - namespace: default -spec: - type: NodePort - selector: - bb: web - ports: - - port: 3000 - targetPort: 3000 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A `Deployment`, describing a scalable group of identical pods. In this case, you'll get just one `replica`, or copy of your pod, and that pod (which is described under the `template:` key) has just one container in it, based off of your `getting-started` image from the previous step in this tutorial. -- A `NodePort` service, which will route traffic from port 30001 on your host to port 3000 inside the pods it routes to, allowing you to reach your Todo app from the network. - -Also, notice that while Kubernetes YAML can appear long and complicated at first, it almost always follows the same pattern: - -- The `apiVersion`, which indicates the Kubernetes API that parses this object -- The `kind` indicating what sort of object this is -- Some `metadata` applying things like names to your objects -- The `spec` specifying all the parameters and configurations of your object. - -## Deploy and check your application - -1. In a terminal, navigate to where you created `bb.yaml` and deploy your application to Kubernetes: - - ```console - $ kubectl apply -f bb.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully: - - ```shell - deployment.apps/bb-demo created - service/bb-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments: - - ```console - $ kubectl get deployments - ``` - - if all is well, your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - bb-demo 1/1 1 1 40s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services: - - ```console - $ kubectl get services - - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - bb-entrypoint NodePort 10.106.145.116 <none> 3000:30001/TCP 53s - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 138d - ``` - - In addition to the default `kubernetes` service, we see our `bb-entrypoint` service, accepting traffic on port 30001/TCP. - -3. Open a browser and visit your Todo app at `localhost:30001`. You should see your Todo application, the same as when you ran it as a stand-alone container in [Part 2](02_our_app.md) of the tutorial. - -4. Once satisfied, tear down your application: - - ```console - $ kubectl delete -f bb.yaml - ``` - -## Conclusion - -At this point, you have successfully used Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. You can now add other components to your app and taking advantage of all the features and power of Kubernetes, right on your own machine. - -In addition to deploying to Kubernetes, you have also described your application as a Kubernetes YAML file. This simple text file contains everything you need to create your application in a running state. You can check it in to version control and share it with your colleagues. This let you distribute your applications to other clusters (like the testing and production clusters that probably come after your development environments). - -## Kubernetes references - -Further documentation for all new Kubernetes objects used in this article are available here: - -- [Kubernetes Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/) -- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) -- [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/) diff --git a/content/guides/lab-agentic-apps.md b/content/guides/lab-agentic-apps.md index 2e8d5e5a246f..19bc988a8c51 100644 --- a/content/guides/lab-agentic-apps.md +++ b/content/guides/lab-agentic-apps.md @@ -11,15 +11,8 @@ keywords: AI, Docker, Model Runner, MCP Gateway, agentic apps, lab, labspace aliases: - /labs/docker-for-ai/agentic-apps/ params: - tags: [ai, labs] + tags: [labs] time: 20 minutes - resource_links: - - title: Docker Model Runner docs - url: /ai/model-runner/ - - title: Docker MCP Gateway docs - url: /ai/mcp-gateway/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-agentic-apps-with-docker --- Get up and running with building agentic applications using Compose, Docker diff --git a/content/guides/lab-ai-fundamentals.md b/content/guides/lab-ai-fundamentals.md index 02837f1774a3..5ee8718201ad 100644 --- a/content/guides/lab-ai-fundamentals.md +++ b/content/guides/lab-ai-fundamentals.md @@ -12,13 +12,8 @@ keywords: AI, Docker, Model Runner, prompt engineering, RAG, tool calling, lab, aliases: - /labs/docker-for-ai/ai-fundamentals/ params: - tags: [ai, labs] + tags: [labs] time: 45 minutes - resource_links: - - title: Docker Model Runner docs - url: /ai/model-runner/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-ai-fundamentals --- Get hands-on with the four core pillars of AI application development: models, diff --git a/content/guides/lab-attestation-basics.md b/content/guides/lab-attestation-basics.md index 7c9aa42aa1bf..4153c114ac08 100644 --- a/content/guides/lab-attestation-basics.md +++ b/content/guides/lab-attestation-basics.md @@ -12,15 +12,6 @@ keywords: Docker, supply chain, SBOM, provenance, SLSA, Cosign, VEX, attestation params: tags: [labs] time: 45 minutes - resource_links: - - title: Build attestations - url: /build/metadata/attestations/ - - title: SBOM attestations - url: /build/metadata/attestations/sbom/ - - title: Provenance attestations - url: /build/metadata/attestations/slsa-provenance/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-attestation-basics --- Prove where your container images came from and that they haven't been diff --git a/content/guides/lab-building-images.md b/content/guides/lab-building-images.md index 550e4bb90fbd..424d5df7a274 100644 --- a/content/guides/lab-building-images.md +++ b/content/guides/lab-building-images.md @@ -13,15 +13,6 @@ keywords: Docker, Dockerfile, images, multi-stage builds, layer caching, build s params: tags: [labs] time: 45 minutes - resource_links: - - title: Dockerfile reference - url: /reference/dockerfile/ - - title: Multi-stage builds - url: /build/building/multi-stage/ - - title: Build secrets - url: /build/building/secrets/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-building-images --- Take a working but naïve Dockerfile and progressively improve it into a diff --git a/content/guides/lab-compose-quickstart.md b/content/guides/lab-compose-quickstart.md index 17605a66aef0..97d821d91a0f 100644 --- a/content/guides/lab-compose-quickstart.md +++ b/content/guides/lab-compose-quickstart.md @@ -13,13 +13,6 @@ keywords: Docker, Compose, multi-container, Flask, Redis, watch mode, volumes, l params: tags: [labs] time: 45 minutes - resource_links: - - title: Docker Compose docs - url: /compose/ - - title: Compose watch mode - url: /compose/how-tos/file-watch/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-compose-quickstart --- Build a Python Flask and Redis hit-counter app using Docker Compose, starting diff --git a/content/guides/lab-container-getting-started.md b/content/guides/lab-container-getting-started.md index e3499688d3e5..3e8ad4ad83b9 100644 --- a/content/guides/lab-container-getting-started.md +++ b/content/guides/lab-container-getting-started.md @@ -11,13 +11,6 @@ keywords: Docker, containers, Dockerfile, images, getting started, lab, labspace params: tags: [labs] time: 30 minutes - resource_links: - - title: Docker overview - url: /get-started/docker-overview/ - - title: Dockerfile reference - url: /reference/dockerfile/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-container-getting-started --- Start from zero and learn Docker's core building blocks. You'll run pre-built diff --git a/content/guides/lab-container-supported-development.md b/content/guides/lab-container-supported-development.md index 9a8b526023a9..1915b40a888e 100644 --- a/content/guides/lab-container-supported-development.md +++ b/content/guides/lab-container-supported-development.md @@ -13,13 +13,6 @@ keywords: Docker, Compose, local development, PostgreSQL, pgAdmin, containers, l params: tags: [labs] time: 30 minutes - resource_links: - - title: Docker Compose docs - url: /compose/ - - title: Bind mounts - url: /engine/storage/bind-mounts/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-container-supported-development --- Use containers to run the services your app depends on — databases, caches, diff --git a/content/guides/lab-containerized-sdlc.md b/content/guides/lab-containerized-sdlc.md index 7e26ea96c2d0..4acd08027520 100644 --- a/content/guides/lab-containerized-sdlc.md +++ b/content/guides/lab-containerized-sdlc.md @@ -13,13 +13,6 @@ keywords: Docker, Compose, Testcontainers, Kubernetes, CI/CD, SDLC, lab, labspac params: tags: [labs] time: 60 minutes - resource_links: - - title: Docker Compose docs - url: /compose/ - - title: Testcontainers docs - url: https://testcontainers.com/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-containerized-sdlc --- Build a real Node.js API, then apply containers at every stage of the software diff --git a/content/guides/lab-creating-ai-product-reviewer.md b/content/guides/lab-creating-ai-product-reviewer.md index af02981645b1..bb295c1119d0 100644 --- a/content/guides/lab-creating-ai-product-reviewer.md +++ b/content/guides/lab-creating-ai-product-reviewer.md @@ -13,13 +13,8 @@ keywords: AI, Docker, Model Runner, sentiment analysis, embeddings, RAG, lab, la aliases: - /labs/docker-for-ai/creating-ai-product-reviewer/ params: - tags: [ai, labs] + tags: [labs] time: 60 minutes - resource_links: - - title: Docker Model Runner docs - url: /ai/model-runner/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-creating-ai-product-reviewer --- Build a complete feedback analysis pipeline for a fictional AI product called diff --git a/content/guides/lab-dhi-node.md b/content/guides/lab-dhi-node.md index 3e775b7e3a9d..9d1a1f51c274 100644 --- a/content/guides/lab-dhi-node.md +++ b/content/guides/lab-dhi-node.md @@ -11,17 +11,8 @@ summary: | builds with DHI, and explore SBOMs, VEX, and compliance attestations. keywords: Docker, Hardened Images, DHI, Node.js, Docker Scout, CVE, security, SBOM, lab, labspace params: - tags: [labs, dhi] + tags: [labs] time: 30 minutes - resource_links: - - title: Docker Hardened Images - url: /dhi/ - - title: Docker Scout docs - url: /scout/ - - title: Build attestations - url: /build/metadata/attestations/ - - title: Labspace repository - url: https://github.com/dockersamples/labspace-dhi-node --- Migrate a Node.js application from a standard `node:24-trixie-slim` base image diff --git a/content/guides/lab-docker-agent.md b/content/guides/lab-docker-agent.md index bb2cfcadbb70..6e21c6111d66 100644 --- a/content/guides/lab-docker-agent.md +++ b/content/guides/lab-docker-agent.md @@ -12,15 +12,8 @@ aliases: - /labs/docker-for-ai/cagent/ - /guides/lab-cagent/ params: - tags: [ai, labs] + tags: [labs] time: 20 minutes - resource_links: - - title: Docker Agent documentation - url: https://github.com/docker/docker-agent - - title: Docker MCP Toolkit - url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/ - - title: Labspace repository - url: https://github.com/ajeetraina/labspace-cagent --- This lab walks you through building intelligent agents with Docker Agent. You'll learn beginner diff --git a/content/guides/lab-docker-for-ai-redirect.md b/content/guides/lab-docker-for-ai-redirect.md deleted file mode 100644 index 0851380aef86..000000000000 --- a/content/guides/lab-docker-for-ai-redirect.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Docker for AI Labs -keywords: docker, ai, labs, machine learning, hands-on -type: redirect -target: /guides/?tags=labs -aliases: - - /labs/ - - /labs/docker-for-ai/ ---- diff --git a/content/guides/lab-mcp-gateway.md b/content/guides/lab-mcp-gateway.md index 4d53c8f37a4b..4d2b97720702 100644 --- a/content/guides/lab-mcp-gateway.md +++ b/content/guides/lab-mcp-gateway.md @@ -11,15 +11,8 @@ keywords: AI, Docker, MCP, MCP Gateway, MCP servers, lab, labspace aliases: - /labs/docker-for-ai/mcp-gateway/ params: - tags: [ai, labs] + tags: [labs] time: 20 minutes - resource_links: - - title: Docker MCP Gateway docs - url: /ai/mcp-gateway/ - - title: MCP Gateway GitHub - url: https://github.com/docker/mcp-gateway - - title: Labspace repository - url: https://github.com/dockersamples/labspace-mcp-gateway --- This lab provides a comprehensive, hands-on overview of the Docker MCP Gateway, diff --git a/content/guides/language-translation.md b/content/guides/language-translation.md deleted file mode 100644 index 751230ce4ade..000000000000 --- a/content/guides/language-translation.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: Build a language translation app -linkTitle: Language translation -keywords: nlp, natural language processing, text summarization, python, language translation, googletrans -description: Learn how to build and run a language translation application using Python, Googletrans, and Docker. -summary: | - This guide demonstrates how to use Docker to deploy language translation - models for NLP tasks. -tags: [ai] -languages: [python] -aliases: - - /guides/use-case/nlp/language-translation/ -params: - time: 20 minutes ---- - -## Overview - -This guide walks you through building and running a language translation -application. You'll build the application using Python with Googletrans, and -then set up the environment and run the application using Docker. - -The application demonstrates a simple but practical use of the Googletrans -library for language translation, showcasing basic Python and Docker concepts. -Googletrans is a free and unlimited Python library that implements the Google -Translate API. It uses the Google Translate Ajax API to make calls to such -methods as detect and translate. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Get the sample application - -1. Open a terminal, and clone the sample application's repository using the - following command. - - ```console - $ git clone https://github.com/harsh4870/Docker-NLP.git - ``` - -2. Verify that you cloned the repository. - - You should see the following files in your `Docker-NLP` directory. - - ```text - 01_sentiment_analysis.py - 02_name_entity_recognition.py - 03_text_classification.py - 04_text_summarization.py - 05_language_translation.py - entrypoint.sh - requirements.txt - Dockerfile - README.md - ``` - -## Explore the application code - -The source code for the application is in the -`Docker-NLP/05_language_translation.py` file. Open `05_language_translation.py` -in a text or code editor to explore its contents in the following steps. - -1. Import the required libraries. - - ```python - from googletrans import Translator - ``` - - This line imports the `Translator` class from `googletrans`. - Googletrans is a Python library that provides an interface to Google - Translate's AJAX API. - -2. Specify the main execution block. - - ```python - if __name__ == "__main__": - ``` - - This Python idiom ensures that the following code block runs only if this - script is the main program. It provides flexibility, allowing the script to - function both as a standalone program and as an imported module. - -3. Create an infinite loop for continuous input. - - ```python - while True: - input_text = input("Enter the text for translation (type 'exit' to end): ") - - if input_text.lower() == 'exit': - print("Exiting...") - break - ``` - - An infinite loop is established here to continuously prompt you for text - input, ensuring interactivity. The loop breaks when you type `exit`, allowing - you to control the application flow effectively. - -4. Create an instance of Translator. - - ```python - translator = Translator() - ``` - - This creates an instance of the Translator class, which - performs the translation. - -5. Translate text. - - ```python - translated_text = translator.translate(input_text, dest='fr').text - ``` - - Here, the `translator.translate` method is called with the user input. The - `dest='fr'` argument specifies that the destination language for translation - is French. The `.text` attribute gets the translated string. For more details - about the available language codes, see the - [Googletrans docs](https://py-googletrans.readthedocs.io/en/latest/). - -6. Print the original and translated text. - - ```python - print(f"Original Text: {input_text}") - print(f"Translated Text: {translated_text}") - ``` - - These two lines print the original text entered by the user and the - translated text. - -7. Create `requirements.txt`. The sample application already contains the - `requirements.txt` file to specify the necessary modules that the - application imports. Open `requirements.txt` in a code or text editor to - explore its contents. - - ```text - ... - - # 05 language_translation - googletrans==4.0.0-rc1 - ``` - - Only `googletrans` is required for the language translation application. - -## Explore the application environment - -You'll use Docker to run the application in a container. Docker lets you -containerize the application, providing a consistent and isolated environment -for running it. This means the application will operate as intended within its -Docker container, regardless of the underlying system differences. - -To run the application in a container, a Dockerfile is required. A Dockerfile is -a text document that contains all the commands you would call on the command -line to assemble an image. An image is a read-only template with instructions -for creating a Docker container. - -The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents. - -The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/). - -1. Specify the base image. - - ```dockerfile - FROM python:3.8-slim - ``` - - This command sets the foundation for the build. `python:3.8-slim` is a - lightweight version of the Python 3.8 image, optimized for size and speed. - Using this slim image reduces the overall size of your Docker image, leading - to quicker downloads and less surface area for security vulnerabilities. This - is particularly useful for a Python-based application where you might not - need the full standard Python image. - -2. Set the working directory. - - ```dockerfile - WORKDIR /app - ``` - - `WORKDIR` sets the current working directory within the Docker image. By - setting it to `/app`, you ensure that all subsequent commands in the - Dockerfile - (like `COPY` and `RUN`) are executed in this directory. This also helps in - organizing your Docker image, as all application-related files are contained - in a specific directory. - -3. Copy the requirements file into the image. - - ```dockerfile - COPY requirements.txt /app - ``` - - The `COPY` command transfers the `requirements.txt` file from - your local machine into the Docker image. This file lists all Python - dependencies required by the application. Copying it into the container - lets the next command (`RUN pip install`) install these dependencies - inside the image environment. - -4. Install the Python dependencies in the image. - - ```dockerfile - RUN pip install --no-cache-dir -r requirements.txt - ``` - - This line uses `pip`, Python's package installer, to install the packages - listed in `requirements.txt`. The `--no-cache-dir` option disables - the cache, which reduces the size of the Docker image by not storing the - unnecessary cache data. - -5. Run additional commands. - - ```dockerfile - RUN python -m spacy download en_core_web_sm - ``` - - This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile. - -6. Copy the application code into the image. - - ```dockerfile - COPY *.py /app - COPY entrypoint.sh /app - ``` - - These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container. - -7. Set permissions for the `entrypoint.sh` script. - - ```dockerfile - RUN chmod +x /app/entrypoint.sh - ``` - - This command modifies the file permissions of `entrypoint.sh`, making it - executable. This step is necessary to ensure that the Docker container can - run this script to start the application. - -8. Set the entry point. - - ```dockerfile - ENTRYPOINT ["/app/entrypoint.sh"] - ``` - - The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` - as its default executable. This means that when the container starts, it - automatically executes the script. - - You can explore the `entrypoint.sh` script by opening it in a code or text - editor. As the sample contains several applications, the script lets you - specify which application to run when the container starts. - -## Run the application - -To run the application using Docker: - -1. Build the image. - - In a terminal, run the following command inside the directory of where the `Dockerfile` is located. - - ```console - $ docker build -t basic-nlp . - ``` - - The following is a break down of the command: - - - `docker build`: This is the primary command used to build a Docker image - from a Dockerfile and a context. The context is typically a set of files at - a specified location, often the directory containing the Dockerfile. - - `-t basic-nlp`: This is an option for tagging the image. The `-t` flag - stands for tag. It assigns a name to the image, which in this case is - `basic-nlp`. Tags are a convenient way to reference images later, - especially when pushing them to a registry or running containers. - - `.`: This is the last part of the command and specifies the build context. - The period (`.`) denotes the current directory. Docker will look for a - Dockerfile in this directory. The build context (the current directory, in - this case) is sent to the Docker daemon to enable the build. It includes - all the files and subdirectories in the specified directory. - - For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/). - - Docker outputs several logs to your console as it builds the image. You'll - see it download and install the dependencies. Depending on your network - connection, this may take several minutes. Docker does have a caching - feature, so subsequent builds can be faster. The console will - return to the prompt when it's complete. - -2. Run the image as a container. - - In a terminal, run the following command. - - ```console - $ docker run -it basic-nlp 05_language_translation.py - ``` - - The following is a break down of the command: - - - `docker run`: This is the primary command used to run a new container from - a Docker image. - - `-it`: This is a combination of two options: - - `-i` or `--interactive`: This keeps the standard input (STDIN) open even - if not attached. It lets the container remain running in the - foreground and be interactive. - - `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a - terminal, like a command prompt or a shell. It's what lets you - interact with the application inside the container. - - `basic-nlp`: This specifies the name of the Docker image to use for - creating the container. In this case, it's the image named `basic-nlp` that - you created with the `docker build` command. - - `05_language_translation.py`: This is the script you want to run inside the - Docker container. It gets passed to the `entrypoint.sh` script, which runs - it when the container starts. - - For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/). - - > [!NOTE] - > - > For Windows users, you may get an error when running the container. Verify - > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers). - - You will see the following in your console after the container starts. - - ```console - Enter the text for translation (type 'exit' to end): - ``` - -3. Test the application. - - Enter some text to get the text summarization. - - ```console - Enter the text for translation (type 'exit' to end): Hello, how are you doing? - Original Text: Hello, how are you doing? - Translated Text: Bonjour comment allez-vous? - ``` - -## Summary - -In this guide, you learned how to build and run a language translation -application. You learned how to build the application using Python with -Googletrans, and then set up the environment and run the application using -Docker. - -Related information: - -- [Docker CLI reference](/reference/cli/docker/) -- [Dockerfile reference](/reference/dockerfile/) -- [Googletrans](https://github.com/ssut/py-googletrans) -- [Python documentation](https://docs.python.org/3/) - -## Next steps - -Explore more [natural language processing guides](./_index.md). diff --git a/content/guides/laravel.md b/content/guides/laravel.md new file mode 100644 index 000000000000..1361b0f46d2f --- /dev/null +++ b/content/guides/laravel.md @@ -0,0 +1,863 @@ +--- +title: Develop and Deploy Laravel applications with Docker Compose +linkTitle: Laravel +summary: Learn how to efficiently set up Laravel development and production environments using Docker Compose. +description: A guide on using Docker Compose to manage Laravel applications for development and production, covering container configurations and service management. +keywords: laravel, php, docker compose, web framework, development, production +aliases: + - /frameworks/laravel/ + - /guides/frameworks/laravel/ + - /guides/frameworks/laravel/common-questions/ + - /guides/frameworks/laravel/development-setup/ + - /guides/frameworks/laravel/prerequisites/ + - /guides/frameworks/laravel/production-setup/ +params: + tags: [languages] + time: 30 minutes +--- + + +Laravel is a popular PHP framework that allows developers to build web applications quickly and effectively. Docker Compose simplifies the management of development and production environments by defining essential services, like PHP, a web server, and a database, in a single YAML file. This guide provides a streamlined approach to setting up a robust Laravel environment using Docker Compose, focusing on simplicity and efficiency. + +> **Acknowledgment** +> +> Docker would like to thank [Sergei Shitikov](https://github.com/rw4lll) for +> his contribution to this guide. + +The demonstrated examples can be found in [this GitHub repository](https://github.com/dockersamples/laravel-docker-examples). Docker Compose offers a straightforward approach to connecting multiple containers for Laravel, though similar setups can also be achieved using tools like Docker Swarm, Kubernetes, or individual Docker containers. + +This guide is intended for educational purposes, helping developers adapt and optimize configurations for their specific use cases. Additionally, there are existing tools that support Laravel in containers: + +- [Laravel Sail](https://laravel.com/docs/12.x/sail): An official package for easily starting Laravel in Docker. +- [Laradock](https://github.com/laradock/laradock): A community project that helps run Laravel applications in Docker. + +## What you’ll learn + +- How to use Docker Compose to set up a Laravel development and production environment. +- Defining services that make Laravel development easier, including PHP-FPM, Nginx, and database containers. +- Best practices for managing Laravel environments using containerization. + +## Who’s this for? + +- Developers who work with Laravel and want to streamline environment management. +- DevOps engineers seeking efficient ways to manage and deploy Laravel applications. + +## Prerequisites for Setting Up Laravel with Docker Compose + +Before you begin setting up Laravel with Docker Compose, make sure you meet the following prerequisites: + +### Docker and Docker Compose + +You need Docker and Docker Compose installed on your system. Docker allows you to containerize applications, and Docker Compose helps you manage multi-container applications. + +- Docker: Make sure Docker is installed and running on your machine. Refer to the [Docker installation guide](/get-docker/) to install Docker. +- Docker Compose: Docker Compose is included with Docker Desktop, but you can also follow the [Docker Compose installation guide](/compose/install/) if needed. + +### Basic understanding of Docker and containers + +A fundamental understanding of Docker and how containers work will be helpful. If you're new to Docker, consider reviewing the [Docker Overview](/get-started/overview/) to familiarize yourself with containerization concepts. + +### Basic knowledge of Laravel + +This guide assumes you have a basic understanding of Laravel and PHP. Familiarity with Laravel’s command-line tools, such as [Artisan](https://laravel.com/docs/12.x/artisan), and its project structure is important for following the instructions. + +- Laravel CLI: You should be comfortable using Laravel’s command-line tool (`artisan`). +- Laravel Project Structure: Familiarize yourself with Laravel’s folder structure (`app`, `config`, `routes`, `tests`, etc.). + +## Laravel Production Setup with Docker Compose + +This guide demonstrates how to set up a production-ready Laravel environment using Docker and Docker Compose. This configuration is designed for streamlined, scalable, and secure Laravel application deployments. + +> [!NOTE] +> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production. + +### Project structure + +```plaintext +my-laravel-app/ +├── app/ +├── bootstrap/ +├── config/ +├── database/ +├── public/ +├── docker/ +│ ├── common/ +│ │ └── php-fpm/ +│ │ ├── Dockerfile +│ │ └── conf.d/ +│ │ └── 20-status-path.conf +│ ├── development/ +│ ├── production/ +│ │ ├── php-fpm/ +│ │ │ └── entrypoint.sh +│ │ └── nginx +│ │ ├── Dockerfile +│ │ └── nginx.conf +├── compose.dev.yaml +├── compose.prod.yaml +├── .dockerignore +├── .env +├── vendor/ +├── ... +``` + +This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable. + +### Create a Dockerfile for PHP-FPM (production) + +For production, the `php-fpm` Dockerfile creates an optimized image with only the PHP extensions and libraries your application needs. As demonstrated in the [GitHub example](https://github.com/dockersamples/laravel-docker-examples), a single Dockerfile with multi-stage builds maintains consistency and reduces duplication between development and production. The following snippet shows only the production-related stages: + +```dockerfile +# Stage 1: Build environment and Composer dependencies +FROM php:8.5-fpm AS builder + +# Install system dependencies and PHP extensions for Laravel with MySQL/PostgreSQL support. +# Dependencies in this stage are only required for building the final image. +# Node.js and asset building are handled in the Nginx stage, not here. +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + unzip \ + libpq-dev \ + libonig-dev \ + libssl-dev \ + libxml2-dev \ + libcurl4-openssl-dev \ + libicu-dev \ + libzip-dev \ + && docker-php-ext-install -j$(nproc) \ + pdo_mysql \ + pdo_pgsql \ + pgsql \ + intl \ + zip \ + bcmath \ + soap \ + && pecl install redis \ + && docker-php-ext-enable redis \ + && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Set the working directory inside the container +WORKDIR /var/www + +# Copy the entire Laravel application code into the container +# ----------------------------------------------------------- +# In Laravel, `composer install` may trigger scripts +# needing access to application code. +# For example, the `post-autoload-dump` event might execute +# Artisan commands like `php artisan package:discover`. If the +# application code (including the `artisan` file) is not +# present, these commands will fail, leading to build errors. +# +# By copying the entire application code before running +# `composer install`, we ensure that all necessary files are +# available, allowing these scripts to run successfully. +# In other cases, it would be possible to copy composer files +# first, to leverage Docker's layer caching mechanism. +# ----------------------------------------------------------- +COPY . /var/www + +# Install Composer and dependencies +RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ + && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist + +# Stage 2: Production environment +FROM php:8.5-fpm AS production + +# Install only runtime libraries needed in production +# libfcgi-bin and procps are required for the php-fpm-healthcheck script +RUN apt-get update && apt-get install -y --no-install-recommends \ + libpq-dev \ + libicu-dev \ + libzip-dev \ + libfcgi-bin \ + procps \ + && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Download and install php-fpm health check script +RUN curl -o /usr/local/bin/php-fpm-healthcheck \ + https://raw.githubusercontent.com/renatomefi/php-fpm-healthcheck/master/php-fpm-healthcheck \ + && chmod +x /usr/local/bin/php-fpm-healthcheck + +# Copy the initialization script +COPY ./docker/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh +RUN chmod +x /usr/local/bin/entrypoint.sh + +# Copy the initial storage structure +COPY ./storage /var/www/storage-init + +# Copy PHP extensions and libraries from the builder stage +COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/ +COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/ +COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/ + +# Use the recommended production PHP configuration +# ----------------------------------------------------------- +# PHP provides development and production configurations. +# Here, we replace the default php.ini with the production +# version to apply settings optimized for performance and +# security in a live environment. +# ----------------------------------------------------------- +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" + +# Keep the image-provided FPM global config intact and add pool overrides separately +COPY ./docker/common/php-fpm/conf.d/*.conf /usr/local/etc/php-fpm.d/ +# Update the variables_order to include E (for ENV) +#RUN sed -i 's/variables_order = "GPCS"/variables_order = "EGPCS"/' "$PHP_INI_DIR/php.ini" + +# Copy the application code and dependencies from the build stage +COPY --from=builder /var/www /var/www + +# Set working directory +WORKDIR /var/www + +# Ensure correct permissions +RUN chown -R www-data:www-data /var/www + +# Switch to the non-privileged user to run the application +USER www-data + +# Change the default command to run the entrypoint script +ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] + +# Expose port 9000 and start php-fpm server +EXPOSE 9000 +CMD ["php-fpm"] +``` + +### Create a Dockerfile for PHP-CLI (production) + +For production, you often need a separate container to run Artisan commands, migrations, and other CLI tasks. In most cases you can run these commands by reusing existing PHP-FPM container: + +```console +$ docker compose -f compose.prod.yaml exec php-fpm php artisan route:list +``` + +If you need a separate CLI container with different extensions or strict separation of concerns, consider a php-cli Dockerfile: + +```dockerfile +# Stage 1: Build environment and Composer dependencies +FROM php:8.5-cli AS builder + +# Install system dependencies and PHP extensions required for Laravel + MySQL/PostgreSQL support +# Some dependencies are required for PHP extensions only in the build stage +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + unzip \ + libpq-dev \ + libonig-dev \ + libssl-dev \ + libxml2-dev \ + libcurl4-openssl-dev \ + libicu-dev \ + libzip-dev \ + && docker-php-ext-install -j$(nproc) \ + pdo_mysql \ + pdo_pgsql \ + pgsql \ + intl \ + zip \ + bcmath \ + soap \ + && pecl install redis \ + && docker-php-ext-enable redis \ + && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Set the working directory inside the container +WORKDIR /var/www + +# Copy the entire Laravel application code into the container +COPY . /var/www + +# Install Composer and dependencies +RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ + && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist + +# Stage 2: Production environment +FROM php:8.5-cli + +# Install client libraries required for php extensions in runtime +RUN apt-get update && apt-get install -y --no-install-recommends \ + libpq-dev \ + libicu-dev \ + libzip-dev \ + && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Copy PHP extensions and libraries from the builder stage +COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/ +COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/ +COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/ + +# Use the default production configuration for PHP runtime arguments +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" + +# Copy the application code and dependencies from the build stage +COPY --from=builder /var/www /var/www + +# Set working directory +WORKDIR /var/www + +# Ensure correct permissions +RUN chown -R www-data:www-data /var/www + +# Switch to the non-privileged user to run the application +USER www-data + +# Default command: Provide a bash shell to allow running any command +CMD ["bash"] +``` + +This Dockerfile is similar to the PHP-FPM Dockerfile, but it uses the `php:8.5-cli` image as the base image and sets up the container for running CLI commands. + +### Create a Dockerfile for Nginx (production) + +Nginx serves as the web server for the Laravel application. You can include static assets directly to the container. Here's an example of possible Dockerfile for Nginx: + +```dockerfile +# docker/nginx/Dockerfile +# Stage 1: Build assets +FROM debian AS builder + +# Install Node.js and build tools +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + nodejs \ + npm \ + && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Set working directory +WORKDIR /var/www + +# Copy Laravel application code +COPY . /var/www + +# Install Node.js dependencies and build assets +RUN npm install && npm run build + +# Stage 2: Nginx production image +FROM nginx:alpine + +# Copy custom Nginx configuration +# ----------------------------------------------------------- +# Replace the default Nginx configuration with our custom one +# that is optimized for serving a Laravel application. +# ----------------------------------------------------------- +COPY ./docker/nginx/nginx.conf /etc/nginx/nginx.conf + +# Copy Laravel's public assets from the builder stage +# ----------------------------------------------------------- +# We only need the 'public' directory from our Laravel app. +# ----------------------------------------------------------- +COPY --from=builder /var/www/public /var/www/public + +# Set the working directory to the public folder +WORKDIR /var/www/public + +# Expose port 80 and start Nginx +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] +``` + +This Dockerfile uses a multi-stage build to separate the asset building process from the final production image. The first stage installs Node.js and builds the assets, while the second stage sets up the Nginx production image with the optimized configuration and the built assets. + +### Create a Docker Compose configuration for production + +To bring all the services together, create a `compose.prod.yaml` file that defines the services, volumes, and networks for the production environment. Here's an example configuration: + +```yaml +services: + web: + build: + context: . + dockerfile: ./docker/production/nginx/Dockerfile + restart: unless-stopped # Automatically restart unless the service is explicitly stopped + volumes: + # Mount the 'laravel-storage' volume to '/var/www/storage' inside the container. + # ----------------------------------------------------------- + # This volume stores persistent data like uploaded files and cache. + # The ':ro' option mounts it as read-only in the 'web' service because Nginx only needs to read these files. + # The 'php-fpm' service mounts the same volume without ':ro' to allow write operations. + # ----------------------------------------------------------- + - laravel-storage-production:/var/www/storage:ro + networks: + - laravel-production + ports: + # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine. + # ----------------------------------------------------------- + # This allows external access to the Nginx web server running inside the container. + # For example, if 'NGINX_PORT' is set to '8080', accessing 'http://localhost:8080' will reach the application. + # ----------------------------------------------------------- + - "${NGINX_PORT:-80}:80" + depends_on: + php-fpm: + condition: service_healthy # Wait for php-fpm health check + + php-fpm: + # For the php-fpm service, we will create a custom image to install the necessary PHP extensions and setup proper permissions. + build: + context: . + dockerfile: ./docker/common/php-fpm/Dockerfile + target: production # Use the 'production' stage in the Dockerfile + restart: unless-stopped + volumes: + - laravel-storage-production:/var/www/storage # Mount the storage volume + env_file: + - .env + networks: + - laravel-production + healthcheck: + test: ["CMD-SHELL", "php-fpm-healthcheck || exit 1"] + interval: 10s + timeout: 5s + retries: 3 + # The 'depends_on' attribute with 'condition: service_healthy' ensures that + # this service will not start until the 'postgres' service passes its health check. + # This prevents the application from trying to connect to the database before it's ready. + depends_on: + postgres: + condition: service_healthy + + # The 'php-cli' service provides a command-line interface for running Artisan commands and other CLI tasks. + # ----------------------------------------------------------- + # This is useful for running migrations, seeders, or any custom scripts. + # It shares the same codebase and environment as the 'php-fpm' service. + # ----------------------------------------------------------- + php-cli: + build: + context: . + dockerfile: ./docker/php-cli/Dockerfile + tty: true # Enables an interactive terminal + stdin_open: true # Keeps standard input open for 'docker exec' + env_file: + - .env + networks: + - laravel-production + + postgres: + image: postgres:18 + restart: unless-stopped + user: postgres + ports: + - "${POSTGRES_PORT}:5432" + environment: + - POSTGRES_DB=${POSTGRES_DATABASE} + - POSTGRES_USER=${POSTGRES_USERNAME} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} + volumes: + - postgres-data-production:/var/lib/postgresql + networks: + - laravel-production + # Health check for PostgreSQL + # ----------------------------------------------------------- + # Health checks allow Docker to determine if a service is operational. + # The 'pg_isready' command checks if PostgreSQL is ready to accept connections. + # This prevents dependent services from starting before the database is ready. + # ----------------------------------------------------------- + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: redis:alpine + restart: unless-stopped # Automatically restart unless the service is explicitly stopped + networks: + - laravel-production + # Health check for Redis + # ----------------------------------------------------------- + # Checks if Redis is responding to the 'PING' command. + # This ensures that the service is not only running but also operational. + # ----------------------------------------------------------- + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 10s + timeout: 5s + retries: 3 + +networks: + # Attach the service to the 'laravel-production' network. + # ----------------------------------------------------------- + # This custom network allows all services within it to communicate using their service names as hostnames. + # For example, 'php-fpm' can connect to 'postgres' by using 'postgres' as the hostname. + # ----------------------------------------------------------- + laravel-production: + +volumes: + postgres-data-production: + laravel-storage-production: +``` + +> [!NOTE] +> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations to match the Docker Compose setup. + +### Running your production environment + +To start the production environment, run: + +```console +$ docker compose -f compose.prod.yaml up --build -d +``` + +This command will build and start all the services in detached mode, providing a scalable and production-ready setup for your Laravel application. + +### Summary + +By setting up a Docker Compose environment for Laravel in production, you ensure that your application is optimized for performance, scalable, and secure. This setup makes deployments consistent and easier to manage, reducing the likelihood of errors due to differences between environments. + +## Laravel Development Setup with Docker Compose + +This guide demonstrates how to configure a **development** environment for a Laravel application using Docker and Docker Compose. It builds **on top of** the production image for PHP-FPM and then adds developer-focused features—like Xdebug—to streamline debugging. By basing the development container on a known production image, you keep both environments closely aligned. + +This setup includes PHP-FPM, Nginx, and PostgreSQL services (although you can easily swap PostgreSQL for another database, like MySQL or MariaDB). Everything runs in containers, so you can develop in isolation without altering your host system. + +> [!NOTE] +> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production. + +### Project structure + +```plaintext +my-laravel-app/ +├── app/ +├── bootstrap/ +├── config/ +├── database/ +├── public/ +├── docker/ +│ ├── common/ +│ │ └── php-fpm/ +│ │ └── Dockerfile +│ ├── development/ +│ │ ├── php-fpm/ +│ │ │ └── entrypoint.sh +│ │ ├── workspace/ +│ │ │ └── Dockerfile +│ │ └── nginx +│ │ ├── Dockerfile +│ │ └── nginx.conf +│ └── production/ +├── compose.dev.yaml +├── compose.prod.yaml +├── .dockerignore +├── .env +├── vendor/ +├── ... +``` + +This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable. + +The environment includes a `workspace` service, a sidecar container for tasks like building front-end assets, running Artisan commands, and other CLI tools your project may require. While this extra container may seem unusual, it’s a familiar pattern in solutions like **Laravel Sail** and **Laradock**. It also includes **Xdebug** to aid in debugging. + +### Create a Dockerfile for PHP-FPM + +This Dockerfile **extends** the production image by installing Xdebug and adjusting user permissions to ease local development. That way, your development environment stays consistent with production while still offering extra debug features and improved file mounting. + +```dockerfile +# Builds a dev-only layer on top of the production image +FROM production AS development + +# Use ARGs to define environment variables passed from the Docker build command or Docker Compose. +ARG XDEBUG_ENABLED=true +ARG XDEBUG_MODE=develop,coverage,debug,profile +ARG XDEBUG_HOST=host.docker.internal +ARG XDEBUG_IDE_KEY=DOCKER +ARG XDEBUG_LOG=/dev/stdout +ARG XDEBUG_LOG_LEVEL=0 + +USER root + +# Configure Xdebug if enabled +RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \ + pecl install xdebug && \ + docker-php-ext-enable xdebug && \ + echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ + echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ +fi + +# Add ARGs for syncing permissions +ARG UID=1000 +ARG GID=1000 + +# Create a new user with the specified UID and GID, reusing an existing group if GID exists +RUN if getent group ${GID}; then \ + group_name=$(getent group ${GID} | cut -d: -f1); \ + useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \ + else \ + groupadd -g ${GID} www && \ + useradd -m -u ${UID} -g www -s /bin/bash www; \ + group_name=www; \ + fi + +# Dynamically update php-fpm to use the new user and group +RUN sed -i "s/user = www-data/user = www/g" /usr/local/etc/php-fpm.d/www.conf && \ + sed -i "s/group = www-data/group = $group_name/g" /usr/local/etc/php-fpm.d/www.conf + + +# Set the working directory +WORKDIR /var/www + +# Copy the entrypoint script +COPY ./docker/development/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh +RUN chmod +x /usr/local/bin/entrypoint.sh + +# Switch back to the non-privileged user to run the application +USER www-data + +# Change the default command to run the entrypoint script +ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] + +# Expose port 9000 and start php-fpm server +EXPOSE 9000 +CMD ["php-fpm"] +``` + +### Create a Dockerfile for Workspace + +A workspace container provides a dedicated shell for asset compilation, Artisan/Composer commands, and other CLI tasks. This approach follows patterns from Laravel Sail and Laradock, consolidating all development tools into one container for convenience. + +```dockerfile +# docker/development/workspace/Dockerfile +# Use the official PHP CLI image as the base +FROM php:8.5-cli + +# Set environment variables for user and group ID +ARG UID=1000 +ARG GID=1000 +ARG NODE_VERSION=22.0.0 + +# Install system dependencies and build libraries +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + unzip \ + libpq-dev \ + libonig-dev \ + libssl-dev \ + libxml2-dev \ + libcurl4-openssl-dev \ + libicu-dev \ + libzip-dev \ + && docker-php-ext-install -j$(nproc) \ + pdo_mysql \ + pdo_pgsql \ + pgsql \ + intl \ + zip \ + bcmath \ + soap \ + && pecl install redis \ + && docker-php-ext-enable redis \ + && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \ + && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +# Use ARG to define environment variables passed from the Docker build command or Docker Compose. +ARG XDEBUG_ENABLED +ARG XDEBUG_MODE +ARG XDEBUG_HOST +ARG XDEBUG_IDE_KEY +ARG XDEBUG_LOG +ARG XDEBUG_LOG_LEVEL + +# Configure Xdebug if enabled +RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \ + pecl install xdebug && \ + docker-php-ext-enable xdebug && \ + echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ + echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ + echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \ +fi + +# If the group already exists, use it; otherwise, create the 'www' group +RUN if getent group ${GID}; then \ + useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \ + else \ + groupadd -g ${GID} www && \ + useradd -m -u ${UID} -g www -s /bin/bash www; \ + fi && \ + usermod -aG sudo www && \ + echo 'www ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers + +# Switch to the non-root user to install NVM and Node.js +USER www + +# Install NVM (Node Version Manager) as the www user +RUN export NVM_DIR="$HOME/.nvm" && \ + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash && \ + [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && \ + nvm install ${NODE_VERSION} && \ + nvm alias default ${NODE_VERSION} && \ + nvm use default + +# Ensure NVM is available for all future shells +RUN echo 'export NVM_DIR="$HOME/.nvm"' >> /home/www/.bashrc && \ + echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> /home/www/.bashrc && \ + echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> /home/www/.bashrc + +# Set the working directory +WORKDIR /var/www + +# Override the entrypoint to avoid the default php entrypoint +ENTRYPOINT [] + +# Default command to keep the container running +CMD ["bash"] +``` + +> [!NOTE] +> If you prefer a **one-service-per-container** approach, simply omit the workspace container and run separate containers for each task. For example, you could use a dedicated `php-cli` container for your PHP scripts, and a `node` container to handle the asset building. + +### Create a Docker Compose configuration for development + +Here's the `compose.yaml` file to set up the development environment: + +```yaml +services: + web: + image: nginx:latest # Using the default Nginx image with custom configuration. + volumes: + # Mount the application code for live updates + - ./:/var/www + # Mount the Nginx configuration file + - ./docker/development/nginx/nginx.conf:/etc/nginx/nginx.conf:ro + ports: + # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine + - "80:80" + environment: + - NGINX_HOST=localhost + networks: + - laravel-development + depends_on: + php-fpm: + condition: service_started # Wait for php-fpm to start + + php-fpm: + # For the php-fpm service, we will use our common PHP-FPM Dockerfile with the development target + build: + context: . + dockerfile: ./docker/common/php-fpm/Dockerfile + target: development + args: + UID: ${UID:-1000} + GID: ${GID:-1000} + XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true} + XDEBUG_MODE: develop,coverage,debug,profile + XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal} + XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER} + XDEBUG_LOG: /dev/stdout + XDEBUG_LOG_LEVEL: 0 + env_file: + # Load the environment variables from the Laravel application + - .env + user: "${UID:-1000}:${GID:-1000}" + volumes: + # Mount the application code for live updates + - ./:/var/www + networks: + - laravel-development + depends_on: + postgres: + condition: service_started # Wait for postgres to start + + workspace: + # For the workspace service, we will also create a custom image to install and setup all the necessary stuff. + build: + context: . + dockerfile: ./docker/development/workspace/Dockerfile + args: + UID: ${UID:-1000} + GID: ${GID:-1000} + XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true} + XDEBUG_MODE: develop,coverage,debug,profile + XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal} + XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER} + XDEBUG_LOG: /dev/stdout + XDEBUG_LOG_LEVEL: 0 + tty: true # Enables an interactive terminal + stdin_open: true # Keeps standard input open for 'docker exec' + env_file: + - .env + volumes: + - ./:/var/www + networks: + - laravel-development + + postgres: + image: postgres:18 + ports: + - "${POSTGRES_PORT:-5432}:5432" + environment: + - POSTGRES_DB=app + - POSTGRES_USER=laravel + - POSTGRES_PASSWORD=secret + volumes: + - postgres-data-development:/var/lib/postgresql + networks: + - laravel-development + + redis: + image: redis:alpine + networks: + - laravel-development + +networks: + laravel-development: + +volumes: + postgres-data-development: +``` + +> [!NOTE] +> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations. You can use the `.env.example` file as a template. + +### Run your development environment + +To start the development environment, use: + +```console +$ docker compose -f compose.dev.yaml up --build -d +``` + +Run this command to build and start the development environment in detached mode. When the containers finish initializing, visit [http://localhost/](http://localhost/) to see your Laravel app in action. + +### Summary + +By building on top of the production image and adding debug tools like Xdebug, you create a Laravel development workflow that closely mirrors production. The optional workspace container simplifies tasks like asset building and running Artisan commands. If you prefer a separate container for every service (e.g., a dedicated `php-cli` and `node` container), you can skip the workspace approach. Either way, Docker Compose provides an efficient, consistent way to develop your Laravel project. + +## Common Questions on Using Laravel with Docker + +<!-- vale Docker.HeadingLength = NO --> + +### 1. Why should I use Docker Compose for Laravel? + +Docker Compose is a powerful tool for managing multi-container environments, particularly in development due to its simplicity. With Docker Compose, you can define and connect all necessary services for Laravel, such as PHP, Nginx, and databases, in a single configuration (`compose.*.yaml`). This setup ensures consistency across development, testing, and production environments, streamlining onboarding and reducing discrepancies between local and server setups. + +While Docker Compose is a great choice for development, tools like **Docker Swarm** or **Kubernetes** offer advanced scaling and orchestration features, which may be beneficial for complex production deployments. + +### 2. How do I debug my Laravel application with Docker Compose? + +To debug your Laravel application in a Docker environment, use **Xdebug**. In the development setup, Xdebug is installed in the `php-fpm` container to enable debugging. Ensure Xdebug is enabled in your `compose.dev.yaml` file by setting the environment variable `XDEBUG_ENABLED=true` and configuring your IDE (e.g., Visual Studio Code or PHPStorm) to connect to the remote container for debugging. + +### 3. Can I use Docker Compose with databases other than PostgreSQL? + +Yes, Docker Compose supports various database services for Laravel. While PostgreSQL is used in the examples, you can easily substitute **MySQL**, **MariaDB**, or even **SQLite**. Update the `compose.*.yaml` file to specify the required Docker image and adjust your `.env` file to reflect the new database configuration. + +### 4. How can I persist data in development and production? + +In both development and production, Docker volumes are used to persist data. For instance, in the `compose.*.yaml` file, the `postgres-data-*` volume stores PostgreSQL data, ensuring that data is retained even if the container restarts. You can also define named volumes for other services where data persistence is essential. + +### 5. What is the difference between development and production Docker configurations? + +In a development environment, Docker configurations include tools that streamline coding and debugging, such as Xdebug for debugging, and volume mounts to enable real-time code updates without requiring image rebuilds. + +In production, the configuration is optimized for performance, security, and efficiency. This setup uses multi-stage builds to keep the image lightweight and includes only essential tools, packages, and libraries. + +It’s recommended to use `alpine`-based images in production for smaller image sizes, enhancing deployment speed and security. + +Additionally, consider using [Docker Scout](/manuals/scout/_index.md) to detect and analyze vulnerabilities, especially in production environments. + +For additional information about using Docker Compose in production, see [this guide](/compose/how-tos/production/). diff --git a/content/guides/localstack.md b/content/guides/localstack.md index e2c66e15768d..aa91bd59e561 100644 --- a/content/guides/localstack.md +++ b/content/guides/localstack.md @@ -6,9 +6,8 @@ linktitle: AWS development with LocalStack summary: | This guide explains how to use Docker to run LocalStack, a local AWS cloud stack emulator. -tags: [cloud-services] -languages: [js] params: + tags: [testing] time: 20 minutes --- @@ -66,11 +65,11 @@ Launch a quick demo of LocalStack by using the following steps: This Compose file also includes specifications for a required Mongo database. You can verify the services are up and running by visiting the Docker Desktop Dashboard. - ![Diagram showing the LocalStack and Mongo container up and running on Docker Desktop ](./images/launch-localstack.webp) + ![Diagram showing the LocalStack and Mongo container up and running on Docker Desktop](./images/launch-localstack.webp) 3. Verify that LocalStack is up and running by selecting the container and checking the logs. - ![Diagram showing the logs of LocalStack container ](./images/localstack-logs.webp) + ![Diagram showing the logs of LocalStack container](./images/localstack-logs.webp) 4. Creating a Local Amazon S3 Bucket @@ -92,7 +91,7 @@ Launch a quick demo of LocalStack by using the following steps: You can verify if the S3 bucket gets created or not by selecting the LocalStack container on the Docker Desktop Dashboard and viewing the logs. The logs indicates that your LocalStack environment is configured correctly and you can now use the `mysamplebucket` for storing and retrieving objects. - ![Diagram showing the logs of LocalStack that highlights the S3 bucket being created successfully ](./images/localstack-s3put.webp) + ![Diagram showing the logs of LocalStack that highlights the S3 bucket being created successfully](./images/localstack-s3put.webp) ## Using LocalStack in development @@ -103,14 +102,14 @@ Now that you've familiarized yourself with LocalStack, it's time to see it in ac - MongoDB: A database to store all the to-do list data - LocalStack: Emulates the Amazon S3 service and stores and retrieve images. -![Diagram showing the tech stack of the sample todo-list application that includes LocalStack, frontend and backend services ](images/localstack-arch.webp) +![Diagram showing the tech stack of the sample todo-list application that includes LocalStack, frontend and backend services](images/localstack-arch.webp) ## Connecting to LocalStack from a non-containerized app Now it’s time to connect your app to LocalStack. The `index.js` file, located in the backend/ directory, serves as the main entry point for the backend application. -The code interacts with LocalStack’s S3 service, which is accessed via the endpoint defined by the `S3_ENDPOINT_URL` environment variable, typically set to `http://localhost:4556` for local development. +The code interacts with LocalStack’s S3 service, which is accessed via the endpoint defined by the `S3_ENDPOINT_URL` environment variable, typically set to `http://localhost:4566` for local development. The `S3Client` from the AWS SDK is configured to use this LocalStack endpoint, along with test credentials (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) that are also sourced from environment variables. This setup lets the application to perform operations on the locally simulated S3 service as if it were interacting with the real AWS S3, making the code flexible for different environments. @@ -264,7 +263,7 @@ Now that you have learnt how to connect a non-containerized Node.js application - SERVICES=s3 - GATEWAY_LISTEN=0.0.0.0:4566 volumes: - - ./localstack:/docker-entrypoint-initaws.d" + - ./localstack:/etc/localstack/init/ready.d volumes: mongodbdata: @@ -308,6 +307,15 @@ Now that you have learnt how to connect a non-containerized Node.js application The command creates an S3 bucket named `mysamplebucket`. + > [!TIP] + > + > You can automate this step by placing a shell script (for example, + > `init.sh`) under the local `./localstack` directory. Make sure the + > script is executable (`chmod +x ./localstack/init.sh`). LocalStack + > runs files mounted in `/etc/localstack/init/ready.d` once it is ready. + > See [LocalStack init hooks](https://docs.localstack.cloud/references/init-hooks/) + > for more details. + Open [http://localhost:5173](http://localhost:5173) to access the complete to-do list application and start uploading images to the Amazon S3 bucket. > [!TIP] diff --git a/content/guides/mistral-vibe-sandbox.md b/content/guides/mistral-vibe-sandbox.md new file mode 100644 index 000000000000..4816d4301249 --- /dev/null +++ b/content/guides/mistral-vibe-sandbox.md @@ -0,0 +1,413 @@ +--- +title: Run Mistral Vibe in a Docker Sandbox +description: Package Mistral's Vibe coding agent as a v3 Docker Sandbox kit with a pinned agent version and host-managed API credentials. +summary: | + Build a reusable v3 workload kit for Mistral's Vibe CLI. Vibe runs in an + isolated microVM and reaches Mistral through the sandbox proxy, so your API + key stays on the host. Verify the setup with a small coding task. +keywords: ai, mistral, vibe, docker sandboxes, sbx, coding agent, microvm, security, kits, uv +params: + tags: [ai] + time: 30 minutes +--- + +Mistral Vibe is Mistral's open source coding agent. This guide shows how to +package it as a Docker Sandbox agent so it runs in an isolated microVM instead +of directly on your host. The agent reaches Mistral through the sandbox +proxy, so your API key stays on the host. + +Install a pinned Vibe version when you build the kit, then reuse that image +for each sandbox. The kit also declares the network access and credentials +Vibe needs at runtime. + +In this guide, you'll learn how to: + +- Store your Mistral API key on the host as a sandbox secret +- Build and publish a v3 workload kit with Vibe installed +- Launch Vibe and verify that it receives a credential placeholder +- Run a sample coding task and inspect the result + +This guide uses [v3 kits](../manuals/ai/sandboxes/customize/_index.md). +Kits are Early Access, and `sbx env` is experimental. + +## How isolation works + +Outbound TCP traffic from the sandbox passes through a proxy on your host. +The proxy enforces network policy and injects credentials into matching +HTTP requests. Vibe sees `MISTRAL_API_KEY=proxy-managed` inside the microVM. +The real key remains in the host secret store. + +Mistral is a +[built-in service](../manuals/ai/sandboxes/configuration/credentials.md#built-in-services). +The kit declares the `mistral` credential and the three hosts where Vibe +uses it: `api.mistral.ai` for inference, `console.mistral.ai` for account +lookup, and `chat.mistral.ai` for managed config. Network access and +credential injection are separate declarations. An allowed package download +doesn't receive the Mistral authorization header. + +## Prerequisites + +Before you start, make sure you have: + +- [Docker Desktop](../get-started/get-docker.md) or Docker Engine with Buildx +- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/install.md), version 0.45.0 or later for v3 kit support +- A [Mistral API key](https://console.mistral.ai/) with an active completion allowance +- Git, for cloning the sample project +- A Docker Hub namespace, or another registry, if you want to publish your kit + +The sample run uses Vibe 2.25.8 and was verified with `sbx` 0.46.0-rc5. + +## Step 1: Store the Mistral key + +Run this command on your host and paste the key when prompted: + +```console +$ sbx secret set mistral +``` + +Service secrets are global by default, so sandboxes that declare the +`mistral` service can request this key. Use `--sandbox` to scope a secret to +one sandbox. The key is stored separately from the kit and workspace. See +[Credentials](../manuals/ai/sandboxes/configuration/credentials.md). + +## Step 2: Install Vibe in the image + +Create a kit directory beside the project you want Vibe to work on. Run the +following command from the directory that will contain both: + +```console +$ mkdir mistral-vibe +``` + +If you don't have an existing project, create an empty workspace beside +the kit to verify the agent launch: + +```console +$ mkdir my-project +``` + +The kit has two files with matching filename stems: + +```text +mistral-vibe/ +├── vibe.yaml +└── vibe.dockerfile +``` + +Create `mistral-vibe/vibe.dockerfile`. The `shell-docker` template supplies +the agent account, Python, `uv`, and the sandbox's Docker tooling: + +```dockerfile {title="mistral-vibe/vibe.dockerfile"} +FROM docker/sandbox-templates:shell-docker + +ARG VIBE_VERSION + +USER agent +RUN uv tool install "mistral-vibe==${VIBE_VERSION}" \ + && uv cache clean \ + && vibe --version + +ENV PATH=/home/agent/.local/bin:${PATH} \ + VIBE_ENABLE_TELEMETRY=false \ + VIBE_ENABLE_AUTO_UPDATE=false \ + GIT_TERMINAL_PROMPT=0 + +WORKDIR /home/agent/workspace +ENTRYPOINT ["vibe", "--trust"] +CMD [] +``` + +The descriptor in the next step supplies `VIBE_VERSION`. Installing as +`agent` puts the executable in `/home/agent/.local/bin`. Turning off Vibe's +automatic update keeps the installed agent version fixed until you rebuild. + +`--trust` lets Vibe load the mounted project's configuration without a +workspace trust prompt. Vibe still uses its tool permission prompts. Review +the project configuration before mounting it. + +## Step 3: Declare access and credentials + +Create `mistral-vibe/vibe.yaml`. The syntax directive selects the v3 kit +frontend, which builds the companion Dockerfile and packages the descriptor +with the image: + +```yaml {title="mistral-vibe/vibe.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: workload +displayName: Mistral Vibe +description: Mistral Vibe with host-managed API credentials + +args: + version: + default: "2.25.8" + pattern: '^[0-9]+\.[0-9]+\.[0-9]+$' + buildArg: VIBE_VERSION + +provides: ["vibe@${{ kit.args.version }}"] + +capabilities: + - type: com.docker.sandbox/sbx@1 + + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + - api.mistral.ai:443 + - console.mistral.ai:443 + - chat.mistral.ai:443 + + - type: com.docker.sandbox/credential@1 + description: Mistral API access + config: + service: mistral + phase: runtime + apiKey: + name: MISTRAL_API_KEY + proxyManaged: true + inject: + - domain: api.mistral.ai + header: Authorization + format: "Bearer %s" + - domain: console.mistral.ai + header: Authorization + format: "Bearer %s" + - domain: chat.mistral.ai + header: Authorization + format: "Bearer %s" +``` + +`kind: workload` declares a kit that supplies the sandbox's root filesystem. +`args.version` selects the Vibe release, maps it to the Dockerfile build +argument, and records that version in `provides`. To install another release, +change the default and rebuild. + +The `sbx@1` capability tells Docker Sandboxes to manage the agent's launch. +The image supplies its user, working directory, and entrypoint. +`network-policy@1` permits HTTPS traffic to the three Mistral hosts. Package +installation happens during the image build, so PyPI doesn't need a runtime +rule unless your coding task downloads packages. + +`credential@1` gives Vibe a placeholder in `MISTRAL_API_KEY` and tells the +host proxy to write the real key into the `Authorization` header. List each +injection host explicitly in the network allowlist. The v3 validator checks +these declarations against each other; a wildcard alone doesn't cover an +injection host for validation. + +## Step 4: Build and publish the kit + +From the directory containing `mistral-vibe`, validate and build the kit +without publishing it: + +```console +$ docker buildx build ./mistral-vibe \ + --file ./mistral-vibe/vibe.yaml \ + --output type=cacheonly +``` + +The build validates the descriptor and installs Vibe. Use the descriptor +with `--file`, rather than the companion Dockerfile, so the output includes +the kit metadata and capabilities. + +Optional. To share the kit, sign in to your registry, replace +`YOUR_NAMESPACE` with your Docker Hub namespace, and publish for both common +architectures: + +```console +$ docker login +$ docker buildx build ./mistral-vibe \ + --file ./mistral-vibe/vibe.yaml \ + --platform linux/amd64,linux/arm64 \ + --provenance=true \ + --sbom=true \ + --tag docker.io/YOUR_NAMESPACE/sbx-kit-vibe:2.25.8 \ + --push +``` + +This publishes the workload and its descriptor as one OCI image, with +provenance and software bill of materials attestations. You can run the +published reference in place of the local kit path in the next step. + +## Step 5: Run and verify Vibe + +From the same directory, launch the local kit against your project. Replace +`./my-project` with the path to the workspace Vibe should edit: + +```console +$ sbx run --name mistral-vibe ./mistral-vibe ./my-project +``` + +`--name` gives the sandbox a predictable name for later commands. The kit +path identifies the workload; the project path identifies the directory +mounted read-write. Vibe's changes to that workspace are visible on your host. + +When prompted, approve the kit's request to use your stored Mistral key. +Storing the key and approving its use are separate steps. See +[Credential bindings](../manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). + +At the Vibe prompt, prefix a shell command with `!` to inspect the value +available inside the sandbox: + +```text +!printf 'MISTRAL_API_KEY=%s\n' "$MISTRAL_API_KEY" +``` + +Expected output: + +```text +MISTRAL_API_KEY=proxy-managed +``` + +Vibe receives the placeholder while the proxy authenticates its Mistral +requests. The following capture shows this check in the sample workspace +used in the next section. Vibe displays the mounted workspace's path; your +path and account greeting will differ from the screenshots: + +![Vibe 2.25.8 displaying MISTRAL_API_KEY=proxy-managed inside the sandbox](images/mistral-vibe-sandbox-credential.jpg) + +## Try a coding task + +The community-maintained +[Mistral Vibe sample](https://github.com/shelajev/mistral-vibe-sbx-demo) +contains a small FastAPI application, three tests, and one intentional bug. +It uses the published +[Vibe kit](https://github.com/shelajev/vibe-sbx-kit), so you can try this +exercise without building or publishing your own kit. This starts a +separate sandbox from the sample's checked-in environment file. Your local +kit sandbox remains available for later use. + +Type `/exit` at the Vibe prompt to return to your host terminal. Then run +these commands from a directory where you want to keep the sample: + +```console +$ git clone https://github.com/shelajev/mistral-vibe-sbx-demo.git +$ cd mistral-vibe-sbx-demo +$ sbx env run +``` + +`sbx env run` reads the repository's `sbxenv.yaml`, pulls +`docker.io/olegselajev241/sbx-kit-vibe:2.25.8`, mounts only `app/`, and opens +Vibe in `mistral-vibe-demo-v3`. Approve the environment plan and credential +binding when prompted. Later runs attach to the same sandbox. + +The environment file uses schema version 1; the kit uses schema version 3. +These formats have independent version numbers. See +[Environment files](../manuals/ai/sandboxes/configuration/environment-files.md). + +Before starting the coding task, open a second host terminal and permit +Python package downloads for this sandbox: + +```console +$ sbx policy allow network --sandbox mistral-vibe-demo-v3 \ + pypi.org,files.pythonhosted.org +``` + +The published kit permits Mistral traffic; the application needs these +additional hosts if `uv` downloads its test dependencies. The rule is scoped +to the sample sandbox, and package requests receive no Mistral credential. + +Return to Vibe, which uses the project's `mistral-medium-3.5` model, and +paste this repair prompt: + +```text +Run the test suite and diagnose the failure. Fix the application code without changing +the tests or the public API contract. Run the full test suite again and summarize the +cause and your change. +``` + +Approve the shell commands and edits when Vibe asks. The failing test checks +`GET /tasks?completed=false`: the endpoint returns all tasks instead of only +incomplete tasks. A correct repair changes `if completed:` to +`if completed is not None:`. + +![Vibe explaining the boolean-filter bug, its application-code repair, and that all three tests pass](images/mistral-vibe-sandbox-repair.jpg) + +Check the test suite yourself at the Vibe prompt: + +```text +!uv run pytest +``` + +The test suite should end with `3 passed`. In your second host terminal, +change to the `mistral-vibe-sbx-demo` repository and inspect the edit: + +```console +$ git diff -- app/main.py +``` + +The repository's `.git` directory stays on the host because only `app/` +is mounted. The diff should show the filter change. To repeat the exercise, +type `/exit` in Vibe and run `git restore app/main.py` from the host +repository to restore the intentional bug. + +Optional. Run `/model` inside Vibe and select **GLM 5.2 (Mistral hosted)**. +The sample adds `zai-glm-5-2` to `app/.vibe/config.toml`; the local kit you +built earlier doesn't add this model configuration. + +![Vibe's model menu showing Mistral Medium 3.5 and GLM 5.2 hosted by Mistral](images/mistral-vibe-sandbox-models.jpg) + +## Troubleshoot and iterate + +If Vibe can't reach a service, inspect the sandbox's proxy log from your host: + +```console +$ sbx policy log mistral-vibe +``` + +For the sample environment, use `mistral-vibe-demo-v3` instead. If another +coding task needs additional services, add the required hosts to the +descriptor or allow them with `sbx policy allow network --sandbox`. + +After editing your local descriptor or Dockerfile, return to the host +directory containing `mistral-vibe` and create another sandbox to test it. +Restarting an existing sandbox doesn't apply kit changes: + +```console +$ sbx run --name mistral-vibe-test-2 ./mistral-vibe ./my-project +``` + +If Vibe keeps retrying without a response, inspect its log from the host: + +```console +$ sbx exec mistral-vibe -- tail -n 50 /home/agent/.vibe/logs/vibe.log +``` + +For the sample, use `mistral-vibe-demo-v3`. Repeated `HTTP 429` responses +indicate a rate or allowance limit. Check the key's organization and workspace +at [Mistral limits](https://admin.mistral.ai/plateforme/limits). A response +with `X-Ratelimit-Limit-Req-Minute: 0` indicates zero request allowance; +the verified sample required activating pay-as-you-go. For authentication +failures, check `sbx secret ls` for a `mistral` entry and confirm the +credential binding covers all three Mistral hosts. + +## Clean up + +Sandboxes persist after Vibe exits. To stop the local sandbox: + +```console +$ sbx stop mistral-vibe +``` + +To remove it: + +```console +$ sbx rm mistral-vibe +``` + +If you created `mistral-vibe-test-2`, remove it with +`sbx rm mistral-vibe-test-2` as well. From the sample repository, remove its +environment with: + +```console +$ sbx env rm --force +``` + +Removing a sandbox preserves the mounted workspace and its edits. + +## Learn more + +- [Get started with Docker Sandboxes](../manuals/ai/sandboxes/get-started.md) +- [Build an agent workload](../manuals/ai/sandboxes/customize/author/build-an-agent.md) +- [Customize sandboxes with kits](../manuals/ai/sandboxes/customize/_index.md) +- [Credentials and built-in services](../manuals/ai/sandboxes/configuration/credentials.md#built-in-services) +- [Mistral Vibe](https://github.com/mistralai/mistral-vibe) diff --git a/content/guides/named-entity-recognition.md b/content/guides/named-entity-recognition.md deleted file mode 100644 index 82b4149a9e88..000000000000 --- a/content/guides/named-entity-recognition.md +++ /dev/null @@ -1,357 +0,0 @@ ---- -title: Build a named entity recognition app -linkTitle: Named entity recognition -keywords: nlp, natural language processing, named entity recognition, python, spacy, ner -description: Learn how to build and run a named entity recognition application using Python, spaCy, and Docker. -summary: | - This guide explains how to containerize named entity recognition (NER) models - using Docker. -tags: [ai] -languages: [python] -aliases: - - /guides/use-case/nlp/named-entity-recognition/ -params: - time: 20 minutes ---- - -## Overview - -This guide walks you through building and running a named entity recognition -(NER) application. You'll build the application using Python with -spaCy, and then set up the environment and run the application using Docker. - -The application processes input text to identify and print named entities, like people, organizations, or locations. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Get the sample application - -1. Open a terminal, and clone the sample application's repository using the - following command. - - ```console - $ git clone https://github.com/harsh4870/Docker-NLP.git - ``` - -2. Verify that you cloned the repository. - - You should see the following files in your `Docker-NLP` directory. - - ```text - 01_sentiment_analysis.py - 02_name_entity_recognition.py - 03_text_classification.py - 04_text_summarization.py - 05_language_translation.py - entrypoint.sh - requirements.txt - Dockerfile - README.md - ``` - -## Explore the application code - -The source code for the name recognition application is in the `Docker-NLP/02_name_entity_recognition.py` file. Open `02_name_entity_recognition.py` in a text or code editor to explore its contents in the following steps. - -1. Import the required libraries. - - ```python - import spacy - ``` - - This line imports the `spaCy` library. `spaCy` is a popular library in Python - used for natural language processing (NLP). - -2. Load the language model. - - ```python - nlp = spacy.load("en_core_web_sm") - ``` - - Here, the `spacy.load` function loads a language model. The `en_core_web_sm` - model is a small English language model. You can use this model for various - NLP tasks, including tokenization, part-of-speech tagging, and named entity - recognition. - -3. Specify the main execution block. - - ```python - if __name__ == "__main__": - ``` - - This Python idiom ensures that the following code block runs only if this - script is the main program. It provides flexibility, allowing the script to - function both as a standalone program and as an imported module. - -4. Create an infinite loop for continuous input. - - ```python - while True: - ``` - - This while loop runs indefinitely until it's explicitly broken. It lets - the user continuously enter text for entity recognition until they decide - to exit. - -5. Get user input. - - ```python - input_text = input("Enter the text for entity recognition (type 'exit' to end): ") - ``` - - This line prompts the user to enter text. The program will then perform entity recognition on this text. - -6. Define an exit condition. - - ```python - if input_text.lower() == 'exit': - print("Exiting...") - break - ``` - - If the user types something, the program converts the input to lowercase and - compares it to `exit`. If they match, the program prints **Exiting...** and - breaks out of the while loop, effectively ending the program. - -7. Perform named entity recognition. - - ```python - doc = nlp(input_text) - - for ent in doc.ents: - print(f"Entity: {ent.text}, Type: {ent.label_}") - ``` - - - `doc = nlp(input_text)`: Here, the nlp model processes the user-input text. This creates a Doc object which contains various NLP attributes, including identified entities. - - `for ent in doc.ents:`: This loop iterates over the entities found in the text. - - `print(f"Entity: {ent.text}, Type: {ent.label_}")`: For each entity, it prints the entity text and its type (like PERSON, ORG, or GPE). - -8. Create `requirements.txt`. - - The sample application already contains the `requirements.txt` file to specify the necessary packages that the application imports. Open `requirements.txt` in a code or text editor to explore its contents. - - ```text - # 02 named_entity_recognition - spacy==3.7.2 - - ... - ``` - - Only the `spacy` package is required for the named recognition application. - -## Explore the application environment - -You'll use Docker to run the application in a container. Docker lets you -containerize the application, providing a consistent and isolated environment -for running it. This means the application will operate as intended within its -Docker container, regardless of the underlying system differences. - -To run the application in a container, a Dockerfile is required. A Dockerfile is -a text document that contains all the commands you would call on the command -line to assemble an image. An image is a read-only template with instructions -for creating a Docker container. - -The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents. - -The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/). - -1. Specify the base image. - - ```dockerfile - FROM python:3.8-slim - ``` - - This command sets the foundation for the build. `python:3.8-slim` is a - lightweight version of the Python 3.8 image, optimized for size and speed. - Using this slim image reduces the overall size of your Docker image, leading - to quicker downloads and less surface area for security vulnerabilities. This - is particularly useful for a Python-based application where you might not - need the full standard Python image. - -2. Set the working directory. - - ```dockerfile - WORKDIR /app - ``` - - `WORKDIR` sets the current working directory within the Docker image. By - setting it to `/app`, you ensure that all subsequent commands in the - Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also - helps in organizing your Docker image, as all application-related files are - contained in a specific directory. - -3. Copy the requirements file into the image. - - ```dockerfile - COPY requirements.txt /app - ``` - - The `COPY` command transfers the `requirements.txt` file from - your local machine into the Docker image. This file lists all Python - dependencies required by the application. Copying it into the container - lets the next command (`RUN pip install`) install these dependencies - inside the image environment. - -4. Install the Python dependencies in the image. - - ```dockerfile - RUN pip install --no-cache-dir -r requirements.txt - ``` - - This line uses `pip`, Python's package installer, to install the packages - listed in `requirements.txt`. The `--no-cache-dir` option disables - the cache, which reduces the size of the Docker image by not storing the - unnecessary cache data. - -5. Run additional commands. - - ```dockerfile - RUN python -m spacy download en_core_web_sm - ``` - - This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. - -6. Copy the application code into the image. - - ```dockerfile - COPY *.py /app - COPY entrypoint.sh /app - ``` - - These commands copy your Python scripts and the `entrypoint.sh` script into - the image's `/app` directory. This is crucial because the container needs - these scripts to run the application. The `entrypoint.sh` script is - particularly important as it dictates how the application starts inside the - container. - -7. Set permissions for the `entrypoint.sh` script. - - ```dockerfile - RUN chmod +x /app/entrypoint.sh - ``` - - This command modifies the file permissions of `entrypoint.sh`, making it - executable. This step is necessary to ensure that the Docker container can - run this script to start the application. - -8. Set the entry point. - - ```dockerfile - ENTRYPOINT ["/app/entrypoint.sh"] - ``` - - The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` - as its default executable. This means that when the container starts, it - automatically executes the script. - - You can explore the `entrypoint.sh` script by opening it in a code or text - editor. As the sample contains several applications, the script lets you - specify which application to run when the container starts. - -## Run the application - -To run the application using Docker: - -1. Build the image. - - In a terminal, run the following command inside the directory of where the `Dockerfile` is located. - - ```console - $ docker build -t basic-nlp . - ``` - - The following is a break down of the command: - - - `docker build`: This is the primary command used to build a Docker image - from a Dockerfile and a context. The context is typically a set of files at - a specified location, often the directory containing the Dockerfile. - - `-t basic-nlp`: This is an option for tagging the image. The `-t` flag - stands for tag. It assigns a name to the image, which in this case is - `basic-nlp`. Tags are a convenient way to reference images later, - especially when pushing them to a registry or running containers. - - `.`: This is the last part of the command and specifies the build context. - The period (`.`) denotes the current directory. Docker will look for a - Dockerfile in this directory. The build context (the current directory, in - this case) is sent to the Docker daemon to enable the build. It includes - all the files and subdirectories in the specified directory. - - For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/). - - Docker outputs several logs to your console as it builds the image. You'll - see it download and install the dependencies. Depending on your network - connection, this may take several minutes. Docker does have a caching - feature, so subsequent builds can be faster. The console will - return to the prompt when it's complete. - -2. Run the image as a container. - - In a terminal, run the following command. - - ```console - $ docker run -it basic-nlp 02_name_entity_recognition.py - ``` - - The following is a break down of the command: - - - `docker run`: This is the primary command used to run a new container from - a Docker image. - - `-it`: This is a combination of two options: - - `-i` or `--interactive`: This keeps the standard input (STDIN) open even - if not attached. It lets the container remain running in the - foreground and be interactive. - - `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a - terminal, like a command prompt or a shell. It's what lets you - interact with the application inside the container. - - `basic-nlp`: This specifies the name of the Docker image to use for - creating the container. In this case, it's the image named `basic-nlp` that - you created with the `docker build` command. - - `02_name_entity_recognition.py`: This is the script you want to run inside - the Docker container. It gets passed to the `entrypoint.sh` script, which - runs it when the container starts. - - For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/). - - > [!NOTE] - > - > For Windows users, you may get an error when running the container. Verify - > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers). - - You will see the following in your console after the container starts. - - ```console - Enter the text for entity recognition (type 'exit' to end): - ``` - -3. Test the application. - - Enter some information to get the named entity recognition. - - ```console - Enter the text for entity recognition (type 'exit' to end): Apple Inc. is planning to open a new store in San Francisco. Tim Cook is the CEO of Apple. - - Entity: Apple Inc., Type: ORG - Entity: San Francisco, Type: GPE - Entity: Tim Cook, Type: PERSON - Entity: Apple, Type: ORG - ``` - -## Summary - -This guide demonstrated how to build and run a named entity recognition -application. You learned how to build the application using Python with spaCy, -and then set up the environment and run the application using Docker. - -Related information: - -- [Docker CLI reference](/reference/cli/docker/) -- [Dockerfile reference](/reference/dockerfile/) -- [spaCy](https://spacy.io/) -- [Python documentation](https://docs.python.org/3/) - -## Next steps - -Explore more [natural language processing guides](./_index.md). diff --git a/content/guides/nextjs.md b/content/guides/nextjs.md new file mode 100644 index 000000000000..790b36744965 --- /dev/null +++ b/content/guides/nextjs.md @@ -0,0 +1,1408 @@ +--- +title: Containerize a Next.js application +linkTitle: Next.js +description: Containerize, develop, and test Next.js apps with Docker +keywords: getting started, Next.js, next.js, docker, language, Dockerfile +summary: | + This guide explains how to containerize Next.js applications and set up + development and testing in containers. +aliases: + - /guides/nextjs/configure-github-actions/ + - /guides/nextjs/containerize/ + - /guides/nextjs/deploy/ + - /guides/nextjs/develop/ + - /guides/nextjs/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +This guide shows you how to containerize a Next.js application using Docker, following best practices for creating efficient, production-ready containers. + +[Next.js](https://nextjs.org/) is a React framework that enables server-side +rendering, static site generation, and full-stack capabilities. Docker +provides a consistent containerized environment from development to +production. + +> **Acknowledgment** +> +> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide and contributing the official [Next.js Docker examples](https://github.com/vercel/next.js/tree/canary/examples/with-docker) to the Vercel Next.js repository, including the standalone and export output examples. As a Docker Captain and experienced engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows. + +--- + +## What will you learn? + +In this guide, you will learn how to: + +- Containerize and run a Next.js application using Docker. +- Set up a local development environment for Next.js inside a container. +- Run tests for your Next.js application within a Docker container. + +To begin, you'll start by containerizing an existing Next.js application. + +--- + +## Prerequisites + +Before you begin, make sure you're familiar with the following: + +- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/). +- Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. +- Familiarity with [React](https://react.dev/) and [Next.js](https://nextjs.org/) fundamentals. +- Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +Once you've completed the Next.js getting started modules, you'll be ready to containerize your own Next.js application using the examples and instructions provided in this guide. + +## Containerize a Next.js Application + +### Prerequisites + +Before you begin, make sure the following tools are installed and available on your system: + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +> [!NOTE] +> New to Docker? Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. + +--- + +### Overview + +This guide walks you through containerizing a Next.js application with Docker. +You'll learn how to create a production-ready Docker image using best +practices that improve performance, security, scalability, and deployment +efficiency. + +By the end of this guide, you will: + +- Containerize a Next.js application using Docker. +- Create and optimize a Dockerfile for production builds. +- Use multi-stage builds to minimize image size. +- Leverage Next.js standalone or export output for efficient containerization. +- Follow best practices for building secure and maintainable Docker images. + +--- + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following command +to clone the git repository: + +```console +$ git clone https://github.com/kristiyan-velkov/docker-nextjs-sample +``` + +--- + +### Build the Docker image + +Next.js has specific requirements for production deployments. This guide shows two approaches: `standalone` output (Node.js server) and `export` output (static files with Nginx). + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +#### Step 1: Configure Next.js and create the Dockerfile + +Before creating a Dockerfile, choose a base image: the [Node.js Official Image](https://hub.docker.com/_/node) or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog) from the Hardened Image catalog. Choosing DHI gives you a production-ready, lightweight, and secure image. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +> [!IMPORTANT] +> This guide uses stable Node.js LTS image tags that are considered secure when the guide is written. Because new releases and security patches are published regularly, always review the [official Node.js Docker images](https://hub.docker.com/_/node) and select a secure, up-to-date version before building or deploying. + +--- + +##### 1.1 Next.js with standalone output + +Standalone output (`output: "standalone"`) makes Next.js build a self-contained output that includes only the files and dependencies needed to run the application. A single `node server.js` can serve the app, which is ideal for Docker and supports server-side rendering, API routes, and incremental static regeneration. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) (including the "standalone" option). + +The container runs the Next.js server with Node.js on port 3000. + +Configure Next.js — Open or create `next.config.ts` in your project root: + +```ts +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + output: "standalone", +}; + +export default nextConfig; +``` + +Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Node.js DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/node:24-alpine3.22-dev + ``` + +3. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use `dhi.io/node:24-alpine3.22-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility. + + ```dockerfile + # ============================================ + # Stage 1: Dependencies Installation Stage + # ============================================ + + # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance + # This Dockerfile uses dhi.io/node. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility. + + FROM dhi.io/node:24-alpine3.22-dev AS dependencies + + # Set working directory + WORKDIR /app + + # Copy package-related files first to leverage Docker's caching mechanism + COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ + + # Install project dependencies with frozen lockfile for reproducible builds + RUN --mount=type=cache,target=/root/.npm \ + --mount=type=cache,target=/usr/local/share/.cache/yarn \ + --mount=type=cache,target=/root/.local/share/pnpm/store \ + if [ -f package-lock.json ]; then \ + npm ci --no-audit --no-fund; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn install --frozen-lockfile --production=false; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm install --frozen-lockfile; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ============================================ + # Stage 2: Build Next.js application in standalone mode + # ============================================ + + FROM dhi.io/node:24-alpine3.22-dev AS builder + + # Set working directory + WORKDIR /app + + # Copy project dependencies from dependencies stage + COPY --from=dependencies /app/node_modules ./node_modules + + # Copy application source code + COPY . . + + ENV NODE_ENV=production + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the build. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Build Next.js application + # If you want to speed up Docker rebuilds, you can cache the build artifacts + # by adding: --mount=type=cache,target=/app/.next/cache + # This caches the .next/cache directory across builds, but it also prevents + # .next/cache/fetch-cache from being included in the final image, meaning + # cached fetch responses from the build won't be available at runtime. + RUN if [ -f package-lock.json ]; then \ + npm run build; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn build; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm build; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ============================================ + # Stage 3: Run Next.js application + # ============================================ + + FROM dhi.io/node:24-alpine3.22-dev AS runner + + # Set working directory + WORKDIR /app + + # Set production environment variables + ENV NODE_ENV=production + ENV PORT=3000 + ENV HOSTNAME="0.0.0.0" + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the run time. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Copy production assets + COPY --from=builder --chown=node:node /app/public ./public + + # Set the correct permission for prerender cache + RUN mkdir .next + RUN chown node:node .next + + # Automatically leverage output traces to reduce image size + # https://nextjs.org/docs/advanced-features/output-file-tracing + COPY --from=builder --chown=node:node /app/.next/standalone ./ + COPY --from=builder --chown=node:node /app/.next/static ./.next/static + + # If you want to persist the fetch cache generated during the build so that + # cached responses are available immediately on startup, uncomment this line: + # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache + + # Switch to non-root user for security best practices + USER node + + # Expose port 3000 to allow HTTP traffic + EXPOSE 3000 + + # Start Next.js standalone server + CMD ["node", "server.js"] + ``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Image" >}} + +Create a file named `Dockerfile` with the following contents (uses `node`): + +```dockerfile + # ============================================ + # Stage 1: Dependencies Installation Stage + # ============================================ + + ARG NODE_VERSION=24.14.0-slim + + FROM node:${NODE_VERSION} AS dependencies + + # Set working directory + WORKDIR /app + + # Copy package-related files first to leverage Docker's caching mechanism + COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ + + # Install project dependencies with frozen lockfile for reproducible builds + RUN --mount=type=cache,target=/root/.npm \ + --mount=type=cache,target=/usr/local/share/.cache/yarn \ + --mount=type=cache,target=/root/.local/share/pnpm/store \ + if [ -f package-lock.json ]; then \ + npm ci --no-audit --no-fund; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn install --frozen-lockfile --production=false; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm install --frozen-lockfile; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ============================================ + # Stage 2: Build Next.js application in standalone mode + # ============================================ + + FROM node:${NODE_VERSION} AS builder + + # Set working directory + WORKDIR /app + + # Copy project dependencies from dependencies stage + COPY --from=dependencies /app/node_modules ./node_modules + + # Copy application source code + COPY . . + + ENV NODE_ENV=production + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the build. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Build Next.js application + # If you want to speed up Docker rebuilds, you can cache the build artifacts + # by adding: --mount=type=cache,target=/app/.next/cache + # This caches the .next/cache directory across builds, but it also prevents + # .next/cache/fetch-cache from being included in the final image, meaning + # cached fetch responses from the build won't be available at runtime. + RUN if [ -f package-lock.json ]; then \ + npm run build; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn build; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm build; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ============================================ + # Stage 3: Run Next.js application + # ============================================ + + FROM node:${NODE_VERSION} AS runner + + # Set working directory + WORKDIR /app + + # Set production environment variables + ENV NODE_ENV=production + ENV PORT=3000 + ENV HOSTNAME="0.0.0.0" + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the run time. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Copy production assets + COPY --from=builder --chown=node:node /app/public ./public + + # Set the correct permission for prerender cache + RUN mkdir .next + RUN chown node:node .next + + # Automatically leverage output traces to reduce image size + # https://nextjs.org/docs/advanced-features/output-file-tracing + COPY --from=builder --chown=node:node /app/.next/standalone ./ + COPY --from=builder --chown=node:node /app/.next/static ./.next/static + + # If you want to persist the fetch cache generated during the build so that + # cached responses are available immediately on startup, uncomment this line: + # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache + + # Switch to non-root user for security best practices + USER node + + # Expose port 3000 to allow HTTP traffic + EXPOSE 3000 + + # Start Next.js standalone server + CMD ["node", "server.js"] +``` + +> [!NOTE] +> This Dockerfile uses three stages: `dependencies`, `builder`, and `runner`. The final image runs `node server.js` and listens on port 3000. + +{{< /tab >}} +{{< /tabs >}} + +--- + +##### 1.2 Next.js with export output + +Output export (`output: "export"`) makes Next.js build a fully static site at build time. It generates HTML, CSS, and JavaScript into an `out` directory that can be served by any static host or CDN—no Node.js server at runtime. Use this when you don't need server-side rendering or API routes. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output). + +Configure Next.js — Open `next.config.ts` in your project root and add the following code: + +```ts +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + output: "export", + trailingSlash: true, + images: { + unoptimized: true, + }, +}; + +export default nextConfig; +``` + +Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) are available for Node.js and Nginx in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog). For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Node.js DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/node:24-alpine3.22-dev + ``` + +3. Pull the Nginx DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev + ``` + +4. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use Docker Hardened Images: `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility. + + ```dockerfile + # ============================================ + # Stage 1: Dependencies Installation Stage + # ============================================ + + # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance + # This Dockerfile uses dhi.io/node and dhi.io/nginx. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility. + + FROM dhi.io/node:24-alpine3.22-dev AS dependencies + + # Set the working directory + WORKDIR /app + + # Copy package-related files first to leverage Docker's caching mechanism + COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ + + # Install project dependencies with frozen lockfile for reproducible builds + RUN --mount=type=cache,target=/root/.npm \ + --mount=type=cache,target=/usr/local/share/.cache/yarn \ + --mount=type=cache,target=/root/.local/share/pnpm/store \ + if [ -f package-lock.json ]; then \ + npm ci --no-audit --no-fund; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn install --frozen-lockfile --production=false; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm install --frozen-lockfile; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ============================================ + # Stage 2: Build Next.js Application + # ============================================ + + FROM dhi.io/node:24-alpine3.22-dev AS builder + + # Set the working directory + WORKDIR /app + + # Copy project dependencies from dependencies stage + COPY --from=dependencies /app/node_modules ./node_modules + + # Copy application source code + COPY . . + + ENV NODE_ENV=production + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the build. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Build Next.js application + RUN --mount=type=cache,target=/app/.next/cache \ + if [ -f package-lock.json ]; then \ + npm run build; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn build; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm build; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + + # ========================================= + # Stage 3: Serve Static Files with Nginx + # ========================================= + + FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner + + # Set the working directory + WORKDIR /app + + # Next.js collects completely anonymous telemetry data about general usage. + # Learn more here: https://nextjs.org/telemetry + # Uncomment the following line in case you want to disable telemetry during the run time. + # ENV NEXT_TELEMETRY_DISABLED=1 + + # Copy custom Nginx config + COPY nginx.conf /etc/nginx/nginx.conf + + # Copy the static build output from the build stage to Nginx's default HTML serving directory + COPY --chown=nginx:nginx --from=builder /app/out /usr/share/nginx/html + + # Non-root user for security best practices + USER nginx + + # Expose port 8080 to allow HTTP traffic + EXPOSE 8080 + + # Start Nginx directly with custom config + ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] + CMD ["-g", "daemon off;"] + ``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Image" >}} + +Create a file named `Dockerfile` with the following contents (uses `node` and `nginxinc/nginx-unprivileged`): + +```dockerfile +# ============================================ +# Stage 1: Dependencies Installation Stage +# ============================================ + +ARG NODE_VERSION=24.14.0-slim +ARG NGINXINC_IMAGE_TAG=alpine3.22 + +FROM node:${NODE_VERSION} AS dependencies + +# Set the working directory +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ + +# Install project dependencies with frozen lockfile for reproducible builds +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=cache,target=/usr/local/share/.cache/yarn \ + --mount=type=cache,target=/root/.local/share/pnpm/store \ + if [ -f package-lock.json ]; then \ + npm ci --no-audit --no-fund; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn install --frozen-lockfile --production=false; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm install --frozen-lockfile; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + +# ============================================ +# Stage 2: Build Next.js Application +# ============================================ + +FROM node:${NODE_VERSION} AS builder + +# Set the working directory +WORKDIR /app + +# Copy project dependencies from dependencies stage +COPY --from=dependencies /app/node_modules ./node_modules + +# Copy application source code +COPY . . + +ENV NODE_ENV=production + +# Next.js collects completely anonymous telemetry data about general usage. +# Learn more here: https://nextjs.org/telemetry +# Uncomment the following line in case you want to disable telemetry during the build. +# ENV NEXT_TELEMETRY_DISABLED=1 + +# Build Next.js application +RUN --mount=type=cache,target=/app/.next/cache \ + if [ -f package-lock.json ]; then \ + npm run build; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn build; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm build; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + +# ========================================= +# Stage 3: Serve Static Files with Nginx +# ========================================= + +FROM nginxinc/nginx-unprivileged:${NGINXINC_IMAGE_TAG} AS runner + +# Set the working directory +WORKDIR /app + +# Next.js collects completely anonymous telemetry data about general usage. +# Learn more here: https://nextjs.org/telemetry +# Uncomment the following line in case you want to disable telemetry during the run time. +# ENV NEXT_TELEMETRY_DISABLED=1 + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --from=builder /app/out /usr/share/nginx/html + +# Non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +> [!NOTE] +> This guide uses [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) instead of the standard Nginx image to run as a non-root user, following security best practices. + +{{< /tab >}} +{{< /tabs >}} + +1. Create `nginx.conf` (required for export output only) — Create a file named `nginx.conf` in the root of your project: + + ```nginx + # Minimal Nginx config for static Next.js app + worker_processes 1; + + # Store PID in /tmp (always writable) + pid /tmp/nginx.pid; + + events { + worker_connections 1024; + } + + http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + # Disable logging to avoid permission issues + access_log off; + error_log /dev/stderr; + + # Optimize static file serving + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + + # Gzip compression + gzip on; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; + gzip_min_length 256; + + server { + listen 8080; + server_name localhost; + + # Serve static files + root /usr/share/nginx/html; + index index.html; + + # Handle Next.js static export routing + # See: https://nextjs.org/docs/app/guides/static-exports#deploying + location / { + try_files $uri $uri.html $uri/ =404; + } + + # This is necessary when `trailingSlash: false` (default). + # You can omit this when `trailingSlash: true` in next.config. + # Handles nested routes like /blog/post -> /blog/post.html + location ~ ^/(.+)/$ { + rewrite ^/(.+)/$ /$1.html break; + } + + # Serve Next.js static assets + location ~ ^/_next/ { + try_files $uri =404; + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # Optional 404 handling + error_page 404 /404.html; + location = /404.html { + internal; + } + } + } + ``` + + > [!NOTE] + > Export uses port 8080. For more details, see the [Next.js output configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) and [Nginx documentation](https://nginx.org/en/docs/). + +#### Step 2: Create the compose.yaml file + +Create a file named `compose.yaml` with the following contents: + +```yaml {collapse=true,title=compose.yaml} +services: + server: + build: + context: . + ports: + - 3000:3000 +``` + +> [!NOTE] +> If using export output (Nginx), change the port mapping to `8080:8080`. + +#### Step 3: Create the .dockerignore file + +The `.dockerignore` file tells Docker which files and folders to exclude when building the image. + +> [!NOTE] +> This helps: +> +> - Reduce image size +> - Speed up the build process +> - Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. +> +> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). + +Create a file named `.dockerignore` with the following contents: + +```dockerignore +# Dependencies (installed inside the image, never copy from host) +node_modules/ +.pnp/ +.pnp.js +.pnpm-store/ + +# Next.js build output (generated during the image build) +.next/ +out/ +dist/ +build/ +.vercel/ + +# Testing (not needed in the production image) +coverage/ +.nyc_output/ +__tests__/ +__mocks__/ +jest/ +cypress/ +playwright-report/ +test-results/ +.vitest/ + +# Environment files (avoid leaking secrets into the build context) +.env +.env* +.env.local +.env.development.local +.env.test.local +.env.production.local + +# Debug and log files +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* +*.log + +# IDE and editor files +.vscode/ +.idea/ +.cursor/ +.cursorrules +.copilot/ +*.swp +*.swo +*~ + +# Git +.git/ +.gitignore +.gitattributes + +# Docker files (reduce build context; not needed inside the image) +Dockerfile* +.dockerignore +docker-compose*.yml +compose*.yaml + +# Documentation (not needed in the image) +*.md +docs/ + +# CI/CD (not needed in the image) +.github/ +.gitlab-ci.yml +.travis.yml +.circleci/ +Jenkinsfile + +# TypeScript and build metadata +*.tsbuildinfo + +# Cache and temporary directories +.cache/ +.parcel-cache/ +.eslintcache +.stylelintcache +.turbo/ +.tmp/ +.temp/ + +# Sensitive or dev-only config (optional; omit if your build needs these) +.pem +.editorconfig +.prettierrc* +.eslintrc* +.stylelintrc* +.babelrc* +*.iml + +# OS-specific files +.DS_Store +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db +Desktop.ini +``` + +#### Step 4: Build the Next.js application image + +With your custom configuration in place, you're now ready to build the Docker image. Use the Dockerfile you created in Step 1 (standalone or export). + +The setup includes: + +- Multi-stage builds for optimized image size +- Standalone: Node.js server on port 3000; Export: Nginx serving static files on port 8080 +- Non-root user for enhanced security +- Proper file permissions and ownership + +After completing the previous steps, your project directory should contain at least the following files (export also requires `nginx.conf`): + +```text +├── docker-nextjs-sample/ +│ ├── Dockerfile +│ ├── .dockerignore +│ ├── compose.yaml +│ └── next.config.ts +``` + +Now that your Dockerfile is configured, you can build the Docker image for your Next.js application. + +> [!NOTE] +> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). + +Run the following command from the root of your project: + +```console +$ docker build --tag nextjs-sample . +``` + +What this command does: + +- Uses the Dockerfile in the current directory (.) +- Packages the application and its dependencies into a Docker image +- Tags the image as nextjs-sample so you can reference it later + +#### Step 5: View local images + +After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. + +To list all locally available Docker images, run the following command: + +```console +$ docker images +``` + +Example Output: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +nextjs-sample latest 8c5fc80f098e 14 seconds ago 130MB +``` + +This output provides key details about your images: + +- Repository – The name assigned to the image. +- Tag – A version label that helps identify different builds (e.g., latest). +- Image ID – A unique identifier for the image. +- Created – The timestamp indicating when the image was built. +- Size – The total disk space used by the image. + +If the build was successful, you should see `nextjs-sample` image listed. + +--- + +### Run the containerized application + +In the previous step, you created a Dockerfile for your Next.js application and built a Docker image using the docker build command. Now it's time to run that image in a container and verify that your application works as expected. + +Run the following command in a terminal. Use the port that matches your setup: standalone uses port 3000, export uses port 8080. + +```console +$ docker run -p 3000:3000 nextjs-sample +``` + +For export output, use port 8080 instead: + +```console +$ docker run -p 8080:8080 nextjs-sample +``` + +Open a browser and view the application: [http://localhost:3000](http://localhost:3000) for standalone or [http://localhost:8080](http://localhost:8080) for export. You should see your Next.js web application. + +Press `ctrl+c` in the terminal to stop your application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` option and `--name` to give the container a name so you can stop it later: + +```console +$ docker run -d -p 3000:3000 --name nextjs-app nextjs-sample +``` + +For export output, use port 8080: + +```console +$ docker run -d -p 8080:8080 --name nextjs-app nextjs-sample +``` + +Open a browser and view the application: [http://localhost:3000](http://localhost:3000) for standalone or [http://localhost:8080](http://localhost:8080) for export. You should see your web application. + +To confirm that the container is running, use the `docker ps` command: + +```console +$ docker ps +``` + +This will list all active containers along with their ports, names, and status. Look for a container exposing port 3000 (standalone) or 8080 (export). + +Example Output: + +```shell +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +f49b74736a9d nextjs-sample "node server.js" About a minute ago Up About a minute 0.0.0.0:3000->3000/tcp nextjs-app +``` + +To stop the application, run: + +```console +$ docker stop nextjs-app +``` + +> [!NOTE] +> For more information about running containers, see the [`docker run` CLI reference](/reference/cli/docker/container/run/) and the [`docker stop` CLI reference](/reference/cli/docker/container/stop/). + +--- + +## Use containers for Next.js development + +### Prerequisites + +Complete [Containerize Next.js application](#containerize-a-nextjs-application). + +--- + +### Overview + +In this section, you'll learn how to set up both production and development environments for your containerized Next.js application using Docker Compose. This setup allows you to run a production build using the standalone server and to develop efficiently inside containers using Next.js's built-in hot reloading with Compose Watch. + +You'll learn how to: + +- Configure separate containers for production and development +- Enable automatic file syncing using Compose Watch in development +- Debug and live-preview your changes in real-time without manual rebuilds + +--- + +### Automatically update services (development mode) + +Use Compose Watch to automatically sync source file changes into your +containerized development environment. This automatically syncs file changes +without needing to restart or rebuild containers manually. + +### Step 1: Create a development Dockerfile + +Create a file named `Dockerfile.dev` in your project root with the following content (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)): + +```dockerfile +# ============================================ +# Development Dockerfile for Next.js +# ============================================ +ARG NODE_VERSION=24.14.0-slim + +FROM node:${NODE_VERSION} AS dev + +WORKDIR /app + +COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ + +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=cache,target=/usr/local/share/.cache/yarn \ + --mount=type=cache,target=/root/.local/share/pnpm/store \ + if [ -f package-lock.json ]; then \ + npm ci --no-audit --no-fund; \ + elif [ -f yarn.lock ]; then \ + corepack enable yarn && yarn install --frozen-lockfile --production=false; \ + elif [ -f pnpm-lock.yaml ]; then \ + corepack enable pnpm && pnpm install --frozen-lockfile; \ + else \ + echo "No lockfile found." && exit 1; \ + fi + +COPY . . + +ENV WATCHPACK_POLLING=true +ENV HOSTNAME="0.0.0.0" + +RUN chown -R node:node /app +USER node + +EXPOSE 3000 + +CMD ["sh", "-c", "if [ -f package-lock.json ]; then npm run dev; elif [ -f yarn.lock ]; then yarn dev; elif [ -f pnpm-lock.yaml ]; then pnpm dev; else npm run dev; fi"] +``` + +This file sets up a development environment for your Next.js app with hot module replacement and supports npm, yarn, and pnpm. + +#### Step 2: Update your `compose.yaml` file + +Open your `compose.yaml` file and define two services: one for production (`nextjs-prod-standalone`) and one for development (`nextjs-dev`). This matches the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) structure. + +Here's an example configuration for a Next.js application: + +```yaml +services: + nextjs-prod-standalone: + build: + context: . + dockerfile: Dockerfile + image: nextjs-sample:prod + container_name: nextjs-sample-prod + ports: + - "3000:3000" + + nextjs-dev: + build: + context: . + dockerfile: Dockerfile.dev + image: nextjs-sample:dev + container_name: nextjs-sample-dev + ports: + - "3000:3000" + environment: + - WATCHPACK_POLLING=true + develop: + watch: + - action: sync + path: . + target: /app + ignore: + - node_modules/ + - .next/ + - action: rebuild + path: package.json +``` + +- The `nextjs-prod-standalone` service builds and runs your production Next.js app using the standalone output. +- The `nextjs-dev` service runs your Next.js development server with hot module replacement. +- `watch` triggers file sync with Compose Watch. +- `WATCHPACK_POLLING=true` ensures file changes are detected properly inside Docker. +- The `rebuild` action for `package.json` ensures dependencies are reinstalled when the file changes. + +> [!NOTE] +> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +#### Step 3: Configure Next.js for Docker development + +Next.js works well inside Docker containers out of the box, but there are a few configurations that can improve the development experience. + +The `next.config.ts` file you created during containerization already includes the `output: "standalone"` option for production. For development, Next.js automatically uses its built-in development server with hot reloading enabled. + +> [!NOTE] +> The Next.js development server automatically: +> +> - Enables Hot Module Replacement (HMR) for instant updates +> - Watches for file changes and recompiles automatically +> - Provides detailed error messages in the browser +> +> The `WATCHPACK_POLLING=true` environment variable in the compose file ensures file watching works correctly inside Docker containers. + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-nextjs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── next.config.ts +``` + +#### Step 4: Start Compose Watch + +Run the following command from your project root to start your container in watch mode: + +```console +$ docker compose watch nextjs-dev +``` + +#### Step 5: Test Compose Watch with Next.js + +To verify that Compose Watch is working correctly: + +1. Open the `app/page.tsx` file in your text editor (or `src/app/page.tsx` if your project uses a `src` directory). + +2. Locate the main content area and find a text element to modify. + +3. Make a visible change, for example, update a heading: + + ```tsx + <h1>Hello from Docker Compose Watch!</h1> + ``` + +4. Save the file. + +5. Open your browser at [http://localhost:3000](http://localhost:3000). + +You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. + +--- + +## Run Next.js tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize Next.js application](#containerize-a-nextjs-application). + +### Overview + +Testing is a critical part of the development process. In this section, you'll learn how to: + +- Run unit tests using Vitest (or Jest) inside a Docker container. +- Run lint (e.g. ESLint) inside a Docker container. +- Use Docker Compose to run tests and lint in an isolated, reproducible environment. + +The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) uses [Vitest](https://vitest.dev/) with [Testing Library](https://testing-library.com/) for component testing. You can use the same setup or follow the alternative Jest configuration later. + +--- + +### Run tests during development + +The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) already includes lint (ESLint) and sample tests (Vitest, `app/page.test.tsx`) in place. If you're using the sample app, you can skip to **Step 3: Update compose.yaml** and run tests or lint with the commands below. If you're using your own project, follow the install and configuration steps to add the packages and scripts. + +The sample includes a test file at: + +```text +app/page.test.tsx +``` + +This file uses Vitest and React Testing Library to verify the behavior of page components. + +#### Step 1: Install Vitest and React Testing Library (custom projects) + +If you're using a custom project and haven't already added the necessary testing tools, install them by running: + +```console +$ npm install --save-dev vitest @vitejs/plugin-react @testing-library/react @testing-library/dom jsdom +``` + +Then, update the scripts section of your `package.json` file to include: + +```json +"scripts": { + "test": "vitest", + "test:run": "vitest run" +} +``` + +For lint, add a `lint` script (and optionally `lint:fix`). For example, with [ESLint](https://eslint.org/): + +```json +"scripts": { + "test": "vitest", + "test:run": "vitest run", + "lint": "eslint .", + "lint:fix": "eslint . --fix" +} +``` + +The sample project uses `eslint` and `eslint-config-next` for Next.js. Install them in a custom project with: + +```console +$ npm install --save-dev eslint eslint-config-next @eslint/eslintrc +``` + +Create an ESLint config file (e.g. `eslint.config.cjs`) in your project root with Next.js rules and global ignores: + +```js +const { defineConfig, globalIgnores } = require("eslint/config"); +const { FlatCompat } = require("@eslint/eslintrc"); + +const compat = new FlatCompat({ baseDirectory: __dirname }); + +module.exports = defineConfig([ + ...compat.extends( + "eslint-config-next/core-web-vitals", + "eslint-config-next/typescript", + ), + globalIgnores([ + ".next/**", + "out/**", + "build/**", + "next-env.d.ts", + "node_modules/**", + "eslint.config.cjs", + ]), +]); +``` + +--- + +#### Step 2: Configure Vitest (custom projects) + +If you're using a custom project, create a `vitest.config.ts` file in your project root (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)): + +```ts +import { defineConfig } from "vitest/config"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + plugins: [react()], + test: { + environment: "jsdom", + setupFiles: "./vitest.setup.ts", + globals: true, + }, +}); +``` + +Create a `vitest.setup.ts` file in your project root: + +```ts +import "@testing-library/jest-dom/vitest"; +``` + +> [!NOTE] +> Vitest works well with Next.js and provides fast execution and ESM support. For more details, see the [Next.js testing documentation](https://nextjs.org/docs/app/building-your-application/testing) and [Vitest docs](https://vitest.dev/). + +#### Step 3: Update compose.yaml + +Add `nextjs-test` and `nextjs-lint` services to your `compose.yaml` file. In the sample project these services use the `tools` profile so they don't start with a normal `docker compose up`. Both reuse `Dockerfile.dev` and run the test or lint command: + +```yaml +services: + nextjs-prod-standalone: + build: + context: . + dockerfile: Dockerfile + image: nextjs-sample:prod + container_name: nextjs-sample-prod + ports: + - "3000:3000" + + nextjs-dev: + build: + context: . + dockerfile: Dockerfile.dev + image: nextjs-sample:dev + container_name: nextjs-sample-dev + ports: + - "3000:3000" + environment: + - WATCHPACK_POLLING=true + develop: + watch: + - action: sync + path: . + target: /app + ignore: + - node_modules/ + - .next/ + - action: rebuild + path: package.json + + nextjs-test: + build: + context: . + dockerfile: Dockerfile.dev + image: nextjs-sample:dev + container_name: nextjs-sample-test + command: + [ + "sh", + "-c", + "if [ -f package-lock.json ]; then npm run test:run 2>/dev/null || npm run test -- --run; elif [ -f yarn.lock ]; then yarn test:run 2>/dev/null || yarn test --run; elif [ -f pnpm-lock.yaml ]; then pnpm run test:run; else npm run test -- --run; fi", + ] + profiles: + - tools + + nextjs-lint: + build: + context: . + dockerfile: Dockerfile.dev + image: nextjs-sample:dev + container_name: nextjs-sample-lint + command: + [ + "sh", + "-c", + "if [ -f package-lock.json ]; then npm run lint; elif [ -f yarn.lock ]; then yarn lint; elif [ -f pnpm-lock.yaml ]; then pnpm lint; else npm run lint; fi", + ] + profiles: + - tools +``` + +The `nextjs-test` and `nextjs-lint` services reuse the same `Dockerfile.dev` used for [development](#use-containers-for-nextjs-development) and override the default command to run tests or lint. The `profiles: [tools]` means these services only run when you use the `--profile tools` option. + +After completing the previous steps, your project directory should contain: + +```text +├── docker-nextjs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ ├── vitest.config.ts +│ ├── vitest.setup.ts +│ └── next.config.ts +``` + +#### Step 4: Run the tests + +To execute your test suite inside the container, run from your project root: + +```console +$ docker compose --profile tools run --rm nextjs-test +``` + +This command will: + +- Start the `nextjs-test` service (because of `--profile tools`). +- Run your test script (`test:run` or `test -- --run`) in the same environment as development. +- Remove the container after the tests complete ([`docker compose run --rm`](/reference/cli/docker/compose/run/)). + +> [!NOTE] +> For more information about Compose commands and profiles, see the [Compose CLI reference](/reference/cli/docker/compose/). + +#### Step 5: Run lint in the container + +To run your linter (e.g. ESLint) inside the container, use the `nextjs-lint` service with the same `tools` profile: + +```console +$ docker compose --profile tools run --rm nextjs-lint +``` + +This command will: + +- Start the `nextjs-lint` service (because of `--profile tools`). +- Run your lint script (`npm run lint`, `yarn lint`, or `pnpm lint` depending on your lockfile) in the same environment as development. +- Remove the container after lint completes. + +Ensure your `package.json` includes a `lint` script. The sample project already has `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`; for a custom project, add the same and install `eslint` and `eslint-config-next` if needed. + +--- + +### Summary + +In this section, you learned how to run unit tests for your Next.js application inside a Docker container using Vitest and Docker Compose. + +What you accomplished: + +- Installed and configured Vitest and React Testing Library for testing Next.js components. +- Created `nextjs-test` and `nextjs-lint` services in `compose.yaml` (with `tools` profile) to isolate test and lint execution. +- Reused the development `Dockerfile.dev` to ensure consistency between dev, test, and lint environments. +- Ran tests inside the container using `docker compose --profile tools run --rm nextjs-test`. +- Ran lint inside the container using `docker compose --profile tools run --rm nextjs-lint`. +- Ensured reliable, repeatable testing and linting across environments without relying on local machine setup. + +--- + +### Related resources + +Explore official references and best practices to sharpen your Docker testing workflow: + +- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. +- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. +- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. +- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. +- [Next.js Testing Documentation](https://nextjs.org/docs/app/building-your-application/testing) – Official Next.js testing guide. diff --git a/content/guides/nextjs/_index.md b/content/guides/nextjs/_index.md deleted file mode 100644 index 995744c5c099..000000000000 --- a/content/guides/nextjs/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Containerize a Next.js application -linkTitle: Next.js -description: Containerize, develop, test, and deploy Next.js apps with Docker and Kubernetes -keywords: getting started, Next.js, next.js, docker, language, Dockerfile, CI/CD, Kubernetes -summary: | - This guide explains how to containerize Next.js applications, set up - development and testing in containers, automate builds with GitHub Actions, - and deploy to Kubernetes. -toc_min: 1 -toc_max: 2 -languages: [js] -tags: [frameworks] -params: - time: 20 minutes ---- - -This guide shows you how to containerize a Next.js application using Docker, following best practices for creating efficient, production-ready containers. - -[Next.js](https://nextjs.org/) is a React framework that enables server-side -rendering, static site generation, and full-stack capabilities. Docker -provides a consistent containerized environment from development to -production. - -> **Acknowledgment** -> -> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide and contributing the official [Next.js Docker examples](https://github.com/vercel/next.js/tree/canary/examples/with-docker) to the Vercel Next.js repository, including the standalone and export output examples. As a Docker Captain and experienced engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows. - ---- - -## What will you learn? - -In this guide, you will learn how to: - -- Containerize and run a Next.js application using Docker. -- Set up a local development environment for Next.js inside a container. -- Run tests for your Next.js application within a Docker container. -- Configure a CI/CD pipeline using GitHub Actions for your containerized app. -- Deploy the containerized Next.js application to a local Kubernetes cluster for testing and debugging. - -To begin, you'll start by containerizing an existing Next.js application. - ---- - -## Prerequisites - -Before you begin, make sure you're familiar with the following: - -- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/). -- Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. -- Familiarity with [React](https://react.dev/) and [Next.js](https://nextjs.org/) fundamentals. -- Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -Once you've completed the Next.js getting started modules, you'll be ready to containerize your own Next.js application using the examples and instructions provided in this guide. diff --git a/content/guides/nextjs/configure-github-actions.md b/content/guides/nextjs/configure-github-actions.md deleted file mode 100644 index 2484e5a11b78..000000000000 --- a/content/guides/nextjs/configure-github-actions.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 60 -keywords: CI/CD, GitHub Actions, Next.js -description: Learn how to configure CI/CD using GitHub Actions for your Next.js application. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize Next.js application](containerize.md). - -You must also have: -- A [GitHub](https://github.com/signup) account. -- A verified [Docker Hub](https://hub.docker.com/signup) account. - ---- - -## Overview - -In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically: - -- Build your Next.js application inside a Docker container. -- Run tests in a consistent environment. -- Push the production-ready image to [Docker Hub](https://hub.docker.com). - ---- - -## Integrate GitHub and Docker Hub - -To enable GitHub Actions to build and push Docker images, you'll securely -store your Docker Hub credentials in your new GitHub repository. - -### Step 1: Connect your GitHub repository to Docker Hub - -1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com) - 1. Go to your **Docker Hub account → Account Settings → Security**. - 2. Generate a new Access Token with **Read/Write** permissions. - 3. Name it something like `nextjs-sample`. - 4. Copy and save the token — you'll need it in Step 4. - -2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/) - 1. Go to your **Docker Hub account → Create a repository**. - 2. For the Repository Name, use something descriptive — for example: `nextjs-sample`. - 3. Once created, copy and save the repository name — you'll need it in Step 4. - -3. Create a new [GitHub repository](https://github.com/new) for your Next.js project - -4. Add Docker Hub credentials as GitHub repository secrets - - In your newly created GitHub repository: - - 1. Navigate to: - **Settings → Secrets and variables → Actions → New repository secret**. - - 2. Add the following secrets: - - | Name | Value | - |-------------------|--------------------------------| - | `DOCKER_USERNAME` | Your Docker Hub username | - | `DOCKERHUB_TOKEN` | Your Docker Hub access token (created in Step 1) | - | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2) | - - These secrets let GitHub Actions authenticate securely with Docker Hub - during automated workflows. - -5. Connect Your Local Project to GitHub - - Link your local project to the GitHub repository you just created by running the following command from your project root: - - ```console - $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git - ``` - - >[!IMPORTANT] - >Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name. - - To confirm that your local project is correctly connected to the remote GitHub repository, run: - - ```console - $ git remote -v - ``` - - You should see output similar to: - - ```console - origin https://github.com/{your-username}/{your-repository-name}.git (fetch) - origin https://github.com/{your-username}/{your-repository-name}.git (push) - ``` - - This confirms that your local repository is properly linked and ready to push your source code to GitHub. - -6. Push Your Source Code to GitHub - - Follow these steps to commit and push your local project to your GitHub repository: - - 1. Stage all files for commit. - - ```console - $ git add -A - ``` - This command stages all changes — including new, modified, and deleted files — preparing them for commit. - - - 2. Commit your changes. - - ```console - $ git commit -m "Initial commit" - ``` - This command creates a commit that snapshots the staged changes with a descriptive message. - - 3. Push the code to the `main` branch. - - ```console - $ git push -u origin main - ``` - This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch. - -Once completed, your code will be available on GitHub, and any GitHub Actions workflow you've configured will run automatically. - -> [!NOTE] -> Learn more about the Git commands used in this step: -> - [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit -> - [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes -> - [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository -> - [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs - ---- - -### Step 2: Set up the workflow - -Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub. - -1. Go to your repository on GitHub and select the **Actions** tab in the top menu. - -2. Select **Set up a workflow yourself** when prompted. - - This opens an inline editor to create a new workflow file. By default, it will be saved to: - `.github/workflows/main.yml` - - -3. Add the following workflow configuration to the new file: - -```yaml -# CI/CD – Next.js Application with Docker -# Builds the app, runs tests in a container, and pushes the production image to Docker Hub. - -name: CI/CD – Next.js Application with Docker - -on: - push: - branches: [main] - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - -jobs: - build-test-push: - name: Build, Test and Push Docker Image - runs-on: ubuntu-latest - - steps: - # 1. Checkout source code - - name: Checkout source code - uses: actions/checkout@v5 - with: - fetch-depth: 0 - - # 2. Set up Docker Buildx - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v4 - - # 3. Cache Docker layers - - name: Cache Docker layers - uses: actions/cache@v5 - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: ${{ runner.os }}-buildx- - - # 4. Cache pnpm dependencies - - name: Cache pnpm dependencies - uses: actions/cache@v4 - with: - path: ~/.local/share/pnpm/store - key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }} - restore-keys: ${{ runner.os }}-pnpm- - - # 5. Extract metadata - - name: Extract metadata - id: meta - run: | - echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT" - echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT" - - # 6. Build dev Docker image (for running tests) - - name: Build Docker image for tests - uses: docker/build-push-action@v6 - with: - context: . - file: Dockerfile.dev - tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest - load: true - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - - # 7. Run Vitest tests inside the container - # Use same package-manager detection as Dockerfile (no corepack at runtime; node user can't write to /usr/local/bin) - - name: Run tests - run: | - docker run --rm \ - --workdir /app \ - --entrypoint "" \ - -e CI=true \ - ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \ - sh -c "if [ -f package-lock.json ]; then npm run test:run; elif [ -f yarn.lock ]; then yarn test:run; elif [ -f pnpm-lock.yaml ]; then pnpm run test:run; else npm run test:run; fi" - env: - CI: true - NODE_ENV: test - timeout-minutes: 10 - - # 8. Log in to Docker Hub (only needed for push) - - name: Log in to Docker Hub - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - uses: docker/login-action@v3 - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - # 9. Build and push production image (only on push to main) - - name: Build and push production image - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - uses: docker/build-push-action@v6 - with: - context: . - file: Dockerfile - push: true - platforms: linux/amd64,linux/arm64 - tags: | - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }} - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - -``` - -This workflow performs the following tasks for your Next.js application: -- Triggers on every `push` or `pull request` targeting the `main` branch. -- Builds a development Docker image using `Dockerfile.dev`, optimized for testing. -- Executes unit tests using Jest inside a clean, containerized environment to ensure consistency. -- Halts the workflow immediately if any test fails — enforcing code quality. -- Caches both Docker build layers and npm dependencies for faster CI runs. -- Authenticates securely with Docker Hub using GitHub repository secrets. -- Builds a production-ready image using the `Dockerfile`. -- Tags and pushes the final image to Docker Hub with both `latest` and short SHA tags for traceability. - -> [!NOTE] -> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - ---- - -### Step 3: Run the workflow - -After you've added your workflow file, it's time to trigger and observe the CI/CD process in action. - -1. Commit and push your workflow file - - Select "Commit changes…" in the GitHub editor. - - - This push will automatically trigger the GitHub Actions pipeline. - -2. Monitor the workflow execution - - 1. Go to the Actions tab in your GitHub repository. - 2. Select the workflow run to follow each step: `build`, `test`, and (if successful) `push`. - -3. Verify the Docker image on Docker Hub - - - After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories). - - You should see a new image under your repository with: - - Repository name: `${your-repository-name}` - - Tags include: - - `latest` – represents the most recent successful build; ideal for quick testing or deployment. - - `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability. - -> [!TIP] Protect your main branch -> To maintain code quality and prevent accidental direct pushes, enable branch protection rules: -> - Navigate to your **GitHub repo → Settings → Branches**. -> - Under Branch protection rules, select **Add rule**. -> - Specify `main` as the branch name. -> - Enable options like: -> - *Require a pull request before merging*. -> - *Require status checks to pass before merging*. -> -> This ensures that only tested and reviewed code is merged into `main` branch. ---- - -## Summary - -In this section, you set up a complete CI/CD pipeline for your containerized Next.js application using GitHub Actions. - -Here's what you accomplished: - -- Created a new GitHub repository specifically for your project. -- Generated a secure Docker Hub access token and added it to GitHub as a secret. -- Defined a GitHub Actions workflow to: - - Build your application inside a Docker container. - - Run tests in a consistent, containerized environment. - - Push a production-ready image to Docker Hub if tests pass. -- Triggered and verified the workflow execution through GitHub Actions. -- Confirmed that your image was successfully published to Docker Hub. - -With this setup, your Next.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity. - ---- - -## Related resources - -Deepen your understanding of automation and best practices for containerized apps: - -- [Introduction to GitHub Actions](/guides/gha.md) – Learn how GitHub Actions automate your workflows -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) – Set up container builds with GitHub Actions -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows -- [Compose file reference](/compose/compose-file/) – Full configuration reference for `compose.yaml` -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security - ---- - -## Next steps - -Next, learn how you can locally test and debug your Next.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment. diff --git a/content/guides/nextjs/containerize.md b/content/guides/nextjs/containerize.md deleted file mode 100644 index 2fac91c48af3..000000000000 --- a/content/guides/nextjs/containerize.md +++ /dev/null @@ -1,961 +0,0 @@ ---- -title: Containerize a Next.js Application -linkTitle: Containerize -weight: 10 -keywords: next.js, node, image, initialize, build -description: Learn how to containerize a Next.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability. - ---- - -## Prerequisites - -Before you begin, make sure the following tools are installed and available on your system: - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -> [!NOTE] -> New to Docker? Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. - ---- - -## Overview - -This guide walks you through containerizing a Next.js application with Docker. -You'll learn how to create a production-ready Docker image using best -practices that improve performance, security, scalability, and deployment -efficiency. - -By the end of this guide, you will: - -- Containerize a Next.js application using Docker. -- Create and optimize a Dockerfile for production builds. -- Use multi-stage builds to minimize image size. -- Leverage Next.js standalone or export output for efficient containerization. -- Follow best practices for building secure and maintainable Docker images. - ---- - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following command -to clone the git repository: - -```console -$ git clone https://github.com/kristiyan-velkov/docker-nextjs-sample -``` ---- - -## Build the Docker image - -Next.js has specific requirements for production deployments. This guide shows two approaches: `standalone` output (Node.js server) and `export` output (static files with Nginx). - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -### Step 1: Configure Next.js and create the Dockerfile - -Before creating a Dockerfile, choose a base image: the [Node.js Official Image](https://hub.docker.com/_/node) or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog) from the Hardened Image catalog. Choosing DHI gives you a production-ready, lightweight, and secure image. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -> [!IMPORTANT] -> This guide uses stable Node.js LTS image tags that are considered secure when the guide is written. Because new releases and security patches are published regularly, always review the [official Node.js Docker images](https://hub.docker.com/_/node) and select a secure, up-to-date version before building or deploying. - ---- - -#### 1.1 Next.js with standalone output - -Standalone output (`output: "standalone"`) makes Next.js build a self-contained output that includes only the files and dependencies needed to run the application. A single `node server.js` can serve the app, which is ideal for Docker and supports server-side rendering, API routes, and incremental static regeneration. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) (including the "standalone" option). - -The container runs the Next.js server with Node.js on port 3000. - -Configure Next.js — Open or create `next.config.ts` in your project root: - -```ts -import type { NextConfig } from "next"; - -const nextConfig: NextConfig = { - output: "standalone", -}; - -export default nextConfig; -``` - -Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below. - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -3. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use `dhi.io/node:24-alpine3.22-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility. - - ```dockerfile - # ============================================ - # Stage 1: Dependencies Installation Stage - # ============================================ - - # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance - # This Dockerfile uses dhi.io/node. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility. - - FROM dhi.io/node:24-alpine3.22-dev AS dependencies - - # Set working directory - WORKDIR /app - - # Copy package-related files first to leverage Docker's caching mechanism - COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ - - # Install project dependencies with frozen lockfile for reproducible builds - RUN --mount=type=cache,target=/root/.npm \ - --mount=type=cache,target=/usr/local/share/.cache/yarn \ - --mount=type=cache,target=/root/.local/share/pnpm/store \ - if [ -f package-lock.json ]; then \ - npm ci --no-audit --no-fund; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn install --frozen-lockfile --production=false; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm install --frozen-lockfile; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ============================================ - # Stage 2: Build Next.js application in standalone mode - # ============================================ - - FROM dhi.io/node:24-alpine3.22-dev AS builder - - # Set working directory - WORKDIR /app - - # Copy project dependencies from dependencies stage - COPY --from=dependencies /app/node_modules ./node_modules - - # Copy application source code - COPY . . - - ENV NODE_ENV=production - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the build. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Build Next.js application - # If you want to speed up Docker rebuilds, you can cache the build artifacts - # by adding: --mount=type=cache,target=/app/.next/cache - # This caches the .next/cache directory across builds, but it also prevents - # .next/cache/fetch-cache from being included in the final image, meaning - # cached fetch responses from the build won't be available at runtime. - RUN if [ -f package-lock.json ]; then \ - npm run build; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn build; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm build; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ============================================ - # Stage 3: Run Next.js application - # ============================================ - - FROM dhi.io/node:24-alpine3.22-dev AS runner - - # Set working directory - WORKDIR /app - - # Set production environment variables - ENV NODE_ENV=production - ENV PORT=3000 - ENV HOSTNAME="0.0.0.0" - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the run time. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Copy production assets - COPY --from=builder --chown=node:node /app/public ./public - - # Set the correct permission for prerender cache - RUN mkdir .next - RUN chown node:node .next - - # Automatically leverage output traces to reduce image size - # https://nextjs.org/docs/advanced-features/output-file-tracing - COPY --from=builder --chown=node:node /app/.next/standalone ./ - COPY --from=builder --chown=node:node /app/.next/static ./.next/static - - # If you want to persist the fetch cache generated during the build so that - # cached responses are available immediately on startup, uncomment this line: - # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache - - # Switch to non-root user for security best practices - USER node - - # Expose port 3000 to allow HTTP traffic - EXPOSE 3000 - - # Start Next.js standalone server - CMD ["node", "server.js"] - ``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` with the following contents (uses `node`): - -```dockerfile - # ============================================ - # Stage 1: Dependencies Installation Stage - # ============================================ - - ARG NODE_VERSION=24.14.0-slim - - FROM node:${NODE_VERSION} AS dependencies - - # Set working directory - WORKDIR /app - - # Copy package-related files first to leverage Docker's caching mechanism - COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ - - # Install project dependencies with frozen lockfile for reproducible builds - RUN --mount=type=cache,target=/root/.npm \ - --mount=type=cache,target=/usr/local/share/.cache/yarn \ - --mount=type=cache,target=/root/.local/share/pnpm/store \ - if [ -f package-lock.json ]; then \ - npm ci --no-audit --no-fund; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn install --frozen-lockfile --production=false; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm install --frozen-lockfile; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ============================================ - # Stage 2: Build Next.js application in standalone mode - # ============================================ - - FROM node:${NODE_VERSION} AS builder - - # Set working directory - WORKDIR /app - - # Copy project dependencies from dependencies stage - COPY --from=dependencies /app/node_modules ./node_modules - - # Copy application source code - COPY . . - - ENV NODE_ENV=production - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the build. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Build Next.js application - # If you want to speed up Docker rebuilds, you can cache the build artifacts - # by adding: --mount=type=cache,target=/app/.next/cache - # This caches the .next/cache directory across builds, but it also prevents - # .next/cache/fetch-cache from being included in the final image, meaning - # cached fetch responses from the build won't be available at runtime. - RUN if [ -f package-lock.json ]; then \ - npm run build; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn build; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm build; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ============================================ - # Stage 3: Run Next.js application - # ============================================ - - FROM node:${NODE_VERSION} AS runner - - # Set working directory - WORKDIR /app - - # Set production environment variables - ENV NODE_ENV=production - ENV PORT=3000 - ENV HOSTNAME="0.0.0.0" - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the run time. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Copy production assets - COPY --from=builder --chown=node:node /app/public ./public - - # Set the correct permission for prerender cache - RUN mkdir .next - RUN chown node:node .next - - # Automatically leverage output traces to reduce image size - # https://nextjs.org/docs/advanced-features/output-file-tracing - COPY --from=builder --chown=node:node /app/.next/standalone ./ - COPY --from=builder --chown=node:node /app/.next/static ./.next/static - - # If you want to persist the fetch cache generated during the build so that - # cached responses are available immediately on startup, uncomment this line: - # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache - - # Switch to non-root user for security best practices - USER node - - # Expose port 3000 to allow HTTP traffic - EXPOSE 3000 - - # Start Next.js standalone server - CMD ["node", "server.js"] -``` - -> [!NOTE] -> This Dockerfile uses three stages: `dependencies`, `builder`, and `runner`. The final image runs `node server.js` and listens on port 3000. - -{{< /tab >}} -{{< /tabs >}} - ---- - -#### 1.2 Next.js with export output - -Output export (`output: "export"`) makes Next.js build a fully static site at build time. It generates HTML, CSS, and JavaScript into an `out` directory that can be served by any static host or CDN—no Node.js server at runtime. Use this when you don't need server-side rendering or API routes. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output). - -Configure Next.js — Open `next.config.ts` in your project root and add the following code: - -```ts -import type { NextConfig } from "next"; - -const nextConfig: NextConfig = { - output: "export", - trailingSlash: true, - images: { - unoptimized: true, - }, -}; - -export default nextConfig; -``` - -Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below. - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) are available for Node.js and Nginx in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog). For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -3. Pull the Nginx DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev - ``` - -4. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use Docker Hardened Images: `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility. - - ```dockerfile - # ============================================ - # Stage 1: Dependencies Installation Stage - # ============================================ - - # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance - # This Dockerfile uses dhi.io/node and dhi.io/nginx. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility. - - FROM dhi.io/node:24-alpine3.22-dev AS dependencies - - # Set the working directory - WORKDIR /app - - # Copy package-related files first to leverage Docker's caching mechanism - COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ - - # Install project dependencies with frozen lockfile for reproducible builds - RUN --mount=type=cache,target=/root/.npm \ - --mount=type=cache,target=/usr/local/share/.cache/yarn \ - --mount=type=cache,target=/root/.local/share/pnpm/store \ - if [ -f package-lock.json ]; then \ - npm ci --no-audit --no-fund; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn install --frozen-lockfile --production=false; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm install --frozen-lockfile; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ============================================ - # Stage 2: Build Next.js Application - # ============================================ - - FROM dhi.io/node:24-alpine3.22-dev AS builder - - # Set the working directory - WORKDIR /app - - # Copy project dependencies from dependencies stage - COPY --from=dependencies /app/node_modules ./node_modules - - # Copy application source code - COPY . . - - ENV NODE_ENV=production - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the build. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Build Next.js application - RUN --mount=type=cache,target=/app/.next/cache \ - if [ -f package-lock.json ]; then \ - npm run build; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn build; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm build; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - - # ========================================= - # Stage 3: Serve Static Files with Nginx - # ========================================= - - FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner - - # Set the working directory - WORKDIR /app - - # Next.js collects completely anonymous telemetry data about general usage. - # Learn more here: https://nextjs.org/telemetry - # Uncomment the following line in case you want to disable telemetry during the run time. - # ENV NEXT_TELEMETRY_DISABLED=1 - - # Copy custom Nginx config - COPY nginx.conf /etc/nginx/nginx.conf - - # Copy the static build output from the build stage to Nginx's default HTML serving directory - COPY --chown=nginx:nginx --from=builder /app/out /usr/share/nginx/html - - # Non-root user for security best practices - USER nginx - - # Expose port 8080 to allow HTTP traffic - EXPOSE 8080 - - # Start Nginx directly with custom config - ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] - CMD ["-g", "daemon off;"] - ``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` with the following contents (uses `node` and `nginxinc/nginx-unprivileged`): - -```dockerfile -# ============================================ -# Stage 1: Dependencies Installation Stage -# ============================================ - -ARG NODE_VERSION=24.14.0-slim -ARG NGINXINC_IMAGE_TAG=alpine3.22 - -FROM node:${NODE_VERSION} AS dependencies - -# Set the working directory -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ - -# Install project dependencies with frozen lockfile for reproducible builds -RUN --mount=type=cache,target=/root/.npm \ - --mount=type=cache,target=/usr/local/share/.cache/yarn \ - --mount=type=cache,target=/root/.local/share/pnpm/store \ - if [ -f package-lock.json ]; then \ - npm ci --no-audit --no-fund; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn install --frozen-lockfile --production=false; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm install --frozen-lockfile; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - -# ============================================ -# Stage 2: Build Next.js Application -# ============================================ - -FROM node:${NODE_VERSION} AS builder - -# Set the working directory -WORKDIR /app - -# Copy project dependencies from dependencies stage -COPY --from=dependencies /app/node_modules ./node_modules - -# Copy application source code -COPY . . - -ENV NODE_ENV=production - -# Next.js collects completely anonymous telemetry data about general usage. -# Learn more here: https://nextjs.org/telemetry -# Uncomment the following line in case you want to disable telemetry during the build. -# ENV NEXT_TELEMETRY_DISABLED=1 - -# Build Next.js application -RUN --mount=type=cache,target=/app/.next/cache \ - if [ -f package-lock.json ]; then \ - npm run build; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn build; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm build; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - -# ========================================= -# Stage 3: Serve Static Files with Nginx -# ========================================= - -FROM nginxinc/nginx-unprivileged:${NGINXINC_IMAGE_TAG} AS runner - -# Set the working directory -WORKDIR /app - -# Next.js collects completely anonymous telemetry data about general usage. -# Learn more here: https://nextjs.org/telemetry -# Uncomment the following line in case you want to disable telemetry during the run time. -# ENV NEXT_TELEMETRY_DISABLED=1 - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --from=builder /app/out /usr/share/nginx/html - -# Non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -> [!NOTE] -> This guide uses [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) instead of the standard Nginx image to run as a non-root user, following security best practices. - -{{< /tab >}} -{{< /tabs >}} - -1. Create `nginx.conf` (required for export output only) — Create a file named `nginx.conf` in the root of your project: - - ```nginx - # Minimal Nginx config for static Next.js app - worker_processes 1; - - # Store PID in /tmp (always writable) - pid /tmp/nginx.pid; - - events { - worker_connections 1024; - } - - http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - # Disable logging to avoid permission issues - access_log off; - error_log /dev/stderr; - - # Optimize static file serving - sendfile on; - tcp_nopush on; - tcp_nodelay on; - keepalive_timeout 65; - - # Gzip compression - gzip on; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; - gzip_min_length 256; - - server { - listen 8080; - server_name localhost; - - # Serve static files - root /usr/share/nginx/html; - index index.html; - - # Handle Next.js static export routing - # See: https://nextjs.org/docs/app/guides/static-exports#deploying - location / { - try_files $uri $uri.html $uri/ =404; - } - - # This is necessary when `trailingSlash: false` (default). - # You can omit this when `trailingSlash: true` in next.config. - # Handles nested routes like /blog/post -> /blog/post.html - location ~ ^/(.+)/$ { - rewrite ^/(.+)/$ /$1.html break; - } - - # Serve Next.js static assets - location ~ ^/_next/ { - try_files $uri =404; - expires 1y; - add_header Cache-Control "public, immutable"; - } - - # Optional 404 handling - error_page 404 /404.html; - location = /404.html { - internal; - } - } - } - ``` - - > [!NOTE] - > Export uses port 8080. For more details, see the [Next.js output configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) and [Nginx documentation](https://nginx.org/en/docs/). - -### Step 2: Create the compose.yaml file - -Create a file named `compose.yaml` with the following contents: - -```yaml {collapse=true,title=compose.yaml} -services: - server: - build: - context: . - ports: - - 3000:3000 -``` - -> [!NOTE] -> If using export output (Nginx), change the port mapping to `8080:8080`. - -### Step 3: Create the .dockerignore file - -The `.dockerignore` file tells Docker which files and folders to exclude when building the image. - - -> [!NOTE] ->This helps: ->- Reduce image size ->- Speed up the build process ->- Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. -> -> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). - -Create a file named `.dockerignore` with the following contents: - -```dockerignore -# Dependencies (installed inside the image, never copy from host) -node_modules/ -.pnp/ -.pnp.js -.pnpm-store/ - -# Next.js build output (generated during the image build) -.next/ -out/ -dist/ -build/ -.vercel/ - -# Testing (not needed in the production image) -coverage/ -.nyc_output/ -__tests__/ -__mocks__/ -jest/ -cypress/ -playwright-report/ -test-results/ -.vitest/ - -# Environment files (avoid leaking secrets into the build context) -.env -.env* -.env.local -.env.development.local -.env.test.local -.env.production.local - -# Debug and log files -npm-debug.log* -yarn-debug.log* -yarn-error.log* -pnpm-debug.log* -lerna-debug.log* -*.log - -# IDE and editor files -.vscode/ -.idea/ -.cursor/ -.cursorrules -.copilot/ -*.swp -*.swo -*~ - -# Git -.git/ -.gitignore -.gitattributes - -# Docker files (reduce build context; not needed inside the image) -Dockerfile* -.dockerignore -docker-compose*.yml -compose*.yaml - -# Documentation (not needed in the image) -*.md -docs/ - -# CI/CD (not needed in the image) -.github/ -.gitlab-ci.yml -.travis.yml -.circleci/ -Jenkinsfile - -# TypeScript and build metadata -*.tsbuildinfo - -# Cache and temporary directories -.cache/ -.parcel-cache/ -.eslintcache -.stylelintcache -.turbo/ -.tmp/ -.temp/ - -# Sensitive or dev-only config (optional; omit if your build needs these) -.pem -.editorconfig -.prettierrc* -.eslintrc* -.stylelintrc* -.babelrc* -*.iml - -# OS-specific files -.DS_Store -._* -.Spotlight-V100 -.Trashes -ehthumbs.db -Thumbs.db -Desktop.ini -``` - -### Step 4: Build the Next.js application image - -With your custom configuration in place, you're now ready to build the Docker image. Use the Dockerfile you created in Step 1 (standalone or export). - -The setup includes: - -- Multi-stage builds for optimized image size -- Standalone: Node.js server on port 3000; Export: Nginx serving static files on port 8080 -- Non-root user for enhanced security -- Proper file permissions and ownership - -After completing the previous steps, your project directory should contain at least the following files (export also requires `nginx.conf`): - -```text -├── docker-nextjs-sample/ -│ ├── Dockerfile -│ ├── .dockerignore -│ ├── compose.yaml -│ └── next.config.ts -``` - -Now that your Dockerfile is configured, you can build the Docker image for your Next.js application. - -> [!NOTE] -> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). - -Run the following command from the root of your project: - -```console -$ docker build --tag nextjs-sample . -``` - -What this command does: -- Uses the Dockerfile in the current directory (.) -- Packages the application and its dependencies into a Docker image -- Tags the image as nextjs-sample so you can reference it later - - -### Step 5: View local images - -After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. - -To list all locally available Docker images, run the following command: - -```console -$ docker images -``` - -Example Output: - -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -nextjs-sample latest 8c5fc80f098e 14 seconds ago 130MB -``` - -This output provides key details about your images: - -- Repository – The name assigned to the image. -- Tag – A version label that helps identify different builds (e.g., latest). -- Image ID – A unique identifier for the image. -- Created – The timestamp indicating when the image was built. -- Size – The total disk space used by the image. - -If the build was successful, you should see `nextjs-sample` image listed. - ---- - -## Run the containerized application - -In the previous step, you created a Dockerfile for your Next.js application and built a Docker image using the docker build command. Now it's time to run that image in a container and verify that your application works as expected. - -Run the following command in a terminal. Use the port that matches your setup: standalone uses port 3000, export uses port 8080. - -```console -$ docker run -p 3000:3000 nextjs-sample -``` - -For export output, use port 8080 instead: - -```console -$ docker run -p 8080:8080 nextjs-sample -``` - -Open a browser and view the application: [http://localhost:3000](http://localhost:3000) for standalone or [http://localhost:8080](http://localhost:8080) for export. You should see your Next.js web application. - -Press `ctrl+c` in the terminal to stop your application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` option and `--name` to give the container a name so you can stop it later: - -```console -$ docker run -d -p 3000:3000 --name nextjs-app nextjs-sample -``` - -For export output, use port 8080: - -```console -$ docker run -d -p 8080:8080 --name nextjs-app nextjs-sample -``` - -Open a browser and view the application: [http://localhost:3000](http://localhost:3000) for standalone or [http://localhost:8080](http://localhost:8080) for export. You should see your web application. - -To confirm that the container is running, use the `docker ps` command: - -```console -$ docker ps -``` - -This will list all active containers along with their ports, names, and status. Look for a container exposing port 3000 (standalone) or 8080 (export). - -Example Output: - -```shell -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -f49b74736a9d nextjs-sample "node server.js" About a minute ago Up About a minute 0.0.0.0:3000->3000/tcp nextjs-app -``` - -To stop the application, run: - -```console -$ docker stop nextjs-app -``` - -> [!NOTE] -> For more information about running containers, see the [`docker run` CLI reference](/reference/cli/docker/container/run/) and the [`docker stop` CLI reference](/reference/cli/docker/container/stop/). - ---- - -## Summary - -In this guide, you learned how to containerize, build, and run a Next.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup. - -What you accomplished: -- Configured Next.js for either standalone output (Node.js server) or export output (static files with Nginx). -- Added a multi-stage Dockerfile for your chosen approach: standalone (port 3000) or export (port 8080, with `nginx.conf`). -- Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient. -- Built your Docker image using `docker build`. -- Ran the container using `docker run` with the image name `nextjs-sample`, both in the foreground and in detached mode. -- Verified that the app was running by visiting [http://localhost:3000](http://localhost:3000) (standalone) or [http://localhost:8080](http://localhost:8080) (export). -- Learned how to stop the containerized application using `docker stop nextjs-app`. - -You now have a fully containerized Next.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker workflow: - -- [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds. -- [Next.js output configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) – Learn about Next.js production optimization (standalone and export). -- [Next.js with Docker (standalone)](https://github.com/vercel/next.js/tree/canary/examples/with-docker) – Official Next.js example: standalone output with Node.js. -- [Next.js with Docker (export)](https://github.com/vercel/next.js/tree/canary/examples/with-docker-export-output) – Official Next.js example: static export with Nginx or serve. -- [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile. -- [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images. -- [`docker run` CLI reference](/reference/cli/docker/container/run/) – Run a command in a new container. -- [`docker stop` CLI reference](/reference/cli/docker/container/stop/) – Stop one or more running containers. - ---- - -## Next steps - -With your Next.js application now containerized, you're ready to move on to the next step. - -In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine. diff --git a/content/guides/nextjs/deploy.md b/content/guides/nextjs/deploy.md deleted file mode 100644 index 7b1017e2c8bb..000000000000 --- a/content/guides/nextjs/deploy.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Test your Next.js deployment -linkTitle: Test your deployment -weight: 70 -keywords: deploy, kubernetes, next.js -description: Learn how to deploy locally to test and debug your Kubernetes deployment - ---- - -## Prerequisites - -Before you begin, make sure you've completed the following: -- Complete all the previous sections of this guide, starting with [Containerize Next.js application](containerize.md). -- [Enable Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -> **New to Kubernetes?** -> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work. - ---- - -## Overview - -This section guides you through deploying your containerized Next.js application locally using [Docker Desktop's built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster allows you to closely simulate a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production. - ---- - -## Create a Kubernetes YAML file - -Follow these steps to define your deployment configuration: - -1. In the root of your project, create a new file named: nextjs-sample-kubernetes.yaml - -2. Open the file in your IDE or preferred text editor. - -3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](configure-github-actions.md). - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nextjs-sample - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: nextjs-sample - template: - metadata: - labels: - app: nextjs-sample - spec: - containers: - - name: nextjs-container - image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest - imagePullPolicy: Always - ports: - - containerPort: 3000 - env: - - name: NODE_ENV - value: "production" - - name: HOSTNAME - value: "0.0.0.0" ---- -apiVersion: v1 -kind: Service -metadata: - name: nextjs-sample-service - namespace: default -spec: - type: NodePort - selector: - app: nextjs-sample - ports: - - port: 3000 - targetPort: 3000 - nodePort: 30001 -``` - -This manifest defines two key Kubernetes resources, separated by `---`: - -- Deployment - Deploys a single replica of your Next.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow - (refer to [Automate your builds with GitHub Actions](configure-github-actions.md)). - The container listens on port `3000`, which is the default port for Next.js applications. - -- Service (NodePort) - Exposes the deployed pod to your local machine. - It forwards traffic from port `30001` on your host to port `3000` inside the container. - This lets you access the application in your browser at [http://localhost:30001](http://localhost:30001). - -> [!NOTE] -> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - ---- - -## Deploy and check your application - -Follow these steps to deploy your containerized Next.js app into a local Kubernetes cluster and verify that it's running correctly. - -### Step 1. Apply the Kubernetes configuration - -In your terminal, navigate to the directory where your `nextjs-sample-kubernetes.yaml` file is located, then deploy the resources using: - -```console - $ kubectl apply -f nextjs-sample-kubernetes.yaml -``` - -If everything is configured properly, you'll see confirmation that both the Deployment and the Service were created: - -```shell - deployment.apps/nextjs-sample created - service/nextjs-sample-service created -``` - -This output means that both the Deployment and the Service were successfully created and are now running inside your local cluster. - -### Step 2. Check the deployment status - -Run the following command to check the status of your deployment: - -```console - $ kubectl get deployments -``` - -You should see an output similar to: - -```shell - NAME READY UP-TO-DATE AVAILABLE AGE - nextjs-sample 1/1 1 1 14s -``` - -This confirms that your pod is up and running with one replica available. - -### Step 3. Verify the service exposure - -Check if the NodePort service is exposing your app to your local machine: - -```console -$ kubectl get services -``` - -You should see something like: - -```shell -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -nextjs-sample-service NodePort 10.100.244.65 <none> 3000:30001/TCP 1m -``` - -This output confirms that your app is available via NodePort on port 30001. - -### Step 4. Access your app in the browser - -Open your browser and navigate to [http://localhost:30001](http://localhost:30001). - -You should see your production-ready Next.js Sample application running — served by your local Kubernetes cluster. - -### Step 5. Clean up Kubernetes resources - -Once you're done testing, you can delete the deployment and service using: - -```console - $ kubectl delete -f nextjs-sample-kubernetes.yaml -``` - -Expected output: - -```shell - deployment.apps "nextjs-sample" deleted - service "nextjs-sample-service" deleted -``` - -This ensures your cluster stays clean and ready for the next deployment. - ---- - -## Summary - -In this section, you learned how to deploy your Next.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud. - -What you accomplished: - -- Created a Kubernetes Deployment and NodePort Service for your Next.js app -- Used `kubectl apply` to deploy the application locally -- Verified the app was running and accessible at `http://localhost:30001` -- Cleaned up your Kubernetes resources after testing - ---- - -## Related resources - -Explore official references and best practices to sharpen your Kubernetes deployment workflow: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more. -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) – Use Docker Desktop's built-in Kubernetes support for local testing and development. -- [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line. -- [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments. -- [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic. diff --git a/content/guides/nextjs/develop.md b/content/guides/nextjs/develop.md deleted file mode 100644 index d2a758434e97..000000000000 --- a/content/guides/nextjs/develop.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Use containers for Next.js development -linkTitle: Develop your app -weight: 30 -keywords: next.js, development, node -description: Learn how to develop your Next.js application locally using containers. - ---- - -## Prerequisites - -Complete [Containerize Next.js application](containerize.md). - ---- - -## Overview - -In this section, you'll learn how to set up both production and development environments for your containerized Next.js application using Docker Compose. This setup allows you to run a production build using the standalone server and to develop efficiently inside containers using Next.js's built-in hot reloading with Compose Watch. - -You'll learn how to: -- Configure separate containers for production and development -- Enable automatic file syncing using Compose Watch in development -- Debug and live-preview your changes in real-time without manual rebuilds - ---- - -## Automatically update services (development mode) - -Use Compose Watch to automatically sync source file changes into your -containerized development environment. This automatically syncs file changes -without needing to restart or rebuild containers manually. - -## Step 1: Create a development Dockerfile - -Create a file named `Dockerfile.dev` in your project root with the following content (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)): - -```dockerfile -# ============================================ -# Development Dockerfile for Next.js -# ============================================ -ARG NODE_VERSION=24.14.0-slim - -FROM node:${NODE_VERSION} AS dev - -WORKDIR /app - -COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ - -RUN --mount=type=cache,target=/root/.npm \ - --mount=type=cache,target=/usr/local/share/.cache/yarn \ - --mount=type=cache,target=/root/.local/share/pnpm/store \ - if [ -f package-lock.json ]; then \ - npm ci --no-audit --no-fund; \ - elif [ -f yarn.lock ]; then \ - corepack enable yarn && yarn install --frozen-lockfile --production=false; \ - elif [ -f pnpm-lock.yaml ]; then \ - corepack enable pnpm && pnpm install --frozen-lockfile; \ - else \ - echo "No lockfile found." && exit 1; \ - fi - -COPY . . - -ENV WATCHPACK_POLLING=true -ENV HOSTNAME="0.0.0.0" - -RUN chown -R node:node /app -USER node - -EXPOSE 3000 - -CMD ["sh", "-c", "if [ -f package-lock.json ]; then npm run dev; elif [ -f yarn.lock ]; then yarn dev; elif [ -f pnpm-lock.yaml ]; then pnpm dev; else npm run dev; fi"] -``` - -This file sets up a development environment for your Next.js app with hot module replacement and supports npm, yarn, and pnpm. - - -### Step 2: Update your `compose.yaml` file - -Open your `compose.yaml` file and define two services: one for production (`nextjs-prod-standalone`) and one for development (`nextjs-dev`). This matches the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) structure. - -Here's an example configuration for a Next.js application: - -```yaml -services: - nextjs-prod-standalone: - build: - context: . - dockerfile: Dockerfile - image: nextjs-sample:prod - container_name: nextjs-sample-prod - ports: - - "3000:3000" - - nextjs-dev: - build: - context: . - dockerfile: Dockerfile.dev - image: nextjs-sample:dev - container_name: nextjs-sample-dev - ports: - - "3000:3000" - environment: - - WATCHPACK_POLLING=true - develop: - watch: - - action: sync - path: . - target: /app - ignore: - - node_modules/ - - .next/ - - action: rebuild - path: package.json -``` - -- The `nextjs-prod-standalone` service builds and runs your production Next.js app using the standalone output. -- The `nextjs-dev` service runs your Next.js development server with hot module replacement. -- `watch` triggers file sync with Compose Watch. -- `WATCHPACK_POLLING=true` ensures file changes are detected properly inside Docker. -- The `rebuild` action for `package.json` ensures dependencies are reinstalled when the file changes. - -> [!NOTE] -> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -### Step 3: Configure Next.js for Docker development - -Next.js works well inside Docker containers out of the box, but there are a few configurations that can improve the development experience. - -The `next.config.ts` file you created during containerization already includes the `output: "standalone"` option for production. For development, Next.js automatically uses its built-in development server with hot reloading enabled. - -> [!NOTE] -> The Next.js development server automatically: -> - Enables Hot Module Replacement (HMR) for instant updates -> - Watches for file changes and recompiles automatically -> - Provides detailed error messages in the browser -> -> The `WATCHPACK_POLLING=true` environment variable in the compose file ensures file watching works correctly inside Docker containers. - - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-nextjs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── next.config.ts -``` - -### Step 4: Start Compose Watch - -Run the following command from your project root to start your container in watch mode: - -```console -$ docker compose watch nextjs-dev -``` - -### Step 5: Test Compose Watch with Next.js - -To verify that Compose Watch is working correctly: - -1. Open the `app/page.tsx` file in your text editor (or `src/app/page.tsx` if your project uses a `src` directory). - -2. Locate the main content area and find a text element to modify. - -3. Make a visible change, for example, update a heading: - - ```tsx - <h1>Hello from Docker Compose Watch!</h1> - ``` - -4. Save the file. - -5. Open your browser at [http://localhost:3000](http://localhost:3000). - -You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. - ---- - -## Summary - -In this section, you set up a complete development and production workflow for your Next.js application using Docker and Docker Compose. - -Here's what you achieved: -- Created a `Dockerfile.dev` to streamline local development with hot reloading -- Defined separate `nextjs-dev` and `nextjs-prod-standalone` services in your `compose.yaml` file -- Enabled real-time file syncing using Compose Watch for a smoother development experience -- Verified that live updates work seamlessly by modifying and previewing a component - -With this setup, you can build, run, and iterate on your Next.js app -entirely within containers across environments. - ---- - -## Related resources - -Deepen your knowledge and improve your containerized development workflow with these guides: - -- [Using Compose Watch](/manuals/compose/how-tos/file-watch.md) – Automatically sync source changes during development -- [Multi-stage builds](/manuals/build/building/multi-stage.md) – Create efficient, production-ready Docker images -- [Dockerfile best practices](/build/building/best-practices/) – Write clean, secure, and optimized Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [Docker volumes](/storage/volumes/) – Persist and manage data between container runs - -## Next steps - -In the next section, you'll learn how to run unit tests for your Next.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup. diff --git a/content/guides/nextjs/run-tests.md b/content/guides/nextjs/run-tests.md deleted file mode 100644 index 69e486e76d38..000000000000 --- a/content/guides/nextjs/run-tests.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Run Next.js tests in a container -linkTitle: Run your tests and lint -weight: 40 -keywords: next.js, test, jest, vitest, lint, eslint -description: Learn how to run your Next.js tests and lint in a container. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize Next.js application](containerize.md). - -## Overview - -Testing is a critical part of the development process. In this section, you'll learn how to: - -- Run unit tests using Vitest (or Jest) inside a Docker container. -- Run lint (e.g. ESLint) inside a Docker container. -- Use Docker Compose to run tests and lint in an isolated, reproducible environment. - -The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) uses [Vitest](https://vitest.dev/) with [Testing Library](https://testing-library.com/) for component testing. You can use the same setup or follow the alternative Jest configuration later. - ---- - -## Run tests during development - -The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) already includes lint (ESLint) and sample tests (Vitest, `app/page.test.tsx`) in place. If you're using the sample app, you can skip to **Step 3: Update compose.yaml** and run tests or lint with the commands below. If you're using your own project, follow the install and configuration steps to add the packages and scripts. - -The sample includes a test file at: - -```text -app/page.test.tsx -``` - -This file uses Vitest and React Testing Library to verify the behavior of page components. - -### Step 1: Install Vitest and React Testing Library (custom projects) - -If you're using a custom project and haven't already added the necessary testing tools, install them by running: - -```console -$ npm install --save-dev vitest @vitejs/plugin-react @testing-library/react @testing-library/dom jsdom -``` - -Then, update the scripts section of your `package.json` file to include: - -```json -"scripts": { - "test": "vitest", - "test:run": "vitest run" -} -``` - -For lint, add a `lint` script (and optionally `lint:fix`). For example, with [ESLint](https://eslint.org/): - -```json -"scripts": { - "test": "vitest", - "test:run": "vitest run", - "lint": "eslint .", - "lint:fix": "eslint . --fix" -} -``` - -The sample project uses `eslint` and `eslint-config-next` for Next.js. Install them in a custom project with: - -```console -$ npm install --save-dev eslint eslint-config-next @eslint/eslintrc -``` - -Create an ESLint config file (e.g. `eslint.config.cjs`) in your project root with Next.js rules and global ignores: - -```js -const { defineConfig, globalIgnores } = require("eslint/config"); -const { FlatCompat } = require("@eslint/eslintrc"); - -const compat = new FlatCompat({ baseDirectory: __dirname }); - -module.exports = defineConfig([ - ...compat.extends( - "eslint-config-next/core-web-vitals", - "eslint-config-next/typescript" - ), - globalIgnores([ - ".next/**", - "out/**", - "build/**", - "next-env.d.ts", - "node_modules/**", - "eslint.config.cjs", - ]), -]); -``` - ---- - -### Step 2: Configure Vitest (custom projects) - -If you're using a custom project, create a `vitest.config.ts` file in your project root (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)): - -```ts -import { defineConfig } from "vitest/config"; -import react from "@vitejs/plugin-react"; - -export default defineConfig({ - plugins: [react()], - test: { - environment: "jsdom", - setupFiles: "./vitest.setup.ts", - globals: true, - }, -}); -``` - -Create a `vitest.setup.ts` file in your project root: - -```ts -import "@testing-library/jest-dom/vitest"; -``` - -> [!NOTE] -> Vitest works well with Next.js and provides fast execution and ESM support. For more details, see the [Next.js testing documentation](https://nextjs.org/docs/app/building-your-application/testing) and [Vitest docs](https://vitest.dev/). - -### Step 3: Update compose.yaml - -Add `nextjs-test` and `nextjs-lint` services to your `compose.yaml` file. In the sample project these services use the `tools` profile so they don't start with a normal `docker compose up`. Both reuse `Dockerfile.dev` and run the test or lint command: - -```yaml -services: - nextjs-prod-standalone: - build: - context: . - dockerfile: Dockerfile - image: nextjs-sample:prod - container_name: nextjs-sample-prod - ports: - - "3000:3000" - - nextjs-dev: - build: - context: . - dockerfile: Dockerfile.dev - image: nextjs-sample:dev - container_name: nextjs-sample-dev - ports: - - "3000:3000" - environment: - - WATCHPACK_POLLING=true - develop: - watch: - - action: sync - path: . - target: /app - ignore: - - node_modules/ - - .next/ - - action: rebuild - path: package.json - - nextjs-test: - build: - context: . - dockerfile: Dockerfile.dev - image: nextjs-sample:dev - container_name: nextjs-sample-test - command: - [ - "sh", - "-c", - "if [ -f package-lock.json ]; then npm run test:run 2>/dev/null || npm run test -- --run; elif [ -f yarn.lock ]; then yarn test:run 2>/dev/null || yarn test --run; elif [ -f pnpm-lock.yaml ]; then pnpm run test:run; else npm run test -- --run; fi", - ] - profiles: - - tools - - nextjs-lint: - build: - context: . - dockerfile: Dockerfile.dev - image: nextjs-sample:dev - container_name: nextjs-sample-lint - command: - [ - "sh", - "-c", - "if [ -f package-lock.json ]; then npm run lint; elif [ -f yarn.lock ]; then yarn lint; elif [ -f pnpm-lock.yaml ]; then pnpm lint; else npm run lint; fi", - ] - profiles: - - tools -``` - -The `nextjs-test` and `nextjs-lint` services reuse the same `Dockerfile.dev` used for [development](develop.md) and override the default command to run tests or lint. The `profiles: [tools]` means these services only run when you use the `--profile tools` option. - -After completing the previous steps, your project directory should contain: - -```text -├── docker-nextjs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ ├── vitest.config.ts -│ ├── vitest.setup.ts -│ └── next.config.ts -``` - -### Step 4: Run the tests - -To execute your test suite inside the container, run from your project root: - -```console -$ docker compose --profile tools run --rm nextjs-test -``` - -This command will: -- Start the `nextjs-test` service (because of `--profile tools`). -- Run your test script (`test:run` or `test -- --run`) in the same environment as development. -- Remove the container after the tests complete ([`docker compose run --rm`](/reference/cli/docker/compose/run/)). - -> [!NOTE] -> For more information about Compose commands and profiles, see the [Compose CLI reference](/reference/cli/docker/compose/). - -### Step 5: Run lint in the container - -To run your linter (e.g. ESLint) inside the container, use the `nextjs-lint` service with the same `tools` profile: - -```console -$ docker compose --profile tools run --rm nextjs-lint -``` - -This command will: -- Start the `nextjs-lint` service (because of `--profile tools`). -- Run your lint script (`npm run lint`, `yarn lint`, or `pnpm lint` depending on your lockfile) in the same environment as development. -- Remove the container after lint completes. - -Ensure your `package.json` includes a `lint` script. The sample project already has `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`; for a custom project, add the same and install `eslint` and `eslint-config-next` if needed. - ---- - -## Summary - -In this section, you learned how to run unit tests for your Next.js application inside a Docker container using Vitest and Docker Compose. - -What you accomplished: -- Installed and configured Vitest and React Testing Library for testing Next.js components. -- Created `nextjs-test` and `nextjs-lint` services in `compose.yaml` (with `tools` profile) to isolate test and lint execution. -- Reused the development `Dockerfile.dev` to ensure consistency between dev, test, and lint environments. -- Ran tests inside the container using `docker compose --profile tools run --rm nextjs-test`. -- Ran lint inside the container using `docker compose --profile tools run --rm nextjs-lint`. -- Ensured reliable, repeatable testing and linting across environments without relying on local machine setup. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker testing workflow: - -- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. -- [Next.js Testing Documentation](https://nextjs.org/docs/app/building-your-application/testing) – Official Next.js testing guide. ---- - -## Next steps - -Next, you'll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Next.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow. diff --git a/content/guides/nodejs.md b/content/guides/nodejs.md new file mode 100644 index 000000000000..a847ec162607 --- /dev/null +++ b/content/guides/nodejs.md @@ -0,0 +1,1351 @@ +--- +title: Node.js language-specific guide +linkTitle: Node.js +description: Containerize and develop Node.js applications using Docker +keywords: getting started, node, node.js +summary: | + This guide explains how to containerize Node.js applications using Docker. +aliases: + - /guides/nodejs/containerize/ + - /guides/nodejs/develop/ + - /guides/nodejs/run-tests/ + - /guides/nodejs/configure-github-actions/ + - /guides/nodejs/deploy/ + - /guides/nodejs/secure-supply-chain/ + - /language/nodejs/ + - /guides/language/nodejs/ + - /get-started/nodejs/build-images/ + - /language/nodejs/build-images/ + - /language/nodejs/run-containers/ + - /language/nodejs/containerize/ + - /get-started/nodejs/develop/ + - /language/nodejs/develop/ + - /language/nodejs/run-tests/ + - /language/nodejs/configure-ci-cd/ + - /language/nodejs/deploy/ +weight: 2 +params: + tags: [languages] + featured: true + time: 20 minutes +--- + +[Node.js](https://nodejs.org/en) is a JavaScript runtime for building server-side applications. This guide shows you how to containerize a TypeScript Node.js application using Docker, starting from a simple Express API and progressively adding features like a database. + +This guide focuses on a backend Node.js API. If you're building a standalone frontend application, Docker has dedicated guides for [React.js](/guides/reactjs/), [Vue.js](/guides/vuejs/), [Angular](/guides/angular/), and [Next.js](/guides/nextjs/). + +> **Acknowledgment** +> +> Docker thanks [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for his contribution to this guide. + +## What will you learn? + +In this guide, you'll learn how to: + +- Containerize and run a Node.js application using Docker. +- Set up a local development environment using containers. +- Run tests inside a Docker container. + +Start by containerizing a Node.js application. + +## Prerequisites + +- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [TypeScript](https://www.typescriptlang.org/). +- Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm). +- Familiarity with Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +## Containerize a Node.js application + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You're familiar with basic Docker concepts. If you're new to Docker, start + with [Build and share a containerized application](/get-started/tutorials/run-an-app.md). + +### Overview + +Containerizing your application means packaging it together with its +dependencies, configuration, and runtime into a single portable unit called a +container image. Running that image creates a container, an isolated process +that behaves the same on any machine, whether it's your laptop, a CI runner, or +a production server. + +In this section, you'll containerize a simple [Express.js](https://expressjs.com/) API written in TypeScript. You'll write a `Dockerfile` that describes how to build the image, add a `compose.yaml` file that defines how Docker runs your container, and then build and start the application with one command. + +You'll use [Docker Hardened Images](/dhi/) as the base. These are minimal, secure Node.js images maintained by Docker. + +This guide focuses on a backend Node.js API. If you're building a standalone frontend application, Docker has dedicated guides for [React.js](/guides/reactjs/), [Vue.js](/guides/vuejs/), [Angular](/guides/angular/), and [Next.js](/guides/nextjs/). + +### Create the application + +The sample application is a minimal Express API with a single endpoint that returns a JSON greeting. Create the following files in a new `nodejs-docker-example` directory. To create all the files at once, switch to the **Scaffold script** tab in the file browser and copy the shell command. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="src/index.ts" status="new" >}} + +```typescript +// A minimal Express application. +// The root endpoint (GET /) returns a JSON greeting. +// See https://expressjs.com/ for the framework reference. + +import express, { type Request, type Response } from "express"; + +const app = express(); +const port = parseInt(process.env.PORT ?? "3000", 10); + +app.get("/", (_req: Request, res: Response) => { + res.json({ message: "Hello World" }); +}); + +app.listen(port, () => { + console.log(`Server listening on port ${port}`); +}); +``` + +{{< /file >}} + +{{< file path="package.json" status="new" >}} + +```json +{ + "name": "nodejs-docker-example", + "version": "1.0.0", + "description": "A minimal Node.js TypeScript application.", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsx watch src/index.ts" + }, + "dependencies": { + "express": "^4.21.2" + }, + "devDependencies": { + "@types/express": "^4.17.21", + "@types/node": "^22.0.0", + "tsx": "^4.19.3", + "typescript": "^5.8.3" + } +} +``` + +{{< /file >}} + +{{< file path="tsconfig.json" status="new" >}} + +```json +{ + // TypeScript compiler configuration for the Node.js application. + // Compiles src/ to dist/ as CommonJS modules targeting ES2022. + // See https://www.typescriptlang.org/tsconfig/ for all options. + "compilerOptions": { + "target": "ES2022", + "module": "commonjs", + "lib": ["ES2022"], + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} +``` + +{{< /file >}} + +{{< file path=".gitignore" status="new" >}} + +```text +# Files and directories that Git should ignore. Covers Node.js dependencies, +# TypeScript build output, environment files, and common editor artifacts. +# See https://git-scm.com/docs/gitignore for syntax reference. + +node_modules/ +dist/ +.env +*.log +.DS_Store +coverage/ +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +If you have Node.js installed and want to verify the app works before containerizing it, you can run it locally. + +To run in development mode with hot-reload: + +```console +$ npm install +$ npm run dev +``` + +To run the compiled production build (matching what the Dockerfile does): + +```console +$ npm install +$ npm run build +$ npm start +``` + +Then open [http://localhost:3000](http://localhost:3000) in your browser. You should see `{"message":"Hello World"}`. + +If you don't have Node.js installed, skip ahead. The remaining steps run the application in a container, with no local Node.js required. + +### Create the Docker assets + +Sign in to the DHI registry so Docker can pull the Node.js base images during the build. The available Node.js images are listed in the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). + +```console +$ docker login dhi.io +``` + +Add the following three files to your `nodejs-docker-example` directory. The `Dockerfile` describes how to build the image, `compose.yaml` defines how Docker runs the container, and `.dockerignore` keeps unwanted files out of the build context. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for +> your project. Ask Gordon to create a Dockerfile, Compose file, and +> `.dockerignore` tailored to your application. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="src/index.ts" >}} + +```typescript +// A minimal Express application. +// The root endpoint (GET /) returns a JSON greeting. +// See https://expressjs.com/ for the framework reference. + +import express, { type Request, type Response } from "express"; + +const app = express(); +const port = parseInt(process.env.PORT ?? "3000", 10); + +app.get("/", (_req: Request, res: Response) => { + res.json({ message: "Hello World" }); +}); + +app.listen(port, () => { + console.log(`Server listening on port ${port}`); +}); +``` + +{{< /file >}} + +{{< file path="package.json" >}} + +```json +{ + "name": "nodejs-docker-example", + "version": "1.0.0", + "description": "A minimal Node.js TypeScript application.", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsx watch src/index.ts" + }, + "dependencies": { + "express": "^4.21.2" + }, + "devDependencies": { + "@types/express": "^4.17.21", + "@types/node": "^22.0.0", + "tsx": "^4.19.3", + "typescript": "^5.8.3" + } +} +``` + +{{< /file >}} + +{{< file path="tsconfig.json" >}} + +```json +{ + // TypeScript compiler configuration for the Node.js application. + // Compiles src/ to dist/ as CommonJS modules targeting ES2022. + // See https://www.typescriptlang.org/tsconfig/ for all options. + "compilerOptions": { + "target": "ES2022", + "module": "commonjs", + "lib": ["ES2022"], + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} +``` + +{{< /file >}} + +{{< file path="Dockerfile" status="new" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Builder stage: install all dependencies and compile TypeScript. +FROM dhi.io/node:24-alpine3.23-dev AS builder + +WORKDIR /app + +# Install dependencies as a separate step to take advantage of Docker's +# caching. Leverage a cache mount to /root/.npm to speed up subsequent +# builds. Leverage a bind mount to package.json to avoid having to copy +# it into this layer. +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install +# Once you create a package-lock.json by running npm install locally, switch to npm ci and bind both files: +# RUN --mount=type=cache,target=/root/.npm \ +# --mount=type=bind,source=package.json,target=package.json \ +# --mount=type=bind,source=package-lock.json,target=package-lock.json \ +# npm ci + +# Copy the source code into the container and compile TypeScript. +COPY . . +RUN npm run build + + +# Deps stage: install production dependencies only. +FROM dhi.io/node:24-alpine3.23-dev AS deps + +WORKDIR /app + +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install --omit=dev +# Once you create a package-lock.json by running npm install locally, switch to npm ci and bind both files: +# RUN --mount=type=cache,target=/root/.npm \ +# --mount=type=bind,source=package.json,target=package.json \ +# --mount=type=bind,source=package-lock.json,target=package-lock.json \ +# npm ci --omit=dev + + +# Runner stage: minimal runtime image with compiled app and production deps. +FROM dhi.io/node:24-alpine3.23 AS runner + +ENV PATH=/app/node_modules/.bin:$PATH + +WORKDIR /app + +COPY --from=deps --chown=node:node /app/node_modules ./node_modules +COPY --from=builder --chown=node:node /app/dist ./dist + +# Expose the port that the application listens on. +EXPOSE 3000 + +# Run the application. +CMD ["node", "dist/index.js"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="new" >}} + +```yaml +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + ports: + - 3000:3000 +``` + +{{< /file >}} + +{{< file path=".dockerignore" status="new" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +node_modules/ +dist/ +.env +.git +.gitignore +.DS_Store +npm-debug.log* +coverage/ +db/ +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. Covers Node.js dependencies, +# TypeScript build output, environment files, and common editor artifacts. +# See https://git-scm.com/docs/gitignore for syntax reference. + +node_modules/ +dist/ +.env +*.log +.DS_Store +coverage/ +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +The `Dockerfile` uses three stages. The `builder` stage installs all dependencies and compiles TypeScript. The `deps` stage does a fresh install of production-only dependencies. The `runner` stage copies the compiled output and production node_modules into a minimal runtime image that contains only Node.js. + +To learn more about each file, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `nodejs-docker-example` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You should see `{"message":"Hello World"}`. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `nodejs-docker-example` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for Node.js development + +### Prerequisites + +Complete [Containerize a Node.js application](#containerize-a-nodejs-application). + +### Overview + +Once your application runs in a container, the next step is making the container part of your everyday development workflow. Code changes should show up quickly, and services your app depends on, like databases, should run right alongside it. + +In this section, you'll adapt the Dockerfile for local development by renaming the `builder` stage to `dev` and pointing Compose at it. You'll also update the application to connect to a PostgreSQL database, add a database service to `compose.yaml`, persist data in a named volume, enable Compose Watch so changes in your editor are picked up without a manual rebuild, and set up Node.js debugging so you can attach VS Code or Chrome DevTools to the running container. + +### Update the application + +You'll update your application to connect to a PostgreSQL database. Continue working in your `nodejs-docker-example` directory. + +Replace `src/index.ts` and `package.json` with the following contents. The file browser shows only the files that change in this step. + +> [!NOTE] +> +> The application won't run yet after this step. It tries to connect to a +> PostgreSQL database that doesn't exist. The next two sections add the +> database service and the Docker configuration needed to run everything +> together. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="src/index.ts" status="modified" >}} + +```typescript +// Express application backed by a PostgreSQL database. +// Creates a heroes table at startup. +// Endpoints: GET / (greeting), GET /health (health check), POST /heroes/ (create), GET /heroes/ (list). +// See https://expressjs.com/ and https://node-postgres.com/ + +import express, { type Request, type Response } from "express"; +import { Pool } from "pg"; +import { readFileSync } from "fs"; + +const app = express(); +const port = parseInt(process.env.PORT ?? "3000", 10); + +app.use(express.json()); + +function getPassword(): string { + const passwordFile = process.env.POSTGRES_PASSWORD_FILE; + if (passwordFile) { + return readFileSync(passwordFile, "utf8").trim(); + } + return process.env.POSTGRES_PASSWORD ?? ""; +} + +const pool = new Pool({ + host: process.env.POSTGRES_SERVER, + port: 5432, + database: process.env.POSTGRES_DB, + user: process.env.POSTGRES_USER, + password: getPassword(), +}); + +pool + .query( + `CREATE TABLE IF NOT EXISTS heroes ( + id SERIAL PRIMARY KEY, + name TEXT NOT NULL, + secret_name TEXT NOT NULL, + age INTEGER + )`, + ) + .catch(console.error); + +app.get("/", (_req: Request, res: Response) => { + res.json({ message: "Hello World" }); +}); + +app.get("/health", (_req: Request, res: Response) => { + res.json({ status: "ok" }); +}); + +app.post("/heroes/", async (req: Request, res: Response) => { + const { name, secret_name, age } = req.body as { + name: string; + secret_name: string; + age?: number; + }; + const result = await pool.query( + "INSERT INTO heroes (name, secret_name, age) VALUES ($1, $2, $3) RETURNING *", + [name, secret_name, age], + ); + res.json(result.rows[0]); +}); + +app.get("/heroes/", async (_req: Request, res: Response) => { + const result = await pool.query("SELECT * FROM heroes"); + res.json(result.rows); +}); + +app.listen(port, () => { + console.log(`Server listening on port ${port}`); +}); +``` + +{{< /file >}} + +{{< file path="package.json" status="modified" hl_lines="13,18" >}} + +```json +{ + "name": "nodejs-docker-example", + "version": "1.0.0", + "description": "A minimal Node.js TypeScript application.", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsx watch src/index.ts" + }, + "dependencies": { + "express": "^4.21.2", + "pg": "^8.16.0" + }, + "devDependencies": { + "@types/express": "^4.17.21", + "@types/node": "^22.0.0", + "@types/pg": "^8.11.0", + "tsx": "^4.19.3", + "typescript": "^5.8.3" + } +} +``` + +{{< /file >}} + +{{< /files >}} + +### Update Docker assets + +Replace `Dockerfile` and `compose.yaml` with the following. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="Dockerfile" status="modified" hl_lines="12,34,37,63" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Development stage: install all dependencies, compile TypeScript, and +# serve with hot-reload. Used directly in development via compose.yaml. +FROM dhi.io/node:24-alpine3.23-dev AS dev + +WORKDIR /app + +# Install dependencies as a separate step to take advantage of Docker's +# caching. Leverage a cache mount to /root/.npm to speed up subsequent +# builds. Leverage a bind mount to package.json to avoid having to copy +# it into this layer. +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install +# Once you create a package-lock.json by running npm install locally, switch to npm ci and bind both files: +# RUN --mount=type=cache,target=/root/.npm \ +# --mount=type=bind,source=package.json,target=package.json \ +# --mount=type=bind,source=package-lock.json,target=package-lock.json \ +# npm ci + +# Copy the source code into the container and compile TypeScript. +COPY . . +RUN npm run build + +# Expose the port that the application listens on. +EXPOSE 3000 + +# Run the application in development mode. +CMD ["npm", "run", "dev"] + + +# Deps stage: install production dependencies only. +FROM dhi.io/node:24-alpine3.23-dev AS deps + +WORKDIR /app + +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install --omit=dev +# Once you create a package-lock.json by running npm install locally, switch to npm ci and bind both files: +# RUN --mount=type=cache,target=/root/.npm \ +# --mount=type=bind,source=package.json,target=package.json \ +# --mount=type=bind,source=package-lock.json,target=package-lock.json \ +# npm ci --omit=dev + + +# Runner stage: minimal runtime image with compiled app and production deps. +FROM dhi.io/node:24-alpine3.23 AS runner + +ENV PATH=/app/node_modules/.bin:$PATH + +WORKDIR /app + +COPY --from=deps --chown=node:node /app/node_modules ./node_modules +COPY --from=dev --chown=node:node /app/dist ./dist + +# Expose the port that the application listens on. +EXPOSE 3000 + +# Run the application. +CMD ["node", "dist/index.js"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="modified" hl_lines="8" >}} + +```yaml +services: + # Application service. The `target: dev` line builds the development + # image (includes tsx and dev tooling); the runner stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: dev + ports: + - 3000:3000 +``` + +{{< /file >}} + +{{< /files >}} + +#### About these changes + +The `builder` stage from containerize is renamed to `dev` and gains `EXPOSE 3000` and `CMD ["npm", "run", "dev"]`, which runs `tsx watch` for hot-reload. The `deps` and `runner` stages are unchanged. + +In `compose.yaml`, the new `target: dev` line tells Compose to build and run the `dev` stage during development. Unlike the production image, the development image includes `tsx` and other dev tooling. If you need a shell in a running production container, use [Docker Debug](/reference/cli/docker/debug/) instead. + +The build step runs `tsc`, which compiles each TypeScript file into a corresponding JavaScript file. [esbuild](https://esbuild.github.io/) is a popular alternative that bundles everything into a single output file and builds significantly faster. To switch, replace the `tsc` call in `package.json` with an esbuild command and update the `COPY --from=dev` path in the `runner` stage to match esbuild's output. + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data, and add a `db/password.txt` file that holds the database password. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="compose.yaml" status="modified" hl_lines="11-46" >}} + +```yaml +services: + # Application service. The `target: dev` line builds the development + # image (includes tsx and dev tooling); the runner stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: dev + ports: + - 3000:3000 + environment: + - POSTGRES_SERVER=db + - POSTGRES_USER=postgres + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + # Database service. Reads the password from a Docker secret mounted at + # /run/secrets/db-password. Compose waits for the healthcheck to pass + # before starting the server, via the server's depends_on. + db: + image: dhi.io/postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +{{< /file >}} + +{{< file path="db/password.txt" status="new" >}} + +```text +mysecretpassword +``` + +{{< /file >}} + +{{< /files >}} + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +Now test your API endpoint. Open a new terminal and make a request to the server using the curl commands. + +Create an object with a POST request: + +```console +$ curl -X 'POST' \ + 'http://localhost:3000/heroes/' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "my hero", + "secret_name": "austing", + "age": 12 +}' +``` + +You should receive the following response: + +```json +{ + "id": 1, + "name": "my hero", + "secret_name": "austing", + "age": 12 +} +``` + +Now make a GET request: + +```console +$ curl http://localhost:3000/heroes/ +``` + +You should receive the same response because it's the only object in the database. + +Press `ctrl`+`c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yaml` file in an IDE or text editor and add the highlighted Compose Watch instructions. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="compose.yaml" status="modified" hl_lines="21-27" >}} + +```yaml +services: + # Application service. The `target: dev` line builds the development + # image (includes tsx and dev tooling); the runner stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: dev + ports: + - 3000:3000 + environment: + - POSTGRES_SERVER=db + - POSTGRES_USER=postgres + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + develop: + watch: + - action: sync + path: ./src + target: /app/src + - action: rebuild + path: package.json + db: + image: dhi.io/postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +In a terminal, curl the application to get a response. + +```console +$ curl http://localhost:3000 +{"message":"Hello World"} +``` + +Any changes to the application's source files on your local machine will now be immediately reflected in the running container. + +Open `nodejs-docker-example/src/index.ts` in an IDE or text editor and update the `Hello World` string by adding a few more exclamation marks. + +```diff +- res.json({ message: 'Hello World' }); ++ res.json({ message: 'Hello World!!!' }); +``` + +Save the changes to `src/index.ts` and then wait a few seconds for the application to reload. Curl the application again and verify that the updated text appears. + +```console +$ curl http://localhost:3000 +{"message":"Hello World!!!"} +``` + +Press `ctrl`+`c` in the terminal to stop your application. + +### Debug your application + +`tsx watch` supports the Node.js inspector protocol, so you can attach a debugger from VS Code or Chrome DevTools and set breakpoints directly in your TypeScript source files. + +Update the `dev` script in `package.json` to start the inspector. The `--inspect=0.0.0.0:9229` flag tells Node.js to listen for debugger connections on all network interfaces at port 9229. Using `0.0.0.0` rather than `localhost` is necessary so the debugger is reachable from outside the container. Also expose the debug port in `compose.yaml`, and add a `.vscode/launch.json` file that tells VS Code how to attach to the running inspector. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="package.json" status="modified" hl_lines="9" >}} + +```json +{ + "name": "nodejs-docker-example", + "version": "1.0.0", + "description": "A minimal Node.js TypeScript application.", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsx watch --inspect=0.0.0.0:9229 src/index.ts" + }, + "dependencies": { + "express": "^4.21.2", + "pg": "^8.16.0" + }, + "devDependencies": { + "@types/express": "^4.17.21", + "@types/node": "^22.0.0", + "@types/pg": "^8.11.0", + "tsx": "^4.19.3", + "typescript": "^5.8.3" + } +} +``` + +{{< /file >}} + +{{< file path=".vscode/launch.json" status="new" >}} + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Attach to Docker Container", + "type": "node", + "request": "attach", + "port": 9229, + "address": "localhost", + "localRoot": "${workspaceFolder}", + "remoteRoot": "/app", + "protocol": "inspector", + "restart": true, + "sourceMaps": true, + "skipFiles": ["<node_internals>/**"] + } + ] +} +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="modified" hl_lines="11" >}} + +```yaml +services: + # Application service. The `target: dev` line builds the development + # image (includes tsx and dev tooling); the runner stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: dev + ports: + - 3000:3000 + - 9229:9229 + environment: + - POSTGRES_SERVER=db + - POSTGRES_USER=postgres + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + develop: + watch: + - action: sync + path: ./src + target: /app/src + - action: rebuild + path: package.json + db: + image: dhi.io/postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +Rebuild and restart with the updated configuration: + +```console +$ docker compose up --build +``` + +When the inspector is ready, you'll see a line like the following in the logs: + +```text +Debugger listening on ws://0.0.0.0:9229/... +``` + +#### VS Code + +With `.vscode/launch.json` in place, attach the debugger using the Debug panel. + +Open the Debug panel (`Ctrl+Shift+D` on Windows and Linux, `Cmd+Shift+D` on Mac), select **Attach to Docker Container**, and press `F5`. You can now set breakpoints in your TypeScript source files under `src/`. + +#### Chrome DevTools + +You can also use the built-in Node.js inspector in Chrome without any editor setup. + +1. Open Chrome and go to `chrome://inspect`. + +2. Select **Configure** and add `localhost:9229`. + +3. When your Node.js target appears in the list, select **inspect**. + +#### Troubleshoot the debugger + +If the debugger doesn't connect, verify the container is running and the port is mapped correctly: + +```console +$ docker compose ps +$ docker compose logs server +``` + +The logs should include a line like: + +```text +Debugger listening on ws://0.0.0.0:9229/... +``` + +If that line is missing, confirm the `dev` script in `package.json` includes `--inspect=0.0.0.0:9229` and that `9229:9229` appears in the `ports` list for the `server` service in `compose.yaml`. + +For more details about Node.js debugging, see the [Node.js debugging guide](https://nodejs.org/en/docs/guides/debugging-getting-started). + +## Run Node.js tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize a Node.js application](#containerize-a-nodejs-application). + +### Overview + +Testing is a core part of building reliable software. Docker makes it easy to +run your tests in the same environment used in CI and production, so failures +are caught before they reach your users. + +In this section, you'll add [Vitest](https://vitest.dev/) to the project and +run tests both locally and inside a container. + +### Update the application + +You'll refactor `src/index.ts` to export the Express `app` instance so tests +can import it without starting a server. Add a test file and update +`package.json` to add Vitest and a test runner for HTTP requests. The file browser shows only the files that change in this step. + +{{< files name="nodejs-docker-example" >}} + +{{< file path="src/index.ts" status="modified" hl_lines="10,31,70-75" >}} + +```typescript +// Express application backed by a PostgreSQL database. +// Creates a heroes table at startup. +// Endpoints: GET / (greeting), GET /health (health check), POST /heroes/ (create), GET /heroes/ (list). +// See https://expressjs.com/ and https://node-postgres.com/ + +import express, { type Request, type Response } from "express"; +import { Pool } from "pg"; +import { readFileSync } from "fs"; + +export const app = express(); +const port = parseInt(process.env.PORT ?? "3000", 10); + +app.use(express.json()); + +function getPassword(): string { + const passwordFile = process.env.POSTGRES_PASSWORD_FILE; + if (passwordFile) { + return readFileSync(passwordFile, "utf8").trim(); + } + return process.env.POSTGRES_PASSWORD ?? ""; +} + +const pool = new Pool({ + host: process.env.POSTGRES_SERVER, + port: 5432, + database: process.env.POSTGRES_DB, + user: process.env.POSTGRES_USER, + password: getPassword(), +}); + +if (process.env.POSTGRES_SERVER) { + pool + .query( + `CREATE TABLE IF NOT EXISTS heroes ( + id SERIAL PRIMARY KEY, + name TEXT NOT NULL, + secret_name TEXT NOT NULL, + age INTEGER + )`, + ) + .catch(console.error); +} + +app.get("/", (_req: Request, res: Response) => { + res.json({ message: "Hello World" }); +}); + +app.get("/health", (_req: Request, res: Response) => { + res.json({ status: "ok" }); +}); + +app.post("/heroes/", async (req: Request, res: Response) => { + const { name, secret_name, age } = req.body as { + name: string; + secret_name: string; + age?: number; + }; + const result = await pool.query( + "INSERT INTO heroes (name, secret_name, age) VALUES ($1, $2, $3) RETURNING *", + [name, secret_name, age], + ); + res.json(result.rows[0]); +}); + +app.get("/heroes/", async (_req: Request, res: Response) => { + const result = await pool.query("SELECT * FROM heroes"); + res.json(result.rows); +}); + +// Only start the server when this file is run directly. +if (require.main === module) { + app.listen(port, () => { + console.log(`Server listening on port ${port}`); + }); +} +``` + +{{< /file >}} + +{{< file path="src/index.test.ts" status="new" >}} + +```typescript +// Unit tests for the Express application. +// Tests the root endpoint without starting a server. +// See https://vitest.dev/ for the test framework reference. + +import { describe, it, expect } from "vitest"; +import request from "supertest"; +import { app } from "./index"; + +describe("GET /", () => { + it("returns a JSON greeting", async () => { + const response = await request(app).get("/"); + expect(response.status).toBe(200); + expect(response.body).toEqual({ message: "Hello World" }); + }); +}); +``` + +{{< /file >}} + +{{< file path="package.json" status="modified" hl_lines="10,20-22" >}} + +```json +{ + "name": "nodejs-docker-example", + "version": "1.0.0", + "description": "A minimal Node.js TypeScript application.", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsx watch src/index.ts", + "test": "vitest run" + }, + "dependencies": { + "express": "^4.21.2", + "pg": "^8.16.0" + }, + "devDependencies": { + "@types/express": "^4.17.21", + "@types/node": "^22.0.0", + "@types/pg": "^8.11.0", + "supertest": "^7.0.0", + "@types/supertest": "^6.0.0", + "tsx": "^4.19.3", + "typescript": "^5.8.3", + "vitest": "^3.0.0" + } +} +``` + +{{< /file >}} + +{{< /files >}} + +### Run tests locally + +Run the following command to run the tests locally: + +```console +$ npm install +$ npm test +``` + +You should see output like the following: + +```console + RUN v3.0.0 /app + + ✓ src/index.test.ts (1) + ✓ GET / (1) + ✓ returns a JSON greeting + + Test Files 1 passed (1) + Tests 1 passed (1) + Start at 12:00:00 + Duration 500ms +``` + +### Run tests in a container + +Run the tests using the dev stage of your Dockerfile: + +```console +$ docker compose run --build --rm --no-deps server npm test +``` + +The `--no-deps` flag skips starting the database, since the unit tests don't require it. The `--rm` flag removes the container when the tests finish. + +You should see the same test output as when running locally. + +### Run tests when building + +To run tests during the Docker build process, add a `test` stage to your Dockerfile that runs after the dev stage. + +```dockerfile {hl_lines="32-36"} +FROM dhi.io/node:24-alpine3.23-dev AS dev + +WORKDIR /app + +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install + +COPY . . +RUN npm run build + +EXPOSE 3000 +CMD ["npm", "run", "dev"] + + +FROM dhi.io/node:24-alpine3.23-dev AS deps +WORKDIR /app +RUN --mount=type=cache,target=/root/.npm \ + --mount=type=bind,source=package.json,target=package.json \ + npm install --omit=dev + +FROM dhi.io/node:24-alpine3.23 AS runner +ENV PATH=/app/node_modules/.bin:$PATH +WORKDIR /app +COPY --from=deps --chown=node:node /app/node_modules ./node_modules +COPY --from=dev --chown=node:node /app/dist ./dist + +EXPOSE 3000 +CMD ["node", "dist/index.js"] + + +FROM dev AS test + +ENV CI=true + +CMD ["npm", "test"] +``` + +Then build and run the test stage: + +```console +$ docker build --target test -t nodejs-app-test . +$ docker run --rm nodejs-app-test +``` + +### Summary + +In this section, you learned how to run tests when developing locally and inside a container. + +Related information: + +- [Dockerfile reference](/reference/dockerfile/) +- [Compose file reference](/compose/compose-file/) +- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) diff --git a/content/guides/nodejs/_index.md b/content/guides/nodejs/_index.md deleted file mode 100644 index 57bd6acc1942..000000000000 --- a/content/guides/nodejs/_index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Node.js language-specific guide -linkTitle: Node.js -description: Containerize and develop Node.js apps using Docker -keywords: getting started, node, node.js -summary: | - This guide explains how to containerize Node.js applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/nodejs/ - - /guides/language/nodejs/ -languages: [js] -tags: [dhi] -params: - time: 20 minutes ---- - -[Node.js](https://nodejs.org/en) is a JavaScript runtime for building web applications. This guide shows you how to containerize a TypeScript Node.js application with a React frontend and PostgreSQL database. - -The sample application is a modern full-stack Todo application featuring: - -- **Backend**: Express.js with TypeScript, PostgreSQL database, and RESTful API -- **Frontend**: React.js with Vite and Tailwind CSS 4 - - -> **Acknowledgment** -> -> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Full-stack engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows. - ---- - -## What will you learn? - -In this guide, you will learn how to: - -- Containerize and run a Node.js application using Docker. -- Run tests inside a Docker container. -- Set up a development container environment. -- Configure GitHub Actions for CI/CD with Docker. -- Deploy your Dockerized Node.js app to Kubernetes. - -To begin, you’ll start by containerizing an existing Node.js application. - ---- - -## Prerequisites - -Before you begin, make sure you're familiar with the following: - -- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [TypeScript](https://www.typescriptlang.org/). -- Basic knowledge of [Node.js](https://nodejs.org/en), [npm](https://docs.npmjs.com/about-npm), and [React](https://react.dev/) for modern web development. -- Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. -- Familiarity with [Express.js](https://expressjs.com/) for backend API development. - -Once you've completed the Node.js getting started modules, you’ll be ready to containerize your own Node.js application using the examples and instructions provided in this guide. diff --git a/content/guides/nodejs/configure-github-actions.md b/content/guides/nodejs/configure-github-actions.md deleted file mode 100644 index 7465ac05176e..000000000000 --- a/content/guides/nodejs/configure-github-actions.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 50 -keywords: CI/CD, GitHub Actions, Node.js, Docker -description: Learn how to configure CI/CD using GitHub Actions for your Node.js application. -aliases: - - /language/nodejs/configure-ci-cd/ - - /guides/language/nodejs/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Node.js application](containerize.md). - -You must also have: - -- A [GitHub](https://github.com/signup) account. -- A verified [Docker Hub](https://hub.docker.com/signup) account. - ---- - -## Overview - -In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically: - -- Build your Node.js application inside a Docker container. -- Run unit and integration tests, and make sure your application meets solid code quality standards. -- Perform security scanning and vulnerability assessment. -- Push production-ready images to [Docker Hub](https://hub.docker.com). - ---- - -## Connect your GitHub repository to Docker Hub - -To enable GitHub Actions to build and push Docker images, you'll securely store your Docker Hub credentials in your new GitHub repository. - -### Step 1: Connect your GitHub repository to Docker Hub - -1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com). - 1. From your Docker Hub account, go to **Account Settings → Security**. - 2. Generate a new Access Token with **Read/Write** permissions. - 3. Name it something like `docker-nodejs-sample`. - 4. Copy and save the token — you'll need it in Step 4. - -2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/). - 1. From your Docker Hub account, select **Create a repository**. - 2. For the Repository Name, use something descriptive — for example: `nodejs-sample`. - 3. Once created, copy and save the repository name — you'll need it in Step 4. - -3. Create a new [GitHub repository](https://github.com/new) for your Node.js project. - -4. Add Docker Hub credentials as GitHub repository secrets. - - In your newly created GitHub repository: - 1. From **Settings**, go to **Secrets and variables → Actions → New repository secret**. - - 2. Add the following secrets: - - | Name | Value | - | ------------------------ | ------------------------------------------------ | - | `DOCKER_USERNAME` | Your Docker Hub username | - | `DOCKERHUB_TOKEN` | Your Docker Hub access token (created in Step 1) | - | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2) | - - These secrets let GitHub Actions to authenticate securely with Docker Hub during automated workflows. - -5. Connect your local project to GitHub. - - Link your local project `docker-nodejs-sample` to the GitHub repository you just created by running the following command from your project root: - - ```console - $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git - ``` - - > [!IMPORTANT] - > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name. - - To confirm that your local project is correctly connected to the remote GitHub repository, run: - - ```console - $ git remote -v - ``` - - You should see output similar to: - - ```console - origin https://github.com/{your-username}/{your-repository-name}.git (fetch) - origin https://github.com/{your-username}/{your-repository-name}.git (push) - ``` - - This confirms that your local repository is properly linked and ready to push your source code to GitHub. - -6. Push your source code to GitHub. - - Follow these steps to commit and push your local project to your GitHub repository: - 1. Stage all files for commit. - - ```console - $ git add -A - ``` - - This command stages all changes — including new, modified, and deleted files — preparing them for commit. - - 2. Commit your changes. - - ```console - $ git commit -m "Initial commit with CI/CD pipeline" - ``` - - This command creates a commit that snapshots the staged changes with a descriptive message. - - 3. Push the code to the `main` branch. - - ```console - $ git push -u origin main - ``` - - This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch. - -Once completed, your code will be available on GitHub, and any GitHub Actions workflow you've configured will run automatically. - -> [!NOTE] -> Learn more about the Git commands used in this step: -> -> - [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit -> - [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes -> - [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository -> - [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs - ---- - -### Step 2: Set up the workflow - -Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub. - -1. From your repository on GitHub, select the **Actions** tab in the top menu. - -2. When prompted, select **Set up a workflow yourself**. - - This opens an inline editor to create a new workflow file. By default, it will be saved to: - `.github/workflows/main.yml` - -3. Add the following workflow configuration to the new file: - -```yaml -name: CI/CD – Node.js Application with Docker - -on: - push: - branches: [main] - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - -jobs: - test: - name: Run Node.js Tests - runs-on: ubuntu-latest - - services: - postgres: - image: postgres:18-alpine - env: - POSTGRES_DB: todoapp_test - POSTGRES_USER: postgres - POSTGRES_PASSWORD: postgres - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - - 5432:5432 - - steps: - - name: Checkout code - uses: actions/checkout@{{% param "checkout_action_version" %}} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Cache npm dependencies - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: ~/.npm - key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} - restore-keys: ${{ runner.os }}-npm- - - - name: Build test image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - target: test - tags: nodejs-app-test:latest - platforms: linux/amd64 - load: true - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - - - name: Run tests inside container - run: | - docker run --rm \ - --network host \ - -e NODE_ENV=test \ - -e POSTGRES_HOST=localhost \ - -e POSTGRES_PORT=5432 \ - -e POSTGRES_DB=todoapp_test \ - -e POSTGRES_USER=postgres \ - -e POSTGRES_PASSWORD=postgres \ - nodejs-app-test:latest - env: - CI: true - timeout-minutes: 10 - - build-and-push: - name: Build and Push Docker Image - runs-on: ubuntu-latest - needs: test - - steps: - - name: Checkout code - uses: actions/checkout@{{% param "checkout_action_version" %}} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Cache Docker layers - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: ${{ runner.os }}-buildx- - - - name: Extract metadata - id: meta - run: | - echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT" - echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT" - - - name: Log in to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Build and push multi-arch production image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - target: production - push: true - platforms: linux/amd64,linux/arm64 - tags: | - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }} - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max -``` - -This workflow performs the following tasks for your Node.js application: - -- Triggers on every `push` or `pull request` to the `main` branch. -- Builds a test Docker image using the `test` stage. -- Runs tests in a containerized environment. -- Stops the workflow if any test fails. -- Caches Docker build layers and npm dependencies for faster runs. -- Authenticates with Docker Hub using GitHub secrets. -- Builds an image using the `production` stage. -- Tags and pushes the image to Docker Hub with `latest` and short SHA tags. - -> [!NOTE] -> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - ---- - -### Step 3: Run the workflow - -After adding your workflow file, trigger the CI/CD process. - -1. Commit and push your workflow file - - From the GitHub editor, select **Commit changes…**. - - This push automatically triggers the GitHub Actions pipeline. - -2. Monitor the workflow execution - 1. From your GitHub repository, go to the **Actions** tab. - 2. Select the workflow run to follow each step: `test`, `build`, `security`, and (if successful) `push` and `deploy`. - -3. Verify the Docker image on Docker Hub - - After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories). - - You should see a new image under your repository with: - - Repository name: `${your-repository-name}` - - Tags include: - - `latest` – represents the most recent successful build; ideal for quick testing or deployment. - - `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability. - -> [!TIP] Protect your main branch -> To maintain code quality and prevent accidental direct pushes, enable branch protection rules: -> -> - From your GitHub repository, go to **Settings → Branches**. -> - Under Branch protection rules, select **Add rule**. -> - Specify `main` as the branch name. -> - Enable options like: -> - _Require a pull request before merging_. -> - _Require status checks to pass before merging_. -> -> This ensures that only tested and reviewed code is merged into `main` branch. - ---- - -## Summary - -In this section, you set up a comprehensive CI/CD pipeline for your containerized Node.js application using GitHub Actions. - -What you accomplished: - -- Created a new GitHub repository specifically for your project. -- Generated a Docker Hub access token and added it as a GitHub secret. -- Created a GitHub Actions workflow that: - - Builds your application in a Docker container. - - Run tests in a containerized environment. - - Pushes an image to Docker Hub if tests pass. -- Verified the workflow runs successfully. - -Your Node.js application now has automated testing and deployment. - ---- - -## Related resources - -Deepen your understanding of automation and best practices for containerized apps: - -- [Introduction to GitHub Actions](/guides/gha.md) – Learn how GitHub Actions automate your workflows -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) – Set up container builds with GitHub Actions -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows -- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) – Learn about GHCR features and usage -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security - ---- - -## Next steps - -Next, learn how you can deploy your containerized Node.js application to Kubernetes with production-ready configuration. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment. diff --git a/content/guides/nodejs/containerize.md b/content/guides/nodejs/containerize.md deleted file mode 100644 index 92edf95c15d0..000000000000 --- a/content/guides/nodejs/containerize.md +++ /dev/null @@ -1,817 +0,0 @@ ---- -title: Containerize a Node.js application -linkTitle: Containerize -weight: 10 -keywords: node.js, node, containerize, initialize -description: Learn how to containerize a Node.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability. -aliases: - - /get-started/nodejs/build-images/ - - /language/nodejs/build-images/ - - /language/nodejs/run-containers/ - - /language/nodejs/containerize/ - - /guides/language/nodejs/containerize/ ---- - -## Prerequisites - -Before you begin, make sure the following tools are installed and available on your system: - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -> [!NOTE] -> New to Docker? Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. - ---- - -## Overview - -This guide walks you through the complete process of containerizing a Node.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that enhance performance, security, scalability, and operational efficiency. - -By the end of this guide, you will: - -- Containerize a Node.js application using Docker. -- Create and optimize a Dockerfile tailored for Node.js environments. -- Use multi-stage builds to separate dependencies and reduce image size. -- Configure the container for secure, efficient runtime using a non-root user. -- Follow best practices for building secure, lightweight, and maintainable Docker images. - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following command -to clone the Git repository: - -```console -$ git clone https://github.com/kristiyan-velkov/docker-nodejs-sample -``` - -## Build the Docker image - -This project is a full-stack TypeScript application with both a backend API and frontend React components, so the Dockerfile is optimized for that architecture. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -### Step 1: Create the Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -> [!IMPORTANT] -> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. -> -> Official Node.js Docker Images: https://hub.docker.com/_/node - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} -Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -Create a file named `Dockerfile` in your project root with the following contents. The `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image. - -```dockerfile -# ======================================== -# Optimized Multi-Stage Dockerfile -# Node.js TypeScript Application (Using DHI) -# ======================================== - -FROM dhi.io/node:24-alpine3.22-dev AS base - -# Set working directory -WORKDIR /app - -# Create non-root user for security -RUN addgroup -g 1001 -S nodejs && \ - adduser -S nodejs -u 1001 -G nodejs && \ - chown -R nodejs:nodejs /app - -# ======================================== -# Dependencies Stage -# ======================================== -FROM base AS deps - -# Copy package files -COPY package*.json ./ - -# Install production dependencies -RUN --mount=type=cache,target=/root/.npm,sharing=locked \ - npm ci --omit=dev && \ - npm cache clean --force - -# Set proper ownership -RUN chown -R nodejs:nodejs /app - -# ======================================== -# Build Dependencies Stage -# ======================================== -FROM base AS build-deps - -# Copy package files -COPY package*.json ./ - -# Install all dependencies with build optimizations -RUN --mount=type=cache,target=/root/.npm,sharing=locked \ - npm ci --no-audit --no-fund && \ - npm cache clean --force - -# Create necessary directories and set permissions -RUN mkdir -p /app/node_modules/.vite && \ - chown -R nodejs:nodejs /app - -# ======================================== -# Build Stage -# ======================================== -FROM build-deps AS build - -# Copy only necessary files for building (respects .dockerignore) -COPY --chown=nodejs:nodejs . . - -# Build the application -RUN npm run build - -# Set proper ownership -RUN chown -R nodejs:nodejs /app - -# ======================================== -# Development Stage -# ======================================== -FROM build-deps AS development - -# Set environment -ENV NODE_ENV=development \ - NPM_CONFIG_LOGLEVEL=warn - -# Copy source files -COPY . . - -# Ensure all directories have proper permissions -RUN mkdir -p /app/node_modules/.vite && \ - chown -R nodejs:nodejs /app && \ - chmod -R 755 /app - -# Switch to non-root user -USER nodejs - -# Expose ports -EXPOSE 3000 5173 9229 - -# Start development server -CMD ["npm", "run", "dev:docker"] - -# ======================================== -# Production Stage -# ======================================== -FROM dhi.io/node:24-alpine3.22-dev AS production - -# Set working directory -WORKDIR /app - -# Create non-root user for security -RUN addgroup -g 1001 -S nodejs && \ - adduser -S nodejs -u 1001 -G nodejs && \ - chown -R nodejs:nodejs /app - -# Set optimized environment variables -ENV NODE_ENV=production \ - NODE_OPTIONS="--max-old-space-size=256 --no-warnings" \ - NPM_CONFIG_LOGLEVEL=silent - -# Copy production dependencies from deps stage -COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules -COPY --from=deps --chown=nodejs:nodejs /app/package*.json ./ -# Copy built application from build stage -COPY --from=build --chown=nodejs:nodejs /app/dist ./dist - -# Switch to non-root user for security -USER nodejs - -# Expose port -EXPOSE 3000 - -# Start production server -CMD ["node", "dist/server.js"] - -# ======================================== -# Test Stage -# ======================================== -FROM build-deps AS test - -# Set environment -ENV NODE_ENV=test \ - CI=true - -# Copy source files -COPY --chown=nodejs:nodejs . . - -# Switch to non-root user -USER nodejs - -# Run tests with coverage -CMD ["npm", "run", "test:coverage"] -``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` in your project root with the following contents: - -```dockerfile -# ======================================== -# Optimized Multi-Stage Dockerfile -# Node.js TypeScript Application -# ======================================== - -ARG NODE_VERSION=24.11.1-alpine -FROM node:${NODE_VERSION} AS base - -# Set working directory -WORKDIR /app - -# Create non-root user for security -RUN addgroup -g 1001 -S nodejs && \ - adduser -S nodejs -u 1001 -G nodejs && \ - chown -R nodejs:nodejs /app - -# ======================================== -# Dependencies Stage -# ======================================== -FROM base AS deps - -# Copy package files -COPY package*.json ./ - -# Install production dependencies -RUN --mount=type=cache,target=/root/.npm,sharing=locked \ - npm ci --omit=dev && \ - npm cache clean --force - -# Set proper ownership -RUN chown -R nodejs:nodejs /app - -# ======================================== -# Build Dependencies Stage -# ======================================== -FROM base AS build-deps - -# Copy package files -COPY package*.json ./ - -# Install all dependencies with build optimizations -RUN --mount=type=cache,target=/root/.npm,sharing=locked \ - npm ci --no-audit --no-fund && \ - npm cache clean --force - -# Create necessary directories and set permissions -RUN mkdir -p /app/node_modules/.vite && \ - chown -R nodejs:nodejs /app - -# ======================================== -# Build Stage -# ======================================== -FROM build-deps AS build - -# Copy only necessary files for building (respects .dockerignore) -COPY --chown=nodejs:nodejs . . - -# Build the application -RUN npm run build - -# Set proper ownership -RUN chown -R nodejs:nodejs /app - -# ======================================== -# Development Stage -# ======================================== -FROM build-deps AS development - -# Set environment -ENV NODE_ENV=development \ - NPM_CONFIG_LOGLEVEL=warn - -# Copy source files -COPY . . - -# Ensure all directories have proper permissions -RUN mkdir -p /app/node_modules/.vite && \ - chown -R nodejs:nodejs /app && \ - chmod -R 755 /app - -# Switch to non-root user -USER nodejs - -# Expose ports -EXPOSE 3000 5173 9229 - -# Start development server -CMD ["npm", "run", "dev:docker"] - -# ======================================== -# Production Stage -# ======================================== -ARG NODE_VERSION=24.11.1-alpine -FROM node:${NODE_VERSION} AS production - -# Set working directory -WORKDIR /app - -# Create non-root user for security -RUN addgroup -g 1001 -S nodejs && \ - adduser -S nodejs -u 1001 -G nodejs && \ - chown -R nodejs:nodejs /app - -# Set optimized environment variables -ENV NODE_ENV=production \ - NODE_OPTIONS="--max-old-space-size=256 --no-warnings" \ - NPM_CONFIG_LOGLEVEL=silent - -# Copy production dependencies from deps stage -COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules -COPY --from=deps --chown=nodejs:nodejs /app/package*.json ./ -# Copy built application from build stage -COPY --from=build --chown=nodejs:nodejs /app/dist ./dist - -# Switch to non-root user for security -USER nodejs - -# Expose port -EXPOSE 3000 - -# Start production server -CMD ["node", "dist/server.js"] - -# ======================================== -# Test Stage -# ======================================== -FROM build-deps AS test - -# Set environment -ENV NODE_ENV=test \ - CI=true - -# Copy source files -COPY --chown=nodejs:nodejs . . - -# Switch to non-root user -USER nodejs - -# Run tests with coverage -CMD ["npm", "run", "test:coverage"] -``` - -{{< /tab >}} - -{{< /tabs >}} - -Key features of this Dockerfile: - -- Multi-stage structure — Separate stages for dependencies, build, development, production, and testing to keep each phase clean and efficient. -- Lean production image — Optimized layering reduces size and keeps only what’s required to run the app. -- Security-minded setup — Uses a dedicated non-root user and excludes unnecessary packages. -- Performance-friendly design — Effective use of caching and well-structured layers for faster builds. -- Clean runtime environment — Removes files not needed in production, such as docs, tests, and build caches. -- Straightforward port usage — The app runs on port 3000 internally, exposed externally as port 8080. -- Memory-optimized runtime — Node.js is configured to run with a smaller memory limit than the default. - -### Step 2: Create the compose.yaml file - -Create a file named `compose.yaml` in your project root: - -```yaml -# ======================================== -# Docker Compose Configuration -# Modern Node.js Todo Application -# ======================================== - -services: - # ======================================== - # Development Service - # ======================================== - app-dev: - build: - context: . - dockerfile: Dockerfile - target: development - container_name: todoapp-dev - ports: - - "${APP_PORT:-3000}:3000" # API server - - "${VITE_PORT:-5173}:5173" # Vite dev server - - "${DEBUG_PORT:-9229}:9229" # Node.js debugger - environment: - NODE_ENV: development - DOCKER_ENV: "true" - POSTGRES_HOST: db - POSTGRES_PORT: 5432 - POSTGRES_DB: todoapp - POSTGRES_USER: todoapp - POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}" - ALLOWED_ORIGINS: "${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}" - volumes: - - ./src:/app/src:ro - - ./package.json:/app/package.json - - ./vite.config.ts:/app/vite.config.ts:ro - - ./tailwind.config.js:/app/tailwind.config.js:ro - - ./postcss.config.js:/app/postcss.config.js:ro - depends_on: - db: - condition: service_healthy - develop: - watch: - - action: sync - path: ./src - target: /app/src - ignore: - - "**/*.test.*" - - "**/__tests__/**" - - action: rebuild - path: ./package.json - - action: sync - path: ./vite.config.ts - target: /app/vite.config.ts - - action: sync - path: ./tailwind.config.js - target: /app/tailwind.config.js - - action: sync - path: ./postcss.config.js - target: /app/postcss.config.js - restart: unless-stopped - networks: - - todoapp-network - - # ======================================== - # Production Service - # ======================================== - app-prod: - build: - context: . - dockerfile: Dockerfile - target: production - container_name: todoapp-prod - ports: - - "${PROD_PORT:-8080}:3000" - environment: - NODE_ENV: production - POSTGRES_HOST: db - POSTGRES_PORT: 5432 - POSTGRES_DB: todoapp - POSTGRES_USER: todoapp - POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}" - ALLOWED_ORIGINS: "${ALLOWED_ORIGINS:-https://yourdomain.com}" - depends_on: - db: - condition: service_healthy - restart: unless-stopped - deploy: - resources: - limits: - memory: "${PROD_MEMORY_LIMIT:-2G}" - cpus: "${PROD_CPU_LIMIT:-1.0}" - reservations: - memory: "${PROD_MEMORY_RESERVATION:-512M}" - cpus: "${PROD_CPU_RESERVATION:-0.25}" - security_opt: - - no-new-privileges:true - read_only: true - tmpfs: - - /tmp - networks: - - todoapp-network - profiles: - - prod - - # ======================================== - # PostgreSQL Database Service - # ======================================== - db: - image: postgres:18-alpine - container_name: todoapp-db - environment: - POSTGRES_DB: "${POSTGRES_DB:-todoapp}" - POSTGRES_USER: "${POSTGRES_USER:-todoapp}" - POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}" - volumes: - - postgres_data:/var/lib/postgresql - ports: - - "${DB_PORT:-5432}:5432" - restart: unless-stopped - healthcheck: - test: - [ - "CMD-SHELL", - "pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}", - ] - interval: 10s - timeout: 5s - retries: 5 - start_period: 5s - networks: - - todoapp-network - -# ======================================== -# Volume Configuration -# ======================================== -volumes: - postgres_data: - name: todoapp-postgres-data - driver: local - -# ======================================== -# Network Configuration -# ======================================== -networks: - todoapp-network: - name: todoapp-network - driver: bridge -``` - -This Docker Compose configuration includes: - -- Development service (`app-dev`): Full development environment with hot reload, debugging support, and bind mounts -- Production service (`app-prod`): Optimized production deployment with resource limits and security hardening -- Database service (`db`): PostgreSQL 18 with persistent storage and health checks -- Networking: Isolated network for secure service communication -- Volumes: Persistent storage for database data - -### Step 3: Create environment configuration - -Create a `.env` file to configure your application settings: - -```console -$ cp .env.example .env -``` - -Update the `.env` file with your preferred settings: - -```env -# Application Configuration -NODE_ENV=development -APP_PORT=3000 -VITE_PORT=5173 -DEBUG_PORT=9229 - -# Production Configuration -PROD_PORT=8080 -PROD_MEMORY_LIMIT=2G -PROD_CPU_LIMIT=1.0 -PROD_MEMORY_RESERVATION=512M -PROD_CPU_RESERVATION=0.25 - -# Database Configuration -POSTGRES_HOST=db -POSTGRES_PORT=5432 -POSTGRES_DB=todoapp -POSTGRES_USER=todoapp -POSTGRES_PASSWORD=todoapp_password -DB_PORT=5432 - -# Security Configuration -ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173 -``` - -### Step 4: Configure the .dockerignore file - -The `.dockerignore` file tells Docker which files and folders to exclude when building the image. - -> [!NOTE] -> This helps: -> -> - Reduce image size -> - Speed up the build process -> - Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. -> -> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). - -Create a file named `.dockerignore` with the following contents: - -```dockerignore -# Optimized .dockerignore for Node.js + React Todo App -# Based on actual project structure - -# Version control -.git/ -.github/ -.gitignore - -# Dependencies (installed in container) -node_modules/ - -# Build outputs (built in container) -dist/ - -# Environment files -.env* - -# Development files -.vscode/ -*.log -coverage/ -.eslintcache - -# OS files -.DS_Store -Thumbs.db - -# Documentation -*.md -docs/ - -# Deployment configs -compose.yaml -Taskfile.yml -nodejs-sample-kubernetes.yaml - -# Non-essential configs (keep build configs) -*.config.js -!vite.config.ts -!esbuild.config.js -!tailwind.config.js -!postcss.config.js -!tsconfig.json -``` - -### Step 5: Build the Node.js application image - -After creating all the configuration files, your project directory should now contain all necessary Docker configuration files: - -```text -├── docker-nodejs-sample/ -│ ├── Dockerfile -│ ├── .dockerignore -│ ├── compose.yaml -│ └── .env -``` - -Now you can build the Docker image for your Node.js application. - -> [!NOTE] -> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). - -Run the following command from the root of your project: - -```console -$ docker build --target production --tag docker-nodejs-sample . -``` - -What this command does: - -- Uses the Dockerfile in the current directory (.) -- Targets the production stage of the multi-stage build -- Packages the application and its dependencies into a Docker image -- Tags the image as docker-nodejs-sample so you can reference it later - -### Step 6: View local images - -After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, use the Docker CLI. - -To list all locally available Docker images, run the following command: - -```console -$ docker images -``` - -Example Output: - -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-nodejs-sample latest 423525528038 14 seconds ago 237.46MB -``` - -This output provides key details about your images: - -- Repository – The name assigned to the image. -- Tag – A version label that helps identify different builds (e.g., latest). -- Image ID – A unique identifier for the image. -- Created – The timestamp indicating when the image was built. -- Size – The total disk space used by the image. - -If the build was successful, you should see `docker-nodejs-sample` image listed. - ---- - -## Run the containerized application - -In the previous step, you created a Dockerfile for your Node.js application and built a Docker image using the `docker build` command. Now it’s time to run that image in a container and verify that your application works as expected. - -Inside the `docker-nodejs-sample` directory, run the following command in a terminal. - -```console -$ docker compose up app-dev --build -``` - -The development application will start with both servers: - -- API Server: [http://localhost:3000](http://localhost:3000) - Express.js backend with REST API -- Frontend: [http://localhost:5173](http://localhost:5173) - Vite dev server with React frontend -- Health Check: [http://localhost:3000/health](http://localhost:3000/health) - Application health status - -For production deployment, you can use: - -```console -$ docker compose up app-prod --build -``` - -Which serves the full-stack app at [http://localhost:8080](http://localhost:8080) with the Express server running on port 3000 internally, mapped to port 8080 externally. - -You should see a modern Todo List application with React 19 and a fully functional REST API. - -Press `CTRL + C` in the terminal to stop your application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-nodejs-sample` directory, run the following command in a terminal. - -```console -$ docker compose up app-dev --build -d -``` - -Open a browser and view the application at [http://localhost:3000](http://localhost:3000) (API) or [http://localhost:5173](http://localhost:5173) (frontend). You should see the Todo application running. - -To confirm that the container is running, use `docker ps` command: - -```console -$ docker ps -``` - -This will list all active containers along with their ports, names, and status. Look for a container exposing ports 3000, 5173, and 9229 for the development app. - -Example Output: - -```shell -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -93f3faee32c3 docker-nodejs-sample-app-dev "docker-entrypoint.s…" 33 seconds ago Up 31 seconds 0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp, 0.0.0.0:5173->5173/tcp, [::]:5173->5173/tcp, 0.0.0.0:9230->9229/tcp, [::]:9230->9229/tcp todoapp-dev -``` - -### Run different profiles - -You can run different configurations using Docker Compose profiles: - -```console -# Run production -$ docker compose up app-prod -d - -# Run tests -$ docker compose up app-test -d -``` - -To stop the application, run: - -```console -$ docker compose down -``` - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this guide, you learned how to containerize, build, and run a Node.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup. - -What you accomplished: - -- Created a `Dockerfile` with a multi-stage build optimized for TypeScript and React. -- Created a `compose.yaml` file with development, production, and database services. -- Set up environment configuration with a `.env` file for flexible deployment settings. -- Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient. -- Built your Docker image using `docker build`. -- Ran the container using `docker compose up`, both in the foreground and in detached mode. -- Verified that the app was running by visiting [http://localhost:8080](http://localhost:8080) (production) or [http://localhost:3000](http://localhost:3000) (development). -- Learned how to stop the containerized application using `docker compose down`. - -You now have a fully containerized Node.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker workflow: - -- [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds. -- [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile. -- [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images. -- [`docker compose up` CLI reference](/reference/cli/docker/compose/up/) – Start and run multi-container applications. -- [`docker compose down` CLI reference](/reference/cli/docker/compose/down/) – Stop and remove containers, networks, and volumes. - ---- - -## Next steps - -With your Node.js application now containerized, you're ready to move on to the next step. - -In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine. diff --git a/content/guides/nodejs/deploy.md b/content/guides/nodejs/deploy.md deleted file mode 100644 index 55db76b0d217..000000000000 --- a/content/guides/nodejs/deploy.md +++ /dev/null @@ -1,594 +0,0 @@ ---- -title: Deploy your Node.js application -linkTitle: Deploy your app -weight: 50 -keywords: deploy, kubernetes, node, node.js, production -description: Learn how to deploy your containerized Node.js application to Kubernetes with production-ready configuration -aliases: - - /language/nodejs/deploy/ - - /guides/language/nodejs/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a Node.js application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to deploy your containerized Node.js application to Kubernetes using Docker Desktop. This deployment uses production-ready configurations including security hardening, auto-scaling, persistent storage, and high availability features. - -You'll deploy a complete stack including: - -- Node.js Todo application with 3 replicas. -- PostgreSQL database with persistent storage. -- Auto-scaling based on CPU and memory usage. -- Ingress configuration for external access. -- Security settings. - -## Create a Kubernetes deployment file - -Create a new file called `nodejs-sample-kubernetes.yaml` in your project root: - -```yaml -# ======================================== -# Node.js Todo App - Kubernetes Deployment -# ======================================== - -apiVersion: v1 -kind: Namespace -metadata: - name: todoapp - labels: - app: todoapp - ---- -# ======================================== -# ConfigMap for Application Configuration -# ======================================== -apiVersion: v1 -kind: ConfigMap -metadata: - name: todoapp-config - namespace: todoapp -data: - NODE_ENV: 'production' - ALLOWED_ORIGINS: 'https://yourdomain.com' - POSTGRES_HOST: 'todoapp-postgres' - POSTGRES_PORT: '5432' - POSTGRES_DB: 'todoapp' - POSTGRES_USER: 'todoapp' - ---- -# ======================================== -# Secret for Database Credentials -# ======================================== -apiVersion: v1 -kind: Secret -metadata: - name: todoapp-secrets - namespace: todoapp -type: Opaque -data: - postgres-password: dG9kb2FwcF9wYXNzd29yZA== # base64 encoded "todoapp_password" - ---- -# ======================================== -# PostgreSQL PersistentVolumeClaim -# ======================================== -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: postgres-pvc - namespace: todoapp -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - storageClassName: standard - ---- -# ======================================== -# PostgreSQL Deployment -# ======================================== -apiVersion: apps/v1 -kind: Deployment -metadata: - name: todoapp-postgres - namespace: todoapp - labels: - app: todoapp-postgres -spec: - replicas: 1 - selector: - matchLabels: - app: todoapp-postgres - template: - metadata: - labels: - app: todoapp-postgres - spec: - containers: - - name: postgres - image: postgres:18-alpine - ports: - - containerPort: 5432 - name: postgres - env: - - name: POSTGRES_DB - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_DB - - name: POSTGRES_USER - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_USER - - name: POSTGRES_PASSWORD - valueFrom: - secretKeyRef: - name: todoapp-secrets - key: postgres-password - volumeMounts: - - name: postgres-storage - mountPath: /var/lib/postgresql - livenessProbe: - exec: - command: - - pg_isready - - -U - - todoapp - - -d - - todoapp - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - exec: - command: - - pg_isready - - -U - - todoapp - - -d - - todoapp - initialDelaySeconds: 5 - periodSeconds: 5 - volumes: - - name: postgres-storage - persistentVolumeClaim: - claimName: postgres-pvc - ---- -# ======================================== -# PostgreSQL Service -# ======================================== -apiVersion: v1 -kind: Service -metadata: - name: todoapp-postgres - namespace: todoapp - labels: - app: todoapp-postgres -spec: - type: ClusterIP - ports: - - port: 5432 - targetPort: 5432 - protocol: TCP - name: postgres - selector: - app: todoapp-postgres - ---- -# ======================================== -# Application Deployment -# ======================================== -apiVersion: apps/v1 -kind: Deployment -metadata: - name: todoapp-deployment - namespace: todoapp - labels: - app: todoapp -spec: - replicas: 3 - selector: - matchLabels: - app: todoapp - template: - metadata: - labels: - app: todoapp - spec: - securityContext: - runAsNonRoot: true - runAsUser: 1001 - fsGroup: 1001 - containers: - - name: todoapp - image: ghcr.io/your-username/docker-nodejs-sample:latest - imagePullPolicy: Always - ports: - - containerPort: 3000 - name: http - protocol: TCP - env: - - name: NODE_ENV - valueFrom: - configMapKeyRef: - name: todoapp-config - key: NODE_ENV - - name: ALLOWED_ORIGINS - valueFrom: - configMapKeyRef: - name: todoapp-config - key: ALLOWED_ORIGINS - - name: POSTGRES_HOST - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_HOST - - name: POSTGRES_PORT - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_PORT - - name: POSTGRES_DB - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_DB - - name: POSTGRES_USER - valueFrom: - configMapKeyRef: - name: todoapp-config - key: POSTGRES_USER - - name: POSTGRES_PASSWORD - valueFrom: - secretKeyRef: - name: todoapp-secrets - key: postgres-password - livenessProbe: - httpGet: - path: /health - port: 3000 - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /health - port: 3000 - initialDelaySeconds: 5 - periodSeconds: 5 - resources: - requests: - memory: '256Mi' - cpu: '250m' - limits: - memory: '512Mi' - cpu: '500m' - securityContext: - allowPrivilegeEscalation: false - readOnlyRootFilesystem: true - capabilities: - drop: - - ALL - ---- -# ======================================== -# Application Service -# ======================================== -apiVersion: v1 -kind: Service -metadata: - name: todoapp-service - namespace: todoapp - labels: - app: todoapp -spec: - type: ClusterIP - ports: - - name: http - port: 80 - targetPort: 3000 - protocol: TCP - selector: - app: todoapp - ---- -# ======================================== -# Ingress for External Access -# ======================================== -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: todoapp-ingress - namespace: todoapp - annotations: - nginx.ingress.kubernetes.io/rewrite-target: / - cert-manager.io/cluster-issuer: 'letsencrypt-prod' -spec: - tls: - - hosts: - - yourdomain.com - secretName: todoapp-tls - rules: - - host: yourdomain.com - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: todoapp-service - port: - number: 80 - ---- -# ======================================== -# HorizontalPodAutoscaler -# ======================================== -apiVersion: autoscaling/v2 -kind: HorizontalPodAutoscaler -metadata: - name: todoapp-hpa - namespace: todoapp -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: todoapp-deployment - minReplicas: 1 - maxReplicas: 5 - metrics: - - type: Resource - resource: - name: cpu - target: - type: Utilization - averageUtilization: 70 - - type: Resource - resource: - name: memory - target: - type: Utilization - averageUtilization: 80 - ---- -# ======================================== -# PodDisruptionBudget -# ======================================== -apiVersion: policy/v1 -kind: PodDisruptionBudget -metadata: - name: todoapp-pdb - namespace: todoapp -spec: - minAvailable: 1 - selector: - matchLabels: - app: todoapp -``` - -## Configure the deployment - -Before deploying, you need to customize the deployment file for your environment: - -1. Image reference: Replace `your-username` with your GitHub username or Docker Hub username: - - ```yaml - image: ghcr.io/your-username/docker-nodejs-sample:latest - ``` - -2. Domain name: Replace `yourdomain.com` with your actual domain in two places: - - ```yaml - # In ConfigMap - ALLOWED_ORIGINS: "https://yourdomain.com" - - # In Ingress - - host: yourdomain.com - ``` - -3. Database password (optional): The default password is already base64 encoded. To change it: - - ```console - $ echo -n "your-new-password" | base64 - ``` - - Then update the Secret: - - ```yaml - data: - postgres-password: <your-base64-encoded-password> - ``` - -4. Storage class: Adjust based on your cluster (current: `standard`) - -## Understanding the deployment - -The deployment file creates a complete application stack with multiple components working together. - -### Architecture - -The deployment includes: - -- Node.js application: Runs 3 replicas of your containerized Todo app -- PostgreSQL database: Single instance with 10Gi of persistent storage -- Services: Kubernetes services handle load balancing across application replicas -- Ingress: External access through an ingress controller with SSL/TLS support - -### Security - -The deployment uses several security features: - -- Containers run as a non-root user (UID 1001) -- Read-only root filesystem prevents unauthorized writes -- Linux capabilities are dropped to minimize attack surface -- Sensitive data like database passwords are stored in Kubernetes secrets - -### High availability - -To keep your application running reliably: - -- Three application replicas ensure service continues if one pod fails -- Pod disruption budget maintains at least one available pod during updates -- Rolling updates allow zero-downtime deployments -- Health checks on the `/health` endpoint ensure only healthy pods receive traffic - -### Auto-scaling - -The Horizontal Pod Autoscaler scales your application based on resource usage: - -- Scales between 1 and 5 replicas automatically -- Triggers scaling when CPU usage exceeds 70% -- Triggers scaling when memory usage exceeds 80% -- Resource limits: 256Mi-512Mi memory, 250m-500m CPU per pod - -### Data persistence - -PostgreSQL data is stored persistently: - -- 10Gi persistent volume stores database files -- Database initializes automatically on first startup -- Data persists across pod restarts and updates - -## Deploy your application - -### Step 1: Deploy to Kubernetes - -Deploy your application to the local Kubernetes cluster: - -```console -$ kubectl apply -f nodejs-sample-kubernetes.yaml -``` - -You should see output confirming all resources were created: - -```shell -namespace/todoapp created -secret/todoapp-secrets created -configmap/todoapp-config created -persistentvolumeclaim/postgres-pvc created -deployment.apps/todoapp-postgres created -service/todoapp-postgres created -deployment.apps/todoapp-deployment created -service/todoapp-service created -ingress.networking.k8s.io/todoapp-ingress created -poddisruptionbudget.policy/todoapp-pdb created -horizontalpodautoscaler.autoscaling/todoapp-hpa created -``` - -### Step 2: Verify the deployment - -Check that your deployments are running: - -```console -$ kubectl get deployments -n todoapp -``` - -Expected output: - -```shell -NAME READY UP-TO-DATE AVAILABLE AGE -todoapp-deployment 3/3 3 3 30s -todoapp-postgres 1/1 1 1 30s -``` - -Verify your services are created: - -```console -$ kubectl get services -n todoapp -``` - -Expected output: - -```shell -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -todoapp-service ClusterIP 10.111.101.229 <none> 80/TCP 45s -todoapp-postgres ClusterIP 10.111.102.130 <none> 5432/TCP 45s -``` - -Check that persistent storage is working: - -```console -$ kubectl get pvc -n todoapp -``` - -Expected output: - -```shell -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -postgres-pvc Bound pvc-12345678-1234-1234-1234-123456789012 10Gi RWO standard 1m -``` - -### Step 3: Access your application - -For local testing, use port forwarding to access your application: - -```console -$ kubectl port-forward -n todoapp service/todoapp-service 8080:80 -``` - -Open your browser and visit [http://localhost:8080](http://localhost:8080) to see your Todo application running in Kubernetes. - -### Step 4: Test the deployment - -Test that your application is working correctly: - -1. Add some todos through the web interface -2. Check application pods: - - ```console - $ kubectl get pods -n todoapp -l app=todoapp - ``` - -3. View application logs: - - ```console - $ kubectl logs -f deployment/todoapp-deployment -n todoapp - ``` - -4. Check database connectivity: - - ```console - $ kubectl get pods -n todoapp -l app=todoapp-postgres - ``` - -5. Monitor auto-scaling: - ```console - $ kubectl describe hpa todoapp-hpa -n todoapp - ``` - -### Step 5: Clean up - -When you're done testing, remove the deployment: - -```console -$ kubectl delete -f nodejs-sample-kubernetes.yaml -``` - -## Summary - -You've deployed your containerized Node.js application to Kubernetes. You learned how to: - -- Create a comprehensive Kubernetes deployment file with security hardening -- Deploy a multi-tier application (Node.js + PostgreSQL) with persistent storage -- Configure auto-scaling, health checks, and high availability features -- Test and monitor your deployment locally using Docker Desktop's Kubernetes - -Your application is now running in a production-like environment with enterprise-grade features including security contexts, resource management, and automatic scaling. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Kubernetes deployment workflow: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more. -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) – Use Docker Desktop's built-in Kubernetes support for local testing and development. -- [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line. -- [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments. -- [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic. diff --git a/content/guides/nodejs/develop.md b/content/guides/nodejs/develop.md deleted file mode 100644 index a3de33aa8506..000000000000 --- a/content/guides/nodejs/develop.md +++ /dev/null @@ -1,526 +0,0 @@ ---- -title: Use containers for Node.js development -linkTitle: Develop your app -weight: 30 -keywords: node, node.js, development -description: Learn how to develop your Node.js application locally using containers. -aliases: - - /get-started/nodejs/develop/ - - /language/nodejs/develop/ - - /guides/language/nodejs/develop/ ---- - -## Prerequisites - -Complete [Containerize a Node.js application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Adding a local database and persisting data -- Configuring your container to run a development environment -- Debugging your containerized application - -## Add a local database and persist data - -The application uses PostgreSQL for data persistence. Add a database service to your Docker Compose configuration. - -### Add database service to Docker Compose - -If you haven't already created a `compose.yml` file in the previous section, or if you need to add the database service, update your `compose.yml` file to include the PostgreSQL database service: - -```yaml -services: - # ... existing app services ... - - # ======================================== - # PostgreSQL Database Service - # ======================================== - db: - image: postgres:18-alpine - container_name: todoapp-db - environment: - POSTGRES_DB: '${POSTGRES_DB:-todoapp}' - POSTGRES_USER: '${POSTGRES_USER:-todoapp}' - POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}' - volumes: - - postgres_data:/var/lib/postgresql - ports: - - '${DB_PORT:-5432}:5432' - restart: unless-stopped - healthcheck: - test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}'] - interval: 10s - timeout: 5s - retries: 5 - start_period: 5s - networks: - - todoapp-network - -# ======================================== -# Volume Configuration -# ======================================== -volumes: - postgres_data: - name: todoapp-postgres-data - driver: local - -# ======================================== -# Network Configuration -# ======================================== -networks: - todoapp-network: - name: todoapp-network - driver: bridge -``` - -### Update your application service - -Make sure your application service in `compose.yml` is configured to connect to the database: - -```yaml {hl_lines="18-20,42-44",collapse=true,title=compose.yml} -services: - app-dev: - build: - context: . - dockerfile: Dockerfile - target: development - container_name: todoapp-dev - ports: - - '${APP_PORT:-3000}:3000' # API server - - '${VITE_PORT:-5173}:5173' # Vite dev server - - '${DEBUG_PORT:-9229}:9229' # Node.js debugger - environment: - NODE_ENV: development - DOCKER_ENV: 'true' - POSTGRES_HOST: db - POSTGRES_PORT: 5432 - POSTGRES_DB: todoapp - POSTGRES_USER: todoapp - POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}' - ALLOWED_ORIGINS: '${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}' - volumes: - - ./src:/app/src:ro - - ./package.json:/app/package.json - - ./vite.config.ts:/app/vite.config.ts:ro - - ./tailwind.config.js:/app/tailwind.config.js:ro - - ./postcss.config.js:/app/postcss.config.js:ro - depends_on: - db: - condition: service_healthy - develop: - watch: - - action: sync - path: ./src - target: /app/src - ignore: - - '**/*.test.*' - - '**/__tests__/**' - - action: rebuild - path: ./package.json - - action: sync - path: ./vite.config.ts - target: /app/vite.config.ts - - action: sync - path: ./tailwind.config.js - target: /app/tailwind.config.js - - action: sync - path: ./postcss.config.js - target: /app/postcss.config.js - restart: unless-stopped - networks: - - todoapp-network - - db: - image: postgres:18-alpine - container_name: todoapp-db - environment: - POSTGRES_DB: '${POSTGRES_DB:-todoapp}' - POSTGRES_USER: '${POSTGRES_USER:-todoapp}' - POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}' - volumes: - - postgres_data:/var/lib/postgresql - ports: - - '${DB_PORT:-5432}:5432' - restart: unless-stopped - healthcheck: - test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}'] - interval: 10s - timeout: 5s - retries: 5 - start_period: 5s - networks: - - todoapp-network - -volumes: - postgres_data: - name: todoapp-postgres-data - driver: local - -networks: - todoapp-network: - name: todoapp-network - driver: bridge -``` - -1. The PostgreSQL database configuration is handled automatically by the application. The database is created and initialized when the application starts, with data persisted using the `postgres_data` volume. - -1. Configure your environment by copying the example file: - - ```console - $ cp .env.example .env - ``` - - Update the `.env` file with your preferred settings: - - ```env - # Application Configuration - NODE_ENV=development - APP_PORT=3000 - VITE_PORT=5173 - DEBUG_PORT=9230 - - # Database Configuration - POSTGRES_HOST=db - POSTGRES_PORT=5432 - POSTGRES_DB=todoapp - POSTGRES_USER=todoapp - POSTGRES_PASSWORD=todoapp_password - - # Security Configuration - ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173 - ``` - -1. Run the following command to start your application in development mode: - - ```console - $ docker compose up app-dev --build - ``` - -1. Open a browser and verify that the application is running at [http://localhost:5173](http://localhost:5173) for the frontend or [http://localhost:3000](http://localhost:3000) for the API. The React frontend is served by Vite dev server on port 5173, with API calls proxied to the Express server on port 3000. - -1. Add some items to the todo list to test data persistence. - -1. After adding some items to the todo list, press `CTRL + C` in the terminal to stop your application. - -1. Run the application again: - ```console - $ docker compose up app-dev - ``` - -1. Refresh [http://localhost:5173](http://localhost:5173) in your browser and verify that the todo items persisted, even after the containers were removed and ran again. - -## Configure and run a development container - -You can use a bind mount to mount your source code into the container. The container can then see the changes you make to the code immediately, as soon as you save a file. This means that you can run processes, like nodemon, in the container that watch for filesystem changes and respond to them. To learn more about bind mounts, see [Storage overview](/manuals/engine/storage/_index.md). - -In addition to adding a bind mount, you can configure your Dockerfile and `compose.yaml` file to install development dependencies and run development tools. - -### Update your Dockerfile for development - -Your Dockerfile should be configured as a multi-stage build with separate stages for development, production, and testing. If you followed the previous section, your Dockerfile already includes a development stage that has all development dependencies and runs the application with hot reload enabled. - -Here's the development stage from your multi-stage Dockerfile: - -```dockerfile {hl_lines="5-26",collapse=true,title=Dockerfile} -# ======================================== -# Development Stage -# ======================================== -FROM build-deps AS development - -# Set environment -ENV NODE_ENV=development \ - NPM_CONFIG_LOGLEVEL=warn - -# Copy source files -COPY . . - -# Ensure all directories have proper permissions -RUN mkdir -p /app/node_modules/.vite && \ - chown -R nodejs:nodejs /app && \ - chmod -R 755 /app - -# Switch to non-root user -USER nodejs - -# Expose ports -EXPOSE 3000 5173 9229 - -# Start development server -CMD ["npm", "run", "dev:docker"] -``` - -The development stage: - -- Installs all dependencies including dev dependencies -- Exposes ports for the API server (3000), Vite dev server (5173), and Node.js debugger (9229) -- Runs `npm run dev` which starts both the Express server and Vite dev server concurrently -- Includes health checks for monitoring container status - -Next, you'll need to update your Compose file to use the new stage. - -### Update your Compose file for development - -Update your `compose.yml` file to run the development stage with bind mounts for hot reloading: - -```yaml {hl_lines=[5,8-10,20-27],collapse=true,title=compose.yml} -services: - app-dev: - build: - context: . - dockerfile: Dockerfile - target: development - container_name: todoapp-dev - ports: - - '${APP_PORT:-3000}:3000' # API server - - '${VITE_PORT:-5173}:5173' # Vite dev server - - '${DEBUG_PORT:-9229}:9229' # Node.js debugger - environment: - NODE_ENV: development - DOCKER_ENV: 'true' - POSTGRES_HOST: db - POSTGRES_PORT: 5432 - POSTGRES_DB: todoapp - POSTGRES_USER: todoapp - POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}' - ALLOWED_ORIGINS: '${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}' - volumes: - - ./src:/app/src:ro - - ./package.json:/app/package.json - - ./vite.config.ts:/app/vite.config.ts:ro - - ./tailwind.config.js:/app/tailwind.config.js:ro - - ./postcss.config.js:/app/postcss.config.js:ro - depends_on: - db: - condition: service_healthy - develop: - watch: - - action: sync - path: ./src - target: /app/src - ignore: - - '**/*.test.*' - - '**/__tests__/**' - - action: rebuild - path: ./package.json - - action: sync - path: ./vite.config.ts - target: /app/vite.config.ts - - action: sync - path: ./tailwind.config.js - target: /app/tailwind.config.js - - action: sync - path: ./postcss.config.js - target: /app/postcss.config.js - restart: unless-stopped - networks: - - todoapp-network -``` - -Key features of the development configuration: - -- Multi-port exposure: API server (3000), Vite dev server (5173), and debugger (9229) -- Comprehensive bind mounts: Source code, configuration files, and package files for hot reloading -- Environment variables: Configurable through `.env` file or defaults -- PostgreSQL database: Production-ready database with persistent storage -- Docker Compose watch: Automatic file synchronization and container rebuilds -- Health checks: Database health monitoring with automatic dependency management - -### Run your development container and debug your application - -Run the following command to run your application with the development configuration: - -```console -$ docker compose up app-dev --build -``` - -Or with file watching for automatic updates: - -```console -$ docker compose up app-dev --watch -``` - -For local development without Docker: - -```console -$ npm run dev:with-db -``` - -Or start services separately: - -```console -$ npm run db:start # Start PostgreSQL container -$ npm run dev # Start both server and client -``` - -### Using Task runner (alternative) - -The project includes a Taskfile.yml for advanced workflows: - -```console -# Development -$ task dev # Start development environment -$ task dev:build # Build development image -$ task dev:run # Run development container - -# Production -$ task build # Build production image -$ task run # Run production container -$ task build-run # Build and run in one step - -# Testing -$ task test # Run all tests -$ task test:unit # Run unit tests with coverage -$ task test:lint # Run linting - -# Kubernetes -$ task k8s:deploy # Deploy to Kubernetes -$ task k8s:status # Check deployment status -$ task k8s:logs # View pod logs - -# Utilities -$ task clean # Clean up containers and images -$ task health # Check application health -$ task logs # View container logs -``` - -The application will start with both the Express API server and Vite development server: - -- API Server: [http://localhost:3000](http://localhost:3000) - Express.js backend with REST API -- Frontend: [http://localhost:5173](http://localhost:5173) - Vite dev server with hot module replacement -- Health Check: [http://localhost:3000/health](http://localhost:3000/health) - Application health status - -Any changes to the application's source files on your local machine will now be immediately reflected in the running container thanks to the bind mounts. - -Try making a change to test hot reloading: - -1. Open `src/client/components/TodoApp.tsx` in an IDE or text editor. -1. Update the main heading text: - - ```diff - - <h1 className="text-3xl font-bold text-gray-900 mb-8"> - - Modern Todo App - - </h1> - + <h1 className="text-3xl font-bold text-gray-900 mb-8"> - + My Todo App - + </h1> - ``` - -1. Save the file and the Vite dev server will automatically reload the page with your changes. - -Debugging support: - -You can connect a debugger to your application on port 9229. The Node.js inspector is enabled with `--inspect=0.0.0.0:9230` in the development script (`dev:server`). - -### VS Code debugger setup - -1. Create a launch configuration in `.vscode/launch.json`: - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "name": "Attach to Docker Container", - "type": "node", - "request": "attach", - "port": 9229, - "address": "localhost", - "localRoot": "${workspaceFolder}", - "remoteRoot": "/app", - "protocol": "inspector", - "restart": true, - "sourceMaps": true, - "skipFiles": ["<node_internals>/**"] - } - ] - } - ``` - -1. Start your development container: - - ```console - docker compose up app-dev --build - ``` - -1. Attach the debugger: - - Open VS Code - - From the Debug panel (Ctrl/Cmd + Shift + D), select **Attach to Docker Container** from the drop-down - - Select the green play button or press F5 - -### Chrome DevTools (alternative) - -You can also use Chrome DevTools for debugging: - -1. Start your container (if not already running): - - ```console - docker compose up app-dev --build - ``` - -1. Open Chrome and go to `chrome://inspect`. - -1. From the **Configure** option, add: - - ```text - localhost:9229 - ``` - -1. When your Node.js target appears, select **inspect**. - -### Debugging configuration details - -The debugger configuration: - -- Container port: 9230 (internal debugger port) -- Host port: 9229 (mapped external port) -- Script: `tsx watch --inspect=0.0.0.0:9230 src/server/index.ts` - -The debugger listens on all interfaces (`0.0.0.0`) inside the container on port 9230 and is accessible on port 9229 from your host machine. - -### Troubleshooting debugger connection - -If the debugger doesn't connect: - -1. Check if the container is running: - - ```console - docker ps - ``` - -1. Check if the port is exposed: - - ```console - docker port todoapp-dev - ``` - -1. Check container logs: - - ```console - docker compose logs app-dev - ``` - - You should see a message like: - - ```text - Debugger listening on ws://0.0.0.0:9230/... - ``` - -Now you can set breakpoints in your TypeScript source files and debug your containerized Node.js application. - -For more details about Node.js debugging, see the [Node.js documentation](https://nodejs.org/en/docs/guides/debugging-getting-started). - -## Summary - -You've set up your Compose file with a PostgreSQL database and data persistence. You also created a multi-stage Dockerfile and configured bind mounts for development. - -Related information: - -- [Volumes top-level element](/reference/compose-file/volumes/) -- [Services top-level element](/reference/compose-file/services/) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll learn how to run unit tests using Docker. diff --git a/content/guides/nodejs/run-tests.md b/content/guides/nodejs/run-tests.md deleted file mode 100644 index c2a270dc764f..000000000000 --- a/content/guides/nodejs/run-tests.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: Run Node.js tests in a container -linkTitle: Run your tests -weight: 30 -keywords: node.js, node, test -description: Learn how to run your Node.js tests in a container. -aliases: - - /language/nodejs/run-tests/ - - /guides/language/nodejs/run-tests/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Node.js application](containerize.md). - -## Overview - -Testing is a core part of building reliable software. Whether you're writing unit tests, integration tests, or end-to-end tests, running them consistently across environments matters. Docker makes this easy by giving you the same setup locally, in CI/CD, and during image builds. - -## Run tests when developing locally - -The sample application uses Vitest for testing, and it already includes tests for React components, custom hooks, API routes, database operations, and utility functions. - -### Run tests locally (without Docker) - -```console -$ npm run test -``` - -### Add test service to Docker Compose - -To run tests in a containerized environment, you need to add a dedicated test service to your `compose.yml` file. Add the following service configuration: - -```yaml -services: - # ... existing services ... - - # ======================================== - # Test Service - # ======================================== - app-test: - build: - context: . - dockerfile: Dockerfile - target: test - container_name: todoapp-test - environment: - NODE_ENV: test - POSTGRES_HOST: db - POSTGRES_PORT: 5432 - POSTGRES_DB: todoapp_test - POSTGRES_USER: todoapp - POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}' - depends_on: - db: - condition: service_healthy - command: ['npm', 'run', 'test:coverage'] - networks: - - todoapp-network - profiles: - - test -``` - -This test service configuration: - -- Builds from test stage: Uses the `test` target from your multi-stage Dockerfile -- Isolated test database: Uses a separate `todoapp_test` database for testing -- Profile-based: Uses the `test` profile so it only runs when explicitly requested -- Health dependency: Waits for the database to be healthy before starting tests - -### Run tests in a container - -You can run tests using the dedicated test service: - -```console -$ docker compose up app-test --build -``` - -Or run tests against the development service: - -```console -$ docker compose run --rm app-dev npm run test -``` - -For a one-off test run with coverage: - -```console -$ docker compose run --rm app-dev npm run test:coverage -``` - -### Run tests with coverage - -To generate a coverage report: - -```console -$ npm run test:coverage -``` - -You should see output like the following: - -```console -> docker-nodejs-sample@1.0.0 test -> vitest --run - - ✓ src/server/__tests__/routes/todos.test.ts (5 tests) 16ms - ✓ src/shared/utils/__tests__/validation.test.ts (15 tests) 6ms - ✓ src/client/components/__tests__/LoadingSpinner.test.tsx (8 tests) 67ms - ✓ src/server/database/__tests__/postgres.test.ts (13 tests) 136ms - ✓ src/client/components/__tests__/ErrorMessage.test.tsx (8 tests) 127ms - ✓ src/client/components/__tests__/TodoList.test.tsx (8 tests) 147ms - ✓ src/client/components/__tests__/TodoItem.test.tsx (8 tests) 218ms - ✓ src/client/__tests__/App.test.tsx (13 tests) 259ms - ✓ src/client/components/__tests__/AddTodoForm.test.tsx (12 tests) 323ms - ✓ src/client/hooks/__tests__/useTodos.test.ts (11 tests) 569ms - - Test Files 9 passed (9) - Tests 88 passed (88) - Start at 20:57:19 - Duration 4.41s (transform 1.79s, setup 2.66s, collect 5.38s, tests 4.61s, environment 14.07s, prepare 4.34s) -``` - -### Test structure - -The test suite covers: - -- Client Components (`src/client/components/__tests__/`): React component testing with React Testing Library -- Custom Hooks (`src/client/hooks/__tests__/`): React hooks testing with proper mocking -- Server Routes (`src/server/__tests__/routes/`): API endpoint testing -- Database Layer (`src/server/database/__tests__/`): PostgreSQL database operations testing -- Utility Functions (`src/shared/utils/__tests__/`): Validation and helper function testing -- Integration Tests (`src/client/__tests__/`): Full application integration testing - -## Run tests when building - -To run tests during the Docker build process, you need to add a dedicated test stage to your Dockerfile. If you haven't already added this stage, add the following to your multi-stage Dockerfile: - -```dockerfile -# ======================================== -# Test Stage -# ======================================== -FROM build-deps AS test - -# Set environment -ENV NODE_ENV=test \ - CI=true - -# Copy source files -COPY --chown=nodejs:nodejs . . - -# Switch to non-root user -USER nodejs - -# Run tests with coverage -CMD ["npm", "run", "test:coverage"] -``` - -This test stage: - -- Test environment: Sets `NODE_ENV=test` and `CI=true` for proper test execution -- Non-root user: Runs tests as the `nodejs` user for security -- Flexible execution: Uses `CMD` instead of `RUN` to allow running tests during build or as a separate container -- Coverage support: Configured to run tests with coverage reporting - -### Build and run tests during image build - -To build an image that runs tests during the build process, you can create a custom Dockerfile or modify the existing one temporarily: - -```console -$ docker build --target test -t node-docker-image-test . -``` - -### Run tests in a dedicated test container - -The recommended approach is to use the test service defined in `compose.yml`: - -```console -$ docker compose --profile test up app-test --build -``` - -Or run it as a one-off container: - -```console -$ docker compose run --rm app-test -``` - -### Run tests with coverage in CI/CD - -For continuous integration, you can run tests with coverage: - -```console -$ docker build --target test --progress=plain --no-cache -t test-image . -$ docker run --rm test-image npm run test:coverage -``` - -You should see output containing the following: - -```console - ✓ src/server/__tests__/routes/todos.test.ts (5 tests) 16ms - ✓ src/shared/utils/__tests__/validation.test.ts (15 tests) 6ms - ✓ src/client/components/__tests__/LoadingSpinner.test.tsx (8 tests) 67ms - ✓ src/server/database/__tests__/postgres.test.ts (13 tests) 136ms - ✓ src/client/components/__tests__/ErrorMessage.test.tsx (8 tests) 127ms - ✓ src/client/components/__tests__/TodoList.test.tsx (8 tests) 147ms - ✓ src/client/components/__tests__/TodoItem.test.tsx (8 tests) 218ms - ✓ src/client/__tests__/App.test.tsx (13 tests) 259ms - ✓ src/client/components/__tests__/AddTodoForm.test.tsx (12 tests) 323ms - ✓ src/client/hooks/__tests__/useTodos.test.ts (11 tests) 569ms - - Test Files 9 passed (9) - Tests 88 passed (88) - Start at 20:57:19 - Duration 4.41s (transform 1.79s, setup 2.66s, collect 5.38s, tests 4.61s, environment 14.07s, prepare 4.34s) -``` - -## Summary - -In this section, you learned how to run tests when developing locally using Docker Compose and how to run tests when building your image. - -Related information: - -- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/opencode-model-runner.md b/content/guides/opencode-model-runner.md index e02d5d523b1e..ca667f17ea54 100644 --- a/content/guides/opencode-model-runner.md +++ b/content/guides/opencode-model-runner.md @@ -5,8 +5,10 @@ summary: | Connect OpenCode to Docker Model Runner with an OpenAI-compatible endpoint, choose coding models, and package `gpt-oss` with a larger context window. keywords: ai, opencode, docker model runner, local models, coding assistant -tags: [ai] +weight: 3 params: + tags: [ai] + featured: true time: 10 minutes --- diff --git a/content/guides/opentelemetry.md b/content/guides/opentelemetry.md index 6c063391c363..5bddee92ad26 100644 --- a/content/guides/opentelemetry.md +++ b/content/guides/opentelemetry.md @@ -4,9 +4,8 @@ description: &desc Learn how to instrument a JavaScript application using OpenTe keywords: OpenTelemetry, observability, tracing linktitle: Instrumenting JS Apps with OpenTelemetry summary: *desc -tags: [app-dev, observability] -languages: [js] params: + tags: [observability] time: 10 minutes --- diff --git a/content/guides/orchestration.md b/content/guides/orchestration.md deleted file mode 100644 index 8127e98e611a..000000000000 --- a/content/guides/orchestration.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: Deployment and orchestration -keywords: orchestration, deploy, kubernetes, swarm, -description: Get oriented on some basics of Docker and install Docker Desktop. -aliases: - - /get-started/orchestration/ - - /guides/deployment-orchestration/orchestration/ -summary: | - Explore the essentials of container orchestration with Docker. -tags: [deploy] -params: - time: 10 minutes ---- - -Containerization provides an opportunity to move and scale applications to -clouds and data centers. Containers effectively guarantee that those applications run the -same way anywhere, allowing you to quickly and easily take advantage of all -these environments. Additionally, as you scale your applications up, you need some -tooling to help automate the maintenance of those applications, enable the -replacement of failed containers automatically, and manage the roll-out of -updates and reconfigurations of those containers during their lifecycle. - -Tools to manage, scale, and maintain containerized applications are called -orchestrators. Two of the most popular orchestration tools are Kubernetes and -Docker Swarm. Docker Desktop provides development environments for both of these -orchestrators. - -The advanced modules teach you how to: - -1. [Set up and use a Kubernetes environment on your development machine](kube-deploy.md) -2. [Set up and use a Swarm environment on your development machine](swarm-deploy.md) - -## Turn on Kubernetes - -Docker Desktop sets up Kubernetes for you quickly and easily. Follow the setup and validation instructions appropriate for your operating system: - -{{< tabs group="os" >}} -{{< tab name="Mac and Linux" >}} - -### Mac - -1. From the Docker Dashboard, navigate to **Settings**, and select the **Kubernetes** tab. - -2. Select the checkbox labeled **Enable Kubernetes**, and select **Apply**. Docker Desktop automatically sets up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes _running_' in **Settings**. - -3. To confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content: - - ```yaml - apiVersion: v1 - kind: Pod - metadata: - name: demo - spec: - containers: - - name: testpod - image: alpine:latest - command: ["ping", "8.8.8.8"] - ``` - - This describes a pod with a single container, isolating a simple ping to 8.8.8.8. - -4. In a terminal, navigate to where you created `pod.yaml` and create your pod: - - ```console - $ kubectl apply -f pod.yaml - ``` - -5. Check that your pod is up and running: - - ```console - $ kubectl get pods - ``` - - You should see something like: - - ```shell - NAME READY STATUS RESTARTS AGE - demo 1/1 Running 0 4s - ``` - -6. Check that you get the logs you'd expect for a ping process: - - ```console - $ kubectl logs demo - ``` - - You should see the output of a healthy ping process: - - ```shell - PING 8.8.8.8 (8.8.8.8): 56 data bytes - 64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms - 64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms - 64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms - ... - ``` - -7. Finally, tear down your test pod: - - ```console - $ kubectl delete -f pod.yaml - ``` - -{{< /tab >}} -{{< tab name="Windows" >}} - -### Windows - -1. From the Docker Dashboard, navigate to **Settings**, and select the **Kubernetes** tab. - -2. Select the checkbox labeled **Enable Kubernetes**, and select **Apply**. Docker Desktop automatically sets up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes _running_' in the **Settings** menu. - -3. To confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content: - - ```yaml - apiVersion: v1 - kind: Pod - metadata: - name: demo - spec: - containers: - - name: testpod - image: alpine:latest - command: ["ping", "8.8.8.8"] - ``` - - This describes a pod with a single container, isolating a simple ping to 8.8.8.8. - -4. In PowerShell, navigate to where you created `pod.yaml` and create your pod: - - ```console - $ kubectl apply -f pod.yaml - ``` - -5. Check that your pod is up and running: - - ```console - $ kubectl get pods - ``` - - You should see something like: - - ```shell - NAME READY STATUS RESTARTS AGE - demo 1/1 Running 0 4s - ``` - -6. Check that you get the logs you'd expect for a ping process: - - ```console - $ kubectl logs demo - ``` - - You should see the output of a healthy ping process: - - ```shell - PING 8.8.8.8 (8.8.8.8): 56 data bytes - 64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms - 64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms - 64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms - ... - ``` - -7. Finally, tear down your test pod: - - ```console - $ kubectl delete -f pod.yaml - ``` - -{{< /tab >}} -{{< /tabs >}} - -## Enable Docker Swarm - -Docker Desktop runs primarily on Docker Engine, which has everything you need to run a Swarm built in. Follow the setup and validation instructions appropriate for your operating system: - -{{< tabs group="os" >}} -{{< tab name="Mac" >}} - -### Mac - -1. Open a terminal, and initialize Docker Swarm mode: - - ```console - $ docker swarm init - ``` - - If all goes well, you should see a message similar to the following: - - ```shell - Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager. - - To add a worker to this swarm, run the following command: - - docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377 - - To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. - ``` - -2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8: - - ```console - $ docker service create --name demo alpine:latest ping 8.8.8.8 - ``` - -3. Check that your service created one running container: - - ```console - $ docker service ps demo - ``` - - You should see something like: - - ```shell - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 463j2s3y4b5o demo.1 alpine:latest docker-desktop Running Running 8 seconds ago - ``` - -4. Check that you get the logs you'd expect for a ping process: - - ```console - $ docker service logs demo - ``` - - You should see the output of a healthy ping process: - - ```shell - demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms - ... - ``` - -5. Finally, tear down your test service: - - ```console - $ docker service rm demo - ``` - -{{< /tab >}} -{{< tab name="Windows" >}} - -### Windows - -1. Open a PowerShell, and initialize Docker Swarm mode: - - ```console - $ docker swarm init - ``` - - If all goes well, you should see a message similar to the following: - - ```shell - Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager. - - To add a worker to this swarm, run the following command: - - docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377 - - To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. - ``` - -2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8: - - ```console - $ docker service create --name demo alpine:latest ping 8.8.8.8 - ``` - -3. Check that your service created one running container: - - ```console - $ docker service ps demo - ``` - - You should see something like: - - ```shell - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 463j2s3y4b5o demo.1 alpine:latest docker-desktop Running Running 8 seconds ago - ``` - -4. Check that you get the logs you'd expect for a ping process: - - ```console - $ docker service logs demo - ``` - - You should see the output of a healthy ping process: - - ```shell - demo.1.463j2s3y4b5o@docker-desktop | PING 8.8.8.8 (8.8.8.8): 56 data bytes - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms - demo.1.463j2s3y4b5o@docker-desktop | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms - ... - ``` - -5. Finally, tear down your test service: - - ```console - $ docker service rm demo - ``` - -{{< /tab >}} -{{< /tabs >}} - -## Conclusion - -At this point, you've confirmed that you can run simple containerized workloads in Kubernetes and Swarm. The next step is to write a YAML file that describes how to run and manage these containers. - -- [Deploy to Kubernetes](kube-deploy.md) -- [Deploy to Swarm](swarm-deploy.md) - -## CLI references - -Further documentation for all CLI commands used in this article are available here: - -- [`kubectl apply`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply) -- [`kubectl get`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get) -- [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs) -- [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete) -- [`docker swarm init`](/reference/cli/docker/swarm/init/) -- [`docker service *`](/reference/cli/docker/service/) diff --git a/content/guides/pgadmin.md b/content/guides/pgadmin.md index 24736175437a..2a688bbb181e 100644 --- a/content/guides/pgadmin.md +++ b/content/guides/pgadmin.md @@ -5,8 +5,8 @@ title: Visualizing your PostgreSQL databases with pgAdmin linktitle: Visualizing your PostgreSQL databases with pgAdmin summary: | Explore how to add pgAdmin to your development stack and make it as easy as possible for your teammates to navigate through your PostgreSQL databases. -tags: [databases] params: + tags: [databases] time: 10 minutes --- @@ -129,7 +129,7 @@ Fortunately, there is an ability to auto-connect to the database. Add the following config to your `compose.yaml` file to define a pgpass file: ```yaml - config: + configs: pgadmin-pgpass: content: | postgres:5432:*:postgres:secret diff --git a/content/guides/php.md b/content/guides/php.md new file mode 100644 index 000000000000..7165b516001a --- /dev/null +++ b/content/guides/php.md @@ -0,0 +1,839 @@ +--- +title: PHP language-specific guide +linkTitle: PHP +description: Containerize and develop PHP apps using Docker +keywords: getting started, php, composer +summary: | + This guide explains how to containerize PHP applications using Docker. +aliases: + - /language/php/ + - /guides/language/php/ + - /language/php/containerize/ + - /language/php/develop/ + - /language/php/run-tests/ + - /language/php/configure-ci-cd/ + - /language/php/deploy/ + - /guides/php/configure-ci-cd/ + - /guides/php/containerize/ + - /guides/php/deploy/ + - /guides/php/develop/ + - /guides/php/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +The PHP language-specific guide teaches you how to create a containerized PHP application using Docker. In this guide, you'll learn how to: + +- Containerize and run a PHP application +- Set up a local environment to develop a PHP application using containers +- Run tests for a PHP application within containers + +After completing the PHP language-specific guide, you should be able to containerize your own PHP application based on the examples and instructions provided in this guide. + +Start by containerizing an existing PHP application. + +## Containerize a PHP application + +### Prerequisites + +- You have installed the latest version of [Docker + Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this + section use a command-line based git client, but you can use any client. + +### Overview + +This section walks you through containerizing and running a PHP +application. + +### Get the sample applications + +In this guide, you will use a pre-built PHP application. The application uses Composer for library dependency management. You'll serve the application via an Apache web server. + +Open a terminal, change directory to a directory that you want to work in, and +run the following command to clone the repository. + +```console +$ git clone https://github.com/docker/docker-php-sample +``` + +The sample application is a basic hello world application and an application that increments a counter in a database. In addition, the application uses PHPUnit for testing. + +### Create Docker assets + +Now that you have an application, you can create the necessary Docker assets to +containerize it. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +Create the following files in your `docker-php-sample` directory. + +```dockerfile {collapse=true,title=Dockerfile} +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +################################################################################ + +# Create a stage for installing app dependencies defined in Composer. +FROM composer:lts as deps + +WORKDIR /app + +# If your composer.json file defines scripts that run during dependency installation and +# reference your application source files, uncomment the line below to copy all the files +# into this layer. +# COPY . . + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a bind mounts to composer.json and composer.lock to avoid having to copy them +# into this layer. +# Leverage a cache mount to /tmp/cache so that subsequent builds don't have to re-download packages. +RUN --mount=type=bind,source=composer.json,target=composer.json \ + --mount=type=bind,source=composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-dev --no-interaction + +################################################################################ + +# Create a new stage for running the application that contains the minimal +# runtime dependencies for the application. This often uses a different base +# image from the install or build stage where the necessary files are copied +# from the install stage. +# +# The example below uses the PHP Apache image as the foundation for running the app. +# By specifying the "8.2-apache" tag, it will also use whatever happens to be the +# most recent version of that tag when you build your Dockerfile. +# If reproducibility is important, consider using a specific digest SHA, like +# php@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4. +FROM php:8.2-apache as final + +# Your PHP application may require additional PHP extensions to be installed +# manually. For detailed instructions for installing extensions can be found, see +# https://github.com/docker-library/docs/tree/master/php#how-to-install-more-php-extensions +# The following code blocks provide examples that you can edit and use. +# +# Add core PHP extensions, see +# https://github.com/docker-library/docs/tree/master/php#php-core-extensions +# This example adds the apt packages for the 'gd' extension's dependencies and then +# installs the 'gd' extension. For additional tips on running apt-get, see +# https://docs.docker.com/go/dockerfile-aptget-best-practices/ +# RUN apt-get update && apt-get install -y \ +# libfreetype-dev \ +# libjpeg62-turbo-dev \ +# libpng-dev \ +# && rm -rf /var/lib/apt/lists/* \ +# && docker-php-ext-configure gd --with-freetype --with-jpeg \ +# && docker-php-ext-install -j$(nproc) gd +# +# Add PECL extensions, see +# https://github.com/docker-library/docs/tree/master/php#pecl-extensions +# This example adds the 'redis' and 'xdebug' extensions. +# RUN pecl install redis-5.3.7 \ +# && pecl install xdebug-3.2.1 \ +# && docker-php-ext-enable redis xdebug + +# Use the default production configuration for PHP runtime arguments, see +# https://github.com/docker-library/docs/tree/master/php#configuration +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" + +# Copy the app dependencies from the previous install stage. +COPY --from=deps app/vendor/ /var/www/html/vendor +# Copy the app files from the app directory. +COPY ./src /var/www/html + +# Switch to a non-privileged user (defined in the base image) that the app will run under. +# See https://docs.docker.com/go/dockerfile-user-best-practices/ +USER www-data +``` + +```yaml {collapse=true,title=compose.yaml} +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + ports: + - 9000:80 + +# The commented out section below is an example of how to define a PostgreSQL +# database that your application can use. `depends_on` tells Docker Compose to +# start the database before your application. The `db-data` volume persists the +# database data between container restarts. The `db-password` secret is used +# to set the database password. You must create `db/password.txt` and add +# a password of your choosing to it before running `docker compose up`. +# depends_on: +# db: +# condition: service_healthy +# db: +# image: postgres +# restart: always +# user: postgres +# secrets: +# - db-password +# volumes: +# - db-data:/var/lib/postgresql/data +# environment: +# - POSTGRES_DB=example +# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password +# expose: +# - 5432 +# healthcheck: +# test: [ "CMD", "pg_isready" ] +# interval: 10s +# timeout: 5s +# retries: 5 +# volumes: +# db-data: +# secrets: +# db-password: +# file: db/password.txt +``` + +```text {collapse=true,title=".dockerignore"} +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/.next +**/.cache +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/charts +**/docker-compose* +**/compose.y*ml +!**/composer.json +!**/composer.lock +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +**/vendor +LICENSE +README.md +``` + +You should now have the following contents in your `docker-php-sample` +directory. + +```text +├── docker-php-sample/ +│ ├── .git/ +│ ├── src/ +│ ├── tests/ +│ ├── .dockerignore +│ ├── .gitignore +│ ├── compose.yaml +│ ├── composer.json +│ ├── composer.lock +│ ├── Dockerfile +│ └── README.md +``` + +To learn more about these files, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `docker-php-sample` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-php-sample` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for PHP development + +### Prerequisites + +Complete [Containerize a PHP application](#containerize-a-php-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Adding a local database and persisting data +- Adding phpMyAdmin to interact with the database +- Configuring Compose to automatically update your running Compose services as + you edit and save your code +- Creating a development container that contains the dev dependencies + +### Add a local database and persist data + +You can use containers to set up local services, like a database. +To do this for the sample application, you'll need to do the following: + +- Update the `Dockerfile` to install extensions to connect to the database +- Update the `compose.yaml` file to add a database service and volume to persist data + +#### Update the Dockerfile to install extensions + +To install PHP extensions, you need to update the `Dockerfile`. Open your +Dockerfile in an IDE or text editor and then update the contents. The following +`Dockerfile` includes one new line that installs the `pdo` and `pdo_mysql` +extensions. All comments have been removed. + +```dockerfile {hl_lines=11} +# syntax=docker/dockerfile:1 + +FROM composer:lts as deps +WORKDIR /app +RUN --mount=type=bind,source=composer.json,target=composer.json \ + --mount=type=bind,source=composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-dev --no-interaction + +FROM php:8.2-apache as final +RUN docker-php-ext-install pdo pdo_mysql +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" +COPY --from=deps app/vendor/ /var/www/html/vendor +COPY ./src /var/www/html +USER www-data +``` + +For more details about installing PHP extensions, see the [Official Docker Image for PHP](https://hub.docker.com/_/php). + +#### Update the compose.yaml file to add a db and persist data + +Open the `compose.yaml` file in an IDE or text editor. You'll notice it +already contains commented-out instructions for a PostgreSQL database and volume. For this application, you'll use MariaDB. For more details about MariaDB, see the [MariaDB Official Docker image](https://hub.docker.com/_/mariadb). + +Open the `src/database.php` file in an IDE or text editor. You'll notice that it reads environment variables in order to connect to the database. + +In the `compose.yaml` file, you'll need to update the following: + +1. Uncomment and update the database instructions for MariaDB. +2. Add a secret to the server service to pass in the database password. +3. Add the database connection environment variables to the server service. +4. Uncomment the volume instructions to persist data. + +The following is the updated `compose.yaml` file. All comments have been removed. + +```yaml +services: + server: + build: + context: . + ports: + - 9000:80 + depends_on: + db: + condition: service_healthy + secrets: + - db-password + environment: + - PASSWORD_FILE_PATH=/run/secrets/db-password + - DB_HOST=db + - DB_NAME=example + - DB_USER=root + db: + image: mariadb + restart: always + user: root + secrets: + - db-password + volumes: + - db-data:/var/lib/mysql + environment: + - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password + - MARIADB_DATABASE=example + expose: + - 3306 + healthcheck: + test: + [ + "CMD", + "/usr/local/bin/healthcheck.sh", + "--su-mysql", + "--connect", + "--innodb_initialized", + ] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Before you run the application using Compose, notice that this Compose file uses +`secrets` and specifies a `password.txt` file to hold the database's password. +You must create this file as it's not included in the source repository. + +In the `docker-php-sample` directory, create a new directory named `db` and +inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file. + +```text +example +``` + +Save and close the `password.txt` file. + +You should now have the following in your `docker-php-sample` directory. + +```text +├── docker-php-sample/ +│ ├── .git/ +│ ├── db/ +│ │ └── password.txt +│ ├── src/ +│ ├── tests/ +│ ├── .dockerignore +│ ├── .gitignore +│ ├── compose.yaml +│ ├── composer.json +│ ├── composer.lock +│ ├── Dockerfile +│ └── README.md +``` + +Run the following command to start your application. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:9000/database.php](http://localhost:9000/database.php). You should see a simple web application with text and a counter that increments every time you refresh. + +Press `ctrl+c` in the terminal to stop your application. + +### Verify that data persists in the database + +In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again. + +```console +$ docker compose rm +$ docker compose up --build +``` + +Refresh [http://localhost:9000/database.php](http://localhost:9000/database.php) in your browser and verify that the previous count still exists. Without a volume, the database data wouldn't persist after you remove the container. + +Press `ctrl+c` in the terminal to stop your application. + +### Add phpMyAdmin to interact with the database + +You can easily add services to your application stack by updating the `compose.yaml` file. + +Update your `compose.yaml` to add a new service for phpMyAdmin. For more details, see the [phpMyAdmin Official Docker Image](https://hub.docker.com/_/phpmyadmin). The following is the updated `compose.yaml` file. + +```yaml {hl_lines="42-49"} +services: + server: + build: + context: . + ports: + - 9000:80 + depends_on: + db: + condition: service_healthy + secrets: + - db-password + environment: + - PASSWORD_FILE_PATH=/run/secrets/db-password + - DB_HOST=db + - DB_NAME=example + - DB_USER=root + db: + image: mariadb + restart: always + user: root + secrets: + - db-password + volumes: + - db-data:/var/lib/mysql + environment: + - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password + - MARIADB_DATABASE=example + expose: + - 3306 + healthcheck: + test: + [ + "CMD", + "/usr/local/bin/healthcheck.sh", + "--su-mysql", + "--connect", + "--innodb_initialized", + ] + interval: 10s + timeout: 5s + retries: 5 + phpmyadmin: + image: phpmyadmin + ports: + - 8080:80 + depends_on: + - db + environment: + - PMA_HOST=db +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +In the terminal, run `docker compose up` to run your application again. + +```console +$ docker compose up --build +``` + +Open [http://localhost:8080](http://localhost:8080) in your browser to access phpMyAdmin. Log in using `root` as the username and `example` as the password. You can now interact with the database through phpMyAdmin. + +Press `ctrl+c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file. + +```yaml {hl_lines="17-21"} +services: + server: + build: + context: . + ports: + - 9000:80 + depends_on: + db: + condition: service_healthy + secrets: + - db-password + environment: + - PASSWORD_FILE_PATH=/run/secrets/db-password + - DB_HOST=db + - DB_NAME=example + - DB_USER=root + develop: + watch: + - action: sync + path: ./src + target: /var/www/html + db: + image: mariadb + restart: always + user: root + secrets: + - db-password + volumes: + - db-data:/var/lib/mysql + environment: + - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password + - MARIADB_DATABASE=example + expose: + - 3306 + healthcheck: + test: + [ + "CMD", + "/usr/local/bin/healthcheck.sh", + "--su-mysql", + "--connect", + "--innodb_initialized", + ] + interval: 10s + timeout: 5s + retries: 5 + phpmyadmin: + image: phpmyadmin + ports: + - 8080:80 + depends_on: + - db + environment: + - PMA_HOST=db +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Open a browser and verify that the application is running at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). + +Any changes to the application's source files on your local machine will now be +immediately reflected in the running container. + +Open `hello.php` in an IDE or text editor and update the string `Hello, world!` to `Hello, Docker!`. + +Save the changes to `hello.php` and then wait a few seconds for the application to sync. Refresh [http://localhost:9000/hello.php](http://localhost:9000/hello.php) in your browser and verify that the updated text appears. + +Press `ctrl+c` in the terminal to stop Compose Watch. Run `docker compose down` in the terminal to stop the application. + +### Create a development container + +At this point, when you run your containerized application, Composer isn't installing the dev dependencies. While this small image is good for production, it lacks the tools and dependencies you may need when developing and it doesn't include the `tests` directory. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](/manuals/build/building/multi-stage.md). + +In the `Dockerfile`, you'll need to update the following: + +1. Split the `deps` staged into two stages. One stage for production + (`prod-deps`) and one stage (`dev-deps`) to install development dependencies. +2. Create a common `base` stage. +3. Create a new `development` stage for development. +4. Update the `final` stage to copy dependencies from the new `prod-deps` stage. + +The following is the `Dockerfile` before and after the changes. + +{{< tabs >}} +{{< tab name="Before" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM composer:lts as deps +WORKDIR /app +RUN --mount=type=bind,source=composer.json,target=composer.json \ + --mount=type=bind,source=composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-dev --no-interaction + +FROM php:8.2-apache as final +RUN docker-php-ext-install pdo pdo_mysql +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" +COPY --from=deps app/vendor/ /var/www/html/vendor +COPY ./src /var/www/html +USER www-data +``` + +{{< /tab >}} +{{< tab name="After" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM composer:lts as prod-deps +WORKDIR /app +RUN --mount=type=bind,source=./composer.json,target=composer.json \ + --mount=type=bind,source=./composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-dev --no-interaction + +FROM composer:lts as dev-deps +WORKDIR /app +RUN --mount=type=bind,source=./composer.json,target=composer.json \ + --mount=type=bind,source=./composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-interaction + +FROM php:8.2-apache as base +RUN docker-php-ext-install pdo pdo_mysql +COPY ./src /var/www/html + +FROM base as development +COPY ./tests /var/www/html/tests +RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" +COPY --from=dev-deps app/vendor/ /var/www/html/vendor + +FROM base as final +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" +COPY --from=prod-deps app/vendor/ /var/www/html/vendor +USER www-data +``` + +{{< /tab >}} +{{< /tabs >}} + +Update your `compose.yaml` file by adding an instruction to target the +development stage. + +The following is the updated section of the `compose.yaml` file. + +```yaml {hl_lines=5} +services: + server: + build: + context: . + target: development + # ... +``` + +Your containerized application will now install the dev dependencies. + +Run the following command to start your application. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should still see the simple "Hello, Docker!" application. + +Press `ctrl+c` in the terminal to stop your application. + +While the application appears the same, you can now make use of the dev dependencies. Continue to the next section to learn how you can run tests using Docker. + +## Run PHP tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize a PHP application](#containerize-a-php-application). + +### Overview + +Testing is an essential part of modern software development. Testing can mean a +lot of things to different development teams. There are unit tests, integration +tests and end-to-end testing. In this guide you take a look at running your unit +tests in Docker when developing and when building. + +### Run tests when developing locally + +The sample application already has a PHPUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests. + +Run the following command in the `docker-php-sample` directory to run the tests inside a container. + +```console +$ docker compose run --build --rm server ./vendor/bin/phpunit tests/HelloWorldTest.php +``` + +You should see output that contains the following. + +```console +Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. + +. 1 / 1 (100%) + +Time: 00:00.003, Memory: 4.00 MB + +OK (1 test, 1 assertion) +``` + +To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). + +### Run tests when building + +To run your tests when building, you need to update your Dockerfile. Create a new test stage that runs the tests. + +The following is the updated Dockerfile. + +```dockerfile {hl_lines="26-28"} +# syntax=docker/dockerfile:1 + +FROM composer:lts as prod-deps +WORKDIR /app +RUN --mount=type=bind,source=./composer.json,target=composer.json \ + --mount=type=bind,source=./composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-dev --no-interaction + +FROM composer:lts as dev-deps +WORKDIR /app +RUN --mount=type=bind,source=./composer.json,target=composer.json \ + --mount=type=bind,source=./composer.lock,target=composer.lock \ + --mount=type=cache,target=/tmp/cache \ + composer install --no-interaction + +FROM php:8.2-apache as base +RUN docker-php-ext-install pdo pdo_mysql +COPY ./src /var/www/html + +FROM base as development +COPY ./tests /var/www/html/tests +RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" +COPY --from=dev-deps app/vendor/ /var/www/html/vendor + +FROM development as test +WORKDIR /var/www/html +RUN ./vendor/bin/phpunit tests/HelloWorldTest.php + +FROM base as final +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" +COPY --from=prod-deps app/vendor/ /var/www/html/vendor +USER www-data +``` + +Run the following command to build an image using the test stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage. + +```console +$ docker build -t php-docker-image-test --progress plain --no-cache --target test . +``` + +You should see output containing the following. + +```console +#18 [test 2/2] RUN ./vendor/bin/phpunit tests/HelloWorldTest.php +#18 0.385 Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. +#18 0.392 +#18 0.394 . 1 / 1 (100%) +#18 0.395 +#18 0.395 Time: 00:00.003, Memory: 4.00 MB +#18 0.395 +#18 0.395 OK (1 test, 1 assertion) +``` + +### Summary + +In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image. + +Related information: + +- [docker compose run](/reference/cli/docker/compose/run/) diff --git a/content/guides/php/_index.md b/content/guides/php/_index.md deleted file mode 100644 index 358b13865aa9..000000000000 --- a/content/guides/php/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: PHP language-specific guide -linkTitle: PHP -description: Containerize and develop PHP apps using Docker -keywords: getting started, php, composer -summary: | - This guide explains how to containerize PHP applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/php/ - - /guides/language/php/ -languages: [php] -params: - time: 20 minutes ---- - -The PHP language-specific guide teaches you how to create a containerized PHP application using Docker. In this guide, you'll learn how to: - -- Containerize and run a PHP application -- Set up a local environment to develop a PHP application using containers -- Run tests for a PHP application within containers -- Configure a CI/CD pipeline for a containerized PHP application using GitHub Actions -- Deploy your containerized application locally to Kubernetes to test and debug your deployment - -After completing the PHP language-specific guide, you should be able to containerize your own PHP application based on the examples and instructions provided in this guide. - -Start by containerizing an existing PHP application. diff --git a/content/guides/php/configure-ci-cd.md b/content/guides/php/configure-ci-cd.md deleted file mode 100644 index 3f1053e5b870..000000000000 --- a/content/guides/php/configure-ci-cd.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Configure CI/CD for your PHP application -linkTitle: Configure CI/CD -weight: 40 -keywords: php, CI/CD -description: Learn how to Configure CI/CD for your PHP application -aliases: - - /language/php/configure-ci-cd/ - - /guides/language/php/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a PHP application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. In your local repository on your machine, run the following command to rename - the branch to main. - - ```console - $ git branch -M main - ``` - -8. Run the following commands to stage, commit, and then push your local - repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my first commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and test - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - target: test - load: true - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - target: final - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/php/containerize.md b/content/guides/php/containerize.md deleted file mode 100644 index 20f4987af1de..000000000000 --- a/content/guides/php/containerize.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: Containerize a PHP application -linkTitle: Containerize your app -weight: 10 -keywords: php, containerize, initialize, apache, composer -description: Learn how to containerize a PHP application. -aliases: - - /language/php/containerize/ - - /guides/language/php/containerize/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker - Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this - section use a command-line based git client, but you can use any client. - -## Overview - -This section walks you through containerizing and running a PHP -application. - -## Get the sample applications - -In this guide, you will use a pre-built PHP application. The application uses Composer for library dependency management. You'll serve the application via an Apache web server. - -Open a terminal, change directory to a directory that you want to work in, and -run the following command to clone the repository. - -```console -$ git clone https://github.com/docker/docker-php-sample -``` - -The sample application is a basic hello world application and an application that increments a counter in a database. In addition, the application uses PHPUnit for testing. - -## Create Docker assets - -Now that you have an application, you can create the necessary Docker assets to -containerize it. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -Create the following files in your `docker-php-sample` directory. - -```dockerfile {collapse=true,title=Dockerfile} -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -################################################################################ - -# Create a stage for installing app dependencies defined in Composer. -FROM composer:lts as deps - -WORKDIR /app - -# If your composer.json file defines scripts that run during dependency installation and -# reference your application source files, uncomment the line below to copy all the files -# into this layer. -# COPY . . - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a bind mounts to composer.json and composer.lock to avoid having to copy them -# into this layer. -# Leverage a cache mount to /tmp/cache so that subsequent builds don't have to re-download packages. -RUN --mount=type=bind,source=composer.json,target=composer.json \ - --mount=type=bind,source=composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-dev --no-interaction - -################################################################################ - -# Create a new stage for running the application that contains the minimal -# runtime dependencies for the application. This often uses a different base -# image from the install or build stage where the necessary files are copied -# from the install stage. -# -# The example below uses the PHP Apache image as the foundation for running the app. -# By specifying the "8.2-apache" tag, it will also use whatever happens to be the -# most recent version of that tag when you build your Dockerfile. -# If reproducibility is important, consider using a specific digest SHA, like -# php@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4. -FROM php:8.2-apache as final - -# Your PHP application may require additional PHP extensions to be installed -# manually. For detailed instructions for installing extensions can be found, see -# https://github.com/docker-library/docs/tree/master/php#how-to-install-more-php-extensions -# The following code blocks provide examples that you can edit and use. -# -# Add core PHP extensions, see -# https://github.com/docker-library/docs/tree/master/php#php-core-extensions -# This example adds the apt packages for the 'gd' extension's dependencies and then -# installs the 'gd' extension. For additional tips on running apt-get, see -# https://docs.docker.com/go/dockerfile-aptget-best-practices/ -# RUN apt-get update && apt-get install -y \ -# libfreetype-dev \ -# libjpeg62-turbo-dev \ -# libpng-dev \ -# && rm -rf /var/lib/apt/lists/* \ -# && docker-php-ext-configure gd --with-freetype --with-jpeg \ -# && docker-php-ext-install -j$(nproc) gd -# -# Add PECL extensions, see -# https://github.com/docker-library/docs/tree/master/php#pecl-extensions -# This example adds the 'redis' and 'xdebug' extensions. -# RUN pecl install redis-5.3.7 \ -# && pecl install xdebug-3.2.1 \ -# && docker-php-ext-enable redis xdebug - -# Use the default production configuration for PHP runtime arguments, see -# https://github.com/docker-library/docs/tree/master/php#configuration -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" - -# Copy the app dependencies from the previous install stage. -COPY --from=deps app/vendor/ /var/www/html/vendor -# Copy the app files from the app directory. -COPY ./src /var/www/html - -# Switch to a non-privileged user (defined in the base image) that the app will run under. -# See https://docs.docker.com/go/dockerfile-user-best-practices/ -USER www-data -``` - -```yaml {collapse=true,title=compose.yaml} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - ports: - - 9000:80 - -# The commented out section below is an example of how to define a PostgreSQL -# database that your application can use. `depends_on` tells Docker Compose to -# start the database before your application. The `db-data` volume persists the -# database data between container restarts. The `db-password` secret is used -# to set the database password. You must create `db/password.txt` and add -# a password of your choosing to it before running `docker compose up`. -# depends_on: -# db: -# condition: service_healthy -# db: -# image: postgres -# restart: always -# user: postgres -# secrets: -# - db-password -# volumes: -# - db-data:/var/lib/postgresql/data -# environment: -# - POSTGRES_DB=example -# - POSTGRES_PASSWORD_FILE=/run/secrets/db-password -# expose: -# - 5432 -# healthcheck: -# test: [ "CMD", "pg_isready" ] -# interval: 10s -# timeout: 5s -# retries: 5 -# volumes: -# db-data: -# secrets: -# db-password: -# file: db/password.txt -``` - -```text {collapse=true,title=".dockerignore"} -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/.next -**/.cache -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/charts -**/docker-compose* -**/compose.y*ml -!**/composer.json -!**/composer.lock -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -**/vendor -LICENSE -README.md -``` - -You should now have the following contents in your `docker-php-sample` -directory. - -```text -├── docker-php-sample/ -│ ├── .git/ -│ ├── src/ -│ ├── tests/ -│ ├── .dockerignore -│ ├── .gitignore -│ ├── compose.yaml -│ ├── composer.json -│ ├── composer.lock -│ ├── Dockerfile -│ └── README.md -``` - -To learn more about these files, see the following: - -- [Dockerfile](/reference/dockerfile.md) -- [.dockerignore](/reference/dockerfile.md#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `docker-php-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-php-sample` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run a simple PHP -application using Docker. - -## Next steps - -In the next section, you'll learn how you can develop your application using -Docker containers. diff --git a/content/guides/php/deploy.md b/content/guides/php/deploy.md deleted file mode 100644 index bd45d5ec0171..000000000000 --- a/content/guides/php/deploy.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Test your PHP deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, php, local, development -description: Learn how to deploy your application -aliases: - - /language/php/deploy/ - - /guides/language/php/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize - a PHP application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker - Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your -application to a fully-featured Kubernetes environment on your development -machine. This allows you to test and debug your workloads on Kubernetes locally -before deploying. - -## Create a Kubernetes YAML file - -In your `docker-php-sample` directory, create a file named -`docker-php-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your PHP application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-php-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - hello-php: web - template: - metadata: - labels: - hello-php: web - spec: - containers: - - name: hello-site - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: php-entrypoint - namespace: default -spec: - type: NodePort - selector: - hello-php: web - ports: - - port: 80 - targetPort: 80 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The container is - created from the image built by GitHub Actions in [Configure CI/CD for your - PHP application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 80 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to the `docker-php-sample` directory - and deploy your application to Kubernetes. - - ```console - $ kubectl apply -f docker-php-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```text - deployment.apps/docker-php-demo created - service/php-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```text - NAME READY UP-TO-DATE AVAILABLE AGE - docker-php-demo 1/1 1 1 6s - ``` - - This indicates all of the pods are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```text - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 7d22h - php-entrypoint NodePort 10.111.101.229 <none> 80:30001/TCP 33s - ``` - - In addition to the default `kubernetes` service, you can see your `php-entrypoint` service. The `php-entrypoint` service is accepting traffic on port 30001/TCP. - -3. Open a browser and visit your app at - [http://localhost:30001/hello.php](http://localhost:30001/hello.php). You - should see your application. - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-php-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/php/develop.md b/content/guides/php/develop.md deleted file mode 100644 index 17ca0cc3a6d6..000000000000 --- a/content/guides/php/develop.md +++ /dev/null @@ -1,458 +0,0 @@ ---- -title: Use containers for PHP development -linkTitle: Develop your app -weight: 20 -keywords: php, development -description: Learn how to develop your PHP application locally using containers. -aliases: - - /language/php/develop/ - - /guides/language/php/develop/ ---- - -## Prerequisites - -Complete [Containerize a PHP application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Adding a local database and persisting data -- Adding phpMyAdmin to interact with the database -- Configuring Compose to automatically update your running Compose services as - you edit and save your code -- Creating a development container that contains the dev dependencies - -## Add a local database and persist data - -You can use containers to set up local services, like a database. -To do this for the sample application, you'll need to do the following: - -- Update the `Dockerfile` to install extensions to connect to the database -- Update the `compose.yaml` file to add a database service and volume to persist data - -### Update the Dockerfile to install extensions - -To install PHP extensions, you need to update the `Dockerfile`. Open your -Dockerfile in an IDE or text editor and then update the contents. The following -`Dockerfile` includes one new line that installs the `pdo` and `pdo_mysql` -extensions. All comments have been removed. - -```dockerfile {hl_lines=11} -# syntax=docker/dockerfile:1 - -FROM composer:lts as deps -WORKDIR /app -RUN --mount=type=bind,source=composer.json,target=composer.json \ - --mount=type=bind,source=composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-dev --no-interaction - -FROM php:8.2-apache as final -RUN docker-php-ext-install pdo pdo_mysql -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" -COPY --from=deps app/vendor/ /var/www/html/vendor -COPY ./src /var/www/html -USER www-data -``` - -For more details about installing PHP extensions, see the [Official Docker Image for PHP](https://hub.docker.com/_/php). - -### Update the compose.yaml file to add a db and persist data - -Open the `compose.yaml` file in an IDE or text editor. You'll notice it -already contains commented-out instructions for a PostgreSQL database and volume. For this application, you'll use MariaDB. For more details about MariaDB, see the [MariaDB Official Docker image](https://hub.docker.com/_/mariadb). - -Open the `src/database.php` file in an IDE or text editor. You'll notice that it reads environment variables in order to connect to the database. - -In the `compose.yaml` file, you'll need to update the following: - -1. Uncomment and update the database instructions for MariaDB. -2. Add a secret to the server service to pass in the database password. -3. Add the database connection environment variables to the server service. -4. Uncomment the volume instructions to persist data. - -The following is the updated `compose.yaml` file. All comments have been removed. - -```yaml -services: - server: - build: - context: . - ports: - - 9000:80 - depends_on: - db: - condition: service_healthy - secrets: - - db-password - environment: - - PASSWORD_FILE_PATH=/run/secrets/db-password - - DB_HOST=db - - DB_NAME=example - - DB_USER=root - db: - image: mariadb - restart: always - user: root - secrets: - - db-password - volumes: - - db-data:/var/lib/mysql - environment: - - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - - MARIADB_DATABASE=example - expose: - - 3306 - healthcheck: - test: - [ - "CMD", - "/usr/local/bin/healthcheck.sh", - "--su-mysql", - "--connect", - "--innodb_initialized", - ] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -> [!NOTE] -> -> To learn more about the instructions in the Compose file, see [Compose file -> reference](/reference/compose-file/). - -Before you run the application using Compose, notice that this Compose file uses -`secrets` and specifies a `password.txt` file to hold the database's password. -You must create this file as it's not included in the source repository. - -In the `docker-php-sample` directory, create a new directory named `db` and -inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file. - -```text -example -``` - -Save and close the `password.txt` file. - -You should now have the following in your `docker-php-sample` directory. - -```text -├── docker-php-sample/ -│ ├── .git/ -│ ├── db/ -│ │ └── password.txt -│ ├── src/ -│ ├── tests/ -│ ├── .dockerignore -│ ├── .gitignore -│ ├── compose.yaml -│ ├── composer.json -│ ├── composer.lock -│ ├── Dockerfile -│ └── README.md -``` - -Run the following command to start your application. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:9000/database.php](http://localhost:9000/database.php). You should see a simple web application with text and a counter that increments every time you refresh. - -Press `ctrl+c` in the terminal to stop your application. - -## Verify that data persists in the database - -In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again. - -```console -$ docker compose rm -$ docker compose up --build -``` - -Refresh [http://localhost:9000/database.php](http://localhost:9000/database.php) in your browser and verify that the previous count still exists. Without a volume, the database data wouldn't persist after you remove the container. - -Press `ctrl+c` in the terminal to stop your application. - -## Add phpMyAdmin to interact with the database - -You can easily add services to your application stack by updating the `compose.yaml` file. - -Update your `compose.yaml` to add a new service for phpMyAdmin. For more details, see the [phpMyAdmin Official Docker Image](https://hub.docker.com/_/phpmyadmin). The following is the updated `compose.yaml` file. - -```yaml {hl_lines="42-49"} -services: - server: - build: - context: . - ports: - - 9000:80 - depends_on: - db: - condition: service_healthy - secrets: - - db-password - environment: - - PASSWORD_FILE_PATH=/run/secrets/db-password - - DB_HOST=db - - DB_NAME=example - - DB_USER=root - db: - image: mariadb - restart: always - user: root - secrets: - - db-password - volumes: - - db-data:/var/lib/mysql - environment: - - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - - MARIADB_DATABASE=example - expose: - - 3306 - healthcheck: - test: - [ - "CMD", - "/usr/local/bin/healthcheck.sh", - "--su-mysql", - "--connect", - "--innodb_initialized", - ] - interval: 10s - timeout: 5s - retries: 5 - phpmyadmin: - image: phpmyadmin - ports: - - 8080:80 - depends_on: - - db - environment: - - PMA_HOST=db -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -In the terminal, run `docker compose up` to run your application again. - -```console -$ docker compose up --build -``` - -Open [http://localhost:8080](http://localhost:8080) in your browser to access phpMyAdmin. Log in using `root` as the username and `example` as the password. You can now interact with the database through phpMyAdmin. - -Press `ctrl+c` in the terminal to stop your application. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file. - -```yaml {hl_lines="17-21"} -services: - server: - build: - context: . - ports: - - 9000:80 - depends_on: - db: - condition: service_healthy - secrets: - - db-password - environment: - - PASSWORD_FILE_PATH=/run/secrets/db-password - - DB_HOST=db - - DB_NAME=example - - DB_USER=root - develop: - watch: - - action: sync - path: ./src - target: /var/www/html - db: - image: mariadb - restart: always - user: root - secrets: - - db-password - volumes: - - db-data:/var/lib/mysql - environment: - - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - - MARIADB_DATABASE=example - expose: - - 3306 - healthcheck: - test: - [ - "CMD", - "/usr/local/bin/healthcheck.sh", - "--su-mysql", - "--connect", - "--innodb_initialized", - ] - interval: 10s - timeout: 5s - retries: 5 - phpmyadmin: - image: phpmyadmin - ports: - - 8080:80 - depends_on: - - db - environment: - - PMA_HOST=db -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Open a browser and verify that the application is running at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). - -Any changes to the application's source files on your local machine will now be -immediately reflected in the running container. - -Open `hello.php` in an IDE or text editor and update the string `Hello, world!` to `Hello, Docker!`. - -Save the changes to `hello.php` and then wait a few seconds for the application to sync. Refresh [http://localhost:9000/hello.php](http://localhost:9000/hello.php) in your browser and verify that the updated text appears. - -Press `ctrl+c` in the terminal to stop Compose Watch. Run `docker compose down` in the terminal to stop the application. - -## Create a development container - -At this point, when you run your containerized application, Composer isn't installing the dev dependencies. While this small image is good for production, it lacks the tools and dependencies you may need when developing and it doesn't include the `tests` directory. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](/manuals/build/building/multi-stage.md). - -In the `Dockerfile`, you'll need to update the following: - -1. Split the `deps` staged into two stages. One stage for production - (`prod-deps`) and one stage (`dev-deps`) to install development dependencies. -2. Create a common `base` stage. -3. Create a new `development` stage for development. -4. Update the `final` stage to copy dependencies from the new `prod-deps` stage. - -The following is the `Dockerfile` before and after the changes. - -{{< tabs >}} -{{< tab name="Before" >}} - -```dockerfile -# syntax=docker/dockerfile:1 - -FROM composer:lts as deps -WORKDIR /app -RUN --mount=type=bind,source=composer.json,target=composer.json \ - --mount=type=bind,source=composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-dev --no-interaction - -FROM php:8.2-apache as final -RUN docker-php-ext-install pdo pdo_mysql -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" -COPY --from=deps app/vendor/ /var/www/html/vendor -COPY ./src /var/www/html -USER www-data -``` - -{{< /tab >}} -{{< tab name="After" >}} - -```dockerfile -# syntax=docker/dockerfile:1 - -FROM composer:lts as prod-deps -WORKDIR /app -RUN --mount=type=bind,source=./composer.json,target=composer.json \ - --mount=type=bind,source=./composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-dev --no-interaction - -FROM composer:lts as dev-deps -WORKDIR /app -RUN --mount=type=bind,source=./composer.json,target=composer.json \ - --mount=type=bind,source=./composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-interaction - -FROM php:8.2-apache as base -RUN docker-php-ext-install pdo pdo_mysql -COPY ./src /var/www/html - -FROM base as development -COPY ./tests /var/www/html/tests -RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" -COPY --from=dev-deps app/vendor/ /var/www/html/vendor - -FROM base as final -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" -COPY --from=prod-deps app/vendor/ /var/www/html/vendor -USER www-data -``` - -{{< /tab >}} -{{< /tabs >}} - -Update your `compose.yaml` file by adding an instruction to target the -development stage. - -The following is the updated section of the `compose.yaml` file. - -```yaml {hl_lines=5} -services: - server: - build: - context: . - target: development - # ... -``` - -Your containerized application will now install the dev dependencies. - -Run the following command to start your application. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should still see the simple "Hello, Docker!" application. - -Press `ctrl+c` in the terminal to stop your application. - -While the application appears the same, you can now make use of the dev dependencies. Continue to the next section to learn how you can run tests using Docker. - -## Summary - -In this section, you took a look at setting up your Compose file to add a local -database and persist data. You also learned how to use Compose Watch to automatically sync your application when you update your code. And finally, you learned how to create a development container that contains the dependencies needed for development. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose file watch](/manuals/compose/how-tos/file-watch.md) -- [Dockerfile reference](/reference/dockerfile.md) -- [Official Docker Image for PHP](https://hub.docker.com/_/php) - -## Next steps - -In the next section, you'll learn how to run unit tests using Docker. diff --git a/content/guides/php/run-tests.md b/content/guides/php/run-tests.md deleted file mode 100644 index 7ddad4d72fb8..000000000000 --- a/content/guides/php/run-tests.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Run PHP tests in a container -linkTitle: Run your tests -weight: 30 -keywords: php, test -description: Learn how to run your PHP tests in a container. -aliases: - - /language/php/run-tests/ - - /guides/language/php/run-tests/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a PHP application](containerize.md). - -## Overview - -Testing is an essential part of modern software development. Testing can mean a -lot of things to different development teams. There are unit tests, integration -tests and end-to-end testing. In this guide you take a look at running your unit -tests in Docker when developing and when building. - -## Run tests when developing locally - -The sample application already has a PHPUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests. - -Run the following command in the `docker-php-sample` directory to run the tests inside a container. - -```console -$ docker compose run --build --rm server ./vendor/bin/phpunit tests/HelloWorldTest.php -``` - -You should see output that contains the following. - -```console -Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. - -. 1 / 1 (100%) - -Time: 00:00.003, Memory: 4.00 MB - -OK (1 test, 1 assertion) -``` - -To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). - -## Run tests when building - -To run your tests when building, you need to update your Dockerfile. Create a new test stage that runs the tests. - -The following is the updated Dockerfile. - -```dockerfile {hl_lines="26-28"} -# syntax=docker/dockerfile:1 - -FROM composer:lts as prod-deps -WORKDIR /app -RUN --mount=type=bind,source=./composer.json,target=composer.json \ - --mount=type=bind,source=./composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-dev --no-interaction - -FROM composer:lts as dev-deps -WORKDIR /app -RUN --mount=type=bind,source=./composer.json,target=composer.json \ - --mount=type=bind,source=./composer.lock,target=composer.lock \ - --mount=type=cache,target=/tmp/cache \ - composer install --no-interaction - -FROM php:8.2-apache as base -RUN docker-php-ext-install pdo pdo_mysql -COPY ./src /var/www/html - -FROM base as development -COPY ./tests /var/www/html/tests -RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" -COPY --from=dev-deps app/vendor/ /var/www/html/vendor - -FROM development as test -WORKDIR /var/www/html -RUN ./vendor/bin/phpunit tests/HelloWorldTest.php - -FROM base as final -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" -COPY --from=prod-deps app/vendor/ /var/www/html/vendor -USER www-data -``` - -Run the following command to build an image using the test stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage. - -```console -$ docker build -t php-docker-image-test --progress plain --no-cache --target test . -``` - -You should see output containing the following. - -```console -#18 [test 2/2] RUN ./vendor/bin/phpunit tests/HelloWorldTest.php -#18 0.385 Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. -#18 0.392 -#18 0.394 . 1 / 1 (100%) -#18 0.395 -#18 0.395 Time: 00:00.003, Memory: 4.00 MB -#18 0.395 -#18 0.395 OK (1 test, 1 assertion) -``` - -## Summary - -In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image. - -Related information: - -- [docker compose run](/reference/cli/docker/compose/run/) - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/postgresql.md b/content/guides/postgresql.md new file mode 100644 index 000000000000..869e976739af --- /dev/null +++ b/content/guides/postgresql.md @@ -0,0 +1,1171 @@ +--- +title: PostgreSQL specific guide +linkTitle: PostgreSQL +description: Containerize PostgreSQL databases using Docker +keywords: Docker, getting started, postgresql, language +summary: | + This guide explains how to containerize PostgreSQL databases using + Docker. +aliases: + - /guides/postgresql/advanced-configuration-and-initialization/ + - /guides/postgresql/companions-for-postgresql/ + - /guides/postgresql/immediate-setup-and-data-persistence/ + - /guides/postgresql/networking-and-connectivity/ +params: + tags: [databases] + time: 20 minutes +--- + + +## Immediate setup & data persistence + +This guide gets you from zero to a running PostgreSQL container in under five minutes, then explains how to keep your data safe across container restarts and removals. + +### Overview + +Running PostgreSQL in Docker requires understanding one critical concept: containers are ephemeral, but your data shouldn't be. This guide covers: + +- Starting PostgreSQL with a single command +- Understanding why containers lose data by default +- Configuring volumes for persistent storage +- Translating your setup to Docker Compose + +### Quick start (minimal viable container) + +> [!NOTE] +> +> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in. + +Run PostgreSQL immediately with this single command: + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. + +```console +docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -d dhi.io/postgres:18 +``` + +{{< /tab >}} + +{{< tab name="Using DOIs" >}} + +```console +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -d postgres:18 +``` + +{{< /tab >}} +{{< /tabs >}} + +#### Understanding the flags + +| Flag | Purpose | +|------|---------| +| `--rm` | Automatically removes the container when it stops | +| `--name postgres-dev` | Assigns a memorable name instead of a random string | +| `-e POSTGRES_PASSWORD=...` | Sets the superuser password (required) | +| `-p 5432:5432` | Maps host port 5432 to container port 5432 | +| `-d` | Runs the container in the background (detached mode) | + +Verify the container is running: + +```console +$ docker ps --filter name=postgres-dev +CONTAINER ID IMAGE COMMAND STATUS PORTS NAMES +a1b2c3d4e5f6 postgres:18 "docker-entrypoint.s…" Up 2 seconds 0.0.0.0:5432->5432/tcp postgres-dev +``` + +Connect using `psql` from inside the container: + +```console +$ docker exec -it postgres-dev psql -U postgres +psql (18.0) +Type "help" for help. + +postgres=# +``` + +You now have a working PostgreSQL instance. But there's a problem—stop this container and your data disappears. + +### The data persistence problem + +Containers use an ephemeral filesystem. When a container is removed, everything inside it, including your database files, is deleted. + +Demonstrate this yourself: + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +```console +$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" +CREATE DATABASE + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb + testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + +$ docker stop postgres-dev +postgres-dev + +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -d dhi.io/postgres:18 + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb +(no output - database is gone) +``` + +{{< /tab >}} + +{{< tab name="Using DOIs" >}} + +```console +$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" +CREATE DATABASE + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb + testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + +$ docker stop postgres-dev +postgres-dev + +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -d postgres:18 + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb +(no output - database is gone) +``` + +{{< /tab >}} +{{< /tabs >}} + +Your `testdb` database vanished because the new container started with a fresh filesystem. This is expected behavior—and exactly why volumes exist. + +### Named volumes + +Named volumes are Docker-managed storage locations that persist independently of containers. Docker handles the filesystem location, permissions, and lifecycle. + +Create a container with a named volume: + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. + +```console +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + -d dhi.io/postgres:18 +``` + +{{< /tab >}} + +{{< tab name="Using DOIs" >}} + +```console +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + -d postgres:18 +``` + +{{< /tab >}} +{{< /tabs >}} + + +The `-v postgres_data:/var/lib/postgresql` flag mounts a named volume called `postgres_data` to PostgreSQL's data directory. If the volume doesn't exist, Docker creates it automatically. + +> [!NOTE] +> +> PostgreSQL 18+ stores data in a version-specific subdirectory under `/var/lib/postgresql`. Mounting at this level (rather than `/var/lib/postgresql/data`) allows for easier upgrades using `pg_upgrade --link`. + +#### Verify persistence works + +To verify data persistence, repeat the previous test, but this time with the named volume attached in place. + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +```console +$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" +CREATE DATABASE + +$ docker stop postgres-dev +postgres-dev + +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + -d dhi.io/postgres:18 + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb + testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | +``` + +{{< /tab >}} + +{{< tab name="Using DOIs" >}} + +```console +$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" +CREATE DATABASE + +$ docker stop postgres-dev +postgres-dev + +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + -d postgres:18 + +$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb + testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | +``` + +{{< /tab >}} + +{{< /tabs >}} + +If you see `testdb` in the output, persistence works: The database survived because the volume preserved the data directory. + +#### Managing volumes + +List all volumes: + +```console +$ docker volume ls --filter name=postgres_data +DRIVER VOLUME NAME +local postgres_data +``` + +Inspect a volume to see its details: + +```console +$ docker volume inspect postgres_data +[ + { + "CreatedAt": "2025-01-05T10:30:00Z", + "Driver": "local", + "Labels": null, + "Mountpoint": "/var/lib/docker/volumes/postgres_data/_data", + "Name": "postgres_data", + "Options": null, + "Scope": "local" + } +] +``` + +Remove an unused volume (warning: this deletes all data): + +```console +$ docker volume rm postgres_data +``` + +### Bind mounts (alternative) + +Bind mounts map a specific host directory to a container path. Unlike named volumes, you control exactly where data lives on the host filesystem. + +Create a directory on your host machine to store Postgres data. + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +```console +mkdir -p ~/postgres-data && sudo chown -R 999:999 ~/postgres-data +``` + +Run Postgres using a bind mount. + +```console +docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v ~/postgres-data:/var/lib/postgresql \ + -d dhi.io/postgres:18 +``` + +{{< /tab >}} + +{{< tab name="Using DOIs" >}} + +```console +$ mkdir -p ~/postgres-data +``` + +Run Postgres using a bind mount. + +```console +$ docker run --rm --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v ~/postgres-data:/var/lib/postgresql \ + -d postgres:18 +``` + +{{< /tab >}} +{{< /tabs >}} + +#### When to use bind mounts + +Bind mounts are useful when you need direct filesystem access to the data directory for backup scripts that read files directly, when integrating with host-level monitoring tools, or when specific permission requirements exist. For most development and production scenarios, named volumes are simpler and less error-prone. + +#### Common bind mount issues + +Permission errors are the most frequent problem with bind mounts. PostgreSQL runs as user `postgres` (UID 999) inside the container. If your host directory has restrictive permissions, the container fails to start. + +Check logs if the container exits immediately: + +```console +$ docker logs postgres-dev +``` + +### Docker Compose configuration + +Docker Compose captures your entire configuration in a file, making setups reproducible and easier to manage as complexity grows. + +Create a `compose.yaml` file: + +```yaml +services: + db: + image: postgres:18 + container_name: postgres-dev + environment: + POSTGRES_PASSWORD: mysecretpassword + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql + +volumes: + postgres_data: +``` + +Start the database: + +```console +$ docker compose up -d +``` + +Stop and remove containers (volume persists): + +```console +$ docker compose down +``` + +Alternatively, you can stop, remove containers, and delete the volume: + +```console +$ docker compose down -v +``` + +This compose file becomes the foundation for adding initialization scripts, performance tuning, and companion services covered in subsequent guides. + +#### Environment variables reference + +The official PostgreSQL image supports these environment variables: + +| Variable | Required | Description | +|----------|----------|-------------| +| `POSTGRES_PASSWORD` | Yes | Superuser password | +| `POSTGRES_USER` | No | Superuser name (default: `postgres`) | +| `POSTGRES_DB` | No | Default database name (default: value of `POSTGRES_USER`) | + +### Next steps + +With persistent storage configured, you're ready to customize PostgreSQL further. The next chapter of the guide covers: + +- Automated schema creation with initialization scripts +- Performance tuning for containerized workloads +- Timezone and locale configuration + +## Advanced Configuration and Initialization + +With persistent storage configured in the previous section, you're ready to customize PostgreSQL for real-world use. This guide covers advanced configuration techniques for running PostgreSQL in Docker containers, including automated database initialization, performance tuning, and timezone configuration. + +### Overview + +While PostgreSQL containers can be started quickly with default settings, production environments require customized configurations. This guide explains how to: + +- Automate database, schema, and user creation during container startup +- Tune PostgreSQL performance parameters for containerized workloads +- Configure timezone and locale settings + +### Initialization scripts + +The official PostgreSQL Docker image supports running initialization scripts automatically when the container starts for the first time. Any files placed in the `/docker-entrypoint-initdb.d/` directory are executed in alphabetical order. + +#### How initialization works + +When the container starts, it checks whether the PostgreSQL data directory is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL. + +#### Supported file formats + +| Format | Description | +|--------|-------------| +| `.sql` | SQL commands executed directly | +| `.sql.gz` | Gzip-compressed SQL files | +| `.sh` | Shell scripts executed with bash | + +> [!IMPORTANT] +> +> Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases. + +### Mounting initialization scripts + +Use Docker Compose to mount initialization scripts into the container. First, create a project directory: + +```console +$ mkdir -p postgres-project/init-db +$ cd postgres-project +``` + +Create a `compose.yaml` file: + +```yaml +services: + db: + image: postgres:18 + volumes: + - ./init-db:/docker-entrypoint-initdb.d + - postgres_data:/var/lib/postgresql + environment: + POSTGRES_PASSWORD: mysecretpassword + +volumes: + postgres_data: +``` + +All scripts in the `./init-db` directory execute when the container starts for the first time. This is great for bootstrapping databases. + +### Initialization script example + +Create a file named `init.sql` in your `init-db` directory: + +```sql +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + email VARCHAR(255) UNIQUE NOT NULL, + name VARCHAR(100) NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +This script runs automatically when the container starts for the first time, creating your initial database schema. + +> [!NOTE] +> +> Ensure initialization scripts have proper read permissions. If you encounter "Permission denied" errors, run `chmod 644 init-db/*.sql` to make the files readable by the container. + +### Performance tuning + +Default PostgreSQL settings are conservative to work on systems with limited resources. For production workloads, you should tune these parameters based on your container's allocated resources. + +#### Method 1: Custom configuration file + +For complete control, mount a custom `postgresql.conf` file. First, extract the default configuration: + +```console +$ docker run -i --rm postgres:18 cat /usr/share/postgresql/postgresql.conf.sample > my-postgres.conf +``` + +Edit `my-postgres.conf` with your desired settings, then mount it in your Compose file: + +```yaml +services: + db: + image: postgres:18 + volumes: + - ./my-postgres.conf:/etc/postgresql/postgresql.conf + - ./init-db:/docker-entrypoint-initdb.d + - postgres_data:/var/lib/postgresql + command: postgres -c config_file=/etc/postgresql/postgresql.conf + environment: + POSTGRES_PASSWORD: mysecretpassword + +volumes: + postgres_data: +``` + +### Key configuration parameters + +The following tables list important `postgresql.conf` parameters for containerized PostgreSQL deployments. + +#### Connection settings + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `listen_addresses` | IP addresses to listen on | `localhost` | +| `port` | TCP port number | `5432` | +| `max_connections` | Maximum concurrent connections | `100` | + +#### Memory settings + +| Parameter | Description | Recommended starting value | +|-----------|-------------|---------------------------| +| `shared_buffers` | Shared memory for caching | 25% of container memory | +| `work_mem` | Memory per query operation | 4MB - 64MB | +| `maintenance_work_mem` | Memory for VACUUM, CREATE INDEX | 64MB - 256MB | +| `effective_cache_size` | Planner's cache size estimate | 50-75% of container memory | + +##### Docker memory limits + +When tuning memory parameters, set explicit memory limits on your container using `deploy.resources.limits.memory` in Compose or `--memory` with `docker run`. Without limits, PostgreSQL sees the host's total RAM and may allocate more than intended. For example, if your container should use 4GB maximum, set `shared_buffers` to approximately 1GB (25%). + +#### I/O settings + +| Parameter | Description | Recommended starting value | +|-----------|-------------|---------------------------| +| `effective_io_concurrency` | Concurrent disk I/O operations | `200` for SSDs, `2` for HDDs | + +#### Timeout settings + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `statement_timeout` | Max time for any statement | `0` (disabled) | +| `lock_timeout` | Max time to wait for a lock | `0` (disabled) | +| `deadlock_timeout` | Time before checking for deadlock | `1s` | +| `transaction_timeout` | Max time for a transaction | `0` (disabled) | + +> [!NOTE] +> +> Setting `shared_buffers` too high in a container can exceed kernel shared memory limits. Use no more than 25-30% of the container's memory limit. + +### Timezone and locale configuration + +Proper localization ensures timestamps and sorting behave correctly for your application's users. + +```yaml +services: + db: + image: postgres:18 + volumes: + - postgres_data:/var/lib/postgresql + - /etc/localtime:/etc/localtime:ro + - /etc/timezone:/etc/timezone:ro + environment: + POSTGRES_PASSWORD: mysecretpassword + TZ: America/New_York + +volumes: + postgres_data: +``` + +Alternatively, set the timezone using a PostgreSQL command-line parameter: + +```yaml +services: + db: + image: postgres:18 + command: ["postgres", "-c", "timezone=America/New_York"] + environment: + POSTGRES_PASSWORD: mysecretpassword +``` + +#### Setting the locale + +Specify locale settings during database initialization using the `POSTGRES_INITDB_ARGS` environment variable: + +```yaml +services: + db: + image: postgres:18 + volumes: + - postgres_data:/var/lib/postgresql + environment: + POSTGRES_PASSWORD: mysecretpassword + POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8" + +volumes: + postgres_data: +``` + +This affects collation (sorting) and character processing behavior. Changing this variable after database creation has no effect—it only applies during the first run when the data directory is initialized. + +### Connecting to the database + +You can interact with PostgreSQL running in a container even without `psql` installed on your host machine. + +#### Interactive shell + +Open a `psql` session inside the container: + +```console +$ docker exec -it postgres-container psql -U postgres +``` + +Connect to a specific database: + +```console +$ docker exec -it postgres-container psql -U postgres -d mydb +``` + +## Networking and connectivity + +This guide covers two common ways to connect to PostgreSQL running in Docker: + +- Container-to-container: Connect from your application container to PostgreSQL over a private Docker network. No ports need to be exposed to the host. +- Host-to-container: Connect from your laptop or development machine using `localhost` and a published port. + +Prerequisite: This guide assumes you have PostgreSQL running with persistent storage. If you don't, follow the [Immediate Setup & Data Persistence](/guides/postgresql/immediate-setup-and-data-persistence/) guide first. + +### Internal network access (container-to-container) + +When your application runs in another container, connecting to PostgreSQL through a user-defined bridge network is the recommended approach. This setup provides automatic DNS resolution, so your application can connect to PostgreSQL using the container name as the hostname, without needing to track IP addresses. + +> [!NOTE] +> Why not use the default bridge network? While containers on the default bridge network can communicate, they can only do so by IP address. Since container IP addresses change when containers restart, this would require updating your PostgreSQL connection strings each time. User-defined bridge networks solve this by providing automatic DNS resolution, ensuring your PostgreSQL connection strings remain stable even if containers restart and receive new IP addresses. + +Here's a quick comparison: + +> [!NOTE] +> +> The following examples show the difference in approach. To actually test this, follow the steps in this guide to set up containers on the appropriate networks first. + +With the default bridge network, you'd need to find the IP address first: +```bash +# Get the container's IP address (changes on restart) +docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' postgres-dev +# Output: 172.17.0.2 + +# Then connect using that IP address from another container +# (No --network flag needed - containers default to bridge network) +docker run --rm -it \ + -e PGPASSWORD=mysecretpassword \ + postgres:18 \ + psql -h 172.17.0.2 -U postgres +``` + +With a user-defined network, you simply use the container name: +```bash +# Container name works directly - no IP lookup needed +docker run --rm -it \ + --network my-app-net \ + -e PGPASSWORD=mysecretpassword \ + postgres:18 \ + psql -h postgres-dev -U postgres +``` + +#### Step 1: Create a user-defined network + +```bash +docker network create my-app-net + +# Example Output +ab7f984be43a0ca15534a9ee568716ddbe869a5875077fad3ef3192e3af7d288 + +docker network ls +# Output +ab7f984be43a my-app-net bridge local + + +``` + +#### Step 2: Run PostgreSQL on that network (no port publishing) + +Notice there is no `-p 5432:5432` here. This keeps PostgreSQL internal to Docker and not accessible from the host machine, which is more secure for production environments. + +```bash +docker run -d --name postgres-dev \ + --network my-app-net \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -v postgres_data:/var/lib/postgresql \ + postgres:18 + + # Output +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +6d351ed89efc postgres:18 "docker-entrypoint.s…" 9 seconds ago Up 8 seconds 5432/tcp postgres-dev + +``` + +#### Step 3: Connect from another container using the Postgres container name + +You can test connectivity with a temporary `psql` client container: + +```bash +docker run --rm -it \ + --network my-app-net \ + -e PGPASSWORD=mysecretpassword \ + postgres:18 \ + psql -h postgres-dev -U postgres +``` + +Key point: `-h postgres-dev` works because Docker DNS resolves the container name on a user-defined network. The container name acts as the hostname. + +#### Connection string examples + +When connecting from your application container, use these PostgreSQL connection strings: + +- PostgreSQL URI format: + This is the standard PostgreSQL connection URI format that combines all connection parameters into a single string, widely supported by PostgreSQL clients and libraries. + + ```bash + postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres + ``` + + This command demonstrates passing a PostgreSQL URI connection string as an environment variable to a container, which your application can then read to connect to the database. + + Example usage in a Docker run command: + ```bash + docker run --rm -it \ + --network my-app-net \ + -e DATABASE_URL="postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres" \ + alpine:latest \ + sh -c 'echo "DATABASE_URL is set to: $DATABASE_URL"' + ``` + + +- PostgreSQL connection parameters: + This format uses key-value pairs separated by spaces, which many PostgreSQL client libraries accept as an alternative to URI format. + ```bash + host=postgres-dev + port=5432 + user=postgres + password=mysecretpassword + dbname=postgres + ``` + + Example usage in application code (Python with psycopg2): + ```python + conn = psycopg2.connect( + host="postgres-dev", + port=5432, + user="postgres", + password="mysecretpassword", + dbname="postgres" + ) + ``` + +- Connecting to a specific database: + Replace the database name in the connection string to connect to a specific database instead of the default `postgres` database. + If you created a custom database (e.g., `testdb`), use: + ```bash + postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb + ``` + + Example with SSL disabled (common in Docker networks): + Add `?sslmode=disable` to the connection string when connecting within a private Docker network where SSL encryption isn't required. + ```bash + postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb?sslmode=disable + ``` + +> [!NOTE] +> +> The default port `5432` is used in these examples. If you're connecting to a different PostgreSQL instance or have changed the port, update the connection string accordingly. The container name (`postgres-dev`) is resolved by Docker DNS to the container's IP address on the network. + + +### Connecting from the host (external access) + +To connect to PostgreSQL from your host machine using tools like `psql`, `pgAdmin`, `DBeaver`, or database management scripts, you need to publish PostgreSQL's port (`5432`) to the host. This allows external tools to reach the PostgreSQL container. + +#### Expose Postgres to localhost only (recommended for development) + +This binds to `127.0.0.1` so it's only reachable from your local machine, not from other devices on your network. This is the most secure option for development. + +```bash +docker run -d --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 127.0.0.1:5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + postgres:18 +``` + +Now connect from your host: + +- Host: `localhost` or `127.0.0.1` +- Port: `5432` + +If you have `psql` installed on your host: +```bash +psql -h localhost -p 5432 -U postgres +``` + +You'll be prompted for the password. Alternatively, you can use the `PGPASSWORD` environment variable: +```bash +PGPASSWORD=mysecretpassword psql -h localhost -p 5432 -U postgres +``` + +#### Connecting with PostgreSQL GUI tools + +Popular PostgreSQL GUI tools can connect using these common connection details: Host: `localhost`, Port: `5432`, User: `postgres`, Database: `postgres` (or your database name). + +- pgAdmin: A web-based PostgreSQL administration and development platform +- DBeaver: A universal database tool that supports PostgreSQL and many other databases. Select PostgreSQL as the connection type +- TablePlus: A modern, native database management tool for macOS and Windows with a clean interface + +All tools will prompt for the password you set with `POSTGRES_PASSWORD`. + +#### Expose Postgres to all network interfaces (use with caution) + +To allow connections from other devices on your network, use `-p 5432:5432` instead of `-p 127.0.0.1:5432:5432`. This binds PostgreSQL to all network interfaces on your host, making it accessible from any device that can reach your host, not just localhost. + +```bash +docker run -d --name postgres-dev \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql \ + postgres:18 +``` + +> [!WARNING] +> +> Exposing PostgreSQL to all network interfaces (`0.0.0.0:5432`) makes it accessible from any device that can reach your host. Only use this in trusted network environments or behind a firewall. For production, consider using a reverse proxy or VPN instead. + +#### PostgreSQL security considerations for external access + +When exposing PostgreSQL to external access, follow these PostgreSQL-specific security practices: + +- Avoid using the `postgres` superuser: The default `postgres` user has full database privileges. Create dedicated users with only the permissions your application needs. +- Use strong passwords: PostgreSQL passwords should be complex. Consider using environment variables or secrets management instead of `hardcoding` passwords. +- Limit network exposure: Binding to `127.0.0.1` (localhost only) is safer than exposing to all interfaces (`0.0.0.0`). +- Consider SSL/TLS: For production, configure PostgreSQL to require SSL connections. The [Advanced Configuration and Initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to configure PostgreSQL settings. +- Create application-specific users: Use initialization scripts to create users with limited privileges. For example, a read-only user for reporting or a user that can only access specific databases. + +The [Advanced configuration and initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to use initialization scripts to create users and roles automatically. + +### Using Docker Compose for networking + +Docker Compose automatically creates a network for your services, making networking configuration simpler. Here's an example that combines both internal and external access: + +```yaml +services: + db: + image: postgres:18 + container_name: postgres-dev + environment: + POSTGRES_PASSWORD: mysecretpassword + volumes: + - postgres_data:/var/lib/postgresql + ports: + - "127.0.0.1:5432:5432" # Expose to localhost only + networks: + - app-network + + app: + build: ./my-app + environment: + DATABASE_URL: postgresql://postgres:mysecretpassword@db:5432/mydb + networks: + - app-network + depends_on: + - db + +volumes: + postgres_data: + +networks: + app-network: + driver: bridge +``` + +In this PostgreSQL-focused setup: +- The `app` service connects to PostgreSQL using the service name (`db`) as the hostname in the connection string +- PostgreSQL is accessible from your host at `localhost:5432` for external tools +- Both services are isolated on a custom network, providing network-level security +- The `depends_on` directive ensures PostgreSQL starts before your application + +PostgreSQL connection details for the app service: +- Hostname: `db` (resolved by Docker DNS) +- Port: `5432` (PostgreSQL default port) +- Database: `mydb` (as specified in the connection string) +- User: `postgres` (or a custom user you've created) + +> [!NOTE] +> +> Docker Compose automatically creates a network for your project. Services can reach each other by service name without explicit network configuration, but defining a custom network gives you more control. For PostgreSQL, this means your application can always connect using the service name, regardless of container restarts or IP changes. + +### Troubleshooting + +This section covers common PostgreSQL connection issues and their solutions when working with Docker networking. + +#### "Could not translate host name postgres-dev" + +- Both containers must be on the same Docker network (`my-app-net`). +- Verify the network exists: `docker network ls` +- Check which network a container is on: `docker inspect postgres-dev | grep NetworkMode` +- Ensure you're using a user-defined network, not the default bridge network + +#### "Connection refused" or "could not connect to server" + +- PostgreSQL may still be initializing: PostgreSQL takes a few seconds to start and initialize the database cluster. Wait 5-10 seconds after container start and retry. +- Check if the PostgreSQL container is running: + + ```bash + docker ps --filter name=postgres-dev + ``` + +- Check PostgreSQL logs for initialization or connection errors: + + ```bash + docker logs postgres-dev + ``` + + Look for messages like "database system is ready to accept connections" to confirm PostgreSQL is fully started. + +- Verify the port mapping is correct: + + ```bash + docker port postgres-dev + ``` + + This should show `5432/tcp -> 127.0.0.1:5432` (or `0.0.0.0:5432` if bound to all interfaces). + +- Test PostgreSQL connectivity from inside the container: + + ```bash + docker exec -it postgres-dev psql -U postgres -c "SELECT version();" + ``` + + If this works but external connections fail, the issue is with port publishing, not PostgreSQL itself. + +#### "Password authentication failed" or "FATAL: password authentication failed for user" + +- Confirm the password: Verify you're using the same password set in `POSTGRES_PASSWORD` when you started the container. +- Existing volume with old credentials: If you reused an existing volume, the password from the original initialization is still in effect. The `POSTGRES_PASSWORD` environment variable only sets the password during the first database initialization. To reset: + - Remove the volume: `docker volume rm postgres_data` + - Or connect with the old password + - Or change the password after connecting: `ALTER USER postgres WITH PASSWORD 'newpassword';` +- Try connecting with password prompt: `psql -h localhost -U postgres -W` (the `-W` flag forces a password prompt) +- Use PGPASSWORD environment variable: `PGPASSWORD=mysecretpassword psql -h localhost -U postgres` +- Check PostgreSQL authentication configuration: If you've customized `pg_hba.conf`, verify the authentication method allows password authentication + +#### "Network not found" + +- Ensure the network exists before starting containers: `docker network create my-app-net` +- If using Docker Compose, the network is created automatically when you run `docker compose up` + +## Companions for PostgreSQL + +### PostgreSQL ecosystem companions: pgAdmin, PgBouncer, and performance testing + +Running a standalone PostgreSQL container is often just the beginning. What happens when thousands of connections arrive, or when you need a visual interface to manage your database? + +This is where **companion tools** come into play. These applications extend PostgreSQL with capabilities the core database engine doesn't provide natively: visual administration, connection pooling, and performance benchmarking. This guide covers how to deploy pgAdmin 4, PgBouncer, Pgpool-II, and `pgbench` in Docker, when to use each tool, and real-world benchmark results demonstrating their performance impact. + +### pgAdmin 4: Visual management platform + +pgAdmin 4 is the industry-standard open source management tool for PostgreSQL. When deployed in Docker, it typically runs in **Server Mode**, providing a multi-user web interface to manage one or more database instances. + +While you can accomplish everything from the command line using `psql`, a visual interface significantly simplifies writing complex queries, visualizing table structures, and exploring database objects. + +#### Key considerations + +When running pgAdmin in Docker, keep these points in mind: + +- **Image**: Use the official `dpage/pgadmin4` image +- **Networking**: In a Docker Compose environment, pgAdmin connects to the database using the internal service name (for example, `db:5432`) rather than `localhost` + +#### Docker Compose configuration + +To quickly deploy pgAdmin: + +```yaml +pgadmin: + image: dpage/pgadmin4:8.14 + environment: + PGADMIN_DEFAULT_EMAIL: admin@example.com + PGADMIN_DEFAULT_PASSWORD: secure_password + volumes: + - pgadmin_data:/var/lib/pgadmin + ports: + - "8080:80" +``` + +With this configuration, access the pgAdmin interface at `http://localhost:8080`. Use the email and password specified in the environment variables for initial sign in. + +> [!IMPORTANT] +> +> In production environments, pass `PGADMIN_DEFAULT_PASSWORD` as an external environment variable or use Docker secrets. Storing passwords in plain text within `docker-compose.yml` poses a security risk. + +Now that you have visual database management in place, the next challenge in production environments is handling connection load. The following section explains how to manage high-volume database traffic. + +### PgBouncer: Lightweight connection pooling + +PostgreSQL creates a new process for every client connection, which consumes significant RAM. What happens when you have 1,000 concurrent users? PgBouncer solves exactly this problem. + +PgBouncer is a lightweight proxy that pools connections, allowing thousands of applications to share a small number of actual database backends. Think of it as a traffic controller: everyone wants to pass through simultaneously, but the controller regulates the flow to prevent congestion. + +#### Pooling modes + +PgBouncer offers three distinct pooling modes: + +| Mode | Description | Use case | +|------|-------------|----------| +| **Session** | Connection assigned for entire session duration | Long-lived connections, session variables | +| **Transaction** | Connection returned after each transaction ends | Web applications, microservices (most common) | +| **Statement** | Connection returned after every SQL statement | Simple queries, no multi-statement transactions | + +#### When to use PgBouncer + +PgBouncer becomes essential when you encounter: + +- "too many connections" errors +- High memory consumption due to connection overhead +- Many short-lived connections (web applications, serverless functions) +- Need to serve thousands of clients with limited database connections + +#### Complete Docker Compose setup + +To run PostgreSQL and PgBouncer together, you need three files: `docker-compose.yml`, `pgbouncer.ini`, and `userlist.txt`. + +First, create the PgBouncer configuration file (`pgbouncer.ini`): + +```bash +[databases] +benchmark = host=postgres port=5432 dbname=benchmark user=postgres + +[pgbouncer] +listen_addr = 0.0.0.0 +listen_port = 6432 +auth_type = trust +auth_file = /etc/pgbouncer/userlist.txt +admin_users = postgres +pool_mode = transaction +max_client_conn = 1000 +default_pool_size = 50 +min_pool_size = 10 +reserve_pool_size = 10 +max_db_connections = 100 +``` + +Next, create the user authentication file (`userlist.txt`): + +```bash +"postgres" "postgres" +``` + +Finally, create the Docker Compose file (`docker-compose.yml`): + +```yaml +services: + postgres: + image: postgres:18 + container_name: postgres + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: benchmark + POSTGRES_HOST_AUTH_METHOD: trust + volumes: + - postgres_data:/var/lib/postgresql + ports: + - "5432:5432" + networks: + - pgnet + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 5s + timeout: 5s + retries: 5 + + pgbouncer: + image: percona/percona-pgbouncer:1.25.0 + container_name: pgbouncer + volumes: + - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini + - ./userlist.txt:/etc/pgbouncer/userlist.txt + ports: + - "6432:6432" + networks: + - pgnet + depends_on: + postgres: + condition: service_healthy + +volumes: + postgres_data: + +networks: + pgnet: + driver: bridge +``` + +Key configuration notes: + +- `PgBouncer` listens on port **6432**, avoiding confusion with the direct PostgreSQL connection on port 5432 +- The `depends_on` directive with `service_healthy` condition ensures PgBouncer starts only after PostgreSQL is ready +- `pool_mode = transaction` is the optimal choice for most web applications +- The [Percona PgBouncer image](https://hub.docker.com/r/percona/percona-pgbouncer) requires mounted configuration files (without the `:ro` flag, as the entrypoint script needs to modify them) +- This example uses `trust` authentication for simplicity. In production, configure proper SCRAM-SHA-256 authentication + +> [!NOTE] +> +> The `Percona PgBouncer` entrypoint script processes the configuration files on startup. Mount them without the read-only flag to avoid permission errors. + + + + +### `pgbench`: Performance benchmarking + +`pgbench` is a benchmarking utility included with the official PostgreSQL image. It allows you to simulate heavy workloads and verify how your Docker configuration performs under pressure. + +#### Initialize benchmark tables + +First, create the test tables. The `-s` (scale) parameter determines data size—scale factor 50 creates approximately 5 million rows: + +```bash +docker exec postgres pgbench -i -s 50 -U postgres benchmark +``` + +#### Run stress tests + +Key parameters: + +- `-c`: Number of simulated clients +- `-j`: Number of threads +- `-T`: Duration in seconds + +Test with direct PostgreSQL connection: + +```bash +docker exec postgres pgbench -h localhost -U postgres -c 50 -j 4 -T 60 benchmark +``` + +Test through PgBouncer: + +```bash +docker exec postgres pgbench -h pgbouncer -p 6432 -U postgres -c 50 -j 4 -T 60 benchmark +``` + +### Understanding benchmark results + +Does PgBouncer actually make a difference? Run the benchmarks yourself to find out. Your results will vary based on your hardware, Docker configuration, network setup, and system load. + +#### What to expect + +When you run these benchmarks, you'll observe patterns rather than specific numbers. Think of it like comparing two different routes to work: the "faster" route depends on traffic conditions, time of day, and your vehicle. + +#### Key observations + +When comparing direct connections versus PgBouncer, you'll typically notice: + +##### 1. Connection overhead differs significantly + +Direct connections require PostgreSQL to spawn a new process for each client. PgBouncer reuses existing connections. Watch the "initial connection time" metric in your results—PgBouncer often shows dramatically faster connection setup. + +##### 2. Behavior under pressure reveals the real difference + +Try increasing the client count (`-c` parameter) gradually: 50, 100, 150, 200. At some point, direct connections will fail with "too many clients already" while PgBouncer continues handling requests. This is PgBouncer's primary value: **it prevents connection exhaustion**. + +##### 3. Throughput varies by environment + +On some systems, direct connections show higher transactions per second (TPS) at low concurrency. On others, PgBouncer wins even with few clients. The difference depends on: +- CPU and memory available +- Docker networking overhead +- Disk I/O speed +- Whether connections are being rapidly opened and closed + diff --git a/content/guides/postgresql/_index.md b/content/guides/postgresql/_index.md deleted file mode 100644 index 36d32a728371..000000000000 --- a/content/guides/postgresql/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: PostgreSQL specific guide -linkTitle: PostgreSQL -description: Containerize PostgreSQL databases using Docker -keywords: Docker, getting started, postgresql, language -summary: | - This guide explains how to containerize PostgreSQL databases using - Docker. -toc_min: 1 -toc_max: 2 -tags: [databases] -params: - time: 20 minutes ---- - diff --git a/content/guides/postgresql/advanced-configuration-and-initialization.md b/content/guides/postgresql/advanced-configuration-and-initialization.md deleted file mode 100644 index bd14d04a2ab7..000000000000 --- a/content/guides/postgresql/advanced-configuration-and-initialization.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Advanced Configuration and Initialization -weight: 20 -description: Configure PostgreSQL initialization scripts, tune performance parameters, and set timezone and locale settings for containerized deployments. -keywords: - - PostgreSQL Docker - - Docker Compose PostgreSQL - - container database - - PostgreSQL performance tuning ---- - -With persistent storage configured in the previous section, you're ready to customize PostgreSQL for real-world use. This guide covers advanced configuration techniques for running PostgreSQL in Docker containers, including automated database initialization, performance tuning, and timezone configuration. - -## Overview - -While PostgreSQL containers can be started quickly with default settings, production environments require customized configurations. This guide explains how to: - -- Automate database, schema, and user creation during container startup -- Tune PostgreSQL performance parameters for containerized workloads -- Configure timezone and locale settings - -## Initialization scripts - -The official PostgreSQL Docker image supports running initialization scripts automatically when the container starts for the first time. Any files placed in the `/docker-entrypoint-initdb.d/` directory are executed in alphabetical order. - -### How initialization works - -When the container starts, it checks whether the PostgreSQL data directory is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL. - -### Supported file formats - -| Format | Description | -|--------|-------------| -| `.sql` | SQL commands executed directly | -| `.sql.gz` | Gzip-compressed SQL files | -| `.sh` | Shell scripts executed with bash | - -> [!IMPORTANT] -> -> Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases. - -## Mounting initialization scripts - -Use Docker Compose to mount initialization scripts into the container. First, create a project directory: - -```console -$ mkdir -p postgres-project/init-db -$ cd postgres-project -``` - -Create a `compose.yaml` file: - -```yaml -services: - db: - image: postgres:18 - volumes: - - ./init-db:/docker-entrypoint-initdb.d - - postgres_data:/var/lib/postgresql - environment: - POSTGRES_PASSWORD: mysecretpassword - -volumes: - postgres_data: -``` - -All scripts in the `./init-db` directory execute when the container starts for the first time. This is great for bootstrapping databases. - -## Initialization script example - -Create a file named `init.sql` in your `init-db` directory: - -```sql -CREATE TABLE users ( - id SERIAL PRIMARY KEY, - email VARCHAR(255) UNIQUE NOT NULL, - name VARCHAR(100) NOT NULL, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); -``` - -This script runs automatically when the container starts for the first time, creating your initial database schema. - -> [!NOTE] -> -> Ensure initialization scripts have proper read permissions. If you encounter "Permission denied" errors, run `chmod 644 init-db/*.sql` to make the files readable by the container. - -## Performance tuning - -Default PostgreSQL settings are conservative to work on systems with limited resources. For production workloads, you should tune these parameters based on your container's allocated resources. - -### Method 1: Custom configuration file - -For complete control, mount a custom `postgresql.conf` file. First, extract the default configuration: - -```console -$ docker run -i --rm postgres:18 cat /usr/share/postgresql/postgresql.conf.sample > my-postgres.conf -``` - -Edit `my-postgres.conf` with your desired settings, then mount it in your Compose file: - -```yaml -services: - db: - image: postgres:18 - volumes: - - ./my-postgres.conf:/etc/postgresql/postgresql.conf - - ./init-db:/docker-entrypoint-initdb.d - - postgres_data:/var/lib/postgresql - command: postgres -c config_file=/etc/postgresql/postgresql.conf - environment: - POSTGRES_PASSWORD: mysecretpassword - -volumes: - postgres_data: -``` - -## Key configuration parameters - -The following tables list important `postgresql.conf` parameters for containerized PostgreSQL deployments. - -### Connection settings - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `listen_addresses` | IP addresses to listen on | `localhost` | -| `port` | TCP port number | `5432` | -| `max_connections` | Maximum concurrent connections | `100` | - -### Memory settings - -| Parameter | Description | Recommended starting value | -|-----------|-------------|---------------------------| -| `shared_buffers` | Shared memory for caching | 25% of container memory | -| `work_mem` | Memory per query operation | 4MB - 64MB | -| `maintenance_work_mem` | Memory for VACUUM, CREATE INDEX | 64MB - 256MB | -| `effective_cache_size` | Planner's cache size estimate | 50-75% of container memory | - -#### Docker memory limits - -When tuning memory parameters, set explicit memory limits on your container using `deploy.resources.limits.memory` in Compose or `--memory` with `docker run`. Without limits, PostgreSQL sees the host's total RAM and may allocate more than intended. For example, if your container should use 4GB maximum, set `shared_buffers` to approximately 1GB (25%). - -### I/O settings - -| Parameter | Description | Recommended starting value | -|-----------|-------------|---------------------------| -| `effective_io_concurrency` | Concurrent disk I/O operations | `200` for SSDs, `2` for HDDs | - -### Timeout settings - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `statement_timeout` | Max time for any statement | `0` (disabled) | -| `lock_timeout` | Max time to wait for a lock | `0` (disabled) | -| `deadlock_timeout` | Time before checking for deadlock | `1s` | -| `transaction_timeout` | Max time for a transaction | `0` (disabled) | - -> [!NOTE] -> -> Setting `shared_buffers` too high in a container can exceed kernel shared memory limits. Use no more than 25-30% of the container's memory limit. - -## Timezone and locale configuration - -Proper localization ensures timestamps and sorting behave correctly for your application's users. - -```yaml -services: - db: - image: postgres:18 - volumes: - - postgres_data:/var/lib/postgresql - - /etc/localtime:/etc/localtime:ro - - /etc/timezone:/etc/timezone:ro - environment: - POSTGRES_PASSWORD: mysecretpassword - TZ: America/New_York - -volumes: - postgres_data: -``` - -Alternatively, set the timezone using a PostgreSQL command-line parameter: - -```yaml -services: - db: - image: postgres:18 - command: ["postgres", "-c", "timezone=America/New_York"] - environment: - POSTGRES_PASSWORD: mysecretpassword -``` - -### Setting the locale - -Specify locale settings during database initialization using the `POSTGRES_INITDB_ARGS` environment variable: - -```yaml -services: - db: - image: postgres:18 - volumes: - - postgres_data:/var/lib/postgresql - environment: - POSTGRES_PASSWORD: mysecretpassword - POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8" - -volumes: - postgres_data: -``` - -This affects collation (sorting) and character processing behavior. Changing this variable after database creation has no effect—it only applies during the first run when the data directory is initialized. - -## Connecting to the database - -You can interact with PostgreSQL running in a container even without `psql` installed on your host machine. - -### Interactive shell - -Open a `psql` session inside the container: - -```console -$ docker exec -it postgres-container psql -U postgres -``` - -Connect to a specific database: - -```console -$ docker exec -it postgres-container psql -U postgres -d mydb -``` \ No newline at end of file diff --git a/content/guides/postgresql/companions-for-postgresql.md b/content/guides/postgresql/companions-for-postgresql.md deleted file mode 100644 index a9db5000ec36..000000000000 --- a/content/guides/postgresql/companions-for-postgresql.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Companions for PostgreSQL -linkTitle: Companions for PostgreSQL -description: This module explains how to customize PostgreSQL for real-world use in Docker, covering automated database initialization, performance tuning, and timezone configuration once persistent storage is in place. -keywords: - - PostgreSQL Docker - - Docker Compose PostgreSQL - - container database -weight: 40 ---- - - -## PostgreSQL ecosystem companions: pgAdmin, PgBouncer, and performance testing - -Running a standalone PostgreSQL container is often just the beginning. What happens when thousands of connections arrive, or when you need a visual interface to manage your database? - -This is where **companion tools** come into play. These applications extend PostgreSQL with capabilities the core database engine doesn't provide natively: visual administration, connection pooling, and performance benchmarking. This guide covers how to deploy pgAdmin 4, PgBouncer, Pgpool-II, and `pgbench` in Docker, when to use each tool, and real-world benchmark results demonstrating their performance impact. - -## pgAdmin 4: Visual management platform - -pgAdmin 4 is the industry-standard open source management tool for PostgreSQL. When deployed in Docker, it typically runs in **Server Mode**, providing a multi-user web interface to manage one or more database instances. - -While you can accomplish everything from the command line using `psql`, a visual interface significantly simplifies writing complex queries, visualizing table structures, and exploring database objects. - -### Key considerations - -When running pgAdmin in Docker, keep these points in mind: - -- **Image**: Use the official `dpage/pgadmin4` image -- **Networking**: In a Docker Compose environment, pgAdmin connects to the database using the internal service name (for example, `db:5432`) rather than `localhost` - -### Docker Compose configuration - -To quickly deploy pgAdmin: - -```yaml -pgadmin: - image: dpage/pgadmin4:8.14 - environment: - PGADMIN_DEFAULT_EMAIL: admin@example.com - PGADMIN_DEFAULT_PASSWORD: secure_password - volumes: - - pgadmin_data:/var/lib/pgadmin - ports: - - "8080:80" -``` - -With this configuration, access the pgAdmin interface at `http://localhost:8080`. Use the email and password specified in the environment variables for initial sign in. - -> [!IMPORTANT] -> -> In production environments, pass `PGADMIN_DEFAULT_PASSWORD` as an external environment variable or use Docker secrets. Storing passwords in plain text within `docker-compose.yml` poses a security risk. - -Now that you have visual database management in place, the next challenge in production environments is handling connection load. The following section explains how to manage high-volume database traffic. - -## PgBouncer: Lightweight connection pooling - -PostgreSQL creates a new process for every client connection, which consumes significant RAM. What happens when you have 1,000 concurrent users? PgBouncer solves exactly this problem. - -PgBouncer is a lightweight proxy that pools connections, allowing thousands of applications to share a small number of actual database backends. Think of it as a traffic controller: everyone wants to pass through simultaneously, but the controller regulates the flow to prevent congestion. - -### Pooling modes - -PgBouncer offers three distinct pooling modes: - -| Mode | Description | Use case | -|------|-------------|----------| -| **Session** | Connection assigned for entire session duration | Long-lived connections, session variables | -| **Transaction** | Connection returned after each transaction ends | Web applications, microservices (most common) | -| **Statement** | Connection returned after every SQL statement | Simple queries, no multi-statement transactions | - -### When to use PgBouncer - -PgBouncer becomes essential when you encounter: - -- "too many connections" errors -- High memory consumption due to connection overhead -- Many short-lived connections (web applications, serverless functions) -- Need to serve thousands of clients with limited database connections - -### Complete Docker Compose setup - -To run PostgreSQL and PgBouncer together, you need three files: `docker-compose.yml`, `pgbouncer.ini`, and `userlist.txt`. - -First, create the PgBouncer configuration file (`pgbouncer.ini`): - -```bash -[databases] -benchmark = host=postgres port=5432 dbname=benchmark user=postgres - -[pgbouncer] -listen_addr = 0.0.0.0 -listen_port = 6432 -auth_type = trust -auth_file = /etc/pgbouncer/userlist.txt -admin_users = postgres -pool_mode = transaction -max_client_conn = 1000 -default_pool_size = 50 -min_pool_size = 10 -reserve_pool_size = 10 -max_db_connections = 100 -``` - -Next, create the user authentication file (`userlist.txt`): - -```bash -"postgres" "postgres" -``` - -Finally, create the Docker Compose file (`docker-compose.yml`): - -```yaml -services: - postgres: - image: postgres:18 - container_name: postgres - environment: - POSTGRES_USER: postgres - POSTGRES_PASSWORD: postgres - POSTGRES_DB: benchmark - POSTGRES_HOST_AUTH_METHOD: trust - volumes: - - postgres_data:/var/lib/postgresql - ports: - - "5432:5432" - networks: - - pgnet - healthcheck: - test: ["CMD-SHELL", "pg_isready -U postgres"] - interval: 5s - timeout: 5s - retries: 5 - - pgbouncer: - image: percona/percona-pgbouncer:1.25.0 - container_name: pgbouncer - volumes: - - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini - - ./userlist.txt:/etc/pgbouncer/userlist.txt - ports: - - "6432:6432" - networks: - - pgnet - depends_on: - postgres: - condition: service_healthy - -volumes: - postgres_data: - -networks: - pgnet: - driver: bridge -``` - -Key configuration notes: - -- `PgBouncer` listens on port **6432**, avoiding confusion with the direct PostgreSQL connection on port 5432 -- The `depends_on` directive with `service_healthy` condition ensures PgBouncer starts only after PostgreSQL is ready -- `pool_mode = transaction` is the optimal choice for most web applications -- The [Percona PgBouncer image](https://hub.docker.com/r/percona/percona-pgbouncer) requires mounted configuration files (without the `:ro` flag, as the entrypoint script needs to modify them) -- This example uses `trust` authentication for simplicity. In production, configure proper SCRAM-SHA-256 authentication - -> [!NOTE] -> -> The `Percona PgBouncer` entrypoint script processes the configuration files on startup. Mount them without the read-only flag to avoid permission errors. - - - - -## `pgbench`: Performance benchmarking - -`pgbench` is a benchmarking utility included with the official PostgreSQL image. It allows you to simulate heavy workloads and verify how your Docker configuration performs under pressure. - -### Initialize benchmark tables - -First, create the test tables. The `-s` (scale) parameter determines data size—scale factor 50 creates approximately 5 million rows: - -```bash -docker exec postgres pgbench -i -s 50 -U postgres benchmark -``` - -### Run stress tests - -Key parameters: - -- `-c`: Number of simulated clients -- `-j`: Number of threads -- `-T`: Duration in seconds - -Test with direct PostgreSQL connection: - -```bash -docker exec postgres pgbench -h localhost -U postgres -c 50 -j 4 -T 60 benchmark -``` - -Test through PgBouncer: - -```bash -docker exec postgres pgbench -h pgbouncer -p 6432 -U postgres -c 50 -j 4 -T 60 benchmark -``` - -## Understanding benchmark results - -Does PgBouncer actually make a difference? Run the benchmarks yourself to find out. Your results will vary based on your hardware, Docker configuration, network setup, and system load. - -### What to expect - -When you run these benchmarks, you'll observe patterns rather than specific numbers. Think of it like comparing two different routes to work: the "faster" route depends on traffic conditions, time of day, and your vehicle. - -### Key observations - -When comparing direct connections versus PgBouncer, you'll typically notice: - -#### 1. Connection overhead differs significantly - -Direct connections require PostgreSQL to spawn a new process for each client. PgBouncer reuses existing connections. Watch the "initial connection time" metric in your results—PgBouncer often shows dramatically faster connection setup. - -#### 2. Behavior under pressure reveals the real difference - -Try increasing the client count (`-c` parameter) gradually: 50, 100, 150, 200. At some point, direct connections will fail with "too many clients already" while PgBouncer continues handling requests. This is PgBouncer's primary value: **it prevents connection exhaustion**. - -#### 3. Throughput varies by environment - -On some systems, direct connections show higher transactions per second (TPS) at low concurrency. On others, PgBouncer wins even with few clients. The difference depends on: -- CPU and memory available -- Docker networking overhead -- Disk I/O speed -- Whether connections are being rapidly opened and closed - diff --git a/content/guides/postgresql/immediate-setup-and-data-persistence.md b/content/guides/postgresql/immediate-setup-and-data-persistence.md deleted file mode 100644 index 75ec251c65d5..000000000000 --- a/content/guides/postgresql/immediate-setup-and-data-persistence.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Immediate setup & data persistence -description: Get PostgreSQL running in Docker in under five minutes. Learn how to configure named volumes and bind mounts to persist your database across container restarts. -keywords: - - PostgreSQL Docker - - Docker Compose PostgreSQL - - container database -weight: 10 ---- - -This guide gets you from zero to a running PostgreSQL container in under five minutes, then explains how to keep your data safe across container restarts and removals. - -## Overview - -Running PostgreSQL in Docker requires understanding one critical concept: containers are ephemeral, but your data shouldn't be. This guide covers: - -- Starting PostgreSQL with a single command -- Understanding why containers lose data by default -- Configuring volumes for persistent storage -- Translating your setup to Docker Compose - -## Quick start (minimal viable container) - -> [!NOTE] -> -> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in. - -Run PostgreSQL immediately with this single command: - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. - -```console -docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -d dhi.io/postgres:18 -``` - -{{< /tab >}} - -{{< tab name="Using DOIs" >}} - -```console -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -d postgres:18 -``` - -{{< /tab >}} -{{< /tabs >}} - -### Understanding the flags - -| Flag | Purpose | -|------|---------| -| `--rm` | Automatically removes the container when it stops | -| `--name postgres-dev` | Assigns a memorable name instead of a random string | -| `-e POSTGRES_PASSWORD=...` | Sets the superuser password (required) | -| `-p 5432:5432` | Maps host port 5432 to container port 5432 | -| `-d` | Runs the container in the background (detached mode) | - -Verify the container is running: - -```console -$ docker ps --filter name=postgres-dev -CONTAINER ID IMAGE COMMAND STATUS PORTS NAMES -a1b2c3d4e5f6 postgres:18 "docker-entrypoint.s…" Up 2 seconds 0.0.0.0:5432->5432/tcp postgres-dev -``` - -Connect using `psql` from inside the container: - -```console -$ docker exec -it postgres-dev psql -U postgres -psql (18.0) -Type "help" for help. - -postgres=# -``` - -You now have a working PostgreSQL instance. But there's a problem—stop this container and your data disappears. - -## The data persistence problem - -Containers use an ephemeral filesystem. When a container is removed, everything inside it, including your database files, is deleted. - -Demonstrate this yourself: - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -```console -$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" -CREATE DATABASE - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb - testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | - -$ docker stop postgres-dev -postgres-dev - -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -d dhi.io/postgres:18 - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb -(no output - database is gone) -``` - -{{< /tab >}} - -{{< tab name="Using DOIs" >}} - -```console -$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" -CREATE DATABASE - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb - testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | - -$ docker stop postgres-dev -postgres-dev - -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -d postgres:18 - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb -(no output - database is gone) -``` - -{{< /tab >}} -{{< /tabs >}} - -Your `testdb` database vanished because the new container started with a fresh filesystem. This is expected behavior—and exactly why volumes exist. - -## Named volumes - -Named volumes are Docker-managed storage locations that persist independently of containers. Docker handles the filesystem location, permissions, and lifecycle. - -Create a container with a named volume: - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. - -```console -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - -d dhi.io/postgres:18 -``` - -{{< /tab >}} - -{{< tab name="Using DOIs" >}} - -```console -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - -d postgres:18 -``` - -{{< /tab >}} -{{< /tabs >}} - - -The `-v postgres_data:/var/lib/postgresql` flag mounts a named volume called `postgres_data` to PostgreSQL's data directory. If the volume doesn't exist, Docker creates it automatically. - -> [!NOTE] -> -> PostgreSQL 18+ stores data in a version-specific subdirectory under `/var/lib/postgresql`. Mounting at this level (rather than `/var/lib/postgresql/data`) allows for easier upgrades using `pg_upgrade --link`. - -### Verify persistence works - -To verify data persistence, repeat the previous test, but this time with the named volume attached in place. - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -```console -$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" -CREATE DATABASE - -$ docker stop postgres-dev -postgres-dev - -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - -d dhi.io/postgres:18 - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb - testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | -``` - -{{< /tab >}} - -{{< tab name="Using DOIs" >}} - -```console -$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;" -CREATE DATABASE - -$ docker stop postgres-dev -postgres-dev - -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - -d postgres:18 - -$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb - testdb | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | -``` - -{{< /tab >}} - -{{< /tabs >}} - -If you see `testdb` in the output, persistence works: The database survived because the volume preserved the data directory. - -### Managing volumes - -List all volumes: - -```console -$ docker volume ls --filter name=postgres_data -DRIVER VOLUME NAME -local postgres_data -``` - -Inspect a volume to see its details: - -```console -$ docker volume inspect postgres_data -[ - { - "CreatedAt": "2025-01-05T10:30:00Z", - "Driver": "local", - "Labels": null, - "Mountpoint": "/var/lib/docker/volumes/postgres_data/_data", - "Name": "postgres_data", - "Options": null, - "Scope": "local" - } -] -``` - -Remove an unused volume (warning: this deletes all data): - -```console -$ docker volume rm postgres_data -``` - -## Bind mounts (alternative) - -Bind mounts map a specific host directory to a container path. Unlike named volumes, you control exactly where data lives on the host filesystem. - -Create a directory on your host machine to store Postgres data. - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -```console -mkdir -p ~/postgres-data && sudo chown -R 999:999 ~/postgres-data -``` - -Run Postgres using a bind mount. - -```console -docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v ~/postgres-data:/var/lib/postgresql \ - -d dhi.io/postgres:18 -``` - -{{< /tab >}} - -{{< tab name="Using DOIs" >}} - -```console -$ mkdir -p ~/postgres-data -``` - -Run Postgres using a bind mount. - -```console -$ docker run --rm --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v ~/postgres-data:/var/lib/postgresql \ - -d postgres:18 -``` - -{{< /tab >}} -{{< /tabs >}} - -### When to use bind mounts - -Bind mounts are useful when you need direct filesystem access to the data directory for backup scripts that read files directly, when integrating with host-level monitoring tools, or when specific permission requirements exist. For most development and production scenarios, named volumes are simpler and less error-prone. - -### Common bind mount issues - -Permission errors are the most frequent problem with bind mounts. PostgreSQL runs as user `postgres` (UID 999) inside the container. If your host directory has restrictive permissions, the container fails to start. - -Check logs if the container exits immediately: - -```console -$ docker logs postgres-dev -``` - -## Docker Compose configuration - -Docker Compose captures your entire configuration in a file, making setups reproducible and easier to manage as complexity grows. - -Create a `compose.yaml` file: - -```yaml -services: - db: - image: postgres:18 - container_name: postgres-dev - environment: - POSTGRES_PASSWORD: mysecretpassword - ports: - - "5432:5432" - volumes: - - postgres_data:/var/lib/postgresql - -volumes: - postgres_data: -``` - -Start the database: - -```console -$ docker compose up -d -``` - -Stop and remove containers (volume persists): - -```console -$ docker compose down -``` - -Alternatively, you can stop, remove containers, and delete the volume: - -```console -$ docker compose down -v -``` - -This compose file becomes the foundation for adding initialization scripts, performance tuning, and companion services covered in subsequent guides. - -### Environment variables reference - -The official PostgreSQL image supports these environment variables: - -| Variable | Required | Description | -|----------|----------|-------------| -| `POSTGRES_PASSWORD` | Yes | Superuser password | -| `POSTGRES_USER` | No | Superuser name (default: `postgres`) | -| `POSTGRES_DB` | No | Default database name (default: value of `POSTGRES_USER`) | - -## Next steps - -With persistent storage configured, you're ready to customize PostgreSQL further. The next chapter of the guide covers: - -- Automated schema creation with initialization scripts -- Performance tuning for containerized workloads -- Timezone and locale configuration \ No newline at end of file diff --git a/content/guides/postgresql/networking-and-connectivity.md b/content/guides/postgresql/networking-and-connectivity.md deleted file mode 100644 index 8d62422e8fcc..000000000000 --- a/content/guides/postgresql/networking-and-connectivity.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: Networking and connectivity -description: This module shows how to connect to PostgreSQL in Docker in two common ways; from another container (internal network) and from your host machine (external access). -keywords: - - Networking PostgreSQL Docker -weight: 30 ---- - -This guide covers two common ways to connect to PostgreSQL running in Docker: - -- Container-to-container: Connect from your application container to PostgreSQL over a private Docker network. No ports need to be exposed to the host. -- Host-to-container: Connect from your laptop or development machine using `localhost` and a published port. - -Prerequisite: This guide assumes you have PostgreSQL running with persistent storage. If you don't, follow the [Immediate Setup & Data Persistence](/guides/postgresql/immediate-setup-and-data-persistence/) guide first. - -## Internal network access (container-to-container) - -When your application runs in another container, connecting to PostgreSQL through a user-defined bridge network is the recommended approach. This setup provides automatic DNS resolution, so your application can connect to PostgreSQL using the container name as the hostname, without needing to track IP addresses. - -> [!NOTE] -> Why not use the default bridge network? While containers on the default bridge network can communicate, they can only do so by IP address. Since container IP addresses change when containers restart, this would require updating your PostgreSQL connection strings each time. User-defined bridge networks solve this by providing automatic DNS resolution, ensuring your PostgreSQL connection strings remain stable even if containers restart and receive new IP addresses. - -Here's a quick comparison: - -> [!NOTE] -> -> The following examples show the difference in approach. To actually test this, follow the steps in this guide to set up containers on the appropriate networks first. - -With the default bridge network, you'd need to find the IP address first: -```bash -# Get the container's IP address (changes on restart) -docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' postgres-dev -# Output: 172.17.0.2 - -# Then connect using that IP address from another container -# (No --network flag needed - containers default to bridge network) -docker run --rm -it \ - -e PGPASSWORD=mysecretpassword \ - postgres:18 \ - psql -h 172.17.0.2 -U postgres -``` - -With a user-defined network, you simply use the container name: -```bash -# Container name works directly - no IP lookup needed -docker run --rm -it \ - --network my-app-net \ - -e PGPASSWORD=mysecretpassword \ - postgres:18 \ - psql -h postgres-dev -U postgres -``` - -### Step 1: Create a user-defined network - -```bash -docker network create my-app-net - -# Example Output -ab7f984be43a0ca15534a9ee568716ddbe869a5875077fad3ef3192e3af7d288 - -docker network ls -# Output -ab7f984be43a my-app-net bridge local - - -``` - -### Step 2: Run PostgreSQL on that network (no port publishing) - -Notice there is no `-p 5432:5432` here. This keeps PostgreSQL internal to Docker and not accessible from the host machine, which is more secure for production environments. - -```bash -docker run -d --name postgres-dev \ - --network my-app-net \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -v postgres_data:/var/lib/postgresql \ - postgres:18 - - # Output -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -6d351ed89efc postgres:18 "docker-entrypoint.s…" 9 seconds ago Up 8 seconds 5432/tcp postgres-dev - -``` - -### Step 3: Connect from another container using the Postgres container name - -You can test connectivity with a temporary `psql` client container: - -```bash -docker run --rm -it \ - --network my-app-net \ - -e PGPASSWORD=mysecretpassword \ - postgres:18 \ - psql -h postgres-dev -U postgres -``` - -Key point: `-h postgres-dev` works because Docker DNS resolves the container name on a user-defined network. The container name acts as the hostname. - -### Connection string examples - -When connecting from your application container, use these PostgreSQL connection strings: - -- PostgreSQL URI format: - This is the standard PostgreSQL connection URI format that combines all connection parameters into a single string, widely supported by PostgreSQL clients and libraries. - - ```bash - postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres - ``` - - This command demonstrates passing a PostgreSQL URI connection string as an environment variable to a container, which your application can then read to connect to the database. - - Example usage in a Docker run command: - ```bash - docker run --rm -it \ - --network my-app-net \ - -e DATABASE_URL="postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres" \ - alpine:latest \ - sh -c 'echo "DATABASE_URL is set to: $DATABASE_URL"' - ``` - - -- PostgreSQL connection parameters: - This format uses key-value pairs separated by spaces, which many PostgreSQL client libraries accept as an alternative to URI format. - ```bash - host=postgres-dev - port=5432 - user=postgres - password=mysecretpassword - dbname=postgres - ``` - - Example usage in application code (Python with psycopg2): - ```python - conn = psycopg2.connect( - host="postgres-dev", - port=5432, - user="postgres", - password="mysecretpassword", - dbname="postgres" - ) - ``` - -- Connecting to a specific database: - Replace the database name in the connection string to connect to a specific database instead of the default `postgres` database. - If you created a custom database (e.g., `testdb`), use: - ```bash - postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb - ``` - - Example with SSL disabled (common in Docker networks): - Add `?sslmode=disable` to the connection string when connecting within a private Docker network where SSL encryption isn't required. - ```bash - postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb?sslmode=disable - ``` - -> [!NOTE] -> -> The default port `5432` is used in these examples. If you're connecting to a different PostgreSQL instance or have changed the port, update the connection string accordingly. The container name (`postgres-dev`) is resolved by Docker DNS to the container's IP address on the network. - - -## Connecting from the host (external access) - -To connect to PostgreSQL from your host machine using tools like `psql`, `pgAdmin`, `DBeaver`, or database management scripts, you need to publish PostgreSQL's port (`5432`) to the host. This allows external tools to reach the PostgreSQL container. - -### Expose Postgres to localhost only (recommended for development) - -This binds to `127.0.0.1` so it's only reachable from your local machine, not from other devices on your network. This is the most secure option for development. - -```bash -docker run -d --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 127.0.0.1:5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - postgres:18 -``` - -Now connect from your host: - -- Host: `localhost` or `127.0.0.1` -- Port: `5432` - -If you have `psql` installed on your host: -```bash -psql -h localhost -p 5432 -U postgres -``` - -You'll be prompted for the password. Alternatively, you can use the `PGPASSWORD` environment variable: -```bash -PGPASSWORD=mysecretpassword psql -h localhost -p 5432 -U postgres -``` - -### Connecting with PostgreSQL GUI tools - -Popular PostgreSQL GUI tools can connect using these common connection details: Host: `localhost`, Port: `5432`, User: `postgres`, Database: `postgres` (or your database name). - -- pgAdmin: A web-based PostgreSQL administration and development platform -- DBeaver: A universal database tool that supports PostgreSQL and many other databases. Select PostgreSQL as the connection type -- TablePlus: A modern, native database management tool for macOS and Windows with a clean interface - -All tools will prompt for the password you set with `POSTGRES_PASSWORD`. - -### Expose Postgres to all network interfaces (use with caution) - -To allow connections from other devices on your network, use `-p 5432:5432` instead of `-p 127.0.0.1:5432:5432`. This binds PostgreSQL to all network interfaces on your host, making it accessible from any device that can reach your host, not just localhost. - -```bash -docker run -d --name postgres-dev \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -p 5432:5432 \ - -v postgres_data:/var/lib/postgresql \ - postgres:18 -``` - -> [!WARNING] -> -> Exposing PostgreSQL to all network interfaces (`0.0.0.0:5432`) makes it accessible from any device that can reach your host. Only use this in trusted network environments or behind a firewall. For production, consider using a reverse proxy or VPN instead. - -### PostgreSQL security considerations for external access - -When exposing PostgreSQL to external access, follow these PostgreSQL-specific security practices: - -- Avoid using the `postgres` superuser: The default `postgres` user has full database privileges. Create dedicated users with only the permissions your application needs. -- Use strong passwords: PostgreSQL passwords should be complex. Consider using environment variables or secrets management instead of `hardcoding` passwords. -- Limit network exposure: Binding to `127.0.0.1` (localhost only) is safer than exposing to all interfaces (`0.0.0.0`). -- Consider SSL/TLS: For production, configure PostgreSQL to require SSL connections. The [Advanced Configuration and Initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to configure PostgreSQL settings. -- Create application-specific users: Use initialization scripts to create users with limited privileges. For example, a read-only user for reporting or a user that can only access specific databases. - -The [Advanced configuration and initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to use initialization scripts to create users and roles automatically. - -## Using Docker Compose for networking - -Docker Compose automatically creates a network for your services, making networking configuration simpler. Here's an example that combines both internal and external access: - -```yaml -services: - db: - image: postgres:18 - container_name: postgres-dev - environment: - POSTGRES_PASSWORD: mysecretpassword - volumes: - - postgres_data:/var/lib/postgresql - ports: - - "127.0.0.1:5432:5432" # Expose to localhost only - networks: - - app-network - - app: - build: ./my-app - environment: - DATABASE_URL: postgresql://postgres:mysecretpassword@db:5432/mydb - networks: - - app-network - depends_on: - - db - -volumes: - postgres_data: - -networks: - app-network: - driver: bridge -``` - -In this PostgreSQL-focused setup: -- The `app` service connects to PostgreSQL using the service name (`db`) as the hostname in the connection string -- PostgreSQL is accessible from your host at `localhost:5432` for external tools -- Both services are isolated on a custom network, providing network-level security -- The `depends_on` directive ensures PostgreSQL starts before your application - -PostgreSQL connection details for the app service: -- Hostname: `db` (resolved by Docker DNS) -- Port: `5432` (PostgreSQL default port) -- Database: `mydb` (as specified in the connection string) -- User: `postgres` (or a custom user you've created) - -> [!NOTE] -> -> Docker Compose automatically creates a network for your project. Services can reach each other by service name without explicit network configuration, but defining a custom network gives you more control. For PostgreSQL, this means your application can always connect using the service name, regardless of container restarts or IP changes. - -## Troubleshooting - -This section covers common PostgreSQL connection issues and their solutions when working with Docker networking. - -### "Could not translate host name postgres-dev" - -- Both containers must be on the same Docker network (`my-app-net`). -- Verify the network exists: `docker network ls` -- Check which network a container is on: `docker inspect postgres-dev | grep NetworkMode` -- Ensure you're using a user-defined network, not the default bridge network - -### "Connection refused" or "could not connect to server" - -- PostgreSQL may still be initializing: PostgreSQL takes a few seconds to start and initialize the database cluster. Wait 5-10 seconds after container start and retry. -- Check if the PostgreSQL container is running: - - ```bash - docker ps --filter name=postgres-dev - ``` - -- Check PostgreSQL logs for initialization or connection errors: - - ```bash - docker logs postgres-dev - ``` - - Look for messages like "database system is ready to accept connections" to confirm PostgreSQL is fully started. - -- Verify the port mapping is correct: - - ```bash - docker port postgres-dev - ``` - - This should show `5432/tcp -> 127.0.0.1:5432` (or `0.0.0.0:5432` if bound to all interfaces). - -- Test PostgreSQL connectivity from inside the container: - - ```bash - docker exec -it postgres-dev psql -U postgres -c "SELECT version();" - ``` - - If this works but external connections fail, the issue is with port publishing, not PostgreSQL itself. - -### "Password authentication failed" or "FATAL: password authentication failed for user" - -- Confirm the password: Verify you're using the same password set in `POSTGRES_PASSWORD` when you started the container. -- Existing volume with old credentials: If you reused an existing volume, the password from the original initialization is still in effect. The `POSTGRES_PASSWORD` environment variable only sets the password during the first database initialization. To reset: - - Remove the volume: `docker volume rm postgres_data` - - Or connect with the old password - - Or change the password after connecting: `ALTER USER postgres WITH PASSWORD 'newpassword';` -- Try connecting with password prompt: `psql -h localhost -U postgres -W` (the `-W` flag forces a password prompt) -- Use PGPASSWORD environment variable: `PGPASSWORD=mysecretpassword psql -h localhost -U postgres` -- Check PostgreSQL authentication configuration: If you've customized `pg_hba.conf`, verify the authentication method allows password authentication - -### "Network not found" - -- Ensure the network exists before starting containers: `docker network create my-app-net` -- If using Docker Compose, the network is created automatically when you run `docker compose up` diff --git a/content/guides/pre-seeding.md b/content/guides/pre-seeding.md index d08fa8d9b93d..f3af5342e8e9 100644 --- a/content/guides/pre-seeding.md +++ b/content/guides/pre-seeding.md @@ -4,8 +4,8 @@ linktitle: Pre-seeding database description: &desc Pre-seeding database with schema and data at startup for development environment keywords: Pre-seeding, database, postgres, container-supported development summary: *desc -tags: [app-dev, databases] params: + tags: [databases] time: 20 minutes --- @@ -123,7 +123,7 @@ Assuming that you have an existing Postgres database instance up and running, fo sampledb=# \l List of databases Name | Owner | Encoding | Collate | Ctype | ICU Locale | Locale Provider | Access privileges - -----------+----------+----------+------------+------------+------------+-----------------+----------------------- + -----------+----------+----------+------------+------------+------------+-----------------+-------------------- postgres | postgres | UTF8 | en_US.utf8 | en_US.utf8 | | libc | sampledb | postgres | UTF8 | en_US.utf8 | en_US.utf8 | | libc | template0 | postgres | UTF8 | en_US.utf8 | en_US.utf8 | | libc | =c/postgres + @@ -138,7 +138,7 @@ Assuming that you have an existing Postgres database instance up and running, fo ```console sampledb=# SELECT * FROM users; id | name | email - ----+-------+------------------- + ----+-------+---------------- 1 | Alpha | alpha@example.com 2 | Beta | beta@example.com 3 | Gamma | gamma@example.com @@ -210,7 +210,7 @@ $ docker container stop postgres data_sql: ``` - It maps port `5432` on the host to the container's `5432`, let you access to the Postgres database from outside the container. It also define `data_sql` for persisting the database data, ensuring that data is not lost when the container is stopped. + It maps port `5432` on the host to the container's `5432`, letting you access the Postgres database from outside the container. It also defines `data_sql` for persisting the database data, ensuring that data is not lost when the container is stopped. It is important to note that the port mapping to the host is only necessary if you want to connect to the database from non-containerized programs. If you containerize the service that connects to the DB, you should connect to the database over a custom bridge network. @@ -231,7 +231,7 @@ $ docker container stop postgres ```sql sampledb=# SELECT * FROM users; id | name | email - ----+-------+------------------- + ----+-------+---------------- 1 | Alpha | alpha@example.com 2 | Beta | beta@example.com 3 | Gamma | gamma@example.com @@ -330,7 +330,7 @@ It is called at the end of the script to initiate the seeding process. The try.. ```console sampledb=# SELECT * FROM todos; id | task | completed - ----+----------------+----------- + ----+----------------+-------- 1 | Watch netflix | f 2 | Finish podcast | f 3 | Pick up kid | f diff --git a/content/guides/python.md b/content/guides/python.md new file mode 100644 index 000000000000..116d23ec6d02 --- /dev/null +++ b/content/guides/python.md @@ -0,0 +1,2262 @@ +--- +title: Python language-specific guide +linkTitle: Python +description: Containerize Python apps using Docker +keywords: Docker, getting started, Python, language +summary: | + This guide explains how to containerize Python applications using Docker. +aliases: + - /language/python/ + - /guides/language/python/ + - /language/python/build-images/ + - /language/python/run-containers/ + - /language/python/containerize/ + - /language/python/develop/ + - /language/python/configure-ci-cd/ + - /guides/language/python/configure-ci-cd/ + - /language/python/deploy/ + - /guides/python/configure-github-actions/ + - /guides/python/containerize/ + - /guides/python/deploy/ + - /guides/python/develop/ + - /guides/python/lint-format-typing/ + - /guides/python/secure-supply-chain/ +params: + tags: [languages] + time: 20 minutes +--- + +> **Acknowledgment** +> +> This guide is a community contribution. Docker would like to thank +> [Esteban Maya](https://www.linkedin.com/in/esteban-x64/) and [Igor Aleksandrov](https://www.linkedin.com/in/igor-aleksandrov/) for their contribution +> to this guide. + +The Python language-specific guide teaches you how to containerize a Python application using Docker. In this guide, you’ll learn how to: + +- Containerize and run a Python application +- Set up a local environment to develop a Python application using containers +- Lint, format, typing and best practices + +Start by containerizing an existing Python application. + +## Containerize a Python application + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). + +### Overview + +Containerizing your application means packaging it together with its +dependencies, configuration, and runtime into a single portable unit called a +container image. Running that image creates a container, an isolated process +that behaves the same on any machine, whether it's your laptop, a CI runner, or +a production server. + +In this section, you'll containerize a simple +[FastAPI](https://fastapi.tiangolo.com) web application. You'll write a +`Dockerfile` that describes how to build the image, add a `compose.yaml` file +that defines how Docker runs your container, and then build and start the +application with one command. + +You'll use [Docker Hardened Images](/dhi/) as the base. These are minimal, +secure Python images maintained by Docker. + +### Create the application + +The sample application is a minimal FastAPI service with a single endpoint +that returns a JSON greeting. Create the following files in a new +`python-docker-example` directory. To create all the files at once, switch to +the **Scaffold script** tab in the file browser and copy the shell command. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" status="new" >}} + +```python +# A minimal FastAPI application. +# The root endpoint (GET /) returns a JSON "Hello World" response. +# See https://fastapi.tiangolo.com/ for the framework reference. + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def root(): + return {"message": "Hello World"} +``` + +{{< /file >}} + +{{< file path="requirements.txt" status="new" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path=".gitignore" status="new" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +If you already have Python installed and want to verify the app works before +containerizing it, you can run it locally: + +```console +$ python3 -m venv .venv +$ source .venv/bin/activate +$ pip install -r requirements.txt +$ uvicorn app:app --reload +``` + +> [!NOTE] +> +> On Windows, activate the virtual environment with `.venv\Scripts\activate` +> instead of `source .venv/bin/activate`. + +If you don't have Python installed, skip ahead to the next section. The +remaining steps run the application in a container, with no local Python +required. + +### Create the Docker assets + +Sign in to the DHI registry so Docker can pull the Python base images during +the build. The available Python images are listed in the +[catalog](https://hub.docker.com/hardened-images/catalog/dhi/python). + +```console +$ docker login dhi.io +``` + +Add the following three files to your `python-docker-example` directory. The +`Dockerfile` describes how to build the image, `compose.yaml` defines how +Docker runs the container, and `.dockerignore` keeps unwanted files out of the +build context. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for +> your project. Ask Gordon to create a Dockerfile, Compose file, and +> `.dockerignore` tailored to your application. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" >}} + +```python +# A minimal FastAPI application. +# The root endpoint (GET /) returns a JSON "Hello World" response. +# See https://fastapi.tiangolo.com/ for the framework reference. + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def root(): + return {"message": "Hello World"} +``` + +{{< /file >}} + +{{< file path="requirements.txt" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path="Dockerfile" status="new" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Use the dev image to build and install dependencies. +FROM dhi.io/python:3.12-dev AS builder + +WORKDIR /app + +RUN python3 -m venv /venv +ENV PATH="/venv/bin:$PATH" + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. +# Leverage a bind mount to requirements.txt to avoid having to copy them into +# this layer. +RUN --mount=type=cache,target=/root/.cache/pip \ + --mount=type=bind,source=requirements.txt,target=requirements.txt \ + pip install -r requirements.txt + +# Use the minimal runtime image. It runs as nonroot by default. +FROM dhi.io/python:3.12 + +WORKDIR /app + +COPY --from=builder /venv /venv +ENV PATH="/venv/bin:$PATH" + +# Copy the source code into the container. +COPY . . + +# Expose the port that the application listens on. +EXPOSE 8000 + +# Run the application. +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="new" >}} + +```yaml +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + ports: + - 8000:8000 +``` + +{{< /file >}} + +{{< file path=".dockerignore" status="new" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.DS_Store +**/__pycache__ +**/.venv +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +To learn more about each file, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `python-docker-example` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You should see a simple FastAPI application. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `python-docker-example` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8000](http://localhost:8000). + +To see the OpenAPI docs you can go to [http://localhost:8000/docs](http://localhost:8000/docs). + +You should see a simple FastAPI application. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for Python development + +### Prerequisites + +Complete [Containerize a Python application](#containerize-a-python-application). + +### Overview + +Once your application runs in a container, the next step is making the +container loop part of your everyday development workflow. Code changes should +show up quickly, and services your app depends on, like databases, should run +right alongside it. + +In this section, you'll extend the project from the previous topic by adding a +PostgreSQL database service to your `compose.yaml`, persisting the database +data in a named volume, and enabling Compose Watch so that changes you save in +your editor are picked up by the running container without a manual rebuild. + +### Update the application + +You'll update your application to connect to a PostgreSQL database. Continue +working in your `python-docker-example` directory. + +Replace `app.py` and `requirements.txt`, and add a new `config.py` file with the +following contents. + +> [!NOTE] +> +> The application won't run yet after this step. It tries to connect to a +> PostgreSQL database that doesn't exist. The next two sections add the +> database service and the Docker configuration needed to run everything +> together. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" status="modified" >}} + +```python +# FastAPI application backed by a PostgreSQL database via SQLModel. +# The FastAPI lifespan handler creates database tables at startup. +# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). +# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ + +from collections.abc import AsyncGenerator, Sequence +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from sqlmodel import Field, Session, SQLModel, create_engine, select + +from config import settings + + +class Hero(SQLModel, table=True): + id: int | None = Field(default=None, primary_key=True) + name: str = Field(index=True) + secret_name: str + age: int | None = Field(default=None, index=True) + + +engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) + + +def create_db_and_tables() -> None: + SQLModel.metadata.create_all(engine) + + +@asynccontextmanager +async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: + create_db_and_tables() + yield + + +app = FastAPI(lifespan=lifespan) + + +@app.get("/") +def hello() -> str: + return "Hello, Docker!" + + +@app.post("/heroes/") +def create_hero(hero: Hero) -> Hero: + with Session(engine) as session: + session.add(hero) + session.commit() + session.refresh(hero) + return hero + + +@app.get("/heroes/") +def read_heroes() -> Sequence[Hero]: + with Session(engine) as session: + heroes = session.exec(select(Hero)).all() + return heroes +``` + +{{< /file >}} + +{{< file path="config.py" status="new" >}} + +```python +# Pydantic settings that read PostgreSQL connection details from the +# environment. Supports a password file (Docker secrets) via +# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. +# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ + +import os +from typing import Any + +from pydantic import ( + PostgresDsn, + computed_field, + field_validator, + model_validator, +) +from pydantic_core import MultiHostUrl +from pydantic_settings import BaseSettings + + +class Settings(BaseSettings): + POSTGRES_SERVER: str + POSTGRES_PORT: int = 5432 + POSTGRES_USER: str + POSTGRES_PASSWORD: str | None = None + POSTGRES_PASSWORD_FILE: str | None = None + POSTGRES_DB: str + + @model_validator(mode="before") + @classmethod + def check_postgres_password(cls, data: Any) -> Any: + """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" + if isinstance(data, dict): + password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore + password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore + if password_file is None and password is None: + raise ValueError( + "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." + ) + return data # type: ignore + + @field_validator("POSTGRES_PASSWORD_FILE", mode="before") + @classmethod + def read_password_from_file(cls, v: str | None) -> str | None: + if v is not None: + file_path = v + if os.path.exists(file_path): + with open(file_path) as file: + return file.read().strip() + raise ValueError(f"Password file {file_path} does not exist.") + return v + + @computed_field + @property + def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: + url = MultiHostUrl.build( + scheme="postgresql+psycopg", + username=self.POSTGRES_USER, + password=self.POSTGRES_PASSWORD + if self.POSTGRES_PASSWORD + else self.POSTGRES_PASSWORD_FILE, + host=self.POSTGRES_SERVER, + port=self.POSTGRES_PORT, + path=self.POSTGRES_DB, + ) + return PostgresDsn(url) + + +settings = Settings() # type: ignore +``` + +{{< /file >}} + +{{< file path="requirements.txt" status="modified" hl_lines="5-7" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +sqlmodel==0.0.24 +psycopg[binary]==3.2.9 +pydantic-settings==2.9.1 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path="Dockerfile" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Use the dev image to build and install dependencies. +FROM dhi.io/python:3.12-dev AS builder + +WORKDIR /app + +RUN python3 -m venv /venv +ENV PATH="/venv/bin:$PATH" + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. +# Leverage a bind mount to requirements.txt to avoid having to copy them into +# this layer. +RUN --mount=type=cache,target=/root/.cache/pip \ + --mount=type=bind,source=requirements.txt,target=requirements.txt \ + pip install -r requirements.txt + +# Use the minimal runtime image. It runs as nonroot by default. +FROM dhi.io/python:3.12 + +WORKDIR /app + +COPY --from=builder /venv /venv +ENV PATH="/venv/bin:$PATH" + +# Copy the source code into the container. +COPY . . + +# Expose the port that the application listens on. +EXPOSE 8000 + +# Run the application. +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" >}} + +```yaml +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker Compose reference guide at +# https://docs.docker.com/go/compose-spec-reference/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + ports: + - 8000:8000 +``` + +{{< /file >}} + +{{< file path=".dockerignore" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.DS_Store +**/__pycache__ +**/.venv +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +### Update Docker assets + +Replace `Dockerfile` and `compose.yaml` with the following. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" >}} + +```python +# FastAPI application backed by a PostgreSQL database via SQLModel. +# The FastAPI lifespan handler creates database tables at startup. +# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). +# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ + +from collections.abc import AsyncGenerator, Sequence +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from sqlmodel import Field, Session, SQLModel, create_engine, select + +from config import settings + + +class Hero(SQLModel, table=True): + id: int | None = Field(default=None, primary_key=True) + name: str = Field(index=True) + secret_name: str + age: int | None = Field(default=None, index=True) + + +engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) + + +def create_db_and_tables() -> None: + SQLModel.metadata.create_all(engine) + + +@asynccontextmanager +async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: + create_db_and_tables() + yield + + +app = FastAPI(lifespan=lifespan) + + +@app.get("/") +def hello() -> str: + return "Hello, Docker!" + + +@app.post("/heroes/") +def create_hero(hero: Hero) -> Hero: + with Session(engine) as session: + session.add(hero) + session.commit() + session.refresh(hero) + return hero + + +@app.get("/heroes/") +def read_heroes() -> Sequence[Hero]: + with Session(engine) as session: + heroes = session.exec(select(Hero)).all() + return heroes +``` + +{{< /file >}} + +{{< file path="config.py" >}} + +```python +# Pydantic settings that read PostgreSQL connection details from the +# environment. Supports a password file (Docker secrets) via +# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. +# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ + +import os +from typing import Any + +from pydantic import ( + PostgresDsn, + computed_field, + field_validator, + model_validator, +) +from pydantic_core import MultiHostUrl +from pydantic_settings import BaseSettings + + +class Settings(BaseSettings): + POSTGRES_SERVER: str + POSTGRES_PORT: int = 5432 + POSTGRES_USER: str + POSTGRES_PASSWORD: str | None = None + POSTGRES_PASSWORD_FILE: str | None = None + POSTGRES_DB: str + + @model_validator(mode="before") + @classmethod + def check_postgres_password(cls, data: Any) -> Any: + """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" + if isinstance(data, dict): + password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore + password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore + if password_file is None and password is None: + raise ValueError( + "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." + ) + return data # type: ignore + + @field_validator("POSTGRES_PASSWORD_FILE", mode="before") + @classmethod + def read_password_from_file(cls, v: str | None) -> str | None: + if v is not None: + file_path = v + if os.path.exists(file_path): + with open(file_path) as file: + return file.read().strip() + raise ValueError(f"Password file {file_path} does not exist.") + return v + + @computed_field + @property + def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: + url = MultiHostUrl.build( + scheme="postgresql+psycopg", + username=self.POSTGRES_USER, + password=self.POSTGRES_PASSWORD + if self.POSTGRES_PASSWORD + else self.POSTGRES_PASSWORD_FILE, + host=self.POSTGRES_SERVER, + port=self.POSTGRES_PORT, + path=self.POSTGRES_DB, + ) + return PostgresDsn(url) + + +settings = Settings() # type: ignore +``` + +{{< /file >}} + +{{< file path="requirements.txt" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +sqlmodel==0.0.24 +psycopg[binary]==3.2.9 +pydantic-settings==2.9.1 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path="Dockerfile" status="modified" hl_lines="11,27-34,37,45" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Use the dev image to build and install dependencies. +# The builder stage is also used directly in development (see compose.yaml). +FROM dhi.io/python:3.12-dev AS builder + +WORKDIR /app + +RUN python3 -m venv /venv +ENV PATH="/venv/bin:$PATH" + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. +# Leverage a bind mount to requirements.txt to avoid having to copy them +# into this layer. +RUN --mount=type=cache,target=/root/.cache/pip \ + --mount=type=bind,source=requirements.txt,target=requirements.txt \ + pip install -r requirements.txt + +# Copy the source code into the container. +COPY . . + +# Expose the port that the application listens on. +EXPOSE 8000 + +# Run the application. +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] + + +# Use the minimal runtime image for production. It runs as nonroot by default. +FROM dhi.io/python:3.12 + +WORKDIR /app + +COPY --from=builder /venv /venv +ENV PATH="/venv/bin:$PATH" + +COPY --from=builder /app . + +EXPOSE 8000 + +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="modified" hl_lines="8" >}} + +```yaml +services: + # Application service. The `target: builder` line builds the development + # image (includes a shell and tools); the production stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: builder + ports: + - 8000:8000 +``` + +{{< /file >}} + +{{< file path=".dockerignore" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.DS_Store +**/__pycache__ +**/.venv +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +#### About these changes + +The `Dockerfile` builder stage now includes `COPY . .` and a `CMD` +instruction, which makes it directly runnable. This lets Compose target the +builder stage during development without rebuilding the production stage. The +production stage at the bottom is unchanged and still produces a minimal, +nonroot runtime image for shipping. + +In `compose.yaml`, the new `target: builder` line tells Compose to build and +run the builder stage of the Dockerfile during development. Unlike the minimal +production image, the development image includes a shell and additional tools +that make debugging easier. If you need a shell in a running production +container, use [Docker Debug](/reference/cli/docker/debug/) instead. + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this +section, you'll update the `compose.yaml` file to define a database service +and a volume to persist data, and add a `db/password.txt` file that holds the +database password. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" >}} + +```python +# FastAPI application backed by a PostgreSQL database via SQLModel. +# The FastAPI lifespan handler creates database tables at startup. +# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). +# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ + +from collections.abc import AsyncGenerator, Sequence +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from sqlmodel import Field, Session, SQLModel, create_engine, select + +from config import settings + + +class Hero(SQLModel, table=True): + id: int | None = Field(default=None, primary_key=True) + name: str = Field(index=True) + secret_name: str + age: int | None = Field(default=None, index=True) + + +engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) + + +def create_db_and_tables() -> None: + SQLModel.metadata.create_all(engine) + + +@asynccontextmanager +async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: + create_db_and_tables() + yield + + +app = FastAPI(lifespan=lifespan) + + +@app.get("/") +def hello() -> str: + return "Hello, Docker!" + + +@app.post("/heroes/") +def create_hero(hero: Hero) -> Hero: + with Session(engine) as session: + session.add(hero) + session.commit() + session.refresh(hero) + return hero + + +@app.get("/heroes/") +def read_heroes() -> Sequence[Hero]: + with Session(engine) as session: + heroes = session.exec(select(Hero)).all() + return heroes +``` + +{{< /file >}} + +{{< file path="config.py" >}} + +```python +# Pydantic settings that read PostgreSQL connection details from the +# environment. Supports a password file (Docker secrets) via +# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. +# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ + +import os +from typing import Any + +from pydantic import ( + PostgresDsn, + computed_field, + field_validator, + model_validator, +) +from pydantic_core import MultiHostUrl +from pydantic_settings import BaseSettings + + +class Settings(BaseSettings): + POSTGRES_SERVER: str + POSTGRES_PORT: int = 5432 + POSTGRES_USER: str + POSTGRES_PASSWORD: str | None = None + POSTGRES_PASSWORD_FILE: str | None = None + POSTGRES_DB: str + + @model_validator(mode="before") + @classmethod + def check_postgres_password(cls, data: Any) -> Any: + """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" + if isinstance(data, dict): + password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore + password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore + if password_file is None and password is None: + raise ValueError( + "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." + ) + return data # type: ignore + + @field_validator("POSTGRES_PASSWORD_FILE", mode="before") + @classmethod + def read_password_from_file(cls, v: str | None) -> str | None: + if v is not None: + file_path = v + if os.path.exists(file_path): + with open(file_path) as file: + return file.read().strip() + raise ValueError(f"Password file {file_path} does not exist.") + return v + + @computed_field + @property + def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: + url = MultiHostUrl.build( + scheme="postgresql+psycopg", + username=self.POSTGRES_USER, + password=self.POSTGRES_PASSWORD + if self.POSTGRES_PASSWORD + else self.POSTGRES_PASSWORD_FILE, + host=self.POSTGRES_SERVER, + port=self.POSTGRES_PORT, + path=self.POSTGRES_DB, + ) + return PostgresDsn(url) + + +settings = Settings() # type: ignore +``` + +{{< /file >}} + +{{< file path="requirements.txt" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +sqlmodel==0.0.24 +psycopg[binary]==3.2.9 +pydantic-settings==2.9.1 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path="Dockerfile" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Use the dev image to build and install dependencies. +# The builder stage is also used directly in development (see compose.yaml). +FROM dhi.io/python:3.12-dev AS builder + +WORKDIR /app + +RUN python3 -m venv /venv +ENV PATH="/venv/bin:$PATH" + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. +# Leverage a bind mount to requirements.txt to avoid having to copy them +# into this layer. +RUN --mount=type=cache,target=/root/.cache/pip \ + --mount=type=bind,source=requirements.txt,target=requirements.txt \ + pip install -r requirements.txt + +# Copy the source code into the container. +COPY . . + +# Expose the port that the application listens on. +EXPOSE 8000 + +# Run the application. +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] + + +# Use the minimal runtime image for production. It runs as nonroot by default. +FROM dhi.io/python:3.12 + +WORKDIR /app + +COPY --from=builder /venv /venv +ENV PATH="/venv/bin:$PATH" + +COPY --from=builder /app . + +EXPOSE 8000 + +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="modified" hl_lines="11-46" >}} + +```yaml +services: + # Application service. The `target: builder` line builds the development + # image (includes a shell and tools); the production stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: builder + ports: + - 8000:8000 + environment: + - POSTGRES_SERVER=db + - POSTGRES_USER=postgres + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + # Database service. Reads the password from a Docker secret mounted at + # /run/secrets/db-password. Compose waits for the healthcheck to pass + # before starting the server, via the server's depends_on. + db: + image: dhi.io/postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +{{< /file >}} + +{{< file path="db/password.txt" status="new" >}} + +```text +mysecretpassword +``` + +{{< /file >}} + +{{< file path=".dockerignore" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.DS_Store +**/__pycache__ +**/.venv +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands: + +Create an object with a POST request: + +```console +$ curl -X 'POST' \ + 'http://localhost:8000/heroes/' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "id": 1, + "name": "my hero", + "secret_name": "austing", + "age": 12 +}' +``` + +You should receive the following response: + +```json +{ + "age": 12, + "id": 1, + "name": "my hero", + "secret_name": "austing" +} +``` + +Now make a GET request: + +```console +$ curl -X 'GET' \ + 'http://localhost:8000/heroes/' \ + -H 'accept: application/json' +``` + +You should receive the same response as above because it's the only object in the database. + +```json +{ + "age": 12, + "id": 1, + "name": "my hero", + "secret_name": "austing" +} +``` + +Press `ctrl+c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yaml` file in an IDE or text editor and add the highlighted +Compose Watch instructions. + +{{< files name="python-docker-example" >}} + +{{< file path="app.py" >}} + +```python +# FastAPI application backed by a PostgreSQL database via SQLModel. +# The FastAPI lifespan handler creates database tables at startup. +# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). +# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ + +from collections.abc import AsyncGenerator, Sequence +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from sqlmodel import Field, Session, SQLModel, create_engine, select + +from config import settings + + +class Hero(SQLModel, table=True): + id: int | None = Field(default=None, primary_key=True) + name: str = Field(index=True) + secret_name: str + age: int | None = Field(default=None, index=True) + + +engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) + + +def create_db_and_tables() -> None: + SQLModel.metadata.create_all(engine) + + +@asynccontextmanager +async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: + create_db_and_tables() + yield + + +app = FastAPI(lifespan=lifespan) + + +@app.get("/") +def hello() -> str: + return "Hello, Docker!" + + +@app.post("/heroes/") +def create_hero(hero: Hero) -> Hero: + with Session(engine) as session: + session.add(hero) + session.commit() + session.refresh(hero) + return hero + + +@app.get("/heroes/") +def read_heroes() -> Sequence[Hero]: + with Session(engine) as session: + heroes = session.exec(select(Hero)).all() + return heroes +``` + +{{< /file >}} + +{{< file path="config.py" >}} + +```python +# Pydantic settings that read PostgreSQL connection details from the +# environment. Supports a password file (Docker secrets) via +# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. +# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ + +import os +from typing import Any + +from pydantic import ( + PostgresDsn, + computed_field, + field_validator, + model_validator, +) +from pydantic_core import MultiHostUrl +from pydantic_settings import BaseSettings + + +class Settings(BaseSettings): + POSTGRES_SERVER: str + POSTGRES_PORT: int = 5432 + POSTGRES_USER: str + POSTGRES_PASSWORD: str | None = None + POSTGRES_PASSWORD_FILE: str | None = None + POSTGRES_DB: str + + @model_validator(mode="before") + @classmethod + def check_postgres_password(cls, data: Any) -> Any: + """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" + if isinstance(data, dict): + password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore + password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore + if password_file is None and password is None: + raise ValueError( + "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." + ) + return data # type: ignore + + @field_validator("POSTGRES_PASSWORD_FILE", mode="before") + @classmethod + def read_password_from_file(cls, v: str | None) -> str | None: + if v is not None: + file_path = v + if os.path.exists(file_path): + with open(file_path) as file: + return file.read().strip() + raise ValueError(f"Password file {file_path} does not exist.") + return v + + @computed_field + @property + def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: + url = MultiHostUrl.build( + scheme="postgresql+psycopg", + username=self.POSTGRES_USER, + password=self.POSTGRES_PASSWORD + if self.POSTGRES_PASSWORD + else self.POSTGRES_PASSWORD_FILE, + host=self.POSTGRES_SERVER, + port=self.POSTGRES_PORT, + path=self.POSTGRES_DB, + ) + return PostgresDsn(url) + + +settings = Settings() # type: ignore +``` + +{{< /file >}} + +{{< file path="requirements.txt" >}} + +```text +# Python package dependencies for the application, pinned for reproducible builds. +# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +fastapi==0.115.12 +sqlmodel==0.0.24 +psycopg[binary]==3.2.9 +pydantic-settings==2.9.1 +uvicorn==0.34.3 +``` + +{{< /file >}} + +{{< file path="Dockerfile" >}} + +```dockerfile +# syntax=docker/dockerfile:1 + +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Dockerfile reference guide at +# https://docs.docker.com/go/dockerfile-reference/ + +# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. +# For more information, see https://docs.docker.com/dhi/ + +# Use the dev image to build and install dependencies. +# The builder stage is also used directly in development (see compose.yaml). +FROM dhi.io/python:3.12-dev AS builder + +WORKDIR /app + +RUN python3 -m venv /venv +ENV PATH="/venv/bin:$PATH" + +# Download dependencies as a separate step to take advantage of Docker's caching. +# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. +# Leverage a bind mount to requirements.txt to avoid having to copy them +# into this layer. +RUN --mount=type=cache,target=/root/.cache/pip \ + --mount=type=bind,source=requirements.txt,target=requirements.txt \ + pip install -r requirements.txt + +# Copy the source code into the container. +COPY . . + +# Expose the port that the application listens on. +EXPOSE 8000 + +# Run the application. +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] + + +# Use the minimal runtime image for production. It runs as nonroot by default. +FROM dhi.io/python:3.12 + +WORKDIR /app + +COPY --from=builder /venv /venv +ENV PATH="/venv/bin:$PATH" + +COPY --from=builder /app . + +EXPOSE 8000 + +CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] +``` + +{{< /file >}} + +{{< file path="compose.yaml" status="modified" hl_lines="21-24" >}} + +```yaml +services: + # Application service. The `target: builder` line builds the development + # image (includes a shell and tools); the production stage of the + # Dockerfile is unused in development. + server: + build: + context: . + target: builder + ports: + - 8000:8000 + environment: + - POSTGRES_SERVER=db + - POSTGRES_USER=postgres + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + develop: + watch: + - action: rebuild + path: . + db: + image: dhi.io/postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +{{< /file >}} + +{{< file path="db/password.txt" >}} + +```text +mysecretpassword +``` + +{{< /file >}} + +{{< file path=".dockerignore" >}} + +```text +# Include any files or directories that you don't want to be copied to your +# container here (e.g., local build artifacts, temporary files, etc.). +# +# For more help, visit the .dockerignore file reference guide at +# https://docs.docker.com/go/build-context-dockerignore/ + +**/.DS_Store +**/__pycache__ +**/.venv +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose.y*ml +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md +``` + +{{< /file >}} + +{{< file path=".gitignore" >}} + +```text +# Files and directories that Git should ignore. This is the standard Python +# template covering bytecode, build artifacts, virtual environments, and IDE +# settings. See https://git-scm.com/docs/gitignore for syntax reference. + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Secrets +db/password.txt +``` + +{{< /file >}} + +{{< /files >}} + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +In a terminal, curl the application to get a response. + +```console +$ curl http://localhost:8000 +Hello, Docker! +``` + +Any changes to the application's source files on your local machine will now be immediately reflected in the running container. + +Open `python-docker-example/app.py` in an IDE or text editor and update the `Hello, Docker!` string by adding a few more exclamation marks. + +```diff +- return 'Hello, Docker!' ++ return 'Hello, Docker!!!' +``` + +Save the changes to `app.py` and then wait a few seconds for the application to rebuild. Curl the application again and verify that the updated text appears. + +```console +$ curl http://localhost:8000 +Hello, Docker!!! +``` + +Press `ctrl+c` in the terminal to stop your application. + +## Linting, formatting, and type checking for Python + +### Prerequisites + +Complete [Develop your app](#use-containers-for-python-development). This topic requires a local Python +installation because the tools and Git hooks introduced here run on your +host. If you don't want to install Python locally, skip this topic. You can +also run the same checks in CI. + +### Overview + +Linting, formatting, and type checking are automated ways to catch bugs, +enforce style, and spot type errors before code runs. Running them on every +commit, in CI, and in your editor catches problems early when they're cheap +to fix. + +In this section, you'll configure three tools for your Python application. +Ruff handles linting and formatting in a single fast pass. Pyright statically +checks your code for type errors. Pre-commit hooks run both of these +automatically before each Git commit so problems are caught locally before +they're committed. + +### Linting and formatting with Ruff + +Ruff is an extremely fast Python linter and formatter written in Rust. It replaces multiple tools like flake8, isort, and black with a single unified tool. + +Create a `pyproject.toml` file in your `python-docker-example` directory: + +{{< files name="python-docker-example" >}} + +{{< file path="pyproject.toml" status="new" >}} + +```toml +# Configuration for code-quality tools. +# - [tool.ruff]: linting and formatting (https://docs.astral.sh/ruff/) +# - [tool.pyright]: static type checking (https://microsoft.github.io/pyright/) + +[tool.ruff] +target-version = "py312" + +[tool.ruff.lint] +select = [ + "E", # pycodestyle errors + "W", # pycodestyle warnings + "F", # pyflakes + "I", # isort + "B", # flake8-bugbear + "C4", # flake8-comprehensions + "UP", # pyupgrade + "ARG001", # unused arguments in functions +] +ignore = [ + "E501", # line too long, handled by black + "B008", # do not perform function calls in argument defaults + "W191", # indentation contains tabs + "B904", # Allow raising exceptions without from e, for HTTPException +] +``` + +{{< /file >}} + +{{< /files >}} + +Install Ruff: + +```console +$ pip install ruff +``` + +If you're using a virtual environment, make sure it is activated so the `ruff` +command is available. + +Run these commands to check and format your code: + +```console +# Check for errors +$ ruff check . + +# Automatically fix fixable errors +$ ruff check --fix . + +# Format code +$ ruff format . +``` + +### Type checking with Pyright + +Pyright is a fast static type checker for Python that works well with modern Python features. + +Update `pyproject.toml` to add the Pyright configuration at the bottom. + +{{< files name="python-docker-example" >}} + +{{< file path="pyproject.toml" status="modified" hl_lines="25-29" >}} + +```toml +# Configuration for code-quality tools. +# - [tool.ruff]: linting and formatting (https://docs.astral.sh/ruff/) +# - [tool.pyright]: static type checking (https://microsoft.github.io/pyright/) + +[tool.ruff] +target-version = "py312" + +[tool.ruff.lint] +select = [ + "E", # pycodestyle errors + "W", # pycodestyle warnings + "F", # pyflakes + "I", # isort + "B", # flake8-bugbear + "C4", # flake8-comprehensions + "UP", # pyupgrade + "ARG001", # unused arguments in functions +] +ignore = [ + "E501", # line too long, handled by black + "B008", # do not perform function calls in argument defaults + "W191", # indentation contains tabs + "B904", # Allow raising exceptions without from e, for HTTPException +] + +[tool.pyright] +typeCheckingMode = "strict" +pythonVersion = "3.12" +exclude = [".venv"] +``` + +{{< /file >}} + +{{< /files >}} + +Install Pyright and run it: + +```console +$ pip install pyright +$ pyright +``` + +### Setting up pre-commit hooks + +Pre-commit hooks run checks automatically before each commit on your local +machine. Create a `.pre-commit-config.yaml` file in your `python-docker-example` +directory to set up Ruff hooks: + +{{< files name="python-docker-example" >}} + +{{< file path=".pre-commit-config.yaml" status="new" >}} + +```yaml +# Pre-commit hook configuration. Runs Ruff (lint + format) on every +# `git commit`. See https://pre-commit.com/ + +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.15.15 + hooks: + - id: ruff + args: [--fix] + - id: ruff-format +``` + +{{< /file >}} + +{{< /files >}} + +To install and use: + +```console +$ pip install pre-commit +$ pre-commit install +$ git commit -m "Test commit" # Automatically runs checks +``` + +### Summary + +In this section, you learned how to: + +- Configure and use Ruff for linting and formatting +- Set up Pyright for static type checking +- Automate checks with pre-commit hooks + +These tools help maintain code quality and catch errors early in development. + +Related information: + +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [Pyright documentation](https://microsoft.github.io/pyright/) +- [pre-commit framework](https://pre-commit.com/) + +### Next steps + +- Customize linting rules to match your team's style preferences +- Explore advanced type checking features diff --git a/content/guides/python/_index.md b/content/guides/python/_index.md deleted file mode 100644 index 7e4c1dbfa5ad..000000000000 --- a/content/guides/python/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Python language-specific guide -linkTitle: Python -description: Containerize Python apps using Docker -keywords: Docker, getting started, Python, language -summary: | - This guide explains how to containerize Python applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/python/ - - /guides/language/python/ -languages: [python] -tags: [dhi] -params: - time: 20 minutes ---- - -> **Acknowledgment** -> -> This guide is a community contribution. Docker would like to thank -> [Esteban Maya](https://www.linkedin.com/in/esteban-x64/) and [Igor Aleksandrov](https://www.linkedin.com/in/igor-aleksandrov/) for their contribution -> to this guide. - -The Python language-specific guide teaches you how to containerize a Python application using Docker. In this guide, you’ll learn how to: - -- Containerize and run a Python application -- Set up a local environment to develop a Python application using containers -- Lint, format, typing and best practices -- Configure a CI/CD pipeline for a containerized Python application using GitHub Actions -- Deploy your containerized Python application locally to Kubernetes to test and debug your deployment - -Start by containerizing an existing Python application. diff --git a/content/guides/python/configure-github-actions.md b/content/guides/python/configure-github-actions.md deleted file mode 100644 index e935147bec1a..000000000000 --- a/content/guides/python/configure-github-actions.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 40 -keywords: ci/cd, github actions, python, flask -description: Learn how to configure CI/CD using GitHub Actions for your Python application. -aliases: - - /language/python/configure-ci-cd/ - - /guides/language/python/configure-ci-cd/ - - /guides/python/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Python application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -If you didn't create a [GitHub repository](https://github.com/new) for your project yet, it is time to do it. After creating the repository, don't forget to [add a remote](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) and ensure you can commit and [push your code](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) to GitHub. - -1. In your project's GitHub repository, open **Settings**, and go to **Secrets and variables** > **Actions**. - -2. Under the **Variables** tab, create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -3. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -4. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -## Overview - -GitHub Actions is a CI/CD automation tool built into GitHub. A workflow is a -YAML file that tells GitHub which jobs to run when something happens in your -repository, like a push to a branch or a pull request opening. Workflows live -in the `.github/workflows/` directory of your repository. - -In this section, you'll add a workflow that runs your linting, formatting, and -type checks on every push to the main branch, then builds your Docker image -and pushes it to Docker Hub. - -## 1. Define the GitHub Actions workflow - -You can create a GitHub Actions workflow by creating a YAML file in the `.github/workflows/` directory of your repository. To do this use your favorite text editor or the GitHub web interface. The following steps show you how to create a workflow file using the GitHub web interface. - -If you prefer to use the GitHub web interface, follow these steps: - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub Actions workflow file in - your repository. By default, the file is created under `.github/workflows/main.yml`. Change the file name to `build.yml`. - -If you prefer to use your text editor, create a new file named `build.yml` in the `.github/workflows/` directory of your repository. - -Add the following content to the file: - -{{< files name="python-docker-example" >}} - -{{< file path=".github/workflows/build.yml" status="new" >}} -```yaml -# GitHub Actions workflow that runs on every push to main. -# - lint-test: runs pre-commit hooks (Ruff) and Pyright type checks. -# - build_and_push: signs in to Docker Hub and the DHI registry, then -# builds and pushes the image (with SBOM and provenance attestations). -name: Build and push Docker image - -on: - push: - branches: - - main - -jobs: - lint-test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@{{% param "checkout_action_version" %}} - - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: '3.12' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - pip install pre-commit pyright - - - name: Run pre-commit hooks - run: pre-commit run --all-files - - - name: Run pyright - run: pyright - - build_and_push: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@{{% param "checkout_action_version" %}} - - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Login to Docker Hardened Images - uses: docker/login-action@{{% param "login_action_version" %}} - with: - registry: dhi.io - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest -``` -{{< /file >}} - -{{< /files >}} - -Each GitHub Actions workflow includes one or several jobs. Each job consists of steps. Each step can either run a set of commands or use already [existing actions](https://github.com/marketplace?type=actions). The action above has three steps: - -1. [Login to Docker Hub](https://github.com/docker/login-action): Action logs in to Docker Hub using the Docker ID and Personal Access Token (PAT) you created earlier. - -2. [Set up Docker Buildx](https://github.com/docker/setup-buildx-action): Action sets up Docker [Buildx](https://github.com/docker/buildx), a CLI plugin that extends the capabilities of the Docker CLI. - -3. [Build and push](https://github.com/docker/build-push-action): Action builds and pushes the Docker image to Docker Hub. The `tags` parameter specifies the image name and tag. The `latest` tag is used in this example. - -## 2. Run the workflow - -Commit the changes and push them to the `main` branch. This workflow is runs every time you push changes to the `main` branch. You can find more information about workflow triggers [in the GitHub documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). - -Go to the **Actions** tab of you GitHub repository. It displays the workflow. Selecting the workflow shows you the breakdown of all the steps. - -When the workflow is complete, go to your [repositories on Docker Hub](https://hub.docker.com/repositories). If you see the new repository in that list, it means the GitHub Actions workflow successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your Python application that includes: - -- Running pre-commit hooks for linting and formatting -- Static type checking with Pyright -- Building and pushing Docker images - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [docker/login-action](https://github.com/docker/login-action) -- [docker/build-push-action](https://github.com/docker/build-push-action) -- [Create a Docker Hub access token](/manuals/security/access-tokens.md#create-an-access-token) - -## Next steps - -In the next section, you'll learn how to inspect and generate supply chain -attestations for your image. See [Secure your supply chain](secure-supply-chain.md). - diff --git a/content/guides/python/containerize.md b/content/guides/python/containerize.md deleted file mode 100644 index 193d191d4f0e..000000000000 --- a/content/guides/python/containerize.md +++ /dev/null @@ -1,439 +0,0 @@ ---- -title: Containerize a Python application -linkTitle: Containerize your app -weight: 10 -keywords: python, flask, containerize, initialize -description: Learn how to containerize a Python application. -aliases: - - /language/python/build-images/ - - /language/python/run-containers/ - - /language/python/containerize/ - - /guides/language/python/containerize/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). - -## Overview - -Containerizing your application means packaging it together with its -dependencies, configuration, and runtime into a single portable unit called a -container image. Running that image creates a container, an isolated process -that behaves the same on any machine, whether it's your laptop, a CI runner, or -a production server. - -In this section, you'll containerize a simple -[FastAPI](https://fastapi.tiangolo.com) web application. You'll write a -`Dockerfile` that describes how to build the image, add a `compose.yaml` file -that defines how Docker runs your container, and then build and start the -application with one command. - -You'll use [Docker Hardened Images](/dhi/) as the base. These are minimal, -secure Python images maintained by Docker. - -## Create the application - -The sample application is a minimal FastAPI service with a single endpoint -that returns a JSON greeting. Create the following files in a new -`python-docker-example` directory. To create all the files at once, switch to -the **Scaffold script** tab in the file browser and copy the shell command. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" status="new" >}} -```python -# A minimal FastAPI application. -# The root endpoint (GET /) returns a JSON "Hello World" response. -# See https://fastapi.tiangolo.com/ for the framework reference. - -from fastapi import FastAPI - -app = FastAPI() - - -@app.get("/") -async def root(): - return {"message": "Hello World"} -``` -{{< /file >}} - -{{< file path="requirements.txt" status="new" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path=".gitignore" status="new" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -If you already have Python installed and want to verify the app works before -containerizing it, you can run it locally: - -```console -$ python3 -m venv .venv -$ source .venv/bin/activate -$ pip install -r requirements.txt -$ uvicorn app:app --reload -``` - -> [!NOTE] -> -> On Windows, activate the virtual environment with `.venv\Scripts\activate` -> instead of `source .venv/bin/activate`. - -If you don't have Python installed, skip ahead to the next section. The -remaining steps run the application in a container, with no local Python -required. - -## Create the Docker assets - -Sign in to the DHI registry so Docker can pull the Python base images during -the build. The available Python images are listed in the -[catalog](https://hub.docker.com/hardened-images/catalog/dhi/python). - -```console -$ docker login dhi.io -``` - -Add the following three files to your `python-docker-example` directory. The -`Dockerfile` describes how to build the image, `compose.yaml` defines how -Docker runs the container, and `.dockerignore` keeps unwanted files out of the -build context. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for -> your project. Ask Gordon to create a Dockerfile, Compose file, and -> `.dockerignore` tailored to your application. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" >}} -```python -# A minimal FastAPI application. -# The root endpoint (GET /) returns a JSON "Hello World" response. -# See https://fastapi.tiangolo.com/ for the framework reference. - -from fastapi import FastAPI - -app = FastAPI() - - -@app.get("/") -async def root(): - return {"message": "Hello World"} -``` -{{< /file >}} - -{{< file path="requirements.txt" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path="Dockerfile" status="new" >}} -```dockerfile -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. -# For more information, see https://docs.docker.com/dhi/ - -# Use the dev image to build and install dependencies. -FROM dhi.io/python:3.12-dev AS builder - -WORKDIR /app - -RUN python3 -m venv /venv -ENV PATH="/venv/bin:$PATH" - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them into -# this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - pip install -r requirements.txt - -# Use the minimal runtime image. It runs as nonroot by default. -FROM dhi.io/python:3.12 - -WORKDIR /app - -COPY --from=builder /venv /venv -ENV PATH="/venv/bin:$PATH" - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] -``` -{{< /file >}} - -{{< file path="compose.yaml" status="new" >}} -```yaml -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - ports: - - 8000:8000 -``` -{{< /file >}} - -{{< file path=".dockerignore" status="new" >}} -```text -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` -{{< /file >}} - -{{< file path=".gitignore" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -To learn more about each file, see the following: - -- [Dockerfile](/reference/dockerfile.md) -- [.dockerignore](/reference/dockerfile.md#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `python-docker-example` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8000](http://localhost:8000). You should see a simple FastAPI application. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `python-docker-example` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8000](http://localhost:8000). - -To see the OpenAPI docs you can go to [http://localhost:8000/docs](http://localhost:8000/docs). - -You should see a simple FastAPI application. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run your Python -application using Docker. - -Related information: - -- [Docker Hardened Images](/dhi/) -- [Dockerfile reference](/reference/dockerfile.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) -- [Docker Compose overview](/manuals/compose/_index.md) - -## Next steps - -In the next section, you'll take a look at how to set up a local development environment using Docker containers. diff --git a/content/guides/python/deploy.md b/content/guides/python/deploy.md deleted file mode 100644 index a47ef1213127..000000000000 --- a/content/guides/python/deploy.md +++ /dev/null @@ -1,341 +0,0 @@ ---- -title: Test your Python deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, python -description: Learn how to develop locally using Kubernetes -aliases: - - /language/python/deploy/ - - /guides/language/python/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Use containers for Python development](develop.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -[Kubernetes](https://kubernetes.io/) is an open source platform that runs and -orchestrates container workloads across one or more machines. You describe -what you want to run, like which container images, how many replicas, and -which network ports to expose, in YAML manifest files. Kubernetes reads the -manifests and makes the cluster match that description. - -In this section, you'll use the Kubernetes environment built into Docker -Desktop to deploy your application locally. You'll write two manifest files, -one for the PostgreSQL database and one for the FastAPI application, apply -them with `kubectl`, and verify the deployment by hitting your application -from a terminal. - -## Registry authentication - -The Docker Hardened Images used in this guide are hosted on `dhi.io`. Docker -Desktop's Kubernetes shares credentials with Docker Desktop, so the `docker login dhi.io` -you completed earlier is all that's needed. No additional image pull secret is required. - -> [!NOTE] -> -> If you're deploying to a Kubernetes cluster outside of Docker Desktop, you'll -> need to create an image pull secret and reference it in your pod specs. See -> [Use a Docker Hardened Image](/dhi/how-to/use/#use-with-kubernetes) for instructions. - -## Create a Kubernetes YAML file - -Create the following two Kubernetes manifest files in your -`python-docker-example` directory. Before applying -`docker-python-kubernetes.yaml`, replace `DOCKER_USERNAME/REPO_NAME` with your -Docker username and the repository name that you created in [Configure CI/CD for -your Python application](./configure-github-actions.md). - -{{< files name="python-docker-example" >}} - -{{< file path="docker-postgres-kubernetes.yaml" status="new" >}} -```yaml -# Kubernetes manifests for the PostgreSQL database used by the FastAPI app. -# Contains a Deployment, Service, PersistentVolumeClaim, and Secret. - -# Deployment: runs one PostgreSQL pod. The image, port, env vars, and the -# persistent volume mount are all defined here. -apiVersion: apps/v1 -kind: Deployment -metadata: - name: postgres - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: postgres - template: - metadata: - labels: - app: postgres - spec: - containers: - - name: postgres - image: dhi.io/postgres:18 - ports: - - containerPort: 5432 - env: - - name: POSTGRES_DB - value: example - - name: POSTGRES_USER - value: postgres - - name: POSTGRES_PASSWORD - valueFrom: - secretKeyRef: - name: postgres-secret - key: POSTGRES_PASSWORD - volumeMounts: - - name: postgres-data - mountPath: /var/lib/postgresql - volumes: - - name: postgres-data - persistentVolumeClaim: - claimName: postgres-pvc ---- -# Service: exposes PostgreSQL inside the cluster on port 5432 so the -# application pod can reach it by the DNS name `postgres`. -apiVersion: v1 -kind: Service -metadata: - name: postgres - namespace: default -spec: - ports: - - port: 5432 - selector: - app: postgres ---- -# PersistentVolumeClaim: storage that survives pod restarts. -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: postgres-pvc - namespace: default -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi ---- -# Secret: holds the database password (base64-encoded). Referenced by both -# the postgres Deployment and the application Deployment. -apiVersion: v1 -kind: Secret -metadata: - name: postgres-secret - namespace: default -type: Opaque -data: - POSTGRES_PASSWORD: cG9zdGdyZXNfcGFzc3dvcmQ= # Base64 encoded password (e.g., 'postgres_password') -``` -{{< /file >}} - -{{< file path="docker-python-kubernetes.yaml" status="new" >}} -```yaml -# Kubernetes manifests for the FastAPI application. -# Contains a Deployment and a NodePort Service. - -# Deployment: runs the FastAPI app. Connection details to the postgres -# service are passed in via environment variables, and the database -# password comes from the shared postgres-secret. -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-python-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: fastapi - template: - metadata: - labels: - service: fastapi - spec: - containers: - - name: fastapi-service - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always - env: - - name: POSTGRES_PASSWORD - valueFrom: - secretKeyRef: - name: postgres-secret - key: POSTGRES_PASSWORD - - name: POSTGRES_USER - value: postgres - - name: POSTGRES_DB - value: example - - name: POSTGRES_SERVER - value: postgres - - name: POSTGRES_PORT - value: "5432" - ports: - - containerPort: 8000 ---- -# Service: exposes the FastAPI app on port 30001 of the cluster node so -# you can reach it from your host with `curl http://localhost:30001/`. -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - service: fastapi - ports: - - port: 8000 - targetPort: 8000 - nodePort: 30001 -``` -{{< /file >}} - -{{< /files >}} - -In these Kubernetes YAML files, there are various objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your Python application](configure-github-actions.md). -- A Service, which will define how the ports are mapped in the containers. -- A PersistentVolumeClaim, to define a storage that will be persistent through restarts for the database. -- A Secret, which stores the database password as a Kubernetes Secret resource. -- A NodePort service, which will route traffic from port 30001 on your host to - port 8000 inside the pods it routes to, so you can reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -> [!NOTE] -> -> The `NodePort` service is good for development and testing. For production, implement an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) instead. - -## Deploy and check your application - -1. In a terminal, navigate to `python-docker-example` and deploy your database to - Kubernetes. - - ```console - $ kubectl apply -f docker-postgres-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```console - deployment.apps/postgres created - service/postgres created - persistentvolumeclaim/postgres-pvc created - secret/postgres-secret created - ``` - - Now, deploy your Python application. - - ```console - $ kubectl apply -f docker-python-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```console - deployment.apps/docker-python-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```console - NAME READY UP-TO-DATE AVAILABLE AGE - docker-python-demo 1/1 1 1 48s - postgres 1/1 1 1 2m39s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```console - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.43.0.1 <none> 443/TCP 13h - postgres ClusterIP 10.43.209.25 <none> 5432/TCP 3m10s - service-entrypoint NodePort 10.43.67.120 <none> 8000:30001/TCP 79s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP and the internal `ClusterIP` `postgres` with the port `5432` open to accept connections from your Python app. - -3. In a terminal, curl the root endpoint to verify the application is running. - - ```console - $ curl http://localhost:30001/ - Hello, Docker! - ``` - -4. Exercise the database by creating a hero with a POST request: - - ```console - $ curl -X 'POST' \ - 'http://localhost:30001/heroes/' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{ - "id": 1, - "name": "my hero", - "secret_name": "austing", - "age": 12 - }' - ``` - - You should receive the following response: - - ```json - { - "age": 12, - "id": 1, - "name": "my hero", - "secret_name": "austing" - } - ``` - - Then read it back with a GET request: - - ```console - $ curl http://localhost:30001/heroes/ - ``` - - You should receive an array containing the hero you just created. This - confirms the application can read from and write to the PostgreSQL database - running in the cluster. - -5. Run the following commands to tear down your application. - - ```console - $ kubectl delete -f docker-python-kubernetes.yaml - $ kubectl delete -f docker-postgres-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Use a Docker Hardened Image with Kubernetes](/dhi/how-to/use/#use-with-kubernetes) diff --git a/content/guides/python/develop.md b/content/guides/python/develop.md deleted file mode 100644 index 7cbfc9f378a5..000000000000 --- a/content/guides/python/develop.md +++ /dev/null @@ -1,1560 +0,0 @@ ---- -title: Use containers for Python development -linkTitle: Develop your app -weight: 15 -keywords: python, local, development -description: Learn how to develop your Python application locally. -aliases: - - /language/python/develop/ - - /guides/language/python/develop/ ---- - -## Prerequisites - -Complete [Containerize a Python application](containerize.md). - -## Overview - -Once your application runs in a container, the next step is making the -container loop part of your everyday development workflow. Code changes should -show up quickly, and services your app depends on, like databases, should run -right alongside it. - -In this section, you'll extend the project from the previous topic by adding a -PostgreSQL database service to your `compose.yaml`, persisting the database -data in a named volume, and enabling Compose Watch so that changes you save in -your editor are picked up by the running container without a manual rebuild. - -## Update the application - -You'll update your application to connect to a PostgreSQL database. Continue -working in your `python-docker-example` directory. - -Replace `app.py` and `requirements.txt`, and add a new `config.py` file with the -following contents. - -> [!NOTE] -> -> The application won't run yet after this step. It tries to connect to a -> PostgreSQL database that doesn't exist. The next two sections add the -> database service and the Docker configuration needed to run everything -> together. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" status="modified" >}} -```python -# FastAPI application backed by a PostgreSQL database via SQLModel. -# The FastAPI lifespan handler creates database tables at startup. -# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). -# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ - -from collections.abc import AsyncGenerator, Sequence -from contextlib import asynccontextmanager - -from fastapi import FastAPI -from sqlmodel import Field, Session, SQLModel, create_engine, select - -from config import settings - - -class Hero(SQLModel, table=True): - id: int | None = Field(default=None, primary_key=True) - name: str = Field(index=True) - secret_name: str - age: int | None = Field(default=None, index=True) - - -engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) - - -def create_db_and_tables() -> None: - SQLModel.metadata.create_all(engine) - - -@asynccontextmanager -async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: - create_db_and_tables() - yield - - -app = FastAPI(lifespan=lifespan) - - -@app.get("/") -def hello() -> str: - return "Hello, Docker!" - - -@app.post("/heroes/") -def create_hero(hero: Hero) -> Hero: - with Session(engine) as session: - session.add(hero) - session.commit() - session.refresh(hero) - return hero - - -@app.get("/heroes/") -def read_heroes() -> Sequence[Hero]: - with Session(engine) as session: - heroes = session.exec(select(Hero)).all() - return heroes -``` -{{< /file >}} - -{{< file path="config.py" status="new" >}} -```python -# Pydantic settings that read PostgreSQL connection details from the -# environment. Supports a password file (Docker secrets) via -# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. -# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ - -import os -from typing import Any - -from pydantic import ( - PostgresDsn, - computed_field, - field_validator, - model_validator, -) -from pydantic_core import MultiHostUrl -from pydantic_settings import BaseSettings - - -class Settings(BaseSettings): - POSTGRES_SERVER: str - POSTGRES_PORT: int = 5432 - POSTGRES_USER: str - POSTGRES_PASSWORD: str | None = None - POSTGRES_PASSWORD_FILE: str | None = None - POSTGRES_DB: str - - @model_validator(mode="before") - @classmethod - def check_postgres_password(cls, data: Any) -> Any: - """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" - if isinstance(data, dict): - password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore - password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore - if password_file is None and password is None: - raise ValueError( - "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." - ) - return data # type: ignore - - @field_validator("POSTGRES_PASSWORD_FILE", mode="before") - @classmethod - def read_password_from_file(cls, v: str | None) -> str | None: - if v is not None: - file_path = v - if os.path.exists(file_path): - with open(file_path) as file: - return file.read().strip() - raise ValueError(f"Password file {file_path} does not exist.") - return v - - @computed_field - @property - def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: - url = MultiHostUrl.build( - scheme="postgresql+psycopg", - username=self.POSTGRES_USER, - password=self.POSTGRES_PASSWORD - if self.POSTGRES_PASSWORD - else self.POSTGRES_PASSWORD_FILE, - host=self.POSTGRES_SERVER, - port=self.POSTGRES_PORT, - path=self.POSTGRES_DB, - ) - return PostgresDsn(url) - - -settings = Settings() # type: ignore -``` -{{< /file >}} - -{{< file path="requirements.txt" status="modified" hl_lines="5-7" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -sqlmodel==0.0.24 -psycopg[binary]==3.2.9 -pydantic-settings==2.9.1 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path="Dockerfile" >}} -```dockerfile -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. -# For more information, see https://docs.docker.com/dhi/ - -# Use the dev image to build and install dependencies. -FROM dhi.io/python:3.12-dev AS builder - -WORKDIR /app - -RUN python3 -m venv /venv -ENV PATH="/venv/bin:$PATH" - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them into -# this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - pip install -r requirements.txt - -# Use the minimal runtime image. It runs as nonroot by default. -FROM dhi.io/python:3.12 - -WORKDIR /app - -COPY --from=builder /venv /venv -ENV PATH="/venv/bin:$PATH" - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] -``` -{{< /file >}} - -{{< file path="compose.yaml" >}} -```yaml -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker Compose reference guide at -# https://docs.docker.com/go/compose-spec-reference/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - ports: - - 8000:8000 -``` -{{< /file >}} - -{{< file path=".dockerignore" >}} -```text -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` -{{< /file >}} - -{{< file path=".gitignore" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -## Update Docker assets - -Replace `Dockerfile` and `compose.yaml` with the following. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" >}} -```python -# FastAPI application backed by a PostgreSQL database via SQLModel. -# The FastAPI lifespan handler creates database tables at startup. -# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). -# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ - -from collections.abc import AsyncGenerator, Sequence -from contextlib import asynccontextmanager - -from fastapi import FastAPI -from sqlmodel import Field, Session, SQLModel, create_engine, select - -from config import settings - - -class Hero(SQLModel, table=True): - id: int | None = Field(default=None, primary_key=True) - name: str = Field(index=True) - secret_name: str - age: int | None = Field(default=None, index=True) - - -engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) - - -def create_db_and_tables() -> None: - SQLModel.metadata.create_all(engine) - - -@asynccontextmanager -async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: - create_db_and_tables() - yield - - -app = FastAPI(lifespan=lifespan) - - -@app.get("/") -def hello() -> str: - return "Hello, Docker!" - - -@app.post("/heroes/") -def create_hero(hero: Hero) -> Hero: - with Session(engine) as session: - session.add(hero) - session.commit() - session.refresh(hero) - return hero - - -@app.get("/heroes/") -def read_heroes() -> Sequence[Hero]: - with Session(engine) as session: - heroes = session.exec(select(Hero)).all() - return heroes -``` -{{< /file >}} - -{{< file path="config.py" >}} -```python -# Pydantic settings that read PostgreSQL connection details from the -# environment. Supports a password file (Docker secrets) via -# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. -# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ - -import os -from typing import Any - -from pydantic import ( - PostgresDsn, - computed_field, - field_validator, - model_validator, -) -from pydantic_core import MultiHostUrl -from pydantic_settings import BaseSettings - - -class Settings(BaseSettings): - POSTGRES_SERVER: str - POSTGRES_PORT: int = 5432 - POSTGRES_USER: str - POSTGRES_PASSWORD: str | None = None - POSTGRES_PASSWORD_FILE: str | None = None - POSTGRES_DB: str - - @model_validator(mode="before") - @classmethod - def check_postgres_password(cls, data: Any) -> Any: - """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" - if isinstance(data, dict): - password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore - password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore - if password_file is None and password is None: - raise ValueError( - "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." - ) - return data # type: ignore - - @field_validator("POSTGRES_PASSWORD_FILE", mode="before") - @classmethod - def read_password_from_file(cls, v: str | None) -> str | None: - if v is not None: - file_path = v - if os.path.exists(file_path): - with open(file_path) as file: - return file.read().strip() - raise ValueError(f"Password file {file_path} does not exist.") - return v - - @computed_field - @property - def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: - url = MultiHostUrl.build( - scheme="postgresql+psycopg", - username=self.POSTGRES_USER, - password=self.POSTGRES_PASSWORD - if self.POSTGRES_PASSWORD - else self.POSTGRES_PASSWORD_FILE, - host=self.POSTGRES_SERVER, - port=self.POSTGRES_PORT, - path=self.POSTGRES_DB, - ) - return PostgresDsn(url) - - -settings = Settings() # type: ignore -``` -{{< /file >}} - -{{< file path="requirements.txt" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -sqlmodel==0.0.24 -psycopg[binary]==3.2.9 -pydantic-settings==2.9.1 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path="Dockerfile" status="modified" hl_lines="11,27-34,37,45" >}} -```dockerfile -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. -# For more information, see https://docs.docker.com/dhi/ - -# Use the dev image to build and install dependencies. -# The builder stage is also used directly in development (see compose.yaml). -FROM dhi.io/python:3.12-dev AS builder - -WORKDIR /app - -RUN python3 -m venv /venv -ENV PATH="/venv/bin:$PATH" - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them -# into this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - pip install -r requirements.txt - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] - - -# Use the minimal runtime image for production. It runs as nonroot by default. -FROM dhi.io/python:3.12 - -WORKDIR /app - -COPY --from=builder /venv /venv -ENV PATH="/venv/bin:$PATH" - -COPY --from=builder /app . - -EXPOSE 8000 - -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] -``` -{{< /file >}} - -{{< file path="compose.yaml" status="modified" hl_lines="8" >}} -```yaml -services: - # Application service. The `target: builder` line builds the development - # image (includes a shell and tools); the production stage of the - # Dockerfile is unused in development. - server: - build: - context: . - target: builder - ports: - - 8000:8000 -``` -{{< /file >}} - -{{< file path=".dockerignore" >}} -```text -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` -{{< /file >}} - -{{< file path=".gitignore" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -### About these changes - -The `Dockerfile` builder stage now includes `COPY . .` and a `CMD` -instruction, which makes it directly runnable. This lets Compose target the -builder stage during development without rebuilding the production stage. The -production stage at the bottom is unchanged and still produces a minimal, -nonroot runtime image for shipping. - -In `compose.yaml`, the new `target: builder` line tells Compose to build and -run the builder stage of the Dockerfile during development. Unlike the minimal -production image, the development image includes a shell and additional tools -that make debugging easier. If you need a shell in a running production -container, use [Docker Debug](/reference/cli/docker/debug/) instead. - -## Add a local database and persist data - -You can use containers to set up local services, like a database. In this -section, you'll update the `compose.yaml` file to define a database service -and a volume to persist data, and add a `db/password.txt` file that holds the -database password. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" >}} -```python -# FastAPI application backed by a PostgreSQL database via SQLModel. -# The FastAPI lifespan handler creates database tables at startup. -# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). -# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ - -from collections.abc import AsyncGenerator, Sequence -from contextlib import asynccontextmanager - -from fastapi import FastAPI -from sqlmodel import Field, Session, SQLModel, create_engine, select - -from config import settings - - -class Hero(SQLModel, table=True): - id: int | None = Field(default=None, primary_key=True) - name: str = Field(index=True) - secret_name: str - age: int | None = Field(default=None, index=True) - - -engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) - - -def create_db_and_tables() -> None: - SQLModel.metadata.create_all(engine) - - -@asynccontextmanager -async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: - create_db_and_tables() - yield - - -app = FastAPI(lifespan=lifespan) - - -@app.get("/") -def hello() -> str: - return "Hello, Docker!" - - -@app.post("/heroes/") -def create_hero(hero: Hero) -> Hero: - with Session(engine) as session: - session.add(hero) - session.commit() - session.refresh(hero) - return hero - - -@app.get("/heroes/") -def read_heroes() -> Sequence[Hero]: - with Session(engine) as session: - heroes = session.exec(select(Hero)).all() - return heroes -``` -{{< /file >}} - -{{< file path="config.py" >}} -```python -# Pydantic settings that read PostgreSQL connection details from the -# environment. Supports a password file (Docker secrets) via -# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. -# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ - -import os -from typing import Any - -from pydantic import ( - PostgresDsn, - computed_field, - field_validator, - model_validator, -) -from pydantic_core import MultiHostUrl -from pydantic_settings import BaseSettings - - -class Settings(BaseSettings): - POSTGRES_SERVER: str - POSTGRES_PORT: int = 5432 - POSTGRES_USER: str - POSTGRES_PASSWORD: str | None = None - POSTGRES_PASSWORD_FILE: str | None = None - POSTGRES_DB: str - - @model_validator(mode="before") - @classmethod - def check_postgres_password(cls, data: Any) -> Any: - """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" - if isinstance(data, dict): - password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore - password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore - if password_file is None and password is None: - raise ValueError( - "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." - ) - return data # type: ignore - - @field_validator("POSTGRES_PASSWORD_FILE", mode="before") - @classmethod - def read_password_from_file(cls, v: str | None) -> str | None: - if v is not None: - file_path = v - if os.path.exists(file_path): - with open(file_path) as file: - return file.read().strip() - raise ValueError(f"Password file {file_path} does not exist.") - return v - - @computed_field - @property - def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: - url = MultiHostUrl.build( - scheme="postgresql+psycopg", - username=self.POSTGRES_USER, - password=self.POSTGRES_PASSWORD - if self.POSTGRES_PASSWORD - else self.POSTGRES_PASSWORD_FILE, - host=self.POSTGRES_SERVER, - port=self.POSTGRES_PORT, - path=self.POSTGRES_DB, - ) - return PostgresDsn(url) - - -settings = Settings() # type: ignore -``` -{{< /file >}} - -{{< file path="requirements.txt" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -sqlmodel==0.0.24 -psycopg[binary]==3.2.9 -pydantic-settings==2.9.1 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path="Dockerfile" >}} -```dockerfile -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. -# For more information, see https://docs.docker.com/dhi/ - -# Use the dev image to build and install dependencies. -# The builder stage is also used directly in development (see compose.yaml). -FROM dhi.io/python:3.12-dev AS builder - -WORKDIR /app - -RUN python3 -m venv /venv -ENV PATH="/venv/bin:$PATH" - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them -# into this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - pip install -r requirements.txt - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] - - -# Use the minimal runtime image for production. It runs as nonroot by default. -FROM dhi.io/python:3.12 - -WORKDIR /app - -COPY --from=builder /venv /venv -ENV PATH="/venv/bin:$PATH" - -COPY --from=builder /app . - -EXPOSE 8000 - -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] -``` -{{< /file >}} - -{{< file path="compose.yaml" status="modified" hl_lines="11-46" >}} -```yaml -services: - # Application service. The `target: builder` line builds the development - # image (includes a shell and tools); the production stage of the - # Dockerfile is unused in development. - server: - build: - context: . - target: builder - ports: - - 8000:8000 - environment: - - POSTGRES_SERVER=db - - POSTGRES_USER=postgres - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - depends_on: - db: - condition: service_healthy - secrets: - - db-password - # Database service. Reads the password from a Docker secret mounted at - # /run/secrets/db-password. Compose waits for the healthcheck to pass - # before starting the server, via the server's depends_on. - db: - image: dhi.io/postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` -{{< /file >}} - -{{< file path="db/password.txt" status="new" >}} -```text -mysecretpassword -``` -{{< /file >}} - -{{< file path=".dockerignore" >}} -```text -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` -{{< /file >}} - -{{< file path=".gitignore" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -> [!NOTE] -> -> To learn more about the instructions in the Compose file, see [Compose file -> reference](/reference/compose-file/). - -Now, run the following `docker compose up` command to start your application. - -```console -$ docker compose up --build -``` - -Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands: - -Create an object with a POST request: - -```console -$ curl -X 'POST' \ - 'http://localhost:8000/heroes/' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{ - "id": 1, - "name": "my hero", - "secret_name": "austing", - "age": 12 -}' -``` - -You should receive the following response: - -```json -{ - "age": 12, - "id": 1, - "name": "my hero", - "secret_name": "austing" -} -``` - -Now make a GET request: - -```console -$ curl -X 'GET' \ - 'http://localhost:8000/heroes/' \ - -H 'accept: application/json' -``` - -You should receive the same response as above because it's the only object in the database. - -```json -{ - "age": 12, - "id": 1, - "name": "my hero", - "secret_name": "austing" -} -``` - -Press `ctrl+c` in the terminal to stop your application. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yaml` file in an IDE or text editor and add the highlighted -Compose Watch instructions. - -{{< files name="python-docker-example" >}} - -{{< file path="app.py" >}} -```python -# FastAPI application backed by a PostgreSQL database via SQLModel. -# The FastAPI lifespan handler creates database tables at startup. -# Endpoints: GET / (greeting), POST /heroes/ (create), GET /heroes/ (list). -# See https://fastapi.tiangolo.com/ and https://sqlmodel.tiangolo.com/ - -from collections.abc import AsyncGenerator, Sequence -from contextlib import asynccontextmanager - -from fastapi import FastAPI -from sqlmodel import Field, Session, SQLModel, create_engine, select - -from config import settings - - -class Hero(SQLModel, table=True): - id: int | None = Field(default=None, primary_key=True) - name: str = Field(index=True) - secret_name: str - age: int | None = Field(default=None, index=True) - - -engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI)) - - -def create_db_and_tables() -> None: - SQLModel.metadata.create_all(engine) - - -@asynccontextmanager -async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]: - create_db_and_tables() - yield - - -app = FastAPI(lifespan=lifespan) - - -@app.get("/") -def hello() -> str: - return "Hello, Docker!" - - -@app.post("/heroes/") -def create_hero(hero: Hero) -> Hero: - with Session(engine) as session: - session.add(hero) - session.commit() - session.refresh(hero) - return hero - - -@app.get("/heroes/") -def read_heroes() -> Sequence[Hero]: - with Session(engine) as session: - heroes = session.exec(select(Hero)).all() - return heroes -``` -{{< /file >}} - -{{< file path="config.py" >}} -```python -# Pydantic settings that read PostgreSQL connection details from the -# environment. Supports a password file (Docker secrets) via -# POSTGRES_PASSWORD_FILE in addition to POSTGRES_PASSWORD. -# See https://docs.pydantic.dev/latest/concepts/pydantic_settings/ - -import os -from typing import Any - -from pydantic import ( - PostgresDsn, - computed_field, - field_validator, - model_validator, -) -from pydantic_core import MultiHostUrl -from pydantic_settings import BaseSettings - - -class Settings(BaseSettings): - POSTGRES_SERVER: str - POSTGRES_PORT: int = 5432 - POSTGRES_USER: str - POSTGRES_PASSWORD: str | None = None - POSTGRES_PASSWORD_FILE: str | None = None - POSTGRES_DB: str - - @model_validator(mode="before") - @classmethod - def check_postgres_password(cls, data: Any) -> Any: - """Validate that either POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE is set.""" - if isinstance(data, dict): - password_file: str | None = data.get("POSTGRES_PASSWORD_FILE") # type: ignore - password: str | None = data.get("POSTGRES_PASSWORD") # type: ignore - if password_file is None and password is None: - raise ValueError( - "At least one of POSTGRES_PASSWORD_FILE and POSTGRES_PASSWORD must be set." - ) - return data # type: ignore - - @field_validator("POSTGRES_PASSWORD_FILE", mode="before") - @classmethod - def read_password_from_file(cls, v: str | None) -> str | None: - if v is not None: - file_path = v - if os.path.exists(file_path): - with open(file_path) as file: - return file.read().strip() - raise ValueError(f"Password file {file_path} does not exist.") - return v - - @computed_field - @property - def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn: - url = MultiHostUrl.build( - scheme="postgresql+psycopg", - username=self.POSTGRES_USER, - password=self.POSTGRES_PASSWORD - if self.POSTGRES_PASSWORD - else self.POSTGRES_PASSWORD_FILE, - host=self.POSTGRES_SERVER, - port=self.POSTGRES_PORT, - path=self.POSTGRES_DB, - ) - return PostgresDsn(url) - - -settings = Settings() # type: ignore -``` -{{< /file >}} - -{{< file path="requirements.txt" >}} -```text -# Python package dependencies for the application, pinned for reproducible builds. -# See https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -fastapi==0.115.12 -sqlmodel==0.0.24 -psycopg[binary]==3.2.9 -pydantic-settings==2.9.1 -uvicorn==0.34.3 -``` -{{< /file >}} - -{{< file path="Dockerfile" >}} -```dockerfile -# syntax=docker/dockerfile:1 - -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Dockerfile reference guide at -# https://docs.docker.com/go/dockerfile-reference/ - -# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. -# For more information, see https://docs.docker.com/dhi/ - -# Use the dev image to build and install dependencies. -# The builder stage is also used directly in development (see compose.yaml). -FROM dhi.io/python:3.12-dev AS builder - -WORKDIR /app - -RUN python3 -m venv /venv -ENV PATH="/venv/bin:$PATH" - -# Download dependencies as a separate step to take advantage of Docker's caching. -# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds. -# Leverage a bind mount to requirements.txt to avoid having to copy them -# into this layer. -RUN --mount=type=cache,target=/root/.cache/pip \ - --mount=type=bind,source=requirements.txt,target=requirements.txt \ - pip install -r requirements.txt - -# Copy the source code into the container. -COPY . . - -# Expose the port that the application listens on. -EXPOSE 8000 - -# Run the application. -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] - - -# Use the minimal runtime image for production. It runs as nonroot by default. -FROM dhi.io/python:3.12 - -WORKDIR /app - -COPY --from=builder /venv /venv -ENV PATH="/venv/bin:$PATH" - -COPY --from=builder /app . - -EXPOSE 8000 - -CMD ["/venv/bin/python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"] -``` -{{< /file >}} - -{{< file path="compose.yaml" status="modified" hl_lines="21-24" >}} -```yaml -services: - # Application service. The `target: builder` line builds the development - # image (includes a shell and tools); the production stage of the - # Dockerfile is unused in development. - server: - build: - context: . - target: builder - ports: - - 8000:8000 - environment: - - POSTGRES_SERVER=db - - POSTGRES_USER=postgres - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - depends_on: - db: - condition: service_healthy - secrets: - - db-password - develop: - watch: - - action: rebuild - path: . - db: - image: dhi.io/postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` -{{< /file >}} - -{{< file path="db/password.txt" >}} -```text -mysecretpassword -``` -{{< /file >}} - -{{< file path=".dockerignore" >}} -```text -# Include any files or directories that you don't want to be copied to your -# container here (e.g., local build artifacts, temporary files, etc.). -# -# For more help, visit the .dockerignore file reference guide at -# https://docs.docker.com/go/build-context-dockerignore/ - -**/.DS_Store -**/__pycache__ -**/.venv -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget -**/.vs -**/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/bin -**/charts -**/docker-compose* -**/compose.y*ml -**/Dockerfile* -**/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -``` -{{< /file >}} - -{{< file path=".gitignore" >}} -```text -# Files and directories that Git should ignore. This is the standard Python -# template covering bytecode, build artifacts, virtual environments, and IDE -# settings. See https://git-scm.com/docs/gitignore for syntax reference. - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Secrets -db/password.txt -``` -{{< /file >}} - -{{< /files >}} - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -In a terminal, curl the application to get a response. - -```console -$ curl http://localhost:8000 -Hello, Docker! -``` - -Any changes to the application's source files on your local machine will now be immediately reflected in the running container. - -Open `python-docker-example/app.py` in an IDE or text editor and update the `Hello, Docker!` string by adding a few more exclamation marks. - -```diff -- return 'Hello, Docker!' -+ return 'Hello, Docker!!!' -``` - -Save the changes to `app.py` and then wait a few seconds for the application to rebuild. Curl the application again and verify that the updated text appears. - -```console -$ curl http://localhost:8000 -Hello, Docker!!! -``` - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you took a look at setting up your Compose file to add a local -database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose secrets](/reference/compose-file/secrets.md) -- [Compose Watch](/manuals/compose/how-tos/file-watch.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll learn how you can set up linting, formatting, and type checking to follow the best practices in Python apps. diff --git a/content/guides/python/lint-format-typing.md b/content/guides/python/lint-format-typing.md deleted file mode 100644 index 64e5b3c5b080..000000000000 --- a/content/guides/python/lint-format-typing.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Linting, formatting, and type checking for Python -linkTitle: Linting and typing -weight: 25 -keywords: Python, linting, formatting, type checking, ruff, pyright -description: Learn how to set up linting, formatting and type checking for your Python application. -aliases: - - /language/python/lint-format-typing/ ---- - -## Prerequisites - -Complete [Develop your app](develop.md). This topic requires a local Python -installation because the tools and Git hooks introduced here run on your -host. If you don't want to install Python locally, skip this topic. The same -checks run in CI in the [next topic](configure-github-actions.md). - -## Overview - -Linting, formatting, and type checking are automated ways to catch bugs, -enforce style, and spot type errors before code runs. Running them on every -commit, in CI, and in your editor catches problems early when they're cheap -to fix. - -In this section, you'll configure three tools for your Python application. -Ruff handles linting and formatting in a single fast pass. Pyright statically -checks your code for type errors. Pre-commit hooks run both of these -automatically before each Git commit so problems are caught locally before -they're committed. - -## Linting and formatting with Ruff - -Ruff is an extremely fast Python linter and formatter written in Rust. It replaces multiple tools like flake8, isort, and black with a single unified tool. - -Create a `pyproject.toml` file in your `python-docker-example` directory: - -{{< files name="python-docker-example" >}} - -{{< file path="pyproject.toml" status="new" >}} -```toml -# Configuration for code-quality tools. -# - [tool.ruff]: linting and formatting (https://docs.astral.sh/ruff/) -# - [tool.pyright]: static type checking (https://microsoft.github.io/pyright/) - -[tool.ruff] -target-version = "py312" - -[tool.ruff.lint] -select = [ - "E", # pycodestyle errors - "W", # pycodestyle warnings - "F", # pyflakes - "I", # isort - "B", # flake8-bugbear - "C4", # flake8-comprehensions - "UP", # pyupgrade - "ARG001", # unused arguments in functions -] -ignore = [ - "E501", # line too long, handled by black - "B008", # do not perform function calls in argument defaults - "W191", # indentation contains tabs - "B904", # Allow raising exceptions without from e, for HTTPException -] -``` -{{< /file >}} - -{{< /files >}} - -Install Ruff: - -```console -$ pip install ruff -``` - -If you're using a virtual environment, make sure it is activated so the `ruff` -command is available. - -Run these commands to check and format your code: - -```console -# Check for errors -$ ruff check . - -# Automatically fix fixable errors -$ ruff check --fix . - -# Format code -$ ruff format . -``` - -## Type checking with Pyright - -Pyright is a fast static type checker for Python that works well with modern Python features. - -Update `pyproject.toml` to add the Pyright configuration at the bottom. - -{{< files name="python-docker-example" >}} - -{{< file path="pyproject.toml" status="modified" hl_lines="25-29" >}} -```toml -# Configuration for code-quality tools. -# - [tool.ruff]: linting and formatting (https://docs.astral.sh/ruff/) -# - [tool.pyright]: static type checking (https://microsoft.github.io/pyright/) - -[tool.ruff] -target-version = "py312" - -[tool.ruff.lint] -select = [ - "E", # pycodestyle errors - "W", # pycodestyle warnings - "F", # pyflakes - "I", # isort - "B", # flake8-bugbear - "C4", # flake8-comprehensions - "UP", # pyupgrade - "ARG001", # unused arguments in functions -] -ignore = [ - "E501", # line too long, handled by black - "B008", # do not perform function calls in argument defaults - "W191", # indentation contains tabs - "B904", # Allow raising exceptions without from e, for HTTPException -] - -[tool.pyright] -typeCheckingMode = "strict" -pythonVersion = "3.12" -exclude = [".venv"] -``` -{{< /file >}} - -{{< /files >}} - -Install Pyright and run it: - -```console -$ pip install pyright -$ pyright -``` - -## Setting up pre-commit hooks - -Pre-commit hooks run checks automatically before each commit on your local -machine. Create a `.pre-commit-config.yaml` file in your `python-docker-example` -directory to set up Ruff hooks: - -{{< files name="python-docker-example" >}} - -{{< file path=".pre-commit-config.yaml" status="new" >}} -```yaml -# Pre-commit hook configuration. Runs Ruff (lint + format) on every -# `git commit`. See https://pre-commit.com/ - -repos: - - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.15.15 - hooks: - - id: ruff - args: [--fix] - - id: ruff-format -``` -{{< /file >}} - -{{< /files >}} - -To install and use: - -```console -$ pip install pre-commit -$ pre-commit install -$ git commit -m "Test commit" # Automatically runs checks -``` - -## Summary - -In this section, you learned how to: - -- Configure and use Ruff for linting and formatting -- Set up Pyright for static type checking -- Automate checks with pre-commit hooks - -These tools help maintain code quality and catch errors early in development. - -Related information: - -- [Ruff documentation](https://docs.astral.sh/ruff/) -- [Pyright documentation](https://microsoft.github.io/pyright/) -- [pre-commit framework](https://pre-commit.com/) - -## Next steps - -- [Configure GitHub Actions](configure-github-actions.md) to run these checks automatically -- Customize linting rules to match your team's style preferences -- Explore advanced type checking features diff --git a/content/guides/python/secure-supply-chain.md b/content/guides/python/secure-supply-chain.md deleted file mode 100644 index 07c8b3f0ca60..000000000000 --- a/content/guides/python/secure-supply-chain.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Secure your Python image supply chain -linkTitle: Secure your supply chain -weight: 45 -keywords: python, sbom, provenance, attestations, docker scout, supply chain, security -description: Learn how to inspect, generate, and verify supply chain attestations for your Python container image. ---- - -## Prerequisites - -Complete [Configure CI/CD for your Python application](configure-github-actions.md). - -## Overview - -When you ship a container image, what's inside it and where it came from -matters. Supply chain attestations are signed records that answer questions -like which packages are in the image, what vulnerabilities affect them, how -the image was built, and what security checks it passed. - -In this section, you'll inspect the attestations that ship with your Docker -Hardened Image base, generate your own SBOM and provenance attestations -during CI, and pin the base image by digest so your builds are reproducible. - -The inspection commands in this topic are shown manually so you can see what -each one returns. In a real workflow you'd automate these checks with -[Docker Scout](/scout/), which runs the same scans on every push, -enforces policies in CI, and surfaces results in your registry and pull -requests. - -## Inspect the base image attestations - -Docker Hardened Images are built to SLSA Build Level 3 and ship with a set of -signed attestations covering bill-of-materials, vulnerabilities, build -provenance, and security scans. See -[DHI attestations](/manuals/dhi/core-concepts/attestations.md) for the full -list of types and how to verify their signatures with Cosign. - -List all the attestations available on the Python DHI: - -```console -$ docker scout attest list registry://dhi.io/python:3.12 -``` - -View the SBOM: - -```console -$ docker scout sbom registry://dhi.io/python:3.12 -``` - -Check known vulnerabilities: - -```console -$ docker scout cves registry://dhi.io/python:3.12 -``` - -> [!NOTE] -> -> The `registry://` prefix forces `docker scout` to fetch the image and its -> attestations from the registry instead of reading a locally pulled copy. If -> you've already pulled or built against the base image, the local copy -> doesn't have the attached attestations, so the prefix is required to see -> them. - -When you base your own image on a DHI image, these attestations stay attached to the base layer in the registry. Tools that inspect your image can follow the chain back to the DHI source. - -## Generate attestations for your image - -Update your GitHub Actions workflow to attach SBOM and provenance attestations to the image you push. - -Edit `.github/workflows/build.yml` and update the build-and-push step: - -```yaml {hl_lines="6-7"} -- name: Build and push Docker image - uses: docker/build-push-action@v6 - with: - context: . - push: true - sbom: true - provenance: mode=max - tags: ${{ steps.meta.outputs.tags }} -``` - -- `sbom: true` tells BuildKit to scan the built image and attach an SBOM attestation. -- `provenance: mode=max` records detailed build provenance, including the source repository, commit, and build parameters. - -The next time your workflow runs, the pushed image will carry these attestations alongside the image manifest in the registry. - -## Inspect your pushed image's attestations - -After your workflow pushes the image, inspect it the same way you inspected the base image: - -```console -$ docker scout attest list registry://DOCKER_USERNAME/REPO_NAME:latest -$ docker scout sbom registry://DOCKER_USERNAME/REPO_NAME:latest -``` - -The SBOM includes packages from every layer, including those inherited from `dhi.io/python:3.12`. The provenance record references the DHI base image by digest, so consumers of your image can trace the build chain back to the DHI source. - -## Pin the base image by digest - -Image tags like `dhi.io/python:3.12` move over time as new patches land. For reproducible builds, pin to an immutable digest. - -The Dockerfile uses two tags, `dhi.io/python:3.12-dev` in the builder stage -and `dhi.io/python:3.12` in the runtime stage. Each tag has its own digest, -so look up both: - -```console -$ docker buildx imagetools inspect dhi.io/python:3.12-dev --format "{{ .Manifest.Digest }}" -sha256:4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945 -$ docker buildx imagetools inspect dhi.io/python:3.12 --format "{{ .Manifest.Digest }}" -sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 -``` - -Each digest is a 64-character hex string. Update your `Dockerfile` to reference -each digest on the matching `FROM` line: - -```dockerfile -FROM dhi.io/python:3.12-dev@sha256:4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945 AS builder -# ... -FROM dhi.io/python:3.12@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 -``` - -> [!TIP] -> -> Pinning by digest also pins you to that image's vulnerabilities. Use [Dependabot](https://docs.github.com/en/code-security/dependabot) or [Renovate](https://docs.renovatebot.com/) to automate digest updates so you get a PR when a new patched image is available, with a changelog to review before merging. - -## Summary - -In this section, you learned how to: - -- Inspect the supply chain attestations that ship with the DHI base image, including SBOMs, CVE reports, VEX statements, and scan results -- Generate SBOM and provenance attestations for your own image in CI -- Pin base images by digest for reproducible builds - -Related information: - -- [DHI attestations](/manuals/dhi/core-concepts/attestations.md) -- [Verify a Docker Hardened Image](/manuals/dhi/how-to/verify.md) -- [Docker Scout](/scout/) -- [Build attestations](/manuals/build/metadata/attestations/_index.md) - -## Next steps - -In the next section, you'll deploy your application to Kubernetes. diff --git a/content/guides/r.md b/content/guides/r.md new file mode 100644 index 000000000000..84fce50850f8 --- /dev/null +++ b/content/guides/r.md @@ -0,0 +1,316 @@ +--- +title: R language-specific guide +linkTitle: R +description: Containerize R apps using Docker +keywords: Docker, getting started, R, language +summary: | + This guide details how to containerize R applications using Docker. +aliases: + - /languages/r/ + - /guides/languages/r/ + - /language/R/build-images/ + - /language/R/run-containers/ + - /language/r/containerize/ + - /language/r/develop/ + - /language/r/configure-ci-cd/ + - /language/r/deploy/ + - /guides/r/configure-ci-cd/ + - /guides/r/containerize/ + - /guides/r/deploy/ + - /guides/r/develop/ +params: + tags: [languages] + time: 10 minutes +--- + +The R language-specific guide teaches you how to containerize a R application using Docker. In this guide, you’ll learn how to: + +- Containerize and run a R application +- Set up a local environment to develop a R application using containers + +Start by containerizing an existing R application. + +## Containerize a R application + +### Prerequisites + +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +### Overview + +This section walks you through containerizing and running a R application. + +### Get the sample application + +The sample application uses the popular [Shiny](https://shiny.posit.co/) framework. + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/mfranzon/r-docker-dev.git && cd r-docker-dev +``` + +You should now have the following contents in your `r-docker-dev` +directory. + +```text +├── r-docker-dev/ +│ ├── src/ +│ │ └── app.R +│ ├── src_db/ +│ │ └── app_db.R +│ ├── compose.yaml +│ ├── Dockerfile +│ └── README.md +``` + +To learn more about the files in the repository, see the following: + +- [Dockerfile](/reference/dockerfile.md) +- [.dockerignore](/reference/dockerfile.md#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) + +### Run the application + +Inside the `r-docker-dev` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:3838](http://localhost:3838). You should see a simple Shiny application. + +In the terminal, press `ctrl`+`c` to stop the application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `r-docker-dev` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:3838](http://localhost:3838). + +You should see a simple Shiny application. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for R development + +### Prerequisites + +Complete [Containerize a R application](#containerize-a-r-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Adding a local database and persisting data +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +### Get the sample application + +You'll need to clone a new repository to get a sample application that includes logic to connect to the database. + +Change to a directory where you want to clone the repository and run the following command. + +```console +$ git clone https://github.com/mfranzon/r-docker-dev.git +``` + +### Configure the application to use the database + +To try the connection between the Shiny application and the local database you have to modify the `Dockerfile` changing the `COPY` instruction: + +```diff +-COPY src/ . ++COPY src_db/ . +``` + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. + +In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. + +In the `compose.yaml` file, you need to un-comment the properties for configuring the database. You must also mount the database password file and set an environment variable on the `shiny-app` service pointing to the location of the file in the container. + +The following is the updated `compose.yaml` file. + +```yaml +services: + shiny-app: + build: + context: . + dockerfile: Dockerfile + ports: + - 3838:3838 + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. + +In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. + +```text +mysecretpassword +``` + +Save and close the `password.txt` file. + +You should now have the following contents in your `r-docker-dev` +directory. + +```text +├── r-docker-dev/ +│ ├── db/ +│ │ └── password.txt +│ ├── src/ +│ │ └── app.R +│ ├── src_db/ +│ │ └── app_db.R +│ ├── requirements.txt +│ ├── .dockerignore +│ ├── compose.yaml +│ ├── Dockerfile +│ └── README.md +``` + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +Now test your DB connection opening a browser at: + +```console +http://localhost:3838 +``` + +You should see a pop-up message: + +```text +DB CONNECTED +``` + +Press `ctrl+c` in the terminal to stop your application. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Lines 15 to 18 in the `compose.yaml` file contain properties that trigger Docker +to rebuild the image when a file in the current working directory is changed: + +```yaml {hl_lines="15-18",linenos=true} +services: + shiny-app: + build: + context: . + dockerfile: Dockerfile + ports: + - 3838:3838 + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + depends_on: + db: + condition: service_healthy + secrets: + - db-password + develop: + watch: + - action: rebuild + path: . + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Now, if you modify your `app.R` you will see the changes in real time without re-building the image! + +Press `ctrl+c` in the terminal to stop your application. + +### Summary + +In this section, you took a look at setting up your Compose file to add a local +database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + +- [Compose file reference](/reference/compose-file/) +- [Compose file watch](/manuals/compose/how-tos/file-watch.md) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) diff --git a/content/guides/r/_index.md b/content/guides/r/_index.md deleted file mode 100644 index c599db41a572..000000000000 --- a/content/guides/r/_index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: R language-specific guide -linkTitle: R -description: Containerize R apps using Docker -keywords: Docker, getting started, R, language -summary: | - This guide details how to containerize R applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /languages/r/ - - /guides/languages/r/ -languages: [r] -params: - time: 10 minutes ---- - -The R language-specific guide teaches you how to containerize a R application using Docker. In this guide, you’ll learn how to: - -- Containerize and run a R application -- Set up a local environment to develop a R application using containers -- Configure a CI/CD pipeline for a containerized R application using GitHub Actions -- Deploy your containerized R application locally to Kubernetes to test and debug your deployment - -Start by containerizing an existing R application. diff --git a/content/guides/r/configure-ci-cd.md b/content/guides/r/configure-ci-cd.md deleted file mode 100644 index 662a2155e14b..000000000000 --- a/content/guides/r/configure-ci-cd.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Configure CI/CD for your R application -linkTitle: Configure CI/CD -weight: 40 -keywords: ci/cd, github actions, R, shiny -description: Learn how to configure CI/CD using GitHub Actions for your R application. -aliases: - - /language/r/configure-ci-cd/ - - /guides/language/r/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a R application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - platforms: linux/amd64,linux/arm64 - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your R application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/r/containerize.md b/content/guides/r/containerize.md deleted file mode 100644 index fd8c966f9f30..000000000000 --- a/content/guides/r/containerize.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Containerize a R application -linkTitle: Containerize your app -weight: 10 -keywords: R, containerize, initialize -description: Learn how to containerize a R application. -aliases: - - /language/R/build-images/ - - /language/R/run-containers/ - - /language/r/containerize/ - - /guides/language/r/containerize/ ---- - -## Prerequisites - -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -## Overview - -This section walks you through containerizing and running a R application. - -## Get the sample application - -The sample application uses the popular [Shiny](https://shiny.posit.co/) framework. - -Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/mfranzon/r-docker-dev.git && cd r-docker-dev -``` - -You should now have the following contents in your `r-docker-dev` -directory. - -```text -├── r-docker-dev/ -│ ├── src/ -│ │ └── app.R -│ ├── src_db/ -│ │ └── app_db.R -│ ├── compose.yaml -│ ├── Dockerfile -│ └── README.md -``` - -To learn more about the files in the repository, see the following: - -- [Dockerfile](/reference/dockerfile.md) -- [.dockerignore](/reference/dockerfile.md#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) - -## Run the application - -Inside the `r-docker-dev` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:3838](http://localhost:3838). You should see a simple Shiny application. - -In the terminal, press `ctrl`+`c` to stop the application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `r-docker-dev` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:3838](http://localhost:3838). - -You should see a simple Shiny application. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run your R -application using Docker. - -Related information: - -- [Docker Compose overview](/manuals/compose/_index.md) - -## Next steps - -In the next section, you'll learn how you can develop your application using -containers. diff --git a/content/guides/r/deploy.md b/content/guides/r/deploy.md deleted file mode 100644 index 70c10b216faa..000000000000 --- a/content/guides/r/deploy.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Test your R deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, R -description: Learn how to develop locally using Kubernetes -aliases: - - /language/r/deploy/ - - /guides/language/r/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a R application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `r-docker-dev` directory, create a file named -`docker-r-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your R application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-r-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: shiny - template: - metadata: - labels: - service: shiny - spec: - containers: - - name: shiny-service - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always - env: - - name: POSTGRES_PASSWORD - value: mysecretpassword ---- -apiVersion: v1 -kind: Service -metadata: - name: service-entrypoint - namespace: default -spec: - type: NodePort - selector: - service: shiny - ports: - - port: 3838 - targetPort: 3838 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your R application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 3838 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `r-docker-dev` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-r-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```text - deployment.apps/docker-r-demo created - service/service-entrypoint created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-r-demo 1/1 1 1 15s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 23h - service-entrypoint NodePort 10.99.128.230 <none> 3838:30001/TCP 75s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a browser, visit the following address. Note that a database was not deployed in - this example. - - ```console - http://localhost:30001/ - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-r-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/r/develop.md b/content/guides/r/develop.md deleted file mode 100644 index 0427464e298a..000000000000 --- a/content/guides/r/develop.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -title: Use containers for R development -linkTitle: Develop your app -weight: 20 -keywords: R, local, development -description: Learn how to develop your R application locally. -aliases: - - /language/r/develop/ - - /guides/language/r/develop/ ---- - -## Prerequisites - -Complete [Containerize a R application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Adding a local database and persisting data -- Configuring Compose to automatically update your running Compose services as you edit and save your code - -## Get the sample application - -You'll need to clone a new repository to get a sample application that includes logic to connect to the database. - -Change to a directory where you want to clone the repository and run the following command. - -```console -$ git clone https://github.com/mfranzon/r-docker-dev.git -``` - -## Configure the application to use the database - -To try the connection between the Shiny application and the local database you have to modify the `Dockerfile` changing the `COPY` instruction: - -```diff --COPY src/ . -+COPY src_db/ . -``` - -## Add a local database and persist data - -You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. - -In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. - -In the `compose.yaml` file, you need to un-comment the properties for configuring the database. You must also mount the database password file and set an environment variable on the `shiny-app` service pointing to the location of the file in the container. - -The following is the updated `compose.yaml` file. - -```yaml -services: - shiny-app: - build: - context: . - dockerfile: Dockerfile - ports: - - 3838:3838 - environment: - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - depends_on: - db: - condition: service_healthy - secrets: - - db-password - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -> [!NOTE] -> -> To learn more about the instructions in the Compose file, see [Compose file -> reference](/reference/compose-file/). - -Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. - -In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. - -```text -mysecretpassword -``` - -Save and close the `password.txt` file. - -You should now have the following contents in your `r-docker-dev` -directory. - -```text -├── r-docker-dev/ -│ ├── db/ -│ │ └── password.txt -│ ├── src/ -│ │ └── app.R -│ ├── src_db/ -│ │ └── app_db.R -│ ├── requirements.txt -│ ├── .dockerignore -│ ├── compose.yaml -│ ├── Dockerfile -│ └── README.md -``` - -Now, run the following `docker compose up` command to start your application. - -```console -$ docker compose up --build -``` - -Now test your DB connection opening a browser at: - -```console -http://localhost:3838 -``` - -You should see a pop-up message: - -```text -DB CONNECTED -``` - -Press `ctrl+c` in the terminal to stop your application. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Lines 15 to 18 in the `compose.yaml` file contain properties that trigger Docker -to rebuild the image when a file in the current working directory is changed: - -```yaml {hl_lines="15-18",linenos=true} -services: - shiny-app: - build: - context: . - dockerfile: Dockerfile - ports: - - 3838:3838 - environment: - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - depends_on: - db: - condition: service_healthy - secrets: - - db-password - develop: - watch: - - action: rebuild - path: . - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Now, if you modify your `app.R` you will see the changes in real time without re-building the image! - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you took a look at setting up your Compose file to add a local -database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose file watch](/manuals/compose/how-tos/file-watch.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/rag-ollama/_index.md b/content/guides/rag-ollama/_index.md deleted file mode 100644 index 79bfff446fbc..000000000000 --- a/content/guides/rag-ollama/_index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: Containerize RAG application using Ollama and Docker -keywords: python, generative ai, genai, llm, ollama, rag, qdrant -title: Build a RAG application using Ollama and Docker -linkTitle: RAG Ollama application -summary: | - This guide demonstrates how to use Docker to deploy Retrieval-Augmented - Generation (RAG) models with Ollama. -tags: [ai] -aliases: - - /guides/use-case/rag-ollama/ -params: - time: 20 minutes ---- - -The Retrieval Augmented Generation (RAG) guide teaches you how to containerize an existing RAG application using Docker. The example application is a RAG that acts like a sommelier, giving you the best pairings between wines and food. In this guide, you’ll learn how to: - -- Containerize and run a RAG application -- Set up a local environment to run the complete RAG stack locally for development - -Start by containerizing an existing RAG application. diff --git a/content/guides/rag-ollama/containerize.md b/content/guides/rag-ollama/containerize.md deleted file mode 100644 index 402c480af541..000000000000 --- a/content/guides/rag-ollama/containerize.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Containerize a RAG application -linkTitle: Containerize your app -weight: 10 -keywords: python, generative ai, genai, llm, ollama, containerize, initialize, qdrant -description: Learn how to containerize a RAG application. -aliases: - - /guides/use-case/rag-ollama/containerize/ ---- - -## Overview - -This section walks you through containerizing a RAG application using Docker. - -> [!NOTE] -> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. - -## Get the sample application - -The sample application used in this guide is an example of RAG application, made by three main components, which are the building blocks for every RAG application. A Large Language Model hosted somewhere, in this case it is hosted in a container and served via [Ollama](https://ollama.ai/). A vector database, [Qdrant](https://qdrant.tech/), to store the embeddings of local data, and a web application, using [Streamlit](https://streamlit.io/) to offer the best user experience to the user. - -Clone the sample application. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/mfranzon/winy.git -``` - -You should now have the following files in your `winy` directory. - -```text -├── winy/ -│ ├── .gitignore -│ ├── app/ -│ │ ├── main.py -│ │ ├── Dockerfile -| | └── requirements.txt -│ ├── tools/ -│ │ ├── create_db.py -│ │ ├── create_embeddings.py -│ │ ├── requirements.txt -│ │ ├── test.py -| | └── download_model.sh -│ ├── docker-compose.yaml -│ ├── wine_database.db -│ ├── LICENSE -│ └── README.md -``` - -## Containerizing your application: Essentials - -Containerizing an application involves packaging it along with its dependencies into a container, which ensures consistency across different environments. Here’s what you need to containerize an app like Winy : - -1. Dockerfile: A Dockerfile that contains instructions on how to build a Docker image for your application. It specifies the base image, dependencies, configuration files, and the command to run your application. - -2. Docker Compose File: Docker Compose is a tool for defining and running multi-container Docker applications. A Compose file allows you to configure your application's services, networks, and volumes in a single file. - -## Run the application - -Inside the `winy` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Docker builds and runs your application. Depending on your network connection, it may take several minutes to download all the dependencies. You'll see a message like the following in the terminal when the application is running. - -```console -server-1 | You can now view your Streamlit app in your browser. -server-1 | -server-1 | URL: http://0.0.0.0:8501 -server-1 | -``` - -Open a browser and view the application at [http://localhost:8501](http://localhost:8501). You should see a simple Streamlit application. - -The application requires a Qdrant database service and an LLM service to work properly. If you have access to services that you ran outside of Docker, specify the connection information in the `docker-compose.yaml`. - -```yaml -winy: - build: - context: ./app - dockerfile: Dockerfile - environment: - - QDRANT_CLIENT=http://qdrant:6333 # Specifies the url for the qdrant database - - OLLAMA=http://ollama:11434 # Specifies the url for the ollama service - container_name: winy - ports: - - "8501:8501" - depends_on: - - qdrant - - ollama -``` - -If you don't have the services running, continue with this guide to learn how you can run some or all of these services with Docker. -Remember that the `ollama` service is empty; it doesn't have any model. For this reason you need to pull a model before starting to use the RAG application. All the instructions are in the following page. - -In the terminal, press `ctrl`+`c` to stop the application. - -## Summary - -In this section, you learned how you can containerize and run your RAG -application using Docker. - -## Next steps - -In the next section, you'll learn how to properly configure the application with your preferred LLM model, completely locally, using Docker. - diff --git a/content/guides/rag-ollama/develop.md b/content/guides/rag-ollama/develop.md deleted file mode 100644 index 280da3295777..000000000000 --- a/content/guides/rag-ollama/develop.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Use containers for RAG development -linkTitle: Develop your app -weight: 10 -keywords: python, local, development, generative ai, genai, llm, rag, ollama -description: Learn how to develop your generative RAG application locally. -aliases: - - /guides/use-case/rag-ollama/develop/ ---- - -## Prerequisites - -Complete [Containerize a RAG application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment to access all the services that your generative RAG application needs. This includes: - -- Adding a local database -- Adding a local or remote LLM service - -> [!NOTE] -> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. - -## Add a local database - -You can use containers to set up local services, like a database. In this section, you'll explore the database service in the `docker-compose.yaml` file. - -To run the database service: - -1. In the cloned repository's directory, open the `docker-compose.yaml` file in an IDE or text editor. - -2. In the `docker-compose.yaml` file, you'll see the following: - - ```yaml - services: - qdrant: - image: qdrant/qdrant - container_name: qdrant - ports: - - "6333:6333" - volumes: - - qdrant_data:/qdrant/storage - ``` - - > [!NOTE] - > To learn more about Qdrant, see the [Qdrant Official Docker Image](https://hub.docker.com/r/qdrant/qdrant). - -3. Start the application. Inside the `winy` directory, run the following command in a terminal. - - ```console - $ docker compose up --build - ``` - -4. Access the application. Open a browser and view the application at [http://localhost:8501](http://localhost:8501). You should see a simple Streamlit application. - -5. Stop the application. In the terminal, press `ctrl`+`c` to stop the application. - -## Add a local or remote LLM service - -The sample application supports both [Ollama](https://ollama.ai/). This guide provides instructions for the following scenarios: - -- Run Ollama in a container -- Run Ollama outside of a container - -While all platforms can use any of the previous scenarios, the performance and -GPU support may vary. You can use the following guidelines to help you choose the appropriate option: - -- Run Ollama in a container if you're on Linux, and using a native installation of the Docker Engine, or Windows 10/11, and using Docker Desktop, you - have a CUDA-supported GPU, and your system has at least 8 GB of RAM. -- Run Ollama outside of a container if running Docker Desktop on a Linux Machine. - -Choose one of the following options for your LLM service. - -{{< tabs >}} -{{< tab name="Run Ollama in a container" >}} - -When running Ollama in a container, you should have a CUDA-supported GPU. While you can run Ollama in a container without a supported GPU, the performance may not be acceptable. Only Linux and Windows 11 support GPU access to containers. - -To run Ollama in a container and provide GPU access: - -1. Install the prerequisites. - - For Docker Engine on Linux, install the [NVIDIA Container Toolkilt](https://github.com/NVIDIA/nvidia-container-toolkit). - - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/features/wsl/_index.md#turn-on-docker-desktop-wsl-2) -2. The `docker-compose.yaml` file already contains the necessary instructions. In your own apps, you'll need to add the Ollama service in your `docker-compose.yaml`. The following is - the updated `docker-compose.yaml`: - - ```yaml - ollama: - image: ollama/ollama - container_name: ollama - ports: - - "8000:8000" - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: 1 - capabilities: [gpu] - ``` - - > [!NOTE] - > For more details about the Compose instructions, see [Turn on GPU access with Docker Compose](/manuals/compose/how-tos/gpu-support.md). - -3. Once the Ollama container is up and running it is possible to use the `download_model.sh` inside the `tools` folder with this command: - - ```console - . ./download_model.sh <model-name> - ``` - -Pulling an Ollama model can take several minutes. - -{{< /tab >}} -{{< tab name="Run Ollama outside of a container" >}} - -To run Ollama outside of a container: - -1. [Install](https://github.com/jmorganca/ollama) and run Ollama on your host - machine. -2. Pull the model to Ollama using the following command. - - ```console - $ ollama pull llama2 - ``` - -3. Remove the `ollama` service from the `docker-compose.yaml` and update properly the connection variables in `winy` service: - - ```diff - - OLLAMA=http://ollama:11434 - + OLLAMA=<your-url> - ``` - -{{< /tab >}} -{{< /tabs >}} - -## Run your RAG application - -At this point, you have the following services in your Compose file: - -- Server service for your main RAG application -- Database service to store vectors in a Qdrant database -- (optional) Ollama service to run the LLM - service - -Once the application is running, open a browser and access the application at [http://localhost:8501](http://localhost:8501). - -Depending on your system and the LLM service that you chose, it may take several -minutes to answer. - -## Summary - -In this section, you learned how to set up a development environment to provide -access all the services that your GenAI application needs. - -Related information: - -- [Dockerfile reference](/reference/dockerfile.md) -- [Compose file reference](/reference/compose-file/_index.md) -- [Ollama Docker image](https://hub.docker.com/r/ollama/ollama) -- [GenAI Stack demo applications](https://github.com/docker/genai-stack) - -## Next steps - -See samples of more GenAI applications in the [GenAI Stack demo applications](https://github.com/docker/genai-stack). diff --git a/content/guides/reactjs.md b/content/guides/reactjs.md new file mode 100644 index 000000000000..3a1545e65a8f --- /dev/null +++ b/content/guides/reactjs.md @@ -0,0 +1,854 @@ +--- +title: React.js language-specific guide +linkTitle: React.js +description: Containerize and develop React.js apps using Docker +keywords: getting started, React.js, react.js, docker, language, Dockerfile +summary: | + This guide explains how to containerize React.js applications using Docker. +aliases: + - /guides/reactjs/configure-github-actions/ + - /guides/reactjs/containerize/ + - /guides/reactjs/deploy/ + - /guides/reactjs/develop/ + - /guides/reactjs/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +The React.js language-specific guide shows you how to containerize a React.js application using Docker, following best practices for creating efficient, production-ready containers. + +[React.js](https://react.dev/) is a widely used library for building interactive user interfaces. However, managing dependencies, environments, and deployments efficiently can be complex. Docker simplifies this process by providing a consistent and containerized environment. + +> **Acknowledgment** +> +> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows. + +--- + +## What will you learn? + +In this guide, you will learn how to: + +- Containerize and run a React.js application using Docker. +- Set up a local development environment for React.js inside a container. +- Run tests for your React.js application within a Docker container. + +To begin, you’ll start by containerizing an existing React.js application. + +--- + +## Prerequisites + +Before you begin, make sure you're familiar with the following: + +- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/). +- Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. +- Familiarity with [React.js](https://react.dev/) fundamentals. +- Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +Once you've completed the React.js getting started modules, you’ll be ready to containerize your own React.js application using the examples and instructions provided in this guide. + +## Containerize a React.js Application + +### Prerequisites + +Before you begin, make sure the following tools are installed and available on your system: + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +> **New to Docker?** +> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. + +--- + +### Overview + +This guide walks you through the complete process of containerizing a React.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. + +By the end of this guide, you will: + +- Containerize a React.js application using Docker. +- Create and optimize a Dockerfile for production builds. +- Use multi-stage builds to minimize image size. +- Serve the application efficiently with a custom NGINX configuration. +- Follow best practices for building secure and maintainable Docker images. + +--- + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following command +to clone the git repository: + +```console +$ git clone https://github.com/kristiyan-velkov/docker-reactjs-sample +``` + +--- + +### Build the Docker image + +React.js is a front-end library that compiles into static assets, so the Dockerfile is tailored to optimize how React applications are built and served in a production environment. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +#### Step 1: Create the Dockerfile + +Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). + +Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +> [!IMPORTANT] +> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. +> +> Official Node.js Docker Images: https://hub.docker.com/_/node + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} +Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Node.js DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/node:24-alpine3.22-dev + ``` + +3. Pull the Nginx DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev + ``` + +In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images. + +```dockerfile +# ========================================= +# Stage 1: Build the React.js Application +# ========================================= + +# Use a lightweight Node.js image for building (customizable via ARG) +FROM dhi.io/node:24-alpine3.22-dev AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the React.js application (outputs to /app/dist) +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html + +# Use a non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default NGINX container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Image" >}} + +Create a file named `Dockerfile` with the following contents: + +```dockerfile +# ========================================= +# Stage 1: Build the React.js Application +# ========================================= +ARG NODE_VERSION=24.12.0-alpine +ARG NGINX_VERSION=alpine3.22 + +# Use a lightweight Node.js image for building (customizable via ARG) +FROM node:${NODE_VERSION} AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the React.js application (outputs to /app/dist) +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html + +# Use a built-in non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default NGINX container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +> [!NOTE] +> We are using nginx-unprivileged instead of the standard NGINX image to follow security best practices. +> Running as a non-root user in the final image: +> +> - Reduces the attack surface +> - Aligns with Docker’s recommendations for container hardening +> - Helps comply with stricter security policies in production environments + +{{< /tab >}} +{{< /tabs >}} + +#### Step 2: Create the compose.yaml file + +Create a file named `compose.yaml` with the following contents: + +```yaml {collapse=true,title=compose.yaml} +services: + server: + build: + context: . + ports: + - 8080:8080 +``` + +#### Step 3: Create the .dockerignore file + +The `.dockerignore` file tells Docker which files and folders to exclude when building the image. + +> [!NOTE] +> This helps: +> +> - Reduce image size +> - Speed up the build process +> - Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. +> +> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). + +Create a file named `.dockerignore` with the following contents: + +```dockerignore +# Ignore dependencies and build output +node_modules/ +dist/ +out/ +.tmp/ +.cache/ + +# Ignore Vite, Webpack, and React-specific build artifacts +.vite/ +.vitepress/ +.eslintcache +.npm/ +coverage/ +jest/ +cypress/ +cypress/screenshots/ +cypress/videos/ +reports/ + +# Ignore environment and config files (sensitive data) +*.env* +*.log + +# Ignore TypeScript build artifacts (if using TypeScript) +*.tsbuildinfo + +# Ignore lockfiles (optional if using Docker for package installation) +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Ignore local development files +.git/ +.gitignore +.vscode/ +.idea/ +*.swp +.DS_Store +Thumbs.db + +# Ignore Docker-related files (to avoid copying unnecessary configs) +Dockerfile +.dockerignore +docker-compose.yml +docker-compose.override.yml + +# Ignore build-specific cache files +*.lock + +``` + +#### Step 4: Create the `nginx.conf` file + +To serve your React.js application efficiently inside the container, you’ll configure NGINX with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. + +Create a file named `nginx.conf` in the root of your project directory, and add the following content: + +> [!NOTE] +> To learn more about configuring NGINX, see the [official NGINX documentation](https://nginx.org/en/docs/). + +```nginx +worker_processes auto; + +# Store PID in /tmp (always writable) +pid /tmp/nginx.pid; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + # Disable logging to avoid permission issues + access_log off; + error_log /dev/stderr warn; + + # Optimize static file serving + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + keepalive_requests 1000; + + # Gzip compression for optimized delivery + gzip on; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml; + gzip_min_length 256; + gzip_vary on; + + server { + listen 8080; + server_name localhost; + + # Root directory where React.js build files are placed + root /usr/share/nginx/html; + index index.html; + + # Serve React.js static files with proper caching + location / { + try_files $uri /index.html; + } + + # Serve static assets with long cache expiration + location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { + expires 1y; + access_log off; + add_header Cache-Control "public, immutable"; + } + + # Handle React.js client-side routing + location /static/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + } +} +``` + +#### Step 5: Build the React.js application image + +With your custom configuration in place, you're now ready to build the Docker image for your React.js application. + +The updated setup includes: + +- Optimized browser caching and gzip compression +- Secure, non-root logging to avoid permission issues +- Support for React client-side routing by redirecting unmatched routes to `index.html` + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-reactjs-sample/ +│ ├── Dockerfile +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +Now that your Dockerfile is configured, you can build the Docker image for your React.js application. + +> [!NOTE] +> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). + +Run the following command from the root of your project: + +```console +$ docker build --tag docker-reactjs-sample . +``` + +What this command does: + +- Uses the Dockerfile in the current directory (.) +- Packages the application and its dependencies into a Docker image +- Tags the image as docker-reactjs-sample so you can reference it later + +#### Step 6: View local images + +After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. + +To list all locally available Docker images, run the following command: + +```console +$ docker images +``` + +Example Output: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-reactjs-sample latest f39b47a97156 14 seconds ago 75.8MB +``` + +This output provides key details about your images: + +- **Repository** – The name assigned to the image. +- **Tag** – A version label that helps identify different builds (e.g., latest). +- **Image ID** – A unique identifier for the image. +- **Created** – The timestamp indicating when the image was built. +- **Size** – The total disk space used by the image. + +If the build was successful, you should see `docker-reactjs-sample` image listed. + +--- + +### Run the containerized application + +In the previous step, you created a Dockerfile for your React.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. + +Inside the `docker-reactjs-sample` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple React.js web application. + +Press `ctrl+c` in the terminal to stop your application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-reactjs-sample` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application preview. + +To confirm that the container is running, use `docker ps` command: + +```console +$ docker ps +``` + +This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. + +Example Output: + +```shell +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +88bced6ade95 docker-reactjs-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-reactjs-sample-server-1 +``` + +To stop the application, run: + +```console +$ docker compose down +``` + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +## Use containers for React.js development + +### Prerequisites + +Complete [Containerize React.js application](#containerize-a-reactjs-application). + +--- + +### Overview + +In this section, you'll learn how to set up both production and development environments for your containerized React.js application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch. + +You’ll learn how to: + +- Configure separate containers for production and development +- Enable automatic file syncing using Compose Watch in development +- Debug and live-preview your changes in real-time without manual rebuilds + +--- + +### Automatically update services (development mode) + +Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without needing to restart or rebuild containers manually. + +### Step 1: Create a development Dockerfile + +Create a file named `Dockerfile.dev` in your project root with the following content: + +```dockerfile +# ========================================= +# Stage 1: Develop the React.js Application +# ========================================= +ARG NODE_VERSION=24.12.0-alpine + +# Use a lightweight Node.js image for development +FROM node:${NODE_VERSION} AS dev + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies +RUN --mount=type=cache,target=/root/.npm npm install + +# Copy the rest of the application source code into the container +COPY . . + +# Expose the port used by the Vite development server +EXPOSE 5173 + +# Use a default command, can be overridden in Docker compose.yml file +CMD ["npm", "run", "dev"] +``` + +This file sets up a lightweight development environment for your React app using the dev server. + +#### Step 2: Update your `compose.yaml` file + +Open your `compose.yaml` file and define two services: one for production (`react-prod`) and one for development (`react-dev`). + +Here’s an example configuration for a React.js application: + +```yaml +services: + react-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-reactjs-sample + ports: + - "8080:8080" + + react-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "5173:5173" + develop: + watch: + - action: sync + path: . + target: /app +``` + +- The `react-prod` service builds and serves your static production app using Nginx. +- The `react-dev` service runs your React development server with live reload and hot module replacement. +- `watch` triggers file sync with Compose Watch. + +> [!NOTE] +> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +#### Step 3: Update vite.config.ts to ensure it works properly inside Docker + +To make Vite’s development server work reliably inside Docker, you need to update your vite.config.ts with the correct settings. + +Open the `vite.config.ts` file in your project root and update it as follows: + +```ts +/// <reference types="vitest" /> + +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + base: "/", + plugins: [react()], + server: { + host: true, + port: 5173, + strictPort: true, + }, +}); +``` + +> [!NOTE] +> The `server` options in `vite.config.ts` are essential for running Vite inside Docker: +> +> - `host: true` allows the dev server to be accessible from outside the container. +> - `port: 5173` sets a consistent development port (must match the one exposed in Docker). +> - `strictPort: true` ensures Vite fails clearly if the port is unavailable, rather than switching silently. +> +> For full details, refer to the [Vite server configuration docs](https://vitejs.dev/config/server-options.html). + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-reactjs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 4: Start Compose Watch + +Run the following command from your project root to start your container in watch mode: + +```console +$ docker compose watch react-dev +``` + +#### Step 5: Test Compose Watch with React + +To verify that Compose Watch is working correctly: + +1. Open the `src/App.tsx` file in your text editor. + +2. Locate the following line: + + ```html + <h1>Vite + React</h1> + ``` + +3. Change it to: + + ```html + <h1>Hello from Docker Compose Watch</h1> + ``` + +4. Save the file. + +5. Open your browser at [http://localhost:5173](http://localhost:5173). + +You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. + +--- + +## Run React.js tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize React.js application](#containerize-a-reactjs-application). + +### Overview + +Testing is a critical part of the development process. In this section, you'll learn how to: + +- Run unit tests using Vitest inside a Docker container. +- Use Docker Compose to run tests in an isolated, reproducible environment. + +You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — along with [Testing Library](https://testing-library.com/) for assertions. + +--- + +### Run tests during development + +`docker-reactjs-sample` application includes a sample test file at location: + +```console +$ src/App.test.tsx +``` + +This file uses Vitest and React Testing Library to verify the behavior of `App` component. + +#### Step 1: Install Vitest and React Testing Library + +If you haven’t already added the necessary testing tools, install them by running: + +```console +$ npm install --save-dev vitest @testing-library/react @testing-library/jest-dom jsdom +``` + +Then, update the scripts section of your `package.json` file to include the following: + +```json +"scripts": { + "test": "vitest run" +} +``` + +--- + +#### Step 2: Configure Vitest + +Update `vitest.config.ts` file in your project root with the following configuration: + +```ts {hl_lines="14-18",linenos=true} +/// <reference types="vitest" /> + +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + base: "/", + plugins: [react()], + server: { + host: true, + port: 5173, + strictPort: true, + }, + test: { + environment: "jsdom", + setupFiles: "./src/setupTests.ts", + globals: true, + }, +}); +``` + +> [!NOTE] +> The `test` options in `vitest.config.ts` are essential for reliable testing inside Docker: +> +> - `environment: "jsdom"` simulates a browser-like environment for rendering and DOM interactions. +> - `setupFiles: "./src/setupTests.ts"` loads global configuration or mocks before each test file (optional but recommended). +> - `globals: true` enables global test functions like `describe`, `it`, and `expect` without importing them. +> +> For more details, see the official [Vitest configuration docs](https://vitest.dev/config/). + +#### Step 3: Update compose.yaml + +Add a new service named `react-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment. + +```yaml {hl_lines="22-26",linenos=true} +services: + react-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "5173:5173" + develop: + watch: + - action: sync + path: . + target: /app + + react-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-reactjs-sample + ports: + - "8080:8080" + + react-test: + build: + context: . + dockerfile: Dockerfile.dev + command: ["npm", "run", "test"] +``` + +The react-test service reuses the same `Dockerfile.dev` used for [development](#use-containers-for-reactjs-development) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. + +After completing the previous steps, your project directory should contain the following files: + +```text +├── docker-reactjs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 4: Run the tests + +To execute your test suite inside the container, run the following command from your project root: + +```console +$ docker compose run --rm react-test +``` + +This command will: + +- Start the `react-test` service defined in your `compose.yaml` file. +- Execute the `npm run test` script using the same environment as development. +- Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +### Summary + +In this section, you learned how to run unit tests for your React.js application inside a Docker container using Vitest and Docker Compose. + +What you accomplished: + +- Installed and configured Vitest and React Testing Library for testing React components. +- Created a `react-test` service in `compose.yaml` to isolate test execution. +- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. +- Ran tests inside the container using `docker compose run --rm react-test`. +- Ensured reliable, repeatable testing across environments without relying on local machine setup. + +--- + +### Related resources + +Explore official references and best practices to sharpen your Docker testing workflow: + +- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. +- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. +- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. +- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. diff --git a/content/guides/reactjs/_index.md b/content/guides/reactjs/_index.md deleted file mode 100644 index 10024e063f5e..000000000000 --- a/content/guides/reactjs/_index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: React.js language-specific guide -linkTitle: React.js -description: Containerize and develop React.js apps using Docker -keywords: getting started, React.js, react.js, docker, language, Dockerfile -summary: | - This guide explains how to containerize React.js applications using Docker. -toc_min: 1 -toc_max: 2 -languages: [js] -params: - time: 20 minutes - ---- - -The React.js language-specific guide shows you how to containerize a React.js application using Docker, following best practices for creating efficient, production-ready containers. - -[React.js](https://react.dev/) is a widely used library for building interactive user interfaces. However, managing dependencies, environments, and deployments efficiently can be complex. Docker simplifies this process by providing a consistent and containerized environment. - -> -> **Acknowledgment** -> -> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows. - ---- - -## What will you learn? - -In this guide, you will learn how to: - -- Containerize and run a React.js application using Docker. -- Set up a local development environment for React.js inside a container. -- Run tests for your React.js application within a Docker container. -- Configure a CI/CD pipeline using GitHub Actions for your containerized app. -- Deploy the containerized React.js application to a local Kubernetes cluster for testing and debugging. - -To begin, you’ll start by containerizing an existing React.js application. - ---- - -## Prerequisites - -Before you begin, make sure you're familiar with the following: - -- Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/). -- Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. -- Familiarity with [React.js](https://react.dev/) fundamentals. -- Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -Once you've completed the React.js getting started modules, you’ll be ready to containerize your own React.js application using the examples and instructions provided in this guide. diff --git a/content/guides/reactjs/configure-github-actions.md b/content/guides/reactjs/configure-github-actions.md deleted file mode 100644 index 158506c13462..000000000000 --- a/content/guides/reactjs/configure-github-actions.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 60 -keywords: CI/CD, GitHub( Actions), React.js, Next.js -description: Learn how to configure CI/CD using GitHub Actions for your React.js application. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize React.js application](containerize.md). - -You must also have: -- A [GitHub](https://github.com/signup) account. -- A verified [Docker Hub](https://hub.docker.com/signup) account. - ---- - -## Overview - -In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically: - -- Build your React.js application inside a Docker container. -- Run tests in a consistent environment. -- Push the production-ready image to [Docker Hub](https://hub.docker.com). - ---- - -## Connect your GitHub repository to Docker Hub - -To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository. - -### Step 1: Connect your GitHub repository to Docker Hub - -1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com) - 1. Go to your **Docker Hub account → Account Settings → Security**. - 2. Generate a new Access Token with **Read/Write** permissions. - 3. Name it something like `docker-reactjs-sample`. - 4. Copy and save the token — you’ll need it in Step 4. - -2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/) - 1. Go to your **Docker Hub account → Create a repository**. - 2. For the Repository Name, use something descriptive — for example: `reactjs-sample`. - 3. Once created, copy and save the repository name — you’ll need it in Step 4. - -3. Create a new [GitHub repository](https://github.com/new) for your React.js project - -4. Add Docker Hub credentials as GitHub repository secrets - - In your newly created GitHub repository: - - 1. Navigate to: - **Settings → Secrets and variables → Actions → New repository secret**. - - 2. Add the following secrets: - - | Name | Value | - |-------------------|--------------------------------| - | `DOCKER_USERNAME` | Your Docker Hub username | - | `DOCKERHUB_TOKEN` | Your Docker Hub access token (created in Step 1) | - | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2) | - - These secrets let GitHub Actions to authenticate securely with Docker Hub during automated workflows. - -5. Connect Your Local Project to GitHub - - Link your local project `docker-reactjs-sample` to the GitHub repository you just created by running the following command from your project root: - - ```console - $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git - ``` - - >[!IMPORTANT] - >Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name. - - To confirm that your local project is correctly connected to the remote GitHub repository, run: - - ```console - $ git remote -v - ``` - - You should see output similar to: - - ```console - origin https://github.com/{your-username}/{your-repository-name}.git (fetch) - origin https://github.com/{your-username}/{your-repository-name}.git (push) - ``` - - This confirms that your local repository is properly linked and ready to push your source code to GitHub. - -6. Push Your Source Code to GitHub - - Follow these steps to commit and push your local project to your GitHub repository: - - 1. Stage all files for commit. - - ```console - $ git add -A - ``` - This command stages all changes — including new, modified, and deleted files — preparing them for commit. - - - 2. Commit your changes. - - ```console - $ git commit -m "Initial commit" - ``` - This command creates a commit that snapshots the staged changes with a descriptive message. - - 3. Push the code to the `main` branch. - - ```console - $ git push -u origin main - ``` - This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch. - -Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically. - -> [!NOTE] -> Learn more about the Git commands used in this step: -> - [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit -> - [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes -> - [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository -> - [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs - ---- - -### Step 2: Set up the workflow - -Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub. - -1. Go to your repository on GitHub and select the **Actions** tab in the top menu. - -2. Select **Set up a workflow yourself** when prompted. - - This opens an inline editor to create a new workflow file. By default, it will be saved to: - `.github/workflows/main.yml` - - -3. Add the following workflow configuration to the new file: - -```yaml -name: CI/CD – React.js Application with Docker - -on: - push: - branches: [main] - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - -jobs: - build-test-push: - name: Build, Test and Push Docker Image - runs-on: ubuntu-latest - - steps: - # 1. Checkout source code - - name: Checkout source code - uses: actions/checkout@{{% param "checkout_action_version" %}} - with: - fetch-depth: 0 # Fetches full history for better caching/context - - # 2. Set up Docker Buildx - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - # 3. Cache Docker layers - - name: Cache Docker layers - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: ${{ runner.os }}-buildx- - - # 4. Cache npm dependencies - - name: Cache npm dependencies - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: ~/.npm - key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} - restore-keys: ${{ runner.os }}-npm- - - # 5. Extract metadata - - name: Extract metadata - id: meta - run: | - echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT" - echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT" - - # 6. Build dev Docker image - - name: Build Docker image for tests - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile.dev - tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest - load: true # Load to local Docker daemon for testing - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - - # 7. Run Vitest tests - - name: Run Vitest tests and generate report - run: | - docker run --rm \ - --workdir /app \ - --entrypoint "" \ - ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \ - sh -c "npm ci && npx vitest run --reporter=verbose" - env: - CI: true - NODE_ENV: test - timeout-minutes: 10 - - # 8. Login to Docker Hub - - name: Log in to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - # 9. Build and push prod image - - name: Build and push production image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile - push: true - platforms: linux/amd64,linux/arm64 - tags: | - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }} - cache-from: type=local,src=/tmp/.buildx-cache -``` - -This workflow performs the following tasks for your React.js application: -- Triggers on every `push` or `pull request` targeting the `main` branch. -- Builds a development Docker image using `Dockerfile.dev`, optimized for testing. -- Executes unit tests using Vitest inside a clean, containerized environment to ensure consistency. -- Halts the workflow immediately if any test fails — enforcing code quality. -- Caches both Docker build layers and npm dependencies for faster CI runs. -- Authenticates securely with Docker Hub using GitHub repository secrets. -- Builds a production-ready image using the `prod` stage in `Dockerfile`. -- Tags and pushes the final image to Docker Hub with both `latest` and short SHA tags for traceability. - -> [!NOTE] -> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - ---- - -### Step 3: Run the workflow - -After you've added your workflow file, it's time to trigger and observe the CI/CD process in action. - -1. Commit and push your workflow file - - Select "Commit changes…" in the GitHub editor. - - - This push will automatically trigger the GitHub Actions pipeline. - -2. Monitor the workflow execution - - 1. Go to the Actions tab in your GitHub repository. - 2. Select the workflow run to follow each step: `build`, `test`, and (if successful) `push`. - -3. Verify the Docker image on Docker Hub - - - After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories). - - You should see a new image under your repository with: - - Repository name: `${your-repository-name}` - - Tags include: - - `latest` – represents the most recent successful build; ideal for quick testing or deployment. - - `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability. - -> [!TIP] Protect your main branch -> To maintain code quality and prevent accidental direct pushes, enable branch protection rules: -> - Navigate to your **GitHub repo → Settings → Branches**. -> - Under Branch protection rules, click **Add rule**. -> - Specify `main` as the branch name. -> - Enable options like: -> - *Require a pull request before merging*. -> - *Require status checks to pass before merging*. -> -> This ensures that only tested and reviewed code is merged into `main` branch. ---- - -## Summary - -In this section, you set up a complete CI/CD pipeline for your containerized React.js application using GitHub Actions. - -Here's what you accomplished: - -- Created a new GitHub repository specifically for your project. -- Generated a secure Docker Hub access token and added it to GitHub as a secret. -- Defined a GitHub Actions workflow to: - - Build your application inside a Docker container. - - Run tests in a consistent, containerized environment. - - Push a production-ready image to Docker Hub if tests pass. -- Triggered and verified the workflow execution through GitHub Actions. -- Confirmed that your image was successfully published to Docker Hub. - -With this setup, your React.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity. - ---- - -## Related resources - -Deepen your understanding of automation and best practices for containerized apps: - -- [Introduction to GitHub Actions](/guides/gha.md) – Learn how GitHub Actions automate your workflows -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) – Set up container builds with GitHub Actions -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows -- [Compose file reference](/compose/compose-file/) – Full configuration reference for `compose.yaml` -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security - ---- - -## Next steps - -Next, learn how you can locally test and debug your React.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment. diff --git a/content/guides/reactjs/containerize.md b/content/guides/reactjs/containerize.md deleted file mode 100644 index dd5a5629e6ce..000000000000 --- a/content/guides/reactjs/containerize.md +++ /dev/null @@ -1,508 +0,0 @@ ---- -title: Containerize a React.js Application -linkTitle: Containerize -weight: 10 -keywords: react.js, node, image, initialize, build -description: Learn how to containerize a React.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability. - ---- - -## Prerequisites - -Before you begin, make sure the following tools are installed and available on your system: - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -> **New to Docker?** -> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. - ---- - -## Overview - -This guide walks you through the complete process of containerizing a React.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. - -By the end of this guide, you will: - -- Containerize a React.js application using Docker. -- Create and optimize a Dockerfile for production builds. -- Use multi-stage builds to minimize image size. -- Serve the application efficiently with a custom NGINX configuration. -- Follow best practices for building secure and maintainable Docker images. - ---- - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change -directory to a directory that you want to work in, and run the following command -to clone the git repository: - -```console -$ git clone https://github.com/kristiyan-velkov/docker-reactjs-sample -``` ---- - -## Build the Docker image - -React.js is a front-end library that compiles into static assets, so the Dockerfile is tailored to optimize how React applications are built and served in a production environment. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -### Step 1: Create the Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -> [!IMPORTANT] -> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. -> -> Official Node.js Docker Images: https://hub.docker.com/_/node - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} -Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -3. Pull the Nginx DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev - ``` - -In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images. - -```dockerfile -# ========================================= -# Stage 1: Build the React.js Application -# ========================================= - -# Use a lightweight Node.js image for building (customizable via ARG) -FROM dhi.io/node:24-alpine3.22-dev AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the React.js application (outputs to /app/dist) -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html - -# Use a non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default NGINX container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` with the following contents: - -```dockerfile -# ========================================= -# Stage 1: Build the React.js Application -# ========================================= -ARG NODE_VERSION=24.12.0-alpine -ARG NGINX_VERSION=alpine3.22 - -# Use a lightweight Node.js image for building (customizable via ARG) -FROM node:${NODE_VERSION} AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the React.js application (outputs to /app/dist) -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html - -# Use a built-in non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default NGINX container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -> [!NOTE] -> We are using nginx-unprivileged instead of the standard NGINX image to follow security best practices. -> Running as a non-root user in the final image: ->- Reduces the attack surface ->- Aligns with Docker’s recommendations for container hardening ->- Helps comply with stricter security policies in production environments - -{{< /tab >}} -{{< /tabs >}} - -### Step 2: Create the compose.yaml file - -Create a file named `compose.yaml` with the following contents: - -```yaml {collapse=true,title=compose.yaml} -services: - server: - build: - context: . - ports: - - 8080:8080 -``` - -### Step 3: Create the .dockerignore file - -The `.dockerignore` file tells Docker which files and folders to exclude when building the image. - - -> [!NOTE] ->This helps: ->- Reduce image size ->- Speed up the build process ->- Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. -> -> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). - -Create a file named `.dockerignore` with the following contents: - -```dockerignore -# Ignore dependencies and build output -node_modules/ -dist/ -out/ -.tmp/ -.cache/ - -# Ignore Vite, Webpack, and React-specific build artifacts -.vite/ -.vitepress/ -.eslintcache -.npm/ -coverage/ -jest/ -cypress/ -cypress/screenshots/ -cypress/videos/ -reports/ - -# Ignore environment and config files (sensitive data) -*.env* -*.log - -# Ignore TypeScript build artifacts (if using TypeScript) -*.tsbuildinfo - -# Ignore lockfiles (optional if using Docker for package installation) -npm-debug.log* -yarn-debug.log* -yarn-error.log* -pnpm-debug.log* - -# Ignore local development files -.git/ -.gitignore -.vscode/ -.idea/ -*.swp -.DS_Store -Thumbs.db - -# Ignore Docker-related files (to avoid copying unnecessary configs) -Dockerfile -.dockerignore -docker-compose.yml -docker-compose.override.yml - -# Ignore build-specific cache files -*.lock - -``` - -### Step 4: Create the `nginx.conf` file - -To serve your React.js application efficiently inside the container, you’ll configure NGINX with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. - -Create a file named `nginx.conf` in the root of your project directory, and add the following content: - -> [!NOTE] -> To learn more about configuring NGINX, see the [official NGINX documentation](https://nginx.org/en/docs/). - - -```nginx -worker_processes auto; - -# Store PID in /tmp (always writable) -pid /tmp/nginx.pid; - -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - # Disable logging to avoid permission issues - access_log off; - error_log /dev/stderr warn; - - # Optimize static file serving - sendfile on; - tcp_nopush on; - tcp_nodelay on; - keepalive_timeout 65; - keepalive_requests 1000; - - # Gzip compression for optimized delivery - gzip on; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml; - gzip_min_length 256; - gzip_vary on; - - server { - listen 8080; - server_name localhost; - - # Root directory where React.js build files are placed - root /usr/share/nginx/html; - index index.html; - - # Serve React.js static files with proper caching - location / { - try_files $uri /index.html; - } - - # Serve static assets with long cache expiration - location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { - expires 1y; - access_log off; - add_header Cache-Control "public, immutable"; - } - - # Handle React.js client-side routing - location /static/ { - expires 1y; - add_header Cache-Control "public, immutable"; - } - } -} -``` - -### Step 5: Build the React.js application image - -With your custom configuration in place, you're now ready to build the Docker image for your React.js application. - -The updated setup includes: - -- Optimized browser caching and gzip compression -- Secure, non-root logging to avoid permission issues -- Support for React client-side routing by redirecting unmatched routes to `index.html` - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-reactjs-sample/ -│ ├── Dockerfile -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -Now that your Dockerfile is configured, you can build the Docker image for your React.js application. - -> [!NOTE] -> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). - -Run the following command from the root of your project: - -```console -$ docker build --tag docker-reactjs-sample . -``` - -What this command does: -- Uses the Dockerfile in the current directory (.) -- Packages the application and its dependencies into a Docker image -- Tags the image as docker-reactjs-sample so you can reference it later - - -### Step 6: View local images - -After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. - -To list all locally available Docker images, run the following command: - -```console -$ docker images -``` - -Example Output: - -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-reactjs-sample latest f39b47a97156 14 seconds ago 75.8MB -``` - -This output provides key details about your images: - -- **Repository** – The name assigned to the image. -- **Tag** – A version label that helps identify different builds (e.g., latest). -- **Image ID** – A unique identifier for the image. -- **Created** – The timestamp indicating when the image was built. -- **Size** – The total disk space used by the image. - -If the build was successful, you should see `docker-reactjs-sample` image listed. - ---- - -## Run the containerized application - -In the previous step, you created a Dockerfile for your React.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. - - -Inside the `docker-reactjs-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple React.js web application. - -Press `ctrl+c` in the terminal to stop your application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-reactjs-sample` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple web application preview. - - -To confirm that the container is running, use `docker ps` command: - -```console -$ docker ps -``` - -This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. - -Example Output: - -```shell -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -88bced6ade95 docker-reactjs-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-reactjs-sample-server-1 -``` - - -To stop the application, run: - -```console -$ docker compose down -``` - - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this guide, you learned how to containerize, build, and run a React.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup. - -What you accomplished: -- Created a multi-stage `Dockerfile` that compiles the React.js application and serves the static files using Nginx. -- Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient. -- Built your Docker image using `docker build`. -- Ran the container using `docker compose up`, both in the foreground and in detached mode. -- Verified that the app was running by visiting [http://localhost:8080](http://localhost:8080). -- Learned how to stop the containerized application using `docker compose down`. - -You now have a fully containerized React.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker workflow: - -- [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds. -- [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile. -- [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images. -- [`docker compose up` CLI reference](/reference/cli/docker/compose/up/) – Start and run multi-container applications. -- [`docker compose down` CLI reference](/reference/cli/docker/compose/down/) – Stop and remove containers, networks, and volumes. - ---- - -## Next steps - -With your React.js application now containerized, you're ready to move on to the next step. - -In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine. - diff --git a/content/guides/reactjs/deploy.md b/content/guides/reactjs/deploy.md deleted file mode 100644 index 37e6a256e0a2..000000000000 --- a/content/guides/reactjs/deploy.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: Test your React.js deployment -linkTitle: Test your deployment -weight: 60 -keywords: deploy, kubernetes, react, react.js -description: Learn how to deploy locally to test and debug your Kubernetes deployment - ---- - -## Prerequisites - -Before you begin, make sure you’ve completed the following: -- Complete all the previous sections of this guide, starting with [Containerize React.js application](containerize.md). -- [Enable Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -> **New to Kubernetes?** -> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work. - ---- - -## Overview - -This section guides you through deploying your containerized React.js application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster allows you to closely simulate a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production. - ---- - -## Create a Kubernetes YAML file - -Follow these steps to define your deployment configuration: - -1. In the root of your project, create a new file named: reactjs-sample-kubernetes.yaml - -2. Open the file in your IDE or preferred text editor. - -3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](configure-github-actions.md). - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: reactjs-sample - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: reactjs-sample - template: - metadata: - labels: - app: reactjs-sample - spec: - containers: - - name: reactjs-container - image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest - imagePullPolicy: Always - ports: - - containerPort: 8080 ---- -apiVersion: v1 -kind: Service -metadata: - name: reactjs-sample-service - namespace: default -spec: - type: NodePort - selector: - app: reactjs-sample - ports: - - port: 8080 - targetPort: 8080 - nodePort: 30001 -``` - -This manifest defines two key Kubernetes resources, separated by `---`: - -- Deployment - Deploys a single replica of your React.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow - (refer to [Automate your builds with GitHub Actions](configure-github-actions.md)). - The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production React app. - -- Service (NodePort) - Exposes the deployed pod to your local machine. - It forwards traffic from port `30001` on your host to port `8080` inside the container. - This lets you access the application in your browser at [http://localhost:30001](http://localhost:30001). - -> [!NOTE] -> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - ---- - -## Deploy and check your application - -Follow these steps to deploy your containerized React.js app into a local Kubernetes cluster and verify that it’s running correctly. - -### Step 1. Apply the Kubernetes configuration - -In your terminal, navigate to the directory where your `reactjs-sample-kubernetes.yaml` file is located, then deploy the resources using: - -```console - $ kubectl apply -f reactjs-sample-kubernetes.yaml -``` - -If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created: - -```shell - deployment.apps/reactjs-sample created - service/reactjs-sample-service created -``` - -This output means that both the Deployment and the Service were successfully created and are now running inside your local cluster. - -### Step 2. Check the deployment status - -Run the following command to check the status of your deployment: - -```console - $ kubectl get deployments -``` - -You should see an output similar to: - -```shell - NAME READY UP-TO-DATE AVAILABLE AGE - reactjs-sample 1/1 1 1 14s -``` - -This confirms that your pod is up and running with one replica available. - -### Step 3. Verify the service exposure - -Check if the NodePort service is exposing your app to your local machine: - -```console -$ kubectl get services -``` - -You should see something like: - -```shell -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -reactjs-sample-service NodePort 10.100.244.65 <none> 8080:30001/TCP 1m -``` - -This output confirms that your app is available via NodePort on port 30001. - -### Step 4. Access your app in the browser - -Open your browser and navigate to [http://localhost:30001](http://localhost:30001). - -You should see your production-ready React.js Sample application running — served by your local Kubernetes cluster. - -### Step 5. Clean up Kubernetes resources - -Once you're done testing, you can delete the deployment and service using: - -```console - $ kubectl delete -f reactjs-sample-kubernetes.yaml -``` - -Expected output: - -```shell - deployment.apps "reactjs-sample" deleted - service "reactjs-sample-service" deleted -``` - -This ensures your cluster stays clean and ready for the next deployment. - ---- - -## Summary - -In this section, you learned how to deploy your React.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud. - -What you accomplished: - -- Created a Kubernetes Deployment and NodePort Service for your React.js app -- Used `kubectl apply` to deploy the application locally -- Verified the app was running and accessible at `http://localhost:30001` -- Cleaned up your Kubernetes resources after testing - ---- - -## Related resources - -Explore official references and best practices to sharpen your Kubernetes deployment workflow: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more. -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) – Use Docker Desktop’s built-in Kubernetes support for local testing and development. -- [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line. -- [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments. -- [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic. \ No newline at end of file diff --git a/content/guides/reactjs/develop.md b/content/guides/reactjs/develop.md deleted file mode 100644 index 8a8b5430dba6..000000000000 --- a/content/guides/reactjs/develop.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: Use containers for React.js development -linkTitle: Develop your app -weight: 30 -keywords: react.js, development, node -description: Learn how to develop your React.js application locally using containers. - ---- - -## Prerequisites - -Complete [Containerize React.js application](containerize.md). - ---- - -## Overview - -In this section, you'll learn how to set up both production and development environments for your containerized React.js application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch. - -You’ll learn how to: -- Configure separate containers for production and development -- Enable automatic file syncing using Compose Watch in development -- Debug and live-preview your changes in real-time without manual rebuilds - ---- - -## Automatically update services (development mode) - -Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without needing to restart or rebuild containers manually. - -## Step 1: Create a development Dockerfile - -Create a file named `Dockerfile.dev` in your project root with the following content: - -```dockerfile -# ========================================= -# Stage 1: Develop the React.js Application -# ========================================= -ARG NODE_VERSION=24.12.0-alpine - -# Use a lightweight Node.js image for development -FROM node:${NODE_VERSION} AS dev - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies -RUN --mount=type=cache,target=/root/.npm npm install - -# Copy the rest of the application source code into the container -COPY . . - -# Expose the port used by the Vite development server -EXPOSE 5173 - -# Use a default command, can be overridden in Docker compose.yml file -CMD ["npm", "run", "dev"] -``` - -This file sets up a lightweight development environment for your React app using the dev server. - - -### Step 2: Update your `compose.yaml` file - -Open your `compose.yaml` file and define two services: one for production (`react-prod`) and one for development (`react-dev`). - -Here’s an example configuration for a React.js application: - -```yaml -services: - react-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-reactjs-sample - ports: - - "8080:8080" - - react-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "5173:5173" - develop: - watch: - - action: sync - path: . - target: /app - -``` -- The `react-prod` service builds and serves your static production app using Nginx. -- The `react-dev` service runs your React development server with live reload and hot module replacement. -- `watch` triggers file sync with Compose Watch. - -> [!NOTE] -> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -### Step 3: Update vite.config.ts to ensure it works properly inside Docker - -To make Vite’s development server work reliably inside Docker, you need to update your vite.config.ts with the correct settings. - -Open the `vite.config.ts` file in your project root and update it as follows: - -```ts -/// <reference types="vitest" /> - -import { defineConfig } from "vite"; -import react from "@vitejs/plugin-react"; - -export default defineConfig({ - base: "/", - plugins: [react()], - server: { - host: true, - port: 5173, - strictPort: true, - }, -}); -``` - -> [!NOTE] -> The `server` options in `vite.config.ts` are essential for running Vite inside Docker: -> - `host: true` allows the dev server to be accessible from outside the container. -> - `port: 5173` sets a consistent development port (must match the one exposed in Docker). -> - `strictPort: true` ensures Vite fails clearly if the port is unavailable, rather than switching silently. -> -> For full details, refer to the [Vite server configuration docs](https://vitejs.dev/config/server-options.html). - - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-reactjs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 4: Start Compose Watch - -Run the following command from your project root to start your container in watch mode: - -```console -$ docker compose watch react-dev -``` - -### Step 5: Test Compose Watch with React - -To verify that Compose Watch is working correctly: - -1. Open the `src/App.tsx` file in your text editor. - -2. Locate the following line: - - ```html - <h1>Vite + React</h1> - ``` - -3. Change it to: - - ```html - <h1>Hello from Docker Compose Watch</h1> - ``` - -4. Save the file. - -5. Open your browser at [http://localhost:5173](http://localhost:5173). - -You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. - ---- - -## Summary - -In this section, you set up a complete development and production workflow for your React.js application using Docker and Docker Compose. - -Here's what you achieved: -- Created a `Dockerfile.dev` to streamline local development with hot reloading -- Defined separate `react-dev` and `react-prod` services in your `compose.yaml` file -- Enabled real-time file syncing using Compose Watch for a smoother development experience -- Verified that live updates work seamlessly by modifying and previewing a component - -With this setup, you're now equipped to build, run, and iterate on your React.js app entirely within containers—efficiently and consistently across environments. - ---- - -## Related resources - -Deepen your knowledge and improve your containerized development workflow with these guides: - -- [Using Compose Watch](/manuals/compose/how-tos/file-watch.md) – Automatically sync source changes during development -- [Multi-stage builds](/manuals/build/building/multi-stage.md) – Create efficient, production-ready Docker images -- [Dockerfile best practices](/build/building/best-practices/) – Write clean, secure, and optimized Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [Docker volumes](/storage/volumes/) – Persist and manage data between container runs - -## Next steps - -In the next section, you'll learn how to run unit tests for your React.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup. diff --git a/content/guides/reactjs/run-tests.md b/content/guides/reactjs/run-tests.md deleted file mode 100644 index dc72025d43f4..000000000000 --- a/content/guides/reactjs/run-tests.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Run React.js tests in a container -linkTitle: Run your tests -weight: 40 -keywords: react.js, react, test, vitest -description: Learn how to run your React.js tests in a container. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize React.js application](containerize.md). - -## Overview - -Testing is a critical part of the development process. In this section, you'll learn how to: - -- Run unit tests using Vitest inside a Docker container. -- Use Docker Compose to run tests in an isolated, reproducible environment. - -You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — along with [Testing Library](https://testing-library.com/) for assertions. - ---- - -## Run tests during development - -`docker-reactjs-sample` application includes a sample test file at location: - -```console -$ src/App.test.tsx -``` - -This file uses Vitest and React Testing Library to verify the behavior of `App` component. - -### Step 1: Install Vitest and React Testing Library - -If you haven’t already added the necessary testing tools, install them by running: - -```console -$ npm install --save-dev vitest @testing-library/react @testing-library/jest-dom jsdom -``` - -Then, update the scripts section of your `package.json` file to include the following: - -```json -"scripts": { - "test": "vitest run" -} -``` - ---- - -### Step 2: Configure Vitest - -Update `vitest.config.ts` file in your project root with the following configuration: - -```ts {hl_lines="14-18",linenos=true} -/// <reference types="vitest" /> - -import { defineConfig } from "vite"; -import react from "@vitejs/plugin-react"; - -export default defineConfig({ - base: "/", - plugins: [react()], - server: { - host: true, - port: 5173, - strictPort: true, - }, - test: { - environment: "jsdom", - setupFiles: "./src/setupTests.ts", - globals: true, - }, -}); -``` - -> [!NOTE] -> The `test` options in `vitest.config.ts` are essential for reliable testing inside Docker: -> - `environment: "jsdom"` simulates a browser-like environment for rendering and DOM interactions. -> - `setupFiles: "./src/setupTests.ts"` loads global configuration or mocks before each test file (optional but recommended). -> - `globals: true` enables global test functions like `describe`, `it`, and `expect` without importing them. -> -> For more details, see the official [Vitest configuration docs](https://vitest.dev/config/). - -### Step 3: Update compose.yaml - -Add a new service named `react-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment. - -```yaml {hl_lines="22-26",linenos=true} -services: - react-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "5173:5173" - develop: - watch: - - action: sync - path: . - target: /app - - react-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-reactjs-sample - ports: - - "8080:8080" - - react-test: - build: - context: . - dockerfile: Dockerfile.dev - command: ["npm", "run", "test"] - -``` - -The react-test service reuses the same `Dockerfile.dev` used for [development](develop.md) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. - - -After completing the previous steps, your project directory should contain the following files: - -```text -├── docker-reactjs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 4: Run the tests - -To execute your test suite inside the container, run the following command from your project root: - -```console -$ docker compose run --rm react-test -``` - -This command will: -- Start the `react-test` service defined in your `compose.yaml` file. -- Execute the `npm run test` script using the same environment as development. -- Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this section, you learned how to run unit tests for your React.js application inside a Docker container using Vitest and Docker Compose. - -What you accomplished: -- Installed and configured Vitest and React Testing Library for testing React components. -- Created a `react-test` service in `compose.yaml` to isolate test execution. -- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. -- Ran tests inside the container using `docker compose run --rm react-test`. -- Ensured reliable, repeatable testing across environments without relying on local machine setup. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker testing workflow: - -- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. ---- - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your React.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow. diff --git a/content/guides/ros2.md b/content/guides/ros2.md new file mode 100644 index 000000000000..2717f87995eb --- /dev/null +++ b/content/guides/ros2.md @@ -0,0 +1,462 @@ +--- +title: Introduction to ROS 2 Development with Docker +linkTitle: ROS 2 +description: Learn how to containerize and develop ROS 2 applications using Docker. +keywords: ros2, robotics, devcontainers, python, cpp, Dockerfile, rviz +summary: | + This guide details how to containerize ROS 2 applications using Docker. +aliases: + - /guides/ros2/develop/ + - /guides/ros2/run-ros2/ + - /guides/ros2/turtlesim-example/ +params: + tags: [deployment] + time: 30 minutes + image: /images/guides/ros2.jpg + featured: false +--- + + +> **Acknowledgment** +> +> This guide is a community contribution. Docker would like to thank +> [Shakirth Anisha](https://www.linkedin.com/in/shakirth-anisha/) for her contribution +> to this guide. + +[ROS 2](https://www.ros.org/) is a set of software libraries and tools for building robot applications. It uses Data Distribution Service (DDS) for real-time, secure communication between distributed nodes, making it ideal for robotics and autonomous systems. + +--- + +## What will you learn? + +In this guide, you'll learn how to: + +- Use official ROS 2 base images from Docker Hub +- Run ROS 2 in an Ubuntu container +- Install ROS 2 packages and dependencies +- Set up a development container for local development +- Run a complete end-to-end example with Turtlesim + +## Prerequisites + +Before you begin, make sure you're familiar with the following: + +- [Docker Desktop](https://docs.docker.com/desktop/): You must have Docker Desktop installed and running. +- [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container.md): You must understand core Docker concepts, such as images and containers. +- [ROS 2 concepts](https://www.ros.org): Basic understanding of concepts like nodes, packages, topics, and services. + +## What's next? + +Start by setting up your ROS 2 development environment using Docker and dev containers. + +## Run ROS 2 in a container + +### Overview + +In this section, you will run ROS 2 in an isolated Docker container using official ROS 2 images, verify that ROS 2 is working, and install additional ROS 2 packages for development and testing. + +--- + +### Run ROS 2 in a container + +The fastest way to get started with ROS 2 is to use the [official Docker image](https://hub.docker.com/_/ros/). To pull an image, start a container, and open an interactive bash shell: + +1. Pull and run the official ROS 2 Docker image: + + ```console + $ docker run -it ros:humble + ``` + + This guide uses the Humble distribution. You can replace `humble` with another supported distribution such as `rolling`, `jazzy`, or `iron`. + + > [!NOTE] + > + > This environment is temporary and does not maintain persistence. + > Any files you create or packages you install will be deleted once the container is stopped or removed. + +2. Verify ROS 2 is working: + + ```console + $ echo $ROS_DISTRO + ``` + + You should see output similar to: + + ```text + humble + ``` + +### Install ROS 2 packages + +The official ROS 2 images include core packages. To install additional packages, use the `apt` package manager: + +1. Update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install the desired package: + + ```console + $ sudo apt install $PACKAGE_NAME + ``` + +Replace `$PACKAGE_NAME` with any package you want to install. + +Some commonly used packages include: + +- `ros-humble-turtlesim` - Visualization and simulation tool +- `ros-humble-rviz2` - 3D visualization tool +- `ros-humble-rqt` - Qt-based ROS graphical tools +- `ros-humble-demo-nodes-cpp` - C++ demo nodes +- `ros-humble-demo-nodes-py` - Python demo nodes +- `ros-humble-colcon-common-extensions` - Build system extensions + +### Summary + +In this section, you pulled an official ROS 2 Docker image, launched an interactive session, and extended the container's capabilities by installing additional ROS 2 packages using apt. + +### Next steps + +In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions. + +## Build and develop a ROS 2 workspace + +### Overview + +In this section, you will set up a ROS 2 workspace using Docker and development containers, review the workspace layout, open the workspace in Visual Studio Code, and edit and build ROS 2 projects inside the container. + +--- + +### Get the sample ROS 2 workspace + +A consistent workspace simplifies managing ROS 2 projects and build artifacts across different distributions. + +1. Open a terminal and clone the sample workspace repository: + + ```console + $ git clone https://github.com/shakirth-anisha/docker-ros2-workspace.git + $ cd docker-ros2-workspace + + ``` + + Moving forward, Linux users can use the `ws_linux` folder, and macOS users can use `ws_mac`. + +2. Verify the workspace structure: + + ```text + ws_linux/ + ├── compose.yml + ├── Dockerfile + └── src/ + ├── package1/ + └── package2/ + + ws_mac/ + ├── compose.yml + ├── Dockerfile + └── src/ + ├── package1/ + └── package2/ + + ``` + +3. Explore the workspace layout + +- `compose.yml` : Defines how Docker Compose builds and runs the ROS 2 container, including mounts, environment variables, and networking settings. +- `Dockerfile` : Builds the ROS 2 development image. It uses an official ROS 2 base image, creates a non-root development user, and installs required system and ROS 2 dependencies. +- `src` : Contains all ROS 2 packages. This directory is mounted into the container as the active workspace. + +### Open and build the container + +1. Execute the following commands to build and start the container: + + For Linux: + + ```console + $ cd ws_linux + $ docker compose up -d + $ docker compose exec ros2 /bin/bash + ``` + + For macOS: + + ```console + $ cd ws_mac + $ docker compose up -d + $ docker compose exec ros2 /bin/bash + ``` + + This command builds the Docker image defined in your `Dockerfile` and starts the container in the background. + + > [!NOTE] + > + > Building the image may take several minutes during the first run + > as the CLI pulls the base ROS 2 image and installs required dependencies. + > Subsequent starts will be significantly faster. + +2. Once the container is running, execute commands inside it using `exec`: + + ```console + $ docker compose exec ros2 /bin/bash + ``` + +3. Inside the container terminal, verify the environment: + +```console +$ echo $ROS_VERSION +$ which colcon +``` + +All commands should execute successfully inside the container. + +### Switch ROS 2 distributions + +Update the base image in your `Dockerfile`, changing from `humble` to another distribution like `rolling`, `jazzy`, or `iron`. + +### Summary + +In this section, you learned how to create a structured workspace, write a Dockerfile with development tools, and configure a Docker Compose setup. Your ROS 2 development environment is now ready with a consistent, reproducible setup across any machine. + +### Next steps + +In the next section, you'll run a complete end-to-end example with Turtlesim. + +## Run a complete example with Turtlesim + +### Overview + +Turtlesim is a simple simulation tool that demonstrates fundamental ROS 2 concepts such as nodes, topics, and services. In this section, you'll run a complete example with Turtlesim, control the turtle, monitor topics, and visualize the system with rqt. + +--- + +### Configure display forwarding + +#### Linux + +Allow Docker access to your X server: + +```console +$ xhost +local:docker +``` + +#### macOS + +On macOS, use XQuartz to provide X11 support. Install XQuartz using Homebrew: + +1. Install XQuartz using Homebrew: + + ```console + $ brew install --cask xquartz + ``` + +2. Open XQuartz from Applications, then navigate to `Preferences > Security` and enable `Allow connections from network clients`. Restart your computer to ensure the changes take effect. + +3. After rebooting, open a terminal and allow local connections: + + ```console + $ defaults write org.xquartz.X11 nolisten_tcp -bool false + $ xhost +localhost + $ xhost + 127.0.0.1 + ``` + +### Start the container + +Start the container using the same Docker Compose setup from the workspace section. + +For Linux: + +```console +$ cd ws_linux +$ docker compose up -d +$ docker compose exec ros2 /bin/bash +``` + +For macOS: + +```console +$ cd ws_mac +$ docker compose up -d +$ docker compose exec ros2 /bin/bash +``` + +### Install and run Turtlesim + +Inside the container, install the Turtlesim package: + +1. Update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install the Turtlesim package: + + ```console + $ sudo apt install -y ros-humble-turtlesim + ``` + +3. Run the Turtlesim node: + + ```console + $ ros2 run turtlesim turtlesim_node + ``` + +A window should appear on your desktop showing a turtle in a grid. + +### Control the turtle + +1. Open a new terminal and connect to the same container, then start the keyboard teleop node: + + ```console + $ ros2 run turtlesim turtle_teleop_key + ``` + + This node allows you to control the turtle using your keyboard. Use the arrow keys to move the turtle forward, backward, left, and right. Press `Ctrl+C` to stop the teleop node. + +2. Move the turtle around the window. You should see it draw a path as it moves. + +### Monitor topics + +1. Open another terminal and connect to the same container, then list all active topics: + + ```console + $ ros2 topic list + ``` + + You should see output similar to the following: + + ```text + /parameter_events + /rosout + /turtle1/cmd_vel + /turtle1/color_sensor + /turtle1/pose + ``` + +2. Get information about a specific topic: + + ```console + $ ros2 topic info /turtle1/pose + ``` + + You'll see the topic type and which nodes publish and subscribe to it. + +### Visualize the system with rqt + +1. Open another terminal and connect to the same container, then update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install rqt: + + ```console + $ sudo apt install -y 'ros-humble-rqt*' + ``` + +3. Start rqt: + + ```console + $ ros2 run rqt_gui rqt_gui + ``` + +An rqt window should appear. rqt provides several useful plugins for visualizing and monitoring ROS 2 systems. + +#### Node Graph + +You can explore the node graph by navigating to **Plugins > Introspection > Node Graph**. A new tab opens showing nodes and topics with connections illustrated as lines. This visualization demonstrates how the teleop node sends velocity commands to the Turtlesim node, and how the Turtlesim node publishes position data back through topics. + +#### Topic Monitor + +You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Select the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands. + +#### Service Caller + +You can call services from rqt using **Plugins > Services > Service Caller**. Select a service such as `/turtle1/teleport_absolute`, enter values for the request fields, and select **Call** to send the request. + +#### Plots + +To plot topic data over time navigate to **Plugins > Visualization > Plot**. For example, in the Plot window, type `/turtle1/pose/x` in the Topic field and press Enter. Move the turtle and watch the X position displayed as a graph over time. + +### Call ROS 2 services + +Turtlesim provides services for actions such as repositioning the turtle and clearing the path. + +1. List available services: + + ```console + $ ros2 service list + ``` + + You should see services such as `/turtle1/set_pen` (to change pen color and width), `/turtle1/teleport_absolute` (to move the turtle to a specific position), and `/turtle1/teleport_relative` (to move the turtle relative to its current position). + +2. Teleport the turtle to a new position: + + ```console + $ ros2 service call /turtle1/teleport_absolute turtlesim/srv/TeleportAbsolute " + x: 1.0 + y: 3.0 + theta: 0.0 + " + ``` + + The turtle should instantly move to the specified position (1.0, 3.0). + +### Create a simple publisher + +1. Create a Python script that publishes velocity commands to control the turtle programmatically. In a new terminal, create a file called `move_turtle.py`: + + ```python + import rclpy + from geometry_msgs.msg import Twist + import time + + def main(): + rclpy.init() + node = rclpy.create_node('turtle_mover') + publisher = node.create_publisher(Twist, 'turtle1/cmd_vel', 10) + + # Create a twist message + msg = Twist() + msg.linear.x = 2.0 # Move forward at 2 m/s + msg.angular.z = 1.0 # Rotate at 1 rad/s + + # Publish the message + for i in range(50): + publisher.publish(msg) + time.sleep(0.1) + + # Stop the turtle + msg.linear.x = 0.0 + msg.angular.z = 0.0 + publisher.publish(msg) + + node.destroy_node() + rclpy.shutdown() + + if __name__ == '__main__': + main() + ``` + +2. Run the script: + + ```console + $ python3 move_turtle.py + ``` + + The turtle should move in a circular motion for 5 seconds and then stop. + +### Summary + +In this section, you configured display forwarding, used the Turtlesim nodes, inspected nodes and topics, and visualized the system using rqt. Finally, you interacted with ROS 2 services and created a simple publisher to move the turtle programmatically. + +These fundamental concepts apply directly to real-world robotics applications with actual sensors and actuators. + +### Related resources + +- [ROS 2 Turtlesim tutorials](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html) +- [ROS 2 Concepts](https://docs.ros.org/en/humble/Concepts.html) +- [Geometry Messages](https://github.com/ros2/geometry2/tree/humble/geometry_msgs) diff --git a/content/guides/ros2/_index.md b/content/guides/ros2/_index.md deleted file mode 100644 index f40208c712a6..000000000000 --- a/content/guides/ros2/_index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Introduction to ROS 2 Development with Docker -linkTitle: ROS 2 -description: Learn how to containerize and develop ROS 2 applications using Docker. -keywords: ros2, robotics, devcontainers, python, cpp, Dockerfile, rviz -summary: | - This guide details how to containerize ROS 2 applications using Docker. -toc_min: 1 -toc_max: 2 -languages: [python] -tags: [frameworks] -params: - time: 30 minutes - image: /images/guides/ros2.jpg - featured: true ---- - -> **Acknowledgment** -> -> This guide is a community contribution. Docker would like to thank -> [Shakirth Anisha](https://www.linkedin.com/in/shakirth-anisha/) for her contribution -> to this guide. - -[ROS 2](https://www.ros.org/) is a set of software libraries and tools for building robot applications. It uses Data Distribution Service (DDS) for real-time, secure communication between distributed nodes, making it ideal for robotics and autonomous systems. - ---- - -## What will you learn? - -In this guide, you'll learn how to: - -- Use official ROS 2 base images from Docker Hub -- Run ROS 2 in an Ubuntu container -- Install ROS 2 packages and dependencies -- Set up a development container for local development -- Run a complete end-to-end example with Turtlesim - -## Prerequisites - -Before you begin, make sure you're familiar with the following: - -- [Docker Desktop](https://docs.docker.com/desktop/): You must have Docker Desktop installed and running. -- [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container.md): You must understand core Docker concepts, such as images and containers. -- [ROS 2 concepts](https://www.ros.org): Basic understanding of concepts like nodes, packages, topics, and services. - -## What's next? - -Start by setting up your ROS 2 development environment using Docker and dev containers. diff --git a/content/guides/ros2/develop.md b/content/guides/ros2/develop.md deleted file mode 100644 index 23c663cedb70..000000000000 --- a/content/guides/ros2/develop.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Build and develop a ROS 2 workspace -linkTitle: Set Up ROS 2 workspace -weight: 15 -keywords: ros2, robotics, docker, dockerfile, devcontainer, vscode, workspace -description: Learn how to develop ROS 2 applications using a Docker based workspace and development containers. ---- - -## Overview - -In this section, you will set up a ROS 2 workspace using Docker and development containers, review the workspace layout, open the workspace in Visual Studio Code, and edit and build ROS 2 projects inside the container. - ---- - -## Get the sample ROS 2 workspace - -A consistent workspace simplifies managing ROS 2 projects and build artifacts across different distributions. - -1. Open a terminal and clone the sample workspace repository: - - ```console - $ git clone https://github.com/shakirth-anisha/docker-ros2-workspace.git - $ cd docker-ros2-workspace - - ``` - - Moving forward, Linux users can use the `ws_linux` folder, and macOS users can use `ws_mac`. - -2. Verify the workspace structure: - - ```text - ws_linux/ - ├── compose.yml - ├── Dockerfile - └── src/ - ├── package1/ - └── package2/ - - ws_mac/ - ├── compose.yml - ├── Dockerfile - └── src/ - ├── package1/ - └── package2/ - - ``` - -3. Explore the workspace layout - -- `compose.yml` : Defines how Docker Compose builds and runs the ROS 2 container, including mounts, environment variables, and networking settings. -- `Dockerfile` : Builds the ROS 2 development image. It uses an official ROS 2 base image, creates a non-root development user, and installs required system and ROS 2 dependencies. -- `src` : Contains all ROS 2 packages. This directory is mounted into the container as the active workspace. - -## Open and build the container - -1. Execute the following commands to build and start the container: - - For Linux: - - ```console - $ cd ws_linux - $ docker compose up -d - $ docker compose exec ros2 /bin/bash - ``` - - For macOS: - - ```console - $ cd ws_mac - $ docker compose up -d - $ docker compose exec ros2 /bin/bash - ``` - - This command builds the Docker image defined in your `Dockerfile` and starts the container in the background. - - > [!NOTE] - > - > Building the image may take several minutes during the first run - > as the CLI pulls the base ROS 2 image and installs required dependencies. - > Subsequent starts will be significantly faster. - -2. Once the container is running, execute commands inside it using `exec`: - - ```console - $ docker compose exec ros2 /bin/bash - ``` - -3. Inside the container terminal, verify the environment: - -```console -$ echo $ROS_VERSION -$ which colcon -``` - -All commands should execute successfully inside the container. - -## Switch ROS 2 distributions - -Update the base image in your `Dockerfile`, changing from `humble` to another distribution like `rolling`, `jazzy`, or `iron`. - -## Summary - -In this section, you learned how to create a structured workspace, write a Dockerfile with development tools, and configure a Docker Compose setup. Your ROS 2 development environment is now ready with a consistent, reproducible setup across any machine. - -## Next steps - -In the next section, you'll run a complete end-to-end example with Turtlesim. diff --git a/content/guides/ros2/run-ros2.md b/content/guides/ros2/run-ros2.md deleted file mode 100644 index 60313d819f24..000000000000 --- a/content/guides/ros2/run-ros2.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Run ROS 2 in a container -linkTitle: Run ROS 2 -weight: 10 -keywords: ros2, robotics, docker, dockerfile, devcontainer, vscode, workspace -description: Run ROS 2 in an isolated Docker container using official ROS 2 images and install additional ROS 2 packages. ---- - -## Overview - -In this section, you will run ROS 2 in an isolated Docker container using official ROS 2 images, verify that ROS 2 is working, and install additional ROS 2 packages for development and testing. - ---- - -## Run ROS 2 in a container - -The fastest way to get started with ROS 2 is to use the [official Docker image](https://hub.docker.com/_/ros/). To pull an image, start a container, and open an interactive bash shell: - -1. Pull and run the official ROS 2 Docker image: - - ```console - $ docker run -it ros:humble - ``` - - This guide uses the Humble distribution. You can replace `humble` with another supported distribution such as `rolling`, `jazzy`, or `iron`. - - > [!NOTE] - > - > This environment is temporary and does not maintain persistence. - > Any files you create or packages you install will be deleted once the container is stopped or removed. - -2. Verify ROS 2 is working: - - ```console - $ echo $ROS_DISTRO - ``` - - You should see output similar to: - - ```text - humble - ``` - -## Install ROS 2 packages - -The official ROS 2 images include core packages. To install additional packages, use the `apt` package manager: - -1. Update the package manager: - - ```console - $ sudo apt update - ``` - -2. Install the desired package: - - ```console - $ sudo apt install $PACKAGE_NAME - ``` - -Replace `$PACKAGE_NAME` with any package you want to install. - -Some commonly used packages include: - -- `ros-humble-turtlesim` - Visualization and simulation tool -- `ros-humble-rviz2` - 3D visualization tool -- `ros-humble-rqt` - Qt-based ROS graphical tools -- `ros-humble-demo-nodes-cpp` - C++ demo nodes -- `ros-humble-demo-nodes-py` - Python demo nodes -- `ros-humble-colcon-common-extensions` - Build system extensions - -## Summary - -In this section, you pulled an official ROS 2 Docker image, launched an interactive session, and extended the container's capabilities by installing additional ROS 2 packages using apt. - -## Next steps - -In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions. diff --git a/content/guides/ros2/turtlesim-example.md b/content/guides/ros2/turtlesim-example.md deleted file mode 100644 index 65abce3f7b98..000000000000 --- a/content/guides/ros2/turtlesim-example.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Run a complete example with Turtlesim -linkTitle: Turtlesim example -weight: 20 -keywords: ros2, turtlesim, example, nodes, topics, teleop -description: Run a complete end-to-end ROS 2 example with Turtlesim. ---- - -## Overview - -Turtlesim is a simple simulation tool that demonstrates fundamental ROS 2 concepts such as nodes, topics, and services. In this section, you'll run a complete example with Turtlesim, control the turtle, monitor topics, and visualize the system with rqt. - ---- - -## Configure display forwarding - -### Linux - -Allow Docker access to your X server: - -```console -$ xhost +local:docker -``` - -### macOS - -On macOS, use XQuartz to provide X11 support. Install XQuartz using Homebrew: - -1. Install XQuartz using Homebrew: - - ```console - $ brew install --cask xquartz - ``` - -2. Open XQuartz from Applications, then navigate to `Preferences > Security` and enable `Allow connections from network clients`. Restart your computer to ensure the changes take effect. - -3. After rebooting, open a terminal and allow local connections: - - ```console - $ defaults write org.xquartz.X11 nolisten_tcp -bool false - $ xhost +localhost - $ xhost + 127.0.0.1 - ``` - -## Start the container - -Start the container using the same Docker Compose setup from the workspace section. - -For Linux: - -```console -$ cd ws_linux -$ docker compose up -d -$ docker compose exec ros2 /bin/bash -``` - -For macOS: - -```console -$ cd ws_mac -$ docker compose up -d -$ docker compose exec ros2 /bin/bash -``` - -## Install and run Turtlesim - -Inside the container, install the Turtlesim package: - -1. Update the package manager: - - ```console - $ sudo apt update - ``` - -2. Install the Turtlesim package: - - ```console - $ sudo apt install -y ros-humble-turtlesim - ``` - -3. Run the Turtlesim node: - - ```console - $ ros2 run turtlesim turtlesim_node - ``` - -A window should appear on your desktop showing a turtle in a grid. - -## Control the turtle - -1. Open a new terminal and connect to the same container, then start the keyboard teleop node: - - ```console - $ ros2 run turtlesim turtle_teleop_key - ``` - - This node allows you to control the turtle using your keyboard. Use the arrow keys to move the turtle forward, backward, left, and right. Press `Ctrl+C` to stop the teleop node. - -2. Move the turtle around the window. You should see it draw a path as it moves. - -## Monitor topics - -1. Open another terminal and connect to the same container, then list all active topics: - - ```console - $ ros2 topic list - ``` - - You should see output similar to the following: - - ```text - /parameter_events - /rosout - /turtle1/cmd_vel - /turtle1/color_sensor - /turtle1/pose - ``` - -2. Get information about a specific topic: - - ```console - $ ros2 topic info /turtle1/pose - ``` - - You'll see the topic type and which nodes publish and subscribe to it. - -## Visualize the system with rqt - -1. Open another terminal and connect to the same container, then update the package manager: - - ```console - $ sudo apt update - ``` - -2. Install rqt: - - ```console - $ sudo apt install -y 'ros-humble-rqt*' - ``` - -3. Start rqt: - - ```console - $ ros2 run rqt_gui rqt_gui - ``` - -An rqt window should appear. rqt provides several useful plugins for visualizing and monitoring ROS 2 systems. - -### Node Graph - -You can explore the node graph by navigating to **Plugins > Introspection > Node Graph**. A new tab opens showing nodes and topics with connections illustrated as lines. This visualization demonstrates how the teleop node sends velocity commands to the Turtlesim node, and how the Turtlesim node publishes position data back through topics. - -### Topic Monitor - -You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Select the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands. - -### Service Caller - -You can call services from rqt using **Plugins > Services > Service Caller**. Select a service such as `/turtle1/teleport_absolute`, enter values for the request fields, and select **Call** to send the request. - -### Plots - -To plot topic data over time navigate to **Plugins > Visualization > Plot**. For example, in the Plot window, type `/turtle1/pose/x` in the Topic field and press Enter. Move the turtle and watch the X position displayed as a graph over time. - -## Call ROS 2 services - -Turtlesim provides services for actions such as repositioning the turtle and clearing the path. - -1. List available services: - - ```console - $ ros2 service list - ``` - - You should see services such as `/turtle1/set_pen` (to change pen color and width), `/turtle1/teleport_absolute` (to move the turtle to a specific position), and `/turtle1/teleport_relative` (to move the turtle relative to its current position). - -2. Teleport the turtle to a new position: - - ```console - $ ros2 service call /turtle1/teleport_absolute turtlesim/srv/TeleportAbsolute " - x: 1.0 - y: 3.0 - theta: 0.0 - " - ``` - - The turtle should instantly move to the specified position (1.0, 3.0). - -## Create a simple publisher - -1. Create a Python script that publishes velocity commands to control the turtle programmatically. In a new terminal, create a file called `move_turtle.py`: - - ```python - import rclpy - from geometry_msgs.msg import Twist - import time - - def main(): - rclpy.init() - node = rclpy.create_node('turtle_mover') - publisher = node.create_publisher(Twist, 'turtle1/cmd_vel', 10) - - # Create a twist message - msg = Twist() - msg.linear.x = 2.0 # Move forward at 2 m/s - msg.angular.z = 1.0 # Rotate at 1 rad/s - - # Publish the message - for i in range(50): - publisher.publish(msg) - time.sleep(0.1) - - # Stop the turtle - msg.linear.x = 0.0 - msg.angular.z = 0.0 - publisher.publish(msg) - - node.destroy_node() - rclpy.shutdown() - - if __name__ == '__main__': - main() - ``` - -2. Run the script: - - ```console - $ python3 move_turtle.py - ``` - - The turtle should move in a circular motion for 5 seconds and then stop. - -## Summary - -In this section, you configured display forwarding, used the Turtlesim nodes, inspected nodes and topics, and visualized the system using rqt. Finally, you interacted with ROS 2 services and created a simple publisher to move the turtle programmatically. - -These fundamental concepts apply directly to real-world robotics applications with actual sensors and actuators. - -## Related resources - -- [ROS 2 Turtlesim tutorials](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html) -- [ROS 2 Concepts](https://docs.ros.org/en/humble/Concepts.html) -- [Geometry Messages](https://github.com/ros2/geometry2/tree/humble/geometry_msgs) diff --git a/content/guides/ruby.md b/content/guides/ruby.md new file mode 100644 index 000000000000..dd0be6677306 --- /dev/null +++ b/content/guides/ruby.md @@ -0,0 +1,590 @@ +--- +title: Ruby on Rails language-specific guide +linkTitle: Ruby +description: Containerize Ruby on Rails apps using Docker +keywords: Docker, getting started, ruby, language +summary: | + This guide explains how to containerize Ruby on Rails applications using + Docker. +aliases: + - /language/ruby/ + - /guides/language/ruby/ + - /language/ruby/build-images/ + - /language/ruby/run-containers/ + - /language/ruby/containerize/ + - /language/ruby/configure-ci-cd/ + - /guides/language/ruby/configure-ci-cd/ + - /language/ruby/develop/ + - /language/ruby/deploy/ + - /guides/ruby/configure-github-actions/ + - /guides/ruby/containerize/ + - /guides/ruby/deploy/ + - /guides/ruby/develop/ +params: + tags: [languages] + time: 20 minutes +--- + +The Ruby language-specific guide teaches you how to containerize a Ruby on Rails application using Docker. In this guide, you’ll learn how to: + +- Containerize and run a Ruby on Rails application +- Set up a local environment to develop a Ruby on Rails application using containers + +Start by containerizing an existing Ruby on Rails application. + +## Containerize a Ruby on Rails application + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [Git client](https://git-scm.com/downloads). The examples in this section show the Git CLI, but you can use any client. + +### Overview + +This section walks you through containerizing and running a [Ruby on Rails](https://rubyonrails.org/) application. + +Starting from Rails 7.1 [Docker is supported out of the box](https://guides.rubyonrails.org/7_1_release_notes.html#generate-dockerfiles-for-new-rails-applications). This means that you will get a `Dockerfile`, `.dockerignore` and `bin/docker-entrypoint` files generated for you when you create a new Rails application. + +If you have an existing Rails application, you will need to create the Docker assets manually from the examples below. + +### 1. Create Docker assets + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +Rails 7.1 and newer generates multistage Dockerfile out of the box. Following are two versions of such a file: one using Docker Hardened Images (DHIs) and another using the Docker Official Image (DOIs). Although the Dockerfile is generated automatically, understanding its purpose and functionality is important. Reviewing the following example is highly recommended. + +[Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in. + +Multistage Dockerfiles help create smaller, more efficient images by separating build and runtime dependencies, ensuring only necessary components are included in the final image. Read more in the [Multi-stage builds guide](/get-started/docker-concepts/building-images/multi-stage-builds/). + +{{< tabs >}} +{{< tab name="Using DHIs" >}} + +You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. + +```dockerfile {title=Dockerfile} +# syntax=docker/dockerfile:1 +# check=error=true + +# This Dockerfile is designed for production, not development. +# docker build -t app . +# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app + +# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html + +# Make sure RUBY_VERSION matches the Ruby version in .ruby-version +ARG RUBY_VERSION=3.4.8 +FROM dhi.io/ruby:$RUBY_VERSION-dev AS base + +# Rails app lives here +WORKDIR /rails + +# Install base packages +# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL +RUN apt-get update -qq && \ + apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \ + rm -rf /var/lib/apt/lists /var/cache/apt/archives + +# Set production environment +ENV RAILS_ENV="production" \ + BUNDLE_DEPLOYMENT="1" \ + BUNDLE_PATH="/usr/local/bundle" \ + BUNDLE_WITHOUT="development" + +# Throw-away build stage to reduce size of final image +FROM base AS build + +# Install packages needed to build gems +RUN apt-get update -qq && \ + apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \ + rm -rf /var/lib/apt/lists /var/cache/apt/archives + +# Install JavaScript dependencies and Node.js for asset compilation +# +# Uncomment the following lines if you are using NodeJS need to compile assets +# +# ARG NODE_VERSION=18.12.0 +# ARG YARN_VERSION=1.22.19 +# ENV PATH=/usr/local/node/bin:$PATH +# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \ +# /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \ +# npm install -g yarn@$YARN_VERSION && \ +# npm install -g mjml && \ +# rm -rf /tmp/node-build-master + +# Install application gems +COPY Gemfile Gemfile.lock ./ +RUN bundle install && \ + rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \ + bundle exec bootsnap precompile --gemfile + +# Install node modules +# +# Uncomment the following lines if you are using NodeJS need to compile assets +# +# COPY package.json yarn.lock ./ +# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \ +# yarn install --frozen-lockfile + +# Copy application code +COPY . . + +# Precompile bootsnap code for faster boot times +RUN bundle exec bootsnap precompile app/ lib/ + +# Precompiling assets for production without requiring secret RAILS_MASTER_KEY +RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile + +# Final stage for app image +FROM base + +# Copy built artifacts: gems, application +COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}" +COPY --from=build /rails /rails + +# Run and own only the runtime files as a non-root user for security +RUN groupadd --system --gid 1000 rails && \ + useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \ + chown -R rails:rails db log storage tmp +USER 1000:1000 + +# Entrypoint prepares the database. +ENTRYPOINT ["/rails/bin/docker-entrypoint"] + +# Start server via Thruster by default, this can be overwritten at runtime +EXPOSE 80 +CMD ["./bin/thrust", "./bin/rails", "server"] +``` + +{{< /tab >}} +{{< tab name="Using DOIs" >}} + +```dockerfile {title=Dockerfile} +# syntax=docker/dockerfile:1 +# check=error=true + +# This Dockerfile is designed for production, not development. +# docker build -t app . +# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app + +# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html + +# Make sure RUBY_VERSION matches the Ruby version in .ruby-version +ARG RUBY_VERSION=3.4.8 +FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base + +# Rails app lives here +WORKDIR /rails + +# Install base packages +# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL +RUN apt-get update -qq && \ + apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \ + rm -rf /var/lib/apt/lists /var/cache/apt/archives + +# Set production environment +ENV RAILS_ENV="production" \ + BUNDLE_DEPLOYMENT="1" \ + BUNDLE_PATH="/usr/local/bundle" \ + BUNDLE_WITHOUT="development" + +# Throw-away build stage to reduce size of final image +FROM base AS build + +# Install packages needed to build gems +RUN apt-get update -qq && \ + apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \ + rm -rf /var/lib/apt/lists /var/cache/apt/archives + +# Install JavaScript dependencies and Node.js for asset compilation +# +# Uncomment the following lines if you are using NodeJS need to compile assets +# +# ARG NODE_VERSION=18.12.0 +# ARG YARN_VERSION=1.22.19 +# ENV PATH=/usr/local/node/bin:$PATH +# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \ +# /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \ +# npm install -g yarn@$YARN_VERSION && \ +# npm install -g mjml && \ +# rm -rf /tmp/node-build-master + +# Install application gems +COPY Gemfile Gemfile.lock ./ +RUN bundle install && \ + rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \ + bundle exec bootsnap precompile --gemfile + +# Install node modules +# +# Uncomment the following lines if you are using NodeJS need to compile assets +# +# COPY package.json yarn.lock ./ +# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \ +# yarn install --frozen-lockfile + +# Copy application code +COPY . . + +# Precompile bootsnap code for faster boot times +RUN bundle exec bootsnap precompile app/ lib/ + +# Precompiling assets for production without requiring secret RAILS_MASTER_KEY +RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile + +# Final stage for app image +FROM base + +# Copy built artifacts: gems, application +COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}" +COPY --from=build /rails /rails + +# Run and own only the runtime files as a non-root user for security +RUN groupadd --system --gid 1000 rails && \ + useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \ + chown -R rails:rails db log storage tmp +USER 1000:1000 + +# Entrypoint prepares the database. +ENTRYPOINT ["/rails/bin/docker-entrypoint"] + +# Start server via Thruster by default, this can be overwritten at runtime +EXPOSE 80 +CMD ["./bin/thrust", "./bin/rails", "server"] +``` + +{{< /tab >}} +{{< /tabs >}} + +The Dockerfile above assumes you are using Thruster together with Puma as an application server. In case you are using any other server, you can replace the last three lines with the following: + +```dockerfile +# Start the application server +EXPOSE 3000 +CMD ["./bin/rails", "server"] +``` + +This Dockerfile uses a script at `./bin/docker-entrypoint` as the container's entrypoint. This script prepares the database and runs the application server. Below is an example of such a script. + +```bash {title=docker-entrypoint} +#!/bin/bash -e + +# Enable jemalloc for reduced memory usage and latency. +if [ -z "${LD_PRELOAD+x}" ]; then + LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit) + export LD_PRELOAD +fi + +# If running the rails server then create or migrate existing database +if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then + ./bin/rails db:prepare +fi + +exec "${@}" +``` + +Besides the two files above you will also need a `.dockerignore` file. This file is used to exclude files and directories from the context of the build. Below is an example of a `.dockerignore` file. + +```text {collapse=true,title=".dockerignore"} +# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files. + +# Ignore git directory. +/.git/ +/.gitignore + +# Ignore bundler config. +/.bundle + +# Ignore all environment files. +/.env* + +# Ignore all default key files. +/config/master.key +/config/credentials/*.key + +# Ignore all logfiles and tempfiles. +/log/* +/tmp/* +!/log/.keep +!/tmp/.keep + +# Ignore pidfiles, but keep the directory. +/tmp/pids/* +!/tmp/pids/.keep + +# Ignore storage (uploaded files in development and any SQLite databases). +/storage/* +!/storage/.keep +/tmp/storage/* +!/tmp/storage/.keep + +# Ignore assets. +/node_modules/ +/app/assets/builds/* +!/app/assets/builds/.keep +/public/assets + +# Ignore CI service files. +/.github + +# Ignore development files +/.devcontainer + +# Ignore Docker-related files +/.dockerignore +/Dockerfile* +``` + +The last optional file that you may want is the `compose.yaml` file, which is used by Docker Compose to define the services that make up the application. Since SQLite is being used as the database, there is no need to define a separate service for the database. The only service required is the Rails application itself. + +```yaml {title=compose.yaml} +services: + web: + build: . + environment: + - RAILS_MASTER_KEY + ports: + - "3000:80" +``` + +You should now have the following files in your application folder: + +- `.dockerignore` +- `compose.yaml` +- `Dockerfile` +- `bin/docker-entrypoint` + +To learn more about the files, see the following: + +- [Dockerfile](/reference/dockerfile) +- [.dockerignore](/reference/dockerfile#dockerignore-file) +- [compose.yaml](/reference/compose-file/_index.md) +- [docker-entrypoint](/reference/dockerfile/#entrypoint) + +### 2. Run the application + +To run the application, run the following command in a terminal inside the application's directory. + +```console +$ RAILS_MASTER_KEY=<master_key_value> docker compose up --build +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You should see a simple Ruby on Rails application. + +In the terminal, press `ctrl`+`c` to stop the application. + +### 3. Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-ruby-on-rails` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). + +You should see a simple Ruby on Rails application. + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +For more information about Compose commands, see the [Compose CLI +reference](/reference/cli/docker/compose/). + +## Use containers for Ruby on Rails development + +### Prerequisites + +Complete [Containerize a Ruby on Rails application](#containerize-a-ruby-on-rails-application). + +### Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Adding a local database and persisting data +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +### Add a local database and persist data + +You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. + +In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. You need to add the database password file as an environment variable to the server service and specify the secret file to use. + +The following is the updated `compose.yaml` file. + +```yaml {hl_lines="07-25"} +services: + web: + build: . + command: bundle exec rails s -b '0.0.0.0' + ports: + - "3000:3000" + depends_on: + - db + environment: + - RAILS_ENV=test + env_file: "webapp.env" + db: + image: postgres:18 + secrets: + - db-password + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + volumes: + - postgres_data:/var/lib/postgresql + +volumes: + postgres_data: +secrets: + db-password: + file: db/password.txt +``` + +> [!NOTE] +> +> To learn more about the instructions in the Compose file, see [Compose file +> reference](/reference/compose-file/). + +Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. + +In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. + +```text +mysecretpassword +``` + +Save and close the `password.txt` file. In addition, in the file `webapp.env` you can change the password to connect to the database. + +You should now have the following contents in your `docker-ruby-on-rails` +directory. + +```text +. +├── Dockerfile +├── Gemfile +├── Gemfile.lock +├── README.md +├── Rakefile +├── app/ +├── bin/ +├── compose.yaml +├── config/ +├── config.ru +├── db/ +│ ├── development.sqlite3 +│ ├── migrate +│ ├── password.txt +│ ├── schema.rb +│ └── seeds.rb +├── lib/ +├── log/ +├── public/ +├── storage/ +├── test/ +├── tmp/ +└── vendor +``` + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +In Ruby on Rails, `db:migrate` is a Rake task that is used to run migrations on the database. Migrations are a way to alter the structure of your database schema over time in a consistent and easy way. + +```console +$ docker exec -it docker-ruby-on-rails-web-1 rake db:migrate RAILS_ENV=test +``` + +You will see a similar message like this: + +```console +== 20240710193146 CreateWhales: migrating ===================================== +-- create_table(:whales) + -> 0.0126s +== 20240710193146 CreateWhales: migrated (0.0127s) ============================ +``` + +Refresh <http://localhost:3000> in your browser and add the whales. + +Press `ctrl+c` in the terminal to stop your application and run `docker compose up` again, the whales are being persisted. + +### Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yaml` file in an IDE or text editor and then add the Compose +Watch instructions. The following is the updated `compose.yaml` file. + +```yaml {hl_lines="13-16"} +services: + web: + build: . + command: bundle exec rails s -b '0.0.0.0' + ports: + - "3000:3000" + depends_on: + - db + environment: + - RAILS_ENV=test + env_file: "webapp.env" + + develop: + watch: + - action: rebuild + path: . + db: + image: postgres:18 + secrets: + - db-password + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + volumes: + - postgres_data:/var/lib/postgresql + +volumes: + postgres_data: +secrets: + db-password: + file: db/password.txt +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Any changes to the application's source files on your local machine will now be immediately reflected in the running container. + +Open `docker-ruby-on-rails/app/views/whales/index.html.erb` in an IDE or text editor and update the `Whales` string by adding an exclamation mark. + +```diff +- <h1>Whales</h1> ++ <h1>Whales!</h1> +``` + +Save the changes to `index.html.erb` and then wait a few seconds for the application to rebuild. Go to the application again and verify that the updated text appears. + +Press `ctrl+c` in the terminal to stop your application. + +### Summary + +In this section, you took a look at setting up your Compose file to add a local +database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + +- [Compose file reference](/reference/compose-file/) +- [Compose file watch](/manuals/compose/how-tos/file-watch.md) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) diff --git a/content/guides/ruby/_index.md b/content/guides/ruby/_index.md deleted file mode 100644 index 5652dc7fe5b2..000000000000 --- a/content/guides/ruby/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Ruby on Rails language-specific guide -linkTitle: Ruby -description: Containerize Ruby on Rails apps using Docker -keywords: Docker, getting started, ruby, language -summary: | - This guide explains how to containerize Ruby on Rails applications using - Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/ruby/ - - /guides/language/ruby/ -languages: [ruby] -tags: [frameworks] -params: - time: 20 minutes ---- - -The Ruby language-specific guide teaches you how to containerize a Ruby on Rails application using Docker. In this guide, you’ll learn how to: - -- Containerize and run a Ruby on Rails application -- Configure a GitHub Actions workflow to build and push a Docker image to Docker Hub -- Set up a local environment to develop a Ruby on Rails application using containers -- Deploy your containerized Ruby on Rails application locally to Kubernetes to test and debug your deployment - -Start by containerizing an existing Ruby on Rails application. diff --git a/content/guides/ruby/configure-github-actions.md b/content/guides/ruby/configure-github-actions.md deleted file mode 100644 index 0485bb00eeb4..000000000000 --- a/content/guides/ruby/configure-github-actions.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 20 -keywords: ci/cd, github actions, ruby, flask -description: Learn how to configure CI/CD using GitHub Actions for your Ruby on Rails application. -aliases: - - /language/ruby/configure-ci-cd/ - - /guides/language/ruby/configure-ci-cd/ - - /guides/ruby/configure-ci-cd/ ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize a Ruby on Rails application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -If you didn't create a [GitHub repository](https://github.com/new) for your project yet, it is time to do it. After creating the repository, don't forget to [add a remote](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) and ensure you can commit and [push your code](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) to GitHub. - -1. In your project's GitHub repository, open **Settings**, and go to **Secrets and variables** > **Actions**. - -2. Under the **Variables** tab, create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -3. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -4. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -## Overview - -GitHub Actions is a CI/CD (Continuous Integration and Continuous Deployment) automation tool built into GitHub. It allows you to define custom workflows for building, testing, and deploying your code when specific events occur (e.g., pushing code, creating a pull request, etc.). A workflow is a YAML-based automation script that defines a sequence of steps to be executed when triggered. Workflows are stored in the `.github/workflows/` directory of a repository. - -In this section, you'll learn how to set up and use GitHub Actions to build your Docker image as well as push it to Docker Hub. You will complete the following steps: - -1. Define the GitHub Actions workflow. -2. Run the workflow. - -## 1. Define the GitHub Actions workflow - -You can create a GitHub Actions workflow by creating a YAML file in the `.github/workflows/` directory of your repository. To do this use your favorite text editor or the GitHub web interface. The following steps show you how to create a workflow file using the GitHub web interface. - -If you prefer to use the GitHub web interface, follow these steps: - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub Actions workflow file in - your repository. By default, the file is created under `.github/workflows/main.yml`, let's change it name to `build.yml`. - -If you prefer to use your text editor, create a new file named `build.yml` in the `.github/workflows/` directory of your repository. - -Add the following content to the file: - -```yaml -name: Build and push Docker image - -on: - push: - branches: - - main - -jobs: - build_and_push: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest -``` - -Each GitHub Actions workflow includes one or several jobs. Each job consists of steps. Each step can either run a set of commands or use already [existing actions](https://github.com/marketplace?type=actions). The action above has three steps: - -1. [Login to Docker Hub](https://github.com/docker/login-action): Action logs in to Docker Hub using the Docker ID and Personal Access Token (PAT) you created earlier. - -2. [Set up Docker Buildx](https://github.com/docker/setup-buildx-action): Action sets up Docker [Buildx](https://github.com/docker/buildx), a CLI plugin that extends the capabilities of the Docker CLI. - -3. [Build and push](https://github.com/docker/build-push-action): Action builds and pushes the Docker image to Docker Hub. The `tags` parameter specifies the image name and tag. The `latest` tag is used in this example. - -## 2. Run the workflow - -Commit the changes and push them to the `main` branch. This workflow is runs every time you push changes to the `main` branch. You can find more information about workflow triggers [in the GitHub documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). - -Go to the **Actions** tab of you GitHub repository. It displays the workflow. Selecting the workflow shows you the breakdown of all the steps. - -When the workflow is complete, go to your [repositories on Docker Hub](https://hub.docker.com/repositories). If you see the new repository in that list, it means the GitHub Actions workflow successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your Ruby on Rails application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -In the next section, you'll learn how you can develop your application using containers. - diff --git a/content/guides/ruby/containerize.md b/content/guides/ruby/containerize.md deleted file mode 100644 index 5243efd211f7..000000000000 --- a/content/guides/ruby/containerize.md +++ /dev/null @@ -1,392 +0,0 @@ ---- -title: Containerize a Ruby on Rails application -linkTitle: Containerize your app -weight: 10 -keywords: ruby, flask, containerize, initialize -description: Learn how to containerize a Ruby on Rails application. -aliases: - - /language/ruby/build-images/ - - /language/ruby/run-containers/ - - /language/ruby/containerize/ - - /guides/language/ruby/containerize/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [Git client](https://git-scm.com/downloads). The examples in this section show the Git CLI, but you can use any client. - -## Overview - -This section walks you through containerizing and running a [Ruby on Rails](https://rubyonrails.org/) application. - -Starting from Rails 7.1 [Docker is supported out of the box](https://guides.rubyonrails.org/7_1_release_notes.html#generate-dockerfiles-for-new-rails-applications). This means that you will get a `Dockerfile`, `.dockerignore` and `bin/docker-entrypoint` files generated for you when you create a new Rails application. - -If you have an existing Rails application, you will need to create the Docker assets manually from the examples below. - -## 1. Create Docker assets - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -Rails 7.1 and newer generates multistage Dockerfile out of the box. Following are two versions of such a file: one using Docker Hardened Images (DHIs) and another using the Docker Official Image (DOIs). Although the Dockerfile is generated automatically, understanding its purpose and functionality is important. Reviewing the following example is highly recommended. - -[Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in. - -Multistage Dockerfiles help create smaller, more efficient images by separating build and runtime dependencies, ensuring only necessary components are included in the final image. Read more in the [Multi-stage builds guide](/get-started/docker-concepts/building-images/multi-stage-builds/). - - - -{{< tabs >}} -{{< tab name="Using DHIs" >}} - -You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate. - -```dockerfile {title=Dockerfile} -# syntax=docker/dockerfile:1 -# check=error=true - -# This Dockerfile is designed for production, not development. -# docker build -t app . -# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app - -# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html - -# Make sure RUBY_VERSION matches the Ruby version in .ruby-version -ARG RUBY_VERSION=3.4.8 -FROM dhi.io/ruby:$RUBY_VERSION-dev AS base - -# Rails app lives here -WORKDIR /rails - -# Install base packages -# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL -RUN apt-get update -qq && \ - apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \ - rm -rf /var/lib/apt/lists /var/cache/apt/archives - -# Set production environment -ENV RAILS_ENV="production" \ - BUNDLE_DEPLOYMENT="1" \ - BUNDLE_PATH="/usr/local/bundle" \ - BUNDLE_WITHOUT="development" - -# Throw-away build stage to reduce size of final image -FROM base AS build - -# Install packages needed to build gems -RUN apt-get update -qq && \ - apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \ - rm -rf /var/lib/apt/lists /var/cache/apt/archives - -# Install JavaScript dependencies and Node.js for asset compilation -# -# Uncomment the following lines if you are using NodeJS need to compile assets -# -# ARG NODE_VERSION=18.12.0 -# ARG YARN_VERSION=1.22.19 -# ENV PATH=/usr/local/node/bin:$PATH -# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \ -# /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \ -# npm install -g yarn@$YARN_VERSION && \ -# npm install -g mjml && \ -# rm -rf /tmp/node-build-master - -# Install application gems -COPY Gemfile Gemfile.lock ./ -RUN bundle install && \ - rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \ - bundle exec bootsnap precompile --gemfile - -# Install node modules -# -# Uncomment the following lines if you are using NodeJS need to compile assets -# -# COPY package.json yarn.lock ./ -# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \ -# yarn install --frozen-lockfile - -# Copy application code -COPY . . - -# Precompile bootsnap code for faster boot times -RUN bundle exec bootsnap precompile app/ lib/ - -# Precompiling assets for production without requiring secret RAILS_MASTER_KEY -RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile - -# Final stage for app image -FROM base - -# Copy built artifacts: gems, application -COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}" -COPY --from=build /rails /rails - -# Run and own only the runtime files as a non-root user for security -RUN groupadd --system --gid 1000 rails && \ - useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \ - chown -R rails:rails db log storage tmp -USER 1000:1000 - -# Entrypoint prepares the database. -ENTRYPOINT ["/rails/bin/docker-entrypoint"] - -# Start server via Thruster by default, this can be overwritten at runtime -EXPOSE 80 -CMD ["./bin/thrust", "./bin/rails", "server"] -``` - -{{< /tab >}} -{{< tab name="Using DOIs" >}} - -```dockerfile {title=Dockerfile} -# syntax=docker/dockerfile:1 -# check=error=true - -# This Dockerfile is designed for production, not development. -# docker build -t app . -# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app - -# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html - -# Make sure RUBY_VERSION matches the Ruby version in .ruby-version -ARG RUBY_VERSION=3.4.8 -FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base - -# Rails app lives here -WORKDIR /rails - -# Install base packages -# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL -RUN apt-get update -qq && \ - apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \ - rm -rf /var/lib/apt/lists /var/cache/apt/archives - -# Set production environment -ENV RAILS_ENV="production" \ - BUNDLE_DEPLOYMENT="1" \ - BUNDLE_PATH="/usr/local/bundle" \ - BUNDLE_WITHOUT="development" - -# Throw-away build stage to reduce size of final image -FROM base AS build - -# Install packages needed to build gems -RUN apt-get update -qq && \ - apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \ - rm -rf /var/lib/apt/lists /var/cache/apt/archives - -# Install JavaScript dependencies and Node.js for asset compilation -# -# Uncomment the following lines if you are using NodeJS need to compile assets -# -# ARG NODE_VERSION=18.12.0 -# ARG YARN_VERSION=1.22.19 -# ENV PATH=/usr/local/node/bin:$PATH -# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \ -# /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \ -# npm install -g yarn@$YARN_VERSION && \ -# npm install -g mjml && \ -# rm -rf /tmp/node-build-master - -# Install application gems -COPY Gemfile Gemfile.lock ./ -RUN bundle install && \ - rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \ - bundle exec bootsnap precompile --gemfile - -# Install node modules -# -# Uncomment the following lines if you are using NodeJS need to compile assets -# -# COPY package.json yarn.lock ./ -# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \ -# yarn install --frozen-lockfile - -# Copy application code -COPY . . - -# Precompile bootsnap code for faster boot times -RUN bundle exec bootsnap precompile app/ lib/ - -# Precompiling assets for production without requiring secret RAILS_MASTER_KEY -RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile - -# Final stage for app image -FROM base - -# Copy built artifacts: gems, application -COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}" -COPY --from=build /rails /rails - -# Run and own only the runtime files as a non-root user for security -RUN groupadd --system --gid 1000 rails && \ - useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \ - chown -R rails:rails db log storage tmp -USER 1000:1000 - -# Entrypoint prepares the database. -ENTRYPOINT ["/rails/bin/docker-entrypoint"] - -# Start server via Thruster by default, this can be overwritten at runtime -EXPOSE 80 -CMD ["./bin/thrust", "./bin/rails", "server"] -``` - -{{< /tab >}} -{{< /tabs >}} - -The Dockerfile above assumes you are using Thruster together with Puma as an application server. In case you are using any other server, you can replace the last three lines with the following: - -```dockerfile -# Start the application server -EXPOSE 3000 -CMD ["./bin/rails", "server"] -``` - -This Dockerfile uses a script at `./bin/docker-entrypoint` as the container's entrypoint. This script prepares the database and runs the application server. Below is an example of such a script. - -```bash {title=docker-entrypoint} -#!/bin/bash -e - -# Enable jemalloc for reduced memory usage and latency. -if [ -z "${LD_PRELOAD+x}" ]; then - LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit) - export LD_PRELOAD -fi - -# If running the rails server then create or migrate existing database -if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then - ./bin/rails db:prepare -fi - -exec "${@}" -``` - -Besides the two files above you will also need a `.dockerignore` file. This file is used to exclude files and directories from the context of the build. Below is an example of a `.dockerignore` file. - -```text {collapse=true,title=".dockerignore"} -# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files. - -# Ignore git directory. -/.git/ -/.gitignore - -# Ignore bundler config. -/.bundle - -# Ignore all environment files. -/.env* - -# Ignore all default key files. -/config/master.key -/config/credentials/*.key - -# Ignore all logfiles and tempfiles. -/log/* -/tmp/* -!/log/.keep -!/tmp/.keep - -# Ignore pidfiles, but keep the directory. -/tmp/pids/* -!/tmp/pids/.keep - -# Ignore storage (uploaded files in development and any SQLite databases). -/storage/* -!/storage/.keep -/tmp/storage/* -!/tmp/storage/.keep - -# Ignore assets. -/node_modules/ -/app/assets/builds/* -!/app/assets/builds/.keep -/public/assets - -# Ignore CI service files. -/.github - -# Ignore development files -/.devcontainer - -# Ignore Docker-related files -/.dockerignore -/Dockerfile* -``` - -The last optional file that you may want is the `compose.yaml` file, which is used by Docker Compose to define the services that make up the application. Since SQLite is being used as the database, there is no need to define a separate service for the database. The only service required is the Rails application itself. - -```yaml {title=compose.yaml} -services: - web: - build: . - environment: - - RAILS_MASTER_KEY - ports: - - "3000:80" -``` - -You should now have the following files in your application folder: - -- `.dockerignore` -- `compose.yaml` -- `Dockerfile` -- `bin/docker-entrypoint` - -To learn more about the files, see the following: - -- [Dockerfile](/reference/dockerfile) -- [.dockerignore](/reference/dockerfile#dockerignore-file) -- [compose.yaml](/reference/compose-file/_index.md) -- [docker-entrypoint](/reference/dockerfile/#entrypoint) - -## 2. Run the application - -To run the application, run the following command in a terminal inside the application's directory. - -```console -$ RAILS_MASTER_KEY=<master_key_value> docker compose up --build -``` - -Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You should see a simple Ruby on Rails application. - -In the terminal, press `ctrl`+`c` to stop the application. - -## 3. Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-ruby-on-rails` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:3000](http://localhost:3000). - -You should see a simple Ruby on Rails application. - -In the terminal, run the following command to stop the application. - -```console -$ docker compose down -``` - -For more information about Compose commands, see the [Compose CLI -reference](/reference/cli/docker/compose/). - -## Summary - -In this section, you learned how you can containerize and run your Ruby -application using Docker. - -Related information: - -- [Docker Compose overview](/manuals/compose/_index.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. - diff --git a/content/guides/ruby/deploy.md b/content/guides/ruby/deploy.md deleted file mode 100644 index 0fe06fb3bb74..000000000000 --- a/content/guides/ruby/deploy.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Test your Ruby on Rails deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, ruby -description: Learn how to develop locally using Kubernetes -aliases: - - /language/ruby/deploy/ - - /guides/language/ruby/deploy/ ---- - -## Prerequisites - -- Complete all the previous sections of this guide, starting with [Containerize a Ruby on Rails application](containerize.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This lets you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `docker-ruby-on-rails` directory, create a file named -`docker-ruby-on-rails-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Ruby on Rails application](configure-github-actions.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: docker-ruby-on-rails-demo - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: ruby-on-rails - template: - metadata: - labels: - service: ruby-on-rails - spec: - containers: - - name: ruby-on-rails-container - image: DOCKER_USERNAME/REPO_NAME - imagePullPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: docker-ruby-on-rails-demo - namespace: default -spec: - type: NodePort - selector: - service: ruby-on-rails - ports: - - port: 3000 - targetPort: 3000 - nodePort: 30001 -``` - -In this Kubernetes YAML file, there are two objects, separated by the `---`: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The - container is created from the image built by GitHub Actions in [Configure CI/CD for - your Ruby on Rails application](configure-github-actions.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 8001 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `docker-ruby-on-rails` and deploy your application to - Kubernetes. - - ```console - $ kubectl apply -f docker-ruby-on-rails-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```shell - deployment.apps/docker-ruby-on-rails-demo created - service/docker-ruby-on-rails-demo created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - docker-ruby-on-rails-demo 1/1 1 1 15s - ``` - - This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 23h - docker-ruby-on-rails-demo NodePort 10.99.128.230 <none> 3000:30001/TCP 75s - ``` - - In addition to the default `kubernetes` service, you can see your `docker-ruby-on-rails-demo` service, accepting traffic on port 30001/TCP. - -3. To create and migrate the database in a Ruby on Rails application running on Kubernetes, you need to follow these steps. - - **Get the Current Pods**: - First, you need to identify the pods running in your Kubernetes cluster. Execute the following command to list the current pods in the `default` namespace: - - ```sh - # Get the current pods in the cluster in the namespace default - $ kubectl get pods - ``` - - This command will display a list of all pods in the `default` namespace. Look for the pod with the prefix `docker-ruby-on-rails-demo-`. Here is an example output: - - ```console - NAME READY STATUS RESTARTS AGE - docker-ruby-on-rails-demo-7cbddb5d6f-qh44l 1/1 Running 2 (22h ago) 9d - ``` - - **Execute the Migration Command**: - Once you've identified the correct pod, use the `kubectl exec` command to run the database migration inside the pod. - - ```sh - $ kubectl exec -it docker-ruby-on-rails-demo-7cbddb5d6f-qh44l -- rails db:migrate RAILS_ENV=development - ``` - - This command opens an interactive terminal session (`-it`) in the specified pod and runs the `rails db:migrate` command with the environment set to development (`RAILS_ENV=development`). - - By following these steps, you ensure that your database is properly migrated within the Ruby on Rails application running in your Kubernetes cluster. This process helps maintain the integrity and consistency of your application's data structure during deployment and updates. - -4. Open the browser and go to [http://localhost:30001](http://localhost:30001), you should see the ruby on rails application working. - -5. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-ruby-on-rails-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/ruby/develop.md b/content/guides/ruby/develop.md deleted file mode 100644 index 2f2d738b5495..000000000000 --- a/content/guides/ruby/develop.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Use containers for Ruby on Rails development -linkTitle: Develop your app -weight: 40 -keywords: ruby, local, development -description: Learn how to develop your Ruby on Rails application locally. -aliases: - - /language/ruby/develop/ - - /guides/language/ruby/develop/ ---- - -## Prerequisites - -Complete [Containerize a Ruby on Rails application](containerize.md). - -## Overview - -In this section, you'll learn how to set up a development environment for your containerized application. This includes: - -- Adding a local database and persisting data -- Configuring Compose to automatically update your running Compose services as you edit and save your code - -## Add a local database and persist data - -You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data. - -In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. You need to add the database password file as an environment variable to the server service and specify the secret file to use. - -The following is the updated `compose.yaml` file. - -```yaml {hl_lines="07-25"} -services: - web: - build: . - command: bundle exec rails s -b '0.0.0.0' - ports: - - "3000:3000" - depends_on: - - db - environment: - - RAILS_ENV=test - env_file: "webapp.env" - db: - image: postgres:18 - secrets: - - db-password - environment: - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - volumes: - - postgres_data:/var/lib/postgresql - -volumes: - postgres_data: -secrets: - db-password: - file: db/password.txt -``` - -> [!NOTE] -> -> To learn more about the instructions in the Compose file, see [Compose file -> reference](/reference/compose-file/). - -Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. - -In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. - -```text -mysecretpassword -``` - -Save and close the `password.txt` file. In addition, in the file `webapp.env` you can change the password to connect to the database. - -You should now have the following contents in your `docker-ruby-on-rails` -directory. - -```text -. -├── Dockerfile -├── Gemfile -├── Gemfile.lock -├── README.md -├── Rakefile -├── app/ -├── bin/ -├── compose.yaml -├── config/ -├── config.ru -├── db/ -│ ├── development.sqlite3 -│ ├── migrate -│ ├── password.txt -│ ├── schema.rb -│ └── seeds.rb -├── lib/ -├── log/ -├── public/ -├── storage/ -├── test/ -├── tmp/ -└── vendor -``` - -Now, run the following `docker compose up` command to start your application. - -```console -$ docker compose up --build -``` - -In Ruby on Rails, `db:migrate` is a Rake task that is used to run migrations on the database. Migrations are a way to alter the structure of your database schema over time in a consistent and easy way. - -```console -$ docker exec -it docker-ruby-on-rails-web-1 rake db:migrate RAILS_ENV=test -``` - -You will see a similar message like this: - -`console -== 20240710193146 CreateWhales: migrating ===================================== --- create_table(:whales) - -> 0.0126s -== 20240710193146 CreateWhales: migrated (0.0127s) ============================ -` - -Refresh <http://localhost:3000> in your browser and add the whales. - -Press `ctrl+c` in the terminal to stop your application and run `docker compose up` again, the whales are being persisted. - -## Automatically update services - -Use Compose Watch to automatically update your running Compose services as you -edit and save your code. For more details about Compose Watch, see [Use Compose -Watch](/manuals/compose/how-tos/file-watch.md). - -Open your `compose.yaml` file in an IDE or text editor and then add the Compose -Watch instructions. The following is the updated `compose.yaml` file. - -```yaml {hl_lines="13-16"} -services: - web: - build: . - command: bundle exec rails s -b '0.0.0.0' - ports: - - "3000:3000" - depends_on: - - db - environment: - - RAILS_ENV=test - env_file: "webapp.env" - - develop: - watch: - - action: rebuild - path: . - db: - image: postgres:18 - secrets: - - db-password - environment: - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - volumes: - - postgres_data:/var/lib/postgresql - -volumes: - postgres_data: -secrets: - db-password: - file: db/password.txt -``` - -Run the following command to run your application with Compose Watch. - -```console -$ docker compose watch -``` - -Any changes to the application's source files on your local machine will now be immediately reflected in the running container. - -Open `docker-ruby-on-rails/app/views/whales/index.html.erb` in an IDE or text editor and update the `Whales` string by adding an exclamation mark. - -```diff -- <h1>Whales</h1> -+ <h1>Whales!</h1> -``` - -Save the changes to `index.html.erb` and then wait a few seconds for the application to rebuild. Go to the application again and verify that the updated text appears. - -Press `ctrl+c` in the terminal to stop your application. - -## Summary - -In this section, you took a look at setting up your Compose file to add a local -database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. - -Related information: - -- [Compose file reference](/reference/compose-file/) -- [Compose file watch](/manuals/compose/how-tos/file-watch.md) -- [Multi-stage builds](/manuals/build/building/multi-stage.md) - -## Next steps - -In the next section, you'll learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/rust.md b/content/guides/rust.md new file mode 100644 index 000000000000..e9be24b28a29 --- /dev/null +++ b/content/guides/rust.md @@ -0,0 +1,794 @@ +--- +title: Rust language-specific guide +linkTitle: Rust +description: Containerize Rust apps using Docker +keywords: Docker, getting started, Rust, language +summary: | + This guide covers how to containerize Rust applications using Docker. +aliases: + - /language/rust/ + - /guides/language/rust/ + - /language/rust/build-images/ + - /language/rust/run-containers/ + - /language/rust/develop/ + - /language/rust/configure-ci-cd/ + - /language/rust/deploy/ + - /guides/rust/build-images/ + - /guides/rust/configure-ci-cd/ + - /guides/rust/deploy/ + - /guides/rust/develop/ + - /guides/rust/run-containers/ +params: + tags: [languages] + time: 20 minutes +--- + +The Rust language-specific guide teaches you how to create a containerized Rust application using Docker. In this guide, you'll learn how to: + +- Containerize a Rust application +- Build an image and run the newly built image as a container +- Set up volumes and networking +- Orchestrate containers using Compose +- Use containers for development + +After completing the Rust modules, you should be able to containerize your own Rust application based on the examples and instructions provided in this guide. + +Start with building your first Rust image. + +## Build your Rust image + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +### Overview + +This guide walks you through building your first Rust image. An image +includes everything needed to run an application - the code or binary, runtime, +dependencies, and any other file system objects required. + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/docker/docker-rust-hello && cd docker-rust-hello +``` + +### Choose a base image + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +Before editing your Dockerfile, you need to choose a base image. You can use the [Rust Docker Official Image](https://hub.docker.com/_/rust), +or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/rust). + +Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker. +They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/). + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) are publicly available and can be used directly as base images. +To pull Docker Hardened Images, authenticate once with Docker: + +```bash +docker login dhi.io +``` + +Use DHIs from the dhi.io registry, for example: + +```bash +FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build +``` + +The following Dockerfile uses a Rust DHI as the build base image: + +```dockerfile {title=Dockerfile} +# Make sure RUST_VERSION matches the Rust version +ARG RUST_VERSION=1.92 +ARG APP_NAME=docker-rust-hello + +################################################################################ +# Create a stage for building the application. +################################################################################ + +FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build +ARG APP_NAME +WORKDIR /app + +# Install host build dependencies. +RUN apk add --no-cache clang lld musl-dev git + +# Build the application. +RUN --mount=type=bind,source=src,target=src \ + --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ + --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ + --mount=type=cache,target=/app/target/ \ + --mount=type=cache,target=/var/cache/cargo \ + CARGO_HOME=/var/cache/cargo cargo build --locked --release && \ + cp ./target/release/$APP_NAME /bin/server + +################################################################################ +# Create a new stage for running the application that contains the minimal +# We use dhi.io/static for the final stage because it’s a minimal Docker Hardened Image runtime (basically “just # enough OS to run the binary”), which helps keep the image small and with a lower attack surface compared to a # # full Alpine/Debian runtime. +################################################################################ + +FROM dhi.io/static:20250419 AS final + +# Copy the executable from the "build" stage. +COPY --from=build /bin/server /bin/ + +# Configure rocket to listen on all interfaces. +ENV ROCKET_ADDRESS=0.0.0.0 + +# Expose the port that the application listens on. +EXPOSE 8000 + +# What the container should run when it is started. +CMD ["/bin/server"] + +``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Images" >}} + +```dockerfile {title=Dockerfile} +# Pin the Rust toolchain version used in the build stage. +ARG RUST_VERSION=1.92 + +# Name of the compiled binary produced by Cargo (must match Cargo.toml package name). +ARG APP_NAME=docker-rust-hello + +################################################################################ +# Build stage (DOI Rust image) +# This stage compiles the application. +################################################################################ + +FROM docker.io/library/rust:${RUST_VERSION}-alpine AS build + +# Re-declare args inside the stage if you want to use them here. +ARG APP_NAME + +# All build steps happen inside /app. +WORKDIR /app + +# Install build dependencies needed to compile Rust crates on Alpine +RUN apk add --no-cache clang lld musl-dev git + +# Build the application +RUN --mount=type=bind,source=src,target=src \ + --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ + --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ + --mount=type=cache,target=/app/target/ \ + --mount=type=cache,target=/var/cache/cargo \ + CARGO_HOME=/var/cache/cargo cargo build --locked --release && \ + cp ./target/release/$APP_NAME /bin/server + +################################################################################ +# Runtime stage (DOI Alpine image) +# This stage runs the already-compiled binary with minimal dependencies. +################################################################################ + +FROM docker.io/library/alpine:3.18 AS final + +# Create a non-privileged user (recommended best practice) +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser + +# Drop privileges for runtime. +USER appuser + +# Copy only the compiled binary from the build stage. +COPY --from=build /bin/server /bin/ + +# Rocket: listen on all interfaces inside the container. +ENV ROCKET_ADDRESS=0.0.0.0 + +# Document the port your app listens on. +EXPOSE 8000 + +# Start the application. +CMD ["/bin/server"] +``` + +{{< /tab >}} +{{< /tabs >}} + +The cache mount uses a single `CARGO_HOME` so concurrent builds coordinate +access through Cargo's cache lock. Setting `CARGO_HOME` also changes where +Cargo looks for global configuration and credentials. Project-level +`.cargo/config.toml` files are unaffected. + +For building an image, only the Dockerfile is necessary. Open the Dockerfile +in your favorite IDE or text editor and see what it contains. To learn more +about Dockerfiles, see the [Dockerfile reference](/reference/dockerfile.md). + +### .dockerignore file + +The [`.dockerignore`](/reference/dockerfile.md#dockerignore-file) file specifies patterns and paths that you don't want copied into the image in order to keep the image as small as possible. Open up the `.dockerignore` file in your favorite IDE or text editor to review its contents. + +### Build an image + +Now that you’ve created the Dockerfile, you can build the image. To do this, use +the `docker build` command. The `docker build` command builds Docker images from +a Dockerfile and a context. A build's context is the set of files located in +the specified PATH or URL. The Docker build process can access any of the files +located in this context. + +The build command optionally takes a `--tag` flag. The tag sets the name of the +image and an optional tag in the format `name:tag`. If you don't pass a tag, +Docker uses "latest" as its default tag. + +Build the Docker image. + +```console +$ docker build --tag docker-rust-image-dhi . +``` + +You should see output like the following. + +```console +[+] Building 1.4s (13/13) FINISHED docker:desktop-linux + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 1.67kB 0.0s + => [internal] load metadata for dhi.io/static:20250419 1.1s + => [internal] load metadata for dhi.io/rust:1.92-alpine3.22-dev 1.2s + => [auth] static:pull token for dhi.io 0.0s + => [auth] rust:pull token for dhi.io 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 646B 0.0s + => [build 1/3] FROM dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s + => => resolve dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s + => [final 1/2] FROM dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s + => => resolve dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s + => [internal] load build context 0.0s + => => transferring context: 117B 0.0s + => CACHED [build 2/3] WORKDIR /build 0.0s + => CACHED [build 3/3] RUN --mount=type=bind,source=src,target=src --mount=type=bind,source=Cargo.toml,target=Cargo.toml --mount=type=bind,source=Cargo.lock,target=Cargo 0.0s + => CACHED [final 2/2] COPY --from=build /build/target/release/docker-rust-hello /server 0.0s + => exporting to image 0.1s + => => exporting layers 0.0s + => => exporting manifest sha256:cc937bbdd712ef6e5445501f77e02ef8455ef64c567598786d46b7b21a4d4fa8 0.0s + => => exporting config sha256:077507b483af4b5e1a928e527e4bb3a4aaf0557e1eea81cd39465f564c187669 0.0s + => => exporting attestation manifest sha256:11b60e7608170493da1fdd88c120e2d2957f2a72a22edbc9cfbdd0dd37d21f89 0.0s + => => exporting manifest list sha256:99a1b925a8d6ebf80e376b8a1e50cd806ec42d194479a3375e1cd9d2911b4db9 0.0s + => => naming to docker.io/library/docker-rust-image-dhi:latest 0.0s + => => unpacking to docker.io/library/docker-rust-image-dhi:latest 0.0s + +View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/yczk0ijw8kc5g20e8nbc8r6lj +``` + +### View local images + +To see a list of images you have on your local machine, you have two options. One is to use the Docker CLI and the other is to use [Docker Desktop](/manuals/desktop/use-desktop/images.md). As you are working in the terminal already, take a look at listing images using the CLI. + +To list images, run the `docker images` command. + +```console +$ docker images +IMAGE ID DISK USAGE CONTENT SIZE EXTRA +docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U +``` + +You should see at least one image listed, including the image you just built `docker-rust-image-dhi:latest`. + +### Tag images + +As mentioned earlier, an image name is made up of slash-separated name components. Name components may contain lowercase letters, digits, and separators. A separator can include a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator. + +An image is made up of a manifest and a list of layers. Don't worry too much about manifests and layers at this point other than a "tag" points to a combination of these artifacts. You can have multiple tags for an image. Create a second tag for the image you built and take a look at its layers. + +To create a new tag for the image you built, run the following command. + +```console +$ docker tag docker-rust-image-dhi:latest docker-rust-image-dhi:v1.0.0 +``` + +The `docker tag` command creates a new tag for an image. It doesn't create a new image. The tag points to the same image and is just another way to reference the image. + +Now, run the `docker images` command to see a list of the local images. + +```console +$ docker images +IMAGE ID DISK USAGE CONTENT SIZE EXTRA +docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U +docker-rust-image-dhi:v1.0.0 99a1b925a8d6 11.6MB 2.45MB U +``` + +You can see that two images start with `docker-rust-image-dhi`. You know they're the same image because if you take a look at the `IMAGE ID` column, you can see that the values are the same for the two images. + +Remove the tag you just created. To do this, use the `rmi` command. The `rmi` command stands for remove image. + +```console +$ docker rmi docker-rust-image-dhi:v1.0.0 +Untagged: docker-rust-image-dhi:v1.0.0 +``` + +Note that the response from Docker tells you that Docker didn't remove the image, but only "untagged" it. You can check this by running the `docker images` command. + +```console +$ docker images +IMAGE ID DISK USAGE CONTENT SIZE EXTRA +docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U +``` + +Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image-dhi:latest` tag is available on your machine. + +## Run your Rust image as a container + +### Prerequisite + +You have completed [Build your Rust image](#build-your-rust-image) and you have built an image. + +### Overview + +A container is a normal operating system process except that Docker isolates this process so that it has its own file system, its own networking, and its own isolated process tree separate from the host. + +To run an image inside of a container, you use the `docker run` command. The `docker run` command requires one parameter which is the name of the image. + +### Run an image + +Use `docker run` to run the image you built in [Build your Rust image](#build-your-rust-image). + +```console +$ docker run docker-rust-image-dhi +``` + +After running this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a server that runs in a loop waiting for incoming requests without returning control back to the OS until you stop the container. + +Open a new terminal then make a request to the server using the `curl` command. + +```console +$ curl http://localhost:8000 +``` + +You should see output like the following. + +```console +curl: (7) Failed to connect to localhost port 8000 after 2236 ms: Couldn't connect to server +``` + +As you can see, your `curl` command failed. This means you weren't able to connect to the localhost on port 8000. This is normal because your container is running in isolation which includes networking. Stop the container and restart with port 8000 published on your local network. + +To stop the container, press ctrl-c. This will return you to the terminal prompt. + +To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host port]:[container port]`. So, if you wanted to expose port 8000 inside the container to port 3001 outside the container, you would pass `3001:8000` to the `--publish` flag. + +You didn't specify a port when running the application in the container and the default is 8000. If you want your previous request going to port 8000 to work, you can map the host's port 3001 to the container's port 8000: + +```console +$ docker run --publish 3001:8000 docker-rust-image-dhi +``` + +Now, rerun the curl command. Remember to open a new terminal. + +```console +$ curl http://localhost:3001 +``` + +You should see output like the following. + +```console +Hello, Docker! +``` + +Success! You were able to connect to the application running inside of your container on port 8000. Switch back to the terminal where your container is running and stop it. + +Press ctrl-c to stop the container. + +### Run in detached mode + +This is great so far, but your sample application is a web server and you don't have to be connected to the container. Docker can run your container in detached mode or in the background. To do this, you can use the `--detach` or `-d` for short. Docker starts your container the same as before but this time will "detach" from the container and return you to the terminal prompt. + +```console +$ docker run -d -p 3001:8000 docker-rust-image-dhi +3e4830e7f01304811d97dd3469d47a0c7a916a8b6c28ce0ef19c6f689a521144 +``` + +Docker started your container in the background and printed the Container ID on the terminal. + +Again, make sure that your container is running properly. Run the curl command again. + +```console +$ curl http://localhost:3001 +``` + +You should see output like the following. + +```console +Hello, Docker! +``` + +### List containers + +Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how you use the ps command in Linux to see a list of processes. + +You should see output like the following. + +```console +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3e4830e7f013 docker-rust-image-dhi "/server" 23 seconds ago Up 22 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp youthful_lamport +``` + +The `docker ps` command provides a bunch of information about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that were exposed, and the name of the container. + +You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You’ll fix this in a minute, but first you need to stop the container. To stop the container, run the `docker stop` command which does just that, stops the container. You need to pass the name of the container or you can use the container ID. + +```console +$ docker stop youthful_lamport +youthful_lamport +``` + +Now, rerun the `docker ps` command to see a list of running containers. + +```console +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +### Stop, start, and name containers + +You can start, stop, and restart Docker containers. When you stop a container, it's not removed, but the status is changed to stopped and the process inside the container is stopped. When you ran the `docker ps` command in the previous module, the default output only shows running containers. When you pass the `--all` or `-a` for short, you see all containers on your machine, irrespective of their start or stop status. + +```console +$ docker ps -a +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3e4830e7f013 docker-rust-image-dhi "/server" About a minute ago Exited (0) 28 seconds ago youthful_lamport +60009b7eaf40 docker-rust-image-dhi "/server" 2 minutes ago Exited (0) About a minute ago sharp_noyce +152e1d7d9eea docker-rust-image-dhi "/server ." 4 minutes ago Exited (0) 2 minutes ago magical_bhabha +``` + +You should now see several containers listed. These are containers that you started and stopped but you haven't removed. + +Restart the container that you just stopped. Locate the name of the container you just stopped and replace the name of the container in following restart command. + +```console +$ docker restart youthful_lamport +``` + +Now list all the containers again using the `docker ps --all` command. + +```console +$ docker ps --all +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3e4830e7f013 docker-rust-image-dhi "/server" 3 minutes ago Up 7 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp youthful_lamport +60009b7eaf40 docker-rust-image-dhi "/server" 4 minutes ago Exited (0) 3 minutes ago sharp_noyce +152e1d7d9eea docker-rust-image-dhi "/server ." 5 minutes ago Exited (0) 4 minutes ago magical_bhabha +``` + +Notice that the container you just restarted has been started in detached mode. Also, observe the status of the container is "Up X seconds". When you restart a container, it starts with the same flags or commands that it was originally started with. + +Now, stop and remove all of your containers and take a look at fixing the random naming issue. Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system. + +```console +$ docker stop youthful_lamport +youthful_lamport +``` + +Now that you have stopped all of your containers, remove them. When you remove a container, it's no longer running, nor is it in the stopped status, but the process inside the container has been stopped and the metadata for the container has been removed. + +To remove a container, run the `docker rm` command with the container name. You can pass multiple container names to the command using a single command. Again, replace the container names in the following command with the container names from your system. + +```console +$ docker rm youthful_lamport friendly_montalcini tender_bose +youthful_lamport +sharp_noyce +magical_bhabha +``` + +Run the `docker ps --all` command again to see that Docker removed all containers. + +Now, it's time to address the random naming issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with. + +To name a container, pass the `--name` flag to the `docker run` command. + +```console +$ docker run -d -p 3001:8000 --name docker-rust-container docker-rust-image-dhi +1aa5d46418a68705c81782a58456a4ccdb56a309cb5e6bd399478d01eaa5cdda +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +219b2e3c7c38 docker-rust-image-dhi "/server" 6 seconds ago Up 5 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp docker-rust-container +``` + +Now you can identify your container based on the name. + +## Develop your Rust application + +### Prerequisites + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have completed the walkthroughs in the Docker Desktop [Learning Center](/manuals/desktop/use-desktop/_index.md) to learn about Docker concepts. +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +### Overview + +In this section, you’ll learn how to use volumes and networking in Docker. You’ll also use Docker to build your images and Docker Compose to make everything a whole lot easier. + +First, you’ll take a look at running a database in a container and how you can use volumes and networking to persist your data and let your application talk with the database. Then you’ll pull everything together into a Compose file which lets you set up and run a local development environment with one command. + +### Run a database in a container + +Instead of downloading PostgreSQL, installing, configuring, and then running the PostgreSQL database as a service, you can use the Docker Official Image for PostgreSQL and run it in a container. + +Before you run PostgreSQL in a container, create a volume that Docker can manage to store your persistent data and configuration. Use the named volumes feature that Docker provides instead of using bind mounts. + +Run the following command to create your volume. + +```console +$ docker volume create db-data +``` + +Now create a network that your application and database will use to talk to each other. The network is called a user-defined bridge network and gives you a nice DNS lookup service which you can use when creating your connection string. + +```console +$ docker network create postgresnet +``` + +Now you can run PostgreSQL in a container and attach to the volume and network that you created previously. Docker pulls the image from Hub and runs it for you locally. +In the following command, option `--mount` is for starting the container with a volume. For more information, see [Docker volumes](/manuals/engine/storage/volumes.md). + +```console +$ docker run --rm -d --mount \ + "type=volume,src=db-data,target=/var/lib/postgresql" \ + -p 5432:5432 \ + --network postgresnet \ + --name db \ + -e POSTGRES_PASSWORD=mysecretpassword \ + -e POSTGRES_DB=example \ + postgres:18 +``` + +Now, make sure that your PostgreSQL database is running and that you can connect to it. Connect to the running PostgreSQL database inside the container. + +```console +$ docker exec -it db psql -U postgres +``` + +You should see output like the following. + +```console +psql (15.3 (Debian 15.3-1.pgdg110+1)) +Type "help" for help. + +postgres=# +``` + +In the previous command, you logged in to the PostgreSQL database by passing the `psql` command to the `db` container. Press ctrl-d to exit the PostgreSQL interactive terminal. + +### Get and run the sample application + +For the sample application, you'll use a variation of the backend from the react-rust-postgres application from [Awesome Compose](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres). + +1. Clone the sample application repository using the following command. + + ```console + $ git clone https://github.com/docker/docker-rust-postgres + ``` + +2. In the cloned repository's directory, create a `Dockerfile`. This application includes a `migrations` directory (in addition to `src`) to initialize the database, so the Dockerfile includes a bind mount for that directory in the build stage. + + ```dockerfile {hl_lines="28"} + # syntax=docker/dockerfile:1 + + # Comments are provided throughout this file to help you get started. + # If you need more help, visit the Dockerfile reference guide at + # https://docs.docker.com/reference/dockerfile/ + + ################################################################################ + # Create a stage for building the application. + + ARG RUST_VERSION=1.70.0 + ARG APP_NAME=react-rust-postgres + FROM rust:${RUST_VERSION}-slim-bookworm AS build + ARG APP_NAME + WORKDIR /app + + # Build the application. + # Leverage a cache mount to /var/cache/cargo for downloaded dependencies + # and a cache mount to /app/target/ for compiled dependencies which will + # speed up subsequent builds. + # Leverage a bind mount to the src directory to avoid having to copy the + # source code into the container. Once built, copy the executable to an + # output directory before the cache mounted /app/target is unmounted. + RUN --mount=type=bind,source=src,target=src \ + --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ + --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ + --mount=type=cache,target=/app/target/ \ + --mount=type=cache,target=/var/cache/cargo \ + --mount=type=bind,source=migrations,target=migrations \ + <<EOF + set -e + CARGO_HOME=/var/cache/cargo cargo build --locked --release + cp ./target/release/$APP_NAME /bin/server + EOF + + ################################################################################ + # Create a new stage for running the application that contains the minimal + # runtime dependencies for the application. This often uses a different base + # image from the build stage where the necessary files are copied from the build + # stage. + # + # The example below uses the Debian Bookworm image as the foundation for running the app. + # By specifying the "bookworm-slim" tag, it will also use whatever happens to be the + # most recent version of that tag when you build your Dockerfile. If + # reproducibility is important, consider using a digest + # (e.g., debian@sha256:88200866dfff7ea7f5cbcb6ec7c8a701889efe6fe859fe64d6990e4b07ea4171). + FROM debian:bookworm-slim AS final + + # Create a non-privileged user that the app will run under. + # See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/ #user + ARG UID=10001 + RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser + USER appuser + + # Copy the executable from the "build" stage. + COPY --from=build /bin/server /bin/ + + # Expose the port that the application listens on. + EXPOSE 8000 + + # What the container should run when it is started. + CMD ["/bin/server"] + ``` + +3. In the cloned repository's directory, run `docker build` to build the image. + + ```console + $ docker build -t rust-backend-image . + ``` + +4. Run `docker run` with the following options to run the image as a container on the same network as the database. + + ```console + $ docker run \ + --rm -d \ + --network postgresnet \ + --name docker-develop-rust-container \ + -p 3001:8000 \ + -e PG_DBNAME=example \ + -e PG_HOST=db \ + -e PG_USER=postgres \ + -e PG_PASSWORD=mysecretpassword \ + -e ADDRESS=0.0.0.0:8000 \ + -e RUST_LOG=debug \ + rust-backend-image + ``` + +5. Curl the application to verify that it connects to the database. + + ```console + $ curl http://localhost:3001/users + ``` + + You should get a response like the following. + + ```json + [{ "id": 1, "login": "root" }] + ``` + +### Use Compose to develop locally + +In the cloned repository's directory, create a `compose.yaml` file. Using Compose, you don't have to type all the parameters to pass to the `docker run` command — you can declare them in the file instead. + +You need to update the following items in the `compose.yaml` file: + +- Uncomment all of the database instructions. +- Add the environment variables under the server service. + +The following is the updated `compose.yaml` file. + +```yaml {hl_lines=["17-23","30-55"]} +# Comments are provided throughout this file to help you get started. +# If you need more help, visit the Docker compose reference guide at +# https://docs.docker.com/reference/compose-file/ + +# Here the instructions define your application as a service called "server". +# This service is built from the Dockerfile in the current directory. +# You can add other services your application may depend on here, such as a +# database or a cache. For examples, see the Awesome Compose repository: +# https://github.com/docker/awesome-compose +services: + server: + build: + context: . + target: final + ports: + - 8000:8000 + environment: + - PG_DBNAME=example + - PG_HOST=db + - PG_USER=postgres + - PG_PASSWORD=mysecretpassword + - ADDRESS=0.0.0.0:8000 + - RUST_LOG=debug + # The commented out section below is an example of how to define a PostgreSQL + # database that your application can use. `depends_on` tells Docker Compose to + # start the database before your application. The `db-data` volume persists the + # database data between container restarts. The `db-password` secret is used + # to set the database password. You must create `db/password.txt` and add + # a password of your choosing to it before running `docker compose up`. + depends_on: + db: + condition: service_healthy + db: + image: postgres:18 + restart: always + user: postgres + secrets: + - db-password + volumes: + - db-data:/var/lib/postgresql + environment: + - POSTGRES_DB=example + - POSTGRES_PASSWORD_FILE=/run/secrets/db-password + expose: + - 5432 + healthcheck: + test: ["CMD", "pg_isready"] + interval: 10s + timeout: 5s + retries: 5 +volumes: + db-data: +secrets: + db-password: + file: db/password.txt +``` + +Note that the file doesn't specify a network for those 2 services. When you use Compose, it automatically creates a network and connects the services to it. For more information see [Networking in Compose](/manuals/compose/how-tos/networking.md). + +Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. + +In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. + +```text +mysecretpassword +``` + +If you have any other containers running from the previous sections, [stop](#stop-start-and-name-containers) them now. + +Now, run the following `docker compose up` command to start your application. + +```console +$ docker compose up --build +``` + +The command passes the `--build` flag so Docker will compile your image and then start the containers. + +Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands: + +```console +$ curl http://localhost:8000/users +``` + +You should receive the following response: + +```json +[{ "id": 1, "login": "root" }] +``` + +### Summary + +In this section, you took a look at setting up your Compose file to run your Rust application and database with a single command. + +Related information: + +- [Docker volumes](/manuals/engine/storage/volumes.md) +- [Compose overview](/manuals/compose/_index.md) diff --git a/content/guides/rust/_index.md b/content/guides/rust/_index.md deleted file mode 100644 index 483040adbfce..000000000000 --- a/content/guides/rust/_index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Rust language-specific guide -linkTitle: Rust -description: Containerize Rust apps using Docker -keywords: Docker, getting started, Rust, language -summary: | - This guide covers how to containerize Rust applications using Docker. -toc_min: 1 -toc_max: 2 -aliases: - - /language/rust/ - - /guides/language/rust/ -languages: [rust] -tags: [dhi] -params: - time: 20 minutes ---- - -The Rust language-specific guide teaches you how to create a containerized Rust application using Docker. In this guide, you'll learn how to: - -- Containerize a Rust application -- Build an image and run the newly built image as a container -- Set up volumes and networking -- Orchestrate containers using Compose -- Use containers for development -- Configure a CI/CD pipeline for your application using GitHub Actions -- Deploy your containerized Rust application locally to Kubernetes to test and debug your deployment - -After completing the Rust modules, you should be able to containerize your own Rust application based on the examples and instructions provided in this guide. - -Start with building your first Rust image. diff --git a/content/guides/rust/build-images.md b/content/guides/rust/build-images.md deleted file mode 100644 index 013dff8ff2be..000000000000 --- a/content/guides/rust/build-images.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Build your Rust image -linkTitle: Build images -weight: 5 -keywords: rust, build, images, dockerfile -description: Learn how to build your first Rust Docker image -aliases: - - /language/rust/build-images/ - - /guides/language/rust/build-images/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -## Overview - -This guide walks you through building your first Rust image. An image -includes everything needed to run an application - the code or binary, runtime, -dependencies, and any other file system objects required. - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: - -```console -$ git clone https://github.com/docker/docker-rust-hello && cd docker-rust-hello -``` - -## Choose a base image - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -Before editing your Dockerfile, you need to choose a base image. You can use the [Rust Docker Official Image](https://hub.docker.com/_/rust), -or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/rust). - -Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker. -They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/). - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} - -Docker Hardened Images (DHIs) are publicly available and can be used directly as base images. -To pull Docker Hardened Images, authenticate once with Docker: - -```bash -docker login dhi.io -``` - -Use DHIs from the dhi.io registry, for example: - -```bash -FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build -``` - -The following Dockerfile uses a Rust DHI as the build base image: - -```dockerfile {title=Dockerfile} -# Make sure RUST_VERSION matches the Rust version -ARG RUST_VERSION=1.92 -ARG APP_NAME=docker-rust-hello - -################################################################################ -# Create a stage for building the application. -################################################################################ - -FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build -ARG APP_NAME -WORKDIR /app - -# Install host build dependencies. -RUN apk add --no-cache clang lld musl-dev git - -# Build the application. -RUN --mount=type=bind,source=src,target=src \ - --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ - --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ - --mount=type=cache,target=/app/target/ \ - --mount=type=cache,target=/usr/local/cargo/git/db \ - --mount=type=cache,target=/usr/local/cargo/registry/ \ - cargo build --locked --release && \ - cp ./target/release/$APP_NAME /bin/server - -################################################################################ -# Create a new stage for running the application that contains the minimal -# We use dhi.io/static for the final stage because it’s a minimal Docker Hardened Image runtime (basically “just # enough OS to run the binary”), which helps keep the image small and with a lower attack surface compared to a # # full Alpine/Debian runtime. -################################################################################ - -FROM dhi.io/static:20250419 AS final - -# Copy the executable from the "build" stage. -COPY --from=build /bin/server /bin/ - -# Configure rocket to listen on all interfaces. -ENV ROCKET_ADDRESS=0.0.0.0 - -# Expose the port that the application listens on. -EXPOSE 8000 - -# What the container should run when it is started. -CMD ["/bin/server"] - -``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Images" >}} - -```dockerfile {title=Dockerfile} -# Pin the Rust toolchain version used in the build stage. -ARG RUST_VERSION=1.92 - -# Name of the compiled binary produced by Cargo (must match Cargo.toml package name). -ARG APP_NAME=docker-rust-hello - -################################################################################ -# Build stage (DOI Rust image) -# This stage compiles the application. -################################################################################ - -FROM docker.io/library/rust:${RUST_VERSION}-alpine AS build - -# Re-declare args inside the stage if you want to use them here. -ARG APP_NAME - -# All build steps happen inside /app. -WORKDIR /app - -# Install build dependencies needed to compile Rust crates on Alpine -RUN apk add --no-cache clang lld musl-dev git - -# Build the application -RUN --mount=type=bind,source=src,target=src \ - --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ - --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ - --mount=type=cache,target=/app/target/ \ - --mount=type=cache,target=/usr/local/cargo/git/db \ - --mount=type=cache,target=/usr/local/cargo/registry/ \ - cargo build --locked --release && \ - cp ./target/release/$APP_NAME /bin/server - -################################################################################ -# Runtime stage (DOI Alpine image) -# This stage runs the already-compiled binary with minimal dependencies. -################################################################################ - -FROM docker.io/library/alpine:3.18 AS final - -# Create a non-privileged user (recommended best practice) -ARG UID=10001 -RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser - -# Drop privileges for runtime. -USER appuser - -# Copy only the compiled binary from the build stage. -COPY --from=build /bin/server /bin/ - -# Rocket: listen on all interfaces inside the container. -ENV ROCKET_ADDRESS=0.0.0.0 - -# Document the port your app listens on. -EXPOSE 8000 - -# Start the application. -CMD ["/bin/server"] -``` -{{< /tab >}} -{{< /tabs >}} - - - -For building an image, only the Dockerfile is necessary. Open the Dockerfile -in your favorite IDE or text editor and see what it contains. To learn more -about Dockerfiles, see the [Dockerfile reference](/reference/dockerfile.md). - -## .dockerignore file - -The [`.dockerignore`](/reference/dockerfile.md#dockerignore-file) file specifies patterns and paths that you don't want copied into the image in order to keep the image as small as possible. Open up the `.dockerignore` file in your favorite IDE or text editor to review its contents. - -## Build an image - -Now that you’ve created the Dockerfile, you can build the image. To do this, use -the `docker build` command. The `docker build` command builds Docker images from -a Dockerfile and a context. A build's context is the set of files located in -the specified PATH or URL. The Docker build process can access any of the files -located in this context. - -The build command optionally takes a `--tag` flag. The tag sets the name of the -image and an optional tag in the format `name:tag`. If you don't pass a tag, -Docker uses "latest" as its default tag. - -Build the Docker image. - -```console -$ docker build --tag docker-rust-image-dhi . -``` - -You should see output like the following. - -```console -[+] Building 1.4s (13/13) FINISHED docker:desktop-linux - => [internal] load build definition from Dockerfile 0.0s - => => transferring dockerfile: 1.67kB 0.0s - => [internal] load metadata for dhi.io/static:20250419 1.1s - => [internal] load metadata for dhi.io/rust:1.92-alpine3.22-dev 1.2s - => [auth] static:pull token for dhi.io 0.0s - => [auth] rust:pull token for dhi.io 0.0s - => [internal] load .dockerignore 0.0s - => => transferring context: 646B 0.0s - => [build 1/3] FROM dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s - => => resolve dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s - => [final 1/2] FROM dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s - => => resolve dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s - => [internal] load build context 0.0s - => => transferring context: 117B 0.0s - => CACHED [build 2/3] WORKDIR /build 0.0s - => CACHED [build 3/3] RUN --mount=type=bind,source=src,target=src --mount=type=bind,source=Cargo.toml,target=Cargo.toml --mount=type=bind,source=Cargo.lock,target=Cargo 0.0s - => CACHED [final 2/2] COPY --from=build /build/target/release/docker-rust-hello /server 0.0s - => exporting to image 0.1s - => => exporting layers 0.0s - => => exporting manifest sha256:cc937bbdd712ef6e5445501f77e02ef8455ef64c567598786d46b7b21a4d4fa8 0.0s - => => exporting config sha256:077507b483af4b5e1a928e527e4bb3a4aaf0557e1eea81cd39465f564c187669 0.0s - => => exporting attestation manifest sha256:11b60e7608170493da1fdd88c120e2d2957f2a72a22edbc9cfbdd0dd37d21f89 0.0s - => => exporting manifest list sha256:99a1b925a8d6ebf80e376b8a1e50cd806ec42d194479a3375e1cd9d2911b4db9 0.0s - => => naming to docker.io/library/docker-rust-image-dhi:latest 0.0s - => => unpacking to docker.io/library/docker-rust-image-dhi:latest 0.0s - -View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/yczk0ijw8kc5g20e8nbc8r6lj -``` - -## View local images - -To see a list of images you have on your local machine, you have two options. One is to use the Docker CLI and the other is to use [Docker Desktop](/manuals/desktop/use-desktop/images.md). As you are working in the terminal already, take a look at listing images using the CLI. - -To list images, run the `docker images` command. - -```console -$ docker images -IMAGE ID DISK USAGE CONTENT SIZE EXTRA -docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U -``` - -You should see at least one image listed, including the image you just built `docker-rust-image-dhi:latest`. - -## Tag images - -As mentioned earlier, an image name is made up of slash-separated name components. Name components may contain lowercase letters, digits, and separators. A separator can include a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator. - -An image is made up of a manifest and a list of layers. Don't worry too much about manifests and layers at this point other than a "tag" points to a combination of these artifacts. You can have multiple tags for an image. Create a second tag for the image you built and take a look at its layers. - -To create a new tag for the image you built, run the following command. - -```console -$ docker tag docker-rust-image-dhi:latest docker-rust-image-dhi:v1.0.0 -``` - -The `docker tag` command creates a new tag for an image. It doesn't create a new image. The tag points to the same image and is just another way to reference the image. - -Now, run the `docker images` command to see a list of the local images. - -```console -$ docker images -IMAGE ID DISK USAGE CONTENT SIZE EXTRA -docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U -docker-rust-image-dhi:v1.0.0 99a1b925a8d6 11.6MB 2.45MB U -``` - -You can see that two images start with `docker-rust-image-dhi`. You know they're the same image because if you take a look at the `IMAGE ID` column, you can see that the values are the same for the two images. - -Remove the tag you just created. To do this, use the `rmi` command. The `rmi` command stands for remove image. - -```console -$ docker rmi docker-rust-image-dhi:v1.0.0 -Untagged: docker-rust-image-dhi:v1.0.0 -``` - -Note that the response from Docker tells you that Docker didn't remove the image, but only "untagged" it. You can check this by running the `docker images` command. - -```console -$ docker images -IMAGE ID DISK USAGE CONTENT SIZE EXTRA -docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U -``` - -Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image-dhi:latest` tag is available on your machine. - -## Summary - -This section showed how to create a Dockerfile and `.dockerignore` file for a Rust application, build an image, and tag and list images. - -Related information: - -- [Dockerfile reference](/reference/dockerfile.md) -- [.dockerignore file](/reference/dockerfile.md#dockerignore-file) -- [docker build CLI reference](/reference/cli/docker/buildx/build/) -- [Docker Hardened Images](/dhi/) - -## Next steps - -In the next section learn how to run your image as a container. diff --git a/content/guides/rust/configure-ci-cd.md b/content/guides/rust/configure-ci-cd.md deleted file mode 100644 index 80a6f287c715..000000000000 --- a/content/guides/rust/configure-ci-cd.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Configure CI/CD for your Rust application -linkTitle: Configure CI/CD -weight: 40 -keywords: rust, CI/CD, local, development -description: Learn how to Configure CI/CD for your application -aliases: - - /language/rust/configure-ci-cd/ - - /guides/language/rust/configure-ci-cd/ ---- - -## Prerequisites - -Complete the previous sections of this guide, starting with [Develop your Rust application](develop.md). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section. - -## Overview - -In this section, you'll learn how to set up and use GitHub Actions to build and push your Docker image to Docker Hub. You will complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -## Step one: Create the repository - -Create a GitHub repository, configure the Docker Hub credentials, and push your source code. - -1. [Create a new repository](https://github.com/new) on GitHub. - -2. Open the repository **Settings**, and go to **Secrets and variables** > - **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as a value. - -4. Create a new [Personal Access Token (PAT)](/manuals/security/access-tokens.md#create-an-access-token) for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -6. In your local repository on your machine, run the following command to change - the origin to the repository you just created. Make sure you change - `your-username` to your GitHub username and `your-repository` to the name of - the repository you created. - - ```console - $ git remote set-url origin https://github.com/your-username/your-repository.git - ``` - -7. Run the following commands to stage, commit, and push your local repository to GitHub. - - ```console - $ git add -A - $ git commit -m "my commit" - $ git push -u origin main - ``` - -## Step two: Set up the workflow - -Set up your GitHub Actions workflow for building, testing, and pushing the image -to Docker Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. - -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - main - - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: true - tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest - ``` - - For more information about the YAML syntax for `docker/build-push-action`, - refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - -## Step three: Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Summary - -In this section, you learned how to set up a GitHub Actions workflow for your Rust application. - -Related information: - -- [Introduction to GitHub Actions](/guides/gha.md) -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - -## Next steps - -Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/rust/deploy.md b/content/guides/rust/deploy.md deleted file mode 100644 index a43551f673c6..000000000000 --- a/content/guides/rust/deploy.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Test your Rust deployment -linkTitle: Test your deployment -weight: 50 -keywords: deploy, kubernetes, rust -description: Learn how to test your Rust deployment locally using Kubernetes -aliases: - - /language/rust/deploy/ - - /guides/language/rust/deploy/ ---- - -## Prerequisites - -- Complete the previous sections of this guide, starting with [Develop your Rust application](develop.md). -- [Turn on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -## Overview - -In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This lets you to test and debug your workloads on Kubernetes locally before deploying. - -## Create a Kubernetes YAML file - -In your `docker-rust-postgres` directory, create a file named -`docker-rust-kubernetes.yaml`. Open the file in an IDE or text editor and add -the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker -username and the name of the repository that you created in [Configure CI/CD for -your Rust application](configure-ci-cd.md). - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: server - name: server - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: server - strategy: {} - template: - metadata: - labels: - service: server - spec: - initContainers: - - name: wait-for-db - image: busybox:1.28 - command: - [ - "sh", - "-c", - 'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;', - ] - containers: - - image: DOCKER_USERNAME/REPO_NAME - name: server - imagePullPolicy: Always - ports: - - containerPort: 8000 - hostPort: 5000 - protocol: TCP - env: - - name: ADDRESS - value: 0.0.0.0:8000 - - name: PG_DBNAME - value: example - - name: PG_HOST - value: db - - name: PG_PASSWORD - value: mysecretpassword - - name: PG_USER - value: postgres - - name: RUST_LOG - value: debug - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - service: db - name: db - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - service: db - strategy: - type: Recreate - template: - metadata: - labels: - service: db - spec: - containers: - - env: - - name: POSTGRES_DB - value: example - - name: POSTGRES_PASSWORD - value: mysecretpassword - - name: POSTGRES_USER - value: postgres - image: postgres:18 - name: db - ports: - - containerPort: 5432 - protocol: TCP - resources: {} - restartPolicy: Always -status: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: server - name: server - namespace: default -spec: - type: NodePort - ports: - - name: "5000" - port: 5000 - targetPort: 8000 - nodePort: 30001 - selector: - service: server -status: - loadBalancer: {} ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: db - name: db - namespace: default -spec: - ports: - - name: "5432" - port: 5432 - targetPort: 5432 - selector: - service: db -status: - loadBalancer: {} -``` - -In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are: - -- A Deployment, describing a scalable group of identical pods. In this case, - you'll get just one replica, or copy of your pod. That pod, which is - described under `template`, has just one container in it. The container is - created from the image built by GitHub Actions in [Configure CI/CD for your - Rust application](configure-ci-cd.md). -- A NodePort service, which will route traffic from port 30001 on your host to - port 5000 inside the pods it routes to, allowing you to reach your app - from the network. - -To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - -## Deploy and check your application - -1. In a terminal, navigate to `docker-rust-postgres` and deploy your application - to Kubernetes. - - ```console - $ kubectl apply -f docker-rust-kubernetes.yaml - ``` - - You should see output that looks like the following, indicating your Kubernetes objects were created successfully. - - ```shell - deployment.apps/server created - deployment.apps/db created - service/server created - service/db created - ``` - -2. Make sure everything worked by listing your deployments. - - ```console - $ kubectl get deployments - ``` - - Your deployment should be listed as follows: - - ```shell - NAME READY UP-TO-DATE AVAILABLE AGE - db 1/1 1 1 2m21s - server 1/1 1 1 2m21s - ``` - - This indicates all of the pods you asked for in your YAML are up and running. Do the same check for your services. - - ```console - $ kubectl get services - ``` - - You should get output like the following. - - ```shell - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - db ClusterIP 10.105.167.81 <none> 5432/TCP 109s - kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 9d - server NodePort 10.101.235.213 <none> 5000:30001/TCP 109s - ``` - - In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. - -3. In a terminal, curl the service. - - ```console - $ curl http://localhost:30001/users - [{"id":1,"login":"root"}] - ``` - -4. Run the following command to tear down your application. - - ```console - $ kubectl delete -f docker-rust-kubernetes.yaml - ``` - -## Summary - -In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. - -Related information: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/use-desktop/kubernetes.md) -- [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/rust/develop.md b/content/guides/rust/develop.md deleted file mode 100644 index b3cbdf0198ec..000000000000 --- a/content/guides/rust/develop.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: Develop your Rust application -linkTitle: Develop your app -weight: 20 -keywords: rust, local, development, run, -description: Learn how to develop your Rust application locally. -aliases: - - /language/rust/develop/ - - /guides/language/rust/develop/ ---- - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have completed the walkthroughs in the Docker Desktop [Learning Center](/manuals/desktop/use-desktop/_index.md) to learn about Docker concepts. -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -## Overview - -In this section, you’ll learn how to use volumes and networking in Docker. You’ll also use Docker to build your images and Docker Compose to make everything a whole lot easier. - -First, you’ll take a look at running a database in a container and how you can use volumes and networking to persist your data and let your application talk with the database. Then you’ll pull everything together into a Compose file which lets you set up and run a local development environment with one command. - -## Run a database in a container - -Instead of downloading PostgreSQL, installing, configuring, and then running the PostgreSQL database as a service, you can use the Docker Official Image for PostgreSQL and run it in a container. - -Before you run PostgreSQL in a container, create a volume that Docker can manage to store your persistent data and configuration. Use the named volumes feature that Docker provides instead of using bind mounts. - -Run the following command to create your volume. - -```console -$ docker volume create db-data -``` - -Now create a network that your application and database will use to talk to each other. The network is called a user-defined bridge network and gives you a nice DNS lookup service which you can use when creating your connection string. - -```console -$ docker network create postgresnet -``` - -Now you can run PostgreSQL in a container and attach to the volume and network that you created previously. Docker pulls the image from Hub and runs it for you locally. -In the following command, option `--mount` is for starting the container with a volume. For more information, see [Docker volumes](/manuals/engine/storage/volumes.md). - -```console -$ docker run --rm -d --mount \ - "type=volume,src=db-data,target=/var/lib/postgresql" \ - -p 5432:5432 \ - --network postgresnet \ - --name db \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -e POSTGRES_DB=example \ - postgres:18 -``` - -Now, make sure that your PostgreSQL database is running and that you can connect to it. Connect to the running PostgreSQL database inside the container. - -```console -$ docker exec -it db psql -U postgres -``` - -You should see output like the following. - -```console -psql (15.3 (Debian 15.3-1.pgdg110+1)) -Type "help" for help. - -postgres=# -``` - -In the previous command, you logged in to the PostgreSQL database by passing the `psql` command to the `db` container. Press ctrl-d to exit the PostgreSQL interactive terminal. - -## Get and run the sample application - -For the sample application, you'll use a variation of the backend from the react-rust-postgres application from [Awesome Compose](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres). - -1. Clone the sample application repository using the following command. - - ```console - $ git clone https://github.com/docker/docker-rust-postgres - ``` - -2. In the cloned repository's directory, create a `Dockerfile`. This application includes a `migrations` directory (in addition to `src`) to initialize the database, so the Dockerfile includes a bind mount for that directory in the build stage. - - ```dockerfile {hl_lines="28"} - # syntax=docker/dockerfile:1 - - # Comments are provided throughout this file to help you get started. - # If you need more help, visit the Dockerfile reference guide at - # https://docs.docker.com/reference/dockerfile/ - - ################################################################################ - # Create a stage for building the application. - - ARG RUST_VERSION=1.70.0 - ARG APP_NAME=react-rust-postgres - FROM rust:${RUST_VERSION}-slim-bullseye AS build - ARG APP_NAME - WORKDIR /app - - # Build the application. - # Leverage a cache mount to /usr/local/cargo/registry/ - # for downloaded dependencies and a cache mount to /app/target/ for - # compiled dependencies which will speed up subsequent builds. - # Leverage a bind mount to the src directory to avoid having to copy the - # source code into the container. Once built, copy the executable to an - # output directory before the cache mounted /app/target is unmounted. - RUN --mount=type=bind,source=src,target=src \ - --mount=type=bind,source=Cargo.toml,target=Cargo.toml \ - --mount=type=bind,source=Cargo.lock,target=Cargo.lock \ - --mount=type=cache,target=/app/target/ \ - --mount=type=cache,target=/usr/local/cargo/registry/ \ - --mount=type=bind,source=migrations,target=migrations \ - <<EOF - set -e - cargo build --locked --release - cp ./target/release/$APP_NAME /bin/server - EOF - - ################################################################################ - # Create a new stage for running the application that contains the minimal - # runtime dependencies for the application. This often uses a different base - # image from the build stage where the necessary files are copied from the build - # stage. - # - # The example below uses the debian bullseye image as the foundation for running the app. - # By specifying the "bullseye-slim" tag, it will also use whatever happens to be the - # most recent version of that tag when you build your Dockerfile. If - # reproducibility is important, consider using a digest - # (e.g., debian@sha256:ac707220fbd7b67fc19b112cee8170b41a9e97f703f588b2cdbbcdcecdd8af57). - FROM debian:bullseye-slim AS final - - # Create a non-privileged user that the app will run under. - # See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/ #user - ARG UID=10001 - RUN adduser \ - --disabled-password \ - --gecos "" \ - --home "/nonexistent" \ - --shell "/sbin/nologin" \ - --no-create-home \ - --uid "${UID}" \ - appuser - USER appuser - - # Copy the executable from the "build" stage. - COPY --from=build /bin/server /bin/ - - # Expose the port that the application listens on. - EXPOSE 8000 - - # What the container should run when it is started. - CMD ["/bin/server"] - ``` - -3. In the cloned repository's directory, run `docker build` to build the image. - - ```console - $ docker build -t rust-backend-image . - ``` - -4. Run `docker run` with the following options to run the image as a container on the same network as the database. - - ```console - $ docker run \ - --rm -d \ - --network postgresnet \ - --name docker-develop-rust-container \ - -p 3001:8000 \ - -e PG_DBNAME=example \ - -e PG_HOST=db \ - -e PG_USER=postgres \ - -e PG_PASSWORD=mysecretpassword \ - -e ADDRESS=0.0.0.0:8000 \ - -e RUST_LOG=debug \ - rust-backend-image - ``` - -5. Curl the application to verify that it connects to the database. - - ```console - $ curl http://localhost:3001/users - ``` - - You should get a response like the following. - - ```json - [{ "id": 1, "login": "root" }] - ``` - -## Use Compose to develop locally - -In the cloned repository's directory, create a `compose.yaml` file. Using Compose, you don't have to type all the parameters to pass to the `docker run` command — you can declare them in the file instead. - -You need to update the following items in the `compose.yaml` file: - -- Uncomment all of the database instructions. -- Add the environment variables under the server service. - -The following is the updated `compose.yaml` file. - -```yaml {hl_lines=["17-23","30-55"]} -# Comments are provided throughout this file to help you get started. -# If you need more help, visit the Docker compose reference guide at -# https://docs.docker.com/reference/compose-file/ - -# Here the instructions define your application as a service called "server". -# This service is built from the Dockerfile in the current directory. -# You can add other services your application may depend on here, such as a -# database or a cache. For examples, see the Awesome Compose repository: -# https://github.com/docker/awesome-compose -services: - server: - build: - context: . - target: final - ports: - - 8000:8000 - environment: - - PG_DBNAME=example - - PG_HOST=db - - PG_USER=postgres - - PG_PASSWORD=mysecretpassword - - ADDRESS=0.0.0.0:8000 - - RUST_LOG=debug - # The commented out section below is an example of how to define a PostgreSQL - # database that your application can use. `depends_on` tells Docker Compose to - # start the database before your application. The `db-data` volume persists the - # database data between container restarts. The `db-password` secret is used - # to set the database password. You must create `db/password.txt` and add - # a password of your choosing to it before running `docker compose up`. - depends_on: - db: - condition: service_healthy - db: - image: postgres:18 - restart: always - user: postgres - secrets: - - db-password - volumes: - - db-data:/var/lib/postgresql - environment: - - POSTGRES_DB=example - - POSTGRES_PASSWORD_FILE=/run/secrets/db-password - expose: - - 5432 - healthcheck: - test: ["CMD", "pg_isready"] - interval: 10s - timeout: 5s - retries: 5 -volumes: - db-data: -secrets: - db-password: - file: db/password.txt -``` - -Note that the file doesn't specify a network for those 2 services. When you use Compose, it automatically creates a network and connects the services to it. For more information see [Networking in Compose](/manuals/compose/how-tos/networking.md). - -Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. - -In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file. - -```text -mysecretpassword -``` - -If you have any other containers running from the previous sections, [stop](./run-containers.md#stop-start-and-name-containers) them now. - -Now, run the following `docker compose up` command to start your application. - -```console -$ docker compose up --build -``` - -The command passes the `--build` flag so Docker will compile your image and then start the containers. - -Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands: - -```console -$ curl http://localhost:8000/users -``` - -You should receive the following response: - -```json -[{ "id": 1, "login": "root" }] -``` - -## Summary - -In this section, you took a look at setting up your Compose file to run your Rust application and database with a single command. - -Related information: - -- [Docker volumes](/manuals/engine/storage/volumes.md) -- [Compose overview](/manuals/compose/_index.md) - -## Next steps - -In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/rust/run-containers.md b/content/guides/rust/run-containers.md deleted file mode 100644 index 9dba632af2a2..000000000000 --- a/content/guides/rust/run-containers.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Run your Rust image as a container -linkTitle: Run containers -weight: 10 -keywords: rust, run, image, container, -description: Learn how to run your Rust image as a container. -aliases: - - /language/rust/run-containers/ - - /guides/language/rust/run-containers/ ---- - -## Prerequisite - -You have completed [Build your Rust image](build-images.md) and you have built an image. - -## Overview - -A container is a normal operating system process except that Docker isolates this process so that it has its own file system, its own networking, and its own isolated process tree separate from the host. - -To run an image inside of a container, you use the `docker run` command. The `docker run` command requires one parameter which is the name of the image. - -## Run an image - -Use `docker run` to run the image you built in [Build your Rust image](build-images.md). - -```console -$ docker run docker-rust-image-dhi -``` - -After running this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a server that runs in a loop waiting for incoming requests without returning control back to the OS until you stop the container. - -Open a new terminal then make a request to the server using the `curl` command. - -```console -$ curl http://localhost:8000 -``` - -You should see output like the following. - -```console -curl: (7) Failed to connect to localhost port 8000 after 2236 ms: Couldn't connect to server -``` - -As you can see, your `curl` command failed. This means you weren't able to connect to the localhost on port 8000. This is normal because your container is running in isolation which includes networking. Stop the container and restart with port 8000 published on your local network. - -To stop the container, press ctrl-c. This will return you to the terminal prompt. - -To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host port]:[container port]`. So, if you wanted to expose port 8000 inside the container to port 3001 outside the container, you would pass `3001:8000` to the `--publish` flag. - -You didn't specify a port when running the application in the container and the default is 8000. If you want your previous request going to port 8000 to work, you can map the host's port 3001 to the container's port 8000: - -```console -$ docker run --publish 3001:8000 docker-rust-image-dhi -``` - -Now, rerun the curl command. Remember to open a new terminal. - -```console -$ curl http://localhost:3001 -``` - -You should see output like the following. - -```console -Hello, Docker! -``` - -Success! You were able to connect to the application running inside of your container on port 8000. Switch back to the terminal where your container is running and stop it. - -Press ctrl-c to stop the container. - -## Run in detached mode - -This is great so far, but your sample application is a web server and you don't have to be connected to the container. Docker can run your container in detached mode or in the background. To do this, you can use the `--detach` or `-d` for short. Docker starts your container the same as before but this time will "detach" from the container and return you to the terminal prompt. - -```console -$ docker run -d -p 3001:8000 docker-rust-image-dhi -3e4830e7f01304811d97dd3469d47a0c7a916a8b6c28ce0ef19c6f689a521144 -``` - -Docker started your container in the background and printed the Container ID on the terminal. - -Again, make sure that your container is running properly. Run the curl command again. - -```console -$ curl http://localhost:3001 -``` - -You should see output like the following. - -```console -Hello, Docker! -``` - -## List containers - -Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how you use the ps command in Linux to see a list of processes. - -You should see output like the following. - -```console -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -3e4830e7f013 docker-rust-image-dhi "/server" 23 seconds ago Up 22 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp youthful_lamport -``` - -The `docker ps` command provides a bunch of information about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that were exposed, and the name of the container. - -You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You’ll fix this in a minute, but first you need to stop the container. To stop the container, run the `docker stop` command which does just that, stops the container. You need to pass the name of the container or you can use the container ID. - -```console -$ docker stop youthful_lamport -youthful_lamport -``` - -Now, rerun the `docker ps` command to see a list of running containers. - -```console -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -## Stop, start, and name containers - -You can start, stop, and restart Docker containers. When you stop a container, it's not removed, but the status is changed to stopped and the process inside the container is stopped. When you ran the `docker ps` command in the previous module, the default output only shows running containers. When you pass the `--all` or `-a` for short, you see all containers on your machine, irrespective of their start or stop status. - -```console -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -3e4830e7f013 docker-rust-image-dhi "/server" About a minute ago Exited (0) 28 seconds ago youthful_lamport -60009b7eaf40 docker-rust-image-dhi "/server" 2 minutes ago Exited (0) About a minute ago sharp_noyce -152e1d7d9eea docker-rust-image-dhi "/server ." 4 minutes ago Exited (0) 2 minutes ago magical_bhabha -``` - -You should now see several containers listed. These are containers that you started and stopped but you haven't removed. - -Restart the container that you just stopped. Locate the name of the container you just stopped and replace the name of the container in following restart command. - -```console -$ docker restart youthful_lamport -``` - -Now list all the containers again using the `docker ps --all` command. - -```console -$ docker ps --all -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -3e4830e7f013 docker-rust-image-dhi "/server" 3 minutes ago Up 7 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp youthful_lamport -60009b7eaf40 docker-rust-image-dhi "/server" 4 minutes ago Exited (0) 3 minutes ago sharp_noyce -152e1d7d9eea docker-rust-image-dhi "/server ." 5 minutes ago Exited (0) 4 minutes ago magical_bhabha -``` - -Notice that the container you just restarted has been started in detached mode. Also, observe the status of the container is "Up X seconds". When you restart a container, it starts with the same flags or commands that it was originally started with. - -Now, stop and remove all of your containers and take a look at fixing the random naming issue. Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system. - -```console -$ docker stop youthful_lamport -youthful_lamport -``` - -Now that you have stopped all of your containers, remove them. When you remove a container, it's no longer running, nor is it in the stopped status, but the process inside the container has been stopped and the metadata for the container has been removed. - -To remove a container, run the `docker rm` command with the container name. You can pass multiple container names to the command using a single command. Again, replace the container names in the following command with the container names from your system. - -```console -$ docker rm youthful_lamport friendly_montalcini tender_bose -youthful_lamport -sharp_noyce -magical_bhabha -``` - -Run the `docker ps --all` command again to see that Docker removed all containers. - -Now, it's time to address the random naming issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with. - -To name a container, pass the `--name` flag to the `docker run` command. - -```console -$ docker run -d -p 3001:8000 --name docker-rust-container docker-rust-image-dhi -1aa5d46418a68705c81782a58456a4ccdb56a309cb5e6bd399478d01eaa5cdda -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -219b2e3c7c38 docker-rust-image-dhi "/server" 6 seconds ago Up 5 seconds 0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp docker-rust-container -``` - -Now you can identify your container based on the name. - -## Summary - -In this section, you took a look at running containers. You also took a look at managing containers by starting, stopping, and restarting them. And finally, you looked at naming your containers so they are more identifiable. - -Related information: - -- [docker run CLI reference](/reference/cli/docker/container/run/) - -## Next steps - -In the next section, you’ll learn how to run a database in a container and connect it to a Rust application. diff --git a/content/guides/sentiment-analysis.md b/content/guides/sentiment-analysis.md deleted file mode 100644 index 725899efe9fc..000000000000 --- a/content/guides/sentiment-analysis.md +++ /dev/null @@ -1,368 +0,0 @@ ---- -title: Build a sentiment analysis app -linkTitle: Sentiment analysis -keywords: nlp, natural language processing, sentiment analysis, python, nltk -description: Learn how to build and run a sentiment analysis application using Python, NLTK, and Docker. -summary: | - This guide demonstrates how to containerize sentiment analysis models using - Docker. -tags: [ai] -languages: [python] -aliases: - - /guides/use-case/nlp/sentiment-analysis/ -params: - time: 20 minutes ---- - -## Overview - -In this guide, you learn how to build and run a sentiment analysis application. -You'll build the application using Python with the Natural Language Toolkit -(NLTK), and then set up the environment and run the application using Docker. - -The application analyzes user input text for sentiment using NLTK's -SentimentIntensityAnalyzer and outputs whether the sentiment is positive, -negative, or neutral. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Get the sample application - -1. Open a terminal, and clone the sample application's repository using the - following command. - - ```console - $ git clone https://github.com/harsh4870/Docker-NLP.git - ``` - -2. Verify that you cloned the repository. - - You should see the following files in your `Docker-NLP` directory. - - ```text - 01_sentiment_analysis.py - 02_name_entity_recognition.py - 03_text_classification.py - 04_text_summarization.py - 05_language_translation.py - entrypoint.sh - requirements.txt - Dockerfile - README.md - ``` - -## Explore the application code - -The source code for the sentiment analysis application is in the `Docker-NLP/01_sentiment_analysis.py` file. Open `01_sentiment_analysis.py` in a text or code editor to explore its contents in the following steps. - -1. Import the required libraries. - - ```python - import nltk - from nltk.sentiment import SentimentIntensityAnalyzer - import ssl - ``` - - - `nltk`: This is the Natural Language Toolkit library used for working with - human language data in Python. - - `SentimentIntensityAnalyzer`: This is a specific tool from NLTK used for - determining the sentiment of a piece of text. - - `ssl`: This module provides access to Transport Layer Security (encryption) - functions used for secure web connections. - -2. Handle SSL certificate verification. - - ```python - try: - _create_unverified_https_context = ssl._create_unverified_context - except AttributeError: - pass - else: - ssl._create_default_https_context = _create_unverified_https_context - ``` - - This block is a workaround for certain environments where downloading data through NLTK might fail due to SSL certificate verification issues. It's telling Python to ignore SSL certificate verification for HTTPS requests. - -3. Download NLTK resources. - - ```python - nltk.download('vader_lexicon') - nltk.download('punkt') - ``` - - - `vader_lexicon`: This is a lexicon used by the `SentimentIntensityAnalyzer` - for sentiment analysis. - - `punkt`: This is used by NLTK for tokenizing sentences. It's necessary for - the `SentimentIntensityAnalyzer` to function correctly. - -4. Create a sentiment analysis function. - - ```python - def perform_semantic_analysis(text): - sid = SentimentIntensityAnalyzer() - sentiment_score = sid.polarity_scores(text) - - if sentiment_score['compound'] >= 0.05: - return "Positive" - elif sentiment_score['compound'] <= -0.05: - return "Negative" - else: - return "Neutral" - ``` - - - `SentimentIntensityAnalyzer()` creates an instance of the - analyzer. - - `polarity_scores(text)` generates a sentiment score for the input text. - - The function returns **Positive**, **Negative**, or **Neutral** based on the - compound score. - -5. Create the main loop. - - ```python - if __name__ == "__main__": - while True: - input_text = input("Enter the text for semantic analysis (type 'exit' to end): ") - - if input_text.lower() == 'exit': - print("Exiting...") - break - - result = perform_semantic_analysis(input_text) - print(f"Sentiment: {result}") - ``` - - This part of the script runs an infinite loop to accept user input for - analysis. If the user types `exit`, the program terminates. Otherwise, it - prints out the sentiment of the provided text. - -6. Create `requirements.txt`. - - The sample application already contains the - `requirements.txt` file to specify the necessary packages that the - application imports. Open `requirements.txt` in a code or text editor to - explore its contents. - - ```text - # 01 sentiment_analysis - nltk==3.6.5 - - ... - ``` - - Only the `nltk` package is required for the sentiment analysis application. - -## Explore the application environment - -You'll use Docker to run the application in a container. Docker lets you -containerize the application, providing a consistent and isolated environment -for running it. This means the application will operate as intended within its -Docker container, regardless of the underlying system differences. - -To run the application in a container, a Dockerfile is required. A Dockerfile is -a text document that contains all the commands you would call on the command -line to assemble an image. An image is a read-only template with instructions -for creating a Docker container. - -The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents. - -The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/). - -1. Specify the base image. - - ```dockerfile - FROM python:3.8-slim - ``` - - This command sets the foundation for the build. `python:3.8-slim` is a - lightweight version of the Python 3.8 image, optimized for size and speed. - Using this slim image reduces the overall size of your Docker image, leading - to quicker downloads and less surface area for security vulnerabilities. This - is particularly useful for a Python-based application where you might not - need the full standard Python image. - -2. Set the working directory. - - ```dockerfile - WORKDIR /app - ``` - - `WORKDIR` sets the current working directory within the Docker image. By - setting it to `/app`, you ensure that all subsequent commands in the - Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also - helps in organizing your Docker image, as all application-related files are - contained in a specific directory. - -3. Copy the requirements file into the image. - - ```dockerfile - COPY requirements.txt /app - ``` - - The `COPY` command transfers the `requirements.txt` file from - your local machine into the Docker image. This file lists all Python - dependencies required by the application. Copying it into the container - lets the next command (`RUN pip install`) install these dependencies - inside the image environment. - -4. Install the Python dependencies in the image. - - ```dockerfile - RUN pip install --no-cache-dir -r requirements.txt - ``` - - This line uses `pip`, Python's package installer, to install the packages - listed in `requirements.txt`. The `--no-cache-dir` option disables - the cache, which reduces the size of the Docker image by not storing the - unnecessary cache data. - -5. Run additional commands. - - ```dockerfile - RUN python -m spacy download en_core_web_sm - ``` - - This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile. - -6. Copy the application code into the image. - - ```dockerfile - COPY *.py /app - COPY entrypoint.sh /app - ``` - - These commands copy your Python scripts and the `entrypoint.sh` script into - the image's `/app` directory. This is crucial because the container needs - these scripts to run the application. The `entrypoint.sh` script is - particularly important as it dictates how the application starts inside the - container. - -7. Set permissions for the `entrypoint.sh` script. - - ```dockerfile - RUN chmod +x /app/entrypoint.sh - ``` - - This command modifies the file permissions of `entrypoint.sh`, making it - executable. This step is necessary to ensure that the Docker container can - run this script to start the application. - -8. Set the entry point. - - ```dockerfile - ENTRYPOINT ["/app/entrypoint.sh"] - ``` - - The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` - as its default executable. This means that when the container starts, it - automatically executes the script. - - You can explore the `entrypoint.sh` script by opening it in a code or text - editor. As the sample contains several applications, the script lets you - specify which application to run when the container starts. - -## Run the application - -To run the application using Docker: - -1. Build the image. - - In a terminal, run the following command inside the directory of where the `Dockerfile` is located. - - ```console - $ docker build -t basic-nlp . - ``` - - The following is a break down of the command: - - - `docker build`: This is the primary command used to build a Docker image - from a Dockerfile and a context. The context is typically a set of files at - a specified location, often the directory containing the Dockerfile. - - `-t basic-nlp`: This is an option for tagging the image. The `-t` flag - stands for tag. It assigns a name to the image, which in this case is - `basic-nlp`. Tags are a convenient way to reference images later, - especially when pushing them to a registry or running containers. - - `.`: This is the last part of the command and specifies the build context. - The period (`.`) denotes the current directory. Docker will look for a - Dockerfile in this directory. The build context (the current directory, in - this case) is sent to the Docker daemon to enable the build. It includes - all the files and subdirectories in the specified directory. - - Docker outputs several logs to your console as it builds the image. You'll - see it download and install the dependencies. Depending on your network - connection, this may take several minutes. Docker does have a caching - feature, so subsequent builds can be faster. The console will - return to the prompt when it's complete. - - For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/). - -2. Run the image as a container. - - In a terminal, run the following command. - - ```console - $ docker run -it basic-nlp 01_sentiment_analysis.py - ``` - - The following is a break down of the command: - - - `docker run`: This is the primary command used to run a new container from - a Docker image. - - `-it`: This is a combination of two options: - - `-i` or `--interactive`: This keeps the standard input (STDIN) open even - if not attached. It lets the container remain running in the - foreground and be interactive. - - `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a - terminal, like a command prompt or a shell. It's what lets you - interact with the application inside the container. - - `basic-nlp`: This specifies the name of the Docker image to use for - creating the container. In this case, it's the image named `basic-nlp` that - you created with the `docker build` command. - - `01_sentiment_analysis.py`: This is the script you want to run inside the - Docker container. It gets passed to the `entrypoint.sh` script, which runs - it when the container starts. - - For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/). - - > [!NOTE] - > - > For Windows users, you may get an error when running the container. Verify - > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers). - - You will see the following in your console after the container starts. - - ```console - Enter the text for semantic analysis (type 'exit' to end): - ``` - -3. Test the application. - - Enter a comment to get the sentiment analysis. - - ```console - Enter the text for semantic analysis (type 'exit' to end): I love containers! - Sentiment: Positive - Enter the text for semantic analysis (type 'exit' to end): I'm still learning about containers. - Sentiment: Neutral - ``` - -## Summary - -In this guide, you learned how to build and run a sentiment analysis -application. You learned how to build the application using Python with NLTK, -and then set up the environment and run the application using Docker. - -Related information: - -- [Docker CLI reference](/reference/cli/docker/) -- [Dockerfile reference](/reference/dockerfile/) -- [Natural Language Toolkit](https://www.nltk.org/) -- [Python documentation](https://docs.python.org/3/) - -## Next steps - -Explore more [natural language processing guides](./_index.md). diff --git a/content/guides/swarm-deploy.md b/content/guides/swarm-deploy.md deleted file mode 100644 index ff04acec9554..000000000000 --- a/content/guides/swarm-deploy.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Deploy to Swarm -keywords: swarm, swarm services, stacks -description: Learn how to describe and deploy a simple application on Docker Swarm. -aliases: - - /get-started/part4/ - - /get-started/swarm-deploy/ - - /guides/deployment-orchestration/swarm-deploy/ -summary: | - Discover how to deploy and manage Docker containers using Docker Swarm. -tags: [deploy] -params: - time: 10 minutes ---- - -{{% include "swarm-mode.md" %}} - -## Prerequisites - -- Download and install Docker Desktop as described in [Get Docker](/get-started/get-docker.md). -- Work through containerizing an application in [Docker workshop part 2](/get-started/workshop/02_our_app.md) -- Make sure that Swarm is enabled on your Docker Desktop by typing `docker system info`, and looking for a message `Swarm: active` (you might have to scroll up a little). - - If Swarm isn't running, simply type `docker swarm init` in a shell prompt to set it up. - -## Introduction - -Now that you've demonstrated that the individual components of your application run as stand-alone containers and shown how to deploy it using Kubernetes, you can look at how to arrange for them to be managed by Docker Swarm. Swarm provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves. - -In order to validate that your containerized application works well on Swarm, you'll use Docker Desktop's built in Swarm environment right on your development machine to deploy your application, before handing it off to run on a full Swarm cluster in production. The Swarm environment created by Docker Desktop is fully featured, meaning it has all the Swarm features your app will enjoy on a real cluster, accessible from the convenience of your development machine. - -## Describe apps using stack files - -Swarm never creates individual containers like you did in the previous step of this tutorial. Instead, all Swarm workloads are scheduled as services, which are scalable groups of containers with added networking features maintained automatically by Swarm. Furthermore, all Swarm objects can and should be described in manifests called stack files. These YAML files describe all the components and configurations of your Swarm app, and can be used to create and destroy your app in any Swarm environment. - -Now you can write a simple stack file to run and manage your Todo app, the container `getting-started` image created in [Part 2](02_our_app.md) of the tutorial. Place the following in a file called `bb-stack.yaml`: - -{{% include "swarm-compose-compat.md" %}} - -```yaml -version: "3.7" - -services: - bb-app: - image: getting-started - ports: - - "8000:3000" -``` - -In this Swarm YAML file, there is one object, a `service`, describing a scalable group of identical containers. In this case, you'll get just one container (the default), and that container will be based on your `getting-started` image created in [Part 2](02_our_app.md) of the tutorial. In addition, you've asked Swarm to forward all traffic arriving at port 8000 on your development machine to port 3000 inside our getting-started container. - -> **Kubernetes Services and Swarm Services are very different** -> -> Despite the similar name, the two orchestrators mean very different things by -> the term 'service'. In Swarm, a service provides both scheduling and -> networking facilities, creating containers and providing tools for routing -> traffic to them. In Kubernetes, scheduling and networking are handled -> separately, deployments (or other controllers) handle the scheduling of -> containers as pods, while services are responsible only for adding -> networking features to those pods. - -## Deploy and check your application - -1. Deploy your application to Swarm: - - ```console - $ docker stack deploy -c bb-stack.yaml demo - ``` - - If all goes well, Swarm will report creating all your stack objects with no complaints: - - ```shell - Creating network demo_default - Creating service demo_bb-app - ``` - - Notice that in addition to your service, Swarm also creates a Docker network by default to isolate the containers deployed as part of your stack. - -2. Make sure everything worked by listing your service: - - ```console - $ docker service ls - ``` - - If all has gone well, your service will report with 1/1 of its replicas created: - - ```shell - ID NAME MODE REPLICAS IMAGE PORTS - il7elwunymbs demo_bb-app replicated 1/1 getting-started:latest *:8000->3000/tcp - ``` - - This indicates 1/1 containers you asked for as part of your services are up and running. Also, you see that port 8000 on your development machine is getting forwarded to port 3000 in your getting-started container. - -3. Open a browser and visit your Todo app at `localhost:8000`; you should see your Todo application, the same as when you ran it as a stand-alone container in [Part 2](02_our_app.md) of the tutorial. - -4. Once satisfied, tear down your application: - - ```console - $ docker stack rm demo - ``` - -## Conclusion - -At this point, you've successfully used Docker Desktop to deploy your application to a fully-featured Swarm environment on your development machine. You can now add other components to your app and taking advantage of all the features and power of Swarm, right on your own machine. - -In addition to deploying to Swarm, you've also described your application as a stack file. This simple text file contains everything you need to create your application in a running state; you can check it in to version control and share it with your colleagues, letting you to distribute your applications to other clusters (like the testing and production clusters that probably come after your development environments). - -## Swarm and CLI references - -Further documentation for all new Swarm objects and CLI commands used in this article are available here: - -- [Swarm Mode](/manuals/engine/swarm/_index.md) -- [Swarm Mode Services](/manuals/engine/swarm/how-swarm-mode-works/services.md) -- [Swarm Stacks](/manuals/engine/swarm/stack-deploy.md) -- [`docker stack *`](/reference/cli/docker/stack/) -- [`docker service *`](/reference/cli/docker/service/) diff --git a/content/guides/tensorflowjs.md b/content/guides/tensorflowjs.md deleted file mode 100644 index 6b1a2e398edc..000000000000 --- a/content/guides/tensorflowjs.md +++ /dev/null @@ -1,561 +0,0 @@ ---- -description: Learn how to deploy pre-trained models in a TensorFlow.js web applications to perform face detection. -keywords: tensorflow.js, machine learning, ml, mediapipe, blazeface, face detection -title: Face detection with TensorFlow.js -summary: | - This guide explains how to run TensorFlow.js in Docker containers. -tags: [ai] -languages: [js] -aliases: - - /guides/use-case/tensorflowjs/ -params: - time: 20 minutes ---- - -This guide introduces the seamless integration of TensorFlow.js with Docker to -perform face detection. In this guide, you'll explore how to: - -- Run a containerized TensorFlow.js application using Docker. -- Implement face detection in a web application with TensorFlow.js. -- Construct a Dockerfile for a TensorFlow.js web application. -- Use Docker Compose for real-time application development and updates. -- Share your Docker image on Docker Hub to facilitate deployment and extend - reach. - -> **Acknowledgment** -> -> Docker would like to thank [Harsh Manvar](https://github.com/harsh4870) for -> his contribution to this guide. - -## Prerequisites - -- You have installed the latest version of - [Docker Desktop](/get-started/get-docker.md). -- You have a [Git client](https://git-scm.com/downloads). The examples in this - guide use a command-line based Git client, but you can use any client. - -## What is TensorFlow.js? - -[TensorFlow.js](https://www.tensorflow.org/js) is an open-source JavaScript -library for machine learning that enables you to train and deploy ML models in -the browser or on Node.js. It supports creating new models from scratch or using -pre-trained models, facilitating a wide range of ML applications directly in web -environments. TensorFlow.js offers efficient computation, making sophisticated -ML tasks accessible to web developers without deep ML expertise. - -## Why use TensorFlow.js and Docker together? - -- Environment consistency and simplified deployment: Docker packages - TensorFlow.js applications and their dependencies into containers, ensuring - consistent runs across all environments and simplifying deployment. -- Efficient development and easy scaling: Docker enhances development efficiency - with features like hot reloading and facilitates easy scaling of - - TensorFlow.js applications using orchestration tools like Kubernetes. -- Isolation and enhanced security: Docker isolates TensorFlow.js applications in - secure environments, minimizing conflicts and security vulnerabilities while - running applications with limited permissions. - -## Get and run the sample application - -In a terminal, clone the sample application using the following command. - -```console -$ git clone https://github.com/harsh4870/TensorJS-Face-Detection -``` - -After cloning the application, you'll notice the application has a `Dockerfile`. -This Dockerfile lets you build and run the application locally with nothing more -than Docker. - -Before you run the application as a container, you must build it into an image. -Run the following command inside the `TensorJS-Face-Detection` directory to -build an image named `face-detection-tensorjs`. - -```console -$ docker build -t face-detection-tensorjs . -``` - -The command builds the application into an image. Depending on your network -connection, it can take several minutes to download the necessary components the -first time you run the command. - -To run the image as a container, run the following command in a terminal. - -```console -$ docker run -p 80:80 face-detection-tensorjs -``` - -The command runs the container and maps port 80 in the container to port 80 on -your system. - -Once the application is running, open a web browser and access the application -at [http://localhost:80](http://localhost:80). You may need to grant access to -your webcam for the application. - -In the web application, you can change the backend to use one of the following: - -- WASM -- WebGL -- CPU - -To stop the application, press `ctrl`+`c` in the terminal. - -## About the application - -The sample application performs real-time face detection using -[MediaPipe](https://developers.google.com/mediapipe/), a comprehensive framework -for building multimodal machine learning pipelines. It's specifically using the -BlazeFace model, a lightweight model for detecting faces in images. - -In the context of TensorFlow.js or similar web-based machine learning -frameworks, the WASM, WebGL, and CPU backends can be used to -execute operations. Each of these backends utilizes different resources and -technologies available in modern browsers and has its strengths and limitations. -The following sections are a brief breakdown of the different backends. - -### WASM - -WebAssembly (WASM) is a low-level, assembly-like language with a compact binary -format that runs at near-native speed in web browsers. It allows code written in -languages like C/C++ to be compiled into a binary that can be executed in the -browser. - -It's a good choice when high performance is required, and either the WebGL -backend is not supported or you want consistent performance across all devices -without relying on the GPU. - -### WebGL - -WebGL is a browser API that allows for GPU-accelerated usage of physics and -image processing and effects as part of the web page canvas. - -WebGL is well-suited for operations that are parallelizable and can -significantly benefit from GPU acceleration, such as matrix multiplications and -convolutions commonly found in deep learning models. - -### CPU - -The CPU backend uses pure JavaScript execution, utilizing the device's central -processing unit (CPU). This backend is the most universally compatible and -serves as a fallback when neither WebGL nor WASM backends are available or -suitable. - -## Explore the application's code - -Explore the purpose of each file and their contents in the following sections. - -### The index.html file - -The `index.html` file serves as the frontend for the web application that -utilizes TensorFlow.js for real-time face detection from the webcam video feed. -It incorporates several technologies and libraries to facilitate machine -learning directly in the browser. It uses several TensorFlow.js libraries, -including: - -- tfjs-core and tfjs-converter for core TensorFlow.js functionality and model - conversion. -- tfjs-backend-webgl, tfjs-backend-cpu, and the tf-backend-wasm script - for different computational backend options that TensorFlow.js can use for - processing. These backends allow the application to perform machine learning - tasks efficiently by leveraging the user's hardware capabilities. -- The BlazeFace library, a TensorFlow model for face detection. - -It also uses the following additional libraries: - -- dat.GUI for creating a graphical interface to interact with the application's - settings in real-time, such as switching between TensorFlow.js backends. -- Stats.min.js for displaying performance metrics (like FPS) to monitor the - application's efficiency during operation. - -{{< accordion title="index.html" >}} - -```html -<style> - body { - margin: 25px; - } - - .true { - color: green; - } - - .false { - color: red; - } - - #main { - position: relative; - margin: 50px 0; - } - - canvas { - position: absolute; - top: 0; - left: 0; - } - - #description { - margin-top: 20px; - width: 600px; - } - - #description-title { - font-weight: bold; - font-size: 18px; - } -</style> - -<body> - <div id="main"> - <video - id="video" - playsinline - style=" - -webkit-transform: scaleX(-1); - transform: scaleX(-1); - width: auto; - height: auto; - " - ></video> - <canvas id="output"></canvas> - <video - id="video" - playsinline - style=" - -webkit-transform: scaleX(-1); - transform: scaleX(-1); - visibility: hidden; - width: auto; - height: auto; - " - ></video> - </div> -</body> -<script src="https://unpkg.com/@tensorflow/tfjs-core@2.1.0/dist/tf-core.js"></script> -<script src="https://unpkg.com/@tensorflow/tfjs-converter@2.1.0/dist/tf-converter.js"></script> - -<script src="https://unpkg.com/@tensorflow/tfjs-backend-webgl@2.1.0/dist/tf-backend-webgl.js"></script> -<script src="https://unpkg.com/@tensorflow/tfjs-backend-cpu@2.1.0/dist/tf-backend-cpu.js"></script> -<script src="./tf-backend-wasm.js"></script> - -<script src="https://unpkg.com/@tensorflow-models/blazeface@0.0.5/dist/blazeface.js"></script> -<script src="https://cdnjs.cloudflare.com/ajax/libs/dat-gui/0.7.6/dat.gui.min.js"></script> -<script src="https://cdnjs.cloudflare.com/ajax/libs/stats.js/r16/Stats.min.js"></script> -<script src="./index.js"></script> -``` - -{{< /accordion >}} - -### The index.js file - -The `index.js` file conducts the facial detection logic. It demonstrates several -advanced concepts in web development and machine learning integration. Here's a -breakdown of some of its key components and functionalities: - -- Stats.js: The script starts by creating a Stats instance to monitor and - display the frame rate (FPS) of the application in real time. This is helpful - for performance analysis, especially when testing the impact of different - TensorFlow.js backends on the application's speed. -- TensorFlow.js: The application allows users to switch between different - computation backends (wasm, webgl, and cpu) for TensorFlow.js through a - graphical interface provided by dat.GUI. Changing the backend can affect - performance and compatibility depending on the device and browser. The - addFlagLabels function dynamically checks and displays whether SIMD (Single - Instruction, Multiple Data) and multithreading are supported, which are - relevant for performance optimization in the wasm backend. -- setupCamera function: Initializes the user's webcam using the MediaDevices Web - API. It configures the video stream to not include audio and to use the - front-facing camera (facingMode: 'user'). Once the video metadata is loaded, - it resolves a promise with the video element, which is then used for face - detection. -- BlazeFace: The core of this application is the renderPrediction function, - which performs real-time face detection using the BlazeFace model, a - lightweight model for detecting faces in images. The function calls - model.estimateFaces on each animation frame to detect faces from the video - feed. For each detected face, it draws a red rectangle around the face and - blue dots for facial landmarks on a canvas overlaying the video. - -{{< accordion title="index.js" >}} - -```javascript -const stats = new Stats(); -stats.showPanel(0); -document.body.prepend(stats.domElement); - -let model, ctx, videoWidth, videoHeight, video, canvas; - -const state = { - backend: "wasm", -}; - -const gui = new dat.GUI(); -gui - .add(state, "backend", ["wasm", "webgl", "cpu"]) - .onChange(async (backend) => { - await tf.setBackend(backend); - addFlagLabels(); - }); - -async function addFlagLabels() { - if (!document.querySelector("#simd_supported")) { - const simdSupportLabel = document.createElement("div"); - simdSupportLabel.id = "simd_supported"; - simdSupportLabel.style = "font-weight: bold"; - const simdSupported = await tf.env().getAsync("WASM_HAS_SIMD_SUPPORT"); - simdSupportLabel.innerHTML = `SIMD supported: <span class=${simdSupported}>${simdSupported}<span>`; - document.querySelector("#description").appendChild(simdSupportLabel); - } - - if (!document.querySelector("#threads_supported")) { - const threadSupportLabel = document.createElement("div"); - threadSupportLabel.id = "threads_supported"; - threadSupportLabel.style = "font-weight: bold"; - const threadsSupported = await tf - .env() - .getAsync("WASM_HAS_MULTITHREAD_SUPPORT"); - threadSupportLabel.innerHTML = `Threads supported: <span class=${threadsSupported}>${threadsSupported}</span>`; - document.querySelector("#description").appendChild(threadSupportLabel); - } -} - -async function setupCamera() { - video = document.getElementById("video"); - - const stream = await navigator.mediaDevices.getUserMedia({ - audio: false, - video: { facingMode: "user" }, - }); - video.srcObject = stream; - - return new Promise((resolve) => { - video.onloadedmetadata = () => { - resolve(video); - }; - }); -} - -const renderPrediction = async () => { - stats.begin(); - - const returnTensors = false; - const flipHorizontal = true; - const annotateBoxes = true; - const predictions = await model.estimateFaces( - video, - returnTensors, - flipHorizontal, - annotateBoxes, - ); - - if (predictions.length > 0) { - ctx.clearRect(0, 0, canvas.width, canvas.height); - - for (let i = 0; i < predictions.length; i++) { - if (returnTensors) { - predictions[i].topLeft = predictions[i].topLeft.arraySync(); - predictions[i].bottomRight = predictions[i].bottomRight.arraySync(); - if (annotateBoxes) { - predictions[i].landmarks = predictions[i].landmarks.arraySync(); - } - } - - const start = predictions[i].topLeft; - const end = predictions[i].bottomRight; - const size = [end[0] - start[0], end[1] - start[1]]; - ctx.fillStyle = "rgba(255, 0, 0, 0.5)"; - ctx.fillRect(start[0], start[1], size[0], size[1]); - - if (annotateBoxes) { - const landmarks = predictions[i].landmarks; - - ctx.fillStyle = "blue"; - for (let j = 0; j < landmarks.length; j++) { - const x = landmarks[j][0]; - const y = landmarks[j][1]; - ctx.fillRect(x, y, 5, 5); - } - } - } - } - - stats.end(); - - requestAnimationFrame(renderPrediction); -}; - -const setupPage = async () => { - await tf.setBackend(state.backend); - addFlagLabels(); - await setupCamera(); - video.play(); - - videoWidth = video.videoWidth; - videoHeight = video.videoHeight; - video.width = videoWidth; - video.height = videoHeight; - - canvas = document.getElementById("output"); - canvas.width = videoWidth; - canvas.height = videoHeight; - ctx = canvas.getContext("2d"); - ctx.fillStyle = "rgba(255, 0, 0, 0.5)"; - - model = await blazeface.load(); - - renderPrediction(); -}; - -setupPage(); -``` - -{{< /accordion >}} - -### The tf-backend-wasm.js file - -The `tf-backend-wasm.js` file is part of the -[TensorFlow.js library](https://github.com/tensorflow/tfjs/tree/master/tfjs-backend-wasm). -It contains initialization logic for the TensorFlow.js WASM backend, some -utilities for interacting with the WASM binaries, and functions to set custom -paths for the WASM binaries. - -### The tfjs-backend-wasm-simd.wasm file - -The `tfjs-backend-wasm-simd.wasm` file is part of the -[TensorFlow.js library](https://github.com/tensorflow/tfjs/tree/master/tfjs-backend-wasm). -It's a WASM binary that's used for the WebAssembly -backend, specifically optimized to utilize SIMD (Single Instruction, Multiple -Data) instructions. - -## Explore the Dockerfile - -In a Docker-based project, the Dockerfile serves as the foundational -asset for building your application's environment. - -A Dockerfile is a text file that instructs Docker how to create an image of your -application's environment. An image contains everything you want and -need when running application, such as files, packages, and tools. - -The following is the Dockerfile for this project. - -```dockerfile -FROM nginx:stable-alpine3.17-slim -WORKDIR /usr/share/nginx/html -COPY . . -``` - -This Dockerfile defines an image that serves static content using Nginx from an -Alpine Linux base image. - -## Develop with Compose - -Docker Compose is a tool for defining and running multi-container Docker -applications. With Compose, you use a YAML file to configure your application's -services, networks, and volumes. In this case, the application isn't a -multi-container application, but Docker Compose has other useful features for -development, like [Compose Watch](/manuals/compose/how-tos/file-watch.md). - -The sample application doesn't have a Compose file yet. To create a Compose -file, in the `TensorJS-Face-Detection` directory, create a text file named -`compose.yaml` and then add the following contents. - -```yaml -services: - server: - build: - context: . - ports: - - 80:80 - develop: - watch: - - action: sync - path: . - target: /usr/share/nginx/html -``` - -This Compose file defines a service that is built using the Dockerfile in the -same directory. It maps port 80 on the host to port 80 in the container. It also -has a `develop` subsection with the `watch` attribute that defines a list of -rules that control automatic service updates based on local file changes. For -more details about the Compose instructions, see the -[Compose file reference](/reference/compose-file/_index.md). - -Save the changes to your `compose.yaml` file and then run the following command to run the application. - -```console -$ docker compose watch -``` - -Once the application is running, open a web browser and access the application -at [http://localhost:80](http://localhost:80). You may need to grant access to -your webcam for the application. - -Now you can make changes to the source code and see the changes automatically -reflected in the container without having to rebuild and rerun the container. - -Open the `index.js` file and update the landmark points to be green instead of -blue on line 83. - -```diff -- ctx.fillStyle = "blue"; -+ ctx.fillStyle = "green"; -``` - -Save the changes to the `index.js` file and then refresh the browser page. The -landmark points should now appear green. - -To stop the application, press `ctrl`+`c` in the terminal. - -## Share your image - -Publishing your Docker image on Docker Hub streamlines deployment processes for -others, enabling seamless integration into diverse projects. It also promotes -the adoption of your containerized solutions, broadening their impact across the -developer ecosystem. To share your image: - -1. [Sign up](https://www.docker.com/pricing?ref=Docs&refAction=DocsGuidesTensorflowjs) or sign in to [Docker Hub](https://hub.docker.com). - -2. Rebuild your image to include the changes to your application. This time, - prefix the image name with your Docker ID. Docker uses the name to determine - which repository to push it to. Open a terminal and run the following - command in the `TensorJS-Face-Detection` directory. Replace `YOUR-USER-NAME` - with your Docker ID. - - ```console - $ docker build -t YOUR-USER-NAME/face-detection-tensorjs . - ``` - -3. Run the following `docker push` command to push the image to Docker Hub. - Replace `YOUR-USER-NAME` with your Docker ID. - - ```console - $ docker push YOUR-USER-NAME/face-detection-tensorjs - ``` - -4. Verify that you pushed the image to Docker Hub. - 1. Go to [Docker Hub](https://hub.docker.com). - 2. Select **My Hub** > **Repositories**. - 3. View the **Last pushed** time for your repository. - -Other users can now download and run your image using the `docker run` command. They need to replace `YOUR-USER-NAME` with your Docker ID. - -```console -$ docker run -p 80:80 YOUR-USER-NAME/face-detection-tensorjs -``` - -## Summary - -This guide demonstrated leveraging TensorFlow.js and Docker for face detection -in web applications. It highlighted the ease of running containerized -TensorFlow.js applications, and developing with Docker Compose for real-time -code changes. Additionally, it covered how sharing your Docker image on Docker -Hub can streamline deployment for others, enhancing the application's reach -within the developer community. - -Related information: - -- [TensorFlow.js website](https://www.tensorflow.org/js) -- [MediaPipe website](https://developers.google.com/mediapipe/) -- [Dockerfile reference](/reference/dockerfile/) -- [Compose file reference](/reference/compose-file/_index.md) -- [Docker CLI reference](/reference/cli/docker/) -- [Docker Blog: Accelerating Machine Learning with TensorFlow.js](https://www.docker.com/blog/accelerating-machine-learning-with-tensorflow-js-using-pretrained-models-and-docker/) diff --git a/content/guides/testcontainers-cloud/_index.md b/content/guides/testcontainers-cloud/_index.md deleted file mode 100644 index 1310bcdf6261..000000000000 --- a/content/guides/testcontainers-cloud/_index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: | - Mastering Testcontainers Cloud by Docker: streamlining integration testing with containers -linkTitle: Testcontainers Cloud by Docker -summary: | - Automate, scale, and optimize testing workflows with Testcontainers Cloud -description: | - Testcontainers Cloud by Docker streamlines integration testing by offloading container management to the cloud. It enables faster, consistent tests for containerized services like databases, improving performance and scalability in CI/CD pipelines without straining local or CI resources. Ideal for developers needing efficient, reliable testing environments. -keywords: testcontainers cloud, integration testing, ci/cd, containerized tests, cloud testing, scalable testing -tags: [product-demo] -params: - image: images/learning-paths/testcontainers-cloud-learning-path.png - time: 12 minutes - resource_links: - - title: Testcontainers Guides - url: https://testcontainers.com/guides - - title: Testcontainers Best Practices - url: https://www.docker.com/blog/testcontainers-best-practices/ - - title: Simple local development with Testcontainers Desktop - url: https://testcontainers.com/guides/simple-local-development-with-testcontainers-desktop/ - - title: Streamlining Local Development with Dev Containers and Testcontainers Cloud - url: https://www.docker.com/blog/streamlining-local-development-with-dev-containers-and-testcontainers-cloud/ - - title: Running Testcontainers Tests Using GitHub Actions and Testcontainers Cloud - url: https://www.docker.com/blog/running-testcontainers-tests-using-github-actions/ - - title: Testcontainers Cloud on the Docker Blog - url: https://www.docker.com/search/?_sf_s=testcontainers%20cloud ---- - -Testcontainers Cloud is a cloud-based solution designed to streamline and enhance the process of running integration tests using Testcontainers. Testcontainers is the open source framework, which allows developers to easily spin up containerized dependencies such as databases, message brokers, and other services required for testing. By shifting the management of Testcontainers-based services to the cloud, Testcontainers Cloud optimizes performance, reduces resource constraints on local machines or CI servers, and ensures consistent test environments. This solution is particularly beneficial for teams working on complex, distributed systems, as it allows for scalable, isolated, and reliable testing without the typical overhead of managing containers locally. - -## What you'll learn - -- Understand the fundamentals of Docker Testcontainers Cloud and its role in integration testing. -- Learn how to set up and configure Docker Testcontainers Cloud for automated testing in various environments. -- Explore how Testcontainers Cloud integrates with CI/CD pipelines to streamline testing workflows. - -## Tools integration - -Works well with Docker Desktop, GitHub Actions, Jenkins, Kubernetes, and other CI solutions - -Docker Pro, Team, and Business subscriptions come with Testcontainers Cloud runtime minutes, and additional minutes are available via consumption pricing. Testcontainers Cloud runtime minutes do not rollover month to month. - -## Who’s this for? - -- Teams that build cloud-native applications and are already using Testcontainers open source. -- DevOps Teams that integrate automated container-based testing into CI/CD pipelines for continuous testing. -- QA Teams that seek scalable and consistent test environments for comprehensive integration and end-to-end testing. -- Developers who need reliable, containerized test environments for testing microservices and databases. diff --git a/content/guides/testcontainers-cloud/common-questions.md b/content/guides/testcontainers-cloud/common-questions.md deleted file mode 100644 index 549af8e0f159..000000000000 --- a/content/guides/testcontainers-cloud/common-questions.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Common challenges and questions -description: Explore common challenges and questions related to Testcontainers Cloud by Docker. -keywords: testcontainers cloud, faq, integration testing, troubleshooting, cloud testing -weight: 40 ---- - -<!-- vale Docker.HeadingLength = NO --> - -### How is Testcontainers Cloud different from the open-source Testcontainers framework? - -While the open-source Testcontainers is a library that provides a lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers, Testcontainers Cloud provides a cloud runtime for these containers. This reduces the resource strain on local environments and provides more scalability, especially in CI/CD workflows, that enables consistent Testcontainers experience across the organization. - -### What types of containers can I run with Testcontainers Cloud? - -Testcontainers Cloud supports any containers you would typically use with the Testcontainers framework, including databases (PostgreSQL, MySQL, MongoDB), message brokers (Kafka, RabbitMQ), and other services required for integration testing. - -### Do I need to change my existing test code to use Testcontainers Cloud? - -No, you don't need to change your existing test code. Testcontainers Cloud integrates seamlessly with the open-source Testcontainers framework. Once the cloud configuration is set up, it automatically manages the containers in the cloud without requiring code changes. - -### How do I integrate Testcontainers Cloud into my project? - -To integrate Testcontainers Cloud, you need to install the Testcontainers Desktop app and select run with Testcontainers Cloud option in the menu. In CI you’ll need to add a workflow step that downloads Testcontainers Cloud agent. No code changes are required beyond enabling Cloud runtime via the Testcontainers Desktop app locally or installing Testcontainers Cloud agent in CI. - -### Can I use Testcontainers Cloud in a CI/CD pipeline? - -Yes, Testcontainers Cloud is designed to work efficiently in CI/CD pipelines. It helps reduce build times and resource bottlenecks by offloading containers that you spin up with Testcontainers library to the cloud, making it a perfect fit for continuous testing environments. - -### What are the benefits of using Testcontainers Cloud? - -The key benefits include reduced resource usage on local machines and CI servers, scalability (run more containers without performance degradation), consistent testing environments, centralized monitoring, ease of CI configuration with removed security concerns of running Docker-in-Docker or a privileged daemon. - -### Does Testcontainers Cloud support all programming languages? - -Testcontainers Cloud supports any language that works with the open-source Testcontainers libraries, including Java, Python, Node.js, Go, and others. As long as your project uses Testcontainers, it can be offloaded to Testcontainers Cloud. - -### How is container cleanup handled in Testcontainers Cloud? - -While Testcontainers library automatically handles container lifecycle management, Testcontainers Cloud manages the allocated cloud worker lifetime. This means that containers are spun up, monitored, and cleaned up after tests are completed by Testcontainers library, and the worker where these containers have being running will be removed automatically after the ~35 min idle period by Testcontainers Cloud. This approach frees developers from manually managing containers and associated cloud resources. - -### Is there a free tier or pricing model for Testcontainers Cloud? - -Pricing details for Testcontainers Cloud can be found on the [pricing page](https://testcontainers.com/cloud/pricing/). diff --git a/content/guides/testcontainers-cloud/demo-ci.md b/content/guides/testcontainers-cloud/demo-ci.md deleted file mode 100644 index 71cdc625f093..000000000000 --- a/content/guides/testcontainers-cloud/demo-ci.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Configuring Testcontainers Cloud in the CI Pipeline -description: Use Testcontainers Cloud with GitHub Workflows to automate testing in a CI pipeline. -keywords: testcontainers cloud, ci/cd, github actions, integration testing, cloud testing -weight: 30 ---- - -{{< youtube-embed "NlZY9aumKJU" >}} - -This demo shows how Testcontainers Cloud can be seamlessly integrated into a -Continuous Integration (CI) pipeline using GitHub Workflows, providing a -powerful solution for running containerized integration tests without -overloading local or CI runner resources. By leveraging GitHub Actions, -developers can automate the process of spinning up and managing containers for -testing in the cloud, ensuring faster and more reliable test execution. With -just a few configuration steps, including setting up Testcontainers Cloud -authentication and adding it to your workflow, you can offload container -orchestration to the cloud. This approach improves the scalability of your -pipeline, ensures consistency across tests, and simplifies resource management, -making it an ideal solution for modern, containerized development workflows. - -- Understand how to set up a GitHub Actions workflow to automate the build and testing of a project. -- Learn how to configure Testcontainers Cloud within GitHub Actions to offload containerized testing to the cloud, improving efficiency and resource management. -- Explore how Testcontainers Cloud integrates with GitHub workflows to run integration tests that require containerized services, such as databases and message brokers. diff --git a/content/guides/testcontainers-cloud/demo-local.md b/content/guides/testcontainers-cloud/demo-local.md deleted file mode 100644 index 870e4e0be783..000000000000 --- a/content/guides/testcontainers-cloud/demo-local.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Setting up Testcontainers Cloud by Docker -description: Set up Testcontainers Cloud by Docker in a local development environment. -keywords: testcontainers cloud, local development, testcontainers desktop, integration testing, setup -weight: 20 ---- - -{{< youtube-embed "7c3xLAG560U" >}} - -This demo shows the process of setting up Testcontainers Cloud by Docker to -work in your local development environment using the Testcontainers Desktop -application. By the end of this walkthrough, you'll have Testcontainers Cloud -by Docker up and running, ready to offload container management from your local -machine to the cloud for more efficient testing. - -- Install and configure Testcontainers Cloud and the CLI to seamlessly integrate with your local development environment. -- Set up and configure the Testcontainers Desktop application to monitor and manage cloud-based containers during local tests. -- Create and run integration tests using Testcontainers that leverage cloud-based container resources. -- Monitor and manage containers efficiently, understanding how Testcontainers Cloud automates cleanup and ensures consistent testing environments. -- Review options for monitoring and troubleshooting in the Testcontainers Cloud Dashboard. diff --git a/content/guides/testcontainers-cloud/why.md b/content/guides/testcontainers-cloud/why.md deleted file mode 100644 index e09cbfbf7d0d..000000000000 --- a/content/guides/testcontainers-cloud/why.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Why Testcontainers Cloud? -description: Learn how Testcontainers Cloud by Docker can help you optimize integration testing. -keywords: testcontainers cloud, integration testing, scalable testing, ci/cd, cloud testing -weight: 10 ---- - -{{< youtube-embed "6dRRlk5Vd0E" >}} - -Testcontainers Cloud is a powerful cloud-based solution designed to optimize integration testing with Testcontainers by offloading container management to the cloud. It helps developers and teams overcome the limitations of traditional local and CI-based testing, ensuring consistent environments, faster test execution, and scalable workflows. Whether you're new to Testcontainers or looking to enhance your existing setup, Testcontainers Cloud offers a seamless way to manage containerized tests, improving efficiency and reliability in your development pipeline. - -Testcontainers Cloud provides several benefits: - -- **Offloading to the Cloud:** Frees up local resources by shifting container management to the cloud, keeping your laptop responsive. -- **Consistent Testing Environments:** Ensures that tests run in isolated, reliable environments, reducing inconsistencies across platforms from Dev to CI. -- **Scalability:** Allows running large numbers of containers simultaneously without being limited by local or CI resources. -- **Faster CI/CD Pipelines:** Reduces configuration bottlenecks and speeds up build times by offloading containers to multiple on-demand cloud workers with the Turbo-mode feature. - -Testcontainers Cloud streamlines integration testing by offloading container management to the cloud, ensuring consistent environments and faster test execution resulting in reduced resource strain, making it an essential tool for improving the stability of your Testcontainers-based workflows. diff --git a/content/guides/testcontainers-dotnet-aspnet-core.md b/content/guides/testcontainers-dotnet-aspnet-core.md new file mode 100644 index 000000000000..31769970ae01 --- /dev/null +++ b/content/guides/testcontainers-dotnet-aspnet-core.md @@ -0,0 +1,501 @@ +--- +title: Testing an ASP.NET Core web app with Testcontainers +linkTitle: ASP.NET Core testing +description: Learn how to use Testcontainers for .NET to replace SQLite with a real Microsoft SQL Server in ASP.NET Core integration tests. +keywords: testcontainers, dotnet, csharp, testing, mssql, asp.net core, integration testing, entity framework +summary: | + Learn how to test an ASP.NET Core web app using Testcontainers for .NET + with a real Microsoft SQL Server instance instead of SQLite. +aliases: + - /guides/testcontainers-dotnet-aspnet-core/create-project/ + - /guides/testcontainers-dotnet-aspnet-core/run-tests/ + - /guides/testcontainers-dotnet-aspnet-core/write-tests/ +params: + tags: [testing] + time: 25 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-testing-aspnet-core --> + +In this guide, you'll learn how to: + +- Use Testcontainers for .NET to spin up a Microsoft SQL Server container for integration tests +- Replace SQLite with a production-like database provider in ASP.NET Core tests +- Customize `WebApplicationFactory` to configure test dependencies with Testcontainers +- Manage container lifecycle with xUnit's `IAsyncLifetime` + +## Prerequisites + +- .NET 8.0+ SDK +- A code editor or IDE (Visual Studio, VS Code, Rider) +- A Docker environment supported by Testcontainers. For details, see the + [Testcontainers .NET system requirements](https://dotnet.testcontainers.org/supported_docker_environment/). + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Set up the project + +### Background + +This guide builds on top of Microsoft's +[Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests) +documentation. The original sample uses an in-memory SQLite database as the +backing store for integration tests. You'll replace SQLite with a real +Microsoft SQL Server instance running in a Docker container using +Testcontainers. + +You can find the original code sample in the +[dotnet/AspNetCore.Docs.Samples](https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/test/integration-tests/IntegrationTestsSample) +repository. + +### Clone the repository + +Clone the Testcontainers guide repository and change into the project +directory: + +```console +$ git clone https://github.com/testcontainers/tc-guide-testing-aspnet-core.git +$ cd tc-guide-testing-aspnet-core +``` + +### Project structure + +The solution contains two projects: + +```text +RazorPagesProject.sln +├── src/RazorPagesProject/ # ASP.NET Core Razor Pages app +└── tests/RazorPagesProject.Tests/ # xUnit integration tests +``` + +#### Application project + +The application project (`src/RazorPagesProject/RazorPagesProject.csproj`) +is a Razor Pages web app that uses Entity Framework Core with SQLite as its +default database provider: + +```xml +<Project Sdk="Microsoft.NET.Sdk.Web"> + + <PropertyGroup> + <TargetFramework>net9.0</TargetFramework> + <ImplicitUsings>enable</ImplicitUsings> + </PropertyGroup> + + <ItemGroup> + <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" /> + <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0"> + <PrivateAssets>all</PrivateAssets> + <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> + </PackageReference> + </ItemGroup> + +</Project> +``` + +The `ApplicationDbContext` stores `Message` entities and provides methods to +query and manage them: + +```csharp +public class ApplicationDbContext : IdentityDbContext +{ + public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) + : base(options) + { + } + + public virtual DbSet<Message> Messages { get; set; } + + public async virtual Task<List<Message>> GetMessagesAsync() + { + return await Messages + .OrderBy(message => message.Text) + .AsNoTracking() + .ToListAsync(); + } + + public async virtual Task AddMessageAsync(Message message) + { + await Messages.AddAsync(message); + await SaveChangesAsync(); + } + + public async virtual Task DeleteAllMessagesAsync() + { + foreach (Message message in Messages) + { + Messages.Remove(message); + } + + await SaveChangesAsync(); + } + + public async virtual Task DeleteMessageAsync(int id) + { + var message = await Messages.FindAsync(id); + + if (message != null) + { + Messages.Remove(message); + await SaveChangesAsync(); + } + } + + public void Initialize() + { + Messages.AddRange(GetSeedingMessages()); + SaveChanges(); + } + + public static List<Message> GetSeedingMessages() + { + return new List<Message>() + { + new Message(){ Text = "You're standing on my scarf." }, + new Message(){ Text = "Would you like a jelly baby?" }, + new Message(){ Text = "To the rational mind, nothing is inexplicable; only unexplained." } + }; + } +} +``` + +#### Test project + +The test project (`tests/RazorPagesProject.Tests/RazorPagesProject.Tests.csproj`) +includes xUnit, the ASP.NET Core testing infrastructure, and the +Testcontainers MSSQL module: + +```xml +<Project Sdk="Microsoft.NET.Sdk.Web"> + + <PropertyGroup> + <TargetFramework>net9.0</TargetFramework> + <ImplicitUsings>enable</ImplicitUsings> + </PropertyGroup> + + <ItemGroup> + <PackageReference Include="AngleSharp" Version="0.17.1" /> + <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" /> + <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="7.0.0" /> + <PackageReference Include="Microsoft.EntityFrameworkCore" Version="7.0.0" /> + <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" /> + <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="7.0.0" /> + <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0"> + <PrivateAssets>all</PrivateAssets> + <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> + </PackageReference> + + <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.4.0" /> + + <PackageReference Include="Testcontainers.MsSql" Version="3.0.0" /> + <PackageReference Include="xunit" Version="2.4.2" /> + <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5"> + <PrivateAssets>all</PrivateAssets> + <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> + </PackageReference> + </ItemGroup> + + <ItemGroup> + <ProjectReference Include="..\..\src\RazorPagesProject\RazorPagesProject.csproj" /> + </ItemGroup> + + <ItemGroup> + <Content Update="xunit.runner.json"> + <CopyToOutputDirectory>Always</CopyToOutputDirectory> + </Content> + </ItemGroup> + +</Project> +``` + +The key dependencies are: + +- `Microsoft.AspNetCore.Mvc.Testing` - provides `WebApplicationFactory` for + bootstrapping the app in tests +- `Microsoft.EntityFrameworkCore.SqlServer` - the SQL Server database provider + for Entity Framework Core +- `Testcontainers.MsSql` - the Testcontainers module for Microsoft SQL Server + +#### Existing SQLite-based test factory + +The original project includes a `CustomWebApplicationFactory` that replaces +the application's database with an in-memory SQLite instance: + +```csharp +public class CustomWebApplicationFactory<TProgram> + : WebApplicationFactory<TProgram> where TProgram : class +{ + protected override void ConfigureWebHost(IWebHostBuilder builder) + { + builder.ConfigureServices(services => + { + var dbContextDescriptor = services.SingleOrDefault( + d => d.ServiceType == + typeof(DbContextOptions<ApplicationDbContext>)); + + services.Remove(dbContextDescriptor); + + var dbConnectionDescriptor = services.SingleOrDefault( + d => d.ServiceType == + typeof(DbConnection)); + + services.Remove(dbConnectionDescriptor); + + // Create open SqliteConnection so EF won't automatically close it. + services.AddSingleton<DbConnection>(container => + { + var connection = new SqliteConnection("DataSource=:memory:"); + connection.Open(); + + return connection; + }); + + services.AddDbContext<ApplicationDbContext>((container, options) => + { + var connection = container.GetRequiredService<DbConnection>(); + options.UseSqlite(connection); + }); + }); + + builder.UseEnvironment("Development"); + } +} +``` + +While this approach works, SQLite has behavioral differences from the database +you'd use in production. In the next section, you'll replace it with a +Testcontainers-managed Microsoft SQL Server instance. + +## Write tests with Testcontainers + +The existing tests use an in-memory SQLite database. While convenient, this +doesn't match production behavior. You can replace it with a real Microsoft SQL +Server instance managed by Testcontainers. + +### Add dependencies + +Change to the test project directory and add the SQL Server Entity Framework +provider and the Testcontainers MSSQL module: + +```console +$ cd tests/RazorPagesProject.Tests +$ dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 7.0.0 +$ dotnet add package Testcontainers.MsSql --version 3.0.0 +``` + +> [!NOTE] +> Testcontainers for .NET offers a range of +> [modules](https://www.nuget.org/profiles/Testcontainers) that follow best +> practice configurations. + +### Create the test class + +Create a `MsSqlTests.cs` file in the `IntegrationTests` directory. This class +manages the SQL Server container lifecycle and contains a nested test class. + +```csharp +using System.Data.Common; +using System.Net; +using AngleSharp.Html.Dom; +using Microsoft.AspNetCore.Mvc.Testing; +using Microsoft.EntityFrameworkCore; +using RazorPagesProject.Data; +using RazorPagesProject.Tests.Helpers; +using Testcontainers.MsSql; +using Xunit; + +namespace RazorPagesProject.Tests.IntegrationTests; + +public sealed class MsSqlTests : IAsyncLifetime +{ + private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build(); + + public Task InitializeAsync() + { + return _msSqlContainer.StartAsync(); + } + + public Task DisposeAsync() + { + return _msSqlContainer.DisposeAsync().AsTask(); + } + + public sealed class IndexPageTests : IClassFixture<MsSqlTests>, IDisposable + { + private readonly WebApplicationFactory<Program> _webApplicationFactory; + + private readonly HttpClient _httpClient; + + public IndexPageTests(MsSqlTests fixture) + { + var clientOptions = new WebApplicationFactoryClientOptions(); + clientOptions.AllowAutoRedirect = false; + + _webApplicationFactory = new CustomWebApplicationFactory(fixture); + _httpClient = _webApplicationFactory.CreateClient(clientOptions); + } + + public void Dispose() + { + _webApplicationFactory.Dispose(); + } + + [Fact] + public async Task Post_DeleteAllMessagesHandler_ReturnsRedirectToRoot() + { + // Arrange + var defaultPage = await _httpClient.GetAsync("/") + .ConfigureAwait(false); + + var document = await HtmlHelpers.GetDocumentAsync(defaultPage) + .ConfigureAwait(false); + + // Act + var form = (IHtmlFormElement)document.QuerySelector("form[id='messages']"); + var submitButton = (IHtmlButtonElement)document.QuerySelector("button[id='deleteAllBtn']"); + + var response = await _httpClient.SendAsync(form, submitButton) + .ConfigureAwait(false); + + // Assert + Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode); + Assert.Equal(HttpStatusCode.Redirect, response.StatusCode); + Assert.Equal("/", response.Headers.Location.OriginalString); + } + + private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program> + { + private readonly string _connectionString; + + public CustomWebApplicationFactory(MsSqlTests fixture) + { + _connectionString = fixture._msSqlContainer.GetConnectionString(); + } + + protected override void ConfigureWebHost(IWebHostBuilder builder) + { + builder.ConfigureServices(services => + { + services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType)); + services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType)); + services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString)); + }); + } + } + } +} +``` + +### Understand the test structure + +#### Container lifecycle with IAsyncLifetime + +The outer `MsSqlTests` class implements `IAsyncLifetime`. xUnit calls +`InitializeAsync()` right after creating the class instance, which starts the +SQL Server container. After all tests complete, `DisposeAsync()` stops and +removes the container. + +```csharp +private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build(); +``` + +`MsSqlBuilder().Build()` creates a pre-configured Microsoft SQL Server +container. Testcontainers modules follow best practices, so you don't need +to configure ports, passwords, or startup wait strategies yourself. + +#### Nested test class with IClassFixture + +The `IndexPageTests` class is nested inside `MsSqlTests` and implements +`IClassFixture<MsSqlTests>`. This gives the test class access to the +container's private field and creates a clean hierarchy in the test explorer. + +#### Custom WebApplicationFactory + +Instead of using the SQLite-based factory, the nested +`CustomWebApplicationFactory` retrieves the connection string from the running +SQL Server container and passes it to `UseSqlServer()`: + +```csharp +private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program> +{ + private readonly string _connectionString; + + public CustomWebApplicationFactory(MsSqlTests fixture) + { + _connectionString = fixture._msSqlContainer.GetConnectionString(); + } + + protected override void ConfigureWebHost(IWebHostBuilder builder) + { + builder.ConfigureServices(services => + { + services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType)); + services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType)); + services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString)); + }); + } +} +``` + +This factory: + +1. Removes the existing `DbContextOptions<ApplicationDbContext>` registration +2. Removes the existing `DbConnection` registration +3. Adds a new `ApplicationDbContext` configured with the SQL Server connection + string from the Testcontainers-managed container + +> [!NOTE] +> The Microsoft SQL Server Docker image isn't compatible with ARM devices, such +> as Macs with Apple Silicon. You can use the +> [SqlEdge](https://www.nuget.org/packages/Testcontainers.SqlEdge) module or +> [Testcontainers Cloud](https://www.testcontainers.cloud/) as alternatives. + +## Run tests and next steps + +### Run the tests + +Run the tests from the solution root: + +```console +$ dotnet test ./RazorPagesProject.sln +``` + +The first run may take longer because Docker needs to pull the Microsoft SQL +Server image. On subsequent runs, the image is cached locally. + +You should see xUnit discover and run the tests, including the +`MsSqlTests.IndexPageTests` class. Testcontainers starts a SQL Server +container, the tests execute against it, and the container is stopped and +removed automatically after the tests finish. + +### Summary + +By replacing SQLite with a Testcontainers-managed Microsoft SQL Server +instance, the integration tests run against the same type of database used in +production. This approach catches database-specific issues early, such as +differences in SQL dialect, transaction behavior, or data type handling between +SQLite and SQL Server. + +The `MsSqlTests` class uses `IAsyncLifetime` to manage the container lifecycle, +and a nested `CustomWebApplicationFactory` wires the container's connection +string into the application's service configuration. You can apply this same +pattern to any database or service that Testcontainers supports. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testcontainers for .NET documentation](https://dotnet.testcontainers.org/) +- [Testcontainers for .NET modules](https://dotnet.testcontainers.org/modules/) +- [Microsoft SQL Server module](https://www.nuget.org/packages/Testcontainers.MsSql) +- [Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests) diff --git a/content/guides/testcontainers-dotnet-aspnet-core/_index.md b/content/guides/testcontainers-dotnet-aspnet-core/_index.md deleted file mode 100644 index 92480b54d167..000000000000 --- a/content/guides/testcontainers-dotnet-aspnet-core/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Testing an ASP.NET Core web app with Testcontainers -linkTitle: ASP.NET Core testing -description: Learn how to use Testcontainers for .NET to replace SQLite with a real Microsoft SQL Server in ASP.NET Core integration tests. -keywords: testcontainers, dotnet, csharp, testing, mssql, asp.net core, integration testing, entity framework -summary: | - Learn how to test an ASP.NET Core web app using Testcontainers for .NET - with a real Microsoft SQL Server instance instead of SQLite. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [c-sharp] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-aspnet-core --> - -In this guide, you'll learn how to: - -- Use Testcontainers for .NET to spin up a Microsoft SQL Server container for integration tests -- Replace SQLite with a production-like database provider in ASP.NET Core tests -- Customize `WebApplicationFactory` to configure test dependencies with Testcontainers -- Manage container lifecycle with xUnit's `IAsyncLifetime` - -## Prerequisites - -- .NET 8.0+ SDK -- A code editor or IDE (Visual Studio, VS Code, Rider) -- A Docker environment supported by Testcontainers. For details, see the - [Testcontainers .NET system requirements](https://dotnet.testcontainers.org/supported_docker_environment/). - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-dotnet-aspnet-core/create-project.md b/content/guides/testcontainers-dotnet-aspnet-core/create-project.md deleted file mode 100644 index 9b1e2a93969c..000000000000 --- a/content/guides/testcontainers-dotnet-aspnet-core/create-project.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Set up the project -linkTitle: Create the project -description: Set up an ASP.NET Core Razor Pages project with integration test dependencies. -keywords: testcontainers, dotnet, asp.net core, getting started, project setup -weight: 10 ---- - -## Background - -This guide builds on top of Microsoft's -[Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests) -documentation. The original sample uses an in-memory SQLite database as the -backing store for integration tests. You'll replace SQLite with a real -Microsoft SQL Server instance running in a Docker container using -Testcontainers. - -You can find the original code sample in the -[dotnet/AspNetCore.Docs.Samples](https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/test/integration-tests/IntegrationTestsSample) -repository. - -## Clone the repository - -Clone the Testcontainers guide repository and change into the project -directory: - -```console -$ git clone https://github.com/testcontainers/tc-guide-testing-aspnet-core.git -$ cd tc-guide-testing-aspnet-core -``` - -## Project structure - -The solution contains two projects: - -```text -RazorPagesProject.sln -├── src/RazorPagesProject/ # ASP.NET Core Razor Pages app -└── tests/RazorPagesProject.Tests/ # xUnit integration tests -``` - -### Application project - -The application project (`src/RazorPagesProject/RazorPagesProject.csproj`) -is a Razor Pages web app that uses Entity Framework Core with SQLite as its -default database provider: - -```xml -<Project Sdk="Microsoft.NET.Sdk.Web"> - - <PropertyGroup> - <TargetFramework>net9.0</TargetFramework> - <ImplicitUsings>enable</ImplicitUsings> - </PropertyGroup> - - <ItemGroup> - <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" /> - <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0"> - <PrivateAssets>all</PrivateAssets> - <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> - </PackageReference> - </ItemGroup> - -</Project> -``` - -The `ApplicationDbContext` stores `Message` entities and provides methods to -query and manage them: - -```csharp -public class ApplicationDbContext : IdentityDbContext -{ - public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) - : base(options) - { - } - - public virtual DbSet<Message> Messages { get; set; } - - public async virtual Task<List<Message>> GetMessagesAsync() - { - return await Messages - .OrderBy(message => message.Text) - .AsNoTracking() - .ToListAsync(); - } - - public async virtual Task AddMessageAsync(Message message) - { - await Messages.AddAsync(message); - await SaveChangesAsync(); - } - - public async virtual Task DeleteAllMessagesAsync() - { - foreach (Message message in Messages) - { - Messages.Remove(message); - } - - await SaveChangesAsync(); - } - - public async virtual Task DeleteMessageAsync(int id) - { - var message = await Messages.FindAsync(id); - - if (message != null) - { - Messages.Remove(message); - await SaveChangesAsync(); - } - } - - public void Initialize() - { - Messages.AddRange(GetSeedingMessages()); - SaveChanges(); - } - - public static List<Message> GetSeedingMessages() - { - return new List<Message>() - { - new Message(){ Text = "You're standing on my scarf." }, - new Message(){ Text = "Would you like a jelly baby?" }, - new Message(){ Text = "To the rational mind, nothing is inexplicable; only unexplained." } - }; - } -} -``` - -### Test project - -The test project (`tests/RazorPagesProject.Tests/RazorPagesProject.Tests.csproj`) -includes xUnit, the ASP.NET Core testing infrastructure, and the -Testcontainers MSSQL module: - -```xml -<Project Sdk="Microsoft.NET.Sdk.Web"> - - <PropertyGroup> - <TargetFramework>net9.0</TargetFramework> - <ImplicitUsings>enable</ImplicitUsings> - </PropertyGroup> - - <ItemGroup> - <PackageReference Include="AngleSharp" Version="0.17.1" /> - <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" /> - <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="7.0.0" /> - <PackageReference Include="Microsoft.EntityFrameworkCore" Version="7.0.0" /> - <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" /> - <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="7.0.0" /> - <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0"> - <PrivateAssets>all</PrivateAssets> - <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> - </PackageReference> - - <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.4.0" /> - - <PackageReference Include="Testcontainers.MsSql" Version="3.0.0" /> - <PackageReference Include="xunit" Version="2.4.2" /> - <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5"> - <PrivateAssets>all</PrivateAssets> - <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> - </PackageReference> - </ItemGroup> - - <ItemGroup> - <ProjectReference Include="..\..\src\RazorPagesProject\RazorPagesProject.csproj" /> - </ItemGroup> - - <ItemGroup> - <Content Update="xunit.runner.json"> - <CopyToOutputDirectory>Always</CopyToOutputDirectory> - </Content> - </ItemGroup> - -</Project> -``` - -The key dependencies are: - -- `Microsoft.AspNetCore.Mvc.Testing` - provides `WebApplicationFactory` for - bootstrapping the app in tests -- `Microsoft.EntityFrameworkCore.SqlServer` - the SQL Server database provider - for Entity Framework Core -- `Testcontainers.MsSql` - the Testcontainers module for Microsoft SQL Server - -### Existing SQLite-based test factory - -The original project includes a `CustomWebApplicationFactory` that replaces -the application's database with an in-memory SQLite instance: - -```csharp -public class CustomWebApplicationFactory<TProgram> - : WebApplicationFactory<TProgram> where TProgram : class -{ - protected override void ConfigureWebHost(IWebHostBuilder builder) - { - builder.ConfigureServices(services => - { - var dbContextDescriptor = services.SingleOrDefault( - d => d.ServiceType == - typeof(DbContextOptions<ApplicationDbContext>)); - - services.Remove(dbContextDescriptor); - - var dbConnectionDescriptor = services.SingleOrDefault( - d => d.ServiceType == - typeof(DbConnection)); - - services.Remove(dbConnectionDescriptor); - - // Create open SqliteConnection so EF won't automatically close it. - services.AddSingleton<DbConnection>(container => - { - var connection = new SqliteConnection("DataSource=:memory:"); - connection.Open(); - - return connection; - }); - - services.AddDbContext<ApplicationDbContext>((container, options) => - { - var connection = container.GetRequiredService<DbConnection>(); - options.UseSqlite(connection); - }); - }); - - builder.UseEnvironment("Development"); - } -} -``` - -While this approach works, SQLite has behavioral differences from the database -you'd use in production. In the next section, you'll replace it with a -Testcontainers-managed Microsoft SQL Server instance. diff --git a/content/guides/testcontainers-dotnet-aspnet-core/run-tests.md b/content/guides/testcontainers-dotnet-aspnet-core/run-tests.md deleted file mode 100644 index affdc827232e..000000000000 --- a/content/guides/testcontainers-dotnet-aspnet-core/run-tests.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run the Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, dotnet, asp.net core, integration testing, run tests -weight: 30 ---- - -## Run the tests - -Run the tests from the solution root: - -```console -$ dotnet test ./RazorPagesProject.sln -``` - -The first run may take longer because Docker needs to pull the Microsoft SQL -Server image. On subsequent runs, the image is cached locally. - -You should see xUnit discover and run the tests, including the -`MsSqlTests.IndexPageTests` class. Testcontainers starts a SQL Server -container, the tests execute against it, and the container is stopped and -removed automatically after the tests finish. - -## Summary - -By replacing SQLite with a Testcontainers-managed Microsoft SQL Server -instance, the integration tests run against the same type of database used in -production. This approach catches database-specific issues early, such as -differences in SQL dialect, transaction behavior, or data type handling between -SQLite and SQL Server. - -The `MsSqlTests` class uses `IAsyncLifetime` to manage the container lifecycle, -and a nested `CustomWebApplicationFactory` wires the container's connection -string into the application's service configuration. You can apply this same -pattern to any database or service that Testcontainers supports. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers for .NET documentation](https://dotnet.testcontainers.org/) -- [Testcontainers for .NET modules](https://dotnet.testcontainers.org/modules/) -- [Microsoft SQL Server module](https://www.nuget.org/packages/Testcontainers.MsSql) -- [Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests) diff --git a/content/guides/testcontainers-dotnet-aspnet-core/write-tests.md b/content/guides/testcontainers-dotnet-aspnet-core/write-tests.md deleted file mode 100644 index 7ce626f91dae..000000000000 --- a/content/guides/testcontainers-dotnet-aspnet-core/write-tests.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Replace SQLite with a real Microsoft SQL Server using Testcontainers for .NET. -keywords: testcontainers, dotnet, asp.net core, sql server, integration testing, xunit -weight: 20 ---- - -The existing tests use an in-memory SQLite database. While convenient, this -doesn't match production behavior. You can replace it with a real Microsoft SQL -Server instance managed by Testcontainers. - -## Add dependencies - -Change to the test project directory and add the SQL Server Entity Framework -provider and the Testcontainers MSSQL module: - -```console -$ cd tests/RazorPagesProject.Tests -$ dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 7.0.0 -$ dotnet add package Testcontainers.MsSql --version 3.0.0 -``` - -> [!NOTE] -> Testcontainers for .NET offers a range of -> [modules](https://www.nuget.org/profiles/Testcontainers) that follow best -> practice configurations. - -## Create the test class - -Create a `MsSqlTests.cs` file in the `IntegrationTests` directory. This class -manages the SQL Server container lifecycle and contains a nested test class. - -```csharp -using System.Data.Common; -using System.Net; -using AngleSharp.Html.Dom; -using Microsoft.AspNetCore.Mvc.Testing; -using Microsoft.EntityFrameworkCore; -using RazorPagesProject.Data; -using RazorPagesProject.Tests.Helpers; -using Testcontainers.MsSql; -using Xunit; - -namespace RazorPagesProject.Tests.IntegrationTests; - -public sealed class MsSqlTests : IAsyncLifetime -{ - private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build(); - - public Task InitializeAsync() - { - return _msSqlContainer.StartAsync(); - } - - public Task DisposeAsync() - { - return _msSqlContainer.DisposeAsync().AsTask(); - } - - public sealed class IndexPageTests : IClassFixture<MsSqlTests>, IDisposable - { - private readonly WebApplicationFactory<Program> _webApplicationFactory; - - private readonly HttpClient _httpClient; - - public IndexPageTests(MsSqlTests fixture) - { - var clientOptions = new WebApplicationFactoryClientOptions(); - clientOptions.AllowAutoRedirect = false; - - _webApplicationFactory = new CustomWebApplicationFactory(fixture); - _httpClient = _webApplicationFactory.CreateClient(clientOptions); - } - - public void Dispose() - { - _webApplicationFactory.Dispose(); - } - - [Fact] - public async Task Post_DeleteAllMessagesHandler_ReturnsRedirectToRoot() - { - // Arrange - var defaultPage = await _httpClient.GetAsync("/") - .ConfigureAwait(false); - - var document = await HtmlHelpers.GetDocumentAsync(defaultPage) - .ConfigureAwait(false); - - // Act - var form = (IHtmlFormElement)document.QuerySelector("form[id='messages']"); - var submitButton = (IHtmlButtonElement)document.QuerySelector("button[id='deleteAllBtn']"); - - var response = await _httpClient.SendAsync(form, submitButton) - .ConfigureAwait(false); - - // Assert - Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode); - Assert.Equal(HttpStatusCode.Redirect, response.StatusCode); - Assert.Equal("/", response.Headers.Location.OriginalString); - } - - private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program> - { - private readonly string _connectionString; - - public CustomWebApplicationFactory(MsSqlTests fixture) - { - _connectionString = fixture._msSqlContainer.GetConnectionString(); - } - - protected override void ConfigureWebHost(IWebHostBuilder builder) - { - builder.ConfigureServices(services => - { - services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType)); - services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType)); - services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString)); - }); - } - } - } -} -``` - -## Understand the test structure - -### Container lifecycle with IAsyncLifetime - -The outer `MsSqlTests` class implements `IAsyncLifetime`. xUnit calls -`InitializeAsync()` right after creating the class instance, which starts the -SQL Server container. After all tests complete, `DisposeAsync()` stops and -removes the container. - -```csharp -private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build(); -``` - -`MsSqlBuilder().Build()` creates a pre-configured Microsoft SQL Server -container. Testcontainers modules follow best practices, so you don't need -to configure ports, passwords, or startup wait strategies yourself. - -### Nested test class with IClassFixture - -The `IndexPageTests` class is nested inside `MsSqlTests` and implements -`IClassFixture<MsSqlTests>`. This gives the test class access to the -container's private field and creates a clean hierarchy in the test explorer. - -### Custom WebApplicationFactory - -Instead of using the SQLite-based factory, the nested -`CustomWebApplicationFactory` retrieves the connection string from the running -SQL Server container and passes it to `UseSqlServer()`: - -```csharp -private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program> -{ - private readonly string _connectionString; - - public CustomWebApplicationFactory(MsSqlTests fixture) - { - _connectionString = fixture._msSqlContainer.GetConnectionString(); - } - - protected override void ConfigureWebHost(IWebHostBuilder builder) - { - builder.ConfigureServices(services => - { - services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType)); - services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType)); - services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString)); - }); - } -} -``` - -This factory: - -1. Removes the existing `DbContextOptions<ApplicationDbContext>` registration -2. Removes the existing `DbConnection` registration -3. Adds a new `ApplicationDbContext` configured with the SQL Server connection - string from the Testcontainers-managed container - -> [!NOTE] -> The Microsoft SQL Server Docker image isn't compatible with ARM devices, such -> as Macs with Apple Silicon. You can use the -> [SqlEdge](https://www.nuget.org/packages/Testcontainers.SqlEdge) module or -> [Testcontainers Cloud](https://www.testcontainers.cloud/) as alternatives. diff --git a/content/guides/testcontainers-dotnet-getting-started.md b/content/guides/testcontainers-dotnet-getting-started.md new file mode 100644 index 000000000000..a6fde6a88d97 --- /dev/null +++ b/content/guides/testcontainers-dotnet-getting-started.md @@ -0,0 +1,263 @@ +--- +title: Getting started with Testcontainers for .NET +linkTitle: Testcontainers for .NET +description: Learn how to use Testcontainers for .NET to test database interactions with a real PostgreSQL instance. +keywords: testcontainers, dotnet, csharp, testing, postgresql, integration testing, xunit +summary: | + Learn how to create a .NET application and test database interactions + using Testcontainers for .NET with a real PostgreSQL instance. +aliases: + - /guides/testcontainers-dotnet-getting-started/create-project/ + - /guides/testcontainers-dotnet-getting-started/run-tests/ + - /guides/testcontainers-dotnet-getting-started/write-tests/ +params: + tags: [testing] + time: 20 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-dotnet --> + +In this guide, you will learn how to: + +- Create a .NET solution with a source and test project +- Implement a `CustomerService` that manages customer records in PostgreSQL +- Write integration tests using Testcontainers and xUnit +- Manage container lifecycle with `IAsyncLifetime` + +## Prerequisites + +- .NET 8.0+ SDK +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the .NET project + +### Set up the solution + +Create a .NET solution with source and test projects: + +```console +$ dotnet new sln -o TestcontainersDemo +$ cd TestcontainersDemo +$ dotnet new classlib -o CustomerService +$ dotnet sln add ./CustomerService/CustomerService.csproj +$ dotnet new xunit -o CustomerService.Tests +$ dotnet sln add ./CustomerService.Tests/CustomerService.Tests.csproj +$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj reference ./CustomerService/CustomerService.csproj +``` + +Add the Npgsql dependency to the source project: + +```console +$ dotnet add ./CustomerService/CustomerService.csproj package Npgsql +``` + +### Implement the business logic + +Create a `Customer` record type: + +```csharp +namespace Customers; + +public readonly record struct Customer(long Id, string Name); +``` + +Create a `DbConnectionProvider` class to manage database connections: + +```csharp +using System.Data.Common; +using Npgsql; + +namespace Customers; + +public sealed class DbConnectionProvider +{ + private readonly string _connectionString; + + public DbConnectionProvider(string connectionString) + { + _connectionString = connectionString; + } + + public DbConnection GetConnection() + { + return new NpgsqlConnection(_connectionString); + } +} +``` + +Create the `CustomerService` class: + +```csharp +namespace Customers; + +public sealed class CustomerService +{ + private readonly DbConnectionProvider _dbConnectionProvider; + + public CustomerService(DbConnectionProvider dbConnectionProvider) + { + _dbConnectionProvider = dbConnectionProvider; + CreateCustomersTable(); + } + + public IEnumerable<Customer> GetCustomers() + { + IList<Customer> customers = new List<Customer>(); + + using var connection = _dbConnectionProvider.GetConnection(); + using var command = connection.CreateCommand(); + command.CommandText = "SELECT id, name FROM customers"; + command.Connection?.Open(); + + using var dataReader = command.ExecuteReader(); + while (dataReader.Read()) + { + var id = dataReader.GetInt64(0); + var name = dataReader.GetString(1); + customers.Add(new Customer(id, name)); + } + + return customers; + } + + public void Create(Customer customer) + { + using var connection = _dbConnectionProvider.GetConnection(); + using var command = connection.CreateCommand(); + + var id = command.CreateParameter(); + id.ParameterName = "@id"; + id.Value = customer.Id; + + var name = command.CreateParameter(); + name.ParameterName = "@name"; + name.Value = customer.Name; + + command.CommandText = "INSERT INTO customers (id, name) VALUES(@id, @name)"; + command.Parameters.Add(id); + command.Parameters.Add(name); + command.Connection?.Open(); + command.ExecuteNonQuery(); + } + + private void CreateCustomersTable() + { + using var connection = _dbConnectionProvider.GetConnection(); + using var command = connection.CreateCommand(); + command.CommandText = "CREATE TABLE IF NOT EXISTS customers (id BIGINT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))"; + command.Connection?.Open(); + command.ExecuteNonQuery(); + } +} +``` + +Here's what `CustomerService` does: + +- The constructor calls `CreateCustomersTable()` to ensure the table exists. +- `GetCustomers()` fetches all rows from the `customers` table and returns them as `Customer` objects. +- `Create()` inserts a customer record into the database. + +## Write tests with Testcontainers + +### Add Testcontainers dependencies + +Add the Testcontainers PostgreSQL module to the test project: + +```console +$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj package Testcontainers.PostgreSql +``` + +### Write the test + +Create `CustomerServiceTest.cs` in the test project: + +```csharp +using Testcontainers.PostgreSql; + +namespace Customers.Tests; + +public sealed class CustomerServiceTest : IAsyncLifetime +{ + private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder() + .WithImage("postgres:16-alpine") + .Build(); + + public Task InitializeAsync() + { + return _postgres.StartAsync(); + } + + public Task DisposeAsync() + { + return _postgres.DisposeAsync().AsTask(); + } + + [Fact] + public void ShouldReturnTwoCustomers() + { + // Given + var customerService = new CustomerService(new DbConnectionProvider(_postgres.GetConnectionString())); + + // When + customerService.Create(new Customer(1, "George")); + customerService.Create(new Customer(2, "John")); + var customers = customerService.GetCustomers(); + + // Then + Assert.Equal(2, customers.Count()); + } +} +``` + +Here's what the test does: + +- Declares a `PostgreSqlContainer` using the `PostgreSqlBuilder` with the + `postgres:16-alpine` Docker image. +- Implements `IAsyncLifetime` for container lifecycle management: + - `InitializeAsync()` starts the container before the test runs. + - `DisposeAsync()` stops and removes the container after the test finishes. +- `ShouldReturnTwoCustomers()` creates a `CustomerService` with connection + details from the container, inserts two customers, fetches all customers, and + asserts the count. + +## Run tests and next steps + +### Run the tests + +Run the tests: + +```console +$ dotnet test +``` + +You can see in the output that Testcontainers pulls the Postgres Docker image +from Docker Hub (if not already available locally), starts the container, and +runs the test. + +Writing an integration test using Testcontainers works like writing a unit test +that you can run from your IDE. Your teammates can clone the project and run +tests without installing Postgres on their machines. + +### Summary + +The Testcontainers for .NET library helps you write integration tests using the +same type of database (Postgres) that you use in production, instead of mocks. +Because you aren't using mocks and instead talk to real services, you're free +to refactor code and still verify that the application works as expected. + +In addition to Postgres, Testcontainers provides dedicated +[modules](https://www.nuget.org/profiles/Testcontainers) for many SQL +databases, NoSQL databases, messaging queues, and more. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testing an ASP.NET Core web app](https://testcontainers.com/guides/testing-an-aspnet-core-web-app/) diff --git a/content/guides/testcontainers-dotnet-getting-started/_index.md b/content/guides/testcontainers-dotnet-getting-started/_index.md deleted file mode 100644 index 6f784c941008..000000000000 --- a/content/guides/testcontainers-dotnet-getting-started/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Getting started with Testcontainers for .NET -linkTitle: Testcontainers for .NET -description: Learn how to use Testcontainers for .NET to test database interactions with a real PostgreSQL instance. -keywords: testcontainers, dotnet, csharp, testing, postgresql, integration testing, xunit -summary: | - Learn how to create a .NET application and test database interactions - using Testcontainers for .NET with a real PostgreSQL instance. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [c-sharp] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-dotnet --> - -In this guide, you will learn how to: - -- Create a .NET solution with a source and test project -- Implement a `CustomerService` that manages customer records in PostgreSQL -- Write integration tests using Testcontainers and xUnit -- Manage container lifecycle with `IAsyncLifetime` - -## Prerequisites - -- .NET 8.0+ SDK -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-dotnet-getting-started/create-project.md b/content/guides/testcontainers-dotnet-getting-started/create-project.md deleted file mode 100644 index 18567d7d5b5a..000000000000 --- a/content/guides/testcontainers-dotnet-getting-started/create-project.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Create the .NET project -linkTitle: Create the project -description: Set up a .NET solution with a PostgreSQL-backed customer service. -keywords: testcontainers, dotnet, postgresql, getting started, project setup -weight: 10 ---- - -## Set up the solution - -Create a .NET solution with source and test projects: - -```console -$ dotnet new sln -o TestcontainersDemo -$ cd TestcontainersDemo -$ dotnet new classlib -o CustomerService -$ dotnet sln add ./CustomerService/CustomerService.csproj -$ dotnet new xunit -o CustomerService.Tests -$ dotnet sln add ./CustomerService.Tests/CustomerService.Tests.csproj -$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj reference ./CustomerService/CustomerService.csproj -``` - -Add the Npgsql dependency to the source project: - -```console -$ dotnet add ./CustomerService/CustomerService.csproj package Npgsql -``` - -## Implement the business logic - -Create a `Customer` record type: - -```csharp -namespace Customers; - -public readonly record struct Customer(long Id, string Name); -``` - -Create a `DbConnectionProvider` class to manage database connections: - -```csharp -using System.Data.Common; -using Npgsql; - -namespace Customers; - -public sealed class DbConnectionProvider -{ - private readonly string _connectionString; - - public DbConnectionProvider(string connectionString) - { - _connectionString = connectionString; - } - - public DbConnection GetConnection() - { - return new NpgsqlConnection(_connectionString); - } -} -``` - -Create the `CustomerService` class: - -```csharp -namespace Customers; - -public sealed class CustomerService -{ - private readonly DbConnectionProvider _dbConnectionProvider; - - public CustomerService(DbConnectionProvider dbConnectionProvider) - { - _dbConnectionProvider = dbConnectionProvider; - CreateCustomersTable(); - } - - public IEnumerable<Customer> GetCustomers() - { - IList<Customer> customers = new List<Customer>(); - - using var connection = _dbConnectionProvider.GetConnection(); - using var command = connection.CreateCommand(); - command.CommandText = "SELECT id, name FROM customers"; - command.Connection?.Open(); - - using var dataReader = command.ExecuteReader(); - while (dataReader.Read()) - { - var id = dataReader.GetInt64(0); - var name = dataReader.GetString(1); - customers.Add(new Customer(id, name)); - } - - return customers; - } - - public void Create(Customer customer) - { - using var connection = _dbConnectionProvider.GetConnection(); - using var command = connection.CreateCommand(); - - var id = command.CreateParameter(); - id.ParameterName = "@id"; - id.Value = customer.Id; - - var name = command.CreateParameter(); - name.ParameterName = "@name"; - name.Value = customer.Name; - - command.CommandText = "INSERT INTO customers (id, name) VALUES(@id, @name)"; - command.Parameters.Add(id); - command.Parameters.Add(name); - command.Connection?.Open(); - command.ExecuteNonQuery(); - } - - private void CreateCustomersTable() - { - using var connection = _dbConnectionProvider.GetConnection(); - using var command = connection.CreateCommand(); - command.CommandText = "CREATE TABLE IF NOT EXISTS customers (id BIGINT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))"; - command.Connection?.Open(); - command.ExecuteNonQuery(); - } -} -``` - -Here's what `CustomerService` does: - -- The constructor calls `CreateCustomersTable()` to ensure the table exists. -- `GetCustomers()` fetches all rows from the `customers` table and returns them as `Customer` objects. -- `Create()` inserts a customer record into the database. diff --git a/content/guides/testcontainers-dotnet-getting-started/run-tests.md b/content/guides/testcontainers-dotnet-getting-started/run-tests.md deleted file mode 100644 index bcaa66452784..000000000000 --- a/content/guides/testcontainers-dotnet-getting-started/run-tests.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, dotnet, postgresql, integration testing, run tests -weight: 30 ---- - -## Run the tests - -Run the tests: - -```console -$ dotnet test -``` - -You can see in the output that Testcontainers pulls the Postgres Docker image -from Docker Hub (if not already available locally), starts the container, and -runs the test. - -Writing an integration test using Testcontainers works like writing a unit test -that you can run from your IDE. Your teammates can clone the project and run -tests without installing Postgres on their machines. - -## Summary - -The Testcontainers for .NET library helps you write integration tests using the -same type of database (Postgres) that you use in production, instead of mocks. -Because you aren't using mocks and instead talk to real services, you're free -to refactor code and still verify that the application works as expected. - -In addition to Postgres, Testcontainers provides dedicated -[modules](https://www.nuget.org/profiles/Testcontainers) for many SQL -databases, NoSQL databases, messaging queues, and more. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testing an ASP.NET Core web app](https://testcontainers.com/guides/testing-an-aspnet-core-web-app/) diff --git a/content/guides/testcontainers-dotnet-getting-started/write-tests.md b/content/guides/testcontainers-dotnet-getting-started/write-tests.md deleted file mode 100644 index ca3528496693..000000000000 --- a/content/guides/testcontainers-dotnet-getting-started/write-tests.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Write integration tests using Testcontainers for .NET and xUnit with a real PostgreSQL database. -keywords: testcontainers, dotnet, postgresql, xunit, integration testing -weight: 20 ---- - -## Add Testcontainers dependencies - -Add the Testcontainers PostgreSQL module to the test project: - -```console -$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj package Testcontainers.PostgreSql -``` - -## Write the test - -Create `CustomerServiceTest.cs` in the test project: - -```csharp -using Testcontainers.PostgreSql; - -namespace Customers.Tests; - -public sealed class CustomerServiceTest : IAsyncLifetime -{ - private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder() - .WithImage("postgres:16-alpine") - .Build(); - - public Task InitializeAsync() - { - return _postgres.StartAsync(); - } - - public Task DisposeAsync() - { - return _postgres.DisposeAsync().AsTask(); - } - - [Fact] - public void ShouldReturnTwoCustomers() - { - // Given - var customerService = new CustomerService(new DbConnectionProvider(_postgres.GetConnectionString())); - - // When - customerService.Create(new Customer(1, "George")); - customerService.Create(new Customer(2, "John")); - var customers = customerService.GetCustomers(); - - // Then - Assert.Equal(2, customers.Count()); - } -} -``` - -Here's what the test does: - -- Declares a `PostgreSqlContainer` using the `PostgreSqlBuilder` with the - `postgres:16-alpine` Docker image. -- Implements `IAsyncLifetime` for container lifecycle management: - - `InitializeAsync()` starts the container before the test runs. - - `DisposeAsync()` stops and removes the container after the test finishes. -- `ShouldReturnTwoCustomers()` creates a `CustomerService` with connection - details from the container, inserts two customers, fetches all customers, and - asserts the count. diff --git a/content/guides/testcontainers-go-getting-started.md b/content/guides/testcontainers-go-getting-started.md new file mode 100644 index 000000000000..650d9fb1aef9 --- /dev/null +++ b/content/guides/testcontainers-go-getting-started.md @@ -0,0 +1,413 @@ +--- +title: Getting started with Testcontainers for Go +linkTitle: Testcontainers for Go +description: Learn how to use Testcontainers for Go to test database interactions with a real PostgreSQL instance. +keywords: testcontainers, go, golang, testing, postgresql, integration testing +summary: | + Learn how to create a Go application and test database interactions + using Testcontainers for Go with a real PostgreSQL instance. +aliases: + - /guides/testcontainers-go-getting-started/create-project/ + - /guides/testcontainers-go-getting-started/run-tests/ + - /guides/testcontainers-go-getting-started/test-suites/ + - /guides/testcontainers-go-getting-started/write-tests/ +params: + tags: [testing] + time: 20 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-go --> + +In this guide, you will learn how to: + +- Create a Go application with modules support +- Implement a Repository to manage customer data in a PostgreSQL database using the pgx driver +- Write integration tests using testcontainers-go +- Reuse containers across multiple tests using test suites + +## Prerequisites + +- Go 1.25+ +- Your preferred IDE (VS Code, GoLand) +- A Docker environment supported by Testcontainers. For details, see + the [testcontainers-go system requirements](https://golang.testcontainers.org/system_requirements/). + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the Go project + +### Initialize the project + +Start by creating a Go project. + +```console +$ mkdir testcontainers-go-demo +$ cd testcontainers-go-demo +$ go mod init github.com/testcontainers/testcontainers-go-demo +``` + +This guide uses the [jackc/pgx](https://github.com/jackc/pgx) PostgreSQL +driver to interact with the Postgres database and the testcontainers-go +[Postgres module](https://golang.testcontainers.org/modules/postgres/) to +spin up a Postgres Docker instance for testing. It also uses +[testify](https://github.com/stretchr/testify) for running multiple tests +as a suite and for writing assertions. + +Install these dependencies: + +```console +$ go get github.com/jackc/pgx/v5 +$ go get github.com/testcontainers/testcontainers-go +$ go get github.com/testcontainers/testcontainers-go/modules/postgres +$ go get github.com/stretchr/testify +``` + +### Create Customer struct + +Create a `types.go` file in the `customer` package and define the `Customer` +struct to model the customer details: + +```go +package customer + +type Customer struct { + Id int + Name string + Email string +} +``` + +### Create Repository + +Next, create `customer/repo.go`, define the `Repository` struct, and add +methods to create a customer and get a customer by email: + +```go +package customer + +import ( + "context" + "fmt" + "os" + + "github.com/jackc/pgx/v5" +) + +type Repository struct { + conn *pgx.Conn +} + +func NewRepository(ctx context.Context, connStr string) (*Repository, error) { + conn, err := pgx.Connect(ctx, connStr) + if err != nil { + _, _ = fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err) + return nil, err + } + return &Repository{ + conn: conn, + }, nil +} + +func (r Repository) CreateCustomer(ctx context.Context, customer Customer) (Customer, error) { + err := r.conn.QueryRow(ctx, + "INSERT INTO customers (name, email) VALUES ($1, $2) RETURNING id", + customer.Name, customer.Email).Scan(&customer.Id) + return customer, err +} + +func (r Repository) GetCustomerByEmail(ctx context.Context, email string) (Customer, error) { + var customer Customer + query := "SELECT id, name, email FROM customers WHERE email = $1" + err := r.conn.QueryRow(ctx, query, email). + Scan(&customer.Id, &customer.Name, &customer.Email) + if err != nil { + return Customer{}, err + } + return customer, nil +} +``` + +Here's what the code does: + +- `Repository` holds a `*pgx.Conn` for performing database operations. +- `NewRepository(connStr)` takes a database connection string and initializes a `Repository`. +- `CreateCustomer()` and `GetCustomerByEmail()` are methods on the `Repository` receiver that insert and query customer records. + +## Write tests with Testcontainers + +You have the `Repository` implementation ready, but for testing you need a +PostgreSQL database. You can use testcontainers-go to spin up a Postgres +database in a Docker container and run your tests against that database. + +### Set up the test database + +In real applications you might use a database migration tool, but for this +guide, use a script to initialize the database. + +Create a `testdata/init-db.sql` file to create the `CUSTOMERS` table and +insert sample data: + +```sql +CREATE TABLE IF NOT EXISTS customers (id serial, name varchar(255), email varchar(255)); + +INSERT INTO customers(name, email) VALUES ('John', 'john@gmail.com'); +``` + +### Understand the testcontainers-go API + +The testcontainers-go library provides the generic `Container` abstraction +that can run any containerized service. To further simplify, testcontainers-go +provides technology-specific modules that reduce boilerplate and provide a +functional options pattern to construct the container instance. + +For example, `PostgresContainer` provides `WithDatabase()`, +`WithUsername()`, `WithPassword()`, and other functions to set various +properties of Postgres containers. + +### Write the test + +Create the `customer/repo_test.go` file and implement the test: + +```go +package customer + +import ( + "context" + "path/filepath" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/testcontainers/testcontainers-go" + "github.com/testcontainers/testcontainers-go/modules/postgres" +) + +func TestCustomerRepository(t *testing.T) { + ctx := context.Background() + + ctr, err := postgres.Run(ctx, + "postgres:16-alpine", + postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")), + postgres.WithDatabase("test-db"), + postgres.WithUsername("postgres"), + postgres.WithPassword("postgres"), + postgres.BasicWaitStrategies(), + ) + testcontainers.CleanupContainer(t, ctr) + require.NoError(t, err) + + connStr, err := ctr.ConnectionString(ctx, "sslmode=disable") + require.NoError(t, err) + + customerRepo, err := NewRepository(ctx, connStr) + require.NoError(t, err) + + c, err := customerRepo.CreateCustomer(ctx, Customer{ + Name: "Henry", + Email: "henry@gmail.com", + }) + assert.NoError(t, err) + assert.NotNil(t, c) + + customer, err := customerRepo.GetCustomerByEmail(ctx, "henry@gmail.com") + assert.NoError(t, err) + assert.NotNil(t, customer) + assert.Equal(t, "Henry", customer.Name) + assert.Equal(t, "henry@gmail.com", customer.Email) +} +``` + +Here's what the test does: + +- Calls `postgres.Run()` with the `postgres:16-alpine` Docker image as the + first argument. This is the v0.41.0 API — the image is a required positional + parameter instead of an option. +- Configures initialization scripts using `WithInitScripts(...)` so that the + `CUSTOMERS` table is created and sample data is inserted after the database + starts. +- Uses `postgres.BasicWaitStrategies()` which combines waiting for the Postgres + log message and for the port to be ready. This replaces manual wait strategy + configuration. +- Calls `testcontainers.CleanupContainer(t, ctr)` right after `postgres.Run()`. + This registers automatic cleanup with the test framework, replacing the manual + `t.Cleanup` and `Terminate` pattern. +- Obtains the database `ConnectionString` from the container and initializes a + `Repository`. +- Creates a customer with the email `henry@gmail.com` and verifies that the + customer exists in the database. + +## Reuse containers with test suites + +In the previous section, you saw how to spin up a Postgres Docker container +for a single test. But often you have multiple tests in a single file, and you +may want to reuse the same Postgres Docker container for all of them. + +You can use the [testify suite](https://pkg.go.dev/github.com/stretchr/testify/suite) +package to implement common test setup and teardown actions. + +### Extract container setup + +First, extract the `PostgresContainer` creation logic into a separate file +called `testhelpers/containers.go`: + +```go +package testhelpers + +import ( + "context" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" + "github.com/testcontainers/testcontainers-go" + "github.com/testcontainers/testcontainers-go/modules/postgres" +) + +type PostgresContainer struct { + *postgres.PostgresContainer + ConnectionString string +} + +func CreatePostgresContainer(t *testing.T, ctx context.Context) *PostgresContainer { + t.Helper() + + ctr, err := postgres.Run(ctx, + "postgres:16-alpine", + postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")), + postgres.WithDatabase("test-db"), + postgres.WithUsername("postgres"), + postgres.WithPassword("postgres"), + postgres.BasicWaitStrategies(), + ) + testcontainers.CleanupContainer(t, ctr) + require.NoError(t, err) + + connStr, err := ctr.ConnectionString(ctx, "sslmode=disable") + require.NoError(t, err) + + return &PostgresContainer{ + PostgresContainer: ctr, + ConnectionString: connStr, + } +} +``` + +In `containers.go`, `PostgresContainer` extends the testcontainers-go +`PostgresContainer` to provide easy access to `ConnectionString`. The +`CreatePostgresContainer()` function accepts `*testing.T` as its first +parameter, calls `t.Helper()` so that test failures point to the caller, +and uses `testcontainers.CleanupContainer()` to register automatic cleanup. + +### Write the test suite + +Create `customer/repo_suite_test.go` and implement tests for creating +a customer and getting a customer by email using the testify suite package: + +```go +package customer + +import ( + "context" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/stretchr/testify/suite" + "github.com/testcontainers/testcontainers-go-demo/testhelpers" +) + +type CustomerRepoTestSuite struct { + suite.Suite + pgContainer *testhelpers.PostgresContainer + repository *Repository + ctx context.Context +} + +func (suite *CustomerRepoTestSuite) SetupSuite() { + suite.ctx = context.Background() + suite.pgContainer = testhelpers.CreatePostgresContainer(suite.T(), suite.ctx) + + repository, err := NewRepository(suite.ctx, suite.pgContainer.ConnectionString) + require.NoError(suite.T(), err) + suite.repository = repository +} + +func (suite *CustomerRepoTestSuite) TestCreateCustomer() { + t := suite.T() + + customer, err := suite.repository.CreateCustomer(suite.ctx, Customer{ + Name: "Henry", + Email: "henry@gmail.com", + }) + require.NoError(t, err) + assert.NotNil(t, customer.Id) +} + +func (suite *CustomerRepoTestSuite) TestGetCustomerByEmail() { + t := suite.T() + + customer, err := suite.repository.GetCustomerByEmail(suite.ctx, "john@gmail.com") + require.NoError(t, err) + assert.Equal(t, "John", customer.Name) + assert.Equal(t, "john@gmail.com", customer.Email) +} + +func TestCustomerRepoTestSuite(t *testing.T) { + suite.Run(t, new(CustomerRepoTestSuite)) +} +``` + +Here's what the code does: + +- `CustomerRepoTestSuite` extends `suite.Suite` and includes fields shared + across multiple tests. +- `SetupSuite()` runs once before all tests. It calls + `CreatePostgresContainer(suite.T(), ...)` which handles cleanup registration + automatically via `CleanupContainer`, so no `TearDownSuite()` is needed. +- `TestCreateCustomer()` uses `require.NoError()` for the create operation + (fail immediately if it errors) and `assert.NotNil()` for the ID check. +- `TestGetCustomerByEmail()` uses `require.NoError()` then asserts on the + returned values. +- `TestCustomerRepoTestSuite(t *testing.T)` runs the test suite when you + execute `go test`. + +> [!TIP] +> For the purpose of this guide, the tests don't reset data in the database. +> In practice, it's a good idea to reset the database to a known state before +> running each test. + +## Run tests and next steps + +### Run the tests + +Run all the tests using `go test ./...`. Optionally add the `-v` flag for +verbose output: + +```console +$ go test -v ./... +``` + +You should see two Postgres Docker containers start automatically: one for the +suite and its two tests, and another for the initial standalone test. All tests +should pass. After the tests finish, the containers are stopped and removed +automatically. + +### Summary + +The Testcontainers for Go library helps you write integration tests by using +the same type of database (Postgres) that you use in production, instead of +mocks. Because you aren't using mocks and instead talk to real services, you're +free to refactor code and still verify that the application works as expected. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testcontainers for Go documentation](https://golang.testcontainers.org/) +- [Testcontainers for Go quickstart](https://golang.testcontainers.org/quickstart/) +- [Testcontainers Postgres module for Go](https://golang.testcontainers.org/modules/postgres/) diff --git a/content/guides/testcontainers-go-getting-started/_index.md b/content/guides/testcontainers-go-getting-started/_index.md deleted file mode 100644 index 5ec598979d08..000000000000 --- a/content/guides/testcontainers-go-getting-started/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Getting started with Testcontainers for Go -linkTitle: Testcontainers for Go -description: Learn how to use Testcontainers for Go to test database interactions with a real PostgreSQL instance. -keywords: testcontainers, go, golang, testing, postgresql, integration testing -summary: | - Learn how to create a Go application and test database interactions - using Testcontainers for Go with a real PostgreSQL instance. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [go] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-go --> - -In this guide, you will learn how to: - -- Create a Go application with modules support -- Implement a Repository to manage customer data in a PostgreSQL database using the pgx driver -- Write integration tests using testcontainers-go -- Reuse containers across multiple tests using test suites - -## Prerequisites - -- Go 1.25+ -- Your preferred IDE (VS Code, GoLand) -- A Docker environment supported by Testcontainers. For details, see - the [testcontainers-go system requirements](https://golang.testcontainers.org/system_requirements/). - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-go-getting-started/create-project.md b/content/guides/testcontainers-go-getting-started/create-project.md deleted file mode 100644 index ce18f4a016f4..000000000000 --- a/content/guides/testcontainers-go-getting-started/create-project.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Create the Go project -linkTitle: Create the project -description: Set up a Go project with a PostgreSQL-backed repository. -keywords: testcontainers, go, golang, postgresql, getting started, project setup -weight: 10 ---- - -## Initialize the project - -Start by creating a Go project. - -```console -$ mkdir testcontainers-go-demo -$ cd testcontainers-go-demo -$ go mod init github.com/testcontainers/testcontainers-go-demo -``` - -This guide uses the [jackc/pgx](https://github.com/jackc/pgx) PostgreSQL -driver to interact with the Postgres database and the testcontainers-go -[Postgres module](https://golang.testcontainers.org/modules/postgres/) to -spin up a Postgres Docker instance for testing. It also uses -[testify](https://github.com/stretchr/testify) for running multiple tests -as a suite and for writing assertions. - -Install these dependencies: - -```console -$ go get github.com/jackc/pgx/v5 -$ go get github.com/testcontainers/testcontainers-go -$ go get github.com/testcontainers/testcontainers-go/modules/postgres -$ go get github.com/stretchr/testify -``` - -## Create Customer struct - -Create a `types.go` file in the `customer` package and define the `Customer` -struct to model the customer details: - -```go -package customer - -type Customer struct { - Id int - Name string - Email string -} -``` - -## Create Repository - -Next, create `customer/repo.go`, define the `Repository` struct, and add -methods to create a customer and get a customer by email: - -```go -package customer - -import ( - "context" - "fmt" - "os" - - "github.com/jackc/pgx/v5" -) - -type Repository struct { - conn *pgx.Conn -} - -func NewRepository(ctx context.Context, connStr string) (*Repository, error) { - conn, err := pgx.Connect(ctx, connStr) - if err != nil { - _, _ = fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err) - return nil, err - } - return &Repository{ - conn: conn, - }, nil -} - -func (r Repository) CreateCustomer(ctx context.Context, customer Customer) (Customer, error) { - err := r.conn.QueryRow(ctx, - "INSERT INTO customers (name, email) VALUES ($1, $2) RETURNING id", - customer.Name, customer.Email).Scan(&customer.Id) - return customer, err -} - -func (r Repository) GetCustomerByEmail(ctx context.Context, email string) (Customer, error) { - var customer Customer - query := "SELECT id, name, email FROM customers WHERE email = $1" - err := r.conn.QueryRow(ctx, query, email). - Scan(&customer.Id, &customer.Name, &customer.Email) - if err != nil { - return Customer{}, err - } - return customer, nil -} -``` - -Here's what the code does: - -- `Repository` holds a `*pgx.Conn` for performing database operations. -- `NewRepository(connStr)` takes a database connection string and initializes a `Repository`. -- `CreateCustomer()` and `GetCustomerByEmail()` are methods on the `Repository` receiver that insert and query customer records. diff --git a/content/guides/testcontainers-go-getting-started/run-tests.md b/content/guides/testcontainers-go-getting-started/run-tests.md deleted file mode 100644 index 194902dd04d0..000000000000 --- a/content/guides/testcontainers-go-getting-started/run-tests.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, go, golang, integration testing, run tests -weight: 40 ---- - -## Run the tests - -Run all the tests using `go test ./...`. Optionally add the `-v` flag for -verbose output: - -```console -$ go test -v ./... -``` - -You should see two Postgres Docker containers start automatically: one for the -suite and its two tests, and another for the initial standalone test. All tests -should pass. After the tests finish, the containers are stopped and removed -automatically. - -## Summary - -The Testcontainers for Go library helps you write integration tests by using -the same type of database (Postgres) that you use in production, instead of -mocks. Because you aren't using mocks and instead talk to real services, you're -free to refactor code and still verify that the application works as expected. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers for Go documentation](https://golang.testcontainers.org/) -- [Testcontainers for Go quickstart](https://golang.testcontainers.org/quickstart/) -- [Testcontainers Postgres module for Go](https://golang.testcontainers.org/modules/postgres/) diff --git a/content/guides/testcontainers-go-getting-started/test-suites.md b/content/guides/testcontainers-go-getting-started/test-suites.md deleted file mode 100644 index 51739335a8fd..000000000000 --- a/content/guides/testcontainers-go-getting-started/test-suites.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Reuse containers with test suites -linkTitle: Test suites -description: Share a single Postgres container across multiple tests using testify suites. -keywords: testcontainers, go, golang, testify, test suites, container reuse -weight: 30 ---- - -In the previous section, you saw how to spin up a Postgres Docker container -for a single test. But often you have multiple tests in a single file, and you -may want to reuse the same Postgres Docker container for all of them. - -You can use the [testify suite](https://pkg.go.dev/github.com/stretchr/testify/suite) -package to implement common test setup and teardown actions. - -## Extract container setup - -First, extract the `PostgresContainer` creation logic into a separate file -called `testhelpers/containers.go`: - -```go -package testhelpers - -import ( - "context" - "path/filepath" - "testing" - - "github.com/stretchr/testify/require" - "github.com/testcontainers/testcontainers-go" - "github.com/testcontainers/testcontainers-go/modules/postgres" -) - -type PostgresContainer struct { - *postgres.PostgresContainer - ConnectionString string -} - -func CreatePostgresContainer(t *testing.T, ctx context.Context) *PostgresContainer { - t.Helper() - - ctr, err := postgres.Run(ctx, - "postgres:16-alpine", - postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")), - postgres.WithDatabase("test-db"), - postgres.WithUsername("postgres"), - postgres.WithPassword("postgres"), - postgres.BasicWaitStrategies(), - ) - testcontainers.CleanupContainer(t, ctr) - require.NoError(t, err) - - connStr, err := ctr.ConnectionString(ctx, "sslmode=disable") - require.NoError(t, err) - - return &PostgresContainer{ - PostgresContainer: ctr, - ConnectionString: connStr, - } -} -``` - -In `containers.go`, `PostgresContainer` extends the testcontainers-go -`PostgresContainer` to provide easy access to `ConnectionString`. The -`CreatePostgresContainer()` function accepts `*testing.T` as its first -parameter, calls `t.Helper()` so that test failures point to the caller, -and uses `testcontainers.CleanupContainer()` to register automatic cleanup. - -## Write the test suite - -Create `customer/repo_suite_test.go` and implement tests for creating -a customer and getting a customer by email using the testify suite package: - -```go -package customer - -import ( - "context" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "github.com/stretchr/testify/suite" - "github.com/testcontainers/testcontainers-go-demo/testhelpers" -) - -type CustomerRepoTestSuite struct { - suite.Suite - pgContainer *testhelpers.PostgresContainer - repository *Repository - ctx context.Context -} - -func (suite *CustomerRepoTestSuite) SetupSuite() { - suite.ctx = context.Background() - suite.pgContainer = testhelpers.CreatePostgresContainer(suite.T(), suite.ctx) - - repository, err := NewRepository(suite.ctx, suite.pgContainer.ConnectionString) - require.NoError(suite.T(), err) - suite.repository = repository -} - -func (suite *CustomerRepoTestSuite) TestCreateCustomer() { - t := suite.T() - - customer, err := suite.repository.CreateCustomer(suite.ctx, Customer{ - Name: "Henry", - Email: "henry@gmail.com", - }) - require.NoError(t, err) - assert.NotNil(t, customer.Id) -} - -func (suite *CustomerRepoTestSuite) TestGetCustomerByEmail() { - t := suite.T() - - customer, err := suite.repository.GetCustomerByEmail(suite.ctx, "john@gmail.com") - require.NoError(t, err) - assert.Equal(t, "John", customer.Name) - assert.Equal(t, "john@gmail.com", customer.Email) -} - -func TestCustomerRepoTestSuite(t *testing.T) { - suite.Run(t, new(CustomerRepoTestSuite)) -} -``` - -Here's what the code does: - -- `CustomerRepoTestSuite` extends `suite.Suite` and includes fields shared - across multiple tests. -- `SetupSuite()` runs once before all tests. It calls - `CreatePostgresContainer(suite.T(), ...)` which handles cleanup registration - automatically via `CleanupContainer`, so no `TearDownSuite()` is needed. -- `TestCreateCustomer()` uses `require.NoError()` for the create operation - (fail immediately if it errors) and `assert.NotNil()` for the ID check. -- `TestGetCustomerByEmail()` uses `require.NoError()` then asserts on the - returned values. -- `TestCustomerRepoTestSuite(t *testing.T)` runs the test suite when you - execute `go test`. - -> [!TIP] -> For the purpose of this guide, the tests don't reset data in the database. -> In practice, it's a good idea to reset the database to a known state before -> running each test. diff --git a/content/guides/testcontainers-go-getting-started/write-tests.md b/content/guides/testcontainers-go-getting-started/write-tests.md deleted file mode 100644 index 0fbc936bf175..000000000000 --- a/content/guides/testcontainers-go-getting-started/write-tests.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Write your first integration test using testcontainers-go and PostgreSQL. -keywords: testcontainers, go, golang, postgresql, integration testing -weight: 20 ---- - -You have the `Repository` implementation ready, but for testing you need a -PostgreSQL database. You can use testcontainers-go to spin up a Postgres -database in a Docker container and run your tests against that database. - -## Set up the test database - -In real applications you might use a database migration tool, but for this -guide, use a script to initialize the database. - -Create a `testdata/init-db.sql` file to create the `CUSTOMERS` table and -insert sample data: - -```sql -CREATE TABLE IF NOT EXISTS customers (id serial, name varchar(255), email varchar(255)); - -INSERT INTO customers(name, email) VALUES ('John', 'john@gmail.com'); -``` - -## Understand the testcontainers-go API - -The testcontainers-go library provides the generic `Container` abstraction -that can run any containerized service. To further simplify, testcontainers-go -provides technology-specific modules that reduce boilerplate and provide a -functional options pattern to construct the container instance. - -For example, `PostgresContainer` provides `WithDatabase()`, -`WithUsername()`, `WithPassword()`, and other functions to set various -properties of Postgres containers. - -## Write the test - -Create the `customer/repo_test.go` file and implement the test: - -```go -package customer - -import ( - "context" - "path/filepath" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "github.com/testcontainers/testcontainers-go" - "github.com/testcontainers/testcontainers-go/modules/postgres" -) - -func TestCustomerRepository(t *testing.T) { - ctx := context.Background() - - ctr, err := postgres.Run(ctx, - "postgres:16-alpine", - postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")), - postgres.WithDatabase("test-db"), - postgres.WithUsername("postgres"), - postgres.WithPassword("postgres"), - postgres.BasicWaitStrategies(), - ) - testcontainers.CleanupContainer(t, ctr) - require.NoError(t, err) - - connStr, err := ctr.ConnectionString(ctx, "sslmode=disable") - require.NoError(t, err) - - customerRepo, err := NewRepository(ctx, connStr) - require.NoError(t, err) - - c, err := customerRepo.CreateCustomer(ctx, Customer{ - Name: "Henry", - Email: "henry@gmail.com", - }) - assert.NoError(t, err) - assert.NotNil(t, c) - - customer, err := customerRepo.GetCustomerByEmail(ctx, "henry@gmail.com") - assert.NoError(t, err) - assert.NotNil(t, customer) - assert.Equal(t, "Henry", customer.Name) - assert.Equal(t, "henry@gmail.com", customer.Email) -} -``` - -Here's what the test does: - -- Calls `postgres.Run()` with the `postgres:16-alpine` Docker image as the - first argument. This is the v0.41.0 API — the image is a required positional - parameter instead of an option. -- Configures initialization scripts using `WithInitScripts(...)` so that the - `CUSTOMERS` table is created and sample data is inserted after the database - starts. -- Uses `postgres.BasicWaitStrategies()` which combines waiting for the Postgres - log message and for the port to be ready. This replaces manual wait strategy - configuration. -- Calls `testcontainers.CleanupContainer(t, ctr)` right after `postgres.Run()`. - This registers automatic cleanup with the test framework, replacing the manual - `t.Cleanup` and `Terminate` pattern. -- Obtains the database `ConnectionString` from the container and initializes a - `Repository`. -- Creates a customer with the email `henry@gmail.com` and verifies that the - customer exists in the database. diff --git a/content/guides/testcontainers-java-aws-localstack/_index.md b/content/guides/testcontainers-java-aws-localstack/_index.md deleted file mode 100644 index 85978649e34a..000000000000 --- a/content/guides/testcontainers-java-aws-localstack/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Testing AWS service integrations using LocalStack -linkTitle: AWS LocalStack -description: Learn how to test Spring Cloud AWS applications using LocalStack and Testcontainers. -keywords: testcontainers, java, spring boot, testing, aws, localstack, s3, sqs, spring cloud aws -summary: | - Learn how to create a Spring Boot application with Spring Cloud AWS, - then test S3 and SQS integrations using Testcontainers and LocalStack. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-aws-service-integrations-using-localstack --> - -In this guide, you will learn how to: - -- Create a Spring Boot application with Spring Cloud AWS integration -- Use AWS S3 and SQS services -- Test the application using Testcontainers and LocalStack - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-aws-localstack/create-project.md b/content/guides/testcontainers-java-aws-localstack/create-project.md deleted file mode 100644 index 1bc2a577ceaf..000000000000 --- a/content/guides/testcontainers-java-aws-localstack/create-project.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with Spring Cloud AWS, S3, and SQS. -keywords: testcontainers, java, spring boot, aws, localstack, s3, sqs, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Testcontainers** starter. Spring Cloud AWS starters are not -available on Spring Initializr, so you need to add them manually. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-aws-service-integrations-using-localstack). - -Add the Spring Cloud AWS BOM to your dependency management and add the S3, SQS -starters as dependencies. Testcontainers provides a -[LocalStack module](https://testcontainers.com/modules/localstack/) for testing -AWS service integrations. You also need -[Awaitility](http://www.awaitility.org/) for testing asynchronous SQS -processing. - -The key dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> - <awspring.version>3.0.3</awspring.version> -</properties> - -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-web</artifactId> - </dependency> - <dependency> - <groupId>io.awspring.cloud</groupId> - <artifactId>spring-cloud-aws-starter-s3</artifactId> - </dependency> - <dependency> - <groupId>io.awspring.cloud</groupId> - <artifactId>spring-cloud-aws-starter-sqs</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-testcontainers</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-localstack</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.awaitility</groupId> - <artifactId>awaitility</artifactId> - <scope>test</scope> - </dependency> -</dependencies> - -<dependencyManagement> - <dependencies> - <dependency> - <groupId>io.awspring.cloud</groupId> - <artifactId>spring-cloud-aws-dependencies</artifactId> - <version>${awspring.version}</version> - <type>pom</type> - <scope>import</scope> - </dependency> - </dependencies> -</dependencyManagement> -``` - -## Create the configuration properties - -To make the SQS queue and S3 bucket names configurable, create an -`ApplicationProperties` record: - -```java -package com.testcontainers.demo; - -import org.springframework.boot.context.properties.ConfigurationProperties; - -@ConfigurationProperties(prefix = "app") -public record ApplicationProperties(String queue, String bucket) {} -``` - -Then add `@ConfigurationPropertiesScan` to the main application class so that -Spring automatically scans for `@ConfigurationProperties`-annotated classes and -registers them as beans: - -```java -package com.testcontainers.demo; - -import org.springframework.boot.SpringApplication; -import org.springframework.boot.autoconfigure.SpringBootApplication; -import org.springframework.boot.context.properties.ConfigurationPropertiesScan; - -@SpringBootApplication -@ConfigurationPropertiesScan -public class Application { - - public static void main(String[] args) { - SpringApplication.run(Application.class, args); - } -} -``` - -## Implement StorageService for S3 - -Spring Cloud AWS provides higher-level abstractions like `S3Template` with -convenience methods for uploading and downloading files. Create a -`StorageService` class: - -```java -package com.testcontainers.demo; - -import io.awspring.cloud.s3.S3Template; -import java.io.IOException; -import java.io.InputStream; -import org.springframework.stereotype.Service; - -@Service -public class StorageService { - - private final S3Template s3Template; - - public StorageService(S3Template s3Template) { - this.s3Template = s3Template; - } - - public void upload(String bucketName, String key, InputStream stream) { - this.s3Template.upload(bucketName, key, stream); - } - - public InputStream download(String bucketName, String key) - throws IOException { - return this.s3Template.download(bucketName, key).getInputStream(); - } - - public String downloadAsString(String bucketName, String key) - throws IOException { - try (InputStream is = this.download(bucketName, key)) { - return new String(is.readAllBytes()); - } - } -} -``` - -## Create the SQS message model - -Create a `Message` record that represents the payload you send to the SQS -queue: - -```java -package com.testcontainers.demo; - -import java.util.UUID; - -public record Message(UUID uuid, String content) {} -``` - -## Implement the message sender - -Create `MessageSender`, which uses `SqsTemplate` to publish messages: - -```java -package com.testcontainers.demo; - -import io.awspring.cloud.sqs.operations.SqsTemplate; -import org.springframework.stereotype.Service; - -@Service -public class MessageSender { - - private final SqsTemplate sqsTemplate; - - public MessageSender(SqsTemplate sqsTemplate) { - this.sqsTemplate = sqsTemplate; - } - - public void publish(String queueName, Message message) { - sqsTemplate.send(to -> to.queue(queueName).payload(message)); - } -} -``` - -## Implement the message listener - -Create `MessageListener` with a handler method annotated with `@SqsListener`. -When a message arrives, the listener uploads the content to an S3 bucket using -the message UUID as the key: - -```java -package com.testcontainers.demo; - -import io.awspring.cloud.sqs.annotation.SqsListener; -import java.io.ByteArrayInputStream; -import java.nio.charset.StandardCharsets; -import org.springframework.stereotype.Service; - -@Service -public class MessageListener { - - private final StorageService storageService; - private final ApplicationProperties properties; - - public MessageListener( - StorageService storageService, - ApplicationProperties properties - ) { - this.storageService = storageService; - this.properties = properties; - } - - @SqsListener(queueNames = { "${app.queue}" }) - public void handle(Message message) { - String bucketName = this.properties.bucket(); - String key = message.uuid().toString(); - ByteArrayInputStream is = new ByteArrayInputStream( - message.content().getBytes(StandardCharsets.UTF_8) - ); - this.storageService.upload(bucketName, key, is); - } -} -``` - -The `${app.queue}` expression reads the queue name from application -configuration instead of hard-coding it. diff --git a/content/guides/testcontainers-java-aws-localstack/run-tests.md b/content/guides/testcontainers-java-aws-localstack/run-tests.md deleted file mode 100644 index e3521ed5f2e0..000000000000 --- a/content/guides/testcontainers-java-aws-localstack/run-tests.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Spring Cloud AWS integration tests and explore next steps. -keywords: testcontainers, java, spring boot, aws, localstack, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the LocalStack Docker container start and the test pass. After -the tests finish, the container stops and is removed automatically. - -## Summary - -LocalStack lets you develop and test AWS-based applications locally. -The Testcontainers LocalStack module makes it straightforward to write -integration tests by using ephemeral LocalStack containers that start on random -ports with no external setup required. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers LocalStack module](https://java.testcontainers.org/modules/localstack/) -- [Getting started with Testcontainers for Java](https://java.testcontainers.org/quickstart/junit_5_quickstart/) -- [Spring Cloud AWS documentation](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html) diff --git a/content/guides/testcontainers-java-aws-localstack/write-tests.md b/content/guides/testcontainers-java-aws-localstack/write-tests.md deleted file mode 100644 index caf7b49d1b7b..000000000000 --- a/content/guides/testcontainers-java-aws-localstack/write-tests.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test Spring Cloud AWS S3 and SQS integration using Testcontainers and LocalStack. -keywords: testcontainers, java, spring boot, aws, localstack, s3, sqs, integration testing -weight: 20 ---- - -To test the application, you need a running LocalStack instance that emulates -the AWS S3 and SQS services. Testcontainers spins up LocalStack in a Docker -container and `@DynamicPropertySource` connects it to Spring Cloud AWS. - -## Configure the test container - -You can start a LocalStack container and configure the Spring Cloud AWS -properties to talk to it instead of actual AWS services. The properties you -need to set are: - -```properties -spring.cloud.aws.s3.endpoint=http://localhost:4566 -spring.cloud.aws.sqs.endpoint=http://localhost:4566 -spring.cloud.aws.credentials.access-key=noop -spring.cloud.aws.credentials.secret-key=noop -spring.cloud.aws.region.static=us-east-1 -``` - -For testing, use an ephemeral container that starts on a random available port -so that you can run multiple builds in CI in parallel without port conflicts. - -## Write the test - -Create `MessageListenerTest.java`: - -```java -package com.testcontainers.demo; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.awaitility.Awaitility.await; -import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3; -import static org.testcontainers.containers.localstack.LocalStackContainer.Service.SQS; - -import java.io.IOException; -import java.time.Duration; -import java.util.UUID; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; -import org.testcontainers.containers.localstack.LocalStackContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.utility.DockerImageName; - -@SpringBootTest -@Testcontainers -class MessageListenerTest { - - @Container - static LocalStackContainer localStack = new LocalStackContainer( - DockerImageName.parse("localstack/localstack:3.0") - ); - - static final String BUCKET_NAME = UUID.randomUUID().toString(); - static final String QUEUE_NAME = UUID.randomUUID().toString(); - - @DynamicPropertySource - static void overrideProperties(DynamicPropertyRegistry registry) { - registry.add("app.bucket", () -> BUCKET_NAME); - registry.add("app.queue", () -> QUEUE_NAME); - registry.add( - "spring.cloud.aws.region.static", - () -> localStack.getRegion() - ); - registry.add( - "spring.cloud.aws.credentials.access-key", - () -> localStack.getAccessKey() - ); - registry.add( - "spring.cloud.aws.credentials.secret-key", - () -> localStack.getSecretKey() - ); - registry.add( - "spring.cloud.aws.s3.endpoint", - () -> localStack.getEndpointOverride(S3).toString() - ); - registry.add( - "spring.cloud.aws.sqs.endpoint", - () -> localStack.getEndpointOverride(SQS).toString() - ); - } - - @BeforeAll - static void beforeAll() throws IOException, InterruptedException { - localStack.execInContainer("awslocal", "s3", "mb", "s3://" + BUCKET_NAME); - localStack.execInContainer( - "awslocal", - "sqs", - "create-queue", - "--queue-name", - QUEUE_NAME - ); - } - - @Autowired - StorageService storageService; - - @Autowired - MessageSender publisher; - - @Autowired - ApplicationProperties properties; - - @Test - void shouldHandleMessageSuccessfully() { - Message message = new Message(UUID.randomUUID(), "Hello World"); - publisher.publish(properties.queue(), message); - - await() - .pollInterval(Duration.ofSeconds(2)) - .atMost(Duration.ofSeconds(10)) - .ignoreExceptions() - .untilAsserted(() -> { - String msg = storageService.downloadAsString( - properties.bucket(), - message.uuid().toString() - ); - assertThat(msg).isEqualTo("Hello World"); - }); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` starts the full Spring application context. -- The Testcontainers JUnit 5 annotations `@Testcontainers` and `@Container` - manage the lifecycle of a `LocalStackContainer` instance. -- `@DynamicPropertySource` obtains the dynamic S3 and SQS endpoint URLs, - region, access key, and secret key from the container, and registers them as - Spring Cloud AWS configuration properties. -- `@BeforeAll` creates the required SQS queue and S3 bucket using the - `awslocal` CLI tool that comes pre-installed in the LocalStack Docker image. - The `localStack.execInContainer()` API runs commands inside the container. -- `shouldHandleMessageSuccessfully()` publishes a `Message` to the SQS queue. - The listener receives the message and stores its content in the S3 bucket - with the UUID as the key. Awaitility waits up to 10 seconds for the expected - content to appear in the bucket. diff --git a/content/guides/testcontainers-java-getting-started.md b/content/guides/testcontainers-java-getting-started.md new file mode 100644 index 000000000000..0e8750894002 --- /dev/null +++ b/content/guides/testcontainers-java-getting-started.md @@ -0,0 +1,326 @@ +--- +title: Getting started with Testcontainers for Java +linkTitle: Testcontainers for Java +description: Learn how to use Testcontainers for Java to test a customer service with a real PostgreSQL database. +keywords: testcontainers, java, testing, postgresql, integration testing, junit, maven +summary: | + Learn how to create a Java application and test database interactions + using Testcontainers for Java with a real PostgreSQL instance. +aliases: + - /guides/testcontainers-java-getting-started/create-project/ + - /guides/testcontainers-java-getting-started/run-tests/ + - /guides/testcontainers-java-getting-started/write-tests/ +params: + tags: [testing] + time: 20 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-java --> + +In this guide, you will learn how to: + +- Create a Java project with Maven +- Implement a `CustomerService` that manages customer records in PostgreSQL +- Write integration tests using Testcontainers with a real Postgres database +- Run the tests and verify everything works + +## Prerequisites + +- Java 17+ +- Maven or Gradle +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the Java project + +### Set up the Maven project + +Create a Java project with Maven from your preferred IDE. This guide uses +Maven, but you can use Gradle if you prefer. Add the following dependencies +to `pom.xml`: + +```xml +<dependencies> + <dependency> + <groupId>org.postgresql</groupId> + <artifactId>postgresql</artifactId> + <version>42.7.3</version> + </dependency> + <dependency> + <groupId>ch.qos.logback</groupId> + <artifactId>logback-classic</artifactId> + <version>1.5.6</version> + </dependency> + <dependency> + <groupId>org.junit.jupiter</groupId> + <artifactId>junit-jupiter</artifactId> + <version>5.10.2</version> + <scope>test</scope> + </dependency> +</dependencies> + +<build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <version>3.2.5</version> + </plugin> + </plugins> +</build> +``` + +This adds the Postgres JDBC driver, logback for logging, JUnit 5 for testing, +and the latest `maven-surefire-plugin` for JUnit 5 support. + +### Implement the business logic + +Create a `Customer` record: + +```java +package com.testcontainers.demo; + +public record Customer(Long id, String name) {} +``` + +Create a `DBConnectionProvider` class to hold JDBC connection parameters and +provide a database `Connection`: + +```java +package com.testcontainers.demo; + +import java.sql.Connection; +import java.sql.DriverManager; + +class DBConnectionProvider { + + private final String url; + private final String username; + private final String password; + + public DBConnectionProvider(String url, String username, String password) { + this.url = url; + this.username = username; + this.password = password; + } + + Connection getConnection() { + try { + return DriverManager.getConnection(url, username, password); + } catch (Exception e) { + throw new RuntimeException(e); + } + } +} +``` + +Create the `CustomerService` class: + +```java +package com.testcontainers.demo; + +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.util.ArrayList; +import java.util.List; + +public class CustomerService { + + private final DBConnectionProvider connectionProvider; + + public CustomerService(DBConnectionProvider connectionProvider) { + this.connectionProvider = connectionProvider; + createCustomersTableIfNotExists(); + } + + public void createCustomer(Customer customer) { + try (Connection conn = this.connectionProvider.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + "insert into customers(id,name) values(?,?)" + ); + pstmt.setLong(1, customer.id()); + pstmt.setString(2, customer.name()); + pstmt.execute(); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + public List<Customer> getAllCustomers() { + List<Customer> customers = new ArrayList<>(); + + try (Connection conn = this.connectionProvider.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + "select id,name from customers" + ); + ResultSet rs = pstmt.executeQuery(); + while (rs.next()) { + long id = rs.getLong("id"); + String name = rs.getString("name"); + customers.add(new Customer(id, name)); + } + } catch (SQLException e) { + throw new RuntimeException(e); + } + return customers; + } + + private void createCustomersTableIfNotExists() { + try (Connection conn = this.connectionProvider.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + """ + create table if not exists customers ( + id bigint not null, + name varchar not null, + primary key (id) + ) + """ + ); + pstmt.execute(); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } +} +``` + +Here's what `CustomerService` does: + +- The constructor calls `createCustomersTableIfNotExists()` to ensure the table exists. +- `createCustomer()` inserts a customer record into the database. +- `getAllCustomers()` fetches all rows from the `customers` table and returns a list of `Customer` objects. + +## Write tests with Testcontainers + +You have the `CustomerService` implementation ready, but for testing you need a +PostgreSQL database. You can use Testcontainers to spin up a Postgres database +in a Docker container and run your tests against it. + +### Add Testcontainers dependencies + +Add the Testcontainers PostgreSQL module as a test dependency in `pom.xml`: + +```xml +<dependency> + <groupId>org.testcontainers</groupId> + <artifactId>testcontainers-postgresql</artifactId> + <version>2.0.4</version> + <scope>test</scope> +</dependency> +``` + +Since the application uses a Postgres database, the Testcontainers Postgres +module provides a `PostgreSQLContainer` class for managing the container. + +### Write the test + +Create `CustomerServiceTest.java` under `src/test/java`: + +```java +package com.testcontainers.demo; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.util.List; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.testcontainers.postgresql.PostgreSQLContainer; + +class CustomerServiceTest { + + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine" + ); + + CustomerService customerService; + + @BeforeAll + static void beforeAll() { + postgres.start(); + } + + @AfterAll + static void afterAll() { + postgres.stop(); + } + + @BeforeEach + void setUp() { + DBConnectionProvider connectionProvider = new DBConnectionProvider( + postgres.getJdbcUrl(), + postgres.getUsername(), + postgres.getPassword() + ); + customerService = new CustomerService(connectionProvider); + } + + @Test + void shouldGetCustomers() { + customerService.createCustomer(new Customer(1L, "George")); + customerService.createCustomer(new Customer(2L, "John")); + + List<Customer> customers = customerService.getAllCustomers(); + assertEquals(2, customers.size()); + } +} +``` + +Here's what the test does: + +- Declares a `PostgreSQLContainer` with the `postgres:16-alpine` Docker image. +- The `@BeforeAll` callback starts the Postgres container before any test + methods run. +- The `@BeforeEach` callback creates a `DBConnectionProvider` using the JDBC + connection parameters from the container, then creates a `CustomerService`. + The `CustomerService` constructor creates the `customers` table if it + doesn't exist. +- `shouldGetCustomers()` inserts 2 customer records, fetches all customers, + and asserts the count. +- The `@AfterAll` callback stops the container after all test methods finish. + +## Run tests and next steps + +### Run the tests + +Run the tests using Maven: + +```console +$ mvn test +``` + +You can see in the logs that Testcontainers pulls the Postgres Docker image +from Docker Hub (if not already available locally), starts the container, and +runs the test. + +Writing an integration test using Testcontainers works like writing a unit test +that you can run from your IDE. Your teammates can clone the project +and run tests without installing Postgres on their machines. + +### Summary + +The Testcontainers for Java library helps you write integration tests using the +same type of database (Postgres) that you use in production, instead of mocks. +Because you aren't using mocks and instead talk to real services, you're free +to refactor code and still verify that the application works as expected. + +In addition to Postgres, Testcontainers provides dedicated modules for many +SQL databases, NoSQL databases, messaging queues, and more. You can use +Testcontainers to run any containerized dependency for your tests. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testcontainers container lifecycle management using JUnit 5](https://testcontainers.com/guides/testcontainers-container-lifecycle/) +- [Replace H2 with a real database for testing](https://testcontainers.com/guides/replace-h2-with-real-database-for-testing/) +- [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/) diff --git a/content/guides/testcontainers-java-getting-started/_index.md b/content/guides/testcontainers-java-getting-started/_index.md deleted file mode 100644 index 1a4ee3b837fa..000000000000 --- a/content/guides/testcontainers-java-getting-started/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Getting started with Testcontainers for Java -linkTitle: Testcontainers for Java -description: Learn how to use Testcontainers for Java to test a customer service with a real PostgreSQL database. -keywords: testcontainers, java, testing, postgresql, integration testing, junit, maven -summary: | - Learn how to create a Java application and test database interactions - using Testcontainers for Java with a real PostgreSQL instance. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-java --> - -In this guide, you will learn how to: - -- Create a Java project with Maven -- Implement a `CustomerService` that manages customer records in PostgreSQL -- Write integration tests using Testcontainers with a real Postgres database -- Run the tests and verify everything works - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-getting-started/create-project.md b/content/guides/testcontainers-java-getting-started/create-project.md deleted file mode 100644 index 19ef95958c31..000000000000 --- a/content/guides/testcontainers-java-getting-started/create-project.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Create the Java project -linkTitle: Create the project -description: Set up a Java project with Maven and implement a PostgreSQL-backed customer service. -keywords: testcontainers, java, maven, postgresql, getting started, project setup -weight: 10 ---- - -## Set up the Maven project - -Create a Java project with Maven from your preferred IDE. This guide uses -Maven, but you can use Gradle if you prefer. Add the following dependencies -to `pom.xml`: - -```xml -<dependencies> - <dependency> - <groupId>org.postgresql</groupId> - <artifactId>postgresql</artifactId> - <version>42.7.3</version> - </dependency> - <dependency> - <groupId>ch.qos.logback</groupId> - <artifactId>logback-classic</artifactId> - <version>1.5.6</version> - </dependency> - <dependency> - <groupId>org.junit.jupiter</groupId> - <artifactId>junit-jupiter</artifactId> - <version>5.10.2</version> - <scope>test</scope> - </dependency> -</dependencies> - -<build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <version>3.2.5</version> - </plugin> - </plugins> -</build> -``` - -This adds the Postgres JDBC driver, logback for logging, JUnit 5 for testing, -and the latest `maven-surefire-plugin` for JUnit 5 support. - -## Implement the business logic - -Create a `Customer` record: - -```java -package com.testcontainers.demo; - -public record Customer(Long id, String name) {} -``` - -Create a `DBConnectionProvider` class to hold JDBC connection parameters and -provide a database `Connection`: - -```java -package com.testcontainers.demo; - -import java.sql.Connection; -import java.sql.DriverManager; - -class DBConnectionProvider { - - private final String url; - private final String username; - private final String password; - - public DBConnectionProvider(String url, String username, String password) { - this.url = url; - this.username = username; - this.password = password; - } - - Connection getConnection() { - try { - return DriverManager.getConnection(url, username, password); - } catch (Exception e) { - throw new RuntimeException(e); - } - } -} -``` - -Create the `CustomerService` class: - -```java -package com.testcontainers.demo; - -import java.sql.Connection; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.util.ArrayList; -import java.util.List; - -public class CustomerService { - - private final DBConnectionProvider connectionProvider; - - public CustomerService(DBConnectionProvider connectionProvider) { - this.connectionProvider = connectionProvider; - createCustomersTableIfNotExists(); - } - - public void createCustomer(Customer customer) { - try (Connection conn = this.connectionProvider.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - "insert into customers(id,name) values(?,?)" - ); - pstmt.setLong(1, customer.id()); - pstmt.setString(2, customer.name()); - pstmt.execute(); - } catch (SQLException e) { - throw new RuntimeException(e); - } - } - - public List<Customer> getAllCustomers() { - List<Customer> customers = new ArrayList<>(); - - try (Connection conn = this.connectionProvider.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - "select id,name from customers" - ); - ResultSet rs = pstmt.executeQuery(); - while (rs.next()) { - long id = rs.getLong("id"); - String name = rs.getString("name"); - customers.add(new Customer(id, name)); - } - } catch (SQLException e) { - throw new RuntimeException(e); - } - return customers; - } - - private void createCustomersTableIfNotExists() { - try (Connection conn = this.connectionProvider.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - """ - create table if not exists customers ( - id bigint not null, - name varchar not null, - primary key (id) - ) - """ - ); - pstmt.execute(); - } catch (SQLException e) { - throw new RuntimeException(e); - } - } -} -``` - -Here's what `CustomerService` does: - -- The constructor calls `createCustomersTableIfNotExists()` to ensure the table exists. -- `createCustomer()` inserts a customer record into the database. -- `getAllCustomers()` fetches all rows from the `customers` table and returns a list of `Customer` objects. diff --git a/content/guides/testcontainers-java-getting-started/run-tests.md b/content/guides/testcontainers-java-getting-started/run-tests.md deleted file mode 100644 index 6ab956485a2d..000000000000 --- a/content/guides/testcontainers-java-getting-started/run-tests.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, java, postgresql, integration testing, run tests -weight: 30 ---- - -## Run the tests - -Run the tests using Maven: - -```console -$ mvn test -``` - -You can see in the logs that Testcontainers pulls the Postgres Docker image -from Docker Hub (if not already available locally), starts the container, and -runs the test. - -Writing an integration test using Testcontainers works like writing a unit test -that you can run from your IDE. Your teammates can clone the project -and run tests without installing Postgres on their machines. - -## Summary - -The Testcontainers for Java library helps you write integration tests using the -same type of database (Postgres) that you use in production, instead of mocks. -Because you aren't using mocks and instead talk to real services, you're free -to refactor code and still verify that the application works as expected. - -In addition to Postgres, Testcontainers provides dedicated modules for many -SQL databases, NoSQL databases, messaging queues, and more. You can use -Testcontainers to run any containerized dependency for your tests. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers container lifecycle management using JUnit 5](https://testcontainers.com/guides/testcontainers-container-lifecycle/) -- [Replace H2 with a real database for testing](https://testcontainers.com/guides/replace-h2-with-real-database-for-testing/) -- [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/) diff --git a/content/guides/testcontainers-java-getting-started/write-tests.md b/content/guides/testcontainers-java-getting-started/write-tests.md deleted file mode 100644 index 051d5bc8a591..000000000000 --- a/content/guides/testcontainers-java-getting-started/write-tests.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Write your first integration test using Testcontainers for Java and PostgreSQL. -keywords: testcontainers, java, postgresql, junit, integration testing -weight: 20 ---- - -You have the `CustomerService` implementation ready, but for testing you need a -PostgreSQL database. You can use Testcontainers to spin up a Postgres database -in a Docker container and run your tests against it. - -## Add Testcontainers dependencies - -Add the Testcontainers PostgreSQL module as a test dependency in `pom.xml`: - -```xml -<dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-postgresql</artifactId> - <version>2.0.4</version> - <scope>test</scope> -</dependency> -``` - -Since the application uses a Postgres database, the Testcontainers Postgres -module provides a `PostgreSQLContainer` class for managing the container. - -## Write the test - -Create `CustomerServiceTest.java` under `src/test/java`: - -```java -package com.testcontainers.demo; - -import static org.junit.jupiter.api.Assertions.assertEquals; - -import java.util.List; -import org.junit.jupiter.api.AfterAll; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.testcontainers.postgresql.PostgreSQLContainer; - -class CustomerServiceTest { - - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ); - - CustomerService customerService; - - @BeforeAll - static void beforeAll() { - postgres.start(); - } - - @AfterAll - static void afterAll() { - postgres.stop(); - } - - @BeforeEach - void setUp() { - DBConnectionProvider connectionProvider = new DBConnectionProvider( - postgres.getJdbcUrl(), - postgres.getUsername(), - postgres.getPassword() - ); - customerService = new CustomerService(connectionProvider); - } - - @Test - void shouldGetCustomers() { - customerService.createCustomer(new Customer(1L, "George")); - customerService.createCustomer(new Customer(2L, "John")); - - List<Customer> customers = customerService.getAllCustomers(); - assertEquals(2, customers.size()); - } -} -``` - -Here's what the test does: - -- Declares a `PostgreSQLContainer` with the `postgres:16-alpine` Docker image. -- The `@BeforeAll` callback starts the Postgres container before any test - methods run. -- The `@BeforeEach` callback creates a `DBConnectionProvider` using the JDBC - connection parameters from the container, then creates a `CustomerService`. - The `CustomerService` constructor creates the `customers` table if it - doesn't exist. -- `shouldGetCustomers()` inserts 2 customer records, fetches all customers, - and asserts the count. -- The `@AfterAll` callback stops the container after all test methods finish. diff --git a/content/guides/testcontainers-java-jooq-flyway/_index.md b/content/guides/testcontainers-java-jooq-flyway/_index.md deleted file mode 100644 index 86e12078d0df..000000000000 --- a/content/guides/testcontainers-java-jooq-flyway/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Working with jOOQ and Flyway using Testcontainers -linkTitle: jOOQ and Flyway -description: Learn how to generate jOOQ code from a database using Testcontainers and Flyway, then test your persistence layer. -keywords: testcontainers, java, testing, jooq, flyway, postgresql, spring boot, code generation -summary: | - Generate typesafe jOOQ code from a real PostgreSQL database managed by - Flyway migrations, then test repositories using Testcontainers. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-working-with-jooq-flyway-using-testcontainers --> - -In this guide, you will learn how to: - -- Create a Spring Boot application with jOOQ support -- Generate jOOQ code using Testcontainers, Flyway, and a Maven plugin -- Implement basic database operations using jOOQ -- Load complex object graphs using jOOQ's MULTISET feature -- Test the jOOQ persistence layer using Testcontainers - -## Prerequisites - -- Java 17+ -- Maven -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-jooq-flyway/create-project.md b/content/guides/testcontainers-java-jooq-flyway/create-project.md deleted file mode 100644 index 83adb5349938..000000000000 --- a/content/guides/testcontainers-java-jooq-flyway/create-project.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with jOOQ, Flyway, PostgreSQL, and Testcontainers code generation. -keywords: testcontainers, java, spring boot, jooq, flyway, postgresql, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting Maven as the build tool and adding the **JOOQ Access Layer**, -**Flyway Migration**, **Spring Boot DevTools**, **PostgreSQL Driver**, and -**Testcontainers** starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-working-with-jooq-flyway-using-testcontainers). - -jOOQ (jOOQ Object Oriented Querying) provides a fluent API for building -typesafe SQL queries. To get the full benefit of its typesafe DSL, you need -to generate Java code from your database tables, views, and other objects. - -> [!TIP] -> To learn more about how the jOOQ code generator helps, read -> [Why You Should Use jOOQ With Code Generation](https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/). - -The typical process for building and testing the application with jOOQ code -generation is: - -1. Create a database instance using Testcontainers. -2. Apply Flyway database migrations. -3. Run the jOOQ code generator to produce Java code from the database objects. -4. Run integration tests. - -The -[testcontainers-jooq-codegen-maven-plugin](https://github.com/testcontainers/testcontainers-jooq-codegen-maven-plugin) -automates this as part of the Maven build. - -## Create Flyway migration scripts - -The sample application has `users`, `posts`, and `comments` tables. Create -the first migration script following the Flyway naming convention. - -Create `src/main/resources/db/migration/V1__create_tables.sql`: - -```sql -create table users -( - id bigserial not null, - name varchar not null, - email varchar not null, - created_at timestamp, - updated_at timestamp, - primary key (id), - constraint user_email_unique unique (email) -); - -create table posts -( - id bigserial not null, - title varchar not null, - content varchar not null, - created_by bigint references users (id) not null, - created_at timestamp, - updated_at timestamp, - primary key (id) -); - -create table comments -( - id bigserial not null, - name varchar not null, - content varchar not null, - post_id bigint references posts (id) not null, - created_at timestamp, - updated_at timestamp, - primary key (id) -); - -ALTER SEQUENCE users_id_seq RESTART WITH 101; -ALTER SEQUENCE posts_id_seq RESTART WITH 101; -ALTER SEQUENCE comments_id_seq RESTART WITH 101; -``` - -The sequence values restart at 101 so that you can insert sample data with -explicit primary key values for testing. - -## Configure jOOQ code generation - -Add the `testcontainers-jooq-codegen-maven-plugin` to `pom.xml`: - -```xml -<properties> - <testcontainers.version>2.0.4</testcontainers.version> - <testcontainers-jooq-codegen-maven-plugin.version>0.0.4</testcontainers-jooq-codegen-maven-plugin.version> -</properties> - -<build> - <plugins> - <plugin> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-jooq-codegen-maven-plugin</artifactId> - <version>${testcontainers-jooq-codegen-maven-plugin.version}</version> - <dependencies> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-postgresql</artifactId> - <version>${testcontainers.version}</version> - </dependency> - <dependency> - <groupId>org.postgresql</groupId> - <artifactId>postgresql</artifactId> - <version>${postgresql.version}</version> - </dependency> - </dependencies> - <executions> - <execution> - <id>generate-jooq-sources</id> - <goals> - <goal>generate</goal> - </goals> - <phase>generate-sources</phase> - <configuration> - <database> - <type>POSTGRES</type> - <containerImage>postgres:16-alpine</containerImage> - </database> - <flyway> - <locations> - filesystem:src/main/resources/db/migration - </locations> - </flyway> - <jooq> - <generator> - <database> - <includes>.*</includes> - <excludes>flyway_schema_history</excludes> - <inputSchema>public</inputSchema> - </database> - <target> - <packageName>com.testcontainers.demo.jooq</packageName> - <directory>target/generated-sources/jooq</directory> - </target> - </generator> - </jooq> - </configuration> - </execution> - </executions> - </plugin> - </plugins> -</build> -``` - -Here's what the plugin configuration does: - -- The `<configuration>/<database>` section sets the database type to - `POSTGRES` and the Docker image to `postgres:16-alpine`. -- The `<configuration>/<flyway>` section points to the Flyway migration - scripts. -- The `<configuration>/<jooq>` section configures the package name and - output directory for the generated code. You can use any configuration - option that the official `jooq-code-generator` plugin supports. - -When you run `./mvnw clean package`, the plugin uses Testcontainers to -spin up a PostgreSQL container, applies the Flyway migrations, and generates -Java code under `target/generated-sources/jooq`. - -## Create model classes - -Create model classes to represent the data structures for various use cases. -These records hold a subset of column values from the tables. - -`User.java`: - -```java -package com.testcontainers.demo.domain; - -public record User(Long id, String name, String email) {} -``` - -`Post.java`: - -```java -package com.testcontainers.demo.domain; - -import java.time.LocalDateTime; -import java.util.List; - -public record Post( - Long id, - String title, - String content, - User createdBy, - List<Comment> comments, - LocalDateTime createdAt, - LocalDateTime updatedAt -) {} -``` - -`Comment.java`: - -```java -package com.testcontainers.demo.domain; - -import java.time.LocalDateTime; - -public record Comment( - Long id, - String name, - String content, - LocalDateTime createdAt, - LocalDateTime updatedAt -) {} -``` - -## Implement repositories using jOOQ - -Create `UserRepository.java` with methods to create a user and look up a user -by email: - -```java -package com.testcontainers.demo.domain; - -import static com.testcontainers.demo.jooq.tables.Users.USERS; -import static org.jooq.Records.mapping; - -import java.time.LocalDateTime; -import java.util.Optional; -import org.jooq.DSLContext; -import org.springframework.stereotype.Repository; - -@Repository -class UserRepository { - - private final DSLContext dsl; - - UserRepository(DSLContext dsl) { - this.dsl = dsl; - } - - public User createUser(User user) { - return this.dsl.insertInto(USERS) - .set(USERS.NAME, user.name()) - .set(USERS.EMAIL, user.email()) - .set(USERS.CREATED_AT, LocalDateTime.now()) - .returningResult(USERS.ID, USERS.NAME, USERS.EMAIL) - .fetchOne(mapping(User::new)); - } - - public Optional<User> getUserByEmail(String email) { - return this.dsl.select(USERS.ID, USERS.NAME, USERS.EMAIL) - .from(USERS) - .where(USERS.EMAIL.equalIgnoreCase(email)) - .fetchOptional(mapping(User::new)); - } -} -``` - -The jOOQ DSL looks similar to SQL but written in Java. Because the code is -generated from the database schema, it stays in sync with the database -structure and provides type safety. For example, -`where(USERS.EMAIL.equalIgnoreCase(email))` expects a `String` value. If you -pass a non-string value like `123`, you get a compiler error. - -## Fetch complex object graphs - -jOOQ shines when it comes to complex queries. The database has a many-to-one -relationship from `Post` to `User` and a one-to-many relationship from `Post` -to `Comment`. - -Create `PostRepository.java` to load a `Post` with its creator and comments -using a single query with jOOQ's MULTISET feature: - -```java -package com.testcontainers.demo.domain; - -import static com.testcontainers.demo.jooq.Tables.COMMENTS; -import static com.testcontainers.demo.jooq.tables.Posts.POSTS; -import static org.jooq.Records.mapping; -import static org.jooq.impl.DSL.multiset; -import static org.jooq.impl.DSL.row; -import static org.jooq.impl.DSL.select; - -import java.util.Optional; -import org.jooq.DSLContext; -import org.springframework.stereotype.Repository; - -@Repository -class PostRepository { - - private final DSLContext dsl; - - PostRepository(DSLContext dsl) { - this.dsl = dsl; - } - - public Optional<Post> getPostById(Long id) { - return this.dsl.select( - POSTS.ID, - POSTS.TITLE, - POSTS.CONTENT, - row(POSTS.users().ID, POSTS.users().NAME, POSTS.users().EMAIL) - .mapping(User::new) - .as("createdBy"), - multiset( - select( - COMMENTS.ID, - COMMENTS.NAME, - COMMENTS.CONTENT, - COMMENTS.CREATED_AT, - COMMENTS.UPDATED_AT - ) - .from(COMMENTS) - .where(POSTS.ID.eq(COMMENTS.POST_ID)) - ) - .as("comments") - .convertFrom(r -> r.map(mapping(Comment::new))), - POSTS.CREATED_AT, - POSTS.UPDATED_AT - ) - .from(POSTS) - .where(POSTS.ID.eq(id)) - .fetchOptional(mapping(Post::new)); - } -} -``` - -This uses jOOQ's -[nested records](https://www.jooq.org/doc/latest/manual/sql-building/column-expressions/nested-records/) -for the many-to-one `Post`-to-`User` association and -[MULTISET](https://www.jooq.org/doc/latest/manual/sql-building/column-expressions/multiset-value-constructor/) -for the one-to-many `Post`-to-`Comment` association. diff --git a/content/guides/testcontainers-java-jooq-flyway/run-tests.md b/content/guides/testcontainers-java-jooq-flyway/run-tests.md deleted file mode 100644 index af346bffba04..000000000000 --- a/content/guides/testcontainers-java-jooq-flyway/run-tests.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run the jOOQ and Flyway integration tests and explore next steps. -keywords: testcontainers, java, spring boot, jooq, flyway, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -You should see the PostgreSQL Docker container start, jOOQ code generation -complete, and all tests pass. After the tests finish, the container stops and -is removed automatically. - -## Summary - -The Testcontainers library helps you generate Java code from the database -using the jOOQ code generator and test your persistence layer against the -same type of database (PostgreSQL) that you use in production, instead of -mocks or in-memory databases. - -Because the code is always generated from the database's current state, you -can be confident that your code stays in sync with database changes. You're -free to refactor and still verify that the application works as expected. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [jOOQ documentation](https://www.jooq.org/) -- [jOOQ code generation](https://www.jooq.org/doc/latest/manual/code-generation/) -- [Spring Boot Testcontainers support](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html) -- [Replace H2 with a real database for testing](/guides/testcontainers-java-replace-h2/) diff --git a/content/guides/testcontainers-java-jooq-flyway/write-tests.md b/content/guides/testcontainers-java-jooq-flyway/write-tests.md deleted file mode 100644 index f4720256d295..000000000000 --- a/content/guides/testcontainers-java-jooq-flyway/write-tests.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test jOOQ repositories using Testcontainers with the @JooqTest slice and @SpringBootTest. -keywords: testcontainers, java, spring boot, jooq, flyway, postgresql, integration testing -weight: 20 ---- - -Before writing the tests, create an SQL script to seed test data at -`src/test/resources/test-data.sql`: - -```sql -DELETE FROM comments; -DELETE FROM posts; -DELETE FROM users; - -INSERT INTO users(id, name, email) VALUES -(1, 'Siva', 'siva@gmail.com'), -(2, 'Oleg', 'oleg@gmail.com'); - -INSERT INTO posts(id, title, content, created_by, created_at) VALUES -(1, 'Post 1 Title', 'Post 1 content', 1, CURRENT_TIMESTAMP), -(2, 'Post 2 Title', 'Post 2 content', 2, CURRENT_TIMESTAMP); - -INSERT INTO comments(id, name, content, post_id, created_at) VALUES -(1, 'Ron', 'Comment 1', 1, CURRENT_TIMESTAMP), -(2, 'James', 'Comment 2', 1, CURRENT_TIMESTAMP), -(3, 'Robert', 'Comment 3', 2, CURRENT_TIMESTAMP); -``` - -## Test with the @JooqTest slice - -The `@JooqTest` annotation loads only the persistence layer components and -auto-configures jOOQ's `DSLContext`. Use the Testcontainers special JDBC URL -to start a Postgres container. - -Create `UserRepositoryJooqTest.java`: - -```java -package com.testcontainers.demo.domain; - -import static org.assertj.core.api.Assertions.assertThat; - -import org.jooq.DSLContext; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.autoconfigure.jooq.JooqTest; -import org.springframework.test.context.jdbc.Sql; - -@JooqTest( - properties = { - "spring.test.database.replace=none", - "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db", - } -) -@Sql("/test-data.sql") -class UserRepositoryJooqTest { - - @Autowired - DSLContext dsl; - - UserRepository repository; - - @BeforeEach - void setUp() { - this.repository = new UserRepository(dsl); - } - - @Test - void shouldCreateUserSuccessfully() { - User user = new User(null, "John", "john@gmail.com"); - - User savedUser = repository.createUser(user); - - assertThat(savedUser.id()).isNotNull(); - assertThat(savedUser.name()).isEqualTo("John"); - assertThat(savedUser.email()).isEqualTo("john@gmail.com"); - } - - @Test - void shouldGetUserByEmail() { - User user = repository.getUserByEmail("siva@gmail.com").orElseThrow(); - - assertThat(user.id()).isEqualTo(1L); - assertThat(user.name()).isEqualTo("Siva"); - assertThat(user.email()).isEqualTo("siva@gmail.com"); - } -} -``` - -Here's what the test does: - -- `@JooqTest` loads only the persistence layer and auto-configures - `DSLContext`. -- The Testcontainers special JDBC URL - (`jdbc:tc:postgresql:16-alpine:///db`) starts a PostgreSQL container - automatically. -- Because `flyway-core` is on the classpath, Spring Boot runs the Flyway - migrations from `src/main/resources/db/migration` on startup. -- `@Sql("/test-data.sql")` loads the test data before each test. -- The `UserRepository` is instantiated manually with the injected - `DSLContext`. - -## Integration test with @SpringBootTest - -For a full integration test, use `@SpringBootTest` with the Testcontainers -`@ServiceConnection` support introduced in Spring Boot 3.1. - -Create `UserRepositoryTest.java`: - -```java -package com.testcontainers.demo.domain; - -import static org.assertj.core.api.Assertions.assertThat; - -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.testcontainers.service.connection.ServiceConnection; -import org.springframework.test.context.jdbc.Sql; -import org.testcontainers.postgresql.PostgreSQLContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; - -@SpringBootTest -@Sql("/test-data.sql") -@Testcontainers -class UserRepositoryTest { - - @Container - @ServiceConnection - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ); - - @Autowired - UserRepository repository; - - @Test - void shouldCreateUserSuccessfully() { - User user = new User(null, "John", "john@gmail.com"); - - User savedUser = repository.createUser(user); - - assertThat(savedUser.id()).isNotNull(); - assertThat(savedUser.name()).isEqualTo("John"); - assertThat(savedUser.email()).isEqualTo("john@gmail.com"); - } - - @Test - void shouldGetUserByEmail() { - User user = repository.getUserByEmail("siva@gmail.com").orElseThrow(); - - assertThat(user.id()).isEqualTo(1L); - assertThat(user.name()).isEqualTo("Siva"); - assertThat(user.email()).isEqualTo("siva@gmail.com"); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` loads the entire application context, so - `UserRepository` is injected directly. -- `@Testcontainers` and `@Container` manage the PostgreSQL container - lifecycle. -- `@ServiceConnection` auto-configures the datasource properties from the - running container, replacing the need for `@DynamicPropertySource`. -- `@Sql("/test-data.sql")` initializes the test data. - -## Test PostRepository - -Test the `PostRepository` that fetches complex object graphs using the -Testcontainers special JDBC URL. - -Create `PostRepositoryTest.java`: - -```java -package com.testcontainers.demo.domain; - -import static org.assertj.core.api.Assertions.assertThat; - -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.test.context.jdbc.Sql; - -@SpringBootTest( - properties = { - "spring.test.database.replace=none", - "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db", - } -) -@Sql("/test-data.sql") -class PostRepositoryTest { - - @Autowired - PostRepository repository; - - @Test - void shouldGetPostById() { - Post post = repository.getPostById(1L).orElseThrow(); - - assertThat(post.id()).isEqualTo(1L); - assertThat(post.title()).isEqualTo("Post 1 Title"); - assertThat(post.content()).isEqualTo("Post 1 content"); - assertThat(post.createdBy().id()).isEqualTo(1L); - assertThat(post.createdBy().name()).isEqualTo("Siva"); - assertThat(post.createdBy().email()).isEqualTo("siva@gmail.com"); - assertThat(post.comments()).hasSize(2); - } -} -``` - -This test verifies that `getPostById` loads the post along with its creator -and comments in a single query using jOOQ's MULTISET feature. diff --git a/content/guides/testcontainers-java-keycloak-spring-boot/_index.md b/content/guides/testcontainers-java-keycloak-spring-boot/_index.md deleted file mode 100644 index 619b69146fa4..000000000000 --- a/content/guides/testcontainers-java-keycloak-spring-boot/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Securing Spring Boot microservice using Keycloak and Testcontainers -linkTitle: Keycloak with Spring Boot -description: Learn how to secure a Spring Boot microservice using Keycloak and test it with the Testcontainers Keycloak module. -keywords: testcontainers, java, spring boot, testing, keycloak, security, oauth2, jwt -summary: | - Learn how to create an OAuth 2.0 Resource Server using Spring Boot, secure API - endpoints with Keycloak, and test the application using the Testcontainers Keycloak module. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 30 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-securing-spring-boot-microservice-using-keycloak-and-testcontainers --> - -In this guide, you'll learn how to: - -- Create an OAuth 2.0 Resource Server using Spring Boot -- Secure API endpoints using Keycloak -- Test the APIs using the Testcontainers Keycloak module -- Run the application locally using the Testcontainers Keycloak module - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-keycloak-spring-boot/create-project.md b/content/guides/testcontainers-java-keycloak-spring-boot/create-project.md deleted file mode 100644 index db7f07663290..000000000000 --- a/content/guides/testcontainers-java-keycloak-spring-boot/create-project.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot OAuth 2.0 Resource Server with Keycloak, PostgreSQL, and Testcontainers. -keywords: testcontainers, java, spring boot, keycloak, oauth2, postgresql, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Spring Web**, **Validation**, **JDBC API**, -**PostgreSQL Driver**, **Spring Security**, **OAuth2 Resource Server**, and -**Testcontainers** starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-securing-spring-boot-microservice-using-keycloak-and-testcontainers). - -After generating the application, add the -[testcontainers-keycloak](https://github.com/dasniko/testcontainers-keycloak) -community module and [REST Assured](https://rest-assured.io/) as test -dependencies. - -The key dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> -</properties> -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-web</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-validation</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-jdbc</artifactId> - </dependency> - <dependency> - <groupId>org.postgresql</groupId> - <artifactId>postgresql</artifactId> - <scope>runtime</scope> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-security</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-oauth2-resource-server</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.springframework.security</groupId> - <artifactId>spring-security-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-testcontainers</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-postgresql</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>com.github.dasniko</groupId> - <artifactId>testcontainers-keycloak</artifactId> - <version>3.4.0</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.rest-assured</groupId> - <artifactId>rest-assured</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -## Create the domain model - -Create a `Product` record that represents the domain object: - -```java -package com.testcontainers.products.domain; - -import jakarta.validation.constraints.NotEmpty; - -public record Product(Long id, @NotEmpty String title, String description) {} -``` - -## Create the repository - -Implement `ProductRepository` using Spring `JdbcClient` to interact with a -PostgreSQL database: - -```java -package com.testcontainers.products.domain; - -import java.util.List; -import org.springframework.jdbc.core.simple.JdbcClient; -import org.springframework.jdbc.support.GeneratedKeyHolder; -import org.springframework.jdbc.support.KeyHolder; -import org.springframework.stereotype.Repository; - -@Repository -public class ProductRepository { - - private final JdbcClient jdbcClient; - - public ProductRepository(JdbcClient jdbcClient) { - this.jdbcClient = jdbcClient; - } - - public List<Product> getAll() { - return jdbcClient.sql("SELECT * FROM products").query(Product.class).list(); - } - - public Product create(Product product) { - String sql = - "INSERT INTO products(title, description) VALUES (:title,:description) RETURNING id"; - KeyHolder keyHolder = new GeneratedKeyHolder(); - jdbcClient - .sql(sql) - .param("title", product.title()) - .param("description", product.description()) - .update(keyHolder); - Long id = keyHolder.getKeyAs(Long.class); - return new Product(id, product.title(), product.description()); - } -} -``` - -## Add a schema creation script - -Create `src/main/resources/schema.sql` to initialize the `products` table: - -```sql -CREATE TABLE products ( - id bigserial primary key, - title varchar not null, - description text -); -``` - -Enable schema initialization in `src/main/resources/application.properties`: - -```properties -spring.sql.init.mode=always -``` - -For production applications, use a database migration tool like Flyway or -Liquibase instead. - -## Implement the API endpoints - -Create `ProductController` with endpoints to fetch all products and create a -product: - -```java -package com.testcontainers.products.api; - -import com.testcontainers.products.domain.Product; -import com.testcontainers.products.domain.ProductRepository; -import jakarta.validation.Valid; -import java.util.List; -import org.springframework.http.HttpStatus; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PostMapping; -import org.springframework.web.bind.annotation.RequestBody; -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.ResponseStatus; -import org.springframework.web.bind.annotation.RestController; - -@RestController -@RequestMapping("/api/products") -class ProductController { - - private final ProductRepository productRepository; - - ProductController(ProductRepository productRepository) { - this.productRepository = productRepository; - } - - @GetMapping - List<Product> getAll() { - return productRepository.getAll(); - } - - @PostMapping - @ResponseStatus(HttpStatus.CREATED) - Product createProduct(@RequestBody @Valid Product product) { - return productRepository.create(product); - } -} -``` - -## Configure OAuth 2.0 security - -Create a `SecurityConfig` class that protects the API endpoints using JWT -token-based authentication: - -```java -package com.testcontainers.products.config; - -import static org.springframework.security.config.Customizer.withDefaults; - -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; -import org.springframework.http.HttpMethod; -import org.springframework.security.config.annotation.web.builders.HttpSecurity; -import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; -import org.springframework.security.config.annotation.web.configurers.CorsConfigurer; -import org.springframework.security.config.annotation.web.configurers.CsrfConfigurer; -import org.springframework.security.config.http.SessionCreationPolicy; -import org.springframework.security.web.SecurityFilterChain; - -@Configuration -@EnableWebSecurity -class SecurityConfig { - - @Bean - SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { - http - .authorizeHttpRequests(c -> - c - .requestMatchers(HttpMethod.GET, "/api/products") - .permitAll() - .requestMatchers(HttpMethod.POST, "/api/products") - .authenticated() - .anyRequest() - .authenticated() - ) - .sessionManagement(c -> - c.sessionCreationPolicy(SessionCreationPolicy.STATELESS) - ) - .cors(CorsConfigurer::disable) - .csrf(CsrfConfigurer::disable) - .oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults())); - return http.build(); - } -} -``` - -This configuration: - -- Permits unauthenticated access to `GET /api/products`. -- Requires authentication for `POST /api/products` and all other endpoints. -- Configures the OAuth 2.0 Resource Server with JWT token-based authentication. -- Disables CORS and CSRF because this is a stateless API. - -Add the JWT issuer URI to `application.properties`: - -```properties -spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9090/realms/keycloaktcdemo -``` - -## Export the Keycloak realm configuration - -Before writing the tests, export a Keycloak realm configuration so that the test -environment can import it automatically. Start a temporary Keycloak instance: - -```console -$ docker run -p 9090:8080 \ - -e KEYCLOAK_ADMIN=admin \ - -e KEYCLOAK_ADMIN_PASSWORD=admin \ - quay.io/keycloak/keycloak:25 start-dev -``` - -Open `http://localhost:9090` and sign in to the Admin Console with `admin/admin`. -Then set up the realm: - -1. In the top-left corner, select the realm drop-down and create a realm named - `keycloaktcdemo`. -2. Under the `keycloaktcdemo` realm, create a client with the following - settings: - - **Client ID**: `product-service` - - **Client Authentication**: `On` - - **Authentication flow**: select only **Service accounts roles** -3. On the **Client details** screen, go to the **Credentials** tab and copy the - **Client secret** value. - -Export the realm configuration: - -```console -$ docker ps -# copy the keycloak container id - -$ docker exec -it <container-id> /bin/bash - -$ /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --realm keycloaktcdemo - -$ exit - -$ docker cp <container-id>:/opt/keycloak/data/import/keycloaktcdemo-realm.json keycloaktcdemo-realm.json -``` - -Copy the exported `keycloaktcdemo-realm.json` file into `src/test/resources`. diff --git a/content/guides/testcontainers-java-keycloak-spring-boot/run-tests.md b/content/guides/testcontainers-java-keycloak-spring-boot/run-tests.md deleted file mode 100644 index 9f3a72f54ff7..000000000000 --- a/content/guides/testcontainers-java-keycloak-spring-boot/run-tests.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Spring Boot Keycloak integration tests and explore next steps. -keywords: testcontainers, java, spring boot, keycloak, oauth2, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the Keycloak and PostgreSQL Docker containers start with the -realm settings imported and the tests pass. After the tests finish, the -containers stop and are removed automatically. - -## Summary - -The Testcontainers Keycloak module lets you develop and test applications using a -real Keycloak server instead of mocks. Testing against a real OAuth 2.0 -provider that mirrors your production setup gives you more confidence in your -security configuration and token-based authentication flows. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/) -- [Testcontainers Keycloak module](https://testcontainers.com/modules/keycloak/) -- [testcontainers-keycloak GitHub repository](https://github.com/dasniko/testcontainers-keycloak) -- [Spring Boot OAuth 2.0 Resource Server](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/index.html) diff --git a/content/guides/testcontainers-java-keycloak-spring-boot/write-tests.md b/content/guides/testcontainers-java-keycloak-spring-boot/write-tests.md deleted file mode 100644 index 90262b3a94a8..000000000000 --- a/content/guides/testcontainers-java-keycloak-spring-boot/write-tests.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test the secured Spring Boot API endpoints using Testcontainers Keycloak and PostgreSQL modules. -keywords: testcontainers, java, spring boot, keycloak, oauth2, postgresql, integration testing -weight: 20 ---- - -To test the secured API endpoints, you need a running Keycloak instance and a -PostgreSQL database, plus a started Spring context. Testcontainers spins up both -services in Docker containers and connects them to Spring through dynamic -property registration. - -## Configure the test containers - -Spring Boot's Testcontainers support lets you declare containers as beans. For -Keycloak, `@ServiceConnection` isn't available, but you can use -`DynamicPropertyRegistry` to set the JWT issuer URI dynamically. - -Create `ContainersConfig.java` under `src/test/java`: - -```java -package com.testcontainers.products; - -import dasniko.testcontainers.keycloak.KeycloakContainer; -import org.springframework.boot.test.context.TestConfiguration; -import org.springframework.boot.testcontainers.service.connection.ServiceConnection; -import org.springframework.context.annotation.Bean; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.testcontainers.postgresql.PostgreSQLContainer; - -@TestConfiguration(proxyBeanMethods = false) -public class ContainersConfig { - - static String POSTGRES_IMAGE = "postgres:16-alpine"; - static String KEYCLOAK_IMAGE = "quay.io/keycloak/keycloak:25.0"; - static String realmImportFile = "/keycloaktcdemo-realm.json"; - static String realmName = "keycloaktcdemo"; - - @Bean - @ServiceConnection - PostgreSQLContainer postgres() { - return new PostgreSQLContainer(POSTGRES_IMAGE); - } - - @Bean - KeycloakContainer keycloak(DynamicPropertyRegistry registry) { - var keycloak = new KeycloakContainer(KEYCLOAK_IMAGE) - .withRealmImportFile(realmImportFile); - registry.add( - "spring.security.oauth2.resourceserver.jwt.issuer-uri", - () -> keycloak.getAuthServerUrl() + "/realms/" + realmName - ); - return keycloak; - } -} -``` - -This configuration: - -- Declares a `PostgreSQLContainer` bean with `@ServiceConnection`, which starts - a PostgreSQL container and automatically registers the datasource properties. -- Declares a `KeycloakContainer` bean using the `quay.io/keycloak/keycloak:25.0` - image, imports the realm configuration file, and dynamically registers the JWT - issuer URI from the Keycloak container's auth server URL. - -## Write the test - -Create `ProductControllerTests.java`: - -```java -package com.testcontainers.products.api; - -import static io.restassured.RestAssured.given; -import static io.restassured.RestAssured.when; -import static java.util.Collections.singletonList; -import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; - -import com.fasterxml.jackson.annotation.JsonProperty; -import com.testcontainers.products.ContainersConfig; -import io.restassured.RestAssured; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.autoconfigure.security.oauth2.resource.OAuth2ResourceServerProperties; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.context.annotation.Import; -import org.springframework.http.HttpEntity; -import org.springframework.http.HttpHeaders; -import org.springframework.http.MediaType; -import org.springframework.util.LinkedMultiValueMap; -import org.springframework.util.MultiValueMap; -import org.springframework.web.client.RestTemplate; - -@SpringBootTest(webEnvironment = RANDOM_PORT) -@Import(ContainersConfig.class) -class ProductControllerTests { - - static final String GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials"; - static final String CLIENT_ID = "product-service"; - static final String CLIENT_SECRET = "jTJJqdzeCSt3DmypfHZa42vX8U9rQKZ9"; - - @LocalServerPort - private int port; - - @Autowired - OAuth2ResourceServerProperties oAuth2ResourceServerProperties; - - @BeforeEach - void setup() { - RestAssured.port = port; - } - - @Test - void shouldGetProductsWithoutAuthToken() { - when().get("/api/products").then().statusCode(200); - } - - @Test - void shouldGetUnauthorizedWhenCreateProductWithoutAuthToken() { - given() - .contentType("application/json") - .body( - """ - { - "title": "New Product", - "description": "Brand New Product" - } - """ - ) - .when() - .post("/api/products") - .then() - .statusCode(401); - } - - @Test - void shouldCreateProductWithAuthToken() { - String token = getToken(); - - given() - .header("Authorization", "Bearer " + token) - .contentType("application/json") - .body( - """ - { - "title": "New Product", - "description": "Brand New Product" - } - """ - ) - .when() - .post("/api/products") - .then() - .statusCode(201); - } - - private String getToken() { - RestTemplate restTemplate = new RestTemplate(); - HttpHeaders httpHeaders = new HttpHeaders(); - httpHeaders.setContentType(MediaType.APPLICATION_FORM_URLENCODED); - - MultiValueMap<String, String> map = new LinkedMultiValueMap<>(); - map.put("grant_type", singletonList(GRANT_TYPE_CLIENT_CREDENTIALS)); - map.put("client_id", singletonList(CLIENT_ID)); - map.put("client_secret", singletonList(CLIENT_SECRET)); - - String authServerUrl = - oAuth2ResourceServerProperties.getJwt().getIssuerUri() + - "/protocol/openid-connect/token"; - - var request = new HttpEntity<>(map, httpHeaders); - KeyCloakToken token = restTemplate.postForObject( - authServerUrl, - request, - KeyCloakToken.class - ); - - assert token != null; - return token.accessToken(); - } - - record KeyCloakToken(@JsonProperty("access_token") String accessToken) {} -} -``` - -Here's what the tests cover: - -- `shouldGetProductsWithoutAuthToken()` invokes `GET /api/products` without an - `Authorization` header. Because this endpoint is configured to permit - unauthenticated access, the response status code is 200. -- `shouldGetUnauthorizedWhenCreateProductWithoutAuthToken()` invokes the secured - `POST /api/products` endpoint without an `Authorization` header and asserts - the response status code is 401 (Unauthorized). -- `shouldCreateProductWithAuthToken()` first obtains an `access_token` using the - Client Credentials flow. It then includes the token as a Bearer token in the - `Authorization` header when invoking `POST /api/products` and asserts the - response status code is 201 (Created). - -The `getToken()` helper method requests an access token from the Keycloak token -endpoint using the client ID and client secret that were configured in the -exported realm. - -## Use Testcontainers for local development - -Spring Boot's Testcontainers support also works for local development. Create -`TestApplication.java` under `src/test/java`: - -```java -package com.testcontainers.products; - -import org.springframework.boot.SpringApplication; - -public class TestApplication { - - public static void main(String[] args) { - SpringApplication - .from(Application::main) - .with(ContainersConfig.class) - .run(args); - } -} -``` - -Run `TestApplication.java` from your IDE instead of the main `Application.java`. -It starts the containers defined in `ContainersConfig` and configures the -application to use the dynamically registered properties, so you don't have to -install or configure PostgreSQL and Keycloak manually. diff --git a/content/guides/testcontainers-java-lifecycle.md b/content/guides/testcontainers-java-lifecycle.md new file mode 100644 index 000000000000..2db26128fc9e --- /dev/null +++ b/content/guides/testcontainers-java-lifecycle.md @@ -0,0 +1,469 @@ +--- +title: Testcontainers container lifecycle management using JUnit 5 +linkTitle: Container lifecycle (Java) +description: Learn how to manage Testcontainers container lifecycle using JUnit 5 callbacks, extension annotations, and the singleton containers pattern. +keywords: testcontainers, java, testing, junit, lifecycle, singleton containers, postgresql +summary: | + Learn different approaches to manage container lifecycle with Testcontainers + using JUnit 5 lifecycle callbacks, extension annotations, and the singleton + containers pattern. +aliases: + - /guides/testcontainers-java-lifecycle/create-project/ + - /guides/testcontainers-java-lifecycle/extension-annotations/ + - /guides/testcontainers-java-lifecycle/lifecycle-callbacks/ + - /guides/testcontainers-java-lifecycle/singleton-containers/ +params: + tags: [testing] + time: 20 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-testcontainers-lifecycle --> + +In this guide, you will learn how to: + +- Start and stop containers using JUnit 5 lifecycle callbacks +- Manage containers using JUnit 5 extension annotations (`@Testcontainers` and `@Container`) +- Share containers across multiple test classes using the singleton containers pattern +- Avoid a common misconfiguration when combining extension annotations with singleton containers + +## Prerequisites + +- Java 17+ +- Your preferred IDE +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the project and business logic + +### Set up the project + +Create a Java project with Maven and add the required dependencies: + +```xml +<dependencies> + <dependency> + <groupId>org.postgresql</groupId> + <artifactId>postgresql</artifactId> + <version>42.7.3</version> + </dependency> + <dependency> + <groupId>ch.qos.logback</groupId> + <artifactId>logback-classic</artifactId> + <version>1.5.6</version> + </dependency> + <dependency> + <groupId>org.junit.jupiter</groupId> + <artifactId>junit-jupiter</artifactId> + <version>5.10.2</version> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.testcontainers</groupId> + <artifactId>testcontainers-junit-jupiter</artifactId> + <version>2.0.4</version> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.testcontainers</groupId> + <artifactId>testcontainers-postgresql</artifactId> + <version>2.0.4</version> + <scope>test</scope> + </dependency> +</dependencies> +``` + +### Create the business logic + +Create a `Customer` record: + +```java +package com.testcontainers.demo; + +public record Customer(Long id, String name) {} +``` + +Create a `CustomerService` class with methods to create, retrieve, and delete +customers: + +```java +package com.testcontainers.demo; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.util.ArrayList; +import java.util.List; +import java.util.Optional; + +public class CustomerService { + + private final String url; + private final String username; + private final String password; + + public CustomerService(String url, String username, String password) { + this.url = url; + this.username = username; + this.password = password; + createCustomersTableIfNotExists(); + } + + public void createCustomer(Customer customer) { + try (Connection conn = this.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + "insert into customers(id,name) values(?,?)" + ); + pstmt.setLong(1, customer.id()); + pstmt.setString(2, customer.name()); + pstmt.execute(); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + public List<Customer> getAllCustomers() { + List<Customer> customers = new ArrayList<>(); + try (Connection conn = this.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + "select id,name from customers" + ); + ResultSet rs = pstmt.executeQuery(); + while (rs.next()) { + long id = rs.getLong("id"); + String name = rs.getString("name"); + customers.add(new Customer(id, name)); + } + } catch (SQLException e) { + throw new RuntimeException(e); + } + return customers; + } + + public Optional<Customer> getCustomer(Long customerId) { + try (Connection conn = this.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + "select id,name from customers where id = ?" + ); + pstmt.setLong(1, customerId); + ResultSet rs = pstmt.executeQuery(); + if (rs.next()) { + long id = rs.getLong("id"); + String name = rs.getString("name"); + return Optional.of(new Customer(id, name)); + } + } catch (SQLException e) { + throw new RuntimeException(e); + } + return Optional.empty(); + } + + public void deleteAllCustomers() { + try (Connection conn = this.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement("delete from customers"); + pstmt.execute(); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + private void createCustomersTableIfNotExists() { + try (Connection conn = this.getConnection()) { + PreparedStatement pstmt = conn.prepareStatement( + """ + create table if not exists customers ( + id bigint not null, + name varchar not null, + primary key (id) + ) + """ + ); + pstmt.execute(); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + private Connection getConnection() { + try { + return DriverManager.getConnection(url, username, password); + } catch (Exception e) { + throw new RuntimeException(e); + } + } +} +``` + +## JUnit 5 lifecycle callbacks + +When testing with Testcontainers, you want to start the required containers +before executing any tests and remove them afterwards. You can use JUnit 5 +`@BeforeAll` and `@AfterAll` lifecycle callback methods for this: + +```java +package com.testcontainers.demo; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.List; +import java.util.Optional; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.testcontainers.postgresql.PostgreSQLContainer; + +class CustomerServiceWithLifeCycleCallbacksTest { + + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine" + ); + + CustomerService customerService; + + @BeforeAll + static void startContainers() { + postgres.start(); + } + + @AfterAll + static void stopContainers() { + postgres.stop(); + } + + @BeforeEach + void setUp() { + customerService = + new CustomerService( + postgres.getJdbcUrl(), + postgres.getUsername(), + postgres.getPassword() + ); + customerService.deleteAllCustomers(); + } + + @Test + void shouldCreateCustomer() { + customerService.createCustomer(new Customer(1L, "George")); + + Optional<Customer> customer = customerService.getCustomer(1L); + assertTrue(customer.isPresent()); + assertEquals(1L, customer.get().id()); + assertEquals("George", customer.get().name()); + } + + @Test + void shouldGetCustomers() { + customerService.createCustomer(new Customer(1L, "George")); + customerService.createCustomer(new Customer(2L, "John")); + + List<Customer> customers = customerService.getAllCustomers(); + assertEquals(2, customers.size()); + } +} +``` + +Here's what the code does: + +- `PostgreSQLContainer` is declared as a **static field**. The container starts + before all tests and stops after all tests in this class. +- `@BeforeAll` starts the container, `@AfterAll` stops it. +- `@BeforeEach` initializes `CustomerService` with the container's JDBC + parameters and deletes all rows to give each test a clean database. + +Key observations: + +- Because the container is a **static field**, it's shared across all test + methods in the class. You can declare it as a non-static field and use + `@BeforeEach`/`@AfterEach` to start a new container per test, but this + isn't recommended as it's resource-intensive. +- Even without explicitly stopping the container in `@AfterAll`, Testcontainers + uses the [Ryuk container](https://github.com/testcontainers/moby-ryuk) to + clean up containers automatically when the JVM exits. + +## JUnit 5 extension annotations + +The Testcontainers library provides a JUnit 5 extension that simplifies +starting and stopping containers using annotations. To use it, add the +`org.testcontainers:testcontainers-junit-jupiter` test dependency. + +```java +package com.testcontainers.demo; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.List; +import java.util.Optional; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.testcontainers.postgresql.PostgreSQLContainer; +import org.testcontainers.junit.jupiter.Container; +import org.testcontainers.junit.jupiter.Testcontainers; + +@Testcontainers +class CustomerServiceWithJUnit5ExtensionTest { + + @Container + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine" + ); + + CustomerService customerService; + + @BeforeEach + void setUp() { + customerService = + new CustomerService( + postgres.getJdbcUrl(), + postgres.getUsername(), + postgres.getPassword() + ); + customerService.deleteAllCustomers(); + } + + @Test + void shouldCreateCustomer() { + customerService.createCustomer(new Customer(1L, "George")); + + Optional<Customer> customer = customerService.getCustomer(1L); + assertTrue(customer.isPresent()); + assertEquals(1L, customer.get().id()); + assertEquals("George", customer.get().name()); + } + + @Test + void shouldGetCustomers() { + customerService.createCustomer(new Customer(1L, "George")); + customerService.createCustomer(new Customer(2L, "John")); + + List<Customer> customers = customerService.getAllCustomers(); + assertEquals(2, customers.size()); + } +} +``` + +Instead of manually starting and stopping the container in `@BeforeAll` and +`@AfterAll`, the `@Testcontainers` annotation on the class and the +`@Container` annotation on the field handle it automatically: + +- The extension finds all `@Container`-annotated fields. +- **Static fields** start once before all tests and stop after all tests. +- **Instance fields** start before each test and stop after each test (not + recommended — it's resource-intensive). + +## Singleton containers pattern + +As the number of test classes grows, starting containers for each class adds +up. The singleton containers pattern starts all required containers once in a +common base class and reuses them across all integration tests. + +### Define the base class + +Create an abstract base class that starts the containers in a static +initializer: + +```java +package com.testcontainers.demo; + +import org.testcontainers.postgresql.PostgreSQLContainer; +import org.testcontainers.kafka.ConfluentKafkaContainer; + +public abstract class AbstractIntegrationTest { + + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine"); + static ConfluentKafkaContainer kafka = new ConfluentKafkaContainer( + "confluentinc/cp-kafka:7.8.0"); + + static { + postgres.start(); + kafka.start(); + } +} +``` + +The containers start once when the class loads and Testcontainers uses the +[Ryuk container](https://github.com/testcontainers/moby-ryuk) to remove them +after the JVM exits. + +> [!TIP] +> Instead of starting containers sequentially, start them in parallel using +> `Startables.deepStart(postgres, kafka).join();` + +### Extend the base class + +Each test class inherits from the base class and reuses the same containers: + +```java +class ProductControllerTest extends AbstractIntegrationTest { + + ProductRepository productRepository; + + @BeforeEach + void setUp() { + productRepository = new ProductRepository(...); + productRepository.deleteAll(); + } + + @Test + void shouldGetAllProducts() { + // test logic using the shared postgres container + } +} +``` + +### Avoid a common misconfiguration + +A common mistake is combining singleton containers with the `@Testcontainers` +and `@Container` annotations: + +```java +// DON'T DO THIS — containers will stop after each test class +@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) +@Testcontainers +public abstract class AbstractIntegrationTest { + + @Container + static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>( + DockerImageName.parse("postgres:16-alpine")); + + @DynamicPropertySource + static void configureProperties(DynamicPropertyRegistry registry) { + registry.add("spring.datasource.url", postgres::getJdbcUrl); + registry.add("spring.datasource.username", postgres::getUsername); + registry.add("spring.datasource.password", postgres::getPassword); + } +} +``` + +The `@Testcontainers` extension stops containers at the end of **each test +class**. Subsequent test classes reuse the cached Spring context, but the +containers are already stopped — causing connection failures. + +Instead, use a static initializer or `@BeforeAll` to start the containers, +without the `@Testcontainers` and `@Container` annotations. + +### Summary + +- Use **JUnit 5 lifecycle callbacks** (`@BeforeAll`/`@AfterAll`) for + explicit control over container startup and shutdown. +- Use **extension annotations** (`@Testcontainers`/`@Container`) for less + boilerplate in single test classes. +- Use the **singleton containers pattern** (static initializer in a base class) + to share containers across multiple test classes. +- Don't mix singleton containers with `@Testcontainers`/`@Container` + annotations. + +### Further reading + +- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) +- [Testcontainers singleton containers pattern](https://java.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers) +- [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/) diff --git a/content/guides/testcontainers-java-lifecycle/_index.md b/content/guides/testcontainers-java-lifecycle/_index.md deleted file mode 100644 index b24f7928ae93..000000000000 --- a/content/guides/testcontainers-java-lifecycle/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Testcontainers container lifecycle management using JUnit 5 -linkTitle: Container lifecycle (Java) -description: Learn how to manage Testcontainers container lifecycle using JUnit 5 callbacks, extension annotations, and the singleton containers pattern. -keywords: testcontainers, java, testing, junit, lifecycle, singleton containers, postgresql -summary: | - Learn different approaches to manage container lifecycle with Testcontainers - using JUnit 5 lifecycle callbacks, extension annotations, and the singleton - containers pattern. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testcontainers-lifecycle --> - -In this guide, you will learn how to: - -- Start and stop containers using JUnit 5 lifecycle callbacks -- Manage containers using JUnit 5 extension annotations (`@Testcontainers` and `@Container`) -- Share containers across multiple test classes using the singleton containers pattern -- Avoid a common misconfiguration when combining extension annotations with singleton containers - -## Prerequisites - -- Java 17+ -- Your preferred IDE -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-lifecycle/create-project.md b/content/guides/testcontainers-java-lifecycle/create-project.md deleted file mode 100644 index 6ca63e724beb..000000000000 --- a/content/guides/testcontainers-java-lifecycle/create-project.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Create the project and business logic -linkTitle: Create the project -description: Set up a Java project with a PostgreSQL-backed customer service for lifecycle testing. -keywords: testcontainers, java, lifecycle, postgresql, junit, project setup -weight: 10 ---- - -## Set up the project - -Create a Java project with Maven and add the required dependencies: - -```xml -<dependencies> - <dependency> - <groupId>org.postgresql</groupId> - <artifactId>postgresql</artifactId> - <version>42.7.3</version> - </dependency> - <dependency> - <groupId>ch.qos.logback</groupId> - <artifactId>logback-classic</artifactId> - <version>1.5.6</version> - </dependency> - <dependency> - <groupId>org.junit.jupiter</groupId> - <artifactId>junit-jupiter</artifactId> - <version>5.10.2</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <version>2.0.4</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-postgresql</artifactId> - <version>2.0.4</version> - <scope>test</scope> - </dependency> -</dependencies> -``` - -## Create the business logic - -Create a `Customer` record: - -```java -package com.testcontainers.demo; - -public record Customer(Long id, String name) {} -``` - -Create a `CustomerService` class with methods to create, retrieve, and delete -customers: - -```java -package com.testcontainers.demo; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.PreparedStatement; -import java.sql.ResultSet; -import java.sql.SQLException; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; - -public class CustomerService { - - private final String url; - private final String username; - private final String password; - - public CustomerService(String url, String username, String password) { - this.url = url; - this.username = username; - this.password = password; - createCustomersTableIfNotExists(); - } - - public void createCustomer(Customer customer) { - try (Connection conn = this.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - "insert into customers(id,name) values(?,?)" - ); - pstmt.setLong(1, customer.id()); - pstmt.setString(2, customer.name()); - pstmt.execute(); - } catch (SQLException e) { - throw new RuntimeException(e); - } - } - - public List<Customer> getAllCustomers() { - List<Customer> customers = new ArrayList<>(); - try (Connection conn = this.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - "select id,name from customers" - ); - ResultSet rs = pstmt.executeQuery(); - while (rs.next()) { - long id = rs.getLong("id"); - String name = rs.getString("name"); - customers.add(new Customer(id, name)); - } - } catch (SQLException e) { - throw new RuntimeException(e); - } - return customers; - } - - public Optional<Customer> getCustomer(Long customerId) { - try (Connection conn = this.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - "select id,name from customers where id = ?" - ); - pstmt.setLong(1, customerId); - ResultSet rs = pstmt.executeQuery(); - if (rs.next()) { - long id = rs.getLong("id"); - String name = rs.getString("name"); - return Optional.of(new Customer(id, name)); - } - } catch (SQLException e) { - throw new RuntimeException(e); - } - return Optional.empty(); - } - - public void deleteAllCustomers() { - try (Connection conn = this.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement("delete from customers"); - pstmt.execute(); - } catch (SQLException e) { - throw new RuntimeException(e); - } - } - - private void createCustomersTableIfNotExists() { - try (Connection conn = this.getConnection()) { - PreparedStatement pstmt = conn.prepareStatement( - """ - create table if not exists customers ( - id bigint not null, - name varchar not null, - primary key (id) - ) - """ - ); - pstmt.execute(); - } catch (SQLException e) { - throw new RuntimeException(e); - } - } - - private Connection getConnection() { - try { - return DriverManager.getConnection(url, username, password); - } catch (Exception e) { - throw new RuntimeException(e); - } - } -} -``` diff --git a/content/guides/testcontainers-java-lifecycle/extension-annotations.md b/content/guides/testcontainers-java-lifecycle/extension-annotations.md deleted file mode 100644 index 790965954136..000000000000 --- a/content/guides/testcontainers-java-lifecycle/extension-annotations.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: JUnit 5 extension annotations -linkTitle: Extension annotations -description: Manage Testcontainers container lifecycle using @Testcontainers and @Container annotations. -keywords: testcontainers, java, lifecycle, junit, annotations, container management -weight: 30 ---- - -The Testcontainers library provides a JUnit 5 extension that simplifies -starting and stopping containers using annotations. To use it, add the -`org.testcontainers:testcontainers-junit-jupiter` test dependency. - -```java -package com.testcontainers.demo; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertTrue; - -import java.util.List; -import java.util.Optional; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.testcontainers.postgresql.PostgreSQLContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; - -@Testcontainers -class CustomerServiceWithJUnit5ExtensionTest { - - @Container - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ); - - CustomerService customerService; - - @BeforeEach - void setUp() { - customerService = - new CustomerService( - postgres.getJdbcUrl(), - postgres.getUsername(), - postgres.getPassword() - ); - customerService.deleteAllCustomers(); - } - - @Test - void shouldCreateCustomer() { - customerService.createCustomer(new Customer(1L, "George")); - - Optional<Customer> customer = customerService.getCustomer(1L); - assertTrue(customer.isPresent()); - assertEquals(1L, customer.get().id()); - assertEquals("George", customer.get().name()); - } - - @Test - void shouldGetCustomers() { - customerService.createCustomer(new Customer(1L, "George")); - customerService.createCustomer(new Customer(2L, "John")); - - List<Customer> customers = customerService.getAllCustomers(); - assertEquals(2, customers.size()); - } -} -``` - -Instead of manually starting and stopping the container in `@BeforeAll` and -`@AfterAll`, the `@Testcontainers` annotation on the class and the -`@Container` annotation on the field handle it automatically: - -- The extension finds all `@Container`-annotated fields. -- **Static fields** start once before all tests and stop after all tests. -- **Instance fields** start before each test and stop after each test (not - recommended — it's resource-intensive). diff --git a/content/guides/testcontainers-java-lifecycle/lifecycle-callbacks.md b/content/guides/testcontainers-java-lifecycle/lifecycle-callbacks.md deleted file mode 100644 index 2aa4207c94f4..000000000000 --- a/content/guides/testcontainers-java-lifecycle/lifecycle-callbacks.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: JUnit 5 lifecycle callbacks -linkTitle: Lifecycle callbacks -description: Manage Testcontainers container lifecycle using JUnit 5 @BeforeAll and @AfterAll callbacks. -keywords: testcontainers, java, lifecycle, junit, callbacks, beforeall, afterall -weight: 20 ---- - -When testing with Testcontainers, you want to start the required containers -before executing any tests and remove them afterwards. You can use JUnit 5 -`@BeforeAll` and `@AfterAll` lifecycle callback methods for this: - -```java -package com.testcontainers.demo; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertTrue; - -import java.util.List; -import java.util.Optional; -import org.junit.jupiter.api.AfterAll; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.testcontainers.postgresql.PostgreSQLContainer; - -class CustomerServiceWithLifeCycleCallbacksTest { - - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ); - - CustomerService customerService; - - @BeforeAll - static void startContainers() { - postgres.start(); - } - - @AfterAll - static void stopContainers() { - postgres.stop(); - } - - @BeforeEach - void setUp() { - customerService = - new CustomerService( - postgres.getJdbcUrl(), - postgres.getUsername(), - postgres.getPassword() - ); - customerService.deleteAllCustomers(); - } - - @Test - void shouldCreateCustomer() { - customerService.createCustomer(new Customer(1L, "George")); - - Optional<Customer> customer = customerService.getCustomer(1L); - assertTrue(customer.isPresent()); - assertEquals(1L, customer.get().id()); - assertEquals("George", customer.get().name()); - } - - @Test - void shouldGetCustomers() { - customerService.createCustomer(new Customer(1L, "George")); - customerService.createCustomer(new Customer(2L, "John")); - - List<Customer> customers = customerService.getAllCustomers(); - assertEquals(2, customers.size()); - } -} -``` - -Here's what the code does: - -- `PostgreSQLContainer` is declared as a **static field**. The container starts - before all tests and stops after all tests in this class. -- `@BeforeAll` starts the container, `@AfterAll` stops it. -- `@BeforeEach` initializes `CustomerService` with the container's JDBC - parameters and deletes all rows to give each test a clean database. - -Key observations: - -- Because the container is a **static field**, it's shared across all test - methods in the class. You can declare it as a non-static field and use - `@BeforeEach`/`@AfterEach` to start a new container per test, but this - isn't recommended as it's resource-intensive. -- Even without explicitly stopping the container in `@AfterAll`, Testcontainers - uses the [Ryuk container](https://github.com/testcontainers/moby-ryuk) to - clean up containers automatically when the JVM exits. diff --git a/content/guides/testcontainers-java-lifecycle/singleton-containers.md b/content/guides/testcontainers-java-lifecycle/singleton-containers.md deleted file mode 100644 index 58f05b3e2e46..000000000000 --- a/content/guides/testcontainers-java-lifecycle/singleton-containers.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Singleton containers pattern -linkTitle: Singleton containers -description: Share containers across multiple test classes using the singleton containers pattern. -keywords: testcontainers, java, lifecycle, singleton, container reuse, junit -weight: 40 ---- - -As the number of test classes grows, starting containers for each class adds -up. The singleton containers pattern starts all required containers once in a -common base class and reuses them across all integration tests. - -## Define the base class - -Create an abstract base class that starts the containers in a static -initializer: - -```java -package com.testcontainers.demo; - -import org.testcontainers.postgresql.PostgreSQLContainer; -import org.testcontainers.kafka.ConfluentKafkaContainer; - -public abstract class AbstractIntegrationTest { - - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine"); - static ConfluentKafkaContainer kafka = new ConfluentKafkaContainer( - "confluentinc/cp-kafka:7.8.0"); - - static { - postgres.start(); - kafka.start(); - } -} -``` - -The containers start once when the class loads and Testcontainers uses the -[Ryuk container](https://github.com/testcontainers/moby-ryuk) to remove them -after the JVM exits. - -> [!TIP] -> Instead of starting containers sequentially, start them in parallel using -> `Startables.deepStart(postgres, kafka).join();` - -## Extend the base class - -Each test class inherits from the base class and reuses the same containers: - -```java -class ProductControllerTest extends AbstractIntegrationTest { - - ProductRepository productRepository; - - @BeforeEach - void setUp() { - productRepository = new ProductRepository(...); - productRepository.deleteAll(); - } - - @Test - void shouldGetAllProducts() { - // test logic using the shared postgres container - } -} -``` - -## Avoid a common misconfiguration - -A common mistake is combining singleton containers with the `@Testcontainers` -and `@Container` annotations: - -```java -// DON'T DO THIS — containers will stop after each test class -@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) -@Testcontainers -public abstract class AbstractIntegrationTest { - - @Container - static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>( - DockerImageName.parse("postgres:16-alpine")); - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("spring.datasource.url", postgres::getJdbcUrl); - registry.add("spring.datasource.username", postgres::getUsername); - registry.add("spring.datasource.password", postgres::getPassword); - } -} -``` - -The `@Testcontainers` extension stops containers at the end of **each test -class**. Subsequent test classes reuse the cached Spring context, but the -containers are already stopped — causing connection failures. - -Instead, use a static initializer or `@BeforeAll` to start the containers, -without the `@Testcontainers` and `@Container` annotations. - -## Summary - -- Use **JUnit 5 lifecycle callbacks** (`@BeforeAll`/`@AfterAll`) for - explicit control over container startup and shutdown. -- Use **extension annotations** (`@Testcontainers`/`@Container`) for less - boilerplate in single test classes. -- Use the **singleton containers pattern** (static initializer in a base class) - to share containers across multiple test classes. -- Don't mix singleton containers with `@Testcontainers`/`@Container` - annotations. - -## Further reading - -- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) -- [Testcontainers singleton containers pattern](https://java.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers) -- [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/) diff --git a/content/guides/testcontainers-java-micronaut-kafka/_index.md b/content/guides/testcontainers-java-micronaut-kafka/_index.md deleted file mode 100644 index 984349bc9c1f..000000000000 --- a/content/guides/testcontainers-java-micronaut-kafka/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Testing Micronaut Kafka Listener using Testcontainers -linkTitle: Micronaut Kafka -description: Learn how to test a Micronaut Kafka listener using Testcontainers with Kafka and MySQL modules. -keywords: testcontainers, java, micronaut, testing, kafka, mysql, jpa, awaitility -summary: | - Learn how to create a Micronaut application with a Kafka listener that persists data in MySQL, - then test it using Testcontainers Kafka and MySQL modules with Awaitility. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-micronaut-kafka-listener --> - -In this guide, you'll learn how to: - -- Create a Micronaut application with Kafka integration -- Implement a Kafka listener and persist data in a MySQL database -- Test the Kafka listener using Testcontainers and Awaitility - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-micronaut-kafka/create-project.md b/content/guides/testcontainers-java-micronaut-kafka/create-project.md deleted file mode 100644 index bfad0bb92828..000000000000 --- a/content/guides/testcontainers-java-micronaut-kafka/create-project.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: Create the Micronaut project -linkTitle: Create the project -description: Set up a Micronaut project with Kafka, Micronaut Data JPA, and MySQL. -keywords: testcontainers, java, micronaut, kafka, mysql, project setup -weight: 10 ---- - -## Set up the project - -Create a Micronaut project from [Micronaut Launch](https://micronaut.io/launch) by -selecting the **kafka**, **data-jpa**, **mysql**, **awaitility**, **assertj**, and -**testcontainers** features. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-micronaut-kafka-listener). - -You'll use the [Awaitility](http://www.awaitility.org/) library to assert the -expectations of an asynchronous process flow. - -The key dependencies in `pom.xml` are: - -```xml -<parent> - <groupId>io.micronaut.platform</groupId> - <artifactId>micronaut-parent</artifactId> - <version>4.1.4</version> -</parent> -<dependencies> - <dependency> - <groupId>io.micronaut.data</groupId> - <artifactId>micronaut-data-hibernate-jpa</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut.kafka</groupId> - <artifactId>micronaut-kafka</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut.serde</groupId> - <artifactId>micronaut-serde-jackson</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut.sql</groupId> - <artifactId>micronaut-jdbc-hikari</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>mysql</groupId> - <artifactId>mysql-connector-java</artifactId> - <scope>runtime</scope> - </dependency> - <dependency> - <groupId>org.awaitility</groupId> - <artifactId>awaitility</artifactId> - <version>4.2.0</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-kafka</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-mysql</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -The Micronaut parent POM manages the Testcontainers BOM, so you don't need to -specify versions for Testcontainers modules individually. - -## Create the JPA entity - -The application listens to a topic called `product-price-changes`. When a -message arrives, it extracts the product code and price from the event payload -and updates the price for that product in the MySQL database. - -Create `Product.java`: - -```java -package com.testcontainers.demo; - -import jakarta.persistence.Column; -import jakarta.persistence.Entity; -import jakarta.persistence.GeneratedValue; -import jakarta.persistence.GenerationType; -import jakarta.persistence.Id; -import jakarta.persistence.Table; -import java.math.BigDecimal; - -@Entity -@Table(name = "products") -public class Product { - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - private Long id; - - @Column(nullable = false, unique = true) - private String code; - - @Column(nullable = false) - private String name; - - @Column(nullable = false) - private BigDecimal price; - - public Product() {} - - public Product(Long id, String code, String name, BigDecimal price) { - this.id = id; - this.code = code; - this.name = name; - this.price = price; - } - - public Long getId() { - return id; - } - - public void setId(Long id) { - this.id = id; - } - - public String getCode() { - return code; - } - - public void setCode(String code) { - this.code = code; - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - - public BigDecimal getPrice() { - return price; - } - - public void setPrice(BigDecimal price) { - this.price = price; - } -} -``` - -## Create the Micronaut Data JPA repository - -Create a repository interface for the `Product` entity with a method to find a -product by code and a method to update the price for a given product code: - -```java -package com.testcontainers.demo; - -import io.micronaut.data.annotation.Query; -import io.micronaut.data.annotation.Repository; -import io.micronaut.data.jpa.repository.JpaRepository; -import java.math.BigDecimal; -import java.util.Optional; - -@Repository -public interface ProductRepository extends JpaRepository<Product, Long> { - - Optional<Product> findByCode(String code); - - @Query("update Product p set p.price = :price where p.code = :productCode") - void updateProductPrice(String productCode, BigDecimal price); -} -``` - -Unlike Spring Data JPA, Micronaut Data uses compile-time annotation processing -to implement repository methods, avoiding runtime reflection. - -## Create the event payload - -Create a record named `ProductPriceChangedEvent` that represents the structure -of the event payload received from the Kafka topic: - -```java -package com.testcontainers.demo; - -import io.micronaut.serde.annotation.Serdeable; -import java.math.BigDecimal; - -@Serdeable -public record ProductPriceChangedEvent(String productCode, BigDecimal price) {} -``` - -The `@Serdeable` annotation tells Micronaut Serialization that this type can be -serialized and deserialized. - -The sender and receiver agree on the following JSON format: - -```json -{ - "productCode": "P100", - "price": 25.0 -} -``` - -## Implement the Kafka listener - -Create `ProductPriceChangedEventHandler.java`, which handles messages from the -`product-price-changes` topic and updates the product price in the database: - -```java -package com.testcontainers.demo; - -import static io.micronaut.configuration.kafka.annotation.OffsetReset.EARLIEST; - -import io.micronaut.configuration.kafka.annotation.KafkaListener; -import io.micronaut.configuration.kafka.annotation.Topic; -import jakarta.inject.Singleton; -import jakarta.transaction.Transactional; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -@Singleton -@Transactional -class ProductPriceChangedEventHandler { - - private static final Logger LOG = LoggerFactory.getLogger(ProductPriceChangedEventHandler.class); - - private final ProductRepository productRepository; - - ProductPriceChangedEventHandler(ProductRepository productRepository) { - this.productRepository = productRepository; - } - - @Topic("product-price-changes") - @KafkaListener(offsetReset = EARLIEST, groupId = "demo") - public void handle(ProductPriceChangedEvent event) { - LOG.info("Received a ProductPriceChangedEvent with productCode:{}: ", event.productCode()); - productRepository.updateProductPrice(event.productCode(), event.price()); - } -} -``` - -Key details: - -- The `@KafkaListener` annotation marks this class as a Kafka message listener. - Setting `offsetReset` to `EARLIEST` makes the listener start consuming - messages from the beginning of the partition, which is useful during testing. -- The `@Topic` annotation specifies which topic to subscribe to. -- Micronaut handles JSON deserialization of the `ProductPriceChangedEvent` - automatically using Micronaut Serialization. - -## Configure the datasource - -Add the following properties to `src/main/resources/application.properties`: - -```properties -micronaut.application.name=tc-guide-testing-micronaut-kafka-listener -datasources.default.db-type=mysql -datasources.default.dialect=MYSQL -jpa.default.properties.hibernate.hbm2ddl.auto=update -jpa.default.entity-scan.packages=com.testcontainers.demo -datasources.default.driver-class-name=com.mysql.cj.jdbc.Driver -``` - -Hibernate's `hbm2ddl.auto=update` creates and updates the database schema -automatically. For testing, you'll override this to `create-drop` in the test -properties file. - -Create `src/test/resources/application-test.properties`: - -```properties -jpa.default.properties.hibernate.hbm2ddl.auto=create-drop -``` diff --git a/content/guides/testcontainers-java-micronaut-kafka/run-tests.md b/content/guides/testcontainers-java-micronaut-kafka/run-tests.md deleted file mode 100644 index c2f8fe3db30f..000000000000 --- a/content/guides/testcontainers-java-micronaut-kafka/run-tests.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Micronaut Kafka integration tests and explore next steps. -keywords: testcontainers, java, micronaut, kafka, mysql, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the Kafka and MySQL Docker containers start and all tests pass. -After the tests finish, the containers stop and are removed automatically. - -## Summary - -Testing with real Kafka and MySQL instances gives you more confidence in the -correctness of your code than mocks or embedded alternatives. The -Testcontainers library manages the container lifecycle so that your integration -tests run against the same services you use in production. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testing REST API integrations in Micronaut apps using WireMock](/guides/testcontainers-java-micronaut-wiremock/) -- [Testing Spring Boot Kafka Listener using Testcontainers](/guides/testcontainers-java-spring-boot-kafka/) -- [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/) -- [Awaitility](http://www.awaitility.org/) -- [Testcontainers Kafka module](https://java.testcontainers.org/modules/kafka/) -- [Testcontainers MySQL module](https://java.testcontainers.org/modules/databases/mysql/) diff --git a/content/guides/testcontainers-java-micronaut-kafka/write-tests.md b/content/guides/testcontainers-java-micronaut-kafka/write-tests.md deleted file mode 100644 index 87bcd02c693e..000000000000 --- a/content/guides/testcontainers-java-micronaut-kafka/write-tests.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test the Micronaut Kafka listener using Testcontainers Kafka and MySQL modules with Awaitility. -keywords: testcontainers, java, micronaut, kafka, mysql, awaitility, integration testing -weight: 20 ---- - -To test the Kafka listener, you need a running Kafka broker and a MySQL -database, plus a started Micronaut application context. Testcontainers spins up -both services in Docker containers and the `TestPropertyProvider` interface -connects them to Micronaut. - -## Create a Kafka client for testing - -First, create a `@KafkaClient` interface to publish events in the test: - -```java -package com.testcontainers.demo; - -import io.micronaut.configuration.kafka.annotation.KafkaClient; -import io.micronaut.configuration.kafka.annotation.KafkaKey; -import io.micronaut.configuration.kafka.annotation.Topic; - -@KafkaClient -public interface ProductPriceChangesClient { - - @Topic("product-price-changes") - void send(@KafkaKey String productCode, ProductPriceChangedEvent event); -} -``` - -Key details: - -- The `@KafkaClient` annotation designates this interface as a Kafka producer. -- The `@Topic` annotation specifies the target topic. -- The `@KafkaKey` annotation marks the parameter used as the Kafka message key. - If no such parameter exists, Micronaut sends the record with a null key. - -## Write the test - -Create `ProductPriceChangedEventHandlerTest.java`: - -```java -package com.testcontainers.demo; - -import static java.util.concurrent.TimeUnit.SECONDS; -import static org.assertj.core.api.Assertions.assertThat; -import static org.awaitility.Awaitility.await; - -import io.micronaut.context.annotation.Property; -import io.micronaut.core.annotation.NonNull; -import io.micronaut.test.extensions.junit5.annotation.MicronautTest; -import io.micronaut.test.support.TestPropertyProvider; -import java.math.BigDecimal; -import java.time.Duration; -import java.util.Collections; -import java.util.Map; -import java.util.Optional; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.TestInstance; -import org.testcontainers.kafka.ConfluentKafkaContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; - -@MicronautTest(transactional = false) -@Property(name = "datasources.default.driver-class-name", value = "org.testcontainers.jdbc.ContainerDatabaseDriver") -@Property(name = "datasources.default.url", value = "jdbc:tc:mysql:8.0.32:///db") -@Testcontainers(disabledWithoutDocker = true) -@TestInstance(TestInstance.Lifecycle.PER_CLASS) -class ProductPriceChangedEventHandlerTest implements TestPropertyProvider { - - @Container - static final ConfluentKafkaContainer kafka = new ConfluentKafkaContainer("confluentinc/cp-kafka:7.8.0"); - - @Override - public @NonNull Map<String, String> getProperties() { - if (!kafka.isRunning()) { - kafka.start(); - } - return Collections.singletonMap("kafka.bootstrap.servers", kafka.getBootstrapServers()); - } - - @Test - void shouldHandleProductPriceChangedEvent( - ProductPriceChangesClient productPriceChangesClient, ProductRepository productRepository) { - Product product = new Product(null, "P100", "Product One", BigDecimal.TEN); - Long id = productRepository.save(product).getId(); - - ProductPriceChangedEvent event = new ProductPriceChangedEvent("P100", new BigDecimal("14.50")); - - productPriceChangesClient.send(event.productCode(), event); - - await().pollInterval(Duration.ofSeconds(3)).atMost(10, SECONDS).untilAsserted(() -> { - Optional<Product> optionalProduct = productRepository.findByCode("P100"); - assertThat(optionalProduct).isPresent(); - assertThat(optionalProduct.get().getCode()).isEqualTo("P100"); - assertThat(optionalProduct.get().getPrice()).isEqualTo(new BigDecimal("14.50")); - }); - - productRepository.deleteById(id); - } -} -``` - -Here's what the test does: - -- `@MicronautTest` initializes the Micronaut application context and the - embedded server. Setting `transactional` to `false` prevents each test method - from running inside a rolled-back transaction, which is necessary because the - Kafka listener processes messages in a separate thread. -- The `@Property` annotations override the datasource driver and URL to use the - Testcontainers special JDBC URL (`jdbc:tc:mysql:8.0.32:///db`). This spins up - a MySQL container and configures it as the datasource automatically. -- `@Testcontainers` and `@Container` manage the Kafka container lifecycle. - The `TestPropertyProvider` interface registers the Kafka bootstrap servers - with Micronaut so that the producer and consumer connect to the test container. -- `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` creates a single test - instance for all test methods, which is required when implementing - `TestPropertyProvider`. -- The test creates a `Product` record in the database, then sends a - `ProductPriceChangedEvent` to the `product-price-changes` topic using the - `ProductPriceChangesClient`. -- Because Kafka message processing is asynchronous, the test uses - [Awaitility](http://www.awaitility.org/) to poll every 3 seconds (up to a - maximum of 10 seconds) until the product price in the database matches the - expected value. diff --git a/content/guides/testcontainers-java-micronaut-wiremock/_index.md b/content/guides/testcontainers-java-micronaut-wiremock/_index.md deleted file mode 100644 index 03923c238572..000000000000 --- a/content/guides/testcontainers-java-micronaut-wiremock/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Testing REST API integrations in Micronaut apps using WireMock -linkTitle: Micronaut WireMock -description: Learn how to test REST API integrations in a Micronaut application using the Testcontainers WireMock module. -keywords: testcontainers, java, micronaut, testing, wiremock, rest api -summary: | - Learn how to create a Micronaut application that integrates with - external REST APIs, then test those integrations using WireMock - and the Testcontainers WireMock module. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-in-micronaut-apps-using-wiremock --> - -In this guide, you'll learn how to: - -- Create a Micronaut application that talks to external REST APIs -- Test external API integrations using WireMock -- Use the Testcontainers WireMock module to run WireMock as a Docker container - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-micronaut-wiremock/create-project.md b/content/guides/testcontainers-java-micronaut-wiremock/create-project.md deleted file mode 100644 index 8b4535858e30..000000000000 --- a/content/guides/testcontainers-java-micronaut-wiremock/create-project.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Create the Micronaut project -linkTitle: Create the project -description: Set up a Micronaut project with an external REST API integration using declarative HTTP clients. -keywords: testcontainers, java, micronaut, wiremock, rest api, project setup -weight: 10 ---- - -## Set up the project - -Create a Micronaut project from [Micronaut Launch](https://micronaut.io/launch) -by selecting the **http-client**, **micronaut-test-rest-assured**, and -**testcontainers** features. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-in-micronaut-apps-using-wiremock). - -After generating the project, add the **WireMock** and **Testcontainers -WireMock** libraries as test dependencies. The key dependencies in `pom.xml` -are: - -```xml -<parent> - <groupId>io.micronaut.platform</groupId> - <artifactId>micronaut-parent</artifactId> - <version>4.1.2</version> -</parent> - -<properties> - <jdk.version>17</jdk.version> - <micronaut.version>4.1.2</micronaut.version> - <micronaut.runtime>netty</micronaut.runtime> -</properties> - -<repositories> - <repository> - <id>jitpack.io</id> - <url>https://jitpack.io</url> - </repository> -</repositories> - -<dependencies> - <dependency> - <groupId>io.micronaut</groupId> - <artifactId>micronaut-http-client</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut</groupId> - <artifactId>micronaut-http-server-netty</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut.serde</groupId> - <artifactId>micronaut-serde-jackson</artifactId> - <scope>compile</scope> - </dependency> - <dependency> - <groupId>io.micronaut.test</groupId> - <artifactId>micronaut-test-junit5</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.micronaut.test</groupId> - <artifactId>micronaut-test-rest-assured</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.wiremock</groupId> - <artifactId>wiremock-standalone</artifactId> - <version>3.2.0</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.wiremock.integrations.testcontainers</groupId> - <artifactId>wiremock-testcontainers-module</artifactId> - <version>1.0-alpha-13</version> - <scope>test</scope> - </dependency> -</dependencies> -``` - -This guide builds an application that manages video albums. A third-party REST -API handles photo assets. For demonstration purposes, the application uses the -publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API -as a photo service. - -The application exposes a `GET /api/albums/{albumId}` endpoint that calls the -photo service to fetch photos for a given album. -[WireMock](https://wiremock.org/) is a tool for building mock APIs. -Testcontainers provides a -[WireMock module](https://testcontainers.com/modules/wiremock/) that runs -WireMock as a Docker container. - -## Create the Album and Photo models - -Create `Album.java` using Java records. Annotate both records with `@Serdeable` -to allow serialization and deserialization: - -```java -package com.testcontainers.demo; - -import io.micronaut.serde.annotation.Serdeable; -import java.util.List; - -@Serdeable -public record Album(Long albumId, List<Photo> photos) {} - -@Serdeable -record Photo(Long id, String title, String url, String thumbnailUrl) {} -``` - -## Create the PhotoServiceClient - -Micronaut provides -[declarative HTTP client](https://docs.micronaut.io/latest/guide/#httpClient) -support. Create an interface with a method that fetches photos for a given album -ID: - -```java -package com.testcontainers.demo; - -import io.micronaut.http.annotation.Get; -import io.micronaut.http.annotation.PathVariable; -import io.micronaut.http.client.annotation.Client; -import java.util.List; - -@Client(id = "photosapi") -interface PhotoServiceClient { - - @Get("/albums/{albumId}/photos") - List<Photo> getPhotos(@PathVariable Long albumId); -} -``` - -The `@Client(id = "photosapi")` annotation ties this client to a named -configuration. Add the following property to -`src/main/resources/application.properties` to set the base URL: - -```properties -micronaut.http.services.photosapi.url=https://jsonplaceholder.typicode.com -``` - -## Create the REST API endpoint - -Create `AlbumController.java`: - -```java -package com.testcontainers.demo; - -import static io.micronaut.scheduling.TaskExecutors.BLOCKING; - -import io.micronaut.http.annotation.Controller; -import io.micronaut.http.annotation.Get; -import io.micronaut.http.annotation.PathVariable; -import io.micronaut.scheduling.annotation.ExecuteOn; - -@Controller("/api") -class AlbumController { - - private final PhotoServiceClient photoServiceClient; - - AlbumController(PhotoServiceClient photoServiceClient) { - this.photoServiceClient = photoServiceClient; - } - - @ExecuteOn(BLOCKING) - @Get("/albums/{albumId}") - public Album getAlbumById(@PathVariable Long albumId) { - return new Album(albumId, photoServiceClient.getPhotos(albumId)); - } -} -``` - -Here's what this controller does: - -- `@Controller("/api")` maps the controller to the `/api` path. -- Constructor injection provides a `PhotoServiceClient` bean. -- `@ExecuteOn(BLOCKING)` offloads blocking I/O to a separate thread pool so it - doesn't block the event loop. -- `@Get("/albums/{albumId}")` maps the `getAlbumById()` method to an HTTP GET - request. - -This endpoint calls the photo service for a given album ID and returns a -response like: - -```json -{ - "albumId": 1, - "photos": [ - { - "id": 51, - "title": "non sunt voluptatem placeat consequuntur rem incidunt", - "url": "https://via.placeholder.com/600/8e973b", - "thumbnailUrl": "https://via.placeholder.com/150/8e973b" - }, - { - "id": 52, - "title": "eveniet pariatur quia nobis reiciendis laboriosam ea", - "url": "https://via.placeholder.com/600/121fa4", - "thumbnailUrl": "https://via.placeholder.com/150/121fa4" - } - ] -} -``` diff --git a/content/guides/testcontainers-java-micronaut-wiremock/run-tests.md b/content/guides/testcontainers-java-micronaut-wiremock/run-tests.md deleted file mode 100644 index a59c6720f779..000000000000 --- a/content/guides/testcontainers-java-micronaut-wiremock/run-tests.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers WireMock integration tests and explore next steps. -keywords: testcontainers, java, micronaut, wiremock, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the WireMock Docker container start in the console output. It -acts as the photo service, serving mock responses based on the configured -expectations. All tests should pass. - -## Summary - -You built a Micronaut application that integrates with an external REST API -using declarative HTTP clients, then tested that integration using WireMock and -the Testcontainers WireMock module. Testing at the HTTP protocol level instead -of mocking Java methods lets you catch serialization issues and simulate -realistic failure scenarios. - -> [!TIP] -> Testcontainers WireMock modules are available for Go and Python as well. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) -- [WireMock documentation](https://wiremock.org/docs/) -- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) -- [Testing REST API integrations in Spring Boot using WireMock](/guides/testcontainers-java-wiremock/) diff --git a/content/guides/testcontainers-java-micronaut-wiremock/write-tests.md b/content/guides/testcontainers-java-micronaut-wiremock/write-tests.md deleted file mode 100644 index 36b9f9ddfe70..000000000000 --- a/content/guides/testcontainers-java-micronaut-wiremock/write-tests.md +++ /dev/null @@ -1,392 +0,0 @@ ---- -title: Write tests with WireMock and Testcontainers -linkTitle: Write tests -description: Test external REST API integrations using WireMock and the Testcontainers WireMock module. -keywords: testcontainers, java, micronaut, wiremock, rest api, integration testing -weight: 20 ---- - -Mocking external API interactions at the HTTP protocol level, rather than -mocking Java methods, lets you verify marshalling and unmarshalling behavior and -simulate network issues. - -## Test with WireMock's JUnit 5 extension - -The first approach uses WireMock's `WireMockExtension` to start an in-process -WireMock server on a dynamic port. - -Create `AlbumControllerTest.java`: - -```java -package com.testcontainers.demo; - -import static com.github.tomakehurst.wiremock.client.WireMock.aResponse; -import static com.github.tomakehurst.wiremock.client.WireMock.urlMatching; -import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig; -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; - -import com.github.tomakehurst.wiremock.client.WireMock; -import com.github.tomakehurst.wiremock.junit5.WireMockExtension; -import io.micronaut.context.ApplicationContext; -import io.micronaut.http.MediaType; -import io.micronaut.runtime.server.EmbeddedServer; -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import java.util.Collections; -import java.util.Map; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.extension.RegisterExtension; - -class AlbumControllerTest { - - @RegisterExtension - static WireMockExtension wireMock = WireMockExtension.newInstance() - .options(wireMockConfig().dynamicPort()) - .build(); - - private Map<String, Object> getProperties() { - return Collections.singletonMap("micronaut.http.services.photosapi.url", wireMock.baseUrl()); - } - - @Test - void shouldGetAlbumById() { - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - Long albumId = 1L; - String responseJson = - """ - [ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } - ] - """; - wireMock.stubFor(WireMock.get(urlMatching("/albums/" + albumId + "/photos")) - .willReturn(aResponse() - .withHeader("Content-Type", MediaType.APPLICATION_JSON) - .withBody(responseJson))); - - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } - } - - @Test - void shouldReturnServerErrorWhenPhotoServiceCallFailed() { - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - Long albumId = 2L; - wireMock.stubFor(WireMock.get(urlMatching("/albums/" + albumId + "/photos")) - .willReturn(aResponse().withStatus(500))); - - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(500); - } - } -} -``` - -Here's what this test does: - -- `WireMockExtension` starts a WireMock server on a dynamic port. -- The `getProperties()` method overrides `micronaut.http.services.photosapi.url` - to point at the WireMock endpoint, so the application talks to WireMock - instead of the real photo service. -- `shouldGetAlbumById()` configures a mock response for - `/albums/{albumId}/photos`, sends a request to the application's - `/api/albums/{albumId}` endpoint, and verifies the response body. -- `shouldReturnServerErrorWhenPhotoServiceCallFailed()` configures WireMock to - return a 500 status and verifies the application propagates that error. - -## Stub using JSON mapping files - -Instead of stubbing with the WireMock Java API, you can use JSON mapping-based -configuration. - -Create `src/test/resources/wiremock/mappings/get-album-photos.json`: - -```json -{ - "mappings": [ - { - "request": { - "method": "GET", - "urlPattern": "/albums/([0-9]+)/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "bodyFileName": "album-photos-resp-200.json" - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/2/photos" - }, - "response": { - "status": 500, - "headers": { - "Content-Type": "application/json" - } - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/3/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "jsonBody": [] - } - } - ] -} -``` - -Create `src/test/resources/wiremock/__files/album-photos-resp-200.json`: - -```json -[ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } -] -``` - -Then initialize WireMock to load stub mappings from these files: - -```java -@RegisterExtension -static WireMockExtension wireMock = WireMockExtension.newInstance() - .options( - wireMockConfig() - .dynamicPort() - .usingFilesUnderClasspath("wiremock") - ) - .build(); -``` - -With mapping files-based stubbing in place, write tests without needing -programmatic stubs: - -```java -@Test -void shouldGetAlbumById() { - Long albumId = 1L; - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } -} -``` - -## Use the Testcontainers WireMock module - -The [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) -provisions a WireMock server as a standalone container within your tests, based -on [WireMock Docker](https://github.com/wiremock/wiremock-docker). - -Create `src/test/resources/mocks-config.json` with the stub mappings: - -```json -{ - "mappings": [ - { - "request": { - "method": "GET", - "urlPattern": "/albums/([0-9]+)/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "bodyFileName": "album-photos-response.json" - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/2/photos" - }, - "response": { - "status": 500, - "headers": { - "Content-Type": "application/json" - } - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/3/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "jsonBody": [] - } - } - ] -} -``` - -Create `src/test/resources/album-photos-response.json`: - -```json -[ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } -] -``` - -Create `AlbumControllerTestcontainersTests.java`: - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; -import static org.hamcrest.Matchers.nullValue; - -import io.micronaut.context.ApplicationContext; -import io.micronaut.core.annotation.NonNull; -import io.micronaut.runtime.server.EmbeddedServer; -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import java.util.Collections; -import java.util.Map; -import org.junit.jupiter.api.Test; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.wiremock.integrations.testcontainers.WireMockContainer; - -@Testcontainers(disabledWithoutDocker = true) -class AlbumControllerTestcontainersTests { - - @Container - static WireMockContainer wiremockServer = new WireMockContainer("wiremock/wiremock:2.35.0") - .withMappingFromResource("mocks-config.json") - .withFileFromResource("album-photos-response.json"); - - @NonNull public Map<String, Object> getProperties() { - return Collections.singletonMap("micronaut.http.services.photosapi.url", wiremockServer.getBaseUrl()); - } - - @Test - void shouldGetAlbumById() { - Long albumId = 1L; - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } - } - - @Test - void shouldReturnServerErrorWhenPhotoServiceCallFailed() { - Long albumId = 2L; - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(500); - } - } - - @Test - void shouldReturnEmptyPhotos() { - Long albumId = 3L; - try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) { - RestAssured.port = server.getPort(); - given().contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", nullValue()); - } - } -} -``` - -Here's what this test does: - -- `@Testcontainers` and `@Container` annotations start a `WireMockContainer` - using the `wiremock/wiremock:2.35.0` Docker image. -- `withMappingFromResource("mocks-config.json")` loads stub mappings from the - classpath resource. -- `withFileFromResource("album-photos-response.json")` makes the response body - file available to WireMock. -- `getProperties()` overrides the photo service URL to point at the WireMock - container's base URL. -- `shouldGetAlbumById()` verifies that the application returns the expected - album with two photos. -- `shouldReturnServerErrorWhenPhotoServiceCallFailed()` verifies that a 500 - from the photo service propagates to the caller. -- `shouldReturnEmptyPhotos()` verifies the application handles an empty photo - list. diff --git a/content/guides/testcontainers-java-mockserver/_index.md b/content/guides/testcontainers-java-mockserver/_index.md deleted file mode 100644 index 0bb73d241e53..000000000000 --- a/content/guides/testcontainers-java-mockserver/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Testing REST API integrations using MockServer -linkTitle: MockServer -description: Learn how to test REST API integrations in a Spring Boot application using the Testcontainers MockServer module. -keywords: testcontainers, java, spring boot, testing, mockserver, rest api, rest assured -summary: | - Learn how to create a Spring Boot application that integrates with - external REST APIs, then test those integrations using Testcontainers - and MockServer. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-mockserver --> - -In this guide, you will learn how to: - -- Create a Spring Boot application that talks to external REST APIs -- Test external API integrations using the Testcontainers MockServer module - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-mockserver/create-project.md b/content/guides/testcontainers-java-mockserver/create-project.md deleted file mode 100644 index 63edcf3d8866..000000000000 --- a/content/guides/testcontainers-java-mockserver/create-project.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with an external REST API integration using declarative HTTP clients. -keywords: testcontainers, java, spring boot, mockserver, rest api, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Spring Web**, **Spring Reactive Web**, and **Testcontainers** -starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-mockserver). - -After generating the project, add the **REST Assured** and **MockServer** -libraries as test dependencies. The key dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> -</properties> -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-web</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-webflux</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-mockserver</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.mock-server</groupId> - <artifactId>mockserver-netty</artifactId> - <version>5.15.0</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.rest-assured</groupId> - <artifactId>rest-assured</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -Using the Testcontainers BOM (Bill of Materials) is recommended so that you -don't have to repeat the version for every Testcontainers module dependency. - -This guide builds an application that manages video albums. A third-party REST -API handles photo assets. For demonstration purposes, the application uses the -publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API -as a photo service. - -The application exposes a `GET /api/albums/{albumId}` endpoint that calls the -photo service to fetch photos for a given album. -[MockServer](https://www.mock-server.com/) is a library for mocking HTTP-based -services. Testcontainers provides a -[MockServer module](https://java.testcontainers.org/modules/mockserver/) that -runs MockServer as a Docker container. - -## Create the Album and Photo models - -Create `Album.java` using Java records: - -```java -package com.testcontainers.demo; - -import java.util.List; - -public record Album(Long albumId, List<Photo> photos) {} - -record Photo(Long id, String title, String url, String thumbnailUrl) {} -``` - -## Create the PhotoServiceClient interface - -Spring Framework 6 introduced -[declarative HTTP client support](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface). -Create an interface with a method that fetches photos for a given album ID: - -```java -package com.testcontainers.demo; - -import java.util.List; -import org.springframework.web.bind.annotation.PathVariable; -import org.springframework.web.service.annotation.GetExchange; - -interface PhotoServiceClient { - @GetExchange("/albums/{albumId}/photos") - List<Photo> getPhotos(@PathVariable Long albumId); -} -``` - -## Register PhotoServiceClient as a bean - -To generate a runtime implementation of `PhotoServiceClient`, register it as a -Spring bean using `HttpServiceProxyFactory`. The factory requires an -`HttpClientAdapter` implementation. Spring Boot provides `WebClientAdapter` as -part of the `spring-webflux` library: - -```java -package com.testcontainers.demo; - -import org.springframework.beans.factory.annotation.Value; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; -import org.springframework.web.reactive.function.client.WebClient; -import org.springframework.web.reactive.function.client.support.WebClientAdapter; -import org.springframework.web.service.invoker.HttpServiceProxyFactory; - -@Configuration -public class AppConfig { - - @Bean - public PhotoServiceClient photoServiceClient( - @Value("${photos.api.base-url}") String photosApiBaseUrl - ) { - WebClient client = WebClient.builder().baseUrl(photosApiBaseUrl).build(); - HttpServiceProxyFactory factory = HttpServiceProxyFactory - .builder(WebClientAdapter.forClient(client)) - .build(); - return factory.createClient(PhotoServiceClient.class); - } -} -``` - -The photo service base URL is externalized as a configuration property. Add the -following entry to `src/main/resources/application.properties`: - -```properties -photos.api.base-url=https://jsonplaceholder.typicode.com -``` - -## Create the REST API endpoint - -Create `AlbumController.java`: - -```java -package com.testcontainers.demo; - -import java.util.List; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.http.ResponseEntity; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PathVariable; -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RestController; -import org.springframework.web.reactive.function.client.WebClientResponseException; - -@RestController -@RequestMapping("/api") -class AlbumController { - - private static final Logger logger = LoggerFactory.getLogger( - AlbumController.class - ); - - private final PhotoServiceClient photoServiceClient; - - AlbumController(PhotoServiceClient photoServiceClient) { - this.photoServiceClient = photoServiceClient; - } - - @GetMapping("/albums/{albumId}") - public ResponseEntity<Album> getAlbumById(@PathVariable Long albumId) { - try { - List<Photo> photos = photoServiceClient.getPhotos(albumId); - return ResponseEntity.ok(new Album(albumId, photos)); - } catch (WebClientResponseException e) { - logger.error("Failed to get photos", e); - return new ResponseEntity<>(e.getStatusCode()); - } - } -} -``` - -This endpoint calls the photo service for a given album ID and returns a -response like: - -```json -{ - "albumId": 1, - "photos": [ - { - "id": 51, - "title": "non sunt voluptatem placeat consequuntur rem incidunt", - "url": "https://via.placeholder.com/600/8e973b", - "thumbnailUrl": "https://via.placeholder.com/150/8e973b" - }, - { - "id": 52, - "title": "eveniet pariatur quia nobis reiciendis laboriosam ea", - "url": "https://via.placeholder.com/600/121fa4", - "thumbnailUrl": "https://via.placeholder.com/150/121fa4" - } - ] -} -``` diff --git a/content/guides/testcontainers-java-mockserver/run-tests.md b/content/guides/testcontainers-java-mockserver/run-tests.md deleted file mode 100644 index ab8e071d5c29..000000000000 --- a/content/guides/testcontainers-java-mockserver/run-tests.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers MockServer integration tests and explore next steps. -keywords: testcontainers, java, spring boot, mockserver, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the MockServer Docker container start in the console output. It -acts as the photo service, serving mock responses based on the configured -expectations. All tests should pass. - -## Summary - -You built a Spring Boot application that integrates with an external REST API -using declarative HTTP clients, then tested that integration using the -Testcontainers MockServer module. Testing at the HTTP protocol level instead of -mocking Java methods lets you catch serialization issues and simulate realistic -failure scenarios. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers MockServer module](https://java.testcontainers.org/modules/mockserver/) -- [MockServer documentation](https://www.mock-server.com/) -- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) diff --git a/content/guides/testcontainers-java-mockserver/write-tests.md b/content/guides/testcontainers-java-mockserver/write-tests.md deleted file mode 100644 index e48654bd8208..000000000000 --- a/content/guides/testcontainers-java-mockserver/write-tests.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Write tests with Testcontainers MockServer -linkTitle: Write tests -description: Test external REST API integrations using the Testcontainers MockServer module and REST Assured. -keywords: testcontainers, java, spring boot, mockserver, rest assured, integration testing -weight: 20 ---- - -Mocking external API interactions at the HTTP protocol level, rather than -mocking Java methods, lets you verify marshalling and unmarshalling behavior and -simulate network issues. - -Testcontainers provides a MockServer module that starts a -[MockServer](https://www.mock-server.com/) instance inside a Docker container. -You can then use `MockServerClient` to configure mock expectations. - -## Write the test - -Create `AlbumControllerTest.java`: - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; -import static org.mockserver.model.HttpRequest.request; -import static org.mockserver.model.HttpResponse.response; -import static org.mockserver.model.JsonBody.json; - -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.mockserver.client.MockServerClient; -import org.mockserver.model.Header; -import org.mockserver.verify.VerificationTimes; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; -import org.testcontainers.mockserver.MockServerContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; - -@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) -@Testcontainers -class AlbumControllerTest { - - @LocalServerPort - private Integer port; - - @Container - static MockServerContainer mockServerContainer = - new MockServerContainer("mockserver/mockserver:5.15.0"); - - static MockServerClient mockServerClient; - - @DynamicPropertySource - static void overrideProperties(DynamicPropertyRegistry registry) { - mockServerClient = - new MockServerClient( - mockServerContainer.getHost(), - mockServerContainer.getServerPort() - ); - registry.add("photos.api.base-url", mockServerContainer::getEndpoint); - } - - @BeforeEach - void setUp() { - RestAssured.port = port; - mockServerClient.reset(); - } - - @Test - void shouldGetAlbumById() { - Long albumId = 1L; - - mockServerClient - .when( - request().withMethod("GET").withPath("/albums/" + albumId + "/photos") - ) - .respond( - response() - .withStatusCode(200) - .withHeaders( - new Header("Content-Type", "application/json; charset=utf-8") - ) - .withBody( - json( - """ - [ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } - ] - """ - ) - ) - ); - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - - verifyMockServerRequest("GET", "/albums/" + albumId + "/photos", 1); - } - - @Test - void shouldReturn404StatusWhenAlbumNotFound() { - Long albumId = 1L; - mockServerClient - .when( - request().withMethod("GET").withPath("/albums/" + albumId + "/photos") - ) - .respond(response().withStatusCode(404)); - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(404); - - verifyMockServerRequest("GET", "/albums/" + albumId + "/photos", 1); - } - - private void verifyMockServerRequest(String method, String path, int times) { - mockServerClient.verify( - request().withMethod(method).withPath(path), - VerificationTimes.exactly(times) - ); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` starts the full application on a random port. -- The `@Testcontainers` and `@Container` annotations start a - `MockServerContainer` and create a `MockServerClient` connected to it. -- `@DynamicPropertySource` overrides `photos.api.base-url` to point at the - MockServer endpoint, so the application talks to MockServer instead of the - real photo service. -- `@BeforeEach` resets the `MockServerClient` before every test so that - expectations from one test don't affect another. -- `shouldGetAlbumById()` configures a mock response for - `/albums/{albumId}/photos`, sends a request to the application's - `/api/albums/{albumId}` endpoint, and verifies the response body. It also - uses `mockServerClient.verify()` to confirm that the expected API call - reached MockServer. -- `shouldReturn404StatusWhenAlbumNotFound()` configures MockServer to return a - 404 status and verifies the application propagates that status to the caller. diff --git a/content/guides/testcontainers-java-quarkus/_index.md b/content/guides/testcontainers-java-quarkus/_index.md deleted file mode 100644 index 2645bb66f6b4..000000000000 --- a/content/guides/testcontainers-java-quarkus/_index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Testing Quarkus applications with Testcontainers -linkTitle: Quarkus -description: Learn how to test a Quarkus REST API using Testcontainers with PostgreSQL, Hibernate ORM with Panache, and REST Assured. -keywords: testcontainers, java, quarkus, testing, postgresql, rest api, rest assured, panache, dev services -summary: | - Learn how to create a Quarkus REST API with Hibernate ORM with Panache and PostgreSQL, - then test it using Quarkus Dev Services, Testcontainers, and REST Assured. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testcontainers-in-quarkus-applications --> - -In this guide, you'll learn how to: - -- Create a Quarkus application with REST API endpoints -- Use Hibernate ORM with Panache and PostgreSQL for persistence -- Test the REST API using Quarkus Dev Services, which uses Testcontainers behind - the scenes -- Test with services not supported by Dev Services using - `QuarkusTestResourceLifecycleManager` - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-quarkus/create-project.md b/content/guides/testcontainers-java-quarkus/create-project.md deleted file mode 100644 index 52d5158a8162..000000000000 --- a/content/guides/testcontainers-java-quarkus/create-project.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Create the Quarkus project -linkTitle: Create the project -description: Set up a Quarkus project with Hibernate ORM with Panache, PostgreSQL, Flyway, and REST API endpoints. -keywords: testcontainers, java, quarkus, postgresql, hibernate, flyway, project setup -weight: 10 ---- - -## Set up the project - -Create a Quarkus project from [code.quarkus.io](https://code.quarkus.io/) by -selecting the **RESTEasy Classic**, **RESTEasy Classic Jackson**, -**Hibernate Validator**, **Hibernate ORM with Panache**, **JDBC Driver - -PostgreSQL**, and **Flyway** extensions. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testcontainers-in-quarkus-applications). - -The key dependencies in `pom.xml` are: - -```xml -<properties> - <quarkus.platform.version>3.22.3</quarkus.platform.version> -</properties> -<dependencies> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-hibernate-orm-panache</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-flyway</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-hibernate-validator</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-resteasy</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-resteasy-jackson</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-jdbc-postgresql</artifactId> - </dependency> - <dependency> - <groupId>io.quarkus</groupId> - <artifactId>quarkus-junit5</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.rest-assured</groupId> - <artifactId>rest-assured</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -## Create the JPA entity - -Hibernate ORM with Panache supports the Active Record pattern and the -Repository pattern to simplify JPA usage. This guide uses the Active Record -pattern. - -Create `Customer.java` by extending `PanacheEntity`. This gives the entity -built-in persistence methods such as `persist()`, `listAll()`, and -`findById()`. - -```java -package com.testcontainers.demo; - -import io.quarkus.hibernate.orm.panache.PanacheEntity; -import jakarta.persistence.Column; -import jakarta.persistence.Entity; -import jakarta.persistence.Table; - -@Entity -@Table(name = "customers") -public class Customer extends PanacheEntity { - - @Column(nullable = false) - public String name; - - @Column(nullable = false, unique = true) - public String email; - - public Customer() {} - - public Customer(Long id, String name, String email) { - this.id = id; - this.name = name; - this.email = email; - } -} -``` - -## Create the CustomerService CDI bean - -Create a `CustomerService` class annotated with `@ApplicationScoped` and -`@Transactional` to handle persistence operations: - -```java -package com.testcontainers.demo; - -import jakarta.enterprise.context.ApplicationScoped; -import jakarta.transaction.Transactional; -import java.util.List; - -@ApplicationScoped -@Transactional -public class CustomerService { - - public List<Customer> getAll() { - return Customer.listAll(); - } - - public Customer create(Customer customer) { - customer.persist(); - return customer; - } -} -``` - -## Add the Flyway database migration script - -Create `src/main/resources/db/migration/V1__init_database.sql`: - -```sql -create sequence customers_seq start with 1 increment by 50; - -create table customers -( - id bigint DEFAULT nextval('customers_seq') not null, - name varchar not null, - email varchar not null, - primary key (id) -); - -insert into customers(name, email) -values ('john', 'john@mail.com'), - ('rambo', 'rambo@mail.com'); -``` - -Enable Flyway migrations in `src/main/resources/application.properties`: - -```properties -quarkus.flyway.migrate-at-start=true -``` - -## Create the REST API endpoints - -Create `CustomerResource.java` with endpoints for fetching all customers and -creating a customer: - -```java -package com.testcontainers.demo; - -import jakarta.ws.rs.Consumes; -import jakarta.ws.rs.GET; -import jakarta.ws.rs.POST; -import jakarta.ws.rs.Path; -import jakarta.ws.rs.Produces; -import jakarta.ws.rs.core.MediaType; -import jakarta.ws.rs.core.Response; -import java.util.List; - -@Path("/api/customers") -@Produces(MediaType.APPLICATION_JSON) -@Consumes(MediaType.APPLICATION_JSON) -public class CustomerResource { - private final CustomerService customerService; - - public CustomerResource(CustomerService customerService) { - this.customerService = customerService; - } - - @GET - public List<Customer> getAllCustomers() { - return customerService.getAll(); - } - - @POST - public Response createCustomer(Customer customer) { - var savedCustomer = customerService.create(customer); - return Response.status(Response.Status.CREATED).entity(savedCustomer).build(); - } -} -``` diff --git a/content/guides/testcontainers-java-quarkus/run-tests.md b/content/guides/testcontainers-java-quarkus/run-tests.md deleted file mode 100644 index 32525d7012d7..000000000000 --- a/content/guides/testcontainers-java-quarkus/run-tests.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Quarkus integration tests and explore next steps. -keywords: testcontainers, java, quarkus, postgresql, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the PostgreSQL Docker container start and all tests pass. After -the tests finish, the container stops and is removed automatically. - -## Run the application locally - -Quarkus Dev Services automatically provisions unconfigured services in -development mode. Start the Quarkus application in dev mode: - -```console -$ ./mvnw compile quarkus:dev -``` - -Or with Gradle: - -```console -$ ./gradlew quarkusDev -``` - -Dev Services starts a PostgreSQL container automatically. If you're running a -PostgreSQL database on your system and want to use that instead, configure the -datasource properties in `src/main/resources/application.properties`: - -```properties -quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres -quarkus.datasource.username=postgres -quarkus.datasource.password=postgres -``` - -When these properties are set explicitly, Dev Services doesn't provision the -database container and instead connects to the configured database. - -## Summary - -Quarkus Dev Services improves the developer experience by automatically -provisioning the required services using Testcontainers during development and -testing. This guide covered: - -- Building a REST API using JAX-RS with Hibernate ORM with Panache -- Testing API endpoints using REST Assured with Dev Services handling database - provisioning -- Using `QuarkusTestResourceLifecycleManager` for services not supported by Dev - Services -- Running the application locally with Dev Services - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Quarkus Dev Services overview](https://quarkus.io/guides/dev-services) -- [Quarkus testing guide](https://quarkus.io/guides/getting-started-testing) -- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) diff --git a/content/guides/testcontainers-java-quarkus/write-tests.md b/content/guides/testcontainers-java-quarkus/write-tests.md deleted file mode 100644 index a22ef561be26..000000000000 --- a/content/guides/testcontainers-java-quarkus/write-tests.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test the Quarkus REST API using Dev Services with Testcontainers, and test with services not supported by Dev Services. -keywords: testcontainers, java, quarkus, dev services, rest api, integration testing -weight: 20 ---- - -## Quarkus Dev Services - -Quarkus Dev Services automatically provisions unconfigured services in -development and test mode. When you include an extension and don't configure it, -Quarkus starts the relevant service using -[Testcontainers](https://www.testcontainers.org/) behind the scenes and wires -the application to use that service. - -> [!NOTE] -> Dev Services requires a -> [supported Docker environment](https://www.testcontainers.org/supported_docker_environment/). - -Quarkus Dev Services supports most commonly used services like SQL databases, -Kafka, RabbitMQ, Redis, and MongoDB. For more information, see the -[Quarkus Dev Services guide](https://quarkus.io/guides/dev-services). - -## Write tests for the API endpoints - -Test the `GET /api/customers` and `POST /api/customers` endpoints using REST -Assured. The `io.rest-assured:rest-assured` library was already added as a test -dependency when you generated the project. - -Create `CustomerResourceTest.java` and annotate it with `@QuarkusTest`. This -bootstraps the application along with the required services using Dev Services. -Because you haven't configured datasource properties, Dev Services automatically -starts a PostgreSQL database using Testcontainers. - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.junit.jupiter.api.Assertions.assertFalse; - -import io.quarkus.test.junit.QuarkusTest; -import io.restassured.common.mapper.TypeRef; -import io.restassured.http.ContentType; -import java.util.List; -import org.junit.jupiter.api.Test; - -@QuarkusTest -class CustomerResourceTest { - - @Test - void shouldGetAllCustomers() { - List<Customer> customers = given().when() - .get("/api/customers") - .then() - .statusCode(200) - .extract() - .as(new TypeRef<>() {}); - assertFalse(customers.isEmpty()); - } - - @Test - void shouldCreateCustomerSuccessfully() { - Customer customer = new Customer(null, "John", "john@gmail.com"); - given().contentType(ContentType.JSON) - .body(customer) - .when() - .post("/api/customers") - .then() - .statusCode(201) - .body("name", is("John")) - .body("email", is("john@gmail.com")); - } -} -``` - -Here's what the test does: - -- `@QuarkusTest` starts the full Quarkus application with Dev Services enabled. -- Dev Services starts a PostgreSQL container using Testcontainers and configures - the datasource automatically. -- `shouldGetAllCustomers()` calls `GET /api/customers` and verifies that seeded - data from the Flyway migration is returned. -- `shouldCreateCustomerSuccessfully()` sends a `POST /api/customers` request and - verifies the response contains the created customer data. - -## Customize test configuration - -By default, the Quarkus test instance starts on port 8081 and uses a -`postgres:14` Docker image. Customize both by adding these properties to -`src/main/resources/application.properties`: - -```properties -quarkus.http.test-port=0 -quarkus.datasource.devservices.image-name=postgres:15.2-alpine -``` - -Setting `quarkus.http.test-port=0` starts the application on a random available -port, avoiding port conflicts. The `devservices.image-name` property lets you -pin the PostgreSQL image to a specific version that matches production. - -## Test with services not supported by Dev Services - -Your application might use a service that Dev Services doesn't support out of -the box. In that case, use `QuarkusTestResourceLifecycleManager` to start the -service before the Quarkus application starts for testing. - -For example, suppose the application uses CockroachDB. First, add the -CockroachDB Testcontainers module dependency: - -```xml -<dependency> - <groupId>org.testcontainers</groupId> - <artifactId>cockroachdb</artifactId> - <scope>test</scope> -</dependency> -``` - -Create a `CockroachDBTestResource` that implements -`QuarkusTestResourceLifecycleManager`: - -```java -package com.testcontainers.demo; - -import io.quarkus.test.common.QuarkusTestResourceLifecycleManager; -import java.util.HashMap; -import java.util.Map; -import org.testcontainers.containers.CockroachContainer; - -public class CockroachDBTestResource implements QuarkusTestResourceLifecycleManager { - - CockroachContainer cockroachdb; - - @Override - public Map<String, String> start() { - cockroachdb = new CockroachContainer("cockroachdb/cockroach:v22.2.0"); - cockroachdb.start(); - Map<String, String> conf = new HashMap<>(); - conf.put("quarkus.datasource.jdbc.url", cockroachdb.getJdbcUrl()); - conf.put("quarkus.datasource.username", cockroachdb.getUsername()); - conf.put("quarkus.datasource.password", cockroachdb.getPassword()); - return conf; - } - - @Override - public void stop() { - cockroachdb.stop(); - } -} -``` - -Use the `CockroachDBTestResource` with `@QuarkusTestResource` in a test class: - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.junit.jupiter.api.Assertions.assertFalse; - -import io.quarkus.test.common.QuarkusTestResource; -import io.quarkus.test.junit.QuarkusTest; -import io.restassured.common.mapper.TypeRef; -import java.util.List; -import org.junit.jupiter.api.Test; - -@QuarkusTest -@QuarkusTestResource(value = CockroachDBTestResource.class, restrictToAnnotatedClass = true) -class CockroachDBTest { - - @Test - void shouldGetAllCustomers() { - List<Customer> customers = given().when() - .get("/api/customers") - .then() - .statusCode(200) - .extract() - .as(new TypeRef<>() {}); - assertFalse(customers.isEmpty()); - } -} -``` - -The `restrictToAnnotatedClass = true` attribute ensures the CockroachDB -container only starts when running this specific test class, rather than being -activated for all tests. diff --git a/content/guides/testcontainers-java-replace-h2.md b/content/guides/testcontainers-java-replace-h2.md new file mode 100644 index 000000000000..ee4062a99a83 --- /dev/null +++ b/content/guides/testcontainers-java-replace-h2.md @@ -0,0 +1,266 @@ +--- +title: Replace H2 with a real database for testing +linkTitle: Replace H2 database +description: Learn how to replace an H2 in-memory database with a real PostgreSQL database for testing using Testcontainers. +keywords: testcontainers, java, testing, h2, postgresql, spring boot, spring data jpa, jdbc +summary: | + Replace your H2 in-memory test database with a real PostgreSQL instance + using the Testcontainers special JDBC URL — a one-line change. +aliases: + - /guides/testcontainers-java-replace-h2/jdbc-url-approach/ + - /guides/testcontainers-java-replace-h2/junit-extension-approach/ + - /guides/testcontainers-java-replace-h2/problem-with-h2/ +params: + tags: [testing] + time: 15 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-replace-h2-with-real-database-for-testing --> + +In this guide, you will learn how to: + +- Understand the drawbacks of using H2 in-memory databases for testing +- Replace H2 with a real PostgreSQL database using the Testcontainers special JDBC URL +- Use the Testcontainers JUnit 5 extension for more control over the container +- Test both Spring Data JPA and JdbcTemplate-based repositories + +## Prerequisites + +- Java 17+ +- Maven or Gradle +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## The problem with H2 for testing + +A common practice is to use lightweight databases like H2 or HSQL as +in-memory databases for testing while using PostgreSQL, MySQL, or Oracle in +production. This approach has significant drawbacks: + +- The test database might not support all features of your production database. +- SQL syntax might not be compatible between H2 and your production database. +- Tests passing with H2 don't guarantee they'll work in production. + +### Example: PostgreSQL-specific syntax + +Consider implementing an "upsert" — insert a product only if it doesn't +already exist. In PostgreSQL, you can use: + +```sql +INSERT INTO products(id, code, name) VALUES(?,?,?) ON CONFLICT DO NOTHING; +``` + +This query doesn't work with H2 by default: + +```text +Caused by: org.h2.jdbc.JdbcSQLException: Syntax error in SQL statement +"INSERT INTO products (id, code, name) VALUES (?, ?, ?) ON[*] CONFLICT DO NOTHING"; +``` + +You can run H2 in PostgreSQL compatibility mode, but not all features are +supported. The inverse is also true — H2 supports `ROWNUM()` which PostgreSQL +doesn't. + +Testing with a different database than production means you can't trust your +test results and must verify after deployment, defeating the purpose of +automated tests. + +### The Spring Boot test using H2 + +A typical H2-based test looks like this: + +```java +@DataJpaTest +class ProductRepositoryTest { + + @Autowired + ProductRepository productRepository; + + @Test + @Sql("classpath:/sql/seed-data.sql") + void shouldGetAllProducts() { + List<Product> products = productRepository.findAll(); + assertEquals(2, products.size()); + } +} +``` + +Spring Boot uses H2 automatically when it's on the classpath. The test passes, +but it doesn't catch PostgreSQL-specific issues. + +## Replace H2 with the Testcontainers JDBC URL + +Replacing H2 with a real PostgreSQL database requires two test properties: + +```java +@DataJpaTest +@TestPropertySource(properties = { + "spring.test.database.replace=none", + "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db" +}) +class ProductRepositoryWithJdbcUrlTest { + + @Autowired + ProductRepository productRepository; + + @Test + @Sql("classpath:/sql/seed-data.sql") + void shouldGetAllProducts() { + List<Product> products = productRepository.findAll(); + assertEquals(2, products.size()); + } +} +``` + +That's it — two properties and your tests run against a real PostgreSQL +database. + +### How the special JDBC URL works + +A standard PostgreSQL JDBC URL looks like: + +```text +jdbc:postgresql://localhost:5432/postgres +``` + +The Testcontainers special JDBC URL inserts `tc:` after `jdbc:`: + +```text +jdbc:tc:postgresql:///db +``` + +The hostname, port, and database name are ignored — Testcontainers manages them +automatically. You can specify the Docker image tag after the database name: + +```text +jdbc:tc:postgresql:16-alpine:///db +``` + +This creates a container from the `postgres:16-alpine` image. + +### Initialize the database with a script + +Pass `TC_INITSCRIPT` to run an SQL script when the container starts: + +```text +jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql +``` + +Testcontainers runs the script automatically. For production applications, +use a database migration tool like Flyway or Liquibase instead. + +The special JDBC URL also works for MySQL, MariaDB, PostGIS, YugabyteDB, +CockroachDB, and other databases with Testcontainers JDBC support. + +### Testing JdbcTemplate-based repositories + +The same approach works for `JdbcTemplate`-based repositories. Use `@JdbcTest` +instead of `@DataJpaTest`: + +```java +@JdbcTest +@TestPropertySource(properties = { + "spring.test.database.replace=none", + "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql" +}) +class JdbcProductRepositoryTest { + + @Autowired + private JdbcTemplate jdbcTemplate; + + private JdbcProductRepository productRepository; + + @BeforeEach + void setUp() { + productRepository = new JdbcProductRepository(jdbcTemplate); + } + + @Test + @Sql("/sql/seed-data.sql") + void shouldGetAllProducts() { + List<Product> products = productRepository.getAllProducts(); + assertEquals(2, products.size()); + } +} +``` + +## Use the JUnit 5 extension for more control + +If the special JDBC URL doesn't meet your needs, or you need more control over +container creation (for example, to copy initialization scripts), use the +Testcontainers JUnit 5 extension: + +```java +@DataJpaTest +@TestPropertySource(properties = { + "spring.test.database.replace=none" +}) +@Testcontainers +class ProductRepositoryTest { + + @Container + static PostgreSQLContainer postgres = + new PostgreSQLContainer("postgres:16-alpine") + .withCopyFileToContainer( + MountableFile.forClasspathResource("sql/init-db.sql"), + "/docker-entrypoint-initdb.d/init-db.sql"); + + @DynamicPropertySource + static void configureProperties(DynamicPropertyRegistry registry) { + registry.add("spring.datasource.url", postgres::getJdbcUrl); + registry.add("spring.datasource.username", postgres::getUsername); + registry.add("spring.datasource.password", postgres::getPassword); + } + + @Autowired + ProductRepository productRepository; + + @Test + @Sql("/sql/seed-data.sql") + void shouldGetAllProducts() { + List<Product> products = productRepository.findAll(); + assertEquals(2, products.size()); + } + + @Test + @Sql("/sql/seed-data.sql") + void shouldNotCreateAProductWithDuplicateCode() { + Product product = new Product(3L, "p101", "Test Product"); + productRepository.createProductIfNotExists(product); + Optional<Product> optionalProduct = productRepository.findById( + product.getId() + ); + assertThat(optionalProduct).isEmpty(); + } +} +``` + +This approach: + +- Uses `@Testcontainers` and `@Container` to manage the container lifecycle. +- Copies `init-db.sql` into the container's init directory so PostgreSQL + runs it at startup. +- Uses `@DynamicPropertySource` to register the container's connection details + with Spring Boot. +- Tests PostgreSQL-specific features like `ON CONFLICT DO NOTHING` that + wouldn't work with H2. + +### Summary + +- Use the **special JDBC URL** (`jdbc:tc:postgresql:...`) for the quickest way + to switch from H2 to a real database — it's a one-property change. +- Use the **JUnit 5 extension** when you need more control over the container + (custom init scripts, environment variables, etc.). +- Both approaches work with Spring Data JPA (`@DataJpaTest`) and JdbcTemplate + (`@JdbcTest`) tests. + +### Further reading + +- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) +- [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/) +- [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/) diff --git a/content/guides/testcontainers-java-replace-h2/_index.md b/content/guides/testcontainers-java-replace-h2/_index.md deleted file mode 100644 index c6dd22e70992..000000000000 --- a/content/guides/testcontainers-java-replace-h2/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Replace H2 with a real database for testing -linkTitle: Replace H2 database -description: Learn how to replace an H2 in-memory database with a real PostgreSQL database for testing using Testcontainers. -keywords: testcontainers, java, testing, h2, postgresql, spring boot, spring data jpa, jdbc -summary: | - Replace your H2 in-memory test database with a real PostgreSQL instance - using the Testcontainers special JDBC URL — a one-line change. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 15 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-replace-h2-with-real-database-for-testing --> - -In this guide, you will learn how to: - -- Understand the drawbacks of using H2 in-memory databases for testing -- Replace H2 with a real PostgreSQL database using the Testcontainers special JDBC URL -- Use the Testcontainers JUnit 5 extension for more control over the container -- Test both Spring Data JPA and JdbcTemplate-based repositories - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-replace-h2/jdbc-url-approach.md b/content/guides/testcontainers-java-replace-h2/jdbc-url-approach.md deleted file mode 100644 index a09dcaf23051..000000000000 --- a/content/guides/testcontainers-java-replace-h2/jdbc-url-approach.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Replace H2 with the Testcontainers JDBC URL -linkTitle: JDBC URL approach -description: Use the Testcontainers special JDBC URL to swap H2 for a real PostgreSQL database. -keywords: testcontainers, java, h2, postgresql, jdbc, integration testing -weight: 20 ---- - -Replacing H2 with a real PostgreSQL database requires two test properties: - -```java -@DataJpaTest -@TestPropertySource(properties = { - "spring.test.database.replace=none", - "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db" -}) -class ProductRepositoryWithJdbcUrlTest { - - @Autowired - ProductRepository productRepository; - - @Test - @Sql("classpath:/sql/seed-data.sql") - void shouldGetAllProducts() { - List<Product> products = productRepository.findAll(); - assertEquals(2, products.size()); - } -} -``` - -That's it — two properties and your tests run against a real PostgreSQL -database. - -## How the special JDBC URL works - -A standard PostgreSQL JDBC URL looks like: - -```text -jdbc:postgresql://localhost:5432/postgres -``` - -The Testcontainers special JDBC URL inserts `tc:` after `jdbc:`: - -```text -jdbc:tc:postgresql:///db -``` - -The hostname, port, and database name are ignored — Testcontainers manages them -automatically. You can specify the Docker image tag after the database name: - -```text -jdbc:tc:postgresql:16-alpine:///db -``` - -This creates a container from the `postgres:16-alpine` image. - -## Initialize the database with a script - -Pass `TC_INITSCRIPT` to run an SQL script when the container starts: - -```text -jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql -``` - -Testcontainers runs the script automatically. For production applications, -use a database migration tool like Flyway or Liquibase instead. - -The special JDBC URL also works for MySQL, MariaDB, PostGIS, YugabyteDB, -CockroachDB, and other databases with Testcontainers JDBC support. - -## Testing JdbcTemplate-based repositories - -The same approach works for `JdbcTemplate`-based repositories. Use `@JdbcTest` -instead of `@DataJpaTest`: - -```java -@JdbcTest -@TestPropertySource(properties = { - "spring.test.database.replace=none", - "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql" -}) -class JdbcProductRepositoryTest { - - @Autowired - private JdbcTemplate jdbcTemplate; - - private JdbcProductRepository productRepository; - - @BeforeEach - void setUp() { - productRepository = new JdbcProductRepository(jdbcTemplate); - } - - @Test - @Sql("/sql/seed-data.sql") - void shouldGetAllProducts() { - List<Product> products = productRepository.getAllProducts(); - assertEquals(2, products.size()); - } -} -``` diff --git a/content/guides/testcontainers-java-replace-h2/junit-extension-approach.md b/content/guides/testcontainers-java-replace-h2/junit-extension-approach.md deleted file mode 100644 index 75c11b516685..000000000000 --- a/content/guides/testcontainers-java-replace-h2/junit-extension-approach.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Use the JUnit 5 extension for more control -linkTitle: JUnit 5 extension -description: Use the Testcontainers JUnit 5 extension for more control over the PostgreSQL container. -keywords: testcontainers, java, h2, postgresql, junit, integration testing -weight: 30 ---- - -If the special JDBC URL doesn't meet your needs, or you need more control over -container creation (for example, to copy initialization scripts), use the -Testcontainers JUnit 5 extension: - -```java -@DataJpaTest -@TestPropertySource(properties = { - "spring.test.database.replace=none" -}) -@Testcontainers -class ProductRepositoryTest { - - @Container - static PostgreSQLContainer postgres = - new PostgreSQLContainer("postgres:16-alpine") - .withCopyFileToContainer( - MountableFile.forClasspathResource("sql/init-db.sql"), - "/docker-entrypoint-initdb.d/init-db.sql"); - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("spring.datasource.url", postgres::getJdbcUrl); - registry.add("spring.datasource.username", postgres::getUsername); - registry.add("spring.datasource.password", postgres::getPassword); - } - - @Autowired - ProductRepository productRepository; - - @Test - @Sql("/sql/seed-data.sql") - void shouldGetAllProducts() { - List<Product> products = productRepository.findAll(); - assertEquals(2, products.size()); - } - - @Test - @Sql("/sql/seed-data.sql") - void shouldNotCreateAProductWithDuplicateCode() { - Product product = new Product(3L, "p101", "Test Product"); - productRepository.createProductIfNotExists(product); - Optional<Product> optionalProduct = productRepository.findById( - product.getId() - ); - assertThat(optionalProduct).isEmpty(); - } -} -``` - -This approach: - -- Uses `@Testcontainers` and `@Container` to manage the container lifecycle. -- Copies `init-db.sql` into the container's init directory so PostgreSQL - runs it at startup. -- Uses `@DynamicPropertySource` to register the container's connection details - with Spring Boot. -- Tests PostgreSQL-specific features like `ON CONFLICT DO NOTHING` that - wouldn't work with H2. - -## Summary - -- Use the **special JDBC URL** (`jdbc:tc:postgresql:...`) for the quickest way - to switch from H2 to a real database — it's a one-property change. -- Use the **JUnit 5 extension** when you need more control over the container - (custom init scripts, environment variables, etc.). -- Both approaches work with Spring Data JPA (`@DataJpaTest`) and JdbcTemplate - (`@JdbcTest`) tests. - -## Further reading - -- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) -- [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/) -- [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/) diff --git a/content/guides/testcontainers-java-replace-h2/problem-with-h2.md b/content/guides/testcontainers-java-replace-h2/problem-with-h2.md deleted file mode 100644 index c51c05961a8f..000000000000 --- a/content/guides/testcontainers-java-replace-h2/problem-with-h2.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: The problem with H2 for testing -linkTitle: The H2 problem -description: Understand why using H2 in-memory databases for testing gives false confidence. -keywords: testcontainers, java, h2, in-memory database, integration testing -weight: 10 ---- - -A common practice is to use lightweight databases like H2 or HSQL as -in-memory databases for testing while using PostgreSQL, MySQL, or Oracle in -production. This approach has significant drawbacks: - -- The test database might not support all features of your production database. -- SQL syntax might not be compatible between H2 and your production database. -- Tests passing with H2 don't guarantee they'll work in production. - -## Example: PostgreSQL-specific syntax - -Consider implementing an "upsert" — insert a product only if it doesn't -already exist. In PostgreSQL, you can use: - -```sql -INSERT INTO products(id, code, name) VALUES(?,?,?) ON CONFLICT DO NOTHING; -``` - -This query doesn't work with H2 by default: - -```text -Caused by: org.h2.jdbc.JdbcSQLException: Syntax error in SQL statement -"INSERT INTO products (id, code, name) VALUES (?, ?, ?) ON[*] CONFLICT DO NOTHING"; -``` - -You can run H2 in PostgreSQL compatibility mode, but not all features are -supported. The inverse is also true — H2 supports `ROWNUM()` which PostgreSQL -doesn't. - -Testing with a different database than production means you can't trust your -test results and must verify after deployment, defeating the purpose of -automated tests. - -## The Spring Boot test using H2 - -A typical H2-based test looks like this: - -```java -@DataJpaTest -class ProductRepositoryTest { - - @Autowired - ProductRepository productRepository; - - @Test - @Sql("classpath:/sql/seed-data.sql") - void shouldGetAllProducts() { - List<Product> products = productRepository.findAll(); - assertEquals(2, products.size()); - } -} -``` - -Spring Boot uses H2 automatically when it's on the classpath. The test passes, -but it doesn't catch PostgreSQL-specific issues. diff --git a/content/guides/testcontainers-java-service-configuration.md b/content/guides/testcontainers-java-service-configuration.md new file mode 100644 index 000000000000..c969f11b2bee --- /dev/null +++ b/content/guides/testcontainers-java-service-configuration.md @@ -0,0 +1,233 @@ +--- +title: Configuration of services running in a container +linkTitle: Service configuration (Java) +description: Learn how to configure services running in Testcontainers by copying files and executing commands inside containers. +keywords: testcontainers, java, testing, postgresql, localstack, container configuration +summary: | + Learn how to initialize and configure Docker containers for testing + by copying files into containers and executing commands inside them. +aliases: + - /guides/testcontainers-java-service-configuration/copy-files/ + - /guides/testcontainers-java-service-configuration/exec-in-container/ +params: + tags: [testing] + time: 15 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-configuration-of-services-running-in-container --> + +In this guide, you will learn how to: + +- Initialize containers by copying files into them +- Run commands inside running containers using `execInContainer()` +- Set up a PostgreSQL database with SQL scripts +- Create AWS S3 buckets in LocalStack containers + +## Prerequisites + +- Java 17+ +- Your preferred IDE +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Copy files into containers + +Sometimes you need to initialize a container by placing files in a specific +location. For example, PostgreSQL runs SQL scripts from +`/docker-entrypoint-initdb.d/` when the container starts. + +### Create the initialization script + +Create `src/test/resources/init-db.sql`: + +```sql +create table customers ( + id bigint not null, + name varchar not null, + primary key (id) +); +``` + +### Copy the file into the container + +Use `withCopyFileToContainer()` to copy the SQL script into the container's +init directory: + +```java +package com.testcontainers.demo; + +import static org.junit.jupiter.api.Assertions.assertFalse; + +import java.util.List; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.testcontainers.postgresql.PostgreSQLContainer; +import org.testcontainers.junit.jupiter.Container; +import org.testcontainers.junit.jupiter.Testcontainers; +import org.testcontainers.utility.MountableFile; + +@Testcontainers +class CustomerServiceTest { + + @Container + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine" + ) + .withCopyFileToContainer( + MountableFile.forClasspathResource("init-db.sql"), + "/docker-entrypoint-initdb.d/" + ); + + CustomerService customerService; + + @BeforeEach + void setUp() { + customerService = + new CustomerService( + postgres.getJdbcUrl(), + postgres.getUsername(), + postgres.getPassword() + ); + } + + @Test + void shouldGetCustomers() { + customerService.createCustomer(new Customer(1L, "George")); + customerService.createCustomer(new Customer(2L, "John")); + + List<Customer> customers = customerService.getAllCustomers(); + assertFalse(customers.isEmpty()); + } +} +``` + +The `withCopyFileToContainer(MountableFile, String)` method copies `init-db.sql` +from the classpath into `/docker-entrypoint-initdb.d/` inside the container. +PostgreSQL executes scripts in that directory automatically at startup. + +You can also copy files from any path on the host: + +```java +.withCopyFileToContainer( + MountableFile.forHostPath("/host/path/to/init-db.sql"), + "/docker-entrypoint-initdb.d/" +); +``` + +## Execute commands inside containers + +Some Docker containers provide CLI tools for performing actions. You can use +`container.execInContainer(String...)` to run any available command inside a +running container. + +### Example: Create an S3 bucket in LocalStack + +The [LocalStack](https://localstack.cloud/) module emulates AWS services. To +test S3 file uploads, create a bucket before running tests: + +```java +package com.testcontainers.demo; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3; + +import java.io.IOException; +import java.net.URI; +import java.util.List; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.testcontainers.containers.localstack.LocalStackContainer; +import org.testcontainers.junit.jupiter.Container; +import org.testcontainers.junit.jupiter.Testcontainers; +import org.testcontainers.utility.DockerImageName; +import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; +import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; +import software.amazon.awssdk.regions.Region; +import software.amazon.awssdk.services.s3.S3Client; +import software.amazon.awssdk.services.s3.model.Bucket; + +@Testcontainers +class LocalStackTest { + + static final String bucketName = "mybucket"; + + @Container + static LocalStackContainer localStack = new LocalStackContainer( + DockerImageName.parse("localstack/localstack:3.4.0") + ); + + @BeforeAll + static void beforeAll() throws IOException, InterruptedException { + localStack.execInContainer("awslocal", "s3", "mb", "s3://" + bucketName); + + org.testcontainers.containers.Container.ExecResult execResult = + localStack.execInContainer("awslocal", "s3", "ls"); + String stdout = execResult.getStdout(); + int exitCode = execResult.getExitCode(); + assertTrue(stdout.contains(bucketName)); + assertEquals(0, exitCode); + } + + @Test + void shouldListBuckets() { + URI s3Endpoint = localStack.getEndpointOverride(S3); + StaticCredentialsProvider credentialsProvider = + StaticCredentialsProvider.create( + AwsBasicCredentials.create( + localStack.getAccessKey(), + localStack.getSecretKey() + ) + ); + S3Client s3 = S3Client + .builder() + .endpointOverride(s3Endpoint) + .credentialsProvider(credentialsProvider) + .region(Region.of(localStack.getRegion())) + .build(); + + List<String> s3Buckets = s3 + .listBuckets() + .buckets() + .stream() + .map(Bucket::name) + .toList(); + + assertTrue(s3Buckets.contains(bucketName)); + } +} +``` + +The `execInContainer("awslocal", "s3", "mb", "s3://mybucket")` call runs the +`awslocal` CLI tool (provided by the LocalStack image) to create an S3 bucket. + +You can capture the output and exit code from any command: + +```java +Container.ExecResult execResult = + localStack.execInContainer("awslocal", "s3", "ls"); +String stdout = execResult.getStdout(); +int exitCode = execResult.getExitCode(); +``` + +> [!NOTE] +> The `withCopyFileToContainer()` and `execInContainer()` methods are inherited +> from `GenericContainer`, so they're available for all Testcontainers modules. + +### Summary + +- Use `withCopyFileToContainer()` to place initialization files inside + containers before they start. +- Use `execInContainer()` to run commands inside running containers for + setup tasks like creating buckets, topics, or queues. + +### Further reading + +- [Getting started with Testcontainers for Java](/guides/testcontainers-java-getting-started/) +- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) +- [Testcontainers LocalStack module](https://java.testcontainers.org/modules/localstack/) diff --git a/content/guides/testcontainers-java-service-configuration/_index.md b/content/guides/testcontainers-java-service-configuration/_index.md deleted file mode 100644 index 2d1ac1d788c6..000000000000 --- a/content/guides/testcontainers-java-service-configuration/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Configuration of services running in a container -linkTitle: Service configuration (Java) -description: Learn how to configure services running in Testcontainers by copying files and executing commands inside containers. -keywords: testcontainers, java, testing, postgresql, localstack, container configuration -summary: | - Learn how to initialize and configure Docker containers for testing - by copying files into containers and executing commands inside them. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 15 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-configuration-of-services-running-in-container --> - -In this guide, you will learn how to: - -- Initialize containers by copying files into them -- Run commands inside running containers using `execInContainer()` -- Set up a PostgreSQL database with SQL scripts -- Create AWS S3 buckets in LocalStack containers - -## Prerequisites - -- Java 17+ -- Your preferred IDE -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-service-configuration/copy-files.md b/content/guides/testcontainers-java-service-configuration/copy-files.md deleted file mode 100644 index 7a992bfc4c8b..000000000000 --- a/content/guides/testcontainers-java-service-configuration/copy-files.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Copy files into containers -linkTitle: Copy files -description: Initialize containers by copying files into specific locations. -keywords: testcontainers, java, service configuration, copy files, container initialization -weight: 10 ---- - -Sometimes you need to initialize a container by placing files in a specific -location. For example, PostgreSQL runs SQL scripts from -`/docker-entrypoint-initdb.d/` when the container starts. - -## Create the initialization script - -Create `src/test/resources/init-db.sql`: - -```sql -create table customers ( - id bigint not null, - name varchar not null, - primary key (id) -); -``` - -## Copy the file into the container - -Use `withCopyFileToContainer()` to copy the SQL script into the container's -init directory: - -```java -package com.testcontainers.demo; - -import static org.junit.jupiter.api.Assertions.assertFalse; - -import java.util.List; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.testcontainers.postgresql.PostgreSQLContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.utility.MountableFile; - -@Testcontainers -class CustomerServiceTest { - - @Container - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ) - .withCopyFileToContainer( - MountableFile.forClasspathResource("init-db.sql"), - "/docker-entrypoint-initdb.d/" - ); - - CustomerService customerService; - - @BeforeEach - void setUp() { - customerService = - new CustomerService( - postgres.getJdbcUrl(), - postgres.getUsername(), - postgres.getPassword() - ); - } - - @Test - void shouldGetCustomers() { - customerService.createCustomer(new Customer(1L, "George")); - customerService.createCustomer(new Customer(2L, "John")); - - List<Customer> customers = customerService.getAllCustomers(); - assertFalse(customers.isEmpty()); - } -} -``` - -The `withCopyFileToContainer(MountableFile, String)` method copies `init-db.sql` -from the classpath into `/docker-entrypoint-initdb.d/` inside the container. -PostgreSQL executes scripts in that directory automatically at startup. - -You can also copy files from any path on the host: - -```java -.withCopyFileToContainer( - MountableFile.forHostPath("/host/path/to/init-db.sql"), - "/docker-entrypoint-initdb.d/" -); -``` diff --git a/content/guides/testcontainers-java-service-configuration/exec-in-container.md b/content/guides/testcontainers-java-service-configuration/exec-in-container.md deleted file mode 100644 index 0ac4dc1ee01f..000000000000 --- a/content/guides/testcontainers-java-service-configuration/exec-in-container.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Execute commands inside containers -linkTitle: Execute commands -description: Run commands inside running containers to initialize services for testing. -keywords: testcontainers, java, service configuration, exec, container initialization -weight: 20 ---- - -Some Docker containers provide CLI tools for performing actions. You can use -`container.execInContainer(String...)` to run any available command inside a -running container. - -## Example: Create an S3 bucket in LocalStack - -The [LocalStack](https://localstack.cloud/) module emulates AWS services. To -test S3 file uploads, create a bucket before running tests: - -```java -package com.testcontainers.demo; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertTrue; -import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3; - -import java.io.IOException; -import java.net.URI; -import java.util.List; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.Test; -import org.testcontainers.containers.localstack.LocalStackContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.testcontainers.utility.DockerImageName; -import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; -import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; -import software.amazon.awssdk.regions.Region; -import software.amazon.awssdk.services.s3.S3Client; -import software.amazon.awssdk.services.s3.model.Bucket; - -@Testcontainers -class LocalStackTest { - - static final String bucketName = "mybucket"; - - @Container - static LocalStackContainer localStack = new LocalStackContainer( - DockerImageName.parse("localstack/localstack:3.4.0") - ); - - @BeforeAll - static void beforeAll() throws IOException, InterruptedException { - localStack.execInContainer("awslocal", "s3", "mb", "s3://" + bucketName); - - org.testcontainers.containers.Container.ExecResult execResult = - localStack.execInContainer("awslocal", "s3", "ls"); - String stdout = execResult.getStdout(); - int exitCode = execResult.getExitCode(); - assertTrue(stdout.contains(bucketName)); - assertEquals(0, exitCode); - } - - @Test - void shouldListBuckets() { - URI s3Endpoint = localStack.getEndpointOverride(S3); - StaticCredentialsProvider credentialsProvider = - StaticCredentialsProvider.create( - AwsBasicCredentials.create( - localStack.getAccessKey(), - localStack.getSecretKey() - ) - ); - S3Client s3 = S3Client - .builder() - .endpointOverride(s3Endpoint) - .credentialsProvider(credentialsProvider) - .region(Region.of(localStack.getRegion())) - .build(); - - List<String> s3Buckets = s3 - .listBuckets() - .buckets() - .stream() - .map(Bucket::name) - .toList(); - - assertTrue(s3Buckets.contains(bucketName)); - } -} -``` - -The `execInContainer("awslocal", "s3", "mb", "s3://mybucket")` call runs the -`awslocal` CLI tool (provided by the LocalStack image) to create an S3 bucket. - -You can capture the output and exit code from any command: - -```java -Container.ExecResult execResult = - localStack.execInContainer("awslocal", "s3", "ls"); -String stdout = execResult.getStdout(); -int exitCode = execResult.getExitCode(); -``` - -> [!NOTE] -> The `withCopyFileToContainer()` and `execInContainer()` methods are inherited -> from `GenericContainer`, so they're available for all Testcontainers modules. - -## Summary - -- Use `withCopyFileToContainer()` to place initialization files inside - containers before they start. -- Use `execInContainer()` to run commands inside running containers for - setup tasks like creating buckets, topics, or queues. - -## Further reading - -- [Getting started with Testcontainers for Java](/guides/testcontainers-java-getting-started/) -- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) -- [Testcontainers LocalStack module](https://java.testcontainers.org/modules/localstack/) diff --git a/content/guides/testcontainers-java-spring-boot-kafka/_index.md b/content/guides/testcontainers-java-spring-boot-kafka/_index.md deleted file mode 100644 index 03ff02d617e0..000000000000 --- a/content/guides/testcontainers-java-spring-boot-kafka/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Testing Spring Boot Kafka Listener using Testcontainers -linkTitle: Spring Boot Kafka -description: Learn how to test a Spring Boot Kafka listener using Testcontainers with Kafka and MySQL modules. -keywords: testcontainers, java, spring boot, testing, kafka, mysql, jpa, awaitility -summary: | - Learn how to create a Spring Boot application with a Kafka listener that persists data in MySQL, - then test it using Testcontainers Kafka and MySQL modules with Awaitility. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-spring-boot-kafka-listener --> - -In this guide, you will learn how to: - -- Create a Spring Boot application with Kafka integration -- Implement a Kafka listener and persist data in a MySQL database -- Test the Kafka listener using Testcontainers and Awaitility - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-spring-boot-kafka/create-project.md b/content/guides/testcontainers-java-spring-boot-kafka/create-project.md deleted file mode 100644 index 52c0e1b7fb67..000000000000 --- a/content/guides/testcontainers-java-spring-boot-kafka/create-project.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with Kafka, Spring Data JPA, and MySQL. -keywords: testcontainers, java, spring boot, kafka, mysql, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Spring for Apache Kafka**, **Spring Data JPA**, **MySQL Driver**, -and **Testcontainers** starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-spring-boot-kafka-listener). - -After generating the application, add the Awaitility library as a test -dependency. You'll use it later to assert the expectations of an asynchronous -process flow. - -The key dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> -</properties> -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-data-jpa</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.kafka</groupId> - <artifactId>spring-kafka</artifactId> - </dependency> - <dependency> - <groupId>com.mysql</groupId> - <artifactId>mysql-connector-j</artifactId> - <scope>runtime</scope> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.springframework.kafka</groupId> - <artifactId>spring-kafka-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-kafka</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-mysql</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.awaitility</groupId> - <artifactId>awaitility</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -Using the Testcontainers BOM (Bill of Materials) is recommended so that you -don't have to repeat the version for every Testcontainers module dependency. - -## Create the JPA entity - -The application listens to a topic called `product-price-changes`. When a -message arrives, it extracts the product code and price from the event payload -and updates the price for that product in the MySQL database. - -Create `Product.java`: - -```java -package com.testcontainers.demo; - -import jakarta.persistence.Column; -import jakarta.persistence.Entity; -import jakarta.persistence.GeneratedValue; -import jakarta.persistence.GenerationType; -import jakarta.persistence.Id; -import jakarta.persistence.Table; -import java.math.BigDecimal; - -@Entity -@Table(name = "products") -class Product { - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - private Long id; - - @Column(nullable = false, unique = true) - private String code; - - @Column(nullable = false) - private String name; - - @Column(nullable = false) - private BigDecimal price; - - public Product() {} - - public Product(Long id, String code, String name, BigDecimal price) { - this.id = id; - this.code = code; - this.name = name; - this.price = price; - } - - public Long getId() { - return id; - } - - public void setId(Long id) { - this.id = id; - } - - public String getCode() { - return code; - } - - public void setCode(String code) { - this.code = code; - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - - public BigDecimal getPrice() { - return price; - } - - public void setPrice(BigDecimal price) { - this.price = price; - } -} -``` - -## Create the Spring Data JPA repository - -Create a repository interface for the `Product` entity with a method to find a -product by code and a method to update the price for a given product code: - -```java -package com.testcontainers.demo; - -import java.math.BigDecimal; -import java.util.Optional; -import org.springframework.data.jpa.repository.JpaRepository; -import org.springframework.data.jpa.repository.Modifying; -import org.springframework.data.jpa.repository.Query; -import org.springframework.data.repository.query.Param; - -interface ProductRepository extends JpaRepository<Product, Long> { - Optional<Product> findByCode(String code); - - @Modifying - @Query("update Product p set p.price = :price where p.code = :productCode") - void updateProductPrice( - @Param("productCode") String productCode, - @Param("price") BigDecimal price - ); -} -``` - -## Add a schema creation script - -Because the application doesn't use an in-memory database, you need to create -the MySQL tables. The recommended approach for production is a migration tool -like Flyway or Liquibase, but for this guide the built-in Spring Boot schema -initialization is sufficient. - -Create `src/main/resources/schema.sql`: - -```sql -create table products ( - id int NOT NULL AUTO_INCREMENT, - code varchar(255) not null, - name varchar(255) not null, - price numeric(5,2) not null, - PRIMARY KEY (id), - UNIQUE (code) -); -``` - -Enable schema initialization in `src/main/resources/application.properties`: - -```properties -spring.sql.init.mode=always -``` - -## Create the event payload - -Create a record named `ProductPriceChangedEvent` that represents the structure -of the event payload received from the Kafka topic: - -```java -package com.testcontainers.demo; - -import java.math.BigDecimal; - -record ProductPriceChangedEvent(String productCode, BigDecimal price) {} -``` - -The sender and receiver agree on the following JSON format: - -```json -{ - "productCode": "P100", - "price": 25.0 -} -``` - -## Implement the Kafka listener - -Create `ProductPriceChangedEventHandler.java`, which handles messages from the -`product-price-changes` topic and updates the product price in the database: - -```java -package com.testcontainers.demo; - -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.kafka.annotation.KafkaListener; -import org.springframework.stereotype.Component; -import org.springframework.transaction.annotation.Transactional; - -@Component -@Transactional -class ProductPriceChangedEventHandler { - - private static final Logger log = LoggerFactory.getLogger( - ProductPriceChangedEventHandler.class - ); - - private final ProductRepository productRepository; - - ProductPriceChangedEventHandler(ProductRepository productRepository) { - this.productRepository = productRepository; - } - - @KafkaListener(topics = "product-price-changes", groupId = "demo") - public void handle(ProductPriceChangedEvent event) { - log.info( - "Received a ProductPriceChangedEvent with productCode:{}: ", - event.productCode() - ); - productRepository.updateProductPrice(event.productCode(), event.price()); - } -} -``` - -The `@KafkaListener` annotation specifies the topic name to listen to. Spring -Kafka handles serialization and deserialization based on the properties -configured in `application.properties`. - -## Configure Kafka serialization - -Add the following Kafka properties to -`src/main/resources/application.properties`: - -```properties -######## Kafka Configuration ######### -spring.kafka.bootstrap-servers=localhost:9092 -spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer -spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer - -spring.kafka.consumer.group-id=demo -spring.kafka.consumer.auto-offset-reset=latest -spring.kafka.consumer.key-deserializer=org.apache.kafka.common.serialization.StringDeserializer -spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer -spring.kafka.consumer.properties.spring.json.trusted.packages=com.testcontainers.demo -``` - -The `productCode` key is (de)serialized using `StringSerializer`/`StringDeserializer`, -and the `ProductPriceChangedEvent` value is (de)serialized using -`JsonSerializer`/`JsonDeserializer`. diff --git a/content/guides/testcontainers-java-spring-boot-kafka/run-tests.md b/content/guides/testcontainers-java-spring-boot-kafka/run-tests.md deleted file mode 100644 index 6dd353b2dd02..000000000000 --- a/content/guides/testcontainers-java-spring-boot-kafka/run-tests.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Spring Boot Kafka integration tests and explore next steps. -keywords: testcontainers, java, spring boot, kafka, mysql, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the Kafka and MySQL Docker containers start and all tests pass. -After the tests finish, the containers stop and are removed automatically. - -## Summary - -Testing with real Kafka and MySQL instances gives you more confidence in the -correctness of your code than mocks or embedded alternatives. The -Testcontainers library manages the container lifecycle so that your integration -tests run against the same services you use in production. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/) -- [The simplest way to replace H2 with a real database for testing](https://testcontainers.com/guides/replace-h2-with-real-database-for-testing/) -- [Awaitility](http://www.awaitility.org/) -- [Testcontainers Kafka module](https://java.testcontainers.org/modules/kafka/) -- [Testcontainers MySQL module](https://java.testcontainers.org/modules/databases/mysql/) diff --git a/content/guides/testcontainers-java-spring-boot-kafka/write-tests.md b/content/guides/testcontainers-java-spring-boot-kafka/write-tests.md deleted file mode 100644 index 2994367eec24..000000000000 --- a/content/guides/testcontainers-java-spring-boot-kafka/write-tests.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test the Spring Boot Kafka listener using Testcontainers Kafka and MySQL modules with Awaitility. -keywords: testcontainers, java, spring boot, kafka, mysql, awaitility, integration testing -weight: 20 ---- - -To test the Kafka listener, you need a running Kafka broker and a MySQL -database, plus a started Spring context. Testcontainers spins up both services -in Docker containers and `@DynamicPropertySource` connects them to Spring. - -## Write the test - -Create `ProductPriceChangedEventHandlerTest.java`: - -```java -package com.testcontainers.demo; - -import static java.util.concurrent.TimeUnit.SECONDS; -import static org.assertj.core.api.Assertions.assertThat; -import static org.awaitility.Awaitility.await; - -import java.math.BigDecimal; -import java.time.Duration; -import java.util.Optional; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.kafka.core.KafkaTemplate; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; -import org.springframework.test.context.TestPropertySource; -import org.testcontainers.kafka.ConfluentKafkaContainer; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; - -@SpringBootTest -@TestPropertySource( - properties = { - "spring.kafka.consumer.auto-offset-reset=earliest", - "spring.datasource.url=jdbc:tc:mysql:8.0.32:///db", - } -) -@Testcontainers -class ProductPriceChangedEventHandlerTest { - - @Container - static final ConfluentKafkaContainer kafka = - new ConfluentKafkaContainer("confluentinc/cp-kafka:7.8.0"); - - @DynamicPropertySource - static void overrideProperties(DynamicPropertyRegistry registry) { - registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers); - } - - @Autowired - private KafkaTemplate<String, Object> kafkaTemplate; - - @Autowired - private ProductRepository productRepository; - - @BeforeEach - void setUp() { - Product product = new Product(null, "P100", "Product One", BigDecimal.TEN); - productRepository.save(product); - } - - @Test - void shouldHandleProductPriceChangedEvent() { - ProductPriceChangedEvent event = new ProductPriceChangedEvent( - "P100", - new BigDecimal("14.50") - ); - - kafkaTemplate.send("product-price-changes", event.productCode(), event); - - await() - .pollInterval(Duration.ofSeconds(3)) - .atMost(10, SECONDS) - .untilAsserted(() -> { - Optional<Product> optionalProduct = productRepository.findByCode( - "P100" - ); - assertThat(optionalProduct).isPresent(); - assertThat(optionalProduct.get().getCode()).isEqualTo("P100"); - assertThat(optionalProduct.get().getPrice()) - .isEqualTo(new BigDecimal("14.50")); - }); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` starts the full Spring application context. -- The Testcontainers special JDBC URL (`jdbc:tc:mysql:8.0.32:///db`) in - `@TestPropertySource` spins up a MySQL container and configures it as the - datasource automatically. -- `@Testcontainers` and `@Container` manage the lifecycle of the Kafka - container. `@DynamicPropertySource` registers the Kafka bootstrap servers - with Spring so that the producer and consumer connect to the test container. -- `@BeforeEach` creates a `Product` record in the database before each test. -- The test sends a `ProductPriceChangedEvent` to the `product-price-changes` - topic using `KafkaTemplate`. Spring Boot converts the object to JSON using - `JsonSerializer`. -- Because Kafka message processing is asynchronous, the test uses - [Awaitility](http://www.awaitility.org/) to poll every 3 seconds (up to a - maximum of 10 seconds) until the product price in the database matches the - expected value. -- The property `spring.kafka.consumer.auto-offset-reset` is set to `earliest` - so that the listener consumes messages even if they're sent to the topic - before the listener is ready. This setting is helpful when running tests. diff --git a/content/guides/testcontainers-java-spring-boot-rest-api.md b/content/guides/testcontainers-java-spring-boot-rest-api.md new file mode 100644 index 000000000000..edc177db5bfd --- /dev/null +++ b/content/guides/testcontainers-java-spring-boot-rest-api.md @@ -0,0 +1,342 @@ +--- +title: Testing a Spring Boot REST API with Testcontainers +linkTitle: Spring Boot REST API +description: Learn how to test a Spring Boot REST API using Testcontainers with PostgreSQL and REST Assured. +keywords: testcontainers, java, spring boot, testing, postgresql, rest api, rest assured, jpa +summary: | + Learn how to create a Spring Boot REST API with Spring Data JPA and PostgreSQL, + then test it using Testcontainers and REST Assured. +aliases: + - /guides/testcontainers-java-spring-boot-rest-api/create-project/ + - /guides/testcontainers-java-spring-boot-rest-api/run-tests/ + - /guides/testcontainers-java-spring-boot-rest-api/write-tests/ +params: + tags: [testing] + time: 25 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-testing-spring-boot-rest-api --> + +In this guide, you will learn how to: + +- Create a Spring Boot application with a REST API endpoint +- Use Spring Data JPA with PostgreSQL to store and retrieve data +- Test the REST API using Testcontainers and REST Assured + +## Prerequisites + +- Java 17+ +- Maven or Gradle +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the Spring Boot project + +### Set up the project + +Create a Spring Boot project from [Spring Initializr](https://start.spring.io) +by selecting the **Spring Web**, **Spring Data JPA**, **PostgreSQL Driver**, and +**Testcontainers** starters. + +Alternatively, clone the +[guide repository](https://github.com/testcontainers/tc-guide-testing-spring-boot-rest-api). + +The key dependencies in `pom.xml` are: + +```xml +<properties> + <java.version>17</java.version> + <testcontainers.version>2.0.4</testcontainers.version> +</properties> +<dependencies> + <dependency> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-data-jpa</artifactId> + </dependency> + <dependency> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-web</artifactId> + </dependency> + <dependency> + <groupId>org.postgresql</groupId> + <artifactId>postgresql</artifactId> + <scope>runtime</scope> + </dependency> + <dependency> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-test</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.testcontainers</groupId> + <artifactId>testcontainers-junit-jupiter</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.testcontainers</groupId> + <artifactId>testcontainers-postgresql</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>io.rest-assured</groupId> + <artifactId>rest-assured</artifactId> + <scope>test</scope> + </dependency> +</dependencies> +``` + +Using the Testcontainers BOM (Bill of Materials) is recommended so that you +don't have to repeat the version for every Testcontainers module dependency. + +### Create the JPA entity + +Create `Customer.java`: + +```java +package com.testcontainers.demo; + +import jakarta.persistence.Column; +import jakarta.persistence.Entity; +import jakarta.persistence.GeneratedValue; +import jakarta.persistence.GenerationType; +import jakarta.persistence.Id; +import jakarta.persistence.Table; + +@Entity +@Table(name = "customers") +class Customer { + + @Id + @GeneratedValue(strategy = GenerationType.IDENTITY) + private Long id; + + @Column(nullable = false) + private String name; + + @Column(nullable = false, unique = true) + private String email; + + public Customer() {} + + public Customer(Long id, String name, String email) { + this.id = id; + this.name = name; + this.email = email; + } + + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getEmail() { + return email; + } + + public void setEmail(String email) { + this.email = email; + } +} +``` + +### Create the Spring Data JPA repository + +```java +package com.testcontainers.demo; + +import org.springframework.data.jpa.repository.JpaRepository; + +interface CustomerRepository extends JpaRepository<Customer, Long> {} +``` + +### Add the schema creation script + +Create `src/main/resources/schema.sql`: + +```sql +create table if not exists customers ( + id bigserial not null, + name varchar not null, + email varchar not null, + primary key (id), + UNIQUE (email) +); +``` + +Enable schema initialization in `src/main/resources/application.properties`: + +```properties +spring.sql.init.mode=always +``` + +### Create the REST API endpoint + +Create `CustomerController.java`: + +```java +package com.testcontainers.demo; + +import java.util.List; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RestController; + +@RestController +class CustomerController { + + private final CustomerRepository repo; + + CustomerController(CustomerRepository repo) { + this.repo = repo; + } + + @GetMapping("/api/customers") + List<Customer> getAll() { + return repo.findAll(); + } +} +``` + +## Write tests with Testcontainers + +To test the REST API, you need a running Postgres database and a started +Spring context. Testcontainers spins up Postgres in a Docker container and +`@DynamicPropertySource` connects it to Spring. + +### Write the test + +Create `CustomerControllerTest.java`: + +```java +package com.testcontainers.demo; + +import static io.restassured.RestAssured.given; +import static org.hamcrest.Matchers.hasSize; + +import io.restassured.RestAssured; +import io.restassured.http.ContentType; +import java.util.List; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.test.context.DynamicPropertyRegistry; +import org.springframework.test.context.DynamicPropertySource; +import org.testcontainers.postgresql.PostgreSQLContainer; + +@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) +class CustomerControllerTest { + + @LocalServerPort + private Integer port; + + static PostgreSQLContainer postgres = new PostgreSQLContainer( + "postgres:16-alpine" + ); + + @BeforeAll + static void beforeAll() { + postgres.start(); + } + + @AfterAll + static void afterAll() { + postgres.stop(); + } + + @DynamicPropertySource + static void configureProperties(DynamicPropertyRegistry registry) { + registry.add("spring.datasource.url", postgres::getJdbcUrl); + registry.add("spring.datasource.username", postgres::getUsername); + registry.add("spring.datasource.password", postgres::getPassword); + } + + @Autowired + CustomerRepository customerRepository; + + @BeforeEach + void setUp() { + RestAssured.baseURI = "http://localhost:" + port; + customerRepository.deleteAll(); + } + + @Test + void shouldGetAllCustomers() { + List<Customer> customers = List.of( + new Customer(null, "John", "john@mail.com"), + new Customer(null, "Dennis", "dennis@mail.com") + ); + customerRepository.saveAll(customers); + + given() + .contentType(ContentType.JSON) + .when() + .get("/api/customers") + .then() + .statusCode(200) + .body(".", hasSize(2)); + } +} +``` + +Here's what the test does: + +- `@SpringBootTest` starts the full application on a random port. +- A `PostgreSQLContainer` starts in `@BeforeAll` and stops in `@AfterAll`. +- `@DynamicPropertySource` registers the container's JDBC URL, username, and + password with Spring so that the datasource connects to the test container. +- `@BeforeEach` deletes all customer rows before each test to prevent test + pollution. +- `shouldGetAllCustomers()` inserts two customers, calls `GET /api/customers`, + and verifies the response contains 2 records. + +## Run tests and next steps + +### Run the tests + +```console +$ ./mvnw test +``` + +Or with Gradle: + +```console +$ ./gradlew test +``` + +You should see the Postgres Docker container start and all tests pass. After +the tests finish, the container stops and is removed automatically. + +### Summary + +The Testcontainers library helps you write integration tests by using the same +type of database (Postgres) that you use in production, instead of mocks or +in-memory databases. Because you test against real services, you're free to +refactor code and still verify that the application works as expected. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) +- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) +- [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/) diff --git a/content/guides/testcontainers-java-spring-boot-rest-api/_index.md b/content/guides/testcontainers-java-spring-boot-rest-api/_index.md deleted file mode 100644 index 23dfa0de0bb3..000000000000 --- a/content/guides/testcontainers-java-spring-boot-rest-api/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Testing a Spring Boot REST API with Testcontainers -linkTitle: Spring Boot REST API -description: Learn how to test a Spring Boot REST API using Testcontainers with PostgreSQL and REST Assured. -keywords: testcontainers, java, spring boot, testing, postgresql, rest api, rest assured, jpa -summary: | - Learn how to create a Spring Boot REST API with Spring Data JPA and PostgreSQL, - then test it using Testcontainers and REST Assured. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 25 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-spring-boot-rest-api --> - -In this guide, you will learn how to: - -- Create a Spring Boot application with a REST API endpoint -- Use Spring Data JPA with PostgreSQL to store and retrieve data -- Test the REST API using Testcontainers and REST Assured - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-spring-boot-rest-api/create-project.md b/content/guides/testcontainers-java-spring-boot-rest-api/create-project.md deleted file mode 100644 index a700278a2145..000000000000 --- a/content/guides/testcontainers-java-spring-boot-rest-api/create-project.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with Spring Data JPA, PostgreSQL, and a REST API. -keywords: testcontainers, java, spring boot, rest api, postgresql, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Spring Web**, **Spring Data JPA**, **PostgreSQL Driver**, and -**Testcontainers** starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-spring-boot-rest-api). - -The key dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> -</properties> -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-data-jpa</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-web</artifactId> - </dependency> - <dependency> - <groupId>org.postgresql</groupId> - <artifactId>postgresql</artifactId> - <scope>runtime</scope> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-postgresql</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.rest-assured</groupId> - <artifactId>rest-assured</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -Using the Testcontainers BOM (Bill of Materials) is recommended so that you -don't have to repeat the version for every Testcontainers module dependency. - -## Create the JPA entity - -Create `Customer.java`: - -```java -package com.testcontainers.demo; - -import jakarta.persistence.Column; -import jakarta.persistence.Entity; -import jakarta.persistence.GeneratedValue; -import jakarta.persistence.GenerationType; -import jakarta.persistence.Id; -import jakarta.persistence.Table; - -@Entity -@Table(name = "customers") -class Customer { - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - private Long id; - - @Column(nullable = false) - private String name; - - @Column(nullable = false, unique = true) - private String email; - - public Customer() {} - - public Customer(Long id, String name, String email) { - this.id = id; - this.name = name; - this.email = email; - } - - public Long getId() { - return id; - } - - public void setId(Long id) { - this.id = id; - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - - public String getEmail() { - return email; - } - - public void setEmail(String email) { - this.email = email; - } -} -``` - -## Create the Spring Data JPA repository - -```java -package com.testcontainers.demo; - -import org.springframework.data.jpa.repository.JpaRepository; - -interface CustomerRepository extends JpaRepository<Customer, Long> {} -``` - -## Add the schema creation script - -Create `src/main/resources/schema.sql`: - -```sql -create table if not exists customers ( - id bigserial not null, - name varchar not null, - email varchar not null, - primary key (id), - UNIQUE (email) -); -``` - -Enable schema initialization in `src/main/resources/application.properties`: - -```properties -spring.sql.init.mode=always -``` - -## Create the REST API endpoint - -Create `CustomerController.java`: - -```java -package com.testcontainers.demo; - -import java.util.List; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.RestController; - -@RestController -class CustomerController { - - private final CustomerRepository repo; - - CustomerController(CustomerRepository repo) { - this.repo = repo; - } - - @GetMapping("/api/customers") - List<Customer> getAll() { - return repo.findAll(); - } -} -``` diff --git a/content/guides/testcontainers-java-spring-boot-rest-api/run-tests.md b/content/guides/testcontainers-java-spring-boot-rest-api/run-tests.md deleted file mode 100644 index c8c7ba2acbf8..000000000000 --- a/content/guides/testcontainers-java-spring-boot-rest-api/run-tests.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based Spring Boot integration tests and explore next steps. -keywords: testcontainers, java, spring boot, rest api, postgresql, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the Postgres Docker container start and all tests pass. After -the tests finish, the container stops and is removed automatically. - -## Summary - -The Testcontainers library helps you write integration tests by using the same -type of database (Postgres) that you use in production, instead of mocks or -in-memory databases. Because you test against real services, you're free to -refactor code and still verify that the application works as expected. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) -- [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/) -- [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/) diff --git a/content/guides/testcontainers-java-spring-boot-rest-api/write-tests.md b/content/guides/testcontainers-java-spring-boot-rest-api/write-tests.md deleted file mode 100644 index 2f5f15b1f204..000000000000 --- a/content/guides/testcontainers-java-spring-boot-rest-api/write-tests.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Test the Spring Boot REST API using Testcontainers and REST Assured. -keywords: testcontainers, java, spring boot, rest api, rest assured, integration testing -weight: 20 ---- - -To test the REST API, you need a running Postgres database and a started -Spring context. Testcontainers spins up Postgres in a Docker container and -`@DynamicPropertySource` connects it to Spring. - -## Write the test - -Create `CustomerControllerTest.java`: - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.hamcrest.Matchers.hasSize; - -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import java.util.List; -import org.junit.jupiter.api.AfterAll; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; -import org.testcontainers.postgresql.PostgreSQLContainer; - -@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) -class CustomerControllerTest { - - @LocalServerPort - private Integer port; - - static PostgreSQLContainer postgres = new PostgreSQLContainer( - "postgres:16-alpine" - ); - - @BeforeAll - static void beforeAll() { - postgres.start(); - } - - @AfterAll - static void afterAll() { - postgres.stop(); - } - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("spring.datasource.url", postgres::getJdbcUrl); - registry.add("spring.datasource.username", postgres::getUsername); - registry.add("spring.datasource.password", postgres::getPassword); - } - - @Autowired - CustomerRepository customerRepository; - - @BeforeEach - void setUp() { - RestAssured.baseURI = "http://localhost:" + port; - customerRepository.deleteAll(); - } - - @Test - void shouldGetAllCustomers() { - List<Customer> customers = List.of( - new Customer(null, "John", "john@mail.com"), - new Customer(null, "Dennis", "dennis@mail.com") - ); - customerRepository.saveAll(customers); - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/customers") - .then() - .statusCode(200) - .body(".", hasSize(2)); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` starts the full application on a random port. -- A `PostgreSQLContainer` starts in `@BeforeAll` and stops in `@AfterAll`. -- `@DynamicPropertySource` registers the container's JDBC URL, username, and - password with Spring so that the datasource connects to the test container. -- `@BeforeEach` deletes all customer rows before each test to prevent test - pollution. -- `shouldGetAllCustomers()` inserts two customers, calls `GET /api/customers`, - and verifies the response contains 2 records. diff --git a/content/guides/testcontainers-java-wiremock/_index.md b/content/guides/testcontainers-java-wiremock/_index.md deleted file mode 100644 index 5de620502c56..000000000000 --- a/content/guides/testcontainers-java-wiremock/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Testing REST API integrations using WireMock -linkTitle: WireMock -description: Learn how to test REST API integrations in a Spring Boot application using the Testcontainers WireMock module. -keywords: testcontainers, java, spring boot, testing, wiremock, rest api, rest assured -summary: | - Learn how to create a Spring Boot application that integrates with - external REST APIs, then test those integrations using Testcontainers - and WireMock. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [java] -params: - time: 20 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-wiremock --> - -In this guide, you'll learn how to: - -- Create a Spring Boot application that talks to external REST APIs -- Test external API integrations using WireMock with both the JUnit 5 extension - and the Testcontainers WireMock module - -## Prerequisites - -- Java 17+ -- Maven or Gradle -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-java-wiremock/create-project.md b/content/guides/testcontainers-java-wiremock/create-project.md deleted file mode 100644 index da34c798577f..000000000000 --- a/content/guides/testcontainers-java-wiremock/create-project.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Create the Spring Boot project -linkTitle: Create the project -description: Set up a Spring Boot project with an external REST API integration using WireMock and Testcontainers. -keywords: testcontainers, java, spring boot, wiremock, rest api, project setup -weight: 10 ---- - -## Set up the project - -Create a Spring Boot project from [Spring Initializr](https://start.spring.io) -by selecting the **Spring Web** and **Testcontainers** starters. - -Alternatively, clone the -[guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-wiremock). - -After generating the project, add the **REST Assured**, **WireMock**, and -**WireMock Testcontainers module** libraries as test dependencies. The key -dependencies in `pom.xml` are: - -```xml -<properties> - <java.version>17</java.version> - <testcontainers.version>2.0.4</testcontainers.version> - <wiremock-testcontainers.version>1.0-alpha-13</wiremock-testcontainers.version> -</properties> -<dependencies> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-web</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.testcontainers</groupId> - <artifactId>testcontainers-junit-jupiter</artifactId> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.wiremock</groupId> - <artifactId>wiremock-standalone</artifactId> - <version>3.6.0</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>org.wiremock.integrations.testcontainers</groupId> - <artifactId>wiremock-testcontainers-module</artifactId> - <version>${wiremock-testcontainers.version}</version> - <scope>test</scope> - </dependency> - <dependency> - <groupId>io.rest-assured</groupId> - <artifactId>rest-assured</artifactId> - <scope>test</scope> - </dependency> -</dependencies> -``` - -Using the Testcontainers BOM (Bill of Materials) is recommended so that you -don't have to repeat the version for every Testcontainers module dependency. - -This guide builds an application that manages video albums. A third-party REST -API handles photo assets. For demonstration purposes, the application uses the -publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API -as a photo service. - -The application exposes a `GET /api/albums/{albumId}` endpoint that calls the -photo service to fetch photos for a given album. -[WireMock](https://wiremock.org/) is a tool for building mock APIs. -Testcontainers provides a -[WireMock module](https://testcontainers.com/modules/wiremock/) that runs -WireMock as a Docker container. - -## Create the Album and Photo models - -Create `Album.java` using Java records: - -```java -package com.testcontainers.demo; - -import java.util.List; - -public record Album(Long albumId, List<Photo> photos) {} - -record Photo(Long id, String title, String url, String thumbnailUrl) {} -``` - -## Create the PhotoServiceClient - -Create `PhotoServiceClient.java`, which uses `RestTemplate` to fetch photos for -a given album ID: - -```java -package com.testcontainers.demo; - -import java.util.List; -import org.springframework.beans.factory.annotation.Value; -import org.springframework.boot.web.client.RestTemplateBuilder; -import org.springframework.core.ParameterizedTypeReference; -import org.springframework.http.HttpMethod; -import org.springframework.http.ResponseEntity; -import org.springframework.stereotype.Service; -import org.springframework.web.client.RestTemplate; - -@Service -class PhotoServiceClient { - - private final String baseUrl; - private final RestTemplate restTemplate; - - PhotoServiceClient( - @Value("${photos.api.base-url}") String baseUrl, - RestTemplateBuilder builder - ) { - this.baseUrl = baseUrl; - this.restTemplate = builder.build(); - } - - List<Photo> getPhotos(Long albumId) { - String url = baseUrl + "/albums/{albumId}/photos"; - ResponseEntity<List<Photo>> response = restTemplate.exchange( - url, - HttpMethod.GET, - null, - new ParameterizedTypeReference<>() {}, - albumId - ); - return response.getBody(); - } -} -``` - -The photo service base URL is externalized as a configuration property. Add the -following entry to `src/main/resources/application.properties`: - -```properties -photos.api.base-url=https://jsonplaceholder.typicode.com -``` - -## Create the REST API endpoint - -Create `AlbumController.java`: - -```java -package com.testcontainers.demo; - -import java.util.List; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.http.ResponseEntity; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PathVariable; -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RestController; -import org.springframework.web.client.RestClientResponseException; - -@RestController -@RequestMapping("/api") -class AlbumController { - - private static final Logger logger = LoggerFactory.getLogger( - AlbumController.class - ); - - private final PhotoServiceClient photoServiceClient; - - AlbumController(PhotoServiceClient photoServiceClient) { - this.photoServiceClient = photoServiceClient; - } - - @GetMapping("/albums/{albumId}") - public ResponseEntity<Album> getAlbumById(@PathVariable Long albumId) { - try { - List<Photo> photos = photoServiceClient.getPhotos(albumId); - return ResponseEntity.ok(new Album(albumId, photos)); - } catch (RestClientResponseException e) { - logger.error("Failed to get photos", e); - return new ResponseEntity<>(e.getStatusCode()); - } - } -} -``` - -This endpoint calls the photo service for a given album ID and returns a -response like: - -```json -{ - "albumId": 1, - "photos": [ - { - "id": 51, - "title": "non sunt voluptatem placeat consequuntur rem incidunt", - "url": "https://via.placeholder.com/600/8e973b", - "thumbnailUrl": "https://via.placeholder.com/150/8e973b" - }, - { - "id": 52, - "title": "eveniet pariatur quia nobis reiciendis laboriosam ea", - "url": "https://via.placeholder.com/600/121fa4", - "thumbnailUrl": "https://via.placeholder.com/150/121fa4" - } - ] -} -``` diff --git a/content/guides/testcontainers-java-wiremock/run-tests.md b/content/guides/testcontainers-java-wiremock/run-tests.md deleted file mode 100644 index ea147efbf284..000000000000 --- a/content/guides/testcontainers-java-wiremock/run-tests.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers WireMock integration tests and explore next steps. -keywords: testcontainers, java, spring boot, wiremock, integration testing -weight: 30 ---- - -## Run the tests - -```console -$ ./mvnw test -``` - -Or with Gradle: - -```console -$ ./gradlew test -``` - -You should see the WireMock Docker container start in the console output. It -acts as the photo service, serving mock responses based on the configured -expectations. All tests should pass. - -## Summary - -You built a Spring Boot application that integrates with an external REST API, -then tested that integration using three different approaches: - -- WireMock JUnit 5 extension with inline stubs -- WireMock JUnit 5 extension with JSON mapping files -- Testcontainers WireMock module running WireMock in a Docker container - -Testing at the HTTP protocol level instead of mocking Java methods lets you -catch serialization issues and simulate realistic failure scenarios. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) -- [WireMock documentation](https://wiremock.org/docs/) -- [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/) diff --git a/content/guides/testcontainers-java-wiremock/write-tests.md b/content/guides/testcontainers-java-wiremock/write-tests.md deleted file mode 100644 index c8d0bd915dfa..000000000000 --- a/content/guides/testcontainers-java-wiremock/write-tests.md +++ /dev/null @@ -1,496 +0,0 @@ ---- -title: Write tests with WireMock and Testcontainers -linkTitle: Write tests -description: Test external REST API integrations using WireMock with both the JUnit 5 extension and the Testcontainers WireMock module. -keywords: testcontainers, java, spring boot, wiremock, junit, rest api, integration testing -weight: 20 ---- - -Mocking external API interactions at the HTTP protocol level, rather than -mocking Java methods, lets you verify marshalling and unmarshalling behavior and -simulate network issues. - -## Test using WireMock JUnit 5 extension - -WireMock provides a JUnit 5 extension that starts an in-process WireMock server. -You can configure stub responses using the WireMock Java API. - -Create `AlbumControllerTest.java`: - -```java -package com.testcontainers.demo; - -import static com.github.tomakehurst.wiremock.client.WireMock.aResponse; -import static com.github.tomakehurst.wiremock.client.WireMock.urlMatching; -import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig; -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; -import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; - -import com.github.tomakehurst.wiremock.client.WireMock; -import com.github.tomakehurst.wiremock.junit5.WireMockExtension; -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.extension.RegisterExtension; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.http.MediaType; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; - -@SpringBootTest(webEnvironment = RANDOM_PORT) -class AlbumControllerTest { - - @LocalServerPort - private Integer port; - - @RegisterExtension - static WireMockExtension wireMock = WireMockExtension - .newInstance() - .options(wireMockConfig().dynamicPort()) - .build(); - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("photos.api.base-url", wireMock::baseUrl); - } - - @BeforeEach - void setUp() { - RestAssured.port = port; - } - - @Test - void shouldGetAlbumById() { - Long albumId = 1L; - - wireMock.stubFor( - WireMock - .get(urlMatching("/albums/" + albumId + "/photos")) - .willReturn( - aResponse() - .withHeader("Content-Type", MediaType.APPLICATION_JSON_VALUE) - .withBody( - """ - [ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } - ] - """ - ) - ) - ); - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } - - @Test - void shouldReturnServerErrorWhenPhotoServiceCallFailed() { - Long albumId = 2L; - wireMock.stubFor( - WireMock - .get(urlMatching("/albums/" + albumId + "/photos")) - .willReturn(aResponse().withStatus(500)) - ); - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(500); - } -} -``` - -Here's what the test does: - -- `@SpringBootTest` starts the full application on a random port. -- `@RegisterExtension` creates a `WireMockExtension` that starts WireMock on a - dynamic port. -- `@DynamicPropertySource` overrides `photos.api.base-url` to point at the - WireMock endpoint, so the application talks to WireMock instead of the real - photo service. -- `shouldGetAlbumById()` configures a stub response for - `/albums/{albumId}/photos`, sends a request to the application's - `/api/albums/{albumId}` endpoint, and verifies the response body. -- `shouldReturnServerErrorWhenPhotoServiceCallFailed()` configures WireMock to - return a 500 status and verifies that the application propagates that status to - the caller. - -## Stub using JSON mapping files - -Instead of using the WireMock Java API, you can configure stubs with JSON -mapping files. Create -`src/test/resources/wiremock/mappings/get-album-photos.json`: - -```json -{ - "mappings": [ - { - "request": { - "method": "GET", - "urlPattern": "/albums/([0-9]+)/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "bodyFileName": "album-photos-resp-200.json" - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/2/photos" - }, - "response": { - "status": 500, - "headers": { - "Content-Type": "application/json" - } - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/3/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "jsonBody": [] - } - } - ] -} -``` - -Create the response body file at -`src/test/resources/wiremock/__files/album-photos-resp-200.json`: - -```json -[ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } -] -``` - -Initialize WireMock to load stubs from the mapping files: - -```java -@RegisterExtension -static WireMockExtension wireMockServer = WireMockExtension - .newInstance() - .options( - wireMockConfig().dynamicPort().usingFilesUnderClasspath("wiremock") - ) - .build(); -``` - -With mapping-based stubs in place, create -`AlbumControllerWireMockMappingTests.java`: - -```java -package com.testcontainers.demo; - -import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig; -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; -import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; - -import com.github.tomakehurst.wiremock.junit5.WireMockExtension; -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.extension.RegisterExtension; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; - -@SpringBootTest(webEnvironment = RANDOM_PORT) -class AlbumControllerWireMockMappingTests { - - @LocalServerPort - private Integer port; - - @RegisterExtension - static WireMockExtension wireMockServer = WireMockExtension - .newInstance() - .options( - wireMockConfig().dynamicPort().usingFilesUnderClasspath("wiremock") - ) - .build(); - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("photos.api.base-url", wireMockServer::baseUrl); - } - - @BeforeEach - void setUp() { - RestAssured.port = port; - } - - @Test - void shouldGetAlbumById() { - Long albumId = 1L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } - - @Test - void shouldReturnServerErrorWhenPhotoServiceCallFailed() { - Long albumId = 2L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(500); - } - - @Test - void shouldReturnEmptyPhotos() { - Long albumId = 3L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(0)); - } -} -``` - -The tests don't need inline stub definitions because WireMock loads the mappings -automatically from the classpath. - -## Test using the Testcontainers WireMock module - -The [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) -provisions WireMock as a standalone Docker container, based on -[WireMock Docker](https://github.com/wiremock/wiremock-docker). This approach is -useful when you want complete isolation between the test JVM and the mock server. - -Create a mock configuration file at -`src/test/resources/com/testcontainers/demo/AlbumControllerTestcontainersTests/mocks-config.json`: - -```json -{ - "mappings": [ - { - "request": { - "method": "GET", - "urlPattern": "/albums/([0-9]+)/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "bodyFileName": "album-photos-response.json" - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/2/photos" - }, - "response": { - "status": 500, - "headers": { - "Content-Type": "application/json" - } - } - }, - { - "request": { - "method": "GET", - "urlPattern": "/albums/3/photos" - }, - "response": { - "status": 200, - "headers": { - "Content-Type": "application/json" - }, - "jsonBody": [] - } - } - ] -} -``` - -Create the response body file at -`src/test/resources/com/testcontainers/demo/AlbumControllerTestcontainersTests/album-photos-response.json`: - -```json -[ - { - "id": 1, - "title": "accusamus beatae ad facilis cum similique qui sunt", - "url": "https://via.placeholder.com/600/92c952", - "thumbnailUrl": "https://via.placeholder.com/150/92c952" - }, - { - "id": 2, - "title": "reprehenderit est deserunt velit ipsam", - "url": "https://via.placeholder.com/600/771796", - "thumbnailUrl": "https://via.placeholder.com/150/771796" - } -] -``` - -Create `AlbumControllerTestcontainersTests.java`: - -```java -package com.testcontainers.demo; - -import static io.restassured.RestAssured.given; -import static org.hamcrest.CoreMatchers.is; -import static org.hamcrest.Matchers.hasSize; -import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; - -import io.restassured.RestAssured; -import io.restassured.http.ContentType; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.springframework.boot.test.context.SpringBootTest; -import org.springframework.boot.test.web.server.LocalServerPort; -import org.springframework.test.context.DynamicPropertyRegistry; -import org.springframework.test.context.DynamicPropertySource; -import org.testcontainers.junit.jupiter.Container; -import org.testcontainers.junit.jupiter.Testcontainers; -import org.wiremock.integrations.testcontainers.WireMockContainer; - -@SpringBootTest(webEnvironment = RANDOM_PORT) -@Testcontainers -class AlbumControllerTestcontainersTests { - - @LocalServerPort - private Integer port; - - @Container - static WireMockContainer wiremockServer = new WireMockContainer( - "wiremock/wiremock:3.6.0" - ) - .withMapping( - "photos-by-album", - AlbumControllerTestcontainersTests.class, - "mocks-config.json" - ) - .withFileFromResource( - "album-photos-response.json", - AlbumControllerTestcontainersTests.class, - "album-photos-response.json" - ); - - @DynamicPropertySource - static void configureProperties(DynamicPropertyRegistry registry) { - registry.add("photos.api.base-url", wiremockServer::getBaseUrl); - } - - @BeforeEach - void setUp() { - RestAssured.port = port; - } - - @Test - void shouldGetAlbumById() { - Long albumId = 1L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(2)); - } - - @Test - void shouldReturnServerErrorWhenPhotoServiceCallFailed() { - Long albumId = 2L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(500); - } - - @Test - void shouldReturnEmptyPhotos() { - Long albumId = 3L; - - given() - .contentType(ContentType.JSON) - .when() - .get("/api/albums/{albumId}", albumId) - .then() - .statusCode(200) - .body("albumId", is(albumId.intValue())) - .body("photos", hasSize(0)); - } -} -``` - -Here's what the test does: - -- The `@Testcontainers` and `@Container` annotations start a - `WireMockContainer` using the `wiremock/wiremock:3.6.0` Docker image. -- `withMapping()` loads stub mappings from `mocks-config.json`, and - `withFileFromResource()` loads the response body file. -- `@DynamicPropertySource` overrides `photos.api.base-url` to point at the - WireMock container's base URL. -- The tests don't contain inline stub definitions because WireMock loads them - from the JSON configuration files. diff --git a/content/guides/testcontainers-nodejs-getting-started.md b/content/guides/testcontainers-nodejs-getting-started.md new file mode 100644 index 000000000000..f59c191ae6cb --- /dev/null +++ b/content/guides/testcontainers-nodejs-getting-started.md @@ -0,0 +1,199 @@ +--- +title: Getting started with Testcontainers for Node.js +linkTitle: Testcontainers for Node.js +description: Learn how to use Testcontainers for Node.js to test database interactions with a real PostgreSQL instance. +keywords: testcontainers, nodejs, javascript, testing, postgresql, integration testing, jest +summary: | + Learn how to create a Node.js application and test database interactions + using Testcontainers for Node.js with a real PostgreSQL instance. +aliases: + - /guides/testcontainers-nodejs-getting-started/create-project/ + - /guides/testcontainers-nodejs-getting-started/run-tests/ + - /guides/testcontainers-nodejs-getting-started/write-tests/ +params: + tags: [testing] + time: 15 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-nodejs --> + +In this guide, you will learn how to: + +- Create a Node.js application that stores and retrieves customers from PostgreSQL +- Write integration tests using Testcontainers and Jest +- Run tests against a real PostgreSQL database in a Docker container + +## Prerequisites + +- Node.js 18+ +- npm +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the Node.js project + +### Initialize the project + +Create a new Node.js project: + +```console +$ npm init -y +``` + +Add `pg`, `jest`, and `@testcontainers/postgresql` as dependencies: + +```console +$ npm install pg --save +$ npm install jest @testcontainers/postgresql --save-dev +``` + +### Implement the customer repository + +Create `src/customer-repository.js` with functions to manage customers in +PostgreSQL: + +```javascript +async function createCustomerTable(client) { + const sql = + "CREATE TABLE IF NOT EXISTS customers (id INT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))"; + await client.query(sql); +} + +async function createCustomer(client, customer) { + const sql = "INSERT INTO customers (id, name) VALUES($1, $2)"; + await client.query(sql, [customer.id, customer.name]); +} + +async function getCustomers(client) { + const sql = "SELECT * FROM customers"; + const result = await client.query(sql); + return result.rows; +} + +module.exports = { createCustomerTable, createCustomer, getCustomers }; +``` + +The module provides three functions: + +- `createCustomerTable()` creates the `customers` table if it doesn't exist. +- `createCustomer()` inserts a customer record. +- `getCustomers()` fetches all customer records. + +## Write tests with Testcontainers + +Create `src/customer-repository.test.js` with the test: + +```javascript +const { Client } = require("pg"); +const { PostgreSqlContainer } = require("@testcontainers/postgresql"); +const { + createCustomerTable, + createCustomer, + getCustomers, +} = require("./customer-repository"); + +describe("Customer Repository", () => { + jest.setTimeout(60000); + + let postgresContainer; + let postgresClient; + + beforeAll(async () => { + postgresContainer = await new PostgreSqlContainer().start(); + postgresClient = new Client({ + connectionString: postgresContainer.getConnectionUri(), + }); + await postgresClient.connect(); + await createCustomerTable(postgresClient); + }); + + afterAll(async () => { + await postgresClient.end(); + await postgresContainer.stop(); + }); + + it("should create and return multiple customers", async () => { + const customer1 = { id: 1, name: "John Doe" }; + const customer2 = { id: 2, name: "Jane Doe" }; + + await createCustomer(postgresClient, customer1); + await createCustomer(postgresClient, customer2); + + const customers = await getCustomers(postgresClient); + expect(customers).toEqual([customer1, customer2]); + }); +}); +``` + +Here's what the test does: + +- The `beforeAll` block starts a real PostgreSQL container using + `PostgreSqlContainer`. It then creates a `pg` client connected to the + container and sets up the `customers` table. +- The `afterAll` block closes the client connection and stops the container. +- The test inserts two customers, fetches all customers, and asserts the + results match. + +The test timeout is set to 60 seconds to allow time for the container to start +on the first run (when the Docker image needs to be pulled). + +## Run tests and next steps + +### Run the tests + +Add the test script to `package.json` if it isn't there already: + +```json +{ + "scripts": { + "test": "jest" + } +} +``` + +Then run the tests: + +```console +$ npm test +``` + +You should see output like: + +```text + PASS src/customer-repository.test.js + Customer Repository + ✓ should create and return multiple customers (5 ms) + +Test Suites: 1 passed, 1 total +Tests: 1 passed, 1 total +``` + +To see what Testcontainers is doing under the hood — which containers it +starts, what versions it uses — set the `DEBUG` environment variable: + +```console +$ DEBUG=testcontainers* npm test +``` + +### Summary + +The Testcontainers for Node.js library helps you write integration tests using +the same type of database (Postgres) that you use in production, instead of +mocks. Because you aren't using mocks and instead talk to real services, you're +free to refactor code and still verify that the application works as expected. + +In addition to PostgreSQL, Testcontainers provides dedicated +[modules](https://github.com/testcontainers/testcontainers-node/tree/main/packages/modules) +for many SQL databases, NoSQL databases, messaging queues, and more. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [Testcontainers for Node.js documentation](https://node.testcontainers.org) diff --git a/content/guides/testcontainers-nodejs-getting-started/_index.md b/content/guides/testcontainers-nodejs-getting-started/_index.md deleted file mode 100644 index 891fa3266e59..000000000000 --- a/content/guides/testcontainers-nodejs-getting-started/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Getting started with Testcontainers for Node.js -linkTitle: Testcontainers for Node.js -description: Learn how to use Testcontainers for Node.js to test database interactions with a real PostgreSQL instance. -keywords: testcontainers, nodejs, javascript, testing, postgresql, integration testing, jest -summary: | - Learn how to create a Node.js application and test database interactions - using Testcontainers for Node.js with a real PostgreSQL instance. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [js] -params: - time: 15 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-nodejs --> - -In this guide, you will learn how to: - -- Create a Node.js application that stores and retrieves customers from PostgreSQL -- Write integration tests using Testcontainers and Jest -- Run tests against a real PostgreSQL database in a Docker container - -## Prerequisites - -- Node.js 18+ -- npm -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-nodejs-getting-started/create-project.md b/content/guides/testcontainers-nodejs-getting-started/create-project.md deleted file mode 100644 index e6a6e39f448c..000000000000 --- a/content/guides/testcontainers-nodejs-getting-started/create-project.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Create the Node.js project -linkTitle: Create the project -description: Set up a Node.js project with a PostgreSQL-backed customer repository. -keywords: testcontainers, node.js, nodejs, postgresql, getting started, project setup -weight: 10 ---- - -## Initialize the project - -Create a new Node.js project: - -```console -$ npm init -y -``` - -Add `pg`, `jest`, and `@testcontainers/postgresql` as dependencies: - -```console -$ npm install pg --save -$ npm install jest @testcontainers/postgresql --save-dev -``` - -## Implement the customer repository - -Create `src/customer-repository.js` with functions to manage customers in -PostgreSQL: - -```javascript -async function createCustomerTable(client) { - const sql = - "CREATE TABLE IF NOT EXISTS customers (id INT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))"; - await client.query(sql); -} - -async function createCustomer(client, customer) { - const sql = "INSERT INTO customers (id, name) VALUES($1, $2)"; - await client.query(sql, [customer.id, customer.name]); -} - -async function getCustomers(client) { - const sql = "SELECT * FROM customers"; - const result = await client.query(sql); - return result.rows; -} - -module.exports = { createCustomerTable, createCustomer, getCustomers }; -``` - -The module provides three functions: - -- `createCustomerTable()` creates the `customers` table if it doesn't exist. -- `createCustomer()` inserts a customer record. -- `getCustomers()` fetches all customer records. diff --git a/content/guides/testcontainers-nodejs-getting-started/run-tests.md b/content/guides/testcontainers-nodejs-getting-started/run-tests.md deleted file mode 100644 index 798dd24a3090..000000000000 --- a/content/guides/testcontainers-nodejs-getting-started/run-tests.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, node.js, nodejs, postgresql, integration testing, run tests -weight: 30 ---- - -## Run the tests - -Add the test script to `package.json` if it isn't there already: - -```json -{ - "scripts": { - "test": "jest" - } -} -``` - -Then run the tests: - -```console -$ npm test -``` - -You should see output like: - -```text - PASS src/customer-repository.test.js - Customer Repository - ✓ should create and return multiple customers (5 ms) - -Test Suites: 1 passed, 1 total -Tests: 1 passed, 1 total -``` - -To see what Testcontainers is doing under the hood — which containers it -starts, what versions it uses — set the `DEBUG` environment variable: - -```console -$ DEBUG=testcontainers* npm test -``` - -## Summary - -The Testcontainers for Node.js library helps you write integration tests using -the same type of database (Postgres) that you use in production, instead of -mocks. Because you aren't using mocks and instead talk to real services, you're -free to refactor code and still verify that the application works as expected. - -In addition to PostgreSQL, Testcontainers provides dedicated -[modules](https://github.com/testcontainers/testcontainers-node/tree/main/packages/modules) -for many SQL databases, NoSQL databases, messaging queues, and more. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [Testcontainers for Node.js documentation](https://node.testcontainers.org) diff --git a/content/guides/testcontainers-nodejs-getting-started/write-tests.md b/content/guides/testcontainers-nodejs-getting-started/write-tests.md deleted file mode 100644 index 61f591f232de..000000000000 --- a/content/guides/testcontainers-nodejs-getting-started/write-tests.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Write integration tests using Testcontainers for Node.js and Jest with a real PostgreSQL database. -keywords: testcontainers, node.js, nodejs, postgresql, jest, integration testing -weight: 20 ---- - -Create `src/customer-repository.test.js` with the test: - -```javascript -const { Client } = require("pg"); -const { PostgreSqlContainer } = require("@testcontainers/postgresql"); -const { - createCustomerTable, - createCustomer, - getCustomers, -} = require("./customer-repository"); - -describe("Customer Repository", () => { - jest.setTimeout(60000); - - let postgresContainer; - let postgresClient; - - beforeAll(async () => { - postgresContainer = await new PostgreSqlContainer().start(); - postgresClient = new Client({ - connectionString: postgresContainer.getConnectionUri(), - }); - await postgresClient.connect(); - await createCustomerTable(postgresClient); - }); - - afterAll(async () => { - await postgresClient.end(); - await postgresContainer.stop(); - }); - - it("should create and return multiple customers", async () => { - const customer1 = { id: 1, name: "John Doe" }; - const customer2 = { id: 2, name: "Jane Doe" }; - - await createCustomer(postgresClient, customer1); - await createCustomer(postgresClient, customer2); - - const customers = await getCustomers(postgresClient); - expect(customers).toEqual([customer1, customer2]); - }); -}); -``` - -Here's what the test does: - -- The `beforeAll` block starts a real PostgreSQL container using - `PostgreSqlContainer`. It then creates a `pg` client connected to the - container and sets up the `customers` table. -- The `afterAll` block closes the client connection and stops the container. -- The test inserts two customers, fetches all customers, and asserts the - results match. - -The test timeout is set to 60 seconds to allow time for the container to start -on the first run (when the Docker image needs to be pulled). diff --git a/content/guides/testcontainers-python-getting-started.md b/content/guides/testcontainers-python-getting-started.md new file mode 100644 index 000000000000..a2cf612e56e9 --- /dev/null +++ b/content/guides/testcontainers-python-getting-started.md @@ -0,0 +1,310 @@ +--- +title: Getting started with Testcontainers for Python +linkTitle: Testcontainers for Python +description: Learn how to use Testcontainers for Python to test database interactions with a real PostgreSQL instance. +keywords: testcontainers, python, testing, postgresql, integration testing, pytest +summary: | + Learn how to create a Python application and test database interactions + using Testcontainers for Python with a real PostgreSQL instance. +aliases: + - /guides/testcontainers-python-getting-started/create-project/ + - /guides/testcontainers-python-getting-started/run-tests/ + - /guides/testcontainers-python-getting-started/write-tests/ +params: + tags: [testing] + time: 15 minutes +--- + + +<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-python --> + +In this guide, you will learn how to: + +- Create a Python application that uses PostgreSQL to store customer data +- Use `psycopg` to interact with the database +- Write integration tests using `testcontainers-python` and `pytest` +- Manage container lifecycle with pytest fixtures + +## Prerequisites + +- Python 3.10+ +- pip +- A Docker environment supported by Testcontainers + +> [!NOTE] +> If you're new to Testcontainers, visit the +> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about +> Testcontainers and the benefits of using it. + +## Create the Python project + +### Initialize the project + +Start by creating a Python project with a virtual environment: + +```console +$ mkdir tc-python-demo +$ cd tc-python-demo +$ python3 -m venv venv +$ source venv/bin/activate +``` + +This guide uses [psycopg3](https://www.psycopg.org/psycopg3/) to interact +with the Postgres database, [pytest](https://pytest.org/) for testing, and +[testcontainers-python](https://testcontainers-python.readthedocs.io/) for +running a PostgreSQL database in a container. + +Install the dependencies: + +```console +$ pip install "psycopg[binary]" pytest testcontainers[postgres] +$ pip freeze > requirements.txt +``` + +The `pip freeze` command generates a `requirements.txt` file so that others +can install the same package versions using `pip install -r requirements.txt`. + +### Create the database helper + +Create a `db/connection.py` file with a function to get a database connection: + +```python +import os + +import psycopg + + +def get_connection(): + host = os.getenv("DB_HOST", "localhost") + port = os.getenv("DB_PORT", "5432") + username = os.getenv("DB_USERNAME", "postgres") + password = os.getenv("DB_PASSWORD", "postgres") + database = os.getenv("DB_NAME", "postgres") + return psycopg.connect(f"host={host} dbname={database} user={username} password={password} port={port}") +``` + +Instead of hard-coding the database connection parameters, the function uses +environment variables. This makes it possible to run the application in +different environments without changing code. + +### Create the business logic + +Create a `customers/customers.py` file and define the `Customer` class: + +```python +class Customer: + def __init__(self, cust_id, name, email): + self.id = cust_id + self.name = name + self.email = email + + def __str__(self): + return f"Customer({self.id}, {self.name}, {self.email})" +``` + +Add a `create_table()` function to create the `customers` table: + +```python +from db.connection import get_connection + + +def create_table(): + with get_connection() as conn: + with conn.cursor() as cur: + cur.execute(""" + CREATE TABLE customers ( + id serial PRIMARY KEY, + name varchar not null, + email varchar not null unique) + """) + conn.commit() +``` + +The function obtains a database connection using `get_connection()` and creates +the `customers` table. The `with` statement automatically closes the connection +when done. + +Add the remaining CRUD functions: + +```python +def create_customer(name, email): + with get_connection() as conn: + with conn.cursor() as cur: + cur.execute( + "INSERT INTO customers (name, email) VALUES (%s, %s)", (name, email)) + conn.commit() + + +def get_all_customers() -> list[Customer]: + with get_connection() as conn: + with conn.cursor() as cur: + cur.execute("SELECT * FROM customers") + return [Customer(cid, name, email) for cid, name, email in cur] + + +def get_customer_by_email(email) -> Customer: + with get_connection() as conn: + with conn.cursor() as cur: + cur.execute("SELECT id, name, email FROM customers WHERE email = %s", (email,)) + (cid, name, email) = cur.fetchone() + return Customer(cid, name, email) + + +def delete_all_customers(): + with get_connection() as conn: + with conn.cursor() as cur: + cur.execute("DELETE FROM customers") + conn.commit() +``` + +> [!NOTE] +> To keep it straightforward for this guide, each function creates a new +> connection. In a real-world application, use a connection pool to reuse +> connections. + +## Write tests with Testcontainers + +You'll create a PostgreSQL container using Testcontainers and use it for all +the tests. Before each test, you'll delete all customer records so that tests +run with a clean database. + +### Set up pytest fixtures + +This guide uses [pytest fixtures](https://pytest.org/en/stable/how-to/fixtures.html) +for setup and teardown logic. A recommended approach is to use +[finalizers](https://pytest.org/en/stable/how-to/fixtures.html#adding-finalizers-directly) +to guarantee cleanup runs even if setup fails: + +```python +@pytest.fixture +def setup(request): + # setup code + + def cleanup(): + # teardown code + + request.addfinalizer(cleanup) + return some_value +``` + +### Create the test file + +Create a `tests/__init__.py` file with empty content to enable pytest +[auto-discovery](https://pytest.org/explanation/goodpractices.html#test-discovery). + +Then create `tests/test_customers.py` with the fixtures: + +```python +import os +import pytest +from testcontainers.postgres import PostgresContainer + +from customers import customers + +postgres = PostgresContainer("postgres:16-alpine") + + +@pytest.fixture(scope="module", autouse=True) +def setup(request): + postgres.start() + + def remove_container(): + postgres.stop() + + request.addfinalizer(remove_container) + os.environ["DB_CONN"] = postgres.get_connection_url() + os.environ["DB_HOST"] = postgres.get_container_host_ip() + os.environ["DB_PORT"] = str(postgres.get_exposed_port(5432)) + os.environ["DB_USERNAME"] = postgres.username + os.environ["DB_PASSWORD"] = postgres.password + os.environ["DB_NAME"] = postgres.dbname + customers.create_table() + + +@pytest.fixture(scope="function", autouse=True) +def setup_data(): + customers.delete_all_customers() +``` + +Here's what the fixtures do: + +- The `setup` fixture has `scope="module"`, so it runs once for all tests in + the file. It starts a PostgreSQL container, sets environment variables with + the connection details, and creates the `customers` table. A cleanup + function removes the container after all tests complete. +- The `setup_data` fixture has `scope="function"`, so it runs before every + test. It deletes all records to give each test a clean database. + +### Write the tests + +Add the test functions to the same file: + +```python +def test_get_all_customers(): + customers.create_customer("Siva", "siva@gmail.com") + customers.create_customer("James", "james@gmail.com") + customers_list = customers.get_all_customers() + assert len(customers_list) == 2 + + +def test_get_customer_by_email(): + customers.create_customer("John", "john@gmail.com") + customer = customers.get_customer_by_email("john@gmail.com") + assert customer.name == "John" + assert customer.email == "john@gmail.com" +``` + +- `test_get_all_customers()` inserts two customer records, fetches all + customers, and asserts the count. +- `test_get_customer_by_email()` inserts a customer, fetches it by email, and + asserts the details. + +Because `setup_data` deletes all records before each test, the tests can run in +any order. + +## Run tests and next steps + +### Run the tests + +Run the tests using pytest: + +```console +$ pytest -v +``` + +You should see output similar to: + +```text +============================= test session starts ============================== +platform linux -- Python 3.13.x, pytest-9.x.x +collected 2 items + +tests/test_customers.py::test_get_all_customers PASSED [ 50%] +tests/test_customers.py::test_get_customer_by_email PASSED [100%] + +============================== 2 passed in 1.90s =============================== +``` + +The tests run against a real PostgreSQL database instead of mocks, which gives +more confidence in the implementation. + +### Summary + +The Testcontainers for Python library helps you write integration tests using the +same type of database (Postgres) that you use in production, instead of mocks. +Because you aren't using mocks and instead talk to real services, you're free +to refactor code and still verify that the application works as expected. + +In addition to PostgreSQL, Testcontainers for Python provides modules for many +SQL databases, NoSQL databases, messaging queues, and more. You can use +Testcontainers to run any containerized dependency for your tests. + +To learn more about Testcontainers, visit the +[Testcontainers overview](https://testcontainers.com/getting-started/). + +### Further reading + +- [testcontainers-python documentation](https://testcontainers-python.readthedocs.io/) +- [Getting started with Testcontainers for Go](/guides/testcontainers-go-getting-started/) +- [Getting started with Testcontainers for Java](https://testcontainers.com/guides/getting-started-with-testcontainers-for-java/) +- [Getting started with Testcontainers for Node.js](https://testcontainers.com/guides/getting-started-with-testcontainers-for-nodejs/) diff --git a/content/guides/testcontainers-python-getting-started/_index.md b/content/guides/testcontainers-python-getting-started/_index.md deleted file mode 100644 index 6a00efa89fcc..000000000000 --- a/content/guides/testcontainers-python-getting-started/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Getting started with Testcontainers for Python -linkTitle: Testcontainers for Python -description: Learn how to use Testcontainers for Python to test database interactions with a real PostgreSQL instance. -keywords: testcontainers, python, testing, postgresql, integration testing, pytest -summary: | - Learn how to create a Python application and test database interactions - using Testcontainers for Python with a real PostgreSQL instance. -toc_min: 1 -toc_max: 2 -tags: [testing-with-docker] -languages: [python] -params: - time: 15 minutes ---- - -<!-- Source: https://github.com/testcontainers/tc-guide-getting-started-with-testcontainers-for-python --> - -In this guide, you will learn how to: - -- Create a Python application that uses PostgreSQL to store customer data -- Use `psycopg` to interact with the database -- Write integration tests using `testcontainers-python` and `pytest` -- Manage container lifecycle with pytest fixtures - -## Prerequisites - -- Python 3.10+ -- pip -- A Docker environment supported by Testcontainers - -> [!NOTE] -> If you're new to Testcontainers, visit the -> [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about -> Testcontainers and the benefits of using it. diff --git a/content/guides/testcontainers-python-getting-started/create-project.md b/content/guides/testcontainers-python-getting-started/create-project.md deleted file mode 100644 index 022cfad7016e..000000000000 --- a/content/guides/testcontainers-python-getting-started/create-project.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Create the Python project -linkTitle: Create the project -description: Set up a Python project with a PostgreSQL-backed customer service. -keywords: testcontainers, python, postgresql, getting started, project setup -weight: 10 ---- - -## Initialize the project - -Start by creating a Python project with a virtual environment: - -```console -$ mkdir tc-python-demo -$ cd tc-python-demo -$ python3 -m venv venv -$ source venv/bin/activate -``` - -This guide uses [psycopg3](https://www.psycopg.org/psycopg3/) to interact -with the Postgres database, [pytest](https://pytest.org/) for testing, and -[testcontainers-python](https://testcontainers-python.readthedocs.io/) for -running a PostgreSQL database in a container. - -Install the dependencies: - -```console -$ pip install "psycopg[binary]" pytest testcontainers[postgres] -$ pip freeze > requirements.txt -``` - -The `pip freeze` command generates a `requirements.txt` file so that others -can install the same package versions using `pip install -r requirements.txt`. - -## Create the database helper - -Create a `db/connection.py` file with a function to get a database connection: - -```python -import os - -import psycopg - - -def get_connection(): - host = os.getenv("DB_HOST", "localhost") - port = os.getenv("DB_PORT", "5432") - username = os.getenv("DB_USERNAME", "postgres") - password = os.getenv("DB_PASSWORD", "postgres") - database = os.getenv("DB_NAME", "postgres") - return psycopg.connect(f"host={host} dbname={database} user={username} password={password} port={port}") -``` - -Instead of hard-coding the database connection parameters, the function uses -environment variables. This makes it possible to run the application in -different environments without changing code. - -## Create the business logic - -Create a `customers/customers.py` file and define the `Customer` class: - -```python -class Customer: - def __init__(self, cust_id, name, email): - self.id = cust_id - self.name = name - self.email = email - - def __str__(self): - return f"Customer({self.id}, {self.name}, {self.email})" -``` - -Add a `create_table()` function to create the `customers` table: - -```python -from db.connection import get_connection - - -def create_table(): - with get_connection() as conn: - with conn.cursor() as cur: - cur.execute(""" - CREATE TABLE customers ( - id serial PRIMARY KEY, - name varchar not null, - email varchar not null unique) - """) - conn.commit() -``` - -The function obtains a database connection using `get_connection()` and creates -the `customers` table. The `with` statement automatically closes the connection -when done. - -Add the remaining CRUD functions: - -```python -def create_customer(name, email): - with get_connection() as conn: - with conn.cursor() as cur: - cur.execute( - "INSERT INTO customers (name, email) VALUES (%s, %s)", (name, email)) - conn.commit() - - -def get_all_customers() -> list[Customer]: - with get_connection() as conn: - with conn.cursor() as cur: - cur.execute("SELECT * FROM customers") - return [Customer(cid, name, email) for cid, name, email in cur] - - -def get_customer_by_email(email) -> Customer: - with get_connection() as conn: - with conn.cursor() as cur: - cur.execute("SELECT id, name, email FROM customers WHERE email = %s", (email,)) - (cid, name, email) = cur.fetchone() - return Customer(cid, name, email) - - -def delete_all_customers(): - with get_connection() as conn: - with conn.cursor() as cur: - cur.execute("DELETE FROM customers") - conn.commit() -``` - -> [!NOTE] -> To keep it straightforward for this guide, each function creates a new -> connection. In a real-world application, use a connection pool to reuse -> connections. diff --git a/content/guides/testcontainers-python-getting-started/run-tests.md b/content/guides/testcontainers-python-getting-started/run-tests.md deleted file mode 100644 index 427756bb6b98..000000000000 --- a/content/guides/testcontainers-python-getting-started/run-tests.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Run tests and next steps -linkTitle: Run tests -description: Run your Testcontainers-based integration tests and explore next steps. -keywords: testcontainers, python, postgresql, integration testing, run tests -weight: 30 ---- - -## Run the tests - -Run the tests using pytest: - -```console -$ pytest -v -``` - -You should see output similar to: - -```text -============================= test session starts ============================== -platform linux -- Python 3.13.x, pytest-9.x.x -collected 2 items - -tests/test_customers.py::test_get_all_customers PASSED [ 50%] -tests/test_customers.py::test_get_customer_by_email PASSED [100%] - -============================== 2 passed in 1.90s =============================== -``` - -The tests run against a real PostgreSQL database instead of mocks, which gives -more confidence in the implementation. - -## Summary - -The Testcontainers for Python library helps you write integration tests using the -same type of database (Postgres) that you use in production, instead of mocks. -Because you aren't using mocks and instead talk to real services, you're free -to refactor code and still verify that the application works as expected. - -In addition to PostgreSQL, Testcontainers for Python provides modules for many -SQL databases, NoSQL databases, messaging queues, and more. You can use -Testcontainers to run any containerized dependency for your tests. - -To learn more about Testcontainers, visit the -[Testcontainers overview](https://testcontainers.com/getting-started/). - -## Further reading - -- [testcontainers-python documentation](https://testcontainers-python.readthedocs.io/) -- [Getting started with Testcontainers for Go](/guides/testcontainers-go-getting-started/) -- [Getting started with Testcontainers for Java](https://testcontainers.com/guides/getting-started-with-testcontainers-for-java/) -- [Getting started with Testcontainers for Node.js](https://testcontainers.com/guides/getting-started-with-testcontainers-for-nodejs/) diff --git a/content/guides/testcontainers-python-getting-started/write-tests.md b/content/guides/testcontainers-python-getting-started/write-tests.md deleted file mode 100644 index 870c0d97f2d7..000000000000 --- a/content/guides/testcontainers-python-getting-started/write-tests.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Write tests with Testcontainers -linkTitle: Write tests -description: Write integration tests using testcontainers-python and pytest with a real PostgreSQL database. -keywords: testcontainers, python, postgresql, pytest, integration testing -weight: 20 ---- - -You'll create a PostgreSQL container using Testcontainers and use it for all -the tests. Before each test, you'll delete all customer records so that tests -run with a clean database. - -## Set up pytest fixtures - -This guide uses [pytest fixtures](https://pytest.org/en/stable/how-to/fixtures.html) -for setup and teardown logic. A recommended approach is to use -[finalizers](https://pytest.org/en/stable/how-to/fixtures.html#adding-finalizers-directly) -to guarantee cleanup runs even if setup fails: - -```python -@pytest.fixture -def setup(request): - # setup code - - def cleanup(): - # teardown code - - request.addfinalizer(cleanup) - return some_value -``` - -## Create the test file - -Create a `tests/__init__.py` file with empty content to enable pytest -[auto-discovery](https://pytest.org/explanation/goodpractices.html#test-discovery). - -Then create `tests/test_customers.py` with the fixtures: - -```python -import os -import pytest -from testcontainers.postgres import PostgresContainer - -from customers import customers - -postgres = PostgresContainer("postgres:16-alpine") - - -@pytest.fixture(scope="module", autouse=True) -def setup(request): - postgres.start() - - def remove_container(): - postgres.stop() - - request.addfinalizer(remove_container) - os.environ["DB_CONN"] = postgres.get_connection_url() - os.environ["DB_HOST"] = postgres.get_container_host_ip() - os.environ["DB_PORT"] = str(postgres.get_exposed_port(5432)) - os.environ["DB_USERNAME"] = postgres.username - os.environ["DB_PASSWORD"] = postgres.password - os.environ["DB_NAME"] = postgres.dbname - customers.create_table() - - -@pytest.fixture(scope="function", autouse=True) -def setup_data(): - customers.delete_all_customers() -``` - -Here's what the fixtures do: - -- The `setup` fixture has `scope="module"`, so it runs once for all tests in - the file. It starts a PostgreSQL container, sets environment variables with - the connection details, and creates the `customers` table. A cleanup - function removes the container after all tests complete. -- The `setup_data` fixture has `scope="function"`, so it runs before every - test. It deletes all records to give each test a clean database. - -## Write the tests - -Add the test functions to the same file: - -```python -def test_get_all_customers(): - customers.create_customer("Siva", "siva@gmail.com") - customers.create_customer("James", "james@gmail.com") - customers_list = customers.get_all_customers() - assert len(customers_list) == 2 - - -def test_get_customer_by_email(): - customers.create_customer("John", "john@gmail.com") - customer = customers.get_customer_by_email("john@gmail.com") - assert customer.name == "John" - assert customer.email == "john@gmail.com" -``` - -- `test_get_all_customers()` inserts two customer records, fetches all - customers, and asserts the count. -- `test_get_customer_by_email()` inserts a customer, fetches it by email, and - asserts the details. - -Because `setup_data` deletes all records before each test, the tests can run in -any order. diff --git a/content/guides/text-classification.md b/content/guides/text-classification.md deleted file mode 100644 index 81df374797a9..000000000000 --- a/content/guides/text-classification.md +++ /dev/null @@ -1,440 +0,0 @@ ---- -title: Build a text recognition app -linkTitle: Text classification -keywords: nlp, natural language processing, sentiment analysis, python, nltk, scikit-learn, text classification -description: Learn how to build and run a text recognition application using Python, NLTK, scikit-learn, and Docker. -summary: | - This guide details how to containerize text classification models using - Docker. -tags: [ai] -languages: [python] -aliases: - - /guides/use-case/nlp/text-classification/ -params: - time: 20 minutes ---- - -## Overview - -In this guide, you'll learn how to create and run a text recognition -application. You'll build the application using Python with scikit-learn and the -Natural Language Toolkit (NLTK). Then you'll set up the environment and run the -application using Docker. - -The application analyzes the sentiment of a user's input text using NLTK's -SentimentIntensityAnalyzer. It lets the user input text, which is then processed -to determine its sentiment, classifying it as either positive or negative. Also, -it displays the accuracy and a detailed classification report of its sentiment -analysis model based on a predefined dataset. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Get the sample application - -1. Open a terminal, and clone the sample application's repository using the - following command. - - ```console - $ git clone https://github.com/harsh4870/Docker-NLP.git - ``` - -2. Verify that you cloned the repository. - - You should see the following files in your `Docker-NLP` directory. - - ```text - 01_sentiment_analysis.py - 02_name_entity_recognition.py - 03_text_classification.py - 04_text_summarization.py - 05_language_translation.py - entrypoint.sh - requirements.txt - Dockerfile - README.md - ``` - -## Explore the application code - -The source code for the text classification application is in the `Docker-NLP/03_text_classification.py` file. Open `03_text_classification.py` in a text or code editor to explore its contents in the following steps. - -1. Import the required libraries. - - ```python - import nltk - from nltk.sentiment import SentimentIntensityAnalyzer - from sklearn.metrics import accuracy_score, classification_report - from sklearn.model_selection import train_test_split - import ssl - ``` - - - `nltk`: A popular Python library for natural language processing (NLP). - - `SentimentIntensityAnalyzer`: A component of `nltk` for sentiment analysis. - - `accuracy_score`, `classification_report`: Functions from scikit-learn for - evaluating the model. - - `train_test_split`: Function from scikit-learn to split datasets into - training and testing sets. - - `ssl`: Used for handling SSL certificate issues which might occur while - downloading data for `nltk`. - -2. Handle SSL certificate verification. - - ```python - try: - _create_unverified_https_context = ssl._create_unverified_context - except AttributeError: - pass - else: - ssl._create_default_https_context = _create_unverified_https_context - ``` - - This block is a workaround for certain environments where downloading data - through NLTK might fail due to SSL certificate verification issues. It's - telling Python to ignore SSL certificate verification for HTTPS requests. - -3. Download NLTK resources. - - ```python - nltk.download('vader_lexicon') - ``` - - The `vader_lexicon` is a lexicon used by the `SentimentIntensityAnalyzer` for - sentiment analysis. - -4. Define text for testing and corresponding labels. - - ```python - texts = [...] - labels = [0, 1, 2, 0, 1, 2] - ``` - - This section defines a small dataset of texts and their corresponding labels (0 for positive, 1 for negative, and 2 for spam). - -5. Split the test data. - - ```python - X_train, X_test, y_train, y_test = train_test_split(texts, labels, test_size=0.2, random_state=42) - ``` - - This part splits the dataset into training and testing sets, with 20% of data - as the test set. As this application uses a pre-trained model, it doesn't - train the model. - -6. Set up sentiment analysis. - - ```python - sia = SentimentIntensityAnalyzer() - ``` - - This code initializes the `SentimentIntensityAnalyzer` to analyze the - sentiment of text. - -7. Generate predictions and classifications for the test data. - - ```python - vader_predictions = [sia.polarity_scores(text)["compound"] for text in X_test] - threshold = 0.2 - vader_classifications = [0 if score > threshold else 1 for score in vader_predictions] - ``` - - This part generates sentiment scores for each text in the test set and classifies them as positive or negative based on a threshold. - -8. Evaluate the model. - - ```python - accuracy = accuracy_score(y_test, vader_classifications) - report_vader = classification_report(y_test, vader_classifications, zero_division='warn') - ``` - - This part calculates the accuracy and classification report for the predictions. - -9. Specify the main execution block. - - ```python - if __name__ == "__main__": - ``` - - This Python idiom ensures that the following code block runs only if this - script is the main program. It provides flexibility, allowing the script to - function both as a standalone program and as an imported module. - -10. Create an infinite loop for continuous input. - - ```python - while True: - input_text = input("Enter the text for classification (type 'exit' to end): ") - - if input_text.lower() == 'exit': - print("Exiting...") - break - ``` - - This while loop runs indefinitely until it's explicitly broken. It lets the - user continuously enter text for entity recognition until they decide to - exit. - -11. Analyze the text. - - ```python - input_text_score = sia.polarity_scores(input_text)["compound"] - input_text_classification = 0 if input_text_score > threshold else 1 - ``` - -12. Print the VADER Classification Report and the sentiment analysis. - - ```python - print(f"Accuracy: {accuracy:.2f}") - print("\nVADER Classification Report:") - print(report_vader) - - print(f"\nTest Text (Positive): '{input_text}'") - print(f"Predicted Sentiment: {'Positive' if input_text_classification == 0 else 'Negative'}") - ``` - -13. Create `requirements.txt`. The sample application already contains the - `requirements.txt` file to specify the necessary packages that the - application imports. Open `requirements.txt` in a code or text editor to - explore its contents. - - ```text - # 01 sentiment_analysis - nltk==3.6.5 - - ... - - # 03 text_classification - scikit-learn==1.3.2 - - ... - ``` - - Both the `nltk` and `scikit-learn` modules are required for the text - classification application. - -## Explore the application environment - -You'll use Docker to run the application in a container. Docker lets you -containerize the application, providing a consistent and isolated environment -for running it. This means the application will operate as intended within its -Docker container, regardless of the underlying system differences. - -To run the application in a container, a Dockerfile is required. A Dockerfile is -a text document that contains all the commands you would call on the command -line to assemble an image. An image is a read-only template with instructions -for creating a Docker container. - -The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents. - -The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/). - -1. Specify the base image. - - ```dockerfile - FROM python:3.8-slim - ``` - - This command sets the foundation for the build. `python:3.8-slim` is a - lightweight version of the Python 3.8 image, optimized for size and speed. - Using this slim image reduces the overall size of your Docker image, leading - to quicker downloads and less surface area for security vulnerabilities. This - is particularly useful for a Python-based application where you might not - need the full standard Python image. - -2. Set the working directory. - - ```dockerfile - WORKDIR /app - ``` - - `WORKDIR` sets the current working directory within the Docker image. By - setting it to `/app`, you ensure that all subsequent commands in the - Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also - helps in organizing your Docker image, as all application-related files are - contained in a specific directory. - -3. Copy the requirements file into the image. - - ```dockerfile - COPY requirements.txt /app - ``` - - The `COPY` command transfers the `requirements.txt` file from - your local machine into the Docker image. This file lists all Python - dependencies required by the application. Copying it into the container - lets the next command (`RUN pip install`) install these dependencies - inside the image environment. - -4. Install the Python dependencies in the image. - - ```dockerfile - RUN pip install --no-cache-dir -r requirements.txt - ``` - - This line uses `pip`, Python's package installer, to install the packages - listed in `requirements.txt`. The `--no-cache-dir` option disables - the cache, which reduces the size of the Docker image by not storing the - unnecessary cache data. - -5. Run additional commands. - - ```dockerfile - RUN python -m spacy download en_core_web_sm - ``` - - This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile. - -6. Copy the application code into the image. - - ```dockerfile - COPY *.py /app - COPY entrypoint.sh /app - ``` - - These commands copy your Python scripts and the `entrypoint.sh` script into - the image's `/app` directory. This is crucial because the container needs - these scripts to run the application. The `entrypoint.sh` script is - particularly important as it dictates how the application starts inside the - container. - -7. Set permissions for the `entrypoint.sh` script. - - ```dockerfile - RUN chmod +x /app/entrypoint.sh - ``` - - This command modifies the file permissions of `entrypoint.sh`, making it - executable. This step is necessary to ensure that the Docker container can - run this script to start the application. - -8. Set the entry point. - - ```dockerfile - ENTRYPOINT ["/app/entrypoint.sh"] - ``` - - The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` - as its default executable. This means that when the container starts, it - automatically executes the script. - - You can explore the `entrypoint.sh` script by opening it in a code or text - editor. As the sample contains several applications, the script lets you - specify which application to run when the container starts. - -## Run the application - -To run the application using Docker: - -1. Build the image. - - In a terminal, run the following command inside the directory of where the `Dockerfile` is located. - - ```console - $ docker build -t basic-nlp . - ``` - - The following is a break down of the command: - - - `docker build`: This is the primary command used to build a Docker image - from a Dockerfile and a context. The context is typically a set of files at - a specified location, often the directory containing the Dockerfile. - - `-t basic-nlp`: This is an option for tagging the image. The `-t` flag - stands for tag. It assigns a name to the image, which in this case is - `basic-nlp`. Tags are a convenient way to reference images later, - especially when pushing them to a registry or running containers. - - `.`: This is the last part of the command and specifies the build context. - The period (`.`) denotes the current directory. Docker will look for a - Dockerfile in this directory. The build context (the current directory, in - this case) is sent to the Docker daemon to enable the build. It includes - all the files and subdirectories in the specified directory. - - For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/). - - Docker outputs several logs to your console as it builds the image. You'll - see it download and install the dependencies. Depending on your network - connection, this may take several minutes. Docker does have a caching - feature, so subsequent builds can be faster. The console will - return to the prompt when it's complete. - -2. Run the image as a container. - - In a terminal, run the following command. - - ```console - $ docker run -it basic-nlp 03_text_classification.py - ``` - - The following is a break down of the command: - - - `docker run`: This is the primary command used to run a new container from - a Docker image. - - `-it`: This is a combination of two options: - - `-i` or `--interactive`: This keeps the standard input (STDIN) open even - if not attached. It lets the container remain running in the - foreground and be interactive. - - `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a - terminal, like a command prompt or a shell. It's what lets you - interact with the application inside the container. - - `basic-nlp`: This specifies the name of the Docker image to use for - creating the container. In this case, it's the image named `basic-nlp` that - you created with the `docker build` command. - - `03_text_classification.py`: This is the script you want to run inside the - Docker container. It gets passed to the `entrypoint.sh` script, which runs - it when the container starts. - - For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/). - - > [!NOTE] - > - > For Windows users, you may get an error when running the container. Verify - > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers). - - You will see the following in your console after the container starts. - - ```console - Enter the text for classification (type 'exit' to end): - ``` - -3. Test the application. - - Enter some text to get the text classification. - - ```console - Enter the text for classification (type 'exit' to end): I love containers! - Accuracy: 1.00 - - VADER Classification Report: - precision recall f1-score support - - 0 1.00 1.00 1.00 1 - 1 1.00 1.00 1.00 1 - - accuracy 1.00 2 - macro avg 1.00 1.00 1.00 2 - weighted avg 1.00 1.00 1.00 2 - - Test Text (Positive): 'I love containers!' - Predicted Sentiment: Positive - ``` - -## Summary - -In this guide, you learned how to build and run a text classification -application. You learned how to build the application using Python with -scikit-learn and NLTK. Then you learned how to set up the environment and run -the application using Docker. - -Related information: - -- [Docker CLI reference](/reference/cli/docker/) -- [Dockerfile reference](/reference/dockerfile/) -- [Natural Language Toolkit](https://www.nltk.org/) -- [Python documentation](https://docs.python.org/3/) -- [scikit-learn](https://scikit-learn.org/) - -## Next steps - -Explore more [natural language processing guides](./_index.md). diff --git a/content/guides/text-summarization.md b/content/guides/text-summarization.md deleted file mode 100644 index e4657f072b12..000000000000 --- a/content/guides/text-summarization.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Build a text summarization app -linkTitle: Text summarization -keywords: nlp, natural language processing, text summarization, python, bert extractive summarizer -description: Learn how to build and run a text summarization application using Python, Bert Extractive Summarizer, and Docker. -summary: | - This guide shows how to containerize text summarization models with Docker. -tags: [ai] -languages: [python] -aliases: - - /guides/use-case/nlp/text-summarization/ -params: - time: 20 minutes ---- - -## Overview - -In this guide, you'll learn how to build and run a text summarization -application. You'll build the application using Python with the Bert Extractive -Summarizer, and then set up the environment and run the application using -Docker. - -The sample text summarization application uses the Bert Extractive Summarizer. -This tool utilizes the HuggingFace Pytorch transformers library to run -extractive summarizations. This works by first embedding the sentences, then -running a clustering algorithm, finding the sentences that are closest to the -cluster's centroids. - -## Prerequisites - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. -- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. - -## Get the sample application - -1. Open a terminal, and clone the sample application's repository using the - following command. - - ```console - $ git clone https://github.com/harsh4870/Docker-NLP.git - ``` - -2. Verify that you cloned the repository. - - You should see the following files in your `Docker-NLP` directory. - - ```text - 01_sentiment_analysis.py - 02_name_entity_recognition.py - 03_text_classification.py - 04_text_summarization.py - 05_language_translation.py - entrypoint.sh - requirements.txt - Dockerfile - README.md - ``` - -## Explore the application code - -The source code for the text summarization application is in the `Docker-NLP/04_text_summarization.py` file. Open `04_text_summarization.py` in a text or code editor to explore its contents in the following steps. - -1. Import the required libraries. - - ```python - from summarizer import Summarizer - ``` - - This line of code imports the `Summarizer` class from the `summarizer` - package, essential for your text summarization application. The summarizer - module implements the Bert Extractive Summarizer, leveraging the HuggingFace - Pytorch transformers library, renowned in the NLP (Natural Language - Processing) domain. This library offers access to pre-trained models like - BERT, which revolutionized language understanding tasks, including text - summarization. - - The BERT model, or Bidirectional Encoder Representations from Transformers, - excels in understanding context in language, using a mechanism known as - "attention" to determine the significance of words in a sentence. For - summarization, the model embeds sentences and then uses a clustering - algorithm to identify key sentences, those closest to the centroids of these - clusters, effectively capturing the main ideas of the text. - -2. Specify the main execution block. - - ```python - if __name__ == "__main__": - ``` - - This Python idiom ensures that the following code block runs only if this - script is the main program. It provides flexibility, allowing the script to - function both as a standalone program and as an imported module. - -3. Create an infinite loop for continuous input. - - ```python - while True: - input_text = input("Enter the text for summarization (type 'exit' to end): ") - - if input_text.lower() == 'exit': - print("Exiting...") - break - ``` - - An infinite loop continuously prompts you for text - input, ensuring interactivity. The loop breaks when you type `exit`, allowing - you to control the application flow effectively. - -4. Create an instance of Summarizer. - - ```python - bert_model = Summarizer() - ``` - - Here, you create an instance of the Summarizer class named `bert_model`. This - instance is now ready to perform the summarization task using the BERT model, - simplifying the complex processes of embedding sentences and clustering into - an accessible interface. - -5. Generate and print a summary. - - ```python - summary = bert_model(input_text) - print(summary) - ``` - - Your input text is processed by the bert_model instance, which then returns a - summarized version. This demonstrates the power of Python's high-level - libraries in enabling complex operations with minimal code. - -6. Create `requirements.txt`. The sample application already contains the - `requirements.txt` file to specify the necessary modules that the - application imports. Open `requirements.txt` in a code or text editor to - explore its contents. - - ```text - ... - - # 04 text_summarization - bert-extractive-summarizer==0.10.1 - - ... - - torch==2.1.2 - ``` - - The `bert-extractive-summarizer` and `torch` modules are required for the - text summarization application. The summarizer module generates a summary of - the input text. This requires PyTorch because the underlying BERT model, - which is used for generating the summary, is implemented in PyTorch. - -## Explore the application environment - -You'll use Docker to run the application in a container. Docker lets you -containerize the application, providing a consistent and isolated environment -for running it. This means the application will operate as intended within its -Docker container, regardless of the underlying system differences. - -To run the application in a container, a Dockerfile is required. A Dockerfile is -a text document that contains all the commands you would call on the command -line to assemble an image. An image is a read-only template with instructions -for creating a Docker container. - -The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents. - -The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/). - -1. Specify the base image. - - ```dockerfile - FROM python:3.8-slim - ``` - - This command sets the foundation for the build. `python:3.8-slim` is a - lightweight version of the Python 3.8 image, optimized for size and speed. - Using this slim image reduces the overall size of your Docker image, leading - to quicker downloads and less surface area for security vulnerabilities. This - is particularly useful for a Python-based application where you might not - need the full standard Python image. - -2. Set the working directory. - - ```dockerfile - WORKDIR /app - ``` - - `WORKDIR` sets the current working directory within the Docker image. By - setting it to `/app`, you ensure that all subsequent commands in the - Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also - helps in organizing your Docker image, as all application-related files are - contained in a specific directory. - -3. Copy the requirements file into the image. - - ```dockerfile - COPY requirements.txt /app - ``` - - The `COPY` command transfers the `requirements.txt` file from - your local machine into the Docker image. This file lists all Python - dependencies required by the application. Copying it into the container - lets the next command (`RUN pip install`) to install these dependencies - inside the image environment. - -4. Install the Python dependencies in the image. - - ```dockerfile - RUN pip install --no-cache-dir -r requirements.txt - ``` - - This line uses `pip`, Python's package installer, to install the packages - listed in `requirements.txt`. The `--no-cache-dir` option disables - the cache, which reduces the size of the Docker image by not storing the - unnecessary cache data. - -5. Run additional commands. - - ```dockerfile - RUN python -m spacy download en_core_web_sm - ``` - - This step is specific to NLP applications that require the spaCy library. It - downloads the `en_core_web_sm` model, which is a small English language model - for spaCy. While not needed for this app, it's included for compatibility - with other NLP applications that might use this Dockerfile. - -6. Copy the application code into the image. - - ```dockerfile - COPY *.py /app - COPY entrypoint.sh /app - ``` - - These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container. - -7. Set permissions for the `entrypoint.sh` script. - - ```dockerfile - RUN chmod +x /app/entrypoint.sh - ``` - - This command modifies the file permissions of `entrypoint.sh`, making it - executable. This step is necessary to ensure that the Docker container can - run this script to start the application. - -8. Set the entry point. - - ```dockerfile - ENTRYPOINT ["/app/entrypoint.sh"] - ``` - - The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` - as its default executable. This means that when the container starts, it - automatically executes the script. - - You can explore the `entrypoint.sh` script by opening it in a code or text - editor. As the sample contains several applications, the script lets you - specify which application to run when the container starts. - -## Run the application - -To run the application using Docker: - -1. Build the image. - - In a terminal, run the following command inside the directory of where the `Dockerfile` is located. - - ```console - $ docker build -t basic-nlp . - ``` - - The following is a break down of the command: - - - `docker build`: This is the primary command used to build a Docker image - from a Dockerfile and a context. The context is typically a set of files at - a specified location, often the directory containing the Dockerfile. - - `-t basic-nlp`: This is an option for tagging the image. The `-t` flag - stands for tag. It assigns a name to the image, which in this case is - `basic-nlp`. Tags are a convenient way to reference images later, - especially when pushing them to a registry or running containers. - - `.`: This is the last part of the command and specifies the build context. - The period (`.`) denotes the current directory. Docker will look for a - Dockerfile in this directory. The build context (the current directory, in - this case) is sent to the Docker daemon to enable the build. It includes - all the files and subdirectories in the specified directory. - - For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/). - - Docker outputs several logs to your console as it builds the image. You'll - see it download and install the dependencies. Depending on your network - connection, this may take several minutes. Docker does have a caching - feature, so subsequent builds can be faster. The console will - return to the prompt when it's complete. - -2. Run the image as a container. - - In a terminal, run the following command. - - ```console - $ docker run -it basic-nlp 04_text_summarization.py - ``` - - The following is a break down of the command: - - - `docker run`: This is the primary command used to run a new container from - a Docker image. - - `-it`: This is a combination of two options: - - `-i` or `--interactive`: This keeps the standard input (STDIN) open even - if not attached. It lets the container remain running in the - foreground and be interactive. - - `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a - terminal, like a command prompt or a shell. It's what lets you - interact with the application inside the container. - - `basic-nlp`: This specifies the name of the Docker image to use for - creating the container. In this case, it's the image named `basic-nlp` that - you created with the `docker build` command. - - `04_text_summarization.py`: This is the script you want to run inside the - Docker container. It gets passed to the `entrypoint.sh` script, which runs - it when the container starts. - - For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/). - - > [!NOTE] - > - > For Windows users, you may get an error when running the container. Verify - > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers). - - You will see the following in your console after the container starts. - - ```console - Enter the text for summarization (type 'exit' to end): - ``` - -3. Test the application. - - Enter some text to get the text summarization. - - ```console - Enter the text for summarization (type 'exit' to end): Artificial intelligence (AI) is a branch of computer science that aims to create machines capable of intelligent behavior. These machines are designed to mimic human cognitive functions such as learning, problem-solving, and decision-making. AI technologies can be classified into two main types: narrow or weak AI, which is designed for a particular task, and general or strong AI, which possesses the ability to understand, learn, and apply knowledge across various domains. One of the most popular approaches in AI is machine learning, where algorithms are trained on large datasets to recognize patterns and make predictions. - - Artificial intelligence (AI) is a branch of computer science that aims to create machines capable of intelligent behavior. These machines are designed to mimic human cognitive functions such as learning, problem-solving, and decision-making. - ``` - -## Summary - -In this guide, you learned how to build and run a text summarization -application. You learned how to build the application using Python with Bert -Extractive Summarizer, and then set up the environment and run the application -using Docker. - -Related information: - -- [Docker CLI reference](/reference/cli/docker/) -- [Dockerfile reference](/reference/dockerfile/) -- [Bert Extractive Summarizer](https://github.com/dmmiller612/bert-extractive-summarizer) -- [PyTorch](https://pytorch.org/) -- [Python documentation](https://docs.python.org/3/) - -## Next steps - -Explore more [natural language processing guides](./_index.md). diff --git a/content/guides/traefik.md b/content/guides/traefik.md index 9130763bc669..c91c42032935 100644 --- a/content/guides/traefik.md +++ b/content/guides/traefik.md @@ -4,8 +4,8 @@ description: &desc Use Traefik to easily route traffic between multiple containe keywords: traefik, container-supported development linktitle: HTTP routing with Traefik summary: *desc -tags: [networking, dhi] params: + tags: [deployment] time: 20 minutes --- diff --git a/content/guides/vuejs.md b/content/guides/vuejs.md new file mode 100644 index 000000000000..5eff6cfb3c14 --- /dev/null +++ b/content/guides/vuejs.md @@ -0,0 +1,823 @@ +--- +title: Vue.js language-specific guide +linkTitle: Vue.js +description: Containerize and develop Vue.js apps using Docker +keywords: getting started, vue, vuejs docker, language, Dockerfile +summary: | + This guide explains how to containerize Vue.js applications using Docker. +aliases: + - /frameworks/vue/ + - /guides/vuejs/configure-github-actions/ + - /guides/vuejs/containerize/ + - /guides/vuejs/deploy/ + - /guides/vuejs/develop/ + - /guides/vuejs/run-tests/ +params: + tags: [languages] + time: 20 minutes +--- + +The Vue.js language-specific guide shows you how to containerize an Vue.js application using Docker, following best practices for creating efficient, production-ready containers. + +[Vue.js](https://vuejs.org/) is a progressive and flexible framework for building modern, interactive web applications. However, as applications scale, managing dependencies, environments, and deployments can become complex. Docker simplifies these challenges by providing a consistent, isolated environment for both development and production. + +> **Acknowledgment** +> +> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and highly skilled Front-end engineer, Kristiyan brings exceptional expertise in modern web development, Docker, and DevOps. His hands-on approach and clear, actionable guidance make this guide an essential resource for developers aiming to build, optimize, and secure Vue.js applications with Docker. + +--- + +## What will you learn? + +In this guide, you will learn how to: + +- Containerize and run an Vue.js application using Docker. +- Set up a local development environment for Vue.js inside a container. +- Run tests for your Vue.js application within a Docker container. + +You'll start by containerizing an existing Vue.js application and work your way up to production-level deployments. + +--- + +## Prerequisites + +Before you begin, ensure you have a working knowledge of: + +- Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). +- Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. +- Familiarity with [Vue.js](https://vuejs.org/) fundamentals. +- Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +Once you've completed the Vue.js getting started modules, you’ll be fully prepared to containerize your own Vue.js application using the detailed examples and best practices outlined in this guide. + +## Containerize an Vue.js Application + +### Prerequisites + +Before you begin, make sure the following tools are installed and available on your system: + +- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). +- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. + +> **New to Docker?** +> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. + +--- + +### Overview + +This guide walks you through the complete process of containerizing an Vue.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. + +By the end of this guide, you will: + +- Containerize an Vue.js application using Docker. +- Create and optimize a Dockerfile for production builds. +- Use multi-stage builds to minimize image size. +- Serve the application efficiently with a custom Nginx configuration. +- Build secure and maintainable Docker images by following best practices. + +--- + +### Get the sample application + +Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command +to clone the git repository: + +```console +$ git clone https://github.com/kristiyan-velkov/docker-vuejs-sample +``` + +--- + +### Build the Docker image + +Vue.js is a front-end framework that compiles into static assets, so the Dockerfile is customized to align with how Vue.js applications are built and efficiently served in a production environment. + +> [!TIP] +> +> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. + +#### Step 1: Create the Dockerfile + +Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). + +Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). + +> [!IMPORTANT] +> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. +> +> Official Node.js Docker Images: https://hub.docker.com/_/node + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} +Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Node.js DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/node:24-alpine3.22-dev + ``` + +3. Pull the Nginx DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev + ``` + +In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images. + +```dockerfile +# ========================================= +# Stage 1: Build the Vue.js Application +# ========================================= +# Use a lightweight DHI Node.js image for building +FROM dhi.io/node:24-alpine3.22-dev AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the Vue.js application +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html + +# Use a built-in non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default Nginx container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +{{< /tab >}} +{{< tab name="Using the Docker Official Image" >}} + +Create a file named `Dockerfile` with the following contents: + +```dockerfile +# ========================================= +# Stage 1: Build the Vue.js Application +# ========================================= +ARG NODE_VERSION=24.12.0-alpine +ARG NGINX_VERSION=alpine3.22 + +# Use a lightweight Node.js image for building (customizable via ARG) +FROM node:${NODE_VERSION} AS builder + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies using npm ci (ensures a clean, reproducible install) +RUN --mount=type=cache,target=/root/.npm npm ci + +# Copy the rest of the application source code into the container +COPY . . + +# Build the Vue.js application +RUN npm run build + +# ========================================= +# Stage 2: Prepare Nginx to Serve Static Files +# ========================================= + +FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner + +# Copy custom Nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static build output from the build stage to Nginx's default HTML serving directory +COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html + +# Use a built-in non-root user for security best practices +USER nginx + +# Expose port 8080 to allow HTTP traffic +# Note: The default Nginx container now listens on port 8080 instead of 80 +EXPOSE 8080 + +# Start Nginx directly with custom config +ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] +CMD ["-g", "daemon off;"] +``` + +> [!NOTE] +> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. +> Running as a non-root user in the final image: +> +> - Reduces the attack surface +> - Aligns with Docker’s recommendations for container hardening +> - Helps comply with stricter security policies in production environments + +{{< /tab >}} +{{< /tabs >}} + +#### Step 2: Create the compose.yaml file + +Create a file named `compose.yaml` with the following contents: + +```yaml {collapse=true,title=compose.yaml} +services: + server: + build: + context: . + ports: + - 8080:8080 +``` + +#### Step 3: Create the .dockerignore file + +The `.dockerignore` file plays a crucial role in optimizing your Docker image by specifying which files and directories should be excluded from the build context. + +> [!NOTE] +> This helps: +> +> - Reduce image size +> - Speed up the build process +> - Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. +> +> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). + +Create a file named `.dockerignore` with the following contents: + +```dockerignore +# ------------------------------- +# Dependency directories +# ------------------------------- +node_modules/ + +# ------------------------------- +# Production and build outputs +# ------------------------------- +dist/ +out/ +build/ +public/build/ + +# ------------------------------- +# Vite, VuePress, and cache dirs +# ------------------------------- +.vite/ +.vitepress/ +.cache/ +.tmp/ + +# ------------------------------- +# Test output and coverage +# ------------------------------- +coverage/ +reports/ +jest/ +cypress/ +cypress/screenshots/ +cypress/videos/ + +# ------------------------------- +# Environment and config files +# ------------------------------- +*.env* +!.env.production # Keep production env if needed +*.local +*.log + +# ------------------------------- +# TypeScript artifacts +# ------------------------------- +*.tsbuildinfo + +# ------------------------------- +# Editor and IDE config +# ------------------------------- +.vscode/ +.idea/ +*.swp + +# ------------------------------- +# System files +# ------------------------------- +.DS_Store +Thumbs.db + +# ------------------------------- +# Lockfiles (optional) +# ------------------------------- +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# ------------------------------- +# Git files +# ------------------------------- +.git/ +.gitignore + +# ------------------------------- +# Docker-related files +# ------------------------------- +Dockerfile +.dockerignore +docker-compose.yml +docker-compose.override.yml +``` + +#### Step 4: Create the `nginx.conf` file + +To serve your Vue.js application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. + +Create a file named `nginx.conf` in the root of your project directory, and add the following content: + +> [!NOTE] +> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/). + +```nginx +worker_processes auto; +pid /tmp/nginx.pid; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + charset utf-8; + + access_log off; + error_log /dev/stderr warn; + + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + keepalive_requests 1000; + + gzip on; + gzip_comp_level 6; + gzip_proxied any; + gzip_min_length 256; + gzip_vary on; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml; + + server { + listen 8080; + server_name localhost; + + root /usr/share/nginx/html; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { + expires 1y; + access_log off; + add_header Cache-Control "public, immutable"; + add_header X-Content-Type-Options nosniff; + } + + location /assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + add_header X-Content-Type-Options nosniff; + } + + error_page 404 /index.html; + } +} +``` + +#### Step 5: Build the Vue.js application image + +With your custom configuration in place, you're now ready to build the Docker image for your Vue.js application. + +The updated setup includes: + +- The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Vue.js. +- Efficient multi-stage Docker build, ensuring a small and secure final image. + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-vuejs-sample/ +│ ├── Dockerfile +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +Now that your Dockerfile is configured, you can build the Docker image for your Vue.js application. + +> [!NOTE] +> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). + +Run the following command from the root of your project: + +```console +$ docker build --tag docker-vuejs-sample . +``` + +What this command does: + +- Uses the Dockerfile in the current directory (.) +- Packages the application and its dependencies into a Docker image +- Tags the image as docker-vuejs-sample so you can reference it later + +#### Step 6: View local images + +After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. + +To list all locally available Docker images, run the following command: + +```console +$ docker images +``` + +Example Output: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +docker-vuejs-sample latest 8c9c199179d4 14 seconds ago 76.2MB +``` + +This output provides key details about your images: + +- **Repository** – The name assigned to the image. +- **Tag** – A version label that helps identify different builds (e.g., latest). +- **Image ID** – A unique identifier for the image. +- **Created** – The timestamp indicating when the image was built. +- **Size** – The total disk space used by the image. + +If the build was successful, you should see `docker-vuejs-sample` image listed. + +--- + +### Run the containerized application + +In the previous step, you created a Dockerfile for your Vue.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. + +Inside the `docker-vuejs-sample` directory, run the following command in a +terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple Vue.js web application. + +Press `ctrl+c` in the terminal to stop your application. + +#### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `docker-vuejs-sample` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see your Vue.js application running in the browser. + +To confirm that the container is running, use `docker ps` command: + +```console +$ docker ps +``` + +This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. + +Example Output: + +```shell +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +37a1fa85e4b0 docker-vuejs-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-vuejs-sample-server-1 +``` + +To stop the application, run: + +```console +$ docker compose down +``` + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +## Use containers for Vue.js development + +### Prerequisites + +Complete [Containerize Vue.js application](#containerize-an-vuejs-application). + +--- + +### Overview + +In this section, you'll set up both production and development environments for your Vue.js application using Docker Compose. This approach streamlines your workflow—delivering a lightweight, static site via Nginx in production, and providing a fast, live-reloading dev server with Compose Watch for efficient local development. + +You’ll learn how to: + +- Configure isolated environments: Set up separate containers optimized for production and development use cases. +- Live-reload in development: Use Compose Watch to automatically sync file changes, enabling real-time updates without manual intervention. +- Preview and debug with ease: Develop inside containers with a seamless preview and debug experience—no rebuilds required after every change. + +--- + +### Automatically update services (development mode) + +Leverage Compose Watch to enable real-time file synchronization between your local machine and the containerized Vue.js development environment. This powerful feature eliminates the need to manually rebuild or restart containers, providing a fast, seamless, and efficient development workflow. + +With Compose Watch, your code updates are instantly reflected inside the container—perfect for rapid testing, debugging, and live previewing changes. + +### Step 1: Create a development Dockerfile + +Create a file named `Dockerfile.dev` in your project root with the following content: + +```dockerfile +# ========================================= +# Stage 1: Develop the Vue.js Application +# ========================================= +ARG NODE_VERSION=24.12.0-alpine + +# Use a lightweight Node.js image for development +FROM node:${NODE_VERSION} AS dev + +# Set environment variable to indicate development mode +ENV NODE_ENV=development + +# Set the working directory inside the container +WORKDIR /app + +# Copy package-related files first to leverage Docker's caching mechanism +COPY package.json package-lock.json* ./ + +# Install project dependencies +RUN --mount=type=cache,target=/root/.npm npm install + +# Copy the rest of the application source code into the container +COPY . . + +# Change ownership of the application directory to the node user +RUN chown -R node:node /app + +# Switch to the node user +USER node + +# Expose the port used by the Vite development server +EXPOSE 5173 + +# Use a default command, can be overridden in Docker compose.yml file +CMD [ "npm", "run", "dev", "--", "--host" ] + +``` + +This file sets up a lightweight development environment for your Vue.js application using the dev server. + +#### Step 2: Update your `compose.yaml` file + +Open your `compose.yaml` file and define two services: one for production (`vuejs-prod`) and one for development (`vuejs-dev`). + +Here’s an example configuration for an Vue.js application: + +```yaml +services: + vuejs-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-vuejs-sample + ports: + - "8080:8080" + + vuejs-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "5173:5173" + develop: + watch: + - path: ./src + target: /app/src + action: sync + - path: ./package.json + target: /app/package.json + action: restart + - path: ./vite.config.js + target: /app/vite.config.js + action: restart +``` + +- The `vuejs-prod` service builds and serves your static production app using Nginx. +- The `vuejs-dev` service runs your Vue.js development server with live reload and hot module replacement. +- `watch` triggers file sync with Compose Watch. + +> [!NOTE] +> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). + +After completing the previous steps, your project directory should now contain the following files: + +```text +├── docker-vuejs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 4: Start Compose Watch + +Run the following command from the project root to start the container in watch mode + +```console +$ docker compose watch vuejs-dev +``` + +#### Step 5: Test Compose Watch with Vue.js + +To confirm that Compose Watch is functioning correctly: + +1. Open the `src/App.vue` file in your text editor. + +2. Locate the following line: + + ```html + <HelloWorld msg="You did it!" /> + ``` + +3. Change it to: + + ```html + <HelloWorld msg="Hello from Docker Compose Watch" /> + ``` + +4. Save the file. + +5. Open your browser at [http://localhost:5173](http://localhost:5173). + +You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. + +--- + +## Run vue.js tests in a container + +### Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize Vue.js application](#containerize-an-vuejs-application). + +### Overview + +Testing is a critical part of the development process. In this section, you'll learn how to: + +- Run unit tests using Vitest inside a Docker container. +- Use Docker Compose to run tests in an isolated, reproducible environment. + +You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — together with [@vue/test-utils](https://test-utils.vuejs.org/) to write unit tests that validate your component logic, props, events, and reactive behavior. + +This setup ensures your Vue.js components are tested in an environment that mirrors how users actually interact with your application. + +--- + +### Run tests during development + +`docker-vuejs-sample` application includes a sample test file at location: + +```console +$ src/components/__tests__/HelloWorld.spec.ts +``` + +This test uses Vitest and Vue Test Utils to verify the behavior of the HelloWorld component. + +--- + +#### Step 1: Update compose.yaml + +Add a new service named `vuejs-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment. + +```yaml {hl_lines="22-26",linenos=true} +services: + vuejs-prod: + build: + context: . + dockerfile: Dockerfile + image: docker-vuejs-sample + ports: + - "8080:8080" + + vuejs-dev: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "5173:5173" + develop: + watch: + - action: sync + path: . + target: /app + + vuejs-test: + build: + context: . + dockerfile: Dockerfile.dev + command: ["npm", "run", "test:unit"] +``` + +The vuejs-test service reuses the same `Dockerfile.dev` used for [development](#use-containers-for-vuejs-development) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. + +After completing the previous steps, your project directory should contain the following files: + +```text +├── docker-vuejs-sample/ +│ ├── Dockerfile +│ ├── Dockerfile.dev +│ ├── .dockerignore +│ ├── compose.yaml +│ └── nginx.conf +``` + +#### Step 2: Run the tests + +To execute your test suite inside the container, run the following command from your project root: + +```console +$ docker compose run --rm vuejs-test +``` + +This command will: + +- Start the `vuejs-test` service defined in your `compose.yaml` file. +- Execute the `npm run test` script using the same environment as development. +- Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. + +You should see output similar to the following: + +```shell +Test Files: 1 passed (1) +Tests: 1 passed (1) +Start at: 16:50:55 +Duration: 718ms +``` + +> [!NOTE] +> For more information about Compose commands, see the [Compose CLI +> reference](/reference/cli/docker/compose/). + +--- + +### Summary + +In this section, you learned how to run unit tests for your Vue.js application inside a Docker container using Vitest and Docker Compose. + +What you accomplished: + +- Created a `vuejs-test` service in `compose.yaml` to isolate test execution. +- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. +- Ran tests inside the container using `docker compose run --rm vuejs-test`. +- Ensured reliable, repeatable testing across environments without depending on your local machine setup. + +--- + +### Related resources + +Explore official references and best practices to sharpen your Docker testing workflow: + +- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. +- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. +- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. +- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. diff --git a/content/guides/vuejs/_index.md b/content/guides/vuejs/_index.md deleted file mode 100644 index 8bd306da6c4b..000000000000 --- a/content/guides/vuejs/_index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Vue.js language-specific guide -linkTitle: Vue.js -description: Containerize and develop Vue.js apps using Docker -keywords: getting started, vue, vuejs docker, language, Dockerfile -summary: | - This guide explains how to containerize Vue.js applications using Docker. -toc_min: 1 -toc_max: 2 -languages: [js] -tags: [frameworks, dhi] -aliases: - - /frameworks/vue/ -params: - time: 20 minutes - ---- - -The Vue.js language-specific guide shows you how to containerize an Vue.js application using Docker, following best practices for creating efficient, production-ready containers. - -[Vue.js](https://vuejs.org/) is a progressive and flexible framework for building modern, interactive web applications. However, as applications scale, managing dependencies, environments, and deployments can become complex. Docker simplifies these challenges by providing a consistent, isolated environment for both development and production. - -> -> **Acknowledgment** -> -> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and highly skilled Front-end engineer, Kristiyan brings exceptional expertise in modern web development, Docker, and DevOps. His hands-on approach and clear, actionable guidance make this guide an essential resource for developers aiming to build, optimize, and secure Vue.js applications with Docker. ---- - -## What will you learn? - -In this guide, you will learn how to: - -- Containerize and run an Vue.js application using Docker. -- Set up a local development environment for Vue.js inside a container. -- Run tests for your Vue.js application within a Docker container. -- Configure a CI/CD pipeline using GitHub Actions for your containerized app. -- Deploy the containerized Vue.js application to a local Kubernetes cluster for testing and debugging. - -You'll start by containerizing an existing Vue.js application and work your way up to production-level deployments. - ---- - -## Prerequisites - -Before you begin, ensure you have a working knowledge of: - -- Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). -- Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts. -- Familiarity with [Vue.js](https://vuejs.org/) fundamentals. -- Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. - -Once you've completed the Vue.js getting started modules, you’ll be fully prepared to containerize your own Vue.js application using the detailed examples and best practices outlined in this guide. \ No newline at end of file diff --git a/content/guides/vuejs/configure-github-actions.md b/content/guides/vuejs/configure-github-actions.md deleted file mode 100644 index 1fb6704f0784..000000000000 --- a/content/guides/vuejs/configure-github-actions.md +++ /dev/null @@ -1,320 +0,0 @@ ---- -title: Automate your builds with GitHub Actions -linkTitle: GitHub Actions CI -weight: 60 -keywords: CI/CD, GitHub( Actions), Vue.js -description: Learn how to configure CI/CD using GitHub Actions for your Vue.js application. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize an Vue.js application](containerize.md). - -You must also have: -- A [GitHub](https://github.com/signup) account. -- A verified [Docker Hub](https://hub.docker.com/signup) account. - ---- - -## Overview - -In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically: - -- Build your Vue.js application inside a Docker container. -- Run tests in a consistent environment. -- Push the production-ready image to [Docker Hub](https://hub.docker.com). - ---- - -## Connect your GitHub repository to Docker Hub - -To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository. - -### Step 1: Generate Docker Hub credentials and set GitHub secrets - -1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com) - 1. Go to your **Docker Hub account → Account Settings → Security**. - 2. Generate a new Access Token with **Read/Write** permissions. - 3. Name it something like `docker-vuejs-sample`. - 4. Copy and save the token — you’ll need it in Step 4. - -2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/) - 1. Go to your **Docker Hub account → Create a repository**. - 2. For the Repository Name, use something descriptive — for example: `vuejs-sample`. - 3. Once created, copy and save the repository name — you’ll need it in Step 4. - -3. Create a new [GitHub repository](https://github.com/new) for your Vue.js project - -4. Add Docker Hub credentials as GitHub repository secrets - - In your newly created GitHub repository: - - 1. Navigate to: - **Settings → Secrets and variables → Actions → New repository secret**. - - 2. Add the following secrets: - - | Name | Value | - |-------------------|--------------------------------| - | `DOCKER_USERNAME` | Your Docker Hub username | - | `DOCKERHUB_TOKEN` | Your Docker Hub access token (created in Step 1) | - | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2) | - - These secrets allow GitHub Actions to authenticate securely with Docker Hub during automated workflows. - -5. Connect Your Local Project to GitHub - - Link your local project `docker-vuejs-sample` to the GitHub repository you just created by running the following command from your project root: - - ```console - $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git - ``` - - >[!IMPORTANT] - >Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name. - - To confirm that your local project is correctly connected to the remote GitHub repository, run: - - ```console - $ git remote -v - ``` - - You should see output similar to: - - ```console - origin https://github.com/{your-username}/{your-repository-name}.git (fetch) - origin https://github.com/{your-username}/{your-repository-name}.git (push) - ``` - - This confirms that your local repository is properly linked and ready to push your source code to GitHub. - -6. Push your source code to GitHub - - Follow these steps to commit and push your local project to your GitHub repository: - - 1. Stage all files for commit. - - ```console - $ git add -A - ``` - This command stages all changes — including new, modified, and deleted files — preparing them for commit. - - - 2. Commit the staged changes with a descriptive message. - - ```console - $ git commit -m "Initial commit" - ``` - This command creates a commit that snapshots the staged changes with a descriptive message. - - 3. Push the code to the `main` branch. - - ```console - $ git push -u origin main - ``` - This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch. - -Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically. - -> [!NOTE] -> Learn more about the Git commands used in this step: -> - [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit -> - [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes -> - [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository -> - [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs - ---- - -### Step 2: Set up the workflow - -Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub. - -1. Go to your repository on GitHub and select the **Actions** tab in the top menu. - -2. Select **Set up a workflow yourself** when prompted. - - This opens an inline editor to create a new workflow file. By default, it will be saved to: - `.github/workflows/main.yml` - - -3. Add the following workflow configuration to the new file: - -```yaml -name: CI/CD – Vue.js App with Docker - -on: - push: - branches: [main] - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - -jobs: - build-test-deploy: - name: Build, Test & Deploy - runs-on: ubuntu-latest - - steps: - # 1. Checkout the codebase - - name: Checkout Code - uses: actions/checkout@{{% param "checkout_action_version" %}} - with: - fetch-depth: 0 - - # 2. Set up Docker Buildx - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - # 3. Cache Docker layers - - name: Cache Docker Layers - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: | - ${{ runner.os }}-buildx- - - # 4. Cache npm dependencies - - name: Cache npm Dependencies - uses: actions/cache@{{% param "cache_action_version" %}} - with: - path: ~/.npm - key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-npm- - - # 5. Generate build metadata - - name: Generate Build Metadata - id: meta - run: | - echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT" - echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT" - - # 6. Build Docker image for testing - - name: Build Dev Docker Image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile.dev - tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest - load: true - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache,mode=max - - # 7. Run unit tests inside container - - name: Run Vue.js Tests - run: | - docker run --rm \ - --workdir /app \ - --entrypoint "" \ - ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \ - sh -c "npm ci && npm run test -- --ci --runInBand" - env: - CI: true - NODE_ENV: test - timeout-minutes: 10 - - # 8. Log in to Docker Hub - - name: Docker Hub Login - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - # 9. Build and push production image - - name: Build and Push Production Image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - context: . - file: Dockerfile - push: true - platforms: linux/amd64,linux/arm64 - tags: | - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest - ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }} - cache-from: type=local,src=/tmp/.buildx-cache -``` - -This workflow performs the following tasks for your Vue.js application: -- Triggers on every `push` or `pull request` targeting the `main` branch. -- Builds a development Docker image using `Dockerfile.dev`, optimized for testing. -- Executes unit tests using Vitest inside a clean, containerized environment to ensure consistency. -- Halts the workflow immediately if any test fails — enforcing code quality. -- Caches both Docker build layers and npm dependencies for faster CI runs. -- Authenticates securely with Docker Hub using GitHub repository secrets. -- Builds a production-ready image using the `prod` stage in `Dockerfile`. -- Tags and pushes the final image to Docker Hub with both `latest` and short SHA tags for traceability. - -> [!NOTE] -> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). - ---- - -### Step 3: Run the workflow - -After you've added your workflow file, it's time to trigger and observe the CI/CD process in action. - -1. Commit and push your workflow file - - Select "Commit changes…" in the GitHub editor. - - This push will automatically trigger the GitHub Actions pipeline. - -2. Monitor the workflow execution - - Go to the Actions tab in your GitHub repository. - - Click into the workflow run to follow each step: **build**, **test**, and (if successful) **push**. - -3. Verify the Docker image on Docker Hub - - - After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories). - - You should see a new image under your repository with: - - Repository name: `${your-repository-name}` - - Tags include: - - `latest` – represents the most recent successful build; ideal for quick testing or deployment. - - `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability. - -> [!TIP] Protect your main branch -> To maintain code quality and prevent accidental direct pushes, enable branch protection rules: -> - Navigate to your **GitHub repo → Settings → Branches**. -> - Under Branch protection rules, click **Add rule**. -> - Specify `main` as the branch name. -> - Enable options like: -> - *Require a pull request before merging*. -> - *Require status checks to pass before merging*. -> -> This ensures that only tested and reviewed code is merged into `main` branch. ---- - -## Summary - -In this section, you set up a complete CI/CD pipeline for your containerized Vue.js application using GitHub Actions. - -Here's what you accomplished: - -- Created a new GitHub repository specifically for your project. -- Generated a secure Docker Hub access token and added it to GitHub as a secret. -- Defined a GitHub Actions workflow that: - - Build your application inside a Docker container. - - Run tests in a consistent, containerized environment. - - Push a production-ready image to Docker Hub if tests pass. -- Triggered and verified the workflow execution through GitHub Actions. -- Confirmed that your image was successfully published to Docker Hub. - -With this setup, your Vue.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity. - ---- - -## Related resources - -Deepen your understanding of automation and best practices for containerized apps: - -- [Introduction to GitHub Actions](/guides/gha.md) – Learn how GitHub Actions automate your workflows -- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) – Set up container builds with GitHub Actions -- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows -- [Compose file reference](/compose/compose-file/) – Full configuration reference for `compose.yaml` -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security - ---- - -## Next steps - -Next, learn how you can locally test and debug your Vue.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment. diff --git a/content/guides/vuejs/containerize.md b/content/guides/vuejs/containerize.md deleted file mode 100644 index c02c217ae134..000000000000 --- a/content/guides/vuejs/containerize.md +++ /dev/null @@ -1,530 +0,0 @@ ---- -title: Containerize an Vue.js Application -linkTitle: Containerize -weight: 10 -keywords: vue.js, vue, js, node, image, initialize, build -description: Learn how to containerize an Vue.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability. - ---- - - -## Prerequisites - -Before you begin, make sure the following tools are installed and available on your system: - -- You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. - -> **New to Docker?** -> Start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide to get familiar with key concepts like images, containers, and Dockerfiles. - ---- - -## Overview - -This guide walks you through the complete process of containerizing an Vue.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency. - -By the end of this guide, you will: - -- Containerize an Vue.js application using Docker. -- Create and optimize a Dockerfile for production builds. -- Use multi-stage builds to minimize image size. -- Serve the application efficiently with a custom Nginx configuration. -- Build secure and maintainable Docker images by following best practices. - ---- - -## Get the sample application - -Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command -to clone the git repository: - -```console -$ git clone https://github.com/kristiyan-velkov/docker-vuejs-sample -``` ---- - -## Build the Docker image - -Vue.js is a front-end framework that compiles into static assets, so the Dockerfile is customized to align with how Vue.js applications are built and efficiently served in a production environment. - -> [!TIP] -> -> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. - -### Step 1: Create the Dockerfile - -Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog). - -Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/). - -> [!IMPORTANT] -> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application. -> -> Official Node.js Docker Images: https://hub.docker.com/_/node - -{{< tabs >}} -{{< tab name="Using Docker Hardened Images" >}} -Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. - -1. Sign in to the DHI registry: - ```console - $ docker login dhi.io - ``` - -2. Pull the Node.js DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/node:24-alpine3.22-dev - ``` - -3. Pull the Nginx DHI (check the catalog for available versions): - ```console - $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev - ``` - -In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images. - -```dockerfile -# ========================================= -# Stage 1: Build the Vue.js Application -# ========================================= -# Use a lightweight DHI Node.js image for building -FROM dhi.io/node:24-alpine3.22-dev AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the Vue.js application -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html - -# Use a built-in non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default Nginx container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -{{< /tab >}} -{{< tab name="Using the Docker Official Image" >}} - -Create a file named `Dockerfile` with the following contents: - -```dockerfile -# ========================================= -# Stage 1: Build the Vue.js Application -# ========================================= -ARG NODE_VERSION=24.12.0-alpine -ARG NGINX_VERSION=alpine3.22 - -# Use a lightweight Node.js image for building (customizable via ARG) -FROM node:${NODE_VERSION} AS builder - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies using npm ci (ensures a clean, reproducible install) -RUN --mount=type=cache,target=/root/.npm npm ci - -# Copy the rest of the application source code into the container -COPY . . - -# Build the Vue.js application -RUN npm run build - -# ========================================= -# Stage 2: Prepare Nginx to Serve Static Files -# ========================================= - -FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner - -# Copy custom Nginx config -COPY nginx.conf /etc/nginx/nginx.conf - -# Copy the static build output from the build stage to Nginx's default HTML serving directory -COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html - -# Use a built-in non-root user for security best practices -USER nginx - -# Expose port 8080 to allow HTTP traffic -# Note: The default Nginx container now listens on port 8080 instead of 80 -EXPOSE 8080 - -# Start Nginx directly with custom config -ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"] -CMD ["-g", "daemon off;"] -``` - -> [!NOTE] -> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. -> Running as a non-root user in the final image: ->- Reduces the attack surface ->- Aligns with Docker’s recommendations for container hardening ->- Helps comply with stricter security policies in production environments - -{{< /tab >}} -{{< /tabs >}} - -### Step 2: Create the compose.yaml file - -Create a file named `compose.yaml` with the following contents: - -```yaml {collapse=true,title=compose.yaml} -services: - server: - build: - context: . - ports: - - 8080:8080 -``` - -### Step 3: Create the .dockerignore file - -The `.dockerignore` file plays a crucial role in optimizing your Docker image by specifying which files and directories should be excluded from the build context. - -> [!NOTE] ->This helps: ->- Reduce image size ->- Speed up the build process ->- Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image. -> -> To learn more, visit the [.dockerignore reference](/reference/dockerfile.md#dockerignore-file). - -Create a file named `.dockerignore` with the following contents: - -```dockerignore -# ------------------------------- -# Dependency directories -# ------------------------------- -node_modules/ - -# ------------------------------- -# Production and build outputs -# ------------------------------- -dist/ -out/ -build/ -public/build/ - -# ------------------------------- -# Vite, VuePress, and cache dirs -# ------------------------------- -.vite/ -.vitepress/ -.cache/ -.tmp/ - -# ------------------------------- -# Test output and coverage -# ------------------------------- -coverage/ -reports/ -jest/ -cypress/ -cypress/screenshots/ -cypress/videos/ - -# ------------------------------- -# Environment and config files -# ------------------------------- -*.env* -!.env.production # Keep production env if needed -*.local -*.log - -# ------------------------------- -# TypeScript artifacts -# ------------------------------- -*.tsbuildinfo - -# ------------------------------- -# Editor and IDE config -# ------------------------------- -.vscode/ -.idea/ -*.swp - -# ------------------------------- -# System files -# ------------------------------- -.DS_Store -Thumbs.db - -# ------------------------------- -# Lockfiles (optional) -# ------------------------------- -npm-debug.log* -yarn-debug.log* -yarn-error.log* -pnpm-debug.log* - -# ------------------------------- -# Git files -# ------------------------------- -.git/ -.gitignore - -# ------------------------------- -# Docker-related files -# ------------------------------- -Dockerfile -.dockerignore -docker-compose.yml -docker-compose.override.yml -``` - -### Step 4: Create the `nginx.conf` file - -To serve your Vue.js application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing. - -Create a file named `nginx.conf` in the root of your project directory, and add the following content: - -> [!NOTE] -> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/). - -```nginx -worker_processes auto; -pid /tmp/nginx.pid; - -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - charset utf-8; - - access_log off; - error_log /dev/stderr warn; - - sendfile on; - tcp_nopush on; - tcp_nodelay on; - keepalive_timeout 65; - keepalive_requests 1000; - - gzip on; - gzip_comp_level 6; - gzip_proxied any; - gzip_min_length 256; - gzip_vary on; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml; - - server { - listen 8080; - server_name localhost; - - root /usr/share/nginx/html; - index index.html; - - location / { - try_files $uri $uri/ /index.html; - } - - location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ { - expires 1y; - access_log off; - add_header Cache-Control "public, immutable"; - add_header X-Content-Type-Options nosniff; - } - - location /assets/ { - expires 1y; - add_header Cache-Control "public, immutable"; - add_header X-Content-Type-Options nosniff; - } - - error_page 404 /index.html; - } -} -``` - -### Step 5: Build the Vue.js application image - -With your custom configuration in place, you're now ready to build the Docker image for your Vue.js application. - -The updated setup includes: - -- The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Vue.js. -- Efficient multi-stage Docker build, ensuring a small and secure final image. - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-vuejs-sample/ -│ ├── Dockerfile -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -Now that your Dockerfile is configured, you can build the Docker image for your Vue.js application. - -> [!NOTE] -> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)). - -Run the following command from the root of your project: - -```console -$ docker build --tag docker-vuejs-sample . -``` - -What this command does: -- Uses the Dockerfile in the current directory (.) -- Packages the application and its dependencies into a Docker image -- Tags the image as docker-vuejs-sample so you can reference it later - - -### Step 6: View local images - -After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](/manuals/desktop/use-desktop/images.md). Since you're already working in the terminal, let's use the Docker CLI. - -To list all locally available Docker images, run the following command: - -```console -$ docker images -``` - -Example Output: - -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -docker-vuejs-sample latest 8c9c199179d4 14 seconds ago 76.2MB -``` - -This output provides key details about your images: - -- **Repository** – The name assigned to the image. -- **Tag** – A version label that helps identify different builds (e.g., latest). -- **Image ID** – A unique identifier for the image. -- **Created** – The timestamp indicating when the image was built. -- **Size** – The total disk space used by the image. - -If the build was successful, you should see `docker-vuejs-sample` image listed. - ---- - -## Run the containerized application - -In the previous step, you created a Dockerfile for your Vue.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected. - - -Inside the `docker-vuejs-sample` directory, run the following command in a -terminal. - -```console -$ docker compose up --build -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see a simple Vue.js web application. - -Press `ctrl+c` in the terminal to stop your application. - -### Run the application in the background - -You can run the application detached from the terminal by adding the `-d` -option. Inside the `docker-vuejs-sample` directory, run the following command -in a terminal. - -```console -$ docker compose up --build -d -``` - -Open a browser and view the application at [http://localhost:8080](http://localhost:8080). You should see your Vue.js application running in the browser. - - -To confirm that the container is running, use `docker ps` command: - -```console -$ docker ps -``` - -This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080. - -Example Output: - -```shell -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -37a1fa85e4b0 docker-vuejs-sample-server "nginx -c /etc/nginx…" About a minute ago Up About a minute 0.0.0.0:8080->8080/tcp docker-vuejs-sample-server-1 -``` - - -To stop the application, run: - -```console -$ docker compose down -``` - - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this guide, you learned how to containerize, build, and run an Vue.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup. - -What you accomplished: -- Created a multi-stage `Dockerfile` that compiles the Vue.js application and serves the static files using Nginx. -- Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient. -- Built your Docker image using `docker build`. -- Ran the container using `docker compose up`, both in the foreground and in detached mode. -- Verified that the app was running by visiting [http://localhost:8080](http://localhost:8080). -- Learned how to stop the containerized application using `docker compose down`. - -You now have a fully containerized Vue.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker workflow: - -- [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds. -- [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile. -- [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images. -- [`docker compose up` CLI reference](/reference/cli/docker/compose/up/) – Start and run multi-container applications. -- [`docker compose down` CLI reference](/reference/cli/docker/compose/down/) – Stop and remove containers, networks, and volumes. - ---- - -## Next steps - -With your Vue.js application now containerized, you're ready to move on to the next step. - -In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine. - diff --git a/content/guides/vuejs/deploy.md b/content/guides/vuejs/deploy.md deleted file mode 100644 index 678f8956e055..000000000000 --- a/content/guides/vuejs/deploy.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Test your Vue.js deployment -linkTitle: Test your deployment -weight: 60 -keywords: deploy, kubernetes, vue, vue.js -description: Learn how to deploy locally to test and debug your Kubernetes deployment - ---- - -## Prerequisites - -Before you begin, make sure you’ve completed the following: -- Complete all the previous sections of this guide, starting with [Containerize Vue.js application](containerize.md). -- [Enable Kubernetes](/manuals/desktop/use-desktop/kubernetes.md#enable-kubernetes) in Docker Desktop. - -> **New to Kubernetes?** -> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work. - ---- - -## Overview - -This section guides you through deploying your containerized Vue.js application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster closely simulates a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production. - ---- - -## Create a Kubernetes YAML file - -Follow these steps to define your deployment configuration: - -1. In the root of your project, create a new file named: vuejs-sample-kubernetes.yaml - -2. Open the file in your IDE or preferred text editor. - -3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](configure-github-actions.md). - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: vuejs-sample - namespace: default -spec: - replicas: 1 - selector: - matchLabels: - app: vuejs-sample - template: - metadata: - labels: - app: vuejs-sample - spec: - containers: - - name: vuejs-container - image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest - imagePullPolicy: Always - ports: - - containerPort: 8080 - resources: - limits: - cpu: "500m" - memory: "256Mi" - requests: - cpu: "250m" - memory: "128Mi" ---- -apiVersion: v1 -kind: Service -metadata: - name: vuejs-sample-service - namespace: default -spec: - type: NodePort - selector: - app: vuejs-sample - ports: - - port: 8080 - targetPort: 8080 - nodePort: 30001 -``` - -This manifest defines two key Kubernetes resources, separated by `---`: - -- Deployment - Deploys a single replica of your Vue.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow - (refer to [Automate your builds with GitHub Actions](configure-github-actions.md)). - The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production Vue.js app. - -- Service (NodePort) - Exposes the deployed pod to your local machine. - It forwards traffic from port `30001` on your host to port `8080` inside the container. - This lets you access the application in your browser at [http://localhost:30001](http://localhost:30001). - -> [!NOTE] -> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). - ---- - -## Deploy and check your application - -Follow these steps to deploy your containerized Vue.js app into a local Kubernetes cluster and verify that it’s running correctly. - -### Step 1. Apply the Kubernetes configuration - -In your terminal, navigate to the directory where your `vuejs-sample-kubernetes.yaml` file is located, then deploy the resources using: - -```console - $ kubectl apply -f vuejs-sample-kubernetes.yaml -``` - -If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created: - -```shell - deployment.apps/vuejs-sample created - service/vuejs-sample-service created -``` - -This confirms that both the Deployment and the Service were successfully created and are now running inside your local cluster. - -### Step 2. Check the deployment status - -Run the following command to check the status of your deployment: - -```console - $ kubectl get deployments -``` - -You should see output similar to the following: - -```shell - NAME READY UP-TO-DATE AVAILABLE AGE - vuejs-sample 1/1 1 1 1m14s -``` - -This confirms that your pod is up and running with one replica available. - -### Step 3. Verify the service exposure - -Check if the NodePort service is exposing your app to your local machine: - -```console -$ kubectl get services -``` - -You should see something like: - -```shell -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -vuejs-sample-service NodePort 10.98.233.59 <none> 8080:30001/TCP 1m -``` - -This output confirms that your app is available via NodePort on port 30001. - -### Step 4. Access your app in the browser - -Open your browser and navigate to [http://localhost:30001](http://localhost:30001). - -You should see your production-ready Vue.js Sample application running — served by your local Kubernetes cluster. - -### Step 5. Clean up Kubernetes resources - -Once you're done testing, you can delete the deployment and service using: - -```console - $ kubectl delete -f vuejs-sample-kubernetes.yaml -``` - -Expected output: - -```shell - deployment.apps "vuejs-sample" deleted - service "vuejs-sample-service" deleted -``` - -This ensures your cluster stays clean and ready for the next deployment. - ---- - -## Summary - -In this section, you learned how to deploy your Vue.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud. - -What you accomplished: - -- Created a Kubernetes Deployment and NodePort Service for your Vue.js app -- Used `kubectl apply` to deploy the application locally -- Verified the app was running and accessible at `http://localhost:30001` -- Cleaned up your Kubernetes resources after testing - ---- - -## Related resources - -Explore official references and best practices to sharpen your Kubernetes deployment workflow: - -- [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more. -- [Deploy on Kubernetes with Docker Desktop](/manuals) – Use Docker Desktop’s built-in Kubernetes support for local testing and development. -- [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line. -- [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments. -- [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic. \ No newline at end of file diff --git a/content/guides/vuejs/develop.md b/content/guides/vuejs/develop.md deleted file mode 100644 index 38614f8a8693..000000000000 --- a/content/guides/vuejs/develop.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Use containers for Vue.js development -linkTitle: Develop your app -weight: 30 -keywords: vuejs, development, node -description: Learn how to develop your Vue.js application locally using containers. - ---- - -## Prerequisites - -Complete [Containerize Vue.js application](containerize.md). - ---- - -## Overview - -In this section, you'll set up both production and development environments for your Vue.js application using Docker Compose. This approach streamlines your workflow—delivering a lightweight, static site via Nginx in production, and providing a fast, live-reloading dev server with Compose Watch for efficient local development. - -You’ll learn how to: -- Configure isolated environments: Set up separate containers optimized for production and development use cases. -- Live-reload in development: Use Compose Watch to automatically sync file changes, enabling real-time updates without manual intervention. -- Preview and debug with ease: Develop inside containers with a seamless preview and debug experience—no rebuilds required after every change. - ---- - -## Automatically update services (development mode) - -Leverage Compose Watch to enable real-time file synchronization between your local machine and the containerized Vue.js development environment. This powerful feature eliminates the need to manually rebuild or restart containers, providing a fast, seamless, and efficient development workflow. - -With Compose Watch, your code updates are instantly reflected inside the container—perfect for rapid testing, debugging, and live previewing changes. - -## Step 1: Create a development Dockerfile - -Create a file named `Dockerfile.dev` in your project root with the following content: - -```dockerfile -# ========================================= -# Stage 1: Develop the Vue.js Application -# ========================================= -ARG NODE_VERSION=24.12.0-alpine - -# Use a lightweight Node.js image for development -FROM node:${NODE_VERSION} AS dev - -# Set environment variable to indicate development mode -ENV NODE_ENV=development - -# Set the working directory inside the container -WORKDIR /app - -# Copy package-related files first to leverage Docker's caching mechanism -COPY package.json package-lock.json* ./ - -# Install project dependencies -RUN --mount=type=cache,target=/root/.npm npm install - -# Copy the rest of the application source code into the container -COPY . . - -# Change ownership of the application directory to the node user -RUN chown -R node:node /app - -# Switch to the node user -USER node - -# Expose the port used by the Vite development server -EXPOSE 5173 - -# Use a default command, can be overridden in Docker compose.yml file -CMD [ "npm", "run", "dev", "--", "--host" ] - -``` - -This file sets up a lightweight development environment for your Vue.js application using the dev server. - -### Step 2: Update your `compose.yaml` file - -Open your `compose.yaml` file and define two services: one for production (`vuejs-prod`) and one for development (`vuejs-dev`). - -Here’s an example configuration for an Vue.js application: - -```yaml -services: - vuejs-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-vuejs-sample - ports: - - "8080:8080" - - vuejs-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "5173:5173" - develop: - watch: - - path: ./src - target: /app/src - action: sync - - path: ./package.json - target: /app/package.json - action: restart - - path: ./vite.config.js - target: /app/vite.config.js - action: restart -``` -- The `vuejs-prod` service builds and serves your static production app using Nginx. -- The `vuejs-dev` service runs your Vue.js development server with live reload and hot module replacement. -- `watch` triggers file sync with Compose Watch. - -> [!NOTE] -> For more details, see the official guide: [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). - -After completing the previous steps, your project directory should now contain the following files: - -```text -├── docker-vuejs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 4: Start Compose Watch - -Run the following command from the project root to start the container in watch mode - -```console -$ docker compose watch vuejs-dev -``` - -### Step 5: Test Compose Watch with Vue.js - -To confirm that Compose Watch is functioning correctly: - -1. Open the `src/App.vue` file in your text editor. - -2. Locate the following line: - - ```html - <HelloWorld msg="You did it!" /> - ``` - -3. Change it to: - - ```html - <HelloWorld msg="Hello from Docker Compose Watch" /> - ``` - -4. Save the file. - -5. Open your browser at [http://localhost:5173](http://localhost:5173). - -You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected. - ---- - -## Summary - -In this section, you set up a complete development and production workflow for your Vue.js application using Docker and Docker Compose. - -Here’s what you accomplished: -- Created a `Dockerfile.dev` to streamline local development with hot reloading -- Defined separate `vuejs-dev` and `vuejs-prod` services in your `compose.yaml` file -- Enabled real-time file syncing using Compose Watch for a smoother development experience -- Verified that live updates work seamlessly by modifying and previewing a component - -With this setup, you're now equipped to build, run, and iterate on your Vue.js app entirely within containers—efficiently and consistently across environments. - ---- - -## Related resources - -Deepen your knowledge and improve your containerized development workflow with these guides: - -- [Using Compose Watch](/manuals/compose/how-tos/file-watch.md) – Automatically sync source changes during development -- [Multi-stage builds](/manuals/build/building/multi-stage.md) – Create efficient, production-ready Docker images -- [Dockerfile best practices](/build/building/best-practices/) – Write clean, secure, and optimized Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [Docker volumes](/storage/volumes/) – Persist and manage data between container runs - -## Next steps - -In the next section, you'll learn how to run unit tests for your Vue.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup. diff --git a/content/guides/vuejs/run-tests.md b/content/guides/vuejs/run-tests.md deleted file mode 100644 index 7e1f2d76897e..000000000000 --- a/content/guides/vuejs/run-tests.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Run vue.js tests in a container -linkTitle: Run your tests -weight: 40 -keywords: vue.js, vue, test, vitest -description: Learn how to run your vue.js tests in a container. - ---- - -## Prerequisites - -Complete all the previous sections of this guide, starting with [Containerize Vue.js application](containerize.md). - -## Overview - -Testing is a critical part of the development process. In this section, you'll learn how to: - -- Run unit tests using Vitest inside a Docker container. -- Use Docker Compose to run tests in an isolated, reproducible environment. - -You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — together with [@vue/test-utils](https://test-utils.vuejs.org/) to write unit tests that validate your component logic, props, events, and reactive behavior. - -This setup ensures your Vue.js components are tested in an environment that mirrors how users actually interact with your application. - ---- - -## Run tests during development - -`docker-vuejs-sample` application includes a sample test file at location: - -```console -$ src/components/__tests__/HelloWorld.spec.ts -``` - -This test uses Vitest and Vue Test Utils to verify the behavior of the HelloWorld component. - ---- - -### Step 1: Update compose.yaml - -Add a new service named `vuejs-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment. - -```yaml {hl_lines="22-26",linenos=true} -services: - vuejs-prod: - build: - context: . - dockerfile: Dockerfile - image: docker-vuejs-sample - ports: - - "8080:8080" - - vuejs-dev: - build: - context: . - dockerfile: Dockerfile.dev - ports: - - "5173:5173" - develop: - watch: - - action: sync - path: . - target: /app - - vuejs-test: - build: - context: . - dockerfile: Dockerfile.dev - command: ["npm", "run", "test:unit"] -``` - -The vuejs-test service reuses the same `Dockerfile.dev` used for [development](develop.md) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration. - - -After completing the previous steps, your project directory should contain the following files: - -```text -├── docker-vuejs-sample/ -│ ├── Dockerfile -│ ├── Dockerfile.dev -│ ├── .dockerignore -│ ├── compose.yaml -│ └── nginx.conf -``` - -### Step 2: Run the tests - -To execute your test suite inside the container, run the following command from your project root: - -```console -$ docker compose run --rm vuejs-test -``` - -This command will: -- Start the `vuejs-test` service defined in your `compose.yaml` file. -- Execute the `npm run test` script using the same environment as development. -- Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command. - -You should see output similar to the following: - -```shell -Test Files: 1 passed (1) -Tests: 1 passed (1) -Start at: 16:50:55 -Duration: 718ms -``` - -> [!NOTE] -> For more information about Compose commands, see the [Compose CLI -> reference](/reference/cli/docker/compose/). - ---- - -## Summary - -In this section, you learned how to run unit tests for your Vue.js application inside a Docker container using Vitest and Docker Compose. - -What you accomplished: -- Created a `vuejs-test` service in `compose.yaml` to isolate test execution. -- Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments. -- Ran tests inside the container using `docker compose run --rm vuejs-test`. -- Ensured reliable, repeatable testing across environments without depending on your local machine setup. - ---- - -## Related resources - -Explore official references and best practices to sharpen your Docker testing workflow: - -- [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax. -- [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles. -- [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`. -- [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container. ---- - -## Next steps - -Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Vue.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow. diff --git a/content/guides/wiremock.md b/content/guides/wiremock.md index 0913e9c08464..394caf39f205 100644 --- a/content/guides/wiremock.md +++ b/content/guides/wiremock.md @@ -4,9 +4,8 @@ description: &desc Mocking API services in development and testing with WireMock keywords: WireMock, container-supported development linktitle: Mocking API services with WireMock summary: *desc -tags: [app-dev, distributed-systems] -languages: [js] params: + tags: [testing] time: 20 minutes --- @@ -58,12 +57,12 @@ Launch a quick demo of WireMock by using the following steps: After a moment, the application will be up and running. - ![Diagram showing the WireMock container running on Docker Desktop ](./images/wiremock-using-docker.webp) + ![Diagram showing the WireMock container running on Docker Desktop](./images/wiremock-using-docker.webp) You can check the logs by selecting the `wiremock-node-docker` container: - ![Diagram showing the logs of WireMock container running on Docker Desktop ](./images/wiremock-logs-docker-desktop.webp) + ![Diagram showing the logs of WireMock container running on Docker Desktop](./images/wiremock-logs-docker-desktop.webp) 4. Test the Mock API. @@ -94,7 +93,7 @@ Now that you have tried WireMock, let’s use it in development and testing. In - External AccuWeather API: The real API from which live weather data is fetched. - WireMock: The mock server that simulates the API responses during testing. It runs as a Docker container. - ![Diagram showing the architecture of WireMock in development ](./images/wiremock-arch.webp) + ![Diagram showing the architecture of WireMock in development](./images/wiremock-arch.webp) - In development, the Node.js backend sends a request to WireMock instead of the actual AccuWeather API. - In production, it connects directly to the live AccuWeather API for real data. diff --git a/content/guides/zscaler.md b/content/guides/zscaler.md new file mode 100644 index 000000000000..dc4662f9d1db --- /dev/null +++ b/content/guides/zscaler.md @@ -0,0 +1,142 @@ +--- +title: Using Docker with Zscaler +summary: | + This guide explains how to embed Zscaler's root certificate into Docker + images, allowing containers to operate securely with Zscaler proxies and + avoid SSL errors. +keywords: zscaler, proxy, ssl certificates, corporate network, https, root certificate +params: + tags: [admin] + time: 10 minutes +--- + +In many corporate environments, network traffic is intercepted and monitored +using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance +and network control, it can cause issues for developers using Docker, +particularly during build processes, where SSL certificate validation errors +might occur. This guide outlines how to configure Docker containers and builds +to properly handle Zscaler's custom certificates, ensuring smooth operation in +monitored environments. + +## The role of certificates in Docker + +When Docker builds or runs containers, it often needs to fetch resources from +the internet—whether it's pulling a base image from a registry, downloading +dependencies, or communicating with external services. In a proxied +environment, Zscaler intercepts HTTPS traffic and replaces the remote server's +certificate with its own. However, Docker doesn't trust this Zscaler +certificate by default, leading to SSL errors. + +```plaintext +x509: certificate signed by unknown authority +``` + +These errors occur because Docker cannot verify the validity of the certificate +presented by Zscaler. To avoid this, you must configure Docker to trust +Zscaler's certificate. + +## Configure Zscaler proxy for Docker Desktop + +Depending on how Zscaler is deployed, you may need to configure Docker Desktop +proxy settings manually to use the Zscaler proxy. + +If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector), +all traffic on the device is automatically routed through Zscaler, so Docker +Desktop uses the Zscaler proxy automatically with no additional configuration +necessary. + +If you are not using Zscaler as a system-level proxy, manually configure proxy +settings in Docker Desktop. Set up proxy settings for all clients in the +organization using [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md), +or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](/manuals/desktop/settings-and-maintenance/settings.md#proxies). + +## Install root certificates in Docker images + +To enable containers to use and trust the Zscaler proxy, embed the certificate +in the image and configure the image's trust store. Installing certificates at +image build time is the preferred approach, as it removes the need for +configuration during startup and provides an auditable, consistent environment. + +### Obtaining the root certificate + +The easiest way to obtain the root certificate is to export it from a machine +where an administrator has already installed it. You can use either a web +browser or the system's certificate management service (for example, Windows +Certificate Store). + +#### Example: Exporting the certificate using Google Chrome + +1. In Google Chrome, navigate to `chrome://certificate-manager/`. +2. Under **Local certificates**, select **View imported certificates**. +3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**. +4. Open the certificate details and select **Export**. +5. Save the certificate in ASCII PEM format. +6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. + +When you have obtained the certificate, store it in an accessible repository, +such as JFrog Artifactory or a Git repository. Alternatively, use generic +storage like AWS S3. + +### Building with the certificate + +To install these certificates when building images, copy the certificate into +the build container and update the trust store. An example Dockerfile looks +like this: + +```dockerfile +FROM debian:bookworm +COPY zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +Here, `zscaler-root-ca.crt` is the root certificate, located at the root of the +build context (often within the application's Git repository). + +If you use an artifact repository, you can fetch the certificate directly using +the `ADD` instruction. You can also use the `--checksum` flag to verify that +the content digest of the certificate is correct. + +```dockerfile +FROM debian:bookworm +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +#### Using multi-stage builds + +For multi-stage builds where certificates are needed in the final runtime +image, ensure the certificate installation occurs in the final stage. + +```dockerfile +FROM debian:bookworm AS build +WORKDIR /build +RUN apt-get update && apt-get install -y \ + build-essential \ + cmake \ + curl \ + git +RUN --mount=target=. cmake -B output/ + +FROM debian:bookworm-slim AS final +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +WORKDIR /app +COPY --from=build /build/output/bin . +ENTRYPOINT ["/app/bin"] +``` + +## Conclusion + +Embedding the Zscaler root certificate directly into your Docker images ensures +that containers run smoothly within Zscaler-proxied environments. By using this +approach, you reduce potential runtime errors and create a consistent, +auditable configuration that allows for smooth Docker operations within a +monitored network. diff --git a/content/guides/zscaler/index.md b/content/guides/zscaler/index.md deleted file mode 100644 index 8fbd51f6a1d5..000000000000 --- a/content/guides/zscaler/index.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Using Docker with Zscaler -tags: [networking, admin] -summary: | - This guide explains how to embed Zscaler’s root certificate into Docker - images, allowing containers to operate securely with Zscaler proxies and - avoid SSL errors. -keywords: zscaler, proxy, ssl certificates, corporate network, https, root certificate -params: - time: 10 minutes ---- - -In many corporate environments, network traffic is intercepted and monitored -using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance -and network control, it can cause issues for developers using Docker, -particularly during build processes, where SSL certificate validation errors -might occur. This guide outlines how to configure Docker containers and builds -to properly handle Zscaler's custom certificates, ensuring smooth operation in -monitored environments. - -## The role of certificates in Docker - -When Docker builds or runs containers, it often needs to fetch resources from -the internet—whether it's pulling a base image from a registry, downloading -dependencies, or communicating with external services. In a proxied -environment, Zscaler intercepts HTTPS traffic and replaces the remote server's -certificate with its own. However, Docker doesn't trust this Zscaler -certificate by default, leading to SSL errors. - -```plaintext -x509: certificate signed by unknown authority -``` - -These errors occur because Docker cannot verify the validity of the certificate -presented by Zscaler. To avoid this, you must configure Docker to trust -Zscaler's certificate. - -## Configure Zscaler proxy for Docker Desktop - -Depending on how Zscaler is deployed, you may need to configure Docker Desktop -proxy settings manually to use the Zscaler proxy. - -If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector), -all traffic on the device is automatically routed through Zscaler, so Docker -Desktop uses the Zscaler proxy automatically with no additional configuration -necessary. - -If you are not using Zscaler as a system-level proxy, manually configure proxy -settings in Docker Desktop. Set up proxy settings for all clients in the -organization using [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md), -or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](/manuals/desktop/settings-and-maintenance/settings.md#proxies). - -## Install root certificates in Docker images - -To enable containers to use and trust the Zscaler proxy, embed the certificate -in the image and configure the image's trust store. Installing certificates at -image build time is the preferred approach, as it removes the need for -configuration during startup and provides an auditable, consistent environment. - -### Obtaining the root certificate - -The easiest way to obtain the root certificate is to export it from a machine -where an administrator has already installed it. You can use either a web -browser or the system's certificate management service (for example, Windows -Certificate Store). - -#### Example: Exporting the certificate using Google Chrome - -1. In Google Chrome, navigate to `chrome://certificate-manager/`. -2. Under **Local certificates**, select **View imported certificates**. -3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**. -4. Open the certificate details and select **Export**. -5. Save the certificate in ASCII PEM format. -6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. - -When you have obtained the certificate, store it in an accessible repository, -such as JFrog Artifactory or a Git repository. Alternatively, use generic -storage like AWS S3. - -### Building with the certificate - -To install these certificates when building images, copy the certificate into -the build container and update the trust store. An example Dockerfile looks -like this: - -```dockerfile -FROM debian:bookworm -COPY zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt -RUN apt-get update && \ - apt-get install -y ca-certificates && \ - update-ca-certificates -``` - -Here, `zscaler-root-ca.crt` is the root certificate, located at the root of the -build context (often within the application's Git repository). - -If you use an artifact repository, you can fetch the certificate directly using -the `ADD` instruction. You can also use the `--checksum` flag to verify that -the content digest of the certificate is correct. - -```dockerfile -FROM debian:bookworm -ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ - https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt -RUN apt-get update && \ - apt-get install -y ca-certificates && \ - update-ca-certificates -``` - -#### Using multi-stage builds - -For multi-stage builds where certificates are needed in the final runtime -image, ensure the certificate installation occurs in the final stage. - -```dockerfile -FROM debian:bookworm AS build -WORKDIR /build -RUN apt-get update && apt-get install -y \ - build-essential \ - cmake \ - curl \ - git -RUN --mount=target=. cmake -B output/ - -FROM debian:bookworm-slim AS final -ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ - https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt -RUN apt-get update && \ - apt-get install -y ca-certificates && \ - update-ca-certificates -WORKDIR /app -COPY --from=build /build/output/bin . -ENTRYPOINT ["/app/bin"] -``` - -## Conclusion - -Embedding the Zscaler root certificate directly into your Docker images ensures -that containers run smoothly within Zscaler-proxied environments. By using this -approach, you reduce potential runtime errors and create a consistent, -auditable configuration that allows for smooth Docker operations within a -monitored network. diff --git a/content/includes/aci-ecs-eol.md b/content/includes/aci-ecs-eol.md deleted file mode 100644 index b106ceb43860..000000000000 --- a/content/includes/aci-ecs-eol.md +++ /dev/null @@ -1,3 +0,0 @@ -> [!IMPORTANT] -> -> Docker Compose's integration for ECS and ACI is retiring in November 2023. diff --git a/content/includes/buildx-v0.10-disclaimer.md b/content/includes/buildx-v0.10-disclaimer.md deleted file mode 100644 index 855bc5f58b61..000000000000 --- a/content/includes/buildx-v0.10-disclaimer.md +++ /dev/null @@ -1,8 +0,0 @@ -> [!NOTE] -> -> Buildx v0.10 enables support for a minimal [SLSA Provenance](https://slsa.dev/provenance/) -> attestation, which requires support for [OCI-compliant](https://github.com/opencontainers/image-spec) -> multi-platform images. This may introduce issues with registry and runtime support -> (e.g. [Google Cloud Run and AWS Lambda](https://github.com/docker/buildx/issues/1533)). -> You can optionally disable the default provenance attestation functionality -> using `--provenance=false`. diff --git a/content/includes/compose-eol.md b/content/includes/compose-eol.md deleted file mode 100644 index ce5ad8fab965..000000000000 --- a/content/includes/compose-eol.md +++ /dev/null @@ -1,5 +0,0 @@ -> [!IMPORTANT] -> -> Docker's documentation refers to and describes Compose V2 functionality. -> -> Effective July 2023, Compose V1 stopped receiving updates and is no longer in new Docker Desktop releases. Compose V2 has replaced it and is now integrated into all current Docker Desktop versions. diff --git a/content/includes/deploy.md b/content/includes/deploy.md deleted file mode 100644 index 22702a8684e4..000000000000 --- a/content/includes/deploy.md +++ /dev/null @@ -1,28 +0,0 @@ -Now that we have configured a CI/CD pipeline, let's look at how we can deploy the application. Docker supports deploying containers on Azure ACI and AWS ECS. You can also deploy your application to Kubernetes if you have enabled Kubernetes in Docker Desktop. - -## Docker and Azure ACI - -The Docker Azure Integration enables developers to use native Docker commands to run applications in Azure Container Instances (ACI) when building cloud-native applications. The new experience provides a tight integration between Docker Desktop and Microsoft Azure allowing developers to quickly run applications using the Docker CLI or VS Code extension to switch seamlessly from local development to cloud deployment. - -For detailed instructions, see [Deploying Docker containers on Azure](/cloud/aci-integration/). - -## Docker and AWS ECS - -The Docker ECS Integration enables developers to use native Docker commands in the Docker Compose CLI to run applications in an Amazon EC2 Container Service (ECS) when building cloud-native applications. - -The integration between Docker and Amazon ECS allows developers to use the Docker Compose CLI to set up an AWS context in one Docker command, allowing them to switch from a local context to a cloud context and run applications quickly and easily to simplify multi-container application development on Amazon ECS using Compose files. - -For detailed instructions, see [Deploying Docker containers on ECS](/cloud/ecs-integration/). - -## Kubernetes - -Docker Desktop includes a standalone Kubernetes server and client, as well as Docker CLI integration that runs on your machine. When you enable Kubernetes, you can test your workloads on Kubernetes. - -To enable Kubernetes: - -1. From the Docker menu, select **Settings**. -2. Select **Kubernetes** and click **Enable Kubernetes**. - - This starts a Kubernetes single-node cluster when Docker Desktop starts. - -For detailed information, see [Deploy on Kubernetes](/manuals/desktop/use-desktop/kubernetes.md) and [Describing apps using Kubernetes YAML](/guides/deployment-orchestration/kube-deploy/#describing-apps-using-kubernetes-yaml). diff --git a/content/includes/dev-envs-changing.md b/content/includes/dev-envs-changing.md deleted file mode 100644 index edd3984a57f1..000000000000 --- a/content/includes/dev-envs-changing.md +++ /dev/null @@ -1,5 +0,0 @@ -> [!IMPORTANT] -> -> Dev Environments is no longer under active development. -> -> While the current functionality remains available, it may take us longer to respond to support requests. diff --git a/content/includes/dockerfile-labs-channel.md b/content/includes/dockerfile-labs-channel.md deleted file mode 100644 index 8a7bca00d15b..000000000000 --- a/content/includes/dockerfile-labs-channel.md +++ /dev/null @@ -1,3 +0,0 @@ -> [!IMPORTANT] -> -> The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel. \ No newline at end of file diff --git a/content/includes/experimental.md b/content/includes/experimental.md deleted file mode 100644 index 86cebbd3f983..000000000000 --- a/content/includes/experimental.md +++ /dev/null @@ -1,7 +0,0 @@ -Experimental features provide early access to future product functionality. -These features are intended for testing and feedback only as they may change -between releases without warning or can be removed entirely from a future -release. Experimental features must not be used in production environments. -Docker does not offer support for experimental features. - -For a list of current experimental features in the Docker CLI, see [Docker CLI Experimental features](https://github.com/docker/cli/blob/master/experimental/README.md). diff --git a/content/includes/guides-get-docker.md b/content/includes/guides-get-docker.md deleted file mode 100644 index 0a5ae3a13a4f..000000000000 --- a/content/includes/guides-get-docker.md +++ /dev/null @@ -1 +0,0 @@ -Before you start, get the latest version of [Docker Desktop](/get-started/get-docker.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. diff --git a/content/includes/labspace-quickstart.md b/content/includes/labspace-quickstart.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/content/includes/open-terminal.md b/content/includes/open-terminal.md deleted file mode 100644 index 845154bc21d7..000000000000 --- a/content/includes/open-terminal.md +++ /dev/null @@ -1,10 +0,0 @@ -> [!TIP] -> -> To run Docker commands, you must use a terminal. Based on your -> operating system, you can open a terminal by doing the following: -> -> For Windows, select the Start Menu, specify `cmd`, and then select -> **Command Prompt**. -> -> For Mac, select the **Launchpad** icon in the Dock, specify `Terminal` in the -> search field, then select **Terminal**. diff --git a/content/includes/sandboxes-local-scope.md b/content/includes/sandboxes-local-scope.md new file mode 100644 index 000000000000..d65bb3899170 --- /dev/null +++ b/content/includes/sandboxes-local-scope.md @@ -0,0 +1,2 @@ +This page describes local sandboxes. For cloud behavior and limitations, see +[Compare local and cloud sandboxes](/manuals/ai/sandboxes/cloud/local-vs-cloud.md). diff --git a/content/manuals/_index.md b/content/manuals/_index.md index 7784513fda3f..d45c63576510 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -12,14 +12,21 @@ params: - AI and agents - Application development - Supply chain security - - Platform - - Enterprise + - Accounts and admin notoc: true ai-and-agents: + - title: Docker Agentic Platform + description: Run agents in cloud sandboxes with this experimental platform. + icon: cloud + link: /agentic-platform/ - title: Docker Sandboxes description: Run AI coding agents in isolated environments. icon: command-line link: /ai/sandboxes/ + - title: Sandboxes API and SDK + description: Create and manage cloud sandboxes from your applications. + icon: code-bracket + link: /ai/sandboxes-api/ - title: MCP Catalog and Toolkit description: Augment your AI workflow with MCP servers. icon: /icons/toolkit.svg @@ -36,6 +43,10 @@ params: description: The open-source multi-agent solution to assist you in your tasks. icon: /icons/cagent.svg link: /ai/docker-agent + - title: Docker Skills + description: Docker's official skills for AI coding agents. + icon: document-text + link: /ai/skills/ application-development: - title: Docker Desktop description: Your command center for container development. @@ -79,31 +90,30 @@ params: icon: /icons/Scout.svg link: /scout/ platform: - - title: Administration - description: Centralized observability for companies and organizations. - icon: shield-check - link: /admin/ - - title: Billing - description: Manage billing and payment methods. - icon: credit-card - link: /billing/ - title: Accounts - description: Manage your Docker account. + description: Manage Docker individual and organization accounts. icon: user-circle link: /accounts/ + - title: Subscription and billing + description: Manage Docker subscriptions, plans, billing, and payments. + icon: credit-card + link: /subscription-billing/ - title: Security description: Security guardrails for both administrators and developers. icon: lock-closed link: /security/ - - title: Subscription - description: Commercial use licenses for Docker products. - icon: credit-card - link: /subscription/ - enterprise: - - title: Deploy Docker Desktop - description: Deploy Docker Desktop at scale within your company - icon: arrow-down-tray - link: /enterprise/enterprise-deployment/ + - title: FAQs + description: Frequently asked questions about Docker accounts, organizations, companies, subscriptions, billing, and security. + icon: question-mark-circle + link: /faqs/ + - title: Support + description: Support options for paid subscriptions and community resources. + icon: chat-bubble-left + link: /support/ + - title: Release notes + description: Features, bug fixes, and breaking changes for Docker Home, billing, security, and subscriptions. + icon: document-plus + link: /platform-release-notes/ --- This section contains user guides on how to install, set up, configure, and use @@ -127,16 +137,8 @@ Security guardrails and image analysis for your software supply chain. {{< grid items=supply-chain-security >}} -## Platform +## Accounts and admin -Documentation related to the Docker platform, such as administration and -subscription management. +Manage Docker accounts, administration, subscriptions, billing, and security. {{< grid items=platform >}} - -## Enterprise - -Targeted at IT administrators with help on deploying Docker Desktop at scale with configuration guidance on security related features. - -{{< grid items=enterprise >}} - diff --git a/content/manuals/accounts/_index.md b/content/manuals/accounts/_index.md index 2f8df43368c4..60c8fb8a884c 100644 --- a/content/manuals/accounts/_index.md +++ b/content/manuals/accounts/_index.md @@ -1,45 +1,54 @@ --- -title: Docker accounts -description: Learn how to create and manage your Docker account -keywords: accounts, docker ID, account management, account settings, docker account, docker home -weight: 30 +title: Accounts +description: > + Manage Docker individual accounts and organization administration, including + members, teams, and companies. +keywords: accounts, admin, Docker ID, organization, company, Docker Home, + account management +weight: 10 params: sidebar: - group: Platform + group: Accounts and admin grid: -- title: Create a Docker ID - description: Get started with Docker and create an account. - icon: finger-print - link: /accounts/create-account/ -- title: Manage account - description: Learn how to manage the settings for your account. - icon: cog - link: /accounts/manage-account/ -- title: Personal access tokens - description: Learn how to create and manage access tokens for your account. - icon: lock-closed - link: /security/access-tokens/ -- title: Set up two-factor authentication - description: Add an extra layer of authentication to your Docker account. - link: /security/2fa/ - icon: device-phone-mobile -- title: Deactivate an account - description: Learn how to deactivate a Docker user account. - link: /accounts/deactivate-user-account/ - icon: no-symbol -- title: Account FAQ - description: Explore frequently asked questions about Docker accounts. - icon: question-mark-circle - link: /accounts/general-faqs/ + - title: Docker individual accounts + description: Create and manage your Docker ID, email, and sign-in methods. + icon: user-circle + link: /accounts/individual/ + - title: Organization accounts + description: Manage members, teams, and organization settings. + icon: building-storefront + link: /accounts/organization/ + - title: Company accounts + description: Group multiple organizations for centralized administration. + icon: building-office-2 + link: /accounts/company/ + - title: Security + description: Authentication, tokens, and roles for accounts and organizations. + icon: lock-closed + link: /security/ + - title: Subscription and billing + description: Plans, payments, and invoices for your account or organization. + icon: credit-card + link: /subscription-billing/ + - title: FAQs + description: Common questions about accounts, billing, and security. + icon: question-mark-circle + link: /faqs/ --- -This section covers individual Docker accounts and Docker IDs. It does -not cover organizations, companies, or administrator roles. +A Docker account identifies you and lets you access Docker products. You +manage your Docker accounts in [Docker Home](https://app.docker.com/). +Docker offers individual, organization, and company account types. -A Docker account is required to: -- Create a Docker ID -- Access Docker products and services like Docker Hub and Docker Desktop -- Receive organization invitations -- Manage your personal settings and security features +| Account type | What it is | Who it's for | +| --- | --- | --- | +| Individual | A Docker ID with personal settings, Hub repositories, and sign-in methods | A person | +| Organization | A shared workspace for members, teams, and repositories | Teams on Docker Team or Business | +| Company | Shared sign-in and administration for organizations that keep their own members, repositories, and billing | Docker Business subscribers | + +You always sign in with your individual account, then work in the +organizations or companies you own or belong to. + +## Next steps {{< grid >}} diff --git a/content/manuals/accounts/company/_index.md b/content/manuals/accounts/company/_index.md new file mode 100644 index 000000000000..5c80ad5d0da1 --- /dev/null +++ b/content/manuals/accounts/company/_index.md @@ -0,0 +1,94 @@ +--- +title: Company accounts +linkTitle: Company +weight: 20 +description: Why a Docker company groups organizations, and what company + owners administer. +keywords: company, multiple organizations, Docker Home, Docker Business, + company owners, SSO, SCIM +grid: + - title: Create a company + description: Get started by learning how to create a company. + icon: building-office-2 + link: /accounts/company/new-company/ + - title: Manage your company + description: Add organizations, manage company owners, and invite members. + icon: building-storefront + link: /accounts/company/manage/ + - title: Configure SSO and SCIM + description: Set up single sign-on and SCIM provisioning for your company. + icon: key + link: /security/authentication/single-sign-on/ + - title: Domain management + description: Add and verify your company's domains. + icon: check-badge + link: /security/provisioning/domain-management/ + - title: FAQs + description: Explore frequently asked questions about companies. + link: /faqs/accounts/ + icon: question-mark-circle +aliases: + - /admin/company/ + - /docker-hub/creating-companies/ +--- + +{{< summary-bar feature_name="Company" >}} + +A company is where you configure sign-in and administration for multiple +Docker organizations. + +> [!TIP] +> +> Organization owners with a Docker Business subscription can +> [create a company](./new-company.md) in +> [Docker Home](https://app.docker.com/). + +## Company structure + +A company sits above its organizations, giving company owners full +administrative access across every organization in the company. + +The following diagram shows that hierarchy: + +```mermaid {title="Company structure" caption="Company owners manage a company that contains one or more organizations."} +flowchart TB + co(("Company owners")) -.->|"manage"| C + subgraph C["Company"] + direction TB + subgraph O1["Organization A"] + direction TB + m1(("Members")) + r1[("Repositories")] + end + subgraph O2["Organization B"] + direction TB + m2(("Members")) + r2[("Repositories")] + end + O1 ~~~ O2 + end + style C fill:#3b82f622,stroke:#3b82f6 +``` + +## What a company lets you do + +When you create a company, you can: + +- Administer every organization in the company from one place. +- Configure single sign-on (SSO) and System for Cross-domain Identity + Management (SCIM) once for every organization in the company. +- Verify your domains once at the company level instead of in each + organization. When you turn on auto-provisioning for a domain, you + choose which organization new users join. +- View members and invitations from every organization in one list, and + export that list as a CSV. + +You can assign up to 10 company owners. Company owners occupy a purchased +seat only when they are also members of an organization. A company owner +who is not an organization member does not occupy a seat. + +## Next steps + +Learn how to create and manage a company in the following sections. + +{{< grid >}} diff --git a/content/manuals/accounts/company/manage.md b/content/manuals/accounts/company/manage.md new file mode 100644 index 000000000000..543c9f371dcc --- /dev/null +++ b/content/manuals/accounts/company/manage.md @@ -0,0 +1,176 @@ +--- +title: Manage company organizations, owners, and members +linkTitle: Manage +weight: 20 +description: Manage your Docker company in Docker Home. Add organizations, invite members, manage owners, resend invitations, export a member CSV, and add subscription seats. +keywords: company, manage company, Docker Home, company owners, add organization, invite members, resend invitations, export members CSV, company members, manage seats +aliases: + - /admin/company/manage/ + - /admin/company/manage/organizations/ + - /admin/company/manage/owners/ + - /admin/company/manage/users/ + - /admin/company/organizations/ + - /admin/company/owners/ + - /admin/company/users/ + - /docker-hub/company-owner/ +--- + +{{< summary-bar feature_name="Company" >}} + +After creating a company, you can manage multiple organizations from +Docker Home. Company owners can use the company portal to invite members to +specific organizations, view seat availability across organizations, and +add new company owners. + +## Add more organizations + +Company owners can add Docker organizations with a Docker Business plan +to their company, so long as they're also the organization owners for +that organization. There's no limit to the number of organizations you +add to a company. + +> [!IMPORTANT] +> +> Once you add an organization to a company, you can't remove it from the +> company. + +1. Sign in to [Docker Home](https://app.docker.com) and select + your company. +1. Select **Managed organizations**. +1. Select **Add organization**, then select an organization from the + drop-down list. + +A nested organization must keep its Docker Business subscription to stay +managed by the company. If an organization downgrades from Docker +Business, you can no longer manage it through the company, and its owner +must manage it separately. + +## Company owners + +A company can have multiple owners who manage the company and all of its +organizations. For details about the company owner role and how it affects +seats, see +[Company structure](/manuals/accounts/company/_index.md#company-structure). + +### Add a company owner + +1. Sign in to [Docker Home](https://app.docker.com) and select your company. +1. Select **Company owners**, then select **Add owner**. +1. Specify the member's Docker ID, then select **Add company owner**. + +### Remove a company owner + +1. Sign in to [Docker Home](https://app.docker.com) and select your company. +1. Select **Company owners**. +1. Find the company owner you want to remove and select the **Actions** + menu, then select **Remove as company owner**. + +## Company invitations + +You add a member to your company by inviting them to an organization within +the company. Company owners can invite members to any organization in the +company using a Docker ID, email address, or in bulk with a CSV file of +email addresses. + +Members and invitations belong to individual organizations, not to the +company itself. A pending invitation occupies a seat until the invitee +accepts. + +### Invite members to an organization + +1. Sign in to [Docker Home](https://app.docker.com) and select your company. +1. Select **Users**, then select **Invite**. + +{{< tabs >}} +{{< tab name="Email or username" >}} + +1. Select **Emails or usernames**. +1. Enter the Docker IDs or email addresses of the invitees. +1. Select an organization for each invitee. + +{{< /tab >}} +{{< tab name="CSV upload" >}} + +1. Select **CSV upload**. +1. Upload a CSV file of email addresses. +1. Select an organization for the invitees. + +{{< /tab >}} +{{< /tabs >}} + +Invitees receive an email with instructions to accept. After they accept, +new members appear on the **Users** page. The table shows how many +organizations each member belongs to. + +### Resend invitations + +Company owners can resend invitations from the company-level **Users** +page. + +{{< tabs >}} +{{< tab name="Individual" >}} + +1. Select your company from [Docker Home](https://app.docker.com/). +1. Select **Users**, then locate the invitee from the table. +1. Select the **Actions** menu, then select **Resend**. + - Before resending, confirm you selected the correct invitee. + - The resend invitation modal displays the date you originally invited + the invitee. +1. Select **Invite** to confirm. + +{{< /tab >}} +{{< tab name="Bulk" >}} + +1. Select your company from [Docker Home](https://app.docker.com/). +1. Select **Users**. +1. From the table, use the multi-select checkboxes next to the invitees + you want to resend to. +1. Select **Resend invites**, then select **Resend** to confirm. + +{{< /tab >}} +{{< /tabs >}} + +## Export a member list CSV + +Company owners can export a CSV file of members across organizations in the +company. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your company. +1. Select **Users**. +1. Select the **Download** icon. The CSV file downloads in your browser. + + {{< accordion title="CSV fields" >}} + - Name: The member's name + - Username: The member's Docker ID + - Email: The member's email address + - Member of Organizations: Organizations the member belongs to within the + company + - Invited to Organizations: Organizations where the invitee has a + pending invitation + - Account created: The time and date when the account was created + + {{< /accordion >}} + +## Add seats to an organization + +If you have a self-serve subscription that has no pending subscription +changes, you can add seats using Docker Home. For more information about +adding seats, see +[Manage seats](/manuals/accounts/organization/manage/manage-seats.md#add-seats-to-your-subscription). + +If you have a sales-assisted subscription, you must contact Docker support +or sales to add seats. + +## Manage teams + +Teams exist at the organization level, not the company level. After inviting +members to an organization, you can add them to teams within that +organization. For more details, see +[Manage members on a team](/manuals/accounts/organization/manage/members.md#manage-members-on-a-team). + +## Next steps + +- [Company overview](/manuals/accounts/company/_index.md) +- [Manage organization members](/manuals/accounts/organization/manage/members.md) +- [Manage seats](/manuals/accounts/organization/manage/manage-seats.md) +- [Roles and permissions](/manuals/security/roles-and-permissions/_index.md) diff --git a/content/manuals/accounts/company/new-company.md b/content/manuals/accounts/company/new-company.md new file mode 100644 index 000000000000..de9b55f015f0 --- /dev/null +++ b/content/manuals/accounts/company/new-company.md @@ -0,0 +1,51 @@ +--- +title: Create new company +linkTitle: Setup +weight: 10 +description: Learn how to create a company to centrally manage multiple organizations. +keywords: company, hub, organization, company owner, Docker Home, company management, Docker Business, create company +aliases: + - /admin/company/new-company/ + - /docker-hub/new-company/ +--- + +{{< summary-bar feature_name="Company" >}} + +Learn how to create a new company in Docker Home, a centralized +dashboard for managing organizations. + +## Prerequisites + +Before you begin, you must: + +- Be the owner of the organization you want to add to your company +- Have a Docker Business subscription + +## Create a company + +To create a new company: + +1. Sign in to [Docker Home](https://app.docker.com/) and select the + organization you want to add to your company. +1. Select **Organization settings**. +1. Select **Create a company**. +1. Enter a unique name for your company, then select **Continue**. + + > [!TIP] + > + > The name for your company can't be the same as an existing user, + > organization, or company namespace. + +1. Review the migration details and then select **Create company**. + +When you create the company, the organization you selected is automatically +migrated to the new company. + +For more information on how you can add more organizations to your company, +see [Add more organizations](./manage.md#add-more-organizations). + +## Next steps + +- [Add organizations](./manage.md#add-more-organizations) +- [Invite company members](./manage.md#company-invitations) +- [Manage company owners](./manage.md#company-owners) diff --git a/content/manuals/accounts/create-account.md b/content/manuals/accounts/create-account.md deleted file mode 100644 index ec26fd1a15c0..000000000000 --- a/content/manuals/accounts/create-account.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Create a Docker account -linkTitle: Create an account -weight: 10 -description: Learn how to register for a Docker ID and sign in to your account -keywords: - accounts, docker ID, billing, paid plans, support, Hub, Store, Forums, knowledge - base, beta access, email, activation, verification -aliases: - - /docker-hub/accounts/ - - /docker-id/ ---- - -You can create a free Docker account with your email address or by signing up -with your Google or GitHub account. After creating a unique Docker ID, you can -access all Docker products, including Docker Hub, Docker Desktop, and Docker Scout. - -Your Docker ID becomes your username for hosted Docker services, and -[Docker forums](https://forums.docker.com/). - -> [!TIP] -> -> Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsCreateAccount) to see what else Docker can offer you. - -## Create and verify your account - -Signing up with an email address, Google, or GitHub account requires additional verification to complete account creation: - -- If you sign up with Google or GitHub, you must first verify your email address with that provider. -- If you sign up with an email address, you need to follow verification steps. - - After creating an account, Docker asks for a one-time password (OTP). - - Find the email from Docker with your code, then return to the OTP page to paste in your OTP code. - -Docker blocks sign-in until you've verified your account. - -### Sign up with your email - -1. Go to the [Docker sign-up page](https://app.docker.com/signup/) and enter a unique, valid email address. -1. Enter a username to use as your Docker ID. Once you create your Docker ID - you can't reuse it in the future if you deactivate this account. Your username: - Must be between 4 and 30 characters long - Can only contain numbers and lowercase letters -1. Choose a password that's at least 9 characters long, then select **Sign Up**. -1. Verify your email address when you receive the Docker OTP verification email. This completes the registration process. - -### Sign up with Google or GitHub - -1. Go to the [Docker sign-up page](https://app.docker.com/signup/). -1. Select your social provider, Google or GitHub. -1. Select the social account you want to link to your Docker account. -1. Select **Authorize Docker** to let Docker access your social account - information. You will be re-routed to the sign-up page. -1. Enter a username to use as your Docker ID. Your username: - - Must be between 4 and 30 characters long - - Can only contain numbers and lowercase letters -1. Select **Sign up**. - -## Sign in to your account - -You can sign in with your email, Google or GitHub account, or from -the Docker CLI. - -### Sign in with email or Docker ID - -1. Go to the [Docker sign in page](https://login.docker.com). -1. Enter your email address or Docker ID and select **Continue**. -1. Enter your password and select **Continue**. - -To reset your password, see [Reset your password](#reset-your-password). - -### Sign in with Google or GitHub - -You can sign in using your Google or GitHub credentials. If your social -account uses the same email address as an existing Docker ID, the -accounts are automatically linked. - -If no Docker ID exists, Docker creates a new account for you. - -Docker doesn't support linking multiple sign-in methods -to the same Docker ID. - -### Sign in using the CLI - -Use the `docker login` command to authenticate from the command line. For -details, see [`docker login`](/reference/cli/docker/login/). - -> [!WARNING] -> -> The `docker login` command stores credentials in your home directory under -> `.docker/config.json`. The password is base64-encoded. -> -> To improve security, use -> [Docker credential helpers](https://github.com/docker/docker-credential-helpers). -> For even stronger protection, use a [personal access token](../security/access-tokens.md) -> instead of a password. This is especially useful in CI/CD environments -> or when credential helpers aren't available. - -## Reset your password - -To reset your password: - -1. Go to the [Docker sign in page](https://login.docker.com/). -1. Enter your email address. -1. When prompted for your password, select **Forgot password?**. - -## Troubleshooting - -If you have a paid Docker subscription, -[contact the Support team](https://hub.docker.com/support/contact/) for assistance. - -All Docker users can seek troubleshooting information and support through the -following resources, where Docker or the community respond on a best effort -basis: - -- [Docker Community Forums](https://forums.docker.com/) -- [Docker Community Slack](http://dockr.ly/comm-slack) diff --git a/content/manuals/accounts/deactivate-user-account.md b/content/manuals/accounts/deactivate-user-account.md deleted file mode 100644 index c3bf2eb8ae2b..000000000000 --- a/content/manuals/accounts/deactivate-user-account.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Deactivate a Docker account -linkTitle: Deactivate an account -weight: 30 -description: Learn how to deactivate a Docker user account. -keywords: Docker Hub, delete, deactivate, account, account management, delete Docker account, close Docker account, disable Docker account ---- - -Learn how to deactivate an individual Docker account, including prerequisites required -for deactivation. - -For information on deactivating an organization, -see [Deactivating an organization](../admin/organization/deactivate-account.md). - -> [!WARNING] -> -> All Docker products and services that use your Docker account are -> inaccessible after deactivating your account. - -## Prerequisites - -Before deactivating your Docker account, ensure you meet the following requirements: - -- If you are an organization or company owner, you must leave your organization - or company before deactivating your Docker account: - 1. Sign in to [Docker Home](https://app.docker.com/admin) and choose - your organization. - 1. Select **Members** and find your username. - 1. Select the **Actions** menu and then select **Leave organization**. -- If you are the sole owner of an organization, you must assign the owner role - to another member of the organization and then remove yourself from the - organization, or deactivate the organization. Similarly, if you are the sole - owner of a company, either add someone else as a company owner and then remove - yourself, or deactivate the company. -- If you have an active Docker subscription, [downgrade it to a Docker Personal subscription](../subscription/change.md). -- Download any images and tags you want to keep. Use `docker pull -a <image>` - to pull all tags, or `docker pull <image>:<tag>` to pull a specific tag. -- Unlink your [GitHub and account](../docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account). - -## Deactivate - -Once you have completed all the previous steps, you can deactivate your account. - -> [!WARNING] -> -> Deactivating your account is permanent and can't be undone. Make sure -> to back up any important data. - -1. Sign in to [Docker Home](https://app.docker.com/login). -1. Select your avatar to open the drop-down menu. -1. Select **Account settings**. -1. Select **Deactivate**. -1. Select **Deactivate account**, then select again to confirm. - -## Delete personal data - -Deactivating your account does not delete your personal data. To request -personal data deletion, fill out Docker's -[Privacy request form](https://preferences.docker.com/). diff --git a/content/manuals/accounts/general-faqs.md b/content/manuals/accounts/general-faqs.md deleted file mode 100644 index 2b927f6e53cf..000000000000 --- a/content/manuals/accounts/general-faqs.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: FAQs on Docker accounts -linkTitle: Accounts -weight: 10 -description: Frequently asked questions about Docker accounts -keywords: onboarding, docker, teams, orgs, user accounts, organization accounts -tags: [FAQ] -aliases: - - /docker-hub/general-faqs/ - - /docker-hub/onboarding-faqs/ - - /faq/admin/general-faqs/ - - /admin/faqs/general-faqs/ ---- - -### What is a Docker ID? - -A Docker ID is a username for your Docker account that lets you access Docker -products. To create a Docker ID you need one of the following: - -- An email address -- A social account -- A GitHub account - -Your Docker ID must be between 4 and 30 characters long, and can only contain -numbers and lowercase letters. You can't use any special characters or spaces. - -For more information, see [Create a Docker ID](/manuals/accounts/create-account.md). - -### Can I change my Docker ID? - -No. You can't change your Docker ID once it's created. If you need a different -Docker ID, you must create a new Docker account with a new Docker ID. - -Docker IDs can't be reused after deactivation. - -### What if my Docker ID is taken? - -All Docker IDs are first-come, first-served except for companies that have a -U.S. Trademark on a username. - -If you have a trademark for your namespace, -[Docker Support](https://hub.docker.com/support/contact/) can retrieve the -Docker ID for you. - -### What's an organization name or namespace? - -The organization name, sometimes referred to as the organization namespace or -the organization ID, is the unique identifier of a Docker organization. The -organization name can't be the same as an existing Docker ID. diff --git a/content/manuals/accounts/individual/_index.md b/content/manuals/accounts/individual/_index.md new file mode 100644 index 000000000000..94b0ca01e4b7 --- /dev/null +++ b/content/manuals/accounts/individual/_index.md @@ -0,0 +1,69 @@ +--- +title: Docker individual accounts +linkTitle: Individual +description: > + What a Docker account is, how a Docker ID relates to your email and + sign-in method, and how the account connects to an organization +keywords: Docker ID, username, email, Google, GitHub, sign-in, + authentication, individual account, organization account, organization + namespace, convert account, Docker Hub, Docker Desktop, SSO, deactivate + account +weight: 10 +grid: + - title: Set up your account + description: Create a Docker account with email, Google, or GitHub. + icon: finger-print + link: /accounts/individual/create-account/ + - title: Manage account + description: Update your profile, email, password, and connected accounts. + icon: cog + link: /accounts/individual/manage-account/ + - title: Personal access tokens + description: Create and manage personal access tokens. + icon: lock-closed + link: /security/access-tokens/ + - title: Manage two-factor authentication + description: Turn two-factor authentication on or off. + icon: device-phone-mobile + link: /security/authentication/2fa/manage/ + - title: Organization accounts + description: Create and manage organization accounts. + icon: building-storefront + link: /accounts/organization/ + - title: Account FAQs + description: Common questions about Docker accounts. + icon: question-mark-circle + link: /faqs/accounts/ +--- + +A Docker account is how Docker identifies you. Use it to access products like +Docker Hub and Docker Desktop, manage settings, and join organizations. + +## Docker ID, email, and sign-in + +When you create an account, you choose a Docker ID and a sign-in method. +Docker also ties a verified email to the account. + +- Your Docker account associates your plans, Hub repositories, and account + settings. +- A Docker ID is a unique username that identifies you. Your Docker ID is + permanent and stays the same when you change your email or sign-in + method. +- Your email is how Docker contacts you for notifications and + security-related communications. +- You can sign in with email and password, Google, or GitHub. An + organization or company you belong to can require + [single sign-on (SSO)](/manuals/security/authentication/single-sign-on/_index.md). + +## Individual and organization accounts + +When you join an organization, you use your individual account and its +Docker ID. To learn more about organization accounts, see +[Organization accounts](/manuals/accounts/organization/_index.md). To +transfer your Docker ID to an organization namespace, see +[Convert a Docker account to an +organization](/manuals/accounts/organization/setup/convert-account.md). + +## Next steps + +{{< grid >}} diff --git a/content/manuals/accounts/individual/create-account.md b/content/manuals/accounts/individual/create-account.md new file mode 100644 index 000000000000..8b4d9b5c3b80 --- /dev/null +++ b/content/manuals/accounts/individual/create-account.md @@ -0,0 +1,81 @@ +--- +title: Create a Docker account +linkTitle: Setup +weight: 10 +description: Create a Docker ID with email, Google, or GitHub, then verify your + account +keywords: + create docker account, docker ID, sign up, sign in, email, Google, GitHub, + Work, Personal, verification, OTP, password, docker login, username + requirements +aliases: + - /accounts/create-account/ + - /docker-hub/accounts/ + - /docker-id/ +--- + +You can create a Docker account with email, Google, or GitHub. Creating an +account gives you a Docker ID, which is your username for Docker Hub, +Docker Desktop, Docker Scout, and +[Docker forums](https://forums.docker.com/). + +> [!TIP] +> +> Ready to move from Docker Personal to Docker Pro? +> [Upgrade your subscription](https://www.docker.com/pricing?ref=Docs&refAction=DocsCreateAccount). + +## Create and verify your account + +Every sign-up path requires verification before you can sign in. Docker +blocks sign-in until you've verified your account. + +### Email + +Create an account with an email address and password, then verify with a +six-digit code Docker emails you. + +1. Go to the [Docker sign-up page](https://app.docker.com/signup/). +1. Select **Work** or **Personal**, then enter a unique, valid email address. +1. Enter a username to use as your Docker ID. Your Docker ID is permanent. + Your username: + - Must be between 4 and 30 characters long + - Can only contain letters and numbers. Docker stores it in lowercase. + - Must not be an email address +1. Choose a password between 9 and 128 characters long, then select + **Sign up**. +1. Enter the six-digit code from the Docker verification email. This + completes the registration process. + +### Google or GitHub + +Create an account with Google or GitHub. Docker uses the email on that +provider account, and you do not set a Docker password during sign-up. +Verify that email with the provider before you continue. + +1. Go to the [Docker sign-up page](https://app.docker.com/signup/). +1. Select **Continue with Google** or **Continue with GitHub**. +1. Select the social account you want to link to your Docker account. +1. Authorize Docker to access your social account information. Docker + redirects you to the sign-up page. +1. Enter a username to use as your Docker ID. Your Docker ID is permanent. + Your username: + - Must be between 4 and 30 characters long + - Can only contain letters and numbers. Docker stores it in lowercase. + - Must not be an email address +1. Select **Sign up**. + +## Troubleshooting + +All Docker users can find troubleshooting help through the +[Docker Community Forums](https://forums.docker.com/) and the +[Docker Community Slack](https://dockr.ly/comm-slack). Docker or the +community respond on a best-effort basis. + +If you have a paid Docker subscription, +[contact the Support team](https://hub.docker.com/support/contact/) for +help. + +## Next steps + +- [Manage a Docker account](/manuals/accounts/individual/manage-account.md) +- [Enable two-factor authentication](/manuals/security/authentication/2fa/manage.md) diff --git a/content/manuals/accounts/individual/deactivate-user-account.md b/content/manuals/accounts/individual/deactivate-user-account.md new file mode 100644 index 000000000000..91cec43415a4 --- /dev/null +++ b/content/manuals/accounts/individual/deactivate-user-account.md @@ -0,0 +1,63 @@ +--- +title: Deactivate a Docker account +linkTitle: Deactivate +weight: 30 +description: Prerequisites and steps to deactivate an individual Docker account +keywords: + deactivate docker account, delete docker account, close docker account, + disable docker account, account management, leave organization, backup + repositories, privacy request, personal data +aliases: + - /accounts/deactivate-user-account/ +--- + +When you deactivate an individual Docker account, Docker removes all of +your public and private repositories. All Docker products and services +that use your Docker account are inaccessible after deactivation. + +> [!WARNING] +> +> Back up any important data before you continue. Deactivating your account is +> permanent and cannot be undone. + +## Before you deactivate + +Before deactivating your Docker account, complete the following +requirements: + +- If you are an organization or company owner, you must [leave your + organization or + company](/manuals/accounts/organization/setup/convert-account.md#leave-an-existing-organization) + before deactivating your Docker account. +- If you have an active Docker subscription, + [downgrade it to a Docker Personal + subscription](/manuals/subscription-billing/plans/docker.md#cancel-a-docker-plan). + This includes paid Docker Scout and Docker Build Cloud plans. +- Pull any images and tags you want to keep. +- If you linked a GitHub or Bitbucket account for automated builds, unlink + it. See + [Unlink a GitHub user + account](/manuals/docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account) + or + [Unlink a Bitbucket user + account](/manuals/docker-hub/repos/manage/builds/link-source.md#unlink-a-bitbucket-user-account). + +## Deactivate + +The **Deactivate account** button stays unavailable until you complete +the deactivation requirements. + +1. Sign in to [Docker Home](https://app.docker.com/login). +1. Select your avatar to open the drop-down menu. +1. Select **Account settings**. +1. Select **Deactivate**. +1. Enter your username in the **User account** field. +1. Select **Deactivate account**. + +Docker signs you out after it deactivates your account. + +## Delete personal data + +Deactivating your account does not delete your personal data. To request +personal data deletion, fill out Docker's +[Privacy request form](https://preferences.docker.com/). diff --git a/content/manuals/accounts/individual/manage-account.md b/content/manuals/accounts/individual/manage-account.md new file mode 100644 index 000000000000..a54ff4a0c0fd --- /dev/null +++ b/content/manuals/accounts/individual/manage-account.md @@ -0,0 +1,118 @@ +--- +title: Manage a Docker account +linkTitle: Manage +weight: 20 +description: Update your profile, email, password, and connected Google or + GitHub accounts +keywords: + manage docker account, account settings, account information, full name, + update email, verify email, change password, reset password, Google, + GitHub, connected accounts, two-factor authentication, personal access + tokens, convert account, deactivate account, Docker Home +aliases: + - /accounts/manage-account/ +--- + +Update your profile, email, password, and Google or GitHub sign-in. + +## Update account information + +Other Docker users can see your account information. + +1. Sign in to [Docker Home](https://app.docker.com/login). +1. Select your avatar in the top-right corner and select + **Account settings**. +1. Select **Account information**. +1. Update any of these fields, then select **Save**: + - **Full name** + - **Company** + - **Location** + - **Website** + - **Gravatar email** + +## Update email address + +A Docker account has one verified email address. If your account uses +single sign-on (SSO) or System for Cross-domain Identity Management +(SCIM) provisioning, contact your administrator to change your email. + +1. Sign in to [Docker Home](https://app.docker.com/login). +1. Select your avatar in the top-right corner and select + **Account settings**. +1. Select **Email**. +1. Enter the new address in **New email address**. +1. Enter your password in **Enter your password to confirm**. +1. Select **Verify email**. +1. Enter the six-digit code in **Enter code**. The code expires after 15 + minutes. +1. Sign in again to finish the update. + +## Change your password + +If your account uses single sign-on (SSO), contact your administrator to +change your password. + +1. Sign in to [Docker Home](https://app.docker.com/login). +1. Select your avatar in the top-right corner and select + **Account settings**. +1. Select **Password**. +1. Select **Reset password**. + +Docker emails you instructions to reset your password. + +You can also +[update or delete personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md#update-or-delete) +and +[update your two-factor authentication](/manuals/security/authentication/2fa/manage.md#disable-two-factor-authentication). + +## Manage connected accounts + +Google or GitHub appears under **Connected accounts** after you connect +that provider. There is no connect button on this page. You connect by +signing in with the provider. + +### Connect provider + +> [!IMPORTANT] +> +> If the Google or GitHub email does not match your Docker account email, +> Docker starts a new sign-up and creates a second account instead of +> linking the provider. + +Sign in with Google or GitHub using the same email as your Docker account +to add that provider as a sign-in method. + +1. Sign out of Docker if you are already signed in. +1. Go to the [Docker sign-in page](https://app.docker.com/login). +1. Select **Continue with Google** or **Continue with GitHub**. +1. Choose a Google or GitHub account that uses the same email address as + your Docker account, then finish the provider sign-in. + +Docker links the provider to your account and emails you a confirmation. +The provider then appears in **Connected accounts** under **Account +settings**. + +### Disconnect provider + +Remove Google or GitHub as a sign-in method from **Connected accounts**. +Your Docker ID stays the same. + +1. Sign in to [Docker Home](https://app.docker.com/login). +1. Select your avatar in the top-right corner and select + **Account settings**. +1. Select **Connected accounts**. +1. Select **Disconnect** on that provider. + +To remove Docker from the Google or GitHub account, see that provider's +documentation: + +- [Manage connections between your Google Account and + third-parties](https://support.google.com/accounts/answer/13533235?hl=en) +- [Reviewing and revoking authorization of GitHub + Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps) + +## Next steps + +- [Manage two-factor authentication](/manuals/security/authentication/2fa/manage.md) +- [Create and manage personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md) +- [Convert a Docker account to an organization](/manuals/accounts/organization/setup/convert-account.md) \ No newline at end of file diff --git a/content/manuals/accounts/manage-account.md b/content/manuals/accounts/manage-account.md deleted file mode 100644 index 5c05f335622e..000000000000 --- a/content/manuals/accounts/manage-account.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Manage a Docker account -linkTitle: Manage an account -weight: 20 -description: Learn how to manage your Docker account. -keywords: accounts, docker ID, account settings, account management, docker home ---- - -You can centrally manage your Docker account using Docker Home, including -administrative and security settings. - -> [!TIP] -> -> If your account is associated with an organization that enforces single -> sign-on (SSO), you may not have permissions to update your account settings. -> You must contact your administrator to update your settings. - -## Update account information - -Account information is visible on your **Account settings** page. You can -update the following account information: - -- Full name -- Company -- Location -- Website -- Gravatar email - -To add or update your avatar using Gravatar: - -1. Create a [Gravatar account](https://gravatar.com/). -1. Create your avatar. -1. Add your Gravatar email to your Docker account settings. - -It may take some time for your avatar to update in Docker. - -## Update email address - -To update your email address: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Go to **Settings**, then choose **Email**. -1. Enter your new email address and confirm your identity with your password. Select **Verify email**. -1. Go to the new Docker email and copy the 6-digit verification code. -1. Paste the verification code to complete updating your email. - -Your verification session expires after 15 minutes. - -> [!NOTE] -> -> Docker accounts only support one verified email address at a time, which -> is used for account notifications and security-related communications. You -> can't add multiple verified email addresses to your account. - -## Change your password - -You can change your password by initiating a password reset via email. To change your password: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner and select **Account settings**. -1. Select **Password**, then **Reset password**. -1. Docker will send you a password reset email with instructions to reset - your password. - -## Manage two-factor authentication - -To update your two-factor authentication (2FA) settings: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner and select **Account settings**. -1. Select **2FA**. - -For more information, see -[Enable two-factor authentication](../security/2fa/_index.md). - -## Manage personal access tokens - -To manage personal access tokens: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner and select **Account settings**. -1. Select **Personal access tokens**. - -For more information, see -[Create and manage access tokens](../security/access-tokens.md). - -## Manage connected accounts - -You can unlink connected Google or GitHub accounts: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner and select **Account settings**. -1. Select **Connected accounts**. -1. Select **Disconnect** on your connected account. - -To fully unlink your Docker account, you must also unlink Docker from Google -or GitHub. See Google or GitHub's documentation for more information: - -- [Manage connections between your Google Account and third-parties](https://support.google.com/accounts/answer/13533235?hl=en) -- [Reviewing and revoking authorization of GitHub Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps) - -## Convert your account - -For information on converting your account into an organization, see -[Convert an account into an organization](../admin/organization/setup/convert-account.md). - -## Deactivate your account - -For information on deactivating your account, see -[Deactivating a user account](./deactivate-user-account.md). diff --git a/content/manuals/accounts/organization/_index.md b/content/manuals/accounts/organization/_index.md new file mode 100644 index 000000000000..5b1fdaa759ff --- /dev/null +++ b/content/manuals/accounts/organization/_index.md @@ -0,0 +1,91 @@ +--- +title: Organization accounts +linkTitle: Organization +description: How Docker organizations relate to members, teams, and + repositories. +keywords: admin, organization, Docker Home, user accounts, account management, + roles, members, permissions, organization settings, owners, teams, + repositories +weight: 15 +grid: + - title: Set up your organization + description: Create, onboard, and configure your organization. + icon: magnifying-glass-plus + link: /accounts/organization/setup/ + - title: Manage your organization + description: Manage members, teams, seats, and product access. + icon: user-plus + link: /accounts/organization/manage/ + - title: Activity logs + description: Review member activity across your organization and + repositories. + icon: clipboard-document-list + link: /accounts/organization/activity-logs/ + - title: Insights + description: See how people in your organization use Docker. + icon: chart-bar + link: /accounts/organization/insights/ + - title: Security + description: Explore security features for administrators. + icon: shield-check + link: /security/ +aliases: + - /admin/ + - /docker-hub/admin-overview + - /admin/organization/ + - /accounts/organization/overview/ +--- + +A Docker organization is a shared workspace for members and repositories +under one namespace. +Organization owners administer membership, access, and security. + +## Organization structure + +Organization owners manage organizations that contain members, +repositories, and teams, which group members within an +organization. + +The following diagram shows that hierarchy: + +```mermaid {title="Organization structure" caption="Organization owners manage an organization that contains members, repositories, and optional teams."} +flowchart TB + oo(("Organization owners")) -.->|"manage"| org + subgraph org["Organization"] + direction TB + m(("Members")) + subgraph t["Teams (optional)"] + tm(("Members")) + end + r[("Repositories")] + end + style org fill:#3b82f622,stroke:#3b82f6 + style t stroke-dasharray: 5 5 +``` + +### Owners + +Organization owners administer the organization. They invite members, assign +roles, and manage teams and repositories. + +An organization can have multiple owners. All owners share the same +predefined permissions. For other roles and their permissions, see +[Roles and permissions](/manuals/security/roles-and-permissions/_index.md). + +### Members + +A member is a Docker user invited to the organization. Organization owners +assign a role to each member, and that role sets organization-wide access. + +### Teams + +Teams are optional. They group members so you can grant repository +access to many people at once. Use a team when several members need the +same repositories. Members can belong to the organization without joining +a team. + +## Next steps + +Learn how to manage organizations in the following sections. + +{{< grid >}} diff --git a/content/manuals/accounts/organization/activity-logs.md b/content/manuals/accounts/organization/activity-logs.md new file mode 100644 index 000000000000..db269a80ca56 --- /dev/null +++ b/content/manuals/accounts/organization/activity-logs.md @@ -0,0 +1,255 @@ +--- +title: Activity logs +weight: 40 +description: >- + View, filter, and export organization and repository activity logs in Docker + Home. +keywords: >- + activity logs, audit logs, Docker Home, organization activity, repository + activity, filter activity logs, export CSV, security audit trail +aliases: +- /admin/activity-logs/ +- /docker-hub/audit-log/ +- /admin/organization/activity-logs/ +--- + +{{< summary-bar feature_name="Activity logs" >}} + +Activity logs show a chronological list of organization and repository +changes in Docker Home. Use them to see what changed, when it changed, and who +made the change. + +Organization owners and members with a custom role that includes the +**View activity logs** permission can open the activity log. + +> [!TIP] +> +> Use activity logs for an admin audit trail of your organization and +> repositories, including AI Governance policy and settings changes. For +> enforcement events, such as policy decisions and sandbox sessions, see +> [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md). + +## Access activity logs + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Select **Activity**. + +To query activity logs programmatically, use the +[Audit logs endpoints](/reference/api/hub/latest/#tag-audit-logs) in the +Docker Hub API. The API returns events from the last 3 months, up to 31 days +per request. + +### Filter by date + +By default, the **Activity** page shows events from the last 7 days. Docker +Home keeps activity logs for 90 days, and you can query up to 30 days at a +time. + +1. On the **Activity** page, select the **Date range** field. +1. Select a preset such as **Today**, **Yesterday**, **This week**, **This + month**, **Last 7 days**, or **Last 30 days**, or type a start date and an + end date. + +On the calendar, you can select dates in the 30 days leading up to the end +date. To view an earlier period within the 90-day retention window, type the +start date and the end date in the field. + +The log updates to show only the activities that occurred during that period. + +### Filter by type + +To show only one category of events: + +1. On the **Activity** page, open the **All activities** drop-down and select + a category: + - **Organization**: Organization management events + - **Repository**: Events from repositories for every repository that belongs + to the organization + - **Enterprise**: Configuration events for company settings + - **Billing**: Subscription change events + - **OIDC**: OIDC setup events + - **Offload**: Docker Offload usage + - **Governance**: Admin configuration events for AI Governance +1. Optional. From the **All Actions** drop-down, select a specific event type + within that category. + +### Export + +To download activity logs as a CSV file from the **Activity** page: + +1. Optional. Apply a date range or activity type filter. The export includes + only the events that match your current filters. +1. Select the export icon next to the date range. + +## Activity log events reference + +{{< accordion title="Organization" >}} + +The following table lists organization events that cover teams, members, SSO +domains, access tokens, and custom roles. + +| Event | Description | +|:------|:------------| +| Team Created | Team was created | +| Team Updated | Team was modified | +| Team Deleted | Team was deleted | +| Team Member Added | Member was added to a team | +| Team Member Removed | Member was removed from a team | +| Org Member Invited | Member was invited to the organization | +| Organization Member Added | Member was added to the organization | +| Organization Member Removed | Member was removed from the organization | +| Member Role Changed | Member's role in the organization was changed | +| Organization Created | Organization was created | +| Organization Settings Updated | Organization setting was updated | +| Registry Access Management enabled | Registry Access Management was enabled | +| Registry Access Management disabled | Registry Access Management was disabled | +| Registry Access Management registry added | Registry was added | +| Registry Access Management registry removed | Registry was removed | +| Registry Access Management registry updated | Registry was updated | +| Single Sign-On domain added | SSO domain was added | +| Single Sign-On domain deleted | SSO domain was removed | +| Single Sign-On domain verified | SSO domain was verified | +| Organization Auto-Provisioning Toggled | Auto-provisioning was turned on or off for a domain | +| Access token created | Access token was created | +| Access token updated | Access token was updated | +| Access token revoked | Access token was revoked | +| Access token deleted | Access token was deleted | +| Custom role created | Custom role was created | +| Custom role updated | Custom role was updated | +| Custom role deleted | Custom role was deleted | + +{{< /accordion >}} + +{{< accordion title="Enterprise" >}} + +The following table lists enterprise events that cover settings policies and +company-level SSO and SCIM connections. + +| Event | Description | +|:------|:------------| +| Policy created | Settings policy was added | +| Policy updated | Settings policy was updated | +| Policy deleted | Settings policy was deleted | +| Policy transferred | Settings policy was transferred to another owner | +| Create SSO Connection | Organization or company SSO connection was created | +| Update SSO Connection | Organization or company SSO connection was updated | +| Delete SSO Connection | Organization or company SSO connection was deleted | +| Enforce SSO | SSO enforcement was toggled on a connection | +| Enforce SCIM | SCIM was toggled on a connection | +| Refresh SCIM Token | SCIM token was refreshed | +| Change SSO Connection Type | Connection type was changed | +| Toggle JIT provisioning | JIT provisioning was toggled on a connection | + +{{< /accordion >}} + +{{< accordion title="Repository" >}} + +The following table lists repository events that cover create, delete, privacy, +tags, and related repository changes. + +> [!NOTE] +> +> Event descriptions that include a user action can refer to a Docker username, +> personal access token (PAT), or organization access token (OAT). For example, +> if a user pushes a tag, the description may show: +> `<user-access-token>` pushed the tag to the repository. + +| Event | Description | +|:------|:------------| +| Repository Created | Repository was created | +| Repository Deleted | Repository was deleted | +| Repository Updated | Repository description, full description, or status was updated | +| Privacy Changed | Repository privacy settings were updated | +| Tag Pushed | Tags were pushed | +| Tag Deleted | Tags were deleted | +| Categories updated | Repository categories were set or updated | +| Tag immutability updated | Tag immutability was updated | + +{{< /accordion >}} + +{{< accordion title="Billing" >}} + +The following table lists billing events that cover plan changes, seats, and +license assignment. + +| Event | Description | +|:------|:------------| +| Plan Upgraded | Billing plan was upgraded | +| Plan Downgraded | Billing plan was downgraded | +| Seat Added | Seat was added to the billing plan | +| Seat Removed | Seat was removed from the billing plan | +| Billing Cycle Changed | Billing cycle interval was changed | +| Plan Downgrade Canceled | Scheduled plan downgrade was canceled | +| Seat Removal Canceled | Scheduled seat removal was canceled | +| Plan Upgrade Requested | User requested a plan upgrade | +| Plan Downgrade Requested | User requested a plan downgrade | +| Seat Addition Requested | User requested additional seats | +| Seat Removal Requested | User requested fewer seats | +| Billing Cycle Change Requested | User requested a billing cycle change | +| Plan Downgrade Cancellation Requested | User requested cancellation of a scheduled plan downgrade | +| Seat Removal Cancellation Requested | User requested cancellation of a scheduled seat removal | +| Billing Product Changed | Subscribed product was changed | +| License Assigned | Product license was assigned to a user | +| License Removed | Product license was removed from a user | +| Auto-assign rule created | Automatic license assignment rule was created | +| Auto-assign rule removed | Automatic license assignment rule was removed | +| Automatic License Assignment Enabled | Automatic license assignment was turned on for a product | +| Automatic License Assignment Disabled | Automatic license assignment was turned off for a product | +| Licenses Expired | Licenses expired | + +{{< /accordion >}} + +{{< accordion title="OIDC" >}} + +The following table lists OIDC events that cover creating, updating, and +deleting OIDC connections. + +| Event | Description | +|:------|:------------| +| OIDC connection created | OIDC connection was created | +| OIDC connection updated | OIDC connection was updated | +| OIDC connection deleted | OIDC connection was deleted | + +{{< /accordion >}} + +{{< accordion title="Offload" >}} + +The following table lists Offload events that cover lease start and end. + +> [!NOTE] +> +> Event descriptions show the Docker username of the actor and details about +> the lease. + +| Event | Description | +|:------|:------------| +| Offload lease start | Offload lease started | +| Offload lease end | Offload lease ended | + +{{< /accordion >}} + +{{< accordion title="Governance" >}} + +The following table lists governance events that cover the AI Governance +admin audit trail, such as policy and settings changes. For enforcement +events, such as policy decisions and sandbox sessions, see +[AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md). + +| Event | Description | +|:------|:------------| +| AI Governance Policy created | AI governance policy was created | +| AI Governance Policy updated | AI governance policy was updated | +| AI Governance Policy deleted | AI governance policy was deleted | +| AI Governance Settings updated | AI governance settings were updated | + +{{< /accordion >}} + +## Next steps + +- [Roles and permissions](/manuals/security/roles-and-permissions/_index.md) for + the **View activity logs** permission and custom roles +- [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md) for + enforcement events such as policy decisions and sandbox sessions +- [Audit logs API](/reference/api/hub/latest/#tag-audit-logs) to query events + programmatically diff --git a/content/manuals/accounts/organization/insights.md b/content/manuals/accounts/organization/insights.md new file mode 100644 index 000000000000..c40fef0921b3 --- /dev/null +++ b/content/manuals/accounts/organization/insights.md @@ -0,0 +1,174 @@ +--- +title: View organization Insights for Docker Desktop +linkTitle: Insights +weight: 50 +description: >- + View Docker Desktop usage for your organization in Insights, including + active users, builds, containers, images, and extensions. +keywords: organization, Insights, Desktop insights, Docker Desktop analytics, + Send usage statistics, analyticsEnabled, active users, builds, containers, + images, extensions, export Docker Desktop users, Docker Business +aliases: + - /admin/insights/ +--- + +{{< summary-bar feature_name="Insights" >}} + +Insights shows organization administrators how people in their organization +use Docker Desktop. Use it to track adoption, spot version and platform +patterns, and see where builds, containers, images, and extensions are in +use. + +> [!TIP] +> +> After +> [upgrading to Docker Business](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminInsights), +> you must reach out to your Docker account team to enable Insights for +> your organization. + +## Prerequisites + +To use Insights, you must meet the following requirements: + +- A Docker Business subscription +- Administrators must + [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) + for users +- Docker Desktop users must have + [Send usage + statistics](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#send-usage-statistics) + enabled (`analyticsEnabled`). You can set this for every user through + [Settings + Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). + +## View Insights {#view-insights-for-organization-users} + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Docker Desktop**, then **Desktop insights**. +1. Select a time period: **1 Week**, **1 Month**, or **3 Months**. Data + may be delayed 24–48 hours. **Last updated** shows the sync date. + +## Export Docker Desktop user data + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Docker Desktop**, then **Desktop insights**. +1. Select **Export Docker Desktop users**. The CSV file downloads + automatically. It includes the standard + [member CSV fields](/manuals/accounts/organization/manage/members.md#export-a-member-list-csv), + plus these Insights columns: + + | Column | Description | + | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | Last Logged-in Date | Last browser sign-in to Docker Hub or Docker Home | + | Docker Desktop Version | Last Docker Desktop version the user ran | + | Last Seen Date | Last time the user ran Docker Desktop | + | Opted Out Analytics | Whether the user turned off [Send usage statistics](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#send-usage-statistics) | + +## Reference + +The Insights dashboard is organized into sections that capture each area of +Docker Desktop activity. Refer to these tables when a value looks +unexpected, when you need to explain a metric to someone else, or when +you're deciding which section answers a question about adoption, build +health, or image usage. + +{{< accordion title="Docker Desktop users" >}} + +The Docker Desktop users section shows how many people in your organization +run Docker Desktop and how that number changes over time. Use it to measure +adoption and to find users missing from the active counts. Active counts +include only users who send analytics. + +| Data | Description | +| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Active members | Users who used Docker Desktop and signed in with a licensed account in your organization, or with an email address from a domain associated with your organization. | +| Total org members | Users who have used Docker Desktop, regardless of their Insights activity. | +| Members opted out of analytics | Organization members who opted out of sending analytics. | +| Registered users | Users linked to unassociated machines whose email addresses Docker captured, and those emails are outside your organization's domain. | +| Active users (graph) | Total active users over time. | + +{{< /accordion >}} + +{{< accordion title="Builds" >}} + +The Builds section shows how often users build images, how long builds take, +and how many succeed. Use it to spot slow or failing builds across the +organization and to gauge how much of your Docker Desktop usage is build +activity. + +| Data | Description | +| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Average build per user | Average builds per active user. A build includes any time a user runs one of: `docker buildx bake`, `docker buildx build`, `docker buildx f`, `docker builder build`, `docker builder f`, `docker compose build`, or `docker image build`. | +| Average build time | Average build time per build. | +| Build success rate | Percentage of builds that exited normally. A failed build is any build that exits abnormally. | +| Total builds (graph) | Successful builds versus failed builds over time. | + +{{< /accordion >}} + +{{< accordion title="Containers" >}} + +The Containers section shows how many containers active users run and how +that activity trends over time. Use it to see how heavily your organization +relies on Docker Desktop for running workloads, not only for building them. + +| Data | Description | +| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Total containers run | Containers run by active users in the Docker Desktop GUI, with `docker run`, or with `docker compose`. | +| Average number of containers run | Average containers run per active user. | +| Containers run by active users (graph) | Containers run over time by active users. | + +{{< /accordion >}} + +{{< accordion title="Docker Desktop usage" >}} + +The Docker Desktop usage section shows which versions, operating systems, +and interfaces your users run. Use it to plan upgrades, find users on +outdated versions, and understand whether your organization works mainly +through the CLI or the GUI. + +| Data | Description | +| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Most used version | Most used Docker Desktop version in your organization. | +| Most used OS | Most used operating system. | +| Versions by active users (graph) | Active users per Docker Desktop version. See the [Docker Desktop release notes](/manuals/desktop/release-notes.md). | +| Interface by active users (graph) | Active users by interface. A CLI user has run a `docker` command. A GUI user has used the Docker Desktop graphical interface. | + +{{< /accordion >}} + +{{< accordion title="Docker Hub images" >}} + +The Docker Hub images section shows which images your users pull and push, +and how often. Use it to see which images matter most to your organization +and to confirm that users pull from the sources you expect. Image data +covers Docker Hub only. Third-party registries and mirrors are excluded. + +| Data | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------ | +| Total pulled images | Images pulled by active users. | +| Total pushed images | Images pushed. | +| Top pulled images | Top images pulled, and how many times each was pulled. | + +{{< /accordion >}} + +{{< accordion title="Extensions" >}} + +The Extensions section shows how widely Docker Desktop extensions are used +in your organization and which ones users install most. Use it to find +popular tools worth supporting and to spot extensions you did not +expect. + +| Data | Description | +| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | +| Percentage of org with extensions installed | Percentage of users with at least one extension installed. | +| Top extensions installed in the organization | Top extensions installed, and how many users installed each one. | + +{{< /accordion >}} + +## Next steps + +- [Activity logs](/manuals/accounts/organization/activity-logs.md) for a + record of organization and repository changes. +- [Insights FAQs](/manuals/faqs/accounts.md#why-is-insights-data-missing-for-some-users) + to troubleshoot missing data. diff --git a/content/manuals/accounts/organization/manage/_index.md b/content/manuals/accounts/organization/manage/_index.md new file mode 100644 index 000000000000..725b428c2ee0 --- /dev/null +++ b/content/manuals/accounts/organization/manage/_index.md @@ -0,0 +1,76 @@ +--- +title: Manage your organization +linkTitle: Manage +weight: 20 +description: Learn how to manage your Docker organization, including members, teams, licenses, seats, product access, and settings. +keywords: manage organization, members, teams, licenses, seats, product access, organization management, docker home, organization settings, deactivate organization +grid: + - title: Information + description: Update your organization's general information and settings. + icon: pencil-square + link: /accounts/organization/manage/general-settings/ + - title: Members + description: Invite, manage, and assign roles to your organization members. + icon: user-plus + link: /accounts/organization/manage/members/ + - title: Teams + description: Create teams and manage repository access for groups of members. + icon: user-group + link: /accounts/organization/manage/manage-a-team/ + - title: Licenses + description: View your license inventory and assign licenses to teams or individual members. + icon: key + link: /accounts/organization/manage/manage-licenses/ + - title: Seats + description: Add or remove seats for Docker Team and Business subscriptions. + icon: user-circle + link: /accounts/organization/manage/manage-seats/ + - title: Products + description: Manage access and view usage for Docker products across your organization. + icon: squares-2x2 + link: /accounts/organization/manage/manage-products/ + - title: Deactivation + description: Deactivate an organization after completing the required steps. + icon: minus-circle + link: /accounts/organization/manage/deactivate-account/ + - title: Security + description: Configure single sign-on, provisioning, and access management. + icon: shield-check + link: /security/ + - title: Billing + description: Manage payment methods and view billing history. + icon: credit-card + link: /subscription-billing/ +aliases: + - /admin/organization/manage/ +--- + +As an organization owner, you manage your organization's membership, access, +product usage, and settings. You can invite members, group them into teams, +assign or revoke licenses and seats, change access to Docker products, update +organization information, and deactivate the organization. + +## Managing your organization + +You manage your organization from [Docker Home](https://app.docker.com) and +must be assigned the +[organization owner role](/manuals/security/roles-and-permissions/_index.md). + +## Seats and licenses + +Seats and licenses both control access, but they apply to different kinds of +plans. The following table summarizes the difference. + +| Entitlement | What it grants | Applies to | Managed from | +| ----------- | ------------------------------------------------------- | ------------------------------------------------ | ---------------------------- | +| Seat | Membership in your Docker Team or Business subscription | Docker Team or Business subscription | Billing | +| License | Access to a specific product or add-on | AI Governance, Docker Offload, and other add-ons | Licenses, Teams, and Members | + +For details, see [Seats](/manuals/accounts/organization/manage/manage-seats.md) +and [Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md). + +## Next steps + +Explore the following sections to manage your organization. + +{{< grid >}} diff --git a/content/manuals/accounts/organization/manage/deactivate-account.md b/content/manuals/accounts/organization/manage/deactivate-account.md new file mode 100644 index 000000000000..f0b14e0a3358 --- /dev/null +++ b/content/manuals/accounts/organization/manage/deactivate-account.md @@ -0,0 +1,57 @@ +--- +title: Deactivate an organization +linkTitle: Deactivation +description: Learn how to deactivate a Docker organization and required + prerequisite steps. +keywords: deactivate organization, delete organization, organization + management, Docker Home, cancel subscription, unlink GitHub, remove SSO +weight: 70 +aliases: + - /admin/organization/deactivate-account/ + - /docker-hub/deactivate-account/ + - /accounts/organization/deactivate-account/ +--- + +{{< summary-bar feature_name="General admin" >}} + +Learn how to deactivate a Docker organization, including required prerequisite +steps. For information about deactivating user accounts, see +[Deactivate a Docker +account](/manuals/accounts/individual/deactivate-user-account.md). + +> [!WARNING] +> +> All Docker products and services that use this organization are +> inaccessible after you deactivate it. Your individual Docker account +> remains active. + +## Prerequisites + +You must complete all the following steps before you can deactivate your +organization: + +- Download any images and tags you want to keep. Use `docker pull -a <image>` + to pull all tags, or `docker pull <image>:<tag>` to pull a specific tag. +- If you have an active Docker subscription, [downgrade it to a basic + organization + account](/manuals/subscription-billing/plans/docker.md#cancel-a-docker-plan). +- Remove all other members within the organization. +- Unlink your [GitHub and Bitbucket + accounts](/manuals/docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account). +- For Business organizations, [remove your SSO + connection](/manuals/security/authentication/single-sign-on/manage.md#delete-a-connection). + +## Deactivate + +> [!WARNING] +> +> Deactivating an organization is permanent and can't be undone. Make sure +> you've gathered all the data you need before you deactivate it. + +1. Sign in to [Docker Home](https://app.docker.com) and select the organization + you want to deactivate. +1. Select **Organization settings**, then **Deactivate**. If the **Deactivate** + button is unavailable, confirm you've completed all + [Prerequisites](#prerequisites). +1. Enter the organization name to confirm deactivation. +1. Select **Deactivate organization**. diff --git a/content/manuals/accounts/organization/manage/general-settings.md b/content/manuals/accounts/organization/manage/general-settings.md new file mode 100644 index 000000000000..78f9363b634e --- /dev/null +++ b/content/manuals/accounts/organization/manage/general-settings.md @@ -0,0 +1,41 @@ +--- +title: Change general organization information +linkTitle: Information +weight: 10 +description: Learn how to manage settings for organizations. +keywords: organization, settings, Docker Home, manage, Docker organization, Gravatar, SCIM, SSO setup, domain management, organization settings +aliases: + - /admin/organization/setup/general-settings/ + - /admin/organization/general-settings/ + - /accounts/organization/setup/general-settings/ +--- + +Learn how to update your organization information. + +## Update organization information + +General organization information appears on your organization landing page. + +This information includes: + +- Organization Name +- Company +- Location +- Website +- Gravatar email: To add an avatar to your Docker account, create a [Gravatar account](https://gravatar.com/) and upload an avatar. Next, add your Gravatar email to your Docker account settings. It may take some time for your avatar to update in Docker. + +To edit this information: + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization from the top-left account drop-down. +1. Select **Organization settings**. +1. Enter or update your organization’s details, then select **Save**. + +## Next steps + +After configuring your organization information, you can: + +- [Configure single sign-on (SSO)](/manuals/security/authentication/single-sign-on/connect.md) +- [Set up SCIM provisioning](/manuals/security/provisioning/scim/_index.md) +- [Manage domains](/manuals/security/provisioning/domain-management.md) +- [Create a company](/manuals/accounts/company/new-company.md) diff --git a/content/manuals/admin/organization/manage/manage-a-team.md b/content/manuals/accounts/organization/manage/manage-a-team.md similarity index 80% rename from content/manuals/admin/organization/manage/manage-a-team.md rename to content/manuals/accounts/organization/manage/manage-a-team.md index ea40e0d536bf..7c9c595068d4 100644 --- a/content/manuals/admin/organization/manage/manage-a-team.md +++ b/content/manuals/accounts/organization/manage/manage-a-team.md @@ -1,18 +1,19 @@ --- title: Create and manage a team linkTitle: Teams -weight: 20 +weight: 30 description: Learn how to create and manage teams for your organization keywords: docker, registry, teams, organizations, plans, Dockerfile, Docker Hub, docs, documentation, repository permissions, configure repository access, team management aliases: + - /admin/organization/manage/manage-a-team/ - /docker-hub/manage-a-team/ - /admin/organization/manage-a-team/ --- {{< summary-bar feature_name="Admin orgs" >}} -You can create teams for your organization in the Admin Console or Docker Hub, +You can create teams for your organization in Docker Home or Docker Hub, and configure team repository access in Docker Hub. A team is a group of Docker users that belong to an organization. An @@ -34,7 +35,7 @@ An organization owner is an administrator who has the following permissions: organization settings - Specify [permissions](#permissions-reference) for each team in the organization -- Enable [SSO](/manuals/enterprise/security/single-sign-on/_index.md) for the +- Enable [SSO](/manuals/security/authentication/single-sign-on/_index.md) for the organization When SSO is enabled for your organization, the organization owner can @@ -46,7 +47,7 @@ Organization owners can add others with the owner role to help them manage users, teams, and repositories in the organization. For more information on roles, see -[Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). +[Roles and permissions](/manuals/security/roles-and-permissions.md). ## Create a team @@ -56,11 +57,23 @@ For more information on roles, see 1. Select **Create team**. 1. Provide the team's information, then select **Create**. +Docker opens the team view, where you can add members and assign licenses. + +## Assign licenses to a team + +Each team has a **Licenses** card that lists the product licenses the team +assigns. Every member of the team receives those licenses, including members +who join later. + +To assign licenses, open the team from **Teams**, then select the **edit** icon +on the **Licenses** card. For the full procedure, what happens when you don't +have enough licenses, and what members lose when you remove a license, see +[Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md#teams). + ## Set team repository permissions You must create a team before you are able to configure repository permissions. -For more details, see [Create and manage a -team](/manuals/admin/organization/manage/manage-a-team.md). +For more details, see [Create a team](#create-a-team). To set team repository permissions: @@ -118,7 +131,10 @@ The following table shows what each permission level allows users to do: Organization owners can delete a team. When you remove a team from your organization, this action revokes member access to the team's permitted resources. It won't remove users from other teams that they belong to, and it -won't delete any resources. +won't delete any resources. Members also lose the licenses that came only from +that team, unless another team assigns the same license or they hold a direct +assignment. See +[Remove licenses](/manuals/accounts/organization/manage/manage-licenses.md#remove-licenses). 1. Sign in to [Docker Home](https://app.docker.com/) and select your organization. @@ -126,8 +142,3 @@ won't delete any resources. 1. Select the **Actions** icon next to the name of the team you want to delete. 1. Select **Delete team**. 1. Review the confirmation message, then select **Delete**. - -## More resources - -- [Video: Docker Teams](https://youtu.be/WKlT1O-4Du8?feature=shared&t=348) -- [Video: Roles, teams, and repositories](https://youtu.be/WKlT1O-4Du8?feature=shared&t=435) diff --git a/content/manuals/accounts/organization/manage/manage-licenses.md b/content/manuals/accounts/organization/manage/manage-licenses.md new file mode 100644 index 000000000000..212a9571969d --- /dev/null +++ b/content/manuals/accounts/organization/manage/manage-licenses.md @@ -0,0 +1,179 @@ +--- +title: Manage licenses +linkTitle: Licenses +description: >- + View your organization's license inventory and assign licenses to teams or + members by team, invitation, or automatic assignment for Docker Team or + Business, AI Governance, and Offload. +keywords: licenses, organization, teams, members, invite, Docker Team, Docker + Business, Docker Offload, AI Governance, license assignment, team assignment, + docker home, automatic license assignment, SSO, SCIM, Sandboxes +weight: 40 +aliases: + - /admin/organization/manage/manage-licenses/ +--- + +Licenses control which organization members can use supported Docker products. +As an organization owner, you manage license availability for your +organization. + +> [!TIP] +> To learn more about product licenses, Docker Team and Business seats, and +> other Docker add-ons, see +> [Docker plans](/manuals/subscription-billing/plans/_index.md), or +> <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_admin_licenses" class="link" rel="noopener">contact sales</a> +> to purchase licenses. + +## License assignment + +You have a few options for assigning a license to a member. You can assign: + +- Through a team, so every member of that team gets the license, including + people who join the team later +- Through the **Members** page with the action menu, or through invitations +- By turning on automatic assignment so members receive a license when they + use a supported product. + +A member can use the product if they have a license from their team, from an +individual assignment, or from automatic assignment. Each member uses one +license per product. Assigning the same product again through another team or +as an individual assignment does not consume a second license. + +## Assign licenses + +Assign licenses from the **Teams** view, the **Members** view, through +invitations, or with automatic assignment. + +### Teams + +Assigning a license to a team ensures every member of that team receives the +license, including members who join the team later. + +1. Sign in to [Docker Home](https://app.docker.com), then choose your + organization. +1. Select **Teams** from the left navigation, then select the team name. +1. On the **Licenses** card, select the **edit** icon to open **Add licenses**. +1. Under **Licenses**, select one or more licenses. + - Each license shows how many are available + - The modal reports how many members receive each license +1. Select **Save**. + +Docker grants the license only to team members who don't already have it. + +- If a member already holds that license, they keep access and the extra + assignment does not consume another license. +- A product can be selected for the team only when enough licenses are + available for every member of the team. + +### Members + +1. Sign in to [Docker Home](https://app.docker.com), then choose your + organization. +1. Select **Members** from the left navigation. +1. Select the **action menu** at the end of the member's row to assign or + revoke an active license. +1. Optional. To assign or revoke licenses for several members, use + multi-select to choose the members you want to manage, then select the + **Bulk actions** menu. + +### Invitations + +Assignment happens on acceptance if a license is available: + +- If a license is available when they accept, Docker assigns it to them and + the number of available licenses decreases by one. +- If no licenses remain when they accept, they still join your organization, + but without a license. +- Docker doesn't reserve or deduct the license at invite time. + +You can monitor availability on the **Licenses** page while invitations are +pending. + +To select licenses through invitations: + +1. Sign in to [Docker Home](https://app.docker.com), then choose your + organization. +1. Select **Members** from the left navigation, then select **Invite**. +1. Select **Emails or usernames**. +1. Enter the email addresses or Docker IDs of the people you want to invite, + then assign their + [role](/manuals/security/roles-and-permissions/_index.md). +1. Under **Licenses (optional)**, select one or more licenses that are + available to your organization. +1. Select **Invite** to send the invite. + +A user can accept from the link in their invitation email or from their +**Notifications Center**. For more about sending, resending, and removing +invitations, including CSV file limits, see +[Manage organization members](/manuals/accounts/organization/manage/members.md). + +### Automatic assignment + +Automatic license assignment gives members a product license when they use a +supported product. Use the **Automatic license assignment** toggle on the +product's license card on the **Licenses** page. The toggle appears only when +that product supports automatic assignment, so you may not see it on every +card. + +When the toggle is on: + +- Docker Team or Business: members receive a license when they sign in to + Docker Desktop. +- AI Governance: members receive a license when they sign in to + [Docker Sandboxes](/manuals/ai/sandboxes/_index.md). The `sbx login` + command provisions licenses on a first-come, first-served basis. +- Licenses are assigned until exhausted. + - Once the available licenses are exhausted, automatic license assignment + stops until more licenses are available. + - Members can still use Docker Sandboxes or Docker Desktop, but + organization policies for those products won't affect their usage. + +AI Governance licenses include single sign-on (SSO) and provisioning with +System for Cross-domain Identity Management (SCIM) or Just-in-Time (JIT), +even if your organization doesn't have a Docker Business subscription. +Members who join through SSO can receive an automatically assigned license +when they use Docker Sandboxes, the same as members you invite. See +[Authentication](/manuals/security/authentication/_index.md). + +## View licenses + +The **Licenses** page shows how many licenses you have, how many are assigned, +and whether those assignments are to teams or to individual members. Use it to +check remaining capacity, view the members or teams that have a license, add +licenses to your subscription, and turn automatic assignment on or off. + +1. Sign in to [Docker Home](https://app.docker.com), then choose your + organization. +1. Select **Licenses** from the left navigation. + +Products you haven't purchased appear as cards with **Learn more** and **Add +licenses**. Products you own show: + +- Remaining licenses under **Available**, and how many of your total are + assigned. To view the members who have the license, select **View all**. +- Team-assigned licenses under **Team assignment**. To view those teams, + select **View teams with this license**. +- Individual assignments under **Direct assignment** + +## Remove licenses + +Removing a license from a team, or +[deleting a team](/manuals/accounts/organization/manage/manage-a-team.md#delete-a-team), +removes that license from every member of the team, unless they hold it from a +direct assignment or through membership in another team. The license returns to +the available pool. The same applies when a member leaves a team. Revoking a +license from one member returns that license to the available pool. + +To remove licenses: + +1. Sign in to [Docker Home](https://app.docker.com), then choose your + organization. +1. To remove licenses from a team: + - Select **Teams**, then select the team name. + - On the **Licenses** card, select the **edit** icon. + - Remove the license you no longer want the team to assign. +1. To revoke a license from one member: + - Select **Members**. + - Use the **action menu** at the end of the member's row. + - Select **Remove**. +1. Review the confirmation message, then select **Remove license**. diff --git a/content/manuals/accounts/organization/manage/manage-products.md b/content/manuals/accounts/organization/manage/manage-products.md new file mode 100644 index 000000000000..fa8ae9a7faf2 --- /dev/null +++ b/content/manuals/accounts/organization/manage/manage-products.md @@ -0,0 +1,156 @@ +--- +title: Manage usage and access for Docker products +linkTitle: Products +weight: 60 +description: Learn how to manage access and usage for Docker products for your organization +keywords: organization, product access, product usage, access control, docker desktop, docker hub, docker scout, docker build cloud, docker offload, testcontainers cloud +aliases: + - /admin/organization/manage/manage-products/ + - /admin/organization/manage-products/ +--- + +{{< summary-bar feature_name="Admin orgs" >}} + +Use this page to learn how to control and monitor product access and usage +for your organization's members. If you're looking for setup and +configuration instructions, see each product's manual under +[Next steps](#next-steps). + +## Control access for your organization + +Organization members can access Docker products that your organization is +subscribed to by default. When signed in as an organization owner, you can +use the following procedures to control access for all members. + +### Docker Desktop access + +To manage Docker Desktop access: + +1. [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). +1. Manage members [manually](./members.md) or use + [provisioning](../../../security/provisioning/_index.md). + +With sign-in enforced, only users who are a member of your organization can +use Docker Desktop after signing in. + +### Docker Hub access + +To manage Docker Hub access: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization, then select **Docker Desktop**. +1. Select **Registry Access** to configure + [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md). +1. Select **Image Access** to control + [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md). + +### Docker Build Cloud access + +To initially set up and configure Docker Build Cloud, sign in to +[Docker Build Cloud](https://app.docker.com/build) and follow the +on-screen instructions. + +To manage Docker Build Cloud access: + +1. Sign in to [Docker Home](https://app.docker.com/), then select + [Docker Build Cloud](http://app.docker.com/build). +1. Select **Account settings**. +1. Select **Lock access to Docker Build Account**. + +### Docker Scout access + +To initially set up and configure Docker Scout, sign in to +[Docker Scout](https://scout.docker.com/) and follow the on-screen +instructions. + +To manage Docker Scout access: + +1. Sign in to [Docker Home](https://app.docker.com/), then select + [Docker Scout](https://scout.docker.com/). +1. Select your organization, then **Settings**. +1. To manage what repositories are enabled for Docker Scout analysis, select + **Repository settings**. For more information, see + [repository settings](../../../scout/explore/dashboard.md#repository-settings). +1. To manage access to Docker Scout for use on local images with Docker + Desktop, use + [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) + and set `sbomIndexing` to `false` to disable, or to `true` to enable. + +### Testcontainers Cloud access + +To initially set up and configure Testcontainers Cloud, sign in to +[Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the +on-screen instructions. + +To manage access to Testcontainers Cloud: + +1. Sign in to the [Testcontainers Cloud](https://app.testcontainers.cloud/), + then select the menu icon. +1. Select **Account**, then **Settings**. +1. Choose **Lock access to Testcontainers Cloud**. + +### Docker Offload access + +> [!NOTE] +> +> Docker Offload isn't included in the core Docker subscription plans. To +> make Docker Offload available, you must +> [contact sales](https://www.docker.com/products/docker-offload/) and +> subscribe. + +To manage Docker Offload access for your organization, use [Settings +Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md): + +1. Sign in to [Docker Home](https://app.docker.com/), then select **Docker + Desktop**. +1. Select **Settings Management**. +1. Configure the **Enable Docker Offload** setting to control whether + Docker Offload features are available in Docker Desktop. You can + configure this setting in five states: + - **Always enabled**: Docker Offload is always enabled and users cannot + disable it. The Offload toggle is always visible in the Docker Desktop + header. Recommended for VDI environments where local Docker execution + is not possible. + - **Enabled**: Docker Offload is enabled by default but users can + disable it in Docker Desktop settings. Suitable for hybrid + environments. + - **Disabled**: Docker Offload is disabled by default but users can + enable it in Docker Desktop settings. + - **Always disabled**: Docker Offload is disabled and users cannot + enable it. The option is visible but locked. Use when Docker Offload + is not approved for organizational use. + - **User defined**: No enforced default. Users choose whether to enable + or disable Docker Offload in their Docker Desktop settings. +1. Select **Save**. + +For more details on Settings Management, see the [Settings +reference](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#enable-docker-offload). + +## Monitor product usage for your organization + +You can monitor usage for Docker products across your organization. Use the +following table to learn where you can monitor organization usage: + +| Product | Monitor usage | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Docker Desktop | From [Docker Home](https://app.docker.com/), view the [**Insights**](/manuals/accounts/organization/insights.md) page. | +| Docker Hub | From Docker Hub, view the [**Usage** page](https://hub.docker.com/usage). | +| Docker Build Cloud | From [Docker Build Cloud](http://app.docker.com/build), view the **Build minutes** page. | +| Docker Scout | From [Docker Home](https://app.docker.com/), select **Go to Scout** to view the [**Repository settings** page](https://scout.docker.com/settings/repos). | +| Testcontainers Cloud | From [Docker Home](https://app.docker.com/), select **Go to Testcontainers Cloud**, then select the menu icon. Go to the [**Billing** page](https://app.testcontainers.cloud/dashboard/billing). | +| Docker Offload | From [Docker Home](https://app.docker.com/), select **Offload**, then **Offload activity**. See [Docker Offload usage and billing](../../../offload/usage.md) for more details. | + +If your usage or seat count exceeds your subscription amount, you can +[add seats](./manage-seats.md) or [view available Docker plans](../../../subscription-billing/plans/_index.md) to meet your needs. + +## Next steps + +For more detailed information about each product, including how to set up +and configure them, see the following manuals: + +- [Docker Desktop](../../../desktop/_index.md) +- [Docker Hub](../../../docker-hub/_index.md) +- [Docker Build Cloud](../../../build-cloud/_index.md) +- [Docker Scout](../../../scout/_index.md) +- [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) +- [Docker Offload](../../../offload/_index.md) diff --git a/content/manuals/admin/organization/manage/manage-seats.md b/content/manuals/accounts/organization/manage/manage-seats.md similarity index 97% rename from content/manuals/admin/organization/manage/manage-seats.md rename to content/manuals/accounts/organization/manage/manage-seats.md index c67156f5224a..b08f6d6dc248 100644 --- a/content/manuals/admin/organization/manage/manage-seats.md +++ b/content/manuals/accounts/organization/manage/manage-seats.md @@ -4,6 +4,7 @@ linkTitle: Seats description: Add or remove seats for Docker Team and Business subscriptions keywords: manage seats, add seats, remove seats, subscription billing, team members aliases: + - /admin/organization/manage/manage-seats/ - /docker-hub/billing/add-seats/ - /subscription/add-seats/ - /docker-hub/billing/remove-seats/ @@ -11,7 +12,7 @@ aliases: - /subscription/core-subscription/add-seats/ - /subscription/core-subscription/remove-seats/ - /subscription/manage-seats/ -weight: 40 +weight: 50 --- You can add or remove seats from your Docker Team or Business subscription at any time to accommodate team changes. When you add seats mid-billing cycle, you're charged a prorated amount for the additional seats. diff --git a/content/manuals/accounts/organization/manage/members.md b/content/manuals/accounts/organization/manage/members.md new file mode 100644 index 000000000000..309a46e0b167 --- /dev/null +++ b/content/manuals/accounts/organization/manage/members.md @@ -0,0 +1,273 @@ +--- +title: Invite and manage organization members +linkTitle: Members +weight: 20 +description: >- + Invite organization members in Docker Home, assign roles and licenses, + manage teams, remove members with or without SCIM, and export a CSV member + list. +keywords: members, invite members, organization members, Docker Home, Docker + Hub, export member list, edit roles, manage invitations, CSV invite, bulk + invite, resend invitation, remove member, accept invitation, teams, pending + invitations, organization owner, licenses, SCIM, IdP, group mapping +aliases: + - /admin/organization/manage/members/ + - /docker-hub/members/ + - /admin/organization/members/ +--- + +Invite and manage members for your organization in Docker Home. + +## Invite members + +Owners can invite new members using a Docker ID, email address, or a CSV file +of email addresses. If an invitee doesn't have a Docker account, they must +create one and verify their email address before they can accept. Pending +invitations occupy a seat. + +When you invite members, you assign them a role. See +[Roles and permissions][roles-permissions] for details about the access +permissions for each role. + +You can also select one or more product licenses for an invitee. Docker +assigns available licenses when they accept. Unlike a seat, licenses aren't +deducted from your organization's available licenses until the invitee +accepts. See [Invitations][license-invitations]. + +The **Members** page is where you assign or revoke a license for one member, +using the **action menu** on their row or the **Bulk actions** menu. To assign +a license to a whole team, or to view how many licenses your organization has, +use the **Teams** and **Licenses** views. See +[Manage licenses][manage-licenses]. + +{{< tabs >}} +{{< tab name="Email or username" >}} + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization from the top-left account drop-down. +1. Select **Members**, then **Invite**. +1. Select **Emails or usernames**. +1. Follow the on-screen instructions to invite members. Invite a maximum of + 1000 members and separate multiple entries by comma, semicolon, or space. + +{{< /tab >}} +{{< tab name="CSV upload" >}} + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization from the top-left account drop-down. Select **Members** > + **Invite** > **CSV upload**. +1. Optional. Select **Download the template CSV file** to download an example + CSV file. The following is an example of the contents of a valid CSV file: + + ```text + email + docker.user-0@example.com + docker.user-1@example.com + ``` + + CSV file requirements: + - The file must contain a header row with at least one heading named + `email`. Additional columns are allowed and are ignored in the import. + - The file must contain a maximum of 1000 email addresses (rows). To invite + more than 1000 members, create multiple CSV files and complete this + procedure for each file. + +1. Create a new CSV file or export a CSV file from another application. + - To export a CSV file from another application, see that application's + documentation. + - To create a new CSV file, open a new file in a text editor, type `email` + on the first line, type one email address per line on the following + lines, then save the file with a `.csv` extension. + +1. Select **Browse files** and select your CSV file, or drag and drop the CSV + file into the **Select a CSV file to upload** box. You can select only one + CSV file at a time. +1. After the CSV file uploads, select **Review** to identify invalid email + addresses, invitees with a pending invitation, members already in the + organization, or duplicate email addresses in the same CSV file. +1. Follow the on-screen instructions to invite members. + +{{< /tab >}} +{{< /tabs >}} + +You can also bulk invite members with the Docker Hub API. For more +information, see the [Bulk create invites][bulk-invites] API endpoint. + +Pending invitations appear in the Members table. Invitees can accept or +decline from the invitation email or the **Notifications Center**. + +## Accept an invitation + +To accept from the invitation email: + +1. Open the Docker invitation email and select the link to Docker Hub. +1. The Docker account creation page opens. If you already have an account, + select **Already have an account? Sign in**. If you don't have an account, + create one using the same email address that received the invitation. +1. Optional. If you created a new account, open your email inbox and verify + your email address using the Docker verification email. +1. After you sign in to Docker Hub, select **My Hub** from the top-level + navigation menu. +1. Select **Accept** on your invitation. + +To accept from the **Notifications Center**: + +1. Sign in to [Docker Hub](https://hub.docker.com/) or + [Docker Home](https://app.docker.com/). +1. Open the **Notifications Center** in the header. +1. Select **Accept** on the invitation. + +After you accept the invitation, you are a member of the organization. + +Invitation email links expire after 14 days. If your link has expired, you +can still accept from the **Notifications Center**. + +## Manage invitations + +After inviting members, you can resend or remove invitations. Each invitee +occupies one seat. If the number of email addresses in your CSV file exceeds +the number of available seats, you can't invite more members. + +> [!TIP] +> +> Need more seats for your organization? +> [Add seats](/manuals/accounts/organization/manage/manage-seats.md) to your +> subscription, or see [Docker pricing][docker-pricing] for plan options. + +### Resend an invitation + +You can resend individual or bulk invitations from Docker Home. + +To resend an individual invitation: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Select the **Actions** menu next to the invitee, then **Resend**. +1. Select **Invite** to confirm. + +To bulk resend invitations: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Use the checkboxes next to **Usernames** to select invitees. +1. Select **Resend invites**. +1. Select **Resend** to confirm. + +### Remove an invitation + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Select the **Actions** menu next to the invitee, then **Remove invitee**. +1. Select **Remove** to confirm. + +## Manage members on a team + +Use Docker Hub or Docker Home to add or remove team members. Organization +owners can add a member to one or more teams within an organization. + +### Add member + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Teams**. +1. Select the team name. +1. Select **Add member**. Search for the member by email address or username. + +An invitee must accept the invitation before you can add them to a team. + +### Update member role + +Organization owners can manage +[roles](/manuals/security/roles-and-permissions/_index.md) within +an organization. If an organization is part of a company, the company owner +can also manage that organization's roles. If SSO is enabled, you can use +[SCIM for role mapping][scim-role-mapping]. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Find the username of the member whose role you want to edit. Select the + **Actions** menu, then **Edit role**. + +If you're the only owner of an organization and you want to edit your role, +assign a new owner first so you can change your own role. + +### Remove members from teams + +If your organization uses +[SCIM group mapping](/manuals/security/provisioning/scim/group-mapping.md) to +manage teams, update team membership in your identity provider (IdP). You can +also remove a member from a team in Docker Home with the following steps. + +Removing a member from a team revokes their access to that team's permitted +resources. To remove someone from the organization entirely when SCIM is +enabled, see +[Remove member from organization](#remove-member-from-organization). + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Teams**, then select the team. +1. Select the **X** next to the member's name to remove them from the team. +1. When prompted, select **Remove** to confirm. + +## Remove member from organization + +Organization owners can remove members from the organization. Removing a +member revokes their access to the organization's resources and teams. + +If your organization uses SSO with +[SCIM](/manuals/security/provisioning/scim/_index.md) enabled, +remove members from your IdP instead. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Find the username of the member you want to remove. Select the + **Actions** menu, then **Remove member**. +1. Select **Remove** to confirm. + +## Export a member list CSV + +Organization owners can export a CSV file of all members. Docker generates +the file asynchronously and emails it to the owner when it's ready. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Select the **Download** icon to start the export. +1. Open the email from Docker and select the link to download the CSV file. + + {{< accordion title="CSV fields" >}} + - Name: The member's name + - Username: The member's Docker ID + - Email: The member's email address + - Type: Whether the entry is a member or an invitee + - Role: The member's role in the organization + - Teams: Teams the member belongs to + - Date Joined: When the member joined the organization + + {{< /accordion >}} + +## Next steps + +After you invite and manage members, explore these related topics: + +- [Manage subscription seats](./manage-seats.md) to add seats for pending + invitations +- [Manage license assignment](./manage-licenses.md) to control product access +- [Create and manage a team](./manage-a-team.md) to group members and set + repository permissions +- [Roles and permissions][roles-permissions] for role definitions +- [SCIM provisioning][scim-provisioning] to automate member and role + management + +[roles-permissions]: /manuals/security/roles-and-permissions/_index.md +[license-invitations]: /manuals/accounts/organization/manage/manage-licenses.md#invitations +[manage-licenses]: /manuals/accounts/organization/manage/manage-licenses.md +[bulk-invites]: /reference/api/hub/latest/operations/postV2InvitesBulk/ +[docker-pricing]: https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminMembers +[scim-role-mapping]: /manuals/security/provisioning/scim/_index.md +[scim-provisioning]: /manuals/security/provisioning/scim/_index.md diff --git a/content/manuals/accounts/organization/setup/_index.md b/content/manuals/accounts/organization/setup/_index.md new file mode 100644 index 000000000000..4d94e1329453 --- /dev/null +++ b/content/manuals/accounts/organization/setup/_index.md @@ -0,0 +1,75 @@ +--- +title: Set up a Docker organization +linkTitle: Setup +weight: 10 +description: > + Create, convert, or onboard a Docker organization under one namespace and + subscription. +keywords: + - Docker organization setup + - create organization + - onboard organization + - convert Docker account + - organization namespace + - Docker Home +grid: + - title: Create your organization + description: Choose a new namespace and subscription. + icon: building-storefront + link: /accounts/organization/setup/orgs/ + - title: Convert your account + description: Keep an existing Docker ID as the organization namespace. + icon: arrows-right-left + link: /accounts/organization/setup/convert-account/ + - title: Onboard your organization + description: Invite members and configure sign-in. + icon: magnifying-glass-plus + link: /accounts/organization/setup/onboard/ + - title: Manage your organization + description: Add members, teams, licenses, and seats after setup. + icon: user-group + link: /accounts/organization/manage/ + - title: Security + description: Configure single sign-on, provisioning, and access management. + icon: shield-check + link: /security/ +aliases: + - /admin/organization/setup/ +--- + +An organization groups members and teams under one namespace and one +subscription. Anyone with a [Docker ID](/manuals/accounts/_index.md) can +create an organization or convert an individual account into one. + +You start by creating a new organization or converting an individual +account. After creating or converting, you can onboard your organization. + +## Names versus namespaces + +When you create an organization, you set two values: + +- Organization namespace is the permanent, unique identifier for your + organization. It becomes the first part of every image name you push, as + in `namespace/image:tag`. You can't change it after you create the + organization. + - Docker IDs and organization namespaces must be unique. + - If a Docker ID is `acme`, no organization can use `acme` as its + namespace. +- Organization name is the display name shown on your organization's + Docker profile. You can change it at any time. See + [Change organization information](/manuals/accounts/organization/manage/general-settings.md). + +## Choose how to set up + +The difference between creating and converting is what happens to your +existing repositories. + +- Create an organization: Choose a new namespace. Your existing + repositories stay under your personal Docker ID. +- Convert your account: Your Docker ID becomes the organization’s + namespace. Your repositories and image names stay the same, so anyone + pulling your images can keep using their existing image references. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/accounts/organization/setup/convert-account.md b/content/manuals/accounts/organization/setup/convert-account.md new file mode 100644 index 000000000000..f067f803627c --- /dev/null +++ b/content/manuals/accounts/organization/setup/convert-account.md @@ -0,0 +1,132 @@ +--- +title: Convert a Docker account to an organization +linkTitle: Convert account +weight: 20 +description: >- + Convert an individual Docker account into an organization. Keep the same + Docker ID and repository namespace, then assign a new owner for shared + access. +keywords: + - convert Docker account + - convert account to organization + - individual account to organization + - organization owner + - Docker organization + - organization namespace +aliases: + - /admin/organization/setup/convert-account/ + - /docker-hub/convert-account/ + - /admin/organization/convert-account/ +toc_max: 3 +--- + +{{< summary-bar feature_name="Admin orgs" >}} + +When you convert, your +[Docker ID](/manuals/accounts/_index.md) becomes an organization instead of +an individual account. The Docker ID stays the same, so repository +namespaces and names stay the same. Convert an existing individual account +into an organization when more than one person needs access to that +account and its repositories. To choose a new namespace and keep your +Docker ID as an individual account, see +[Create a Docker organization](/manuals/accounts/organization/setup/orgs.md). + +## Conversion + +Converting an account into an organization does the following: + +- The account gets a + [Docker Team](/manuals/subscription-billing/plans/docker.md) + subscription. If the individual account was on a paid plan, it keeps + the same billing cycle. +- Docker signs you out. Your email address is no longer on any Docker + account. You can [sign up](https://hub.docker.com/signup) with it again + or update an existing account to use it. +- Repository collaborators are removed. + [Invite them to your organization](/manuals/accounts/organization/manage/members.md), + then add them to a + [team](/manuals/accounts/organization/manage/manage-a-team.md) + that has access to the repositories. +- Existing automated builds appear as if the new owner set them up. + +## Prerequisites + +Before you convert an individual account to an organization: + +- The individual account must have a verified email address. +- You need a separate Docker ID to [assign as organization owner](#choose-an-organization-owner). +- The individual account must not belong to an organization, a team, or a + company. If it does, you must + [leave the organization](#leave-an-existing-organization) before you convert. + +> [!TIP] +> +> After you convert an account, personal access tokens from that account +> stop working. Sign in as the new owner and create an +> [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md) +> for the converted organization. + +### Choose an organization owner + +To convert, you must name an owner. That owner has full administrative access +to configure and manage the organization. You can add more owners after +conversion. Each owner signs in to a separate individual account, then +selects the organization in Docker Home. + +To name someone else as the owner, enter that person's Docker ID during +conversion. If you still need access after conversion, you must sign up +again so the new owner can invite you to the organization. + +If you want to remain the sole owner without assigning another owner, you +must create a second individual account with a different email address. +Use your new account's Docker ID. + +- For example, if the account you are converting uses `alex@example.com`, + create the owner account with `alex.admin@example.com`. +- After conversion, `alex@example.com` is no longer on any Docker account. + +You can update the `alex.admin@example.com` email back to +`alex@example.com` after conversion. See +[Update email address](/manuals/accounts/individual/manage-account.md#update-email-address). + +### Leave an existing organization + +Use this procedure when the individual account is already a member of an +organization, a team, or a company. The account can be converted after it +has left each of them. If it has no memberships, skip this section and +[convert the account](#convert-to-an-organization). + +If the account is the only owner of an organization or company, assign +the owner role to another member first. Leave after that member can +administer the organization or company. + +To leave an organization and its teams: + +1. Sign in to [Docker Home](https://app.docker.com/) and select the + organization. +1. Select **Members** and find your username. +1. Select the **Actions** menu, then **Leave organization**. + +## Convert to an organization + +Converting an account into an organization is permanent. Back up any data +or settings you want to keep. + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Select your avatar in the top-right corner. +1. Select **Account settings**, then **Convert**. +1. Review the warning. You can't undo this action. +1. Enter the **Username of new owner**. + Enter a Docker ID, not an email address. Use 4 to 30 letters and + digits. The Docker ID must belong to a different account from the one + you are converting. That account must be active and have a verified + email address. +1. Select **Confirm**. For an account on a Pro plan, the button is + **Confirm and purchase**. + The new owner receives a notification email. Sign in with that account + to manage the organization. + +## Next steps + +- [Onboard your organization](/manuals/accounts/organization/setup/onboard.md) +- [Create an organization access token](/manuals/security/access-tokens/organization-access-tokens.md) diff --git a/content/manuals/accounts/organization/setup/onboard.md b/content/manuals/accounts/organization/setup/onboard.md new file mode 100644 index 000000000000..950c246a7245 --- /dev/null +++ b/content/manuals/accounts/organization/setup/onboard.md @@ -0,0 +1,179 @@ +--- +title: Onboard a Docker organization +linkTitle: Onboard +weight: 30 +description: > + Invite members, configure SSO and SCIM, and enforce Docker Desktop + sign-in for a Team or Business organization. +keywords: + - onboard Docker organization + - guided setup + - Docker Team + - Docker Business + - enforce sign-in + - SSO + - SCIM + - Docker Desktop +toc_max: 2 +aliases: + - /admin/organization/setup/onboard/ + - /docker-hub/onboard/ + - /docker-hub/onboard-team/ + - /docker-hub/onboard-business/ + - /admin/organization/onboard/ +--- + +{{< summary-bar feature_name="Admin orgs" >}} + +Onboarding your organization includes: + +- Identifying users so you can allocate subscription seats +- Inviting members and owners +- Securing authentication and authorization +- Enforcing sign-in for Docker Desktop + +These actions give administrators visibility into user activity and a way +to enforce security settings. Organization members also receive higher +pull limits and other benefits when they are signed in. + +## Prerequisites + +Before you onboard your organization, you need a Docker Team or Business +subscription. For details, see +[Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOnboard). +When you buy a self-serve subscription, the on-screen instructions guide +you through creating an organization. + +If you bought a subscription through Docker Sales and you haven't created +an organization yet, see +[Create an organization](/manuals/accounts/organization/setup/orgs.md). + +## Guided onboarding + +You can use a guided setup for the first onboarding tasks: + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Guided setup** at the bottom of the left sidebar. + +Guided setup walks through these steps: + +- **Invite your team**: Invite owners and members. +- **Manage user access**: Claim your company's domain, manage members + with SSO, and enforce Docker Desktop sign-in. +- **Docker Desktop security**: Configure Image Access Management, + Registry Access Management, and Settings Management. + +## Manual onboarding + +### Step one: Identify your Docker users + +Identifying your users helps you allocate seats and makes sure they +receive your Docker subscription benefits. + +1. Identify the Docker users in your organization. + - If your organization uses device management software, such as MDM + or Jamf, use it to find machines with Docker Desktop installed: + - Mac: `/Applications/Docker.app` + - Windows: `C:\Program Files\Docker\Docker` (all-users + installation) or `%LOCALAPPDATA%\Programs\DockerDesktop` + (per-user installation) + - Linux: `/opt/docker-desktop` + - If your organization doesn't use device management software, or + users haven't installed Docker Desktop yet, ask them who uses + Docker Desktop. +1. Ask users to update their Docker account email address to one in your + organization's domain, or to create an account with that email. + - To update an email address, see + [Update email address](/manuals/accounts/individual/manage-account.md#update-email-address). + - To create an account, users + [sign up](https://hub.docker.com/signup) with an email address in + your organization's domain and verify that address. +1. Identify Docker accounts that already use your organization's domain: + - Ask your Docker sales representative, or + <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_org_onboarding" class="link" rel="noopener">contact sales</a>, + for a list of Docker accounts that use an email address in your + domain. + +### Step two: Invite owners + +When you create an organization, you are the only owner. Adding more +owners is optional, but additional owners can help you onboard and manage +your organization. + +To add an owner, invite a user and assign the owner role. For details, +see [Invite members](/manuals/accounts/organization/manage/members.md) +and +[Roles and permissions](/manuals/security/roles-and-permissions/_index.md). + +### Step three: Invite members + +When you add users to your organization, you can see their activity and +enforce security settings. Members also receive higher pull limits and +other organization-wide benefits when they are signed in. + +To add a member, invite a user and assign the member role. For details, +see [Invite members](/manuals/accounts/organization/manage/members.md) +and +[Roles and permissions](/manuals/security/roles-and-permissions/_index.md). + +### Step four: Manage user access with SSO and SCIM + +SSO and SCIM are optional and available to Docker Business subscribers. +To upgrade a Docker Team subscription to Docker Business, see +[Upgrade a plan](/manuals/subscription-billing/manage/plans.md#upgrade-plans). + +Use your identity provider (IdP) to manage members and provision them to +Docker through SSO and SCIM: + +- [Configure SSO](/manuals/security/authentication/single-sign-on/connect.md) + to authenticate members and add them when they sign in through your + identity provider. +- Optional. + [Enforce SSO](/manuals/security/authentication/single-sign-on/connect.md) + so users must use SSO when they sign in to Docker. + + > [!NOTE] + > + > Enforcing single sign-on (SSO) and enforcing Docker Desktop sign-in + > are different features. For details, see + > [Enforcing sign-in versus enforcing single sign-on (SSO)](/manuals/desktop/enterprise/enforce-sign-in/_index.md#enforcing-sign-in-versus-enforcing-single-sign-on-sso). + +- [Configure SCIM](/manuals/security/provisioning/scim/_index.md) to + provision, add, and deprovision members through your identity + provider. + +### Step five: Enforce sign-in for Docker Desktop + +By default, members of your organization can use Docker Desktop without +signing in. When users don't sign in as a member of your organization, +they don't receive the +[benefits of your organization's subscription](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOnboard) +and they can bypass +[Docker's security features](/manuals/desktop/enterprise/hardened-desktop/_index.md). + +You can enforce sign-in in more than one way: + +- [Registry key method (Windows only)](/manuals/desktop/enterprise/enforce-sign-in/methods.md#registry-key-method-windows-only) +- [`.plist` method (Mac only)](/manuals/desktop/enterprise/enforce-sign-in/methods.md#plist-method-mac-only) +- [`registry.json` method (All)](/manuals/desktop/enterprise/enforce-sign-in/methods.md#registryjson-method-all) + +### Step six: Manage Docker Desktop security + +Use these features to manage your organization's security posture: + +- [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md): + Control which types of images developers can pull from Docker Hub. +- [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md): + Define which registries developers can access. +- [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management.md): + Set and control Docker Desktop settings for your users. + +## Next steps + +- [Manage Docker products](../manage/manage-products.md) to configure + access and view usage. +- Configure + [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md) + to tighten security for containerized development. +- [Manage your domains](/manuals/security/provisioning/domain-management.md) + so Docker users in your domain are part of your organization. diff --git a/content/manuals/accounts/organization/setup/orgs.md b/content/manuals/accounts/organization/setup/orgs.md new file mode 100644 index 000000000000..6efa3c2bd353 --- /dev/null +++ b/content/manuals/accounts/organization/setup/orgs.md @@ -0,0 +1,95 @@ +--- +title: Create a Docker organization +linkTitle: Create +weight: 10 +description: Create a Docker organization and choose its namespace and plan. +keywords: + - create Docker organization + - organization namespace + - organization name + - Docker Team + - Docker Business + - Docker Home +aliases: + - /admin/organization/setup/orgs/ + - /docker-hub/orgs/ + - /admin/organization/orgs/ +--- + +{{< summary-bar feature_name="Admin orgs" >}} + +Create an organization to group members and teams under one namespace and +one subscription. Your Docker ID stays an individual account. To use an +existing Docker ID as the namespace, see +[Convert a Docker account to an organization](/manuals/accounts/organization/setup/convert-account.md). + +## Prerequisites + +You need a [Docker ID](/manuals/accounts/_index.md) before you create an +organization. + +> [!TIP] +> +> Review [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOrgs) +> before you choose a plan. + +## Create an organization + +When you create a new organization, you must select a Docker plan, +enter organization details, and verify billing details. + +1. Sign in to [Docker Home](https://app.docker.com/) and select + **Create new organization** at the bottom of the organization list. +1. On **Plan**, choose a subscription, a billing cycle, and the number of + seats. Select **Continue to profile**. +1. On **Organization**, enter the details for the new organization. + - If you already belong to one or more organizations, this step opens + as **Choose an organization**, which applies the subscription to an + existing organization. + - Select **Create an organization** to make a new one instead. The + picker is replaced by the **Organization namespace** and + **Organization name** fields. + - For what each field means, see + [Names versus namespaces](/manuals/accounts/organization/setup/_index.md#names-versus-namespaces). +1. Select **Continue to billing**. +1. On **Billing**, enter billing information and select + **Continue to payment**. +1. On **Payment**, enter payment details and select **Purchase**. + +You can now view your new organization. + +## View an organization + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select your organization. + +Docker Home lists the options you use to configure the organization. + +## Merge organizations + +> [!WARNING] +> +> Merge organizations at the end of your billing cycle. When you merge an +> organization and downgrade another, you lose seats on the downgraded +> organization. Docker doesn't offer refunds for downgrades. + +If you have multiple organizations that you want to merge into one: + +1. Based on the number of seats from the secondary organization, + [purchase additional seats](../manage/manage-seats.md) for the primary + organization you want to keep. +1. Add users to the primary organization and remove them from the + secondary organization. +1. Move your data, including repositories. +1. After the users and data are on the primary organization, + [downgrade](../../../subscription-billing/plans/docker.md#cancel-a-docker-plan) + the secondary account to a free subscription. Docker doesn't offer + refunds for a downgrade in the middle of a billing cycle. + +If your organization has a Docker Business subscription with a purchase +order, contact Support or your account manager at Docker. + +## Next steps + +- [Onboard your organization](/manuals/accounts/organization/setup/onboard.md) +- [Manage organization members](/manuals/accounts/organization/manage/members.md) diff --git a/content/manuals/admin/_index.md b/content/manuals/admin/_index.md deleted file mode 100644 index a01bd2f87330..000000000000 --- a/content/manuals/admin/_index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Administration -description: Overview of administration features and roles in the Docker Admin Console -keywords: admin, administration, company, organization, Admin Console, user accounts, account management -weight: 10 -params: - sidebar: - group: Enterprise -grid: - - title: Company administration - description: Explore how to manage a company. - icon: building-office-2 - link: /admin/company/ - - title: Organization administration - description: Learn about organization administration. - icon: building-storefront - link: /admin/organization/ - - title: Onboard your organization - description: Learn how to onboard and secure your organization. - icon: magnifying-glass-plus - link: /admin/organization/setup/onboard - - title: Company FAQ - description: Discover common questions and answers about companies. - icon: question-mark-circle - link: /faq/admin/company-faqs/ - - title: Organization FAQ - description: Explore popular FAQ topics about organizations. - icon: question-mark-circle - link: /faq/admin/organization-faqs/ - - title: Security - description: Explore security features for administrators. - icon: shield-check - link: /security/ -aliases: - - /docker-hub/admin-overview ---- - -Administrators can manage companies and organizations using the -[Docker Admin Console](https://app.docker.com/admin). The Admin Console -provides centralized observability, access management, and security controls -across Docker environments. - -## Company and organization hierarchy - -The [Docker Admin Console](https://app.docker.com/admin) provides administrators with centralized observability, access management, and controls for their company and organizations. To provide these features, Docker uses the following hierarchy and roles. - -![Diagram showing Docker’s administration hierarchy with Company at the top, followed by Organizations, Teams, and Members](./images/docker-admin-structure.webp) - -### Company - -A company groups multiple Docker organizations for centralized configuration. Companies have the company owner administrator role available. - -The company owner: - -- Can view and manage all organizations within the company -- Has full access to company-wide settings and inherits the same permissions as organization owners -- Does not occupy a seat - -Companies are only available for Docker Business subscribers. - -### Organization - -Organization owners have the organization owner administrator role available. They can manage organization settings, users, and access controls, but occupy a [seat](/manuals/admin/organization/organization-faqs.md#what-is-the-difference-between-user-invitee-seat-and-member). - -- An organization contains teams and repositories. -- All Docker Team and Business subscribers must have at least one organization. - -> [!TIP] -> [Upgrading to a Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdmin) grants you the company owner role so you can manage multiple organizations. - -### Team - -Teams are optional and let you group members to assign repository permissions -collectively. Teams simplify permission management across projects -or functions. - -### Member - -A member is any Docker user added to an organization. Organization and company -owners can assign roles to members to define their level of access. - -## Admin Console features - -Docker's [Admin Console](https://app.docker.com/admin) allows you to: - -- Create and manage companies and organizations -- Assign roles and permissions to members -- Group members into teams to manage access by project or role -- Set company-wide policies, including SCIM provisioning and security - enforcement - -## Manage companies and organizations - -Learn how to manage companies and organizations in the following sections. - -{{< grid >}} diff --git a/content/manuals/admin/activity-logs.md b/content/manuals/admin/activity-logs.md deleted file mode 100644 index f382d6f0e815..000000000000 --- a/content/manuals/admin/activity-logs.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Activity logs -weight: 30 -description: Learn how to access and interpret Docker activity logs for organizations and repositories. -keywords: audit log, organization activity, Docker business logs, repository activity, track changes Docker, security logs Docker, filter logs, log Docker events -aliases: -- /docker-hub/audit-log/ -- /admin/organization/activity-logs/ ---- - -{{< summary-bar feature_name="Activity logs" >}} - -Activity logs display a chronological list of activities that occur at organization and repository levels. The activity log provides organization owners with a record of all -member activities. - -With activity logs, owners can view and track: - - - What changes were made - - The date when a change was made - - Who initiated the change - -For example, activity logs display activities such as the date when a repository was created or deleted, the member who created the repository, the name of the repository, and when there was a change to the privacy settings. - -Owners can also see the activity logs for their repository if the repository is part of the organization subscribed to a Docker Business or Team subscription. - -## Access activity logs - -{{< tabs >}} -{{< tab name="Docker Home">}} - -To view activity logs in Docker Home: - -1. Sign in to [Docker Home](https://app.docker.com) and select your -organization. -1. Select **Admin Console**, then **Activity logs**. - -{{< /tab >}} -{{< tab name="API">}} - -To view activity logs using the Docker Hub API, use the [Audit logs endpoints](https://docs.docker.com/reference/api/hub/latest/#tag/audit-logs). - -{{< /tab >}} -{{< /tabs >}} - -## Filter and customize activity logs - -> [!IMPORTANT] -> -> Docker Home retains activity logs for 30 days. To retrieve -activities beyond 30 days, you must use the -[Docker Hub API](https://docs.docker.com/reference/api/hub/latest/#tag/audit-logs). - -By default, the **Activity** tab displays all recorded events within -the last 30 days. To narrow your view, use the calendar to select a specific -date range. The log updates to show only the activities that occurred during -that period. - -You can also filter by activity type. Use the **All Activities** drop-down to -focus on organization-level, repository-level, or billing-related events. -In Docker Hub, when viewing a repository, the **Activities** tab only shows -events for that repository. - -After selecting a category—**Organization**, **Repository**, or **Billing**—use -the **All Actions** drop-down to refine the results even further by specific -event type. - -> [!NOTE] -> -> Events triggered by Docker Support appear under the username **dockersupport**. - -## Types of activity log events - -Refer to the following section for a list of events and their descriptions: - -### Organization events - -| Event | Description | -|:------------------------------------------------------------------|:------------------------------------------------| -| Team Created | Activities related to the creation of a team | -| Team Updated | Activities related to the modification of a team | -| Team Deleted | Activities related to the deletion of a team | -| Team Member Added | Details of the member added to your team | -| Team Member Removed | Details of the member removed from your team | -| Team Member Invited | Details of the member invited to your team | -| Organization Member Added | Details of the member added to your organization | -| Organization Member Removed | Details about the member removed from your organization | -| Member Role Changed | Details about the role changed for a member in your organization | -| Organization Created | Activities related to the creation of a new organization | -| Organization Settings Updated | Details related to the organization setting that was updated | -| Registry Access Management enabled | Activities related to enabling Registry Access Management | -| Registry Access Management disabled | Activities related to disabling Registry Access Management | -| Registry Access Management registry added | Activities related to the addition of a registry | -| Registry Access Management registry removed | Activities related to the removal of a registry | -| Registry Access Management registry updated | Details related to the registry that was updated | -| Single Sign-On domain added | Details of the single sign-on domain added to your organization | -| Single Sign-On domain removed | Details of the single sign-on domain removed from your organization | -| Single Sign-On domain verified | Details of the single sign-on domain verified for your organization | -| Access token created | Access token created in organization | -| Access token updated | Access token updated in organization | -| Access token deleted | Access token deleted in organization | -| Policy created | Details of adding a settings policy | -| Policy updated | Details of updating a settings policy | -| Policy deleted | Details of deleting a settings policy | -| Policy transferred | Details of transferring a settings policy to another owner | -| Create SSO Connection | Details of creating a new org/company SSO connection | -| Update SSO Connection | Details of updating an existing org/company SSO connection | -| Delete SSO Connection | Details of deleting an existing org/company SSO connection | -| Enforce SSO | Details of toggling enforcement on an existing org/company SSO connection | -| Enforce SCIM | Details of toggling SCIM on an existing org/company SSO connection | -| Refresh SCIM Token | Details of a SCIM token refresh on an existing org/company SSO connection | -| Change SSO Connection Type | Details of a connection type change on an existing org/company SSO connection | -| Toggle JIT provisioning | Details of a JIT toggle on an existing org/company SSO connection | - -### Repository events - -> [!NOTE] -> -> Event descriptions that include a user action can refer to a Docker username, personal access token (PAT) or organization access token (OAT). For example, if a user pushes a tag to a repository, the event would include the description: `<user-access-token>` pushed the tag to the repository. - -| Event | Description | -|:------------------------------------------------------------------|:------------------------------------------------| -| Repository Created | Activities related to the creation of a new repository | -| Repository Deleted | Activities related to the deletion of a repository | -| Repository Updated | Activities related to updating the description, full description, or status of a repository | -| Privacy Changed | Details related to the privacy policies that were updated | -| Tag Pushed | Activities related to the tags pushed | -| Tag Deleted | Activities related to the tags deleted | -| Categories Updated | Activities related to setting or updating categories of a repository | - -### Billing events - -| Event | Description | -|:------------------------------------------------------------------|:------------------------------------------------| -| Plan Upgraded | Occurs when your organization’s billing plan is upgraded to a higher tier plan.| -| Plan Downgraded | Occurs when your organization’s billing plan is downgraded to a lower tier plan. | -| Seat Added | Occurs when a seat is added to your organization’s billing plan. | -| Seat Removed | Occurs when a seat is removed from your organization’s billing plan. | -| Billing Cycle Changed | Occurs when there is a change in the recurring interval that your organization is charged.| -| Plan Downgrade Canceled | Occurs when a scheduled plan downgrade for your organization is canceled.| -| Seat Removal Canceled | Occurs when a scheduled seat removal for an organization’s billing plan is canceled. | -| Plan Upgrade Requested | Occurs when a user in your organization requests a plan upgrade. | -| Plan Downgrade Requested | Occurs when a user in your organization requests a plan downgrade. | -| Seat Addition Requested | Occurs when a user in your organization requests an increase in the number of seats. | -| Seat Removal Requested | Occurs when a user in your organization requests a decrease in the number of seats. | -| Billing Cycle Change Requested | Occurs when a user in your organization requests a change in the billing cycle. | -| Plan Downgrade Cancellation Requested | Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade. | -| Seat Removal Cancellation Requested | Occurs when a user in your organization requests a cancellation of a scheduled seat removal. | - -### Offload events - -> [!NOTE] -> -> Event descriptions show the Docker username of the actor and details about the lease. - -| Event | Description | -|:------------------------------------------------------------------|:------------------------------------------------| -| Offload Lease Start | Occurs when an Offload lease is started in your organization. | -| Offload Lease End | Occurs when an Offload lease is ended in your organization. | diff --git a/content/manuals/admin/company/_index.md b/content/manuals/admin/company/_index.md deleted file mode 100644 index 4a8dd4eef229..000000000000 --- a/content/manuals/admin/company/_index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Company overview -linkTitle: Company -weight: 20 -description: Learn how to manage multiple organizations using companies, including managing users, owners, and security. -keywords: company, multiple organizations, manage companies, admin console, Docker Business settings -grid: - - title: Create a company - description: Get started by learning how to create a company. - icon: building-office-2 - link: /admin/company/new-company/ - - title: Manage organizations - description: - Learn how to add and manage organizations as well as seats within your - company. - icon: building-storefront - link: /admin/company/manage/organizations/ - - title: Manage company owners - description: Find out more about company owners and how to manage them. - icon: user-group - link: /admin/company/manage/owners/ - - title: Manage users - description: Explore how to manage users in all organizations. - icon: user-plus - link: /admin/company/manage/users/ - - title: Configure single sign-on - description: Discover how to configure SSO for your entire company. - icon: key - link: /enterprise/security/single-sign-on/ - - title: Set up SCIM - description: - Set up SCIM to automatically provision and deprovision users in your - company. - icon: clipboard-document-check - link: /enterprise/security/provisioning/scim/ - - title: Domain management - description: Add and verify your company's domains. - icon: check-badge - link: /enterprise/security/domain-management/ - - title: FAQs - description: Explore frequently asked questions about companies. - link: /faq/admin/company-faqs/ - icon: question-mark-circle -aliases: - - /docker-hub/creating-companies/ ---- - -{{< summary-bar feature_name="Company" >}} - -A company provides a single point of visibility across multiple organizations, -simplifying organization and settings management. - -Organization owners with a Docker Business subscription can create a company -and manage it through the [Docker Admin Console](https://app.docker.com/admin). - -The following diagram shows how a company relates to its associated -organizations. - -![Diagram showing how companies relate to Docker organizations](/admin/images/docker-admin-structure.webp) - -## Key features - -With a company, administrators can: - -- View and manage all nested organizations -- Configure company and organization settings centrally -- Control access to the company -- Have up to ten unique users assigned to the company owner role -- Configure SSO and SCIM for all nested organizations -- Enforce SSO for all users in the company - -## Create and manage your company - -Learn how to create and manage a company in the following sections. - -{{< grid >}} diff --git a/content/manuals/admin/company/company-faqs.md b/content/manuals/admin/company/company-faqs.md deleted file mode 100644 index ef88e17bd990..000000000000 --- a/content/manuals/admin/company/company-faqs.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Company FAQs -linkTitle: FAQs -weight: 30 -description: Company FAQs -keywords: Docker, Docker Hub, SSO FAQs, single sign-on, company, administration, company management -tags: [FAQ] -aliases: - - /docker-hub/company-faqs/ - - /faq/admin/company-faqs/ - - /admin/faqs/company-faqs/ ---- - -### Some of my organizations don’t have a Docker Business subscription. Can I still use a parent company? - -Yes, but you can only add organizations with a Docker Business subscription -to a company. - -### What happens if one of my organizations downgrades from Docker Business, but I still need access as a company owner? - -To access and manage child organizations, the organization must have a -Docker Business subscription. If the organization isn’t included in this -subscription, the owner of the organization must manage the organization -outside of the company. - -### Do company owners occupy a subscription seat? - -Company owners do not occupy a seat unless one of the following is true: - -- They are added as a member of an organization under your company -- SSO is enabled and the company owner signs in via SSO, which automatically adds them as an organization member - -Although company owners have the same access as organization owners across all -organizations in the company, it's not necessary to add them to any -organization. Doing so will cause them to occupy a seat. - -When you first create a company, your account is both a company owner and an -organization owner. In that case, your account will occupy a seat as long as -you remain an organization owner. - -To avoid occupying a seat, [assign another user as the organization owner](/manuals/admin/organization/manage/members.md#update-a-member-role) and remove yourself from the organization. -You'll retain full administrative access as a company owner without using a -subscription seat. - -### What permissions does the company owner have in the associated/nested organizations? - -Company owners can navigate to the **Organizations** page to view all their -nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company. - -For more information, see [Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). diff --git a/content/manuals/admin/company/manage/_index.md b/content/manuals/admin/company/manage/_index.md deleted file mode 100644 index 026a74431255..000000000000 --- a/content/manuals/admin/company/manage/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Manage -weight: 20 ---- diff --git a/content/manuals/admin/company/manage/organizations.md b/content/manuals/admin/company/manage/organizations.md deleted file mode 100644 index 4a122de6e069..000000000000 --- a/content/manuals/admin/company/manage/organizations.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Manage company organizations -linkTitle: Organizations -description: Learn how to manage organizations in a company. -keywords: company, multiple organizations, manage organizations, Docker Admin Console, organization settings, add organization, company management -aliases: - - /admin/company/organizations/ ---- - -{{< summary-bar feature_name="Company" >}} - -Learn to manage the organizations in a company using the Docker Admin Console. - -## View all organizations - -1. Sign in to the [Docker Home](https://app.docker.com) and choose - your company. -1. Select **Admin Console**, then **Organizations**. - -The **Organizations** view displays all organizations under your company. - -## Add seats to an organization - -If you have a self-serve subscription that has no pending subscription changes, -you can add seats using Docker Home. For more information about adding seats, -see [Manage seats](/manuals/admin/organization/manage/manage-seats.md#add-seats-to-your-subscription). - -If you have a sales-assisted subscription, you must contact Docker support or -sales to add seats. - -## Add organizations to a company - -To add an organization to a company, ensure the following: - -- You are a company owner. -- You are an organization owner of the organization you want to add. -- The organization has a Docker Business subscription. -- There’s no limit to how many organizations can exist under a company. - -> [!IMPORTANT] -> -> Once you add an organization to a company, you can't remove it from the -> company. - -1. Sign in to [Docker Home](https://app.docker.com) and select your company from - the top-left account drop-down. -1. Select **Admin Console**, then **Organizations**. -1. Select **Add organization**. -1. Choose the organization you want to add from the drop-down menu. -1. Select **Add organization** to confirm. - -## Manage an organization - -1. Sign in to [Docker Home](https://app.docker.com) and select your company from - the top-left account drop-down. -1. Select **Admin Console**, then **Organizations**. -1. Select the organization you want to manage. - -For more details about managing an organization, see -[Organization administration](../../organization/_index.md). - -## More resources - -- [Video: Managing a company and nested organizations](https://youtu.be/XZ5_i6qiKho?feature=shared&t=229) -- [Video: Adding nested organizations to a company](https://youtu.be/XZ5_i6qiKho?feature=shared&t=454) diff --git a/content/manuals/admin/company/manage/owners.md b/content/manuals/admin/company/manage/owners.md deleted file mode 100644 index e064d232b2c5..000000000000 --- a/content/manuals/admin/company/manage/owners.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Manage company owners -linkTitle: Owners -description: Learn how to add and remove company owners. -keywords: company, owners, add company owner, remove company owner, company management, company owner permissions -aliases: - - /admin/company/owners/ - - /docker-hub/company-owner/ ---- - -{{< summary-bar feature_name="Company" >}} - -A company can have multiple owners. Company owners have visibility across the -entire company and can manage settings that apply to all organizations under -that company. They also have the same access rights as organization owners but -don’t need to be members of any individual organization. - -> [!IMPORTANT] -> -> Company owners do not occupy a seat unless they are added as a member of an -> organization under your company, or SSO is enabled and the company owner signs -> in via SSO (which automatically adds them as an organization member). - -## Add a company owner - -1. Sign in to [Docker Home](https://app.docker.com) and select your company from - the top-left account drop-down. -1. Select **Admin Console**, then **Company owners**. -1. Select **Add owner**. -1. Specify the user's Docker ID to search for the user. -1. After you find the user, select **Add company owner**. - -## Remove a company owner - -1. Sign in to [Docker Home](https://app.docker.com) and select your company from - the top-left account drop-down. -1. Select **Admin Console**, then **Company owners**. -1. Locate the company owner you want to remove and select the **Actions** menu. -1. Select **Remove as company owner**. diff --git a/content/manuals/admin/company/manage/users.md b/content/manuals/admin/company/manage/users.md deleted file mode 100644 index fd23d2891e07..000000000000 --- a/content/manuals/admin/company/manage/users.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Manage company members -linkTitle: Users -description: Learn how to manage company members in the Docker Admin Console. -keywords: company, company members, members, admin, Admin Console, member management, organization management, company management, bulk invite, resend invites -aliases: - - /admin/company/users/ ---- - -{{< summary-bar feature_name="Company" >}} - -Company owners can invite new members to an organization via Docker ID, -email address, or in bulk with a CSV file containing email -addresses. - -If an invitee does not have a Docker account, they must create an account and -verify their email address before they can accept an invitation to join the -organization. Pending invitations occupy seats for the organization -the user is invited to. - -## Invite members via Docker ID or email address - -Use the following steps to invite members to your organization via Docker ID or -email address. - -1. Sign in to [Docker Home](https://app.docker.com) and select - your company. -1. On the **Organizations** page, select the organization you want - to invite members to. -1. Select **Members**, then **Invite**. -1. Select **Emails or usernames**. -1. Follow the on-screen instructions to invite members. - Invite a maximum of 1000 members and separate multiple entries by comma, - semicolon, or space. - - > [!NOTE] - > - > When you invite members, you assign them a role. - > See [Roles and permissions](/manuals/enterprise/security/roles-and-permissions/core-roles.md) - > for details about the access permissions for each role. - - Pending invitations appear on the Members page. The invitees receive an - email with a link to Docker Hub where they can accept or decline the - invitation. - -## Invite members via CSV file - -To invite multiple members to an organization via a CSV file containing email -addresses: - -1. Sign in to [Docker Home](https://app.docker.com) and select - your company. -1. On the **Organizations** page, select the organization you want - to invite members to. -1. Select **Members**, then **Invite**. -1. Select **CSV upload**. -1. Select **Download the template CSV file** to optionally download an example - CSV file. The following is an example of the contents of a valid CSV file. - - ```text - email - docker.user-0@example.com - docker.user-1@example.com - ``` - - CSV file requirements: - - The file must contain a header row with at least one heading named `email`. - Additional columns are allowed and are ignored in the import. - - The file must contain a maximum of 1000 email addresses (rows). To invite - more than 1000 users, create multiple CSV files and perform all steps in - this task for each file. - -1. Create a new CSV file or export a CSV file from another application. - - To export a CSV file from another application, see the application’s - documentation. - - To create a new CSV file, open a new file in a text editor, type `email` - on the first line, type the user email addresses one per line on the - following lines, and then save the file with a .csv extension. - -1. Select **Browse files** and then select your CSV file, or drag and drop the - CSV file into the **Select a CSV file to upload** box. You can only select - one CSV file at a time. - - > [!NOTE] - > - > If the amount of email addresses in your CSV file exceeds the number of - > available seats in your organization, you cannot continue to invite members. - > To invite members, you can purchase more seats, or remove some email - > addresses from the CSV file and re-select the new file. To purchase more - > seats, see [Add seats to your subscription](/manuals/admin/organization/manage/manage-seats.md#add-seats-to-your-subscription) or - > <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_admin_invite_users" class="link" rel="noopener">Contact sales</a>. - -1. After the CSV file has been uploaded, select **Review**. - - Valid email addresses and any email addresses that have issues will appear. - Email addresses may have the following issues: - - Invalid email: The email address is not a valid address. The email address - will be ignored if you send invites. You can correct the email address in - the CSV file and re-import the file. - - Already invited: The user has already been sent an invite email and another - invite email will not be sent. - - Member: The user is already a member of your organization and an invite - email will not be sent. - - Duplicate: The CSV file has multiple occurrences of the same email address. - The user will be sent only one invite email. - -1. Follow the on-screen instructions to invite members. - - > [!NOTE] - > - > When you invite members, you assign them a role. - > See [Roles and permissions](/manuals/enterprise/security/roles-and-permissions/core-roles.md) - > for details about the access permissions for each role. - -Pending invitations appear on the Members page. The invitees receive an email -with a link to Docker Hub where they can accept or decline the invitation. - -## Resend invitations to users - -You can resend individual invitations, or bulk invitations from the Admin Console. - -### Resend individual invitations - -1. In [Docker Home](https://app.docker.com/), select your company from - the top-left account drop-down. -2. Select **Admin Console**, then **Users**. -3. Select the **action menu** next to the invitee and select **Resend**. -4. Select **Invite** to confirm. - -### Bulk resend invitation - -1. In [Docker Home](https://app.docker.com/), select your company from - the top-left account drop-down. -2. Select **Admin Console**, then **Users**. -3. Use the **checkboxes** next to **Usernames** to bulk select users. -4. Select **Resend invites**. -5. Select **Resend** to confirm. - -## Invite members via API - -You can bulk invite members using the Docker Hub API. For more information, -see the [Bulk create invites](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) API endpoint. - -## Manage members on a team - -Use Docker Hub to add a member to a team or remove a member from a team. For -more details, see [Manage members](../../organization/manage/members.md#manage-members-on-a-team). diff --git a/content/manuals/admin/company/new-company.md b/content/manuals/admin/company/new-company.md deleted file mode 100644 index d4e5cce1524e..000000000000 --- a/content/manuals/admin/company/new-company.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Create new company -linkTitle: Create -weight: 10 -description: Learn how to create a company to centrally manage multiple organizations. -keywords: company, hub, organization, company owner, Admin Console, company management, Docker Business, create company, Docker Admin Console -aliases: - - /docker-hub/new-company/ ---- - -{{< summary-bar feature_name="Company" >}} - -Learn how to create a new company in the Docker Admin Console, a centralized -dashboard for managing organizations. - -## Prerequisites - -Before you begin, you must: - -- Be the owner of the organization you want to add to your company -- Have a Docker Business subscription - -## Create a company - -To create a new company: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Admin Console**, then **Company management**. -1. Select **Create a company**. -1. Enter a unique name for your company, then select **Continue**. - - > [!TIP] - > - > The name for your company can't be the same as an existing user, - > organization, or company namespace. - -1. Review the migration details and then select **Create company**. - -For more information on how you can add organizations to your company, -see [Add organizations to a company](./manage/organizations.md#add-organizations-to-a-company). - -## Next steps - -- [Manage organizations](./manage/organizations.md) -- [Manage company members](./manage/users.md) -- [Manage company owners](./manage/owners.md) - -## More resources - -- [Video: Create a company](https://youtu.be/XZ5_i6qiKho?feature=shared&t=359) diff --git a/content/manuals/admin/images/docker-admin-structure.webp b/content/manuals/admin/images/docker-admin-structure.webp deleted file mode 100644 index b3ab384d7090..000000000000 Binary files a/content/manuals/admin/images/docker-admin-structure.webp and /dev/null differ diff --git a/content/manuals/admin/images/org-structure.webp b/content/manuals/admin/images/org-structure.webp deleted file mode 100644 index 1e810019ff58..000000000000 Binary files a/content/manuals/admin/images/org-structure.webp and /dev/null differ diff --git a/content/manuals/admin/insights.md b/content/manuals/admin/insights.md deleted file mode 100644 index a2b62aa995fe..000000000000 --- a/content/manuals/admin/insights.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Insights -weight: 40 -description: Gain insights about your organization's users and their Docker usage. -keywords: organization, insights, Docker Desktop analytics, user usage statistics, Docker Business, track Docker activity ---- - -{{< summary-bar feature_name="Insights" >}} - -Insights helps administrators visualize and understand how Docker is used within -their organizations. With Insights, administrators can ensure their teams are -fully equipped to utilize Docker to its fullest potential, leading to improved -productivity and efficiency across the organization. - -Key benefits include: - -- Uniform working environment: Establish and maintain standardized - configurations across teams. -- Best practices: Promote and enforce usage guidelines to ensure optimal - performance. -- Increased visibility: Monitor and drive adoption of organizational - configurations and policies. -- Optimized license use: Ensure that developers have access to advanced - features provided by a Docker subscription. - -## Prerequisites - -To use Insights, you must meet the following requirements: - -- [Docker Business subscription](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminInsights) -- Administrators must [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) - for users -- Your Account Executive must turn on Insights for your organization - -## View Insights for organization users - -To access Insights, contact your Account Executive to turn on the feature. Once enabled, access Insights using the -following steps: - -1. Sign in to [Docker Home](https://app.docker.com/) and choose - your organization. -2. Select **Insights**, then select a time period for the data you want to view. - -> [!NOTE] -> -> Insights data is not real-time and is updated daily. At the top-right of the -> Insights page, view the **Last updated** date to understand when the data was -> last updated. - -### Docker Desktop users - -Track active Docker Desktop users in your domain, differentiated by license -status. This chart helps you understand the engagement levels within your -organization, providing insights into how many users are actively using Docker -Desktop. Note that users who opt out of analytics aren't included in the active -counts. - -The chart contains the following data: - -| Data | Description | -| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Active user | The number of users who have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization. <br><br>Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). | -| Total organization members | The number of users who have used Docker Desktop, regardless of their Insights activity. | -| Users opted out of analytics | The number of users who are members of your organization that have opted out of sending analytics. <br><br>When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) to set `analyticsEnabled` for all your users. | -| Active users (graph) | The view over time for total active users. | - -### Builds - -Monitor development efficiency and the time your team invests in builds with -this chart. It provides a clear view of the build activity, helping you identify -patterns, optimize build times, and enhance overall development productivity. - -The chart contains the following data: - -| Data | Description | -| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Average build per user | The average number of builds per active user. A build includes any time a user runs one of the following commands: <ul><li>`docker build`</li><li>`docker buildx b`</li><li>`docker buildx bake`</li><li>`docker buildx build`</li><li>`docker buildx f`</li><li>`docker builder b`</li><li>`docker builder bake`</li><li>`docker builder build`</li><li>`docker builder f`</li><li>`docker compose build`</li><li>`docker compose up --build`</li><li>`docker image build`</li></ul> | -| Average build time | The average build time per build. | -| Build success rate | The percentage of builds that were successful out of the total number of builds. A successful build includes any build that exits normally. | -| Total builds (graph) | The total number of builds separated into successful builds and failed builds. A successful build includes any build that exits normally. A failed build includes any build that exits abnormally. | - -### Containers - -View the total and average number of containers run by users with this chart. It -lets you gauge container usage across your organization, helping you understand -usage trends and manage resources effectively. - -The chart contains the following data: - -| Data | Description | -| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Total containers run | The total number of containers run by active users. Containers run include those run using the Docker Desktop graphical user interface, `docker run`, or `docker compose`. | -| Average number of containers run | The average number of containers run per active user. | -| Containers run by active users (graph) | The number of containers run over time by active users. | - -### Docker Desktop usage - -Explore Docker Desktop usage patterns with this chart to optimize your team's -workflows and ensure compatibility. It provides valuable insights into how -Docker Desktop is being utilized, enabling you to streamline processes and -improve efficiency. - -The chart contains the following data: - -| Data | Description | -| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Most used version | The most used version of Docker Desktop by users in your organization. | -| Most used OS | The most used operating system by users. | -| Versions by active users (graph) | The number of active users using each version of Docker Desktop. <br><br>To learn more about each version and release dates, see the [Docker Desktop release notes](/manuals/desktop/release-notes.md). | -| Interface by active users (graph) | The number of active users grouped into the type of interface they used to interact with Docker Desktop. <br><br>A CLI user is any active user who has run a `docker` command. A GUI user is any active user who has interacted with the Docker Desktop graphical user interface. | - -### Docker Hub images - -Analyze image distribution activity with this chart and view the most utilized -Docker Hub images within your domain. This information helps you manage image -usage, ensuring that the most critical resources are readily available and -efficiently used. - -> [!NOTE] -> -> Data for images is only for Docker Hub. Data for third-party -> registries and mirrors aren't included. - -The chart contains the following data: - -| Data | Description | -| :------------------- | :-------------------------------------------------------------------------------------------------------------- | -| Total pulled images | The total number of images pulled by users from Docker Hub. | -| Total pushed images | The total number of images pushed by users to Docker Hub. | -| Top 10 pulled images | A list of the top 10 images pulled by users from Docker Hub and the number of times each image has been pulled. | - -### Extensions - -Monitor extension installation activity with this chart. It provides visibility -into the Docker Desktop extensions your teams are using, letting you track -adoption and identify popular tools that enhance productivity. - -The chart contains the following data: - -| Data | Description | -| :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | -| Percentage of org with extensions installed | The percentage of users in your organization with at least one Docker Desktop extension installed. | -| Top 5 extensions installed in the organization | A list of the top 5 Docker Desktop extensions installed by users in your organization and the number of users who have installed each extension. | - -## Export Docker Desktop user data - -You can export Docker Desktop user data as a CSV file: - -1. Open [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Select **Admin Console** in the left-hand navigation menu. -1. Select **Desktop insights**. -1. Choose a timeframe for your insights data: **1 Week**, **1 Month**, or - **3 Months**. -1. Select **Export** and choose **Docker Desktop users** from the drop-down. - -Your export will automatically download. Open the file to view -the export data. - -### Understanding export data - -A Docker Desktop user export file contains the following data points: - -- Name: User's name -- Username: User's Docker ID -- Email: User's email address associated with their Docker ID -- Type: User type -- Role: User [role](/manuals/enterprise/security/roles-and-permissions.md) -- Teams: Team(s) within your organization the user is a - member of -- Date Joined: The date the user joined your organization -- Last Logged-In Date: The last date the user logged into Docker using - their web browser (this includes Docker Hub and Docker Home) -- Docker Desktop Version: The version of Docker Desktop the user has - installed -- Last Seen Date: The last date the user used the Docker Desktop application -- Opted Out Analytics: Whether the user has opted out of the - [Send usage statistics](/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md#send-usage-statistics) setting in Docker Desktop - -## Troubleshoot Insights - -If you’re experiencing issues with data in Insights, consider the following -solutions to resolve common problems: - -- Update users to the latest version of Docker Desktop. - - Data is not shown for users using versions 4.16 or lower of Docker Desktop. - In addition, older versions may not provide all data. Ensure all users have - installed the latest version of Docker Desktop. - -- Turn on **Send usage statistics** in Docker Desktop for all your users. - - If users have opted out of sending usage statistics for Docker Desktop, then - their usage data will not be a part of Insights. To manage the setting at - scale for all your users, you can use [Settings - Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) and turn on the - `analyticsEnabled` setting. - -- Ensure users use Docker Desktop and aren't using the standalone - version of Docker Engine. - - Only Docker Desktop can provide data for Insights. If a user installs Docker - Engine outside of Docker Desktop, Docker Engine won't provide - data for that user. - -- Make sure users sign in to an account associated with your - organization. - - Users who don’t sign in to an account associated with your organization are - not represented in the data. To ensure users sign in with an account - associated with your organization, you can [enforce - sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). diff --git a/content/manuals/admin/organization/_index.md b/content/manuals/admin/organization/_index.md deleted file mode 100644 index 2d4ece38e93d..000000000000 --- a/content/manuals/admin/organization/_index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Organization overview -linkTitle: Organization -weight: 10 -description: Learn how to manage your Docker organization, including teams, members, permissions, and settings. -keywords: organizations, admin, overview, manage teams, roles -grid: - - title: Onboard your organization - description: Learn how to onboard and secure your organization. - icon: magnifying-glass-plus - link: /admin/organization/setup/onboard - - title: Manage members - description: Explore how to manage members. - icon: user-plus - link: /admin/organization/manage/members/ - - title: Activity logs - description: Learn how to audit the activities of your members. - icon: document-text - link: /admin/activity-logs/ - - title: Image Access Management - description: Control which types of images your developers can pull. - icon: photo - link: /admin/organization/image-access/ - - title: Registry Access Management - description: Define which registries your developers can access. - icon: server - link: /admin/organization/registry-access/ - - title: Organization settings - description: Configure information for your organization and manage settings. - icon: cog-6-tooth - link: /admin/organization/setup/general-settings/ - - title: SSO and SCIM - description: - "Set up [Single Sign-On](/manuals/enterprise/security/single-sign-on/_index.md) - and [SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) for your organization." - icon: key - - title: Domain management - description: Add, verify, and audit your domains. - link: /enterprise/security/domain-management/ - icon: check-badge - - title: FAQs - description: Explore common organization FAQs. - link: /faq/admin/organization-faqs/ - icon: question-mark-circle ---- - -A Docker organization is a collection of teams and repositories with centralized -management. It helps administrators group members and assign access in a -streamlined, scalable way. - -## Organization structure - -The following diagram shows how organizations relate to teams and members. - -![Diagram showing how teams and members relate within a Docker organization](/admin/images/org-structure.webp) - -## Organization members - -Organization owners have full administrator access to manage members, roles, -and teams across the organization. - -An organization includes members and optional teams. Teams help group members -and simplify permission management. - -## Create and manage your organization - -Learn how to create and manage your organization in the following sections. - -{{< grid >}} diff --git a/content/manuals/admin/organization/deactivate-account.md b/content/manuals/admin/organization/deactivate-account.md deleted file mode 100644 index bf794b2adcc3..000000000000 --- a/content/manuals/admin/organization/deactivate-account.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Deactivate an organization -linkTitle: Deactivate -description: Learn how to deactivate a Docker organization and required prerequisite steps. -keywords: delete, deactivate organization, account, organization management, Admin Console, cancel subscription -weight: 50 -aliases: - - /docker-hub/deactivate-account/ ---- - -{{< summary-bar feature_name="General admin" >}} - -Learn how to deactivate a Docker organization, including required prerequisite -steps. For information about deactivating user -accounts, see [Deactivate a user account](../../accounts/deactivate-user-account.md). - -> [!WARNING] -> -> All Docker products and services that use your Docker account or organization -> account will be inaccessible after deactivating your account. - -## Prerequisites - -You must complete all the following steps before you can deactivate your -organization: - -- Download any images and tags you want to keep. Use `docker pull -a <image>` - to pull all tags, or `docker pull <image>:<tag>` to pull a specific tag. -- If you have an active Docker subscription, [downgrade it to a free subscription](../../subscription/change.md). -- Remove all other members within the organization. -- Unlink your [GitHub and Bitbucket accounts](../../docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account). -- For Business organizations, [remove your SSO connection](/manuals/enterprise/security/single-sign-on/manage.md#remove-an-organization). - -## Deactivate - -You can deactivate your organization using either the Admin Console or -Docker Hub. - -> [!WARNING] -> -> This cannot be undone. Be sure you've gathered all the data you need from -> your organization before deactivating it. - -1. Sign in to [Docker Home](https://app.docker.com) and select the organization - you want to deactivate. -1. Select **Admin Console**, then **Deactivate**. If the **Deactivate** - button is unavailable, confirm you've completed all [Prerequisites](#prerequisites). -1. Enter the organization name to confirm deactivation. -1. Select **Deactivate organization**. diff --git a/content/manuals/admin/organization/manage/_index.md b/content/manuals/admin/organization/manage/_index.md deleted file mode 100644 index 36430754391c..000000000000 --- a/content/manuals/admin/organization/manage/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Manage -weight: 20 ---- \ No newline at end of file diff --git a/content/manuals/admin/organization/manage/manage-licenses.md b/content/manuals/admin/organization/manage/manage-licenses.md deleted file mode 100644 index 38bb6cf1659a..000000000000 --- a/content/manuals/admin/organization/manage/manage-licenses.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Manage license assignment -linkTitle: License assignment -description: Manage product licenses for your organization, including assignment, revocation, and automatic assignment. -keywords: licenses, organization, members, Docker Core, Docker Offload, AI governance, license assignment, admin console -weight: 30 ---- - -Licenses let you selectively choose which of your organization members have access to supported Docker products. Organization owners can oversee who on their team has active licenses, or configure licenses to assign automatically when members access supported Docker products. Like Docker Core seats, licenses can be configured on a per member basis. - -> [!TIP] -> To learn more about product licenses, Docker Core seats, and other Docker add-ons see [scale your subscription](/manuals/subscription/scale.md), -> or <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_admin_licenses" class="link" rel="noopener">contact sales</a> to purchase licenses. - -## Manage licenses - -The **Members** page lets you track the number of available licenses for your organization and who currently holds a license. You can also assign or revoke licenses from this page. - -To manage licenses for your organization: - -1. Sign in to [Docker Home](https://app.docker.com), then choose your organization. -1. Select **Members** from the left navigation. -1. Select the action menu at the end of the row to assign or revoke an active license. -1. Optional. To bulk assign or revoke licenses, choose the members you want to bulk manage, then select the **Bulk actions** menu. -1. Optional. To manage automatic license assignment, turn off or turn on with the **Automatically assign licenses** toggle. - -You must assign licenses manually, or configure automatic license assignment to consume a license. Inviting a new member to your organization consumes a seat or license if you select a product in **Licenses (optional)** during the [invite flow](/manuals/admin/organization/manage/members.md), but won't auto-assign product licenses by default. Conversely, purchasing a set of licenses won't trigger automatic assignment to existing members. - -## Automatic license assignment - -Automatic license assignment gives members a product license when they use a supported product for the first time. Automatic license assignment is available for AI Governance licenses. Only organizations that purchase AI Governance can set up auto-assignment for Docker Core as well. - -- When you purchase AI Governance, signing into [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) with `login` command in `sbx` CLI (`sbx login`) automatically provisions AI Governance licenses on a first-come, first served basis. -- Similarly, logins to Docker Desktop will automatically provision Docker Core for AI Governance license-holding organizations that have available Docker Core seats. -- Licenses are assigned until exhausted. - - Once the available licenses are exhausted, automatic license assignment will stop until you purchase more licenses or revoke assigned licenses. - - Members can still use Docker Sandbox or Docker Desktop, but organization policies for those products won't affect their usage. - -AI Governance licenses include single sign-on (SSO) and provisioning features regardless of your Docker Core subscription. Automatic license assignment requires [setting up SSO](/manuals/enterprise/security/single-sign-on/connect.md), then [provisioning with System for Cross-domain Identity Management (SCIM) or Just-in-Time (JIT)](/manuals/enterprise/security/provisioning/_index.md). - -## What's next - -See these docs to explore Docker Core add-ons, or products that need licenses: - -- [Scale your subscription](/manuals/subscription/scale.md) to learn about different add-ons -- [Manage seats](/manuals/admin/organization/manage/manage-seats.md) to add more seats to your Docker Core subscription -- [AI Governance](/manuals/ai/sandboxes/governance/org.md) to set up organization policies for your organization members -- [Docker Offload](/manuals/offload/about.md) to let your developers offload building and running containers to the cloud diff --git a/content/manuals/admin/organization/manage/manage-products.md b/content/manuals/admin/organization/manage/manage-products.md deleted file mode 100644 index 7016f69cd409..000000000000 --- a/content/manuals/admin/organization/manage/manage-products.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Docker products -weight: 50 -description: Learn how to manage access and usage for Docker products for your organization -keywords: organization, tools, products, product access, organization management -aliases: - - /admin/organization/manage-products/ ---- - -{{< summary-bar feature_name="Admin orgs" >}} - -In this section, learn how to manage access and view usage of the Docker -products for your organization. For more detailed information about each -product, including how to set up and configure them, see the following manuals: - -- [Docker Desktop](../../../desktop/_index.md) -- [Docker Hub](../../../docker-hub/_index.md) -- [Docker Build Cloud](../../../build-cloud/_index.md) -- [Docker Scout](../../../scout/_index.md) -- [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) -- [Docker Offload](../../../offload/_index.md) - -## Manage product access for your organization - -Access to the Docker products included in your subscription is turned on by -default for all users. For an overview of products included in your -subscription, see -[Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminManageProducts). - -{{< tabs >}} -{{< tab name="Docker Desktop" >}} - -### Manage Docker Desktop access - -To manage Docker Desktop access: - -1. [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). -1. Manage members [manually](./members.md) or use - [provisioning](/manuals/enterprise/security/provisioning/_index.md). - -With sign-in enforced, only users who are a member of your organization can -use Docker Desktop after signing in. - -{{< /tab >}} -{{< tab name="Docker Hub" >}} - -### Manage Docker Hub access - -To manage Docker Hub access, sign in to -[Docker Home](https://app.docker.com/) and configure [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) -or [Image Access Management](/manuals/enterprise/security/hardened-desktop/image-access-management.md). - -{{< /tab >}} -{{< tab name="Docker Build Cloud" >}} - -### Manage Docker Build Cloud access - -To initially set up and configure Docker Build Cloud, sign in to -[Docker Build Cloud](https://app.docker.com/build) and follow the -on-screen instructions. - -To manage Docker Build Cloud access: - -1. Sign in to [Docker Build Cloud](http://app.docker.com/build) as an - organization owner. -1. Select **Account settings**. -1. Select **Lock access to Docker Build Account**. - -{{< /tab >}} -{{< tab name="Docker Scout" >}} - -### Manage Docker Scout access - -To initially set up and configure Docker Scout, sign in to -[Docker Scout](https://scout.docker.com/) and follow the on-screen instructions. - -To manage Docker Scout access: - -1. Sign in to [Docker Scout](https://scout.docker.com/) as an organization - owner. -1. Select your organization, then **Settings**. -1. To manage what repositories are enabled for Docker Scout analysis, select - **Repository settings**. For more information on, - see [repository settings](../../../scout/explore/dashboard.md#repository-settings). -1. To manage access to Docker Scout for use on local images with Docker Desktop, - use [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) - and set `sbomIndexing` to `false` to disable, or to `true` to enable. - -{{< /tab >}} -{{< tab name="Testcontainers Cloud" >}} - -### Manage Testcontainers Cloud access - -To initially set up and configure Testcontainers Cloud, sign in to -[Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the -on-screen instructions. - -To manage access to Testcontainers Cloud: - -1. Sign in to the [Testcontainers Cloud](https://app.testcontainers.cloud/) and - select **Account**. -1. Select **Settings**, then **Lock access to Testcontainers Cloud**. - -{{< /tab >}} -{{< tab name="Docker Offload" >}} - -### Manage Docker Offload access - -> [!NOTE] -> -> Docker Offload isn't included in the core Docker subscription plans. To make Docker Offload available, you must [contact sales](https://www.docker.com/products/docker-offload/) and subscribe. - -To manage Docker Offload access for your organization, use [Settings -Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md): - -1. Sign in to [Docker Home](https://app.docker.com/) as an organization owner. -1. Select **Admin Console** > **Desktop Settings Management**. -1. Configure the **Enable Docker Offload** setting to control whether Docker Offload features are available in Docker - Desktop. You can configure this setting in five states: - - **Always enabled**: Docker Offload is always enabled and users cannot disable it. The Offload - toggle is always visible in Docker Desktop header. Recommended for VDI environments where local Docker execution is - not possible. - - **Enabled**: Docker Offload is enabled by default but users can disable it in Docker Desktop - settings. Suitable for hybrid environments. - - **Disabled**: Docker Offload is disabled by default but users can enable it in Docker Desktop - settings. - - **Always disabled**: Docker Offload is disabled and users cannot enable it. The option is - visible but locked. Use when Docker Offload is not approved for organizational use. - - **User defined**: No enforced default. Users choose whether to enable or disable Docker Offload in their - Docker Desktop settings. -1. Select **Save**. - -For more details on Settings Management, see the [Settings -reference](/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md#enable-docker-offload). - -{{< /tab >}} -{{< /tabs >}} - -## Monitor product usage for your organization - -To view usage for Docker products: - -- Docker Desktop: View the **Insights** page in [Docker Home](https://app.docker.com/). For more details, see [Insights](../../insights.md). -- Docker Hub: View the [**Usage** page](https://hub.docker.com/usage) in Docker Hub. -- Docker Build Cloud: View the **Build minutes** page in [Docker Build Cloud](http://app.docker.com/build). -- Docker Scout: View the [**Repository settings** page](https://scout.docker.com/settings/repos) in Docker Scout. -- Testcontainers Cloud: View the [**Billing** page](https://app.testcontainers.cloud/dashboard/billing) in Testcontainers Cloud. -- Docker Offload: View the **Offload** > **Offload overview** page in [Docker Home](https://app.docker.com/). For more details, see - [Docker Offload usage and billing](/manuals/offload/usage.md). - -If your usage or seat count exceeds your subscription amount, you can -[scale your subscription](../../../subscription/scale.md) to meet your needs. diff --git a/content/manuals/admin/organization/manage/members.md b/content/manuals/admin/organization/manage/members.md deleted file mode 100644 index 0278be28dd61..000000000000 --- a/content/manuals/admin/organization/manage/members.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Manage organization members -linkTitle: Members -weight: 10 -description: Learn how to manage organization members in Docker Hub and Docker Admin Console. -keywords: members, teams, organizations, invite members, manage team members, export member list, edit roles, organization teams, user management -aliases: - - /docker-hub/members/ - - /admin/organization/members/ ---- - -Learn how to manage members for your organization in Docker Hub and the Docker Admin Console. - -## Invite members - -Owners can invite new members to an organization via Docker ID, email address, or with a CSV file containing email addresses. If an invitee does not have a Docker account, they must create an account and verify their email address before they can accept an invitation to join the organization. When inviting members, their pending invitation occupies a seat. - -### Invite members via Docker ID or email address - -Use the following steps to invite members to your organization via Docker ID or email address. - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Select **Members**, then **Invite**. -1. Select **Emails or usernames**. -1. Follow the on-screen instructions to invite members. Invite a maximum of 1000 members and separate multiple entries by comma, semicolon, or space. - -When you invite members, you assign them a role. See [Roles and permissions](/manuals/enterprise/security/roles-and-permissions/_index.md) for -details about the access permissions for each role. - -Pending invitations appear in the table. Invitees receive an email with a link to Docker Hub where they can accept or decline the invitation. - -### Invite members via CSV file - -To invite multiple members to an organization via a CSV file containing email addresses: - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. Select **Members** > **Invite** > **CSV upload**. -1. Optional. Select **Download the template CSV file** to download an example CSV file. The following is an example of the contents of a valid CSV file: - - ```text - email - docker.user-0@example.com - docker.user-1@example.com - ``` - - The example file demonstrates CSV file requirements: - - The file must contain a header row with at least one heading named email. Additional columns are allowed and are ignored in the import. - - The file must contain a maximum of 1000 email addresses (rows). To invite more than 1000 users, create multiple CSV files and perform all steps in this task for each file. - -1. Create a new CSV file or export a CSV file from another application. - - To export a CSV file from another application, see the application’s documentation. - - To create a new CSV file, open a new file in a text editor, type email on the first line, type the user email addresses one per line on the following lines, and then save the file with a .csv extension. -1. Select **Browse files** and then select your CSV file, or drag and drop the CSV file into the **Select a CSV file to upload** box. You can only select one CSV file at a time. -1. After the CSV file has been uploaded, select **Review** to identify any invalid email addresses, already invited users, invited users who are already members, or duplicated email addresses within the same CSV file. -1. Follow the on-screen instructions to invite members. - -Pending invitations appear in the table. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation. - -### Invite members via API - -You can bulk invite members using the Docker Hub API. For more information, see the [Bulk create invites](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) API endpoint. - -## Accept invitation - -After receiving an email invitation, users can access -a link to Docker Hub where they can accept or decline the invitation. - -To accept an invitation: - -1. Check your email inbox and open the Docker email with an invitation to - join the Docker organization. -1. To open the link to Docker Hub, select the **click here** link. -1. The Docker create an account page will open. If you already have an account, select **Already have an account? Sign in**. - If you do not have an account yet, create an account using the same email - address you received the invitation through. -1. Optional. If you do not have an account and created one, you must navigate - back to your email inbox and verify your email address using the Docker verification - email. -1. Once you are signed in to Docker Hub, select **My Hub** from the top-level navigation menu. -1. Select **Accept** on your invitation. - -After accepting an invitation, you are now a member of the organization. - -Invitation email links expire after 14 days. If your email link has expired, you can sign in to [Docker Hub](https://hub.docker.com/) with the email address the link was sent to and accept the invitation from the **Notifications** panel. - -## Manage invitations - -After inviting members, you can resend or remove invitations as needed. Each invitee occupies one seat, so if the amount of email addresses in your CSV file exceeds the number of available seats in your organization, you won't be able to invite more members. - -> [!TIP] -> Need to manage more than 1,000 team members? [Upgrade to Docker Business for unlimited user invites](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminMembers) and advanced role management. You can also [add seats](/manuals/admin/organization/manage/manage-seats.md) to your subscription. - -### Resend an invitation - -You can send individual invitations, or bulk invitations from the Admin Console. - -To resend an individual invitation: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Members**. -1. Select the **action menu** next to the invitee and select **Resend**. -1. Select **Invite** to confirm. - -To bulk resend invitations: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Members**. -1. Use the **checkboxes** next to **Usernames** to bulk select users. -1. Select **Resend invites**. -1. Select **Resend** to confirm. - -### Remove an invitation - -To remove an invitation from the Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Members**. -1. Select the **action menu** next to the invitee and select **Remove invitee**. -1. Select **Remove** to confirm. - -## Manage members on a team - -Use Docker Hub or the Admin Console to add or remove team members. Organization owners can add a member to one or more teams within an organization. - -### Add a member to a team - -To add a member to a team with the Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Teams**. -1. Select the team name. -1. Select **Add member**. You can add the member by searching for their email address or username. - -An invitee must first accept the invitation to join the organization before being added to the team. - -### Remove members from teams - -If your organization uses single sign-on (SSO) with [SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) enabled, you should remove members from your identity provider (IdP). This automatically removes members from Docker. If SCIM is disabled, follow procedures in this doc to remove members manually in Docker. - -Organization owners can remove a member from a team in Docker Hub or Admin Console. Removing the member from the team will revoke their access to the permitted resources. To remove a member from a specific team with the Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Teams**, then choose the name of the team member you want to remove. -1. Select the **X** next to the user's name to remove them from the team. -1. When prompted, select **Remove** to confirm. - -### Update a member role - -Organization owners can manage [roles](/manuals/enterprise/security/roles-and-permissions/_index.md) -within an organization. If an organization is part of a company, -the company owner can also manage that organization's roles. If you have SSO enabled, you can use [SCIM for role mapping](/manuals/enterprise/security/provisioning/scim/_index.md). - -To update a member role in the Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Members**. -1. Find the username of the member whose role you want to edit. Select the - **Actions** menu, then **Edit role**. - -If you're the only owner of an organization and you want to edit your role, assign a new owner -for your organization so you can edit your role. - -## Export members CSV file - -{{< summary-bar feature_name="Admin orgs" >}} - -Owners can export a CSV file containing all members. The CSV file for a company contains the following fields: - -- Name: The user's name -- Username: The user's Docker ID -- Email: The user's email address -- Member of Organizations: All organizations the user is a member of within a company -- Invited to Organizations: All organizations the user is an invitee of within a company -- Account Created: The time and date when the user account was created - -To export a CSV file of your members: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Members**. -1. Select the **download** icon to export a CSV file of all members. diff --git a/content/manuals/admin/organization/organization-faqs.md b/content/manuals/admin/organization/organization-faqs.md deleted file mode 100644 index 5f80988d7e13..000000000000 --- a/content/manuals/admin/organization/organization-faqs.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Organization FAQs -linkTitle: FAQs -weight: 60 -description: Organization FAQs -keywords: Docker, Docker Hub, SSO FAQs, single sign-on, organizations, administration, Admin Console, members, organization management, manage orgs -tags: [FAQ] -aliases: - - /docker-hub/organization-faqs/ - - /faq/admin/organization-faqs/ - - /admin/faqs/organization-faqs/ ---- - -### How can I see how many active users are in my organization? - -If your organization uses a Software Asset Management tool, you can use it to -find out how many users have Docker Desktop installed. If your organization -doesn't use this software, you can run an internal survey -to find out who is using Docker Desktop. - -For more information, see [Identify your Docker users and their Docker accounts](../../admin/organization/setup/onboard.md#step-one-identify-your-docker-users). - -### Do users need to authenticate with Docker before an owner can add them to an organization? - -No. Organization owners can invite users with their email addresses, and also -assign them to a team during the invite process. - -### Can I force my organization's members to authenticate before using Docker Desktop and are there any benefits? - -Yes. You can -[enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). - -Some benefits of enforcing sign-in are: - -- Ensures users receive the benefits of your subscription. -- Ensures security features like [Image Access Management](/manuals/enterprise/security/hardened-desktop/image-access-management.md) and [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) are applied. -- Ensures you gain insights into users' activity. - -### Can I convert my personal Docker ID to an organization account? - -Yes. You can convert your user account to an organization account. Once you -convert a user account into an organization, it's not possible to -revert it to a personal user account. - -For prerequisites and instructions, see -[Convert an account into an organization](convert-account.md). - -### Do organization invitees take up seats? - -Yes. A user invited to an organization will take up one of the provisioned -seats, even if that user hasn’t accepted their invitation yet. - -To manage invites, see [Manage organization members](/manuals/admin/organization/manage/members.md). - -### Do organization owners take a seat? - -Yes. Organization owners occupy a seat. - -### What is the difference between user, invitee, seat, and member? - -- User: Docker user with a Docker ID. -- Invitee: A user that an administrator has invited to join an organization but - has not yet accepted their invitation. -- Seats: The number of purchased seats in an organization. -- Member: A user who has received and accepted an invitation to join an - organization. Member can also refer to a member of a team within an - organization. - -### If I have two organizations and a user belongs to both organizations, do they take up two seats? - -Yes. In a scenario where a user belongs to two organizations, they take up one -seat in each organization. diff --git a/content/manuals/admin/organization/setup/_index.md b/content/manuals/admin/organization/setup/_index.md deleted file mode 100644 index 676f6ca7c187..000000000000 --- a/content/manuals/admin/organization/setup/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Setup -weight: 10 ---- \ No newline at end of file diff --git a/content/manuals/admin/organization/setup/convert-account.md b/content/manuals/admin/organization/setup/convert-account.md deleted file mode 100644 index 7c5b856d5bfc..000000000000 --- a/content/manuals/admin/organization/setup/convert-account.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -description: Convert your Docker Hub user account into an organization -linkTitle: Convert account -title: Convert an account into an organization -keywords: docker hub, hub, organization, convert account, migrate account -weight: 40 -aliases: - - /docker-hub/convert-account/ - - /admin/organization/convert-account/ ---- - -{{< summary-bar feature_name="Admin orgs" >}} - -Learn how to convert an existing user account into an organization. This is -useful if you need multiple users to access your account and the repositories -it’s connected to. Converting it to an organization gives you better control -over permissions for these users through -[teams](/manuals/admin/organization/manage/manage-a-team.md) and -[roles](/manuals/enterprise/security/roles-and-permissions.md). - -When you convert a user account to an organization, the account is migrated to -a Docker Team subscription by default. - -## Prerequisites - -Before you convert a user account to an organization, ensure that you meet the following requirements: - -- The user account that you want to convert must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company. - - To do this: - 1. Navigate to **My Hub** and then select the organization you need to leave. - 1. Find your username in the **Members** tab. - 1. Select the **More options** menu and then select **Leave organization**. - - If the user account is the sole owner of any organization or company, assign another user the owner role and then remove yourself from the organization or company. - -- You must have a separate Docker ID ready to assign as the owner of the organization during conversion. - - If you want to convert your user account into an organization account and you don't have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. With the owner role assigned, this user account has full administrative access to configure and manage the organization. You can assign more users the owner role after the conversion. - -## What happens when you convert your account - -The following happens when you convert your account into -an organization: - -- This process removes the email address for the account. Notifications are - instead sent to organization owners. You'll be able to reuse the - removed email address for another account after converting. -- The current subscription will automatically cancel and your new subscription - will start. -- Repository namespaces and names won't change, but converting your account - removes any repository collaborators. Once you convert the account, you'll need - to add repository collaborators as team members. -- Existing automated builds appear as if they were set up by the first owner - added to the organization. -- The user account that you add as the first owner will have full - administrative access to configure and manage the organization. -- To transfer a user's personal access tokens (PATs) to your converted - organization, you must designate the user as an organization owner. This will - ensure any PATs associated with the user's account are transferred to the - organization owner. - -## Convert an account into an organization - -> [!IMPORTANT] -> -> Converting an account into an organization is permanent. Back up any data -> or settings you want to retain. - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Select your avatar in the top-right corner to open the drop-down. -1. From **Account settings**, select **Convert**. -1. Review the warning displayed about converting a user account. This action - cannot be undone and has considerable implications for your assets and the - account. -1. Enter a **Username of new owner** to set an organization owner. The new - Docker ID you specify becomes the organization’s owner. You cannot use the - same Docker ID as the account you are trying to convert. The Docker ID is - case-sensitive. -1. Select **Confirm**. The new owner receives a notification email. Use that - owner account to sign in and manage the new organization. diff --git a/content/manuals/admin/organization/setup/general-settings.md b/content/manuals/admin/organization/setup/general-settings.md deleted file mode 100644 index 8a90fec0d446..000000000000 --- a/content/manuals/admin/organization/setup/general-settings.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Change general organization information -linkTitle: Change information -weight: 30 -description: Learn how to manage settings for organizations using Docker Admin Console. -keywords: organization, settings, Admin Console, manage, Docker organization, Gravatar, SCIM, SSO setup, domain management, organization settings -aliases: - - /admin/organization/general-settings/ ---- - -Learn how to update your organization information using the Admin Console. - -## Update organization information - -General organization information appears on your organization landing page in the Admin Console. - -This information includes: - -- Organization Name -- Company -- Location -- Website -- Gravatar email: To add an avatar to your Docker account, create a [Gravatar account](https://gravatar.com/) and upload an avatar. Next, add your Gravatar email to your Docker account settings. It may take some time for your avatar to update in Docker. - -To edit this information: - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and - select your organization from the top-left account drop-down. -1. Enter or update your organization’s details, then select **Save**. - -## Next steps - -After configuring your organization information, you can: - -- [Configure single sign-on (SSO)](/manuals/enterprise/security/single-sign-on/connect.md) -- [Set up SCIM provisioning](/manuals/enterprise/security/provisioning/scim/_index.md) -- [Manage domains](/manuals/enterprise/security/domain-management.md) -- [Create a company](/manuals/admin/company/new-company.md) diff --git a/content/manuals/admin/organization/setup/onboard.md b/content/manuals/admin/organization/setup/onboard.md deleted file mode 100644 index 97cfef98576b..000000000000 --- a/content/manuals/admin/organization/setup/onboard.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Onboard your organization -linkTitle: Onboard -weight: 20 -description: Get started onboarding your Docker Team or Business organization. -keywords: business, team, organizations, get started, onboarding, Admin Console, organization management, -toc_min: 1 -toc_max: 3 -aliases: - - /docker-hub/onboard/ - - /docker-hub/onboard-team/ - - /docker-hub/onboard-business/ - - /admin/organization/onboard/ ---- - -{{< summary-bar feature_name="Admin orgs" >}} - -Learn how to onboard your organization using the Admin Console or Docker Hub. - -Onboarding your organization includes: - -- Identifying users to help you allocate your subscription seats -- Invite members and owners to your organization -- Secure authentication and authorization for your organization -- Enforce sign-in for Docker Desktop to ensure security best practices - -These actions help administrators gain visibility into user activity and -enforce security settings. Organization members also receive increased pull -limits and other benefits when they are signed in. - -## Prerequisites - -Before you start onboarding your organization, ensure you: - -- Have a Docker Team or Business subscription. For more details, see - [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOnboard). - - > [!NOTE] - > - > When purchasing a self-serve subscription, the on-screen instructions - > guide you through creating an organization. If you have purchased a - > subscription through Docker Sales and you have not yet created an - > organization, see [Create an organization](/manuals/admin/organization/setup/orgs.md). - -- Familiarize yourself with Docker concepts and terminology in - the [administration overview](../../_index.md). - -## Onboard with guided setup - -The Admin Console has a guided setup to help you -onboard your organization. The guided setup's steps consist of basic onboarding -tasks. If you want to onboard outside of the guided setup, -see [Recommended onboarding steps](/manuals/admin/organization/setup/onboard.md#recommended-onboarding-steps). - -To onboard using the guided setup, -navigate to the [Admin Console](https://app.docker.com) and -select **Guided setup** in the left-hand navigation. - -The guided setup walks you through the following onboarding steps: - -- **Invite your team**: Invite owners and members. -- **Manage user access**: Add and verify a domain, manage users with SSO, and - enforce Docker Desktop sign-in. -- **Docker Desktop security**: Configure image access management, registry - access management, and settings management. - -## Recommended onboarding steps - -### Step one: Identify your Docker users - -Identifying your users helps you allocate seats efficiently and ensures they -receive your Docker subscription benefits. - -1. Identify the Docker users in your organization. - - If your organization uses device management software, like MDM or Jamf, - you can use the device management software to help identify Docker users. - See your device management software's documentation for details. You can - identify Docker users by checking if Docker Desktop is installed at the - following location on each user's machine: - - Mac: `/Applications/Docker.app` - - Windows: `C:\Program Files\Docker\Docker`(all-user installation) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installation (Beta)) - - Linux: `/opt/docker-desktop` - - If your organization doesn't use device management software or your - users haven't installed Docker Desktop yet, you can survey your users to - identify who is using Docker Desktop. -1. Ask users to update their Docker account's email address to one associated - with your organization's domain, or create a new account with that email. - - To update an account's email address, instruct your users to sign in - to [Docker Hub](https://hub.docker.com), and update the email address to - their email address in your organization's domain. - - To create a new account, instruct your users to - [sign up](https://hub.docker.com/signup) using their email address associated - with your organization's domain. Ensure your users verify their email address. -1. Identify Docker accounts associated with your organization's domain: - - Ask your Docker sales representative or - <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_org_onboarding" class="link" rel="noopener">contact sales</a> to get a list - of Docker accounts that use an email address in your organization's domain. - -### Step two: Invite owners - -Owners can help you onboard and manage your organization. - -When you create an organization, you are the only owner. It is optional to -add additional owners. - -To add an owner, invite a user and assign them the owner role. For more -details, see [Invite members](/manuals/admin/organization/manage/members.md) and -[Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). - -### Step three: Invite members - -When you add users to your organization, you gain visibility into their -activity and you can enforce security settings. Your members also -receive increased pull limits and other organization wide benefits when -they are signed in. - -To add a member, invite a user and assign them the member role. -For more details, see [Invite members](/manuals/admin/organization/manage/members.md) and -[Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md). - -### Step four: Manage user access with SSO and SCIM - -Configuring SSO and SCIM is optional and only available to Docker Business -subscribers. To upgrade a Docker Team subscription to a Docker Business -subscription, see [Change your subscription](/manuals/subscription/change.md). - -Use your identity provider (IdP) to manage members and provision them to Docker -automatically via SSO and SCIM. See the following for more details: - -- [Configure SSO](/manuals/enterprise/security/single-sign-on/connect.md) - to authenticate and add members when they sign in to Docker through your - identity provider. -- Optional. - [Enforce SSO](/manuals/enterprise/security/single-sign-on/connect.md) to - ensure that when users sign in to Docker, they must use SSO. - - > [!NOTE] - > - > Enforcing single sign-on (SSO) and enforcing Docker Desktop sign in - > are different features. For more details, see - > [Enforcing sign-in versus enforcing single sign-on (SSO)](/manuals/enterprise/security/enforce-sign-in/_index.md#enforcing-sign-in-versus-enforcing-single-sign-on-sso). - -- [Configure SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) to - automatically provision, add, and de-provision members to Docker through - your identity provider. - -### Step five: Enforce sign-in for Docker Desktop - -By default, members of your organization can use Docker Desktop without signing -in. When users don’t sign in as a member of your organization, they don’t -receive the -[benefits of your organization’s subscription](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOnboard) -and they can circumvent [Docker’s security features](/manuals/enterprise/security/hardened-desktop/_index.md). - -There are multiple ways you can enforce sign-in, depending on your organization's -Docker configuration: - -- [Registry key method (Windows only)](/manuals/enterprise/security/enforce-sign-in/methods.md#registry-key-method-windows-only) -- [`.plist` method (Mac only)](/manuals/enterprise/security/enforce-sign-in/methods.md#plist-method-mac-only) -- [`registry.json` method (All)](/manuals/enterprise/security/enforce-sign-in/methods.md#registryjson-method-all) - -### Step six: Manage Docker Desktop security - -Docker offers the following security features to manage your organization's -security posture: - -- [Image Access Management](/manuals/enterprise/security/hardened-desktop/image-access-management.md): Control which types of images your developers can pull from Docker Hub. -- [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md): Define which registries your developers can access. -- [Settings management](/manuals/enterprise/security/hardened-desktop/settings-management.md): Set and control Docker Desktop settings for your users. - -## What's next - -- [Manage Docker products](../manage/manage-products.md) to configure access and view usage. -- Configure [Hardened Docker Desktop](/manuals/enterprise/security/hardened-desktop/_index.md) to improve your organization’s security posture for containerized development. -- [Manage your domains](/manuals/enterprise/security/domain-management.md) to ensure that all Docker users in your domain are part of your organization. - -Your Docker subscription provides many more additional features. To learn more, -see [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOnboard). diff --git a/content/manuals/admin/organization/setup/orgs.md b/content/manuals/admin/organization/setup/orgs.md deleted file mode 100644 index 4ce5256b3496..000000000000 --- a/content/manuals/admin/organization/setup/orgs.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Create your organization -linkTitle: Create -weight: 10 -description: Learn how to create an organization. -keywords: docker organizations, organization, create organization, docker teams, docker admin console, organization management -aliases: - - /docker-hub/orgs/ - - /admin/organization/orgs/ ---- - -{{< summary-bar feature_name="Admin orgs" >}} - -There are multiple ways to create an organization. You can either: - -- Create a new organization using the **Create Organization** option in the - Admin Console or Docker Hub -- Convert an existing user account to an organization - -These procedures walk you through creating an organization from the Admin Console. - -## Prerequisites - -- Before you create an organization, you need a [Docker ID](/manuals/accounts/create-account.md). -- For prerequisites and detailed instructions on converting an existing user account to an organization, see - [Convert an account into an organization](/manuals/admin/organization/setup/convert-account.md). - -> [!TIP] -> Need a different plan for your team's needs? Review different [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOrgs) to choose a subscription for your organization. - -## Create an organization - -1. Sign in to [Docker Home](https://app.docker.com/) and navigate to the bottom - of the organization list. Select **Create new organization**. -1. Choose a subscription for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing?ref=Docs&refAction=DocsAdminOrgs) for details on the features offered in the Team and Business subscription. -1. Select **Continue to profile**, then **Create an organization** to create a new organization. -1. Enter an **Organization namespace**. This is the official, unique name for - your organization in Docker Hub. - - It's not possible to change the name of the organization after you've created it. - - Your Docker ID and organization can't share the same name. - - If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](/manuals/admin/organization/setup/convert-account.md). -1. Enter your **Company name**. This is the full name of your company. - - Docker displays the company name on your organization page and in the details of any - public images you publish. - - You can update the company name anytime by navigating to your organization's **Settings** page. -1. Select **Continue to billing** to continue, then enter your organization's billing information. Select **Continue to payment** to continue to the billing portal. -1. Provide your payment details and select **Purchase**. - -You've now created an organization. - -## View an organization - -To view an organization in the Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. -1. From the left-hand navigation menu, select **Admin Console**. - -The Admin Console contains many options that let you to -configure your organization. - -## Merge organizations - -> [!WARNING] -> -> If you are merging organizations, it is recommended to do so at the _end_ of -> your billing cycle. When you merge an organization and downgrade another, you -> will lose seats on your downgraded organization. Docker does not offer -> refunds for downgrades. - -If you have multiple organizations that you want to merge into one, complete -the following steps: - -1. Based on the number of seats from the secondary organization, [purchase additional seats](../manage/manage-seats.md) for the primary organization account that you want to keep. -1. Manually add users to the primary organization and remove existing users from the secondary organization. -1. Manually move over your data, including all repositories. -1. Once you're done moving all of your users and data, [downgrade](../../../subscription/change.md) the secondary account to a free subscription. Note that Docker does not offer refunds for downgrading organizations mid-billing cycle. - -If your organization has a Docker Business subscription with a purchase -order, contact Support or your Account Manager at Docker. - -## More resources - -- [Video: Docker Hub Organizations](https://www.youtube.com/watch?v=WKlT1O-4Du8) diff --git a/content/manuals/agentic-platform/_index.md b/content/manuals/agentic-platform/_index.md new file mode 100644 index 000000000000..e26099a48164 --- /dev/null +++ b/content/manuals/agentic-platform/_index.md @@ -0,0 +1,78 @@ +--- +title: Docker Agentic Platform +description: Run agents and tools in isolated cloud sandboxes with Docker Agentic Platform. +keywords: docker agentic platform, agents, kits, sandboxes, mcp, secrets, network policies +weight: 5 +params: + sidebar: + group: AI and agents + badge: + color: violet + text: Experimental +grid: + - title: Sign up + description: Activate cloud access and review billing. + icon: credit-card + link: /agentic-platform/signup/ + - title: Get started + description: Start your first sandbox. + icon: rocket-launch + link: /agentic-platform/get-started/ + - title: Kits + description: Find a kit or run your own public kit. + icon: cube + link: /agentic-platform/kits/ + - title: Sandboxes + description: Access, pause, resume, and delete your sandboxes. + icon: command-line + link: /agentic-platform/sandboxes/ + - title: MCP + description: Connect predefined or custom MCP servers. + icon: cpu-chip + link: /agentic-platform/mcp/ + - title: Secrets + description: Manage model provider and service credentials. + icon: key + link: /agentic-platform/secrets/ + - title: Policies + description: Control outbound network access from sandboxes. + icon: shield-check + link: /agentic-platform/policies/ + - title: FAQ + description: Find answers about access, billing, and supported features. + icon: question-mark-circle + link: /agentic-platform/faq/ +--- + +> [!NOTE] +> Docker Agentic Platform is experimental. Features and behavior may change. + +Docker Agentic Platform lets you run agents and tools in isolated cloud +sandboxes. Your agent keeps working when you close the Console, disconnect +your computer, or put it to sleep. + +The `sbx` CLI supports both +[local sandboxes](/manuals/ai/sandboxes/get-started.md) and +[cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md). These pages describe +the web Console experience. The Console and CLI use different secret names; +see [Cloud credentials](/manuals/ai/sandboxes/cloud/credentials.md). + +In the Console, choose a [kit](/manuals/agentic-platform/kits.md) and configure +the sandbox's credentials, network access, tools, and compute size. Once it +starts, use its terminal to work with the agent. You can return to running or +paused sandboxes from **Sandboxes**. + +You can reuse these settings across sandboxes: + +- [MCP](/manuals/agentic-platform/mcp.md) connects external tools. +- [Secrets](/manuals/agentic-platform/secrets.md) provide credentials + without placing their values inside a sandbox. +- [Network policies](/manuals/agentic-platform/policies.md) control + which hosts and services a sandbox can reach. + +To begin, [activate your subscription](signup.md#activate-cloud-access), then +[start a sandbox](get-started.md). You pay for compute by the second while your +sandbox runs. See [Signup and billing](signup.md) for account and payment +information. + +{{< grid >}} diff --git a/content/manuals/agentic-platform/faq.md b/content/manuals/agentic-platform/faq.md new file mode 100644 index 000000000000..16220096d444 --- /dev/null +++ b/content/manuals/agentic-platform/faq.md @@ -0,0 +1,84 @@ +--- +title: Docker Agentic Platform FAQ +linkTitle: FAQ +description: Find answers about Docker Agentic Platform sandboxes, access, credentials, billing, and data retention. +keywords: docker agentic platform, faq, sandboxes, agents, docker sandboxes, usage, billing, inference, logs, telemetry, snapshots, data retention +weight: 80 +aliases: + - /agentic-platform/concepts/local-cloud/ +--- + +## What can I run in Docker Agentic Platform? + +You can run agents such as Claude Code, Codex, and Hermes in isolated cloud +sandboxes with live terminals. Browse [Kits](kits.md) for curated and community +agents, or choose Shell to work without an agent. You can also enter a public +kit reference in the launcher. + +## Can I use private kits? + +You can run private Docker Hub kits using the Docker Sandboxes CLI. Launching +a kit from the Console requires both the kit and its base image to be public. +The **Kits** page provides the CLI command to copy. + +To access private GitHub repositories from inside a sandbox, use a +[GitHub credential](secrets.md#github-credential). + +## How does Docker Agentic Platform differ from Docker Sandboxes? + +Docker Agentic Platform runs sandboxes on Docker-managed cloud infrastructure +through a web Console. The `sbx` CLI runs local sandboxes on your development +machine and cloud sandboxes with `sbx --cloud`. The Console and CLI have +different workflows and secret names. See +[Cloud sandboxes](/manuals/ai/sandboxes/cloud/_index.md) for the CLI experience. + +## Can I move a sandbox between my machine and Docker Agentic Platform? + +The `sbx move` command copies a sandbox filesystem between local and cloud +environments. It does not transfer running processes, host bind mounts, or +managed secrets, and it leaves the source sandbox in place. See +[Move a sandbox](/manuals/ai/sandboxes/cloud/move.md) for the CLI workflow and +its limitations. + +## Can I share sandboxes and configuration with a team? + +The initial release is for individual use. You manage your own sandboxes, MCP +connections, secrets, and network policies. Shared workspaces and team +ownership aren't supported. + +## How does a sandbox access external services? + +The **Open** user policy allows outbound access to any host. **Balanced** +allows a curated set of hosts and services. Allow rules from all applicable +policies are combined: selecting both **Open** and **Balanced** permits all +outbound destinations except those blocked by explicit deny rules. Balanced's +allow list doesn't restrict Open's access. To restrict access with an allow +list, deselect **Open** if it is selected and can be removed. + +The launcher remembers your policy selections from the previous launch in the +same browser. Without saved selections, it selects the account's policies +marked **Always applied**. These policies can't be deselected in the launcher. + +Your kit's network rules also apply. If an allow rule and a deny rule match +the same destination, the deny rule wins. See [Network policies](policies.md) +for details. + +For services that need authentication, save your credentials under +[Secrets](secrets.md). The sandbox proxy adds them to matching requests without +exposing their values to the agent. + +## How are sandbox usage and model inference billed? + +You pay for compute by the second while your sandbox runs. The Console also +shows the equivalent hourly rate. + +Your model provider bills inference separately, under the account associated +with your API key. See [Docker Billing](/subscription-billing/) for account, +usage, and payment information. + +## How long are logs, telemetry, and snapshots retained? + +Service logs are kept for 31 days and raw telemetry for 12 months. + +All snapshots, including the most recent snapshot created when you pause a +sandbox, are automatically deleted after seven days of non-use. diff --git a/content/manuals/agentic-platform/get-started.md b/content/manuals/agentic-platform/get-started.md new file mode 100644 index 000000000000..6b5c76925d5e --- /dev/null +++ b/content/manuals/agentic-platform/get-started.md @@ -0,0 +1,234 @@ +--- +title: Get started with Docker Agentic Platform +linkTitle: Get started +description: Review a sample project with a coding agent or build and preview it from a shell in a cloud sandbox, without setting up a local development environment. +keywords: docker agentic platform, get started, cloud sandboxes, shell, agents, ssh, vscode, cursor +weight: 10 +aliases: + - /agentic-platform/concepts/platform-model/ +--- + +Use a cloud sandbox to review a project with a coding agent or build and run +an application from a shell, without setting up the project on your computer. + +You can complete either workflow in the browser. An optional step shows how +to open the same project in VS Code or Cursor over SSH. + +## Before you begin + +You need a personal Docker account with an active +[Docker Agentic Platform subscription](signup.md#activate-cloud-access). + +Both workflows use a public sample project, so you don't need a GitHub token. + +## Choose a workflow + +- [Use a coding agent](#use-a-coding-agent) to have Claude Code review a sample + project and save its findings. You need an Anthropic API key. +- [Use a shell](#use-a-shell) to build and run the sample application and preview + it in your browser. You don't need a model provider API key. + +## Use a coding agent + +Add an Anthropic API key under **Secrets** or enter it when you launch the +sandbox. Your model provider bills inference separately from Docker's sandbox +compute charges. For other agents and their credentials, see [Kits](kits.md) +and [Secrets](secrets.md). + +### Launch Claude Code + +1. Open [Docker Agentic Platform](https://agentic-platform.docker.com/) and + select **+ New sandbox**. +2. Choose the Claude Code kit. +3. Add your Anthropic API key if it isn't already saved. Don't enter it in + the agent's prompt or in a file inside the sandbox. +4. Keep the defaults and select **Run**. + +On your first launch, the default **Open** network policy permits outbound +access to any host. If you're using a custom policy, make sure it permits +GitHub and your model provider. See [Network policies](policies.md). + +When the sandbox is ready, its terminal opens with Claude Code. + +### Give the agent a task + +Your local files aren't mounted in a cloud sandbox. Ask Claude Code to clone +and review a public sample project: + +```text +Clone https://github.com/docker/welcome-to-docker.git into +/home/agent/workspace/project, then review the application. +Read the source, package.json, and Dockerfile. Don't modify the application +or install dependencies. +Write /home/agent/workspace/review.md with: +- A short explanation of what the application does. +- The commands defined in package.json for running and building it. +- An explanation of how the Dockerfile builds and serves the application. +- One small improvement you'd recommend, with the relevant file path. +Base the review on the files you read. Don't claim to have run the application. +Summarize your findings in your response. +``` + +Claude Code summarizes the project in the conversation and saves the review +at `/home/agent/workspace/review.md`. You can ask follow-up questions or give +it another task in the same session. + +Continue to [keep your work](#keep-your-work), or +[open the project in your editor](#open-the-project-in-your-editor-optional). + +## Use a shell + +### Launch a shell + +The Shell kit starts a Bash shell without an agent. + +1. Open [Docker Agentic Platform](https://agentic-platform.docker.com/) and + select **+ New sandbox**. +2. Open the kit picker and choose **shell**. +3. If saved secrets or a GitHub token are selected, deselect them for this + walkthrough. You don't need MCP tools either. +4. In the network policy picker, select **Balanced** to permit access to + GitHub, Docker Hub, and npm. Keep the compute and timer defaults and select + **Run**. + +If you use a custom network policy, make sure it permits GitHub, Docker Hub, +and npm. See [Network policies](policies.md). + +When the sandbox is ready, its terminal opens with a Bash shell. + +### Build and run an application + +Your local files aren't mounted in a cloud sandbox. In the browser terminal, +clone a public sample project: + +```console +$ git clone https://github.com/docker/welcome-to-docker.git project +$ cd project +``` + +The Shell kit includes Docker Engine. Build the application's container image: + +```console +$ docker build -t welcome-to-docker . +``` + +The build installs the application's dependencies and compiles it inside the +sandbox. When it finishes, start a container and publish its port: + +```console +$ docker run -d --name welcome-to-docker -p 3000:3000 welcome-to-docker +``` + +### Preview the application + +1. Select **Connect** on the sandbox's detail page. +2. Under **Connect via a Port**, enter `3000` and select **Open Port**. +3. Open the generated URL in your browser. + +You should see the Welcome to Docker application. The application runs in the +cloud sandbox, so you can try it without installing Docker or Node.js on your +computer. + +The generated URL is public. Close the port in **Connect** when you've finished +previewing the application. + +Continue to [keep your work](#keep-your-work), or +[open the project in your editor](#open-the-project-in-your-editor-optional). + +## Keep your work + +The cloned project and any files you create are stored in the sandbox. Files +don't sync automatically with your computer or a remote repository. They remain available +when you pause and resume the sandbox, but are lost when you delete it. + +To keep files outside the sandbox, use the CLI to +[transfer files](/manuals/ai/sandboxes/cloud/usage.md#transfer-files), or commit +and push changes to a repository. Include a +[GitHub credential](secrets.md#github-credential) when launching a sandbox that +needs to push changes. + +## Open the project in your editor (optional) + +Open the project in VS Code or Cursor over SSH to edit the application. Your +editor runs on your computer, while the files and terminal commands stay in +the cloud sandbox. + +1. Install the [Docker Sandboxes CLI](/manuals/ai/sandboxes/install.md), + version 0.45.0 or later. +2. In a terminal on your computer, sign in with the same Docker account you + used in the Console and configure cloud SSH access: + + ```console + $ sbx login + $ sbx --cloud setup ssh + $ sbx --cloud ls + ``` + +3. Find your sandbox in the list and copy its `sbx_`-prefixed ID. Test the + connection, replacing `<SANDBOX_ID>` with that ID: + + ```console + $ ssh <SANDBOX_ID>@sbx_cloud + ``` + + A successful connection opens a shell inside the cloud sandbox. Run `exit` + to return to your computer's terminal. +4. In VS Code, install the + [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh). + In Cursor, install its Remote - SSH support. +5. Open your editor's Command Palette and run **Remote-SSH: Connect to Host**. + Enter `<SANDBOX_ID>@sbx_cloud`, using the same ID as in the SSH command. +6. Open `/home/agent/workspace` in the remote window. Both workflows clone + the application into `project`. The coding agent also saves `review.md` + in the workspace. + +The first connection installs the editor's server inside the sandbox. + +If you followed the coding agent workflow, download the review run this command in a terminal on your computer: + +```console +$ sbx --cloud cp <SANDBOX_ID>:/home/agent/workspace/review.md ./review.md +``` + +## Pause, keep running, or delete the sandbox + +Closing the browser or disconnecting your editor leaves the sandbox running. +Commands and background processes can continue until you pause or delete the +sandbox, or its timer expires. Compute is billed while the sandbox runs, even +when no commands are running. + +Return to **Sandboxes** in the Console and choose what to do next: + +- Pause the sandbox to stop compute charges and keep its files. Confirm that + it is paused in the list. To continue later, reopen the sandbox and resume + it. Resuming starts a fresh timer with the original duration. +- Leave it running if the agent still has work to do or to keep the application available. Check the expiration + time: the default **Stop** action stops the sandbox after one hour, including + background processes, and keeps its files. +- Delete it when you no longer need it. Push any source changes + you want to keep first. Deletion removes files stored only in the sandbox. + +For more detail, see [Lifecycle actions](sandboxes.md#manage-the-lifecycle). +To run a task from your own terminal, follow the +[cloud CLI walkthrough](/manuals/ai/sandboxes/cloud/_index.md#get-started). +For programmatic workflows, see the +[Sandboxes API quickstart](/manuals/ai/sandboxes-api/get-started.md). + +## Sandbox options + +After launch, you can't change the selected credentials, tools, network policies, +or compute size. Configure these options before selecting **Run**: + +| Option | What to choose | +| --- | --- | +| Agent credentials | Add the API keys or tokens your kit needs. Saved credentials are reused by default; deselect optional credentials you don't want to include. See [Secrets](secrets.md). | +| GitHub token | Provide a token for Copilot or for cloning private repositories and pushing changes. Copilot uses the same token for both. Repository access is optional for other agents. See [GitHub credential](secrets.md#github-credential). | +| Network policies | Review the hosts and services the sandbox can reach. See [Network policies](policies.md). | +| MCP tools | Choose the servers your agent can use and authorize them if prompted. See [MCP](mcp.md). | +| Compute and platform | Choose CPU and memory resources. Under **Platform**, use **auto** or a platform supported by the kit's image. See [Sandbox platforms](sandboxes.md#choose-a-platform). | +| Timer | Under **Run for**, choose 1 to 24 hours. Under **When the time is up**, choose **Stop**, **Delete**, or **Restart** if offered. See [Lifecycle actions](sandboxes.md#manage-the-lifecycle). | + +The launcher remembers your policy selections from the previous launch in the +same browser. Policies marked **Always applied** are selected automatically. +Review the selected policies before launching. Selecting **Balanced** alongside +**Open** doesn't restrict Open's access; see [How policies combine](policies.md#how-policies-combine). diff --git a/content/manuals/agentic-platform/kits.md b/content/manuals/agentic-platform/kits.md new file mode 100644 index 000000000000..dac324a10ba0 --- /dev/null +++ b/content/manuals/agentic-platform/kits.md @@ -0,0 +1,77 @@ +--- +title: Kits +description: Browse sandbox kits, check kit formats and Docker Hub details, or launch a public kit in Docker Agentic Platform. +keywords: docker agentic platform, kits, community kits, custom kits, docker hub, sandboxes +weight: 15 +aliases: + - /agentic-platform/concepts/kits/ + - /agentic-platform/guides/manage-kits/ +--- + +A kit defines a sandbox's base image, agent, setup, network rules, and the +credentials it can use. Choose a kit from the **Kits** catalog or enter a public +kit reference to run an agent in Docker Agentic Platform. + +Launching a kit from the Console requires both the kit and its base image to +be public. To run a kit from a private Docker Hub repository, use the Docker +Sandboxes CLI. The **Kits** page provides the command to copy. + +## Browse and run a kit + +Kits curated by Docker include agents such as Claude Code, Codex, Antigravity, +and Hermes, as well as a Shell kit for working without a pre-installed agent. + +Use the format badge to identify [v2 kits](/manuals/ai/sandboxes/customize/kits-v2.md) +or [v3 kits](/manuals/ai/sandboxes/customize/_index.md). +When available, Docker Hub details include the publisher, pull and star counts, +last update, architectures, and a security attestations indicator. + +1. Open **Kits** in the Console. +2. Search by name or description. +3. Select **Run** on a kit to open the sandbox launcher with that kit selected. +4. Review its credentials, network policies, tools, compute size, and + timer, then select **Run** in the launcher to create the sandbox. + +Use a kit's Hub link to open its repository on Docker Hub. For the launch steps, +see [Get started](get-started.md#start-a-sandbox). + +## Run a kit by reference + +To use a public kit that you already know: + +1. Open **New** and open the kit picker. +2. Select **add a public kit**. +3. Enter the kit's registry reference, such as `myorg/my-kit:1.0`. You can omit + the `docker.io/` prefix for Docker Hub references. +4. Wait for the kit's name and supported credentials to appear. If you see an + error, check the reference and confirm that the kit is public. +5. Configure the sandbox and select **Run**. + +Enter a reference to a sandbox kit. You can't launch a sandbox from a container +image reference or a mixin kit. Mixins add capabilities to other kits, and the +Console doesn't support combining kits. + +The credentials available in the launcher depend on the kit. A custom kit must +declare the credentials it needs, including GitHub credentials for private +repository access. See [Secrets](secrets.md). + +## Kit size limits + +Custom kits can contain up to 64 MiB of registry content, measured as the total +size of the config blob and compressed layers declared in the kit manifest. +The kit's file payload must also fit within 256 MiB when loaded for launch. +These limits apply to the kit artifact, not its referenced base image. + +If the launcher reports "That kit is larger than this platform accepts", the +reference exceeds the 64 MiB limit. Check that the reference points to a +sandbox kit rather than a container image. Put large dependencies in the +base image and keep the kit's bundled files small. + +## Create your own kit + +To ask your coding agent to help create a kit, copy the prompt from **Kits** and +paste it into your agent. Follow the **Kit authoring docs** link for instructions, +or see [Kit authoring](/manuals/ai/sandboxes/customize/author/_index.md). + +After publishing the kit to a public registry, enter its reference in the +launcher. Its base image must also be public. diff --git a/content/manuals/agentic-platform/mcp.md b/content/manuals/agentic-platform/mcp.md new file mode 100644 index 000000000000..ffe064cc1dd1 --- /dev/null +++ b/content/manuals/agentic-platform/mcp.md @@ -0,0 +1,45 @@ +--- +title: MCP +description: Connect predefined and custom MCP servers for Docker Agentic Platform sandboxes. +keywords: docker agentic platform, mcp servers, mcp tools, authorization, remote url +weight: 30 +aliases: + - /agentic-platform/concepts/mcp-tools/ + - /agentic-platform/guides/configure-mcp-tools/ +--- + +Connect Model Context Protocol (MCP) servers to give your agent tools for +working with external services. From **MCP**, choose a predefined server or +add a custom server by URL. Authorize access if prompted. + +You can also select or connect servers from the tools control in the sandbox +launcher. Select a server to use it in the sandbox, and authorize access if +prompted. To connect a custom server there, enter its URL and +select **Connect**. + +Connecting an MCP server doesn't restrict or inspect the sandbox's other +network traffic. To control which hosts and services the sandbox can reach, +use [network policies](/manuals/agentic-platform/policies.md). The initial +release doesn't support MCP-specific policies. + +## Connect a predefined server + +1. Open **MCP** and choose a predefined server. +2. Connect the server. +3. Authorize access if prompted. + +## Add a server by URL + +To connect a server that is not predefined: + +1. Open **MCP**. +2. Choose the option to add a server and enter its URL. +3. Connect the server and authorize access if prompted. + +## Use tools from another client + +On the **MCP** page, use **MCP Gateway endpoint URL** to connect your external +MCP client to the gateway. Select **Add to your client**, choose your +client, and follow the connection and authorization instructions. Supported +options include VS Code and Codex CLI. The VS Code instructions include an +install link and a manual configuration example. diff --git a/content/manuals/agentic-platform/policies.md b/content/manuals/agentic-platform/policies.md new file mode 100644 index 000000000000..065f28c33640 --- /dev/null +++ b/content/manuals/agentic-platform/policies.md @@ -0,0 +1,97 @@ +--- +title: Network policies +linkTitle: Policies +description: Control outbound network access from Docker Agentic Platform sandboxes. +keywords: docker agentic platform, network policies, network access, allow rules, deny rules +weight: 50 +aliases: + - /agentic-platform/concepts/policies/ + - /agentic-platform/guides/create-and-apply-policies/ +--- + +Use network policies to control which hosts and services your sandbox can +reach. For tools and authentication, configure [MCP](mcp.md) and +[Secrets](secrets.md) separately. + +There are two types of network policy: + +- Kit policies are the read-only network rules defined by the selected kit. + They apply automatically when you create a sandbox, including when you use a + custom kit. Review curated kit rules under **Kit policies** on the + **Policies** page. The launcher's policy picker also shows the selected kit's + policy when the kit includes network rules. +- User policies are policies that you can select when you create a sandbox. + Choose the read-only **Open** or **Balanced** presets, or create a custom + policy. **Open** allows outbound access to any host. **Balanced** allows + access to a curated set of hosts and services. + +## Select policies for a sandbox + +The launcher remembers your policy selections from the previous launch in the +same browser. Without saved selections, it selects the account's policies +marked **Always applied**. These policies can't be deselected in the launcher. +You can select zero, one, or several additional user policies. By default, +**Open** is marked **Always applied**, unlike local sandboxes where you choose a +network preset. + +## How policies combine + +Allow rules from all applicable user policies and the kit are combined. A +destination allowed by any of these rules is permitted unless an explicit +deny rule blocks it. Deny rules take precedence over allow rules. + +For example, selecting both **Open** and **Balanced** permits all outbound +destinations except those explicitly denied. Open's `**` rule already allows +all destinations, so Balanced's allow list doesn't narrow access. To restrict +access with an allow list, deselect **Open** if it is selected and can be +removed, and review the allow rules in the remaining policies and kit. + +If the combined allow list contains any rules, destinations outside that list +are blocked. This default behavior isn't an explicit deny rule: adding an +allow rule in another policy permits the matching destinations. If the +combined allow list is empty or absent, the sandbox can reach any destination +except those blocked by deny rules. + +## Policy rules + +Policy rules allow or deny network destinations. Use the following hostname +patterns: + +| Pattern | Example | Matches | +| --------------------- | ----------------- | -------------------------------------------------- | +| Exact hostname | `example.com` | `example.com` only, not subdomains | +| Single-level wildcard | `*.example.com` | One subdomain level, such as `api.example.com` | +| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` | +| Hostname with port | `example.com:443` | `example.com` on port 443 only | + +`example.com` does not match subdomains, and `*.example.com` does not match the +root domain. Add each pattern required by your destinations. + +You can also match IPv4 and IPv6 CIDR ranges, such as `10.0.0.0/8`, +`192.168.1.0/24`, and `2001:db8::/32`. + +Include the hosts your agent needs both during setup and while it runs, such +as source control services, package registries, and model providers. + +## Create a policy + +1. Open **Policies** and select **New policy**. +2. Give the policy a name that describes what it's for. +3. Add allow and deny rules for the required destinations. +4. Review the rules and save the policy. + +To apply the policy, select it under **Egress policy for this sandbox** when you +create a sandbox. + +You can edit, copy, or delete a custom policy. You can't edit or delete the +built-in presets or kit policies. + +## Understand blocked access + +If a policy blocks a service, your agent or tool might report an HTTP 403 +response, a connection failure, or another service error. Check the error +message for the host it tried to reach. + +Check that your allow rules cover the host and port, along with any supporting +APIs the service needs. Add the narrowest rule that permits the required +access. Use **Open** if your task needs broad outbound access. diff --git a/content/manuals/agentic-platform/release-notes.md b/content/manuals/agentic-platform/release-notes.md new file mode 100644 index 000000000000..1c22c340215e --- /dev/null +++ b/content/manuals/agentic-platform/release-notes.md @@ -0,0 +1,74 @@ +--- +title: Docker Agentic Platform release notes +linkTitle: Release notes +description: Review feature updates, behavior changes, and fixes in Docker Agentic Platform. +keywords: docker agentic platform, release notes, updates, fixes +weight: 90 +--- + +## September 24, 2026 + +This marks the experimental public release of Docker Agentic Platform. +Features and behavior may change. To begin, [activate your subscription](signup.md). + +- Added a **Kits** catalog with search, kit format badges, Docker Hub details + when available, and links to Docker Hub. Selecting **Run** opens the sandbox + launcher with the kit selected. +- Added public kit references in the launcher. Both the kit and its base image + must be public. +- Added Hermes and Antigravity as curated kits. Hermes uses Anthropic or + OpenAI credentials; Antigravity uses a Google credential. +- Updated the launcher with separate credential and GitHub controls. The + launcher reuses saved keys and tokens that the kit supports without requiring + you to select them again. Optional credentials can be deselected. +- Added an agent prompt and authoring documentation link on **Kits**, and a + compact **Recent sandboxes** list on **New**. +- Added custom secrets for services outside the built-in provider list. +- Added platform selection and a **Restart** timer action for accounts with + these controls enabled. Resuming a sandbox starts a fresh lifecycle timer. +- Added support for multiple shell tabs and port publishing from the + **Connect** panel. +- Added a VS Code install link and Codex CLI support in **Add to your client**. +- Fixed always-applied policies to stay selected in the launcher. +- Improved sandbox quota errors with guidance on stopping or deleting + sandboxes to free capacity. +- Updated sandbox creation to show provisioning progress and resume tracking + after a page reload. + +## September 14, 2026 + +- Added image attachments in Claude Code sandboxes. Paste or drop an image + into the terminal to include it in your prompt. + +## September 1, 2026 + +- Added options to save and select credentials in the sandbox launcher. + +## August 28, 2026 + +- Fixed **Usage & billing** to show the active billing cycle and accrued + compute costs for plans that renew mid-month. + +## August 27, 2026 + +- Added Groq and xAI credentials under **Secrets** for OpenCode sandboxes. + +## August 26, 2026 + +Run agents and tools in isolated cloud sandboxes with Docker Agentic Platform. + +The initial release includes: + +- Predefined sandbox types for Claude Code, Codex, OpenCode, Copilot, and + Gemini CLI +- A terminal for working with your agent or shell +- Pause, resume, and delete controls for sandboxes +- Automatic sandbox stop or deletion after a timer from 1 to 24 hours +- Options to connect and authorize predefined MCP servers or add custom + servers by URL +- API keys and tokens saved under **Secrets**, with their values kept outside + sandboxes +- Network policies combining read-only kit rules with the read-only **Open** + and **Balanced** presets or custom user policies. Deny rules take precedence + over allow rules. +- A choice of compute sizes, billed by the second while the sandbox runs diff --git a/content/manuals/agentic-platform/sandboxes.md b/content/manuals/agentic-platform/sandboxes.md new file mode 100644 index 000000000000..4cb220f9a6d0 --- /dev/null +++ b/content/manuals/agentic-platform/sandboxes.md @@ -0,0 +1,149 @@ +--- +title: Sandboxes +description: Create and manage cloud sandboxes in Docker Agentic Platform. +keywords: docker agentic platform, sandboxes, agents, cloud runtime, terminal, compute +weight: 20 +aliases: + - /agentic-platform/concepts/sandboxes/ + - /agentic-platform/guides/manage-sandboxes/ +--- + +A sandbox is an isolated environment for running agents and tools in the cloud. +You can work with your agent through a terminal in the Console. + +The [kit](kits.md) you select determines the sandbox's base image, agent, and +installed tools. Each sandbox has its own filesystem, network settings, and +terminal. Choose a compute size to set how much CPU and +memory your sandbox has. Check your kit for installed tools such as Docker +Engine. For example, the Hermes kit doesn't include it. + +The Shell kit opens a Bash shell without a pre-installed agent. It uses the +same environment as [`sbx run shell`](/manuals/ai/sandboxes/agents/shell.md) +and is useful for working manually or installing your own agent. + +Your sandbox keeps running when you leave the Console. It runs until you pause +or delete it. When its timer expires, it performs the action you selected. + +## Choose a platform + +In the compute picker, under **Platform**, choose **auto**, **linux/amd64** +(Intel/AMD), or **linux/arm64** (Arm). The default, **auto**, uses the platform +provided by the kit's image. An explicit platform choice requires the image +to support that platform; otherwise, creation fails. + +## Source code and files + +Each sandbox starts with a fresh filesystem. Your local repositories, +directories, and workspaces aren't mounted in it by default. + +Files don't sync automatically with your computer or a remote repository. +Commit and push any work you want to keep before deleting the sandbox. Files +left only in a deleted sandbox won't be available in a later sandbox. + +Use GitHub to clone source code into your sandbox and save changes remotely. +To clone a private repository or push changes, use the **GitHub token** +control in the launcher. Copilot uses this token for both the agent and GitHub +repository access. A custom kit must declare a GitHub credential to offer this +option. +Make sure your token has the required repository permissions. You can clone +public repositories without a token, but pushing to them still requires +authentication. + +## Open a sandbox + +After you select **Run**, the Console shows provisioning progress. When the +sandbox is ready, its detail page opens. Use the terminal to work with your +agent or shell. Reloading the launch page resumes tracking the launch. + +Open **Sandboxes** to review each sandbox's name, type, status, hourly rate, +expiration, and age. Select a sandbox to reopen its detail page and terminal. + +The **New** page also lists **Recent sandboxes**. Select a sandbox to reopen it, +or select **See all sandboxes** to open the full list. + +In a Claude Code sandbox, paste an image from your clipboard or drag an image +file onto the terminal to attach it to your prompt. Wait for the upload to +finish, type your question, and press Enter to send it. + +## Open additional shells + +Use the **+** button in the terminal tab bar to open another shell in the same +sandbox. Switch tabs to work with multiple shells. The agent remains in its +own tab while you run commands in another. + +## Connect from your computer + +If the sandbox detail page shows **Connect**, open it to find SSH connection +options. The panel includes a Docker Sandboxes CLI option and a connect script. +For the script, manage your public SSH key under **Settings**. Follow the +instructions in the panel for your chosen connection method. + +### Access a service by port + +To access a web application or development server running in your sandbox: + +1. Start the service in the sandbox and note its port. +2. Open **Connect** and find **Connect via a Port**. +3. Enter the port and select **Open Port**. +4. Copy the public URL to access the service. + +The sandbox must be running. Port 2222 is reserved for SSH and can't be +published through this control. To stop exposing a service, use the close +action next to its port. + +## Pause, resume, or delete a sandbox {#manage-the-lifecycle} + +A sandbox can be running or paused: + +- Pause a running sandbox to stop it without deleting its files. +- Resume a paused sandbox to continue working with it. Resuming starts a fresh + timer with the original duration. +- Delete a sandbox when you no longer need it. + +When you create a sandbox, set a timer from 1 to 24 hours and choose +what happens when it expires. **Stop** stops the sandbox, while **Delete** +deletes the sandbox and its files. If **Restart** is offered, select it to +restart the sandbox automatically when the timer expires. When a sandbox stops, +all processes inside it stop too, including background processes. + +After launch, you can't change the selected credentials, tools, network +policies, or compute size. + +You pay for compute by the second while your sandbox runs. Your model provider +bills inference separately. For account, usage, and payment information, see +[Docker Billing](/subscription-billing/). + +## Account quotas + +The following default quotas apply across your cloud sandbox account, whether +resources are created through the Console, CLI, or API: + +| Resource | Default limit | +| --- | ---: | +| Concurrent sandboxes | 10 | +| Stored sandboxes | 50 | +| Volumes | 100 | +| Secrets | 100 | +| Images being prepared at the same time | 3 | + +Your account can have different quotas. Confirm your account's limits with +Docker before planning a workload that depends on a particular allowance. + +Stopping an ordinary sandbox releases its concurrency slot, but the sandbox +still counts toward stored usage. Resuming it needs a concurrency slot. An +always-on sandbox retains its concurrency reservation while stopped. Delete +sandboxes you no longer need to release stored usage. + +If the Console reports a running sandbox limit, stop or delete a sandbox +before trying again. If it reports a sandbox storage limit, delete a sandbox; +stopping it doesn't free a stored-sandbox slot. + +## Check sandbox configuration + +If your agent cannot reach a service or use a tool: + +- Check that the network policies allow access to the service. +- If the sandbox needs an MCP tool, confirm that its server is connected and + authorized. +- If the service requires authentication, check that its credential was + included when you created the sandbox. diff --git a/content/manuals/agentic-platform/secrets.md b/content/manuals/agentic-platform/secrets.md new file mode 100644 index 000000000000..0a6186f474fc --- /dev/null +++ b/content/manuals/agentic-platform/secrets.md @@ -0,0 +1,100 @@ +--- +title: Secrets +description: Save and manage API keys and tokens for your Docker Agentic Platform sandboxes. +keywords: docker agentic platform, secrets, api keys, service credentials, proxy +weight: 40 +aliases: + - /agentic-platform/concepts/secrets/ + - /agentic-platform/guides/manage-secrets/ +--- + +Save API keys and tokens under **Secrets** so your agents can use external +services without reading the credentials themselves. The values stay outside +the sandbox. + +You can save credentials for the following services: + +| Service | Secret ID | Used by | +| ------------- | ------------------- | ------------------------------------------------- | +| Anthropic | `ANTHROPIC_API_KEY` | Claude Code, OpenCode, and Hermes with Anthropic models | +| OpenAI | `OPENAI_API_KEY` | Codex, OpenCode, and Hermes with OpenAI models | +| Google | `GEMINI_API_KEY` | Gemini CLI, Antigravity, and OpenCode with Google models | +| Groq | `GROQ_API_KEY` | OpenCode with Groq models | +| xAI | `XAI_API_KEY` | OpenCode with xAI models | +| GitHub | `GITHUB_TOKEN` | Copilot and kits that support GitHub access | + +Each kit supports a particular set of credentials. For example, a Codex +sandbox doesn't use your Anthropic key. OpenCode supports all the listed model +providers. Hermes needs at least one Anthropic or OpenAI key. The built-in +provider list doesn't include OpenRouter. + +For custom kits, the launcher shows the supported credentials listed in the +kit's definition. + +## GitHub credential + +Use `GITHUB_TOKEN` for Copilot and for cloning private repositories or pushing +changes to GitHub. The token you enter in the launcher is also saved under +**Secrets**. All curated kits offer this option. Custom kits must declare a +GitHub credential to use it. + +For Copilot, the token you provide to run the agent also authenticates GitHub +repository access. You don't need to provide a separate token. + +## Configure a secret + +To configure a credential before launching a sandbox: + +1. Open **Secrets** and find the service. +2. Select the edit icon for that service. +3. Enter its API key or token and save the value. + +You can also add or edit credentials from **New** when you launch a sandbox. +For a single provider credential, select its prompt to enter the value inline. +For multiple provider credentials, open the provider control to add or edit +values in its panel. Use the **GitHub token** control for Copilot and GitHub +repository access. + +By default, the launcher includes saved API keys and tokens that the kit +supports. You don't need to enter them again. You can deselect optional +credentials to exclude them from a sandbox. Required credentials stay selected. +For kits that need one of several providers, keep at least one available +provider credential selected. + +If you add a missing key or token in the launcher, it is included without a +separate selection step. If a required credential is missing when you select +**Run**, the launcher opens the missing credential's input so you can add it. + +## Add a custom secret + +Use a custom secret for a service outside the built-in provider list. + +1. Open **Secrets** and select **New secret** in the **Custom** section. +2. Enter the hosts that may receive the credential. +3. Set the request header and value format, such as `Authorization` and + `Bearer %s`, then enter the secret value. +4. Optionally, set an environment variable name for the credential. +5. Name the secret and save it. + +Expand the secret's row to copy its generated placeholder. Use that placeholder +where your client expects a credential. The sandbox proxy substitutes the real +value only for requests to the configured hosts. The value stays outside the +sandbox. + +The launcher includes all your custom secrets when you create a sandbox. To +edit a custom secret, enter its value again; saved values can't be retrieved. +You can also remove custom secrets from the **Custom** section. + +## Manage secrets + +The **Secrets** page shows each secret ID and the sandboxes that use it. Select +the copy icon to copy the secret ID, or select the edit icon to change the +stored value. + +Agents see a secret ID instead of the actual key or token. For requests that +match the secret's configured service, the sandbox proxy substitutes the real +value. It doesn't expose that value inside the sandbox or send it to other +services. + +Do not put API keys or tokens in prompts or files inside the sandbox. Rotate or +revoke a credential at its provider when it is no longer needed. diff --git a/content/manuals/agentic-platform/signup.md b/content/manuals/agentic-platform/signup.md new file mode 100644 index 000000000000..15f8e6b32276 --- /dev/null +++ b/content/manuals/agentic-platform/signup.md @@ -0,0 +1,64 @@ +--- +title: Sign up for Docker Agentic Platform +linkTitle: Sign up +description: Activate Docker Agentic Platform access for the Console, cloud sandbox CLI, and API or SDKs. +keywords: docker agentic platform, cloud sandboxes, signup, billing, subscription, account access +weight: 5 +--- + +> [!NOTE] +> Docker Agentic Platform is experimental. Features and behavior may change. + +To use Docker Agentic Platform or run cloud sandboxes through the CLI, API, or +SDKs, activate a Docker Agentic Platform pay-as-you-go subscription. The same +subscription provides cloud access for all these interfaces. + +## Before you begin + +Subscribe using your personal Docker account. You can use this account even +if you belong to an organization. The Docker Agentic Platform subscription +is attached to your personal account and billed separately from your Docker +subscription. Review the [billing details](#billing) before subscribing. + +## Activate cloud access + +1. Open the [Docker Agentic Platform Console](https://agentic-platform.docker.com/) + and sign in with the Docker account you want to use for cloud sandboxes. +2. If your account doesn't have access, follow the redirect to Docker Billing. + Review the Docker Agentic Platform pay-as-you-go plan, provide the requested + billing and payment details, and complete checkout. + + If you see **Docker Agentic Platform access required** instead of a redirect, + select **Go to Docker Billing** to subscribe. +3. Return to the Console after checkout. If your account already has an active + subscription, you can skip checkout. + +To create a sandbox in the Console, follow [Get started](get-started.md). +Use the same Docker account for CLI sign-in or API authentication that you +used to subscribe. +Agent credentials are configured separately from subscription activation; +follow your interface's instructions to set them up. + +## Check account access + +If the Console, CLI, or API reports that your account doesn't have access, +confirm that checkout completed and that you're using the account with the +active subscription. You can review the plan in Docker Home under +**Billing** > **Active subscriptions** > **Docker Agentic Platform**. + +## Billing + +Cloud sandboxes use pay-as-you-go compute with no recurring subscription fee. +Docker meters compute in seconds, based on sandbox runtime and the CPU and +memory configuration. Your model provider bills inference separately. + +Open [Usage & billing](https://agentic-platform.docker.com/usage) in the Console +to review pricing, usage, and available credits. Compute credits offset +eligible cloud compute usage; they don't cover model-provider charges. + +Billing is monthly, on the day you subscribed. Your invoice reflects usage +accrued during the previous billing period. Stop or delete sandboxes you no +longer need. + +For instructions on reviewing your plan, billing dates, and cancellation, see +[Docker Agentic Platform plans](/manuals/subscription-billing/plans/docker-agentic-platform.md). diff --git a/content/manuals/ai-overview.md b/content/manuals/ai-overview.md index 9597a324a683..e064b00ccb41 100644 --- a/content/manuals/ai-overview.md +++ b/content/manuals/ai-overview.md @@ -3,7 +3,7 @@ title: Docker AI overview linkTitle: Overview description: Docker's AI tools help you build, run, and manage AI-powered applications and workflows. weight: 1 -keywords: docker, ai, gordon, docker agent, sandboxes, model runner, mcp +keywords: docker, ai, gordon, docker agent, sandboxes, agentic platform, model runner, mcp params: sidebar: group: AI and agents @@ -14,13 +14,15 @@ Each tool serves a different purpose. ## Which tool do I need? -| I want to... | Use | CLI command | +| I want to... | Use | Interface | | --------------------------------------------------------------- | -------------------------------------------------------- | ---------------- | +| Run coding agents in isolated environments | [Docker Sandboxes](./ai/sandboxes/) | `sbx` | +| Run agents in cloud sandboxes through a web Console | [Docker Agentic Platform](./agentic-platform/_index.md) (experimental) | Web Console | | Get AI help with Docker tasks (containers, images, Dockerfiles) | [Gordon](./ai/gordon/) | `docker ai` | | Run AI models locally with an OpenAI-compatible API | [Model Runner](./ai/model-runner/) | `docker model` | -| Connect AI tools to external services via MCP | [MCP Catalog and Toolkit](./ai/mcp-catalog-and-toolkit/) | `docker mcp` | +| Connect AI tools to external services via MCP | [MCP Catalog and Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md) | `docker mcp` | | Build and orchestrate custom multi-agent teams | [Docker Agent](./ai/docker-agent/) | `docker agent` | -| Run coding agents in isolated environments | [Docker Sandboxes](./ai/sandboxes/) | `docker sandbox` | +| Give my coding agent Docker best-practice guidance | [Docker Skills](./ai/skills/) | None | ## How these tools relate @@ -33,10 +35,23 @@ in YAML. You configure agents with specific roles, models, and tools, then run them from your terminal. Docker Agent is a general-purpose agent runtime, not specific to Docker tasks. -**Docker Sandboxes** provides isolated microVM environments for running coding -agents. It supports multiple agents including Claude Code, Codex, Copilot, -Gemini, and Docker Agent. Sandboxes is the isolation layer — the agents -themselves are separate tools. +**Docker Skills** are Docker's official, open-source instructions for compatible +coding agents working on Docker tasks. Install them through your agent's +supported method; they can also be used by Docker Agent and agents running in +Docker Sandboxes. Browse the [Docker Skills +catalog](https://github.com/docker/skills#readme) for current guidance. + +Docker Sandboxes provides isolated environments for running coding agents +[locally](./ai/sandboxes/get-started.md) or +[in the cloud](./ai/sandboxes/cloud/_index.md). Sandboxes is the isolation layer; +the agents themselves are separate tools. Agent configuration and supported +features differ between local and cloud sandboxes. + +Docker Agentic Platform is an experimental service for running agents in +Docker-managed cloud sandboxes. Its web Console provides kit selection, +credentials, network policies, MCP tools, and sandbox lifecycle controls. +[Activate a subscription](./agentic-platform/signup.md) to use cloud compute, +billed on a pay-as-you-go basis. **Model Runner** lets you run LLMs locally. Other tools like Docker Agent can use Model Runner as a model provider. diff --git a/content/manuals/ai/compose/_index.md b/content/manuals/ai/compose/_index.md deleted file mode 100644 index 0f2905440944..000000000000 --- a/content/manuals/ai/compose/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -build: - render: never -title: AI and Docker Compose -weight: 50 -params: - sidebar: - group: AI and agents ---- diff --git a/content/manuals/ai/docker-agent/_index.md b/content/manuals/ai/docker-agent/_index.md index 060168ad8113..8e0adc2f6ac9 100644 --- a/content/manuals/ai/docker-agent/_index.md +++ b/content/manuals/ai/docker-agent/_index.md @@ -5,6 +5,9 @@ weight: 60 aliases: - /ai/cagent/ - /manuals/ai/cagent/ + - /ai/docker-agent/integrations/ + - /ai/docker-agent/reference/ + - /ai/docker-agent/reference/examples/ params: sidebar: group: AI and agents @@ -107,7 +110,7 @@ define. Each agent: - Has its own context (agents don't share knowledge) - Can access built-in tools like todo lists, memory, and task delegation - Can use external tools via [MCP - servers](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) + servers](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) The root agent delegates tasks to agents listed under `sub_agents`. Sub-agents can have their own sub-agents for deeper hierarchies. @@ -134,7 +137,7 @@ agents: You can also configure model settings (like context limits), tools (including MCP servers), and more. See the [configuration -reference](./reference/config.md) +reference](./configuration/overview/index.md) for complete details. ## Share agent teams @@ -152,16 +155,12 @@ it doesn't exist yet. ## What's next -- Follow the [tutorial](./tutorial.md) to build your first coding agent -- Learn [best practices](./best-practices.md) for building effective agents -- Integrate Docker Agent with your [editor](./integrations/acp.md) or use agents as - [tools in MCP clients](./integrations/mcp.md) +- Follow the [quickstart](./getting-started/quickstart/index.md) to build your first agent +- Learn [best practices](./guides/tips/index.md) for building effective agents +- Integrate Docker Agent with your [editor](./features/acp/index.md) or use agents as + [tools in MCP clients](./tools/mcp/index.md) - Browse example agent configurations in the [Docker Agent repository](https://github.com/docker/docker-agent/tree/main/examples) -- Use `docker agent new` to generate agent teams with AI <!-- TODO: link to some page - where we explain this, probably a CLI reference? --> - Connect agents to external tools via the [Docker MCP - Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) -- Read the full [configuration - reference](https://github.com/docker/docker-agent?tab=readme-ov-file#-configuration-reference) - <!-- TODO: move to this site/repo --> + Gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) +- Read the full [configuration reference](./configuration/overview/index.md) diff --git a/content/manuals/ai/docker-agent/best-practices.md b/content/manuals/ai/docker-agent/best-practices.md deleted file mode 100644 index 80ffeb63dc27..000000000000 --- a/content/manuals/ai/docker-agent/best-practices.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -title: Best practices -description: Patterns and techniques for building effective agents -keywords: [docker agent, best practices, patterns, agent design, optimization] -weight: 40 ---- - -Patterns you learn from building and running agents with Docker Agent. These aren't -features or configuration options - they're approaches that work well in -practice. - -## Handling large command outputs - -Shell commands that produce large output can overflow your agent's context -window. Validation tools, test suites, and build logs often generate thousands -of lines. If you capture this output directly, it consumes all available context -and the agent fails. - -The solution: redirect output to a file, then read the file. The Read tool -automatically truncates large files to 2000 lines, and your agent can navigate -through it if needed. - -**Don't do this:** - -```yaml -reviewer: - instruction: | - Run validation: `docker buildx bake validate` - Check the output for errors. - toolsets: - - type: shell -``` - -The validation output goes directly into context. If it's large, the agent fails -with a context overflow error. - -**Do this:** - -```yaml -reviewer: - instruction: | - Run validation and save output: - `docker buildx bake validate > validation.log 2>&1` - - Read validation.log to check for errors. - The file can be large - read the first 2000 lines. - Errors usually appear at the beginning. - toolsets: - - type: filesystem - - type: shell -``` - -The output goes to a file, not context. The agent reads what it needs using the -filesystem toolset. - -## Structuring agent teams - -A single agent handling multiple responsibilities makes instructions complex and -behavior unpredictable. Breaking work across specialized agents produces better -results. - -The coordinator pattern works well: a root agent understands the overall task -and delegates to specialists. Each specialist focuses on one thing. - -**Example: Documentation writing team** - -```yaml -agents: - root: - description: Technical writing coordinator - instruction: | - Coordinate documentation work: - 1. Delegate to writer for content creation - 2. Delegate to editor for formatting polish - 3. Delegate to reviewer for validation - 4. Loop back through editor if reviewer finds issues - sub_agents: [writer, editor, reviewer] - toolsets: [filesystem, todo] - - writer: - description: Creates and edits documentation content - instruction: | - Write clear, practical documentation. - Focus on content quality - the editor handles formatting. - toolsets: [filesystem, think] - - editor: - description: Polishes formatting and style - instruction: | - Fix formatting issues, wrap lines, run prettier. - Remove AI-isms and polish style. - Don't change meaning or add content. - toolsets: [filesystem, shell] - - reviewer: - description: Runs validation tools - instruction: | - Run validation suite, report failures. - toolsets: [filesystem, shell] -``` - -Each agent has clear responsibilities. The writer doesn't worry about line -wrapping. The editor doesn't generate content. The reviewer just runs tools. - -This example uses `sub_agents` where root delegates discrete tasks and gets -results back. The root agent maintains control and coordinates all work. For -different coordination patterns where agents should transfer control to each -other, see the `handoffs` mechanism in the [configuration -reference](./reference/config.md#task-delegation-versus-conversation-handoff). - -**When to use teams:** - -- Multiple distinct steps in your workflow -- Different skills required (writing ↔ editing ↔ testing) -- One step might need to retry based on later feedback - -**When to use a single agent:** - -- Simple, focused tasks -- All work happens in one step -- Adding coordination overhead doesn't help - -## Optimizing RAG performance - -RAG indexing takes time when you have many files. A configuration that indexes -your entire codebase might take minutes to start. Optimize for what your agent -actually needs. - -**Narrow the scope:** - -Don't index everything. Index what's relevant for the agent's work. - -```yaml -# Too broad - indexes entire codebase -rag: - codebase: - docs: [./] - -# Better - indexes only relevant directories -rag: - codebase: - docs: [./src/api, ./docs, ./examples] -``` - -If your agent only works with API code, don't index tests, vendor directories, -or generated files. - -**Increase batching and concurrency:** - -Process more chunks per API call and make parallel requests. - -```yaml -strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - batch_size: 50 # More chunks per API call - max_embedding_concurrency: 10 # Parallel requests - chunking: - size: 2000 # Larger chunks = fewer total chunks - overlap: 150 -``` - -This reduces both API calls and indexing time. - -**Consider BM25 for fast local search:** - -If you need exact term matching (function names, error messages, identifiers), -BM25 is fast and runs locally without API calls. - -```yaml -strategies: - - type: bm25 - database: ./bm25.db - chunking: - size: 1500 -``` - -Combine with embeddings using hybrid retrieval when you need both semantic -understanding and exact matching. - -## Preserving document scope - -When building agents that update documentation, a common problem: the agent -transforms minimal guides into tutorials. It adds prerequisites, -troubleshooting, best practices, examples, and detailed explanations to -everything. - -These additions might individually be good, but they change the document's -character. A focused 90-line how-to becomes a 200-line reference. - -**Build this into instructions:** - -```yaml -writer: - instruction: | - When updating documentation: - - 1. Understand the current document's scope and length - 2. Match that character - don't transform minimal guides into tutorials - 3. Add only what's genuinely missing - 4. Value brevity - not every topic needs comprehensive coverage - - Good additions fill gaps. Bad additions change the document's character. - When in doubt, add less rather than more. -``` - -Tell your agents explicitly to preserve the existing document's scope. Without -this guidance, they default to being comprehensive. - -## Model selection - -Choose models based on the agent's role and complexity. - -**Use larger models (Sonnet, GPT-5) for:** - -- Complex reasoning and planning -- Writing and editing content -- Coordinating multiple agents -- Tasks requiring judgment and creativity - -**Use smaller models (Haiku, GPT-5 Mini) for:** - -- Running validation tools -- Simple structured tasks -- Reading logs and reporting errors -- High-volume, low-complexity work - -Example from the documentation writing team: - -```yaml -agents: - root: - model: anthropic/claude-sonnet-4-5 # Complex coordination - writer: - model: anthropic/claude-sonnet-4-5 # Creative content work - editor: - model: anthropic/claude-sonnet-4-5 # Judgment about style - reviewer: - model: anthropic/claude-haiku-4-5 # Just runs validation -``` - -The reviewer uses Haiku because it runs commands and checks for errors. No -complex reasoning needed, and Haiku is faster and cheaper. - -## What's next - -- Review [configuration reference](./reference/config.md) for all available - options -- Check [toolsets reference](./reference/toolsets.md) to understand what tools - agents can use -- See [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) for - complete working agents -- Read the [RAG guide](./rag.md) for detailed retrieval optimization diff --git a/content/manuals/ai/docker-agent/evals.md b/content/manuals/ai/docker-agent/evals.md deleted file mode 100644 index 3eeda1ab736d..000000000000 --- a/content/manuals/ai/docker-agent/evals.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Evals -description: Test your agents with saved conversations -keywords: [docker agent, evaluations, testing, evals] -weight: 80 ---- - -Evaluations (evals) help you track how your agent's behavior changes over time. -When you save a conversation as an eval, you can replay it later to see if the -agent responds differently. Evals measure consistency, not correctness - they -tell you if behavior changed, not whether it's right or wrong. - -## What are evals - -An eval is a saved conversation you can replay. When you run evals, Docker Agent -replays the user messages and compares the new responses against the original -saved conversation. High scores mean the agent behaved similarly; low scores -mean behavior changed. - -What you do with that information depends on why you saved the conversation. -You might save successful conversations to catch regressions, or save failure -cases to document known issues and track whether they improve. - -## Common workflows - -How you use evals depends on what you're trying to accomplish: - -Regression testing: Save conversations where your agent performs well. When you -make changes later (upgrade models, update prompts, refactor code), run the -evals. High scores mean behavior stayed consistent, which is usually what you -want. Low scores mean something changed - examine the new behavior to see if -it's still correct. - -Tracking improvements: Save conversations where your agent struggles or fails. -As you make improvements, run these evals to see how behavior evolves. Low -scores indicate the agent now behaves differently, which might mean you fixed -the issue. You'll need to manually verify the new behavior is actually better. - -Documenting edge cases: Save interesting or unusual conversations regardless of -quality. Use them to understand how your agent handles edge cases and whether -that behavior changes over time. - -Evals measure whether behavior changed. You determine if that change is good or -bad. - -## Creating an eval - -Save a conversation from an interactive session: - -```console -$ docker agent run ./agent.yaml -``` - -Have a conversation with your agent, then save it as an eval: - -```console -> /eval test-case-name -Eval saved to evals/test-case-name.json -``` - -The conversation is saved to the `evals/` directory in your current working -directory. You can organize eval files in subdirectories if needed. - -## Running evals - -Run all evals in the default directory: - -```console -$ docker agent eval ./agent.yaml -``` - -Use a custom eval directory: - -```console -$ docker agent eval ./agent.yaml ./my-evals -``` - -Run evals against an agent from a registry: - -```console -$ docker agent eval agentcatalog/myagent -``` - -Example output: - -```console -$ docker agent eval ./agent.yaml ---- 0 -First message: tell me something interesting about kil -Eval file: c7e556c5-dae5-4898-a38c-73cc8e0e6abe -Tool trajectory score: 1.000000 -Rouge-1 score: 0.447368 -Cost: 0.00 -Output tokens: 177 -``` - -## Understanding results - -For each eval, Docker Agent shows: - -- **First message** - The initial user message from the saved conversation -- **Eval file** - The UUID of the eval file being run -- **Tool trajectory score** - How similarly the agent used tools (0-1 scale, - higher is better) -- **[ROUGE-1](https://en.wikipedia.org/wiki/ROUGE_(metric)) score** - Text - similarity between responses (0-1 scale, higher is better) -- **Cost** - The cost for this eval run -- **Output tokens** - Number of tokens generated - -Higher scores mean the agent behaved more similarly to the original recorded -conversation. A score of 1.0 means identical behavior. - -### What the scores mean - -**Tool trajectory score** measures whether the agent called the same tools in -the same order as the original conversation. Lower scores might indicate the -agent found a different approach to solve the problem, which isn't necessarily -wrong but worth investigating. - -**Rouge-1 score** measures how similar the response text is to the original. -This is a heuristic measure - different wording might still be correct, so use -this as a signal rather than absolute truth. - -### Interpreting your results - -Scores close to 1.0 mean your changes maintained consistent behavior - the -agent is using the same approach and producing similar responses. This is -generally good; your changes didn't break existing functionality. - -Lower scores mean behavior changed compared to the saved conversation. This -could be a regression where the agent now performs worse, or it could be an -improvement where the agent found a better approach. - -When scores drop, examine the actual behavior to determine if it's better or -worse. The eval files are stored as JSON in your evals directory - open the -file to see the original conversation. Then test your modified agent with the -same input to compare responses. If the new response is better, save a new -conversation to replace the eval. If it's worse, you found a regression. - -The scores guide you to what changed. Your judgment determines if the change is -good or bad. - -## When to use evals - -Evals help you track behavior changes over time. They're useful for catching -regressions when you upgrade models or dependencies, documenting known failure -cases you want to fix, and understanding how edge cases evolve as you iterate. - -Evals aren't appropriate for determining which agent configuration works best - -they measure similarity to a saved conversation, not correctness. Use manual -testing to evaluate different configurations and decide which works better. - -Save conversations worth tracking. Build a collection of important workflows, -interesting edge cases, and known issues. Run your evals when making changes to -see what shifted. - -## What's next - -- Check the [CLI reference](reference/cli.md#eval) for all `docker agent eval` - options -- Learn [best practices](best-practices.md) for building effective agents -- Review [example configurations](https://github.com/docker/docker-agent/tree/main/examples) - for different agent types diff --git a/content/manuals/ai/docker-agent/images/cagent-acp-zed.avif b/content/manuals/ai/docker-agent/images/cagent-acp-zed.avif deleted file mode 100644 index 258e751effaf..000000000000 Binary files a/content/manuals/ai/docker-agent/images/cagent-acp-zed.avif and /dev/null differ diff --git a/content/manuals/ai/docker-agent/integrations/_index.md b/content/manuals/ai/docker-agent/integrations/_index.md deleted file mode 100644 index ff22ba28dac3..000000000000 --- a/content/manuals/ai/docker-agent/integrations/_index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Integrations -description: Connect agents to editors, MCP clients, and other agents -keywords: [docker agent, integration, acp, mcp, a2a, editor, protocol] -weight: 60 ---- - -Agents created with Docker Agent can integrate with different environments depending on how you -want to use them. Each integration type serves a specific purpose. - -## Integration types - -### ACP - Editor integration - -Run agents directly in your editor (Neovim, Zed). The agent sees your -editor's file context and can read and modify files through the editor's -interface. Use ACP when you want an AI coding assistant embedded in your -editor. - -See [ACP integration](./acp.md) for setup instructions. - -### MCP - Tool integration - -Expose agents as tools in MCP clients like Claude Desktop or Claude -Code. Your agents appear in the client's tool list, and the client can call -them when needed. Use MCP when you want Claude Desktop (or another MCP client) -to have access to your specialized agents. - -See [MCP integration](./mcp.md) for setup instructions. - -### A2A - Agent-to-agent communication - -Run agents as HTTP servers that other agents or systems can call using -the Agent-to-Agent protocol. Your agent becomes a service that other systems -can discover and invoke over the network. Use A2A when you want to build -multi-agent systems or expose your agent as an HTTP service. - -See [A2A integration](./a2a.md) for setup instructions. - -## Choosing the right integration - -| Feature | ACP | MCP | A2A | -| ------------- | ------------------ | ------------------ | -------------------- | -| Use case | Editor integration | Agents as tools | Agent-to-agent calls | -| Transport | stdio | stdio/SSE | HTTP | -| Discovery | Editor plugin | Server manifest | Agent card | -| Best for | Code editing | Tool integration | Multi-agent systems | -| Communication | Editor calls agent | Client calls tools | Between agents | - -Choose ACP if you want your agent embedded in your editor while you code. -Choose MCP if you want Claude Desktop (or another MCP client) to be able to -call your specialized agents as tools. Choose A2A if you're building -multi-agent systems where agents need to call each other over HTTP. diff --git a/content/manuals/ai/docker-agent/integrations/a2a.md b/content/manuals/ai/docker-agent/integrations/a2a.md deleted file mode 100644 index ca58923130db..000000000000 --- a/content/manuals/ai/docker-agent/integrations/a2a.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: A2A mode -linkTitle: A2A -description: Expose agents via the Agent-to-Agent protocol -keywords: [docker agent, a2a, agent-to-agent, multi-agent, protocol] -weight: 40 ---- - -A2A mode runs your agent as an HTTP server that other systems can call -using the Agent-to-Agent protocol. This lets you expose your agent as a service -that other agents or applications can discover and invoke over the network. - -Use A2A when you want to make your agent callable by other systems over HTTP. -For editor integration, see [ACP integration](./acp.md). For using agents as -tools in MCP clients, see [MCP integration](./mcp.md). - -## Prerequisites - -Before starting an A2A server, you need: - -- Docker Agent installed - See the [installation guide](../_index.md#installation) -- Agent configuration - A YAML file defining your agent. See the - [tutorial](../tutorial.md) -- API keys configured - If using cloud model providers (see [Model - providers](../model-providers.md)) - -## Starting an A2A server - -Basic usage: - -```console -$ docker agent serve a2a ./agent.yaml -``` - -Your agent is now accessible via HTTP. Other A2A systems can discover your -agent's capabilities and call it. - -Custom port: - -```console -$ docker agent serve a2a ./agent.yaml --port 8080 -``` - -Specific agent in a team: - -```console -$ docker agent serve a2a ./agent.yaml --agent engineer -``` - -From OCI registry: - -```console -$ docker agent serve a2a agentcatalog/pirate --port 9000 -``` - -## HTTP endpoints - -When you start an A2A server, it exposes two HTTP endpoints: - -### Agent card: `/.well-known/agent-card` - -The agent card describes your agent's capabilities: - -```console -$ curl http://localhost:8080/.well-known/agent-card -``` - -```json -{ - "name": "agent", - "description": "A helpful coding assistant", - "skills": [ - { - "id": "agent_root", - "name": "root", - "description": "A helpful coding assistant", - "tags": ["llm", "dockeragent"] - } - ], - "preferredTransport": "jsonrpc", - "url": "http://localhost:8080/invoke", - "capabilities": { - "streaming": true - }, - "version": "0.1.0" -} -``` - -### Invoke endpoint: `/invoke` - -Call your agent by sending a JSON-RPC request: - -```console -$ curl -X POST http://localhost:8080/invoke \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": "req-1", - "method": "message/send", - "params": { - "message": { - "role": "user", - "parts": [ - { - "kind": "text", - "text": "What is 2+2?" - } - ] - } - } - }' -``` - -The response includes the agent's reply: - -```json -{ - "jsonrpc": "2.0", - "id": "req-1", - "result": { - "artifacts": [ - { - "parts": [ - { - "kind": "text", - "text": "2+2 equals 4." - } - ] - } - ] - } -} -``` - -## Example: Multi-agent workflow - -Here's a concrete scenario where A2A is useful. You have two agents: - -1. A general-purpose agent that interacts with users -2. A specialized code review agent with access to your codebase - -Run the specialist as an A2A server: - -```console -$ docker agent serve a2a ./code-reviewer.yaml --port 8080 -Listening on 127.0.0.1:8080 -``` - -Configure your main agent to call it: - -```yaml -agents: - root: - model: anthropic/claude-sonnet-4-5 - instruction: You are a helpful assistant - toolsets: - - type: a2a - url: http://localhost:8080 - name: code-reviewer -``` - -Now when users ask the main agent about code quality, it can delegate to the -specialist. The main agent sees `code-reviewer` as a tool it can call, and the -specialist has access to the codebase tools it needs. - -## Calling other A2A agents - -Your agents can call remote A2A agents as tools. Configure the A2A -toolset with the remote agent's URL: - -```yaml -agents: - root: - toolsets: - - type: a2a - url: http://localhost:8080 - name: specialist -``` - -The `url` specifies where the remote agent is running, and `name` is an -optional identifier for the tool. Your agent can now delegate tasks to the -remote specialist agent. - -If the remote agent requires authentication or custom headers: - -```yaml -agents: - root: - toolsets: - - type: a2a - url: http://localhost:8080 - name: specialist - remote: - headers: - Authorization: Bearer token123 - X-Custom-Header: value -``` - -## What's next - -- Review the [CLI reference](../reference/cli.md#a2a) for all `docker agent serve a2a` - options -- Learn about [MCP mode](./mcp.md) to expose agents as tools in MCP clients -- Learn about [ACP mode](./acp.md) for editor integration -- Share your agents with [OCI registries](../sharing-agents.md) diff --git a/content/manuals/ai/docker-agent/integrations/acp.md b/content/manuals/ai/docker-agent/integrations/acp.md deleted file mode 100644 index 495af2ace981..000000000000 --- a/content/manuals/ai/docker-agent/integrations/acp.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -linkTitle: ACP -title: ACP integration -description: Configure your editor or IDE to use agents as coding assistants -keywords: [docker agent, acp, editor, ide, neovim, zed, integration] -weight: 40 ---- - -Run agents directly in your editor using the Agent Client Protocol (ACP). -Your agent gets access to your editor's filesystem context and can read and -modify files as you work. The editor handles file operations while Docker Agent -provides the AI capabilities. - -This guide shows you how to configure Neovim, or Zed to run agents with Docker Agent. If -you're looking to expose agents as tools to MCP clients like Claude -Desktop or Claude Code, see [MCP integration](./mcp.md) instead. - -## How it works - -When you run Docker Agent with ACP, it becomes part of your editor's environment. You -select code, highlight a function, or reference a file - the agent sees what you -see. No copying file paths or switching to a terminal. - -Ask "explain this function" and the agent reads the file you're viewing. Ask it -to "add error handling" and it edits the code right in your editor. The agent -works with your editor's view of the project, not some external file system it -has to navigate. - -The difference from running Docker Agent in a terminal: file operations go through -your editor instead of the agent directly accessing your filesystem. When the -agent needs to read or write a file, it requests it from your editor. This keeps -the agent's view of your code synchronized with yours - same working directory, -same files, same state. - -## Prerequisites - -Before configuring your editor, you need: - -- **Docker Agent installed** - See the [installation guide](../_index.md#installation) -- **Agent configuration** - A YAML file defining your agent. See the - [tutorial](../tutorial.md) or [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) -- **Editor with ACP support** - Neovim, Intellij, Zed, etc. - -Your agents will use model provider API keys from your shell environment -(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.). Make sure these are set before -launching your editor. - -## Editor configuration - -### Zed - -Zed has built-in ACP support. - -1. Add `docker agent` to your agent servers in `settings.json`: - - ```json - { - "agent_servers": { - "my-agent-team": { - "command": "docker", - "args": ["agent", "serve", "acp", "agent.yml"] - } - } - } - ``` - - Replace: - - `my-agent-team` with the name you want to use for the agent - - `agent.yml` with the path to your agent configuration file. - - If you have multiple agent files that you like to run separately, you can - create multiple entries under `agent_servers` for each agent. - -2. Start a new external agent thread. Select your agent in the drop-down list. - - ![New external thread with Docker Agent in Zed](../images/cagent-acp-zed.avif) - -### Neovim - -Use the [CodeCompanion](https://github.com/olimorris/codecompanion.nvim) plugin, -which has native support for Docker Agent through a built-in adapter: - -1. [Install CodeCompanion](https://codecompanion.olimorris.dev/installation) - through your plugin manager. -2. Extend the `dockeragent` adapter in your CodeCompanion config: - - ```lua - require("codecompanion").setup({ - adapters = { - acp = { - dockeragent = function() - return require("codecompanion.adapters").extend("dockeragent", { - commands = { - default = { - "docker", - "agent", - "serve", - "acp", - "agent.yml", - }, - }, - }) - end, - }, - }, - }) - ``` - - Replace `agent.yml` with the path to your agent configuration file. If you - have multiple agent files that you like to run separately, you can create - multiple commands for each agent. - -3. Restart Neovim and launch CodeCompanion: - - ```plaintext - :CodeCompanion - ``` - -4. Switch to the Docker Agent adapter (keymap `ga` in the CodeCompanion buffer, by - default). - -See the [CodeCompanion ACP -documentation](https://codecompanion.olimorris.dev/usage/acp-protocol) for more -information about ACP support in CodeCompanion. Note that terminal operations -are not supported, so [toolsets](../reference/toolsets.md) like `shell` or -`script_shell` are not usable through CodeCompanion. - -## Agent references - -You can specify your agent configuration as a local file path or OCI registry -reference: - -```console -# Local file path -$ docker agent serve acp ./agent.yml - -# OCI registry reference -$ docker agent serve acp agentcatalog/pirate -$ docker agent serve acp dockereng/myagent:v1.0.0 -``` - -Use the same syntax in your editor configuration: - -```json -{ - "agent_servers": { - "myagent": { - "command": "docker", - "args": ["agent", "serve", "acp", "agentcatalog/pirate"] - } - } -} -``` - -Registry references enable team sharing, version management, and clean -configuration without local file paths. See [Sharing -agents](../sharing-agents.md) for details on using OCI registries. - -## Testing your setup - -Verify your configuration works: - -1. Start the Docker Agent ACP server using your editor's configured method -2. Send a test prompt through your editor's interface -3. Check that the agent responds -4. Verify filesystem operations work by asking the agent to read a file - -If the agent starts but can't access files or perform other actions, check: - -- Working directory in your editor is set correctly to your project root -- Agent configuration file path is absolute or relative to working directory -- Your editor or plugin properly implements ACP protocol features - -## What's next - -- Review the [configuration reference](../reference/config.md) for advanced - agent setup -- Explore the [toolsets reference](../reference/toolsets.md) to learn what tools - are available -- Add [RAG for codebase search](../rag.md) to your agent -- Check the [CLI reference](../reference/cli.md) for all `docker agent serve acp` options -- Browse [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) for - inspiration diff --git a/content/manuals/ai/docker-agent/integrations/mcp.md b/content/manuals/ai/docker-agent/integrations/mcp.md deleted file mode 100644 index 4f4dfc522862..000000000000 --- a/content/manuals/ai/docker-agent/integrations/mcp.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -title: MCP mode -linkTitle: MCP -description: Expose agents as tools to MCP clients like Claude Desktop and Claude Code -keywords: - [ - cagent, - mcp, - model context protocol, - claude desktop, - claude code, - integration, - ] -weight: 50 ---- - -When you run Docker Agent in MCP mode, your agents show up as tools in Claude Desktop -and other MCP clients. Instead of switching to a terminal to run your security -agent, you ask Claude to use it and Claude calls it for you. - -This guide covers setup for Claude Desktop and Claude Code. If you want agents -embedded in your editor instead, see [ACP integration](./acp.md). - -## How it works - -You configure Claude Desktop (or another MCP client) to connect to Docker Agent. Your -agents appear in Claude's tool list. When you ask Claude to use one, it calls -that agent through the MCP protocol. - -Say you have a security agent configured. Ask Claude Desktop "Use the security -agent to audit this authentication code" and Claude calls it. The agent runs -with its configured tools (filesystem, shell, whatever you gave it), then -returns results to Claude. - -If your configuration has multiple agents, each one becomes a separate tool. A -config with `root`, `designer`, and `engineer` agents gives Claude three tools -to choose from. Claude might call the engineer directly or use the root -coordinator—depends on your agent descriptions and what you ask for. - -## MCP Gateway - -Docker provides an [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) that -gives agents access to a catalog of pre-configured MCP servers. Instead -of configuring individual MCP servers, agents can use the gateway to access -tools like web search, database queries, and more. - -Configure MCP toolset with gateway reference: - -```yaml -agents: - root: - toolsets: - - type: mcp - ref: docker:duckduckgo # Uses Docker MCP Gateway -``` - -The `docker:` prefix tells Docker Agent to use the MCP Gateway for this server. See -the [MCP Catalog](/ai/mcp-catalog-and-toolkit/catalog/) for available servers and the -[MCP Gateway documentation](/ai/mcp-catalog-and-toolkit/mcp-gateway/) for -configuration options. - -You can also use the [MCP Toolkit](/ai/mcp-catalog-and-toolkit/) to explore and -manage MCP servers interactively. - -## Prerequisites - -Before configuring MCP integration, you need: - -- **Docker Agent installed** - See the [installation guide](../_index.md#installation) -- **Agent configuration** - A YAML file defining your agent. See the - [tutorial](../tutorial.md) or [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) -- **MCP client** - Claude Desktop, Claude Code, or another MCP-compatible - application -- **API keys** - Environment variables for any model providers your agents use - (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) - -## MCP client configuration - -Your MCP client needs to know how to start Docker Agent and communicate with it. This -typically involves adding Docker Agent as an MCP server in your client's -configuration. - -### Claude Desktop - -Add Docker Agent to your Claude Desktop MCP settings file: - -- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` -- Windows: `%APPDATA%\Claude\claude_desktop_config.json` - -Example configuration: - -```json -{ - "mcpServers": { - "myagent": { - "command": "docker", - "args": [ - "agent", - "serve", - "mcp", - "/path/to/agent.yml", - "--working-dir", - "/Users/yourname/projects" - ], - "env": { - "ANTHROPIC_API_KEY": "your_anthropic_key_here", - "OPENAI_API_KEY": "your_openai_key_here" - } - } - } -} -``` - -Configuration breakdown: - -- `command`: Full path to your `docker` binary (use `which docker` to find it), or path to `docker-agent` if not using the Docker CLI plugin -- `args`: MCP command arguments: - - `mcp`: The subcommand to run `docker agent` in MCP mode - - `dockereng/myagent`: Your agent configuration (local file path or OCI - reference) - - `--working-dir`: Optional working directory for agent execution -- `env`: Environment variables your agents need: - - Model provider API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) - - Any other environment variables your agents reference - -After updating the configuration, restart Claude Desktop. Your agents will -appear as available tools. - -### Claude Code - -Add Docker Agent as an MCP server using the `claude mcp add` command: - -```console -$ claude mcp add --transport stdio myagent \ - --env OPENAI_API_KEY=$OPENAI_API_KEY \ - --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ - -- docker agent serve mcp /path/to/agent.yml --working-dir $(pwd) -``` - -Command breakdown: - -- `claude mcp add`: Claude Code command to register an MCP server -- `--transport stdio`: Use stdio transport (standard for local MCP servers) -- `myagent`: Name for this MCP server in Claude Code -- `--env`: Pass environment variables (repeat for each variable) -- `--`: Separates Claude Code options from the MCP server command -- `docker agent serve mcp /path/to/agent.yml`: The Docker Agent MCP command with the path to your - agent configuration -- `--working-dir $(pwd)`: Set the working directory for agent execution - -After adding the server, your agents will be available as tools in Claude Code -sessions. - -### Other MCP clients - -For other MCP-compatible clients, you need to: - -1. Start Docker Agent with `docker agent serve mcp /path/to/agent.yml --working-dir /project/path` -2. Configure the client to communicate with Docker Agent over stdio -3. Pass required environment variables (API keys, etc.) - -Consult your MCP client's documentation for specific configuration steps. - -## Agent references - -You can specify your agent configuration as a local file path or OCI registry -reference: - -```console -# Local file path -$ docker agent serve mcp ./agent.yml - -# OCI registry reference -$ docker agent serve mcp agentcatalog/pirate -$ docker agent serve mcp dockereng/myagent:v1.0.0 -``` - -Use the same syntax in MCP client configurations: - -```json -{ - "mcpServers": { - "myagent": { - "command": "docker", - "args": ["agent", "serve", "mcp", "agentcatalog/pirate"] - } - } -} -``` - -Registry references let your team use the same agent configuration without -managing local files. See [Sharing agents](../sharing-agents.md) for details. - -## Designing agents for MCP - -MCP clients see each of your agents as a separate tool and can call any of them -directly. This changes how you should think about agent design compared to -running agents with `docker agent run`. - -### Write good descriptions - -The `description` field tells the MCP client what the agent does. This is how -the client decides when to call it. "Analyzes code for security vulnerabilities -and compliance issues" is specific. "A helpful security agent" doesn't say what -it actually does. - -```yaml -agents: - security_auditor: - description: Analyzes code for security vulnerabilities and compliance issues - # Not: "A helpful security agent" -``` - -### MCP clients call agents directly - -The MCP client can call any of your agents, not just root. If you have `root`, -`designer`, and `engineer` agents, the client might call the engineer directly -instead of going through root. Design each agent to work on its own: - -```yaml -agents: - engineer: - description: Implements features and writes production code - instruction: | - You implement code based on requirements provided. - You can work independently without a coordinator. - toolsets: - - type: filesystem - - type: shell -``` - -If an agent needs others to work properly, say so in the description: -"Coordinates design and engineering agents to implement complete features." - -### Test each agent on its own - -MCP clients call agents individually, so test them that way: - -```console -$ docker agent run agent.yml --agent engineer -``` - -Make sure the agent works without going through root first. Check that it has -the right tools and that its instructions make sense when it's called directly. - -## Testing your setup - -Verify your MCP integration works: - -1. Restart your MCP client after configuration changes -2. Check that agents appear as available tools -3. Invoke an agent with a simple test prompt -4. Verify the agent can access its configured tools (filesystem, shell, etc.) - -If agents don't appear or fail to execute, check: - -- `docker agent` command is available and executable -- Agent configuration file exists and is valid -- All required API keys are set in environment variables -- Working directory path exists and has appropriate permissions -- MCP client logs for connection or execution errors - -## Common workflows - -### Call specialist agents - -You have a security agent that knows your compliance rules and common -vulnerabilities. In Claude Desktop, paste some authentication code and ask "Use -the security agent to review this." The agent checks the code and reports what -it finds. You stay in Claude's interface the whole time. - -### Work with agent teams - -Your configuration has a coordinator that delegates to designer and engineer -agents. Ask Claude Code "Use the coordinator to implement a login form" and the -coordinator hands off UI work to the designer and code to the engineer. You get -a complete implementation without running `docker agent run` yourself. - -### Run domain-specific tools - -You built an infrastructure agent with custom deployment scripts and monitoring -queries. Ask any MCP client "Use the infra agent to check production status" and -it runs your tools and returns results. Your deployment knowledge is now -available wherever you use MCP clients. - -### Share agents - -Your team keeps agents in an OCI registry. Everyone adds -`agentcatalog/security-expert` to their MCP client config. When you update the -agent, they get the new version on their next restart. No YAML files to pass -around. - -## What's next - -- Use the [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) to give your - agents access to pre-configured MCP servers -- Explore MCP servers interactively with the [MCP - Toolkit](/ai/mcp-catalog-and-toolkit/) -- Review the [configuration reference](../reference/config.md) for advanced - agent setup -- Explore the [toolsets reference](../reference/toolsets.md) to learn what tools - agents can use -- Add [RAG for codebase search](../rag.md) to your agent -- Check the [CLI reference](../reference/cli.md) for all `docker agent serve mcp` options -- Browse [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) for - different agent types diff --git a/content/manuals/ai/docker-agent/local-models.md b/content/manuals/ai/docker-agent/local-models.md deleted file mode 100644 index 7ddc81f3740a..000000000000 --- a/content/manuals/ai/docker-agent/local-models.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Local models with Docker Model Runner -linkTitle: Local models -description: Run AI models locally using Docker Model Runner - no API keys required -keywords: [docker agent, docker model runner, dmr, local models, embeddings, offline] -weight: 20 ---- - -Docker Model Runner lets you run AI models locally on your machine. No API -keys, no recurring costs, and your data stays private. - -## Why use local models - -Docker Model Runner lets you run models locally without API keys or recurring -costs. Your data stays on your machine, and you can work offline once models -are downloaded. This is an alternative to [cloud model -providers](model-providers.md). - -## Prerequisites - -You need Docker Model Runner installed and running: - -- Docker Desktop (macOS/Windows) - Enable Docker Model Runner in - **Settings > AI > Enable Docker Model Runner**. See [Get started with - DMR](/manuals/ai/model-runner/get-started.md#enable-docker-model-runner) for - detailed instructions. -- Docker Engine (Linux) - Install with `sudo apt-get install -docker-model-plugin` or `sudo dnf install docker-model-plugin`. See [Get - started with DMR](/manuals/ai/model-runner/get-started.md#docker-engine). - -Verify Docker Model Runner is available: - -```console -$ docker model version -``` - -If the command returns version information, you're ready to use local models. - -## Using models with DMR - -Docker Model Runner can run any compatible model. Models can come from: - -- Docker Hub repositories (`docker.io/namespace/model-name`) -- Your own OCI artifacts packaged and pushed to any registry -- HuggingFace models directly (`hf.co/org/model-name`) -- The Docker Model catalog in Docker Desktop - -To see models available to the local Docker catalog, run: - -```console -$ docker model list --openai -``` - -To use a model, reference it in your configuration. DMR automatically pulls -models on first use if they're not already local. - -## Configuration - -Configure your agent to use Docker Model Runner with the `dmr` provider: - -```yaml -agents: - root: - model: dmr/ai/qwen3 - instruction: You are a helpful assistant - toolsets: - - type: filesystem -``` - -When you first run your agent, Docker Agent prompts you to pull the model if it's -not already available locally: - -```console -$ docker agent run agent.yaml -Model not found locally. Do you want to pull it now? ([y]es/[n]o) -``` - -## How it works - -When you configure an agent to use DMR, Docker Agent automatically connects to your -local Docker Model Runner and routes inference requests to it. If a model isn't -available locally, Docker Agent prompts you to pull it on first use. No API keys or -authentication are required. - -## Advanced configuration - -For more control over model behavior, define a model configuration: - -```yaml -models: - local-qwen: - provider: dmr - model: ai/qwen3:14B - temperature: 0.7 - max_tokens: 8192 - -agents: - root: - model: local-qwen - instruction: You are a helpful coding assistant -``` - -### Faster inference with speculative decoding - -Speed up model responses using speculative decoding with a smaller draft model: - -```yaml -models: - fast-qwen: - provider: dmr - model: ai/qwen3:14B - provider_opts: - speculative_draft_model: ai/qwen3:0.6B-Q4_K_M - speculative_num_tokens: 16 - speculative_acceptance_rate: 0.8 -``` - -The draft model generates token candidates, and the main model validates them. -This can significantly improve throughput for longer responses. - -### Runtime flags - -Pass engine-specific flags to optimize performance: - -```yaml -models: - optimized-qwen: - provider: dmr - model: ai/qwen3 - provider_opts: - runtime_flags: ["--ngl=33", "--threads=8"] -``` - -Common flags: - -- `--ngl` - Number of GPU layers -- `--threads` - CPU thread count -- `--repeat-penalty` - Repetition penalty - -## Using DMR for RAG - -Docker Model Runner supports both embeddings and reranking for RAG workflows. - -### Embedding with DMR - -Use local embeddings for indexing your knowledge base: - -```yaml -rag: - codebase: - docs: [./src] - strategies: - - type: chunked-embeddings - embedding_model: dmr/ai/embeddinggemma - database: ./code.db -``` - -### Reranking with DMR - -DMR provides native reranking for improved RAG results: - -```yaml -models: - reranker: - provider: dmr - model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf - -rag: - docs: - docs: [./documentation] - strategies: - - type: chunked-embeddings - embedding_model: dmr/ai/embeddinggemma - limit: 20 - results: - reranking: - model: reranker - threshold: 0.5 - limit: 5 -``` - -Native DMR reranking is the fastest option for reranking RAG results. - -## Troubleshooting - -If Docker Agent can't find Docker Model Runner: - -1. Verify Docker Model Runner status: - - ```console - $ docker model status - ``` - -2. Check available models: - - ```console - $ docker model list - ``` - -3. Check model logs for errors: - - ```console - $ docker model logs - ``` - -4. Ensure Docker Desktop has Model Runner enabled in settings (macOS/Windows) - -## What's next - -- Follow the [tutorial](tutorial.md) to build your first agent with local - models -- Learn about [RAG](rag.md) to give your agents access to codebases and - documentation -- See the [configuration reference](reference/config.md#docker-model-runner-dmr) - for all DMR options diff --git a/content/manuals/ai/docker-agent/model-providers.md b/content/manuals/ai/docker-agent/model-providers.md deleted file mode 100644 index 2ca872064c5a..000000000000 --- a/content/manuals/ai/docker-agent/model-providers.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Model providers -description: Get API keys and configure cloud model providers for Docker Agent -keywords: [docker agent, model providers, api keys, anthropic, openai, google, gemini] -weight: 10 ---- - -To run Docker Agent, you need a model provider. You can either use a cloud provider -with an API key or run models locally with [Docker Model -Runner](local-models.md). - -This guide covers cloud providers. For the local alternative, see [Local -models with Docker Model Runner](local-models.md). - -## Supported providers - -Docker Agent supports these cloud model providers: - -- Anthropic - Claude models -- OpenAI - GPT models -- Google - Gemini models - -## Anthropic - -Anthropic provides the Claude family of models, including Claude Sonnet and -Claude Opus. - -To get an API key: - -1. Go to [console.anthropic.com](https://console.anthropic.com/). -2. Sign up or sign in to your account. -3. Navigate to the API Keys section. -4. Create a new API key. -5. Copy the key. - -Set your API key as an environment variable: - -```console -$ export ANTHROPIC_API_KEY=your_key_here -``` - -Use Anthropic models in your agent configuration: - -```yaml -agents: - root: - model: anthropic/claude-sonnet-4-5 - instruction: You are a helpful coding assistant -``` - -Available models include: - -- `anthropic/claude-sonnet-4-5` -- `anthropic/claude-opus-4-5` -- `anthropic/claude-haiku-4-5` - -## OpenAI - -OpenAI provides the GPT family of models, including GPT-5 and GPT-5 mini. - -To get an API key: - -1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys). -2. Sign up or sign in to your account. -3. Navigate to the API Keys section. -4. Create a new API key. -5. Copy the key. - -Set your API key as an environment variable: - -```console -$ export OPENAI_API_KEY=your_key_here -``` - -Use OpenAI models in your agent configuration: - -```yaml -agents: - root: - model: openai/gpt-5 - instruction: You are a helpful coding assistant -``` - -Available models include: - -- `openai/gpt-5` -- `openai/gpt-5-mini` - -## Google Gemini - -Google provides the Gemini family of models. - -To get an API key: - -1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey). -2. Sign in with your Google account. -3. Create an API key. -4. Copy the key. - -Set your API key as an environment variable: - -```console -$ export GOOGLE_API_KEY=your_key_here -``` - -Use Gemini models in your agent configuration: - -```yaml -agents: - root: - model: google/gemini-2.5-flash - instruction: You are a helpful coding assistant -``` - -Available models include: - -- `google/gemini-2.5-flash` -- `google/gemini-2.5-pro` - -## OpenAI-compatible providers - -You can use the `openai` provider type to connect to any model or provider that -implements the OpenAI API specification. This includes services like Azure -OpenAI, local inference servers, and other compatible endpoints. - -Configure an OpenAI-compatible provider by specifying the base URL: - -```yaml -agents: - root: - model: openai/your-model-name - instruction: You are a helpful coding assistant - provider: - base_url: https://your-provider.example.com/v1 -``` - -By default, Docker Agent uses the `OPENAI_API_KEY` environment variable for -authentication. If your provider uses a different variable, specify it with -`token_key`: - -```yaml -agents: - root: - model: openai/your-model-name - instruction: You are a helpful coding assistant - provider: - base_url: https://your-provider.example.com/v1 - token_key: YOUR_PROVIDER_API_KEY -``` - -## What's next - -- Follow the [tutorial](tutorial.md) to build your first agent -- Learn about [local models with Docker Model Runner](local-models.md) as an - alternative to cloud providers -- Review the [configuration reference](reference/config.md) for advanced model - settings diff --git a/content/manuals/ai/docker-agent/rag.md b/content/manuals/ai/docker-agent/rag.md deleted file mode 100644 index d27b32d28613..000000000000 --- a/content/manuals/ai/docker-agent/rag.md +++ /dev/null @@ -1,436 +0,0 @@ ---- -title: RAG -description: How RAG gives your agents access to codebases and documentation -keywords: [docker agent, rag, retrieval, embeddings, semantic search] -weight: 70 ---- - -When you configure a RAG source in Docker Agent, your agent automatically gains a -search tool for that knowledge base. The agent decides when to search, retrieves -only relevant information, and uses it to answer questions or complete tasks - -all without you manually managing what goes in the prompt. - -This guide explains how Docker Agent's RAG system works, when to use it, and how to -configure it effectively for your content. - -> [!NOTE] -> RAG is an advanced feature that requires configuration and tuning. The defaults -> work well for getting started, but tailoring the configuration to your specific -> content and use case significantly improves results. - -## The problem: too much context - -Your agent can work with your entire codebase, but it can't fit everything in -its context window. Even with 200K token limits, medium-sized projects are too -large. Finding relevant code buried in hundreds of files wastes context. - -Filesystem tools help agents read files, but the agent has to guess which files -to read. It can't search by meaning, only by filename. Ask "find the retry -logic" and the agent reads files hoping to stumble on the right code. - -Grep finds exact text matches but misses related concepts. Searching -"authentication" won't find code using "auth" or "login." You either get -hundreds of matches or zero, and grep doesn't understand code structure - it -just matches strings anywhere they appear. - -RAG indexes your content ahead of time and enables semantic search. The agent -searches pre-indexed content by meaning, not exact words. It retrieves only -relevant chunks that respect code structure. No wasted context on exploration. - -## How RAG works in Docker Agent - -Configure a RAG source in your Docker Agent config: - -```yaml -rag: - codebase: - docs: [./src, ./pkg] - strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./code.db - -agents: - root: - model: openai/gpt-5 - instruction: You are a coding assistant. Search the codebase when needed. - rag: [codebase] -``` - -When you reference `rag: [codebase]`, Docker Agent: - -1. **At startup** - Indexes your documents (first run only, blocks until complete) -2. **During conversation** - Gives the agent a search tool -3. **When the agent searches** - Retrieves relevant chunks and adds them to context -4. **On file changes** - Automatically re-indexes modified files - -The agent decides when to search based on the conversation. You don't manage -what goes in context - the agent does. - -### The indexing process - -On first run, Docker Agent: - -- Reads files from configured paths -- Respects `.gitignore` patterns (can be disabled) -- Splits documents into chunks -- Creates searchable representations using your chosen strategy -- Stores everything in a local database - -Subsequent runs reuse the index. If files change, Docker Agent detects this and -re-indexes only what changed, keeping your knowledge base up to date without -manual intervention. - -## Retrieval strategies - -Different content requires different retrieval approaches. Docker Agent supports -three strategies, each optimized for different use cases. The defaults work -well, but understanding the trade-offs helps you choose the right approach. - -### Semantic search (chunked-embeddings) - -Converts text to vectors that represent meaning, enabling search by concept -rather than exact words: - -```yaml -strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./docs.db - chunking: - size: 1000 - overlap: 100 -``` - -During indexing, documents are split into chunks and each chunk is converted -to a 1536-dimensional vector by the embedding model. These vectors are -essentially coordinates in a high-dimensional space where similar concepts are -positioned close together. - -When you search for "how do I authenticate users?", your query becomes a vector -and the database finds chunks with nearby vectors using cosine similarity -(measuring the angle between vectors). The embedding model learned that -"authentication," "auth," and "login" are related concepts, so searching for -one finds the others. - -Example: The query "how do I authenticate users?" finds both "User -authentication requires a valid API token" and "Token-based auth validates -requests" despite different wording. It won't find "The authentication tests -are failing" because that's a different meaning despite containing the word. - -This works well for documentation where users ask questions using different -terminology than your docs. The downside is it may miss exact technical terms -and sometimes you want literal matches, not semantic ones. Requires embedding -API calls during indexing. - -### Keyword search (BM25) - -Statistical algorithm that matches and ranks by term frequency and rarity: - -```yaml -strategies: - - type: bm25 - database: ./bm25.db - k1: 1.5 - b: 0.75 - chunking: - size: 1000 - overlap: 100 -``` - -During indexing, documents are tokenized and the algorithm calculates how often -each term appears (term frequency) and how rare it is across all documents -(inverse document frequency). The scoring index is stored in a local SQLite -database. - -When you search for "HandleRequest function", the algorithm finds chunks -containing these exact terms and scores them based on term frequency, term -rarity, and document length. Finding "HandleRequest" is scored as more -significant than finding common words like "function". Think of it as grep with -statistical ranking. - -Example: Searching "HandleRequest function" finds `func HandleRequest(w -http.ResponseWriter, r *http.Request)` and "The HandleRequest function -processes incoming requests", but not "process HTTP requests" despite that -being semantically similar. - -The `k1` parameter (default 1.5) controls how much repeated terms matter - -higher values emphasize repetition more. The `b` parameter (default 0.75) -controls length normalization - higher values penalize longer documents more. - -This is fast, local (no API costs), and predictable for finding function names, -class names, API endpoints, and any identifier that appears verbatim. The -trade-off is zero understanding of meaning - "RetryHandler" and "retry logic" -won't match despite being related. Essential complement to semantic search. - -### LLM-enhanced semantic search (semantic-embeddings) - -Generates semantic summaries with an LLM before embedding, enabling search by -what code does rather than what it's called: - -```yaml -strategies: - - type: semantic-embeddings - embedding_model: openai/text-embedding-3-small - chat_model: openai/gpt-5-mini - vector_dimensions: 1536 - database: ./code.db - ast_context: true - chunking: - size: 1000 - code_aware: true -``` - -During indexing, code is split using AST structure (functions stay intact), -then the `chat_model` generates a semantic summary of each chunk. The summary -gets embedded, not the raw code. When you search, your query matches against -these summaries, but the original code is returned. - -This solves a problem with regular embeddings: raw code embeddings are -dominated by variable names and implementation details. A function called -`processData` that implements retry logic won't semantically match "retry". But -when the LLM summarizes it first, the summary explicitly mentions "retry -logic," making it findable. - -Example: Consider this code: - -```go -func (c *Client) Do(req *Request) (*Response, error) { - for i := 0; i < 3; i++ { - resp, err := c.attempt(req) - if err == nil { return resp, nil } - time.Sleep(time.Duration(1<<i) * time.Second) - } - return nil, errors.New("max retries exceeded") -} -``` - -The LLM summary is: "Implements exponential backoff retry logic for HTTP -requests, attempting up to 3 times with delays of 1s, 2s, 4s before failing." - -Searching "retry logic exponential backoff" now finds this code, despite the -code never using those words. The `ast_context: true` option includes AST -metadata in prompts for better understanding. The `code_aware: true` chunking -prevents splitting functions mid-implementation. - -This approach excels at finding code by behavior in large codebases with -inconsistent naming. The trade-off is significantly slower indexing (LLM call -per chunk) and higher API costs (both chat and embedding models). Often -overkill for well-documented code or simple projects. - -## Combining strategies with hybrid retrieval - -Each strategy has strengths and weaknesses. Combining them captures both -semantic understanding and exact term matching: - -```yaml -rag: - knowledge: - docs: [./documentation, ./src] - strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./vector.db - limit: 20 - - - type: bm25 - database: ./bm25.db - limit: 15 - - results: - fusion: - strategy: rrf - k: 60 - deduplicate: true - limit: 5 -``` - -### How fusion works - -Both strategies run in parallel, each returning its top candidates (20 and 15 -in this example). Fusion combines results using rank-based scoring, removes -duplicates, and returns the top 5 final results. Your agent gets results that -work for both semantic queries ("how do I...") and exact term searches ("find -`configure_auth` function"). - -### Fusion strategies - -RRF (Reciprocal Rank Fusion) is recommended. It combines results based on rank -rather than absolute scores, which works reliably when strategies use different -scoring scales. No tuning required. - -For weighted fusion, you give more importance to one strategy: - -```yaml -fusion: - strategy: weighted - weights: - chunked-embeddings: 0.7 - bm25: 0.3 -``` - -This requires tuning for your content. Use it when you know one approach works -better for your use case. - -Max score fusion takes the highest score across strategies: - -```yaml -fusion: - strategy: max -``` - -This only works if strategies use comparable scoring scales. Simple but less -sophisticated than RRF. - -## Improving retrieval quality - -### Reranking results - -Initial retrieval optimizes for speed. Reranking rescores results with a more -sophisticated model for better relevance: - -```yaml -results: - reranking: - model: openai/gpt-5-mini - threshold: 0.3 - criteria: | - When scoring relevance, prioritize: - - Official documentation over community content - - Recent information over outdated material - - Practical examples over theoretical explanations - - Code implementations over design discussions - limit: 5 -``` - -The `criteria` field is powerful - use it to encode domain knowledge about what -makes results relevant for your specific use case. The more specific your -criteria, the better the reranking. - -Trade-off: Significantly better results but adds latency and API costs (LLM -call for scoring each result). - -### Chunking configuration - -How you split documents dramatically affects retrieval quality. Tailor chunking -to your content type. Chunk size is measured in characters (Unicode code -points), not tokens. - -For documentation and prose, use moderate chunks with overlap: - -```yaml -chunking: - size: 1000 - overlap: 100 - respect_word_boundaries: true -``` - -Overlap preserves context at chunk boundaries. Respecting word boundaries -prevents cutting words in half. - -For code, use larger chunks with AST-based splitting: - -```yaml -chunking: - size: 2000 - code_aware: true -``` - -This keeps functions intact. The `code_aware` setting uses tree-sitter to -respect code structure. - -> [!NOTE] <!-- TODO: update this when we add support for more languages. --> -> Currently only Go is supported; support for additional languages is planned. - -For short, focused content like API references: - -```yaml -chunking: - size: 500 - overlap: 50 -``` - -Brief sections need less overlap since they're naturally self-contained. - -Experiment with these values. If retrieval misses context, increase chunk size -or overlap. If results are too broad, decrease chunk size. - -## Making decisions about RAG - -### When to use RAG - -Use RAG when: - -- Your content is too large for the context window -- You want targeted retrieval, not everything at once -- Content changes and needs to stay current -- Agent needs to search across many files - -Don't use RAG when: - -- Content is small enough to include in agent instructions -- Information rarely changes (consider prompt engineering instead) -- You need real-time data (RAG uses pre-indexed snapshots) -- Content is already in a searchable format the agent can query directly - -### Choosing retrieval strategies - -Use semantic search (chunked-embeddings) for user-facing documentation, content -with varied terminology, and conceptual searches where users phrase questions -differently than your docs. - -Use keyword search (BM25) for code identifiers, function names, API endpoints, -error messages, and any content where exact term matching matters. Essential -for technical jargon and proper nouns. - -Use LLM-enhanced semantic (semantic-embeddings) for code search by -functionality, finding implementations by behavior rather than name, or complex -technical content requiring deep understanding. Choose this when accuracy -matters more than indexing speed. - -Use hybrid (multiple strategies) for general-purpose search across mixed -content, when you're unsure which approach works best, or for production -systems where quality matters most. Maximum coverage at the cost of complexity. - -### Tuning for your project - -Start with defaults, then adjust based on results. - -If retrieval misses relevant content: - -- Increase `limit` in strategies to retrieve more candidates -- Adjust `threshold` to be less strict -- Increase chunk `size` to capture more context -- Add more retrieval strategies - -If retrieval returns irrelevant content: - -- Decrease `limit` to fewer candidates -- Increase `threshold` to be more strict -- Add reranking with specific criteria -- Decrease chunk `size` for more focused results - -If indexing is too slow: - -- Increase `batch_size` for fewer API calls -- Increase `max_embedding_concurrency` for parallelism -- Consider BM25 instead of embeddings (local, no API) -- Use smaller embedding models - -If results lack context: - -- Increase chunk `overlap` -- Increase chunk `size` -- Use `return_full_content: true` to return entire documents -- Add neighboring chunks to results - -## Further reading - -- [Configuration reference](reference/config.md#rag) - Complete RAG options and - parameters -- [RAG examples](https://github.com/docker/docker-agent/tree/main/examples/rag) - - Working configurations for different scenarios -- [Tools reference](reference/toolsets.md) - How RAG search tools work in agent workflows diff --git a/content/manuals/ai/docker-agent/reference/_index.md b/content/manuals/ai/docker-agent/reference/_index.md deleted file mode 100644 index 8403097afcef..000000000000 --- a/content/manuals/ai/docker-agent/reference/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Reference -weight: 60 ---- diff --git a/content/manuals/ai/docker-agent/reference/cli.md b/content/manuals/ai/docker-agent/reference/cli.md deleted file mode 100644 index e1817e9d4186..000000000000 --- a/content/manuals/ai/docker-agent/reference/cli.md +++ /dev/null @@ -1,482 +0,0 @@ ---- -title: CLI reference -linkTitle: CLI -description: Complete reference for Docker Agent command-line interface -keywords: [ai, agent, docker agent, cli, command line] -weight: 30 ---- - -Command-line interface for running, managing, and deploying AI agents. - -For agent configuration file syntax, see the [Configuration file -reference](./config.md). For toolset capabilities, see the [Toolsets -reference](./toolsets.md). - -## Synopsis - -```console -$ docker agent [command] [flags] -``` - -## Global flags - -Work with all commands: - -| Flag | Type | Default | Description | -| --------------- | ------- | ------- | -------------------- | -| `-d`, `--debug` | boolean | false | Enable debug logging | -| `-o`, `--otel` | boolean | false | Enable OpenTelemetry | -| `--log-file` | string | - | Debug log file path | - -Debug logs write to `~/.cagent/cagent.debug.log` by default. Override with -`--log-file`. - -## Runtime flags - -Work with most commands. Supported commands link to this section. - -| Flag | Type | Default | Description | -| ------------------- | ------- | ------- | ------------------------------------ | -| `--models-gateway` | string | - | Models gateway address | -| `--env-from-file` | array | - | Load environment variables from file | -| `--code-mode-tools` | boolean | false | Enable JavaScript tool orchestration | -| `--working-dir` | string | - | Working directory for the session | - -Set `--models-gateway` via `CAGENT_MODELS_GATEWAY` environment variable. - -## Commands - -### a2a - -Expose agent via the Agent2Agent (A2A) protocol. Allows other A2A-compatible -systems to discover and interact with your agent. Auto-selects an available -port if not specified. - -```console -$ docker agent serve a2a agent-file|registry-ref -``` - -> [!NOTE] -> A2A support is experimental. Tool calls are -> handled internally and not exposed as separate ADK events. Some ADK features -> are not integrated. - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) - -Flags: - -| Flag | Type | Default | Description | -| --------------- | ------- | ------- | ----------------- | -| `-a`, `--agent` | string | root | Agent name | -| `--port` | integer | 0 | Port (0 = random) | - -Supports [runtime flags](#runtime-flags). - -Examples: - -```console -$ docker agent serve a2a ./agent.yaml --port 8080 -$ docker agent serve a2a agentcatalog/pirate --port 9000 -``` - -### acp - -Start agent as ACP (Agent Client Protocol) server on stdio for editor integration. -See [ACP integration](../integrations/acp.md) for setup guides. - -```console -$ docker agent serve acp agent-file|registry-ref -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) - -Supports [runtime flags](#runtime-flags). - -### alias add - -Create alias for agent. - -```console -$ docker agent alias add name target -``` - -Arguments: - -- `name` - Alias name (required) -- `target` - Path to YAML or registry reference (required) - -Examples: - -```console -$ docker agent alias add dev ./dev-agent.yaml -$ docker agent alias add prod docker.io/user/prod-agent:latest -$ docker agent alias add default ./agent.yaml -``` - -Setting alias name to "default" lets you run `docker agent run` without arguments. - -### alias list - -List all aliases. - -```console -$ docker agent alias list -$ docker agent alias ls -``` - -### alias remove - -Remove alias. - -```console -$ docker agent alias remove name -$ docker agent alias rm name -``` - -Arguments: - -- `name` - Alias name (required) - -### api - -HTTP API server. - -```console -$ docker agent serve api agent-file|agents-dir -``` - -Arguments: - -- `agent-file|agents-dir` - Path to YAML or directory with agents (required) - -Flags: - -| Flag | Type | Default | Description | -| -------------------- | ------- | ---------- | --------------------------------- | -| `-l`, `--listen` | string | :8080 | Listen address | -| `-s`, `--session-db` | string | session.db | Session database path | -| `--pull-interval` | integer | 0 | Auto-pull OCI ref every N minutes | - -Supports [runtime flags](#runtime-flags). - -Examples: - -```console -$ docker agent serve api ./agent.yaml -$ docker agent serve api ./agents/ --listen :9000 -$ docker agent serve api docker.io/user/agent --pull-interval 10 -``` - -The `--pull-interval` flag works only with OCI references. Automatically pulls and reloads at the specified interval. - -### build - -Build Docker image for agent. - -```console -$ docker agent build agent-file|registry-ref [image-name] -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) -- `image-name` - Docker image name (optional) - -Flags: - -| Flag | Type | Default | Description | -| ------------ | ------- | ------- | -------------------------- | -| `--dry-run` | boolean | false | Print Dockerfile only | -| `--push` | boolean | false | Push image after build | -| `--no-cache` | boolean | false | Build without cache | -| `--pull` | boolean | false | Pull all referenced images | - -Example: - -```console -$ docker agent build ./agent.yaml myagent:latest -$ docker agent build ./agent.yaml --dry-run -``` - -### catalog list - -List catalog agents. - -```console -$ docker agent catalog list [org] -``` - -Arguments: - -- `org` - Organization name (optional, default: `agentcatalog`) - -Queries Docker Hub for agent repositories. - -### debug config - -Show resolved agent configuration. - -```console -$ docker agent debug config agent-file|registry-ref -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) - -Supports [runtime flags](#runtime-flags). - -Shows canonical configuration in YAML after all processing and defaults. - -### debug toolsets - -List agent tools. - -```console -$ docker agent debug toolsets agent-file|registry-ref -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) - -Supports [runtime flags](#runtime-flags). - -Lists all tools for each agent in the configuration. - -### eval - -Run evaluation tests. - -```console -$ docker agent eval agent-file|registry-ref [eval-dir] -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) -- `eval-dir` - Evaluation files directory (optional, default: `./evals`) - -Supports [runtime flags](#runtime-flags). - -### exec - -Single message execution without TUI. - -```console -$ docker agent exec agent-file|registry-ref [message|-] -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) -- `message` - Prompt, or `-` for stdin (optional) - -Same flags as [run](#run). - -Supports [runtime flags](#runtime-flags). - -Examples: - -```console -$ docker agent exec ./agent.yaml -$ docker agent exec ./agent.yaml "Check for security issues" -$ echo "Instructions" | docker agent exec ./agent.yaml - -``` - -### feedback - -Submit feedback. - -```console -$ docker agent feedback -``` - -Shows link to submit feedback. - -### mcp - -MCP (Model Context Protocol) server on stdio. Exposes agents as tools to MCP -clients. See [MCP integration](../integrations/mcp.md) for setup guides. - -```console -$ docker agent serve mcp agent-file|registry-ref -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (required) - -Supports [runtime flags](#runtime-flags). - -Examples: - -```console -$ docker agent serve mcp ./agent.yaml -$ docker agent serve mcp docker.io/user/agent:latest -``` - -### new - -Create agent configuration interactively. - -```console -$ docker agent new [message...] -``` - -Flags: - -| Flag | Type | Default | Description | -| ------------------ | ------- | ------- | ------------------------------- | -| `--model` | string | - | Model as `provider/model` | -| `--max-iterations` | integer | 0 | Maximum agentic loop iterations | - -Supports [runtime flags](#runtime-flags). - -Opens interactive TUI to configure and generate agent YAML. - -### pull - -Pull agent from OCI registry. - -```console -$ docker agent share pull registry-ref -``` - -Arguments: - -- `registry-ref` - OCI registry reference (required) - -Flags: - -| Flag | Type | Default | Description | -| --------- | ------- | ------- | --------------------------- | -| `--force` | boolean | false | Pull even if already exists | - -Example: - -```console -$ docker agent share pull docker.io/user/agent:latest -``` - -Saves to local YAML file. - -### push - -Push agent to OCI registry. - -```console -$ docker agent share push agent-file registry-ref -``` - -Arguments: - -- `agent-file` - Path to local YAML (required) -- `registry-ref` - OCI reference like `docker.io/user/agent:latest` (required) - -Example: - -```console -$ docker agent share push ./agent.yaml docker.io/myuser/myagent:latest -``` - -### run - -Interactive terminal UI for agent sessions. - -```console -$ docker agent run [agent-file|registry-ref] [message|-] -``` - -Arguments: - -- `agent-file|registry-ref` - Path to YAML or OCI registry reference (optional) -- `message` - Initial prompt, or `-` for stdin (optional) - -Flags: - -| Flag | Type | Default | Description | -| --------------- | ------- | ------- | ---------------------------- | -| `-a`, `--agent` | string | root | Agent name | -| `--yolo` | boolean | false | Auto-approve all tool calls | -| `--attach` | string | - | Attach image file | -| `--model` | array | - | Override model (repeatable) | -| `--dry-run` | boolean | false | Initialize without executing | -| `--remote` | string | - | Remote runtime address | - -Supports [runtime flags](#runtime-flags). - -Examples: - -```console -$ docker agent run ./agent.yaml -$ docker agent run ./agent.yaml "Analyze this codebase" -$ docker agent run ./agent.yaml --agent researcher -$ echo "Instructions" | docker agent run ./agent.yaml - -$ docker agent run -``` - -Running without arguments uses the default agent or a "default" alias if configured. - -Shows interactive TUI in a terminal. Falls back to exec mode otherwise. - -#### Interactive commands - -TUI slash commands: - -| Command | Description | -| ---------- | -------------------------------- | -| `/exit` | Exit | -| `/reset` | Clear history | -| `/eval` | Save conversation for evaluation | -| `/compact` | Compact conversation | -| `/yolo` | Toggle auto-approval | - -### version - -Print version information. - -```console -$ docker agent version -``` - -Shows Docker Agent version and commit hash. - -## Environment variables - -| Variable | Description | -| ------------------------------ | ------------------------------- | -| `CAGENT_MODELS_GATEWAY` | Models gateway address | -| `TELEMETRY_ENABLED` | Telemetry control (set `false`) | -| `CAGENT_HIDE_TELEMETRY_BANNER` | Hide telemetry banner (set `1`) | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry endpoint | - -## Model overrides - -Override models specified in your configuration file using the `--model` flag. - -Format: `[agent=]provider/model` - -Without an agent name, the model applies to all agents. With an agent name, it applies only to that specific agent. - -Apply to all agents: - -```console -$ docker agent run ./agent.yaml --model gpt-5 -$ docker agent run ./agent.yaml --model anthropic/claude-sonnet-4-5 -``` - -Apply to specific agents only: - -```console -$ docker agent run ./agent.yaml --model researcher=gpt-5 -$ docker agent run ./agent.yaml --model "agent1=gpt-5,agent2=claude-sonnet-4-5" -``` - -Providers: `openai`, `anthropic`, `google`, `dmr` - -Omit provider for automatic selection based on model name. diff --git a/content/manuals/ai/docker-agent/reference/config.md b/content/manuals/ai/docker-agent/reference/config.md deleted file mode 100644 index a5447b86e5a9..000000000000 --- a/content/manuals/ai/docker-agent/reference/config.md +++ /dev/null @@ -1,621 +0,0 @@ ---- -title: Configuration file reference -linkTitle: Configuration file -description: Complete reference for the Docker Agent YAML configuration file format -keywords: [ai, agent, cagent, configuration, yaml] -weight: 10 ---- - -This reference documents the YAML configuration file format for agents using Docker Agent. -It covers file structure, agent parameters, model configuration, toolset setup, -and RAG sources. - -For detailed documentation of each toolset's capabilities and specific options, -see the [Toolsets reference](./toolsets.md). - -## File structure - -A configuration file has four top-level sections: - -```yaml -agents: # Required - agent definitions - root: - model: anthropic/claude-sonnet-4-5 - description: What this agent does - instruction: How it should behave - -models: # Optional - model configurations - custom_model: - provider: openai - model: gpt-5 - -rag: # Optional - RAG sources - docs: - docs: [./documents] - strategies: [...] - -metadata: # Optional - author, license, readme - author: Your Name -``` - -## Agents - -| Property | Type | Description | Required | -| ---------------------- | ------- | ---------------------------------------------- | -------- | -| `model` | string | Model reference or name | Yes | -| `description` | string | Brief description of agent's purpose | No | -| `instruction` | string | Detailed behavior instructions | Yes | -| `sub_agents` | array | Agent names for task delegation | No | -| `handoffs` | array | Agent names for conversation handoff | No | -| `toolsets` | array | Available tools | No | -| `welcome_message` | string | Message displayed on start | No | -| `add_date` | boolean | Include current date in context | No | -| `add_environment_info` | boolean | Include working directory, OS, Git info | No | -| `add_prompt_files` | array | Prompt file paths to include | No | -| `max_iterations` | integer | Maximum tool call loops (unlimited if not set) | No | -| `num_history_items` | integer | Conversation history limit | No | -| `code_mode_tools` | boolean | Enable Code Mode for tools | No | -| `commands` | object | Named prompts accessible via `/command_name` | No | -| `structured_output` | object | JSON schema for structured responses | No | -| `rag` | array | RAG source names | No | - -### Task delegation versus conversation handoff - -Agents support two different delegation mechanisms. Choose based on whether you -need task results or conversation control. - -#### Sub_agents: Hierarchical task delegation - -Use `sub_agents` for hierarchical task delegation. The parent agent assigns a -specific task to a child agent using the `transfer_task` tool. The child -executes in its own context and returns results. The parent maintains control -and can delegate to multiple agents in sequence. - -This works well for structured workflows where you need to combine results from -specialists, or when tasks have clear boundaries. Each delegated task runs -independently and reports back to the parent. - -**Example:** - -```yaml -agents: - root: - sub_agents: [researcher, analyst] - instruction: | - Delegate research to researcher. - Delegate analysis to analyst. - Combine results and present findings. -``` - -Root calls: `transfer_task(agent="researcher", task="Find pricing data")`. The -researcher completes the task and returns results to root. - -#### Handoffs: Conversation transfer - -Use `handoffs` to transfer conversation control to a different agent. When an -agent uses the `handoff` tool, the new agent takes over completely. The -original agent steps back until someone hands back to it. - -This works well when different agents should own different parts of an ongoing -conversation, or when specialists need to collaborate as peers without a -coordinator managing every step. - -**Example:** - -```yaml -agents: - generalist: - handoffs: [database_expert, security_expert] - instruction: | - Help with general development questions. - If the conversation moves to database optimization, - hand off to database_expert. - If security concerns arise, hand off to security_expert. - - database_expert: - handoffs: [generalist, security_expert] - instruction: Handle database design and optimization. - - security_expert: - handoffs: [generalist, database_expert] - instruction: Review code for security vulnerabilities. -``` - -When the user asks about query performance, generalist executes: -`handoff(agent="database_expert")`. The database expert now owns the -conversation and can continue working with the user directly, or hand off to -security_expert if the discussion shifts to SQL injection concerns. - -### Commands - -Named prompts users invoke with `/command_name`. Supports JavaScript template -literals with `${env.VARIABLE}` for environment variables: - -```yaml -commands: - greet: "Say hello to ${env.USER}" - analyze: "Analyze ${env.PROJECT_NAME || 'demo'}" -``` - -Run with: `docker agent run config.yaml /greet` - -### Structured output - -Constrain responses to a JSON schema (OpenAI and Gemini only): - -```yaml -structured_output: - name: code_analysis - strict: true - schema: - type: object - properties: - issues: - type: array - items: { ... } - required: [issues] -``` - -## Models - -| Property | Type | Description | Required | -| --------------------- | ------- | ---------------------------------------------- | -------- | -| `provider` | string | `openai`, `anthropic`, `google`, `dmr` | Yes | -| `model` | string | Model name | Yes | -| `temperature` | float | Randomness (0.0-2.0) | No | -| `max_tokens` | integer | Maximum response length | No | -| `top_p` | float | Nucleus sampling (0.0-1.0) | No | -| `frequency_penalty` | float | Repetition penalty (-2.0 to 2.0, OpenAI only) | No | -| `presence_penalty` | float | Topic penalty (-2.0 to 2.0, OpenAI only) | No | -| `base_url` | string | Custom API endpoint | No | -| `parallel_tool_calls` | boolean | Enable parallel tool execution (default: true) | No | -| `token_key` | string | Authentication token key | No | -| `track_usage` | boolean | Track token usage | No | -| `thinking_budget` | mixed | Reasoning effort (provider-specific) | No | -| `provider_opts` | object | Provider-specific options | No | - -### Alloy models - -Use multiple models in rotation by separating names with commas: - -```yaml -model: anthropic/claude-sonnet-4-5,openai/gpt-5 -``` - -### Thinking budget - -Controls reasoning depth. Configuration varies by provider: - -- **OpenAI**: String values - `minimal`, `low`, `medium`, `high` -- **Anthropic**: Integer token budget (1024-32768, must be less than - `max_tokens`) - - Set `provider_opts.interleaved_thinking: true` for tool use during reasoning -- **Gemini**: Integer token budget (0 to disable, -1 for dynamic, max 24576) - - Gemini 2.5 Pro: 128-32768, cannot disable (minimum 128) - -```yaml -# OpenAI -thinking_budget: low - -# Anthropic -thinking_budget: 8192 -provider_opts: - interleaved_thinking: true - -# Gemini -thinking_budget: 8192 # Fixed -thinking_budget: -1 # Dynamic -thinking_budget: 0 # Disabled -``` - -### Docker Model Runner (DMR) - -Run local models. If `base_url` is omitted, Docker Agent auto-discovers via Docker -Model plugin. - -```yaml -provider: dmr -model: ai/qwen3 -max_tokens: 8192 -base_url: http://localhost:12434/engines/llama.cpp/v1 # Optional -``` - -Pass llama.cpp options via `provider_opts.runtime_flags` (array, string, or -multiline): - -```yaml -provider_opts: - runtime_flags: ["--ngl=33", "--threads=8"] - # or: runtime_flags: "--ngl=33 --threads=8" -``` - -Model config fields auto-map to runtime flags: - -- `temperature` → `--temp` -- `top_p` → `--top-p` -- `max_tokens` → `--context-size` - -Explicit `runtime_flags` override auto-mapped flags. - -Speculative decoding for faster inference: - -```yaml -provider_opts: - speculative_draft_model: ai/qwen3:0.6B-F16 - speculative_num_tokens: 16 - speculative_acceptance_rate: 0.8 -``` - -## Tools - -Configure tools in the `toolsets` array. Three types: built-in, MCP -(local/remote), and Docker Gateway. - -> [!NOTE] This section covers toolset configuration syntax. For detailed -> documentation of each toolset's capabilities, available tools, and specific -> configuration options, see the [Toolsets reference](./toolsets.md). - -All toolsets support common properties like `tools` (whitelist), `defer` -(deferred loading), `toon` (output compression), `env` (environment variables), -and `instruction` (usage guidance). See the [Toolsets reference](./toolsets.md) -for details on these properties and what each toolset does. - -### Built-in tools - -```yaml -toolsets: - - type: filesystem - - type: shell - - type: think - - type: todo - shared: true - - type: memory - path: ./memory.db -``` - -### MCP tools - -Local process: - -```yaml -- type: mcp - command: npx - args: - ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] - tools: ["read_file", "write_file"] # Optional: limit to specific tools - env: - NODE_OPTIONS: "--max-old-space-size=8192" -``` - -Remote server: - -```yaml -- type: mcp - remote: - url: https://mcp-server.example.com - transport_type: sse - headers: - Authorization: Bearer token -``` - -### Docker MCP Gateway - -Containerized tools from [Docker MCP -Catalog](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md): - -```yaml -- type: mcp - ref: docker:duckduckgo -``` - -## RAG - -Retrieval-augmented generation for document knowledge bases. Define sources at -the top level, reference in agents. - -```yaml -rag: - docs: - docs: [./documents, ./README.md] - strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./embeddings.db - -agents: - root: - rag: [docs] -``` - -### Retrieval strategies - -All strategies support chunking configuration. Chunk size and overlap are -measured in characters (Unicode code points), not tokens. - -#### Chunked-embeddings - -Direct semantic search using vector embeddings. Best for understanding intent, -synonyms, and paraphrasing. - -| Field | Type | Default | -| ---------------------------------- | ------- | ------- | -| `embedding_model` | string | - | -| `database` | string | - | -| `vector_dimensions` | integer | - | -| `similarity_metric` | string | cosine | -| `threshold` | float | 0.5 | -| `limit` | integer | 5 | -| `chunking.size` | integer | 1000 | -| `chunking.overlap` | integer | 75 | -| `chunking.respect_word_boundaries` | boolean | true | -| `chunking.code_aware` | boolean | false | - -```yaml -- type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./vector.db - similarity_metric: cosine_similarity - threshold: 0.5 - limit: 10 - chunking: - size: 1000 - overlap: 100 -``` - -#### Semantic-embeddings - -LLM-enhanced semantic search. Uses a language model to generate rich semantic -summaries of each chunk before embedding, capturing deeper meaning. Best for complex documents where context and relationships between concepts matter. - -| Field | Type | Default | -| ---------------------------------- | ------- | ------- | -| `embedding_model` | string | - | -| `chat_model` | string | - | -| `database` | string | - | -| `vector_dimensions` | integer | - | -| `similarity_metric` | string | cosine | -| `threshold` | float | 0.5 | -| `limit` | integer | 5 | -| `ast_context` | boolean | false | -| `semantic_prompt` | string | - | -| `chunking.size` | integer | 1000 | -| `chunking.overlap` | integer | 75 | -| `chunking.respect_word_boundaries` | boolean | true | -| `chunking.code_aware` | boolean | false | - -```yaml -- type: semantic-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - chat_model: openai/gpt-5-mini - database: ./semantic.db - threshold: 0.3 - limit: 10 - chunking: - size: 1000 - overlap: 100 -``` - -#### BM25 - -Keyword-based search using BM25 algorithm. Best for exact terms, technical -jargon, and code identifiers. - -| Field | Type | Default | -| ---------------------------------- | ------- | ------- | -| `database` | string | - | -| `k1` | float | 1.5 | -| `b` | float | 0.75 | -| `threshold` | float | 0.0 | -| `limit` | integer | 5 | -| `chunking.size` | integer | 1000 | -| `chunking.overlap` | integer | 75 | -| `chunking.respect_word_boundaries` | boolean | true | -| `chunking.code_aware` | boolean | false | - -```yaml -- type: bm25 - database: ./bm25.db - k1: 1.5 - b: 0.75 - threshold: 0.3 - limit: 10 - chunking: - size: 1000 - overlap: 100 -``` - -### Hybrid retrieval - -Combine multiple strategies with fusion: - -```yaml -strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./vector.db - limit: 20 - - type: bm25 - database: ./bm25.db - limit: 15 - -results: - fusion: - strategy: rrf # Options: rrf, weighted, max - k: 60 # RRF smoothing parameter - deduplicate: true - limit: 5 -``` - -Fusion strategies: - -- `rrf`: Reciprocal Rank Fusion (recommended, rank-based, no normalization - needed) -- `weighted`: Weighted combination (`fusion.weights: {chunked-embeddings: 0.7, -bm25: 0.3}`) -- `max`: Maximum score across strategies - -### Reranking - -Re-score results with a specialized model for improved relevance: - -```yaml -results: - reranking: - model: openai/gpt-5-mini - top_k: 10 # Only rerank top K (0 = all) - threshold: 0.3 # Minimum score after reranking - criteria: | # Optional domain-specific guidance - Prioritize official docs over blog posts - limit: 5 -``` - -DMR native reranking: - -```yaml -models: - reranker: - provider: dmr - model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf - -results: - reranking: - model: reranker -``` - -### Code-aware chunking - -For source code, use AST-based chunking. With semantic-embeddings, you can -include AST metadata in the LLM prompts: - -```yaml -- type: semantic-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - chat_model: openai/gpt-5-mini - database: ./code.db - ast_context: true # Include AST metadata in semantic prompts - chunking: - size: 2000 - code_aware: true # Enable AST-based chunking -``` - -### RAG properties - -Top-level RAG source: - -| Field | Type | Description | -| ------------ | -------- | --------------------------------------------------------------- | -| `docs` | []string | Document paths (supports glob patterns, respects `.gitignore`) | -| `tool` | object | Customize RAG tool name/description/instruction | -| `strategies` | []object | Retrieval strategies (see above for strategy-specific fields) | -| `results` | object | Post-processing (fusion, reranking, limits) | - -Results: - -| Field | Type | Default | -| --------------------- | ------- | ------- | -| `limit` | integer | 15 | -| `deduplicate` | boolean | true | -| `include_score` | boolean | false | -| `fusion.strategy` | string | - | -| `fusion.k` | integer | 60 | -| `fusion.weights` | object | - | -| `reranking.model` | string | - | -| `reranking.top_k` | integer | 0 | -| `reranking.threshold` | float | 0.5 | -| `reranking.criteria` | string | "" | -| `return_full_content` | boolean | false | - -## Metadata - -Documentation and sharing information: - -| Property | Type | Description | -| --------- | ------ | ------------------------------- | -| `author` | string | Author name | -| `license` | string | License (e.g., MIT, Apache-2.0) | -| `readme` | string | Usage documentation | - -```yaml -metadata: - author: Your Name - license: MIT - readme: | - Description and usage instructions -``` - -## Example configuration - -Complete configuration demonstrating key features: - -```yaml -agents: - root: - model: claude - description: Technical lead - instruction: Coordinate development tasks and delegate to specialists - sub_agents: [developer, reviewer] - toolsets: - - type: filesystem - - type: mcp - ref: docker:duckduckgo - rag: [readmes] - commands: - status: "Check project status" - - developer: - model: gpt - description: Software developer - instruction: Write clean, maintainable code - toolsets: - - type: filesystem - - type: shell - - reviewer: - model: claude - description: Code reviewer - instruction: Review for quality and security - toolsets: - - type: filesystem - -models: - gpt: - provider: openai - model: gpt-5 - - claude: - provider: anthropic - model: claude-sonnet-4-5 - max_tokens: 64000 - -rag: - readmes: - docs: ["**/README.md"] - strategies: - - type: chunked-embeddings - embedding_model: openai/text-embedding-3-small - vector_dimensions: 1536 - database: ./embeddings.db - limit: 10 - - type: bm25 - database: ./bm25.db - limit: 10 - results: - fusion: - strategy: rrf - k: 60 - limit: 5 -``` - -## What's next - -- Read the [Toolsets reference](./toolsets.md) for detailed toolset - documentation -- Review the [CLI reference](./cli.md) for command-line options -- Browse [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) -- Learn about [sharing agents](../sharing-agents.md) diff --git a/content/manuals/ai/docker-agent/reference/examples.md b/content/manuals/ai/docker-agent/reference/examples.md deleted file mode 100644 index b626ab9d5f0e..000000000000 --- a/content/manuals/ai/docker-agent/reference/examples.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Examples -description: Get inspiration from agent examples -keywords: [ai, agent, cagent] -weight: 40 ---- - -Get inspiration from the following agent examples. -See more examples in the [Docker Agent GitHub repository](https://github.com/docker/docker-agent/tree/main/examples). - -## Development team - -{{% cagent-example.inline "dev-team.yaml" %}} -{{- $example := .Get 0 }} -{{- $baseUrl := "https://raw.githubusercontent.com/docker/docker-agent/refs/heads/main/examples" }} -{{- $url := fmt.Printf "%s/%s" $baseUrl $example }} -{{- with resources.GetRemote $url }} -{{ $data := .Content | transform.Unmarshal }} - -```yaml {collapse=true} -{{ .Content }} -``` - -{{ end }} -{{% /cagent-example.inline %}} - -## Go developer - -{{% cagent-example.inline "gopher.yaml" /%}} - -## Technical blog writer - -{{% cagent-example.inline "blog.yaml" /%}} diff --git a/content/manuals/ai/docker-agent/reference/toolsets.md b/content/manuals/ai/docker-agent/reference/toolsets.md deleted file mode 100644 index decc31fea644..000000000000 --- a/content/manuals/ai/docker-agent/reference/toolsets.md +++ /dev/null @@ -1,639 +0,0 @@ ---- -title: Toolsets reference -linkTitle: Toolsets -description: Complete reference for Docker Agent toolsets and their capabilities -keywords: [ai, agent, cagent, tools, toolsets] -weight: 20 ---- - -This reference documents the toolsets available in Docker Agent and what each one -does. Tools give agents the ability to take action—interacting with files, -executing commands, accessing external resources, and managing state. - -For configuration file syntax and how to set up toolsets in your agent YAML, -see the [Configuration file reference](./config.md). - -## How agents use tools - -When you configure toolsets for an agent, those tools become available in the -agent's context. The agent can invoke tools by name with appropriate parameters -based on the task at hand. - -Tool invocation flow: - -1. Agent analyzes the task and determines which tool to use -2. Agent constructs tool parameters based on requirements -3. Docker Agent executes the tool and returns results -4. Agent processes results and decides next steps - -Agents can call multiple tools in sequence or make decisions based on tool -results. Tool selection is automatic based on the agent's understanding of the -task and available capabilities. - -## Tool types - -Docker Agent supports three types of toolsets: - -Built-in toolsets -: Core functionality built directly into Docker Agent (`filesystem`, `shell`, -`memory`, etc.). These provide essential capabilities for file operations, -command execution, and state management. -MCP toolsets -: Tools provided by Model Context Protocol servers, either local processes -(stdio) or remote servers (HTTP/SSE). MCP enables access to a wide ecosystem -of standardized tools. -Custom toolsets -: Shell scripts wrapped as tools with typed parameters (`script`). This -lets you define domain-specific tools for your use case. - -## Configuration - -Toolsets are configured in your agent's YAML file under the `toolsets` array: - -```yaml -agents: - my_agent: - model: anthropic/claude-sonnet-4-5 - description: A helpful coding assistant - toolsets: - # Built-in toolset - - type: filesystem - - # Built-in toolset with configuration - - type: memory - path: ./memories.db - - # Local MCP server (stdio) - - type: mcp - command: npx - args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"] - - # Remote MCP server (SSE) - - type: mcp - remote: - url: https://mcp.example.com/sse - transport_type: sse - headers: - Authorization: Bearer ${API_TOKEN} - - # Custom shell tools - - type: script - tools: - build: - cmd: npm run build - description: Build the project -``` - -### Common configuration options - -All toolset types support these optional properties: - -| Property | Type | Description | -| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `instruction` | string | Additional instructions for using the toolset | -| `tools` | array | Specific tool names to enable (defaults to all) | -| `env` | object | Environment variables for the toolset | -| `toon` | string | Comma-delimited regex patterns matching tool names whose JSON outputs should be compressed. Reduces token usage by simplifying/compressing JSON responses from matched tools using automatic encoding. Example: `"search.*,list.*"` | -| `defer` | boolean or array | Control which tools load into initial context. Set to `true` to defer all tools, or array of tool names to defer specific tools. Deferred tools don't consume context until explicitly loaded via `search_tool`/`add_tool`. | - -### Tool selection - -By default, agents have access to all tools from their configured toolsets. You -can restrict this using the `tools` option: - -```yaml -toolsets: - - type: filesystem - tools: [read_file, write_file, list_directory] -``` - -This is useful for: - -- Limiting agent capabilities for security -- Reducing context size for smaller models -- Creating specialized agents with focused tool access - -### Deferred loading - -Deferred loading keeps tools out of the initial context window, loading them -only when explicitly requested. This is useful for large toolsets where most -tools won't be used, significantly reducing context consumption. - -Defer all tools in a toolset: - -```yaml -toolsets: - - type: mcp - command: npx - args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"] - defer: true # All tools load on-demand -``` - -Or defer specific tools while loading others immediately: - -```yaml -toolsets: - - type: mcp - command: npx - args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"] - defer: [search_files, list_directory] # Only these are deferred -``` - -Agents can discover deferred tools via `search_tool` and load them into context -via `add_tool` when needed. Best for toolsets with dozens of tools where only a -few are typically used. - -### Output compression - -The `toon` property compresses JSON outputs from matched tools to reduce token -usage. When a tool's output is JSON, it's automatically compressed using -efficient encoding before being returned to the agent: - -```yaml -toolsets: - - type: mcp - command: npx - args: ["-y", "@modelcontextprotocol/server-github"] - toon: "search.*,list.*" # Compress outputs from search/list tools -``` - -Useful for tools that return large JSON responses (API results, file listings, -search results). The compression is transparent to the agent but can -significantly reduce context consumption for verbose tool outputs. - -### Auto-installation of tool binaries - -MCP and LSP toolsets that require a binary command can be auto-installed if the -command isn't on your system. Docker Agent uses the -[aqua registry](https://github.com/aquaproj/aqua-registry), a curated index of -CLI tool packages, to resolve and download binaries. - -When a toolset with a `command` property is loaded, Docker Agent: - -1. Checks if the command exists in your `PATH`. -2. Checks the Docker Agent tools directory (`~/.cagent/tools/bin/`). -3. If still not found, looks up the command in the aqua registry and installs it. - -Installed binaries are stored under `~/.cagent/tools/`. You can override this -location with the `DOCKER_AGENT_TOOLS_DIR` environment variable. - -Use the `version` property to pin a specific package and version: - -```yaml -toolsets: - - type: lsp - command: gopls - version: "golang/tools@v0.21.0" - file_types: [".go"] - - - type: mcp - command: some-mcp-server - version: "owner/repo@v1.2.3" -``` - -The format is `owner/repo` or `owner/repo@version`. Without a version tag, -Docker Agent uses the latest release. Without the `version` property entirely, -Docker Agent tries to auto-detect the package from the command name. - -To disable auto-installation for a single toolset, set `version` to `"false"`: - -```yaml -toolsets: - - type: mcp - command: my-custom-server - version: "false" -``` - -To disable auto-installation globally, set the `DOCKER_AGENT_AUTO_INSTALL` -environment variable to `false`. - -### Per-agent tool configuration - -Different agents can have different toolsets: - -```yaml -agents: - coordinator: - model: anthropic/claude-sonnet-4-5 - sub_agents: [code_writer, code_reviewer] - toolsets: - - type: filesystem - tools: [read_file] - - code_writer: - model: openai/gpt-5-mini - toolsets: - - type: filesystem - - type: shell - - code_reviewer: - model: anthropic/claude-sonnet-4-5 - toolsets: - - type: filesystem - tools: [read_file, read_multiple_files] -``` - -This allows specialized agents with focused capabilities, security boundaries, -and optimized performance. - -## Built-in tools reference - -### Filesystem - -The `filesystem` toolset gives your agent the ability to work with -files and directories. Your agent can read files to understand -context, write new files, make targeted edits to existing files, -search for content, and explore directory structures. Essential for -code analysis, documentation updates, configuration management, and -any agent that needs to understand or modify project files. - -Access is restricted to the current working directory by default. Agents can -request access to additional directories at runtime, which requires your -approval. - -#### Configuration - -```yaml -toolsets: - - type: filesystem - - # Optional: restrict to specific tools - - type: filesystem - tools: [read_file, write_file, edit_file] -``` - -### LSP - -The `lsp` toolset connects your agent to -[Language Server Protocol](https://microsoft.github.io/language-server-protocol/) -servers, providing code intelligence like go-to-definition, find references, -diagnostics, rename, formatting, and more. - -You can configure multiple LSP servers for different programming languages, -giving your agent code intelligence across your project. - -#### Configuration - -```yaml -toolsets: - - type: lsp - command: gopls - file_types: [".go"] - - - type: lsp - command: typescript-language-server - args: ["--stdio"] - file_types: [".ts", ".tsx", ".js", ".jsx"] - - - type: lsp - command: pylsp - file_types: [".py"] -``` - -If an LSP server binary isn't in your PATH, Docker Agent can -[auto-install it](#auto-installation-of-tool-binaries) using the `version` -property. - -#### Properties - -| Property | Type | Required | Description | -| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | -| `command` | string | Yes | LSP server executable command | -| `args` | array of strings | No | Command-line arguments for the LSP server | -| `env` | object | No | Environment variables for the LSP server process | -| `file_types` | array of strings | No | File extensions this server handles (e.g., `[".go", ".mod"]`) | -| `version` | string | No | Package reference for auto-installing the server binary (e.g., `"golang/tools@v0.21.0"`). Set `"false"` to disable. | - -#### Available tools - -| Tool | Description | Read-only | -| ----------------------- | --------------------------------------------- | --------- | -| `lsp_workspace` | Get workspace info and available capabilities | Yes | -| `lsp_hover` | Get type info and documentation for a symbol | Yes | -| `lsp_definition` | Find where a symbol is defined | Yes | -| `lsp_references` | Find all references to a symbol | Yes | -| `lsp_document_symbols` | List all symbols in a file | Yes | -| `lsp_workspace_symbols` | Search symbols across the workspace | Yes | -| `lsp_diagnostics` | Get errors and warnings for a file | Yes | -| `lsp_code_actions` | Get available quick fixes and refactorings | Yes | -| `lsp_rename` | Rename a symbol across the workspace | No | -| `lsp_format` | Format a file | No | -| `lsp_call_hierarchy` | Find incoming and outgoing calls | Yes | -| `lsp_type_hierarchy` | Find supertypes and subtypes | Yes | -| `lsp_implementations` | Find interface implementations | Yes | -| `lsp_signature_help` | Get function signature at call site | Yes | -| `lsp_inlay_hints` | Get type annotations and parameter names | Yes | - -Not all LSP servers support all features. The agent uses `lsp_workspace` to -discover the capabilities of each configured server. - -#### Language server examples - -The following examples show configurations for common languages: - -| Language | Command | `file_types` | -| --------------------- | ---------------------------- | -------------------------------- | -| Go | `gopls` | `[".go"]` | -| TypeScript/JavaScript | `typescript-language-server` | `[".ts", ".tsx", ".js", ".jsx"]` | -| Python | `pylsp` | `[".py"]` | -| Rust | `rust-analyzer` | `[".rs"]` | -| C/C++ | `clangd` | `[".c", ".cpp", ".h", ".hpp"]` | - -For TypeScript/JavaScript, pass `args: ["--stdio"]` to the language server. - -### Shell - -The `shell` toolset lets your agent execute commands in your system's shell -environment. Use this for agents that need to run builds, execute tests, manage -processes, interact with CLI tools, or perform system operations. The agent can -run commands in the foreground or background. - -Commands execute in the current working directory and inherit environment -variables from the Docker Agent process. This toolset is powerful but should be used -with appropriate security considerations. - -#### Configuration - -```yaml -toolsets: - - type: shell -``` - -### Think - -The `think` toolset provides your agent with a reasoning scratchpad. The agent -can record thoughts and reasoning steps without taking actions or modifying -data. Particularly useful for complex tasks where the agent needs to plan -multiple steps, verify requirements, or maintain context across a long -conversation. - -Agents use this to break down problems, list applicable rules, verify they have -all needed information, and document their reasoning process before acting. - -#### Configuration - -```yaml -toolsets: - - type: think -``` - -### Todo - -The `todo` toolset gives your agent task-tracking capabilities for managing -multi-step operations. Your agent can break down complex work into discrete -tasks, track progress through each step, and ensure nothing is missed before -completing a request. Especially valuable for agents handling complex -workflows with multiple dependencies. - -The `shared` option allows todos to persist across different agents in a -multi-agent system, enabling coordination. - -#### Configuration - -```yaml -toolsets: - - type: todo - - # Optional: share todos across agents - - type: todo - shared: true -``` - -### Tasks - -The `tasks` toolset is an advanced version of the `todo` toolset, and provides -task management with priorities, dependencies, and persistence. Your agent can -create tasks with different priority levels, establish prerequisite -relationships between tasks, and automatically track which tasks are blocked by -incomplete dependencies. Tasks are sorted by priority and blocking status, -making it easy to identify the next actionable work. - -Tasks are stored in a JSON file and persist across Docker Agent sessions. - -#### Configuration - -```yaml -toolsets: - - type: tasks - - # Optional: specify storage location - - type: tasks - path: ./project-tasks.json -``` - -#### Available tools - -The tasks toolset provides these tools: - -- **create_task**: Create a new task with title, description, priority, and - dependencies -- **get_task**: Retrieve full details of a task by ID, including effective - status -- **update_task**: Modify task fields (title, description, priority, status, - dependencies) -- **delete_task**: Remove a task and clean up its dependencies -- **list_tasks**: List all tasks sorted by priority, optionally filtered by - status or priority -- **next_task**: Get the highest-priority actionable task (not blocked or done) -- **add_dependency**: Add a dependency between tasks (with cycle detection) -- **remove_dependency**: Remove a dependency from a task - -#### Task statuses and priorities - -Tasks have four statuses: `pending`, `in_progress`, `done`, and `blocked`. The -agent automatically calculates the effective status. A task becomes `blocked` -if any of its dependencies are not `done`, regardless of its assigned status. - -Priority levels (from highest to lowest): `critical`, `high`, `medium` -(default), `low`. Tasks are sorted by blocking status first (unblocked tasks -first), then by priority, then by creation time. - -### Memory - -The `memory` toolset allows your agent to store and retrieve information across -conversations and sessions. Your agent can remember user preferences, project -context, previous decisions, and other information that should persist. Useful -for agents that interact with users over time or need to maintain state about -a project or environment. - -Memories are stored in a local database file and persist across Docker Agent -sessions. - -#### Configuration - -```yaml -toolsets: - - type: memory - - # Optional: specify database location - - type: memory - path: ./agent-memories.db -``` - -### Fetch - -The `fetch` toolset enables your agent to retrieve content from HTTP/HTTPS URLs. -Your agent can fetch documentation, API responses, web pages, or any content -accessible via HTTP GET requests. Useful for agents that need to access -external resources, check API documentation, or retrieve web content. - -The agent can specify custom HTTP headers when needed for authentication or -other purposes. - -#### Configuration - -```yaml -toolsets: - - type: fetch -``` - -### User Prompt - -The `user_prompt` toolset lets your agent ask you questions during task -execution. When the agent needs clarification, decisions, or additional -information it can't determine on its own, it displays a dialog and waits for -your response. - -You'll see a prompt with the agent's question. Depending on what the agent -needs, you might provide free-form text, select from options, or fill out a -form with multiple fields. You can accept and provide the information, decline -to answer, or cancel the operation entirely. - -#### Configuration - -```yaml -toolsets: - - type: user_prompt -``` - -No additional configuration is required. The tool becomes available to the -agent once configured. When the agent calls this tool, the user sees a dialog -with the prompt. The user can: - -- **Accept**: Provide the requested information -- **Decline**: Refuse to provide the information -- **Cancel**: Cancel the operation - -### API - -The `api` toolset lets you define custom tools that call HTTP APIs. Similar to -`script` but for web services, this allows you to expose REST APIs, -webhooks, or any HTTP endpoint as a tool your agent can use. The agent sees -these as typed tools with automatic parameter validation. - -Use this to integrate with external services, call internal APIs, trigger -webhooks, or interact with any HTTP-based system. - -#### Configuration - -Each API tool is defined with an `api_config` containing the endpoint, HTTP method, and optional typed parameters: - -```yaml -toolsets: - - type: api - api_config: - name: search_docs - endpoint: https://api.example.com/search - method: GET - instruction: Search the documentation database - headers: - Authorization: Bearer ${API_TOKEN} - args: - query: - type: string - description: Search query - limit: - type: number - description: Maximum results - required: [query] - - - type: api - api_config: - name: create_ticket - endpoint: https://api.example.com/tickets - method: POST - instruction: Create a support ticket - args: - title: - type: string - description: Ticket title - description: - type: string - description: Ticket description - required: [title, description] -``` - -For GET requests, parameters are interpolated into the endpoint URL. For POST -requests, parameters are sent as JSON in the request body. - -Supported argument types: `string`, `number`, `boolean`, `array`, `object`. - -### Script - -The `script` toolset lets you define custom tools by wrapping shell -commands with typed parameters. This allows you to expose domain-specific -operations to your agent as first-class tools. The agent sees these custom -tools just like built-in tools, with parameter validation and type checking -handled automatically. - -Use this to create tools for deployment scripts, build commands, test runners, -or any operation specific to your project or workflow. - -#### Configuration - -Each custom tool is defined with a command, description, and optional typed -parameters: - -```yaml -toolsets: - - type: script - tools: - deploy: - cmd: ./deploy.sh - description: Deploy the application to an environment - args: - environment: - type: string - description: Target environment (dev, staging, prod) - version: - type: string - description: Version to deploy - required: [environment] - - run_tests: - cmd: npm test - description: Run the test suite - args: - filter: - type: string - description: Test name filter pattern -``` - -Supported argument types: `string`, `number`, `boolean`, `array`, `object`. - -#### Tools - -The tools you define become available to your agent. In the previous example, -the agent would have access to `deploy` and `run_tests` tools. - -## Automatic tools - -Some tools are automatically added to agents based on their configuration. You -don't configure these explicitly—they appear when needed. - -### transfer_task - -Automatically available when your agent has `sub_agents` configured. Allows -the agent to delegate tasks to sub-agents and receive results back. - -### handoff - -Automatically available when your agent has `handoffs` configured. Allows the -agent to transfer the entire conversation to a different agent. - -## What's next - -- Read the [Configuration file reference](./config.md) for YAML file structure -- Review the [CLI reference](./cli.md) for running agents -- Explore [MCP servers](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) for extended capabilities -- Browse [example configurations](https://github.com/docker/docker-agent/tree/main/examples) diff --git a/content/manuals/ai/docker-agent/sharing-agents.md b/content/manuals/ai/docker-agent/sharing-agents.md deleted file mode 100644 index 3dd282260ac9..000000000000 --- a/content/manuals/ai/docker-agent/sharing-agents.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Sharing agents -description: Distribute agent configurations through OCI registries -keywords: [docker agent, oci, registry, docker hub, sharing, distribution] -weight: 50 ---- - -Push your agent to a registry and share it by name. Your teammates -reference `agentcatalog/security-expert` instead of copying YAML files -around or asking you where your agent configuration lives. - -When you update the agent in the registry, everyone gets the new version -the next time they pull or restart their client. - -## Prerequisites - -To push agents to a registry, authenticate first: - -```console -$ docker login -``` - -For other registries, use their authentication method. - -## Publishing agents - -Push your agent configuration to a registry: - -```console -$ docker agent share push ./agent.yml myusername/agent-name -``` - -Push creates the repository if it doesn't exist yet. Use Docker Hub or -any OCI-compatible registry. - -Tag specific versions: - -```console -$ docker agent share push ./agent.yml myusername/agent-name:v1.0.0 -$ docker agent share push ./agent.yml myusername/agent-name:latest -``` - -## Using published agents - -Pull an agent to inspect it locally: - -```console -$ docker agent share pull agentcatalog/pirate -``` - -This saves the configuration as a local YAML file. - -Run agents directly from the registry: - -```console -$ docker agent run agentcatalog/pirate -``` - -Or reference it directly in integrations: - -### Editor integration (ACP) - -Use registry references in ACP configurations so your editor always uses -the latest version: - -```json -{ - "agent_servers": { - "myagent": { - "command": "docker", - "args": ["agent", "aserve", "acp", "agentcatalog/pirate"] - } - } -} -``` - -### MCP client integration - -Agents can be exposed as tools in MCP clients: - -```json -{ - "mcpServers": { - "myagent": { - "command": "docker", - "args": ["agent", "serve", "mcp", "agentcatalog/pirate"] - } - } -} -``` - -## What's next - -- Set up [ACP integration](./integrations/acp.md) with shared agents -- Configure [MCP integration](./integrations/mcp.md) with shared agents -- Browse the [agent catalog](https://hub.docker.com/u/agentcatalog) for examples diff --git a/content/manuals/ai/docker-agent/tutorial.md b/content/manuals/ai/docker-agent/tutorial.md deleted file mode 100644 index c8e23c538fce..000000000000 --- a/content/manuals/ai/docker-agent/tutorial.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Building a coding agent -description: Create a coding agent that can read, write, and validate code changes in your projects -keywords: [docker agent, tutorial, coding agent, ai assistant] -weight: 30 ---- - -This tutorial teaches you how to build a coding agent that can help with -software development tasks. You'll start with a basic agent and progressively -add capabilities until you have a production-ready assistant that can read code, -make changes, run tests, and even look up documentation. - -By the end, you'll understand how to structure agent instructions, configure -tools, and compose multiple agents for complex workflows. - -## What you'll build - -A coding agent that can: - -- Read and modify files in your project -- Run commands like tests and linters -- Follow a structured development workflow -- Look up documentation when needed -- Track progress through multi-step tasks - -## What you'll learn - -- How to configure agents in YAML with Docker Agents -- How to give agents access to tools (filesystem, shell, etc.) -- How to write effective agent instructions -- How to compose multiple agents for specialized tasks -- How to adapt agents for your own projects - -## Prerequisites - -Before starting, you need: - -- **Docker Agent installed** - See the [installation guide](_index.md#installation) -- **API key configured** - Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your - environment. Get keys from [Anthropic](https://console.anthropic.com/) or - [OpenAI](https://platform.openai.com/api-keys) -- **A project to work with** - Any codebase where you want agent assistance - -## Creating your first agent - -An agent is defined in a YAML configuration file. The minimal agent needs -just a model and instructions that define its purpose. - -Create a file named `agents.yml`: - -```yaml -agents: - root: - model: openai/gpt-5 - description: A basic coding assistant - instruction: | - You are a helpful coding assistant. - Help me write and understand code. -``` - -Run your agent: - -```console -$ docker agent run agents.yml -``` - -Try asking it: "How do I read a file in Python?" - -The agent can answer coding questions, but it can't see your files or run -commands yet. To make it useful for real development work, it needs access to -tools. - -## Adding tools - -A coding agent needs to interact with your project files and run commands. You -enable these capabilities by adding toolsets. - -Update `agents.yml` to add filesystem and shell access: - -```yaml -agents: - root: - model: openai/gpt-5 - description: A coding assistant with filesystem access - instruction: | - You are a helpful coding assistant. - You can read and write files to help me develop software. - Always check if code works before finishing a task. - toolsets: - - type: filesystem - - type: shell -``` - -Run the updated agent and try: "Read the README.md file and summarize it." - -Your agent can now: - -- Read and write files in the current directory -- Execute shell commands -- Explore your project structure - -> [!NOTE] By default, filesystem access is restricted to the current working -> directory. The agent will request permission if it needs to access other -> directories. - -The agent can now interact with your code, but its behavior is still generic. -Next, you'll teach it how to work effectively. - -## Structuring agent instructions - -Generic instructions produce generic results. For production use, you want your -agent to follow a specific workflow and understand your project's conventions. - -Update your agent with structured instructions. This example shows a Go -development agent, but you can adapt the pattern for any language: - -```yaml -agents: - root: - model: anthropic/claude-sonnet-4-5 - description: Expert Go developer - instruction: | - Your goal is to help with code-related tasks by examining, modifying, - and validating code changes. - - <TASK> - # Workflow: - # 1. Analyze: Understand requirements and identify relevant code. - # 2. Examine: Search for files, analyze structure and dependencies. - # 3. Modify: Make changes following best practices. - # 4. Validate: Run linters/tests. If issues found, return to Modify. - </TASK> - - Constraints: - - Be thorough in examination before making changes - - Always validate changes before considering the task complete - - Write code to files, don't show it in chat - - ## Development Workflow - - `go build ./...` - Build the application - - `go test ./...` - Run tests - - `golangci-lint run` - Check code quality - - add_date: true - add_environment_info: true - toolsets: - - type: filesystem - - type: shell - - type: todo -``` - -Try asking: "Add error handling to the `parseConfig` function in main.go" - -The structured instructions give your agent: - -- A clear workflow to follow (analyze, examine, modify, validate) -- Project-specific commands to run -- Constraints that prevent common mistakes -- Context about the environment (`add_date` and `add_environment_info`) - -The `todo` toolset helps the agent track progress through multi-step tasks. When -you ask for complex changes, the agent will break down the work and update its -progress as it goes. - -## Composing multiple agents - -Complex tasks often benefit from specialized agents. You can add sub-agents that -handle specific responsibilities, like researching documentation while your main -agent stays focused on coding. - -Add a librarian agent that can search for documentation: - -```yaml -agents: - root: - model: anthropic/claude-sonnet-4-5 - description: Expert Go developer - instruction: | - Your goal is to help with code-related tasks by examining, modifying, - and validating code changes. - - When you need to look up documentation or research how something works, - ask the librarian agent. - - (rest of instructions from previous section...) - toolsets: - - type: filesystem - - type: shell - - type: todo - sub_agents: - - librarian - - librarian: - model: anthropic/claude-haiku-4-5 - description: Documentation researcher - instruction: | - You are the librarian. Your job is to find relevant documentation, - articles, or resources to help the developer agent. - - Search the internet and fetch web pages as needed. - toolsets: - - type: mcp - ref: docker:duckduckgo - - type: fetch -``` - -Try asking: "How do I use `context.Context` in Go? Then add it to my server -code." - -Your main agent will delegate the research to the librarian, then use that -information to modify your code. This keeps the main agent's context focused on -the coding task while still having access to up-to-date documentation. - -Using a smaller, faster model (Haiku) for the librarian saves costs since -documentation lookup doesn't need the same reasoning depth as code changes. - -## Adapting for your project - -Now that you understand the core concepts, adapt the agent for your specific -project: - -### Update the development commands - -Replace the Go commands with your project's workflow: - -```yaml -## Development Workflow -- `npm test` - Run tests -- `npm run lint` - Check code quality -- `npm run build` - Build the application -``` - -### Add project-specific constraints - -If your agent keeps making the same mistakes, add explicit constraints: - -```yaml -Constraints: - - Always run tests before considering a task complete - - Follow the existing code style in src/ directories - - Never modify files in the generated/ directory - - Use TypeScript strict mode for new files -``` - -### Choose the right models - -For coding tasks, use reasoning-focused models: - -- `anthropic/claude-sonnet-4-5` - Strong reasoning, good for complex code -- `openai/gpt-5` - Fast, good general coding ability - -For auxiliary tasks like documentation lookup, smaller models work well: - -- `anthropic/claude-haiku-4-5` - Fast and cost-effective -- `openai/gpt-5-mini` - Good for simple tasks - -### Iterate based on usage - -The best way to improve your agent is to use it. When you notice issues: - -1. Add specific instructions to prevent the problem -2. Update constraints to guide behavior -3. Add relevant commands to the development workflow -4. Consider adding specialized sub-agents for complex areas - -## What you learned - -You now know how to: - -- Create a basic Docker Agent configuration -- Add tools to enable agent capabilities -- Write structured instructions for consistent behavior -- Compose multiple agents for specialized tasks -- Adapt agents for different programming languages and workflows - -## Next steps - -- Learn [best practices](best-practices.md) for handling large outputs, - structuring agent teams, and optimizing performance -- Integrate Docker Agent with your [editor](integrations/acp.md) or use agents as - [tools in MCP clients](integrations/mcp.md) -- Review the [Configuration reference](reference/config.md) for all available - options -- Explore the [Tools reference](reference/toolsets.md) to see what capabilities - you can enable -- Check out [example - configurations](https://github.com/docker/docker-agent/tree/main/examples) for - different use cases -- See the full - [golang_developer.yaml](https://github.com/docker/docker-agent/blob/main/golang_developer.yaml) - that the Docker Team uses to develop Docker Agent diff --git a/content/manuals/ai/gordon/_index.md b/content/manuals/ai/gordon/_index.md index 6b586e91c999..a2355c3afec2 100644 --- a/content/manuals/ai/gordon/_index.md +++ b/content/manuals/ai/gordon/_index.md @@ -67,7 +67,7 @@ Before you begin: > 1. Contact Docker Support to activate Gordon for your organization. Docker > will confirm when activation is complete. > 2. Once confirmed, an organization administrator must turn on Gordon via -> [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +> [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). > Set **Enable Gordon** to **Enabled** or **Always enabled**. Ensure all > Settings Management prerequisites are met for the setting to take effect > on Docker Desktop clients. diff --git a/content/manuals/ai/gordon/concepts/data-privacy.md b/content/manuals/ai/gordon/concepts/data-privacy.md index c69a709f6858..91f1d22a970b 100644 --- a/content/manuals/ai/gordon/concepts/data-privacy.md +++ b/content/manuals/ai/gordon/concepts/data-privacy.md @@ -2,6 +2,7 @@ title: Data privacy and Gordon linkTitle: Data privacy description: How Gordon handles your data and what information is collected +keywords: Gordon, data privacy, data retention, security weight: 30 --- @@ -43,21 +44,41 @@ Gordon has access to your Docker daemon's state, including: Gordon's data retention differs based on your subscription tier: -### Paid subscriptions (Pro, Team, Business) +### Paid subscriptions Docker and its AI providers do not retain any inputs or outputs from your Gordon sessions. Your queries, Gordon's responses, and any code or files -processed are not stored. +processed are not stored. This applies to all paid subscriptions: Docker +Desktop plans (Pro, Team, Business) and Gordon plans (Plus, Max, Ultra). -### Personal (free) subscription +### Base tier (free) -Anonymized conversation threads are stored for 30 days to improve the service. -Individual queries and responses are retained as part of your conversation history. +Anonymized conversation threads are stored for 5 days to help guarantee +quality of service and fight abuse. Individual queries and responses are +retained as part of your conversation history. ### All subscriptions Data is never used for training AI models or shared with third parties. All -data transferred to Gordon's backend is encrypted in transit. +data transferred to Gordon's backend is encrypted in transit. Docker's +third-party AI providers process requests under zero-data-retention +agreements: they don't store your prompts or Gordon's responses. + +## Sensitive data protection + +Gordon automatically detects and redacts secrets and other sensitive material +from your requests using [portcullis](https://github.com/docker/portcullis), +Docker's open source redaction library. Around 240 patterns are covered, +including: + +- Cloud provider credentials (AWS, GCP, Azure, and others) +- API tokens (GitHub, GitLab, Docker Hub, Slack, OpenAI, Stripe, and more) +- PEM private keys and JWTs +- Database connection-string passwords +- Payment card numbers, IBANs, and US Social Security numbers + +Detected values are replaced with `[REDACTED]` before your request is +processed. ## Data security @@ -65,17 +86,13 @@ Your data is protected through encryption in transit. For paid subscriptions, no persistent storage occurs—Gordon processes your requests and discards the data immediately. -For questions about privacy terms and conditions, review [Gordon's -Supplemental -Terms](https://www.docker.com/legal/docker-ai-supplemental-terms/). - ## Organizational data policies For Business subscriptions, administrators can enable or disable Gordon for their organization using Settings Management. Review your organization's data handling requirements before enabling Gordon. -See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) +See [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) for configuration details. ## Disabling Gordon @@ -92,7 +109,7 @@ Individual users: Business organizations: Administrators can disable Gordon for the entire organization using Settings -Management. See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) +Management. See [Settings Management](/desktop/enterprise/hardened-desktop/settings-management/) for details. ## Questions about privacy @@ -100,5 +117,5 @@ for details. For questions about Docker's privacy practices: - Review the [Docker Privacy Policy](https://www.docker.com/legal/privacy/) -- Read [Gordon's Supplemental Terms](https://www.docker.com/legal/docker-ai-supplemental-terms/) +- Read the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement/) - Contact Docker Support for specific concerns diff --git a/content/manuals/ai/gordon/how-to/configure-tools.md b/content/manuals/ai/gordon/how-to/configure-tools.md index 90c3b6ae11f7..d1eddcdfc055 100644 --- a/content/manuals/ai/gordon/how-to/configure-tools.md +++ b/content/manuals/ai/gordon/how-to/configure-tools.md @@ -77,5 +77,5 @@ Administrators can: - Lock tool configuration to prevent users from changing it - Set organization-wide tool policies -See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) +See [Settings Management](/desktop/enterprise/hardened-desktop/settings-management/) for details. diff --git a/content/manuals/ai/gordon/how-to/permissions.md b/content/manuals/ai/gordon/how-to/permissions.md index 3e08cfb3c58a..db9a41a2b66e 100644 --- a/content/manuals/ai/gordon/how-to/permissions.md +++ b/content/manuals/ai/gordon/how-to/permissions.md @@ -121,5 +121,5 @@ Available controls: For Business subscriptions, Gordon must be enabled by an administrator before users can access it. -See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) +See [Settings Management](/desktop/enterprise/hardened-desktop/settings-management/) for details. diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/_index.md b/content/manuals/ai/mcp-catalog-and-toolkit/_index.md deleted file mode 100644 index 724eef580045..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/_index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Docker MCP Catalog and Toolkit -linkTitle: MCP Catalog and Toolkit -params: - sidebar: - group: AI and agents - badge: - color: blue - text: Beta -weight: 20 -description: Learn about Docker's MCP catalog on Docker Hub -keywords: Docker, ai, mcp servers, ai agents, extension, docker desktop, llm, docker hub -grid: - - title: Get started with MCP Toolkit - description: Learn how to quickly install and use the MCP Toolkit to set up servers and clients. - icon: magnifying-glass-plus - link: /ai/mcp-catalog-and-toolkit/get-started/ - - title: MCP Catalog - description: Browse Docker's curated collection of verified MCP servers - icon: globe-alt - link: /ai/mcp-catalog-and-toolkit/catalog/ - - title: MCP Profiles - description: Organize servers into profiles for different projects and share configurations - icon: folder - link: /ai/mcp-catalog-and-toolkit/profiles/ - - title: MCP Toolkit - description: Use Docker Desktop's UI to discover, configure, and manage MCP servers - icon: /icons/toolkit.svg - link: /ai/mcp-catalog-and-toolkit/toolkit/ - - title: MCP Gateway - description: Use the CLI and Gateway to run MCP servers with custom configurations - icon: cpu-chip - link: /ai/mcp-catalog-and-toolkit/mcp-gateway/ - - title: Dynamic MCP - description: Discover and add MCP servers on-demand using natural language - icon: magnifying-glass - link: /ai/mcp-catalog-and-toolkit/dynamic-mcp/ - - title: Docker Hub MCP server - description: Use the Docker Hub MCP server to search images and manage repositories - icon: server-stack - link: /ai/mcp-catalog-and-toolkit/hub-mcp/ - - title: Security FAQs - description: Common questions about MCP security, credentials, and server verification - icon: shield-check - link: /ai/mcp-catalog-and-toolkit/faqs/ - - title: E2B sandboxes - description: Cloud sandboxes for AI agents with built-in MCP Catalog access - icon: cloud - link: /ai/mcp-catalog-and-toolkit/e2b-sandboxes/ ---- - -{{< summary-bar feature_name="Docker MCP Catalog and Toolkit" >}} - -[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is -an open protocol that standardizes how AI applications access external tools -and data sources. By connecting LLMs to local development tools, databases, -APIs, and other resources, MCP extends their capabilities beyond their base -training. - -The challenge is that running MCP servers locally creates operational friction. -Each server requires separate installation and configuration for every -application you use. You run untrusted code directly on your machine, manage -updates manually, and troubleshoot dependency conflicts yourself. Configure a -GitHub server for Claude, then configure it again for Cursor, and so on. Each -time you manage credentials, permissions, and environment setup. - -## Docker MCP features - -The [MCP Toolkit](/ai/mcp-catalog-and-toolkit/toolkit/) and [MCP -Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) solve these challenges -through centralized management. Instead of configuring each server for every AI -application separately, you set things up once and connect all your clients to -it. The workflow centers on three concepts: catalogs, profiles, and clients. - -![MCP overview](./images/mcp_toolkit.avif) - -[Catalogs](/ai/mcp-catalog-and-toolkit/catalog/) are curated collections of -MCP servers. The Docker MCP Catalog provides 300+ verified servers packaged as -container images with versioning, provenance, and security updates. Organizations -can create [custom -catalogs](/ai/mcp-catalog-and-toolkit/catalog/#custom-catalogs) with approved -servers for their teams. - -[Profiles](/ai/mcp-catalog-and-toolkit/profiles/) organize servers into named -collections for different projects. Your "web-dev" profile might use GitHub and -Playwright; your "backend" profile, database tools. Profiles support both -containerized servers from catalogs and remote MCP servers. Configure a profile -once, then share it across clients or with your team. - -Clients are the AI applications that connect to your profiles. Claude Code, -Cursor, Zed, and others connect through the MCP Gateway, which routes requests -to the right server and handles authentication and lifecycle management. - -## Learn more - -{{< grid >}} diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/cli.md b/content/manuals/ai/mcp-catalog-and-toolkit/cli.md deleted file mode 100644 index dd80b53564a6..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/cli.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Use MCP Toolkit from the CLI -linkTitle: Use with CLI -description: Manage MCP profiles, servers, and catalogs using Docker MCP CLI. -keywords: docker mcp, cli, profiles, servers, catalog, gateway -weight: 35 ---- - -{{< summary-bar feature_name="Docker MCP Toolkit" >}} - -> [!NOTE] -> The `docker mcp` commands documented here are available in Docker Desktop -> 4.62 and later. Earlier versions may not support all commands shown. - -The `docker mcp` commands let you manage MCP profiles, servers, OAuth -credentials, and catalogs from the terminal. Use the CLI for scripting, -automation, and headless environments. - -## Profiles - -### Create a profile - -```console -$ docker mcp profile create --name <profile-id> -``` - -The profile ID is used to reference the profile in subsequent commands: - -```console -$ docker mcp profile create --name web-dev -``` - -### List profiles - -```console -$ docker mcp profile list -``` - -### View a profile - -```console -$ docker mcp profile show <profile-id> -``` - -### Remove a profile - -```console -$ docker mcp profile remove <profile-id> -``` - -> [!CAUTION] -> Removing a profile deletes all its server configurations and settings. This -> action can't be undone. - -## Servers - -### Browse the catalog - -List available servers and their IDs: - -```console -$ docker mcp catalog server ls mcp/docker-mcp-catalog -``` - -The output lists each server by name. The name (for example, `playwright` or -`github-official`) is the server ID to use in `catalog://` URIs. - -To look up a server ID in Docker Desktop, open **MCP Toolkit** > **Catalog**, -select a server, and check the **Server ID** field. - -### Add servers to a profile - -Servers are referenced by URI. The URI format depends on where the server -comes from: - -| Format | Source | -| ------------------------------------- | -------------------------- | -| `catalog://<catalog-ref>/<server-id>` | An OCI catalog | -| `docker://<image>:<tag>` | A Docker image | -| `https://<url>/v0/servers/<uuid>` | The MCP community registry | -| `file://<path>` | A local YAML or JSON file | - -The most common format is `catalog://`, where `<catalog-ref>` matches the -**Catalog** field and `<server-id>` matches the **Server ID** field shown in -Docker Desktop or in the `catalog server ls` output: - -```console -$ docker mcp profile server add <profile-id> \ - --server catalog://<catalog-ref>/<server-id> -``` - -Add multiple servers in one command: - -```console -$ docker mcp profile server add web-dev \ - --server catalog://mcp/docker-mcp-catalog/github-official \ - --server catalog://mcp/docker-mcp-catalog/playwright -``` - -To add a server defined in a local YAML file: - -```console -$ docker mcp profile server add my-profile \ - --server file://./my-server.yaml -``` - -The YAML file defines the server image and configuration: - -```yaml -name: my-server -title: My Server -type: server -image: myimage:latest -description: Description of the server -``` - -If the server requires OAuth authentication, authorize it in Docker Desktop -after adding. See [OAuth authentication](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication). - -### List servers - -List all servers across all profiles: - -```console -$ docker mcp profile server ls -``` - -Filter by profile: - -```console -$ docker mcp profile server ls --filter profile=web-dev -``` - -### Remove a server - -```console -$ docker mcp profile server remove <profile-id> --name <server-name> -``` - -Remove multiple servers at once: - -```console -$ docker mcp profile server remove web-dev \ - --name github-official \ - --name playwright -``` - -### Configure server settings - -Set and retrieve configuration values for servers in a profile: - -```console -$ docker mcp profile config <profile-id> --set <server-id>.<key>=<value> -$ docker mcp profile config <profile-id> --get-all -$ docker mcp profile config <profile-id> --del <server-id>.<key> -``` - -Server configuration keys and their expected values are defined by each server. -Check the server's documentation or its entry in Docker Desktop under -**MCP Toolkit** > **Catalog** > **Configuration**. - -## Gateway - -Run the MCP Gateway with a specific profile: - -```console -$ docker mcp gateway run --profile <profile-id> -``` - -Omit `--profile` to use the default profile. - -### Connect a client manually - -To connect any client that isn't listed in Docker Desktop, configure it to run -the gateway over `stdio`. For example, in a JSON-based client configuration: - -```json -{ - "servers": { - "MCP_DOCKER": { - "command": "docker", - "args": ["mcp", "gateway", "run", "--profile", "web-dev"], - "type": "stdio" - } - } -} -``` - -For Claude Desktop, the format is: - -```json -{ - "mcpServers": { - "MCP_DOCKER": { - "command": "docker", - "args": ["mcp", "gateway", "run", "--profile", "web-dev"] - } - } -} -``` - -### Connect a named client - -Connect a supported client to a profile: - -```console -$ docker mcp client connect <client> --profile <profile-id> -``` - -For example, to connect VS Code to a project-specific profile: - -```console -$ docker mcp client connect vscode --profile my-project -``` - -This creates a `.vscode/mcp.json` file in the current directory. Because this -is a user-specific file, add it to `.gitignore`: - -```console -$ echo ".vscode/mcp.json" >> .gitignore -``` - -## Share profiles - -Share profiles with your team using OCI registries or version control. - -### Share via OCI registry - -Profiles are shared as OCI artifacts via any OCI-compatible registry. -Credentials are not included for security reasons. Team members configure -authentication credentials separately after pulling. - -To push an existing profile called `web-dev` to an OCI registry: - -```console -$ docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1 -``` - -To pull the same profile: - -```console -$ docker mcp profile pull registry.example.com/profiles/team-standard:latest -``` - -### Share via version control - -For project-specific profiles, you can use the `export` and `import` commands -and store the profiles in version control alongside your code. Team members can -import the file to get the same configuration. - -To export a profile to your project directory: - -```console -$ mkdir -p .docker -$ docker mcp profile export web-dev .docker/mcp-profile.json -``` - -Team members who clone the repository can import the profile: - -```console -$ docker mcp profile import .docker/mcp-profile.json -``` - -This creates a profile with the servers and configuration defined in the -file. Any authentication credentials must be configured separately if needed. - -## Custom catalogs - -Custom catalogs let you curate a focused collection of servers for your team -or organization. For an overview of what custom catalogs are and when to use -them, see [Custom catalogs](/manuals/ai/mcp-catalog-and-toolkit/catalog.md#custom-catalogs). - -Catalogs are referenced by OCI reference, for example -`registry.example.com/mcp/my-catalog:latest`. Servers within a catalog use -the same URI schemes as when -[adding servers to a profile](#add-servers-to-a-profile). - -### Customize the Docker catalog - -Use the Docker catalog as a base, then add or remove servers to fit your -organization's needs. Copy it first: - -```console -$ docker mcp catalog tag mcp/docker-mcp-catalog \ - registry.example.com/mcp/company-tools:latest -``` - -List the servers it contains: - -```console -$ docker mcp catalog server ls registry.example.com/mcp/company-tools:latest -``` - -Remove servers your organization doesn't approve: - -```console -$ docker mcp catalog server remove \ - registry.example.com/mcp/company-tools:latest \ - --name <server-name> -``` - -Add your own private servers, packaged as Docker images: - -```console -$ docker mcp catalog server add registry.example.com/mcp/company-tools:latest \ - --server docker://registry.example.com/mcp/internal-api:latest \ - --server docker://registry.example.com/mcp/data-pipeline:latest -``` - -Push when ready: - -```console -$ docker mcp catalog push registry.example.com/mcp/company-tools:latest -``` - -### Build a catalog from scratch - -To include exactly what you choose and nothing else, create a catalog from -scratch. You can include servers from the Docker catalog, your own private -images, or both. - -Create a catalog and specify which servers to include: - -```console -$ docker mcp catalog create registry.example.com/mcp/data-tools:latest \ - --title "Data Analysis Tools" \ - --server catalog://mcp/docker-mcp-catalog/sequentialthinking \ - --server catalog://mcp/docker-mcp-catalog/brave \ - --server docker://registry.example.com/mcp/analytics:latest -``` - -View the result: - -```console -$ docker mcp catalog show registry.example.com/mcp/data-tools:latest -``` - -Push to distribute: - -```console -$ docker mcp catalog push registry.example.com/mcp/data-tools:latest -``` - -### Distribute a catalog - -Push your catalog so team members can import it: - -```console -$ docker mcp catalog push <oci-reference> -``` - -Team members can pull it using the CLI: - -```console -$ docker mcp catalog pull <oci-reference> -``` - -Or import it using Docker Desktop: select **MCP Toolkit** > **Catalog** > -**Import catalog** and enter the OCI reference. - -### Use a custom catalog with the gateway - -Run the gateway with your catalog instead of the default Docker catalog: - -```console -$ docker mcp gateway run --catalog <oci-reference> -``` - -For [Dynamic MCP](/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md), where -agents discover and add servers during conversations, this limits what agents -can find to your curated set. - -To enable specific servers from your catalog without using a profile: - -```console -$ docker mcp gateway run --catalog <oci-reference> \ - --servers <name1> --servers <name2> -``` - -## Further reading - -- [Get started with MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/get-started.md) -- [MCP Profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md) -- [MCP Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) -- [MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md b/content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md deleted file mode 100644 index b3e2b0c1ff20..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md +++ /dev/null @@ -1,452 +0,0 @@ ---- -title: E2B sandboxes -description: Cloud-based secure sandboxes for AI agents with built-in Docker MCP Gateway integration -keywords: E2B, cloud sandboxes, MCP Gateway, AI agents, MCP Catalog -aliases: - - /ai/mcp-catalog-and-toolkit/sandboxes/ ---- - -Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. E2B sandboxes include direct access to Docker's [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools from publishers including GitHub, Notion, and Stripe. - -When you create a sandbox, you specify which MCP tools it should access. E2B launches these tools and provides access through the Docker MCP Gateway. - -## Example: Using GitHub and Notion MCP server - -This example demonstrates how to connect multiple MCP servers in an E2B sandbox. You'll analyze data in Notion and create GitHub issues using Claude. - -### Prerequisites - -Before you begin, make sure you have the following: - -- [E2B account](https://e2b.dev/docs/quickstart) with API access -- Anthropic API key for Claude - - > [!NOTE] - > This example uses Claude Code, which is pre-installed in E2B sandboxes. - > However, you can adapt the example to work with other AI assistants of your - > choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) - > for alternative connection methods. - -- Node.js 18+ installed on your machine -- Notion account with: - - A database containing sample data - - [Integration token](https://www.notion.com/help/add-and-manage-connections-with-the-api) -- GitHub account with: - - A repository for testing - - Personal access token with `repo` scope - -### Set up your environment - -Create a new directory and initialize a Node.js project: - -```console -$ mkdir mcp-e2b-quickstart -$ cd mcp-e2b-quickstart -$ npm init -y -``` - -Configure your project for ES modules by updating `package.json`: - -```json -{ - "name": "mcp-e2b-quickstart", - "version": "1.0.0", - "type": "module", - "scripts": { - "start": "node index.js" - } -} -``` - -Install required dependencies: - -```console -$ npm install e2b dotenv -``` - -Create a `.env` file with your credentials: - -```console -$ cat > .env << 'EOF' -E2B_API_KEY=your_e2b_api_key_here -ANTHROPIC_API_KEY=your_anthropic_api_key_here -NOTION_INTEGRATION_TOKEN=ntn_your_notion_integration_token_here -GITHUB_TOKEN=ghp_your_github_pat_here -EOF -``` - -Protect your credentials: - -```console -$ echo ".env" >> .gitignore -$ echo "node_modules/" >> .gitignore -``` - -### Create an E2B sandbox with MCP servers - -{{< tabs group="" >}} -{{< tab name="Typescript">}} - -Create a file named `index.ts`: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function quickstart(): Promise<void> { - console.log("Creating E2B sandbox with Notion and GitHub MCP servers...\n"); - - const sbx: Sandbox = await Sandbox.create({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY as string, - }, - mcp: { - notion: { - internalIntegrationToken: process.env - .NOTION_INTEGRATION_TOKEN as string, - }, - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN as string, - }, - }, - }); - - const mcpUrl = sbx.getMcpUrl(); - const mcpToken = await sbx.getMcpToken(); - - console.log("Sandbox created successfully!"); - console.log(`MCP Gateway URL: ${mcpUrl}\n`); - - // Wait for MCP initialization - await new Promise<void>((resolve) => setTimeout(resolve, 1000)); - - // Connect Claude to MCP gateway - console.log("Connecting Claude to MCP gateway..."); - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log("\nConnection successful! Cleaning up..."); - await sbx.kill(); -} - -quickstart().catch(console.error); -``` - -Run the script: - -```console -$ npx tsx index.ts -``` - -{{< /tab >}} -{{< tab name="Python">}} - -Create a file named `index.py`: - -```python -import os -import asyncio -from dotenv import load_dotenv -from e2b import Sandbox - -load_dotenv() - -async def quickstart(): - print("Creating E2B sandbox with Notion and GitHub MCP servers...\n") - - sbx = await Sandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - }, - mcp={ - "notion": { - "internalIntegrationToken": os.getenv("NOTION_INTEGRATION_TOKEN"), - }, - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - print("Sandbox created successfully!") - print(f"MCP Gateway URL: {mcp_url}\n") - - # Wait for MCP initialization - await asyncio.sleep(1) - - # Connect Claude to MCP gateway - print("Connecting Claude to MCP gateway...") - - def on_stdout(output): - print(output, end='') - - def on_stderr(output): - print(output, end='') - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout_ms=0, - on_stdout=on_stdout, - on_stderr=on_stderr - ) - - print("\nConnection successful! Cleaning up...") - await sbx.kill() - -if __name__ == "__main__": - try: - asyncio.run(quickstart()) - except Exception as e: - print(f"Error: {e}") - -``` - -Run the script: - -```console -$ python index.py -``` - -{{< /tab >}} -{{</tabs >}} - -You should see: - -```console -Creating E2B sandbox with Notion and GitHub MCP servers... - -Sandbox created successfully! -MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp - -Connecting Claude to MCP gateway... -Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp - -Connection successful! Cleaning up... -``` - -### Test with example workflow - -Now, test the setup by running a simple workflow that searches Notion and creates a GitHub issue. - -{{< tabs group="" >}} -{{< tab name="Typescript">}} - -> [!IMPORTANT] -> -> Replace `owner/repo` in the prompt with your actual GitHub username and repository -> name (for example, `yourname/test-repo`). - -Update `index.ts` with the following example: - -```typescript -import "dotenv/config"; -import { Sandbox } from "e2b"; - -async function exampleWorkflow(): Promise<void> { - console.log("Creating sandbox...\n"); - - const sbx: Sandbox = await Sandbox.create({ - envs: { - ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY as string, - }, - mcp: { - notion: { - internalIntegrationToken: process.env - .NOTION_INTEGRATION_TOKEN as string, - }, - githubOfficial: { - githubPersonalAccessToken: process.env.GITHUB_TOKEN as string, - }, - }, - }); - - const mcpUrl = sbx.getMcpUrl(); - const mcpToken = await sbx.getMcpToken(); - - console.log("Sandbox created successfully\n"); - - // Wait for MCP servers to initialize - await new Promise<void>((resolve) => setTimeout(resolve, 3000)); - - console.log("Connecting Claude to MCP gateway...\n"); - await sbx.commands.run( - `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - console.log("\nRunning example: Search Notion and create GitHub issue...\n"); - - const prompt: string = `Using Notion and GitHub MCP tools: -1. Search my Notion workspace for databases -2. Create a test issue in owner/repo titled "MCP Toolkit Test" with description "Testing E2B + Docker MCP integration" -3. Confirm both operations completed successfully`; - - await sbx.commands.run( - `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`, - { - timeoutMs: 0, - onStdout: console.log, - onStderr: console.log, - }, - ); - - await sbx.kill(); -} - -exampleWorkflow().catch(console.error); -``` - -Run the script: - -```console -$ npx tsx index.ts -``` - -{{< /tab >}} -{{< tab name="Python">}} - -Update `index.py` with this example: - -> [!IMPORTANT] -> -> Replace `owner/repo` in the prompt with your actual GitHub username and repository -> name (for example, `yourname/test-repo`). - -```python -import os -import asyncio -import shlex -from dotenv import load_dotenv -from e2b import Sandbox - -load_dotenv() - -async def example_workflow(): - print("Creating sandbox...\n") - - sbx = await Sandbox.beta_create( - envs={ - "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"), - }, - mcp={ - "notion": { - "internalIntegrationToken": os.getenv("NOTION_INTEGRATION_TOKEN"), - }, - "githubOfficial": { - "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"), - }, - }, - ) - - mcp_url = sbx.beta_get_mcp_url() - mcp_token = await sbx.beta_get_mcp_token() - - print("Sandbox created successfully\n") - - # Wait for MCP servers to initialize - await asyncio.sleep(3) - - print("Connecting Claude to MCP gateway...\n") - - def on_stdout(output): - print(output, end='') - - def on_stderr(output): - print(output, end='') - - await sbx.commands.run( - f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"', - timeout_ms=0, - on_stdout=on_stdout, - on_stderr=on_stderr - ) - - print("\nRunning example: Search Notion and create GitHub issue...\n") - - prompt = """Using Notion and GitHub MCP tools: -1. Search my Notion workspace for databases -2. Create a test issue in owner/repo titled "MCP Toolkit Test" with description "Testing E2B + Docker MCP integration" -3. Confirm both operations completed successfully""" - - # Escape single quotes for shell - escaped_prompt = prompt.replace("'", "'\\''") - - await sbx.commands.run( - f"echo '{escaped_prompt}' | claude -p --dangerously-skip-permissions", - timeout_ms=0, - on_stdout=on_stdout, - on_stderr=on_stderr - ) - - await sbx.kill() - -if __name__ == "__main__": - try: - asyncio.run(example_workflow()) - except Exception as e: - print(f"Error: {e}") -``` - -Run the script: - -```console -$ python workflow.py -``` - -{{< /tab >}} -{{</tabs >}} - -You should see: - -```console -Creating sandbox... - -Running example: Search Notion and create GitHub issue... - -## Task Completed Successfully - -I've completed both operations using the Notion and GitHub MCP tools: - -### 1. Notion Workspace Search - -Found 3 databases in your Notion workspace: -- **Customer Feedback** - Database with 12 entries tracking feature requests -- **Product Roadmap** - Planning database with 8 active projects -- **Meeting Notes** - Shared workspace with 45 pages - -### 2. GitHub Issue Creation - -Successfully created test issue: -- **Repository**: your-org/your-repo -- **Issue Number**: #47 -- **Title**: "MCP Test" -- **Description**: "Testing E2B + Docker MCP integration" -- **Status**: Open -- **URL**: https://github.com/your-org/your-repo/issues/47 - -Both operations completed successfully. The MCP servers are properly configured and working. -``` - -The sandbox connected multiple MCP servers and orchestrated a workflow across Notion and GitHub. You can extend this pattern to combine any of the 200+ MCP servers in the Docker MCP Catalog. - -## Related pages - -- [How to build an AI-powered code quality workflow with SonarQube and E2B](/guides/github-sonarqube-sandbox.md) -- [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/) -- [Docker Sandboxes](/manuals/ai/sandboxes/_index.md) -- [Docker MCP Toolkit and Catalog](/manuals/ai/mcp-catalog-and-toolkit/_index.md) -- [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) -- [E2B MCP documentation](https://e2b.dev/docs/mcp) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/faqs.md b/content/manuals/ai/mcp-catalog-and-toolkit/faqs.md deleted file mode 100644 index 6d803b1c97dd..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/faqs.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: MCP Toolkit FAQs -linkTitle: FAQs -description: Frequently asked questions related to MCP Catalog and Toolkit security -keywords: MCP, Toolkit, MCP server, MCP client, security, faq -tags: [FAQ] -weight: 70 ---- - -Docker MCP Catalog and Toolkit is a solution for securely building, sharing, and -running MCP tools. This page answers common questions about MCP Catalog and Toolkit security. - -### What process does Docker follow to add a new MCP server to the catalog? - -Developers can submit a pull request to the [Docker MCP Registry](https://github.com/docker/mcp-registry) to propose new servers. Docker provides detailed [contribution guidelines](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md) to help developers meet the required standards. - -Currently, a majority of the servers in the catalog are built directly by Docker. Each server includes attestations such as: - -- Build attestation: Servers are built on Docker Build Cloud. -- Source provenance: Verifiable source code origins. -- Signed SBOMs: Software Bill of Materials with cryptographic signatures. - -> [!NOTE] -> When using the images with [Docker MCP gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md), -> you can verify attestations at runtime using the `docker mcp gateway run ---verify-signatures` CLI command. - - -In addition to Docker-built servers, the catalog includes select servers from trusted registries such as GitHub and HashiCorp. Each third-party server undergoes a verification process that includes: - -- Pulling and building the code in an ephemeral build environment. -- Testing initialization and functionality. -- Verifying that tools can be successfully listed. - -### Under what conditions does Docker reject MCP server submissions? - -Docker rejects MCP server submissions that fail automated testing and validation processes during pull request review. Additionally, Docker reviewers evaluate submissions against specific requirements and reject MCP servers that don't meet these criteria. - -### Does Docker take accountability for malicious MCP servers in the Toolkit? - -Docker’s security measures currently represent a best-effort approach. While Docker implements automated testing, scanning, and metadata extraction for each server in the catalog, these security measures are not yet exhaustive. Docker is actively working to enhance its security processes and expand testing coverage. Enterprise customers can contact their Docker account manager for specific security requirements and implementation details. - -### How are credentials managed for MCP servers? - -Starting with Docker Desktop version 4.43.0, credentials are stored securely in the Docker Desktop VM. The storage implementation depends on the platform (for example, macOS, WSL2). You can manage the credentials using the following CLI commands: - -- `docker mcp secret ls` - List stored credentials -- `docker mcp secret rm` - Remove specific credentials -- `docker mcp oauth revoke` - Revoke OAuth-based credentials - -In the upcoming versions of Docker Desktop, Docker plans to support pluggable storage for these secrets and additional out-of-the-box storage providers to give users more flexibility in managing credentials. - -### Are credentials removed when an MCP server is uninstalled? - -No. MCP servers are not technically uninstalled since they exist as Docker containers pulled to your local Docker Desktop. Removing an MCP server stops the container but leaves the image on your system. Even if the container is deleted, credentials remain stored until you remove them manually. - -### Why don't I see remote MCP servers in the catalog? - -If remote MCP servers aren't visible in the Docker Desktop catalog, your local -catalog may be out of date. Remote servers are indicated by a cloud icon and -include services like GitHub, Notion, and Linear. - -Update your catalog by running: - -```console -$ docker mcp catalog update -``` - -After the update completes, refresh the **Catalog** tab in Docker Desktop. - -### What's the difference between profiles and the catalog? - -The [catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) is the source of -available MCP servers - a library of tools you can choose from. -[Profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md) are collections of -servers you've added to organize your work. Think of the catalog as a library, -and profiles as your personal bookshelves containing the books you've selected -for different purposes. - -### Can I share profiles with my team? - -Yes. Profiles can be pushed to OCI-compliant registries using -`docker mcp profile push my-profile registry.example.com/profiles/my-profile:v1`. -Team members can pull your profile with -`docker mcp profile pull registry.example.com/profiles/my-profile:v1`. Note -that credentials aren't included in shared profiles for security reasons - team -members need to configure OAuth and other credentials separately. - -### Do I need to create a profile to use MCP Toolkit? - -Yes, MCP Toolkit requires a profile to run servers. If you're upgrading from a -version before profiles were introduced, a default profile is automatically -created for you with your existing server configurations. You can create -additional named profiles to organize servers for different projects or -environments. - -### What happens to servers when I switch profiles? - -Each profile contains its own set of servers and configurations. When you run -the gateway with `--profile profile-name`, only servers in that profile are -available to clients. The default profile is used when no profile is specified. -Switching between profiles changes which servers your AI applications can -access. - -### Can I use the same server in multiple profiles? - -Yes. You can add the same MCP server to multiple profiles, each with different -configurations if needed. This is useful when you need the same server with -different settings for different projects or environments. - -## Related pages - -- [Get started with MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/get-started.md) -- [Open-source MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/get-started.md b/content/manuals/ai/mcp-catalog-and-toolkit/get-started.md deleted file mode 100644 index 4c2f8e8e6913..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/get-started.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -title: Get started with Docker MCP Toolkit -linkTitle: Get started -description: Learn how to quickly install and use the MCP Toolkit to set up servers and clients. -keywords: Docker MCP Toolkit, MCP server, MCP client, AI agents -weight: 5 -params: - test_prompt: Use the GitHub MCP server to show me my open pull requests ---- - -{{< summary-bar feature_name="Docker MCP Toolkit" >}} - -> [!NOTE] -> This page describes the MCP Toolkit interface in Docker Desktop 4.62 and -> later. Earlier versions have a different UI. Upgrade to follow these -> instructions exactly. - -The Docker MCP Toolkit makes it easy to set up, manage, and run containerized -Model Context Protocol (MCP) servers in profiles, and connect them to AI -agents. It provides secure defaults and support for a growing ecosystem of -LLM-based clients. This page shows you how to get started quickly with the -Docker MCP Toolkit. - -## Setup - -Before you begin, make sure you meet the following requirements to get started with Docker MCP Toolkit. - -1. Download and install the latest version of [Docker Desktop](/get-started/get-docker/). -2. Open the Docker Desktop settings and select **Beta features**. -3. Select **Enable Docker MCP Toolkit**. -4. Select **Apply**. - -The **Learning center** in Docker Desktop provides walkthroughs and resources -to help you get started with Docker products and features. On the **MCP -Toolkit** page, the **Get started** walkthrough guides you through installing -an MCP server, connecting a client, and testing your setup. - -Alternatively, follow the step-by-step instructions on this page: - -- [Create a profile](#create-a-profile) - Your workspace for organizing servers -- [Add MCP servers to your profile](#add-mcp-servers) - Select tools from the catalog -- [Connect clients](#connect-clients) - Link AI applications to your profile -- [Verify connections](#verify-connections) - Test that everything works - -Once configured, your AI applications can use all the servers in your profile. - -> [!TIP] -> Prefer working from the terminal? See [Use MCP Toolkit from the CLI](cli.md) -> for instructions on using the `docker mcp` commands. - -## Create a profile - -Profiles organize your MCP servers into collections. Create a profile for your -work: - -> [!NOTE] -> If you're upgrading from a previous version of MCP Toolkit, your existing -> server configurations are already in a `default` profile. You can continue -> using the default profile or create new profiles for different projects. - -1. In Docker Desktop, select **MCP Toolkit** and select the **Profiles** tab. -2. Select **Create profile**. -3. Enter a name for your profile (e.g., "Frontend development"). -4. Optionally, add servers and clients now, or add them later. -5. Select **Create**. - -Your new profile appears in the profiles list. - -## Add MCP servers - -1. In Docker Desktop, select **MCP Toolkit** and select the **Catalog** tab. -2. Browse the catalog and select the servers you want to add. -3. Select the **Add to** button and choose whether you want to add the servers - to an existing profile, or create a new profile. - -If a server requires configuration, a **Configuration Required** badge appears -next to the server's name. You must complete the mandatory configuration before -you can use the server. - -You've now successfully added MCP servers to your profile. Next, connect an MCP -client to use the servers in your profile. - -## Connect clients - -To connect a client to MCP Toolkit: - -1. In Docker Desktop, select **MCP Toolkit** and select the **Clients** tab. -2. Find your application in the list. -3. Select **Connect** to configure the client. - -If your client isn't listed, you can connect the MCP Toolkit manually over -`stdio` by configuring your client to run the gateway with your profile: - -```plaintext -docker mcp gateway run --profile my_profile -``` - -For example, if your client uses a JSON file to configure MCP servers, you may -add an entry like: - -```json {title="Example configuration" -{ - "servers": { - "MCP_DOCKER": { - "command": "docker", - "args": ["mcp", "gateway", "run", "--profile", "my_profile"], - "type": "stdio" - } - } -} -``` - -Consult the documentation of the application you're using for instructions on -how to set up MCP servers manually. - -## Verify connections - -Refer to the relevant section for instructions on how to verify that your setup -is working: - -- [Claude Code](#claude-code) -- [Claude Desktop](#claude-desktop) -- [OpenAI Codex](#codex) -- [Continue](#continue) -- [Cursor](#cursor) -- [Gemini](#gemini) -- [Goose](#goose) -- [LM Studio](#lm-studio) -- [OpenCode](#opencode) -- [Sema4.ai](#sema4) -- [Visual Studio Code](#vscode) -- [Zed](#zed) - -### Claude Code - -If you configured the MCP Toolkit for a specific project, navigate to the -relevant project directory. Then run `claude mcp list`. The output should show -`MCP_DOCKER` with a "connected" status: - -```console -$ claude mcp list -Checking MCP server health... - -MCP_DOCKER: docker mcp gateway run - ✓ Connected -``` - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```console -$ claude "{{% param test_prompt %}}" -``` - -### Claude Desktop - -Restart Claude Desktop and check the **Search and tools** menu in the chat -input. You should see the `MCP_DOCKER` server listed and enabled: - -![Claude Desktop](images/claude-desktop.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param test_prompt %}} -``` - -### Codex - -Run `codex mcp list` to view active MCP servers and their statuses. The -`MCP_DOCKER` server should appear in the list with an "enabled" status: - -```console -$ codex mcp list -Name Command Args Env Cwd Status Auth -MCP_DOCKER docker mcp gateway run - - enabled Unsupported -``` - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```console -$ codex "{{% param test_prompt %}}" -``` - -### Continue - -Launch the Continue terminal UI by running `cn`. Use the `/mcp` command to view -active MCP servers and their statuses. The `MCP_DOCKER` server should appear in -the list with a "connected" status: - -```plaintext - MCP Servers - - ➤ 🟢 MCP_DOCKER (🔧75 📝3) - 🔄 Restart all servers - ⏹️ Stop all servers - 🔍 Explore MCP Servers - Back - - ↑/↓ to navigate, Enter to select, Esc to go back -``` - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```console -$ cn "{{% param test_prompt %}}" -``` - -### Cursor - -Open Cursor. If you configured the MCP Toolkit for a specific project, open the -relevant project directory. Then navigate to **Cursor Settings > Tools & MCP**. -You should see `MCP_DOCKER` under **Installed MCP Servers**: - -![Cursor](images/cursor.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param test_prompt %}} -``` - -### Gemini - -Run `gemini mcp list` to view active MCP servers and their statuses. The -`MCP_DOCKER` should appear in the list with a "connected" status. - -```console -$ gemini mcp list -Configured MCP servers: - -✓ MCP_DOCKER: docker mcp gateway run (stdio) - Connected -``` - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```console -$ gemini "{{% param test_prompt %}}" -``` - -### Goose - -{{< tabs >}} -{{< tab name="Desktop app" >}} - -Open the Goose desktop application and select **Extensions** in the sidebar. -Under **Enabled Extensions**, you should see an extension named `Mcpdocker`: - -![Goose desktop app](images/goose.avif) - -{{< /tab >}} -{{< tab name="CLI" >}} - -Run `goose info -v` and look for an entry named `mcpdocker` under extensions. -The status should show `enabled: true`: - -```console -$ goose info -v -… - mcpdocker: - args: - - mcp - - gateway - - run - available_tools: [] - bundled: null - cmd: docker - description: The Docker MCP Toolkit allows for easy configuration and consumption of MCP servers from the Docker MCP Catalog - enabled: true - env_keys: [] - envs: {} - name: mcpdocker - timeout: 300 - type: stdio -``` - -{{< /tab >}} -{{< /tabs >}} - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param "test_prompt" %}} -``` - -### LM Studio - -Restart LM Studio and start a new chat. Open the integrations menu and look for -an entry named `mcp/mcp-docker`. Use the toggle to enable the server: - -![LM Studio](images/lm-studio.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param "test_prompt" %}} -``` - -### OpenCode - -The OpenCode configuration file (at `~/.config/opencode/opencode.json` by -default) contains the setup for MCP Toolkit: - -```json -{ - "mcp": { - "MCP_DOCKER": { - "type": "local", - "command": ["docker", "mcp", "gateway", "run"], - "enabled": true - } - }, - "$schema": "https://opencode.ai/config.json" -} -``` - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```console -$ opencode "{{% param "test_prompt" %}}" -``` - -### Sema4.ai Studio {#sema4} - -In Sema4.ai Studio, select **Actions** in the sidebar, then select the **MCP -Servers** tab. You should see Docker MCP Toolkit in the list: - -![Docker MCP Toolkit in Sema4.ai Studio](./images/sema4-mcp-list.avif) - -To use MCP Toolkit with Sema4.ai, add it as an agent action. Find the agent you -want to connect to the MCP Toolkit and open the agent editor. Select **Add -Action**, enable Docker MCP Toolkit in the list, then save your agent: - -![Editing an agent in Sema4.ai Studio](images/sema4-edit-agent.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param test_prompt %}} -``` - -### Visual Studio Code {#vscode} - -Open Visual Studio Code. If you configured the MCP Toolkit for a specific -project, open the relevant project directory. Then open the **Extensions** -pane. You should see the `MCP_DOCKER` server listed under installed MCP -servers. - -![MCP_DOCKER installed in Visual Studio Code](images/vscode-extensions.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param test_prompt %}} -``` - -### Zed - -Launch Zed and open agent settings: - -![Opening Zed agent settings from command palette](images/zed-cmd-palette.avif) - -Ensure that `MCP_DOCKER` is listed and enabled in the MCP Servers section: - -![MCP_DOCKER in Zed's agent settings](images/zed-agent-settings.avif) - -Test the connection by submitting a prompt that invokes one of your installed -MCP servers: - -```plaintext -{{% param test_prompt %}} -``` - -## Further reading - -- [MCP Profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md) -- [MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) -- [MCP Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) -- [MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md b/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md deleted file mode 100644 index 04c86f262424..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Docker Hub MCP server -linkTitle: Hub MCP server -description: The Docker Hub MCP Server makes Docker Hub image metadata accessible to LLMs for content discovery. -keywords: Docker Hub MCP Server, Hub MCP server, Hub MCP -weight: 60 ---- - -The Docker Hub MCP Server is a Model Context Protocol (MCP) server that -interfaces with Docker Hub APIs to make rich image metadata accessible to LLMs, -enabling intelligent content discovery and repository management. - -For more information about MCP concepts and how MCP servers work, see the [Docker MCP Catalog and Toolkit](index.md) overview page. - -## Key features - -- Advanced LLM context: Docker's MCP Server provides LLMs with detailed, structured context for Docker Hub images, enabling smarter, more relevant recommendations for developers, whether they're choosing a base image or automating CI/CD workflows. -- Natural language image discovery: Developers can find the right container image using natural language, no need to remember tags or repository names. Just describe what you need, and Docker Hub will return images that match your intent. -- Simplified repository management: Hub MCP Server enables agents to manage repositories through natural language fetching image details, viewing stats, searching content, and performing key operations quickly and easily. - -## Install Docker Hub MCP server - -1. From the **MCP Toolkit** menu, select the **Catalog** tab and search for **Docker Hub** and select the plus icon to add the Docker Hub MCP server. -1. In the server's **Configuration** tab, insert your Docker Hub username and personal access token (PAT). -1. In the **Clients** tab in MCP Toolkit, ensure Gordon is connected. -1. From the **Gordon** menu, you can now send requests related to your - Docker Hub account, in accordance to the tools provided by the Docker Hub MCP server. To test it, ask Gordon: - - ```text - What repositories are in my namespace? - ``` - -> [!TIP] -> By default, the Gordon [client](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md#install-an-mcp-client) is enabled, -> which means Gordon can automatically interact with your MCP servers. - -## Use Claude Desktop as a client - -1. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`: - - {{< tabs >}} - {{< tab name="For public repositories only">}} - - ```json - { - "mcpServers": { - "docker-hub": { - "command": "node", - "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"] - } - } - } - ``` - - Where : - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository - - {{< /tab >}} - {{< tab name="For authenticated access">}} - - ```json - { - "mcpServers": { - "docker-hub": { - "command": "node", - "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio", "--username=YOUR_DOCKER_HUB_USERNAME"], - "env": { - "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN" - } - } - } - } - ``` - - Where : - - `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username. - - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository - - - {{< /tab >}} - {{</tabs >}} - -1. Save the configuration file and completely restart Claude Desktop for the changes to take effect. - -## Usage with Visual Studio Code - -1. Add the Docker Hub MCP Server configuration to your User Settings (JSON) - file in Visual Studio Code. You can do this by opening the `Command Palette` and - typing `Preferences: Open User Settings (JSON)`. - - - {{< tabs >}} - {{< tab name="For public repositories only">}} - - ```json - { - "mcpServers": { - "docker-hub": { - "command": "node", - "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"] - } - } - } - ``` - - Where : - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository - - {{< /tab >}} - {{< tab name="For authenticated access">}} - - ```json - { - "mcpServers": { - "docker-hub": { - "command": "node", - "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"], - "env": { - "HUB_USERNAME": "YOUR_DOCKER_HUB_USERNAME", - "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN" - } - } - } - } - ``` - - Where : - - `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username. - - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository - - - {{< /tab >}} - {{</tabs >}} - -1. Open the `Command Palette` and type `MCP: List Servers`. -1. Select `docker-hub` and select `Start Server`. - -## Using other clients - -To integrate the Docker Hub MCP Server into your own development -environment, see the source code and installation instructions on the -[`hub-mcp` GitHub repository](https://github.com/docker/hub-mcp). - - -## Usage examples - -This section provides task-oriented examples for common operations with Docker Hub -tools. - -### Finding images - - -```console -# Search for official images -$ docker ai "Search for official nginx images on Docker Hub" - -# Search for lightweight images to reduce deployment size and improve performance -$ docker ai "Search for minimal Node.js images with small footprint" - -# Get the most recent tag of a base image -$ docker ai "Show me the latest tag details for go" - -# Find a production-ready database with enterprise features and reliability -$ docker ai "Search for production ready database images" - -# Compare Ubuntu versions to choose the right one for my project -$ docker ai "Help me find the right Ubuntu version for my project" -``` - -### Repository management - -```console -# Create a repository -$ docker ai "Create a repository in my namespace" - -# List all repositories in my namespace -$ docker ai "List all repositories in my namespace" - -# Find the largest repository in my namespace -$ docker ai "Which of my repositories takes up the most space?" - -# Find repositories that haven't been updated recently -$ docker ai "Which of my repositories haven't had any pushes in the last 60 days?" - -# Find which repositories are currently active and being used -$ docker ai "Show me my most recently updated repositories" - -# Get details about a repository -$ docker ai "Show me information about my '<repository-name>' repository" -``` - -### Pull/push images - - -```console -# Pull latest PostgreSQL version -$ docker ai "Pull the latest postgres image" - -# Push image to your Docker Hub repository -$ docker ai "Push my <image-name> to my <repository-name> repository" -``` - -### Tag management - -```console -# List all tags for a repository -$ $ docker ai "Show me all tags for my '<repository-name>' repository" - -# Find the most recently pushed tag -$ docker ai "What's the most recent tag pushed to my '<repository-name>' repository?" - -# List tags with architecture filtering -$ docker ai "List tags for in the '<repository-name>' repository that support amd64 architecture" - -# Get detailed information about a specific tag -$ docker ai "Show me details about the '<tag-name>' tag in the '<repository-name>' repository" - -# Check if a specific tag exists -$ docker ai "Check if version 'v1.2.0' exists for my 'my-web-app' repository" -``` - -### Docker Hardened Images - -```console -# List available hardened images -$ docker ai "What is the most secure image I can use to run a node.js application?" - -# Convert Dockerfile to use a hardened image -$ docker ai "Can you help me update my Dockerfile to use a docker hardened image instead of the current one" -``` -> [!NOTE] -> To access Docker Hardened Images, a subscription is required. If you're interested in using Docker Hardened Images, visit [Docker Hardened Images](https://www.docker.com/products/hardened-images/). - - -## Reference - -This section provides a comprehensive listing of the tools you can find -in the Docker Hub MCP Server. - -### Docker Hub MCP server tools - -Tools to interact with your Docker repositories and discover content on Docker Hub. - -| Name | Description | -|------|-------------| -| `check-repository` | Check repository | -| `check-repository-tag` | Check repository tag | -| `check-repository-tags` | Check repository tags | -| `create-repository` | Creates a new repository | -| `docker-hardened-images` | Lists available [Docker Hardened Images](https://www.docker.com/products/hardened-images/) in specified namespace | -| `get-namespaces` | Get organizations/namespaces for a user | -| `get-repository-dockerfile` | Gets Dockerfile for repository | -| `get-repository-info` | Gets repository info | -| `list-repositories-by-namespace` | Lists repositories under namespace | -| `list-repository-tags` | List repository tags | -| `read-repository-tag` | Read repository tag | -| `search` | Search content on Docker Hub | -| `set-repository-dockerfile` | Sets Dockerfile for repository | -| `update-repository-info` | Updates repository info | diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md b/content/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md deleted file mode 100644 index f88d16e2b75a..000000000000 --- a/content/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: MCP Gateway -linkTitle: Gateway -description: "Docker's MCP Gateway provides secure, centralized, and scalable orchestration of AI tools through containerized MCP servers, empowering developers, operators, and security teams." -keywords: MCP Gateway -weight: 40 -aliases: - - /ai/mcp-gateway/ ---- - -The MCP Gateway is Docker's open source solution for orchestrating Model -Context Protocol (MCP) servers. It acts as a centralized proxy between clients -and servers, managing configuration, credentials, and access control. - -When using MCP servers without the MCP Gateway, you need to configure -applications individually for each AI application. With the MCP Gateway, you -configure applications to connect to the Gateway. The Gateway then handles -server lifecycle, routing, and authentication across all servers in your -[profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md). - -> [!NOTE] -> If you use Docker Desktop with MCP Toolkit enabled, the Gateway runs -> automatically in the background. You don't need to start or configure it -> manually. This documentation is for users who want to understand how the -> Gateway works or run it directly for advanced use cases. - -> [!TIP] -> E2B sandboxes now include direct access to the Docker MCP Catalog, giving developers -> access to over 200 tools and services to seamlessly build and run AI agents. For -> more information, see [E2B Sandboxes](sandboxes.md). - -## How it works - -MCP Gateway runs MCP servers in isolated Docker containers with restricted -privileges, network access, and resource usage. It includes built-in logging -and call-tracing capabilities to ensure full visibility and governance of AI -tool activity. - -The MCP Gateway manages the server's entire lifecycle. When an AI application -needs to use a tool, it sends a request to the Gateway. The Gateway identifies -which server handles that tool and, if the server isn't already running, starts -it as a Docker container. The Gateway then injects any required credentials, -applies security restrictions, and forwards the request to the server. The -server processes the request and returns the result through the Gateway back to -the AI application. - -The MCP Gateway solves a fundamental problem: MCP servers are just programs -that need to run somewhere. Running them directly on your machine means dealing -with installation, dependencies, updates, and security risks. By running them -as containers managed by the Gateway, you get isolation, consistent -environments, and centralized control. - -The Gateway works with profiles to determine which servers are available. When -you run the Gateway, you specify which profile to use with the `--profile` flag -to determine which servers are made available to clients. - -## Usage - -To use the MCP Gateway, you'll need Docker Desktop with MCP Toolkit enabled. -Follow the [MCP Toolkit guide](toolkit.md) to enable and configure servers -through the Docker Desktop interface, or see -[Use MCP Toolkit from the CLI](cli.md) for terminal-based workflows. - -### Install the MCP Gateway manually - -For Docker Engine without Docker Desktop, you'll need to download and install -the MCP Gateway separately before you can run it. - -1. Download the latest binary from the [GitHub releases page](https://github.com/docker/mcp-gateway/releases/latest). - -2. Move or symlink the binary to the destination matching your OS: - - | OS | Binary destination | - | ------- | ----------------------------------- | - | Linux | `~/.docker/cli-plugins/docker-mcp` | - | macOS | `~/.docker/cli-plugins/docker-mcp` | - | Windows | `%USERPROFILE%\.docker\cli-plugins` | - -3. Make the binaries executable: - - ```bash - $ chmod +x ~/.docker/cli-plugins/docker-mcp - ``` - -You can now use the `docker mcp` command: - -```bash -docker mcp --help -``` - -## Additional information - -For more details on how the MCP Gateway works and available customization -options, see the complete documentation [on GitHub](https://github.com/docker/mcp-gateway). diff --git a/content/manuals/ai/model-runner/_index.md b/content/manuals/ai/model-runner/_index.md index 8ca4c4bb2332..9c1ad509b530 100644 --- a/content/manuals/ai/model-runner/_index.md +++ b/content/manuals/ai/model-runner/_index.md @@ -117,9 +117,26 @@ See [Configuration options](configuration.md) for details on context size and ot > Using Testcontainers or Docker Compose? > [Testcontainers for Java](https://java.testcontainers.org/modules/docker_model_runner/) > and [Go](https://golang.testcontainers.org/modules/dockermodelrunner/), and -> [Docker Compose](/manuals/ai/compose/models-and-compose.md) support Docker +> [Docker Compose](/manuals/compose/how-tos/models-and-compose.md) support Docker > Model Runner. +## Security and isolation + +### Execution environment + +Docker Model Runner isolates inference engines from your host: + +- On Linux, Docker Model Runner and its inference engines, such as Diffusers, + run inside a container, which provides the isolation boundary. +- On macOS and Windows, the engines don't run inside a container, so Docker + Model Runner runs them in a sandboxed environment (seatbelt/sandbox-exec and Job Objects respectively) + +### Networking + +The Model Runner API is not authenticated. Any client that can reach it, +including other containers on the same Docker network, can pull, load, and +run models, and send inference requests. + ## Known issues ### `docker model` is not recognised diff --git a/content/manuals/ai/model-runner/configuration.md b/content/manuals/ai/model-runner/configuration.md index 89934e97a7ca..ae6fea4a6d4d 100644 --- a/content/manuals/ai/model-runner/configuration.md +++ b/content/manuals/ai/model-runner/configuration.md @@ -285,7 +285,7 @@ You can also configure models via environment variables in containers: | `LLM_URL` | Auto-injected URL of the model endpoint | | `LLM_MODEL` | Auto-injected model identifier | -See [Models and Compose](/manuals/ai/compose/models-and-compose.md) for details on how these are populated. +See [Models and Compose](/manuals/compose/how-tos/models-and-compose.md) for details on how these are populated. ## Reset configuration @@ -302,4 +302,4 @@ Using `-1` resets to the default value. - [Inference engines](inference-engines.md) - Learn about llama.cpp and vLLM - [API reference](api-reference.md) - API parameters for per-request configuration -- [Models and Compose](/manuals/ai/compose/models-and-compose.md) - Configure models in Compose applications +- [Models and Compose](/manuals/compose/how-tos/models-and-compose.md) - Configure models in Compose applications diff --git a/content/manuals/ai/model-runner/examples.md b/content/manuals/ai/model-runner/examples.md index 1570b07285f0..4dd92b1f4532 100644 --- a/content/manuals/ai/model-runner/examples.md +++ b/content/manuals/ai/model-runner/examples.md @@ -189,4 +189,4 @@ jobs: ## Related pages -- [Models and Compose](../compose/models-and-compose.md) +- [Models and Compose](/manuals/compose/how-tos/models-and-compose.md) diff --git a/content/manuals/ai/model-runner/get-started.md b/content/manuals/ai/model-runner/get-started.md index aece1e2761d4..c3ddb7c688a2 100644 --- a/content/manuals/ai/model-runner/get-started.md +++ b/content/manuals/ai/model-runner/get-started.md @@ -70,11 +70,9 @@ then reinstall it: ```bash docker model uninstall-runner --images && docker model install-runner ``` - > [!NOTE] -> With the above command, local models are preserved. -> To delete the models during the upgrade, add the `--models` option to the -> `uninstall-runner` command. +> With the above command, local models are preserved and only the Docker Model Runner images are removed. +> To also delete the local models during the upgrade, add the `--models` option to the `uninstall-runner` command. ## Pull a model @@ -132,7 +130,7 @@ Use the [`docker model run` command](/reference/cli/docker/model/run/). You can configure a model, such as its maximum token limit and more, use Docker Compose. -See [Models and Compose - Model configuration options](../compose/models-and-compose.md#model-configuration-options). +See [Models and Compose - Model configuration options](/manuals/compose/how-tos/models-and-compose.md#model-configuration-options). ## Publish a model @@ -221,5 +219,5 @@ In Docker Desktop, to inspect the requests and responses for each model: - [Inference engines](./inference-engines.md) - llama.cpp and vLLM details - [IDE integrations](./ide-integrations.md) - Connect Cline, Continue, Cursor, and more - [Open WebUI integration](./openwebui-integration.md) - Set up a web chat interface -- [Models and Compose](../compose/models-and-compose.md) - Use models in Compose applications +- [Models and Compose](/manuals/compose/how-tos/models-and-compose.md) - Use models in Compose applications - [Docker Model Runner CLI reference](/reference/cli/docker/model) - Complete CLI documentation \ No newline at end of file diff --git a/content/manuals/ai/sandboxes-api/_index.md b/content/manuals/ai/sandboxes-api/_index.md new file mode 100644 index 000000000000..544eafc937d1 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/_index.md @@ -0,0 +1,55 @@ +--- +title: Docker Sandboxes API and SDK +linkTitle: Sandboxes API and SDK +description: Use the Docker Sandboxes API and TypeScript SDK to manage cloud sandboxes programmatically. +keywords: docker sandboxes API, cloud sandboxes API, sandbox SDK, TypeScript SDK, JavaScript +weight: 15 +params: + apiReferenceBanner: false + sidebar: + group: AI and agents +aliases: + - /ai/sandboxes/api/ +--- + +Use the Docker Sandboxes API to create cloud sandboxes, run commands, and +transfer files from your applications and automated workflows. You can also +manage related resources, including images, snapshots, volumes, and secrets. + +To try it, [run your first cloud sandbox](get-started.md) with the TypeScript +SDK. The tutorial uses a bundled kit that supplies a shell environment for +running commands. + +## Activate cloud access + +To use the API or SDK, [activate a Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access). +Use the same Docker account to [authenticate your application](authentication.md). + +Cloud compute is billed separately from your Docker subscription. See +[Billing](/manuals/agentic-platform/signup.md#billing) for details. + +## Choose an interface + +Use the TypeScript SDK in your JavaScript or TypeScript application. The SDK +provides typed requests and responses, waits for sandboxes to start or stop, +and handles file transfers and interactive processes. +See [Install the SDK](install.md) for installation instructions. + +You can also call the REST API directly from any language or HTTP tool. +See the [API reference](/reference/api/sandboxes/latest/) for operations, +request fields, responses, and the downloadable OpenAPI specification. + +To run agents from your terminal, see [Docker Sandboxes](../sandboxes/_index.md). + +## Develop your application + +- [SDK cookbook](cookbook/_index.md): follow examples for processes, files, + storage, networking, and other sandbox operations. +- [API concepts](concepts.md): choose a kit or image, identify resources, and + wait for actions to finish. +- [Authentication and authorization](authentication.md): authenticate requests + and understand which permissions your application needs. +- [Errors and retries](errors.md): handle failures and retry requests without + duplicating work. +- [Compute sizes and limits](limits.md): choose resources and handle account + quotas and request rate limits. diff --git a/content/manuals/ai/sandboxes-api/authentication.md b/content/manuals/ai/sandboxes-api/authentication.md new file mode 100644 index 000000000000..fa4b357f671b --- /dev/null +++ b/content/manuals/ai/sandboxes-api/authentication.md @@ -0,0 +1,158 @@ +--- +title: Authentication and authorization +description: >- + Authenticate requests to the Docker Sandboxes API with a personal + access token or browser sign-in, and learn which permissions your + application needs. +keywords: >- + docker sandboxes API authentication, sandbox authorization, bearer + token, sandbox permissions, personal access token, PAT, sandbox:use, + Allow Cloud Sandboxes access, Cloud Sandboxes +weight: 30 +aliases: + - /ai/sandboxes/api/authentication/ +--- + +Use browser sign-in when running an application interactively, or a personal +access token (PAT) for automation. The SDK obtains short-lived access tokens +and renews them as needed. + +You need an active [Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access). +Authenticate with the Docker account you used to subscribe. + +## Sign in through your browser + +Use the OAuth helper to sign in with your Docker account: + +```typescript +import { oauth, Sandboxes } from '@docker/sandboxes'; + +const auth = oauth({ + onVerification({ verificationUriComplete, verificationUri, userCode }) { + console.log(`Open ${verificationUriComplete ?? verificationUri}`); + console.log(`Verification code: ${userCode}`); + }, +}); +await auth.getAccessToken(); +const client = new Sandboxes({ auth }); +``` + +Open the printed URL and complete sign-in. Browser sign-in supports single +sign-on and two-factor authentication. The `getAccessToken()` call waits for +you to finish before the program continues. + +The SDK keeps credentials in memory and refreshes them while your application +runs. With the default configuration, you sign in again each time you start +the application. SDK sign-in is separate from `docker login` and `sbx login`. + +## Authenticate automation with a PAT + +Use a [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) +for CI jobs and unattended applications. When creating the token, select +**Allow Cloud Sandboxes access**. That grants the `sandbox:use` scope. The +same token can also have a repository permission, for example to push +images and use Cloud Sandboxes. Registry permissions alone don't grant +Cloud Sandboxes access. + +Provide your Docker ID and PAT to the SDK. For example, read them from your +application's environment: + +```typescript +import { pat, Sandboxes } from '@docker/sandboxes'; + +const username = process.env.DOCKER_ID; +const personalAccessToken = process.env.DOCKER_PAT; +if (!username || !personalAccessToken) { + throw new Error('Set DOCKER_ID and DOCKER_PAT'); +} + +const client = new Sandboxes({ + auth: pat({ username, personalAccessToken }), +}); +``` + +The SDK exchanges the PAT for a short-lived access token and repeats the +exchange when needed. If the PAT is invalid or revoked, authentication fails. + +Store the PAT in your CI or application's secret store and keep it out of +source control and logs. + +## Authenticate agents + +An AI agent needs credentials for its model provider in addition to your +Docker sign-in. For example, Claude Code can use an Anthropic API key, and +Codex can use an OpenAI API key. + +Store the provider key as a secret and attach it when creating the sandbox. +For example, with an authenticated `client` and an Anthropic API key in +`providerKey`: + +```typescript +const secret = await client.secrets.create({ + displayName: 'anthropic-key', + serviceType: 'anthropic', + token: { value: providerKey }, +}); + +const sandbox = await client.kits.launchAndWait('claude', { + storage: { secrets: [secret.name] }, +}); +``` + +The secret is attached before the agent runs. Keep the key out of command +arguments, source files, and plain environment variables inside the sandbox. + +## Resource access and permissions + +Your credentials determine which account's resources you can access. Cloud +uses them to identify the account, so leave the optional `parent` field empty +in requests. + +Each request also checks whether you have permission for the action on the +target resource. For example, creating a sandbox requires `sandboxesCreate`, +reading it requires `sandboxesRead`, and deleting it requires +`sandboxesDelete`. + +Account permissions also control access to optional features. See +[Supported Cloud options](concepts.md#choose-supported-cloud-options). + +## Authenticate direct API requests + +If you call the REST API without the SDK, obtain and renew access tokens in +your application. Exchange your Docker ID and a PAT with the `sandbox:use` +scope using the [Docker Hub authentication API](/reference/api/hub/latest/operations/AuthCreateAccessToken/): + +```console +$ ACCESS_TOKEN=$(curl --silent --show-error --fail --request POST \ + --url https://hub.docker.com/v2/auth/token \ + --header "Content-Type: application/json" \ + --data '{"identifier":"<DOCKER_ID>","secret":"<PERSONAL_ACCESS_TOKEN>"}' \ + | jq -er '.access_token') +``` + +Send the returned access token in the `Authorization` header when calling +`https://connect.docker.com/sandboxes`: + +```http +Authorization: Bearer <access_token> +``` + +The Sandboxes API accepts the access token returned by the exchange, not the +PAT itself. + +If you manage access tokens but use the SDK for requests, import `bearer` from +`@docker/sandboxes` and configure the client with `auth: bearer(accessToken)`. +Create a client with a fresh token when the previous token expires. + +## Authenticate sandbox requests + +The SDK handles authentication when you run commands or transfer files using +a sandbox's methods. It obtains a token scoped to that sandbox and the +operation, then reuses or renews the token as needed. + +For example, running a command requires `sandboxesExec` and obtaining its +token requires `sandboxesCredential`. Your account must have both permissions. + +If you call a sandbox endpoint directly, use a token issued for that sandbox. +Don't send the Docker Hub token used for management requests to a sandbox +endpoint. See [Management and sandbox endpoints](concepts.md#management-and-sandbox-endpoints). diff --git a/content/manuals/ai/sandboxes-api/concepts.md b/content/manuals/ai/sandboxes-api/concepts.md new file mode 100644 index 000000000000..5ff96002ae97 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/concepts.md @@ -0,0 +1,196 @@ +--- +title: Docker Sandboxes API concepts +linkTitle: API concepts +description: Learn how kits and images define a cloud sandbox, how to connect to it, and how to manage resources throughout their lifecycle. +keywords: docker sandboxes API concepts, sandbox kits, sandbox images, cloud sandbox endpoint, API operations +weight: 20 +aliases: + - /ai/sandboxes/api/concepts/ +--- + +An application uses the Docker Sandboxes API to create sandboxes, connect to +them, and track their state. Choose the environment for your sandbox, then +learn how to work with its resources throughout their lifecycle. + +## Kits and sandbox images + +A sandbox kit defines an environment for an agent or tool, including its +image, setup, network rules, and credential requirements. The SDK bundles a +catalog of kits you can launch by name. Using kits from other sources +requires preparing their content for the API. + +You can also create a sandbox from a container image. Choose the source based +on how much of the environment you want to configure yourself: + +| Source | What it provides | How to create a sandbox | +| --- | --- | --- | +| [Bundled kit](#bundled-kits) | An image reference and configuration included in the SDK's catalog | `client.kits.launch('shell')` | +| Custom kit | An environment defined by a kit you obtain separately | `client.create()` with [prepared kit artifacts](#supply-kit-artifacts) | +| Registry image (`imageRef`) | A container image to use with your own sandbox settings | `client.create({ imageRef: 'ubuntu:24.04', resources: 'small' })` | +| Image resource (`image`) | An image already prepared for Cloud Sandboxes, including its compute settings | `client.create({ image: 'images/<uid>' })` | + +The `imageRef` value is an image name in a registry. The `image` value is a +resource name returned by the Sandboxes API. When you use `image`, omit +`resources` because the image resource supplies its compute settings. + +These creation methods don't wait for the sandbox to be running. See +[Wait for an action to finish](#wait-for-an-action-to-finish) before running +commands. + +### Bundled kits + +The npm package includes the following kit definitions and supporting files. +Launch a bundled kit by its short name, such as `shell`: + +| Kit name | Environment | +| --- | --- | +| `shell` | A shell environment for running your own commands | +| `claude` | Claude Code | +| `codex` | Codex | +| `cursor` | Cursor | +| `devin` | Devin | +| `docker-agent` | Docker Agent | +| `gemini` | Gemini CLI | +| `opencode` | OpenCode | + +For example, `client.kits.launchAndWait('shell')` creates a shell sandbox and +waits until it's running. The kit launch helpers default to `small` compute, +with two CPUs and 4 GiB of memory. See [Compute sizes](limits.md#compute-sizes) +to choose a different size. + +Bundled kits are tied to the SDK release. Call `client.kits.list()` to see +the catalog in your installed version. The kit definitions are included in +the npm package, so the SDK doesn't download them from a registry. Cloud +Sandboxes pulls their referenced container images as needed. + +To run an AI agent, provide credentials for its model provider, such as an +Anthropic API key for Claude Code. See +[Authenticate agents](authentication.md#authenticate-agents). The `shell` kit +needs no provider key to run commands. + +## Resource names + +Use a resource's returned `name` to refer to it in later requests. A sandbox +name has the form `sandboxes/<uid>`. Pass the complete name, including the +`sandboxes/` prefix, when reading or deleting it. + +The server assigns the name, which stays the same throughout the resource's +lifetime. The optional `displayName` is a label you can change without +changing the resource's identity. + +## Wait for an action to finish + +Wait until a sandbox is running before sending commands to it. In the SDK, +`client.kits.launchAndWait()` creates a bundled kit's sandbox and waits for it +to run. If you use `client.create()` or `client.kits.launch()`, call +`waitUntilRunning()` on the returned sandbox and use the result to run commands. + +For direct API requests, HTTP 202 means the action was accepted and is still +in progress. Read the resource repeatedly until it reaches the state you need. + +Sandbox creation can continue after your client stops waiting. Read the +sandbox again to check its state, and inspect its `failure` field if it has +failed. See [Errors and retries](errors.md) for how to recover. + +Deletion can also take time. The API returns HTTP 202 while the sandbox is +being deleted and HTTP 204 when deletion is complete. After deletion, +authorized reads return `notFound`. + +### Wait for kit setup + +`waitUntilRunning()` and `kits.launchAndWait()` wait for the sandbox to reach +the `running` state. Kit setup commands, such as installing tools or cloning +a repository, can still be running at that point. + +The SDK doesn't provide a helper that waits for all kit setup to finish. If +your application depends on that setup, add a readiness check before starting +its work. What you check depends on the kit and the task—for example, a +completion marker written after a repository clone finishes, or a successful +health check from a service. + +Poll with a delay between checks and a timeout so your application stops +waiting if setup fails. + +## Management and sandbox endpoints + +Creating a sandbox and running a command inside it use different endpoints: + +| Endpoint | Use it to | +| --- | --- | +| Management API at `https://connect.docker.com/sandboxes` | Create, inspect, and delete sandboxes and manage related resources. | +| Sandbox API at the returned `core.endpoint.uri` | Run processes and read or write files inside that sandbox. | + +The SDK builds request URLs from these base URLs. If you make HTTP requests +directly, append the `/v1` route to the base URL, preserving any existing path. +For example, the management route `/v1/sandboxes` becomes +`https://connect.docker.com/sandboxes/v1/sandboxes`. + +Each sandbox endpoint requires a token that grants access to that sandbox. +The SDK obtains this token when you use a sandbox's process or file methods. See +[Authentication and authorization](authentication.md) for details. + +A sandbox's endpoint can change when its runtime changes. Read the sandbox +resource again before reconnecting to get its endpoint. + +## Read all results from a list + +List requests return one page of results at a time. To retrieve the next page, +pass the response's `nextPageToken` as the next request's `pageToken`. Keep the +same page size, filter, and ordering. Continue until `nextPageToken` is empty, +even if a page contains fewer items than you requested. + +The default page size is 25 for Cloud sandbox, image, snapshot, volume, and +secret lists. You can request up to 100 items per page. + +## Choose supported Cloud options + +Cloud supports kits, sandbox timeouts, stored secrets, and volume attachments, +subject to account permissions and feature availability. For example, volume +access must be enabled for your account. An SDK method's presence doesn't +guarantee that your account can use it. + +## Supply kit artifacts + +To use a kit outside the bundled catalog, your application must load and +prepare its content before calling `client.create()`. The npm SDK doesn't +fetch kits from a registry. Its `kits.launch()` and `kits.launchAndWait()` +helpers accept only bundled kit names. + +For example, the [Hermes agent kit](https://hub.docker.com/r/sbx/hermes-agent-kit) +is published as `docker.io/sbx/hermes-agent-kit:latest`. To use it through the +SDK, you need code outside the SDK that loads the kit definition and its +supporting files into the serialized +[v2 artifact format](https://github.com/docker/sbx-kits-contrib/blob/v0.17.0/spec/types.go) +accepted by the API. + +The kit artifacts described here use the v2 format. The `kits` array contains +a sandbox kit and any mixins that add configuration to it. See the +[v2 kit reference](../sandboxes/customize/kits-v2.md) for details. The bundled +launch helpers prepare this same input for the kits in their catalog. + +Pass the kit's source reference and prepared artifact bytes to +`client.create()`: + +```typescript +function createFromKit(reference: string, artifactBytes: Uint8Array) { + return client.create({ + resources: 'small', + kits: [ + { + artifact: { + ref: { ref: reference, kind: 'sandbox' }, + inline: artifactBytes, + }, + }, + ], + }); +} +``` + +The `ref` identifies the kit's source. It doesn't trigger a registry pull. +The `inline` value contains the serialized artifact as a `Uint8Array`, +including the kit's file content. Raw `spec.yaml`, ZIP files, and OCI manifests +aren't valid inputs for this field. + +To launch a public kit by registry reference without writing loading code, +use the [Docker Agentic Platform Console](/manuals/agentic-platform/kits.md#run-a-kit-by-reference). diff --git a/content/manuals/ai/sandboxes-api/cookbook/_index.md b/content/manuals/ai/sandboxes-api/cookbook/_index.md new file mode 100644 index 000000000000..90ee0183aee3 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/_index.md @@ -0,0 +1,62 @@ +--- +title: Docker Sandboxes SDK cookbook +linkTitle: Cookbook +description: Build agent workflows with the Docker Sandboxes SDK for TypeScript. +keywords: cloud sandboxes, sandboxes sdk, typescript, agent kits +weight: 60 +params: + recipeCatalog: true + sidebar: + activeChildrenOnly: true +--- + +Use these recipes to add file transfers, processes, storage, and other sandbox +operations to your application. Each recipe shows the relevant SDK calls and +an expandable complete TypeScript example. + +Start with [Get started](../get-started.md) to run your first sandbox, or +[install the SDK](../install.md) to use these examples in an existing project. +For HTTP operations and request fields, see the +[API reference](/reference/api/sandboxes/latest/). + +## Get started + +Authenticate and launch a kit before exploring individual SDK operations. + +{{< recipe-list group="Get started" >}} + +## Working in a sandbox + +Use a running sandbox for commands, project files, and web applications. + +{{< recipe-list group="Working in a sandbox" >}} + +## Packaging and state + +Keep an environment or its state for later work. + +{{< recipe-list group="Packaging and state" >}} + +## Security and policy + +Give agents the access they need without embedding credentials in application code. + +{{< recipe-list group="Security and policy" >}} + +## Connect and configure + +Choose a different image, control lifetime, or connect additional storage and clients. + +{{< recipe-list group="Connect and configure" >}} + +## Requests and responses + +Handle request options and failures deliberately. + +{{< recipe-list group="Requests and responses" >}} + +## Long-running work + +Continue work across lost connections or coordinate several sandboxes. + +{{< recipe-list group="Long-running work" >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/add-a-docker-credential-for-cloud-sandboxes.md b/content/manuals/ai/sandboxes-api/cookbook/add-a-docker-credential-for-cloud-sandboxes.md new file mode 100644 index 000000000000..94b267b6946d --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/add-a-docker-credential-for-cloud-sandboxes.md @@ -0,0 +1,48 @@ +--- +title: "Add a Docker credential for cloud sandboxes" +linkTitle: "Add a Docker credential for cloud sandboxes" +description: "Exchange a Docker OIDC identity token for a credential that the service stores for your sandboxes to use." +keywords: "cloud sandboxes, sandboxes api, add a docker credential for cloud sandboxes" +weight: 404 +params: + sidebar: + group: "Security and policy" +--- + +Store a Docker credential for workloads that need Docker access. This is separate from [signing your application in](connect-to-cloud-with-a-bearer-token.md): the application's access token authenticates SDK calls, while this exchange stores a credential for sandboxes. + +You need an authenticated client and a fresh Docker OpenID Connect identity token for the same identity. The example accepts that identity token; it does not perform the sign-in that issues it. + +## Exchange the token {#1-exchange-the-token} + +Pass the identity token to the identity collection. The service stores the resulting credential as `secrets/docker`, replacing its previous value. It returns no credential material. + +Treat the identity token as single-use. If you lose the response, obtain a new identity token before trying again. Never log either token. + +Use [stored secrets](get-a-stored-secret-into-a-sandbox.md) for other workload credentials. For an automation client that needs to call the SDK, use [PAT authentication](connect-to-cloud-with-a-bearer-token.md) instead of this exchange. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.identity.exchangeDockerCredential({ idToken }); +``` + +<details> +<summary>Complete TypeScript example: credentials/exchange.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function exchangeDockerCredential( + client: Sandboxes, + idToken: string, +) { + return client.identity.exchangeDockerCredential({ idToken }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/add-tools-with-kits.md b/content/manuals/ai/sandboxes-api/cookbook/add-tools-with-kits.md new file mode 100644 index 000000000000..e7119f3ddff5 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/add-tools-with-kits.md @@ -0,0 +1,151 @@ +--- +title: "Run agents with kits" +linkTitle: "Run agents with kits" +description: "Discover the available kits, launch an agent sandbox, and run work inside it." +keywords: "cloud sandboxes, sandboxes api, run agents with kits" +weight: 104 +params: + sidebar: + group: "Get started" +--- + +A kit supplies an agent's image and configuration, including tools and the settings they need. Launching a kit gives you a repeatable starting point without assembling those settings in every application. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md). Agent workloads also need credentials for their model provider. Docker authentication gives access to sandboxes; it does not sign you in to Anthropic, OpenAI, or another agent provider. + +## Discover available kits {#1-discover-available-kits} + +List the kits bundled with your installed SDK. Use an entry's name when launching it. Listing the catalog does not create a sandbox. + +The SDK's launch-by-name helper includes these starting points: + +| Kit name | Environment | +| --- | --- | +| `claude` | Claude Code | +| `codex` | Codex | +| `cursor` | Cursor | +| `devin` | Devin | +| `docker-agent` | Docker Agent | +| `gemini` | Gemini CLI | +| `opencode` | OpenCode | +| `shell` | A shell environment for your own commands | + +Use the catalog result as the list for your installed version. Upgrading the SDK can update the bundled kits. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.kits.list(); +``` + +<details> +<summary>Complete TypeScript example: kits/catalog.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export function listKits(client: Sandboxes) { + return client.kits.list(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Launch a kit {#2-launch-a-kit} + +To run Claude Code, choose `claude` and attach a stored `anthropic` secret containing your Anthropic API key. [Store the provider credential](get-a-stored-secret-into-a-sandbox.md) first, then pass the stored secret's resource name to the launch example. Keep credentials out of command arguments and plain environment values. + +Pass a catalog name, a display name, and any stored secret names the agent needs. The example selects Small (2 vCPUs, 4 GiB) and uses the launch-and-wait helper to return a running sandbox under one deadline. Small is also the default when you omit kit resources. See [compute sizes](work-within-the-limits.md) for the other choices. + +Use `launch` when you want the accepted handle immediately and will wait separately. If the wait fails, inspect the accepted sandbox retained by the error before launching another one. + +`launchAndWait()` waits for the sandbox to reach the running state. A kit can still be installing tools or cloning a repository at that point. The SDK has no helper that waits for all kit setup to finish. + +If your work depends on that setup, check the result it needs before starting. For example, a kit can write a completion marker after cloning a repository, or a service can expose a health check. Poll with a delay between checks and a timeout so failed setup does not leave your application waiting indefinitely. + +The launch helper accepts only names returned by the bundled catalog, not community repository URLs or registry references. Account network policies still apply to kit sandboxes. + +Use `shell` when you need an environment for scripts, builds, or your own executable. To use a container image directly, see [Run your own container image](run-your-own-container-image.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.kits.launchAndWait(kitName, { + displayName, + resources: 'small', + storage: { secrets }, +}); +``` + +<details> +<summary>Complete TypeScript example: kits/launch.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function launchKit( + client: Sandboxes, + kitName: string, + displayName: string, + secrets: string[] = [], +) { + return client.kits.launchAndWait(kitName, { + displayName, + resources: 'small', + storage: { secrets }, + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Run the agent {#3-run-the-agent} + +Pass the sandbox handle returned by the launch example and your prompt to the run helper. It runs `claude -p` and waits for the response. Launching a kit alone does not submit an agent task. + +The example returns captured output and an exit code. Check both when diagnosing an agent failure. For a long task, [stream output](run-something-that-produces-real-output.md); for a conversation in a terminal, [open an interactive session](run-an-interactive-shell-in-a-cloud-sandbox.md). + +Save the sandbox name if you will resume the work later. [Delete the sandbox](delete-a-cloud-sandbox.md) when you no longer need its files or running processes. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes.run( + { args: ['claude', '-p', prompt] }, + { timeoutMs: 300_000 }, +); +``` + +<details> +<summary>Complete TypeScript example: kits/run.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function runKitAgent(sandbox: Sandbox, prompt: string) { + return sandbox.processes.run( + { args: ['claude', '-p', prompt] }, + { timeoutMs: 300_000 }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Explore the wider kit catalog {#4-explore-the-wider-kit-catalog} + +The [community kit catalog](https://github.com/docker/sbx-kits-contrib) includes agents such as Aider, Amp, Copilot, Kiro, and OpenHands, plus development tools, browser automation, source control, and security scanning. For example, Code Server adds a browser-based editor and Playwright adds browser automation. + +Some kits define a complete sandbox environment; others add tools or configuration to an existing agent environment. These are not all bundled SDK launch targets. See the [Docker kits guide](https://docs.docker.com/ai/sandboxes/customize/kits/) for the catalog's usage instructions. diff --git a/content/manuals/ai/sandboxes-api/cookbook/attach-persistent-storage.md b/content/manuals/ai/sandboxes-api/cookbook/attach-persistent-storage.md new file mode 100644 index 000000000000..49e94c946790 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/attach-persistent-storage.md @@ -0,0 +1,143 @@ +--- +title: "Attach persistent storage" +linkTitle: "Attach persistent storage" +description: "Create a volume, mount it into a new sandbox so its data outlives the sandbox, and delete the volume when you no longer need it." +keywords: "cloud sandboxes, sandboxes api, attach persistent storage" +weight: 505 +params: + sidebar: + group: "Connect and configure" +--- + +Keep project data after a sandbox is deleted by mounting a persistent volume. A volume is an independent resource: deleting a sandbox does not delete the volume. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md), a managed image from [Register and manage an image](register-and-manage-an-image.md), and an absolute mount path such as `/workspace/data`. + +## Create a volume {#1-create-a-volume} + +Choose a display name and an idempotency key for the create request. Save the returned volume name, such as `volumes/…`. That name identifies the volume in later requests; its display name is only a label. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.volumes.create( + { displayName: name }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: volumes/create.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createVolume( + client: Sandboxes, + name: string, + requestId: string, +) { + return client.volumes.create( + { displayName: name }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Mount it in a new sandbox {#2-mount-it-in-a-new-sandbox} + +Supply the volume name and destination path when creating the sandbox. The example accepts a map of volume names to mount paths and waits for the sandbox to run. For Cloud Sandboxes, supply one entry and use exclusive attachment. Volume access must be enabled for your account; memory-snapshot images do not support volume attachment. + +Attachments belong to the sandbox's creation settings. To mount the volume elsewhere, create another sandbox with the attachment. With exclusive attachment, release the first sandbox before attaching the volume to another one. Avoid overlapping mount paths. + +Write a file under the mount path, delete the sandbox, then attach the volume to a new sandbox to read it again. Files outside the mount remain on the sandbox's own disk. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { + displayName: name, + image, + storage: { + volumes: [...mountPaths].map(([volume, target]) => ({ + volume, + target, + })), + }, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: volumes/attach.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createWithVolumes( + client: Sandboxes, + name: string, + image: string, + mountPaths: Map<string, string>, + requestId: string, +) { + const sandbox = await client.create( + { + displayName: name, + image, + storage: { + volumes: [...mountPaths].map(([volume, target]) => ({ + volume, + target, + })), + }, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Delete the volume {#3-delete-the-volume} + +Delete the sandbox using the volume first, then delete the volume through its handle. If the service reports that it is still in use, wait for sandbox deletion to finish before retrying. + +Deleting the volume permanently removes its contents. Copy out anything you need to keep. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await volume.delete(); +``` + +<details> +<summary>Complete TypeScript example: volumes/delete.ts</summary> + +```typescript +import type { Volume } from '@docker/sandboxes'; + +export async function deleteVolume(volume: Volume) { + await volume.delete(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/clone-a-cloud-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/clone-a-cloud-sandbox.md new file mode 100644 index 000000000000..7e1696510187 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/clone-a-cloud-sandbox.md @@ -0,0 +1,111 @@ +--- +title: "Clone a cloud sandbox" +linkTitle: "Clone a cloud sandbox" +description: "Read how a running sandbox was configured, then create a second sandbox with the same image and environment." +keywords: "cloud sandboxes, sandboxes api, clone a cloud sandbox" +weight: 702 +params: + sidebar: + group: "Long-running work" +--- + +Create another sandbox using selected settings from an existing one. This example copies the image source and environment, not the sandbox's files or running processes. For a saved filesystem or memory state, use a [snapshot](snapshot-and-fork-a-sandbox.md). + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md), the source sandbox's resource name, and a display name for the new sandbox. + +## Read the source configuration {#1-read-the-source-configuration} + +Get the source sandbox and inspect its image and environment. Review environment values before copying them; they may contain credentials or settings specific to the original job. + +Do not treat the complete response as a create request. It includes read-only state and connection details. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.get(name); +return sandbox.core; +``` + +<details> +<summary>Complete TypeScript example: clone/inspect.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function inspectSandbox(client: Sandboxes, name: string) { + const sandbox = await client.get(name); + return sandbox.core; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Create a fresh sandbox {#2-create-a-fresh-sandbox} + +The example copies the image source and environment. For a registry image it also copies resource settings. It waits for the new sandbox to run. + +The call returns the new sandbox's handle, ready for running commands or transferring files. + +This is a limited configuration copy, not a complete clone. It does not copy kits, attached policies, secrets, volumes, files, or process state. A copied image alone may not reproduce a kit's setup. For repeated agent environments, launch the same [named kit](add-tools-with-kits.md) with the options your application saved. + +Attach required network policies and credentials before running work in the new sandbox. The source is unchanged, and both sandboxes need their own cleanup. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const copy = await client.create( + { + displayName: name, + ...(core.image + ? { image: core.image, agent: core.agent } + : { + imageRef: core.imageRef!, + resources: core.resources, + }), + environment: core.environment, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return copy.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: clone/rebuild.ts</summary> + +```typescript +import type { Sandbox, Sandboxes } from '@docker/sandboxes'; + +export async function rebuildSandbox( + client: Sandboxes, + core: Sandbox['core'], + name: string, + requestId: string, +) { + if (!core.image && !core.imageRef) + throw new TypeError('Source has no image'); + const copy = await client.create( + { + displayName: name, + ...(core.image + ? { image: core.image, agent: core.agent } + : { + imageRef: core.imageRef!, + resources: core.resources, + }), + environment: core.environment, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return copy.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/connect-to-cloud-with-a-bearer-token.md b/content/manuals/ai/sandboxes-api/cookbook/connect-to-cloud-with-a-bearer-token.md new file mode 100644 index 000000000000..6f08e409203f --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/connect-to-cloud-with-a-bearer-token.md @@ -0,0 +1,217 @@ +--- +title: "Authenticate to Docker" +linkTitle: "Authenticate to Docker" +description: "Sign in interactively, use a Docker personal access token, or supply an access token from your application." +keywords: "cloud sandboxes, sandboxes api, authenticate to docker" +weight: 101 +params: + sidebar: + group: "Get started" +--- + +Sign in to Docker so your application can create and use Cloud Sandboxes. Before you begin, [install the SDK](https://docs.docker.com/ai/sandboxes-api/install/) and make sure your Docker account has Cloud Sandboxes access. + +Choose interactive sign-in when running an example yourself. Use a personal access token (PAT) for a service or CI job. If your application already manages Docker access tokens, pass a token or a token provider. + +## Sign in interactively {#1-sign-in-interactively} + +Call `const client = await login()` using the function below. It prints a link and a code in your terminal. Open the link in your browser, enter the code, and approve sign-in with your Docker account. + +The function waits for sign-in to finish before returning a client you can use to call the API. If you deny sign-in or the verification code expires, it reports an error. Run the program again to get a new code. The [complete program](run-a-complete-example.md) shows how to sign in and create a sandbox. + +The SDK keeps your sign-in details in memory and renews access automatically while your sign-in remains valid. You need to sign in again when you restart the program unless you save these details as described below. Call `await client.close()` when finished. Closing the client does not delete your sandboxes or sign you out of Docker. + +You can pass the same authenticator to several clients to reuse their sign-in. Closing one client leaves the authenticator usable by the others. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +export const login = async () => { + const auth = oauth({ + onVerification: ({ verificationUri, userCode }) => { + console.log(`Open ${verificationUri} and enter ${userCode}`); + }, + }); + await auth.getAccessToken(); + return new Sandboxes({ auth }); +}; +``` + +<details> +<summary>Complete TypeScript example: cloudauth/login.ts</summary> + +```typescript +import { + fileOAuthCredentialStore, + oauth, + Sandboxes, +} from '@docker/sandboxes'; + +export const login = async () => { + const auth = oauth({ + onVerification: ({ verificationUri, userCode }) => { + console.log(`Open ${verificationUri} and enter ${userCode}`); + }, + }); + await auth.getAccessToken(); + return new Sandboxes({ auth }); +}; + +export async function loginWithSavedCredentials(path: string) { + const storedAuth = oauth({ + store: fileOAuthCredentialStore({ path }), + onVerification: ({ verificationUri, userCode }) => { + console.log(`Open ${verificationUri} and enter ${userCode}`); + }, + }); + await storedAuth.getAccessToken(); + return new Sandboxes({ auth: storedAuth }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Optional: save credentials between runs {#2-optional-save-credentials-between-runs} + +To reuse your sign-in when a Node.js program restarts, expand the complete example above and use `await loginWithSavedCredentials(path)`. Set `path` to the file where you want to save your sign-in details. The function uses saved details when they are still valid, or asks you to sign in again, before returning a client. + +The file store works in Node.js on systems such as macOS and Linux, but not in browsers or on Windows. The file is not encrypted. Keep it in a private directory, exclude it from source control, and do not share it between running programs. To save sign-in details in a keychain or secret manager instead, implement `OAuthCredentialStore` with `load` and `save`. + +Remove the stored credentials when your application no longer needs them. Your application owns that removal; closing a client does not remove the file or revoke the credentials. + +## Use a personal access token {#3-use-a-personal-access-token} + +Create a +[Docker personal access token](https://docs.docker.com/security/access-tokens/) +for the Docker account your application will use. Provide your Docker +username and PAT through your application's secret manager or +environment, then pass them to the SDK's PAT authentication option. + +The SDK exchanges the PAT for a short-lived access token and repeats +the exchange when needed. Supply the PAT as a PAT credential, not as +an access token or an Authorization header. A revoked or expired PAT +requires a replacement credential. + +Managed OAuth and PAT authentication use the default Docker service +address. Use a caller-supplied access token or provider when you need +to override that address. + +Your PAT needs the `sandbox:use` scope. When you create the token, +select **Allow Cloud Sandboxes access**. The same token can also have +a repository permission. Create the token at +`https://app.docker.com/accounts/[username]/settings/personal-access-tokens`. + +Keep the PAT on the machine running your application. Do not put it in +a sandbox's environment, source code, or logs. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return new Sandboxes({ + auth: pat({ username, personalAccessToken }), +}); +``` + +<details> +<summary>Complete TypeScript example: cloudauth/pat.ts</summary> + +```typescript +import { pat, Sandboxes } from '@docker/sandboxes'; + +export function connectWithPAT( + username: string, + personalAccessToken: string, +) { + return new Sandboxes({ + auth: pat({ username, personalAccessToken }), + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Supply an access token {#4-supply-an-access-token} + +If you already hold a Docker access-token JWT, pass it as the client's access token. The SDK sends it as a bearer credential. A raw PAT is not an access-token JWT. + +A fixed token has no refresh credential. Once it expires, create a client with a fresh token, or use the provider option below. The example accepts a service URL for applications that need an override; the default is `https://connect.docker.com/sandboxes`. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return new Sandboxes({ + baseUrl: endpoint, + auth: bearer(accessToken), +}); +``` + +<details> +<summary>Complete TypeScript example: cloudauth/connect.ts</summary> + +```typescript +import { bearer, Sandboxes } from '@docker/sandboxes'; + +export function connectToCloud(endpoint: string, accessToken: string) { + return new Sandboxes({ + baseUrl: endpoint, + auth: bearer(accessToken), + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Supply a token provider {#5-supply-a-token-provider} + +Pass a callback that obtains a current Docker access token from your credential system. The callback returns the token string; your application owns its acquisition, storage, and renewal. Do not return an expired token. + +Use one credential source per client. The SDK does not read environment variables or credentials saved by Docker command-line tools automatically. + +Authentication errors mean the credential is missing, rejected, or expired. Sign in again or replace the credential. A permission error means the account cannot perform the requested action; check its Cloud Sandboxes access and resource permissions before retrying. + +When you run commands or transfer files through a sandbox handle, the SDK obtains a credential scoped to that sandbox. You do not need to copy your account token into a second client. + +Docker sign-in is separate from an agent's provider credential. To let an agent call its model provider, follow [Use secrets in a sandbox](get-a-stored-secret-into-a-sandbox.md). + +Next, [run a complete program](run-a-complete-example.md) that signs in and launches a kit. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return new Sandboxes({ + auth: { getAccessToken: tokenProvider }, +}); +``` + +<details> +<summary>Complete TypeScript example: cloudauth/provider.ts</summary> + +```typescript +import { Sandboxes, type Authenticator } from '@docker/sandboxes'; + +export function connectWithTokenProvider( + tokenProvider: Authenticator['getAccessToken'], +) { + return new Sandboxes({ + auth: { getAccessToken: tokenProvider }, + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/control-what-a-sandbox-can-reach.md b/content/manuals/ai/sandboxes-api/cookbook/control-what-a-sandbox-can-reach.md new file mode 100644 index 000000000000..9d75c4d910fb --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/control-what-a-sandbox-can-reach.md @@ -0,0 +1,122 @@ +--- +title: "Control what a sandbox can reach" +linkTitle: "Control what a sandbox can reach" +description: "Attach your account's network policies to a new sandbox, read the policy the service enforces, and review which destinations it allowed or blocked." +keywords: "cloud sandboxes, sandboxes api, control what a sandbox can reach" +weight: 401 +params: + sidebar: + group: "Security and policy" +--- + +Control which destinations an agent or command can reach. A sandbox's effective policy combines account rules with the policies attached to it. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md), a managed image, and policy IDs from your account. Create policies in the Console or with [Manage network policies](manage-network-policies.md). + +## Attach policies at creation {#1-attach-policies-at-creation} + +Pass the policy IDs when creating the sandbox. The example waits until the sandbox is running and returns its handle. + +Attachments refer to existing policies; they do not contain policy definitions. Keep the IDs distinct from display names. Attached policies restrict access alongside account policy, so they cannot grant access that your account denies. + +Include every destination the workload needs, including its model provider and package registries. A kit's network requirements do not override account restrictions. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { displayName: name, image, network: { policyIds } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: netpolicy/reference.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createWithPolicyIds( + client: Sandboxes, + name: string, + image: string, + policyIds: string[], + requestId: string, +) { + const sandbox = await client.create( + { displayName: name, image, network: { policyIds } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Inspect the rules in force {#2-inspect-the-rules-in-force} + +Read the sandbox's effective policy before troubleshooting an application timeout. The result includes combined allow and deny rules, their origins, and an exact policy representation. + +The effective view is the useful starting point for questions such as “can this sandbox reach api.anthropic.com?” Check the default mode as well as matching rules. A deny-by-default policy needs an explicit allowance for the destination. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.networkPolicies.get(); +``` + +<details> +<summary>Complete TypeScript example: netpolicy/effective.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function getNetworkPolicies(sandbox: Sandbox) { + return sandbox.networkPolicies.get(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Check allowed and blocked traffic {#3-check-allowed-and-blocked-traffic} + +List policy log entries for the sandbox, using `domain=network` to select network decisions. The example follows pagination and returns all matching entries. + +Use each entry's destination, decision, reason, and count to identify blocked dependencies. An empty result means no matching entries were returned; it does not prove that a destination is reachable. The log records recent activity, not a permanent audit history. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.networkPolicies.logs.all({ filter }).collect(); +``` + +<details> +<summary>Complete TypeScript example: netpolicy/logs.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function listPolicyLogEntries( + client: Sandboxes, + sandboxName: string, + filter: string, +) { + const sandbox = await client.get(sandboxName); + return sandbox.networkPolicies.logs.all({ filter }).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/copy-a-file-into-a-cloud-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/copy-a-file-into-a-cloud-sandbox.md new file mode 100644 index 000000000000..fec1e7333bf0 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/copy-a-file-into-a-cloud-sandbox.md @@ -0,0 +1,116 @@ +--- +title: "Copy a file into a cloud sandbox" +linkTitle: "Copy a file into a cloud sandbox" +description: "Create a directory inside a running cloud sandbox, write one file into it from memory, and read the size the write reports back." +keywords: "cloud sandboxes, sandboxes api, copy a file into a cloud sandbox" +weight: 202 +params: + sidebar: + group: "Working in a sandbox" +--- + +Send project files, scripts, or input data to a running sandbox. Use its file collection instead of putting large file contents into command arguments. + +You need a sandbox handle from [your first sandbox](create-your-first-sandbox.md) and an absolute destination path. The paths in these examples are inside the sandbox, not on your computer. + +## Create the destination directory {#1-create-the-destination-directory} + +Create the destination directory with the desired permission mode. The example also creates missing parent directories. + +Choose the narrowest permissions the workload needs. Remember that a file's contents and its executable permission are separate settings. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await sandbox.files.mkdir(path, { mode, parents: true }); +``` + +<details> +<summary>Complete TypeScript example: upload/mkdir.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function makeDirectory( + sandbox: Sandbox, + path: string, + mode: number, +) { + await sandbox.files.mkdir(path, { mode, parents: true }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Write a small text file {#2-write-a-small-text-file} + +Use the write helper for a configuration file or short script already held as a string. Pass its destination path and content. For binary data or streamed transfers, use upload instead. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.files.write(path, content); +``` + +<details> +<summary>Complete TypeScript example: upload/write.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function writeFile( + sandbox: Sandbox, + path: string, + content: string, +) { + return sandbox.files.write(path, content); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Upload file content {#3-upload-file-content} + +Upload bytes to the destination and read its metadata afterward. The example accepts content from your application; read a local file first if that is your source. + +Choose a file mode explicitly when executable or restricted permissions matter. A failed upload may have written some data. Inspect the destination before retrying if replacing its contents would be unsafe. + +Next, [run a command](run-your-first-command.md) that reads the file, or [read it back](read-files-out-of-a-sandbox.md) to verify the content. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await sandbox.files.upload(path, content, { mode }); +return (await sandbox.files.stat(path)).info; +``` + +<details> +<summary>Complete TypeScript example: upload/upload.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function uploadFile( + sandbox: Sandbox, + path: string, + content: Uint8Array, + mode: number, +) { + await sandbox.files.upload(path, content, { mode }); + return (await sandbox.files.stat(path)).info; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/create-your-first-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/create-your-first-sandbox.md new file mode 100644 index 000000000000..7e156b08fc64 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/create-your-first-sandbox.md @@ -0,0 +1,160 @@ +--- +title: "Create your first sandbox" +linkTitle: "Create your first sandbox" +description: "Launch a kit, run a command in its sandbox, and inspect the result." +keywords: "cloud sandboxes, sandboxes api, create your first sandbox" +weight: 103 +params: + sidebar: + group: "Get started" +--- + +Create a sandbox from a kit and run a command inside it. A kit bundles an image and configuration for a tool or agent. The `shell` kit is a useful first choice because a greeting command needs no model-provider credential. + +[Install an SDK](https://docs.docker.com/ai/sandboxes-api/install/) and [authenticate to Docker](connect-to-cloud-with-a-bearer-token.md) first. Pass the authenticated client to this example along with a kit name and command. + +## Launch a kit and run a command {#1-launch-a-kit-and-run-a-command} + +Choose `shell` as the kit name and pass `['echo', 'Hello from Docker Sandboxes']` as the command. The example requests 2 CPUs and 4096 MiB of memory. See [compute sizes and account limits](work-within-the-limits.md) when sizing other workloads. + +The example launches the kit, waits until the sandbox is running, and runs the command through the sandbox's process collection. The SDK handles the connection and its sandbox-scoped credential. + +A successful greeting returns `Hello from Docker Sandboxes` in `stdout` and exit code zero. See [Run your first command](run-your-first-command.md) for argument arrays, shell syntax, and interpreting command results. + +Keep the returned sandbox name. This example leaves the sandbox available for the next guides. [Delete it](delete-a-cloud-sandbox.md) when you finish; closing the SDK client does not delete it. If a wait times out after creation was accepted, the sandbox can still exist. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const created = await client.kits.launch( + kitName, + { resources: { cpus: 2, memoryMib: 4096 } }, + { timeoutMs, signal }, +); +const sandbox = await created.waitUntilRunning({ timeoutMs, signal }); +const result = await sandbox.processes.run( + { args }, + { timeoutMs, signal }, +); +return { sandbox, result }; +``` + +<details> +<summary>Complete TypeScript example: quickstart/run.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createAndRun( + client: Sandboxes, + kitName: string, + args: string[], + timeoutMs = 300_000, +) { + const signal = AbortSignal.timeout(timeoutMs); + const created = await client.kits.launch( + kitName, + { resources: { cpus: 2, memoryMib: 4096 } }, + { timeoutMs, signal }, + ); + const sandbox = await created.waitUntilRunning({ timeoutMs, signal }); + const result = await sandbox.processes.run( + { args }, + { timeoutMs, signal }, + ); + return { sandbox, result }; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Clean up a temporary sandbox automatically {#2-clean-up-a-temporary-sandbox-automatically} + +For a single task, the scoped sandbox helper creates a sandbox, runs your callback, and attempts deletion afterward, including when the callback fails. This example explicitly stops the sandbox and waits for that transition before the helper attempts deletion. Supply the command arguments and creation options appropriate for the task; for a published image, set its reference and resources. + +Cleanup has its own deadline. If it fails, inspect the workflow error and the retained sandbox identity so you can finish cleanup. Do not treat a client timeout as confirmation that the sandbox was deleted. + +Next, [choose an agent kit](add-tools-with-kits.md) or [work with processes](run-your-first-command.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.withSandbox(options, async (sandbox) => { + const outcome = await sandbox.processes + .run({ args }, { timeoutMs: 300_000 }) + .then( + (value) => ({ value }), + (error: unknown) => ({ error }), + ); + try { + const cleanup = { signal: AbortSignal.timeout(30_000) }; + const current = await client.get(sandbox.name, cleanup); + if (current.uid !== sandbox.uid) + throw new Error( + 'Sandbox identity changed; refusing to stop a replacement', + ); + const stopped = await current.stop(cleanup); + await stopped.waitUntilStopped(cleanup); + } catch (error) { + if ('error' in outcome) + throw new AggregateError( + [outcome.error, error], + 'Command and stop both failed', + ); + throw error; + } + if ('error' in outcome) throw outcome.error; + return outcome.value; +}); +``` + +<details> +<summary>Complete TypeScript example: quickstart/scoped.ts</summary> + +```typescript +import type { ClientCreateOptions, Sandboxes } from '@docker/sandboxes'; + +export async function runTemporary( + client: Sandboxes, + options: ClientCreateOptions, + args: string[], +) { + return client.withSandbox(options, async (sandbox) => { + const outcome = await sandbox.processes + .run({ args }, { timeoutMs: 300_000 }) + .then( + (value) => ({ value }), + (error: unknown) => ({ error }), + ); + try { + const cleanup = { signal: AbortSignal.timeout(30_000) }; + const current = await client.get(sandbox.name, cleanup); + if (current.uid !== sandbox.uid) + throw new Error( + 'Sandbox identity changed; refusing to stop a replacement', + ); + const stopped = await current.stop(cleanup); + await stopped.waitUntilStopped(cleanup); + } catch (error) { + if ('error' in outcome) + throw new AggregateError( + [outcome.error, error], + 'Command and stop both failed', + ); + throw error; + } + if ('error' in outcome) throw outcome.error; + return outcome.value; + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/delete-a-cloud-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/delete-a-cloud-sandbox.md new file mode 100644 index 000000000000..274de2e9e47a --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/delete-a-cloud-sandbox.md @@ -0,0 +1,64 @@ +--- +title: "Delete a cloud sandbox" +linkTitle: "Delete a cloud sandbox" +description: "Delete a sandbox you have read back and wait until it is gone, with the option to override a refusal based on its current state." +keywords: "cloud sandboxes, sandboxes api, delete a cloud sandbox" +weight: 106 +params: + sidebar: + group: "Get started" +--- + +Delete a sandbox when its work is finished. Deletion removes its processes and sandbox-local files, so download results or save a snapshot first. + +Use a current sandbox handle from creation or from reading its resource name. Closing the SDK client does not delete the sandbox. + +## Delete and wait {#1-delete-and-wait} + +Delete through the sandbox handle, then wait until the sandbox is absent. Deletion can terminate running work. If you choose to [stop the sandbox](stop-and-restart-a-sandbox.md) first, wait for that transition to finish before deleting it: deletion during a stop or resume can be refused. + +The example takes an idempotency key and a wait deadline. Its optional force setting requests deletion when the service would otherwise refuse the sandbox's state. It does not guarantee that every state can be deleted immediately; handle a refusal rather than assuming cleanup succeeded. + +The handle supplies the resource version it read. When an operation returns an updated handle, keep that handle for your next operation; older handles do not update themselves. + +If deletion fails because the resource version changed, call `refresh()`. Inspect the returned handle and decide whether deletion is still appropriate. Refreshing does not change the original handle, so call delete on the returned one. If you supply idempotency keys, use a new key: deleting the refreshed version is a new logical operation, not a retry of the refused request. + +If the wait times out, read the sandbox again to check its state. Keep its name so you can retry cleanup if needed. Repeating a completed deletion is safe. + +Separate resources such as volumes, snapshots, and stored secrets have their own lifetimes. Delete those only when nothing still needs them. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const deleting = await sandbox.delete( + { force }, + { idempotencyKey: requestId }, +); +if (deleting) await deleting.waitUntilDeleted({ timeoutMs }); +``` + +<details> +<summary>Complete TypeScript example: removal/delete.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function deleteSandbox( + sandbox: Sandbox, + requestId: string, + force = false, + timeoutMs = 300_000, +) { + const deleting = await sandbox.delete( + { force }, + { idempotencyKey: requestId }, + ); + if (deleting) await deleting.waitUntilDeleted({ timeoutMs }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/expose-a-port-from-a-cloud-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/expose-a-port-from-a-cloud-sandbox.md new file mode 100644 index 000000000000..35f3ae61c910 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/expose-a-port-from-a-cloud-sandbox.md @@ -0,0 +1,111 @@ +--- +title: "Expose a port from a cloud sandbox" +linkTitle: "Expose a port from a cloud sandbox" +description: "Publish a TCP port that a program inside a cloud sandbox listens on, read back the URL that reaches it, list the sandbox's published ports, and withdraw the publication." +keywords: "cloud sandboxes, sandboxes api, expose a port from a cloud sandbox" +weight: 204 +params: + sidebar: + group: "Working in a sandbox" +--- + +Reach a web application running inside a sandbox through an HTTPS URL. Publishing creates a route to the application; it does not start the application. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md), the sandbox name, and an HTTP application listening on the port you will publish. Bind the application to an address reachable inside the sandbox, such as `0.0.0.0`. + +## Publish the application's port {#1-publish-the-application-s-port} + +Supply the sandbox name and the application's port number. The example uses TCP. Use the URL returned by the service rather than constructing a hostname. + +This is HTTP application access, not a general-purpose TCP tunnel. Docker account authentication does not protect the application URL. Configure authentication in your application before exposing sensitive data, and never send your Docker account token to that URL. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.ports.create( + { number, protocol: 'tcp' }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: ports/publish.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createPort( + client: Sandboxes, + sandboxName: string, + number: number, + requestId: string, +) { + const sandbox = await client.get(sandboxName); + return sandbox.ports.create( + { number, protocol: 'tcp' }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## List published ports {#2-list-published-ports} + +Read the sandbox's port collection to find existing publications and their URLs. Check the application's readiness separately: a published route does not prove the application has started. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return (await sandbox.ports.list()).published ?? []; +``` + +<details> +<summary>Complete TypeScript example: ports/list.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function listPorts(sandbox: Sandbox) { + return (await sandbox.ports.list()).published ?? []; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Withdraw a publication {#3-withdraw-a-publication} + +Delete the published port when access is no longer needed. This removes the route but leaves the application process running. + +Stopping the sandbox does not remove its port publications. Deleting the sandbox does. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await port.delete(); +``` + +<details> +<summary>Complete TypeScript example: ports/unpublish.ts</summary> + +```typescript +import type { Port } from '@docker/sandboxes'; + +export async function deletePort(port: Port) { + await port.delete(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/find-a-process-you-lost-track-of.md b/content/manuals/ai/sandboxes-api/cookbook/find-a-process-you-lost-track-of.md new file mode 100644 index 000000000000..f61117584b46 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/find-a-process-you-lost-track-of.md @@ -0,0 +1,113 @@ +--- +title: "Find a process you lost track of" +linkTitle: "Find a process you lost track of" +description: "Look up a running process by the session tag you gave it when you created it, then pick up its output from the resume point its own report publishes." +keywords: "cloud sandboxes, sandboxes api, find a process you lost track of" +weight: 701 +params: + sidebar: + group: "Long-running work" +--- + +Reconnect to work after losing a process connection. Starting a new command can duplicate effects, so first look for the process you already started. + +Connections opened through TypeScript process handles recover from temporary disconnects while you consume output. They reconnect to the same process and resume after the last delivered chunk, with a 30-second budget per recovery episode. They never restart the command or replay terminal input. Raw streams require explicit reconnection. Use this guide when automatic recovery stops, you close a connection, or your application restarts. + +You need a current sandbox handle and a session tag that your application assigned when it started the process. A session tag is searchable metadata, not the process's resource name. + +## Find the running session {#1-find-the-running-session} + +List processes filtered by session and running state. The example follows pagination. If multiple processes match, choose the intended resource by its saved name or metadata rather than attaching to an arbitrary result. + +An empty list means no running process matched. It does not prove that the original command never started: it may have exited. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes + .all({ filter: `session=${session},state=running` }) + .collect(); +``` + +<details> +<summary>Complete TypeScript example: reconnect/list.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function findSession(sandbox: Sandbox, session: string) { + return sandbox.processes + .all({ filter: `session=${session},state=running` }) + .collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Reconnect to its output {#2-reconnect-to-its-output} + +Connect to the selected process handle and consume output events. The example resumes from the last sequence reported by that handle. + +For delivery to another system, keep your own cursor for the last chunk that system actually handled. The latest sequence reported by the process may be ahead of that cursor. Use [explicit output resumption](run-an-interactive-shell-in-a-cloud-sandbox.md) when you need to replay from your saved position. + +Close the connection when finished. Keep the process name if the connection drops again; do not replace reconnection with a second process start. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const connection = await process.connect({ + resumeFrom: process.lastStreamSequence, +}); +let lastSequence = BigInt(process.lastStreamSequence ?? '0'); +try { + for await (const event of connection) { + if (event.type === 'chunk') + write( + event.data ?? new Uint8Array(), + (lastSequence = BigInt(event.streamSequence ?? '0')), + ); + } + return lastSequence; +} finally { + await connection.close(); +} +``` + +<details> +<summary>Complete TypeScript example: reconnect/attach.ts</summary> + +```typescript +import type { Process } from '@docker/sandboxes'; + +export async function rejoinProcess( + process: Process, + write: (bytes: Uint8Array, sequence: bigint) => void, +) { + const connection = await process.connect({ + resumeFrom: process.lastStreamSequence, + }); + let lastSequence = BigInt(process.lastStreamSequence ?? '0'); + try { + for await (const event of connection) { + if (event.type === 'chunk') + write( + event.data ?? new Uint8Array(), + (lastSequence = BigInt(event.streamSequence ?? '0')), + ); + } + return lastSequence; + } finally { + await connection.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/get-a-stored-secret-into-a-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/get-a-stored-secret-into-a-sandbox.md new file mode 100644 index 000000000000..5e2ae02527ce --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/get-a-stored-secret-into-a-sandbox.md @@ -0,0 +1,100 @@ +--- +title: "Get a stored secret into a sandbox" +linkTitle: "Get a stored secret into a sandbox" +description: "Store a credential once, then pass its resource name when creating a sandbox so the sandbox starts with that secret attached." +keywords: "cloud sandboxes, sandboxes api, get a stored secret into a sandbox" +weight: 405 +params: + sidebar: + group: "Security and policy" +--- + +Give an agent access to its provider without placing the real credential in its command arguments or source files. Store the credential once, then attach its secret name when creating each sandbox. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md). Obtain the provider credential from that provider and read it from your application's secret manager. For Claude Code, use an Anthropic API key and service type `anthropic`; the Docker login token is not an Anthropic key. + +## Store the provider credential {#1-store-the-provider-credential} + +Supply a display name, service type, token value, and an idempotency key. Save the returned secret name. The response contains metadata, never the stored token. + +Choose the service type that matches the workload's provider. A token for one provider does not authenticate another agent. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.secrets.create( + { displayName: name, serviceType, token: { value: token } }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: credinject/store.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function storeSecret( + client: Sandboxes, + name: string, + serviceType: string, + token: string, + requestId: string, +) { + return client.secrets.create( + { displayName: name, serviceType, token: { value: token } }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Attach the secret at creation {#2-attach-the-secret-at-creation} + +Put the secret name in the sandbox's storage options. This example uses a managed image; the same storage options can be passed when [launching a named kit](add-tools-with-kits.md). + +Attach the secret when creating the sandbox, before starting the agent. Passing a secret's display name instead of its resource name will not select it. Keep the real token on the client side of the storage step rather than duplicating it in environment variables. + +The SDK returns a handle after the example waits for the sandbox to run. Use that handle to run the agent. To replace or delete the credential later, follow [Manage cloud secrets](manage-cloud-secrets.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { displayName: name, image, storage: { secrets: secretNames } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: credinject/attach.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createWithSecrets( + client: Sandboxes, + name: string, + image: string, + secretNames: string[], + requestId: string, +) { + const sandbox = await client.create( + { displayName: name, image, storage: { secrets: secretNames } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/get-an-ssh-certificate.md b/content/manuals/ai/sandboxes-api/cookbook/get-an-ssh-certificate.md new file mode 100644 index 000000000000..32eba1784cf9 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/get-an-ssh-certificate.md @@ -0,0 +1,57 @@ +--- +title: "Get an SSH certificate" +linkTitle: "Get an SSH certificate" +description: "Have the service sign your SSH public key for one sandbox and return the host, port, username, and host keys your SSH client needs." +keywords: "cloud sandboxes, sandboxes api, get an ssh certificate" +weight: 506 +params: + sidebar: + group: "Connect and configure" +--- + +Request a short-lived SSH certificate for access to a sandbox. Keep the private key on your machine; send only the public key to Docker. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md), a sandbox name, and an SSH public key. Generate a key pair with your SSH tooling if you do not have one. + +## Request the certificate {#1-request-the-certificate} + +Pass the sandbox name and public key. Save the returned certificate using your SSH client's expected certificate-file format, alongside the matching private key. + +The response supplies the connection details for the sandbox. Use them rather than guessing a hostname or port. The example returns those details; it does not start an SSH process. + +A certificate expires. Request a new one when needed, and keep the private key and certificate out of your repository. For programmatic command execution without an SSH client, use [processes](run-your-first-command.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.ssh.issueCertificate({ + publicKey, + ttlMs: lifeSeconds * 1_000, +}); +``` + +<details> +<summary>Complete TypeScript example: ssh/certificate.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function issueSSHCert( + client: Sandboxes, + sandboxName: string, + publicKey: string, + lifeSeconds: number, +) { + const sandbox = await client.get(sandboxName); + return sandbox.ssh.issueCertificate({ + publicKey, + ttlMs: lifeSeconds * 1_000, + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/get-image-pull-urls.md b/content/manuals/ai/sandboxes-api/cookbook/get-image-pull-urls.md new file mode 100644 index 000000000000..182772b83a63 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/get-image-pull-urls.md @@ -0,0 +1,45 @@ +--- +title: "Get image pull URLs" +linkTitle: "Get image pull URLs" +description: "Get the manifest details and short-lived download URLs for a managed image so a registry tool can pull its contents." +keywords: "cloud sandboxes, sandboxes api, get image pull urls" +weight: 507 +params: + sidebar: + group: "Connect and configure" +--- + +Obtain the registry references needed to pull a managed image with an OCI-compatible tool. This is useful when another part of your workflow needs the image content outside a sandbox. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and the image name returned by [image registration](register-and-manage-an-image.md). + +## Get the pull information {#1-get-the-pull-information} + +Read the image's pull specification. The result identifies its manifest digest and image references. + +Pass those references to your OCI client. This example only retrieves the pull information; it does not download layers or authenticate a separate registry client. Treat any returned access information as sensitive, and do not publish it in logs. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const image = await client.images.get(name); +return image.getPullSpec(); +``` + +<details> +<summary>Complete TypeScript example: pullspec/spec.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function getImagePullSpec(client: Sandboxes, name: string) { + const image = await client.images.get(name); + return image.getPullSpec(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/give-a-sandbox-an-mcp-gateway.md b/content/manuals/ai/sandboxes-api/cookbook/give-a-sandbox-an-mcp-gateway.md new file mode 100644 index 000000000000..1fcc590bb90a --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/give-a-sandbox-an-mcp-gateway.md @@ -0,0 +1,203 @@ +--- +title: "Give a sandbox an MCP gateway" +linkTitle: "Give a sandbox an MCP gateway" +description: "Configure MCP tools when launching a kit, then inspect, authorize, and manage the gateway." +keywords: "cloud sandboxes, sandboxes api, give a sandbox an mcp gateway" +weight: 403 +params: + sidebar: + group: "Security and policy" +--- + +Give an agent access to external tools through MCP, the Model Context Protocol. A gateway presents several tool servers through one endpoint. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and server IDs available to your account. Choose servers from the [Docker MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/) and use their catalog IDs, not display names invented by your application. Provider sign-in and permission to use each tool may be required. + +## Configure MCP when launching a kit {#1-configure-mcp-when-launching-a-kit} + +Supply the server IDs in the kit's MCP options when creating the sandbox. This makes gateway configuration available when the agent starts. Attach any model-provider secrets the agent needs separately. + +To add a gateway to an existing sandbox, recreate the sandbox with MCP configured. There is no separate gateway start or stop operation. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.kits.launch( + kitName, + { + resources: { cpus: 2, memoryMib: 4096 }, + mcp: { servers, static: true }, + storage: { secrets }, + }, + { timeoutMs: 300_000 }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: mcp/create.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function launchMcpKit( + client: Sandboxes, + kitName: string, + servers: string[], + secrets: string[] = [], +) { + const sandbox = await client.kits.launch( + kitName, + { + resources: { cpus: 2, memoryMib: 4096 }, + mcp: { servers, static: true }, + storage: { secrets }, + }, + { timeoutMs: 300_000 }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Read the gateway address {#2-read-the-gateway-address} + +Read the gateway by its `sandboxes/{sandbox}/mcp-gateway` name. The example waits through provisioning with the SDK's bounded waiter and returns the URL only when ready. A failed gateway or an expired wait returns an error. Supply a timeout appropriate for your application. + +Keep gateway credentials private. The gateway's address and the published URL of an application inside the sandbox are different endpoints. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const deadline = AbortSignal.timeout(options.timeoutMs); +const signal = options.signal + ? AbortSignal.any([options.signal, deadline]) + : deadline; +options = { ...options, signal }; +const observed = await client.getMcpGateway({ name }, options); +const gateway = await client + .mcpGateway(observed) + .waitFor(['ready', 'failed'], options); +if (gateway.state !== 'ready') + throw new Error('MCP gateway is not ready'); +if (!gateway.url) throw new Error('The ready MCP gateway has no URL'); +return gateway.url; +``` + +<details> +<summary>Complete TypeScript example: mcp/read.ts</summary> + +```typescript +import type { Sandboxes, WaitOptions } from '@docker/sandboxes'; + +export async function readGatewayUrl( + client: Sandboxes, + name: string, + options: WaitOptions = { timeoutMs: 120_000 }, +) { + const deadline = AbortSignal.timeout(options.timeoutMs); + const signal = options.signal + ? AbortSignal.any([options.signal, deadline]) + : deadline; + options = { ...options, signal }; + const observed = await client.getMcpGateway({ name }, options); + const gateway = await client + .mcpGateway(observed) + .waitFor(['ready', 'failed'], options); + if (gateway.state !== 'ready') + throw new Error('MCP gateway is not ready'); + if (!gateway.url) throw new Error('The ready MCP gateway has no URL'); + return gateway.url; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Add a catalog server {#3-add-a-catalog-server} + +Add a server to a ready, writable gateway. Adding a server already present does not add a second copy. A shared gateway attached by URL cannot be modified through this sandbox. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await sandbox.mcp.servers.add({ server }); +``` + +<details> +<summary>Complete TypeScript example: mcp/add.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function addMcpGatewayServer( + client: Sandboxes, + name: string, + server: string, +) { + const sandbox = await client.get(name.replace(/\/mcp-gateway$/, '')); + await sandbox.mcp.servers.add({ server }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Complete a server's sign-in {#4-complete-a-server-s-sign-in} + +Start authorization for a server that requires user sign-in. Present its authorization URL to the user, then read the authorization resource to check progress. The example performs the start and read calls; your application decides how to display and poll the flow. + +Only an authorized result means the credential is ready. Keep the authorization identity so a later attempt is not mistaken for completion of an earlier one. Request reauthorization only when you intend a new sign-in. + +Delete the sandbox when it is no longer needed. Its managed gateway is cleaned up with it; a shared gateway attached by URL remains available to its other users. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.mcp.authorizations.authorize({ + server: name, + forceReauth, +}); +``` + +<details> +<summary>Complete TypeScript example: mcp/authorize.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function authorizeMcpServer( + client: Sandboxes, + name: string, + forceReauth: boolean, +) { + return client.mcp.authorizations.authorize({ + server: name, + forceReauth, + }); +} + +export async function getMcpAuthorization( + client: Sandboxes, + name: string, +) { + return client.mcp.authorizations.get(name); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/handle-errors-and-degradation.md b/content/manuals/ai/sandboxes-api/cookbook/handle-errors-and-degradation.md new file mode 100644 index 000000000000..551c20e4ca7c --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/handle-errors-and-degradation.md @@ -0,0 +1,106 @@ +--- +title: "Handle errors and degradation" +linkTitle: "Handle errors and degradation" +description: "Tell an API refusal, a failed sandbox transition, and a nonzero command exit apart, and read the code and details each one carries." +keywords: "cloud sandboxes, sandboxes api, handle errors and degradation" +weight: 602 +params: + sidebar: + group: "Requests and responses" +--- + +Distinguish a rejected request from an accepted operation that later fails. This keeps retries from hiding invalid input or duplicating work. + +The SDK exposes typed request and wait errors. A command's nonzero exit code is a third outcome: the SDK can successfully observe a command that failed. + +## Classify the failure {#1-classify-the-failure} + +Use the error type and structured code, not the text of its message. The example groups common request failures and retains their details for the caller. + +- Invalid arguments need a corrected request. +- Authentication failures need a valid credential; permission failures need appropriate account access. +- A wrong-state error needs a state check before another attempt. +- A capacity or quota refusal may require waiting or reducing usage. +- A transient availability failure may be retryable if the operation can be repeated safely. + +Wait errors retain the state or resource observed before the wait stopped. Inspect that information and read the resource again when necessary. A failed create, an interrupted wait, and an expired client deadline do not have the same cleanup outcome. + +A process helper can fail while obtaining a sandbox credential or reading output after the process has started. The error retains the accepted process and its cause. That process may still be running: inspect it before deciding whether to retry the command. Inspect the cause chain for a typed credential-service rate-limit error, including any request identifier and retry delay supplied by the service. + +Unknown errors remain unknown in the example. They may be connection failures before any response arrived. Do not assume that a write was never accepted. + +Keep credentials and secret-bearing request bodies out of diagnostics. Record resource names, error codes, and request identifiers instead. See [safe retries](retry-without-creating-duplicates.md) before repeating a mutation. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +if (!(error instanceof RequestError)) { + return { kind: 'other', code: undefined, details: [] }; +} +const { code, details } = error.raw; +const known = KINDS.get(code); +return { kind: known ?? 'other', code, details: details ?? [] }; +``` + +<details> +<summary>Complete TypeScript example: failures/classify.ts</summary> + +```typescript +import { RequestError, ResourceWaitError } from '@docker/sandboxes'; + +type Status = RequestError['raw']; +type Detail = NonNullable<Status['details']>[number]; + +export type FailureKind = + | 'invalid-request' + | 'not-served' + | 'wrong-state' + | 'exhausted' + | 'access-or-missing' + | 'unavailable' + | 'other'; + +export interface Failure { + kind: FailureKind; + code: string | undefined; + details: Detail[]; +} + +const KINDS = new Map<string, FailureKind>([ + ['invalidArgument', 'invalid-request'], + ['unimplemented', 'not-served'], + ['failedPrecondition', 'wrong-state'], + ['resourceExhausted', 'exhausted'], + ['unauthenticated', 'access-or-missing'], + ['permissionDenied', 'access-or-missing'], + ['notFound', 'access-or-missing'], + ['unavailable', 'unavailable'], +]); + +export function readFailure(error: unknown): Failure { + if (!(error instanceof RequestError)) { + return { kind: 'other', code: undefined, details: [] }; + } + const { code, details } = error.raw; + const known = KINDS.get(code); + return { kind: known ?? 'other', code, details: details ?? [] }; +} + +export function readSandboxWait( + error: unknown, +): 'degraded' | 'failed' | 'other' { + if (error instanceof ResourceWaitError) { + if (error.kind === 'interrupted' && error.state === 'degraded') + return 'degraded'; + if (error.kind === 'failure' && error.state === 'failed') + return 'failed'; + } + return 'other'; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/keep-a-cloud-sandbox-running.md b/content/manuals/ai/sandboxes-api/cookbook/keep-a-cloud-sandbox-running.md new file mode 100644 index 000000000000..3030d112657b --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/keep-a-cloud-sandbox-running.md @@ -0,0 +1,114 @@ +--- +title: "Keep a cloud sandbox running" +linkTitle: "Keep a cloud sandbox running" +description: "Choose a sandbox's lifetime and what happens when it ends, then renew the lifetime before the deadline passes." +keywords: "cloud sandboxes, sandboxes api, keep a cloud sandbox running" +weight: 503 +params: + sidebar: + group: "Connect and configure" +--- + +Set a sandbox lifetime to prevent abandoned work from running indefinitely, and choose what happens when it expires. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and a managed image. The same lifecycle options can be supplied when launching a kit. + +## Set the lifetime at creation {#1-set-the-lifetime-at-creation} + +Pass the lifetime in the units shown by your SDK and choose the expiry action. The example accepts seconds and converts to the SDK's duration representation. + +Stopping preserves the sandbox for later use; deletion removes it. Check that your choice matches whether the application needs the sandbox's files after expiry. Account limits may restrict permitted durations and actions. + +Accounts with always-on access can instead select the restart action. This preserves memory through automatic stop-and-resume cycles. It retains a concurrency reservation while stopped and is different from restarting in response to an incoming request. + +The example waits for startup. Its wait deadline is separate from the sandbox lifetime: ending a client wait does not delete the sandbox. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { + displayName: name, + image, + lifecycle: { + timeoutMs: lifeSeconds * 1_000, + onTimeout: stopOnTimeout ? 'stop' : 'delete', + }, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: timeout/deadline.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createWithDeadline( + client: Sandboxes, + name: string, + image: string, + lifeSeconds: number, + stopOnTimeout: boolean, + requestId: string, +) { + const sandbox = await client.create( + { + displayName: name, + image, + lifecycle: { + timeoutMs: lifeSeconds * 1_000, + onTimeout: stopOnTimeout ? 'stop' : 'delete', + }, + }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Extend the remaining lifetime {#2-extend-the-remaining-lifetime} + +Use `renewTimeout()` to extend the sandbox's remaining lifetime. Pass the desired duration from the time the service accepts the renewal, not an increment to add to the existing deadline. Renewal can only extend the lifetime; it cannot shorten it. + +Renew a configured timeout before it expires. If the call fails, inspect the sandbox's current state instead of assuming that renewal took effect. + +The service manages timeouts for automatically restarting sandboxes; do not renew those yourself. + +For request-triggered restart after a stop, see [Resume on demand](let-a-stopped-sandbox-resume-on-demand.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.renewTimeout({ timeoutMs: remainingSeconds * 1_000 }); +``` + +<details> +<summary>Complete TypeScript example: timeout/renew.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function renewSandboxTimeout( + client: Sandboxes, + name: string, + remainingSeconds: number, +) { + const sandbox = await client.get(name); + return sandbox.renewTimeout({ timeoutMs: remainingSeconds * 1_000 }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/let-a-stopped-sandbox-resume-on-demand.md b/content/manuals/ai/sandboxes-api/cookbook/let-a-stopped-sandbox-resume-on-demand.md new file mode 100644 index 000000000000..8d1c8d002dbf --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/let-a-stopped-sandbox-resume-on-demand.md @@ -0,0 +1,108 @@ +--- +title: "Let a stopped sandbox resume on demand" +linkTitle: "Let a stopped sandbox resume on demand" +description: "Choose at creation whether a stopped cloud sandbox starts itself when a request arrives at one of its published ports, then read back the setting in force." +keywords: "cloud sandboxes, sandboxes api, let a stopped sandbox resume on demand" +weight: 508 +params: + sidebar: + group: "Connect and configure" +--- + +Let a request to a published application start a stopped sandbox. This can suit an application that should be available on demand without remaining active between uses. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and a managed image that starts the application. [Publish its port](expose-a-port-from-a-cloud-sandbox.md) before relying on requests to reach it. + +## Configure resume on creation {#1-configure-resume-on-creation} + +Set automatic resume in the sandbox's lifecycle options. Omit the value when you want the service default; explicitly set false to disable it. + +The example waits for the initial startup. Automatic resume does not recover a deleted sandbox, and it does not replace application startup configuration. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { displayName: name, image, lifecycle: { autoResume } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: wake/configure.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createWithAutoResume( + client: Sandboxes, + name: string, + image: string, + autoResume: boolean | undefined, + requestId: string, +) { + const sandbox = await client.create( + { displayName: name, image, lifecycle: { autoResume } }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Read the effective setting {#2-read-the-effective-setting} + +Get the sandbox and inspect the effective lifecycle automatic-resume value together with its state. The example falls back to the timeout value for older responses and reports an error if neither value is present. An absent value is unknown, not disabled. + +This checks what the service recorded; it does not send a request to the application or prove that the application can start. Authentication is still required. + +To verify the whole flow, stop the sandbox, request its published application URL, and confirm that the application becomes ready. Allow for startup time and keep the application's own authentication enabled. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.get(name); +const active = + sandbox.effectiveFeatures?.lifecycle?.autoResume ?? + sandbox.effectiveFeatures?.timeouts?.autoResume; +if (active == null) { + throw new Error(`sandbox ${name}: auto-resume setting is unknown`); +} +return { + autoResume: active, + status: sandbox.status, +}; +``` + +<details> +<summary>Complete TypeScript example: wake/verify.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function autoResumeInForce(client: Sandboxes, name: string) { + const sandbox = await client.get(name); + const active = + sandbox.effectiveFeatures?.lifecycle?.autoResume ?? + sandbox.effectiveFeatures?.timeouts?.autoResume; + if (active == null) { + throw new Error(`sandbox ${name}: auto-resume setting is unknown`); + } + return { + autoResume: active, + status: sandbox.status, + }; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/manage-cloud-secrets.md b/content/manuals/ai/sandboxes-api/cookbook/manage-cloud-secrets.md new file mode 100644 index 000000000000..f404fb1c8ba5 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/manage-cloud-secrets.md @@ -0,0 +1,153 @@ +--- +title: "Manage cloud secrets" +linkTitle: "Manage cloud secrets" +description: "Store a token as a stored secret, list your secrets' metadata, replace the token, and delete the secret." +keywords: "cloud sandboxes, sandboxes api, manage cloud secrets" +weight: 402 +params: + sidebar: + group: "Security and policy" +--- + +Store workload credentials separately from application code. Secret reads return metadata only, so keep the original credential in your secret manager if you need it elsewhere. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md). These examples store a token for a named service. For instructions on giving a kit access to that token, see [Get a stored secret into a sandbox](get-a-stored-secret-into-a-sandbox.md). + +## Create a secret {#1-create-a-secret} + +Pass a display name, service type, token value, and idempotency key. Save the returned resource name for attachments and future updates. Do not log the request or token. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.secrets.create( + { displayName: name, serviceType, token: { value: token } }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: secrets/create.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createSecret( + client: Sandboxes, + name: string, + serviceType: string, + token: string, + requestId: string, +) { + return client.secrets.create( + { displayName: name, serviceType, token: { value: token } }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## List stored credentials {#2-list-stored-credentials} + +List secret metadata to find a credential by name or label. The example follows each page. Listing does not reveal secret values. + +Use the resource name, not the display name, when attaching a secret to a sandbox. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.secrets.all().collect(); +``` + +<details> +<summary>Complete TypeScript example: secrets/list.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function listSecrets(client: Sandboxes) { + return client.secrets.all().collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Rotate the credential {#3-rotate-the-credential} + +Read the existing secret, then update it through a handle with the replacement value and service type. The handle carries the version it read so an intervening change is detected. + +The update replaces the record's writable content. Send the service type again instead of assuming omitted values are preserved. Keep the returned metadata for subsequent operations. + +If another writer changed the secret, read it again and decide whether to apply your replacement. Do not silently overwrite another rotation. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return secret.update( + { serviceType, token: { value: token } }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: secrets/update.ts</summary> + +```typescript +import type { Secret } from '@docker/sandboxes'; + +export async function updateSecret( + secret: Secret, + serviceType: string, + token: string, + requestId: string, +) { + return secret.update( + { serviceType, token: { value: token } }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Delete a secret {#4-delete-a-secret} + +Delete through the secret handle when no workload needs the credential. Deleting an already absent secret is safe for repeated cleanup. + +Removing a stored secret is not a substitute for revoking a leaked credential with its provider. Revoke compromised credentials and replace them before starting new workloads. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await secret.delete(); +``` + +<details> +<summary>Complete TypeScript example: secrets/delete.ts</summary> + +```typescript +import type { Secret } from '@docker/sandboxes'; + +export async function deleteSecret(secret: Secret) { + await secret.delete(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/manage-network-policies.md b/content/manuals/ai/sandboxes-api/cookbook/manage-network-policies.md new file mode 100644 index 000000000000..a0f1e1fd7875 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/manage-network-policies.md @@ -0,0 +1,75 @@ +--- +title: "Manage network policies" +linkTitle: "Manage network policies" +description: "Create, read, update, and delete personal network policies through the SDK." +keywords: "cloud sandboxes, sandboxes api, manage network policies" +weight: 406 +params: + sidebar: + group: "Security and policy" +--- + +Create reusable network policies in your Docker account, then attach their IDs when creating sandboxes. The SDK's governance collection uses the same Docker authentication as the sandbox client. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md). These methods manage your personal policies, not organization-wide administration. + +## Manage a policy's lifetime {#1-manage-a-policy-s-lifetime} + +The example creates a policy, lists the available policies, reads the new one, and replaces its definition. It attempts to delete the temporary policy in cleanup, including when a later step fails. Check cleanup errors; a cancelled request can leave the policy behind. + +Supply a policy definition and a replacement using your SDK's policy input type. Include the destinations your workload needs. For a deny-by-default policy, allow the agent's model provider and any required package registries explicitly. + +Set `status: 'POLICY_STATUS_ACTIVE'` on both the policy and its replacement. Although the SDK type makes this field optional, the service rejects omitted or other values with `unimplemented`. + +An update replaces the definition rather than appending rules. Read the existing policy before deciding what to retain. Personal-policy mutations are not automatically replayed, so inspect the current state after an uncertain result before trying again. + +This is a disposable policy-management example: the returned policy ID has been deleted by the time the function finishes. To keep a policy for real workloads, remove that demonstration cleanup and store its ID with your application configuration. Follow [Control what a sandbox can reach](control-what-a-sandbox-can-reach.md) to attach it and inspect enforced rules. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const created = await client.governance.policies.create(policy); +try { + const listed = await client.governance.policies.list(); + const current = await client.governance.policies.get(created.id); + const updated = await client.governance.policies.update( + created.id, + replacement, + ); + return { listed, current, updated }; +} finally { + await client.governance.policies.delete(created.id); +} +``` + +<details> +<summary>Complete TypeScript example: policies/manage.ts</summary> + +```typescript +import type { GovernancePolicyInput, Sandboxes } from '@docker/sandboxes'; + +export async function managePolicy( + client: Sandboxes, + policy: GovernancePolicyInput, + replacement: GovernancePolicyInput, +) { + const created = await client.governance.policies.create(policy); + try { + const listed = await client.governance.policies.list(); + const current = await client.governance.policies.get(created.id); + const updated = await client.governance.policies.update( + created.id, + replacement, + ); + return { listed, current, updated }; + } finally { + await client.governance.policies.delete(created.id); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/page-through-and-filter-lists.md b/content/manuals/ai/sandboxes-api/cookbook/page-through-and-filter-lists.md new file mode 100644 index 000000000000..3b4eed459913 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/page-through-and-filter-lists.md @@ -0,0 +1,76 @@ +--- +title: "Page through and filter lists" +linkTitle: "Page through and filter lists" +description: "Walk every page of a list with the SDK's iterators, and narrow a list on the server with a filter and an ordering." +keywords: "cloud sandboxes, sandboxes api, page through and filter lists" +weight: 604 +params: + sidebar: + group: "Requests and responses" +--- + +List resources without losing results at page boundaries. SDK collection iterators request each page for you; collecting materializes the complete result in memory. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md). For a large account, process iterator items as they arrive instead of collecting them all. + +## Walk every sandbox {#1-walk-every-sandbox} + +Set a page size and iterate the sandbox collection. The example collects the results for convenience. A page size controls each request, not the total number of returned resources. + +When using one-page methods directly, pass the returned next-page token unchanged and keep the filter, order, and page size stable. Stop when no next token is returned, not when a page contains fewer items than requested. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.all({ pageSize }).collect(); +``` + +<details> +<summary>Complete TypeScript example: pagination/walk.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function walkSandboxes(client: Sandboxes, pageSize: number) { + return client.all({ pageSize }).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Filter and order the result {#2-filter-and-order-the-result} + +Pass a filter and ordering supported by the collection. The example uses images; choose a filter such as `status=completed` to select ready images. + +Filters are strings interpreted by the service. Use the field names and operators documented for that list method rather than a language object's property names. An invalid filter should be fixed, not silently removed and retried as an unfiltered list. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.images.all({ filter, orderBy }).collect(); +``` + +<details> +<summary>Complete TypeScript example: pagination/filter.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function filterImages( + client: Sandboxes, + filter: string, + orderBy: string, +) { + return client.images.all({ filter, orderBy }).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/read-files-out-of-a-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/read-files-out-of-a-sandbox.md new file mode 100644 index 000000000000..6ae6a23ea210 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/read-files-out-of-a-sandbox.md @@ -0,0 +1,212 @@ +--- +title: "Read files out of a sandbox" +linkTitle: "Read files out of a sandbox" +description: "List a directory in a running cloud sandbox, download files from it into memory, then move or remove paths inside it." +keywords: "cloud sandboxes, sandboxes api, read files out of a sandbox" +weight: 203 +params: + sidebar: + group: "Working in a sandbox" +--- + +Read build results, inspect project files, or copy data out before deleting a sandbox. Start with a running sandbox handle and an absolute path inside it. + +The examples return content to your application. To keep it on your machine, write the received bytes to a local file. + +## List a directory {#1-list-a-directory} + +Walk the directory through the file collection's iterator. It follows pagination and returns the entries. Listing gives metadata, not file content. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.files.all(path).collect(); +``` + +<details> +<summary>Complete TypeScript example: download/list.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function listDirectory(sandbox: Sandbox, path: string) { + return sandbox.files.all(path).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Read a small text file {#2-read-a-small-text-file} + +Use the bounded read helper for text you want in memory. The example limits the read to one MiB. Choose a bound that fits your application's memory budget, or download a larger file as a stream. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.files.read(path, { + encoding: 'utf8', + maxBytes: 1024 * 1024, +}); +``` + +<details> +<summary>Complete TypeScript example: download/read.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function readFile(sandbox: Sandbox, path: string) { + return sandbox.files.read(path, { + encoding: 'utf8', + maxBytes: 1024 * 1024, + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Inspect a path {#3-inspect-a-path} + +Read metadata before deciding whether to download, move, or remove a path. A successful metadata read does not reserve the file: another process may change it afterward. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.files.stat(path); +``` + +<details> +<summary>Complete TypeScript example: download/stat.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function statFile(sandbox: Sandbox, path: string) { + return sandbox.files.stat(path); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Download a file as a stream {#4-download-a-file-as-a-stream} + +Pass the sandbox path and a callback or writer that consumes bytes. The example closes the transfer when it finishes or fails. + +Treat the download as complete only when it ends successfully. If it fails halfway through, discard or separately identify the partial local file before retrying. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const download = await sandbox.files.download(path); +try { + for await (const chunk of download) write(chunk); +} finally { + await download.close(); +} +``` + +<details> +<summary>Complete TypeScript example: download/download.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function downloadFiles( + sandbox: Sandbox, + path: string, + write: (bytes: Uint8Array) => void, +) { + const download = await sandbox.files.download(path); + try { + for await (const chunk of download) write(chunk); + } finally { + await download.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Move a path {#5-move-a-path} + +Pass the current path and destination. This moves data inside the sandbox; it does not download anything to your computer. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await sandbox.files.move(from, to); +``` + +<details> +<summary>Complete TypeScript example: download/move.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function movePath( + sandbox: Sandbox, + from: string, + to: string, +) { + await sandbox.files.move(from, to); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Remove a path {#6-remove-a-path} + +Remove a file, or enable recursive removal for a directory tree. Check the result for a failed path rather than assuming that every requested removal succeeded. + +Recursive removal is destructive. Keep user-supplied paths constrained to the directory your application owns. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const result = await sandbox.files.remove(path, { recursive }); +if (result.failedPath) + throw new Error(`Remove ${path} stopped at ${result.failedPath}`); +``` + +<details> +<summary>Complete TypeScript example: download/remove.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function removePath( + sandbox: Sandbox, + path: string, + recursive: boolean, +) { + const result = await sandbox.files.remove(path, { recursive }); + if (result.failedPath) + throw new Error(`Remove ${path} stopped at ${result.failedPath}`); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/recover-when-the-endpoint-moves.md b/content/manuals/ai/sandboxes-api/cookbook/recover-when-the-endpoint-moves.md new file mode 100644 index 000000000000..d5728c2bf182 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/recover-when-the-endpoint-moves.md @@ -0,0 +1,88 @@ +--- +title: "Recover when the endpoint moves" +linkTitle: "Recover when the endpoint moves" +description: "Read a sandbox again to learn its current endpoint, then run one command through a connection built for that endpoint." +keywords: "cloud sandboxes, sandboxes api, recover when the endpoint moves" +weight: 704 +params: + sidebar: + group: "Long-running work" +--- + +Refresh a sandbox handle after a restart or connection change. A saved address can become stale even though the sandbox still has the same resource name. + +Start with the handle your application already holds. Keep its name and UID; do not replace them with another sandbox's identity. + +## Compare the current endpoint {#1-compare-the-current-endpoint} + +Refresh the handle, then compare the old and new connection information. The SDK checks the resource identity while constructing the refreshed handle. + +The example reports whether the endpoint changed and returns a refreshed handle. Use that handle for later process and file calls. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const current = await held.refresh(); +const before = held.core.endpoint; +const after = current.core.endpoint; +return { + moved: + before?.uri !== after?.uri || before?.protocol !== after?.protocol, + current, +}; +``` + +<details> +<summary>Complete TypeScript example: rebind/detect.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function endpointMoved(held: Sandbox) { + const current = await held.refresh(); + const before = held.core.endpoint; + const after = current.core.endpoint; + return { + moved: + before?.uri !== after?.uri || before?.protocol !== after?.protocol, + current, + }; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Run through the refreshed handle {#2-run-through-the-refreshed-handle} + +Refresh before opening a new process connection. The SDK obtains the appropriate sandbox credential for the current endpoint; your application does not need to pass its Docker account token there. + +This example starts new work after refresh. It does not replay a command whose completion is unknown. If an earlier command may still be running, [find and reconnect to it](find-a-process-you-lost-track-of.md) first. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const current = await held.refresh(); +return current.processes.run({ args }, { timeoutMs: 300_000 }); +``` + +<details> +<summary>Complete TypeScript example: rebind/rebuild.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function runAndRebind(held: Sandbox, args: string[]) { + const current = await held.refresh(); + return current.processes.run({ args }, { timeoutMs: 300_000 }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/register-and-manage-an-image.md b/content/manuals/ai/sandboxes-api/cookbook/register-and-manage-an-image.md new file mode 100644 index 000000000000..a74f1aad8d9a --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/register-and-manage-an-image.md @@ -0,0 +1,148 @@ +--- +title: "Register and manage an image" +linkTitle: "Register and manage an image" +description: "Register an image with Cloud Sandboxes, get the target to push its content to, check when it is ready, list your images, and delete one you no longer need." +keywords: "cloud sandboxes, sandboxes api, register and manage an image" +weight: 301 +params: + sidebar: + group: "Packaging and state" +--- + +Reuse an image across sandboxes by registering it with Docker Cloud Sandboxes. Registration creates an image record and a temporary upload destination. You must push the image content separately with an OCI-compatible registry client. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and a built image. If you already have an image in a registry, [run it directly](run-your-own-container-image.md) instead. + +## Register an upload destination {#1-register-an-upload-destination} + +Choose a display name, startup command, CPU and memory preferences, and an idempotency key. The returned image includes its resource name and a push target. + +Use the target's registry reference and temporary credential to push your image. Keep that credential private and finish before it expires. Save the target from the initial response: later image reads do not issue a replacement upload credential. + +This example registers the destination. It does not build or push image content. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.images.create( + { displayName: name, fromImage: { resources }, startCmd }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: images/create.ts</summary> + +```typescript +import type { + ClientImagesCreateOptions, + Sandboxes, +} from '@docker/sandboxes'; + +export async function createImage( + client: Sandboxes, + name: string, + startCmd: string[], + resources: Extract< + ClientImagesCreateOptions, + { fromImage: unknown } + >['fromImage']['resources'], + requestId: string, +) { + return client.images.create( + { displayName: name, fromImage: { resources }, startCmd }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Check preparation status {#2-check-preparation-status} + +After the push finishes, read the image by its resource name. A `COMPLETED` status means it is ready to use. `WAITING_FOR_PUSH` means content has not arrived, `PREPARING` means preparation is in progress, and `FAILED` includes failure details. + +The example performs one read. If preparation is still in progress, repeat the read with a delay and deadline. Repeating creation would register another image rather than advance this one. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.images.get(name); +``` + +<details> +<summary>Complete TypeScript example: images/ready.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function getImage(client: Sandboxes, name: string) { + return client.images.get(name); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Find registered images {#3-find-registered-images} + +List images with an optional filter, such as `status=completed`. The example follows all pages. List entries are summaries; get the image by name when you need its complete record. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.images.all({ filter }).collect(); +``` + +<details> +<summary>Complete TypeScript example: images/list.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function listImages(client: Sandboxes, filter: string) { + return client.images.all({ filter }).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Remove an image {#4-remove-an-image} + +Read the image and delete through its handle. The SDK supplies its name and version to protect against deleting a newer record you have not read. + +Keep images that future sandbox creations still depend on. Deleting an already absent image is safe for cleanup. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await image.delete(); +``` + +<details> +<summary>Complete TypeScript example: images/delete.ts</summary> + +```typescript +import type { Image } from '@docker/sandboxes'; + +export async function deleteImage(image: Image) { + await image.delete(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/retry-without-creating-duplicates.md b/content/manuals/ai/sandboxes-api/cookbook/retry-without-creating-duplicates.md new file mode 100644 index 000000000000..20af1095bb9e --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/retry-without-creating-duplicates.md @@ -0,0 +1,127 @@ +--- +title: "Retry without creating duplicates" +linkTitle: "Retry without creating duplicates" +description: "Retry a sandbox or process create under one request ID so a failure you can't interpret never leaves two copies behind." +keywords: "cloud sandboxes, sandboxes api, retry without creating duplicates" +weight: 603 +params: + sidebar: + group: "Requests and responses" +--- + +Retry a request without creating duplicate work. An idempotency key identifies one logical operation, such as creating the sandbox for a particular job. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md). Generate the key once, then persist it with the job if retries can happen in another program run. + +## Retry the same create request {#1-retry-the-same-create-request} + +Reuse the same key and payload on every attempt. The example retries a transient availability refusal and disables automatic SDK retries. Do not run your own retry loop and the SDK's together without accounting for their total attempts. + +Use a deadline and a bounded attempt count. For production retry scheduling, add delay and jitter or use the SDK's configured retry behavior. Changing the payload while keeping the key is not an update; it conflicts with the original request. + +An accepted creation returns the sandbox's resource data. Save its name and use the client's get method to obtain a handle. Read or wait on that resource to follow progress instead of repeating creation to make it advance. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +for (let attempt = 0; attempt < attempts; attempt++) { + try { + return await client.kits.launch( + 'shell', + { displayName, resources: { cpus: 2, memoryMib: 4096 } }, + { + idempotencyKey: requestId, + timeoutMs: 300_000, + signal, + maxRetries: 0, + }, + ); + } catch (error) { + if ( + !(error instanceof RequestError) || + error.raw.code !== 'unavailable' || + attempt + 1 === attempts + ) + throw error; + } +} +``` + +<details> +<summary>Complete TypeScript example: idempotency/retry.ts</summary> + +```typescript +import { RequestError, type Sandboxes } from '@docker/sandboxes'; + +export async function createWithRetry( + client: Sandboxes, + displayName: string, + requestId: string, + attempts: number, +) { + if (!Number.isInteger(attempts) || attempts < 1) + throw new RangeError('attempts must be at least 1'); + const signal = AbortSignal.timeout(300_000); + for (let attempt = 0; attempt < attempts; attempt++) { + try { + return await client.kits.launch( + 'shell', + { displayName, resources: { cpus: 2, memoryMib: 4096 } }, + { + idempotencyKey: requestId, + timeoutMs: 300_000, + signal, + maxRetries: 0, + }, + ); + } catch (error) { + if ( + !(error instanceof RequestError) || + error.raw.code !== 'unavailable' || + attempt + 1 === attempts + ) + throw error; + } + } + throw new Error('attempt count was validated'); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Start a process once {#2-start-a-process-once} + +Start the process with its own idempotency key and keep the returned process name. After losing a response or connection, find that process before starting another one. + +Keys do not make every operation safe to replay. Repeating process input, a signal, or a file write can have a second effect. Use [process reconnection](find-a-process-you-lost-track-of.md) for a lost stream and inspect files before repeating an uncertain write. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes.start({ args }, { idempotencyKey: requestId }); +``` + +<details> +<summary>Complete TypeScript example: idempotency/unsafe.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function createProcessOnce( + sandbox: Sandbox, + args: string[], + requestId: string, +) { + return sandbox.processes.start({ args }, { idempotencyKey: requestId }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-a-complete-example.md b/content/manuals/ai/sandboxes-api/cookbook/run-a-complete-example.md new file mode 100644 index 000000000000..f4a8431e212d --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-a-complete-example.md @@ -0,0 +1,109 @@ +--- +title: "Run a complete example" +linkTitle: "Run a complete example" +description: "Sign in, launch the shell kit, print a greeting, and clean up with one runnable program." +keywords: "cloud sandboxes, sandboxes api, run a complete example" +weight: 102 +params: + sidebar: + group: "Get started" +--- + +Run a small program that signs in to Docker, creates a sandbox from the `shell` kit, prints a greeting, and deletes the sandbox. You do not need a model-provider key for this example. + +[Install your SDK](https://docs.docker.com/ai/sandboxes-api/install/) first. Your Docker account must have Cloud Sandboxes access and billing set up. This program creates a real sandbox with 2 CPUs and 4096 MiB of memory; compute usage is subject to your Docker billing terms. + +## Run the program {#1-run-the-program} + +Expand the complete example and copy the whole program into a file. Save it as `example.mts`, then run `npx tsx example.mts`. + +The program prints a verification URL and code. Open the URL, enter the code, and approve sign-in. Your terminal then shows the sandbox's name and `Hello from Docker Sandboxes`. The program checks the command's exit status and attempts to delete its sandbox before closing the client. + +The program waits for sign-in to finish or the verification code to expire. After sign-in, creating the sandbox and running the command share a five-minute time limit. Once the program receives the new sandbox's details, it allows another 30 seconds to delete that sandbox, even if a later step fails. + +If sign-in fails, follow the steps in [Authenticate to Docker](connect-to-cloud-with-a-bearer-token.md). If sandbox creation fails, check account access and [resource limits](work-within-the-limits.md). + +A creation timeout can occur after Docker creates the sandbox but before the program receives its details. In that case, the program cannot delete it. [List your sandboxes](page-through-and-filter-lists.md) to check for a sandbox created by this run and [delete it](delete-a-cloud-sandbox.md) if needed. If deletion fails or times out, use the sandbox name printed in your terminal to check whether it still exists. + +This example deletes its sandbox because it is a one-off demonstration. Next, [keep a sandbox for later work](create-your-first-sandbox.md) or [run an agent kit](add-tools-with-kits.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const result = await sandbox.processes.run( + { + args: ['echo', 'Hello from Docker Sandboxes'], + }, + operation, +); +console.log(result.stdout); +``` + +<details> +<summary>Complete TypeScript example: hello/main.ts</summary> + +```typescript +import { pathToFileURL } from 'node:url'; +import { oauth, Sandboxes, type Sandbox } from '@docker/sandboxes'; + +export async function main() { + const auth = oauth({ + onVerification: ({ verificationUri, userCode }) => { + console.log(`Open ${verificationUri} and enter ${userCode}`); + }, + }); + const client = new Sandboxes({ auth }); + let sandbox: Sandbox | undefined; + try { + await auth.getAccessToken(); + const operation = { + signal: AbortSignal.timeout(300_000), + timeoutMs: 300_000, + }; + sandbox = await client.kits.launch( + 'shell', + { + resources: { cpus: 2, memoryMib: 4096 }, + }, + operation, + ); + console.log(`Sandbox: ${sandbox.name}`); + sandbox = await sandbox.waitUntilRunning(operation); + const result = await sandbox.processes.run( + { + args: ['echo', 'Hello from Docker Sandboxes'], + }, + operation, + ); + console.log(result.stdout); + if (result.exitCode !== 0) + throw new Error(`Command exited with status ${result.exitCode}`); + } finally { + try { + if (sandbox) { + const cleanup = { signal: AbortSignal.timeout(30_000) }; + const deleting = await sandbox.delete({ force: true }, cleanup); + await deleting?.waitUntilDeleted(cleanup); + } + } finally { + await client.close(); + } + } +} + +if ( + process.argv[1] && + import.meta.url === pathToFileURL(process.argv[1]).href +) { + main().catch((error: unknown) => { + console.error(error); + process.exitCode = 1; + }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-an-interactive-shell-in-a-cloud-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/run-an-interactive-shell-in-a-cloud-sandbox.md new file mode 100644 index 000000000000..e8dd32c7754d --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-an-interactive-shell-in-a-cloud-sandbox.md @@ -0,0 +1,220 @@ +--- +title: "Run an interactive shell in a cloud sandbox" +linkTitle: "Run an interactive shell in a cloud sandbox" +description: "Start a shell on a pseudo-terminal, send it input and read its output over one connection, connect again and pick up the output the service kept, and stop it." +keywords: "cloud sandboxes, sandboxes api, run an interactive shell in a cloud sandbox" +weight: 201 +params: + sidebar: + group: "Working in a sandbox" +--- + +Run a process with a terminal when it expects interactive input. A terminal session differs from a captured command: you manage input, output, and connection lifetime. + +Use a running sandbox handle from [your first sandbox](create-your-first-sandbox.md). Pass the command as an argument array, such as `['sh']`. + +## Start a terminal process {#1-start-a-terminal-process} + +Start the process with a pseudo-terminal and an initial terminal size. The returned process handle identifies this session. Save its resource name if you want to reconnect later. + +Use one idempotency key for this start request. Reconnecting does not require starting another process. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes.start( + { args, pty: { initialSize: { rows: 40, cols: 120 } } }, + { idempotencyKey: requestId }, +); +``` + +<details> +<summary>Complete TypeScript example: shell/create.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function createProcess( + sandbox: Sandbox, + args: string[], + requestId: string, +) { + return sandbox.processes.start( + { args, pty: { initialSize: { rows: 40, cols: 120 } } }, + { idempotencyKey: requestId }, + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Send input and read output {#2-send-input-and-read-output} + +Connect to the process, write input, and consume output events. This example sends a finite input buffer and closes standard input; a terminal application should keep input open until the user finishes. + +Forward output chunks to your terminal or callback. An exit event reports the process exit code. A connection ending without that event does not establish that the command finished. + +Close the connection when you stop consuming it. Closing a connection and terminating the process are separate actions. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const connection = await process.connect(); +try { + await connection.write(stdin); + await connection.closeStdin(); + for await (const event of connection) { + if (event.type === 'chunk') + write( + event.data ?? new Uint8Array(), + BigInt(event.streamSequence ?? '0'), + ); + if (event.type === 'exited') return event.exitCode ?? 0; + } + throw new Error( + `Stream for ${process.name} ended before the process exited`, + ); +} finally { + await connection.close(); +} +``` + +<details> +<summary>Complete TypeScript example: shell/attach.ts</summary> + +```typescript +import type { Process } from '@docker/sandboxes'; + +export async function attachToProcess( + process: Process, + stdin: Uint8Array, + write: (bytes: Uint8Array, sequence: bigint) => void, +) { + const connection = await process.connect(); + try { + await connection.write(stdin); + await connection.closeStdin(); + for await (const event of connection) { + if (event.type === 'chunk') + write( + event.data ?? new Uint8Array(), + BigInt(event.streamSequence ?? '0'), + ); + if (event.type === 'exited') return event.exitCode ?? 0; + } + throw new Error( + `Stream for ${process.name} ended before the process exited`, + ); + } finally { + await connection.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Resume output after a disconnect {#3-resume-output-after-a-disconnect} + +Record the sequence number after handling each output chunk. On reconnect, pass the last handled sequence number to resume after that point. + +Connections opened through TypeScript process handles resume automatically after temporary disconnects while you consume output. They use the last chunk delivered to your application, not the last chunk your application saved elsewhere. Raw streams require explicit reconnection. Keep your own cursor if you need to resume after an application restart. Input is never replayed; if a write fails, check the process before sending that input again. + +Retain the process name with the cursor. A cursor from one process cannot identify output from another. Persist the cursor only after your application has handled the corresponding output. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const connection = await process.connect({ resumeFrom }); +let lastSequence = BigInt(resumeFrom); +try { + for await (const event of connection) { + if (event.type === 'chunk') { + write( + event.data ?? new Uint8Array(), + (lastSequence = BigInt(event.streamSequence ?? '0')), + ); + } + } + return lastSequence; +} finally { + await connection.close(); +} +``` + +<details> +<summary>Complete TypeScript example: shell/resume.ts</summary> + +```typescript +import type { Process } from '@docker/sandboxes'; + +export async function resumeProcessOutput( + process: Process, + resumeFrom: bigint, + write: (bytes: Uint8Array, sequence: bigint) => void, +) { + const connection = await process.connect({ resumeFrom }); + let lastSequence = BigInt(resumeFrom); + try { + for await (const event of connection) { + if (event.type === 'chunk') { + write( + event.data ?? new Uint8Array(), + (lastSequence = BigInt(event.streamSequence ?? '0')), + ); + } + } + return lastSequence; + } finally { + await connection.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Send a signal {#4-send-a-signal} + +Get the process by name and send the signal your application intends. Use a graceful termination signal when the process should clean up its own files. + +Signals operate on the process; they do not delete the sandbox. [Delete the sandbox](delete-a-cloud-sandbox.md) separately when all work is finished. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const process = await sandbox.processes.get(name); +await process.signal(signal); +``` + +<details> +<summary>Complete TypeScript example: shell/signal.ts</summary> + +```typescript +import type { Sandbox, Process } from '@docker/sandboxes'; + +export async function signalProcess( + sandbox: Sandbox, + name: string, + signal: Parameters<Process['signal']>[0], +) { + const process = await sandbox.processes.get(name); + await process.signal(signal); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-something-that-produces-real-output.md b/content/manuals/ai/sandboxes-api/cookbook/run-something-that-produces-real-output.md new file mode 100644 index 000000000000..a9b105636dab --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-something-that-produces-real-output.md @@ -0,0 +1,111 @@ +--- +title: "Run something that produces real output" +linkTitle: "Run something that produces real output" +description: "Choose between a call that returns a command's captured output when it finishes and a process whose output you read while it runs." +keywords: "cloud sandboxes, sandboxes api, run something that produces real output" +weight: 210 +params: + sidebar: + group: "Working in a sandbox" +--- + +Choose how your application receives command output. Captured output is convenient for a short command; streaming lets you display progress or process output without waiting for completion. + +Start with a running sandbox handle from [your first sandbox](create-your-first-sandbox.md). Supply the command as an argument array. + +## Collect the result {#1-collect-the-result} + +Run the process and wait for its result. Inspect standard output, standard error, and the exit code. Use an application deadline so a command cannot hold your request open indefinitely. + +This form accumulates output for you. Prefer streaming when output could be large or your user needs progress updates. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes.run({ args }, { timeoutMs: 300_000 }); +``` + +<details> +<summary>Complete TypeScript example: longrun/choose.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function collectOutput(sandbox: Sandbox, args: string[]) { + return sandbox.processes.run({ args }, { timeoutMs: 300_000 }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Stream output as it arrives {#2-stream-output-as-it-arrives} + +Start the process, connect to it, and consume output events. The example forwards each output chunk to a callback and returns the exit code from the exit event. + +The callback owns what happens to each chunk: display it, append it to a file, or send it to a client. Do not log sensitive output indiscriminately. + +Always close the connection. A stream that ends before an exit event is an incomplete observation, not proof of success. Keep the process name to [reconnect](find-a-process-you-lost-track-of.md) rather than immediately starting a duplicate command. + +Connections opened through TypeScript process handles reconnect after temporary disconnects while you consume output. They resume after the last delivered chunk and stop if recovery exceeds 30 seconds, without replaying process input. These connections have no default lifetime limit once connected, but a timeout you supply still limits the whole session. Raw streams require explicit reconnection. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const process = await sandbox.processes.start( + { args }, + { idempotencyKey: requestId }, +); +const connection = await process.connect(); +try { + for await (const event of connection) { + if (event.type === 'chunk') write(event.data ?? new Uint8Array()); + if (event.type === 'exited') return event.exitCode ?? 0; + } + throw new Error( + `Output of ${process.name} ended before the command exited`, + ); +} finally { + await connection.close(); +} +``` + +<details> +<summary>Complete TypeScript example: longrun/stream.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function streamOutput( + sandbox: Sandbox, + args: string[], + requestId: string, + write: (bytes: Uint8Array) => void, +) { + const process = await sandbox.processes.start( + { args }, + { idempotencyKey: requestId }, + ); + const connection = await process.connect(); + try { + for await (const event of connection) { + if (event.type === 'chunk') write(event.data ?? new Uint8Array()); + if (event.type === 'exited') return event.exitCode ?? 0; + } + throw new Error( + `Output of ${process.name} ended before the command exited`, + ); + } finally { + await connection.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-work-across-many-sandboxes.md b/content/manuals/ai/sandboxes-api/cookbook/run-work-across-many-sandboxes.md new file mode 100644 index 000000000000..8be8dc7c4bbd --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-work-across-many-sandboxes.md @@ -0,0 +1,126 @@ +--- +title: "Run work across many sandboxes" +linkTitle: "Run work across many sandboxes" +description: "Run one command on every running sandbox you hold, a bounded number at a time, and read one answer per sandbox even when some of them fail." +keywords: "cloud sandboxes, sandboxes api, run work across many sandboxes" +weight: 703 +params: + sidebar: + group: "Long-running work" +--- + +Run a command across several existing sandboxes while keeping concurrency bounded. This can collect diagnostics or apply the same task to a group of independent workspaces. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and an argument array. Only run the command in sandboxes your application owns for this task. + +## Select running sandboxes {#1-select-running-sandboxes} + +Walk the sandbox collection and retain running handles. The example selects all running sandboxes visible to the client; narrow that selection to your application's jobs before executing a command with side effects. + +Listing and execution are separate requests. A sandbox can change state between them, so the execution step still needs to handle failures. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const running: Sandbox[] = []; +for await (const sandbox of client.all()) { + if (sandbox.status === 'running') running.push(sandbox); +} +return running; +``` + +<details> +<summary>Complete TypeScript example: fanout/spread.ts</summary> + +```typescript +import type { Sandbox, Sandboxes } from '@docker/sandboxes'; + +export async function runningSandboxes(client: Sandboxes) { + const running: Sandbox[] = []; + for await (const sandbox of client.all()) { + if (sandbox.status === 'running') running.push(sandbox); + } + return running; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Collect individual results {#2-collect-individual-results} + +Choose a concurrency bound and run the command on each selected sandbox. The example keeps each result or failure alongside the sandbox name, so one failed request does not discard every other result. + +Inspect both request failures and process exit codes. A returned process result can contain a nonzero exit code. + +Keep concurrency below your account's limits and your application's memory budget. For large output, stream results instead of collecting them all. The example does not delete the existing sandboxes. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const outcomes: Outcome[] = []; +const size = Number.isFinite(bound) ? Math.max(1, Math.trunc(bound)) : 1; +for (let start = 0; start < sandboxes.length; start += size) { + const group = sandboxes.slice(start, start + size); + const settled = await Promise.allSettled( + group.map((sandbox) => + sandbox.processes.run({ args }, { timeoutMs: 300_000 }), + ), + ); + settled.forEach((result, index) => { + outcomes.push( + result.status === 'fulfilled' + ? { sandboxName: group[index].name, response: result.value } + : { sandboxName: group[index].name, failure: result.reason }, + ); + }); +} +return outcomes; +``` + +<details> +<summary>Complete TypeScript example: fanout/gather.ts</summary> + +```typescript +import type { RunResult, Sandbox } from '@docker/sandboxes'; + +export type Outcome = { + sandboxName: string; + response?: RunResult; + failure?: unknown; +}; + +export async function runOnEach( + sandboxes: Sandbox[], + args: string[], + bound: number, +) { + const outcomes: Outcome[] = []; + const size = Number.isFinite(bound) ? Math.max(1, Math.trunc(bound)) : 1; + for (let start = 0; start < sandboxes.length; start += size) { + const group = sandboxes.slice(start, start + size); + const settled = await Promise.allSettled( + group.map((sandbox) => + sandbox.processes.run({ args }, { timeoutMs: 300_000 }), + ), + ); + settled.forEach((result, index) => { + outcomes.push( + result.status === 'fulfilled' + ? { sandboxName: group[index].name, response: result.value } + : { sandboxName: group[index].name, failure: result.reason }, + ); + }); + } + return outcomes; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-your-first-command.md b/content/manuals/ai/sandboxes-api/cookbook/run-your-first-command.md new file mode 100644 index 000000000000..4ea3a617db0f --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-your-first-command.md @@ -0,0 +1,112 @@ +--- +title: "Run your first command" +linkTitle: "Run your first command" +description: "Connect to a running sandbox, run a command in it, and tell a command that exited unsuccessfully apart from a call that failed." +keywords: "cloud sandboxes, sandboxes api, run your first command" +weight: 105 +params: + sidebar: + group: "Get started" +--- + +Run a command in an existing sandbox and collect its output. Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and the sandbox name returned by [your first launch](create-your-first-sandbox.md). + +For most commands, use the process collection's run helper. It starts the process and waits for its result. + +## Open the sandbox {#1-open-the-sandbox} + +Get the sandbox by its resource name. The returned handle exposes processes and files and manages their authenticated connections. You do not need to copy the sandbox address or Docker token into a second client. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.get(name); +``` + +<details> +<summary>Complete TypeScript example: exec/endpoint.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function processesAt(client: Sandboxes, name: string) { + return client.get(name); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Use the process run helper {#2-use-the-process-run-helper} + +Pass an argument array: the program followed by its arguments, such as `['echo', 'Hello from Docker Sandboxes']`. Arguments are not shell syntax. For pipes, redirection, or variable expansion, run `sh -c` with your script as the next argument. + +The run helper returns the process result after collecting output. A successful SDK call does not mean the command succeeded: inspect its exit code. Standard error is diagnostic output and can be nonempty even when the exit code is zero. + +An SDK error means the request, wait, or connection failed. Keep the process handle carried by an error when available so you can inspect it instead of starting duplicate work. [Error handling](handle-errors-and-degradation.md) explains the distinction. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return sandbox.processes.run({ args }, { timeoutMs: 300_000 }); +``` + +<details> +<summary>Complete TypeScript example: exec/outcome.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function classifyOutcome(sandbox: Sandbox, args: string[]) { + return sandbox.processes.run({ args }, { timeoutMs: 300_000 }); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Optional: execute a command directly {#3-optional-execute-a-command-directly} + +For a short command whose output you only need after it exits, direct execution is simpler: one request waits for the command and returns its captured output and exit code, without a separate process-creation and output-reading sequence. + +Check the incomplete flag before treating captured output as complete. Choose [streaming output](run-something-that-produces-real-output.md) when you need output while the command runs. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const result = await endpoint.api.exec({ body: { cmd: args } }); +``` + +<details> +<summary>Complete TypeScript example: exec/exec.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function runCommand(sandbox: Sandbox, args: string[]) { + const endpoint = await sandbox.endpointClient(['sandboxesExec'], 'exec'); + try { + const result = await endpoint.api.exec({ body: { cmd: args } }); + return { + exitCode: result.exitCode ?? 0, + stdout: new TextDecoder().decode(result.stdout), + stderr: new TextDecoder().decode(result.stderr), + incomplete: result.incomplete ?? false, + }; + } finally { + await endpoint.close(); + } +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/run-your-own-container-image.md b/content/manuals/ai/sandboxes-api/cookbook/run-your-own-container-image.md new file mode 100644 index 000000000000..fa3042c63a82 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/run-your-own-container-image.md @@ -0,0 +1,61 @@ +--- +title: "Run your own container image" +linkTitle: "Run your own container image" +description: "Start a sandbox from a container image in a registry you name, instead of from a managed image." +keywords: "cloud sandboxes, sandboxes api, run your own container image" +weight: 501 +params: + sidebar: + group: "Connect and configure" +--- + +Run your own tools from a container image when a [bundled kit](add-tools-with-kits.md) does not fit the task. You supply the image reference and machine size; the SDK creates an isolated sandbox around it. + +You need an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and an OCI image the service can pull. Use a versioned reference or digest when repeatability matters. The image must include `/bin/sh`. + +## Create from a registry image {#1-create-from-a-registry-image} + +Pass the image reference, CPU count, memory size, display name, and idempotency key. The SDK's image-reference option avoids assembling nested request fields. Do not also supply a managed image or named agent. + +The example waits for the sandbox to run. A wait timeout stops your wait; it does not delete a sandbox that was already accepted. Save any sandbox handle retained by the error so you can inspect or clean it up. + +The image's startup command runs inside the sandbox. Read `WORKSPACE_DIR` to find the workspace rather than assuming a path. + +Next, [run a command](run-your-first-command.md) or [copy in your project files](copy-a-file-into-a-cloud-sandbox.md). [Delete the sandbox](delete-a-cloud-sandbox.md) when the work is complete. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await client.create( + { displayName: name, imageRef, resources }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: rawimage/create.ts</summary> + +```typescript +import type { ClientCreateOptions, Sandboxes } from '@docker/sandboxes'; + +export async function createFromImageRef( + client: Sandboxes, + name: string, + imageRef: string, + resources: ClientCreateOptions['resources'], + requestId: string, +) { + const sandbox = await client.create( + { displayName: name, imageRef, resources }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/send-values-the-api-accepts.md b/content/manuals/ai/sandboxes-api/cookbook/send-values-the-api-accepts.md new file mode 100644 index 000000000000..273e6f2ae70b --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/send-values-the-api-accepts.md @@ -0,0 +1,110 @@ +--- +title: "Send values the API accepts" +linkTitle: "Send values the API accepts" +description: "Build a create request whose durations, counts, and flags mean what you intend, then read back the values the service settled on." +keywords: "cloud sandboxes, sandboxes api, send values the api accepts" +weight: 605 +params: + sidebar: + group: "Requests and responses" +--- + +Build SDK options without confusing an omitted value with an explicit false or zero. This matters for settings whose default is chosen by the service. + +Start with an [authenticated client](connect-to-cloud-with-a-bearer-token.md). Use the option types exported by your SDK so your editor can show the supported inputs. + +## Construct creation options {#1-construct-creation-options} + +Supply the image source and lifecycle settings, using the duration units required by your SDK. The example accepts seconds and converts them at the boundary. + +This example uses a managed image, which supplies its resource defaults. For a registry image instead, use the image-reference option and provide a supported CPU and memory pair. + +Preserve absence for an optional boolean when you want the service default. Explicit false is a choice, not a missing value. Validate user-supplied values before building the request. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return { + displayName: name, + image, + platform, + lifecycle: { timeoutMs: lifeSeconds * 1_000, autoResume }, +}; +``` + +<details> +<summary>Complete TypeScript example: values/build.ts</summary> + +```typescript +import type { ClientCreateOptions, Sandboxes } from '@docker/sandboxes'; + +export function createRequest( + name: string, + image: string, + lifeSeconds: number, + platform: ClientCreateOptions['platform'], + autoResume: boolean | undefined, +): ClientCreateOptions { + return { + displayName: name, + image, + platform, + lifecycle: { timeoutMs: lifeSeconds * 1_000, autoResume }, + }; +} + +export async function sendCreate( + client: Sandboxes, + request: ClientCreateOptions, +) { + const sandbox = await client.create(request, { timeoutMs: 300_000 }); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Read the effective values {#2-read-the-effective-values} + +Get the sandbox and inspect the reported platform, resources, and expiration. These describe what the service recorded, which can differ from omitted or defaulted input values. + +Keep the language's native numeric and duration representations. Avoid converting large integers through a floating-point type merely to display or serialize them. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return { + expiresAt: sandbox.effectiveFeatures?.timeouts?.expiresAt, + platform: sandbox.core.platform, + cpus: sandbox.core.resources?.cpus ?? undefined, +}; +``` + +<details> +<summary>Complete TypeScript example: values/read.ts</summary> + +```typescript +import type { Sandbox, Sandboxes } from '@docker/sandboxes'; + +export function reportedValues(sandbox: Sandbox) { + return { + expiresAt: sandbox.effectiveFeatures?.timeouts?.expiresAt, + platform: sandbox.core.platform, + cpus: sandbox.core.resources?.cpus ?? undefined, + }; +} + +export async function readSandbox(client: Sandboxes, name: string) { + return reportedValues(await client.get(name)); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/snapshot-and-fork-a-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/snapshot-and-fork-a-sandbox.md new file mode 100644 index 000000000000..94cc5b4940ba --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/snapshot-and-fork-a-sandbox.md @@ -0,0 +1,172 @@ +--- +title: "Snapshot and fork a sandbox" +linkTitle: "Snapshot and fork a sandbox" +description: "Capture the state of a running sandbox as a snapshot, then start a new sandbox from that snapshot." +keywords: "cloud sandboxes, sandboxes api, snapshot and fork a sandbox" +weight: 302 +params: + sidebar: + group: "Packaging and state" +--- + +Save a sandbox's state so you can start another sandbox from the same point later. A snapshot is separate from its source sandbox; restoring it creates a new sandbox with its own identity. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md) and the resource name of a running sandbox. + +## Capture a snapshot {#1-capture-a-snapshot} + +Choose a display name, capture mode, and idempotency key. Use disk-only capture when you need the filesystem. Request memory only when your environment supports it and you need the running state. + +The example waits until capture finishes and returns a snapshot handle. Keep the returned name for restoration. + +A failed capture carries failure details; a timed-out wait does not prove the capture was cancelled. + +Snapshots can contain credentials and private project data. Restrict access to them, especially when capturing memory. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const snapshot = await sandbox.snapshot( + { + displayName: snapshotName, + captureMode: withMemory ? 'all' : 'disk', + }, + { idempotencyKey: requestId }, +); +return snapshot.waitUntilReady(); +``` + +<details> +<summary>Complete TypeScript example: snapshots/create.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function createSnapshot( + client: Sandboxes, + sandboxName: string, + snapshotName: string, + withMemory: boolean, + requestId: string, +) { + const sandbox = await client.get(sandboxName); + const snapshot = await sandbox.snapshot( + { + displayName: snapshotName, + captureMode: withMemory ? 'all' : 'disk', + }, + { idempotencyKey: requestId }, + ); + return snapshot.waitUntilReady(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Restore into another sandbox {#2-restore-into-another-sandbox} + +Use a ready snapshot's name and a display name for the new sandbox. The example waits for the restored sandbox to run. + +The call returns a sandbox handle, ready for running commands or transferring files. + +The source sandbox does not need to remain running. Restoration does not replace it. Save the new sandbox's name and delete it separately when you finish. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const sandbox = await snapshot.restore( + { displayName: newSandboxName }, + { timeoutMs: 300_000, idempotencyKey: requestId }, +); +return sandbox.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: snapshots/restore.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function restoreSnapshot( + client: Sandboxes, + snapshotName: string, + newSandboxName: string, + requestId: string, +) { + const snapshot = await client.snapshots.get(snapshotName); + const sandbox = await snapshot.restore( + { displayName: newSandboxName }, + { timeoutMs: 300_000, idempotencyKey: requestId }, + ); + return sandbox.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Find saved snapshots {#3-find-saved-snapshots} + +List snapshots for the source sandbox. The example follows all pages and returns summaries. Read a selected snapshot before restoring it if you need its current status or complete metadata. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +return client.snapshots.all({ sandbox: sandboxName }).collect(); +``` + +<details> +<summary>Complete TypeScript example: snapshots/list.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function listSnapshots( + client: Sandboxes, + sandboxName: string, +) { + return client.snapshots.all({ sandbox: sandboxName }).collect(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Delete a snapshot {#4-delete-a-snapshot} + +Delete through a handle when you no longer need that restore point. Deletion removes the snapshot, not sandboxes that have already been restored from it. Snapshot deletion is refused while a sandbox restored from it is still running. + +Deleting the source sandbox and deleting its snapshots are separate cleanup steps. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +await snapshot.delete(); +``` + +<details> +<summary>Complete TypeScript example: snapshots/delete.ts</summary> + +```typescript +import type { Snapshot } from '@docker/sandboxes'; + +export async function deleteSnapshot(snapshot: Snapshot) { + await snapshot.delete(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/stop-and-restart-a-sandbox.md b/content/manuals/ai/sandboxes-api/cookbook/stop-and-restart-a-sandbox.md new file mode 100644 index 000000000000..e169871954a1 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/stop-and-restart-a-sandbox.md @@ -0,0 +1,80 @@ +--- +title: "Stop and restart a sandbox" +linkTitle: "Stop and restart a sandbox" +description: "Stop a running sandbox without deleting it, wait for the stop to settle, and start the same sandbox again when you need it." +keywords: "cloud sandboxes, sandboxes api, stop and restart a sandbox" +weight: 207 +params: + sidebar: + group: "Working in a sandbox" +--- + +Stop a sandbox when you want to keep its disk but pause its execution. Start the same sandbox later to continue working with those files. + +Use a sandbox handle obtained by creation or by reading its resource name. Stopping is different from [deleting](delete-a-cloud-sandbox.md), which removes the sandbox. + +## Stop the sandbox {#1-stop-the-sandbox} + +Call stop and wait for the stopped state. The example returns a handle with the updated resource version. + +Wait completion confirms the state change. A timeout means your client stopped waiting; read the sandbox to learn whether the operation completed. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const changed = await sandbox.stop({ idempotencyKey: requestId }); +return changed.waitUntilStopped(); +``` + +<details> +<summary>Complete TypeScript example: lifecycle/stop.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function stopSandbox(sandbox: Sandbox, requestId: string) { + const changed = await sandbox.stop({ idempotencyKey: requestId }); + return changed.waitUntilStopped(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Start it again {#2-start-it-again} + +Do not reuse a handle whose version predates the stop. + +Start the stopped sandbox and wait for it to run. As with stopping, the call returns a handle. + +Do not assume that a process connection from before the stop remains usable. [Find an existing process](find-a-process-you-lost-track-of.md) or start the work again as appropriate for the application. + +A stopped sandbox still exists. Delete it when you no longer need its disk, and clean up separate snapshots or volumes only when their data is no longer needed. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const changed = await sandbox.start({ idempotencyKey: requestId }); +return changed.waitUntilRunning(); +``` + +<details> +<summary>Complete TypeScript example: lifecycle/start.ts</summary> + +```typescript +import type { Sandbox } from '@docker/sandboxes'; + +export async function startSandbox(sandbox: Sandbox, requestId: string) { + const changed = await sandbox.start({ idempotencyKey: requestId }); + return changed.waitUntilRunning(); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/what-your-workload-starts-with.md b/content/manuals/ai/sandboxes-api/cookbook/what-your-workload-starts-with.md new file mode 100644 index 000000000000..f6b41ac79d5e --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/what-your-workload-starts-with.md @@ -0,0 +1,136 @@ +--- +title: "What your workload starts with" +linkTitle: "What your workload starts with" +description: "Read the environment variables every command in a sandbox starts with, and see which source wins when two of them set the same name." +keywords: "cloud sandboxes, sandboxes api, what your workload starts with" +weight: 209 +params: + sidebar: + group: "Working in a sandbox" +--- + +Inspect the environment a process receives and override a value for one command. This helps diagnose a missing workspace path or configuration setting. + +Use a running sandbox handle. The environment can contain credentials, so do not dump the full result into logs or send it to an untrusted client. + +## Read the process environment {#1-read-the-process-environment} + +Run `env` and parse its output. Read `WORKSPACE_DIR` to locate the workspace rather than assuming a fixed path. + +This reports the environment seen by that process. It is a diagnostic example, not a way to retrieve stored secret values. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +export async function readFloor(sandbox: Sandbox) { + const result = requireSuccess( + await sandbox.processes.run({ args: ['env'] }, { timeoutMs: 300_000 }), + ); + return Object.fromEntries( + result.stdout + .split('\n') + .filter((line) => line.includes('=')) + .map((line) => { + const delimiter = line.indexOf('='); + return [line.slice(0, delimiter), line.slice(delimiter + 1)]; + }), + ); +} +``` + +<details> +<summary>Complete TypeScript example: runtime/read.ts</summary> + +```typescript +import { requireSuccess, type Sandbox } from '@docker/sandboxes'; + +export async function readFloor(sandbox: Sandbox) { + const result = requireSuccess( + await sandbox.processes.run({ args: ['env'] }, { timeoutMs: 300_000 }), + ); + return Object.fromEntries( + result.stdout + .split('\n') + .filter((line) => line.includes('=')) + .map((line) => { + const delimiter = line.indexOf('='); + return [line.slice(0, delimiter), line.slice(delimiter + 1)]; + }), + ); +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Override a variable for one command {#2-override-a-variable-for-one-command} + +Supply a value in the process request's environment map. The first command reads that override. A second command without the override reads the sandbox's original value. + +The override belongs to the process request and does not change the sandbox's environment for later commands. Use it for task-specific configuration. For provider credentials, prefer [stored secrets](get-a-stored-secret-into-a-sandbox.md). + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +const fromRequest = requireSuccess( + await sandbox.processes.run( + { + args: ['printenv', name], + env: { [name]: value }, + }, + { timeoutMs: 300_000 }, + ), +); +const fromSandbox = await sandbox.processes.run( + { + args: ['printenv', name], + }, + { timeoutMs: 300_000 }, +); +return { + fromRequest: fromRequest.stdout.trimEnd(), + fromSandbox: fromSandbox.stdout.trimEnd(), +}; +``` + +<details> +<summary>Complete TypeScript example: runtime/precedence.ts</summary> + +```typescript +import { requireSuccess, type Sandbox } from '@docker/sandboxes'; + +export async function overrideVariable( + sandbox: Sandbox, + name: string, + value: string, +) { + const fromRequest = requireSuccess( + await sandbox.processes.run( + { + args: ['printenv', name], + env: { [name]: value }, + }, + { timeoutMs: 300_000 }, + ), + ); + const fromSandbox = await sandbox.processes.run( + { + args: ['printenv', name], + }, + { timeoutMs: 300_000 }, + ); + return { + fromRequest: fromRequest.stdout.trimEnd(), + fromSandbox: fromSandbox.stdout.trimEnd(), + }; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/cookbook/work-within-the-limits.md b/content/manuals/ai/sandboxes-api/cookbook/work-within-the-limits.md new file mode 100644 index 000000000000..0e854ca2b2b4 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/cookbook/work-within-the-limits.md @@ -0,0 +1,178 @@ +--- +title: "Work within the limits" +linkTitle: "Work within the limits" +description: "Choose a supported compute size, understand account quotas, and handle refusals without endless retries." +keywords: "cloud sandboxes, sandboxes api, work within the limits" +weight: 606 +params: + sidebar: + group: "Requests and responses" +--- + +Bound work so account limits and temporary capacity refusals do not turn into unbounded retries. + +Use an [authenticated client](connect-to-cloud-with-a-bearer-token.md). Account limits are separate from SDK configuration; changing the client does not grant additional capacity. + +### Choose a compute size + +Cloud Sandboxes uses fixed CPU and memory pairs as billing shapes: + +| Size | vCPUs | Memory | SDK memory value (MiB) | +| ------ | ----: | -----: | ---------------------: | +| Micro | 1 | 2 GiB | 2048 | +| Small | 2 | 4 GiB | 4096 | +| Medium | 4 | 8 GiB | 8192 | +| Large | 8 | 16 GiB | 16384 | +| XL | 16 | 32 GiB | 32768 | + +Choose a size by name, for example, `resources: 'small'`. The supported names are `micro`, `small`, `medium`, `large`, and `xl`. Kit launches default to Small when you omit resources. Explicit settings take precedence. + +You can still supply both CPU and memory directly. Use a supported pair; 1 CPU with 1024 MiB is not supported in Cloud Sandboxes. A saved image supplies its own resources, so do not override them when creating from that image. Your account and available capacity determine whether a request can be accepted. Check your Docker billing terms for prices. + +### Understand account quotas + +The default limits are 10 concurrent sandboxes, 50 stored sandboxes, 100 volumes, 100 secrets, and 3 images being prepared at once. These are account-wide defaults, not a separate allowance per user. Your account can have different limits; confirm them with Docker before sizing a large workload. + +Stopping an ordinary sandbox frees its concurrency slot but leaves it in stored usage. Starting or resuming it needs a slot again. An always-on sandbox, configured to restart automatically on timeout, retains its concurrency reservation even while stopped. Delete sandboxes you no longer need to release stored usage. + +## Count existing sandboxes {#1-count-existing-sandboxes} + +Walk all sandbox pages and count resources visible to you. This gives your application a usage observation, not a reservation or authoritative quota balance. Other users can hold resources in the same account that your list does not show. + +Another caller can create a sandbox immediately afterward. Treat the create response as the final decision, even when your count appears below a planned limit. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +let count = 0; +for await (const sandbox of client.all({ pageSize })) { + if (sandbox.name) count++; +} +return count; +``` + +<details> +<summary>Complete TypeScript example: limits/budget.ts</summary> + +```typescript +import type { Sandboxes } from '@docker/sandboxes'; + +export async function countSandboxes(client: Sandboxes, pageSize: number) { + let count = 0; + for await (const sandbox of client.all({ pageSize })) { + if (sandbox.name) count++; + } + return count; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} + +## Back off after a refusal {#2-back-off-after-a-refusal} + +Use the server's retry delay when supplied and keep the same idempotency key for the same create request. Bound the number of attempts and give the overall operation a deadline. + +The example owns the retry loop, disables automatic SDK retries, and sets an overall timeout. Do not layer two retry policies without accounting for their combined attempts and deadlines. + +A quota refusal may need cleanup or an account change rather than another immediate request. Stop after the bound, report the failure, and keep any accepted sandbox identity available for inspection. + +{{< tabs >}} +{{< tab name="TypeScript" >}} + +```typescript +for (let attempt = 0; attempt < attempts; attempt++) { + try { + return await client.kits.launch( + 'shell', + { displayName, resources: { cpus: 2, memoryMib: 4096 } }, + { + idempotencyKey: requestId, + timeoutMs: 300_000, + signal, + maxRetries: 0, + }, + ); + } catch (error) { + if ( + !(error instanceof RequestError) || + error.raw.code !== 'resourceExhausted' || + attempt + 1 === attempts + ) + throw error; + await pause(retryAfter(error, fallbackMs), undefined, { signal }); + } +} +throw new Error('attempt count was validated'); +``` + +<details> +<summary>Complete TypeScript example: limits/backoff.ts</summary> + +```typescript +import { setTimeout as pause } from 'node:timers/promises'; +import { + RequestError, + type Sandbox, + type Sandboxes, +} from '@docker/sandboxes'; + +export async function createWithBackoff( + client: Sandboxes, + displayName: string, + attempts: number, + fallbackMs: number, + requestId: string, +): Promise<Sandbox> { + if (!Number.isInteger(attempts) || attempts < 1) + throw new Error(`attempts must be at least 1, got ${attempts}`); + const signal = AbortSignal.timeout(300000); + for (let attempt = 0; attempt < attempts; attempt++) { + try { + return await client.kits.launch( + 'shell', + { displayName, resources: { cpus: 2, memoryMib: 4096 } }, + { + idempotencyKey: requestId, + timeoutMs: 300_000, + signal, + maxRetries: 0, + }, + ); + } catch (error) { + if ( + !(error instanceof RequestError) || + error.raw.code !== 'resourceExhausted' || + attempt + 1 === attempts + ) + throw error; + await pause(retryAfter(error, fallbackMs), undefined, { signal }); + } + } + throw new Error('attempt count was validated'); +} + +export function retryAfter( + error: RequestError, + fallbackMs: number, +): number { + const header = error.retryAfter?.trim(); + if (header) { + const delay = /^\d+(?:\.\d+)?$/.test(header) + ? Number(header) * 1000 + : /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)[a-z]*,?\s/.test(header) + ? Math.max(0, Date.parse(header) - Date.now()) + : NaN; + if (Number.isFinite(delay) && delay >= 0) return delay; + } + return error.decoded.retryDelayMs ?? fallbackMs; +} +``` + +</details> + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/ai/sandboxes-api/errors.md b/content/manuals/ai/sandboxes-api/errors.md new file mode 100644 index 000000000000..061126031cf0 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/errors.md @@ -0,0 +1,138 @@ +--- +title: Errors and retries +description: Handle Docker Sandboxes API errors, recover from failed waits, and retry requests without duplicating work. +keywords: docker sandboxes API errors, REST errors, API retries, idempotency keys, rate limits +weight: 40 +aliases: + - /ai/sandboxes/api/errors/ +--- + +Before retrying a failed request, check whether the service already started +the work. For example, a create request can succeed even if your application +loses the response. Retrying without checking can create a second sandbox. + +## Read an error response + +API errors contain a `code`, a `message`, and optional typed `details`. Use the +code to decide how to respond. Several codes share an HTTP status, so the +status alone might not explain the failure. + +| Code | What to do | +| --- | --- | +| `invalidArgument` | Correct the malformed request or unsupported value before retrying. | +| `unauthenticated` | Obtain a valid credential to replace the missing, invalid, or expired one. | +| `permissionDenied` | Check that your credentials have permission for the action. | +| `notFound` | Check the resource name and request URL. Cloud also returns this code for routes it doesn't serve. | +| `failedPrecondition` | Check the resource state, required features, and any `If-Match` header. | +| `resourceExhausted` | Check the error details for a quota, rate limit, or request-size limit. | +| `unimplemented` | Check whether the backend supports the requested feature. | +| `unavailable` | Retry after a delay, once you know the retry won't duplicate work. | + +For more detail, inspect `google.rpc.ErrorInfo` in the error's `details`, if +present. Use its `reason` and `domain` fields together with the error code to +handle specific causes. Avoid matching the free-form message text, and +handle responses even when they include detail types you don't recognize. + +## Recover from a failed wait + +If the API returns HTTP 202, the work is still in progress. Keep reading the +resource until it reaches the state you need or fails. The resource's `failure` +field describes a failure that occurs after the initial request succeeds. + +If a wait times out or is canceled, the action can still finish. Inspect the +resource before trying again or deleting it. SDK wait helpers report +`WaitError`, which includes the last resource the client received and any +failure details. + +If the client never received a resource, retry the original request with its +idempotency key to recover the response. See +[Retry without duplicating work](#retry-without-duplicating-work). + +## Retry without duplicating work + +An idempotency key identifies one request, so the service can return its +original response if you send it again. For example, repeating a sandbox +creation request with the same key returns the first sandbox instead of +creating another one. + +The SDK generates a key for each supported mutation unless you supply one. +For direct API calls, include an `Idempotency-Key` header in the original +request. Keep the key and the exact request, including any `If-Match` value, +for retries. + +The service keeps accepted results for at least 24 hours. A replay returns +the original response, so read the resource afterward to check its latest +state. + +Use the same key only when repeating the same request. Changing the request +under that key causes an error, and using a different key submits another +action. Send the header only for operations that support it: + +| Operations | `Idempotency-Key` | +| --- | --- | +| Create a sandbox, image, process, port, snapshot, secret, or volume | Optional | +| Restore a snapshot | Optional | +| Start, stop, or delete a sandbox | Optional | +| Update a secret | Optional | +| Update a sandbox | Required | + +Other operations don't accept an idempotency key. + +Once you know a create request succeeded, poll the returned resource to wait +for completion. Retry only when you need to recover from a failure or a lost +response. For temporary failures, wait between retries and limit the number +of attempts. + +Process creation also supports an idempotency key. Recover the creation +response with the same key before starting another process. Process input, +signals, and file writes aren't covered by that key. Check the outcome +before repeating those actions. + +## Account for SDK retries + +The SDK makes up to two additional attempts for eligible transient failures. +If your application manages its own retry loop, set `maxRetries: 0` for the +call to disable automatic retries. Combining both policies can produce more +attempts than you intended. + +Automatic retries within a call reuse its idempotency key. When retrying from +your application, pass the original key in the call options as +`idempotencyKey`. Otherwise, a separate create call can generate a different +key and create another sandbox. + +Limit both retry attempts and elapsed time, and honor server retry delays. +See [Request rate limits](limits.md#request-rate-limits) for how rate limits +differ from resource quotas. + +## Handle concurrent changes + +To avoid changing a resource that someone else has modified, send its `etag` +in the `If-Match` header. An etag identifies the version of the resource you +read. Operations such as sandbox updates and deletion require this header. +The SDK sends the etag stored in the resource object you're using. + +For direct API requests, pass the etag exactly as returned, including its +quotes. A missing required header returns HTTP 428, and a stale etag returns +HTTP 412. + +If the etag is stale, read the resource again and decide whether your change +is still appropriate. In the SDK, use the object returned by `refresh()` for +the next operation. The original object still has the old etag. Use a +different idempotency key for a request with an updated etag. + +## Check command results + +An API request can succeed even when the command it runs fails. Check the +command result's exit code and output separately from request and wait errors. +A nonzero exit code reports a command failure. + +## Set a timeout for commands + +To limit how long `processes.run()` waits for a command, pass `timeoutMs` in +the second argument. For example, +`sandbox.processes.run(input, { timeoutMs: 300_000 })` waits up to five minutes. +Timing out or canceling the call stops local waiting. It doesn't kill the +process in the sandbox. + +Without `timeoutMs`, the overall run has no timeout. Individual requests to +create the process and read its output have a 30-second timeout. diff --git a/content/manuals/ai/sandboxes-api/get-started.md b/content/manuals/ai/sandboxes-api/get-started.md new file mode 100644 index 000000000000..c9cb8bdbe115 --- /dev/null +++ b/content/manuals/ai/sandboxes-api/get-started.md @@ -0,0 +1,121 @@ +--- +title: Run your first cloud sandbox +linkTitle: Get started +description: Use the TypeScript SDK to create a cloud sandbox, run a command, and delete the sandbox. +keywords: Docker Sandboxes API tutorial, cloud sandbox TypeScript, create sandbox, sandbox SDK quickstart +weight: 10 +aliases: + - /ai/sandboxes/api/get-started/ +--- + +Create a cloud sandbox, run a command inside it, and delete it using the Docker +Sandboxes TypeScript SDK. This tutorial uses the bundled `shell` kit to print +`Hello from Docker Sandboxes`. You don't need an AI agent or a model provider +API key to run it. + +## Prerequisites + +To follow this tutorial, you need: + +- A Docker account with an active + [Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access) +- Node.js 20 or later and npm + +## Create a project + +Create a directory and initialize a Node.js project: + +```console +$ mkdir sandboxes-api-tutorial +$ cd sandboxes-api-tutorial +$ npm init --yes +$ npm pkg set type=module +``` + +Install the SDK and TypeScript tooling: + +```console +$ npm install @docker/sandboxes +$ npm install --save-dev tsx typescript @types/node +``` + +## Create and use a sandbox + +A kit supplies the sandbox's image and configuration for an agent or tool. +The `shell` kit provides the environment for this example. + +The SDK launches it with the default `small` compute size: two CPUs and +4 GiB of memory. Cloud compute is billed to your subscription. See +[Compute sizes and limits](limits.md) for other sizes. + +Create a file named `index.ts` with the following code. The program prompts +you to sign in, creates a sandbox, runs a command, and deletes the sandbox. + +```typescript +import { oauth, Sandboxes } from '@docker/sandboxes'; + +const client = new Sandboxes({ + auth: oauth({ + onVerification({ verificationUriComplete, verificationUri, userCode }) { + console.log(`Open ${verificationUriComplete ?? verificationUri}`); + console.log(`Verification code: ${userCode}`); + }, + }), +}); + +try { + const sandbox = await client.kits.launchAndWait('shell'); + console.log('Sandbox:', sandbox.name); + + const result = await sandbox.processes.run( + { args: ['echo', 'Hello from Docker Sandboxes'] }, + { timeoutMs: 300_000 }, + ); + console.log(result.stdout.trim()); + + const latest = await sandbox.refresh(); + const deleting = await latest.delete({ force: true }); + await deleting?.waitUntilDeleted(); + console.log('Deleted', sandbox.name); +} finally { + await client.close(); +} +``` + +`kits.launchAndWait` creates the sandbox and waits until it's running. +`processes.run` runs the command and collects its output. +The program then reads the sandbox's latest state, deletes it, and waits for +deletion to finish. The `force` option permits deletion while the sandbox is +running. + +The SDK handles sign-in, access tokens, and the connection to the sandbox. +Closing the client releases its local resources. + +## Run the program + +Run the program with `tsx`: + +```console +$ npx tsx index.ts +``` + +Open the printed verification URL and sign in with the Docker account that +has your cloud subscription. The program continues after sign-in. On success, +it prints `Hello from Docker Sandboxes`, then confirms sandbox deletion. + +For CI jobs and other unattended applications, use +[PAT authentication](authentication.md#authenticate-automation-with-a-pat). + +If the program stops after printing the sandbox name, retrieve the sandbox +with `client.get(name)` and delete it when you're finished. Closing the client +doesn't delete the sandbox. + +## Next steps + +- Explore the [SDK cookbook](cookbook/_index.md) for examples you can use in + your application. +- If you use a kit that clones a repository or installs tools, + [wait for kit setup](concepts.md#wait-for-kit-setup) before using its results. +- Read [API concepts](concepts.md) to learn about resource names, lifecycle + states, and supported Cloud options. +- Review [Errors and retries](errors.md) before adding recovery logic. diff --git a/content/manuals/ai/sandboxes-api/install.md b/content/manuals/ai/sandboxes-api/install.md new file mode 100644 index 000000000000..1db72543dbba --- /dev/null +++ b/content/manuals/ai/sandboxes-api/install.md @@ -0,0 +1,39 @@ +--- +title: Install the Docker Sandboxes SDK +linkTitle: Install the SDK +description: Install and use the Docker Sandboxes SDK in your JavaScript or TypeScript application. +keywords: docker sandboxes SDK, TypeScript SDK, JavaScript, npm, install sandbox SDK +weight: 5 +aliases: + - /ai/sandboxes-api/sdks/ + - /ai/sandboxes/api/sdks/ +--- + +Use the Docker Sandboxes SDK to create and manage cloud sandboxes from +JavaScript or TypeScript. The SDK includes methods for running commands, +transferring files, and waiting for a sandbox to start or stop. + +You don't need the Docker CLI to use the SDK. + +## Install the SDK + +With Node.js 20 or later, install the SDK in your project: + +```console +$ npm install @docker/sandboxes +``` + +Import `Sandboxes` from `@docker/sandboxes`. + +## Connect to Cloud Sandboxes + +Before connecting, [activate a Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access) +for your Docker account. + +Configure your client with browser sign-in for interactive use or a personal +access token for automation. The SDK supplies the service URL and manages +access tokens. See [Authentication and authorization](authentication.md) for +setup instructions. + +Follow [Run your first cloud sandbox](get-started.md) for a complete TypeScript +example that creates a sandbox, runs a command, and deletes it. diff --git a/content/manuals/ai/sandboxes-api/limits.md b/content/manuals/ai/sandboxes-api/limits.md new file mode 100644 index 000000000000..eed9abfa6faa --- /dev/null +++ b/content/manuals/ai/sandboxes-api/limits.md @@ -0,0 +1,84 @@ +--- +title: Compute sizes and limits +description: Choose a Cloud Sandboxes compute size and plan for account quotas and request rate limits. +keywords: cloud sandboxes, compute sizes, CPU, memory, quotas, rate limits +weight: 50 +aliases: + - /ai/sandboxes/api/limits/ +--- + +Choose a compute size for each sandbox and keep your application's resource +usage within your account's quotas. Request rate limits also constrain how +quickly your application can send API requests. + +## Compute sizes + +Cloud Sandboxes supports these CPU and memory pairs: + +| SDK size name | CPUs | Memory | Memory in MiB | +| --- | ---: | ---: | ---: | +| `micro` | 1 | 2 GiB | 2048 | +| `small` | 2 | 4 GiB | 4096 | +| `medium` | 4 | 8 GiB | 8192 | +| `large` | 8 | 16 GiB | 16384 | +| `xl` | 16 | 32 GiB | 32768 | + +The kit launch helpers default to `small` when you omit `resources`. To select +another size, pass its name: + +```typescript +const sandbox = await client.kits.launchAndWait('shell', { + resources: 'medium', +}); +``` + +For a registry image, specify a size in `client.create()`, such as +`resources: 'small'`. You can also pass an explicit CPU and memory pair: +`resources: { cpus: 2, memoryMib: 4096 }`. + +Named sizes are an SDK convenience. In direct REST requests, supply both +`resources.cpus` and `resources.memoryMib`. CPU and memory aren't independent +settings: for example, 1 CPU with 1024 MiB is not a supported pair. + +When creating from an existing image resource with `image`, omit resource +settings because the image supplies them. + +Your account access and available capacity determine whether a request can +be accepted. See [Billing](/manuals/agentic-platform/signup.md#billing) for +pricing and usage information. + +## Account quotas + +The default quotas apply across an account: + +| Resource | Default limit | +| --- | ---: | +| Concurrent sandboxes | 10 | +| Stored sandboxes | 50 | +| Volumes | 100 | +| Secrets | 100 | +| Images being prepared at the same time | 3 | + +Your account can have different quotas. Confirm your account's limits with +Docker before planning a workload that depends on a particular allowance. + +Stopping a sandbox releases its concurrency slot unless the sandbox is +configured as always-on. Restarting a stopped sandbox requires a concurrency +slot. A stopped sandbox still counts toward the stored sandbox quota. +Delete sandboxes you no longer need to reduce stored usage. + +Handle quota errors even if you checked usage before creating a resource. +Other applications can consume the remaining allowance between requests. +Reduce concurrency or remove unused resources before retrying. + +## Request rate limits + +Rate limits control how quickly you can send requests and can vary by +operation. When a request reaches a rate limit, wait before retrying and +honor any delay specified by the server. Limit concurrent requests and set +bounds on retry attempts and elapsed time. + +Check the error details to distinguish a rate limit from a resource quota. +Waiting can resolve a rate limit, but exceeding a quota requires reducing +resource usage. See [Errors and retries](errors.md) for how to retry without +duplicating work. diff --git a/content/manuals/ai/sandboxes-api/reference.md b/content/manuals/ai/sandboxes-api/reference.md new file mode 100644 index 000000000000..3ded7e620a1c --- /dev/null +++ b/content/manuals/ai/sandboxes-api/reference.md @@ -0,0 +1,13 @@ +--- +title: Docker Sandboxes API reference +linkTitle: API reference +description: HTTP operations, request fields, and responses for the Docker Sandboxes API. +keywords: Docker Sandboxes API, REST API, OpenAPI, API reference +weight: 70 +build: + render: never + list: local +params: + sidebar: + goto: /reference/api/sandboxes/latest/ +--- diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 75e419dc9984..ecb9d4727888 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -8,68 +8,53 @@ params: group: AI and agents --- -Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each -sandbox gets its own Docker daemon, filesystem, and network — the agent can -build containers, install packages, and modify files without touching your host -system. +Docker Sandboxes run AI coding agents in isolated environments on your machine +or on Docker-managed cloud infrastructure. Use the `sbx` CLI to create and +manage either kind of sandbox. + +The `sbx` CLI and local sandbox compute are free to use, including for commercial +work. Cloud compute uses a +[pay-as-you-go subscription](/manuals/agentic-platform/signup.md#billing). +Model-provider charges are separate. Organization admins can -[centrally manage sandbox network and filesystem policies](governance/org.md) -from the Docker Admin Console, so the same rules apply uniformly across every -developer's machine. Available on a separate paid subscription. +[centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md), +for local sandboxes across developer machines. +Available on a separate paid subscription. ## Get started -For complete system requirements, see the -[get started prerequisites](get-started.md#prerequisites). - -Install the `sbx` CLI and sign in: - -{{< tabs >}} -{{< tab name="macOS" >}} - -```console -$ brew install docker/tap/sbx -$ sbx login -``` - -{{< /tab >}} -{{< tab name="Windows" >}} +[Install the `sbx` CLI](install.md) and sign in, then choose where to run your +agent: -```powershell -> winget install -h Docker.sbx -> sbx login -``` +| Environment | Use it for | Start here | +| --- | --- | --- | +| Local sandboxes | Work with files and supported hardware on your machine | [Get started locally](get-started.md) | +| Cloud sandboxes | Run on Docker-managed compute without local virtualization | [Get started in the cloud](cloud/_index.md#get-started) | -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} +The two environments have separate credentials, network policies, and lifecycle +controls. See [Compare local and cloud sandboxes](cloud/local-vs-cloud.md) +before adapting a workflow. -```console -$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh -$ sudo apt-get install docker-sbx -$ sudo usermod -aG kvm $USER -$ newgrp kvm -$ sbx login -``` - -{{< /tab >}} -{{< /tabs >}} - -Then launch an agent in a sandbox: - -```console -$ cd ~/my-project -$ sbx run claude -``` - -See the [get started guide](get-started.md) for a full walkthrough, or jump to -the [usage guide](usage.md) for common patterns. +To create and manage cloud sandboxes from your application, see +[Sandboxes API and SDK](../sandboxes-api/_index.md). ## Learn more +The following guides describe local sandbox workflows. For cloud workflows, +see [Cloud sandboxes](cloud/). + - [Agents](agents/) — supported agents and per-agent configuration -- [Customize](customize/) — reusable templates and declarative kits for - extending or tailoring sandboxes +- [Workflows](workflows/) — patterns for Git, local development, + authentication, agent skills, and automation +- [Configuration](configuration/) — manage credentials, declare project + environments, turn on GPU passthrough, and configure an upstream proxy +- [Integrations](integrations/) — connect editors and apps like VS Code and + Cursor to a sandbox over SSH +- [MCP gateway](mcp-gateway.md) — register MCP servers and connect them to + sandboxed agents +- [Kits](customize/) — package tools and configuration into reusable + sandbox environments - [Architecture](architecture.md) — microVM isolation, workspace mounting, networking - [Security](security/) — isolation model, credential handling, and diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md index ad8fecf38657..8d0cdbb4d3b3 100644 --- a/content/manuals/ai/sandboxes/agents/_index.md +++ b/content/manuals/ai/sandboxes/agents/_index.md @@ -1,22 +1,23 @@ --- title: Supported agents linkTitle: Agents -weight: 30 +weight: 40 description: AI coding agents supported by Docker Sandboxes. -keywords: docker sandboxes, ai agents, claude code, codex, cursor, gemini +keywords: docker sandboxes, ai agents, claude code, codex, cursor, devin, gemini --- -Docker Sandboxes runs the following agents out of the box: +Docker Sandboxes runs the following agents in local sandboxes: - [Claude Code](claude-code/) - [Codex](codex/) - [Copilot](copilot/) - [Cursor](cursor/) +- [Devin](devin/) +- [Docker Agent](docker-agent/) - [Droid](droid/) - [Gemini](gemini/) - [Kiro](kiro/) - [OpenCode](opencode/) -- [Docker Agent](docker-agent/) - [Shell](shell/) — agent-less sandbox for manual setup or testing Want to pre-install tools or customize an agent's environment? diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 1bf4acd09301..931a5d7f8429 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -2,11 +2,15 @@ title: Claude Code weight: 10 description: | - Use Claude Code in Docker Sandboxes with authentication, configuration, and - YOLO mode for AI-assisted development. -keywords: docker sandboxes, claude code, anthropic, ai agent, sbx + Use Claude Code in Docker Sandboxes with authentication, local models, + configuration, and YOLO mode for AI-assisted development. +keywords: docker sandboxes, claude code, anthropic, ai agent, sbx, local models, llmman, ollama --- +The following instructions apply to local sandboxes. For cloud authentication +and usage, see [Authenticate cloud agents](../cloud/credentials.md) and +[Use cloud sandboxes](../cloud/usage.md). + Official documentation: [Claude Code](https://code.claude.com/docs) ## Quick start @@ -17,34 +21,33 @@ Launch Claude Code in a sandbox by pointing it at a project directory: $ sbx run claude ~/my-project ``` -The workspace parameter defaults to the current directory, so `sbx run claude` -from inside your project works too. To start Claude with a specific prompt: +To start Claude with a specific prompt in the current directory: ```console -$ sbx run claude --name my-sandbox -- "Add error handling to the login function" +$ sbx run --name my-sandbox claude -- "Add error handling to the login function" ``` Everything after `--` is passed directly to Claude Code. You can also pipe in a prompt from a file with `-- "$(cat prompt.txt)"`. +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. + ## Authentication -Claude Code requires either an Anthropic API key or a Claude subscription. +For the default Anthropic models, Claude Code requires either an Anthropic +API key or a Claude subscription. For other models, see +[Use a local model](#use-a-local-model). **API key**: Store your key using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g anthropic +$ sbx secret set anthropic ``` -Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your -shell before running the sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - -**Claude subscription**: If no API key is set, Claude Code prompts you to -authenticate interactively using OAuth. The proxy handles the OAuth flow, so -credentials aren't stored inside the sandbox. +**Claude subscription**: If no API key is set, use the `/login` command inside +Claude Code to authenticate via OAuth. ## Configuration @@ -54,6 +57,15 @@ available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds. +### Remote control + +To use Claude Code's `/remote-control` command inside a sandbox, turn on +[`claude.remoteControl`](../configuration/settings.md#clauderemotecontrol): + +```console +$ sbx settings set claude.remoteControl true +``` + ### Default startup command Without extra args, the sandbox runs: @@ -62,25 +74,29 @@ Without extra args, the sandbox runs: claude --dangerously-skip-permissions ``` -Args after `--` replace these defaults rather than being appended. To keep -`--dangerously-skip-permissions`, include it yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`), so `--dangerously-skip-permissions` is +preserved: ```console -$ sbx run claude -- --dangerously-skip-permissions -c +$ sbx run --name <sandbox-name> -- -c # runs claude --dangerously-skip-permissions -c ``` +When the first argument is a bare word, such as the `agents` subcommand, it +replaces the defaults instead. + See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) for available options. ## Agents view Claude Code's [agents view](https://code.claude.com/docs/en/agent-view) -dispatches tasks to subagents that work in parallel, each in its own -Git worktree. Pair it with [clone mode](../usage.md#clone-mode) for an -isolated multi-agent workflow: +starts background sessions that run tasks in parallel. Pair it with +[clone mode](../workflows/git.md#clone-mode) to keep their changes inside the +sandbox: ```console -$ sbx run --clone claude -- agents +$ sbx run --clone claude . -- agents ``` This invocation replaces the @@ -90,31 +106,32 @@ bypass-permissions mode inside the sandbox. To work around this, either use Claude Code's auto mode or pass the flag explicitly: ```console -$ sbx run --clone claude -- --dangerously-skip-permissions agents +$ sbx run --clone claude . -- --dangerously-skip-permissions agents ``` -The subagents' worktrees live inside the sandbox's private clone — none -of them touches your host repository. Each subagent commits to its own -branch, and you review the work from the host by fetching the -`sandbox-<sandbox-name>` remote: +For simultaneous tasks, each background session needs a separate worktree or +clone. Branches alone don't isolate edits in one working directory. How Claude +Code manages working directories depends on the task, configuration, and +project instructions. The `--clone` flag doesn't control this behavior. Ask +Claude Code to create a separate worktree for each task inside the sandbox. + +To review a branch created by a session, fetch the +`sandbox-<sandbox-name>` remote from the host: ```console $ git fetch sandbox-<sandbox-name> $ git diff main..sandbox-<sandbox-name>/<branch> ``` -See [Git workflow](../usage.md#git-workflow) for clone-mode details. +See [Git workflows](../workflows/git.md) for clone-mode details. ## Base image The sandbox uses `docker/sandbox-templates:claude-code`. See -[Templates](../customize/templates.md) to build your own image on top of +[Base images](/manuals/ai/sandboxes/customize/author/base-images.md) to build your own image on top of this base. ## Use a local model -To run Claude Code in a sandbox against a local model on your host through -Docker Model Runner, see -[Run Claude Code in a Docker Sandbox with Docker Model Runner](/guides/claude-code-sandbox-model-runner/). -For the host-only version without a sandbox, see -[Use Claude Code with Docker Model Runner](/guides/claude-code-model-runner/). +For local models, hosted providers, and custom inference endpoints, see +[Use local and hosted models](../configuration/models.md). diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index e2452524f982..da3e8d289a9e 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, codex, openai, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Codex in a sandboxed environment. @@ -20,25 +22,28 @@ Create a sandbox and run Codex for a project directory: $ sbx run codex ~/my-project ``` -The workspace parameter is optional and defaults to the current directory: +`sbx run` defaults the workspace to the current directory: ```console $ cd ~/my-project $ sbx run codex ``` +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. + ## Authentication -If you haven't stored an OpenAI credential, `sbx run codex` prompts you to -authenticate on your host before launching the sandbox. The flow runs on the -host, so credentials are never exposed inside the sandbox. +For the default OpenAI models, `sbx run codex` prompts you to authenticate on +your host if you haven't stored an OpenAI credential. Authentication happens +before launching the sandbox, so credentials are never exposed inside it. To set up authentication ahead of time, choose one of the following methods. **OAuth**: Start the OAuth flow on your host with: ```console -$ sbx secret set -g openai --oauth +$ sbx secret set openai --oauth ``` This opens a browser window for authentication and stores the resulting tokens @@ -46,16 +51,18 @@ in your OS keychain. The OAuth flow runs on the host, not inside the sandbox, so browser-based authentication works without any extra setup. **API key**: Store your OpenAI API key using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g openai +$ sbx secret set openai ``` -Alternatively, export the `OPENAI_API_KEY` environment variable in your shell -before running the sandbox. +See [Credentials](../configuration/credentials.md) for more details. + +## Model selection -See [Credentials](../security/credentials.md) for more details. +To use Codex with a local model or another inference provider, see +[Use local and hosted models](../configuration/models.md). ## Configuration @@ -73,11 +80,12 @@ Without extra args, the sandbox runs: codex --dangerously-bypass-approvals-and-sandbox ``` -Args after `--` replace these defaults rather than being appended. To keep -the flag, include it yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`). A bare word — such as a prompt — replaces the +defaults instead, so lead with the flag to keep bypass mode: ```console -$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build" +$ sbx run --name <sandbox-name> -- --dangerously-bypass-approvals-and-sandbox "fix the build" ``` ## Base image diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md index c8b75049a8a8..085d56dba343 100644 --- a/content/manuals/ai/sandboxes/agents/copilot.md +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -7,6 +7,8 @@ description: | keywords: docker sandboxes, github copilot, ai agent, github token, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of GitHub Copilot in a sandboxed environment. @@ -30,16 +32,12 @@ $ sbx run copilot ## Authentication Copilot requires a GitHub token with Copilot access. Store your token using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ echo "$(gh auth token)" | sbx secret set -g github +$ sbx secret set github --command 'gh auth token' ``` -Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in -your shell before running the sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - ## Configuration Sandboxes don't pick up user-level configuration from your host. Only @@ -59,13 +57,16 @@ Without extra args, the sandbox runs: copilot --yolo ``` -Args after `--` replace these defaults rather than being appended. To keep -`--yolo`, include it yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`), so `--yolo` is preserved: ```console -$ sbx run copilot -- --yolo -p "review this PR" +$ sbx run copilot -- -p "review this PR" # runs copilot --yolo -p "review this PR" ``` +When the first argument is a bare word — a subcommand or prompt — it replaces +the defaults instead. + ## Base image Template: `docker/sandbox-templates:copilot` diff --git a/content/manuals/ai/sandboxes/agents/cursor.md b/content/manuals/ai/sandboxes/agents/cursor.md index 1d94fed53c9d..65b1d650f85e 100644 --- a/content/manuals/ai/sandboxes/agents/cursor.md +++ b/content/manuals/ai/sandboxes/agents/cursor.md @@ -1,12 +1,14 @@ --- title: Cursor -weight: 33 +weight: 40 description: | Use Cursor in Docker Sandboxes with API key or proxy-managed OAuth authentication. keywords: docker sandboxes, cursor, cursor agent, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Cursor in a sandboxed environment. @@ -20,28 +22,27 @@ Create a sandbox and run Cursor for a project directory: $ sbx run cursor ~/my-project ``` -The workspace parameter is optional and defaults to the current directory: +`sbx run` defaults the workspace to the current directory: ```console $ cd ~/my-project $ sbx run cursor ``` +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. + ## Authentication Cursor supports two authentication methods: an API key or OAuth. **API key**: Store your Cursor API key using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g cursor +$ sbx secret set cursor ``` -Alternatively, export the `CURSOR_API_KEY` environment variable in your shell -before running the sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - **OAuth**: If no API key is set, Cursor prompts you to sign in interactively on first run. The proxy intercepts the token exchange with `api2.cursor.sh/auth/poll`, so credentials are managed by the host and aren't @@ -65,13 +66,16 @@ Without extra args, the sandbox runs: cursor-agent --yolo ``` -Args after `--` replace these defaults rather than being appended. To keep -`--yolo`, include it yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`), so `--yolo` is preserved: ```console -$ sbx run cursor -- --yolo -p "refactor this" +$ sbx run --name <sandbox-name> -- -p "refactor this" # runs cursor-agent --yolo -p "refactor this" ``` +When the first argument is a bare word — a subcommand or prompt — it replaces +the defaults instead. + ## Base image Template: `docker/sandbox-templates:cursor-agent-docker` diff --git a/content/manuals/ai/sandboxes/agents/devin.md b/content/manuals/ai/sandboxes/agents/devin.md new file mode 100644 index 000000000000..349c73c0ebc2 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/devin.md @@ -0,0 +1,57 @@ +--- +title: Devin +weight: 45 +description: Use Devin CLI in Docker Sandboxes with reusable, proxy-managed authentication. +keywords: docker sandboxes, devin, cognition, ai agent, sbx +--- + +{{% include "sandboxes-local-scope.md" %}} + +Official documentation: [Devin CLI](https://docs.devin.ai/work-with-devin/devin-cli) + +## Quick start + +Create a sandbox and run Devin for a project directory: + +```console +$ sbx run devin ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ sbx run devin +``` + +## Authentication + +On first run, Devin prompts you to sign in interactively inside the sandbox. +After you sign in, Docker Sandboxes manages the reusable credential on the host +and supplies it to future Devin sandboxes through the proxy. + +## Configuration + +Sandboxes don't pick up user-level Devin configuration from your host. Only +project-level configuration in the working directory is available inside the +sandbox. See +[Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) +for workarounds. + +Devin reads `AGENTS.md` from the workspace for agent-specific instructions and +uses the [shared agent skills](../workflows/agent-skills.md) store. + +### Default startup command + +Without extra args, the sandbox runs: + +```text +devin --permission-mode dangerous --respect-workspace-trust=false +``` + +## Base image + +Template: `docker/sandbox-templates:devin-docker` + +See [Customize](../customize/) to pre-install tools or customize this +environment. diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md index 713cb2a265a3..50e4540d9ad0 100644 --- a/content/manuals/ai/sandboxes/agents/docker-agent.md +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -1,13 +1,15 @@ --- title: Docker Agent -weight: 70 +weight: 50 description: | Use Docker Agent in Docker Sandboxes with multi-provider authentication supporting OpenAI, Anthropic, and more. keywords: docker sandboxes, docker agent, openai, anthropic, sbx --- -Official documentation: [Docker Agent](https://docs.docker.com/ai/docker-agent/) +{{% include "sandboxes-local-scope.md" %}} + +Official documentation: [Docker Agent](/manuals/ai/docker-agent/_index.md) ## Quick start @@ -17,33 +19,30 @@ Create a sandbox and run Docker Agent for a project directory: $ sbx run docker-agent ~/my-project ``` -The workspace parameter defaults to the current directory, so -`sbx run docker-agent` from inside your project works too. +`sbx run docker-agent` defaults the workspace to the current directory, so you +can run it from inside your project. + +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. ## Authentication Docker Agent supports multiple providers. Store keys for the providers you want -to use with [stored secrets](../security/credentials.md#stored-secrets): +to use with [stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g openai -$ sbx secret set -g anthropic -$ sbx secret set -g google -$ sbx secret set -g xai -$ sbx secret set -g nebius -$ sbx secret set -g mistral -$ sbx secret set -g openrouter +$ sbx secret set openai +$ sbx secret set anthropic +$ sbx secret set google +$ sbx secret set xai +$ sbx secret set nebius +$ sbx secret set mistral +$ sbx secret set openrouter ``` You only need to configure the providers you want to use. Docker Agent detects available credentials and routes requests to the appropriate provider. -Alternatively, export the environment variables (`OPENAI_API_KEY`, -`ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `NEBIUS_API_KEY`, -`MISTRAL_API_KEY`, `OPENROUTER_API_KEY`) in your shell before running the -sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - ## Configuration Sandboxes don't pick up user-level configuration from your host. Only @@ -60,15 +59,17 @@ Without extra args, the sandbox runs: docker-agent run --yolo ``` -Args after `--` replace these defaults rather than being appended. To keep -`run --yolo`, include them yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`). When the first argument is a bare word — such +as the `run` subcommand or a config file — it replaces the defaults, so include +`run --yolo` yourself: ```console -$ sbx run docker-agent -- run --yolo agent.yml +$ sbx run --name <sandbox-name> -- run --yolo agent.yml ``` ## Base image The sandbox uses `docker/sandbox-templates:docker-agent`. See -[Templates](../customize/templates.md) to build your own image on top of +[Base images](/manuals/ai/sandboxes/customize/author/base-images.md) to build your own image on top of this base. diff --git a/content/manuals/ai/sandboxes/agents/droid.md b/content/manuals/ai/sandboxes/agents/droid.md index d62612100c34..34d155fb4f3a 100644 --- a/content/manuals/ai/sandboxes/agents/droid.md +++ b/content/manuals/ai/sandboxes/agents/droid.md @@ -1,11 +1,13 @@ --- title: Droid -weight: 35 +weight: 60 description: | Use Droid in Docker Sandboxes with API key or OAuth authentication. keywords: docker sandboxes, droid, factory, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Droid, an AI coding agent by Factory, in a sandboxed environment. @@ -34,16 +36,12 @@ where you supply a model provider key, Factory manages model access through your Factory account. **API key**: Store your Factory API key using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g droid +$ sbx secret set droid ``` -Alternatively, export the `FACTORY_API_KEY` environment variable in your shell -before running the sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - **OAuth**: If no API key is set, Droid prompts you to authenticate interactively on first run. The proxy handles the OAuth flow, so credentials aren't stored inside the sandbox. diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md index 898dc0740613..e1723ee1ee3d 100644 --- a/content/manuals/ai/sandboxes/agents/gemini.md +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -1,12 +1,14 @@ --- title: Gemini -weight: 40 +weight: 70 description: | Use Google Gemini in Docker Sandboxes with proxy-managed authentication and API key configuration. keywords: docker sandboxes, gemini, google, ai agent, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Google Gemini in a sandboxed environment. @@ -20,28 +22,27 @@ Create a sandbox and run Gemini for a project directory: $ sbx run gemini ~/my-project ``` -The workspace parameter is optional and defaults to the current directory: +`sbx run` defaults the workspace to the current directory: ```console $ cd ~/my-project $ sbx run gemini ``` +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. + ## Authentication Gemini requires either a Google API key or a Google account with Gemini access. **API key**: Store your key using -[stored secrets](../security/credentials.md#stored-secrets): +[stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g google +$ sbx secret set google ``` -Alternatively, export the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment -variable in your shell before running the sandbox. See -[Credentials](../security/credentials.md) for details on both methods. - **Google account**: If no API key is set, Gemini prompts you to sign in interactively when it starts. Interactive authentication is scoped to the sandbox and doesn't persist if you remove and recreate it. @@ -65,13 +66,16 @@ Without extra args, the sandbox runs: gemini --yolo ``` -Args after `--` replace these defaults rather than being appended. To keep -`--yolo`, include it yourself: +Arguments after `--` are added after the default flags when the first one is +itself a flag (begins with `-`), so `--yolo` is preserved: ```console -$ sbx run gemini -- --yolo -p "explain this" +$ sbx run --name <sandbox-name> -- -p "explain this" # runs gemini --yolo -p "explain this" ``` +When the first argument is a bare word — a subcommand or prompt — it replaces +the defaults instead. + ## Base image Template: `docker/sandbox-templates:gemini` diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md index 048160301c8f..02328e6cd338 100644 --- a/content/manuals/ai/sandboxes/agents/kiro.md +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -1,12 +1,14 @@ --- title: Kiro -weight: 50 +weight: 80 description: | Use Kiro in Docker Sandboxes with device flow authentication for interactive AI-assisted development. keywords: docker sandboxes, kiro, ai agent, authentication, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of Kiro in a sandboxed environment. @@ -85,10 +87,12 @@ Without extra args, the sandbox runs: kiro chat --trust-all-tools ``` -Args after `--` replace these defaults rather than being appended. This is -why `sbx run kiro -- login --use-device-flow` works for the login subcommand. -To keep `chat --trust-all-tools` alongside your own args, include them -yourself: +When the first argument after `--` is a flag (begins with `-`), it's added +after the defaults — for example, `sbx run kiro -- --resume` runs +`kiro chat --trust-all-tools --resume`. When the first argument is a bare word, +it replaces the defaults, which is why `sbx run kiro -- login --use-device-flow` +runs the login subcommand on its own. To run `chat` with extra arguments of +your own, include the subcommand: ```console $ sbx run kiro -- chat --trust-all-tools --resume diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md index 23896acb4608..81684aa384a1 100644 --- a/content/manuals/ai/sandboxes/agents/opencode.md +++ b/content/manuals/ai/sandboxes/agents/opencode.md @@ -1,12 +1,14 @@ --- title: OpenCode -weight: 60 +weight: 90 description: | Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI interface for AI development. keywords: docker sandboxes, opencode, ai agent, authentication, sbx --- +{{% include "sandboxes-local-scope.md" %}} + This guide covers authentication, configuration, and usage of OpenCode in a sandboxed environment. @@ -20,38 +22,80 @@ Create a sandbox and run OpenCode for a project directory: $ sbx run opencode ~/my-project ``` -The workspace parameter is optional and defaults to the current directory: +`sbx run` defaults the workspace to the current directory: ```console $ cd ~/my-project $ sbx run opencode ``` +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name. + OpenCode launches a TUI (text user interface) where you can select your preferred LLM provider and interact with the agent. ## Authentication OpenCode supports multiple providers. Store keys for the providers you want to -use with [stored secrets](../security/credentials.md#stored-secrets): +use with [stored secrets](../configuration/credentials.md#stored-secrets): ```console -$ sbx secret set -g openai -$ sbx secret set -g anthropic -$ sbx secret set -g google -$ sbx secret set -g xai -$ sbx secret set -g groq -$ sbx secret set -g aws -$ sbx secret set -g openrouter +$ sbx secret set openai +$ sbx secret set anthropic +$ sbx secret set google +$ sbx secret set xai +$ sbx secret set groq +$ sbx secret set aws +$ sbx secret set openrouter ``` You only need to configure the providers you want to use. OpenCode detects available credentials and offers those providers in the TUI. -You can also use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, -`GOOGLE_GENERATIVE_AI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, -`AWS_ACCESS_KEY_ID`, `OPENROUTER_API_KEY`). See -[Credentials](../security/credentials.md) for details on both methods. +### GitHub Copilot + +To use GitHub Copilot models in OpenCode, configure a +[GitHub credential](../configuration/credentials.md#github-token) for an +account with Copilot access. When OpenCode starts, Docker Sandboxes configures +its GitHub Copilot provider using that credential. You don't need a separate +device login inside OpenCode. + +### OpenCode Zen API keys + +OpenCode Zen API keys aren't part of the built-in OpenCode credentials that +`sbx secret set` supports. To use an OpenCode Zen API key, store it as a +[custom secret](../configuration/credentials.md#custom-secrets): + +Set the `OPENCODE_API_KEY` environment variable on the host, then store it: + +```console +$ sbx secret set-custom \ + --host opencode.ai \ + --env OPENCODE_API_KEY \ + --value "$OPENCODE_API_KEY" +``` + +Custom secrets keep the real key in the host secret store. The sandbox receives +`OPENCODE_API_KEY` as a placeholder, and the host-side proxy replaces that +placeholder with the real key on requests to `opencode.ai`. + +OpenCode Zen also requires network access to `opencode.ai`: + +```console +$ sbx policy allow network opencode.ai:443 +``` + +If you add a global custom secret, recreate existing OpenCode sandboxes so the +new environment variable is available inside the sandbox. + +## Model selection + +To select a local model or inference endpoint with `sbx run --model`, see +[Use local and hosted models](../configuration/models.md). + +When you use `--model`, the model's supported thinking levels are available +as OpenCode variants. Press Ctrl+T to cycle through them. ## Configuration @@ -71,7 +115,7 @@ The sandbox runs `opencode` with no implicit flags. Args after `--` are passed straight through. For example, to resume an existing session: ```console -$ sbx run opencode -- -s <session-id> +$ sbx run --name <sandbox-name> -- -s <session-id> ``` ### TUI mode diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md index 004bb0c1f9a9..2aa72f0aa97f 100644 --- a/content/manuals/ai/sandboxes/agents/shell.md +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -1,10 +1,12 @@ --- title: Shell -weight: 90 +weight: 100 description: Run an agent-less sandbox with a Bash login shell for manual setup, testing custom agent implementations, or inspecting a running environment. keywords: sandboxes, sbx, shell, agent, manual setup, testing --- +{{% include "sandboxes-local-scope.md" %}} + `sbx run shell` drops you into a Bash login shell inside a sandbox with no pre-installed agent binary. It's useful for installing and configuring agents manually, testing custom implementations, or inspecting a running @@ -14,35 +16,45 @@ environment. $ sbx run shell ~/my-project ``` -The workspace path defaults to the current directory. To run a one-off +`sbx run` defaults the workspace to the current directory. To run a one-off command instead of an interactive shell, pass it after `--`: ```console $ sbx run shell -- -c "echo 'Hello from sandbox'" ``` -### Default startup command +To create a [mountless sandbox](../usage.md#choose-a-workspace), use +`sbx create` without a workspace path, then attach by name: + +```console +$ sbx create --name scratch shell +$ sbx run --name scratch +``` + +## Default startup command -Without extra args, the sandbox runs `bash -l`. Args after `--` replace `-l` -rather than being appended. To preserve login-shell behavior, include `-l` -yourself: +Without extra args, the sandbox runs `bash -l`. When the first argument after +`--` is a flag (begins with `-`), it's added after `-l`, so login-shell +behavior is preserved: ```console -$ sbx run shell -- -l -c "echo hi" +$ sbx run shell -- -c "echo hi" # runs bash -l -c "echo hi" ``` -Set your API keys as environment variables so the sandbox proxy can inject -them into API requests automatically. Credentials are never stored inside -the VM: +When the first argument is a bare word, it replaces `-l` instead. + +Store credentials using [stored secrets](../configuration/credentials.md#stored-secrets) +before running the sandbox. The proxy injects them into outbound API requests; +credentials are never stored inside the VM: ```console -$ export ANTHROPIC_API_KEY=sk-ant-xxxxx -$ export OPENAI_API_KEY=sk-xxxxx +$ sbx secret set anthropic +$ sbx secret set openai ``` Once inside the shell, you can install agents using their standard methods, for example `npm install -g @continuedev/cli`. For complex setups, build a -[custom template](../customize/templates.md) instead of installing +[workload kit](/manuals/ai/sandboxes/customize/_index.md) instead of installing interactively each time. ## Base image diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index b8d9f2c1e73f..5e9be8737b0d 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -1,23 +1,41 @@ --- title: Architecture -weight: 40 +weight: 100 description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle. keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle --- +{{% include "sandboxes-local-scope.md" %}} + This page explains how Docker Sandboxes work under the hood. For the security properties of the architecture, see [Sandbox isolation](security/isolation.md). -## Workspace mounting - -Your workspace is mounted directly into the sandbox through a filesystem -passthrough. The sandbox sees your actual host files, so changes in either -direction are instant with no sync process involved. - -Your workspace is mounted at the same absolute path as on your host. Preserving -absolute paths means error messages, configuration files, and build outputs all -reference paths you can find on your host. The agent sees exactly the directory -structure you see, which reduces confusion when debugging or reviewing changes. +## Workspace storage + +Starting with `sbx` version 0.42.0, workspace paths are optional for +`sbx create`. When you omit them, the sandbox has no host workspace bind mount. +The sandbox uses the template image's configured `WORKDIR` as its default +working directory. Docker-provided agent templates set `WORKDIR` to +`/home/agent/workspace`. A custom template can set another absolute path. If +the daemon can't resolve a usable absolute `WORKDIR` from the image config, it +falls back to `/home/agent/workspace`. Files created there stay inside the +sandbox and persist across stops and restarts. + +When you pass a workspace path to `sbx create` or `sbx run`, the directory is +mounted into the sandbox through a filesystem passthrough. `sbx run` uses the +current directory when you don't pass a path. The sandbox sees your actual +host files, so changes in either direction are instant with no sync process +involved. + +A directly mounted workspace appears at the same absolute path as on your +host. Preserving absolute paths means error messages, configuration files, and +build outputs all reference paths you can find on your host. The agent sees the +same directory structure, which reduces confusion when debugging or reviewing +changes. + +Clone mode uses a third storage layout. The host repository is mounted +read-only at `/run/sandbox/source`, and the agent works in a private clone +inside the sandbox. See [Clone mode](usage.md#clone-mode). > [!WARNING] > Avoid mounting network-attached or remote storage (network drives, SMB/NFS @@ -29,35 +47,97 @@ structure you see, which reduces confusion when debugging or reviewing changes. When you create a sandbox, everything inside it persists until you remove it: Docker images and containers built or pulled by the agent, installed packages, -agent state and history, and workspace changes. - -Sandboxes are isolated from each other. Each one maintains its own Docker -daemon state, image cache, and package installations. Multiple sandboxes don't -share images or layers. +agent state and history, and files in mountless or cloned workspaces. Files in +a directly mounted workspace live on the host instead. + +Each sandbox maintains its own Docker daemon state, image cache, and package +installations. Multiple sandboxes don't share images or layers. The +[shared agent skills store](workflows/agent-skills.md) is an exception: +sandboxes created for supported agents mount the same host-side store read-only +by default. Use `--skills` or +[`skills.defaultMode`](configuration/settings.md#skillsdefaultmode) +to choose another mode at +creation. Existing sandboxes retain their mounts until recreated. Each sandbox consumes disk space for its VM image, Docker images, container layers, and volumes, and this grows as you build images and install packages. +Virtiofs caching is enabled by default for directly mounted workspaces on all +operating systems. File reads from the sandbox VM are cached on the host side, +reducing round-trips through the filesystem passthrough and improving +performance for read-heavy workloads such as `git status` or directory scans. +To opt out, set +`DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0` when creating the sandbox: + +```console +$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent> +``` + ## Networking -All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on -your host. Agents are configured to use the proxy automatically. The proxy -enforces [network access policies](governance/) and handles -[credential injection](security/credentials.md). See +All outbound TCP traffic from the sandbox routes through a proxy on your host. +Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded +transparently. Both paths enforce +[network access policies](governance/access-controls/network.md). The forward +proxy also handles [credential injection](configuration/credentials.md). See [Network isolation](security/isolation.md#network-isolation) for how this works and [Default security posture](security/defaults.md) for what is allowed out of the box. +### Follow an authenticated request + +Step through the following diagram to see where Docker Sandboxes checks network +policy and replaces a sentinel credential with the real value. The real credential stays +outside the sandbox throughout the request. + +{{< interactive-diagram src="diagrams/credential-injection.yaml" >}} + +### Upstream proxy + +The host-side proxy makes its outbound connections using your host's network +configuration and routing. When a destination is reachable through a direct +route, traffic follows that route. When reaching a destination requires an +upstream proxy, the host-side proxy forwards the request to it. Chaining to an +upstream proxy means sandbox traffic respects the same egress controls as other +applications on your host. + +By default, both sandbox traffic and the daemon's own traffic follow your OS +system proxy, so this usually works without any configuration. To set a proxy +explicitly — with a proxy URL, a PAC file, a SOCKS5 proxy, or separate settings +for sandbox and daemon traffic — see +[Configure an upstream proxy](configuration/upstream-proxy.md). Upstream proxy support is +experimental and subject to change. + +Only HTTP and HTTPS traffic can be forwarded to an upstream proxy. Other TCP +traffic can't be redirected to a proxy. + +## MCP gateway + +Supported agents connect to a single MCP gateway endpoint for the sandbox. The +gateway runs on the host side of the sandbox boundary and brokers access to +registered MCP servers. + +Registered MCP servers can be remote endpoints, or they can be local stdio +servers launched on the host. Local stdio servers don't run inside the sandbox +VM. If a local stdio server is packaged as an OCI image, or if you register an +explicit `docker` command, it uses Docker on the host. + +When MCP policies apply, enforcement happens on the MCP gateway path, separate +from the HTTP/HTTPS network proxy. Server registration is checked before the +server is stored, and governed MCP requests are checked by the gateway before +tool calls, resource reads, prompt retrieval, or gateway meta-tool execution. + ## Lifecycle -`sbx run` initializes a VM with a workspace for a specified agent and starts -the agent. You can stop and restart without recreating the VM, preserving -installed packages and Docker images. +`sbx run` initializes a VM for a specified agent and starts the agent. You can +stop and restart without recreating the VM, preserving installed packages, +Docker images, and in-sandbox files. Sandboxes persist until explicitly removed. Stopping an agent doesn't delete the VM; environment setup carries over between runs. Use `sbx rm` to delete the sandbox, its VM, and all of its contents. If the sandbox used -`--branch`, the worktree directories and their branches are also removed. +[`--clone`](usage.md#clone-mode), the `sandbox-<name>` Git remote is also +removed from your host repository. ## Comparison to alternatives diff --git a/content/manuals/ai/sandboxes/cloud/_index.md b/content/manuals/ai/sandboxes/cloud/_index.md new file mode 100644 index 000000000000..3a397424aafd --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/_index.md @@ -0,0 +1,134 @@ +--- +title: Cloud sandboxes +description: Run Docker Sandboxes on Docker-managed cloud infrastructure and understand the cloud-specific command, storage, and billing model. +keywords: docker sandboxes, cloud sandboxes, sbx cloud, ai agents, agentic platform +weight: 35 +--- + +Cloud sandboxes run AI agents on Docker-managed infrastructure instead of your +local machine. Use them when you need an isolated environment that doesn't +depend on the compute resources or virtualization support of your host. + +Cloud sandboxes use the same `sbx` CLI as local sandboxes. Add the global +`--cloud` flag to send a supported command to the Cloud Sandboxes API: + +```console +$ sbx --cloud ls +``` + +Cloud and local sandboxes have separate state and different capabilities. A +cloud sandbox can't mount a host workspace or use host hardware, and its +secrets, network policy, ports, and lifecycle are managed in the cloud. See +[Local and cloud differences](local-vs-cloud.md) before adapting a local +workflow. + +## Prerequisites + +To use cloud sandboxes, you need: + +- The [`sbx` CLI](../install.md), version 0.45.0 or later +- An active [Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access) + +Follow [Signup and billing](/manuals/agentic-platform/signup.md) to activate +cloud access and review compute charges. Then return here to sign in from the +CLI and configure your agent. + +### Sign in from the CLI + +Sign in with the same Docker account you used to subscribe: + +```console +$ sbx login +``` + +For CI and other environments without a browser, sign in with a Docker +Personal Access Token (PAT) for the subscribed account: + +```console +$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin +``` + +For PAT setup instructions, see [CI and headless use](../workflows/automation.md). + +Check cloud connectivity and account access: + +```console +$ sbx --cloud diagnose +``` + +If the check reports that your account doesn't have access, follow +[Check account access](/manuals/agentic-platform/signup.md#check-account-access). + +## Get started + +Credentials configured for local sandboxes aren't available to cloud +sandboxes. Configure a cloud credential for your agent before launching it. +For Claude Code, store an Anthropic API key: + +```console +$ sbx --cloud secret set anthropic +``` + +See [Authenticate cloud agents](credentials.md) for other agents and credential +options. + +Cloud sandboxes expire after one hour by default. On expiration, the service +stops sandboxes that can be resumed and deletes the rest. Check the timeout +action before relying on a sandbox to retain your work. See +[Configure expiration](usage.md#configure-expiration). + +Create a sandbox without attaching, allowing access to GitHub for this example: + +```console +$ sbx --cloud create --name cloud-project --allow-network github.com:443 claude +``` + +Cloud sandboxes don't accept a local workspace path. Clone the public +[Welcome to Docker repository](https://github.com/docker/welcome-to-docker) +inside the sandbox: + +```console +$ sbx --cloud exec cloud-project git clone \ + https://github.com/docker/welcome-to-docker.git /home/agent/workspace/project +``` + +Attach to the agent: + +```console +$ sbx --cloud attach cloud-project +``` + +Ask Claude to inspect `/home/agent/workspace/project` and write a description +of the application to `/home/agent/workspace/review.md`. When the file is ready, +press `Ctrl+\` to detach and leave the agent running. + +Copy the result to your machine: + +```console +$ sbx --cloud cp cloud-project:/home/agent/workspace/review.md ./review.md +``` + +Read the result, then remove the sandbox when you're finished: + +```console +$ sbx --cloud rm cloud-project +``` + +Removal deletes files stored only in the sandbox. For your own projects, see +[Transfer files](usage.md#transfer-files) and +[Authenticate cloud agents](credentials.md) before cloning private repositories. + +## Learn more + +- [Signup and billing](/manuals/agentic-platform/signup.md) covers activation + and compute charges +- [Local and cloud differences](local-vs-cloud.md) compares the two execution + environments +- [Use cloud sandboxes](usage.md) covers creation, files, ports, and lifecycle +- [Authenticate cloud agents](credentials.md) covers cloud-specific secrets, + API keys, and OAuth +- [Manage cloud network policy](network-policy.md) covers account-level and + sandbox-level network access +- [Move a sandbox](move.md) explains filesystem transfers between local and + cloud environments +- [`sbx` CLI reference](/reference/cli/sbx/) lists commands and options diff --git a/content/manuals/ai/sandboxes/cloud/credentials.md b/content/manuals/ai/sandboxes/cloud/credentials.md new file mode 100644 index 000000000000..7f64f369316b --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/credentials.md @@ -0,0 +1,151 @@ +--- +title: Authenticate cloud agents +linkTitle: Credentials +description: Configure cloud-specific API keys and OpenAI OAuth credentials for agents without storing credentials in the cloud sandbox filesystem. +keywords: docker sandboxes, cloud credentials, cloud secrets, oauth, anthropic, openai +weight: 30 +--- + +Cloud agents authenticate with credentials from the cloud secret store. Set up +these credentials before launching an agent so authentication doesn't depend +on files stored inside the sandbox. + +## Use the cloud secret store + +The following secret interfaces are separate: + +- `sbx secret` manages secrets for local sandboxes +- `sbx --cloud secret` manages secrets for cloud sandboxes created by the CLI +- Docker Agentic Platform manages its own secret names through its web + interface + +A credential created through one interface isn't available through the +others. Configure a cloud credential using one of the following methods before +starting a cloud sandbox. + +## Choose an authentication method + +For Claude Code, use an Anthropic API key. For Codex, use an OpenAI API key or +account-scoped OpenAI OAuth credentials. + +Configure your agent with the corresponding command: + +| Agent or provider | Recommended command | Authentication | +| --- | --- | --- | +| Claude Code | `sbx --cloud secret set anthropic` | Prompts for an Anthropic API key | +| Codex with OpenAI OAuth | `sbx --cloud secret set openai --oauth` | Opens the OpenAI OAuth flow and stores the resulting credential at account scope | +| Service API key | `sbx --cloud secret set <service>` | Prompts for an API key or token | + +For Codex, you can use OpenAI OAuth at account scope or store an OpenAI API +key with `sbx --cloud secret set openai`. + +After storing an Anthropic API key, launch Claude Code: + +```console +$ sbx --cloud run claude --name cloud-project +``` + +## Keep credentials out of the sandbox filesystem + +Credentials configured with `sbx --cloud secret` stay in the cloud secret store, +outside the sandbox filesystem. + +An agent's interactive sign-in can write credentials inside the sandbox. +Those files can be included in templates and `sbx move` snapshots. If you +signed in inside an agent, follow the provider's sign-out guidance and remove +those credentials before capturing or moving the sandbox. + +## Set credential scope + +Credentials use account scope by default. An account-scoped credential is +available to cloud sandboxes in the Docker account: + +```console +$ sbx --cloud secret set github +``` + +Scope an API key or token to one sandbox by name: + +```console +$ sbx --cloud secret set openai --sandbox cloud-project +``` + +A sandbox-scoped secret takes precedence over an account-scoped secret for the +same service. Set it before creating the sandbox so the CLI can include it when +the sandbox starts. OAuth credentials can't use sandbox scope. + +## Service identifiers + +The following table shows cloud secret support for the +[built-in services documented for local sandboxes](../configuration/credentials.md#built-in-services): + +| Service | Cloud secret authentication | +| --- | --- | +| `anthropic` | API key | +| `cursor` | API key | +| `droid` | API key; cloud-managed OAuth is not supported | +| `github` | Token | +| `google` | API key | +| `groq` | API key | +| `mistral` | API key | +| `nebius` | API key | +| `openai` | API key or OAuth | +| `openrouter` | Use a [custom secret](#configure-a-custom-secret) | +| `xai` | API key | + +To configure a supported service, run `sbx --cloud secret set <service>`. +For OpenAI OAuth, add `--oauth` and use account scope. + +For other services, configure a [custom secret](#configure-a-custom-secret). + +The cloud secret commands don't support registry credentials or dynamic +`--ref` and `--command` resolvers. An +[environment file](../configuration/environment-files.md#secrets) can resolve a +host command or vault reference once with `snapshot: true` and upload the +result as a literal cloud secret. + +## Configure a custom secret + +Use `set-custom` for an API that isn't a built-in service: + +```console +$ sbx --cloud secret set-custom --name project-api \ + --host api.example.com --env PROJECT_API_TOKEN +``` + +The command prompts for the value. Sandboxes using this secret receive a +placeholder in `PROJECT_API_TOKEN`. The cloud proxy sets +`Authorization: Bearer <secret>` on requests to `api.example.com`. Unlike local +custom secrets, cloud injection sets the header based on the destination host +without requiring a matching placeholder in the request. + +Use `--header` to select another header. When you specify a header, the default +value is the raw secret. Use `--format` with one `%s` placeholder to add a +prefix, for example `--header Authorization --format 'Bearer %s'`. + +Each `--host` must be an exact DNS name without a scheme, port, or path. Repeat +the flag for multiple hosts. IP addresses and wildcards aren't supported. +Add `--sandbox cloud-project` to scope the secret to that sandbox, and set it +before creating the sandbox. A custom secret name can't match a built-in +service name. + +## List and remove credentials + +List cloud secret metadata without revealing values: + +```console +$ sbx --cloud secret ls +``` + +Remove a credential from the matching scope: + +```console +$ sbx --cloud secret rm github +$ sbx --cloud secret rm openai --sandbox cloud-project +$ sbx --cloud secret rm project-api +``` + +Custom secrets can also be removed by a host they serve, using +`sbx --cloud secret rm --host api.example.com`. Removal asks for confirmation. +Use `--force` in scripts. Cloud mode doesn't support removing every secret in +one operation. diff --git a/content/manuals/ai/sandboxes/cloud/environment-files.md b/content/manuals/ai/sandboxes/cloud/environment-files.md new file mode 100644 index 000000000000..32bf6d37d455 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/environment-files.md @@ -0,0 +1,289 @@ +--- +title: Use environment files in the cloud +linkTitle: Environment files +description: Create a repeatable cloud sandbox with sbx env, copy in your project, work with an agent, and retrieve your changes. +keywords: docker sandboxes, cloud sandbox, sbx env, sbxenv, environment file +weight: 25 +--- + +Use an environment file to share a cloud sandbox's agent, tools, environment +variables, and resource limits with your project contributors. Run +`sbx --cloud env` to apply that configuration on Docker-managed infrastructure. + +A cloud environment has its own filesystem. It doesn't mount or synchronize +directories from your machine, so leave `workspace` out of the file. Copy your +project into the sandbox or clone it there, and copy the results back or push +your commits before removing the sandbox. Credentials and network policy are +also separate from your local sandbox configuration. Host lifecycle commands +still run on your machine, with your privileges. + +> [!NOTE] +> `sbx env` is experimental. The command interface and file format may change. + +## Prepare your environment + +Complete the [cloud prerequisites](_index.md#prerequisites), including activating +cloud access and signing in with `sbx login`. Cloud compute charges apply. + +This walkthrough uses Claude Code to work on a local project named `web-app`. +Configure an Anthropic API key in the cloud secret store before creating the +sandbox: + +```console +$ sbx --cloud secret set anthropic +``` + +The command prompts for the key. For other agents and authentication options, +see [Authenticate cloud agents](credentials.md). A credential configured for a +local sandbox isn't available in the cloud. + +If you want the agent to push changes to GitHub, configure a GitHub token +before creating the sandbox: + +```console +$ sbx --cloud secret set github --sandbox cloud-web-app +``` + +The command prompts for a token. Use one with write access to your repository. +The `--sandbox` value must match the environment's `name`. Cloud environments +select their credentials at creation: adding a GitHub secret afterward won't +make it available to an existing environment. If you decide to push later, +copy your work out first, then recreate the environment with the secret. + +Save the following as `cloud.sbxenv.yaml` in your project's root directory. +You can keep the file elsewhere if you prefer: its location doesn't determine +which files are available in the cloud sandbox. + +```yaml +schemaVersion: "1" +name: cloud-web-app +agent: claude + +env: + NODE_ENV: test + +sandboxOptions: + cpus: 2 + memory: 4g +``` + +This selects Claude Code, sets `NODE_ENV` for the sandbox, and requests two +CPUs and 4 GiB of memory. Resource limits must match a +[cloud size](usage.md#choose-resources-and-platform). You can also add +[`kits`](../configuration/environment-files.md#kits) to install project tools. + +## Create the sandbox and add your project + +From your project directory, review the plan and create the sandbox without +attaching: + +```console +$ sbx --cloud env plan ./cloud.sbxenv.yaml +$ sbx --cloud env create --ttl 2h --on-timeout delete ./cloud.sbxenv.yaml +``` + +The plan shows the configuration and inherited cloud credentials. Creation +asks you to approve the plan before applying it. This example explicitly +deletes the sandbox after two hours, so retrieve your work before then. +Without timeout flags, a cloud sandbox expires after one hour, and the service +stops sandboxes that can be resumed and deletes the rest. See +[Configure expiration](usage.md#configure-expiration) for other options. + +Copy your project into the sandbox's workspace: + +```console +$ sbx --cloud cp . cloud-web-app:/home/agent/workspace/web-app +``` + +Use a destination that doesn't already exist for this first copy. Copying a +directory to an existing directory nests it under its source name. Review the +files you're uploading: `cp .` doesn't respect `.gitignore`. It includes hidden +files such as `.env`, Git history, dependencies, and build output. For larger +projects, prepare a clean staging directory containing only the files you want +to upload, and copy that directory instead. Copying is a one-time transfer: +later edits on either side aren't synchronized. Directory uploads skip symbolic +links and empty directories and report what was skipped. Install dependencies +inside the sandbox rather than copying a local dependency directory. + +For a Git workflow, you can instead clone a repository inside the sandbox and +push commits to your remote. Configure [cloud credentials](credentials.md) for +private repository access and [cloud network policy](network-policy.md) for +the destinations your project needs. Copying includes uncommitted local work; +cloning a specific commit gives contributors a reproducible starting point. + +### Automate the initial upload + +To upload your project whenever you create a fresh sandbox, add a `postCreate` +command to the environment file. This automates the initial upload as part of +setup. + +```yaml +lifecycle: + postCreate: + - name: Upload project + command: sbx --cloud cp . "$SBX_SANDBOX_NAME:/home/agent/workspace/web-app" +``` + +Here, `.` resolves to the directory containing the environment file. If you +keep the file elsewhere or upload from a staging directory, set the command's +`workdir` to the project or staging directory. The same file selection rules +as the manual copy apply, including copying ignored files and skipping symbolic +links and empty directories. + +The command runs on your machine after sandbox creation and before `run` +attaches to the agent. `SBX_SANDBOX_NAME` contains the sandbox name, including +any `--name` override. Reconnecting skips `postCreate`, preserving the agent's +work. Later local edits aren't uploaded automatically. + +With this block in place, use `sbx --cloud env run ./cloud.sbxenv.yaml` to create +the sandbox, upload the project, and attach to the agent. It replaces the manual +upload step for future sandbox creation. + +If the upload fails, the sandbox has already been created and remains available. +Inspect it and finish transferring files manually, or remove it with +`sbx --cloud env rm ./cloud.sbxenv.yaml` before trying a fresh creation. + +See [Automate setup with host commands](#automate-setup-with-host-commands) for more +about lifecycle commands and approval. + +## Work with the agent + +Attach to Claude Code using the same environment file: + +```console +$ sbx --cloud env run ./cloud.sbxenv.yaml +``` + +For example, ask the agent: + +```text +Work in /home/agent/workspace/web-app. Find the test and lint commands in +package.json, install the dependencies, and run those checks. Fix any failures +and explain your changes. Ask before changing dependencies. +``` + +Use `run` again to reconnect to the existing sandbox. It creates a sandbox if +one doesn't exist. Pass `--ttl` and `--on-timeout` only when creating a sandbox: +`run` rejects those flags when attaching to an existing one. + +Press `Ctrl+\` to detach while leaving the agent running. You can also run a +command without an agent session, for example to inspect the working tree of +a copied Git project: + +```console +$ sbx --cloud env exec ./cloud.sbxenv.yaml -- \ + git -C /home/agent/workspace/web-app diff --stat +``` + +For subsequent environment commands, keep the same machine, cloud endpoint, +Docker account, and ordered environment file paths. The CLI records the cloud +sandbox's identity locally to manage it across invocations. + +## Retrieve your work and clean up + +After the agent finishes, copy the project back to a separate local directory +so you can review it before updating your original files: + +```console +$ sbx --cloud cp cloud-web-app:/home/agent/workspace/web-app ../web-app-result +``` + +Use a destination that doesn't already exist. + +### Push changes to GitHub instead + +If you configured the GitHub secret before creating the environment, you can +retrieve changes through Git instead of copying files. This works with a +repository cloned inside the sandbox or a copied Git repository whose +`.git` directory contains the repository history. Use an HTTPS GitHub remote +that your token can push to. + +For example, ask the agent: + +```text +In /home/agent/workspace/web-app, review the diff, create a branch named +cloud-fixes, commit the changes for this task, and push that branch to origin. +``` + +Then, from your local checkout, fetch the branch and check it out for review: + +```console +$ git fetch origin +$ git switch --track origin/cloud-fixes +``` + +The commits are available on GitHub even after the sandbox is removed. + +### Remove the environment + +When you've saved your work, remove the environment: + +```console +$ sbx --cloud env rm ./cloud.sbxenv.yaml +``` + +Removal asks for approval and deletes the sandbox and secrets provisioned by +this environment. Inherited credentials, such as the Anthropic key configured +earlier, remain. Global bindings remain unless you pass `--prune-bindings`. +Files stored only in the sandbox are lost on deletion. + +For unattended commands, use `--force` with `create`, `run`, or `rm` to approve +the plan for that invocation. Use `run --detach` when no interactive terminal +is available. + +## Adapt an existing environment file + +Cloud environments support agents, kits, environment variables, CPU and memory +limits, credentials for supported providers, and host lifecycle commands. +They support a subset of the [environment file fields](../configuration/environment-files.md#file-reference). +Use the following checks before reusing a local file. + +### Remove local settings + +Remove these declarations: + +- `workspace`, `additionalWorkspaces`, and clone options +- `ports`, `registries`, and `mcp.servers` +- `sandboxOptions.template`, `profile`, `pullPolicy`, `skills`, `display`, + `gpu`, `usb`, and `writableEnvFiles` + +Unsupported settings are rejected before host commands or provisioning run. +Pass the cloud file path explicitly to avoid loading local settings from +`~/.sbxenv.yaml`. For services and integrations, use the cloud commands to +[expose ports](usage.md#expose-a-port) and [load MCP servers](usage.md#load-an-mcp-server). + +### Automate setup with host commands + +Lifecycle commands connect the cloud environment’s lifecycle to work on your +machine. They’re useful when setup or cleanup depends on local files, tools, or +credentials. Including those steps in the environment file makes the workflow +repeatable, even when it spans your machine and the cloud sandbox. + +Use `initialize` to prepare files before creation and `preRemove` to retrieve +results when you run `sbx --cloud env rm`. `preRemove` doesn't run when the +cloud service deletes an expired sandbox, and a failed command doesn't prevent +removal. Save work you need to keep before removing the environment. + +Host commands appear in the plan and require approval. See +[Lifecycle commands](../configuration/environment-files.md#lifecycle) for phase +timing, working directories, and approval options. + +### Configure cloud credentials + +The plan shows inherited cloud credentials. Sandbox-scoped credentials override +account defaults, and credentials declared in `secrets` override both. Use +[`snapshot: true`](../configuration/environment-files.md#secrets) to resolve a +host command or vault reference once and upload the value. Snapshots don't +refresh. Dynamic secret sources and custom credential providers aren't +supported. Credential bindings require cloud support for kit credentials and +explicit approval of the kit's injection domains. + +### Apply changes and recover interrupted creation + +Changes to secrets, bindings, kits, or resource limits require recreating the +sandbox. Updated `env` values apply to subsequent sessions. Rejoining a running +agent keeps that process's environment. + +If creation is interrupted, retry the same command and unchanged declaration +within 23 hours. Unresolved requests prevent removal. Follow the recovery +message and retain its journal until the original requests are resolved. diff --git a/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md new file mode 100644 index 000000000000..1f4521efeb71 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md @@ -0,0 +1,105 @@ +--- +title: Compare local and cloud sandboxes +linkTitle: Local and cloud +description: Compare local and cloud Docker Sandboxes, including workspaces, host integrations, ports, secrets, storage, and lifecycle behavior. +keywords: docker sandboxes, local sandbox, cloud sandbox, sbx cloud, comparison +weight: 10 +--- + +Local and cloud sandboxes provide isolated environments for AI agents, but +they run against different resources and stores. This comparison helps you +choose an environment and identify workflows that need cloud-specific setup. + +| Capability | Local sandbox | Cloud sandbox | +| --- | --- | --- | +| Compute | Uses resources from the host | Uses Docker-managed cloud resources | +| CPU architecture | Uses the platform supported by the local runtime | Supports `linux/amd64` and `linux/arm64`, subject to account availability; moves must retain the source platform | +| Workspace | Mounts host paths or uses a private Git clone backed by the host repository | Has no access to host paths; transfer files or clone a repository inside the sandbox | +| Hardware | Can use supported host integrations, such as GPU, USB, display, and nested virtualization | Has no access to host hardware | +| Ports | Binds sandbox ports to host addresses and ports | Exposes a sandbox port through a public HTTPS URL | +| Secrets | Reads from the local `sbx` secret store | Reads from the separate `sbx --cloud` secret store | +| Network policy | Uses local and organization policy sources supported by the local runtime | Uses separate, network-only account and sandbox policy; local policies aren't copied | +| MCP servers | Uses servers registered in the local MCP store | Uses servers connected through Docker Agentic Platform | +| Storage | Persists in the local sandbox and its attached host resources | Persists in the cloud sandbox and optional cloud volumes | +| Lifetime | Persists across stops until you remove it | Expires according to its time-to-live and timeout action | +| Billing | No metered sandbox compute charge | [Pay-as-you-go compute](/manuals/agentic-platform/signup.md#billing) | + +If your workflow runs Docker inside the sandbox, review the +[Docker exec and healthcheck limitation](usage.md#docker-exec-and-healthchecks). +It can affect container setup, debugging, and Compose service readiness. + +## Host-dependent features + +A cloud sandbox has no path back to the machine where you run `sbx`. The +following local features don't apply in cloud mode: + +- Workspace paths, bind mounts, `--clone`, and Git worktrees created with + `--branch` +- GPU, USB, display, and nested virtualization options +- Model selection through `--model` and `--provider` +- Host port bindings +- Host-backed agent skills and the full local MCP management workflow + +The CLI rejects local-only flags used with `--cloud` instead of ignoring them. + +You can use [environment files](environment-files.md) +with `sbx --cloud env`. Cloud environments support a subset of the local +configuration fields, including agents, environment variables, resource limits, +and credentials. Remove host workspace and port mappings before using a local +environment file in the cloud. + +## Separate resources + +Adding `--cloud` changes the backend for the command. A sandbox shown by +`sbx ls` doesn't appear in `sbx --cloud ls`, and resources created for one +backend don't automatically become available to the other. + +This separation applies to sandboxes, templates, secrets, volumes, and network +policy. Use [`sbx move`](move.md) when you need to copy a sandbox filesystem +between backends. Moving doesn't unify the resource stores or transfer +host-mounted files or managed secrets. Credentials saved in copied files can +still travel with the sandbox. + +## Network policy differences + +Configure and verify [cloud network policy](network-policy.md) separately. +Moving a sandbox doesn't carry its local policy configuration into the cloud. +The cloud CLI supports account and sandbox network rules, but rejects local +governance profiles and the `--protocol` option. + +HTTP method and path restrictions, also called L7 filtering, aren't supported +in cloud sandboxes. If these rules apply to a local sandbox, `sbx move` warns +and asks for confirmation before moving it to the cloud. + +## What changes when you move + +[`sbx move`](move.md) copies a filesystem snapshot and creates a separate +destination sandbox. It doesn't transfer running processes or memory, and it +leaves the source sandbox in place. Large images can take time to upload or +download, depending on image size and available bandwidth. For cloud-to-local +moves, also allow for [temporary disk space](move.md#move-from-cloud-to-local). + +| State | Local to cloud | Cloud to local | What to do | +| --- | --- | --- | --- | +| Network policy | Local rules aren't copied; the CLI warns that cloud policy applies | Cloud rules aren't copied; the CLI notice explains that the host's default egress policy applies | Configure destination rules and verify allowed and blocked connections before continuing work | +| Managed secrets | Uses applicable credentials in the cloud secret store | Uses applicable credentials in the local secret store | Configure credentials in the destination store; the CLI warns that secrets aren't copied and you may need to sign in again | +| Workspace and attached storage | Host mounts and clone-mode volumes aren't copied; a workspace triggers a warning and confirmation | Cloud volumes aren't copied and no host folder is mounted | Transfer needed files separately with `sbx cp` | +| Published ports | TCP ports get cloud URLs; refused ports are skipped with a warning | Ports use local loopback bindings; cloud URLs aren't retained | Inspect destination ports and update clients | +| CPU and memory | Rounds recorded source limits up to a supported cloud size; missing limits use defaults with a warning | Uses local defaults | Check destination resources and workload performance; `sbx move` has no CPU or memory override flags | +| CPU architecture | Cloud access must support the source platform | The local runtime must support the source platform | Match platforms; the CLI checks compatibility before transfer | + +The managed-secret warning doesn't itself block a move. Configure +[cloud credentials](credentials.md) or +[local credentials](../configuration/credentials.md) before using an agent +that needs them. Credentials written to files inside the sandbox can be +included in the snapshot; remove those files before moving if you don't want +the credentials copied. + +Cloud-to-local moves display a notice and ask for confirmation. Local-to-cloud +moves ask for confirmation when workspace files or L7 filtering would be left +behind. If a confirmation is required and standard input isn't a terminal, +the move fails unless you pass `--force`. This flag skips confirmation but +retains warnings and doesn't change what transfers. + +Verify the destination's files, credentials, network access, ports, and +[expiration settings](usage.md#configure-expiration) before removing the source. diff --git a/content/manuals/ai/sandboxes/cloud/move.md b/content/manuals/ai/sandboxes/cloud/move.md new file mode 100644 index 000000000000..cc2e83de2599 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/move.md @@ -0,0 +1,162 @@ +--- +title: Move a sandbox +description: Transfer a Docker Sandbox filesystem between local and cloud environments and understand which state, files, policies, and secrets remain behind. +keywords: docker sandboxes, sbx move, cloud sandbox, local sandbox, migrate sandbox +weight: 50 +--- + +The `sbx move` command transfers a filesystem snapshot between a local sandbox +and a cloud sandbox. Use it to continue from the captured filesystem in the +other environment, not as a live migration of the running sandbox. + +## Transfer behavior + +A move performs the following operations: + +1. Captures the source sandbox filesystem as a template image +2. Transfers the image across the local and cloud boundary +3. Creates a destination sandbox from the image + +The destination gets a different sandbox ID. The source isn't deleted, so the +two sandboxes have independent state after the transfer. A local-to-cloud move +stops the local source while capturing it. A cloud-to-local move attempts to +stop the cloud source after creating the destination. This is a best-effort +operation, so the cloud source can remain running if it can't be stopped. +The move can return before the stop finishes. Check `sbx --cloud ls` for its +state. A cloud source with no agent is left running. +Remove the source separately after you verify the destination. + +> [!IMPORTANT] +> +> Managed secrets aren't copied from the source secret store. Credentials +> written inside a sandbox by an agent's interactive sign-in are ordinary +> filesystem files and are included in the snapshot. Remove in-sandbox +> credentials before moving a sandbox. + +Moving transfers filesystem data stored in the sandbox container. It doesn't +transfer: + +- Running processes, memory, or open sockets +- Local workspace mounts, bind mounts, or clone-mode volumes +- Managed secrets from the source secret store +- Other resources attached outside the sandbox filesystem + +Changes made to either sandbox after the move aren't synchronized. + +The snapshot retains the source sandbox's platform. The destination must +support the same platform because `sbx move` doesn't convert between +`linux/amd64` and `linux/arm64`. For a local-to-cloud move, your cloud account +must support the local sandbox's platform. For a cloud-to-local move, create +the cloud sandbox with `--platform linux/amd64` or `--platform linux/arm64` +to match your local sandbox runtime. The CLI checks compatibility before +transferring the snapshot. + +## Move from local to cloud + +Move a local sandbox to the cloud: + +```console +$ sbx move local-project --to cloud +``` + +The `move` command spans both backends, so don't add the global `--cloud` flag. +Use `--name` to set the destination name prefix. The cloud destination appends +a short unique suffix: + +```console +$ sbx move local-project --to cloud --name cloud-project +``` + +Local workspace files are mounted outside the sandbox filesystem and don't +appear in the cloud destination. When the source has a workspace, the CLI +warns and asks for confirmation. The `--force` flag skips the prompt but +doesn't include those files. + +The destination uses cloud network policy and the network rules of the +sandbox's kit, or of its built-in agent, as `sbx --cloud create` does. Network +rules you added locally don't transfer. If the local source has HTTP method or +path restrictions, the CLI warns and asks for confirmation because those +restrictions won't apply in the cloud. `--force` skips the prompt but retains +the warning. + +Published TCP sandbox ports are published on the cloud destination with cloud +URLs. Ports that the cloud refuses are skipped with a warning. Host port +numbers and non-TCP mappings don't transfer. + +The destination can use applicable credentials that already exist in the cloud +secret store. Credentials in the local secret store don't transfer. + +The CLI rounds the source's recorded CPU and memory limits up to a supported +[cloud size](usage.md#choose-resources-and-platform). Missing limits use cloud +defaults with a warning. Limits above the largest cloud size prevent the move. +The `move` command has no `--cpus` or `--memory` overrides. Resource sizing +doesn't guarantee the same performance as the source; check your workload on +the destination before removing the source. + +### Set destination expiration + +The cloud destination has an expiration time, even if the local source had +none. Without `--ttl`, it uses the server default, typically one hour. The +move requests that the sandbox stop on expiration when the account and sandbox +support it. Otherwise, it falls back to the server's default timeout action, +which deletes the sandbox. + +Set the expiration and action explicitly when moving work you want to retain: + +```console +$ sbx move local-project --to cloud --ttl 2h --on-timeout stop +``` + +The `stop` action preserves state. An explicit request fails if stopping is +unavailable. Use `--on-timeout delete` to delete on expiration. + +To restart the destination automatically when it expires, use `restart`: + +```console +$ sbx move local-project --to cloud --ttl 4h --on-timeout restart +``` + +The `restart` action stops and immediately starts the destination. If you +specify `--ttl`, it must be at least one hour. + +These flags apply only to moves to the cloud. After the move, inspect or extend +the expiration with [`sbx --cloud ttl`](usage.md#configure-expiration). + +## Move from cloud to local + +Move a cloud sandbox to the local runtime by ID or name: + +```console +$ sbx move cloud-project --to local --name local-copy +``` + +The local destination starts with the host's default network policy. Cloud +network rules aren't copied back to the local runtime. + +Published TCP ports are saved on the local sandbox and bound to loopback while +it runs. Host port numbers can change after a restart. Run +`sbx ports local-copy` to see the bindings. + +The move doesn't create a host workspace. Use `sbx cp` to copy files from the +local sandbox to your host. Attached cloud volumes and environment variables +don't transfer. The local destination uses local CPU and memory defaults. + +This direction requires a machine that meets the local sandbox requirements +because the command imports the snapshot and creates a local sandbox. The +cloud source remains available unless you remove it with `sbx --cloud rm`. + +Layer reuse during download can require up to 32 GiB of temporary host disk +space in addition to the local runtime's image storage. + +## Verify the result + +List both backends after the move: + +```console +$ sbx ls +$ sbx --cloud ls +``` + +Inspect the destination filesystem and verify its credentials, ports, volumes, +and other environment-specific resources before removing the source. Configure +anything that didn't carry over. diff --git a/content/manuals/ai/sandboxes/cloud/network-policy.md b/content/manuals/ai/sandboxes/cloud/network-policy.md new file mode 100644 index 000000000000..85cf01026e02 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/network-policy.md @@ -0,0 +1,127 @@ +--- +title: Manage cloud network policy +linkTitle: Network policy +description: Control outbound connections from Docker cloud sandboxes with account-level and sandbox-level allow and deny network rules. +keywords: docker sandboxes, cloud network policy, sbx cloud, allow network, deny network +weight: 40 +--- + +Cloud network policy controls outbound connections from cloud sandboxes. It is +a separate, network-only policy store with Docker account and individual +sandbox scopes. + +> [!IMPORTANT] +> +> Local policy configuration isn't copied to cloud sandboxes. Configure cloud +> rules with `sbx --cloud policy` and verify network access using connection +> checks and policy logs. + +## Understand policy scope + +The cloud CLI supports account and sandbox policy scopes. Your account policy +supplies the default for cloud sandboxes you create in the Docker account. A +sandbox policy adds rules for one cloud sandbox. Matching deny rules take +precedence over allow rules across the applicable policies. + +Cloud creation uses cloud account policy, network rules passed to the command, +and network access declared by the agent or kit. Both `sbx --cloud create` and +`sbx --cloud run` leave local network and organization policies on the host. +Moving a local sandbox to the cloud works the same way, except that rules you +added locally don't transfer. + +Define the intended policy in the cloud store. After creation, inspect the +configured rules and [verify connection decisions](#inspect-network-policy). + +## Initialize account policy + +Set the account policy to `allow-all`, `balanced`, or `deny-all`: + +```console +$ sbx --cloud policy init deny-all +``` + +The default applies to your cloud sandboxes in the Docker account. You can add +rules after initialization or specify initial rules when creating a sandbox. +A deny-all default still permits destinations allowed by applicable sandbox +or agent-kit rules. + +The `balanced` preset sets deny-all as the default and adds allow rules for +common development services. To set a default for one sandbox, use +`sbx --cloud policy init deny-all --sandbox cloud-project`. + +You can run `init` again to change the default. Existing allow and deny rules +remain in place. Use `reset` to remove account rules before choosing another +preset. + +## Add network rules + +Add an account-level exception: + +```console +$ sbx --cloud policy allow network api.github.com:443 +``` + +Scope a rule to one sandbox: + +```console +$ sbx --cloud policy allow network api.anthropic.com:443 \ + --sandbox cloud-project +``` + +Deny rules take precedence when the same destination matches both an allow +rule and a deny rule. + +Cloud rules match network destinations. HTTP method and path restrictions, +`--protocol`, and local governance profiles aren't supported. + +You can also add initial rules while creating a sandbox: + +```console +$ sbx --cloud create --name cloud-project \ + --allow-network api.github.com:443 \ + --deny-network example.com claude +``` + +## Inspect network policy + +Inspect your account policy or a sandbox's configured policy: + +```console +$ sbx --cloud policy ls +$ sbx --cloud policy ls cloud-project +``` + +The sandbox view shows its policy document, or your account default when the +sandbox has no policy document. It does not show the complete combination of +applicable rules. + +To verify enforcement, attempt the connection from the sandbox, then review +the connection decisions: + +```console +$ sbx --cloud exec cloud-project curl -I https://api.github.com +$ sbx --cloud policy log cloud-project +``` + +These records describe cloud network policy decisions. They aren't Docker AI +Governance organization audit logs. + +## Remove network rules + +Remove a rule by its pattern, from whichever allow or deny list contains it: + +```console +$ sbx --cloud policy rm network --resource api.github.com:443 +$ sbx --cloud policy rm network --sandbox cloud-project --resource api.anthropic.com:443 +``` + +Remove the custom account policy and return to the platform default: + +```console +$ sbx --cloud policy reset +``` + +The command asks for confirmation and prints the default stored by the server +after the reset. Use `--force` in scripts. The local daemon is unaffected. +Sandbox-specific policies remain in place and can still grant access. Inspect +those policies separately. diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md new file mode 100644 index 000000000000..99b3ae95bce9 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/usage.md @@ -0,0 +1,419 @@ +--- +title: Use cloud sandboxes +description: Create and manage Docker cloud sandboxes with the sbx CLI, including file transfer, commands, ports, storage, and lifecycle controls. +keywords: docker sandboxes, cloud sandbox, sbx cloud, cloud ports, sandbox ttl +weight: 20 +--- + +Use the `--cloud` flag with supported `sbx` commands to create and manage +sandboxes on Docker-managed infrastructure. Cloud operations use cloud IDs, +names, resources, and lifecycle controls rather than the local sandbox daemon. + +## Create a sandbox + +A cloud sandbox expires after one hour by default. On expiration, the service +stops sandboxes that can be resumed and deletes the rest. See +[Configure expiration](#configure-expiration) to choose the timeout and action +before creating it. + +Credentials saved for local sandboxes aren't available in cloud sandboxes. +[Configure a cloud credential](credentials.md) before launching an agent. + +Create a sandbox and attach to its agent, or reuse the named sandbox if it +already exists: + +```console +$ sbx --cloud run claude --name cloud-project +``` + +Without `--name`, an interactive run offers existing sandboxes for that agent +and an option to create another. Pass `--new` to create a fresh sandbox. +Launches that bake a kit template also create a fresh sandbox. + +Reusing a sandbox keeps its creation settings. Flags such as `--cpus`, +`--memory`, `--platform`, `--ttl`, `--env`, and `--allow-network` are rejected +when resuming. Use `--new` to create a sandbox with different settings. + +To create the sandbox without opening an agent session, use `create`: + +```console +$ sbx --cloud create --name cloud-project claude +``` + +The command prints the cloud sandbox ID. Attach by ID or name: + +```console +$ sbx --cloud attach cloud-project +``` + +Cloud sandbox names must have at least two characters, start with a letter or +number, and contain only letters, numbers, and hyphens. The name `default` is +reserved. Periods accepted in local sandbox names aren't accepted in the cloud. + +Cloud creation doesn't accept workspace paths. For example, +`sbx --cloud run claude .` returns an error because `.` refers to the local +filesystem. + +### Choose resources and platform + +Without resource flags, a cloud sandbox starts with 2 CPUs and 4 GiB of +memory. Use `--cpus` and `--memory` to select one of these configurations: + +| Size | CPUs | Memory | +| --- | --- | --- | +| micro | 1 | 2 GiB | +| small | 2 | 4 GiB | +| medium | 4 | 8 GiB | +| large | 8 | 16 GiB | +| xl | 16 | 32 GiB | + +For example: + +```console +$ sbx --cloud create --name cloud-project --cpus 4 --memory 8g claude +``` + +If you specify only CPU or memory, the CLI selects the matching value for the +other resource. Unsupported combinations are rejected. + +Use `--platform linux/amd64` or `--platform linux/arm64` to select an +architecture supported by your account. This matters when you plan to +[move the sandbox to your machine](move.md): the architectures must match. + +## Run without attaching + +For scripts or terminals without interactive input, start the sandbox without +opening an agent session: + +```console +$ sbx --cloud run --detach claude --name cloud-task +``` + +A detached run with `--name` reuses the named sandbox and starts it if stopped. +If the sandbox doesn't exist, or you omit `--name`, it creates a sandbox. +Use `sbx --cloud exec` to run commands and `sbx --cloud rm --force` for +unattended cleanup. An interactive agent session requires `run` or `attach` +from a terminal. + +To detach from an interactive `run` or `attach` session while leaving the +agent running, press `Ctrl+\`. Reconnect with `sbx --cloud attach <sandbox-name>`. +Reconnecting joins the existing agent session. Use `--detach-keys` with `run` +or `attach` to change the detach gesture, for example `--detach-keys ctrl-x,ctrl-d`. + +## List and inspect sandboxes + +List cloud sandboxes separately from local sandboxes: + +```console +$ sbx --cloud ls +``` + +Most cloud commands accept either the sandbox name or the `sbx_`-prefixed ID +shown in the output. + +## Run commands + +Run a command inside a cloud sandbox: + +```console +$ sbx --cloud exec cloud-project pwd +``` + +## Connect with SSH + +Configure cloud SSH access and connect with your SSH client: + +```console +$ sbx --cloud setup ssh +$ ssh sbx_01abc123@sbx_cloud +``` + +Replace the example with `ssh <sandbox-id>@sbx_cloud`, using the +`sbx_`-prefixed ID from `sbx --cloud ls`. + +Cloud SSH honors your host's configured upstream proxy. If the proxy refuses +SSH connections, see [Cloud SSH proxy configuration](../configuration/upstream-proxy.md#cloud-ssh). + +## Transfer files + +Use `sbx --cloud cp` to copy files or directories between the client machine +and a cloud sandbox. Use absolute sandbox paths: + +```console +$ sbx --cloud cp ./src cloud-project:/home/agent/workspace/src +$ sbx --cloud cp cloud-project:/home/agent/workspace/result.json ./result.json +``` + +Copying creates a point-in-time transfer. It doesn't mount or synchronize the +local path. For source control workflows, you can also clone a remote +repository from inside the sandbox and push changes to the remote. Configure +[cloud credentials](credentials.md) before creating a sandbox that needs access +to a private repository. The [cloud walkthrough](_index.md#get-started) shows a +public repository example. + +## Expose a port + +Expose a TCP service by specifying its sandbox port: + +```console +$ sbx --cloud ports cloud-project --publish 8080 +``` + +The command returns a public HTTPS URL assigned by the cloud control plane. +Cloud mode accepts a sandbox port number with an optional `/tcp` suffix, such +as `8080/tcp`. Host IP addresses, host port bindings, and other protocols are +rejected. + +List or remove exposed ports: + +```console +$ sbx --cloud ports cloud-project +$ sbx --cloud ports cloud-project --unpublish 8080 +``` + +Treat an exposed URL as a public endpoint. Apply authentication in the service +and remove the exposure when you no longer need it. + +## Configure expiration + +Set the time-to-live and the action taken when it lapses during creation: + +```console +$ sbx --cloud create --name cloud-project --ttl 2h --on-timeout delete claude +``` + +The default time-to-live is one hour. If you omit `--on-timeout`, the server +stops sandboxes that can be resumed and deletes the rest. Choose an action +explicitly when you need a particular outcome: + +- `stop` preserves the sandbox so it can be started again. This requires + support for stopping the sandbox. +- `restart` stops and immediately starts the sandbox. If you also specify + `--ttl`, it must be at least one hour. +- `delete` removes the sandbox. + +Volume-backed sandboxes require the `delete` action. Omitting `--ttl` uses +the server default. Setting `--ttl 0` is an error, not a way to disable +expiration. + +Inspect or extend the expiration. Extensions cannot move expiration beyond +24 hours from creation: + +```console +$ sbx --cloud ttl cloud-project +$ sbx --cloud ttl +30m cloud-project +``` + +A stopped sandbox has no running time-to-live, so `sbx --cloud ttl` reports +that it is stopped instead of showing an expiration time. Its time-to-live +starts again when the sandbox resumes. In `--json` output, `stopped` and +`ttl_paused` are `true`, and the expiry fields still hold the previous +deadline. While the sandbox is resuming, only `ttl_paused` is `true`. + +## Stop or remove a sandbox + +Stop a cloud sandbox while preserving its memory and filesystem: + +```console +$ sbx --cloud stop cloud-project +``` + +The command returns when the stop request is accepted. Check `sbx --cloud ls` +to confirm that the sandbox has stopped. Compute isn't billed while it is +stopped. + +To resume the sandbox and connect to its agent: + +```console +$ sbx --cloud attach cloud-project +``` + +You can also use `sbx --cloud run claude --name cloud-project`, or run the agent +without `--name` and select the sandbox when prompted. Add `--detach` to a +named run to resume without attaching. + +Resuming keeps the sandbox ID and state, and starts a new time-to-live +period. Check its expiration with `sbx --cloud ttl cloud-project` after +resuming. + +If stop or resume reports that an existing sandbox was not found, the operation +may be disabled for your account. + +Volume-backed sandboxes can't be stopped. Remove a volume-backed sandbox to end +it and save the volume snapshot. + +Remove a sandbox when you no longer need its state: + +```console +$ sbx --cloud rm cloud-project +``` + +Removal asks for confirmation, deletes the cloud sandbox, and can't be undone. +Use `--force` to skip the prompt in scripts. + +### Remove a sandbox when the agent exits + +Pass `--rm` to an interactive `run` to remove the sandbox when the agent +session ends: + +```console +$ sbx --cloud run --rm claude +``` + +The detach gesture is turned off for that session, and you can't combine +`--rm` with `--detach`. If the session ends without completing, for example +because the connection drops, the sandbox is kept and the CLI prints the +command to remove it. + +## Use persistent volumes + +Cloud volumes are experimental and preserve data independently of a sandbox. +Create a volume, then attach it at sandbox creation: + +```console +$ sbx --cloud volume create dependency-cache +$ sbx --cloud create --name cloud-project \ + --volume dependency-cache:/workspace/cache claude +``` + +The root directory of a newly created volume is owned by `root`. Change its +ownership after attaching it so the agent can write to it: + +```console +$ sbx --cloud exec cloud-project \ + sudo chown agent:agent /workspace/cache +``` + +Volume data is saved as a snapshot when a sandbox exits, not continuously. If +multiple sandboxes mount the same volume at the same time, the last sandbox to +exit overwrites the stored snapshot. + +## Customize a cloud sandbox + +### Save and reuse a template + +Save a running cloud sandbox as a template to reuse its configured filesystem. +Before saving, remove credentials written to the sandbox filesystem: snapshots +include those files. Managed cloud secrets stay in the secret store. See +[Authenticate cloud agents](credentials.md). + +```console +$ sbx --cloud template save cloud-project cloud-template +$ sbx --cloud create --name cloud-copy --template cloud-template +``` + +By default, saving a template captures disk state, and sandboxes created from +it cold-boot from that filesystem. To resume from the running sandbox's state +instead, add `--capture-mode all` to `template save`. This captures memory, +disk, and the microVM checkpoint, and takes longer to load. + +The template supplies its CPU and memory configuration. Do not combine +`--template` with an agent name, `--cpus`, or `--memory`. To launch an OCI image +directly instead, use `--image-ref` with explicit CPU and memory values. + +### Import a local template + +Cloud templates have a separate store. To use a local template in the cloud, +upload its tar file with a name that is unique in your account: + +```console +$ sbx --cloud template load my-template.tar cloud-template \ + --cpus 2 --memory-mib 4096 +``` + +Both resource flags are required and must match a +[cloud size](#choose-resources-and-platform). Like `template save`, +`template load` uses disk capture by default and accepts `--capture-mode all` to capture +memory and checkpoint state as well. Uploading or saving large templates can +take several minutes. + +### Customize with kits + +Cloud sandboxes also support sandbox kits and `--kit` mixins. See +[Kits](../customize/_index.md) for customization and +[Local and cloud differences](local-vs-cloud.md) for host-dependent features. +Configure [cloud credentials](credentials.md) before adapting a local kit. + +Use `--kit-arg` or `--kit-args-file` with `sbx --cloud create` to pass +arguments to kits supplied with `--kit`. +For example, configure a v2 mixin that declares a `version` argument: + +```console +$ sbx --cloud create --name cloud-tools claude \ + --kit docker.io/<NAMESPACE>/company-cli:1.0.0 \ + --kit-arg company-cli.version=1.2 +``` + +Replace the kit reference and argument with those from your kit's +documentation. The `company-cli` prefix targets the kit by its repository +name. Built-in agents such as `claude` require v2 mixins. + +To load arguments from a file, pass `--kit-args-file <FILE>` with one +`name=value` entry per line, such as `company-cli.version=1.2`. Values passed +with `--kit-arg` override values from the file. + +To declare reusable cloud configuration in a file, see +[Use environment files in the cloud](environment-files.md). + +## Load an MCP server + +[Connect an MCP server in Docker Agentic Platform](/manuals/agentic-platform/mcp.md) +before loading it into a cloud sandbox. Use the same Docker account you use +with `sbx`. + +Load the connected server into a running cloud sandbox, using its name from +the console: + +```console +$ sbx --cloud mcp load <server-name> --sandbox cloud-project +``` + +The server name is resolved by the MCP gateway associated with your Docker +Agentic Platform account. Cloud sandboxes don't use servers registered in the +local MCP store with `sbx mcp add`. + +List servers reported by existing cloud sandbox gateways, or inspect one +sandbox's gateway: + +```console +$ sbx --cloud mcp ls +$ sbx --cloud mcp ls cloud-project +``` + +The account listing shows servers reported by gateways, with the sandboxes +that use them. It omits unused server configurations and servers skipped by +a gateway. The sandbox view includes skipped servers. + +## Diagnose cloud access + +Check the CLI, Docker sign-in, cloud API connectivity, and account access: + +```console +$ sbx --cloud diagnose +``` + +These checks don't require a local sandbox daemon. For local diagnostics, +see [Troubleshooting](../troubleshooting.md). + +## Known limitations + +### Docker exec and healthchecks + +When running Docker inside a cloud sandbox, `docker exec` can access the +sandbox VM filesystem instead of the target container's filesystem. This also +affects `docker compose exec` and Docker healthchecks, which use the same +execution path. + +Commands can fail because application files, binaries, or mounted data aren't +found. They can also succeed while reading or writing the wrong files. A +successful exit status doesn't confirm that the command used the target +container's filesystem. + +Healthchecks can report incorrect results. Compose services that depend on +`condition: service_healthy` can remain blocked even when the service they +need is running. + +A container's main process, started by `docker run`, uses the correct +filesystem. Where your workflow supports it, run setup or readiness checks +as a container's main command. This avoids the affected exec path for that +command but doesn't restore exec behavior or ongoing health monitoring. diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md new file mode 100644 index 000000000000..10263715d76b --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/_index.md @@ -0,0 +1,27 @@ +--- +title: Configure Docker Sandboxes +linkTitle: Configuration +weight: 60 +description: Configure Docker Sandboxes settings, credentials, models, project environments, GPU passthrough, registry mirrors, and upstream proxies. +keywords: docker sandboxes, sbx, configuration, settings, credentials, models, environment files, gpu passthrough, registry mirror, upstream proxy +--- + +Configure credentials and how Docker Sandboxes run for a project, host, or +network environment. These settings control sandbox creation, authentication, +and connectivity. To change the tools and agent configuration inside a +sandbox, see [Customize](../customize/). + +- [Settings](settings.md) lists host-level settings, environment variable + equivalents, and commands to inspect and change values. +- [Credentials](credentials.md) configures API keys, authentication + credentials, and registry access for sandboxed agents. +- [Models](models.md) selects local models, hosted providers, or custom + inference endpoints for sandboxed agents. +- [Environment files](environment-files.md) declare reusable project + configuration in `sbxenv.yaml` for local or cloud sandboxes. +- [GPU passthrough](gpu-passthrough.md) configures a Linux host and sandbox for + NVIDIA GPU workloads. +- [Registry mirror](registry-mirror.md) routes Docker Hub template, kit, and + in-sandbox Docker image pulls through an organization's registry mirror. +- [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through + an operating system or corporate proxy. diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md new file mode 100644 index 000000000000..c351fc2a65b5 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -0,0 +1,760 @@ +--- +title: Manage credentials +linkTitle: Credentials +weight: 10 +description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents. +keywords: docker sandboxes, credentials, api keys, authentication, proxy, ssh agent, secrets +aliases: + - /ai/sandboxes/security/credentials/ +--- + +These credential stores and authentication flows apply to local sandboxes. +Cloud credentials require separate setup: see +[Authenticate cloud agents](../cloud/credentials.md). + +Most agents need an API key for their model provider. An HTTP/HTTPS proxy on +your host intercepts outbound requests from the sandbox, looks up the matching +credential on the host, and overwrites the auth header before forwarding. The +real credential stays on the host when proxy management is active; the sandbox +sees only a sentinel value. See +[Trust boundaries](../security/_index.md#trust-boundaries) for how credential isolation +fits into the broader sandbox security model. + +## How credential injection works + +When a sandbox makes an outbound request, the host-side proxy decides three +things: whether the request **matches** a service the kit (or built-in agent) +declares, what **header** to write, and what **value** to inject. The kit +declares the match and the header; you provide the value on the host. For +proxy-managed credentials, the real value never enters the sandbox — the agent +sees only a sentinel like `proxy-managed`. + +A kit can set OAuth `passthrough: true` to opt out of sentinel masking. This +sends the real token response into the sandbox and reduces credential isolation. +See the [`oauth` kit fields](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/credential@1.md). + +There are several ways to provide that value. When more than one source has a +value for the same service, the stored secret takes precedence. + +| Form | What it is | Use it when | +| --------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| [Stored secrets](#stored-secrets) (`sbx secret set`) | A value or dynamic source in your OS keychain, keyed by service | The default for any built-in or kit-declared service | +| [Custom secrets](#custom-secrets) (`sbx secret set-custom`) | A value keyed to a domain and environment variable | The service model doesn't fit, or the agent validates the variable's format | +| OAuth | A host-side sign-in flow; the token never enters the sandbox | The agent supports it, such as Claude Code, Codex, Cursor, or Droid | +| [Registry credentials](#registry-credentials) (`sbx secret set --registry`) | Authentication for pulling images and kits | Pulling templates or kits from a private registry | + +Providing a value and approving its use are separate steps. +[Credential bindings](#credential-bindings) record which mechanisms and domains +you authorize a kit to use. They don't store the credential value. + +For multi-provider agents (OpenCode, Docker Agent), the proxy selects +credentials based on the API endpoint being called. See individual +[agent pages](../agents/) for provider-specific details. + +## Stored secrets + +`sbx secret set` stores credential values or dynamic secret sources in your OS +keychain, keyed on a service identifier. Built-in agents declare a fixed set of +services. Custom kits can declare their own. The same `sbx secret set` flow +works for both. + +Secrets whose names start with `mcp:` are reserved for the host's +[MCP gateway](../mcp-gateway.md). See [MCP secrets](#mcp-secrets) for how +these differ from agent and provider credentials. + +### Where secrets are stored + +The store backing `sbx secret set` depends on your operating system: + +- macOS: the system Keychain. +- Windows: the Windows Credential Manager. +- Linux: the Secret Service exposed by your desktop keyring, such as GNOME + Keyring or KDE Wallet. + +The Ubuntu package depends on GNOME Keyring, so a standard desktop install +needs no extra setup. + +On Linux hosts without a running Secret Service — headless servers and some WSL +setups — `sbx` falls back to a file under your user config directory +`$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to +`~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. The fallback +is automatic and needs no configuration. When you store a secret this way, +`sbx` prints a notice: + +```text +No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password +``` + +`sbx` stores the file in a directory with `0700` permissions, the same +file-permission model used for `~/.docker/config.json`. Any user or process that +can read the file can retrieve the stored credentials, so treat the directory as +sensitive. Where available, prefer a keychain, which mediates access per +application. + +If you start a Secret Service on the host later, `sbx` stores new secrets in the +keychain again. For more on running sandboxes without a desktop keyring, see +[Can I use Docker Sandboxes on headless Linux?](../faq.md#can-i-use-docker-sandboxes-on-headless-linux) + +### Store a secret + +```console +$ sbx secret set anthropic +``` + +This prompts you for the secret value interactively. Service secrets are +global by default, so the secret is available to all sandboxes. To scope a +secret to a specific sandbox instead: + +```console +$ sbx secret set openai --sandbox my-sandbox +``` + +Adding, updating, or removing a service secret takes effect in existing local +sandboxes without a restart, including secrets configured with `--command` or +`--ref`. Sandbox-scoped secrets take precedence over global secrets. + +### MCP secrets + +The MCP gateway uses the same host credential store for OAuth client secrets +and custom request header secrets. These records have names starting with +`mcp:` and appear in `sbx secret ls`. They stay on the host and aren't injected +into sandboxes. The gateway uses them to authenticate connections to MCP +servers on behalf of sandboxed agents. + +For setup instructions, see +[OAuth client secrets](../mcp-gateway.md#use-a-pre-registered-oauth-client) and +[custom request headers](../mcp-gateway.md#custom-request-headers). Header +secrets use the global scope and have their own +[restart requirements](../mcp-gateway.md#manage-header-secrets). + +### Use a dynamic secret source + +Dynamic secret sources let `sbx` retrieve a credential from an authenticated +host tool when the proxy needs it. The secret store contains the reference or +command instead of the credential value. Resolution and caching happen on the +host, and the sandbox still receives only the proxy-managed placeholder. + +Use `--ref` with a 1Password secret reference or an AWS Secrets Manager ARN: + +```console +$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential' +$ sbx secret set openai \ + --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:openai-api-key' +``` + +The corresponding `op` or `aws` CLI must be installed and authenticated on the +host. + +> [!NOTE] +> To resolve a reference with a specific 1Password account or AWS profile, set +> `OP_ACCOUNT` or `AWS_PROFILE` when you run `sbx secret set`. `sbx` uses that +> account or profile whenever it resolves the secret. If neither variable is +> set, the provider CLI uses its default. + +Use `--command` for another host tool that prints a secret to standard output: + +```console +$ sbx secret set github --command 'gh auth token' +``` + +`sbx` runs the command through the host shell and trims its output. The command +text is stored and replayed by the daemon. Don't embed a secret directly in the +command because the text can appear in shell history and process listings. + +Secret commands run from a fresh temporary directory on the host during +verification and refresh. Relative paths such as `./credential-helper` resolve +from that temporary directory. This applies to both +`sbx secret set --command` and `sbx secret set-custom --command`. + +Store helpers and any code or configuration they load outside writable +sandbox mounts. Run a helper by name from an absolute directory on the host's +`PATH`, use its absolute path, or explicitly change to its private directory +in the command. Keep the host's temporary directory outside writable sandbox +mounts as well. + +By default, `sbx` verifies the source when you register it and reports an error +without exposing the resolver's standard error. Use `--no-verify` to store a +source that can't be resolved during registration. To troubleshoot an initial +verification failure, use `--show-error`. Provider error output can contain +sensitive information. You can't combine `--show-error` with `--no-verify`. + +Resolved service secrets are cached for 55 minutes by default. To change the +cache duration, use `--refresh <duration>`. To resolve the source for every +credential use instead of caching it, pass `--refresh on-demand`: + +```console +$ sbx secret set anthropic \ + --ref 'op://Work/Anthropic/credential' \ + --refresh 30m +$ sbx secret set github --command 'gh auth token' --refresh on-demand +``` + +`--ref` and `--command` are mutually exclusive. They can't be combined with +`--token`, `--oauth`, or `--registry`. + +### Import from environment variables + +If you already have API keys set in your shell, `sbx secret import` reads them +and stores them in the keychain without typing each value manually: + +```console +$ sbx secret import +``` + +This scans your current session for the environment variables in the +[built-in services table](#built-in-services) below and prompts you to confirm +each one before writing. To import a single service: + +```console +$ sbx secret import openai +``` + +Pass `--all` to import everything without prompting (new entries only; existing +entries are left unchanged), or `--force` to overwrite existing entries: + +```console +$ sbx secret import --all +$ sbx secret import openai --force +``` + +Pass `--dry-run` to preview what would be imported without writing anything. +Run `sbx secret ls` afterwards to confirm what's stored. For setting up +credentials in CI, see [CI and headless use](../workflows/automation.md). + +### Built-in services + +Each built-in service name maps to the environment variables `sbx secret import` +reads and the API domains the proxy injects credentials into: + +| Service | Environment variables | API domains | +| ------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `anthropic` | `ANTHROPIC_API_KEY` | `api.anthropic.com`, `console.anthropic.com`, `claude.ai`, `mcp-proxy.anthropic.com` | +| `cursor` | `CURSOR_API_KEY` | `api2.cursor.sh`, `api3.cursor.sh`, `repo42.cursor.sh`, `cursor.com` | +| `droid` | `FACTORY_API_KEY` | `api.factory.ai`, `app.factory.ai`, `relay.factory.ai` | +| `github` | `GH_TOKEN`, `GITHUB_TOKEN` | `api.github.com`, `github.com`, `raw.githubusercontent.com`, `gist.github.com`, `copilot.github.com`, `api.githubcopilot.com` | +| `google` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `generativelanguage.googleapis.com`, `oauth2.googleapis.com`, `aiplatform.googleapis.com`, `vertexai.googleapis.com` | +| `groq` | `GROQ_API_KEY` | `api.groq.com` | +| `mistral` | `MISTRAL_API_KEY` | `api.mistral.ai` | +| `nebius` | `NEBIUS_API_KEY` | `api.studio.nebius.com`, `api.tokenfactory.nebius.com` | +| `openai` | `OPENAI_API_KEY` | `api.openai.com`, `openai.com`, `chatgpt.com`, `www.chatgpt.com` | +| `openrouter` | `OPENROUTER_API_KEY` | `openrouter.ai` | +| `xai` | `XAI_API_KEY` | `api.x.ai` | + +When you store a secret with `sbx secret set <service>`, the proxy injects +it into requests to the listed API domains. + +### Services declared by kits + +Use the service identifier from the kit's documentation when storing its +credential. For a kit that declares `my-service`, run: + +```console +$ sbx secret set my-service +``` + +There's no separate registration step. The stored value and the kit's request +use the same identifier. Approve the kit's credential request when prompted. +See [Credential bindings](#credential-bindings). + +When authoring a kit, declare how it uses that service. V3 uses a credential +capability, and v2 uses a top-level `credentials` list. Both examples declare the +service and permit access to its API host: + +{{< tabs >}} +{{< tab name="v3" >}} + +```yaml +capabilities: + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: [api.my-service.com] + - type: com.docker.sandbox/credential@1 + config: + service: my-service + phase: runtime + apiKey: + name: MY_SERVICE_TOKEN + proxyManaged: true + inject: + - domain: api.my-service.com + header: Authorization + format: "Bearer %s" +``` + +For API keys, specify both the HTTP header and its value format, as in this +example. `sbx` doesn't use `apiKey.inject[].scheme` in v3 kits. + +For OAuth, use JSON credential files and a provider that returns the refresh +token in `refresh_token`. `sbx` doesn't support TOML credential files or a +different refresh-token field. + +Credentials declared for the install phase are available during install hooks. +Add the domains that receive these credentials to the network policy's +`install.allow` list. An entry in `runtime.allow` alone doesn't grant access +during installation. If a hook reads a credential environment variable, +include that name in its `env` list. + +In `sbx`, the proxy stops injecting credentials into install-only domains +before the agent launches. A domain remains available for credential injection +if any runtime credential targets it, even under a different service name. +If you declare the same service for both phases, `sbx` uses the runtime +declaration's credential settings in both phases. + +{{< /tab >}} +{{< tab name="v2" >}} + +```yaml +credentials: + - service: my-service + apiKey: + name: MY_SERVICE_TOKEN + proxyManaged: true + inject: + - domain: api.my-service.com + scheme: bearer + +permissions: + network: + allow: [api.my-service.com] +``` + +{{< /tab >}} +{{< /tabs >}} + +Each service declares `apiKey`, `oauth`, or both. When both resolve at runtime, +the API key takes precedence and OAuth acts as the fallback. For complete +kit-side configuration, see +[V3 credential definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/credential@1.md) +or [V2 credentials](../customize/kits-v2.md#credentials). + +### List and remove secrets + +List all stored secrets: + +```console +$ sbx secret ls +SCOPE SERVICE SECRET +(global) github gho_GCaw4o****...****43qy +``` + +Remove a secret: + +```console +$ sbx secret rm github +``` + +To remove a sandbox-scoped secret, pass `--sandbox`: + +```console +$ sbx secret rm github --sandbox my-sandbox +``` + +Removing a sandbox-scoped secret restores the global secret for that service, +if one is available. + +> [!NOTE] +> Running `sbx reset` deletes all stored secrets along with all sandbox state. +> You'll need to re-add your secrets after a reset. + +### GitHub token + +The `github` service gives the agent access to the `gh` CLI inside the +sandbox. Resolve your existing GitHub CLI token on the host: + +```console +$ sbx secret set github --command 'gh auth token' +``` + +The daemon refreshes the token from the host command after the default cache +period. This is useful for agents that create pull requests, open issues, or +interact with GitHub APIs on your behalf. + +### SSH agent + +SSH agent forwarding is enabled by default. V3 kits must also request +[`ssh-agent@1`](/manuals/ai/sandboxes/customize/author/capabilities.md#support-by-capability) +for the phase where they need it. Without that request, no agent socket is +forwarded to a v3 sandbox. + +When `SSH_AUTH_SOCK` is set, +Docker Sandboxes uses the value from the client that creates, starts, or joins +each sandbox. It forwards that agent into the sandbox and sets `SSH_AUTH_SOCK` +there. + +If your agent exposes a stable socket path, such as the 1Password SSH agent, +configure that path for every sandbox: + +```console +$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK" +``` + +An empty [`ssh.agentSocketPath`](settings.md#sshagentsocketpath), which is the +default, uses the agent supplied by each client instead. Use +[`ssh.agentForwardingEnabled`](settings.md#sshagentforwardingenabled) to turn +forwarding on or off. + +After changing forwarding or the socket selection, restart the daemon so +existing sandboxes use the new configuration: + +```console +$ sbx daemon restart +``` + +The private keys stay on your host. Processes inside the sandbox can request +signatures from the forwarded agent, but they can't read or copy a private key. + +Use SSH agent forwarding for Git operations over SSH and SSH-based commit +signing. The signing key must be loaded in the host SSH agent for sandboxed +commit signing to work. Outbound SSH connections are still subject to sandbox +network policy. For details, see +[Commit signing](../workflows/git.md#commit-signing). + +## Custom secrets + +> [!IMPORTANT] +> Custom secrets are experimental. Behavior, flags, and the placeholder format may +> change without notice. + +For credentials that don't fit the service-identifier model — for example, +when an agent validates the environment variable format at boot — use +`sbx secret set-custom`. The secret is keyed on one or more target domains, an +environment variable name, and an optional placeholder string, instead of a +service identifier. + +Prefer the [service-based flow](#stored-secrets) whenever it's an option — +the kit handles the wiring; you only provide the value. + +### Set a custom secret + +Custom secrets are global by default. Pass `--sandbox` to scope one to a +specific sandbox. + +```console +$ sbx secret set-custom \ + --host api.example.com \ + --env API_KEY \ + --value <secret> +``` + +> [!WARNING] +> Passing the secret as `--value <secret>` records it in your shell history +> and exposes it to other processes running as your user. Avoid pasting +> real credentials inline — read the value from a variable that's already +> in your environment, and clear shell history if a real secret was passed +> on the command line. + +Inside the sandbox, `API_KEY` is set to a generated placeholder (for example, +`sbx-cs-<rand>`). When a sandboxed process sends a request to any of the +configured hosts and the placeholder appears in an HTTP request header, the +proxy replaces it with the real value. Replacement applies only to HTTP request +headers, not request bodies. The agent never sees the real secret. + +### Target multiple hosts + +Repeat `--host` to cover multiple domains with the same secret — useful when +an API is split across related hostnames or when two unrelated endpoints share +a credential: + +```console +$ sbx secret set-custom \ + --host api.example.com \ + --host uploads.example.com \ + --env API_KEY \ + --value <secret> +``` + +A `--host` value can also use wildcards, with the same syntax as +[network rules](../governance/concepts.md#network-rules): `*` matches a +single label (`*.example.com` covers `api.example.com`) and `**` matches any +number (`**.example.com` covers `api.example.com` and `v2.api.example.com`). + +### Resolve custom secrets dynamically + +Custom secrets also accept [dynamic secret sources](#use-a-dynamic-secret-source). +Replace `--value` with either `--ref` or `--command`: + +```console +$ sbx secret set-custom \ + --host api.example.com \ + --env API_KEY \ + --ref 'op://Work/Example/credential' +``` + +Dynamic custom secrets resolve on demand by default. Pass `--refresh` with a +duration to cache the resolved value. The verification and error-output flags +work the same as they do for service secrets. `--ref` and `--command` can't be +combined with `--value` or `--token`. + +### Install npm packages from GitHub Packages + +The built-in `github` service doesn't inject credentials into requests to +`npm.pkg.github.com`. To install private npm packages from GitHub Packages, +add a custom secret for that host. + +On the host, authenticate the GitHub CLI with a token that can read the package. +GitHub documents a personal access token (classic) with at least `read:packages` +scope for this use. See +[Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages). +Then register the token source, replacing `my-sandbox` with your sandbox's name: + +```console +$ sbx secret set-custom \ + --sandbox my-sandbox \ + --host npm.pkg.github.com \ + --env NODE_AUTH_TOKEN \ + --command 'gh auth token' +``` + +The command prints a generated placeholder. For an existing sandbox, set +`NODE_AUTH_TOKEN` to that placeholder using `sbx run -e` for an agent session, +or `/etc/sandbox-persistent.sh` for future sessions. See +[Set environment variables](../usage.md#set-environment-variables). +Use the placeholder, not the actual GitHub token. + +Inside the sandbox, add the following entries to your project's `.npmrc`, +replacing `@my-org` with the package's scope. Keep `${NODE_AUTH_TOKEN}` literal +so npm reads the environment variable: + +```ini +@my-org:registry=https://npm.pkg.github.com +//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN} +``` + +Install the package inside the sandbox: + +```console +$ npm install @my-org/my-package +``` + +Replace `@my-org/my-package` with your package name. npm sends the placeholder +to `npm.pkg.github.com`, and the proxy replaces it with the token retrieved by +`gh auth token` on the host. + +## Credential bindings + +A credential bindings file records which credential mechanisms and domains +you've approved for each service. It lives at +`~/.config/sbx/credentials.yaml`, or `%APPDATA%\sbx\credentials.yaml` on +Windows. + +Third-party kits require an approved binding for each credential they use, +regardless of schema version. `sbx` creates one interactively the first time you +run such a kit (see [First-run approval](#first-run-approval)); you can also +write entries by hand. Credentials requested only by the built-in kits shipped +with `sbx` don't need a binding. + +Each entry under `bindings` is keyed by a +[service identifier](#built-in-services) and approves one or both credential +mechanisms: + +- `apiKey` — approves injecting the service's stored API key. The value comes + from the [secret store](#stored-secrets) (`sbx secret set <service>`); the + binding records approval, it doesn't hold or locate the value. +- `oauth` — approves the OAuth flow for the service. You sign in on the host, + and the proxy handles token refresh and routing. OAuth domains include the + token endpoint host and any resource hosts declared by the kit. + +Each mechanism takes a `domains` list that records the domains you approved. +`sbx` asks for approval when a kit requests domains that the existing binding +doesn't cover. + +```yaml +bindings: + anthropic: + apiKey: + domains: [api.anthropic.com] + github: + apiKey: + domains: [api.github.com, github.com] +``` + +A binding is only an approval record: the presence of `apiKey` or `oauth` +authorizes that mechanism. Declining a credential writes no entry at all. +The real credential isn't stored in this file. + +### First-run approval + +When a third-party kit needs a credential that has no binding, `sbx` walks you +through approving one. For an API key, you can use a value already in the secret +store or enter one at the prompt. For OAuth, you approve the sign-in flow. In +both cases, you approve the domains declared by the kit. `sbx` writes the entry +to `credentials.yaml`. + +In non-interactive contexts (CI or `--detach`), there's no one to answer the +prompt. In `sbx`, the sandbox starts with the credential withheld when no +binding exists. For a required credential, `sbx` prints a warning rather than +failing sandbox creation. This is a limitation of `sbx` enforcement: kit authors +shouldn't rely on a required credential being available merely because the +sandbox started. + +Pre-create the binding by running the kit interactively once or by writing +`credentials.yaml` directly before running unattended. + +The bindings file gates whether a third-party kit can use a service +credential. The kit's credential injection rules and network permissions still +constrain which requests can carry the credential. + +### Kits that require a binding + +Third-party kits require your approval to use credentials, regardless of +schema version. The built-in kits shipped with `sbx` can use credentials they +request without a binding. If a third-party v2 kit extends a built-in agent, +you must approve its use of the inherited credentials. You must also approve +a third-party kit that requests the same service itself. + +## Registry credentials + +Registry credentials authenticate to private OCI registries when pulling +[templates](../usage.md#load-a-template) or [kits](/manuals/ai/sandboxes/customize/_index.md), and can +also let the agent pull and push images from inside the sandbox through the +host-side proxy. Use `sbx secret set --registry <host>` to store them. For +Docker Hub, `sbx` reuses your `sbx login` session — no registry secret needed. +For other registries (GitHub Container Registry, ECR, ACR, self-hosted Nexus, +and so on), store credentials with `sbx secret set --registry`. + +Choose the scope by adding `--all-sandboxes`, adding `--sandbox SANDBOX`, or +passing neither: + +```text +sbx secret set [--all-sandboxes | --sandbox SANDBOX] --registry HOST +``` + +- **Host-only** (no scope flag): the `sbx` CLI uses it to pull templates + and kits when creating a sandbox. The credential stays on the host and is + never available inside the sandbox. +- **All sandboxes** (`--all-sandboxes`): same as host-only, plus the proxy + authenticates registry login requests from sandboxes. The credential stays + on the host and is never written to the sandbox filesystem. Use it when + agents build and publish container images. +- **Sandbox-scoped** (`--sandbox SANDBOX`): same proxy behavior as + `--all-sandboxes`, but only for the named sandbox. Use it when only one + sandbox needs registry access. + +### Store registry credentials + +Pipe a token from stdin and target the registry hostname: + +```console +$ gh auth token | sbx secret set --registry ghcr.io --password-stdin +``` + +For registries that require a username (for example, ACR with an admin +account), add `--username`: + +```console +$ echo "$ACR_PASSWORD" | sbx secret set \ + --registry myregistry.azurecr.io \ + --username myuser \ + --password-stdin +``` + +Add `--all-sandboxes` to make the credential available to every new sandbox: + +```console +$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin +$ sbx run claude +``` + +Store all-sandboxes registry credentials before creating a sandbox. Existing +sandboxes don't pick up all-sandboxes registry credentials added later. To add +registry access to an existing sandbox, use a sandbox-scoped credential instead. + +To scope the credential to a single sandbox, store it under that sandbox's name: + +```console +$ gh auth token | sbx secret set --sandbox my-app --registry ghcr.io --password-stdin +``` + +For v2 kits on Docker Hub, `sbx kit pull` and `sbx kit push` use the session from +`sbx login`. For other registries, both commands use these credentials. Both +commands fall back to the Docker credential store, so credentials from +`docker login` also work. V3 kits are +[published with Docker Buildx](/manuals/ai/sandboxes/customize/author/distribute.md#publish-an-image), +which uses the credentials from `docker login`. + +### Trust a private registry authentication endpoint + +Use `--registry-auth-endpoint` with `--registry` when a self-hosted registry +authenticates sandbox requests through a separate host. For example, a +self-hosted GitLab registry at +`registry.example.com` might advertise `https://gitlab.example.com/jwt/auth` +as the `realm` in its Registry v2 `WWW-Authenticate: Bearer` challenge. + +Store the credential and trust that endpoint for a specific sandbox: + +```console +$ echo "$GITLAB_PAT" | sbx secret set --sandbox my-app \ + --registry registry.example.com \ + --username "$GITLAB_USER" \ + --registry-auth-endpoint https://gitlab.example.com/jwt/auth \ + --password-stdin +``` + +Replace the example hosts with your registry and authentication hosts, and set +`GITLAB_USER` and `GITLAB_PAT` to your GitLab username and personal access token. + +This authorizes the proxy to send the stored registry credential to +`https://gitlab.example.com/jwt/auth` to exchange it for a registry token. The +advertised realm must use HTTPS and match the configured host and path exactly. +Other paths on that host, including `/jwt/auth/`, aren't covered. The endpoint +URL must contain no embedded credentials, query string, or fragment. Token +requests can still include protocol parameters such as `service` and `scope`. + +Without this flag, the proxy accepts authentication endpoints on the registry's +own host and built-in registry relationships, such as Docker Hub's authentication +host. Other authentication hosts require explicit configuration. + +### Remove registry credentials + +Remove both the host-only and all-sandboxes entries for a registry: + +```console +$ sbx secret rm --registry ghcr.io -f +``` + +To remove only the all-sandboxes entry and leave the host-only credential in +place, pass `--all-sandboxes`: + +```console +$ sbx secret rm --all-sandboxes --registry ghcr.io -f +``` + +To remove a sandbox-scoped credential, pass the sandbox name: + +```console +$ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f +``` + +## Best practices + +- Use [stored secrets](#stored-secrets) to provide credentials. The OS keychain + protects them at rest; on Linux hosts without a keychain they are held in a + permission-protected file instead. See + [Where secrets are stored](#where-secrets-are-stored). +- Don't set API keys manually inside the sandbox. Sandbox agents are + pre-configured to use proxy-managed credentials. +- Registry credentials stay on the host and are injected by the proxy when a + sandbox authenticates to the registry. Reserve them for sandboxes that need + registry access, and prefer sandbox scope over `--all-sandboxes` to limit + exposure. +- Several agents support OAuth as another secure option: the flow runs on the + host, so the token is never exposed inside the sandbox. If you haven't stored + a credential, the agent prompts you to authenticate — Codex prompts on the + host from `sbx run codex`, while Claude Code, Cursor, and Droid prompt + interactively inside the sandbox. To authenticate ahead of time, run + `sbx secret set openai --oauth` for Codex or use `/login` inside Claude + Code; Cursor and Droid have no ahead-of-time option, so their sign-in prompt + appears when the agent starts. See the individual [agent pages](../agents/) + for each agent's flow. +- If you store credentials in 1Password or AWS Secrets Manager, see + [Sourcing credentials from 1Password](../workflows/authentication.md#source-credentials-from-1password) + and [Sourcing credentials from AWS Secrets Manager](../workflows/authentication.md#source-credentials-from-aws-secrets-manager). + +## Custom templates and placeholder values + +When building custom templates or installing agents manually in a shell +sandbox, some agents require environment variables like `OPENAI_API_KEY` to be +set before they start. Set these to placeholder values (e.g. `proxy-managed`) +if needed. The proxy injects actual credentials regardless of the environment +variable value. diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md new file mode 100644 index 000000000000..c15a6022acf8 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -0,0 +1,834 @@ +--- +title: Sandbox environment files +linkTitle: Environment files +weight: 20 +description: Use a declarative sbxenv.yaml file to describe and share your sandbox configuration. +keywords: + - docker sandboxes + - sbx env + - sbxenv + - environment file + - sandbox configuration + - declarative +aliases: + - /ai/sandboxes/sandbox-environments/ +params: + sidebar: + badge: + color: violet + text: Experimental +--- + +A sandbox environment file captures the setup for a local or cloud sandbox in a +`sbxenv.yaml` file. Share the file with project contributors so they use the +same agent, tools, resources, and credentials without reproducing CLI flags and +setup steps. + +Kits package software and declare what it needs to run. An environment file +selects those kits and configures the sandbox that uses them, including its +workspace, resources, credentials, and lifecycle commands. You can change or +share that configuration without repackaging the tools. See +[Kits](/manuals/ai/sandboxes/customize/_index.md) for how kits supply agents, +tools, and their runtime requirements. + +> [!NOTE] +> `sbx env` is experimental. The command interface and file format may change. + +The examples on this page use local sandboxes unless stated otherwise. For +cloud configuration and lifecycle differences, see +[Use a cloud environment](#use-a-cloud-environment). + +## Start an environment + +Keep the environment file outside the directories you mount into the sandbox. +That includes the primary workspace and every `additionalWorkspaces` mount. +For example, place it beside your project: + +```text +web-app-env/ +├── sbxenv.yaml +└── web-app/ +``` + +Create `web-app-env/sbxenv.yaml`. This example gives the agent a shared +environment variable and the Playwright browser-testing tools. It also +publishes the application's development port: + +```yaml +schemaVersion: "1" +name: web-app +agent: claude +workspace: ./web-app + +kits: + - docker.io/sbx/playwright-kit:latest + +env: + NODE_ENV: test + +ports: + - sandbox: 3000 + host: 3000 +``` + +> [!NOTE] +> This example uses kits v2, the format used by built-in agents. For v3, see +> [Add v3 kits](#add-v3-kits). + +From `web-app-env`, run the environment: + +```console +$ sbx env run +``` + +`sbx` shows an environment plan and asks you to approve it. If you approve the +plan, the `web-app` directory becomes the workspace, while `sbxenv.yaml` remains +outside the sandbox. If the environment doesn't exist, `sbx` creates a sandbox +named `web-app`, installs Playwright and Chromium, and publishes sandbox port +`3000` on the host. It then attaches to the agent. Later runs attach to the +existing sandbox. + + + +### Protect the environment file + +Environment files can declare lifecycle and secret commands that run on your +host. Keep them outside writable sandbox mounts so the agent cannot change +what a later invocation runs. This applies to both the primary workspace and +`additionalWorkspaces`. + +If you need to keep an environment file in a direct-mounted workspace, place +it directly in the workspace root. `sbx` mounts the file read-only by default, +but a file in a subdirectory can still be replaced by renaming its parent +directory. + +For a local environment where you intend the agent to edit the file, set +`sandboxOptions.writableEnvFiles: true`. The plan reports that the file is +writable. Use this option only when you trust the agent to change commands +that future invocations run on your host. + +## Commands + +| Command | Description | +| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| `sbx env plan [PATH...]` | Shows what applying the environment would change without changing or approving it | +| [`sbx env run`](/reference/cli/sbx/env/run/) `[PATH...]` | Applies the approved plan, creates the environment if needed, and attaches | +| [`sbx env create`](/reference/cli/sbx/env/create/) `[PATH...]` | Applies the approved plan and creates the environment without attaching | +| [`sbx env exec`](/reference/cli/sbx/env/exec/) `[PATH...] -- COMMAND [ARG...]` | Runs a command in an existing environment without running lifecycle commands | +| [`sbx env rm`](/reference/cli/sbx/env/rm/) `[PATH...]` | Shows a destroy plan, then removes the sandbox and resources named in the plan | + +To use an environment file, pass its path to `sbx env`. If you pass a +directory, `sbx` looks for `sbxenv.yaml` inside it. If you don't pass a path, +`sbx` looks in the directory you run the command from and loads your +[user defaults](#set-user-defaults), if present. + +Every `sbx env` subcommand accepts `--name`. This flag sets the sandbox name +for that command, overriding the `name` field in the file or the automatically +generated name: + +```console +$ sbx env create --name web-app-test +$ sbx env exec --name web-app-test -- npm test +$ sbx env rm --name web-app-test +``` + +Use the same file paths for each command. If you set `--name`, use that same +name for every command that manages the sandbox. + +### Set user defaults + +Create `~/.sbxenv.yaml` to share settings across your projects. For example, +this file selects Claude as the agent and mounts the directory you run +`sbx env` from: + +```yaml +schemaVersion: "1" +agent: claude +workspace: ${{ env.projectDir }} +``` + +With this file saved in your home directory, run: + +```console +$ cd /projects/web-app +$ sbx env run +``` + +The sandbox mounts `/projects/web-app` as its workspace. Run the same command +from `/projects/api`, and it mounts `/projects/api` instead. You don't need a +separate `sbxenv.yaml` in either project. + +If the project has a `sbxenv.yaml`, `sbx` combines it with your user defaults. +Project settings override individual default values. Lists such as `ports` +and `mcp.servers` combine entries from both files. If you pass a file or +directory path to the command, `sbx` skips `~/.sbxenv.yaml`. + +In `~/.sbxenv.yaml`, you can set `workspace` to `${{ env.projectDir }}` or a +subdirectory such as `${{ env.projectDir }}/src`. Other workspace paths +aren't accepted in this file. + +The user defaults file cannot set `name`. Set the sandbox name in a project +environment file or with `--name`. + +### Reference directories + +You can use `${{ env.projectDir }}` and `${{ env.fileDir }}` in environment +files to insert absolute directory paths. They refer to directories on the +host. + +#### Project directory + +`${{ env.projectDir }}` is the absolute path to your project directory. +`sbx` chooses this directory from the command you run: + +- `sbx env run`: the directory you run the command from. +- `sbx env run /projects/web-app`: `/projects/web-app`. +- `sbx env run /projects/web-app/custom.yaml`: `/projects/web-app`, the + directory containing the file. + +If you pass several paths, the first one sets the project directory. Every +file loaded by that command uses the same value for `env.projectDir`. + +Use this reference in shared settings that need to point to each project's +files. For example, `workspace: ${{ env.projectDir }}/src` mounts the `src` +directory in whichever project you select. + +#### File directory + +`${{ env.fileDir }}` is the absolute path to the directory containing the +environment file where you write the reference. For example, inside +`/shared/environment.yaml`, its value is `/shared`. + +Use this reference when an environment file needs to locate files stored +alongside it. For example, suppose your setup script is +`/shared/scripts/setup.sh`. Add this [lifecycle command](#lifecycle) to +`/shared/environment.yaml` to run the script from `/shared`: + +```yaml +lifecycle: + initialize: + - command: ./scripts/setup.sh + workdir: ${{ env.fileDir }} +``` + +The command runs from `/shared`, even if you use this environment file with +a project in another directory. + +Relative workspace paths already use the directory containing the environment +file. For example, `workspace: ./src` in `/shared/environment.yaml` mounts +`/shared/src`. + +Both directory references can appear in YAML values, but not in field names +or inside the `args` block. + +### Parameterize an environment + +Declare inputs in a top-level `args` block when values need to vary between +uses of the same environment file. Each argument must have exactly one of +`default` or `required: true`: + +```yaml +schemaVersion: "1" +name: web-app +agent: claude + +args: + channel: + default: stable + description: Release channel + enum: + - stable + - beta + endpoint: + required: true + description: API endpoint + cpus: + default: "4" + pattern: "[1-9][0-9]*" + +env: + RELEASE_CHANNEL: ${{ env.args.channel }} + API_ENDPOINT: ${{ env.args.endpoint }} + +sandboxOptions: + cpus: ${{ env.args.cpus }} +``` + +Reference a declared argument as `${{ env.args.NAME }}` anywhere a YAML value +can appear. References can't be used in field names or within the `args` block. +An unquoted reference is interpreted as a YAML value after substitution, so +the `cpus` value in this example becomes an integer. Quote a reference to +preserve it as a string. + +All `sbx env` commands accept repeatable `--env-arg NAME=VALUE` flags. Values +provided with a flag replace defaults from the environment file: + +```console +$ sbx env run --env-arg endpoint=https://api.example.com --env-arg channel=beta +``` + +Use `--env-args-file` to load values from a file. Each non-empty, non-comment +line must have the form `NAME=VALUE`: + +```text +# production.args +channel=beta +endpoint=https://api.example.com +``` + +```console +$ sbx env run --env-args-file production.args +``` + +You can pass multiple argument files. Later files take precedence over earlier +files, and `--env-arg` flags take precedence over every argument file. +Values can contain `=`, and values in an argument file are read literally +rather than expanded by a shell. + +Argument references and the two directory references are the only variable +expressions expanded in an environment file. Shell-style expressions such as +`${VAR}` aren't expanded from the host environment. Other dollar signs remain +literal, so a value such as `$PATH:/opt/bin` is passed unchanged. +Use `$${{ env.args.NAME }}` to produce the literal text `${{ env.args.NAME }}`. Substituted values aren't expanded a +second time. + +## Common workflows + +The following examples combine environment file fields into configurations you +can adapt for a project. + +### Add v3 kits + +To add v3 mixins, include a v3 workload in `kits` and set `agent` to the +workload's name. + +For example, save this as `web-app-env/v3.sbxenv.yaml` to use a v3 Claude Code +workload with the v3 Playwright mixin: + +```yaml +schemaVersion: "1" +name: web-app-v3 +agent: sbx-kit-claude +workspace: ./web-app + +kits: + - docker.io/docker/sbx-kit-claude:2.1.267 + - docker.io/sbx/playwright:1.61.1 +``` + +From `web-app-env`, run: + +```console +$ sbx env run v3.sbxenv.yaml +``` + +The `agent` value, `sbx-kit-claude`, matches the last component of the +workload's repository name. The `web-app-v3` name creates a separate sandbox. +For other agents, see the +[published v3 workloads](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads). + +### Combine team defaults and personal settings + +Keep the shared configuration in a version-controlled environment directory +outside the mounted workspace. Put machine-specific settings in a file excluded +from version control. For example, commit `base.sbxenv.yaml` beside the +`web-app` directory: + +```yaml +schemaVersion: "1" +name: web-app +agent: claude +workspace: ./web-app + +env: + NODE_ENV: development + +sandboxOptions: + cpus: 4 + memory: 8g +``` + +Add `local.sbxenv.yaml` to `.gitignore`, then use it for personal settings: + +```yaml +env: + LOG_LEVEL: debug + +sandboxOptions: + memory: 12g +``` + +Pass both files in merge order: + +```console +$ sbx env run base.sbxenv.yaml local.sbxenv.yaml +``` + +Nested mappings merge by key, lists concatenate, and values from later files +replace earlier scalar values. In this example, the sandbox has four CPUs, +12 GB of memory, and both environment variables. Each relative workspace path +resolves from the directory of the file that declares it. + +Each source file must contain valid fields and values before merging. A later +override can't repair an invalid value in an earlier file. This also applies +to [user defaults](#set-user-defaults) loaded from `~/.sbxenv.yaml`. + +### Work across multiple repositories + +Mount related repositories alongside the primary project when the agent needs +to coordinate changes or consult shared code and documentation: + +```yaml +# sbxenv.yaml in the directory above the repositories +schemaVersion: "1" +name: web-platform +agent: codex + +workspace: ./web-app + +additionalWorkspaces: + - path: ./shared-components + - path: ./architecture-docs + readOnly: true +``` + +The agent starts in `web-app`, can modify `shared-components`, and can read +`architecture-docs` without changing it. The environment file stays outside all +three workspaces. Relative paths resolve from the directory of the +environment file that declares them. Additional workspaces are mounted directly +even when the primary workspace uses clone mode. + +### Reuse an environment in automation + +Use the same committed environment for interactive development and automated +tasks. Developers attach to the agent with `run`: + +```console +$ sbx env run +``` + +Automation can create the sandbox without attaching, run commands in it, and +remove it afterward: + +```console +$ sbx env create --force +$ sbx env exec -- npm test +$ sbx env rm --force +``` + +For `create` and `run`, `--force` approves the plan for that invocation without +recording consent for later invocations. Use the flag for each unattended `create` or +`run`. For `rm`, `--force` approves the destroy plan and removes the sandbox even +when it is in use. + +Commands and vault references under `secrets` resolve on the host, so the +automation runner must provide the referenced tools and authentication. The +secret values remain outside the environment file. + +## Use a cloud environment + +Use `sbx --cloud env` to create a sandbox on Docker-managed infrastructure from +an environment file. Cloud sandboxes don't mount or synchronize local project +files, and local credentials aren't available to them. You copy files into the +sandbox or clone a repository there, then retrieve your work before removing it. + +For a walkthrough, supported settings, and lifecycle differences, see +[Use environment files in the cloud](../cloud/environment-files.md). + +## Review an environment plan + +`sbx env create`, `sbx env run`, and `sbx env rm` show the changes an +environment makes outside its sandbox and ask for approval before applying +them. The plan includes host commands, credentials, bindings, MCP +registrations, directories, kits, published ports, sandbox options, and +environment variables. + +Run `sbx env plan` to inspect the apply plan without changing, approving, or +recording anything: + +```console +$ sbx env plan +``` + +The plan compares the environment file with the environment's last applied +state and the resources on the host. It omits resources that are unchanged and +already approved. Literal secret values appear as SHA-256 digests. Secret +references, host commands, environment variables, ports, paths, and binding +domains remain visible so you can review them. + +Changes appear under the same keys and nesting as the environment file. +For example, this plan changes `GOFLAGS` from `-mod=mod` to `-mod=readonly`: + +```text + env: +~ GOFLAGS: -mod=mod -> -mod=readonly +``` + +Read the symbol beside each entry before approving the plan: + +| Symbol | Effect of applying the entry | +| ------ | ---------------------------- | +| `+` | Add a resource | +| `~` | Change a resource | +| `-` | Destroy a resource | +| `>` | Run a host command again | +| `!` | Stop tracking a resource that is no longer declared, without deleting it | + +Interactive approval is recorded for the environment under the `sbx` state +directory. Plans without host commands apply silently on later invocations until +the environment changes or a resource is missing. An approval provided with +`--force` applies only to that invocation. + +## Update an environment + +For an existing sandbox, `sbx env run` applies updated `env` values to the new +agent session and reconciles declared MCP servers. Changes to workspaces, kits, +ports, secrets, bindings, and `sandboxOptions` take effect only when the +sandbox is next created. Remove the environment with `sbx env rm`, then create +it again to apply those changes. + +## Remove an environment + +Secrets and registry credentials are sandbox-scoped. Credential bindings and +MCP server registrations are host-global and can be shared by multiple +sandboxes. + +`sbx env rm` builds a destroy plan from the resources on the host. The plan +includes all credentials stored at the sandbox's scope, including credentials +that the environment file no longer declares. After approval, `sbx` removes +only the resources named in the plan. + +Global credential bindings remain unless you pass `--prune-bindings`. MCP +registrations remain available to other sandboxes. + +### Clean up after a failed create + +Secret provisioning, binding updates, and MCP server registration occur before +the sandbox is created. If sandbox creation fails, scoped secrets remain, and +bindings and MCP registrations may also remain. Run `sbx env rm` with the same +paths to remove the scoped secrets. Pass `--prune-bindings` if you also want to +remove the declared global bindings. MCP registrations are host-global and +remain after cleanup. + +## File reference + +### Top-level fields + +| Field | Type | Required | Default | Description | +| ---------------------- | ---------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------- | +| `schemaVersion` | string | Yes | None | Schema version. The supported value is `"1"` | +| `name` | string | No | `<agent>-<workspace-basename>` | Sandbox name, overridden by `--name` | +| `agent` | string | Yes | None | Built-in agent or the name of an agent kit | +| `args` | map | No | None | Environment arguments. See [`args`](#args) | +| `kits` | list | No | None | Kits to install at creation. See [`kits`](#kits) | +| `workspace` | string or object | No | No host mount | Primary workspace. See [`workspace`](#workspace) | +| `additionalWorkspaces` | list | No | None | Extra directories to mount. See [`additionalWorkspaces`](#additionalworkspaces) | +| `env` | map of strings | No | None | Environment variables for the sandbox | +| `sandboxOptions` | object | No | None | Creation options. See [`sandboxOptions`](#sandboxoptions) | +| `secrets` | map | No | None | Service credentials. See [`secrets`](#secrets) | +| `bindings` | map | No | None | Credential injection approvals. See [`bindings`](#bindings) | +| `registries` | map | No | None | Registry pull credentials. See [`registries`](#registries) | +| `mcp` | object | No | None | MCP servers. See [`mcp`](#mcp) | +| `ports` | list | No | None | Port mappings. See [`ports`](#ports) | +| `lifecycle` | object | No | None | Host commands. See [`lifecycle`](#lifecycle) | + +### `args` + +`args` maps argument names to their declarations. Names must start with a +letter or underscore and can contain letters, numbers, underscores, and +hyphens. Each declaration must set exactly one of `default` or `required: +true`. + +| Field | Type | Default | Description | +| ------------- | --------------- | ------- | ----------------------------------------------------------------- | +| `default` | string | None | Value used when the command doesn't supply the argument | +| `required` | boolean | `false` | Require the command to supply the argument | +| `description` | string | None | Explanation shown in command output | +| `enum` | list of strings | None | Values accepted for the argument | +| `pattern` | string | None | Go (`RE2`) expression matched against the complete argument value | + +`enum` and `pattern` can't be used together. + +### `kits` + +`kits` accepts local directories, ZIP archives, OCI registry references, and +Git URLs prefixed with `git+https://` or `git+ssh://`. Kits can install tools, +configure the sandbox, and give the agent project-specific instructions. +Built-in agents use v2 mixins. For v3 workloads and mixins, see +[Add v3 kits](#add-v3-kits). + +An environment file selects kits and configures a sandbox's host resources. +A kit descriptor defines the package itself. The environment file's +`schemaVersion` is independent of the schema version in a kit descriptor. + +Explicit relative paths resolve from the directory of the environment file +that declares them. These include `.`, `..`, paths that start with `./` or +`../`, and relative paths that end in `.zip`. Bare references such as +`organization/kit` remain registry references. + +Use an object entry to pass arguments to a kit. Set `source` to the kit +reference and map the kit's argument names to values under `args`: + +```yaml +kits: + - source: ./kits/tool + args: + version: ${{ env.args.channel }} +``` + +Remote kit sources must match the +[`kit.allowedSources`](settings.md#kitallowedsources) setting. Docker Hub is +allowed by default. To use Git kits from `docker/sbx-kits-contrib`, add its +source: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]' +``` + +The setting replaces the complete allowlist, so include any existing sources +you want to keep. For reproducible setup, pin Git kits with the `ref` URL +parameter and OCI kits with an immutable tag or digest. + +### `workspace` + +When specified as a string, `workspace` is the path. Use the object form for +clone mode. Omit `workspace` to create a sandbox without a host bind mount. Set +`workspace: .` to mount the directory that contains the environment file +that declares it. + +For environment file placement and write protection, see +[Protect the environment file](#protect-the-environment-file). + +| Field | Type | Required | Default | Description | +| ------- | ------- | -------- | ------- | --------------------------------------------------------------- | +| `path` | string | Yes | None | Workspace directory. Relative paths resolve from the declaring file's directory | +| `clone` | boolean | No | `false` | Use a private clone, equivalent to `sbx create --clone` | + +You can override `workspace.clone` for one `create` or `run` invocation with +`--clone` or `--clone=false`. + +### `additionalWorkspaces` + +Each additional workspace is mounted after the primary workspace. Relative +paths resolve from the directory of the environment file that declares them. + +| Field | Type | Required | Default | Description | +| ---------- | ------- | -------- | ------- | ----------------------------- | +| `path` | string | Yes | None | Directory to mount | +| `readOnly` | boolean | No | `false` | Mount the directory read-only | + +### `sandboxOptions` + +| Field | Type | Default | Description | +| ------------- | --------------- | -------- | ----------------------------------------------------- | +| `template` | string | None | Custom sandbox template image | +| `memory` | string | None | Memory limit, such as `8g` or `512m` | +| `cpus` | integer | `0` | Number of CPUs. `0` selects the host default | +| `pullPolicy` | string | `always` | Image pull policy: `always`, `missing`, or `never` | +| `profile` | string | None | Governance profile name | +| `skills` | string | Daemon default | Shared agent skills store access: `off`, `readonly`, or `readwrite` | +| `display` | boolean | `false` | Provision a display socket for graphical applications | +| `gpu` | boolean | `false` | Pass the host GPU through to the sandbox | +| `usb` | list of strings | None | USB device selectors to pass through to the sandbox | +| `writableEnvFiles` | boolean | `false` | Let the sandbox write to shared environment files; local only | + +For local sandboxes, `cpus: 0` allocates all host CPUs, except on Linux arm64 +hosts, where the default is capped at 16. Set `cpus` to an explicit count to +request a larger allocation, up to the number of available host CPUs. When creating a sandbox directly with +`sbx create` or `sbx run`, use `--cpus` for the same override. Cloud resource +limits must match a [cloud size](../cloud/usage.md#choose-resources-and-platform). + +`skills` controls access to the shared [agent skills](../workflows/agent-skills.md) +store. Set it to `off` to omit the mount, `readonly` to mount the store read-only, +or `readwrite` to let the sandbox modify shared skills. If omitted, it uses the +daemon's default, which is `readonly` unless your organization overrides it. + +### `lifecycle` + +The `lifecycle` block declares commands that run on the host with your user +privileges. Use lifecycle commands for work that must happen outside the +sandbox, such as creating a workspace, seeding fixtures, or archiving state. + +```yaml +lifecycle: + initialize: + - name: Prepare workspace + command: test -d web-app || git clone https://github.com/example/web-app + timeout: 5m + postCreate: + - command: ./scripts/seed-fixtures.sh + workdir: web-app + preRemove: + - command: ./scripts/archive-state.sh +``` + +Lifecycle phases run at the following points: + +| Phase | Timing | +| ------------ | ---------------------------------------------------------------------------------------------------------------- | +| `initialize` | Before other create or run actions. Runs for every `create` and `run` | +| `postCreate` | After a new sandbox is created. For `run`, before attachment. Does not run when attaching to an existing sandbox | +| `preRemove` | After you approve removal and before `sbx` deletes resources. A failure produces a warning and removal continues | + +`sbx env exec` doesn't run lifecycle commands. Commands within a phase run in +order and stop at the first failure. Make `initialize` commands safe to run +more than once. + +After `preRemove` commands finish, `sbx` generates the destroy plan again. +Removal stops if the commands introduced changes that weren't included in the +approved plan. + +Each command requires `command` and accepts the following fields: + +| Field | Type | Default | Description | +| --------- | ------ | ----------------- | ------------------------------------------------------------------------------ | +| `name` | string | Command text | Label shown in progress and plan output | +| `command` | string | None | Command passed to the user's shell | +| `workdir` | string | Project directory | Host working directory. Relative paths resolve from the first file's directory | +| `timeout` | string | None | Maximum runtime, such as `90s` or `5m` | + +Commands inherit the environment of the `sbx` process and receive the following +variables: + +- `SBX_LIFECYCLE_PHASE` +- `SBX_ENV_FILE` and `SBX_ENV_FILES` +- `SBX_ENV_DIR` +- `SBX_SANDBOX_NAME` +- `SBX_AGENT` +- `SBX_WORKSPACE` + +The environment file's `env` values and resolved secrets aren't passed to host +commands. + +Plans containing lifecycle commands or credential `command` sources require +approval for every invocation by default, even when the command text hasn't +changed. Approve one invocation with `--force`, skip lifecycle commands +with `--skip-host-commands`, or turn on +[`env.rememberHostCommands`](settings.md#envrememberhostcommands) to remember +approval until the commands change: + +```console +$ sbx settings set env.rememberHostCommands true +``` + +### `secrets` + +`secrets` maps service names to secret sources. Each entry must set exactly one +of `value`, `ref`, or `command`. The secret is stored at the sandbox scope when +the environment is created. + +| Field | Type | Default | Description | +| ---------- | ------- | ------- | ---------------------------------------------------------------------------- | +| `value` | string | None | Literal secret value | +| `ref` | string | None | Vault URI, such as `op://Vault/Item/field` | +| `command` | string | None | Host shell command whose standard output becomes the secret | +| `snapshot` | boolean | `false` | Resolve `ref` or `command` once on the host and store the result as a literal | +| `refresh` | string | None | Resolution policy for `ref` or `command`, such as `on-demand` or `55m` | +| `backend` | string | Automatic | Resolver for `ref`: `sdk` or `cli` | +| `noVerify` | boolean | `false` | Skip verifying that a `ref` or `command` resolves during provisioning | + +> [!WARNING] +> A literal `value` is visible to anyone with read access to the file. Use a +> vault URI with `ref` or obtain the value at runtime with `command`. + +```yaml +secrets: + anthropic: + ref: op://Private/Anthropic/api-key + refresh: 55m + github: + command: gh auth token +``` + +Secret commands execute from a fresh temporary directory on the host. Relative +helper paths resolve from that directory. Keep helpers and their dependencies +outside writable sandbox mounts. Use an absolute path, an absolute host +`PATH` entry, or an explicit change to the helper's private directory. See +[dynamic secret sources](credentials.md#use-a-dynamic-secret-source). + +For a cloud environment, set `snapshot: true` on a `ref` or `command` source: + +```yaml +secrets: + github: + command: gh auth token + snapshot: true +``` + +The command runs on the host after plan approval. The resolved value is stored +as a literal secret and doesn't refresh. Recreate the environment to rotate +it. Snapshots also work with local environments. A snapshot can't set +`refresh` or `noVerify`. Cloud snapshots use CLI resolvers for vault references +and don't support `backend: sdk`. + +### `bindings` + +`bindings` approves credential injection domains for each service. The +environment merges these approvals into the user's global +`credentials.yaml`. Each service can contain an `apiKey` block, an `oauth` +block, or both. Each block contains a `domains` list: + +```yaml +bindings: + github: + apiKey: + domains: + - api.github.com +``` + +`sbx env rm` preserves global bindings by default. Pass `--prune-bindings` to +remove every service binding declared by the environment file. + +> [!WARNING] +> `--prune-bindings` deletes the complete global binding entry for every +> service declared in the environment file. This can affect other sandboxes +> that share those service bindings. + +### `registries` + +`registries` maps registry hostnames to pull credentials. Each entry requires +`secret` and accepts an optional `username`. Both fields accept a secret source +with exactly one of `value`, `ref`, or `command`. + +When `username` is omitted, `sbx` stores a token-only credential. Registries +such as GHCR and GitLab accept token-only credentials. + +```yaml +registries: + ghcr.io: + secret: + command: gh auth token +``` + +### `mcp` + +The `mcp.servers` list registers servers with the built-in +[MCP gateway](../mcp-gateway.md) and adds them to the sandbox. MCP registrations +are host-global and remain after `sbx env rm`. + +| Field | Type | Required | Default | Description | +| --------- | --------------- | -------- | ------- | --------------------------------------------------------------- | +| `name` | string | Yes | None | Server name | +| `url` | string | No | None | Remote server URL, registry reference, or OCI reference | +| `command` | string | No | None | Command for a local stdio server | +| `args` | list of strings | No | None | Arguments passed to `command` | + +Each server must set exactly one of `url` or `command`. + +### `ports` + +`ports` publishes sandbox ports when the environment is created. Ports exposed +by a kit but omitted from this list receive an ephemeral host port. + +| Field | Type | Required | Default | Description | +| ---------- | ------- | -------- | ------------------------------------ | ----------------------------------------------- | +| `sandbox` | integer | Yes | None | Sandbox port from 1 through 65535 | +| `host` | integer | No | Ephemeral | Host port from 1 through 65535 | +| `protocol` | string | No | `tcp4`, or `tcp6` for IPv6 `hostIP` | `tcp`, `tcp4`, `tcp6`, `udp`, `udp4`, or `udp6` | +| `hostIP` | string | No | Loopback | Host interface to bind | + +Set `protocol: tcp` to bind both IPv4 and IPv6. Leave `hostIP` unset for a +dual-stack binding because an explicit address binds only its own IP family. + +If a port can't be published, sandbox creation fails and removes the new +sandbox. diff --git a/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md new file mode 100644 index 000000000000..48650ce76071 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/gpu-passthrough.md @@ -0,0 +1,142 @@ +--- +title: Enable NVIDIA GPU passthrough +linkTitle: GPU passthrough +description: Run GPU-accelerated workloads in a sandbox by building and installing the NVIDIA driver bundle for VFIO passthrough. +keywords: docker sandboxes, sbx, gpu, gpu passthrough, nvidia, vfio, iommu, driver bundle, cuda +weight: 30 +aliases: + - /ai/sandboxes/gpu-passthrough/ +--- + +> [!IMPORTANT] +> GPU passthrough is experimental. The `--gpu` flag, the driver bundle, and the +> setup steps on this page are subject to change. + +GPU passthrough in local Docker Sandboxes runs workloads on a physical NVIDIA +GPU. + +GPU passthrough in Docker sandboxes works via [VFIO](https://www.kernel.org/doc/html/latest/driver-api/vfio.html), a Linux feature +that assigns a PCI device directly to a virtual machine. The GPU is +bound to VFIO instead of the host's driver, and the sandboxed workload +drives the hardware itself. + +## Requirements + +VFIO-based GPU passthrough is supported only on `x86_64` Linux hosts (not Arm) +with NVIDIA GPUs, and requires a GPU that nothing else is using: a headless +host with a GPU, or an additional GPU. + +The host also needs IOMMU turned on in its BIOS, and the `iommufd` and +`vfio_pci` kernel modules loaded: + +```console +sudo modprobe -a iommufd vfio_pci +``` + +For the sandbox to drive the GPU, it requires: + +- The `nvidia` and `nvidia-uvm` kernel modules, built for the Docker Sandboxes + guest kernel +- The NVIDIA userspace driver libraries and firmware + +Docker Sandboxes looks for these dependencies, packaged as an EROFS image, at +`/usr/libexec/nerdbox-nvidia-bundle.erofs`. This bundle isn't included with +Docker Sandboxes. To build it, see [Build the bundle](#build-the-bundle). + +## Turn on the feature + +The `--gpu` flag is hidden until you turn on experimental features and the GPU +feature flag: + +```console +sbx settings set platform.allowExperimentalFeatures true +sbx settings set feature.sandbox-gpu true +``` + +## Build the bundle + +A zip archive containing all the components required to build the bundle is +published with each Docker Sandboxes release, as +`nerdbox-nvidia-modules-x86_64.zip`. The archive contains the kernel modules +(`nvidia.ko` and `nvidia-uvm.ko`), the driver version they were built against +(`VERSION`), and a build script. + +The build script runs a `linux/amd64` container that downloads the matching +NVIDIA driver, assembles the bundle, and installs it to +`/usr/libexec/nerdbox-nvidia-bundle.erofs`. Writing to that path requires root, +hence the `sudo` in the following commands. + +Prerequisites: + +- Network access to `download.nvidia.com` +- Docker + +Download and unpack the archive, then run the script from the unpacked +directory: + +```console +curl -fSLO https://github.com/docker/sbx-releases/releases/latest/download/nerdbox-nvidia-modules-x86_64.zip +unzip nerdbox-nvidia-modules-x86_64.zip -d nvidia-modules +cd nvidia-modules +sudo ./prepare-nvidia-bundle.sh +``` + +If the script can't write to the output path, it leaves the bundle in the +current directory and prints the `install` command that finishes the job. + +Two environment variables override the script's default behavior: + +| Variable | Default | Purpose | +| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| `OUTPUT` | `/usr/libexec/nerdbox-nvidia-bundle.erofs` | Where the finished bundle is written. | +| `ACCEPT_NVIDIA_LICENSE` | None | Set to `1` to accept the NVIDIA license non-interactively, for scripts or CI. | + +For example, the following command writes the finished bundle to +`/mnt/some-place/nerdbox-nvidia-bundle.erofs`: + +```console +OUTPUT=/mnt/some-place/nerdbox-nvidia-bundle.erofs ./prepare-nvidia-bundle.sh +``` + +## Install the bundle + +If you ran the script on the `x86_64` Linux host that runs your GPU sandboxes, +and you didn't override `OUTPUT`, the bundle is already in place. If you built +it elsewhere, copy the `nerdbox-nvidia-bundle.erofs` file it produced into that +host's `/usr/libexec` directory. + +## Run a sandbox with a GPU + +To run a sandbox with GPU passthrough, pass the `--gpu` flag: + +```console +sbx create --gpu claude . +``` + +The `sbx run` command takes the same flag: + +```console +sbx run --gpu claude +``` + +The flag takes effect when the sandbox is created. Passing it when you +re-attach to an existing sandbox has no effect. + +> [!IMPORTANT] +> Each Docker Sandboxes release uses a specific guest kernel. The NVIDIA +> kernel modules in your bundle must match that kernel. After upgrading +> Docker Sandboxes, download the new release's `nerdbox-nvidia-modules-x86_64.zip` +> archive and run the script again to rebuild the bundle. + +## Troubleshooting + +### The script reports `... not found in the driver download` + +The extracted driver didn't contain an expected library or firmware file. +Confirm that the download completed. If a library is named differently in your +driver version, adjust `DRIVER_LIB_FAMILIES` in the script. + +### GPU workloads fail after a Docker Sandboxes upgrade + +The guest kernel or the pinned driver version likely changed. Download the new +release's archive, re-run the script, and reinstall the bundle. diff --git a/content/manuals/ai/sandboxes/configuration/models.md b/content/manuals/ai/sandboxes/configuration/models.md new file mode 100644 index 000000000000..74c7eecc8913 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/models.md @@ -0,0 +1,225 @@ +--- +title: Use local and hosted models +linkTitle: Models +weight: 15 +description: Choose a local model, hosted provider, or custom inference endpoint for Claude Code, Codex, or OpenCode in Docker Sandboxes. +keywords: docker sandboxes, sbx, models, providers, llmman, ollama, inference, local models +--- + +Use `sbx run --model` to choose the model and service that answer your agent's +requests. The agent runs inside a local sandbox. The model can run on your +host, at a hosted provider, or at an inference endpoint you configure. + +This page covers the built-in `claude`, `codex`, and `opencode` agents. Choose +a model that supports the tool calls and context length your agent needs. +`--model` isn't supported with cloud sandboxes or v3 kits. + +> [!NOTE] +> Model selection is experimental. Enable it before following these examples. + +## Bundled model service + +Docker Sandboxes includes `llmman`, a model management tool installed alongside +`sbx`. It serves local models and forwards requests to hosted providers or +custom endpoints. You don't need to install it separately. + +The Docker Sandboxes daemon starts `llmman` on your host and stops it when +the daemon stops. At startup, `llmman` downloads its llama.cpp runtime if +needed, so the first startup requires network access for that download. The service starts even if you haven't used `--model`. + +The service keeps running after a sandbox or CLI exits. Sandboxes share its +model store and loaded models. + +On Linux, `llmman` first tries Docker or Podman to run the inference server +in a container. If neither is usable, it tries a downloaded binary, then +`llama-server` on the host's `PATH`. + +## Enable model selection + +Run these commands on your host: + +```console +$ sbx settings set platform.allowExperimentalFeatures true +$ sbx settings set feature.model true +``` + +The `--provider` flag selects where the model runs: + +| Provider | Model destination | +| --- | --- | +| Omitted, or `llmman` | A local model managed by `llmman` | +| `ollama` | An existing Ollama installation on your host | +| A hosted provider ID | A provider supported by `llmman`, such as `openai` or `anthropic` | +| An ID from `model.providers` | An endpoint you configure | + +## Run a local model + +Pass a GGUF model reference or short name to `--model`: + +```console +$ sbx run --model gemma4 claude +``` + +Docker Sandboxes downloads the model if needed. The model runs on the host, +so its memory and compute requirements are separate from the sandbox's +resource limits. Replace `claude` with `codex` or `opencode` to use another +agent with the same model. + +### Use Ollama + +Install and start Ollama on your host, then select it with `--provider`: + +```console +$ sbx run --model gemma4 --provider ollama claude +``` + +Docker Sandboxes connects to Ollama at `localhost:11434`. It doesn't install, +start, or manage the Ollama process. + +For Docker Model Runner, see +[Run Claude Code in a Docker Sandbox with Docker Model Runner](/guides/claude-code-sandbox-model-runner/). + +## Use a hosted provider + +Select a provider supported by `llmman` and a model available from that +provider. For example, store your OpenAI API key on the host, then run Codex +with an OpenAI model: + +```console +$ sbx secret set openai +$ sbx run --provider openai --model gpt-5-nano codex +``` + +The host's `llmman` service forwards requests to the provider. It doesn't +download or run the hosted model. For available providers and their API-key +variable names, see the [llmman provider documentation](https://github.com/llmmanorg/llmman/blob/main/docs/providers.md). + +### Provider authentication + +Store the API key with `sbx secret set <PROVIDER_ID>`, using the same ID as +`--provider` or `--overflow-provider`. This also works for a custom provider +ID defined in `model.providers`. Sandbox-scoped secrets take precedence over +global secrets. + +The sandbox sends a placeholder in place of the key. The host proxy replaces +it with the stored key only in authentication headers on requests to the host's +`llmman` service. That service uses the key to authenticate requests to the +selected provider. The real key stays outside the sandbox. + +Docker Sandboxes configures this injection automatically when you select the +provider. You don't need `sbx secret set-custom` or domain injection rules for +this workflow. + +> [!WARNING] +> Model-provider credentials are protected differently from other sandbox +> credentials. For other credentials, the proxy restricts injection to their +> configured domains. For model providers, it supplies the key to the host's +> `llmman` service instead. That service can forward the key to other endpoints +> it supports; selecting `--provider` does not restrict the key to that +> provider's endpoint. + +If no stored secret is available, make the key available in the host shell +that starts the daemon. For a custom endpoint, choose the variable name with +[`apiKeyEnv`](#connect-a-custom-endpoint). + +`llmman` inherits the daemon's environment. After setting or changing a key +in that environment, run `sbx daemon restart` from the shell containing the +updated variable. +This restarts the model service and interrupts model requests from sandboxes +using it. Setting a variable only in the shell where you run `sbx run --model` +doesn't update an already-running service. + +Using a stored secret avoids restarting the daemon to load a key from its +environment. For the agents' default authentication flows, see +[Manage credentials](credentials.md). + +## Connect a custom endpoint + +Use `model.providers` to connect to an OpenAI- or Anthropic-compatible +inference endpoint, such as an internal GPU server. The endpoint must be +reachable from your host. + +The setting is a JSON object keyed by provider ID. Check its existing value +before changing it: + +```console +$ sbx settings get model.providers +``` + +For an OpenAI-compatible endpoint, define a provider named `company`: + +```console +$ sbx settings set model.providers '{"company":{"url":"https://inference.example.com/v1","wire":"openai"}}' +``` + +Replace the URL with your endpoint's base URL. Setting `model.providers` +replaces the whole object, so include any existing providers you want to keep. + +| Field | Description | +| --- | --- | +| `url` | Required HTTP or HTTPS base URL, usually ending in `/v1`. Use the base URL, without `/chat/completions` or `/messages`. | +| `wire` | The endpoint's API format: `openai` (default) or `anthropic`. This describes the endpoint, regardless of which agent you run. | +| `apiKeyEnv` | Name of an optional host environment variable containing the API key. Used as a fallback when no stored provider secret is available. | +| `name` | Optional display name. Defaults to the provider ID. | + +If the endpoint requires an API key, store it using the provider ID +(`company`). Docker Sandboxes configures authentication when you select that +provider with `--provider`: + +```console +$ sbx secret set company +$ sbx run --provider company --model <MODEL_NAME> claude +``` + +Docker Sandboxes applies the provider configuration when you run with +`--model`. You can use the same provider with `codex` or `opencode`. + +## Change an existing sandbox's model + +Pass the sandbox name and your model selection: + +```console +$ sbx run --name <SANDBOX_NAME> --model <MODEL_NAME> --provider <PROVIDER_ID> +``` + +Changing the model recreates the sandbox container. The workspace and +kit-owned volumes persist. Omit `--provider` to select a local model managed +by `llmman`. + +## Choose a reasoning level + +Use `--variant` with `--model` to select a reasoning level supported by your +model. For example, replace `<MODEL_NAME>` with an OpenAI model that supports +`high` reasoning effort to start Codex at that level: + +```console +$ sbx run --provider openai --model <MODEL_NAME> --variant high codex +``` + +Available values depend on the model and agent. Reasoning levels are `minimal`, +`low`, `medium`, `high`, `xhigh`, and `max`. Some models support `none` to disable +thinking or `thinking` to enable it. Omit `--variant` to use the default. + +Claude Code doesn't support `none` or `minimal`. For Claude Code and Codex, +`--variant` requires an attached session and can't be combined with `--detach`. +In OpenCode, it selects the initial variant, which you can change inside +OpenCode. + +## Use another provider for larger requests + +Pair a local model with another provider to handle requests that exceed the +local model's context capacity: + +```console +$ sbx run --model gemma4 \ + --overflow-provider openai --overflow-model gpt-5-nano claude +``` + +Configure [provider authentication](#provider-authentication) before starting +the model service. You can also use a provider defined in `model.providers`. +Both overflow flags are required, and the local model must use the default +`llmman` provider. This option can't be combined with `--provider ollama` or +a hosted provider selected with `--provider`. + +Requests that fit the local model stay local. Requests routed to the overflow +provider send their contents to that endpoint and can incur provider charges. diff --git a/content/manuals/ai/sandboxes/configuration/registry-mirror.md b/content/manuals/ai/sandboxes/configuration/registry-mirror.md new file mode 100644 index 000000000000..5ffc2b77614a --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/registry-mirror.md @@ -0,0 +1,74 @@ +--- +title: Configure a registry mirror +linkTitle: Registry mirror +description: Route Docker Hub template, kit, and in-sandbox Docker image pulls through an organization's registry mirror. +keywords: docker sandboxes, sbx, registry mirror, docker hub, templates, kits, image pulls +weight: 50 +--- + +{{% include "sandboxes-local-scope.md" %}} + +A registry mirror routes Docker Hub pulls for sandbox templates and OCI kits +through your organization's registry infrastructure. If the mirror meets +Docker Engine's requirements, Docker inside the sandbox uses it too. + +## Configure the mirror + +Set [`platform.images.registryMirror`](settings.md#platformimagesregistrymirror) +to the mirror host. Include a port when needed, but omit the URL scheme: + +```console +$ sbx settings set platform.images.registryMirror registry.example.com +``` + +You can include a path prefix for registries that store mirrored Docker Hub +content below a repository path: + +```console +$ sbx settings set platform.images.registryMirror registry.example.com/docker-remote +``` + +Docker Sandboxes redirects image references that resolve to Docker Hub and +preserves their repository path, tag, and digest. References that explicitly +name another registry remain unchanged. + +If the mirror requires authentication, configure +[registry credentials](credentials.md#registry-credentials) for the mirror +host. + +## Mirror Docker pulls inside the sandbox + +Docker Sandboxes configures Docker Engine inside a sandbox to use the same +mirror when the setting contains a non-loopback host without a path prefix. + +| Mirror setting | Template and OCI kit pulls | Docker pulls inside the sandbox | +| -------------------------------------- | -------------------------- | ------------------------------- | +| `registry.example.com` | Mirrored | Mirrored | +| `registry.example.com:5000` | Mirrored | Mirrored | +| `registry.example.com/docker-remote` | Mirrored | Not mirrored | +| `localhost:5000` or `127.0.0.1` | Mirrored | Not mirrored | + +Loopback addresses refer to the sandbox itself from inside its network +namespace, so Docker Sandboxes doesn't add them to the sandbox's Docker Engine +configuration. A path prefix is also excluded because Docker Engine interprets +mirror URL paths differently from image repository prefixes. + +Docker Engine connects to the mirror over HTTPS, so the sandbox must trust the +certificate that the mirror presents. For a mirror that uses an internal +certificate authority, add the CA to the sandbox's system trust store. See +[Install an internal CA certificate](../customize/kits-v2.md#install-an-internal-ca-certificate). + +Template and kit pulls use the changed setting immediately. Existing sandboxes +retain the Docker Engine mirror configuration with which they were created. +Recreate a sandbox to apply a changed mirror to Docker inside it. + +## Disable the mirror + +Unset the setting to disable mirroring: + +```console +$ sbx settings unset platform.images.registryMirror +``` + +An empty setting value also disables mirroring. Recreate existing sandboxes to +remove a mirror from their Docker Engine configuration. diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md new file mode 100644 index 000000000000..6d57bd52564d --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -0,0 +1,756 @@ +--- +title: Docker Sandboxes settings +linkTitle: Settings +description: Configure Docker Sandboxes with sbx settings. View effective values, manage persistent overrides, and use environment variables for supported settings. +keywords: docker sandboxes, sbx, settings, configuration, environment variables, overrides +weight: 5 +--- + +Use `sbx settings` to configure Docker Sandboxes on your host, including +clipboard access, kit sources, and defaults for sandbox creation. Settings +apply across your local sandboxes. For project-specific configuration, use +[environment files](environment-files.md). + +The commands read and write settings through the local daemon, starting it if +necessary. Overrides persist across CLI invocations and daemon restarts. + +## View settings + +List settings with their effective value, type, source, and description: + +```console +$ sbx settings ls +``` + +Long values and descriptions are truncated in the table. Use +`sbx settings ls --no-trunc` for complete text, or `sbx settings ls --json` +for JSON output. The JSON records also include defaults and environment +variable names where available. + +To inspect one setting: + +```console +$ sbx settings get clipboard.imagePaste +false +$ sbx settings get clipboard.imagePaste --json +``` + +By default, `get` prints only the effective value. Use `--json` or +`--format yaml` for the complete setting record, including the source and default. + +## Change a setting + +Set an override by passing the setting key and a value of the required type. +For example, allow sandboxed agents to read images from your host clipboard: + +```console +$ sbx settings set clipboard.imagePaste true +``` + +For JSON values, quote the argument so your shell passes it intact. This +example permits kits from Docker Hub and your organization's GitHub repositories: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/myorg/"]' +``` + +JSON arrays and objects replace the whole value. Include any entries you want +to keep. + +Remove an override with `unset`: + +```console +$ sbx settings unset clipboard.imagePaste +``` + +The setting falls back to its environment variable, if set, or its default. +Setting a value equal to its built-in default also removes the stored override. + +### Value precedence + +For each setting, the first available value wins: + +1. The setting's environment variable, if it has one +2. A user override written with `sbx settings set` +3. The built-in default + +The `SOURCE` column in `sbx settings ls` identifies the selected source as +`envvar`, `override`, or `default`. If an environment variable takes precedence, +`set` still updates the stored override and reports why the effective value +hasn't changed. `unset` removes only the stored override, not the environment +variable. + +### When changes take effect + +Most changes take effect within about five seconds. Settings marked `yes` in +the `RESTART` column require a daemon restart for existing daemon-side consumers: + +```console +$ sbx daemon restart +``` + +The `set` and `unset` commands print a restart reminder when needed. Some +settings apply only when creating a sandbox: changing a template default or disk +size doesn't update existing sandboxes. Proxy settings have separate timing for +CLI requests, daemon traffic, and sandbox traffic. See +[When proxy changes take effect](upstream-proxy.md#when-changes-take-effect). + +## Environment variables + +Some settings have an environment variable equivalent, listed in the reference +entries below. These variables configure Docker Sandboxes on the host. They +don't set environment variables inside a sandbox. + +The daemon inherits environment variables when it starts. Export a variable +before the first `sbx` command, or restart an existing daemon from the shell +where you set it. For example: + +```console +$ export DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE=true +$ sbx daemon restart +$ sbx settings get clipboard.imagePaste +true +``` + +Changing your shell environment doesn't change the environment of a running +daemon, even for settings that normally take effect without a restart. To +return to a stored override or default, remove the variable and restart: + +```console +$ unset DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE +$ sbx daemon restart +``` + +CLI operations that read settings locally use their own environment on each +invocation. Keep the CLI and daemon environments consistent when using these +variables. A persistent override with `sbx settings set` avoids needing to +export a variable in each shell. + +## Settings reference + +Each entry lists its built-in default, before overrides. An environment +variable appears only when the setting has a direct equivalent. Use +`sbx settings ls` to inspect the values supported by your installed version. + +### Agents and host access + +#### browser.enabled {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="true" >}} + +Set this to `false` to prevent sandboxed processes from opening URLs in your +host browser: + +```console +$ sbx settings set browser.enabled false +``` + +This also prevents in-sandbox OAuth logins that redirect to localhost. + +#### clipboard.imagePaste {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE" >}} + +Turn this on to paste screenshots and other host clipboard images into agents +such as Claude Code and Codex with `Ctrl+V`. Text paste doesn't need this setting. + +```console +$ sbx settings set clipboard.imagePaste true +``` + +This grants sandboxed processes access to host clipboard images. The change +applies to running sandboxes without recreating them. Set it to `false` to +withdraw that access. See [image paste](../faq.md#can-i-paste-images-into-an-agent) +for supported behavior. + +#### claude.remoteControl {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_CLAUDE_REMOTE_CONTROL" >}} + +Turn this on before using Claude Code's `/remote-control` command inside a +sandbox: + +```console +$ sbx settings set claude.remoteControl true +``` + +The remote-control connection must authenticate with its own session token. +This setting lets it do so instead of having the sandbox proxy replace that +token with the host credential. Set it to `false` to restore credential +replacement on that connection. Changes apply to requests from running +sandboxes. See [Claude Code remote control](../agents/claude-code.md#remote-control). + +#### env.rememberHostCommands {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" >}} + +Use this when you repeatedly run a trusted environment file and want to +approve its host commands once, until those commands change: + +```console +$ sbx settings set env.rememberHostCommands true +``` + +The first approval is still required. Commands run on your host with your +permissions, outside the sandbox. Leave the setting at `false` to require +approval on every invocation, or use `--force` to approve only one +invocation. See [environment lifecycle commands](environment-files.md#lifecycle). + +#### ssh.agentForwardingEnabled {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="true" >}} + +Set this to `false` when sandboxes should not be able to request signatures +from your host SSH agent, including for Git authentication and commit signing: + +```console +$ sbx settings set ssh.agentForwardingEnabled false +$ sbx daemon restart +``` + +Restarting the daemon applies the change to existing forwarders. When forwarding +is enabled, the private keys remain on the host, but sandboxed processes can +ask the agent to use them. See [SSH agent credentials](credentials.md#ssh-agent). + +#### ssh.agentSocketPath {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Use a fixed path when every sandbox should use the same host SSH agent, such +as a password manager's agent, regardless of which shell starts the sandbox: + +```console +$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK" +$ sbx daemon restart +``` + +Run this from a shell whose `SSH_AUTH_SOCK` points to the intended agent. The +command stores that path, not a reference to the variable. + +When this setting is empty, Docker Sandboxes uses the `SSH_AUTH_SOCK` value +supplied by each client. On Windows, if `SSH_AUTH_SOCK` is also unset, it uses +the `\\.\pipe\openssh-ssh-agent` named pipe. This works with Windows OpenSSH +and with 1Password's SSH agent when it provides that pipe. The host agent must +be running. Set `SSH_AUTH_SOCK` or configure `ssh.agentSocketPath` to use a +different agent. + +Remove the fixed path with `sbx settings unset ssh.agentSocketPath` and restart +the daemon to update existing forwarders. + +### Images and storage + +#### platform.images.registryMirror {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Use this when your organization routes Docker Hub pulls through a registry +mirror. Specify a host, optionally with a port and path prefix, without a URL +scheme: + +```console +$ sbx settings set platform.images.registryMirror registry.example.com/docker-remote +``` + +The mirror applies to template and kit references that resolve to Docker Hub. +References to other registries stay unchanged. An empty value disables +mirroring. + +A bare, non-loopback host can also configure Docker pulls inside sandboxes +created after the change. A mirror with a path prefix doesn't configure those +pulls. See [registry mirrors](registry-mirror.md) for authentication, certificate +requirements, and how to apply changes to existing sandboxes. + +#### platform.images.useDHI {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_USE_DHI" >}} + +Turn this on to use Docker Hardened Image variants when creating sandboxes +with default agent templates: + +```console +$ sbx settings set platform.images.useDHI true +``` + +For example, the default template `docker/sandbox-templates:claude-code-docker` +becomes `dhi/sbx-templates:claude-code-docker`. The image tag stays the same. +An explicit `--template` or a custom kit image takes precedence. + +Existing sandboxes keep their template. Create a sandbox after changing the +setting to use the selected image variant. + +#### sandbox.disk.dockerVolume {.wrap-anywhere} + +{{< setting-metadata type="string" default="10g" >}} + +Increase this default if sandboxes need more room for Docker images, +containers, and volumes under `/var/lib/docker`. The minimum is 512 MiB: + +```console +$ sbx settings set sandbox.disk.dockerVolume 20g +``` + +The size applies when creating a sandbox. It doesn't resize existing volumes +or increase the size of the sandbox workspace. + +To choose a size for one sandbox without changing the default: + +```console +$ DOCKER_SANDBOXES_DOCKER_SIZE=30g sbx create claude ~/my-project +``` + +This variable applies to that creation command. It doesn't change the value +reported by `sbx settings get sandbox.disk.dockerVolume`. + +### Kits + +#### kit.allowedSources {.wrap-anywhere} + +{{< setting-metadata type="JSON" default="[\"docker.io/\"]" + env="DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES" >}} + +Add a publisher here before installing its kits from a remote registry or Git +repository. The value replaces the entire allowlist, so retain any sources you +still need: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/myorg/"]' +``` + +Prefixes match on a path-segment boundary: `github.com/myorg/` permits that +organization's repositories, but not `github.com/myorg-other/`. The value +`["*"]` permits any remote source. Local directories and ZIP files are controlled +by [kit.allowLocalKits](#kitallowlocalkits), and pinned agent kits have the +[kit.allowExtractedAgents](#kitallowextractedagents) exception. + +See [restrict kit sources](../customize/use-kits.md#restrict-kit-sources) for source +formats and examples. + +#### kit.allowLocalKits {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="true" + env="DOCKER_SANDBOXES_KIT_ALLOW_LOCAL" >}} + +Set this to `false` to require kits to come from a remote source instead of a +local directory or ZIP file: + +```console +$ sbx settings set kit.allowLocalKits false +``` + +Remote sources must still satisfy [kit.allowedSources](#kitallowedsources). +Keep this enabled while developing kits locally. Allowing local kits doesn't +exempt them from signature requirements when +[kit.requireSignature](#kitrequiresignature) is enabled. + +#### kit.allowExtractedAgents {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="true" + env="DOCKER_SANDBOXES_KIT_ALLOW_EXTRACTED_AGENTS" >}} + +Some agents that previously shipped inside Docker Sandboxes are distributed +as kits. By default, Docker Sandboxes permits the exact pinned references it +uses for those agents even if their sources aren't in `kit.allowedSources`, +and exempts them from `kit.requireSignature`. + +To apply your source and signature requirements to those kits too: + +```console +$ sbx settings set kit.allowExtractedAgents false +``` + +After this change, launching one of those agents can fail unless you allow its +source and, when signatures are required, it has a signature from a trusted +signer. The default exception applies only to the pinned references, not to +other kits from the same publisher. + +#### kit.requireSignature {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_KIT_REQUIRE_SIGNATURE" >}} + +Turn this on to reject unsigned kits and kits whose signatures don't match +your trusted signers. Configure [kit.trustedSigners](#kittrustedsigners) first, +then require signatures: + +```console +$ sbx settings set kit.requireSignature true +``` + +The check applies when installing kits from local directories, Git, or OCI +registries. ZIP kits can't carry verifiable signatures and are rejected. +Pinned agent kits remain exempt while +[kit.allowExtractedAgents](#kitallowextractedagents) is `true`. + +A signature covers the kit's `spec.yaml` and `files/` content. It doesn't pin +image tags or verify downloads performed by the kit's commands. See +[sign and verify kits](../customize/kits-v2.md#sign-and-verify-kits). + +#### kit.trustedSigners {.wrap-anywhere} + +{{< setting-metadata type="JSON" default="Docker employee identities" + env="DOCKER_SANDBOXES_KIT_TRUSTED_SIGNERS" >}} + +Set the identities or public keys whose kit signatures you trust. The value is +a JSON array. Each entry describes either a keyless signer or a public key, and +a signature can match any entry. + +For a keyless signer, specify both the identity and its OpenID Connect issuer: + +```console +$ sbx settings set kit.trustedSigners \ + '[{"identity":"release-bot@example.com","issuer":"https://accounts.google.com"}]' +``` + +For a public key: + +```console +$ sbx settings set kit.trustedSigners '[{"key":"/path/to/cosign.pub"}]' +``` + +Each command replaces the whole list. To trust both, include both objects in +one array. The default policy trusts Docker employee identities ending in +`@docker.com`, attested by Google's issuer. Setting trusted signers alone +doesn't require signatures: also enable +[kit.requireSignature](#kitrequiresignature). + +#### kit.ignoreTransparencyLog {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_KIT_IGNORE_TLOG" >}} + +Use this for private kits whose keyless signatures were created with +`--tlog-upload=false`, so verification doesn't require a public Rekor +transparency log entry: + +```console +$ sbx settings set kit.ignoreTransparencyLog true +``` + +Signature and signer verification still apply. These signatures must provide a +timestamp from a timestamp authority instead of a transparency log timestamp. +Leave this at `false` when your signing workflow uses the public transparency +log. It has no effect on signatures verified with a public key. + +### MCP gateway + +#### mcp.forceLocalGateway {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" >}} + +Set this to `true` to use the local MCP gateway when your account would +otherwise use the SaaS gateway: + +```console +$ sbx settings set mcp.forceLocalGateway true +$ sbx daemon restart +``` + +The daemon caches its gateway selection, so a restart is required after changing +this setting. It doesn't override a gateway selected by organization governance. +Set it back to `false` and restart to return to automatic selection. See +[MCP gateway](../mcp-gateway.md) for server registration and agent setup. + +### Daemon logging + +These settings control rotation of `daemon.log`, not logs written by the CLI +or processes inside a sandbox. Changes take effect after `sbx daemon restart`. +The backup count and age limits apply together: a rotated log is removed when +it exceeds either limit. + +#### daemon.log.maxSizeMB {.wrap-anywhere} + +{{< setting-metadata type="integer" default="50" >}} + +Set the size in MB at which the daemon log rotates. The minimum is `1`: + +```console +$ sbx settings set daemon.log.maxSizeMB 100 +$ sbx daemon restart +``` + +#### daemon.log.maxBackups {.wrap-anywhere} + +{{< setting-metadata type="integer" default="3" >}} + +Set the maximum number of rotated daemon logs to keep. The value must be zero +or greater. A value of `0` removes the count limit, but the age limit still +applies: + +```console +$ sbx settings set daemon.log.maxBackups 5 +$ sbx daemon restart +``` + +#### daemon.log.maxAgeDays {.wrap-anywhere} + +{{< setting-metadata type="integer" default="0" >}} + +Set how many days to keep rotated daemon logs, from `0` to `3650`. A value of +`0` removes the age limit, but the backup count limit still applies: + +```console +$ sbx settings set daemon.log.maxAgeDays 30 +$ sbx daemon restart +``` + +### Diagnostics + +#### diagnostics.autoUpload {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Choose whether Docker Sandboxes may automatically upload diagnostic bundles +after eligible daemon errors: + +- `yes`: Consent to automatic uploads. +- `no`: Decline automatic uploads and suppress further consent prompts. +- Empty string: No recorded decision. Docker Sandboxes may prompt for consent, + but doesn't automatically upload without it. + +For example, decline automatic uploads: + +```console +$ sbx settings set diagnostics.autoUpload no +``` + +Use `sbx settings unset diagnostics.autoUpload` to clear the decision. Read +[automatic diagnostics uploads](../troubleshooting.md#enable-automatic-diagnostics-uploads) +for what bundles contain before opting in. This controls automatic uploads, +not an explicit `sbx diagnose --upload` request. + +#### diagnostics.autoUploadErrorCooldownInDays {.wrap-anywhere} + +{{< setting-metadata type="integer" default="1" >}} + +Increase this value to upload automatic diagnostic bundles less frequently. +For example, allow at most one automatic upload per seven days: + +```console +$ sbx settings set diagnostics.autoUploadErrorCooldownInDays 7 +``` + +The cooldown applies across all eligible errors, not separately to each error +type. Values below one are treated as one day. This setting doesn't grant +upload consent: [diagnostics.autoUpload](#diagnosticsautoupload) must be `yes`. + +### Upstream proxies and TLS + +Upstream proxy support is experimental. Use these settings to control how +outbound traffic reaches the network. See [upstream proxies](upstream-proxy.md) +for setup and [when changes take effect](upstream-proxy.md#when-changes-take-effect). + +The standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables and their +lowercase forms are fallbacks for proxy selection, not direct overrides of the +`proxy` and `no_proxy` settings. + +#### proxy {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Set a shared upstream proxy when both sandbox traffic and host-side Docker +Sandboxes traffic should pass through it: + +```console +$ sbx settings set proxy http://proxy.corp:3128 +$ sbx daemon restart +``` + +The value can be an HTTP, HTTPS, or SOCKS5 proxy URL, a PAC source, `system` to +use the operating system's proxy, or `direct` to bypass upstream proxies. An +empty value falls back to the standard proxy environment variables and then the +operating system's proxy settings. + +The scope-specific settings below take precedence over this shared value. +See [proxy value formats](upstream-proxy.md#set-a-proxy-manually) and +[proxy precedence](upstream-proxy.md#precedence). + +#### proxy.sandbox {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" + env="DOCKER_SANDBOXES_PROXY" >}} + +Use this when traffic from inside sandboxes needs a different route from the +daemon and CLI. For example, send sandbox traffic through a SOCKS5 proxy: + +```console +$ sbx settings set proxy.sandbox socks5h://proxy.corp:1080 +$ sbx daemon restart +``` + +With `socks5h://`, the proxy resolves destination names. Use `direct` to bypass +the shared proxy for sandbox traffic, or unset this setting to inherit `proxy`. +It doesn't affect daemon traffic. Sandboxes created after the change use the +updated value; existing sandbox proxies require a daemon restart. + +#### proxy.daemon {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Use this to route the daemon's requests, such as image pulls, separately from +sandbox traffic. Host CLI connections, including connections to cloud sandboxes, +also use this scope. See [traffic scopes](upstream-proxy.md). + +For example, keep a shared proxy for sandbox traffic while letting the daemon +connect directly: + +```console +$ sbx settings set proxy.daemon direct +$ sbx daemon restart +``` + +Unset this setting to inherit `proxy`. Supported CLI requests use changes on +the next invocation; the daemon's own requests require a restart. + +#### proxy.sshDirect {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" >}} + +Set this to `true` to bypass the upstream proxy for cloud SSH connections. +Other host CLI requests keep using the configured proxy. Changes apply on the +next SSH connection without a daemon restart. For setup, see +[Cloud SSH](upstream-proxy.md#cloud-ssh). + +#### no_proxy {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +List destinations that should bypass the selected upstream proxy. Use a +comma-separated string of hosts, domain suffixes, IP addresses, or CIDR ranges: + +```console +$ sbx settings set no_proxy "registry.internal,10.0.0.0/8" +$ sbx daemon restart +``` + +This shared list applies to sandbox and daemon traffic unless a scope-specific +list replaces it. A value of `*` bypasses the upstream proxy for all destinations. +Proxy exclusions don't grant network access: sandbox requests must still pass +[network policy](../governance/access-controls/network.md). + +#### no_proxy.sandbox {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" + env="DOCKER_SANDBOXES_NO_PROXY" >}} + +Use this when only sandbox traffic should bypass the upstream proxy for a set +of destinations. For example, connect directly to cluster services: + +```console +$ sbx settings set no_proxy.sandbox "*.svc.cluster.local" +$ sbx daemon restart +``` + +A non-empty value replaces the shared `no_proxy` list for sandbox traffic; it +doesn't append to it. Include any shared exclusions that sandboxes still need. +Unset it to inherit `no_proxy` again. Existing sandbox proxies require a daemon +restart. + +#### no_proxy.daemon {.wrap-anywhere} + +{{< setting-metadata type="string" default="Empty string" >}} + +Use this when the daemon and supported CLI requests need different proxy +exclusions from sandbox traffic. For example, pull images directly from an +internal registry: + +```console +$ sbx settings set no_proxy.daemon "registry.internal" +$ sbx daemon restart +``` + +A non-empty value replaces the shared `no_proxy` list for this scope. It doesn't +change sandbox exclusions. Unset it to inherit `no_proxy` again. Supported CLI +requests use changes on the next invocation; daemon requests require a restart. + +#### proxy.integratedAuth {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" >}} + +Turn this on when a corporate proxy requires NTLM or Kerberos authentication +using your Windows sign-in identity: + +```console +$ sbx settings set proxy.integratedAuth true +$ sbx daemon restart +``` + +It applies to both sandbox and daemon proxy traffic. Authentication happens on +the host, so the Windows credentials don't enter the sandbox. It has no effect +on macOS or Linux. For cross-platform authentication with credentials in a +proxy URL, see [proxy authentication](upstream-proxy.md#authentication). + +#### tls.allowNegativeSerial {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" + env="DOCKER_SANDBOXES_TLS_ALLOW_NEGATIVE_SERIAL" >}} + +Use this compatibility setting when HTTPS requests fail with +`x509: negative serial number` because a TLS-inspecting proxy issues +certificates with negative serial numbers: + +```console +$ sbx settings set tls.allowNegativeSerial true +$ sbx daemon restart +``` + +It relaxes certificate validation to accept those serial numbers. It doesn't +make an untrusted certificate authority trusted or resolve other certificate +errors. For an untrusted internal CA, see +[certificate troubleshooting](../troubleshooting.md#api-calls-fail-with-a-certificate-error). + +### Shared agent skills + +Shared agent skills are experimental. + +#### skills.defaultMode {.wrap-anywhere} + +{{< setting-metadata type="string" default="readonly" >}} + +Choose how future sandboxes use the shared agent skills store when you omit +`--skills`: + +- `readonly`: Agents can read shared skills but can't change the store. +- `readwrite`: Agents can read and modify skills used by other sandboxes. +- `off`: Don't mount the shared store. + +For example, omit the shared store by default: + +```console +$ sbx settings set skills.defaultMode off +``` + +An explicit `--skills` value or environment-file `skills` value overrides this +default. Existing sandboxes retain their mounts: recreate them to change their +access mode. See [share agent skills](../workflows/agent-skills.md) for setup +and the consequences of sharing a writable store. + +## Command reference + +### sbx settings ls + +List settings. Alias: `sbx settings list`. + +Use `--json` for complete records as JSON, or `--no-trunc` for full text. These +options are mutually exclusive. + +### sbx settings get \<KEY\> + +Print one effective value. + +Use `--json` for the complete setting record. + +### sbx settings set \<KEY\> \<VALUE\> + +Write a user override. + +Values are parsed as `bool`, `int`, `float`, `string`, or `json`, according to +the setting's type. + +### sbx settings unset \<KEY\> + +Remove a user override. + +Use `sbx settings <COMMAND> --help` for command help. diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md new file mode 100644 index 000000000000..93514fe688d8 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -0,0 +1,199 @@ +--- +title: Configure an upstream proxy +linkTitle: Upstream proxy +description: Route local sandbox, daemon, and host CLI traffic through an upstream proxy, including cloud connections, PAC files, SOCKS5, and your OS system proxy. +keywords: docker sandboxes, sbx, upstream proxy, corporate proxy, pac, socks5, system proxy, no_proxy, egress, ntlm, kerberos +weight: 40 +aliases: + - /ai/sandboxes/upstream-proxy/ +--- + +This page describes proxy settings for local sandboxes, the local daemon, and +host CLI connections to cloud sandboxes. These settings don't configure traffic +originating inside a cloud sandbox. For cloud sandbox egress controls, see +[Cloud network policy](../cloud/network-policy.md). + +> [!IMPORTANT] +> Upstream proxy support is experimental. Everything described on this page — +> proxy URLs, PAC files, SOCKS5, use of the OS system proxy, proxy +> authentication, and the settings that configure them — is subject to change. +> Share feedback and bug reports in the +> [docker/sbx-releases](https://github.com/docker/sbx-releases) repository. + +An upstream proxy is the corporate or network proxy that Docker Sandboxes +forwards outbound traffic through on its way to the internet. This is separate +from the [network policy](../governance/access-controls/network.md), which decides +_which_ destinations are allowed. The upstream proxy decides _how_ allowed +traffic reaches them. + +Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them +independently: + +- Sandbox traffic — network access from inside your local sandboxes. +- Daemon and host CLI traffic — the daemon's own access, including image pulls, + telemetry, and feature flags, and host CLI requests, including `sbx login`, + `sbx diagnose --upload`, cloud commands, `sbx move`, the TUI, and cloud SSH. + +## Default behavior + +By default, both kinds of traffic use your operating system's proxy settings, +including any PAC URL configured there. You don't need to configure anything. On +macOS and Windows, `sbx` tracks the OS proxy setting while it runs, so a change +to your network, VPN, or PAC configuration is picked up without a restart. If +your OS has no proxy configured, traffic goes direct. + +## Set a proxy manually + +Use [`sbx settings set`](settings.md#change-a-setting) to override the default +for one or both kinds of traffic: + +```console +$ sbx settings set proxy http://proxy.corp:3128 # both kinds of traffic +$ sbx settings set proxy.sandbox socks5://proxy.corp:1080 # sandbox traffic only +$ sbx settings set proxy.daemon direct # daemon traffic only +``` + +A proxy value can be any of the following: + +| Value | Meaning | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| _(unset)_ | Fall back to the wider scope, then environment variables, then the OS system proxy (the default) | +| `http://host:port` or `https://host:port` | An HTTP or HTTPS proxy | +| `socks5://host:port` or `socks5h://host:port` | A SOCKS5 proxy | +| `pac+http://host/proxy.pac`, `pac+https://host/proxy.pac`, or `file:///path/proxy.pac` | A PAC (proxy auto-config) file | +| `system` | Force the use of the OS system proxy | +| `direct` | Force a direct connection with no proxy | + +With `socks5://`, DNS is resolved locally before the connection is handed to the +proxy. With `socks5h://`, DNS resolution is delegated to the proxy. + +### Exclude destinations from the proxy + +Exclusion lists mirror the same scopes. Each takes a comma-separated list of +hosts, domain suffixes, IP addresses, or CIDR ranges, or `*` to bypass the +proxy entirely: + +```console +$ sbx settings set no_proxy "*.internal.corp,10.0.0.0/8" # both kinds of traffic +$ sbx settings set no_proxy.sandbox "*.svc.cluster.local" # sandbox traffic only +$ sbx settings set no_proxy.daemon "registry.internal" # daemon traffic only +``` + +## Environment variables + +Because `sbx` runs from your shell, it also honors the standard and legacy proxy +environment variables, so existing setups keep working without migration: + +- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (and their lowercase forms) — the + standard variables. They apply to both kinds of traffic when no `proxy` or + `no_proxy` setting is configured. +- `DOCKER_SANDBOXES_PROXY` and `DOCKER_SANDBOXES_NO_PROXY` — the environment + form of `proxy.sandbox` and `no_proxy.sandbox`. They apply to sandbox traffic + only and never affect daemon traffic. + +For how to apply environment variable changes to the CLI and daemon, see +[Settings environment variables](settings.md#environment-variables). + +## Precedence + +For each kind of traffic, the first match wins: + +1. The scope-specific value: + - `proxy.sandbox` or `DOCKER_SANDBOXES_PROXY` for sandbox traffic + - `proxy.daemon` for daemon traffic +2. The `proxy` setting +3. `HTTP_PROXY` or `HTTPS_PROXY` from the shell +4. The OS system proxy (the default) +5. Direct + +The matching exclusion list (`no_proxy.<scope>`, then `no_proxy`) applies to the +chosen proxy, and the standard `NO_PROXY` variable still applies on the +environment path. + +For example, if `proxy` specifies a shared proxy and `proxy.sandbox` is set to +`direct`, sandbox traffic connects directly while daemon traffic uses the +shared proxy. If no proxy setting is configured, `HTTP_PROXY` takes precedence +over the OS system proxy. + +## When changes take effect + +Proxy settings take effect at different times depending on the consumer: + +- Sandbox scope (`proxy.sandbox`, `no_proxy.sandbox`, and the sandbox side of + `proxy` and `no_proxy`) is resolved when a sandbox network proxy is created. + Sandboxes you create after a change use the updated settings. Existing + sandboxes retain their selected upstream proxy until `sbx daemon restart` + rebuilds their network proxies. Restarting a sandbox alone is insufficient. +- Daemon scope (`proxy.daemon`, `no_proxy.daemon`, and the daemon side of + `proxy` and `no_proxy`) is resolved once when the daemon starts. Changes to + the daemon's own traffic require `sbx daemon restart`. +- Host CLI clients read daemon-scoped settings on each invocation. Changes + apply on the next invocation without a daemon restart. + +The `DOCKER_SANDBOXES_*` environment variables are a separate case. They control +sandbox traffic only, as described in +[Environment variables](#environment-variables), but `sbx` reads them from the +daemon's environment as the daemon starts, so changing one also requires a +daemon restart. If one of these variables overrides a stored setting, unset +the variable and restart the daemon for the stored setting to take effect. + +When a `system` or PAC proxy is in use, `sbx` still tracks OS-level proxy changes +(such as switching networks, connecting a VPN, or updated PAC contents) live. + +## Cloud SSH + +Cloud SSH uses the configured host proxy to connect to the SSH gateway. Some +proxies refuse connections to the gateway's SSH port. If your network permits +direct SSH connections, bypass the proxy for cloud SSH: + +```console +$ sbx settings set proxy.sshDirect true +``` + +This setting skips the proxy entirely for cloud SSH, without trying it first. +Other host CLI requests keep using the configured proxy. The change applies on +the next SSH connection without a daemon restart. Set it to `false` to use the +proxy again. + +## Authentication + +If the upstream proxy requires you to authenticate to it, `sbx` supports two +mechanisms. + +### Credentials in the proxy URL + +Put the credentials in the proxy URL: `http://user:pass@host:port` for an HTTP +or HTTPS proxy, or `socks5://user:pass@host:port` for SOCKS5. This works on all +platforms and covers proxies that challenge with Basic authentication. + +### Integrated Windows authentication + +Proxies that answer `CONNECT` with a `407` challenge and accept only integrated +schemes — NTLM or Kerberos/Negotiate — can instead authenticate you with your +Windows sign-in identity. This is opt-in and off by default: + +```console +$ sbx settings set proxy.integratedAuth true +``` + +The setting isn't scoped: it applies to both sandbox and daemon traffic. If the +proxy offers several schemes, the strongest one is used, preferring Negotiate +over NTLM. Changes follow the same +[schedule as other proxy settings](#when-changes-take-effect): on the next +invocation for supported CLI clients, when you create a sandbox, and after +`sbx daemon restart` for daemon traffic and existing sandbox proxies. + +Your identity stays on the host. Authentication to the upstream proxy happens +on the host side of the sandbox boundary, after network policy has already been +applied, so no credential enters the sandbox and nothing about which +destinations a sandbox may reach changes. + +This depends on Windows SSPI, so it has no effect on macOS or Linux. On those +platforms, credentials in the proxy URL remain the only option. + +## Related pages + +- [Network isolation](../security/isolation.md) — how traffic leaves a sandbox and + the network policy it passes through +- [Troubleshooting: API calls fail with a certificate error](../troubleshooting.md#api-calls-fail-with-a-certificate-error) + — installing an internal root CA when your proxy inspects HTTPS traffic diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index 5d1b7a30d824..22c51638efe6 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -1,70 +1,123 @@ --- -title: Customizing sandboxes -linkTitle: Customize -description: Build reusable sandbox images, extend agents with tools and credentials, and define custom agents using templates and kits. -keywords: sandboxes, sbx, customize, templates, kits, mixins, custom agents -weight: 35 +title: Kits +description: Use sandbox kits and share environments as kit sets composed from workloads and mixins. +keywords: sandboxes, sbx, kits, v3, workloads, mixins +weight: 90 +linkTitle: Kits aliases: - /ai/sandboxes/agents/custom-environments/ -params: - sidebar: - badge: - color: blue - text: Early Access --- {{< summary-bar feature_name="Docker Sandboxes sbx" >}} -Docker Sandboxes offers two ways to customize a sandbox beyond the built-in -defaults: - -- [Templates](templates.md) — reusable sandbox images with tools, packages, - and configuration baked in. Extend a base image with a Dockerfile, or - save a running sandbox as a template. -- [Kits](kits.md) — declarative YAML artifacts that extend an agent with - tools, credentials, network rules, and files at runtime, or define a new - agent from scratch. - -Kits are experimental. The kit file format, CLI commands, and experience for -creating, loading, and managing kits are subject to change as the feature -evolves. Share feedback and bug reports in the -[docker/sbx-releases](https://github.com/docker/sbx-releases) repository. - -## Templates and kits, side by side - -A template is a Docker image that the sandbox runs. It's built ahead -of time with a Dockerfile (or saved from a running sandbox), pushed to a -registry, and pulled when a sandbox is created. Use templates for things -that belong in an image: system packages, language toolchains, large -dependencies — anything you'd rather not reinstall on every sandbox start. - -A kit is a YAML artifact applied at sandbox creation. The kit can run -install commands, drop files into the sandbox, declare network and -credential rules, and (for agent kits) define which template image the -agent runs in. Use kits for things that vary per agent or per team: -shared linter config, project-specific install steps, credential -injection for a service the agent talks to. - -Templates and kits work together. An agent kit's `agent.image` field -points at a template: the template provides the base environment, the -kit layers config, secrets, and runtime behavior on top. A team can ship -one heavy template and several thin kits without rebuilding the image -each time something changes. - -## When to use which - -| Goal | Option | -| --------------------------------------------------------- | ------------------------------------------------------------- | -| Pre-install tools and packages into a reusable base image | [Template](templates.md) | -| Capture a configured running sandbox for reuse | [Saved template](templates.md#saving-a-sandbox-as-a-template) | -| Add a tool, credential, or config to agent runs via YAML | [Kit (mixin)](kits.md) | -| Define a new agent from scratch | [Kit (agent)](kits.md#defining-an-agent) | - -Templates and kits can be used together. A template bakes heavy tools into -the image for fast sandbox startup; a kit layered on top adds per-run -credentials, config, or extra capabilities. - -## Tutorials - -- [Build your own agent kit](build-an-agent.md) — step-by-step walkthrough - for packaging [Amp](https://ampcode.com/) as an agent kit. +Kits let you shape a sandbox around the way you work. Use a custom base image, +add the tools your project needs, and give your agent instructions for using +them. You also control which services the sandbox can access, how it +authenticates, and what runs when the sandbox starts. + +A kit can define the whole environment or add something to an existing one, +such as a toolchain or your team's shared configuration. Package those choices +once, then reuse them across projects and share them with your team. + +To keep the configuration for a sandbox in an editable, shareable file, use a +[sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md). +It selects kits alongside workspace paths, resources, credentials, and lifecycle +commands. Keep a tool's requirements in its kit so they follow the tool across +environments. Use the environment file for the choices involved in setting up +your sandbox. + +Docker recommends v3 kits. This section covers v3. For the supported v2 +format, see [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md). + +## What is a kit? + +A kit packages software and configuration for a sandbox. A YAML file, called +its descriptor, tells Docker Sandboxes what the kit needs: network access, +credentials, setup commands, or instructions for the agent. You publish the +kit as a container image containing its files and descriptor. + +You identify a published kit by its container image reference, such as +`docker.io/docker/sbx-kit-claude:2.1.267`. When you use the kit, `sbx` +prepares its files and applies its settings. You can use one kit for a +complete environment or combine kits that contribute different parts. + +## What kits can do + +Use kits to: + +- Package a custom agent, or configure an existing agent for your team's + projects. +- Include the tools the agent needs, such as linters, language runtimes, + test runners, and compilers. +- Share linter rules, editor settings, helper scripts, and reference material. + Give the agent instructions and skills for using them. +- Connect the agent to services through network rules and credentials, + including internal APIs and private package registries. +- Initialize each sandbox and run supporting services when it starts, such + as a development server for previewing the agent's work. + +## Workloads and mixins + +Kits have two roles in a sandbox: a workload supplies the base environment +and launch command, and mixins add tools or behavior to it. + +| Kind | What it supplies | How you use it | +| --- | --- | --- | +| `workload` | The environment and command to run, such as an agent or a shell | Pass it to `sbx run` or `sbx create` | +| `mixin` | Additional tools, configuration, or runtime behavior | Add it with `--kit` | + +For example, this command runs a workload with a mixin: + +```console +$ sbx run docker.io/docker/sbx-kit-claude:2.1.267 --kit docker.io/sbx/playwright:1.61.1 +``` + +The Claude Code workload starts the agent, and the Playwright mixin adds +browser-testing tools. + +## Kit sets + +A kit set combines kits into a single kit that you can publish and reuse. +Use it to package a workload with the mixins you need, so you and your team +can run the environment from one reference. + +The set specifies which kits and versions to combine. It can also add setup +commands, agent instructions, network access, and other settings for the +combined environment. + +If the set includes a workload, you run the published kit with `sbx run`. +If it contains only mixins, you add it to a workload with `--kit`. + +An environment file can select individual kits or a published set. Choose a set +when you want one published reference with a fixed list of components. The set +records their image digests when you build it. + +See [Use kits](/manuals/ai/sandboxes/customize/use-kits.md) for how to run kits +and add mixins. To customize and publish your own combination, see +[Compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). + +## Version compatibility + +V3 requires `sbx` v0.45 or later. Every kit in a v3 sandbox must use v3: +select a v3 workload and add only v3 mixins. + +Built-in agent names such as `claude` and `codex` select v2 kits, so +`sbx run claude --kit ./some-v3-mixin` fails. To use that mixin, choose a +[v3 workload](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads) +by its image, local path, or Git reference. + +A kit's capabilities can require a later release or a local sandbox. See +[Kit capability support](/manuals/ai/sandboxes/customize/author/capabilities.md) +for details. V2 remains supported and is not deprecated. + +## Choose your next step + +- [Use kits](/manuals/ai/sandboxes/customize/use-kits.md) to run a published environment or combine + a workload with mixins. +- [Author kits](/manuals/ai/sandboxes/customize/author/_index.md) to build an agent environment, + package a tool, or combine kits into a set to share with your team. +- Explore the [sandbox-kit-spec repository](https://github.com/docker/sandbox-kit-spec) + for the authoritative v3 specification, build frontend, and examples. + +To save an environment you've configured inside a sandbox, +see [Save a sandbox as a template](/manuals/ai/sandboxes/usage.md#saving-a-sandbox-as-a-template). diff --git a/content/manuals/ai/sandboxes/customize/author/_index.md b/content/manuals/ai/sandboxes/customize/author/_index.md new file mode 100644 index 000000000000..525d4c915b17 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/_index.md @@ -0,0 +1,235 @@ +--- +title: Author kits +description: Build and share sandbox environments with kits. Choose a tutorial, organize your source files, and decide what happens during build and setup. +keywords: sandboxes, sbx, kits, v3, workloads, mixins +weight: 20 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Build a kit to give your team a repeatable sandbox environment. You can +package an agent, add a tool to use with different agents, or combine existing +kits into one kit your team can run. The guides in this section walk through +each approach. + +> [!NOTE] +> Select a v3 workload and v3 mixins together. +> Built-in shortcuts such as `claude` and `codex` use v2 and can't be combined +> with v3 mixins. See [Version compatibility](/manuals/ai/sandboxes/customize/_index.md#version-compatibility) +> or the [v2 reference](/manuals/ai/sandboxes/customize/kits-v2.md). + +## Choose what to author + +- [Compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md) to combine + kits you've published or chosen from a registry. A set can also add network + access, setup commands, and agent instructions, and let users choose settings + such as which model to use. +- [Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md) to + package a reusable tool with its network access and credentials. +- [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md) + to control the base environment, agent installation, and launch command. + You can also [use an existing agent image](/manuals/ai/sandboxes/customize/author/base-images.md#use-an-image-in-a-v3-workload). + +For complete kits you can study and adapt, see +[Kit examples](https://github.com/docker/sandbox-kit-spec/tree/main/examples) +in the Docker Sandbox Kit Specification repository. + +## Directory and build layout + +Keep each kit's source in its own directory. A kit usually starts with two +files: + +- A YAML descriptor identifies the kit as a workload, mixin, or set and + declares its settings and requirements. +- A Dockerfile installs software and copies files into the image. + +Use the kit's name for the directory and descriptor. If the kit has a +Dockerfile, use the same filename stem as the descriptor: `my-kit.yaml` +pairs with `my-kit.dockerfile`. + +For example: + +```text +my-kit/ +├── my-kit.yaml +├── my-kit.dockerfile +├── context.md +└── files/ + └── settings.json +``` + +Organize supporting files in whatever way suits your kit. This example keeps +agent instructions in `context.md` and configuration files under `files/`. + +### How the files work together + +The Dockerfile defines what goes into the image, such as installed tools +and configuration files. For a workload, it also sets the command to launch. +The YAML descriptor defines the kit's settings and requirements, such as +network access, credentials, and agent instructions. + +The descriptor starts with a syntax declaration: + +```yaml +# syntax=docker/sandbox-kit:3 +``` + +This selects the kit build frontend, which reads the descriptor and its +matching Dockerfile. The build produces a container image containing the +software, supporting files, and validated descriptor. + +A kit set uses the descriptor's `kits:` list to combine published kits. + +### Build and use the kit + +When building with Docker Buildx, pass the YAML descriptor to `-f` and +the source directory as the build context: + +```console +$ docker buildx build -f my-kit/my-kit.yaml -t my-kit:dev my-kit/ +``` + +You can also give `sbx` a reference to a local kit directory. It builds the kit +when creating the sandbox. After publishing the image to a registry, you can +use its image reference instead. + +For build options and publishing instructions, see +[Build and distribute kits](/manuals/ai/sandboxes/customize/author/distribute.md). + +### Other source layouts + +The separate descriptor and Dockerfile are one way to organize a kit. +You can also write a Dockerfile inline under `build: |`, select one with +`dockerfile:`, or embed the descriptor in a Dockerfile comment. + +See [Authoring forms](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#3-authoring-forms) +for the syntax. + +## Capabilities + +Installing a tool is often only part of the job. The tool might also need to +reach an API, authenticate with a credential, or run a setup command before +the agent starts. Describe those needs in the descriptor's `capabilities` +list. Each entry asks Docker Sandboxes to provide one of these features. + +A kit's Dockerfile defines how its image is built. Its capabilities describe +what Docker Sandboxes needs to do when preparing and running the sandbox. +For example, a tool mixin can install an API client through its Dockerfile +and use a network capability to request access to that API. Building or +running the image with Docker alone doesn't apply these capability settings. + +You can add capabilities to a workload, mixin, or set. Keep each request with +the kit that needs it, so a tool's access rules follow it when you use it with +another agent. + +Each capability entry identifies the feature in `type`. Capabilities that +need settings take them in `config`. For example, `com.docker.sandbox/network-policy@1` +requests network access, and its `config` lists the domains to allow. + +The `@1` identifies the capability's version. It is independent of the kit +format version and the `sbx` release. The +[upstream capability definitions](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#72-well-known-types) +describe the available capabilities and their settings. + +See [Capability support](capabilities.md) for local and cloud availability, +minimum `sbx` versions, and Docker-specific restrictions. + +The guides here show how to use capabilities with Docker Sandboxes. For all +descriptor fields and the rules for combining kits, see the +[upstream v3 specification](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md). + +## Choose when setup runs + +Install tools and copy static files during the image build so you can reuse +them in every sandbox. Some setup needs to wait until the sandbox exists. For +example, a mixin can bring a CA certificate, but it needs the workload's tools +to register that certificate. Use a lifecycle capability to run commands or +generate files at the right point: + +| Where to put the work | When it runs in `sbx` | Example | +| --- | --- | --- | +| Dockerfile `RUN` and `COPY` | Image build | Install a tool and copy its default configuration | +| Lifecycle `install` hooks | Once during sandbox creation, before the agent launches | Register a CA or populate a mounted directory | +| Lifecycle `files` | During creation, after install hooks and before the agent launches | Generate settings from kit arguments | +| Lifecycle `startup` hooks | Every sandbox start, alongside the agent | Start a background service or refresh state after a restart | + +Lifecycle hooks are commands that run during sandbox creation or startup. +Make startup hooks safe to run more than once. In `sbx`, they run alongside +the agent, so the agent might start before they finish. If a command must +finish before every agent launch, put it in the workload's entrypoint instead. + +### Pass environment variables to hooks + +In `sbx`, install hooks receive a limited set of environment variables: +basic process variables, proxy settings, and certificate paths. If your command needs another +variable, name it in the hook's `env` list. For example, `env: [WORKSPACE_DIR]` +gives the command the mounted workspace's path. In `sbx`, startup hooks receive +the sandbox's environment without this filtering. + +Sandbox containers set `SBX_AGENT` to the provisioned agent's name, such +as `claude` or `codex`. For a v3 workload from a registry, the value is the +last component of the kit's repository name. For example, +`sbx run --name foo docker.io/me/my-custom-kit` sets `SBX_AGENT` to +`my-custom-kit`. The `--name` flag names the sandbox and does not change +`SBX_AGENT`. + +Use `SBX_AGENT` in hooks or scripts that need different behavior for different +agents. Add `SBX_AGENT` to an install hook's `env` list to make it available +to that hook. Startup hooks receive it without that declaration. + +See [Kit authoring patterns](/manuals/ai/sandboxes/customize/author/patterns.md#run-setup-after-combining-kits) +for setup examples and the upstream +[lifecycle definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md) +for the fields. + +### Generated files + +In lifecycle `files` content, write `${{ kit.env.NAME }}` to insert a +container environment variable. For example, write +`${{ kit.env.WORKSPACE_DIR }}` for the workspace path. Plain `$VAR` and +`${VAR}` are written unchanged, without substituting their values. In hook +commands, use shell syntax such as `$WORKSPACE_DIR` instead. + +Docker Sandboxes substitutes `${{ kit.env.NAME }}` once, when it creates the +sandbox. `kit.env` reads the final container environment, independently of a +hook's `env` list. + +## Set workload compute requirements + +Set the workload's default CPU and memory allocation with the +[`resources@1` capability](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/resources@1.md) +in its descriptor. Use a whole number of CPU cores. Anyone running the kit +can override these defaults with `--cpus` and `--memory` when creating a sandbox. + +Put these settings on the workload. `sbx` ignores resource settings on +mixins added separately, and it doesn't use the capability's `gpu` field +to select GPUs. + +## Keep the sandbox running after sessions end + +By default, a local sandbox stops automatically shortly after its last session +disconnects. A kit that runs a service, such as a development server on a +published port, can ask the sandbox to keep running instead. Declare the +[`long-running@1` capability](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md), +which takes no `config`: + +```yaml +capabilities: + - type: com.docker.sandbox/long-running@1 +``` + +A sandbox created with this kit behaves like one started with +[`sbx run --detach`](/manuals/ai/sandboxes/usage.md#keep-a-sandbox-running-in-the-background): +it keeps running until someone stops or removes it, including after you attach +to it and disconnect. When a workload, mixin, or set declares the capability, +it applies to the whole sandbox. + +A kit that declares the capability runs only where the runtime can provide it. +If the kit also works when the sandbox stops after its sessions end, set +`optional: true` on the entry. A runtime that can't provide the capability +then skips it instead of refusing the kit. In `sbx`, two cases can't provide +it: + +- Cloud sandboxes can't provide this capability. `sbx --cloud` refuses a kit + that requires it and skips an optional entry. +- `sbx kit add` can't apply the capability to a running sandbox. Create the sandbox with the kit to apply it. diff --git a/content/manuals/ai/sandboxes/customize/author/base-images.md b/content/manuals/ai/sandboxes/customize/author/base-images.md new file mode 100644 index 000000000000..c4d9124a6176 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/base-images.md @@ -0,0 +1,191 @@ +--- +title: Base images for sandbox workloads +linkTitle: Base images +weight: 10 +description: Choose a Docker-provided agent image or your own Linux base image for a sandbox workload kit. +keywords: sandboxes, sbx, kits, base images, templates, dockerfile, custom agents +aliases: + - /ai/sandboxes/customize/templates/ +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +A base image gives your workload its operating system and starting set of +tools. Docker provides images with agents already installed. You can also start +from another Linux image and prepare it yourself. Choose the base image in your +workload's Dockerfile. Use the kit descriptor to configure network access, +credentials, and other sandbox behavior. A kit set uses the base image from its +workload. + +To save and reuse an environment you've configured interactively, see +[Save a sandbox as a template](/manuals/ai/sandboxes/usage.md#saving-a-sandbox-as-a-template). + +## Docker-provided images + +Docker's sandbox templates are published as +`docker/sandbox-templates:<variant>`. They are based on Ubuntu and run as a +non-root `agent` user with sudo access. Most variants include Git, Docker +CLI, and common development tools like Node.js, Python, Go, and Java. Full +templates also include a C/C++ compiler toolchain for building native code. + +| Variant | Agent | +| --------------------- | -------------------------------------------------------------------- | +| `claude-code` | [Claude Code](https://claude.ai/download) | +| `claude-code-minimal` | Claude Code with a minimal toolset (no Node.js, Python, Go, or Java) | +| `codex` | [OpenAI Codex](https://github.com/openai/codex) | +| `copilot` | [GitHub Copilot](https://github.com/github/copilot-cli) | +| `cursor-agent` | [Cursor](https://cursor.com/cli) | +| `devin` | [Devin CLI](https://docs.devin.ai/work-with-devin/devin-cli) | +| `docker-agent` | [Docker Agent](https://github.com/docker/docker-agent) | +| `droid` | [Droid](https://www.factory.ai) | +| `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | +| `kiro` | [Kiro](https://kiro.dev) | +| `opencode` | [OpenCode](https://opencode.ai) | +| `shell` | No agent pre-installed. Use for manual agent setup. | + +## Use an image in a v3 workload + +Start your workload's Dockerfile with `FROM`, then add the tools and +configuration you need. Install system packages as `root`, and switch back +to `agent` before installing tools in the agent's home directory. Running +those installers as `root` puts files under `/root/`, where the agent can't +use them. + +### What the base image provides + +`FROM` inherits the image's files and settings. If the image is also a +published kit, its capabilities don't carry over. Declare network access, +credentials, storage, and hooks in your own descriptor. To keep an existing +kit's capabilities and add tools, [compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). + +Your descriptor determines the kit format version. A v3 descriptor creates +a v3 kit, including when you use a Docker template image as its base. See +[Version compatibility](/manuals/ai/sandboxes/customize/_index.md#version-compatibility). + +### Package an existing agent image + +This example packages Docker's OpenCode image as a v3 workload. The image +already has an agent installed, so you only need to choose its launch command +and describe what it needs to run. You can run the resulting kit directly or +include it in a set with additional tools. + +Create a directory with these two files: + +```text +opencode-workload/ +├── opencode-workload.yaml +└── opencode-workload.dockerfile +``` + +The Dockerfile selects the base image and tells Docker Sandboxes to run +OpenCode as the `agent` user: + +```dockerfile {title="opencode-workload/opencode-workload.dockerfile"} +FROM docker/sandbox-templates:opencode +USER agent +ENTRYPOINT ["opencode"] +CMD [] +``` + +The template supplies OpenCode, Python, uv, and the `agent` user. Create a +YAML descriptor to identify this as a workload and declare what OpenCode +needs: network access, an Anthropic API key, and instructions about its +environment: + +```yaml {title="opencode-workload/opencode-workload.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: workload + +capabilities: + - type: com.docker.sandbox/sbx@1 + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + - api.anthropic.com + - opencode.ai + - models.dev + - registry.npmjs.org + - pypi.org + - files.pythonhosted.org + - type: com.docker.sandbox/credential@1 + config: + service: anthropic + phase: runtime + apiKey: + name: ANTHROPIC_API_KEY + proxyManaged: true + inject: + - domain: api.anthropic.com + header: x-api-key + format: "%s" + - type: com.docker.sandbox/agent-context@1 + config: + filename: AGENTS.md + content: | + OpenCode runs as the agent user. Python and uv are available. + Use the project's environment and dependency configuration. +``` + +The credential entry names the service and describes how to authenticate API +requests. Store the actual API key on your host. + +`sbx` can build this directory when you create a sandbox. The result is a +container image with the kit's files and descriptor, which you can also +publish to a registry for others to use. + +## Use your own Linux image + +If you need a different operating system or set of packages, start from a +Linux image of your choice. You'll need to add the tools and user account +that Docker Sandboxes expects, then install your agent. + +The following requirements help you prepare that image. For a step-by-step +example, follow [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md). + +### Base image requirements + +Prepare your image with the following: + +- Tools: Include `curl`, `git`, and trusted CA certificates for accessing + source repositories and making HTTPS requests. +- Shells: Provide executable `/bin/sh` and `/bin/bash` files for setup commands + and agent launch. +- User account: Create a non-root `agent` account with UID 1000 and home + directory `/home/agent`. Add the account to `/etc/passwd` and set `USER + agent` in the image. +- Launch command: Set `ENTRYPOINT` or `CMD` to the agent or shell you want the + sandbox to launch. + +Docker Sandboxes uses the account's entry in `/etc/passwd` to determine +the user ID, group ID, and home directory when running commands and writing +files. + +For a sandbox with a mounted workspace, `WORKDIR` doesn't choose the mount +location. For a sandbox without a mounted workspace, `sbx` uses the image's +absolute `WORKDIR` as the working directory. If the image doesn't specify a +usable absolute path, `sbx` falls back to `/home/agent/workspace`. + +### Declare the agent launch contract + +`sbx` keeps the sandbox running and starts the agent as a separate process, +using the image's launch command. The `com.docker.sandbox/sbx@1` capability +declares that your workload is prepared to run this way: + +```yaml +capabilities: + - type: com.docker.sandbox/sbx@1 +``` + +This capability takes no `config` and doesn't request extra permissions. It +lets the upstream conformance tests check that your image meets the shell and +user account requirements before you publish. + +The host launches the agent through non-interactive Bash. To load persistent +environment settings at launch, set `BASH_ENV` to an absolute path and include +that file in the image. Bash reads this file instead of login profiles or +`.bashrc`. + +For the complete contract, see the upstream +[`sbx@1` definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/sbx@1.md). diff --git a/content/manuals/ai/sandboxes/customize/author/build-an-agent.md b/content/manuals/ai/sandboxes/customize/author/build-an-agent.md new file mode 100644 index 000000000000..68f1978d37cd --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/build-an-agent.md @@ -0,0 +1,419 @@ +--- +title: Build an agent workload +linkTitle: Build an agent workload +description: Build a schema v3 agent workload from your own Linux base image, prepare its sandbox environment, and configure credentials and agent instructions. +keywords: sandboxes, sbx, kits, agent, tutorial, claude, workload, build +weight: 20 +aliases: + - /ai/sandboxes/customize/build-an-agent/ +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Build a kit that runs Claude Code on a Linux base image of your choice. +You'll install the agent, give it access to the Anthropic API, and add model +settings and instructions for your team. The result is a v3 workload kit you +can run locally or publish for others to use. You can follow the same steps +for other agents or your organization's own base images. + +This tutorial prepares the whole environment, from system packages to the +command that starts the agent. If you already have a suitable agent image, +see [Package an existing agent image](/manuals/ai/sandboxes/customize/author/base-images.md#package-an-existing-agent-image). +To combine a published agent kit with tools, [author a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). + +If you're starting with kits, read [Author kits](/manuals/ai/sandboxes/customize/author/_index.md) +for an introduction to the files you'll create. Field definitions are in the +[upstream v3 specification](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md). + +## Prepare the kit directory + +You need `sbx`, Docker with Buildx, and an Anthropic +API key. Create a directory beside the project you want the agent to work on: + +```console +$ mkdir claude-team +``` + +The completed directory contains three files: + +```text +claude-team/ +├── claude-team.yaml +├── claude-team.dockerfile +└── context.md +``` + +The Dockerfile installs the agent and sets the command to run it. The YAML +file, called the descriptor, tells Docker Sandboxes what the agent needs to +run, such as network access and credentials. The Markdown file contains +instructions for the agent. Give the YAML file and Dockerfile the same name +before the extension so the build can find both files. + +This kit uses v3 and is independent of the built-in `claude` kit, which uses +v2. Any mixins you add must also use v3. To customize the built-in kit, see +[Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md). + +## Use your own base image + +This tutorial starts from Red Hat Universal Base Image (UBI) 9. The following +steps add the tools, user account, and certificates the sandbox needs. You can +use another Linux image, including one maintained by your organization. +Adjust the package and account commands for that image, following the same +[base image requirements](/manuals/ai/sandboxes/customize/author/base-images.md#base-image-requirements). + +### Install the system packages + +Create `claude-team/claude-team.dockerfile` with the base image and packages: + +```dockerfile {title="claude-team/claude-team.dockerfile"} +FROM registry.access.redhat.com/ubi9/ubi:9.8 + +USER root +RUN dnf install -y bash ca-certificates curl-minimal git shadow-utils tar gzip \ + && dnf clean all +``` + +Bash runs shell commands, Git accesses source repositories, and curl uses +the CA certificates to make HTTPS requests. The remaining packages create +the agent's user account and unpack its installer. Add any compilers, +libraries, or other tools your projects need here. + +### Create the agent account + +The sandbox needs a non-root `agent` user with UID 1000 and home directory +`/home/agent`. Append the following to the Dockerfile to create that account +and writable directories for its workspace, configuration, and state: + +```dockerfile {title="Append to claude-team/claude-team.dockerfile"} +RUN groupadd --gid 1000 agent \ + && useradd --uid 1000 --gid 1000 --create-home --shell /bin/bash agent \ + && mkdir -p /home/agent/workspace /home/agent/.local/bin \ + /home/agent/.local/share /home/agent/.local/state \ + /home/agent/.config/claude-team /home/agent/.docker/sandbox/locks \ + && chown -R agent:agent /home/agent +``` + +Creating these directories during the build makes the agent their owner +before Docker Sandboxes mounts the workspace and storage. The agent runs +without `sudo` in this example, so install system packages in the Dockerfile. +Use install hooks for setup that depends on an individual sandbox. + +### Prepare certificate trust + +HTTPS requests from the sandbox go through a proxy. Docker Sandboxes adds +the proxy's certificate authority (CA) to the sandbox's trusted certificates +when it starts. UBI keeps its certificates at a different path from the one +`sbx` uses. Copy them to the expected path, then tell tools to use that file +so they trust both public certificates and the proxy: + +```dockerfile {title="Append to claude-team/claude-team.dockerfile"} +RUN update-ca-trust \ + && mkdir -p /usr/local/share/ca-certificates /etc/ssl/certs \ + && cp /etc/pki/tls/certs/ca-bundle.crt /etc/ssl/certs/ca-certificates.crt + +ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \ + CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \ + REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \ + NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt +``` + +If you add corporate CA certificates during the build, add them to +`/etc/pki/ca-trust/source/anchors/` before running `update-ca-trust` and +copying the bundle. For another distribution, use its certificate management +command and source bundle path. + +### Prepare the shell environment + +An environment variable exported in one shell isn't automatically available +in another. Give the agent a file where it can save variables for later +shell sessions. The following lines create that file and arrange for login, +interactive, and non-interactive Bash shells to read it: + +```dockerfile {title="Append to claude-team/claude-team.dockerfile"} +RUN touch /etc/sandbox-persistent.sh \ + && chown agent:agent /etc/sandbox-persistent.sh \ + && chmod 0644 /etc/sandbox-persistent.sh \ + && printf '%s\n' '. /etc/sandbox-persistent.sh' \ + > /etc/profile.d/sandbox-persistent.sh \ + && printf '%s\n' '. /etc/sandbox-persistent.sh' >> /home/agent/.bashrc + +ENV HOME=/home/agent \ + PATH="/home/agent/.local/bin:${PATH}" \ + BASH_ENV=/etc/sandbox-persistent.sh +``` + +`BASH_ENV` tells non-interactive Bash to read the file. You'll include +instructions for the agent to use it later in the tutorial. + +## Build the agent into the image + +Append the following to the Dockerfile to install Claude Code as `agent` and +set its launch command: + +```dockerfile {title="Append to claude-team/claude-team.dockerfile"} +USER agent +ENV CLAUDE_ENV_FILE=/etc/sandbox-persistent.sh \ + IS_SANDBOX=1 +ARG CLAUDE_VERSION +RUN curl -fsSL https://claude.ai/install.sh -o /tmp/install-claude.sh \ + && bash /tmp/install-claude.sh "${CLAUDE_VERSION}" \ + && rm /tmp/install-claude.sh + +WORKDIR /home/agent/workspace +ENTRYPOINT ["claude", "--settings", "/home/agent/.config/claude-team/settings.json"] +CMD [] +``` + +Installing as `agent` puts Claude Code under `/home/agent/`, where that user +can access it. `CLAUDE_ENV_FILE` points Claude Code to the file you prepared +for persistent environment variables. You'll set `CLAUDE_VERSION` in the +descriptor in the next step. + +The Dockerfile also sets the user, working directory, environment variables, +and launch command. `CMD []` clears any arguments inherited from the base +image. The `--settings` option loads the model you choose for each sandbox. +You'll create its settings file in [Write the model settings](#write-the-model-settings). + +Each sandbox created from this image gets the same Claude Code binary. +The next steps configure how Docker Sandboxes runs it. Any mixins you add +must use v3 and contain tools compatible with this workload's operating +system and architecture. + +## Describe the workload and its inputs + +Create `claude-team/claude-team.yaml`. Start by identifying the workload and +declaring two arguments: + +- `version` selects the Claude Code version to install during the image build. +- `model` selects the model to use when creating a sandbox. + +```yaml {title="claude-team/claude-team.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: workload +displayName: Team Claude Code +description: Claude Code with team defaults and API-key authentication + +args: + version: + default: "2.1.278" + pattern: '^[0-9]+\.[0-9]+\.[0-9]+$' + buildArg: CLAUDE_VERSION + model: + default: sonnet + enum: [sonnet, opus, haiku] + +provides: ["claude@${{ kit.args.version }}"] +``` + +`version` sets the Dockerfile's `CLAUDE_VERSION` build argument. The build +checks the version against `pattern`, then includes it in `provides` so +other kits can check which Claude Code version is installed. + +`model` lets you choose a model when creating each sandbox. The choice goes +into a settings file, so it doesn't change the installed agent. + +## Allow access to the API + +With the agent installed, the next step is to give it access to the Anthropic +API. Add a `capabilities` list at the top level of `claude-team.yaml`, after +`provides`: + +```yaml {title="Add to claude-team/claude-team.yaml"} +capabilities: + - type: com.docker.sandbox/sbx@1 + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + - api.anthropic.com:443 +``` + +The network rule permits HTTPS requests to the Anthropic API while the +sandbox runs. Downloading Claude Code in the Dockerfile uses the builder's +network, so it doesn't need a rule here. + +The `sbx@1` entry declares that the workload is prepared for `sbx` to manage +the agent's launch. See [Declare the agent launch contract](/manuals/ai/sandboxes/customize/author/base-images.md#declare-the-agent-launch-contract) +for the shells and user account that this requires. + +## Declare the credential + +Claude Code can reach the API, but it also needs to authenticate. Add a +credential capability to tell Docker Sandboxes which key to use and how to +include it in requests. You'll store the key on your host, outside the kit. + +Append this entry to the same `capabilities` list: + +```yaml {title="Append under capabilities"} + - type: com.docker.sandbox/credential@1 + description: Anthropic API access + config: + service: anthropic + phase: runtime + apiKey: + name: ANTHROPIC_API_KEY + proxyManaged: true + inject: + - domain: api.anthropic.com + header: x-api-key + format: "%s" +``` + +The sandbox receives a placeholder in `ANTHROPIC_API_KEY`. When Claude Code +makes a request to `api.anthropic.com`, the host proxy inserts the real API +key into the `x-api-key` header. The key stays on the host. You'll supply +its value and approve its use when launching the kit. + +## Write the model settings + +The Dockerfile's launch command reads +`/home/agent/.config/claude-team/settings.json`. Use the lifecycle capability +to create that file with the model chosen for the sandbox. + +Append this entry to `capabilities`: + +```yaml {title="Append under capabilities"} + - type: com.docker.sandbox/lifecycle@1 + config: + files: + - path: /home/agent/.config/claude-team/settings.json + content: | + {"model": "${{ kit.args.model }}"} + mode: "0644" +``` + +Docker Sandboxes fills in the chosen `model` and writes the file before +Claude Code starts. Creating the file at this point lets each sandbox use a +different model with the same image. + +Docker Sandboxes writes these files as UID 1000 after running install hooks. +Use an absolute path the agent can write to, as in this example. Shell +variables such as `$HOME` aren't expanded in the path. + +## Add agent instructions + +The kit can also give Claude Code instructions about the environment. Save the +following Markdown alongside the descriptor and Dockerfile: + +```markdown {title="claude-team/context.md"} +## Team workflow + +Read the project's README before changing code. Run the project's checks +before reporting a task complete, and report any checks you couldn't run. + +Claude Code is installed in this sandbox. Its additional settings are at +`/home/agent/.config/claude-team/settings.json`. + +Use `/etc/sandbox-persistent.sh` for environment exports needed by later +Bash commands. Keep shell completion scripts out of that file because +non-interactive commands also source it. +``` + +Append an agent-context entry to `capabilities` to include these instructions: + +```yaml {title="Append under capabilities"} + - type: com.docker.sandbox/agent-context@1 + config: + filename: CLAUDE.md + contentFile: ./context.md +``` + +The build includes `context.md` in the image. When the sandbox runs, `sbx` +writes a `CLAUDE.md` file in the parent directory of the mounted workspace. +That file points Claude Code to your `context.md`. A `CLAUDE.md` in your +project stays in place. + +Use `contentFile`, as in this example, to keep longer instructions in a +separate Markdown file. You can also write instructions directly in the +workload's descriptor using `content` instead of `contentFile`. +For how instructions from multiple kits work together, see +[Runtime access and instructions](/manuals/ai/sandboxes/customize/use-kits.md#runtime-access-and-instructions). + +## Store the key and run + +Store your Anthropic API key on the host: + +```console +$ sbx secret set anthropic +``` + +From the directory containing `claude-team`, launch the kit: + +```console +$ sbx run --name claude-team ./claude-team +``` + +`sbx` builds the kit, mounts your current directory as the workspace, and +launches Claude Code. To work on another project, append its path to the command. +When prompted, approve the kit's request to use your stored key, then follow +Claude Code's first-run prompts. The agent needs both the stored key and your +approval to use it. See +[Credential bindings](/manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). + +Choose a different model when creating a sandbox: + +```console +$ sbx run --name claude-team-opus ./claude-team \ + --kit-arg claude-team.model=opus +``` + +The `claude-team` prefix matches the local kit directory's name. Docker +Sandboxes checks that `opus` is one of the choices in `enum`, then writes it +to the settings file before Claude Code starts. + +## Iterate and publish + +Edit the descriptor, Dockerfile, or context file and create another sandbox +with a different name to test the changes: + +```console +$ sbx run --name claude-team-test-2 ./claude-team +``` + +Restarting an existing sandbox won't pick up your edits. To try another +agent version locally, update `args.version.default` in the descriptor and +create another sandbox. + +`sbx` reuses the local build when the source files and kit arguments are +unchanged. Changing either can trigger a build, even for arguments such as +`model` that only affect sandbox setup. BuildKit can still reuse unchanged +image layers. + +### Publish the workload + +When the kit is ready to share, sign in to Docker Hub, then build and push it +with Docker Buildx. Replace `<NAMESPACE>` with a Docker Hub namespace you can +push to: + +```console +$ docker login +$ docker buildx build ./claude-team \ + --file ./claude-team/claude-team.yaml \ + --tag docker.io/<NAMESPACE>/claude-team:1.0.0 \ + --push +``` + +The `--file` option tells Buildx to read the descriptor. Its `syntax` line +selects the kit frontend, which reads the companion Dockerfile and includes +the descriptor in the published image. To publish a different agent version, +add `--build-arg version=<CLAUDE_VERSION>`. This flag uses the kit argument +name, `version`, which the descriptor maps to the Dockerfile's `CLAUDE_VERSION`. + +Run the published kit by its image reference: + +```console +$ sbx run --name claude-team-shared docker.io/<NAMESPACE>/claude-team:1.0.0 +``` + +For multi-platform images and distribution details, see +[Build and distribute kits](/manuals/ai/sandboxes/customize/author/distribute.md). +To learn how to package a tool separately from its workload, see +[Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md). +That tutorial also packages Claude Code, so use its mixin with a shell workload. +Combining it with this workload would give two kits that provide `claude`, +which Docker Sandboxes rejects. +You can also include the published workload in a +[kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md) and add settings +and instructions there. The workload still defines how to prepare the base +image, install the agent, and launch it. diff --git a/content/manuals/ai/sandboxes/customize/author/capabilities.md b/content/manuals/ai/sandboxes/customize/author/capabilities.md new file mode 100644 index 000000000000..8dc9910d9f5e --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/capabilities.md @@ -0,0 +1,85 @@ +--- +title: Kit capability support +linkTitle: Capability support +description: Check which v3 kit capabilities Docker Sandboxes supports locally and in the cloud, their minimum sbx versions, and restrictions that affect kit authors. +keywords: sandboxes, sbx, kits, capabilities, compatibility, cloud +weight: 37 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Use this reference to check whether a v3 kit can run on your version of Docker +Sandboxes and whether it needs a local sandbox. Follow each capability link +for its settings and examples in the Docker Sandbox Kit Specification. + +## Support by capability + +Version numbers identify the first `sbx` release that supports the +capability, subject to the restrictions in the table. Limited support means +that Docker Sandboxes applies only part of the capability. Declaration only +means that Docker Sandboxes accepts the entry without using its commands. +The table covers behavior through v0.48.0. + +All capability names in the table have the `com.docker.sandbox/` prefix. + +| Capability | Local sandboxes | Cloud sandboxes | Restrictions | +| --- | --- | --- | --- | +| [`agent-context@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-context@1.md) | v0.45.0 | v0.45.0 | Agent instructions are applied when creating the sandbox. | +| [`agent-interactive-sessions@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-interactive-sessions@1.md) | Unsupported | Unsupported | Docker Sandboxes does not use these session commands. | +| [`agent-sessions@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-sessions@1.md) | Declaration only | Declaration only | Accepted since v0.45.0, but Docker Sandboxes does not execute the declared session commands. | +| [`agent-skill@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-skill@1.md) | v0.48.0 | Unsupported | Requires a selected `agent-skills@1` destination. Bundled skills remain available with `--skills=off`. | +| [`agent-skills@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-skills@1.md) | v0.45.0 | Unsupported | Local sandboxes mount the shared skills store. From v0.48.0, discovery paths also receive bundled skills. | +| [`credential@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/credential@1.md) | v0.45.0 | Limited: v0.45.0 | In cloud sandboxes, credentials scoped to installation remain available after setup. | +| [`git-identity@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/git-identity@1.md) | v0.48.0 | Unsupported | Requires `user.name` and `user.email` in the host Git config. | +| [`host-mount@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/host-mount@1.md) | Unsupported | Unsupported | Kit requests for shared host directories are not supported. | +| [`kit-registry@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/kit-registry@1.md) | v0.45.0 | Unsupported | Restricted to approved OCI builder kits. Local and Git kit sources do not receive registry access. | +| [`lifecycle@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md) | v0.45.0 | v0.45.0 | Local startup hooks run alongside the agent, rather than blocking its launch. | +| [`long-running@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md) | v0.47.0 | Unsupported | Keeps a local sandbox running after its last session disconnects. | +| [`network-policy@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes keep installation-phase network access after setup. | +| [`network-policy@2`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@2.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes enforce host rules, but not HTTP method or path restrictions. Installation-phase access remains after setup. | +| [`port@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/port@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes expose TCP ports only. | +| [`privileged@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/privileged@1.md) | v0.48.0 | Unsupported | Accepted by the local runtime, which runs Docker-in-Docker containers in privileged mode inside the sandbox VM. | +| [`resources@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/resources@1.md) | Limited: v0.45.0 | Limited: v0.45.0 | Workload CPU and memory defaults are applied. The `gpu` field does not select GPUs; cloud creation rejects a required GPU request. | +| [`sbx@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/sbx@1.md) | v0.45.0 | v0.45.0 | Docker Sandboxes launches the agent using the workload command. | +| [`ssh-agent@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/ssh-agent@1.md) | v0.48.0 | Unsupported | Requires SSH-agent forwarding to be enabled and a host SSH agent to be available. | +| [`usb-device@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/usb-device@1.md) | Unsupported | Unsupported | Kit requests for USB device access are not supported. | +| [`volume@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) | v0.45.0 | Limited: v0.45.0 | Local sandboxes provide block storage or tmpfs. Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests. | + +## Capability groups + +Docker Sandboxes supports capability groups in `sbx` v0.48.0 and later. +A group is selected only when the runtime can provide every capability in it. +If a capability is unavailable, an optional group is skipped in full, including +its network rules, setup commands, generated files, and agent instructions. +An unavailable capability in a required group prevents sandbox creation. + +Availability also depends on the host: Git identity requires configured +`user.name` and `user.email`, and SSH-agent access requires an available +agent with forwarding enabled. See the upstream +[capability group definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#711-capability-groups) +for syntax and composition rules. + +## Capabilities that require sandbox creation + +Include kits that need the following settings when you create the sandbox. +`sbx kit add` cannot apply these settings to an existing sandbox: + +| Capability | Settings that require creation | +| --- | --- | +| `credential@1` | Credential routing and authentication | +| `kit-registry@1` | Access to the kit registry | +| `long-running@1` | Keeping the sandbox running after sessions disconnect | +| `port@1` | Published ports | +| `resources@1` | CPU and memory allocation | +| `volume@1` | Block storage and tmpfs mounts | +| `lifecycle@1` | Generated `files` require sandbox creation. Install and startup hooks can be added with `sbx kit add`. | +| `network-policy@1` and `network-policy@2` | Host-level deny rules require sandbox creation. Allow rules can be added with `sbx kit add`, as can HTTP method and path rules for `network-policy@2`. | + +`sbx kit add` rejects kits that declare credentials, published ports, +resource settings, volumes, generated lifecycle files, or host-level deny +rules. To use those kits, remove and recreate the sandbox with the kits +included. Save any work you need from the sandbox before removing it. + +Skill discovery paths (`agent-skills@1`) and bundled skills (`agent-skill@1`) +can be added with `sbx kit add`: the command replaces the sandbox container +and applies the updated skill configuration. diff --git a/content/manuals/ai/sandboxes/customize/author/distribute.md b/content/manuals/ai/sandboxes/customize/author/distribute.md new file mode 100644 index 000000000000..0d24a9fa1f04 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/distribute.md @@ -0,0 +1,117 @@ +--- +title: Build and distribute kits +description: Build and publish v3 kit images, share source through Git, and sign images for distribution. +keywords: sandboxes, sbx, kits, v3, workloads, mixins +weight: 40 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +Once you've [authored a kit](/manuals/ai/sandboxes/customize/author/_index.md), +share it by publishing an image to a registry or its source to Git. +Publishing an image saves others from building the kit themselves. Sharing +the source lets them build it when they create a sandbox. Either way, `sbx` +reads the kit's descriptor to configure the sandbox. + +This page shows how to publish and sign v3 kits. To run a kit someone else has +shared, see [Use kits](/manuals/ai/sandboxes/customize/use-kits.md). + +## Publish an image + +Use Docker Buildx to build and publish your kit as an OCI image. Pass the YAML +descriptor with `-f` and the source directory as the build context: + +```console +$ docker login +$ docker buildx build ./my-kit -f ./my-kit/my-kit.yaml \ + -t docker.io/<NAMESPACE>/my-kit:1.0.0 --push +``` + +Replace `<NAMESPACE>` with a Docker Hub namespace you can push to. Buildx +uses your `docker login` credentials to push the image. + +Push the image before running it by its registry reference. `sbx` pulls the +published image. It can't use images stored only in your host's Docker image +store. During development, you can pass a local source directory to `sbx` +instead. For private images, configure +[registry credentials](/manuals/ai/sandboxes/configuration/credentials.md#registry-credentials) +for your sandbox. + +Use Buildx for v3 kits. The `sbx kit pack`, `push`, and `pull` commands are +for v1 and v2 kits. + +### Support both Linux architectures + +To share the kit with people who use different machines, build for both +supported Linux architectures: + +```console +$ docker buildx build ./my-kit -f ./my-kit/my-kit.yaml \ + --platform linux/amd64,linux/arm64 \ + -t docker.io/<NAMESPACE>/my-kit:1.0.0 --push +``` + +## Publish a kit set + +Publish a set with the same Buildx command, passing its YAML descriptor with +`-f`. The build fetches the published images listed in `kits:`, checks whether +their declarations are compatible, and combines their files and settings into +one image. See +[Compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md) for a complete example. + +The result is a workload or mixin image that people can use directly. It +records each component's manifest digest, which identifies the exact image +used in the build. Updating a component's tag doesn't change a published +set. To share the update, rebuild the set and publish another version. +If you want rebuilds to use the same component images, add a `digest` beside +each `ref` in `kits:`. + +## Share source through Git + +Commit the kit's source directory to a Git repository, then share a reference +in this format. Use `dir` to select the kit directory and `ref` to select the +commit: + +```text +git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-kit +``` + +When someone creates a sandbox from that reference, `sbx` builds the kit +from the selected commit. + +## Sign and verify kits + +Sign your published image so others can verify who signed it: + +```console +$ sbx kit sign docker.io/<NAMESPACE>/my-kit:1.0.0 +$ sbx kit verify docker.io/<NAMESPACE>/my-kit:1.0.0 \ + --certificate-identity <SIGNER_IDENTITY> \ + --certificate-oidc-issuer <ISSUER_URL> +``` + +These commands use Sigstore signatures, which are compatible with Cosign. +The example signs without a key, so verification needs the signer's certificate +identity and OpenID Connect issuer. To sign with a key instead, pass +`--key cosign.key` to `sign` and `--key cosign.pub` to `verify`. + +To require a valid signature before using a kit, see +[Verify kit signatures](/manuals/ai/sandboxes/customize/use-kits.md#verify-kit-signatures). + +V3 kits shared as source directories or Git references can't be signed. +If you need signatures, publish and sign an OCI image. + +## Published format + +A published kit image contains both the kit's content and its descriptor. +Docker image tools can inspect and distribute it, and Docker Sandboxes reads +the descriptor when creating the sandbox. + +You can also inspect the descriptor inside the sandbox, under +`/usr/share/sandbox/kit/<stem>/`. +For the image annotations and file layout, see +[Published image format](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#10-the-oci-layout). + +Use `sbx` to run a workload with the settings and hooks declared in its kit +descriptor. Running it with `docker run` uses only the image configuration, +so those settings and hooks aren't applied. diff --git a/content/manuals/ai/sandboxes/customize/author/kit-sets.md b/content/manuals/ai/sandboxes/customize/author/kit-sets.md new file mode 100644 index 000000000000..712d09b0b807 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/kit-sets.md @@ -0,0 +1,244 @@ +--- +title: Compose a kit set +description: Combine published workloads and mixins into a kit set, configure shared settings and arguments, and publish it for your team. +keywords: sandboxes, sbx, kits, v3, sets, composition, workloads, mixins +weight: 5 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +A kit set gives your team one kit to run, with the tools and versions you've +chosen. You list the kits to include, add any settings the combined environment +needs, and publish the result. A set can also run setup commands, supply agent +instructions, and offer choices such as which model to use. + +Use a set when you want to share a combination of kits and manage its +settings in one place. The components can be kits your team publishes or +kits from other publishers. You need Docker Buildx and a registry namespace +you can push to when publishing the set. + +## Choose the components + +A set can contain one workload and any number of mixins. Together, they +provide a complete sandbox environment. You can also make a set of only +mixins, to share tools and settings that users add to a workload with `--kit`. + +Choose v3 kits that work together. For example, you could combine an agent +workload with a linter mixin and a mixin that adds your team's configuration. +To package a tool of your own, see +[Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md). + +You can try a workload and mixins together with `sbx run` and `--kit` +before composing a set. See +[Add mixins](/manuals/ai/sandboxes/customize/use-kits.md#add-mixins). +If one kit depends on another, Docker Sandboxes applies the dependency first. +Changing the order of `--kit` flags or entries in a set doesn't change that +order. + +## Write the set descriptor + +A set descriptor uses `kind: set` and lists its components under `kits:`. +For example, this descriptor combines Docker's Codex workload with a +mixin: + +```yaml {title="codex-tools/codex-tools.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: set +displayName: Codex with tools +version: "1.0.0" + +kits: + - ref: docker.io/docker/sbx-kit-codex:0.155.1 + - ref: <MIXIN_REFERENCE> +``` + +Replace `<MIXIN_REFERENCE>` with a published v3 mixin's full image reference. +Choose a different workload reference to use another agent or environment. +The components supply their own network rules and credential requests, so +the set doesn't need to repeat them. + +The set gets its software and files from the `kits:` list. It doesn't have a +Dockerfile, a `dockerfile:` field, or a `build:` block. To include more software +or static files, package them in a workload or mixin, publish that kit, and +add it to the list. + +Every `ref` must be a published registry reference. Local paths and Git URLs +aren't accepted as components, even when building the set from local source. + +## Add runtime access to the set + +You can give the combined environment access to services beyond those its +components request. For example, to let the agent download packages from an +internal registry, add this network capability to the set's descriptor: + +```yaml +capabilities: + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + - packages.company.example:443 +``` + +Replace the example domain with your registry's host. The rule permits access +as long as the sandbox's policy allows it. If the registry also requires +authentication, add a credential request. See +[Services declared by kits](/manuals/ai/sandboxes/configuration/credentials.md#services-declared-by-kits). + +Keep access required by a tool in that tool's kit, so its access rules follow +it when used with another workload. Put settings shared by the combined +environment on the set, such as access to your team's package registry. +You can also add setup commands, generate configuration files, provide +instructions, and define arguments on the set. + +## Build and publish the set + +Before publishing, [check for file conflicts](#check-for-file-conflicts) +between the components. + +Build and publish a set by passing its descriptor to Docker Buildx. +For a descriptor at `codex-tools/codex-tools.yaml`: + +```console +$ docker login +$ docker buildx build ./codex-tools -f ./codex-tools/codex-tools.yaml \ + -t docker.io/<NAMESPACE>/codex-tools:1.0.0 --push +``` + +Replace the paths with your set's source directory and descriptor, and +`<NAMESPACE>` with a Docker Hub namespace you can push to. + +The build pulls the listed kits, checks their declared requirements, and +combines their files and settings. It fails if a dependency is missing, two +kits declare the same feature in `provides`, or more than one kit is a workload. + +A set that includes a workload publishes as `kind: workload`. +A set containing only mixins publishes as `kind: mixin`. +Your team can use the result like any other workload or mixin. The published +kit records each component's exact image digest in `kits:`. Only the source +descriptor uses `kind: set`. + +## Run the set + +Run a published set that contains a workload by passing its image reference +to `sbx run`, as you would for an individual workload: + +```console +$ sbx run <SET_REFERENCE> --name my-project +``` + +The sandbox includes the workload and all the mixins packaged in the set. +You don't need to list those mixins separately with `--kit`. + +For a set containing only mixins, add it to a workload with `--kit`: + +```console +$ sbx run <WORKLOAD_REFERENCE> --kit <SET_REFERENCE> --name my-project +``` + +Authentication depends on the kits in the set. Check their documentation for +required credentials, store those credentials on the host, and approve access +when prompted. See +[Credential configuration](/manuals/ai/sandboxes/configuration/credentials.md) +for authentication options and preparing unattended runs. + +To control the agent's base image or launch command, see +[Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md). + +## Configure component arguments + +You can let your team change a setting without changing which kits are +included. For example, they might need to choose whether a linter checks or +fixes files while using the linter version you've selected. + +A set controls which component arguments users can change. You can fix an +argument's value when publishing the set, or expose it as an argument on the +set so users can choose a value when creating a sandbox. + +After changing the argument definitions in the descriptor, rebuild and publish +the set. + +### Fix an argument's value + +Suppose you have a linter kit with a `mode` argument that users normally set +when creating a sandbox. Add it to the set with a fixed value of `check`: + +```yaml +kits: + - ref: docker.io/my-org/linter-kit:1.0.0 + args: + mode: check +``` + +This excerpt fixes the linter's `mode` to `check` when you publish the set. +Use your linter's image reference and argument name. Other components in the +set can have their own argument values. + +### Let users choose a value + +To let users choose the mode when creating a sandbox, define an argument on +the set and pass its value to the linter: + +```yaml +args: + lint_mode: + default: check + enum: [check, fix] + +kits: + - ref: docker.io/my-org/linter-kit:1.0.0 + args: + mode: ${{ kit.args.lint_mode }} +``` + +This example assumes the linter defines `mode` with the same default and +allowed values. The set must preserve those constraints. Users can then pass +`--kit-arg lint_mode=fix` when running the published set. They can change only +arguments defined on the set, not other arguments on its components. +See [Set merge rules](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#95-merging-a-set) +for the argument rules. + +### Change a build argument + +Arguments used to build a component, such as the tool version to install, +are fixed in its published image. To change one, rebuild and publish the +component, then update its reference in the set. + +## Review and update the composition + +### Check for file conflicts + +Before sharing a set, check that its components work together. Give each +component's files separate paths: if two components include the same path, +the file from the later image layer replaces the earlier one. The build +orders layers by kit dependencies, so reordering `kits:` doesn't choose +which file wins. Inspect the built image for unintended replacements. +When you combine kits with `--kit` instead, Docker Sandboxes rejects files +that collide when it creates the sandbox. + +### Check combined settings + +The set includes each component's network rules and agent instructions. +Lifecycle hooks run in dependency order, but startup hooks run alongside +the agent. The agent might start before those hooks finish. + +Use install hooks for setup that must finish during sandbox creation. For +setup that must finish before every agent launch, use the workload's +entrypoint. + +The workload chooses the instruction filename. If you add instructions with +an `agent-context` capability on the set, leave out the filename. + +### Update a component + +Change the component's reference, rebuild the set, and publish another +version. Create another sandbox to try the updated set. Existing sandboxes +keep the kit configuration they were created with. + +A published set keeps the files and settings it was built with, even if a +component's tag later points to a different image. To use those same images +when rebuilding, add a `digest` beside each `ref` in the source. + +For signing and multi-platform builds, see +[Build and distribute kits](/manuals/ai/sandboxes/customize/author/distribute.md). diff --git a/content/manuals/ai/sandboxes/customize/author/patterns.md b/content/manuals/ai/sandboxes/customize/author/patterns.md new file mode 100644 index 000000000000..4e5b004b4862 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/patterns.md @@ -0,0 +1,147 @@ +--- +title: Kit authoring patterns +linkTitle: Authoring patterns +description: Build reusable kits that carry the access their tools need, prepare certificates and storage during setup, and offer useful options to your team. +keywords: sandboxes, sbx, kits, patterns, mixins, lifecycle, certificates +weight: 35 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +When you package a tool as a kit, aim to make it work wherever you add it. +These patterns show how to include the access it needs, prepare it for each +sandbox, and give your team useful options without asking them to assemble +the environment themselves. + +## Keep runtime access with the tool + +Keep a tool's network rules and credential request in the mixin that installs +it. For example, a Claude Code mixin can package the executable, allow access +to the Anthropic API, and request the API key. Those requirements follow the +tool when you add it to another workload. + +The user still needs to supply the credential and approve access. See +[Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md) +for a complete example. + +## Leave build tools out of the mixin + +Build a tool in one Dockerfile stage, then copy the executable into an empty +stage. Each sandbox gets the tool without also getting its compiler and +source code: + +```yaml {title="gojq/gojq.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: mixin +provides: ["gojq@0.12.17"] + +build: | + FROM golang:1.25 AS build + RUN CGO_ENABLED=0 go install github.com/itchyny/gojq/cmd/gojq@v0.12.17 + + FROM scratch + COPY --from=build /go/bin/gojq /usr/local/bin/gojq +``` + +`CGO_ENABLED=0` builds gojq without a dependency on the workload's C libraries. +`FROM scratch` starts the final stage empty, so it contains only the binary +you copy. The `provides` entry tells other kits which gojq version this mixin +installs. + +## Run setup after combining kits + +Some setup needs tools or files from the workload. Package what you can in the +mixin, then use an install hook to finish setup once all the kits' files are +in place. For example, bring an internal certificate authority (CA) certificate +in the mixin and register it in the workload's trust store: + +```yaml {title="internal-ca/internal-ca.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: mixin + +build: | + FROM scratch + COPY internal-ca.crt /usr/local/share/ca-certificates/team-internal-ca.crt + +capabilities: + - type: com.docker.sandbox/lifecycle@1 + config: + install: + - command: update-ca-certificates + user: "0" +``` + +Save your PEM-encoded CA as `internal-ca.crt` beside the descriptor and use the +mixin with a workload that supplies `update-ca-certificates`, such as Docker's +shell kit. The hook updates the workload's trust store as root, after all kit +files are present and before the agent launches. + +```console +$ sbx run docker.io/docker/sbx-kit-shell:1.0.0 --kit ./internal-ca +``` + +## Seed storage after it is mounted + +Mounting storage at a path hides any files the image already has there. To +give a tool some initial data, keep that data elsewhere in the image and +copy it to the mounted directory in an install hook. Check whether the +destination file exists first so you preserve any changes the user has made: + +```yaml {title="tool-state/tool-state.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: mixin + +build: | + FROM scratch + COPY defaults.json /usr/share/company-cli/defaults.json + +capabilities: + - type: com.docker.sandbox/volume@1 + config: + path: /home/agent/.company-cli + size: 1g + - type: com.docker.sandbox/lifecycle@1 + config: + install: + - command: | + set -eu + chown 1000:1000 /home/agent/.company-cli + if [ ! -e /home/agent/.company-cli/config.json ]; then + install -o 1000 -g 1000 -m 0644 /usr/share/company-cli/defaults.json /home/agent/.company-cli/config.json + fi + user: "0" +``` + +Save your tool's initial configuration as `defaults.json` beside the descriptor. +Use a workload with `chown` and `install`, such as Docker's shell kit. The hook +makes the directory and configuration file writable by the agent. If the +volume already has a configuration file, the hook leaves its contents intact. + +### Configure the volume + +The volume keeps the tool's data across sandbox restarts. A replacement +sandbox gets its own volume. This example allocates `1g` of space. If you +omit `size`, `sbx` allocates `512m`. + +Use an install hook to set ownership and permissions for persistent volumes, +as this example does. The volume capability's `mode` setting applies only +to tmpfs mounts. See the upstream +[volume definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) +for storage options. + +To copy initial files into a mounted workspace instead, use +`WORKSPACE_DIR` as the destination and +[declare it in the hook's environment](/manuals/ai/sandboxes/customize/author/_index.md#choose-when-setup-runs). + +## Publish fixed components with configurable options + +Choose compatible agent and tool versions for your team, then publish them +as a set. Expose arguments for settings users can change without replacing +those components, such as a model or linter mode. Keep version choices fixed +in the published images. + +For the argument syntax and constraints, see +[Configure component arguments](/manuals/ai/sandboxes/customize/author/kit-sets.md#configure-component-arguments). diff --git a/content/manuals/ai/sandboxes/customize/author/tool-mixins.md b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md new file mode 100644 index 000000000000..69bc14701a19 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md @@ -0,0 +1,210 @@ +--- +title: Build a tool mixin +description: Package Claude Code as a reusable mixin with API access and credentials, test it in a shell workload, and publish it. +keywords: sandboxes, sbx, kits, mixins, tools, credentials, build +weight: 30 +aliases: + - /ai/sandboxes/customize/kit-examples/ +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +A tool mixin adds an executable and the settings it needs to an existing +workload. This tutorial packages Claude Code as a mixin, adds it to a shell +workload, and tests a request to the Anthropic API. The sandbox starts a shell, +and you choose when to run Claude Code. + +The example adapts the upstream +[Claude Code mixin](https://github.com/docker/sandbox-kit-spec/tree/main/examples/claude-mixin) +to use API-key authentication. The upstream example also includes OAuth, +session storage, and MCP configuration. + +You need `sbx`, Docker with Buildx, and an Anthropic API key. To publish the +mixin, you also need a registry namespace you can push to. Use a v3 workload +with this mixin. Built-in shortcuts such as `shell` and `claude` use v2. See +[Version compatibility](/manuals/ai/sandboxes/customize/_index.md#version-compatibility). + +## Package the executable + +Create a `claude-mixin` directory with a Dockerfile and YAML descriptor: + +```text +claude-mixin/ +├── claude-mixin.dockerfile +└── claude-mixin.yaml +``` + +The Dockerfile downloads the native Claude Code executable in a build stage, +then copies it into an empty image: + +```dockerfile {title="claude-mixin/claude-mixin.dockerfile"} +FROM debian:trixie-slim AS build +ARG CLAUDE_VERSION +ARG TARGETARCH +RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates +RUN case "$TARGETARCH" in \ + amd64) platform=linux-x64 ;; \ + arm64) platform=linux-arm64 ;; \ + *) echo "unsupported TARGETARCH: $TARGETARCH" >&2; exit 1 ;; \ + esac \ + && mkdir -p /out/usr/local/bin \ + && curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_VERSION}/${platform}/claude" \ + -o /out/usr/local/bin/claude \ + && chmod 0755 /out/usr/local/bin/claude + +FROM scratch +COPY --from=build /out/ / +``` + +BuildKit supplies `TARGETARCH` to select the download for the image's Linux +architecture. You'll set `CLAUDE_VERSION` in the descriptor. The final stage +contains only the executable, so the mixin doesn't add Debian or the download +tools to the workload. + +Docker Sandboxes adds the mixin's files to the workload's environment. The +workload keeps its own startup command, user, and working directory. This +example uses Docker's shell workload. When choosing another workload, check +that it supplies the Linux libraries and shell your tool needs. + +A mixin includes only the files its Dockerfile adds or changes. If you use +a larger base image instead of `scratch`, the mixin won't include that +image's unchanged files. + +## Declare runtime access + +Create the descriptor with the version to install and the API access Claude +Code needs: + +```yaml {title="claude-mixin/claude-mixin.yaml"} +# syntax=docker/sandbox-kit:3 +schemaVersion: "3" +kind: mixin +displayName: Claude Code mixin + +args: + version: + default: "2.1.278" + pattern: '^[0-9]+\.[0-9]+\.[0-9]+$' + buildArg: CLAUDE_VERSION + +provides: ["claude@${{ kit.args.version }}"] + +capabilities: + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + - api.anthropic.com:443 + - type: com.docker.sandbox/credential@1 + config: + service: anthropic + phase: runtime + apiKey: + name: ANTHROPIC_API_KEY + proxyManaged: true + inject: + - domain: api.anthropic.com + header: x-api-key + format: "%s" +``` + +The `version` argument supplies `CLAUDE_VERSION` to the Dockerfile. The +`provides` entry identifies the installed Claude Code version so other kits +can check their requirements. + +The network rule permits HTTPS requests to the Anthropic API. The credential +entry requests the key stored under `anthropic` on your host. Inside the +sandbox, `ANTHROPIC_API_KEY` contains a placeholder. The host proxy inserts +the real key into the `x-api-key` header when Claude Code calls the API. + +Network access and credential access are separate: declaring a credential +doesn't allow connections to its service. This example pairs `phase: runtime` +with `runtime.allow`. The download in the Dockerfile uses the builder's +network and doesn't need a rule in the descriptor. + +Keep the tool's access requirements in the mixin so they follow it when you +use it with another workload. Access shared by a project's tools, such as a +package registry, can go in a +[kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). + +## Try the mixin + +Store your Anthropic API key on the host: + +```console +$ sbx secret set anthropic +``` + +From the directory containing `claude-mixin`, add the mixin to Docker's +published shell workload: + +```console +$ sbx run docker.io/docker/sbx-kit-shell:1.0.0 --name claude-mixin-test \ + --kit ./claude-mixin +``` + +Approve the mixin's credential request when prompted. `sbx` builds the mixin, +adds its executable to the workload, and opens a shell. The mixin doesn't +replace the workload's launch command. + +Inside the sandbox, check that Claude Code runs: + +```console +$ claude --version +``` + +Then send a request to check network access and authentication. This command +uses the Anthropic API and incurs usage charges: + +```console +$ claude -p "Reply with the word hello." +``` + +A response confirms that Claude Code can reach the API and authenticate with +your stored key. If authentication fails, check that you stored the key and +approved the kit's request to use it. See +[Credential bindings](/manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). +Network requests must also meet the sandbox's +[network policy](/manuals/ai/sandboxes/governance/concepts.md#precedence). + +Run `claude` without arguments to start an interactive session. Follow its +first-run prompts. Exit Claude Code and the shell to return to your host. + +After editing the kit's files, create a sandbox with a different name to test +your changes. Reopening an existing sandbox uses the kits it was created with. + +## Publish the mixin + +Build and publish the mixin so others can use it without building from source: + +```console +$ docker login +$ docker buildx build ./claude-mixin -f ./claude-mixin/claude-mixin.yaml \ + -t docker.io/<NAMESPACE>/claude-mixin:1.0.0 --push +``` + +Replace `<NAMESPACE>` with a Docker Hub namespace you can push to. Use the +published reference with `--kit` in place of `./claude-mixin`. + +Choose a workload that doesn't already provide Claude Code. Two kits that +declare the same feature in `provides` conflict. To share the shell workload +and this mixin as one kit, see +[Compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). + +## More source examples + +The [sandbox-kit-spec examples](https://github.com/docker/sandbox-kit-spec/tree/main/examples) +contain complete kits you can study and adapt: + +- [Claude Code mixin](https://github.com/docker/sandbox-kit-spec/tree/main/examples/claude-mixin) + includes additional authentication options, session storage, and agent + instructions. +- [GitHub CLI](https://github.com/docker/sandbox-kit-spec/tree/main/examples/gh) + packages `gh` and its dependencies with network rules, credentials, and + agent instructions. +- [Message of the day](https://github.com/docker/sandbox-kit-spec/tree/main/examples/motd) + uses an inline Dockerfile and a build argument in a single-file mixin. + +For examples of building a tool from source, running setup scripts, and other +reusable approaches, see +[Kit authoring patterns](/manuals/ai/sandboxes/customize/author/patterns.md). diff --git a/content/manuals/ai/sandboxes/customize/build-an-agent.md b/content/manuals/ai/sandboxes/customize/build-an-agent.md deleted file mode 100644 index 237e25e209e2..000000000000 --- a/content/manuals/ai/sandboxes/customize/build-an-agent.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: Build your own agent kit -linkTitle: Build an agent -description: Walk through building an agent kit for Amp, from base image choice to invocation. -keywords: sandboxes, sbx, kits, agent, tutorial, amp, ampcode -weight: 30 ---- - -{{< summary-bar feature_name="Docker Sandboxes sbx" >}} - -> [!NOTE] -> Kits are experimental. The kit file format, CLI commands, and experience -> for creating, loading, and managing kits are subject to change as the -> feature evolves. Share feedback and bug reports in the -> [docker/sbx-releases](https://github.com/docker/sbx-releases) repository. - -This tutorial walks through building an agent kit for the -[Amp](https://ampcode.com/) coding agent. Each step explains the decision -behind a part of the spec, so you can apply the same reasoning to other agents. - -For reference on every field, see the [Kits](kits.md) page. This tutorial -focuses on the journey. - -The finished kit is also published as a runnable sample at -[docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/main/amp) — -useful as a reference while you follow along. - -## Choose a base image - -An agent kit needs a container image that satisfies the -[base image requirements](kits.md#base-image-requirements): non-root -`agent` user at UID 1000, passwordless sudo, `/home/agent/` home, and HTTP -proxy environment variable forwarding. - -Rather than build an image from scratch, extend one of the published -sandbox templates. Three common starting points: - -- `docker/sandbox-templates:shell`. Generic base with no pre-installed - agent. -- `docker/sandbox-templates:shell-docker`. Same, with Docker Engine inside - the sandbox. -- Agent-specific variants (`claude-code`, `codex`, etc.). Only useful if - you're extending that specific agent. - -For Amp, pick `shell-docker`: - -- Amp isn't pre-installed in any variant, so you need a generic base - (`shell`). -- Docker support is handy since coding agents often need to run containers. -- If you don't need Docker inside the sandbox, use the `shell` tag for a - lighter, non-privileged environment. - -## Plan authentication - -Amp authenticates with an API key in `AMP_API_KEY`. To keep the real key -out of the VM, you split the work in two: - -- The kit's network section maps the API host to a service identifier - and tells the proxy which header to inject. -- You provide your key once on the host, via sbx's secret store. The - real value stays on the host; only a placeholder reaches the sandbox. - -Inside the sandbox `AMP_API_KEY` is set to that placeholder. The proxy -substitutes the real key on outbound requests to the API host, so the -secret never enters the sandbox. A later section walks through the -specific command for storing the key. - -## Write the agent block - -The `agent:` block tells the sandbox how to launch Amp when the user -attaches. - -```yaml {title="amp/spec.yaml"} -schemaVersion: "1" -kind: agent -name: amp -displayName: Amp -description: The frontier coding agent. - -agent: - image: "docker/sandbox-templates:shell-docker" - aiFilename: AGENTS.md - persistence: persistent - entrypoint: - run: [amp, --dangerously-allow-all] -``` - -- `aiFilename: AGENTS.md` tells the sandbox to create `AGENTS.md` at launch - and append the [`memory`](#prime-amp-with-memory) block to it. Amp reads - this file for instructions. -- `persistence: persistent` keeps Amp's state (auth tokens, history) in a - named volume across sandbox restarts. Without it, you re-authenticate - every time. -- `entrypoint.run` runs `amp` in "YOLO-mode" when the sandbox starts. Adjust if - you want to pass different args on startup. - -## Install Amp - -Amp installs via a curl-to-bash script: - -```yaml -commands: - install: - - command: "curl -fsSL https://ampcode.com/install.sh | bash" - user: "1000" - description: Install Amp -``` - -Note `user: "1000"`. That's the agent user. Install commands run as root -(UID 0) by default, and Amp's installer puts the binary in the user's home -directory. Running as root would land the binary in `/root/` where the -agent can't reach it. - -## Allow network access - -The network block does two things: it lists the hosts the sandbox can -reach (`allowedDomains`), and it wires the kit-side half of the auth flow -from [Plan authentication](#plan-authentication) with `serviceDomains` and -`serviceAuth`. - -```yaml -network: - serviceDomains: - ampcode.com: amp - serviceAuth: - amp: - headerName: Authorization - valueFormat: "Bearer %s" - allowedDomains: - - "ampcode.com:443" - - "*.ampcode.com:443" -``` - -`allowedDomains` here covers the apex (`ampcode.com`) and the -install/CDN subdomains (`*.ampcode.com`). Treat it as a starting point; -Amp may reach other domains (model providers, analytics, updates) that -you'll discover by watching `sbx policy log` while testing. - -Kits can also declare `deniedDomains` for hosts the sandbox should not -reach, such as telemetry endpoints. Deny rules take precedence over -allow rules and apply only to sandboxes that use the kit. - -For the auth wiring, when the agent makes an outbound request to -`ampcode.com`, the proxy looks up the host in `serviceDomains` to find -the service id `amp`, then uses `serviceAuth.amp` to inject an -`Authorization: Bearer <key>` header. The `<key>` value comes from the -secret you'll register in -[Register your API key](#register-your-api-key), matched by host. The -service id (`amp`) is just a label that ties the two blocks together — -pick any name. - -> [!IMPORTANT] -> Keep `serviceDomains` narrow. Mapping `*.ampcode.com` would push the -> proxy into TLS-intercepting mode for every subdomain — including the -> binary CDN the install script downloads from — which corrupts those -> downloads. List only the host that actually needs auth. - -## Prime Amp with memory - -The `memory` field appends markdown to `AGENTS.md` at sandbox creation. -Use it to tell Amp about the sandbox environment so it knows the -conventions when it starts. - -```yaml -memory: | - ## Sandbox environment - - You are running inside a Docker sandbox. The workspace is mounted at - its absolute host path. `sudo` is passwordless; use it for package - installs. Docker is available inside the sandbox; containers you start - are isolated in the microVM. -``` - -Keep this short and sandbox-specific. For project instructions, put a -regular `AGENTS.md` in the workspace. - -## The full spec - -Putting it all together: - -```yaml {title="amp/spec.yaml"} -schemaVersion: "1" -kind: agent -name: amp -displayName: Amp -description: The frontier coding agent. - -agent: - image: "docker/sandbox-templates:shell-docker" - aiFilename: AGENTS.md - persistence: persistent - entrypoint: - run: [amp, --dangerously-allow-all] - -network: - serviceDomains: - ampcode.com: amp - serviceAuth: - amp: - headerName: Authorization - valueFormat: "Bearer %s" - allowedDomains: - - "ampcode.com:443" - - "*.ampcode.com:443" - -commands: - install: - - command: "curl -fsSL https://ampcode.com/install.sh | bash" - user: "1000" - description: Install Amp - -memory: | - ## Sandbox environment - - You are running inside a Docker sandbox. The workspace is mounted at - its absolute host path. `sudo` is passwordless; use it for package - installs. -``` - -## Register your API key - -Register your Amp API key on the host with `sbx secret set-custom`. The -value goes into the host secret store, and a placeholder is exposed -inside every sandbox you launch from this kit. - -Amp validates `AMP_API_KEY`'s format at startup, so the placeholder needs -to look like a real Amp key. Pick a placeholder shape that matches Amp's -expected format: - -```console -$ sbx secret set-custom -g \ - --host ampcode.com \ - --env AMP_API_KEY \ - --placeholder "sgamp-{rand}" \ - --value "$AMP_API_KEY" -``` - -`{rand}` expands to a random suffix at registration time. Inside the -sandbox `AMP_API_KEY` is set to that placeholder; Amp accepts it as a -syntactically valid key, and the proxy substitutes the real secret on -outbound requests to `ampcode.com`. - -> [!TIP] -> `sbx secret set-custom` is only required because Amp validates the -> key's format. If your agent reads the env var without a local format -> check, you can declare `environment.proxyManaged: [AMP_API_KEY]` in -> the kit instead and skip this user-side step — the proxy uses a -> default sentinel value (`proxy-managed`) that the agent never sees -> rejected. - -> [!NOTE] -> `sbx secret set-custom` is experimental and may change in future -> releases. This tutorial surfaces it because there's no other path to -> register a custom-format placeholder. - -## Run it - -Validate the spec: - -```console -$ sbx kit validate ./amp/ -``` - -Launch a sandbox with the kit, passing the kit's `name:` (`amp`) as the -agent argument: - -```console -$ sbx run --kit ./amp/ amp -``` - -The published copy of this kit also runs directly from the contrib -repository: - -```console -$ sbx run --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=amp" amp -``` - -## Iterate - -As you use the kit, you'll likely hit missing domains or install quirks. -Two loops help: - -- Watch the network policy log (`sbx policy log`) to catch blocked - requests, then add their domains to `allowedDomains`. -- Add domains to `deniedDomains` when the agent should stay blocked from - a host even if another policy permits it. -- Edit the spec and re-run `sbx run --kit ./amp/ amp` to pick up changes. - Remove the sandbox first (`sbx rm <name>`) for a clean start. - -Flesh out the `memory` block as you refine how Amp should behave in the -sandbox. - -## Publish - -Once the kit works, share it by packaging as a ZIP, pushing to an OCI -registry, or committing to a Git repository. See -[Packaging and distribution](kits.md#packaging-and-distribution) for the -`sbx kit` subcommands. - -## Adapt this to another agent - -Most of the specifics here are Amp's. To port the pattern, work through -the same decisions for your agent: - -- **Base image**: `shell-docker` if you need Docker inside the sandbox, - `shell` otherwise. Or extend either with your own image if the install - is heavy. -- **Install**: a `commands.install` block at runtime, or bake the agent - into a custom image. Pick install if it's a one-line script; bake if - the install is slow or you need a pinned version. -- **Network mapping**: list only the API host in `serviceDomains`, not - a wildcard. Keep install/CDN paths out of TLS-intercepting mode. Use - `deniedDomains` for hosts the agent should not reach. -- **Credential injection**: if the agent validates the API key's format - locally, register with `sbx secret set-custom` and pick a matching - placeholder. If it accepts the env var as-is, declare - `environment.proxyManaged` in the kit and skip the user-side step. - -The rest — memory block, network-policy iteration, packaging — is the -same regardless of agent. - -## Remove the stored secret - -To remove the entry created earlier with `sbx secret set-custom`, pass -the host to `sbx secret rm`: - -```console -$ sbx secret rm -g --host ampcode.com -``` - -The `--host` flag is part of the experimental `set-custom` surface and doesn't appear in `sbx secret rm --help`. diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md deleted file mode 100644 index 2e8556cead3a..000000000000 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Kit examples -linkTitle: Examples -description: Copy-and-adapt spec.yaml snippets for common mixin and agent kit patterns — static files, install commands, background services, initFiles, Claude Code skills, and agent forks. -keywords: sandboxes, sbx, kits, mixins, examples, patterns, skills -weight: 25 ---- - -{{< summary-bar feature_name="Docker Sandboxes sbx" >}} - -> [!NOTE] -> Kits are experimental. The kit file format, CLI commands, and experience -> for creating, loading, and managing kits are subject to change as the -> feature evolves. Share feedback and bug reports in the -> [docker/sbx-releases](https://github.com/docker/sbx-releases) repository. - -Each section below shows one `spec.yaml` snippet that demonstrates a -single kit pattern. These aren't complete, distributable kits — they're -small, focused examples you can lift into your own kit. For the full -spec reference, see [Kits](kits.md). - -## Drop a shared config file - -Use static files under `files/workspace/` when the content is the same -across every sandbox and doesn't need any runtime values substituted -in. Typical use cases: linter rules, editor settings, a shared -`.editorconfig`, team dotfiles. - -```text -ruff-lint/ -├── spec.yaml -└── files/ - └── workspace/ - └── ruff.toml -``` - -```yaml {title="ruff-lint/spec.yaml"} -schemaVersion: "1" -kind: mixin -name: ruff-lint -displayName: Ruff -description: Python linting with shared team config - -commands: - install: - - command: "uv tool install ruff@latest" - user: "1000" -``` - -```toml {title="ruff-lint/files/workspace/ruff.toml"} -line-length = 80 - -[lint] -select = ["E", "F", "I"] -``` - -## Install a tool at sandbox creation - -`commands.install` runs once per sandbox, at creation time. It's where -anything that needs to land in the image goes — package managers -(`apt-get`, `pip`, `npm`), binary downloads, or vendor install scripts. - -```yaml -commands: - install: - - command: "apt-get update && apt-get install -y jq" - - command: "curl -fsSL https://example.com/install.sh | sh" -``` - -Install commands run as root by default. Set `user: "1000"` when the -step should run as the agent user — for example, `npm install -g` -against a user-scoped prefix, or anything that writes to -`/home/agent/`. - -## Install an internal CA certificate - -If your organization uses a proxy that inspects HTTPS traffic, install -the proxy's internal root CA in the sandbox trust store. This helps -agents and SDKs trust certificates signed by the proxy. - -```text -internal-ca/ -├── spec.yaml -└── files/ - └── home/ - └── internal-ca.crt -``` - -Use a PEM-encoded certificate with a `.crt` extension. Files under -`files/home/` land in `/home/agent/` in the sandbox, so -`files/home/internal-ca.crt` becomes `/home/agent/internal-ca.crt` — -which is the path the install command reads from. If traffic can be -signed by more than one internal proxy, include each proxy's root CA in -the kit and install each certificate before running -`update-ca-certificates`. - -```yaml {title="internal-ca/spec.yaml"} -schemaVersion: "1" -kind: mixin -name: internal-ca - -commands: - install: - - command: "install -m 0644 /home/agent/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt && update-ca-certificates" - user: "0" - description: Install internal CA certificate -``` - -`update-ca-certificates` adds the certificate to the system trust -store, so tools and SDKs that read the system bundle trust the proxy's -certificates without further configuration. - -## Run a background service - -<!-- TODO: follow up on commands.startup[].background. - `background: true` on its own isn't enough to keep a - long-running service alive — the process exits shortly after start. - Using `nohup … &` inside a shell command is the current workaround - and what this section teaches. If background ever actually daemonizes - the command, this section can be simplified. --> - -`commands.startup` runs at every sandbox start. For long-running -services, background them inside a shell command and redirect output to -a log file. Relying on the `background: true` field alone can leave -the service attached to a shell that exits, which silently kills it. - -```yaml -commands: - startup: - - command: - - sh - - -c - - nohup my-service --port 8080 > /tmp/my-service.log 2>&1 & - user: "1000" -``` - -The log file is worth the extra flag: if the service exits early, its -stderr goes to a parent shell that isn't attached to anything you can -read. An empty log file tells you the wrapper ran; a populated one -tells you why it failed. - -## Bake runtime values into a file with initFiles - -When a config file needs a value that isn't known until sandbox start -— most often the absolute workspace path — use `commands.initFiles`. -The `${WORKDIR}` placeholder expands to the primary workspace path -when the file is written. - -```yaml -commands: - initFiles: - - path: /home/agent/.local/bin/start-code-server.sh - content: | - exec code-server --bind-addr 0.0.0.0:8080 --auth none "${WORKDIR}" - mode: "0755" - startup: - - command: - - sh - - -c - - nohup /home/agent/.local/bin/start-code-server.sh > /tmp/code-server.log 2>&1 & - user: "1000" -``` - -`mode: "0755"` makes the generated file executable so the startup -command can invoke it directly. - -Use `initFiles` instead of a static file whenever the content depends -on a runtime value. Use a static file otherwise. - -> [!TIP] -> This snippet is lifted from the -> [code-server kit](https://github.com/docker/sbx-kits-contrib/tree/main/code-server) -> in the contrib repository, which is also a runnable sample that demonstrates -> the full pattern. - -## Ship a Claude Code skill - -Claude Code reads project-scoped skills from -`.claude/skills/<name>/SKILL.md` in the workspace. Drop one into -`files/workspace/` and it's available in the sandbox. - -```text -docker-review/ -├── spec.yaml -└── files/ - └── workspace/ - └── .claude/ - └── skills/ - └── docker-review/ - └── SKILL.md -``` - -```yaml {title="docker-review/spec.yaml"} -schemaVersion: "1" -kind: mixin -name: docker-review -displayName: Dockerfile review skill -description: Ships a Claude Code skill that reviews Dockerfiles -``` - -```markdown {title="docker-review/files/workspace/.claude/skills/docker-review/SKILL.md"} ---- -name: docker-review -description: Review a Dockerfile for best practices. Use when the user asks to review, audit, or improve a Dockerfile. ---- - -When reviewing a Dockerfile, check: - -1. Base image — pinned tag or digest, appropriate for the workload -2. Layer order — dependencies copied before application source -3. Image size — multi-stage builds, `.dockerignore`, package-manager cache flags -4. Security — non-root `USER`, no secrets in `ARG`/`ENV` -5. Reproducibility — pinned package versions, frontend directive where relevant -``` - -Kits have to target the workspace rather than `~/.claude/` because -sandboxes don't pick up user-level agent configuration from the host. -See the -[FAQ](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) -for details. - -## Override agent settings - -Sandboxes seed settings files for some built-in agents during setup. -For example, the sandbox writes `/home/agent/.claude/settings.json` -for the `claude` agent. This happens after the kit's static files and -`initFiles`, so a kit can't override those paths with either mechanism. -Use `commands.startup` instead, which runs after the sandbox seeds its -files: - -```yaml -commands: - startup: - - command: - - sh - - -c - - | - mkdir -p /home/agent/.claude - cat > /home/agent/.claude/settings.json <<'JSON' - {"permissions": {"allow": ["Bash(echo:*)"]}} - JSON - user: "1000" - description: Write user-scope claude settings -``` - -Startup commands replay on every sandbox start, so the script must be -idempotent. The heredoc pattern overwrites cleanly each time. - -## Fork an existing agent - -Agent kits (`kind: agent`) define a full agent from scratch. The most -common variant is a fork of a built-in agent — same image and -credentials, but a different entrypoint. This example reproduces the -built-in `claude` agent but drops `--dangerously-skip-permissions` so -every tool call prompts for approval: - -```yaml {title="claude-safe/spec.yaml"} -schemaVersion: "1" -kind: agent -name: claude-safe -displayName: Claude Code (with approval prompts) -description: Claude Code without --dangerously-skip-permissions - -agent: - image: "docker/sandbox-templates:claude-code-docker" - aiFilename: CLAUDE.md - persistence: persistent - entrypoint: - run: [claude] - -network: - serviceDomains: - api.anthropic.com: anthropic - console.anthropic.com: anthropic - serviceAuth: - anthropic: - headerName: x-api-key - valueFormat: "%s" - allowedDomains: - - "claude.com:443" - -credentials: - sources: - anthropic: - env: - - ANTHROPIC_API_KEY -``` - -Launch with the kit's `name:` as the agent argument to `sbx run`: - -```console -$ sbx run claude-safe --kit ./claude-safe -``` - -For a step-by-step walkthrough of building a new agent kit from -scratch, see [Build an agent](build-an-agent.md). - -## More examples - -These patterns are all drawn from working kits in the -[sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib) -repository, which contains each example as a complete, loadable kit. -Use it to study the full shape of a kit, or load one directly: - -```console -$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=<kit>" -``` diff --git a/content/manuals/ai/sandboxes/customize/kits-v2.md b/content/manuals/ai/sandboxes/customize/kits-v2.md new file mode 100644 index 000000000000..6d83f41fa451 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/kits-v2.md @@ -0,0 +1,847 @@ +--- +title: Kits v2 +linkTitle: Kits v2 +description: Reference for v2 kits, including usage, schema fields, maintenance examples, signing, and migration to v3. +keywords: sandboxes, sbx, kits, v2, migration, spec.yaml +weight: 60 +aliases: + - /ai/sandboxes/customize/kits/ + - /ai/sandboxes/customize/kit-reference/ +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +V2 kits remain supported and are not deprecated. Built-in agent names such +as `claude` and `codex` select v2 kits and work with v2 mixins. This page +covers their usage and specification. For new kits, Docker recommends +[v3](/manuals/ai/sandboxes/customize/_index.md). V1 also remains supported. + +## Use existing kits + +A v2 kit contains `spec.yaml` with `schemaVersion: "2"` and an optional `files/` +tree. A sandbox kit defines the agent environment. A mixin adds tools or +configuration to it. Pass a sandbox kit in place of the agent name and add +mixins with `--kit`: + +```console +$ sbx run ./my-agent --name my-project --kit ./team-config +$ sbx run claude --name claude-project --kit ./team-config +``` + +`sbx run` uses your current directory as the workspace. Append a project path +to use another directory. To create without launching the agent, use +`sbx create`; include a workspace path or `.` to mount a directory. +References can be local directories, ZIP files, OCI artifacts, or Git URLs. +Start relative paths with `./` or `../`. For Docker Hub kits, you can omit +`docker.io/` and use `<NAMESPACE>/<KIT>:<TAG>`. In Git URLs, `ref` selects a +revision and `dir` the kit directory. Quote URLs containing `&`: + +```console +$ sbx run "git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent" +``` + +`git+ssh://` URLs work with your local SSH agent and Git credentials. +For private registries, see +[Registry credentials](../configuration/credentials.md#registry-credentials). + +Kit selection with `--kit` applies at creation. Recreate the sandbox to change +its kit set, except for the limited updates supported by +[`sbx kit add`](#execution-order). That command restarts the sandbox while +preserving packages, images, volumes, and agent history. Kits can't be +removed from a running sandbox. + +### Restrict kit sources + +See [Restrict kit sources](/manuals/ai/sandboxes/customize/use-kits.md#restrict-kit-sources) +for source policies. `kit.allowLocalKits` also governs v2 ZIP files. + +## Image overrides for built-in agents + +Use `--template` to replace a built-in agent's image while keeping its +configuration and launch command. The replacement image must support the +same agent. For example, an image used with `claude` must have Claude Code +installed. + +To define an environment with its own launch command and sandbox settings, +see [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md) +for the v3 workflow. + +### Choose a template + +Docker publishes agent images as `docker/sandbox-templates:<variant>`. +Choose the variant that matches your agent. See +[Base images](/manuals/ai/sandboxes/customize/author/base-images.md) +for the available variants. + +Variants with a `-docker` suffix, such as `claude-code-docker`, include +Docker Engine for building and running containers inside the sandbox. +Built-in agents use these variants by default when you don't specify a +custom template. + +If you don't need Docker inside the sandbox, select a variant without +the suffix. It uses fewer resources and doesn't require privileged mode: + +```console +$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code +``` + +Include the registry domain in `--template` image references. Unlike kit +references, template references don't automatically expand to include +`docker.io`. + +### Build a custom template + +Building a custom template requires +[Docker Desktop](/manuals/desktop/_index.md). + +Extend the Docker-provided image for the agent you plan to run. For example, +this Dockerfile adds Rust and protocol buffer tools to the Claude Code image: + +```dockerfile +FROM docker/sandbox-templates:claude-code +USER root +RUN apt-get update && apt-get install -y protobuf-compiler +USER agent +RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +``` + +Install system packages as `root`, then switch back to `agent` before +installing tools in the agent's home directory. + +Build the image and push it to a registry. Replace `<NAMESPACE>` with a +Docker Hub namespace you can push to: + +```console +$ docker build -t docker.io/<NAMESPACE>/my-template:v1 --push . +``` + +For registry credentials and loading a locally built image, see +[Load a template](/manuals/ai/sandboxes/usage.md#load-a-template). + +Run the sandbox with your image: + +```console +$ sbx run claude --template docker.io/<NAMESPACE>/my-template:v1 +``` + +Because this image extends `claude-code`, use it with `claude`. For an +image based on `codex`, use `codex`. For one based on `shell`, use `shell` +to open Bash without an agent. + +If your added tools need network access, allow the domains they use in +the sandbox's network policy, unless you use the `allow-all` policy: + +```console +$ sbx policy allow network "*.example.com:443,example.com:443" +``` + +## Kit kinds + +### `kind: mixin` + +A mixin layers capabilities onto an existing sandbox. It must not declare a +`sandbox:` block, `extends:`, or `mixins:`. A mixin can declare `requires:` to +pin the base agent it is designed for: + +```yaml +schemaVersion: "2" +kind: mixin +name: github-tools +requires: + agent: claude +``` + +`requires.agent` takes one base-agent name. It is validated as a kit name and +enforced during composition. + +### `kind: sandbox` + +A sandbox kit defines a full agent. A root sandbox must declare a `sandbox:` +block. A sandbox that uses `extends:` can inherit the parent image and omit its +own `sandbox:` block: + +```yaml +schemaVersion: "2" +kind: sandbox +name: claude-safe +extends: claude +``` + +`extends:` is sandbox-only. The parent must resolve to a sandbox kit. `mixins:` +is also sandbox-only and accepted by the parser, but runtime composition support +is pending. + +## Top-level fields + +For the normative grammar, see the +[v2 specification](https://github.com/docker/sbx-kits-contrib/blob/main/spec/SPEC-v2.md). + +| Field | Required | Description | +| --------------- | -------- | ----------------------------------------------------------------------------------------------- | +| `schemaVersion` | Yes | Spec schema version. Use `"2"` for this grammar. | +| `kind` | Yes | `mixin` for kits that extend an agent; `sandbox` for kits that define one. | +| `name` | Yes | Unique identifier. Lowercase alphanumeric with hyphens, 1 to 64 characters. | +| `version` | No | Kit version. | +| `displayName` | No | Human-readable name. | +| `description` | No | Short description. | +| `sourceURL` | No | Source repository or documentation URL. | +| `licenses` | No | SPDX license identifiers. | +| `locked` | No | Dotted paths child kits may not override. | +| `security` | No | Container security settings. `security.privileged: true` runs the container in privileged mode. | +| `args` | No | Arguments supplied when the kit is loaded. Schema v2 only. | + +A kit also declares behavior blocks such as `agentInstructions`, +`permissions`, `ports`, `credentials`, `environment`, `setup`, and `volumes`. + +## Arguments + +A schema v2 kit can declare arguments and reference them anywhere in +`spec.yaml` or under `files/` as `${{ kit.args.<name> }}`. Substitution happens +before the spec is decoded. + +```yaml +args: + version: + default: latest + description: Tool version to install + pattern: '^(latest|[0-9]+\.[0-9]+\.[0-9]+)$' + channel: + default: stable + enum: [stable, beta, nightly] + target: + required: true + description: Build target + +environment: + variables: + TOOL_VERSION: "${{ kit.args.version }}" +``` + +Don't use kit arguments for API tokens, passwords, or other secrets. Use +[Credentials](../configuration/credentials.md) to provide sensitive values to +a sandbox. + +| Field | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------ | +| Argument name | Starts with a letter or underscore and contains only letters, digits, underscores, and hyphens. | +| `default` | String to use when the caller supplies no value. Mutually exclusive with `required: true`. | +| `required` | Set to `true` when the caller must supply a value. Mutually exclusive with `default`. | +| `description` | Optional help text shown when a required value is missing. | +| `enum` | Optional list of accepted values. Mutually exclusive with `pattern`. | +| `pattern` | Optional Go RE2 regular expression matched against the complete value. Mutually exclusive with `enum`. | + +Each argument must declare either `default`, including an empty-string +default, or `required: true`. + +Argument values are strings, but substitution happens before YAML decoding. +Quote a placeholder in a string-valued field so a value such as `1.20` isn't +decoded as a number. + +### Pass arguments to kits + +Use `--kit-arg name=value` for every kit declaring that argument, or prefix +with the kit's `name` to target one kit. Scoped values override shared values: + +```console +$ sbx run ./my-agent --kit ./my-mixin --kit-arg channel=stable \ + --kit-arg my-mixin.channel=beta +``` + +`--kit-args-file <FILE>` reads `name=value` entries, ignoring blank lines and +`#` comments. Later files override earlier files; `--kit-arg` overrides files. +For repeated CLI keys, the last value wins. Missing required values, unknown +arguments, undeclared placeholders, and invalid values fail before creation. +Pass the same flags to `sbx kit validate` or `sbx kit inspect` when needed. +Argument values can remain in shell history and are stored unencrypted in +argument files. + +## Sandbox block + +```yaml +sandbox: + image: <image-ref> + build: + context: . + dockerfile: Dockerfile + args: + AGENT_VERSION: "1.0.0" + target: runtime + platforms: + - linux/amd64 + entrypoint: [my-agent, "--flag"] + command: + default: ["--task-mode"] + interactive: [] + resources: + cpu: 2 + memory: 4g + gpu: "1" +``` + +| Field | Required | Description | +| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `sandbox.image` | When `extends:` is omitted | Docker image reference. | +| `sandbox.build` | No | Build configuration. Runtime support is pending, so a kit with `build:` must also set `image:`. | +| `sandbox.entrypoint` | No | Fixed process prefix as a string array. The first element is the agent binary. | +| `sandbox.command` | No | Mode-specific argument tail. Use a list shorthand for `default`, or a mapping with `default` and `interactive`. | +| `sandbox.resources` | No | Optional CPU, memory, and GPU constraints. Memory uses byte-size strings such as `4096m` or `4g`. | + +The effective command is `entrypoint` plus `command.default` for non-interactive +launches, and `entrypoint` plus `command.interactive` for TTY sessions. If +`interactive` is omitted, it falls back to `default`. + +For a kit that uses `extends:`, `sandbox.command` replaces the full inherited +argument tail, including flags after the binary in the parent's +`sandbox.entrypoint`. It doesn't append to that tail. Define every argument the +child needs. For example, a child of `claude` that adds `--settings` must also +include `--dangerously-skip-permissions` to preserve that behavior. + +The agent's container image must provide: + +- A non-root `agent` user at UID 1000 with passwordless sudo. +- A `/home/agent/` home directory owned by `agent`. +- HTTP proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) preserved across sudo. +- The agent binary, either baked in or installed with [`setup.install`](#setup). + +Build on top of `docker/sandbox-templates:shell-docker` to get these base +requirements. + +## Agent instructions + +Declare these fields under `agentInstructions`: + +| Field | Description | +| ---------- | --------------------------------------------------------------------------------------------------- | +| `filename` | AI profile filename. Meaningful for `kind: sandbox`; ignored with a warning for `kind: mixin`. | +| `content` | Markdown instructions. For a sandbox, inlined into the profile. For a mixin, written to kit memory. | + +For mixins, the engine writes `content` to +`<dir-of-AI-file>/kits-memory/<kit-name>.md` and adds a `## Kits` pointer +section to the base AI file. This keeps each mixin's instructions in a separate +file. + +The generated profile lives in the parent directory of the mounted workspace +inside the sandbox. It sits outside the mount and doesn't replace an +instruction file in the project. The sandbox kit's inline instructions go +directly into that profile. + +## Credentials + +A kit declares the credentials it needs and how the proxy injects them into +outbound requests. It does not declare a host discovery source. The user +provides the value through the secret store or the first-run prompt, and a +[credential binding](../configuration/credentials.md) authorizes its use. A kit +can't read arbitrary host environment variables or files. + +`credentials` is a list; each entry names a `service` and configures one or more +auth mechanisms. + +| Field | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `service` | Credential identifier, matched against the value stored with `sbx secret set`. Lowercase kebab-case. | +| `description` | Optional. Shown to the user when approving a [binding](../configuration/credentials.md#credential-bindings). | +| `required` | Marks the credential as essential to the agent. If it has no binding, `sbx` warns and starts with the credential withheld. Default `false`. | +| `provider` | Reserved for a provider registry. Accepted with a warning and no runtime effect. | +| `apiKey` | API-key injection (see [apiKey](#apikey)). | +| `oauth` | OAuth interception (see [oauth](#oauth)). | + +Each service must declare `apiKey`, `oauth`, or both. When both resolve at +runtime, the API key takes precedence and OAuth acts as the fallback. + +### `apiKey` + +| Field | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Environment variable name for the credential (for example, `ANTHROPIC_API_KEY`). | +| `proxyManaged` | If `true`, `sbx` sets `name` inside the container to the `proxy-managed` sentinel. Default `false`. | +| `inject[].domain` | Domain to inject the credential into. Must also be allowed in [`permissions.network`](#network). | +| `inject[].header` | HTTP header the proxy sets (for example, `x-api-key`, `Authorization`). | +| `inject[].format` | Header value format, with one `%s` placeholder (for example, `"%s"` or `"Bearer %s"`). Mutually exclusive with `scheme`. | +| `inject[].scheme` | Shorthand for common auth schemes. `bearer` expands to `Authorization: Bearer %s`; `basic` requires `username`. Mutually exclusive with `format`. | +| `inject[].username` | Username for HTTP Basic auth, for example `x-access-token` for Git over HTTPS. | + +### `oauth` + +For agents that authenticate with OAuth (for example, Claude Code), the proxy +intercepts token responses and replaces real tokens with sentinels, then swaps +the real token back in on outbound requests. By default, the token never enters +the sandbox. Setting `passthrough: true` opts out of sentinel masking and sends +the real token response into the sandbox. + +| Field | Description | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tokenEndpoint.host` / `path` | The OAuth token endpoint the proxy intercepts. | +| `sentinels.accessToken` / `refreshToken` | Sentinel values written into the container in place of the real tokens. | +| `credentialFile.path` | Where to write the credential file inside the container (`~` expands). | +| `credentialFile.structure` | Declarative JSON shape. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, and `{{.Scopes}}`. | +| `credentialFile.template` | Go template. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, `{{.Scopes}}`, and `{{.ScopesJSON}}`. | +| `resourceHosts` | API hosts where the proxy attaches the token on outbound requests, distinct from the token endpoint host. | +| `skipIfEnv` | Accepted for compatibility, but ignored for schema v2. A v2 binding is authoritative instead of host environment variables. | +| `responseFields` | Overrides the default field names the proxy reads from the token response. | +| `passthrough` | If `true`, the proxy passes the token response through unchanged instead of replacing the tokens with sentinels. | + +`credentialFile.structure` provides a declarative alternative to +`credentialFile.template`. The engine renders it as well-formed JSON. If both +fields are set, `structure` takes precedence. + +## Network + +Network egress is declared under `permissions.network`. Credentials no longer carry +their own domain mapping — the proxy injects a credential only into the domains +its [`apiKey.inject`](#apikey) lists, and every domain the +sandbox reaches must be allowed here. + +| Field | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `permissions.network.allow` | Domains the sandbox can reach. | +| `permissions.network.deny` | Domains the sandbox is blocked from reaching. Deny takes precedence over allow, including across composed kits. | + +Allow and deny patterns: + +| Pattern | Example | Status | +| --------------------- | ------------------------ | --------------------------- | +| Exact host | `api.example.com` | Enforced | +| Exact host and port | `api.example.com:8080` | Enforced | +| Single-label wildcard | `*.example.com` | Enforced | +| Multi-label wildcard | `**.example.com` | Parsed; enforcement pending | +| Port range | `api.example.com:80-443` | Parsed; enforcement pending | +| Port wildcard | `api.example.com:*` | Parsed; enforcement pending | +| CIDR | `10.0.0.0/8` | Parsed; enforcement pending | + +In v1 this was the `network:` block (`allowedDomains` / `deniedDomains`, plus +`serviceDomains` / `serviceAuth`). In v2, those fields are decode errors. + +## Ports + +Declare `ports` as a list of entries to expose sandbox services to the host: + +| Field | Description | +| ----------- | ------------------------------------------------------------------- | +| `container` | Container port, 1 to 65535. | +| `protocol` | `tcp` or `udp`. Empty publishes one family; see below. | +| `name` | Optional label surfaced by tools that list published port bindings. | + +Host ports are allocated ephemerally. Leave `protocol` empty unless the service +listens on IPv6: an empty value publishes IPv4 only (`127.0.0.1`), which is what +a service bound to `0.0.0.0` needs, while `tcp` publishes both `127.0.0.1` and +`::1` — and a client arriving over `::1` is accepted and then reset if nothing +in the sandbox is listening there. Users can pin host ports with +`sbx ports --publish <host>:<container>`. + +## Environment + +| Field | Description | +| ----------- | ---------------------------------------------- | +| `environment.variables` | Key-value pairs set directly in the container. | + +Do not set `DASH_`, `SBX_`, or `DOCKER_` variables, and avoid overriding +`HOME`, `USER`, `SHELL`, `PATH`, `LD_PRELOAD`, and `LD_LIBRARY_PATH`. The +runtime reserves these names and may override them. + +## Setup + +`setup.install`, `setup.startup`, and `setup.files` are lists of commands or +files with the fields described here. + +### Execution order + +When a sandbox is created, kit content is applied in this order: + +1. Network permissions and environment variables. +2. Static files under `files/home/`. +3. `setup.install` commands, in declaration order. +4. `setup.files` entries. +5. `setup.startup` commands are registered for each sandbox start. +6. Static files under `files/workspace/`, after the workspace is ready. With + `--clone`, this means after the repository has been cloned. + +For stacked kits, entries in each stage are applied in `--kit` order. An install +command can consume a bundled file from `files/home/`, but not one from +`files/workspace/` or `setup.files`, because those files land later. + +`sbx kit add` recreates the sandbox rather than modifying it in place. It +supports mixin kits limited to +`environment.variables`, `setup.install`, `setup.startup`, and +`permissions.network.allow`, which follow the same order as sandbox creation. +Startup commands run after the kit is added and on each subsequent sandbox +start. The command rejects kits that declare static files or `setup.files`. +To use those fields, create the sandbox with the kit included. + +### install + +Runs synchronously when a kit is applied, either during sandbox creation or +through `sbx kit add`. Shell strings are passed to `sh -c`. + +Kit install commands start in the template image's configured `WORKDIR`. +Docker-provided templates use `/home/agent/workspace`, which isn't necessarily +the primary workspace in a direct-mounted or clone-mode sandbox. Don't rely on +the current directory to locate workspace files. Use absolute paths for bundled +assets from `files/home/`. + +| Field | Default | Description | +| ------------- | ------- | ----------------------------- | +| `command` | — | Shell command string. | +| `user` | `"0"` | User to run as. `"0"` = root. | +| `description` | — | Human-readable description. | + +### startup + +Runs at every sandbox start. String array, not interpreted by a shell. A +`$WORKSPACE_DIR` reference in the array is passed unchanged. To expand it, run +the command through a shell, for example `["sh", "-c", "..."]`. + +| Field | Default | Description | +| ------------- | -------- | ----------------------------------- | +| `command` | — | Command and args as a string array. | +| `user` | `"1000"` | User to run as. `"1000"` = agent. | +| `background` | `false` | Block later startup commands until this command finishes. Set to `true` to let later commands run without waiting. | +| `description` | — | Human-readable description. | + +Startup commands are non-interactive. They run before the agent +attaches, with no terminal connected, so they can't prompt the user +(for example, an interactive `aws login` will hang or fail). They also +don't gate the agent's entrypoint: the agent launches once startup +commands have been dispatched, regardless of `background`. A value of +`false` waits within the startup dispatcher before it runs the next command; +it doesn't delay the agent entrypoint. Use startup commands +for work that can run alongside the agent. Use `setup.files` for any value that +needs to land on disk before the agent runs. + +Startup commands must be idempotent. They run on every sandbox start +and replay on container restarts, so a command that fails or +misbehaves on a second invocation breaks the restart path. Guard +work with existence checks, use upserts instead of inserts, and +prefer commands that converge to the same end state regardless of +how many times they run. + +### files + +Files written at sandbox start, with runtime substitution. + +| Field | Default | Description | +| --------------- | -------- | --------------------------------------------------------- | +| `path` | — | Absolute container path. | +| `content` | — | File content. Write `${WORKDIR}` for the workspace path. | +| `mode` | `"0644"` | File permissions in octal. | +| `onlyIfMissing` | `false` | Skip if the file already exists. | + +The runtime writes these files as the agent user with UID 1000. The target +path must be writable by that user. To write to a root-owned path such as +`/etc`, use an `install` command, which runs as root by default. Set ownership +in the install command if the agent needs to modify the file later. + +Write `${WORKDIR}` in `content` and `$WORKSPACE_DIR` in commands. Three names +look alike and mean different things: + +| Name | What it is | Where it applies | +| --------------- | ------------------------------------------------------------- | ------------------------------------------------ | +| `${WORKDIR}` | Placeholder for the workspace path | `setup.files[].content` only | +| `WORKSPACE_DIR` | Environment variable set by the runtime to the workspace path | Shell commands, and the agent | +| `WORKDIR` | The template image's Dockerfile working directory | Where commands start, see [install](#install) | + +The runtime replaces `${WORKDIR}` when it creates the sandbox, only inside +`content`, never in `path` or in commands. `WORKSPACE_DIR` is an environment +variable, so a `$WORKSPACE_DIR` reference expands only when a shell runs the +command. `install` strings run through `sh -c`. `startup` arrays run without a +shell. A Dockerfile `WORKDIR` doesn't define an environment variable. + +### Shell initialization and service logs + +With Docker templates, append shell initialization to +`/etc/sandbox-persistent.sh` in an install command. Keep existing content and +omit completion scripts: interactive and non-interactive Bash commands source +this file. For a background service, redirect startup output to a file and +read it with `sbx exec`. Use `background: true` instead of a trailing `&`. + +## Static files + +```text +my-kit/files/ +├── home/ → /home/agent/ +└── workspace/ → primary workspace path +``` + +| Kit path | Container destination | +| ------------------ | --------------------------------------- | +| `files/home/` | `/home/agent/` (config files, dotfiles) | +| `files/workspace/` | The primary workspace path | + +Parent directories are created automatically. Existing files are +overwritten. Absolute paths and path-traversal sequences (`../../`) are +rejected. + +Static files can supply linter settings, helper scripts, or agent skills. +For example, a Claude Code project skill belongs at +`files/workspace/.claude/skills/<NAME>/SKILL.md`. + +## Volumes + +Declare `volumes` as a list of mounts with these fields: + +| Field | Description | +| ------ | ------------------------------------------------------------------- | +| `path` | Required absolute container path. | +| `type` | Empty for a block-backed volume, or `tmpfs` for RAM-backed storage. | +| `size` | Optional byte-size string. | +| `mode` | Optional octal permissions. | + +Volumes are applied only when a sandbox is created. `sbx kit add` cannot attach +volumes to a running container. + +## Fork an existing agent + +Sandbox kits (`kind: sandbox`) define a full agent from scratch. The most +common variant is a fork of a built-in agent. Use `extends:` to inherit the +parent's complete configuration and declare only the fields you want to change. +This example replaces the built-in `claude` entrypoint so Claude Code uses +manual permission mode instead of bypassing approval prompts: + +```yaml {title="claude-safe/spec.yaml"} +schemaVersion: "2" +kind: sandbox +name: claude-safe +displayName: Claude Code (with approval prompts) +description: Claude Code in manual permission mode + +extends: claude + +sandbox: + entrypoint: [claude, "--permission-mode", "manual"] +``` + +The child inherits the built-in image, credentials, network permissions, +persistent volumes, settings, MCP integration, agent instructions, setup +entries, and environment variables. Its `sandbox.entrypoint` replaces the +inherited entrypoint. + +Launch by passing the sandbox kit in place of a built-in agent name: + +```console +$ sbx run ./claude-safe +``` + +## Install an internal CA certificate + +Put each PEM-encoded root certificate under `files/home/` with a `.crt` +extension. For `files/home/internal-ca.crt`, use: + +```yaml {title="internal-ca/spec.yaml"} +schemaVersion: "2" +kind: mixin +name: internal-ca +setup: + install: + - command: "install -m 0644 /home/agent/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt && update-ca-certificates" + user: "0" +``` + +This updates the system trust store. For several CAs, install every +certificate before running `update-ca-certificates`. + +## Sandbox-managed agent configuration + +Built-in agent kits reserve the following paths for sandbox setup. Treat these +paths as sandbox-managed, even if a file is only needed for a particular +feature. Don't target them with static files, `setup.files`, or install +commands. Later setup can replace your content or depend on settings that your +file removes. In this table, `~` is `/home/agent`. + +| Built-in agent kit | Managed configuration paths | +| ------------------ | --------------------------- | +| `claude` | `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/.config.json` | +| `codex` | `~/.codex/config.toml` | +| `copilot` | `~/.copilot/config.json` | +| `cursor` | `~/.cursor/cli-config.json` | +| `devin` | `~/.config/devin/config.json`, `~/.config/devin/mcp_config.json` | +| `gemini` | `~/.gemini/settings.json` | +| `kiro` | `~/.kiro/settings/mcp.json` | +| `opencode` | `~/.config/opencode/opencode.json` | + +Use separate settings files when supported: Claude Code accepts `--settings`, +and OpenCode reads `OPENCODE_CONFIG`. Don't use `setup.startup` for settings +the agent must read during initialization; startup commands don't gate the +entrypoint. + +## Validate and inspect kits + +Use these commands to check a kit before sharing it: + +- `sbx kit validate <path>` — check that a kit directory or ZIP is + well-formed. +- `sbx kit inspect <path>` — display kit details. Add `--json` for + machine-readable output. + +Add `--offline` to validate or inspect a local directory or ZIP without starting +the daemon or signing in. Offline checks skip kit source and signature policies; +they don't establish whether the kit is permitted to load. + +## Packaging and distribution + +- `sbx kit pack <path> -o <file.zip>` — package a directory as a ZIP file + for sharing. +- `sbx kit push <path> <ref>` — publish to an OCI registry (for example, + `ghcr.io/myorg/my-kit:1.0`). +- `sbx kit pull <ref>` — download a kit to the working directory as `.zip` + for schema v1 or `.tar.gz` for schema v2. Use `--output <FILE>` to choose + the output path. + +For Docker Hub, `sbx kit pull` and `sbx kit push` use the session from +`sbx login`. For other registries, they prefer credentials stored with +[`sbx secret set --registry`](../configuration/credentials.md#registry-credentials). +Both commands fall back to the Docker credential store, so credentials from +`docker login` also work. + +## Sign and verify kits + +Use cosign-compatible Sigstore signatures to verify who approved a kit and +that its signed content hasn't changed. Signing is keyless by default. Verify a +keyless signature with the certificate identity and OpenID Connect (OIDC) +issuer: + +```console +$ sbx kit sign ./my-kit/ +$ sbx kit verify \ + --certificate-identity user@example.com \ + --certificate-oidc-issuer https://accounts.google.com \ + ./my-kit/ +``` + +For key-based signing, use an ECDSA P-256 key pair: + +```console +$ sbx kit sign --key cosign.key ./my-kit/ +$ sbx kit verify --key cosign.pub ./my-kit/ +``` + +For a local directory, `sbx kit sign` writes a `kit.sig.bundle` file next to +`spec.yaml`. Commit this file so consumers can verify a kit loaded from the Git +repository. + +Git line-ending conversion and clean filters can invalidate a source signature. +If `sbx kit sign` warns about these transformations, ensure Git preserves the +signed files unchanged before sharing the Git reference. + +For an OCI kit, the signature is stored as an OCI referrer. You can sign an OCI +kit after pushing it, or push and sign it in one step: + +```console +$ sbx kit push ./my-kit/ ghcr.io/myorg/my-kit:1.0 --sign +``` + +ZIP kits can't carry verifiable signatures. + +### Inspect provenance + +Pushing a kit also attaches a provenance attestation that records its content +digests, declared sandbox image, and source Git commit when pushed from a +working tree. Inspect it to check the source of a published kit: + +```console +$ sbx kit provenance ghcr.io/myorg/my-kit:1.0 +``` + +Provenance is unsigned by default. Use `sbx kit push --sign` to sign both the +kit manifest and its provenance when publishing. + +### Require signed kits + +Set [`kit.trustedSigners`](../configuration/settings.md#kittrustedsigners) to +the identities or keys you trust before requiring signatures. Otherwise, `sbx` uses the default policy, which trusts +Docker employee identities attested by Google's OpenID Connect issuer. A +keyless policy must specify both the certificate identity and its OpenID +Connect issuer: + +```console +$ sbx settings set kit.trustedSigners \ + '[{"identity":"release-bot@example.com","issuer":"https://accounts.google.com"}]' +$ sbx settings set kit.requireSignature true +``` + +To trust a key-based signature, set the policy to the public key path: + +```console +$ sbx settings set kit.trustedSigners '[{"key":"/path/to/cosign.pub"}]' +$ sbx settings set kit.requireSignature true +``` + +When `kit.requireSignature` is `true`, `sbx` rejects unsigned kits, signatures +that don't match `kit.trustedSigners`, and ZIP kits. This policy applies when a +kit is loaded from a local directory, Git repository, or OCI registry. + +The signature covers `spec.yaml` and the kit's `files/` content, but not mutable +dependencies such as image tags or content downloaded by install and startup +commands. Pin those dependencies by digest or checksum when they must remain +immutable. + +## Schema versions + +Schema v2 is supported starting with Docker Sandboxes version 0.36. Use +`schemaVersion: "2"` for the syntax on this page. Version `"1"` also remains +accepted. V3 is a separate format for environments built entirely +with v3 workloads and mixins. V3 kits can't compose with v1 or v2 kits. +See [Kits v3](/manuals/ai/sandboxes/customize/_index.md) for that workflow. + +When migrating to `schemaVersion: "2"`, replace v1 fields with their v2 +equivalents: + +| v1 | v2 | +| ------------------------------------------- | ---------------------------------------- | +| `credentials.sources.<id>` | `credentials:` list entry with `service` | +| `network.allowedDomains` / `deniedDomains` | `permissions.network.allow` / `deny` | +| `network.serviceDomains` / `serviceAuth` | `credentials[].apiKey.inject` | +| `network.publishedPorts` / `publishedPorts` | top-level `ports` | +| standalone `oauth:` block | `credentials[].oauth` | +| `oauth.skipIfEnv` | Accepted but ignored | +| `environment.proxyManaged` | `credentials[].apiKey.proxyManaged` | +| `memory` / `agentContext` | `agentInstructions.content` | +| `kind: agent` / `agent:` block | `kind: sandbox` / `sandbox:` block | +| `sandbox.aiFilename` | `agentInstructions.filename` | +| `sandbox.entrypoint.run` | `sandbox.entrypoint` | +| `sandbox.entrypoint.args` | `sandbox.command.default` | +| `sandbox.entrypoint.ttyArgs` | `sandbox.command.interactive` | +| `tmpfs:` | `volumes:` entries with `type: tmpfs` | +| `volumes:` (mapping form) | `volumes:` sequence (`- path: <path>`) | +| `commands:` / `commands.initFiles` | `setup:` / `setup.files` | +| `settings:` / `kitDir` / `persistence` | Removed | + +Credential discovery also moved out of the kit in v2: a kit declares which +credentials it needs and how to inject them, but where each value comes from is +controlled by the user through +[credential bindings](../configuration/credentials.md#credential-bindings). + +> [!NOTE] +> `mixins` and `sandbox.build` are accepted by the parser, but runtime support +> is pending. A kit that sets `sandbox.build` must also set `sandbox.image`. + +## Move an environment to v3 + +Select a [v3 workload](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads), +convert or replace its mixins, and create a separate sandbox. Every selected +kit must use v3. Running an existing sandbox keeps its recorded kit configuration. + +For an environment file, see [Add v3 kits](/manuals/ai/sandboxes/configuration/environment-files.md#add-v3-kits). +Keep its `schemaVersion: "1"`: the environment file version is independent of +kit descriptor versions. + +Changing `schemaVersion` alone doesn't convert a kit. Separate reusable image +content from sandbox initialization, and declare runtime capabilities: + +| V2 surface | V3 equivalent | +| --- | --- | +| `kind: sandbox` | `kind: workload` with a Dockerfile recipe | +| `sandbox.image` | Dockerfile `FROM` | +| `sandbox.entrypoint`, `sandbox.command`, `environment.variables` | Dockerfile `ENTRYPOINT`, `CMD`, and `ENV` | +| `extends` | A mixin for composition, or a derived workload image with its own descriptor | +| `setup.install` | Dockerfile `RUN` for reusable content; lifecycle `install` for sandbox initialization | +| `setup.startup` and `setup.files` | Lifecycle capability `startup` and `files` | +| `setup.files[].onlyIfMissing: true` | Lifecycle `files[].overwrite: false` | +| Automatic `files/home/` and `files/workspace/` injection | Dockerfile `COPY`, with lifecycle hooks for destinations provided by runtime mounts | +| `permissions.network` and `credentials` | Network-policy and credential capabilities | +| `agentInstructions` | Agent-context capability | +| `${WORKDIR}` in `setup.files[].content` | `${{ kit.env.WORKSPACE_DIR }}` in lifecycle [`files` content](/manuals/ai/sandboxes/customize/author/_index.md#generated-files) | + +Follow the [v3 authoring guidance](/manuals/ai/sandboxes/customize/author/_index.md) +when converting runtime setup and capability declarations. +Use a [kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md) to combine +published v3 components with your settings. To rebuild the agent environment +from a base image, follow [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md). diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md deleted file mode 100644 index eb7038d8f79a..000000000000 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ /dev/null @@ -1,793 +0,0 @@ ---- -title: Kits -description: Extend a sandbox with tools, credentials, network rules, and configuration using declarative YAML artifacts. -keywords: sandboxes, sbx, kits, mixins, customization, extensions, agents -weight: 20 ---- - -{{< summary-bar feature_name="Docker Sandboxes sbx" >}} - -> [!NOTE] -> Kits are experimental. The kit file format, CLI commands, and experience -> for creating, loading, and managing kits are subject to change as the -> feature evolves. Share feedback and bug reports in the -> [docker/sbx-releases](https://github.com/docker/sbx-releases) repository. - -A kit packages a set of capabilities a sandbox can use, such as: - -- Tools to install -- Environment variables to set -- Credentials to inject -- Network rules to allow or deny domains -- Files to drop in -- Startup commands to run -- Memory instructions to give the agent - -You declare these in a single `spec.yaml` file, point the CLI at the -directory (or a ZIP, OCI artifact, or Git URL), and the sandbox applies -and enforces them at runtime. Credentials stay on the host and go through -a proxy instead of entering the VM, and outbound traffic is restricted to -the domains permitted by the kit's network rules. - -A kit is either a mixin or an agent: - -- Mixin kits (`kind: mixin`) extend an existing agent with extra - capabilities. Stack several on the same sandbox. -- Agent kits (`kind: agent`) define a full agent from scratch: its image, - entrypoint, network policies, and everything else the agent needs. - -## What kits can do - -### Run commands - -A kit can run commands inside the sandbox automatically. **Install -commands** run once at creation; **startup commands** run each time -the sandbox starts. - -Install commands are the place to put anything an agent needs into the -image, via `apt`, `pip`, `npm`, `curl | bash`, or whatever fits: - -```yaml -commands: - install: - - command: "apt-get update && apt-get install -y jq" -``` - -Startup commands cover things like launching background services, -warming caches, or refreshing config on each start. They must be -idempotent — see the [`startup`](#startup) spec reference: - -```yaml -commands: - startup: - - command: ["sh", "-c", "my-daemon &"] -``` - -### Inject files - -Kits can inject files into the sandbox in two ways: **static files** bundled -with the kit, and **`initFiles`** written at startup with runtime values -substituted in. - -Static files work well for content that doesn't vary between sandboxes, such -as tool configurations, shared linter rules, helper scripts the agent can -invoke, or reference material like a style guide or API cheatsheet. - -```text -my-kit/ -├── spec.yaml -└── files/ - ├── home/ - │ └── .config/my-tool/settings.json - └── workspace/ - └── .editorconfig -``` - -`initFiles` cover content that depends on runtime values, such as an -absolute workspace path that a tool needs to bake into its config file -at startup: - -```yaml -commands: - initFiles: - - path: /home/agent/.my-tool/config.json - content: '{"workspace": "${WORKDIR}"}' - onlyIfMissing: true -``` - -See [`initFiles`](#initfiles) in the spec reference for all fields. - -Sandboxes seed settings files for some built-in agents during setup. -For example, the sandbox writes `/home/agent/.claude/settings.json` -for the `claude` agent. This happens after the kit's static files and -`initFiles`, so kit-injected files at those paths get overwritten. -Workspace files (such as `<workspace>/.claude/settings.local.json`) -aren't affected, and you can ship them under `files/workspace/` as -usual. To override a path the sandbox writes to, use a -[`commands.startup`](#startup) script instead. See -[Override agent settings](kit-examples.md#override-agent-settings) for -an example. - -### Set environment variables - -Environment variables set by the kit are available to the agent at -runtime: - -```yaml -environment: - variables: - MY_TOOL_WORKSPACE: /home/agent/my-tool -``` - -For credentials, see -[Authenticate to external services](#authenticate-to-external-services). -Don't put secret values directly in `environment.variables` — they'd -be visible inside the sandbox VM. - -### Control network access - -Network rules define which domains the sandbox can reach or block. Kit -network rules apply only to sandboxes that use the kit: - -```yaml -network: - allowedDomains: - - api.example.com - - "*.cdn.example.com" - deniedDomains: - - telemetry.example.com -``` - -Use `allowedDomains` for hosts the agent needs, such as package -registries, install endpoints, or external APIs. Use `deniedDomains` for -hosts the agent should not reach, such as telemetry endpoints. If a domain -matches both an allow rule and a deny rule, the deny rule wins. - -> [!IMPORTANT] -> Kit network rules don't apply when organization governance is active. In -> that case, only organization rules are evaluated, so kit-defined allow and -> deny rules are ignored — including any domains a kit allows for the agent -> to reach. For details, see -> [Policy precedence](../governance/concepts.md#precedence). - -For authenticated services, see -[Authenticate to external services](#authenticate-to-external-services). - -### Authenticate to external services - -A kit can attach credentials to outbound requests through the -host-side proxy. The agent inside the VM works with a sentinel value; -the proxy reads the real credential on the host and overwrites the -auth header before the request leaves the sandbox. - -The standard pattern uses four blocks tied to a service identifier -you choose (here, `my-service`): - -```yaml -network: - allowedDomains: - - api.example.com - serviceDomains: - api.example.com: my-service # Tag traffic to this domain - serviceAuth: - my-service: - headerName: Authorization # Overwrite this header - valueFormat: "Bearer %s" - -credentials: - sources: - my-service: - env: - - MY_SERVICE_API_KEY # Host-side credential lookup - -environment: - proxyManaged: - - MY_SERVICE_API_KEY # Set the in-VM env var to "proxy-managed" -``` - -The agent boots with `MY_SERVICE_API_KEY=proxy-managed`, sends a -request with that value in `Authorization`, and the proxy overwrites -the header with the real credential before forwarding. The real -secret never enters the VM. - -See [Credentials](../security/credentials.md) for how to provide the -credential value on your host, other approaches for cases the example -above doesn't fit, and what the proxy does at request time. - -### Inject agent memory - -A kit can append content to the agent's memory file, such as `CLAUDE.md` -or `AGENTS.md`. The agent reads this file at startup. Use it to give -the agent project conventions, usage tips for a tool the kit installs, -or other guidance that should be in scope when the sandbox runs. - -```yaml -memory: | - Ruff is installed. Run `ruff check` before committing. - Shared config lives at `/workspace/ruff.toml`. -``` - -Both mixin and agent kits can declare `memory:`. The content is written -only when the active agent kit sets [`agent.aiFilename`](#agent-block), -which determines the memory file's name. - -When more than one loaded kit declares a `memory:` block, each kit's -content is written to its own `<kit-name>.md` file under a sibling -`kits-memory/` directory. The main memory file gets a `## Kits` section -that points to each kit file: - -```text -/Users/you/ -├── myproject/ # workspace -├── AGENTS.md # main memory file with a "## Kits" index -└── kits-memory/ - ├── ruff-lint.md - ├── vale.md - └── git-ssh-sign.md -``` - -See [`memory`](#memory) in the spec reference for the full field schema. - -### Define an agent - -Agent kits declare an `agent:` block with the image the agent runs in and -the command the user attaches to when they launch the sandbox: - -```yaml -agent: - image: "my-registry/my-agent:latest" - entrypoint: - run: [my-agent, "--yolo"] -``` - -See [Agent kits](#agent-kits) for use cases and an example. - -## Mixin kits - -A mixin kit extends an existing agent with extra capabilities. Common use -cases: - -- Pre-install tools: linters, libraries, or other custom programs -- Grant the agent access to a new authenticated service (a database, a - vendor API) -- Inject shared team config (linter rules, editor settings, dotfiles) - -### Example: Python linting kit - -This kit installs [Ruff](https://docs.astral.sh/ruff/) and injects a shared -configuration file, so every sandbox starts with the same linting setup. - -```text -ruff-lint/ -├── spec.yaml -└── files/ - └── workspace/ - └── ruff.toml -``` - -```yaml {title="ruff-lint/spec.yaml"} -schemaVersion: "1" -kind: mixin -name: ruff-lint -displayName: Ruff Linter -description: Python linting with shared team config - -network: - allowedDomains: - - pypi.org - - files.pythonhosted.org - -commands: - install: - - command: "uv tool install ruff@latest" - user: "1000" - description: Install Ruff -``` - -```toml {title="ruff-lint/files/workspace/ruff.toml"} -line-length = 100 - -[lint] -select = ["E", "F", "I"] -``` - -> [!TIP] -> The templates for the built-in agents (`claude`, `codex`, etc) already -> includes `uv`, so this mixin can use it without installing it separately. - -To start a new sandbox with this mixin: - -```console -$ sbx run claude --kit /path/to/ruff-lint/ -``` - -To apply the mixin to a sandbox that's already running, use -[`sbx kit add`](#local) instead. The `--kit` flag only takes effect when a -sandbox is created. - -## Agent kits - -An agent kit defines a full agent from scratch — image, entrypoint, and -everything the agent needs. Common use cases: - -- Package a custom agent you've built so others can run it -- Ship a team-internal agent with defaults baked in -- Run a fork of an existing agent with your own config -- Prototype a new agent integration - -Agent kits declare everything a mixin kit can, plus an -[`agent:` block](#agent-block) that tells the sandbox how to launch the -agent. For a step-by-step walkthrough, see -[Build your own agent kit](build-an-agent.md). - -### Example: the built-in `claude` agent - -The `claude` agent you get from `sbx run claude` is defined as a kit. Here -is an abbreviated version of its spec, showing how the agent block combines -with network, credentials, environment, and commands: - -```yaml {title="claude/spec.yaml"} -schemaVersion: "1" -kind: agent -name: claude -agent: - image: "docker/sandbox-templates:claude-code-docker" - aiFilename: CLAUDE.md - persistence: persistent - entrypoint: - run: [claude, "--dangerously-skip-permissions"] - -network: - serviceDomains: - api.anthropic.com: anthropic - console.anthropic.com: anthropic - serviceAuth: - anthropic: - headerName: x-api-key - valueFormat: "%s" - allowedDomains: - - "claude.com:443" - -credentials: - sources: - anthropic: - env: - - ANTHROPIC_API_KEY - -environment: - variables: - IS_SANDBOX: "1" - -commands: - install: - - command: "curl -fsSL https://claude.ai/install.sh | bash" - user: "1000" - description: Install Claude Code -``` - -## Using kits - -Kits can be loaded from a local path (a directory or ZIP file), a Git -repository, or an OCI registry. Pass `--kit` more than once to stack -several kits on the same sandbox. - -> [!IMPORTANT] -> `--kit` only takes effect when a sandbox is created. Passing it -> against an existing sandbox name fails with -> `--kit can only be used when creating a new sandbox`. To extend a -> running sandbox with a kit, use [`sbx kit add`](#local) instead. - -### Local - -Point `--kit` at a directory or ZIP file on disk: - -```console -$ sbx run claude --kit ./my-kit/ -$ sbx run claude --kit ./my-kit-1.0.zip -``` - -While iterating on a kit, apply changes to a running sandbox with -`sbx kit add` instead of recreating it: - -```console -$ sbx kit add my-sandbox ./my-kit/ -``` - -`kit add` re-runs install commands and re-copies files. Kits can't be -removed from a running sandbox — remove and recreate it to start clean. - -### Git repository - -```console -$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#ref=v0.1.0&dir=code-server" -``` - -- `#ref=<branch|tag|commit>` pins to a specific revision. Defaults to the - repository's default branch. -- `#dir=<path>` loads a kit from a subdirectory. -- `git+ssh://` URLs also work, using your local SSH agent, Git credential - helpers, and `.netrc`. -- Quote the URL in shells where `&` starts a background job. - -### OCI registry - -```console -$ sbx run claude --kit ghcr.io/myorg/my-kit:1.0 -``` - -For Docker Hub, include the full `docker.io` prefix. See -[Packaging and distribution](#packaging-and-distribution) for publishing. - -> [!IMPORTANT] -> For Docker Hub, `sbx` reuses your `sbx login` session to pull private -> kits. For other registries, store pull credentials with -> [`sbx secret set --registry`](../security/credentials.md#registry-credentials) -> before running the sandbox: -> -> ```console -> $ gh auth token | sbx secret set --registry ghcr.io --password-stdin -> ``` -> -> Without stored credentials, pulls from non-Docker Hub registries are -> anonymous and private kits fail to pull. - -## Packaging and distribution - -The `sbx kit` subcommands validate, inspect, and publish kits: - -- `sbx kit validate <path>` — check that a kit directory or ZIP is - well-formed. -- `sbx kit inspect <path>` — display kit details. Add `--json` for - machine-readable output. -- `sbx kit pack <path> -o <file.zip>` — package a directory as a ZIP file - for sharing. -- `sbx kit push <path> <ref>` — publish to an OCI registry (for example, - `ghcr.io/myorg/my-kit:1.0`). -- `sbx kit pull <ref>` — download a kit from a registry as a ZIP file to - the working directory. - -For Docker Hub, include the full `docker.io` prefix — `sbx` doesn't add it -automatically. - -`sbx kit pull` prefers credentials stored with -[`sbx secret set --registry`](../security/credentials.md#registry-credentials), -falling back to the Docker credential store. `sbx kit push` only uses the -Docker credential store, so pushing to a private registry requires a prior -`docker login`. - -## Spec reference - -A kit directory has a required `spec.yaml` and an optional `files/` tree: - -```text -my-kit/ -├── spec.yaml # required -└── files/ # optional — static files to inject - ├── home/ - └── workspace/ -``` - -### Top-level fields - -```yaml -schemaVersion: "1" -kind: <mixin | agent> -name: <name> -displayName: <name> -description: <text> -``` - -| Field | Required | Description | -| --------------- | -------- | ------------------------------------------------------------------------ | -| `schemaVersion` | Yes | Spec schema version. Set to `"1"`. | -| `kind` | Yes | `mixin` for kits that extend an agent; `agent` for kits that define one. | -| `name` | Yes | Unique identifier. Lowercase, alphanumeric, hyphens. | -| `displayName` | No | Human-readable name. | -| `description` | No | Short description. | - -The sections below apply to both kinds. Agent kits also declare an -[`agent:` block](#agent-block). - -### Credentials - -```yaml -credentials: - sources: - <service-id>: - env: [<env-var>, ...] - file: - path: <path> - parser: <parser> - priority: <env-first | file-first> -``` - -| Field | Description | -| -------------------------- | ------------------------------------------------------------- | -| `sources` | Map of service identifier to credential source. | -| `sources.<id>.env` | Environment variables to read on the host, in priority order. | -| `sources.<id>.file.path` | Path on host. `~` expands to home directory. | -| `sources.<id>.file.parser` | How to extract the credential value from the file. | -| `sources.<id>.priority` | `env-first` (default) or `file-first`. | - -Service identifiers link credentials to [network rules](#network). - -#### file.parser - -`file.parser` tells the proxy how to extract a credential from the file at `file.path`. -Omit it for plain-text files; set it to `json:<dot.path>` to extract a field from a JSON file. - -| Value | Behavior | -| ----------------- | ------------------------------------------------------------------------------------ | -| omitted or empty | Reads the entire file as the credential. Leading and trailing whitespace is trimmed. | -| `json:<dot.path>` | Parses the file as JSON and returns the value at the dot-separated path. | -| any other value | Rejected — `unsupported parser: <value>`. | - -For `json:` paths, segments are separated by `.` (for example, `json:credentials.github.token`). -Only object keys can be navigated — arrays are not supported and there is no `[0]`-style indexing. -Keys that contain a literal `.` cannot be referenced. The resolved value must be a string, number, -or boolean; numbers and booleans are converted to strings. Objects, arrays, and null are rejected. - -When a source has both `env` and `file` defined, `priority` controls which is tried first. The -preferred source is used when it exists — the environment variable is set, or the file is -present on disk. If it doesn't, the other source is used instead. The choice is made once at -discovery time, so parser errors (missing JSON field, wrong value type, invalid JSON) surface -as errors rather than triggering a fallback. - -Plain-text token file: - -```yaml -credentials: - sources: - openai: - file: - path: "~/.openai/token" -``` - -Nested JSON field, with an environment variable as fallback: - -```yaml -credentials: - sources: - github: - env: - - GH_TOKEN - file: - path: "~/.config/myapp/creds.json" - parser: "json:credentials.github.token" - priority: file-first -``` - -Given `~/.config/myapp/creds.json`: - -```json -{ - "credentials": { - "github": { "token": "ghp_xyz", "expires": "2026-12-31" } - } -} -``` - -The proxy resolves the credential to `ghp_xyz`, falling back to `GH_TOKEN` if the file is -missing. If the file exists but the JSON path doesn't resolve, the request fails with the -parser error below instead of falling back. - -Common errors when using `json:` parsers: - -| Error message | Cause | -| --------------------------------------------- | ------------------------------------------------------------------- | -| `field 'X' not found in JSON` | The path doesn't exist in the file. | -| `cannot navigate to field 'X': not an object` | A path segment hit a string, array, or scalar instead of an object. | -| `field 'X' is not a string value` | The resolved value is an object, array, or null. | -| `failed to parse JSON: ...` | The file is not valid JSON. | - -### Network - -```yaml -network: - allowedDomains: [<domain>, ...] - deniedDomains: [<domain>, ...] - serviceDomains: - <domain>: <service-id> - serviceAuth: - <service-id>: - headerName: <header> - valueFormat: <format> -``` - -| Field | Description | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `allowedDomains` | Domains the sandbox can reach. Wildcards supported. | -| `deniedDomains` | Domains the sandbox is blocked from reaching. Deny rules take precedence over allow rules, including those from other composed kits. | -| `serviceDomains` | Map of domain to service identifier from `credentials.sources`. | -| `serviceAuth.headerName` | HTTP header the proxy sets (for example, `Authorization`). | -| `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). | - -### Environment - -```yaml -environment: - variables: - <NAME>: <value> - proxyManaged: [<NAME>, ...] -``` - -| Field | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------- | -| `variables` | Key-value pairs set directly in the container. | -| `proxyManaged` | Environment variable names populated by the proxy at request time. Pair with [`credentials.sources`](#credentials). | - -Variable names must be valid shell identifiers (`[A-Za-z_][A-Za-z0-9_]*`). - -### Commands - -```yaml -commands: - install: - - command: <shell-string> - user: <uid> - description: <text> - startup: - - command: [<argv>, ...] - user: <uid> - background: <true | false> - description: <text> - initFiles: - - path: <path> - content: <text> - mode: <octal> - onlyIfMissing: <true | false> - description: <text> -``` - -#### `install` - -Runs once during sandbox creation. Shell strings passed to `sh -c`. - -| Field | Default | Description | -| ------------- | ------- | ----------------------------- | -| `command` | — | Shell command string. | -| `user` | `"0"` | User to run as. `"0"` = root. | -| `description` | — | Human-readable description. | - -#### `startup` - -Runs at every sandbox start. String array, not interpreted by a shell. - -| Field | Default | Description | -| ------------- | -------- | ----------------------------------- | -| `command` | — | Command and args as a string array. | -| `user` | `"1000"` | User to run as. `"1000"` = agent. | -| `background` | `false` | Run in background. | -| `description` | — | Human-readable description. | - -Startup commands are non-interactive. They run before the agent -attaches, with no terminal connected, so they can't prompt the user -(for example, an interactive `aws login` will hang or fail). They also -don't gate the agent's entrypoint: the agent launches once startup -commands have been dispatched, regardless of `background`. Use them -for non-interactive prep — launching daemons, warming caches, -refreshing config — and use `commands.initFiles` for any value that -needs to land on disk before the agent runs. - -Startup commands must be idempotent. They run on every sandbox start -and replay on container restarts, so a command that fails or -misbehaves on a second invocation breaks the restart path. Guard -work with existence checks, use upserts instead of inserts, and -prefer commands that converge to the same end state regardless of -how many times they run. - -#### `initFiles` - -Files written at sandbox start, with runtime substitution. - -| Field | Default | Description | -| --------------- | -------- | --------------------------------------------------------- | -| `path` | — | Absolute container path. | -| `content` | — | File content. `${WORKDIR}` expands to the workspace path. | -| `mode` | `"0644"` | File permissions in octal. | -| `onlyIfMissing` | `false` | Skip if the file already exists. | - -### Static files - -```text -my-kit/files/ -├── home/ → /home/agent/ -└── workspace/ → primary workspace path -``` - -| Kit path | Container destination | -| ------------------ | --------------------------------------- | -| `files/home/` | `/home/agent/` (config files, dotfiles) | -| `files/workspace/` | The primary workspace path | - -Parent directories are created automatically. Existing files are -overwritten. Absolute paths and path-traversal sequences (`../../`) are -rejected. - -### Memory - -```yaml -memory: | - <markdown> -``` - -Top-level field. Available in both mixin and agent kits. Markdown -appended to the agent's memory file at sandbox creation. The agent reads -this content at startup. Write it as instructions or notes the agent -should follow when working in the sandbox. Applied only when the active -agent kit sets [`agent.aiFilename`](#agent-block). - -The file is written to the parent of the workspace path inside the -sandbox, not to the workspace itself. For a workspace mounted at -`/Users/you/myproject`, the memory file lands at -`/Users/you/AGENTS.md` (or whatever `aiFilename` is set to). It exists -only inside the sandbox. Nothing is written to the host. - -When several loaded kits declare `memory:` blocks, the content is split -across files instead of being concatenated into the main one: - -- Each kit's memory is written to `<kit-name>.md` in a sibling - `kits-memory/` directory next to the main memory file. -- The main memory file gets a `## Kits` section listing every kit with - a pointer to its file. The section is delimited by - `<!-- sbx:kits-section start -->` and `<!-- sbx:kits-section end -->` - markers so it can be regenerated when kits are added or removed. - -### Agent block - -Required for `kind: agent`. - -```yaml -agent: - image: <image-ref> - aiFilename: <filename> - persistence: <persistent | ephemeral> - entrypoint: - run: [<argv>, ...] - args: [<arg>, ...] -``` - -| Field | Required | Description | -| ----------------------- | -------- | ---------------------------------------------------------------------------------------------- | -| `agent.image` | Yes | Docker image reference. See [Base image requirements](#base-image-requirements). | -| `agent.aiFilename` | No | Memory filename (for example, `AGENTS.md`). Appends top-level [`memory`](#memory) at creation. | -| `agent.persistence` | No | `persistent` (named volume across restarts) or `ephemeral` (default). | -| `agent.entrypoint.run` | No | Command and args as a string array. Replaces the image's entrypoint. | -| `agent.entrypoint.args` | No | Args appended to the image's existing entrypoint. | - -#### Base image requirements - -The agent's container image must provide: - -- A non-root `agent` user at UID 1000 with passwordless sudo. -- A `/home/agent/` home directory owned by `agent`. -- HTTP proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, - `NO_PROXY`) preserved across sudo. -- The agent binary (baked in, or installed via - [`commands.install`](#commands)). - -Build on top of `docker/sandbox-templates:shell-docker` to get these for -free. - -## Debugging - -When a kit doesn't behave as expected, start with the network policy log -and direct inspection inside the sandbox: - -- `sbx policy log` shows every outbound request the sandbox proxy saw, - the rule it matched, extra context when available, and its `PROXY` - value, such as `forward`, `forward-bypass`, `transparent`, or - `browser-open`. Use it to diagnose install-time download failures, - blocked domains, and unexpected TLS interception. If downloads fail or - arrive corrupted after you add `serviceDomains`, check whether the - service mapping is too broad. Map only the hosts that need credential - injection. -- `sbx exec <sandbox> -- <cmd>` runs an arbitrary command inside an - existing sandbox. Useful for inspecting post-install state without - recreating: `which mytool`, `ls /home/agent/.local/bin/`, - `cat /home/agent/.config/...`, and so on. - -Install and startup command output is only emitted during `sbx run` or -`sbx create`; `sbx` doesn't retain it for later inspection. To repeat -setup with fresh output, remove and recreate the sandbox: -`sbx rm <sandbox> && sbx run ...`. diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md deleted file mode 100644 index b525f0caf86b..000000000000 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: Templates -weight: 10 -description: Build reusable sandbox images with tools and configuration baked in, or save a running sandbox as a template. -keywords: sandboxes, sbx, templates, images, dockerfile, snapshot, custom environments ---- - -{{< summary-bar feature_name="Docker Sandboxes sbx" >}} - -Every sandbox is customizable — agents install packages, pull images, and -configure tools as they work, and those changes persist for the sandbox's -lifetime. Templates capture a configured environment into a reusable image -so you don't have to set it up again every time. - -## Custom templates - -Custom templates are reusable sandbox images that extend one of the built-in -agent environments with additional tools and configuration baked in. Instead -of asking the agent to install packages every time, build a template once and -reuse it across sandboxes and team members. - -Templates make sense when multiple people need the same environment, when -setup involves steps that are tedious to repeat, or when you need pinned -versions of specific tools. For one-off work, the default image is fine — -ask the agent to install what's needed. - -> [!NOTE] -> Custom templates customize an existing agent's environment — they don't -> create new agent runtimes. The agent that launches inside the sandbox is -> determined by the base image variant you extend and the agent you specify -> in the `sbx run` command, not by binaries installed in the template. To -> define a new agent from scratch, see [Kits](kits.md#defining-an-agent). - -### Base images - -All sandbox templates are published as -`docker/sandbox-templates:<variant>`. They are based on Ubuntu and run as a -non-root `agent` user with sudo access. Most variants include Git, Docker -CLI, and common development tools like Node.js, Python, Go, and Java. - -| Variant | Agent | -| --------------------- | -------------------------------------------------------------------- | -| `claude-code` | [Claude Code](https://claude.ai/download) | -| `claude-code-minimal` | Claude Code with a minimal toolset (no Node.js, Python, Go, or Java) | -| `codex` | [OpenAI Codex](https://github.com/openai/codex) | -| `copilot` | [GitHub Copilot](https://github.com/github/copilot-cli) | -| `cursor-agent` | [Cursor](https://cursor.com/cli) | -| `docker-agent` | [Docker Agent](https://github.com/docker/docker-agent) | -| `droid` | [Droid](https://www.factory.ai) | -| `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | -| `kiro` | [Kiro](https://kiro.dev) | -| `opencode` | [OpenCode](https://opencode.ai) | -| `shell` | No agent pre-installed. Use for manual agent setup. | - -Each variant also has a `-docker` version (for example, `claude-code-docker`) -that includes a full Docker Engine running inside the sandbox — no local Docker -daemon required. When you pick a built-in agent without specifying a custom -template, `sbx run` and `sbx create` use the `-docker` template variants by -default. - -The agent containers created from the `-docker` templates run in privileged -mode inside the microVM (not on your host), with a dedicated block volume at -`/var/lib/docker`, and `dockerd` starts automatically inside the sandbox. The -block volume defaults to 50 GB and uses a sparse file, so it only consumes -disk space as Docker writes to it. - -To override the volume size, set the `DOCKER_SANDBOXES_DOCKER_SIZE` -environment variable to a size string before starting the sandbox: - -```console -$ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude -``` - -Use the non-Docker variant if you don't need to build or run containers -inside the sandbox and want a lighter, non-privileged environment. Specify -it explicitly with `--template`: - -```console -$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code -``` - -### Build a custom template - -Building a custom template requires -[Docker Desktop](https://docs.docker.com/desktop/). - -Write a Dockerfile that extends one of the base images. Pick the variant -that matches the agent you plan to run. For example, extend `claude-code` -to customize a Claude Code environment, or `codex` to customize an OpenAI -Codex environment. - -The following example creates a Claude Code template with Rust and -protocol buffer tools pre-installed: - -```dockerfile -FROM docker/sandbox-templates:claude-code -USER root -RUN apt-get update && apt-get install -y protobuf-compiler -USER agent -RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y -``` - -Use `root` for system-level package installations (`apt-get`), and switch -back to `agent` before installing user-level tools. Tools that install into -the home directory, such as `rustup`, `nvm`, or `pyenv`, must run as -`agent` — otherwise they install under `/root/` and aren't available in -the sandbox. - -Build the image and push it to an OCI registry, such as Docker Hub: - -```console -$ docker build -t my-org/my-template:v1 --push . -``` - -> [!NOTE] -> The Docker daemon used by Docker Sandboxes pulls templates from a -> registry directly; it doesn't share the image store of your local Docker -> daemon on the host. - -> [!IMPORTANT] -> For Docker Hub, `sbx` reuses your `sbx login` session to pull private -> images. For other registries (GitHub Container Registry, ECR, ACR, a -> self-hosted Nexus, and so on), store pull credentials with -> [`sbx secret set --registry`](../security/credentials.md#registry-credentials) -> before running the sandbox: -> -> ```console -> $ gh auth token | sbx secret set --registry ghcr.io --password-stdin -> ``` -> -> Without stored credentials, pulls from non-Docker Hub registries are -> anonymous and private images fail to pull. - -For locally-built images, save the image to a tar and load it directly -into the sandbox runtime instead of pulling from a registry: - -```console -$ docker image save my-org/my-template:v1 -o my-template.tar -$ sbx template load my-template.tar -$ sbx run --template my-org/my-template:v1 claude -``` - -`sbx template load` imports the tar into the sandbox runtime's image -store, so the image doesn't need to be reachable from a registry at -sandbox creation time. - -Unless you use the permissive `allow-all` network policy, you may also need -to allow-list any domains that your custom tools depend on: - -```console -$ sbx policy allow network "*.example.com:443,example.com:443" -``` - -Then run a sandbox with your template. The agent you specify must match -the base image variant your template extends: - -```console -$ sbx run --template docker.io/my-org/my-template:v1 claude -``` - -Because this template extends the `claude-code` base image, you run it -with `claude`. If you extend `codex`, use `codex`; if you extend `shell`, -use `shell` (which drops you into a Bash shell with no agent). - -> [!NOTE] -> Unlike Docker commands, `sbx` does not automatically resolve the Docker -> Hub domain (`docker.io`) in image references. - -### Template caching - -Template images are cached locally. The first use pulls from the registry; -subsequent sandboxes reuse the cache. Cached images persist across sandbox -creation and deletion, and are cleared when you run `sbx reset`. - -## Saving a sandbox as a template - -Instead of writing a Dockerfile, you can save a running sandbox's state as -a template. This captures installed packages, configuration changes, and -files into a reusable image — useful when you've set up an environment -interactively and want to preserve it. - -> [!WARNING] -> Saving a sandbox captures its entire filesystem, including any secrets -> stored on it. If you manually added API keys, tokens, or other -> credentials to the sandbox, they're embedded in the saved template and -> shared with anyone you distribute it to. To keep credentials out of -> templates, manage them with `sbx secret set` instead — the proxy injects -> them at runtime so they're never written to the filesystem. For more -> information, see [Manage credentials](../security/credentials.md). - -### Save and reuse - -Stop the sandbox (or let the CLI prompt you), then save it with a name and -tag: - -```console -$ sbx template save my-sandbox my-template:v1 -``` - -The image is stored in the sandbox runtime's local image store. Create a -new sandbox from it with the `-t` flag: - -```console -$ sbx run -t my-template:v1 claude -``` - -### List and remove templates - -List all saved templates: - -```console -$ sbx template ls -``` - -Remove a template you no longer need: - -```console -$ sbx template rm my-template:v1 -``` - -### Export and import - -To share a saved template or move it to another machine, export it as a -tar file: - -```console -$ sbx template save my-sandbox my-template:v1 --output my-template.tar -``` - -On the other machine, load the tar file and use it: - -```console -$ sbx template load my-template.tar -$ sbx run -t my-template:v1 claude -``` - -### Limitations - -Agent configuration files are always recreated when a sandbox is created. -Changes to user-level agent configuration files, such as -`/home/agent/.claude/settings.json` and `/home/agent/.claude.json`, do not -persist in saved templates. - -If the saved template was built for a different agent than the one you -specify in `sbx run`, you get a warning. For example, saving a Claude -sandbox and running it with `codex` produces: - -```text -⚠ WARNING: template "my-template:v1" was built for the "claude" agent but you are using "codex". - The sandbox may not work correctly. Consider using: sbx run -t my-template:v1 claude -``` diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md new file mode 100644 index 000000000000..306107d30220 --- /dev/null +++ b/content/manuals/ai/sandboxes/customize/use-kits.md @@ -0,0 +1,341 @@ +--- +title: Use kits +description: Run published v3 kit sets and workloads, add compatible mixins, and configure kit arguments and runtime access. +keywords: sandboxes, sbx, kits, v3, workloads, mixins +weight: 10 +--- + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +If you've run `sbx run claude` or `sbx run codex`, you've already used a kit. +The built-in agents are kits that package an environment, tools, and runtime +settings. You run kits you build yourself or get from another publisher in the +same way: give `sbx` a reference, and Docker Sandboxes prepares the environment +and applies the kit's settings. + +Docker recommends v3 kits. V2 remains supported and is the default format +for built-in agent references such as `claude` and `codex`. + +## Run a kit + +The built-in agent names are shortcuts for kit references. To run another kit, +replace the agent name with that kit's reference. For example, run Docker's +published v3 Codex workload: + +```console +$ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit +``` + +### Published v3 workloads + +Use these published v3 workloads in place of built-in shortcuts when adding +v3 mixins with `sbx run` or `sbx create`. + +A workload's agent name comes from the last component of its repository name. +It must differ from built-in agent names: `docker/sbx-kit-claude` registers +`sbx-kit-claude`, while `sbx/claude` conflicts with built-in `claude` and +fails to register. Changing the sandbox's `--name` doesn't change the agent name. + +| Built-in agent | V3 workload OCI reference | +| --- | --- | +| `claude` | `docker.io/docker/sbx-kit-claude:2.1.267` | +| `codex` | `docker.io/docker/sbx-kit-codex:0.155.1` | +| `copilot` | `docker.io/docker/sbx-kit-copilot:1.0.86` | +| `cursor` | `docker.io/docker/sbx-kit-cursor:2026.09.18-9a7762b` | +| `devin` | `docker.io/docker/sbx-kit-devin:3000.10.31` | +| `docker-agent` | `docker.io/docker/sbx-kit-docker-agent:1.141.0` | +| `droid` | `docker.io/docker/sbx-kit-droid:0.223.0` | +| `kiro` | `docker.io/docker/sbx-kit-kiro:1.0.0` | +| `opencode` | `docker.io/docker/sbx-kit-opencode:1.18.31` | +| `shell` | `docker.io/docker/sbx-kit-shell:1.0.0` | + +For a [sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md), +list the workload reference under `kits` and set `agent` to its repository +name, such as `sbx-kit-claude`. + +Published `sbx/*` mixins, such as `sbx/playwright` and `sbx/codex-mixin`, can +be combined with these workloads. Their sources are on the +[v3 branch of docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/v3). +For more source examples, see +[sandbox-kit-spec](https://github.com/docker/sandbox-kit-spec/tree/main/examples). + +Use a version tag to select a kit release, or a digest to identify exact +content. A `latest` tag can move to a kit that needs a later `sbx` release. +V3 format support starts at v0.45, but a kit's capabilities can require a +later version or a local sandbox. Check +[Kit capability support](/manuals/ai/sandboxes/customize/author/capabilities.md) +and the publisher's requirements before choosing a kit. + +### Choose a kit source + +The previous example uses a published image from Docker Hub. You can also +run a kit from a local directory or a Git repository. The same source types +work for mixins added with `--kit`: + +| Source | Example reference | +| --- | --- | +| Published image | `docker.io/my-org/agent-kit:1.0.0` | +| Local directory | `./my-agent` | +| Git repository | `git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent` | + +For Git sources, `ref` selects a revision and `dir` selects the kit's +subdirectory. Quote Git URLs in shell commands because they can contain `&`: + +```console +$ sbx run "git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent" +``` + +`sbx` pulls published images and builds local or Git sources when creating +the sandbox. Builds with unchanged source content and supplied kit arguments +reuse cached results. + +By default, remote kit sources are limited to Docker Hub. To use a Git +source or another registry, see [Restrict kit sources](#restrict-kit-sources). +For private images, see +[Registry credentials](/manuals/ai/sandboxes/configuration/credentials.md#registry-credentials). + +## Reuse a sandbox + +A sandbox keeps the kit configuration it was created with. To return to the +sandbox from the previous example, specify its name: + +```console +$ sbx run --name codex-v3-kit +``` + +You don't need to specify the kit reference again. To try a different workload, +mixin combination, or argument value, create a sandbox with a different name +or recreate the existing one. To add a mixin to an existing sandbox, see +[Add mixins](#add-mixins). + +## Runtime access and instructions + +A kit can request access to the services it needs. For example, the Codex +workload needs to reach OpenAI and authenticate. If you use an API key, +store it on your host and approve the kit's request to use it. These are +separate steps: storing a secret doesn't give a third-party kit permission to +use it. See +[Credential bindings](/manuals/ai/sandboxes/configuration/credentials.md#credential-bindings) +for preparing unattended runs. + +Check the kit's documentation for the services it contacts, the credentials +it needs, and the commands it runs at startup. For proxy-managed credentials, +the kit's credential binding tells the proxy which credential to add to +requests to the service. Once you approve the binding, the proxy adds the +credential to outgoing requests. The credential value stays on your host +and isn't exposed inside the sandbox. + +Network requests must also meet your sandbox's network policy. Kit allow rules +can't grant access beyond your organization's policy. If a connection fails, +check the [policy log](#debug-kits) to see which rule blocked it. + +Kits can also give the agent instructions for using their tools. These +instructions are stored in context files inside the sandbox. Files packaged +with a kit live under `/usr/share/sandbox/kit/`, for example +`/usr/share/sandbox/kit/git-signing/git-signing-context.md`. Docker Sandboxes +adds a list of kits and their context file paths to the agent's instructions, +such as `AGENTS.md` or `CLAUDE.md`, so the agent can read each file when needed. +This keeps kit guidance separate from your project's instructions. + +## Add mixins + +Mixins add tools and configuration to a workload. Use `--kit` to add a mixin +when creating a sandbox. + +For example, an internal CLI mixin can package your company's executable +along with network rules and a credential request for its API: + +```console +$ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-tools \ + --kit docker.io/<NAMESPACE>/company-cli:1.0.0 +``` + +Replace the mixin reference with one your organization has published. +To build your own, see +[Build a tool mixin](/manuals/ai/sandboxes/customize/author/tool-mixins.md). +Store the credential requested by the mixin on the host and approve access +when prompted. + +Codex starts with `company-cli` available to use. Docker Sandboxes +applies the files and settings from both the workload and the mixin. + +### Combine multiple mixins + +Repeat `--kit` to add more mixins. You can also add compatible mixins to a +published workload set, or pass a set containing only mixins with `--kit`. + +Avoid adding a kit that's already in the set. If two kits provide the same +feature, Docker Sandboxes can reject the combination. + +To publish your combination as one reference, see +[Compose a kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md). +To keep the kits separate in a shared sandbox configuration, list them in a +[sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md). +Give each published kit its own image repository name. Different tags of the +same repository have the same kit name, and Docker Sandboxes rejects duplicate +names in a composition. + +### Change a sandbox's mixins + +For v3 kits, you choose the mixins when you create the sandbox. To use a +different combination, create another sandbox with a different name. +Specify the workload and all the mixins you want to include. + +The `sbx kit add` command can't add mixins to an existing v3 sandbox. + +The new sandbox doesn't inherit changes or kit volume data from the previous sandbox. + +## Compose kits + +Some mixins need a tool another kit supplies. For example, a mixin whose +scripts call `gojq` can declare that dependency: + +```yaml +requires: [gojq] +``` + +The [gojq mixin example](/manuals/ai/sandboxes/customize/author/patterns.md#leave-build-tools-out-of-the-mixin) +declares the feature it provides: + +```yaml +provides: ["gojq@0.12.17"] +``` + +Include both mixins when you create the sandbox. Docker Sandboxes applies +the gojq mixin before the mixin whose scripts need it, regardless of the order +of your `--kit` flags. If you leave out gojq, sandbox creation fails. + +A `requires` entry tells Docker Sandboxes what a kit needs. You still choose +and include the kit that provides it. Docker Sandboxes doesn't download a +kit for you based on this entry. A kit can also require a minimum feature +version or rule out incompatible kits. + +With `--kit`, Docker Sandboxes checks and combines the kits when it creates +the sandbox. For a set, this happens when the publisher builds it. The +published kit includes a record of the exact components used, identified by +their image digests. + +To declare these relationships in your own kits, see +[Composition fields](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md#5-provides-requires-integrates-conflicts). + +## Pass arguments to kits + +Kits can expose arguments for settings such as a linter's mode. Check the +kit's documentation for argument names, defaults, and accepted values. +Use `--kit-arg name=value` to set an argument: + +```console +$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \ + --name codex-tools-fix --kit-arg lint_mode=fix +``` + +This example uses a workload set that exposes a `lint_mode` argument. +Replace the image reference with your set's published reference. To expose +arguments in your own set, see +[Configure component arguments](/manuals/ai/sandboxes/customize/author/kit-sets.md#configure-component-arguments). + +Argument values are plain text and can be recorded in shell history and +sandbox state. Use +[stored credentials](/manuals/ai/sandboxes/configuration/credentials.md) +for secrets. + +### Target a specific kit + +An argument without a kit prefix applies to every selected kit that declares +it. To target one kit, use `--kit-arg <HANDLE>.<ARGUMENT>=<VALUE>`: + +```console +$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \ + --name codex-tools-fix --kit-arg codex-tools.lint_mode=fix +``` + +The handle identifies the kit and comes from its reference: + +| Kit source | Handle | +| --- | --- | +| Published image | Final part of the repository name, such as `codex-tools` | +| Local directory | Directory name | +| Git repository | Selected subdirectory name, or repository name if no subdirectory is selected | + +A value targeted at one kit overrides a value supplied to all kits. + +### Load arguments from a file + +Use `--kit-args-file <FILE>` to load arguments from a reusable file. +Write one `name=value` entry per line. You can prefix names with a kit +handle, as with `--kit-arg`. + +Values passed with `--kit-arg` override those in the file. + +### Which settings can you change? + +For a kit set, you can change only the arguments the author has exposed. +Other component arguments are fixed when the set is published. + +Settings chosen during the image build, such as a tool's version, require +rebuilding the image. + +## Restrict kit sources + +[`kit.allowedSources`](../configuration/settings.md#kitallowedsources) controls +permitted remote kit sources. Its default permits +Docker Hub. To include a Git publisher, set the complete list of prefixes you +want to permit: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]' +``` + +Prefixes match at path-segment boundaries. Local source directories are +controlled separately by `kit.allowLocalKits`, which defaults to `true`: + +```console +$ sbx settings set kit.allowLocalKits false +``` + +For defaults and environment variable equivalents, see the +[kit settings reference](../configuration/settings.md#kits). + +## Verify kit signatures + +To verify a published kit against its author's signing identity: + +```console +$ sbx kit verify docker.io/<NAMESPACE>/my-kit:1.0.0 \ + --certificate-identity <SIGNER_IDENTITY> \ + --certificate-oidc-issuer <ISSUER_URL> +``` + +For key-based signatures, use `--key cosign.pub` instead of the certificate +identity and issuer options. Obtain the expected identity or public key from +the publisher. + +To require trusted signatures when loading kits, configure the trusted signer +policy, then turn on the requirement: + +```console +$ sbx settings set kit.trustedSigners \ + '[{"identity":"release-bot@example.com","issuer":"https://accounts.google.com"}]' +$ sbx settings set kit.requireSignature true +``` + +V3 source directories and Git sources don't support the source-signing +workflow. Use a signed OCI image when signatures are required. + +## Debug kits + +When a tool is missing or a request fails, inspect the running sandbox: + +```console +$ sbx exec <SANDBOX> -- which <TOOL> +$ sbx exec <SANDBOX> -- cat /home/agent/.config/<TOOL>/settings.json +$ sbx policy log +``` + +The policy log shows outbound requests and the rules they matched. Use it to +find blocked package registries or API hosts. If downloads fail after adding a kit that requests +credentials, ask its author to check that credential injection targets only +the service hosts that need it. + +To try an updated v3 kit, create a sandbox with a different name. Reusing +an existing sandbox keeps its recorded kit configuration. diff --git a/content/manuals/ai/sandboxes/diagrams/credential-injection.yaml b/content/manuals/ai/sandboxes/diagrams/credential-injection.yaml new file mode 100644 index 000000000000..8ea80dcec03a --- /dev/null +++ b/content/manuals/ai/sandboxes/diagrams/credential-injection.yaml @@ -0,0 +1,145 @@ +title: Follow an authenticated request +description: Use Next and Previous to follow the request at your own pace, or select a step to jump to it. +canvas: + width: 820 + height: 430 +boundaries: + - id: host + label: Host machine + x: 16 + y: 24 + width: 532 + height: 382 + kind: host + - id: sandbox + label: Sandbox microVM + x: 36 + y: 68 + width: 300 + height: 310 + kind: sandbox +nodes: + - id: agent + label: AI agent + description: Sends the API request + x: 65 + y: 122 + width: 168 + height: 76 + kind: process + - id: docker-engine + label: Docker Engine + description: Private to this sandbox + x: 65 + y: 267 + width: 126 + height: 64 + kind: context + - id: workspace + label: Workspace + description: Shared with the host + x: 200 + y: 267 + width: 126 + height: 64 + kind: context + - id: policy + label: Network policy + description: Checks the destination + x: 360 + y: 106 + width: 168 + height: 70 + kind: control + - id: proxy + label: Host-side proxy + description: Rewrites the auth header + x: 360 + y: 218 + width: 168 + height: 70 + kind: control + - id: credentials + label: Credential store + description: Real token stays here + x: 360 + y: 326 + width: 168 + height: 56 + kind: secret + - id: provider + label: Model provider + description: Receives the request + x: 648 + y: 192 + width: 156 + height: 84 + kind: external +edges: + - id: agent-policy + from: agent + to: policy + - id: policy-proxy + from: policy + to: proxy + - id: credentials-proxy + from: credentials + to: proxy + - id: proxy-provider + from: proxy + to: provider + offset: -7 + - id: provider-proxy + from: provider + to: proxy + offset: 7 +steps: + - label: The agent prepares the request + body: The agent sees a sentinel value instead of the real API credential. + activeNodes: [agent] + token: + node: agent + label: proxy-managed + placement: bottom + state: The sandbox sees only the proxy-managed sentinel. + - label: The request leaves the microVM + body: Outbound HTTP and HTTPS traffic crosses the sandbox boundary through the host network path. + activeNodes: [agent, policy] + activeEdges: [agent-policy] + token: + edge: agent-policy + label: proxy-managed + state: The real credential remains outside the microVM. + - label: Network policy checks the destination + body: The request continues only when an active policy permits the provider domain. + activeNodes: [policy] + activeEdges: [agent-policy] + token: + node: policy + label: allowed + placement: top + state: Network policy allows the provider destination. + - label: The proxy retrieves the credential + body: The host-side proxy resolves the matching credential without copying it into the sandbox. + activeNodes: [proxy, credentials] + activeEdges: [policy-proxy, credentials-proxy] + token: + edge: credentials-proxy + label: host lookup + state: The credential stays in the host credential store. + - label: The proxy rewrites the header + body: The proxy replaces the sentinel with the real credential after the request has left the microVM. + activeNodes: [proxy, provider] + activeEdges: [proxy-provider] + token: + edge: proxy-provider + label: Bearer •••••• + state: The provider receives the rewritten authorization header. + - label: The response returns + body: The provider response returns through the host proxy to the agent. The credential remains on the host. + activeNodes: [provider, proxy, agent] + activeEdges: [provider-proxy] + token: + edge: provider-proxy + label: 200 OK + state: The credential remains on the host after the response. diff --git a/content/manuals/ai/sandboxes/diagrams/trust-boundary-topology.yaml b/content/manuals/ai/sandboxes/diagrams/trust-boundary-topology.yaml new file mode 100644 index 000000000000..b129b23c9a22 --- /dev/null +++ b/content/manuals/ai/sandboxes/diagrams/trust-boundary-topology.yaml @@ -0,0 +1,123 @@ +type: topology +title: Explore the microVM isolation boundary +description: Select a component or labeled connection to inspect what is private, mounted, or unreachable. +canvas: + width: 720 + height: 520 +overview: + category: Isolation overview + label: The agent is contained inside the microVM + body: The agent controls the private VM filesystem and Docker Engine. The workspace, optional skills store, and forwarded SSH agent socket are explicit host connections; other host resources have no direct access path. +boundaries: + - id: host + label: Host machine + x: 12 + y: 18 + width: 696 + height: 484 + kind: host + - id: sandbox + label: Sandbox microVM + x: 34 + y: 56 + width: 350 + height: 426 + kind: sandbox +nodes: + - id: agent + label: AI agent + description: Full control in the microVM + details: The agent has sudo access inside the microVM. It can install packages, run code, and modify resources that are inside the sandbox boundary. + category: Inside the microVM + x: 90 + y: 165 + width: 180 + height: 72 + kind: process + - id: vm-filesystem + label: VM filesystem + description: Private to this sandbox + details: The microVM has its own persistent filesystem. The agent cannot use it to browse files elsewhere on the host. + category: Inside the microVM + x: 50 + y: 370 + width: 158 + height: 72 + kind: context + - id: sandbox-engine + label: Docker Engine + description: No host connection + details: Containers created by the agent run on the Docker Engine inside the microVM. This engine has no connection to the Docker daemon on the host. + category: Inside the microVM + x: 218 + y: 370 + width: 145 + height: 72 + kind: control + - id: workspace + label: Workspace + description: Mounted from the host + details: Direct mode mounts the host working tree read-write, so edits are visible on both sides. Clone mode mounts the host repository read-only and gives the agent a private clone. + category: Explicitly shared + x: 445 + y: 68 + width: 205 + height: 72 + kind: shared + - id: skills + label: Shared skills store + description: Optional shared mount + details: Supported agents mount the host-side skills store read-write unless you opt out. Changes can become visible to agents in other participating sandboxes. + category: Explicitly shared + x: 445 + y: 170 + width: 205 + height: 72 + kind: shared + - id: ssh-agent + label: SSH agent socket + description: Forwarded by default + details: When SSH_AUTH_SOCK is set on the host, Docker Sandboxes forwards the agent socket into the microVM. Sandbox processes can request signatures, but the private keys stay on the host. + category: Explicitly shared + x: 445 + y: 272 + width: 205 + height: 72 + kind: shared + - id: host-resources + label: Other host resources + description: No direct access + details: The agent has no direct path to the rest of the host filesystem, host processes, or the host Docker daemon. + category: Outside the microVM + x: 445 + y: 390 + width: 205 + height: 72 + kind: restricted +edges: + - id: workspace-mount + from: agent + to: workspace + label: Workspace mount + details: This explicit mount is the agent's path to project files on the host. Its permissions depend on whether the sandbox uses direct mode or clone mode. + category: Shared relationship + kind: shared + bidirectional: true + labelOffset: -4 + - id: skills-mount + from: agent + to: skills + label: Skills mount + details: This optional read-write mount connects supported agents to a persistent skills store shared through the host. + category: Shared relationship + kind: shared + bidirectional: true + - id: ssh-agent-mount + from: agent + to: ssh-agent + label: SSH agent socket + details: The forwarded socket gives sandbox processes access to signing operations through the host SSH agent without exposing the private keys. + category: Shared relationship + kind: shared + bidirectional: true + labelOffset: 4 diff --git a/content/manuals/ai/sandboxes/docker-desktop.md b/content/manuals/ai/sandboxes/docker-desktop.md deleted file mode 100644 index 57a07f97a748..000000000000 --- a/content/manuals/ai/sandboxes/docker-desktop.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Docker Desktop sandboxes (deprecated) -linkTitle: Docker Desktop -description: Run sandboxed AI coding agents using Docker Desktop and the docker sandbox CLI. -keywords: docker desktop, docker sandbox, ai agents, sandboxes, deprecated -weight: 80 -sitemap: false -notoc: true ---- - -> [!WARNING] -> -> The Docker Desktop-integrated `docker sandbox` commands are deprecated and -> replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). This -> deprecation applies only to the Docker Desktop integration, not to Docker -> Sandboxes. - -This page covers the Docker Desktop-integrated `docker sandbox` command for -running AI coding agents in isolated microVMs. This integration is superseded -by the standalone `sbx` CLI, which provides the full Docker Sandboxes workflow -and doesn't require Docker Desktop. - -> [!NOTE] -> Use the standalone `sbx` CLI for sandboxed AI agent workflows. - -## Prerequisites - -- Docker Desktop 4.58 or later -- macOS or Windows -- API keys for your chosen agent - -## Quick start - -1. Set your API key in your shell configuration file: - - ```plaintext {title="~/.bashrc or ~/.zshrc"} - export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx - ``` - - Source your shell configuration and restart Docker Desktop so the daemon - picks up the variable. - -2. Create and run a sandbox: - - ```console - $ cd ~/my-project - $ docker sandbox run claude - ``` - - The first run takes longer while Docker initializes the microVM. - -Replace `claude` with a different [agent](#supported-agents) if needed. - -## Supported agents - -| Agent | Command | Notes | -| --------------------------------- | -------------- | ------------------------------------ | -| Claude Code | `claude` | Most tested implementation | -| Codex | `codex` | | -| Copilot | `copilot` | | -| Gemini | `gemini` | | -| [Docker Agent](/ai/docker-agent/) | `docker-agent` | Also available as a standalone tool | -| Kiro | `kiro` | | -| OpenCode | `opencode` | | -| Custom shell | `shell` | Minimal environment for manual setup | - -The agent type is specified when creating a sandbox and can't be changed later. - -## Authentication - -Each agent requires its own API key or credentials. Docker Sandboxes uses a -daemon that doesn't inherit environment variables from your shell session, so -you must set keys in your shell configuration file (not just export them in -your terminal). - -Common environment variables by agent: - -| Agent | Environment variable(s) | -| ------------ | ------------------------------------------------- | -| Claude Code | `ANTHROPIC_API_KEY` | -| Codex | `OPENAI_API_KEY` | -| Copilot | `GH_TOKEN` or `GITHUB_TOKEN` | -| Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | -| Docker Agent | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and others | -| OpenCode | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and others | -| Kiro | Device flow (interactive browser login) | -| Shell | Any provider keys needed | - -After setting variables, source your shell configuration and restart Docker -Desktop. The sandbox proxy injects credentials into API requests so keys stay -on your host and are never stored inside the sandbox. - -## Commands - -```console -$ docker sandbox run AGENT [PATH] # Create and run -$ docker sandbox ls # List sandboxes -$ docker sandbox exec -it <name> bash # Shell into a sandbox -$ docker sandbox rm <name> # Remove a sandbox -$ docker sandbox reset # Remove all sandboxes -$ docker sandbox network proxy <name> --policy … # Set network policy -$ docker sandbox network log # View network log -``` - -Sandboxes don't appear in `docker ps` because they're microVMs, not -containers. For the full command reference, see the -[CLI reference](/reference/cli/docker/sandbox/). - -Pass agent-specific CLI options after the sandbox name with a `--` separator: - -```console -$ docker sandbox run <name> -- --continue -``` - -## Architecture - -Each sandbox is a lightweight microVM with its own kernel, using your system's -native virtualization (macOS virtualization.framework, Windows Hyper-V). The -default agent templates include a private Docker daemon, so `docker build` and -`docker compose up` run inside the sandbox without affecting your host. - -```plaintext -Host system - ├── Your containers and images - ├── Sandbox VM 1 - │ ├── Docker daemon (isolated) - │ ├── Agent container - │ └── Containers created by agent - └── Sandbox VM 2 - ├── Docker daemon (isolated) - └── Agent container -``` - -Your workspace syncs bidirectionally between host and sandbox at the same -absolute path. Outbound internet goes through an HTTP/HTTPS filtering proxy on -the host. See [Network policies](#network-policies) for configuration. - -## Network policies - -The filtering proxy controls what a sandbox can access. By default, all -traffic is allowed except private networks and localhost. - -Allow mode (block specific destinations): - -```console -$ docker sandbox network proxy my-sandbox \ - --policy allow \ - --block-cidr 10.0.0.0/8 -``` - -Deny mode (allow specific destinations): - -```console -$ docker sandbox network proxy my-sandbox \ - --policy deny \ - --allow-host api.anthropic.com \ - --allow-host "*.npmjs.org" -``` - -View what an agent is accessing: - -```console -$ docker sandbox network log -``` - -## Custom templates - -Build custom templates to pre-install tools: - -```dockerfile -FROM docker/sandbox-templates:claude-code - -USER root -RUN apt-get update && apt-get install -y build-essential \ - && rm -rf /var/lib/apt/lists/* -USER agent -``` - -```console -$ docker build -t my-template:v1 . -$ docker sandbox run -t my-template:v1 claude ~/project -``` - -## Base environment - -All agent templates share a common environment: - -- Ubuntu 25.10 -- Docker CLI (with Buildx and Compose), Git, GitHub CLI, Node.js, Go, Python 3, uv, make, jq, ripgrep -- Non-root `agent` user with sudo access -- Package managers: apt, pip, npm - -## Troubleshooting - -<!-- vale off --> - -### 'sandbox' is not a docker command - -<!-- vale on --> - -The CLI plugin isn't installed or isn't in the correct location. Verify the -plugin exists at `~/.docker/cli-plugins/docker-sandbox` and restart Docker -Desktop. - -### Beta features need to be enabled - -If your Docker Desktop is managed by an administrator with -[Settings Management](/enterprise/security/hardened-desktop/settings-management/), -ask them to -[allow beta features](/enterprise/security/hardened-desktop/settings-management/configure-json-file/#beta-features). - -### Authentication failure - -Verify your API key is valid and set in your shell configuration file (not -just exported in the current session). Source the file and restart Docker -Desktop. - -### Permission denied on workspace files - -Check **Docker Desktop** > **Settings** > **Resources** > **File Sharing** and -ensure your workspace path is listed. Verify file permissions with `ls -la`. - -### Sandbox crashes on Windows - -If launching multiple sandboxes causes crashes, end all `docker.openvmm.exe` -processes in Task Manager and restart Docker Desktop. Launch sandboxes one at a -time. - -### Persistent issues - -Reset all sandbox state: - -```console -$ docker sandbox reset -``` - -This stops all VMs and deletes all sandbox data. Create fresh sandboxes -afterward. diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 2e60dff35f78..8125db917a11 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -1,10 +1,30 @@ --- title: FAQ -weight: 70 +weight: 140 description: Frequently asked questions about Docker Sandboxes. -keywords: docker sandboxes, sbx, faq, sign in, telemetry +keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste, pricing, commercial use, allowlist, firewall, domains, proxy --- +Host integration and workspace instructions on this page describe local +sandboxes. See [Local and cloud differences](cloud/local-vs-cloud.md) before +adapting those workflows to the cloud. + +## Is Docker Sandboxes free? Can I use it commercially? + +The `sbx` CLI and local sandbox compute are free to use, including for +commercial and professional work. Cloud sandbox compute uses a +[pay-as-you-go subscription](/manuals/agentic-platform/signup.md#billing). +Model-provider charges are separate from sandbox compute. + +Organization governance for local sandboxes includes centrally managed network, +filesystem, and MCP policies, +[sign-in enforcement](governance/monitor-and-enforce/sign-in-enforcement.md), +and [audit logs](governance/audit/). These +[organization governance features](governance/) require a separate paid +subscription — +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +to get started. + ## Why do I need to sign in? Docker Sandboxes is built around the idea that you and your agents are a team. @@ -14,26 +34,49 @@ Signing in gives each sandbox a verified identity, which lets Docker: containers, install packages, and push code. Your Docker identity is the anchor. - **Enable team features.** Team-scale features like - [organization governance](governance/org.md), shared environments, and - audit logs need a concept of "who," and adding that later would be worse for - everyone. + [organization governance](governance/), shared environments, and audit logs + need a concept of "who," and adding that later would be worse for everyone. - **Authenticate against Docker infrastructure.** Sandboxes pull images, run - daemons, and talk to Docker services. A Docker account makes that seamless. + daemons, and talk to Docker services. A Docker account authenticates those + requests. Your Docker account email is only used for authentication, not marketing. ## Can I enforce sandbox policies across my organization? -Yes. Admins can centrally manage network and filesystem policies from the -Docker Admin Console. Rules defined there apply to every sandbox in the -organization. When organization governance is active, it replaces local rules -set with `sbx policy` — local rules are no longer evaluated. +Yes. Admins can centrally manage network, filesystem, and MCP policies. These +controls apply to local sandboxes in the organization. When organization +governance is active, only organization allow rules grant access: local allow +rules set with `sbx policy` are no longer evaluated, while local deny rules +still apply on top. -See [Organization governance](governance/org.md). This feature requires -a separate paid subscription — +See [Organization policies](governance/access-controls/organization.md). This +feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. +Cloud sandboxes use separate network policy configuration. +See [Cloud network policy](cloud/network-policy.md) for cloud controls. + +## Which domains do I need to allow for Docker Sandboxes to work? + +If your organization restricts outbound network access with a firewall or +proxy, add the following domains to your allowlist so that `sbx` can +authenticate, pull images, and report diagnostics for local sandboxes. +Cloud operations also connect to `https://api.sandboxes-cloud.docker.com`. + +| Domain | Description | +| -------------------------------------------------- | ----------------------- | +| https://login.docker.com | Authentication | +| https://hub.docker.com | Docker Hub | +| https://api.docker.com | Docker API | +| https://marlin-2.docker.com | Telemetry | +| https://marlin-api.docker.com | Telemetry | +| https://registry-1.docker.io | Docker pull/push | +| https://auth.docker.io | Registry authentication | +| https://dhi.io | Docker Hardened Images | +| https://sbx-diagnostics.s3.us-east-1.amazonaws.com | Diagnostics upload | + ## Does the CLI collect telemetry? The `sbx` CLI collects basic usage data about CLI invocations: @@ -43,10 +86,11 @@ The `sbx` CLI collects basic usage data about CLI invocations: - How long it took - If you're signed in, your Docker username is included -Docker Sandboxes doesn't monitor sessions, read your prompts, or access your -code. Your code stays in the sandbox and on your host. +CLI usage telemetry does not include your prompts or code. Cloud sandboxes +execute on Docker-managed infrastructure, so files you transfer to them are +stored in the cloud. -To opt out of all analytics, set the `SBX_NO_TELEMETRY` environment variable: +To opt out of CLI usage analytics, set the `SBX_NO_TELEMETRY` environment variable: ```console $ export SBX_NO_TELEMETRY=1 @@ -54,78 +98,38 @@ $ export SBX_NO_TELEMETRY=1 ## How do I set custom environment variables inside a sandbox? -The [`sbx secret`](/reference/cli/sbx/secret/) command only supports a fixed set -of [services](security/credentials.md#built-in-services) (Anthropic, OpenAI, -GitHub, and others). If your agent needs an environment variable that isn't -tied to a supported service, such as `BRAVE_API_KEY` or a custom internal -token, write it to `/etc/sandbox-persistent.sh` inside the sandbox. This -file is sourced on every shell login, so the variable persists across agent -sessions for the sandbox's lifetime. - -Use `sbx exec` to append the export: - -```console -$ sbx exec -d <sandbox-name> bash -c "echo 'export BRAVE_API_KEY=your_key' >> /etc/sandbox-persistent.sh" -``` - -The `bash -c` wrapper is required so the `>>` redirect runs inside the -sandbox instead of on your host. - -> [!NOTE] -> Unlike `sbx secret`, which injects credentials through a host-side proxy -> without exposing them to the agent, this approach stores the value inside -> the sandbox. The agent process can read it directly. Only use this for -> credentials where proxy-based injection isn't available. +Starting with `sbx` version 0.39.0, use `-e`/`--env` or `--env-file` with +`sbx run` and `sbx create`. See +[Set environment variables](usage.md#set-environment-variables) for syntax, +precedence rules, persistent configuration for an existing sandbox, and +guidance for credentials. -Variables in `/etc/sandbox-persistent.sh` are sourced automatically when -bash runs inside the sandbox, including interactive sessions and agents -started with `sbx run`. If you run a command directly with -`sbx exec <name> <command>`, the command runs without a shell, so the -persistent environment file is not sourced. Wrap the command in `bash -c` -to load the environment: - -```console -$ sbx exec <sandbox-name> bash -c "your-command" -``` - -To verify the variable is set, open a shell in the sandbox: - -```console -$ sbx exec -it <sandbox-name> bash -$ echo $BRAVE_API_KEY -``` +Variables in `/etc/sandbox-persistent.sh` are available to interactive sessions +and agents started with `sbx run`. A variable only takes effect for sessions +and agents started after it's added. Restart a running agent, or stop and start +the sandbox, to pick up the new value. ## Why do agents run without approval prompts? The sandbox itself is the safety boundary. Because agents run inside an -isolated microVM with [network policies](governance/), -[credential isolation](security/credentials.md), and no access to your host -system outside the workspace, the usual reasons for approval prompts (preventing -destructive commands, network access, file modifications) are handled by the -sandbox isolation layers instead. +isolated microVM with [network policies](governance/access-controls/network.md), +[credential isolation](security/isolation.md#credential-isolation), and no access to your host +system outside explicitly shared paths, the usual reasons for approval prompts +(preventing destructive commands, network access, file modifications) are +handled by the sandbox isolation layers instead. If you prefer to re-enable approval prompts, change the permission mode inside the session. Most agents let you switch permission modes after startup. In Claude Code, use the `/permissions` command to change the mode interactively. -To make approval prompts the default for every session, define a custom -agent kit that overrides the agent's entrypoint to drop the -permission-skipping flag. For example, a kit that launches Claude Code -without `--dangerously-skip-permissions`: - -```yaml {title="claude-safe/spec.yaml"} -schemaVersion: "1" -kind: agent -name: claude-safe -agent: - image: "docker/sandbox-templates:claude-code-docker" - entrypoint: - run: [claude] -``` +To make approval prompts the default for every session, create a v2 sandbox +kit that extends the built-in agent and changes its launch options. See +[Fork an existing agent](customize/kits-v2.md#fork-an-existing-agent) +for a complete example. -Run it with `sbx run claude-safe --kit ./claude-safe/`. See -[Agent kits](customize/kits.md#agent-kits) for the full pattern. +For an environment built entirely with v3 kits, set the launch command in +the workload's Dockerfile. See [Build a v3 agent kit](/manuals/ai/sandboxes/customize/author/build-an-agent.md). ## How do I know if my agent is running in a sandbox? @@ -139,45 +143,73 @@ in-progress task: ## Why doesn't the sandbox use my user-level agent configuration? -Sandboxes don't pick up user-level agent configuration from your host. This -includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex, -where hooks, skills, and other settings are stored. Only project-level -configuration in the working directory is available inside the sandbox. +Local sandboxes don't import your complete user-level agent configuration. Hooks, +settings, and other files under directories such as `~/.claude` remain on the +host. Project-level configuration in the working directory remains available +inside the sandbox. -To make configuration available in a sandbox, copy or move what you need into -your project directory before starting a session: +Shared agent skills are the exception. Use `sbx skills add` to install skills +from a Git repository, or run `sbx skills import` to copy skills from supported +host directories. `sbx` keeps the skills in a persistent store shared with +sandboxes. See [Share agent skills](workflows/agent-skills.md) for repository +management, supported host directories, mount behavior, and per-sandbox +opt-out. + +Keep project-specific skills and other agent configuration in the project +itself. This versions the configuration alongside the code. Don't use symlinks +to host paths because a sandboxed agent can't follow them outside the sandbox. + +## Can I paste images into an agent? + +In local sandboxes, image paste is off by default. Text paste works because the +terminal sends it directly. Pasting an image or screenshot with `Ctrl+V` is different: +the agent reads it from your host clipboard, and the sandbox blocks that access +unless you opt in. + +Turn on [`clipboard.imagePaste`](configuration/settings.md#clipboardimagepaste): ```console -$ cp -r ~/.claude/skills .claude/skills +$ sbx settings set clipboard.imagePaste true ``` -Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside -the sandbox. +`Ctrl+V` then pastes host images into agents that read the clipboard, including +Claude Code and Codex. The setting takes effect within a few seconds, even for +running sandboxes. -Collocating skills and other agent configuration with the project itself is a -good practice regardless of sandboxes. It's versioned alongside the code and -evolves with the project as it changes. +This is opt-in because it relaxes the sandbox's isolation: when enabled, a process +inside the sandbox can read your host clipboard through the host-side proxy. The +exposure is narrow — reads happen only on a paste, return image data only +(`image/png`), and clipboard content is never cached or logged — but it's still +host data crossing into the sandbox, so it stays off until you turn it on. + +To turn it back off: + +```console +$ sbx settings set clipboard.imagePaste false +``` ## Can I use Docker Sandboxes on headless Linux? -Yes. On Linux, `sbx` stores secrets in the Secret Service exposed by your -desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some -WSL setups have no running Secret Service, so `sbx` falls back to an encrypted -file under `$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to +Yes. For local sandboxes on Linux, `sbx` stores secrets in the Secret Service +exposed by your desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some +WSL setups have no running Secret Service, so `sbx` falls back to a file under +`$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to `~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. No setup is required. When you store a secret on such a host, `sbx` prints a notice: ```text -No keychain detected - this secret will be stored in an encrypted file on disk +No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password ``` -The file is encrypted at rest and protected by `0700` directory permissions, -the same posture as `~/.docker/config.json`. It's weaker than an OS keychain, -which also mediates access per application. +`sbx` stores the file in a directory with `0700` permissions, the same +file-permission model used for `~/.docker/config.json`. Any user or process that +can read the file can retrieve the stored credentials, so treat the directory as +sensitive. Where available, prefer a keychain, which mediates access per +application. To keep secrets in a keyring instead, run a Secret Service on the host before storing them: install `gnome-keyring` and start `dbus-run-session`, or run the keyring daemon under a login session that unlocks it. Once a working Secret Service is available, `sbx` stores new secrets in the keychain again. For where each platform keeps secrets, see -[Where secrets are stored](security/credentials.md#where-secrets-are-stored). +[Where secrets are stored](configuration/credentials.md#where-secrets-are-stored). diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 3694a402c85a..28b6bfe6a9f0 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -1,153 +1,46 @@ --- -title: Get started with Docker Sandboxes -linkTitle: Get started -weight: 10 -description: Install the sbx CLI, configure credentials, and work through your first sandbox session. -keywords: sandbox, sbx, get started, install, credentials, clone mode, network policy +title: Get started with local Docker Sandboxes +linkTitle: Get started locally +weight: 20 +description: Configure agent credentials and work through your first local Docker Sandboxes session. +keywords: sandbox, sbx, get started, credentials, clone mode, network policy --- +This walkthrough uses local sandboxes. For cloud credentials and a first cloud +session, see [Get started with cloud sandboxes](cloud/_index.md#get-started). + Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each sandbox gets its own Docker daemon, filesystem, and network — the agent can -build containers, install packages, and modify files without touching your host -system. +build containers, install packages, and modify files without accessing host +resources beyond those you share. -This page walks through a typical first session: installing the CLI, -authenticating your agent, running a sandbox, isolating the agent's workspace, -and cleaning up. +This page walks through your first session: run an agent in a sandbox, see how +the sandbox isolates it, control what it can reach on the network, and clean +up. ## Prerequisites -{{< tabs group="os" >}} -{{< tab name="macOS" >}} - -- macOS Sonoma (version 14) or later -- Apple silicon - -{{< /tab >}} -{{< tab name="Windows" >}} - -- 64-bit Intel or AMD (x86_64) -- Windows 11 -- Windows Hypervisor Platform enabled. Open an elevated PowerShell prompt (Run - as Administrator) and run: - ```powershell - Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All - ``` - -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} - -- Ubuntu 24.04 or later -- 64-bit Intel or AMD (x86_64) -- KVM hardware virtualization supported and enabled by the CPU. If you're - running inside a VM, nested virtualization must be turned on. Verify that KVM - is available: - ```console - $ lsmod | grep kvm - ``` - A working setup shows `kvm_intel` or `kvm_amd` in the output. If the output - is empty, run `kvm-ok` for diagnostics. If KVM is unavailable, `sbx` will - not start. -- Your user in the `kvm` group: - ```console - $ sudo usermod -aG kvm $USER - ``` - Log out and back in (or run `newgrp kvm`) for the group change to take effect. - -{{< /tab >}} -{{< /tabs >}} - -An API key or authentication method for the agent you want to use. Most agents -require an API key for their model provider (Anthropic, OpenAI, Google, and -others). See the [agent pages](agents/) for provider-specific instructions. - -Docker Desktop is not required to use `sbx`. - -## Install and sign in - -{{< tabs group="os" >}} -{{< tab name="macOS" >}} - -```console -$ brew install docker/tap/sbx -$ sbx login -``` - -{{< /tab >}} -{{< tab name="Windows" >}} - -```powershell -> winget install -h Docker.sbx -> sbx login -``` - -{{< /tab >}} -{{< tab name="Linux (Ubuntu)" >}} - -```console -$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh -$ sudo apt-get install docker-sbx -$ sbx login -``` - -The first command adds Docker's `apt` repository to your system. - -{{< /tab >}} -{{< /tabs >}} - -If you need to install `sbx` manually, download a binary directly from the -[sbx-releases](https://github.com/docker/sbx-releases/releases) repository. - -`sbx login` opens a browser for Docker OAuth. On first login (and after `sbx -policy reset`), the CLI prompts you to choose a default network policy for your -sandboxes: - -```plaintext -Choose a default network policy: - - 1. Open — All network traffic allowed, no restrictions. - 2. Balanced — Default deny, with common dev sites allowed. - 3. Locked Down — All network traffic blocked unless you allow it. - -Use ↑/↓ to navigate, Enter to select, or press 1–3. -``` - -**Balanced** is a good starting point — it permits traffic to common -development services while blocking everything else. You can adjust individual -rules later. See [Policies](governance/local.md) for a full description of each -option. - -> [!NOTE] -> See the [FAQ](faq.md) for details on why sign-in is required and what -> happens with your data. +- [Install the `sbx` CLI](install.md) and sign in to Docker +- Configure an authentication method for the agent you want to use. Most agents + require an API key for their model provider. See the [agent pages](agents/) + for provider-specific instructions. ## Authenticate your agent -Agents need credentials for their model provider. How you provide them depends -on the agent. - For Claude Code with a Claude subscription (Max, Team, or Enterprise), no upfront setup is needed — use the `/login` command inside the sandbox to sign -in with OAuth. The session token stays on your host and is injected by a -proxy, not stored inside the sandbox. - -For agents that use API keys (or if you prefer API key authentication for -Claude Code), store the key before starting a sandbox: - -```console -$ sbx secret set -g anthropic -``` +in with OAuth. The session token stays on your host and is never stored inside +the sandbox. -This prompts for the secret value and stores it in your OS keychain. A proxy on -your host injects the key into outbound API requests so it's never exposed -inside the sandbox. See [Credentials](security/credentials.md) for details on -scoping, supported services, and alternative methods. +If you prefer to authenticate with an API key, see +[Credentials](configuration/credentials.md) for how to store one with +`sbx secret set`. To give the agent access to GitHub for creating pull requests or interacting with repositories: ```console -$ sbx secret set -g github -t "$(gh auth token)" +$ sbx secret set github --command 'gh auth token' ``` ## Run your first sandbox @@ -160,75 +53,77 @@ $ cd ~/my-project $ sbx run --name my-sandbox claude ``` -Replace `claude` with the agent you want to use — see [Agents](agents/) for the -full list. +The first time you run a sandbox, the CLI prompts you to choose a default +network preset: -The first run takes a little longer while the agent image is pulled. Subsequent -runs reuse the cached image and start in seconds. +```plaintext +Initialize the global network policy for your sandboxes: -You can check what's running at any time: + Applies to all sandboxes, current and future — change it later with + "sbx policy allow/deny/rm". Kits, including built-in agent kits, may + also add per-sandbox rules. -```console -$ sbx ls -SANDBOX AGENT STATUS PORTS WORKSPACE -my-sandbox claude running ~/my-project + 1. Open — All network traffic allowed, no restrictions. + ❯ 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + + Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. ``` -You can also run `sbx` with no arguments to open an interactive dashboard. -The dashboard shows your sandboxes with live status, lets you attach to -agents, open shells, and manage network rules from one place. See -[Interactive mode](usage.md#interactive-mode) for details. +**Balanced** is a good starting point — it permits traffic to common +development services while blocking everything else. You can adjust individual +rules later. See [Local policy](governance/access-controls/local.md) for a full +description of each option. -![The interactive dashboard showing sandbox status, resource usage, and network governance controls.](images/sbx-dashboard.png) +Replace `claude` with the agent you want to use — see [Agents](agents/) for the +full list. -## Use clone mode +The first run takes a little longer while the agent image is pulled. Subsequent +runs reuse the cached image and start in seconds. -By default, the agent edits your working tree directly. To give the agent an -isolated copy of your repository, use `--clone`. Because `--clone` is a -create-time flag, remove the existing sandbox first: +This attaches you to the agent running inside the sandbox. Give it a real +task — ask it to add a feature, install a dependency, or build and run your +project. The agent has a full Linux environment with its own Docker daemon, so +it can install packages, build images, and start containers on its own while it +works. -```console -$ sbx rm my-sandbox -$ sbx run --clone --name my-sandbox claude -``` +## See what the agent can touch -In clone mode, the sandbox keeps a private Git clone inside the microVM and -mounts your host repository read-only. The sandbox exposes its clone as a -`sandbox-<sandbox-name>` remote on your host, so you review the agent's -commits the same way you'd fetch from any other remote: +From another terminal, list your sandboxes: ```console -$ git fetch sandbox-my-sandbox -$ git log sandbox-my-sandbox/main -$ git diff main..sandbox-my-sandbox/main +$ sbx ls +SANDBOX AGENT STATUS PORTS WORKSPACE CREATED +my-sandbox claude ● running ~/my-project 2m ``` -When you're ready to create a pull request: +Each row shows a sandbox's name, agent, status, +[published ports](usage.md#publish-ports), workspace, and age. The workspace is +the host directory shared into the sandbox and the one part of your machine +the agent can see. -```console -$ git checkout -b my-feature sandbox-my-sandbox/main -$ git push -u origin my-feature -$ gh pr create -``` +When you run `sbx run` from a project directory without passing a workspace +path, the current directory is mounted read-write. The agent and your host see +the same files. Edits the agent makes to your project appear in your working +tree as it writes them, and you review them as an ordinary Git diff before +committing. -For Claude Code, pair `--clone` with the -[agents view](agents/claude-code.md#agents-view) to dispatch tasks to -subagents that each work on their own branch inside the same sandbox: +Everything else runs inside the microVM, isolated from your host: -```console -$ sbx run --clone --name my-sandbox claude -- agents -``` +- The agent has its own filesystem, Docker daemon, and network. +- Packages it installs, images it pulls, and containers it starts stay inside + the sandbox. Your host system is untouched, and removing the sandbox discards + them. -Clone mode is especially useful when running multiple agents on the same -repository in parallel — each works in its own isolated clone without -touching your host working tree. See [Clone mode](usage.md#clone-mode) for -the full workflow, including how to have the agent commit to a dedicated -branch. +If you'd rather the agent not touch your working tree at all — for example, +when running several agents on one repository — use +[clone mode](usage.md#clone-mode), which gives it a private clone instead. -## Manage network access +## Control what the agent can reach -Your network policy controls what the sandbox can reach. If the agent fails to -connect to an API or service, it's likely blocked by the policy. +Isolation isn't only about the filesystem. You also control what the sandbox +can reach on the network. You chose a default policy before the sandbox +started, and you can inspect or adjust it at any time. Check which rules are in effect: @@ -244,12 +139,14 @@ $ sbx policy allow network registry.npmjs.org With **Locked Down**, even your model provider API is blocked unless you explicitly allow it. With **Balanced**, common development services are -permitted by default. See [Policies](governance/local.md) for the full rule -set and how to customize it. +permitted by default. See +[local policy](governance/access-controls/local.md) for the full rule set +and how to customize it. ## Clean up -Sandboxes persist after the agent exits. To stop a sandbox without deleting it: +Sandboxes persist after the agent exits, so you can stop one and pick up where +you left off later: ```console $ sbx stop my-sandbox @@ -267,14 +164,28 @@ Removing a sandbox deletes everything inside it — installed packages, Docker images, and the in-sandbox Git clone if you used clone mode. Files in your host working tree are unaffected. -## Next steps - -- [Usage guide](usage.md) — sandbox management, reconnecting, multiple - workspaces, port forwarding, and more -- [Agents](agents/) — supported agents and configuration -- [Customize](customize/) — build reusable templates or declare capabilities - with kits -- [Credentials](security/credentials.md) — credential storage and management -- [Workspace isolation](security/isolation.md#workspace-isolation) — what - the agent can affect on your host, and how to review changes -- [Governance](governance/) — control outbound access +## What's next + +You've run an agent, seen how the sandbox isolates it, and controlled its +network access. A few directions from here. + +Run `sbx` with no arguments to open the interactive dashboard: a live view of +every sandbox where you can attach to agents, open shells, and manage network +rules from one place. + +![The interactive dashboard showing sandbox status, resource usage, and network governance controls.](images/sbx-dashboard.png) + +Then explore: + +- [Usage guide](usage.md) — basic commands, reconnecting, workspaces, and port + publishing. +- [Workflow patterns](workflows/) — Git strategies, local services, CI, and + authenticated tools. +- [Sandbox environment files](configuration/environment-files.md) — declare and share + repeatable local sandbox configurations with `sbxenv.yaml`. +- [Customize with kits](customize/) — package an agent, its tools, and its + network rules into a reusable definition you launch with a single flag. +- [Agents](agents/) — the full list of supported agents and how to configure + each one. +- [Governance](governance/) — centrally manage network, filesystem, and MCP + policies across a team. diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 5d7f49955402..7c1fba061daf 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -1,29 +1,38 @@ --- title: Governance -weight: 55 +weight: 120 description: Control what sandboxes can access, from local developer rules to org-wide enforcement. -keywords: docker sandboxes, governance, policy, network access, filesystem access, organization policy +keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy --- +The governance described here applies to local sandboxes. Cloud sandboxes +use separate network policy configuration. See +[Cloud network policy](../cloud/network-policy.md) for cloud controls. + Sandbox governance covers the policy system that controls what sandboxes can -access over the network and on the filesystem. It operates at two layers, and -only one applies at a time: +access over the network, on the filesystem, and through MCP. For MCP setup and +server registration, see [MCP gateway](../mcp-gateway.md). Governance operates +at two layers: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. -See [Local policy](local.md). +See [Local policy](access-controls/local.md). -**Organization policy** is configured centrally in the Docker Admin Console or -via the [Governance API](/reference/api/ai-governance/). Rules defined at the org level apply -uniformly across every sandbox in the organization. When organization -governance is active, it replaces local policy entirely: local `sbx policy` -rules are no longer evaluated. See [Organization policy](org.md). +**Organization policy** is configured centrally in Docker Home. Network and +filesystem policies can also be managed via the +[Governance API](/reference/api/ai-governance/). Controls defined at the org +level apply uniformly across every local sandbox in the organization. Organization +governance can also include MCP policies for sandbox MCP activity. When +organization governance is active, only organization allow rules grant access: +local `sbx policy` allow rules are no longer evaluated, while local deny rules +still apply on top. See +[Organization policies](access-controls/organization.md). Alongside this access-control policy, admins can require developers to sign in as members of their organization before using sandboxes at all. -[Sign-in enforcement](sign-in-enforcement.md) is deployed through endpoint -management and ensures developers can't bypass organization policy by using a -personal account. +[Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md) is deployed +through endpoint management and ensures developers can't bypass organization +policy by using a personal account. > [!NOTE] > Organization governance is available on a separate paid subscription. @@ -32,17 +41,36 @@ personal account. ## Learn more -- [Policy concepts](concepts.md): resource model, rule syntax, evaluation, - and precedence -- [Local policy](local.md): configure network and filesystem rules on your - machine with the `sbx policy` CLI -- [Organization policy](org.md): centrally manage sandbox policies across - your organization from the Admin Console -- [Sign-in enforcement](sign-in-enforcement.md): require developers to sign in - as organization members, enforced through endpoint management -- [Monitoring](monitoring.md): inspect active rules and monitor sandbox - network traffic with `sbx policy ls` and `sbx policy log` -- [Audit logs](audit.md): capture a durable, structured record of every - policy decision for SIEM ingestion and compliance -- [API reference](/reference/api/ai-governance/): manage org policies - programmatically via the Governance API +Start with [Policy concepts](concepts.md) for the resource model, rule syntax, +MCP policy basics, evaluation, and precedence. + +### Access controls + +- [Local policy](access-controls/local.md): configure network rules on your + machine with the `sbx policy` CLI. +- [Organization policies](access-controls/organization.md): centrally manage + sandbox policies across your organization. +- [Network access policies](access-controls/network.md): control outbound network + access from sandboxes, by host or by HTTP method and path. +- [Filesystem access policies](access-controls/filesystem.md): control which + host paths sandboxes can mount as workspaces. +- [MCP access policies](access-controls/mcp.md): control MCP server registration, + tool calls, resources, prompts, and approval gates. + +### Monitor and enforce + +- [Monitoring policies](monitor-and-enforce/monitoring.md): inspect active + rules and monitor sandbox network traffic with `sbx policy ls` and + `sbx policy log`. +- [Audit logs](audit/): view, configure, export, and collect governance audit + records. +- [Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md): require + developers to sign in as organization members, enforced through endpoint + management. + +### Reference + +- [AI Governance API](/reference/api/ai-governance/): manage network and + filesystem org policies programmatically. +- [MCP policy reference](reference/mcp-policy.md): look up Docker MCP policy + actions, resources, attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md new file mode 100644 index 000000000000..bcaabdd429a5 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -0,0 +1,27 @@ +--- +title: Access controls +weight: 20 +description: Configure local and organization controls for sandbox network, filesystem, and MCP access. +keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access +--- + +Access controls are expressed as policies. Local and organization pages +describe where policies apply. Network and filesystem pages describe the rules +inside those policies. MCP policies use Cedar statements instead of the network +and filesystem rule format. + +## Policy scope + +- [Local policy](local.md): configure network rules on a developer machine with + the `sbx policy` CLI. +- [Organization policies](organization.md): manage centralized policies for an + organization or team. + +## Access surfaces + +- [Network access policies](network.md): control outbound network access from + sandboxes, by host or by HTTP method and path. +- [Filesystem access policies](filesystem.md): control which host paths + sandboxes can mount as workspaces. +- [MCP access policies](mcp.md): control MCP server registration, tool calls, + resources, prompts, and approval gates with Cedar policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md new file mode 100644 index 000000000000..7445a10d42f4 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -0,0 +1,55 @@ +--- +title: Filesystem access policies +linkTitle: Filesystem access +weight: 40 +description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. +keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount, organization policy, governance +--- + +Filesystem access policies control which host paths a sandbox can mount as a +workspace. Each policy contains one or more rules that restrict sandbox +workspaces to approved directories. + +Filesystem access is managed with [organization policies](organization.md). When +organization governance is active, organization rules determine which paths a +sandbox can mount, and the local filesystem allow rules from the default preset +become inactive. `sbx policy deny` applies to network access only, so there are +no local filesystem deny rules to layer on top. See +[Precedence](../concepts.md#precedence). + +## Rule syntax + +Filesystem rules use the actions `read` and `write`. Resources are host path +patterns. + +A writable workspace mount must be allowed by both a `read` rule and a `write` +rule. A read-only workspace needs only `read`. + +Examples: + +- `~/**` +- `/data/project/**` +- `C:\data\project\**` +- `\\wsl.localhost\<distro>\data\project\**` + +Use `**` to match a directory tree recursively. A single `*` matches only one +path segment. For exact path matching behavior across macOS, Linux, Windows, +and WSL, see [Filesystem rules](../concepts.md#filesystem-rules). + +## Organization filesystem rules + +Organization filesystem rules belong to policies that can apply to the whole +organization or to selected teams. For setup steps and team scoping, see +[Organization policies](organization.md). + +Filesystem policy is checked when a workspace is mounted, which happens when a +sandbox is created. To apply a filesystem policy change to a running workflow, +remove the sandbox and create a new one. + +## Troubleshooting + +### Sandbox cannot mount workspace + +If a sandbox fails to mount with a `mount policy denied` error, verify that the +filesystem allow rule uses `**` rather than `*`. A single `*` doesn't match +across directory separators. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md new file mode 100644 index 000000000000..c120e3863394 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -0,0 +1,383 @@ +--- +title: Local policy +weight: 10 +description: Configure local network access rules for sandboxes on your machine. +keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy +aliases: + - /ai/sandboxes/security/policy/ + - /ai/sandboxes/governance/local/ +--- + +The `sbx policy` command manages the local policy on your machine. The local +policy contains network access rules. Rules apply to all sandboxes on the +machine when you use the global scope, or to a single sandbox when scoped by +name. + +Local policy interacts with organization governance as follows: + +- **No org governance**: the local policy controls what sandboxes can access. +- **Org governance active**: only organization allow rules grant access, so + local allow rules are inactive and can't expand what the organization permits. + Local deny rules are still evaluated, so you can restrict access further than + the organization policy does. To list inactive rules, run + `sbx policy ls --include-inactive`. See + [Monitoring](../monitor-and-enforce/monitoring.md#showing-inactive-rules). + +See [Organization policies](organization.md) for how organization governance +works. + +For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see +[Policy concepts](../concepts.md#rule-syntax). + +## Default preset + +Outbound TCP traffic passes through a proxy on your host, which enforces access +rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed +with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an +address-based rule. UDP requires the experimental feature and policy rules +described in [Allow outbound UDP](#allow-outbound-udp). ICMP is blocked. + +If you haven't chosen a default preset, the CLI prompts you before it runs a +sandbox. Running `sbx policy reset` clears the preset and prompts you to choose +again: + +```plaintext +Initialize the global network policy for your sandboxes: + + Applies to all sandboxes, current and future — change it later with + "sbx policy allow/deny/rm". Kits, including built-in agent kits, may + also add per-sandbox rules. + + 1. Open — All network traffic allowed, no restrictions. + ❯ 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + + Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. +``` + +| Preset | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | +| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | +| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. | + +Presets initialize the global policy. Built-in agent kits and other kits can +add per-sandbox allow rules, including under **Locked Down** (`deny-all`). The +preset isn't an explicit deny rule that overrides those allowances. + +Under **Balanced** and **Locked Down**, a sandbox request that no rule matches +is blocked and asks for your approval instead of being denied outright, so you +can open access to each destination as a sandbox needs it. See +[Approval-required access](network.md#approval-required-access). + +To inspect the rules a kit adds to a sandbox, run: + +```console +$ sbx policy ls my-sandbox --source kit --type network --wide +``` + +To block a destination allowed by a kit, add an explicit deny rule: + +```console +$ sbx policy deny network --sandbox my-sandbox openrouter.ai +``` + +Deny rules take precedence over allow rules. See +[Policy precedence](../concepts.md#precedence). + +The **Balanced** preset's baseline allowlist is a good starting point for most +workflows. Run `sbx policy ls` to see exactly which rules it includes. + +> [!NOTE] +> If your organization manages sandbox policies centrally, organization rules +> take precedence over the preset you select here. See +> [Organization policies](organization.md). + +### Non-interactive environments + +In non-interactive environments such as CI pipelines or headless servers, the +interactive prompt can't be displayed. Use `sbx policy init` to set the +preset before running any other `sbx` commands: + +```console +$ sbx policy init balanced +``` + +Available values are `allow-all`, `balanced`, and `deny-all`. + +## Managing rules + +A rule covers a destination host. It can also name HTTP methods and paths to +narrow the match to part of that host. + +### Network rules + +Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and +[`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add or restrict access +on top of the active preset. Changes take effect immediately. Rules apply to +all sandboxes by default: + +```console +$ sbx policy allow network api.anthropic.com +$ sbx policy deny network ads.example.com +``` + +Pass `--sandbox <name>` to scope a rule to one sandbox: + +```console +$ sbx policy allow network --sandbox my-sandbox api.example.com +$ sbx policy deny network --sandbox my-sandbox ads.example.com +``` + +As of v0.38.0, you can also set per-sandbox deny rules at creation time with +`--deny-network` on `sbx create` or `sbx run`, instead of adding them after the +fact: + +```console +$ sbx create --deny-network ads.example.com claude . +$ sbx run --deny-network ads.example.com claude +``` + +Pass the flag multiple times to deny more than one host. Rules added this way +appear in `sbx policy ls <name>` and can be removed with +`sbx policy rm network --sandbox <name> --resource <host>`. + +Specify multiple hosts in one command with a comma-separated list: + +```console +$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" +``` + +Remove a rule by resource or by rule ID: + +```console +$ sbx policy rm network --resource ads.example.com +$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +To remove a sandbox-scoped rule, pass `--sandbox <name>`: + +```console +$ sbx policy rm network --sandbox my-sandbox --resource api.example.com +``` + +### HTTP method and path rules + +Add `--method` to an allow or deny rule to match specific HTTP methods on a +host, and `--path` to restrict it to part of the host's URL space: + +```console +$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**' +``` + +Quote the path so your shell doesn't expand the wildcard. Pass several methods +as a comma-separated list: + +```console +$ sbx policy allow network api.github.com --method GET,HEAD +``` + +`--method ANY` matches every HTTP method, and `--path` defaults to `/**` when +you omit it: + +```console +$ sbx policy allow network api.github.com --method ANY +``` + +`ANY` can't be combined with specific methods, and a path without a method is +rejected. Pass a method, or use `ANY` when you mean every method. + +Method names are case-insensitive. The accepted values are `GET`, `HEAD`, +`POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `CONNECT`, and `TRACE`. + +A path must start with `/` and be canonical. It can't contain a query string, a +fragment, percent-encoding, control characters, surrounding whitespace, +repeated or trailing slashes, or dot segments such as `.` and `..`. Each rule +takes one path. Repeating `--path` keeps only the last value, and a comma is +read as part of the path, so add a separate rule for each path: + +```console +$ sbx policy allow network api.github.com --method GET --path '/repos/**' +$ sbx policy allow network api.github.com --method GET --path '/users/**' +``` + +Hosts follow the same patterns as network rules and can include a port. Write +the host on its own, without a scheme, so an HTTP rule takes `api.example.com` +rather than `https://api.example.com`. + +A local HTTP rule takes a hostname. To match an IP address or a CIDR range, +add a plain network rule for that destination instead. + +Deny rules take the same flags, which is the usual way to carve a method or +path out of a broader allow: + +```console +$ sbx policy allow network api.example.com +$ sbx policy deny network api.example.com --method POST --path '/admin/**' +``` + +For how the two layers combine, see +[HTTP rules](../concepts.md#http-method-and-path). + +Remove an HTTP rule by naming the same qualifiers you added it with, or by +rule ID: + +```console +$ sbx policy rm network --resource api.github.com --method GET --path '/repos/org/project/**' +$ sbx policy rm network --id 7f3a1c2e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +List HTTP rules with `--type http`, or see them alongside network rules in a +wide listing, where the `METHOD` and `PATH` columns are empty for rules that +match a whole host: + +```console +$ sbx policy ls --wide +TYPE METHOD PATH +network - - +http GET /repos/org/project/** +``` + +> [!NOTE] +> `sbx policy check network` and `sbx policy log` don't evaluate or display +> HTTP methods and paths. A check reports the decision for the host, which can +> differ from the decision for a specific method and path on that host. + +## Inspecting rules + +To inspect which policies are active and where they come from, use +`sbx policy ls`. Use `--source` to filter by origin (`local`, `org`, `kit`), +`--decision` to filter by outcome (`allow`, `deny`), and `--wide` for +rule-level detail including rule IDs. To inspect a single policy or rule in +full, use `sbx policy inspect`. See +[Monitoring](../monitor-and-enforce/monitoring.md). + +### Allow outbound UDP + +Outbound UDP is experimental and disabled by default. Turn on experimental +features and UDP egress before adding UDP allow rules: + +```console +$ sbx settings set platform.allowExperimentalFeatures true +$ sbx settings set feature.udp-egress true +$ sbx policy allow network --protocol udp api.example.com:443 +``` + +Local allow rules apply to TCP by default. Use `--protocol udp` for UDP or +`--protocol tcp,udp` for both. Deny rules apply to both protocols by default. +Use `--protocol` to restrict a deny rule to one protocol. + +UDP follows the same organization and local policy precedence as TCP. It is +refused when the destination requires an HTTP, SOCKS5, system, or PAC-selected +proxy, because those proxies can't carry UDP. ICMP remains blocked. + +UDP to local-network destinations is blocked before any policy is evaluated, +so no allow rule can permit it, including one that allows all hosts. This +covers multicast, link-local, and unspecified addresses, `255.255.255.255`, +and the broadcast addresses of the host's networks. As a result, discovery +protocols that use multicast, such as mDNS and SSDP, don't work from a +sandbox. UDP to `host.docker.internal` isn't affected. The network log records +these connections under the rule `<udp local network boundary>`. + +Inspect UDP rules or check a destination: + +```console +$ sbx policy ls --protocol udp +$ sbx policy check network --protocol udp api.example.com:443 +``` + +The CLI warns if you save a UDP rule while UDP egress is disabled. + +## Testing policy + +Before running a sandbox, you can check whether the current policy would allow +a network request with `sbx policy check network`: + +```console +$ sbx policy check network api.anthropic.com +$ sbx policy check network blocked.example.com +``` + +The output reports `Allowed` or `Denied`, along with governance and context +details. A denied check returns a non-zero exit status. + +The target can be a hostname, a `host:port` pair, an IP address, or a URL. +Bare hostnames and IP addresses are evaluated against port 443. This is useful +for verifying custom rules or checking what the Locked Down preset blocks +before you start an agent. + +A check never creates an approval request. A destination that a sandbox would +ask you to approve shows as `Denied:`, with a `Reason:` line of +`no matching allow rule (default deny)`, or `approval required by policy` under +organization governance. + +To check policy in the context of a specific sandbox: + +```console +$ sbx policy check network --sandbox my-sandbox api.example.com +``` + +### Resetting + +To remove all custom rules and start fresh with a new preset, use +`sbx policy reset`: + +```console +$ sbx policy reset +``` + +This deletes the local policy store, restarts the daemon, and prompts you to +choose a new preset. Running sandboxes stop when the daemon shuts down. Pass +`--force` to skip the confirmation prompt: + +```console +$ sbx policy reset --force +``` + +## Troubleshooting + +### Local allow rules have no effect + +If rules you add with `sbx policy allow` don't change sandbox behavior, your +organization likely has governance enabled. Run `sbx policy ls` to check: if +the summary block contains `Governance: Managed by <org>`, +org governance is active. When it's active, local allow rules are inactive. +You can't use them to loosen restrictions the org policy imposes. + +Inactive allow rules are hidden from `sbx policy ls` by default; run +`sbx policy ls --include-inactive` to see them with an `inactive` status in +the `STATUS` column. + +When organization governance is active, only organization allow rules can grant +access. Ask your admin to update the organization policy if you need access to +an additional resource. Local deny rules remain active, so you can use +`sbx policy deny` to restrict access further. + +### A domain is still blocked after adding an allow rule + +If a domain remains blocked after you add a local allow rule, your organization +likely enforces governance, which makes local allow rules inactive. Run `sbx +policy ls` to check whether org governance is active; if the output starts with +a `Governance:` status line showing `Managed by <org>`, it is. Add +`--include-inactive` to confirm your rule shows an `inactive` status. If so, +the block can only be lifted by updating the org policy in Docker Home or via +the [API](/reference/api/ai-governance/). + +### An HTTP method or path is blocked on an allowed host + +A host that a network rule allows can still have individual methods or paths +denied by an HTTP rule. Run `sbx policy ls --type http` to see which HTTP rules +apply. `sbx policy check network` reports the decision for the host only, so it +shows a host as allowed even when the specific request is denied. See +[HTTP method and path rules](#http-method-and-path-rules). + +### A request is blocked with "Approval required" + +The destination needs your confirmation. Either no allow or deny rule matches +it and your machine isn't under organization governance, or an organization +policy allows it but requires approval first. + +Run `sbx policy approval ls` to see the pending request and respond to it with +`sbx policy approval respond`. Approving applies to later requests, not the one +that was blocked, so run the operation again afterward. See +[Respond to an approval request](network.md#respond-to-an-approval-request). diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md new file mode 100644 index 000000000000..07475cb8984d --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -0,0 +1,245 @@ +--- +title: MCP access policies +linkTitle: MCP access +weight: 50 +description: Use Cedar-based policies to control MCP server registration and activity routed through the Docker Sandboxes MCP gateway. +keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApproval, AI Governance +--- + +MCP access policies let organization administrators control which Model +Context Protocol (MCP) servers developers can register and what agents can do +through Docker's MCP gateway. Use these policies to approve trusted servers, +withdraw access to a server, require approval for tool calls, and restrict +host-run servers. To register MCP servers and connect them to sandboxes, see +[MCP gateway](../../mcp-gateway.md). + +MCP access policies apply only to server registration and requests handled by +Docker's MCP gateway. They don't govern an MCP server that an agent or MCP +client configures and connects to directly from inside the sandbox. A direct +connection to a remote MCP server is outbound sandbox traffic, so +[network access policy](network.md) determines whether the sandbox can reach +the server. To prevent access through both paths, block the server in MCP +access policy and block its network destination in network access policy. + +Unlike [network access policies](network.md) and +[filesystem access policies](filesystem.md), MCP policies are organization +policies written in Cedar. Docker defines the `MCP` namespace, including the +actions, resource types, attributes, and approval behavior that policies can +match. This page focuses on representative access patterns. For Docker's exact +policy surface, see the [MCP policy reference](../reference/mcp-policy.md). For +Cedar syntax and language semantics, see the +[Cedar documentation](https://docs.cedarpolicy.com/). + +## Govern the server lifecycle + +MCP policy applies at two points in a server's lifecycle. A rule for one point +doesn't automatically govern the other. + +| Admin decision | Evaluation point | Match with | +| ------------------------------------------ | ------------------------------------------- | -------------------------------------------------------------------------- | +| Whether a server can be registered | When a developer runs `sbx mcp add` | The registered name and resolved server attributes, such as `identityURL` | +| What agents can do through the MCP gateway | When the gateway handles a governed request | The registered server name, tool annotations, resource URI, or prompt name | + +Registration rules affect future registrations. They don't remove a saved +registration or prevent an existing registration from being loaded with +`sbx mcp load`. Use-time rules govern tool calls, resource reads, and prompt +retrieval from servers that are already registered or loaded. + +Server names are chosen during registration. Registration rules can match the +chosen name and resolved server identity together. At use time, tools, +resources, and prompts are associated with the registered name, so rules for an +existing server must match every name under which it was registered. + +Built-in gateway tools, such as `mcp-add`, `code-mode`, and OAuth authorization +helpers, are also governed at use time. They are `MCP::Primordial` resources +rather than tools associated with a registered server. For details, see +[Built-in gateway tools](../../mcp-gateway.md#built-in-gateway-tools). + +Use-time policy doesn't hide or remove existing registrations. Tool and +resource listings can also include entries that policy denies when an agent +tries to use them. + +## Choose an access posture + +When MCP policy enforcement is active for a user, registration and governed MCP +requests are denied unless a matching `permit` allows them. A matching `forbid` +overrides any `permit`, including a permit with `@requireApproval`. + +Use permits for an allowlist policy. For a blocklist policy that grants MCP +activity except for explicit restrictions, start with an actionless permit: + +```plaintext +permit (principal, action, resource); +``` + +This statement permits every MCP action that reaches Cedar evaluation. Add +`forbid` statements for the restrictions the policy must enforce. + +Policy scope supplies the principal. Use organization or team scope instead of +matching users, teams, tenants, or roles in Cedar. If MCP policy enforcement +isn't active for a user, the gateway doesn't evaluate Cedar policy and permits +MCP activity. MCP doesn't have a local preset equivalent to network policy. + +## Approve a server + +For an allowlist, approve both the server registration and its use-time +capabilities. The following policy approves a remote server only when it is +registered as `example` with the expected identity URL. It permits read-only +tool calls, resource reads, and prompt retrieval from that registered server: + +```plaintext +// Permit registration with the expected name and identity URL. +permit (principal, action == MCP::Action::"register", resource) +when { + resource in MCP::Server::"example" && + resource.identityURL == "https://mcp.example.com/mcp" +}; + +// Permit read-only tool calls. +permit (principal, action == MCP::Action::"invokeTool", resource) +when { + resource in MCP::Server::"example" && + resource.readOnly == true +}; + +// Permit resource reads. +permit (principal, action == MCP::Action::"readResource", resource) +when { resource in MCP::Server::"example" }; + +// Permit prompt retrieval. +permit (principal, action == MCP::Action::"getPrompt", resource) +when { resource in MCP::Server::"example" }; +``` + +Matching both the name and identity URL establishes a canonical registration. +It prevents a developer from registering another endpoint under the approved +name or registering the approved endpoint under another name. Remove the +resource or prompt permit if users don't need that capability. + +## Require confirmation with MCP elicitation + +Use `@requireApproval` to require per-request confirmation through MCP. When a +request matches the annotated `permit`, the gateway sends an +`elicitation/create` request to the same MCP client session that made the +governed request. In a human-driven client, the person operating the agent sees +the prompt and decides whether to proceed. + +The following policy requires confirmation for non-read-only tools on a server +registered as `example`. Use it alongside any permits needed to register the +server or use its other capabilities. The annotation string becomes the reason +shown in the elicitation: + +```plaintext +@requireApproval("non-read-only tool call") +permit (principal, action == MCP::Action::"invokeTool", resource) +when { + resource in MCP::Server::"example" && + resource.readOnly == false +}; +``` + +Tool annotations are supplied by the server and are advisory. `readOnly` +defaults to `false` for tools that don't declare it, so this pattern requires +confirmation for unannotated tools. + +The gateway handles a matching request as follows: + +```mermaid +flowchart TD + request["Agent sends a governed MCP request"] --> evaluate["Gateway evaluates MCP policy"] + evaluate -->|"Normal permit"| forward["Forward request"] + evaluate -->|"No permit or matching forbid"| deny["Deny request"] + evaluate -->|"Permit with @requireApproval"| elicit["Send MCP elicitation to connected client"] + elicit --> confirm{"Client returns explicit confirmation?"} + confirm -->|"No, unsupported, or error"| deny + confirm -->|"Yes"| reevaluate["Re-evaluate with approval digest"] + reevaluate -->|"Allowed"| forward + reevaluate -->|"Denied or changed"| deny +``` + +The prompt identifies the server or gateway tool and includes the annotation +reason. It doesn't include raw tool arguments. Each matching request requires a +new confirmation. After confirmation, the gateway re-evaluates the request with +a digest that binds the response to the evaluated authorization request. + +Use this mechanism as a confirmation guardrail for human-driven clients. It +doesn't create administrator approval or separation of duties. An autonomous +MCP client can respond to an in-protocol elicitation programmatically. Use +`forbid` for operations that must never run. + +The request is denied if the originating client session can't handle MCP +elicitation, the user declines, the elicitation fails, or re-evaluation doesn't +allow the request. `sbx mcp add` can't present an elicitation, so a registration +permit with `@requireApproval` results in a denial. Tool calls made from an +execution context that can't relay an elicitation, including calls from inside +`code-mode`, are also denied. + +## Withdraw server access + +To withdraw access from a server that broader rules permit, block it at +registration and at use time. Registration policy controls future `sbx mcp add` +operations, while use-time policy controls requests from servers that are +already registered or loaded. + +Prevent future registrations of the server by matching its identity URL: + +```plaintext +forbid (principal, action == MCP::Action::"register", resource) +when { resource.identityURL == "https://mcp.example.com/mcp" }; +``` + +Deny use-time requests for each registered name that refers to the server: + +```plaintext +forbid (principal, action == MCP::Action::"invokeTool", resource) +when { resource in MCP::Server::"example" }; + +forbid (principal, action == MCP::Action::"readResource", resource) +when { resource in MCP::Server::"example" }; + +forbid (principal, action == MCP::Action::"getPrompt", resource) +when { resource in MCP::Server::"example" }; +``` + +The registration remains saved and can still be listed or loaded. These rules +prevent another registration for the identity URL and deny governed use under +the registered name. If the server was registered under other names, add +use-time rules for those names as well. + +An OAuth authorization helper is a built-in gateway tool, not a child of the +registered server. To prevent agents from starting authorization for the +server, govern the helper separately: + +```plaintext +forbid (principal, action == MCP::Action::"invokePrimordial", resource) +when { resource in MCP::Primordial::"example-authorize" }; +``` + +## Restrict host-run servers + +Local stdio servers run on the host, outside the sandbox VM. This includes +explicit host commands and OCI-packaged stdio servers started with host Docker. +For details about this boundary, see +[Docker Engine isolation](../../security/isolation.md#docker-engine-isolation). + +In a blocklist policy that otherwise permits registration, deny the host-run +server type: + +```plaintext +forbid (principal, action == MCP::Action::"register", resource) +when { resource.type == "local-stdio" }; +``` + +`local-stdio` covers explicit commands, including commands that start a Docker +container, and OCI-packaged stdio servers resolved from registry or manifest +metadata with `--local`. + +## Related information + +- [MCP policy concepts](../concepts.md#mcp-policies): policy model and rule + evaluation. +- [MCP policy reference](../reference/mcp-policy.md): exact action, resource, + attribute, context, and approval behavior. +- [Organization policies](organization.md): policy creation and scope. +- [MCP policy audit logs](../audit/): policy decision + records. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md new file mode 100644 index 000000000000..b4a1c6c06320 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -0,0 +1,204 @@ +--- +title: Network access policies +linkTitle: Network access +weight: 30 +description: Control outbound network access from Docker Sandboxes with local and organization policy rules. +keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy +--- + +The governance described here applies to local sandboxes. Cloud sandboxes +use separate network policy configuration. See +[Cloud network policy](../../cloud/network-policy.md) for cloud controls. + +Network access policies control outbound connections from sandboxes. Each +policy contains one or more rules that allow the domains, IP ranges, and ports a +workflow needs, or block destinations that should stay unavailable. Rules can +also match the HTTP method and path of a request, so a policy can allow part of +an API without allowing all of it. + +You can configure network access in two places: + +- [Local policy](local.md), which applies to sandboxes on one developer machine + when organization governance is not active. +- [Organization policies](organization.md), which apply centrally across an + organization or to selected teams. + +When organization governance is active, only organization allow rules grant +network access. Local allow rules are inactive until organization governance no +longer applies, while local deny rules still apply on top of the organization +policy. See [Precedence](../concepts.md#precedence). + +## Rule syntax + +Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are +hostnames, CIDR ranges, ports, or hostnames with ports. UDP requires +[experimental outbound UDP](local.md#allow-outbound-udp). ICMP is blocked. + +Examples: + +- `api.example.com` +- `*.example.com` +- `**.example.com` +- `example.com:443` +- `10.0.0.0/8` + +For exact wildcard behavior and CIDR support, see +[Network rules](../concepts.md#network-rules). + +## HTTP method and path rules + +A network rule matches a destination, so it allows or blocks everything a +sandbox sends there. An HTTP rule narrows the match to specific HTTP methods +and URL paths on that destination, which lets a policy allow reads from an API +without allowing writes to it. + +HTTP rules layer on top of network rules. A network allow is the baseline for +a destination and HTTP rules carve into it, while a network deny blocks the +destination outright and no HTTP allow can reopen it. For the pattern syntax +and the full matching table, see +[HTTP rules](../concepts.md#http-method-and-path). + +Configure them in either place: + +- Organization policies, in the network rule composer in Docker Home. Set the + rule **Type** to **HTTP**, then select the methods and path patterns. See + [Add a network rule](organization.md#add-a-network-rule). +- Local policies, with `--method` and `--path` on `sbx policy`. See + [HTTP method and path rules](local.md#http-method-and-path-rules). + +## Local network rules + +Use `sbx policy allow network` and `sbx policy deny network` to manage local +network rules: + +```console +$ sbx policy allow network api.example.com +$ sbx policy deny network ads.example.com +``` + +For presets, sandbox-scoped rules, testing, and troubleshooting, see +[Local policy](local.md). + +## Organization network rules + +Organization network rules belong to policies that can apply to the whole +organization or to selected teams. For setup steps and team scoping, see +[Organization policies](organization.md). + +Use [Monitoring policies](../monitor-and-enforce/monitoring.md) to inspect +which network rules are active on a developer machine. + +## Approval-required access + +An organization network policy can require approval instead of granting access +outright. Destinations the policy allows aren't reachable until the developer +confirms them, which keeps an allowlist broad enough to be usable while still +putting a person in front of each destination an agent reaches for. + +Without organization governance, a request with no matching allow or deny rule +also asks for approval rather than being denied outright, so access opens up as +the developer approves each destination. + +Under organization governance, approval is a property of the policy rather +than of individual rules, so turning it on applies it to every allow rule in +that policy. A destination stays directly reachable only when no policy that +allows it requires approval. If a policy that requires approval also matches, +the request needs approval regardless of what the other policies allow. + +Only a destination the developer has already approved satisfies the +requirement. Preset rules, +[kit-defined rules](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md), +and rules the developer added with `sbx policy allow network` don't answer it. +An approval also can't reach a destination the organization doesn't allow at +all, and it can't override a deny rule. To withdraw a destination, add a deny +rule, which takes precedence over any approval already recorded. + +To require approval on an organization policy, see +[Organization policies](organization.md#require-approval-for-a-network-policy). + +### Respond to an approval request + +When a destination needs approval, a sandbox can't reach it until you confirm +it. The request is blocked and the sandbox receives a message naming the +destination: + +```plaintext +Approval required for api.example.com. + +Review and respond with: + sbx policy approval ls +``` + +If your organization +[configures a support message](organization.md#configure-a-support-message), it +appears after the approval instructions. + +The request that triggers the prompt doesn't wait for an answer. It's denied, +and approving the destination affects later requests. Agents that retry a +failed request pick up the new access on their next attempt. For others, run +the operation again. + +List the destinations waiting for a response: + +```console +$ sbx policy approval ls +APPROVAL SANDBOX TITLE DETAIL OPTIONS +network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY my-sandbox api.example.com:443 Protocol: TCP Resource type: domain approval required by policy "default network" allow (Allow), dismiss (Dismiss) +``` + +Each entry names the destination, the sandbox that asked for it, and why it +needs approval. Under organization governance that reason names the policy, as +shown. Without it, the reason is that no matching allow rule covers the +destination. A request that an HTTP rule matches also shows the method and +path, such as `GET api.example.com:443/v1/data`. + +To inspect a single entry, pass its ID to `sbx policy approval inspect`: + +```console +$ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY +``` + +Respond by selecting one of the options the entry offers: + +```console +$ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY --option allow +``` + +Choosing `allow` grants access to that destination. Choosing `dismiss` leaves +it blocked, and the destination is requested again the next time the sandbox +tries to reach it. Repeated attempts collapse into a single entry, so a sandbox +retrying in a loop leaves one request to answer, not a queue of duplicates. + +#### What approving grants + +Approving records a rule that allows the destination the sandbox actually +asked for, scoped to the sandbox that asked. Three things follow from that: + +- The rule covers one destination, not the pattern the policy rule used. A + policy that allows `*.example.com` with approval asks about + `api.example.com` and `cdn.example.com` separately. +- A destination includes its port, so `api.example.com:443` and + `api.example.com:8443` are approved separately. +- Another sandbox reaching the same destination asks again. + +When an [HTTP rule](../concepts.md#http-method-and-path) in the policy matches +the request, approving covers the method and exact path the sandbox requested +rather than the whole destination. `GET /v1/data` and `POST /v1/data` on the +same host are approved separately. A request whose method or path can't be +recorded as a rule, such as a path with percent-encoding, is blocked without an +entry to respond to. + +Approved destinations stay allowed until the rule is removed. List them with +`sbx policy ls --wide --created-via approval`, and remove one the same way as +any other local rule, with [`sbx policy rm network`](local.md#managing-rules). + +Approvals live in the local policy store, so [`sbx policy reset`](local.md#resetting) +removes all of them along with your other local rules. Each destination is +requested again the next time a sandbox reaches it. + +> [!NOTE] +> To manage Model Context Protocol (MCP) server registration and requests +> through Docker's MCP gateway, use [MCP access policies](mcp.md). These +> policies apply only to the gateway. Direct MCP connections from a sandbox +> don't use the gateway, but you can control access to remote MCP servers with +> network policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md new file mode 100644 index 000000000000..d38d08507ba4 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -0,0 +1,245 @@ +--- +title: Organization policies +linkTitle: Org policies +weight: 20 +description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. +keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy +aliases: + - /ai/sandboxes/security/governance/ + - /ai/sandboxes/governance/org/ +--- + +The governance described here applies to local sandboxes. Cloud sandboxes +use separate network policy configuration. See +[Cloud network policy](../../cloud/network-policy.md) for cloud controls. + +[Local policies](local.md) give individual developers control over what their +sandboxes can access. Organization policy moves that control to the admin level: +organization policies apply to local sandboxes across the organization, either to +every member or to specific teams. When organization governance is active, only +organization allow rules grant access: local `sbx policy` allow rules are no +longer evaluated and can't expand what the organization permits. Local network +deny rules remain active, so developers can restrict access further but never +loosen it. + +Admins can manage organization policies through the Docker Home UI. For +programmatic management of network and filesystem policies, use the +[Governance API](/reference/api/ai-governance/). + +By default, only organization +[owners](/manuals/security/roles-and-permissions/core-roles.md) can +view and manage AI Governance policies. To let someone other than an owner +manage policies, create a +[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) +with the **Governance** permissions and assign it to a user or team. + +> [!NOTE] +> Sandbox organization governance is available on a separate paid +> subscription. +> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +> to request access. + +## Create a policy + +Manage policies from the **AI Platform** section in the left-hand navigation +of [Docker Home](https://app.docker.com). + +To create a policy: + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. In the left-hand navigation, expand **AI Platform** and select + **Network access**, **Filesystem access**, or **MCP access**. +1. Select **Create policy**. +1. Enter a **Policy name**. +1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, + choose the teams the policy applies to. See + [Scope policies to teams](#scope-policies-to-teams). +1. Define the policy rules. + - Network and filesystem policies: select **Add rule** for each rule. For a + network policy, see [Add a network rule](#add-a-network-rule). + - MCP policies: enter Cedar statements in the policy editor. See + [MCP access policies](mcp.md). +1. For a network policy, set **Require approval before access** if developers + should confirm each destination before a sandbox can reach it. See + [Require approval for a network policy](#require-approval-for-a-network-policy). + +Existing policies are listed with their name, scope, rule count, and last +update. Use the action menu (⋮) to edit or delete a policy. + +### Add a network rule + +Each rule has an optional **Rule name**, a **Type** that decides what the rule +matches, and a **Decision** of **Allow** or **Deny**. + +- **HTTP** matches only HTTP requests with the methods and paths you specify. + - In **Destination**, enter the host or IP address the rule covers. It + matches any port unless you add one. Enter the destination with no scheme + and no path, so `api.github.com` rather than + `https://api.github.com/repos`. A local HTTP rule accepts only a host. + - Under **HTTP methods**, select the methods the rule applies to. Use + **Select all** to select every method, or **Read-only** to select `GET`, + `HEAD`, and `OPTIONS`. A rule saved with no methods selected matches every + method the composer lists. The composer doesn't list `CONNECT` or + `TRACE`, which differs from the CLI, where `--method ANY` matches every + HTTP method. + - Under **Path patterns**, add one or more paths the rule covers, such as + `/repos/*` and `/v1/**`. Leave it empty to match any path. +- **All traffic** matches every request to the destinations you list, on any + port, method, and path. + - Under **Protocols**, select **TCP**, **UDP**, or **Both**. + - Under **Destinations**, add the hosts, IP addresses, or CIDR ranges the + rule covers. A destination matches any port unless you add one, such as + `example.com:8080`. + +An HTTP rule's paths all belong to its one destination, so to cover paths on a +second host, add a second rule. For the pattern syntax and how HTTP rules +combine with **All traffic** rules, see +[HTTP rules](../concepts.md#http-method-and-path). + +### Require approval for a network policy + +Turning on **Require approval before access** means the destinations a network +policy allows aren't reachable until the developer confirms each one. For how +approval behaves and what satisfies it, see +[Approval-required access](network.md#approval-required-access). + +To set it on an existing policy: + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. In the left-hand navigation, expand **AI Platform** and select + **Network access**. +1. In the policy list, open the policy's action menu (⋮) and select **Edit**. +1. Turn on **Require approval before access**. +1. Select **Save**. + +The policy's detail page reports approval as **Required** or **Not required**. +Editing a policy replaces it in full, so turning the setting off removes the +requirement from every rule in that policy. + +## Configure a support message + +Admins can add an optional support message that appears after the policy denial +details when a sandbox action is blocked by organization governance. Use it to +point members to an internal support channel, ticket queue, or security contact. + +To set the message: + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. In the left-hand navigation, expand **AI Platform** and select **Manage**. +1. In **Support message**, enter up to 500 characters. +1. Select **Save changes**. + +Docker shows the message only for denials caused by organization governance +policy and for requests an +[approval-required policy](network.md#approval-required-access) blocks. If you +leave it blank, Docker shows the policy denial without additional contact text. + +## Choose a policy type + +Organization policies are managed by access surface. Use the access-control +pages for syntax, examples, and enforcement details: + +- [Network access policies](network.md): control outbound network access from + sandboxes, by host or by HTTP method and path. +- [Filesystem access policies](filesystem.md): control which host paths + sandboxes can mount as workspaces. +- [MCP access policies](mcp.md): control MCP server registration, tool calls, + resources, prompts, and approval gates with Cedar policy. + +When organization governance is active, local and kit-defined allow rules are +not evaluated, while deny rules from those sources still apply. See +[Precedence](../concepts.md#precedence). To see which rules are active on a +developer machine, use +[Monitoring policies](../monitor-and-enforce/monitoring.md). + +## Scope policies to teams + +An organization can have more than one policy, and each policy applies either +to the whole organization or to specific teams. Scoping lets you apply different +rules to different parts of the organization. + +A policy's [**Scope**](#create-a-policy) controls who it applies to. Set it to +**Organization** to apply the policy to every member, or to **Teams** to apply +it only to members of the teams you select. + +### Before you start + +Team scoping targets your organization's existing +[teams](/manuals/accounts/organization/manage/manage-a-team.md), so a team must +exist before you can scope a policy to it. Create teams and manage their members +in one of two ways: + +- Manually, in Docker Home. +- Automatically, by using + [group mapping](/manuals/security/provisioning/scim/group-mapping.md) + to synchronize your identity provider's groups with the teams in your + organization. Group mapping creates teams that don't already exist and keeps + their membership in step with your IdP groups. + +Because policies apply by team, a user's policies update automatically as their +team membership changes, including changes synced from your IdP. + +### How scoped policies combine + +A user is governed by all of their +[effective policies](../concepts.md#policy-scope): every org-wide policy, plus +the team-scoped policies for the teams they belong to. Use org-wide policies +for guardrails that must apply everywhere, and team-scoped policies for access +that only some teams need. + +For precedence between local and organization policies, and for how allow and +deny rules combine, see [Policy concepts](../concepts.md). + +## Troubleshooting + +### Policy changes not taking effect + +After updating organization policies, changes take up to 5 minutes to +propagate to developer machines. To apply changes immediately, users can run +`sbx policy reset`, which stops the daemon and forces it to pull the latest +organization policies on the next `sbx` command. + +> [!WARNING] +> `sbx policy reset` deletes all locally configured policy rules, including any +> destinations the developer has approved under an +> [approval-required policy](network.md#approval-required-access). Those +> destinations are requested again the next time a sandbox reaches them. The +> command prompts for confirmation before proceeding. + +#### Enforcement timing by policy type + +Policy types differ in when a change takes effect after it reaches the +developer machine: + +- Network policy is evaluated on every outbound request. Once a policy + change has synced to the developer's machine (up to 5 minutes), it applies + immediately to subsequent requests. HTTP rules are evaluated per request in + the same way. + +- An approval requirement applies from the point the policy change syncs. + Destinations a developer already approved stay reachable, because the + approval is recorded on the developer's machine. To withdraw one, add a deny + rule. A deny takes precedence over a recorded approval. + +- Filesystem policy is only checked when a workspace is mounted — that + is, when a sandbox is created. Once a sandbox is running, changing the + filesystem policy has no effect on that sandbox. The sandbox continues to + access the previously allowed path until it is removed and a new one is + created. + +- MCP registration policy is evaluated when a server is registered with + `sbx mcp add`. Changing registration rules doesn't remove existing + registrations or stop an already-loaded server by itself. + +- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a + governed MCP request, such as a tool call, resource read, prompt retrieval, + or built-in gateway tool call. Once a policy change has synced, use-time + rules apply to subsequent governed MCP requests through the gateway. + +To apply a filesystem policy change immediately, remove the running sandbox +and create a new one. To prevent use of an MCP server that is already registered +or loaded, add use-time rules for the registered server name. For examples, see +[Withdraw server access](mcp.md#withdraw-server-access). diff --git a/content/manuals/ai/sandboxes/governance/api.md b/content/manuals/ai/sandboxes/governance/api.md deleted file mode 100644 index dcbb778b8aee..000000000000 --- a/content/manuals/ai/sandboxes/governance/api.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: AI Governance API -linkTitle: API reference -description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON. -weight: 30 -build: - render: never -sidebar: - goto: /reference/api/ai-governance/ ---- diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md deleted file mode 100644 index fcf2a4d24c98..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Audit logging -linkTitle: Audit logs -weight: 28 -description: Capture a structured, durable record of every sandbox policy decision for SIEM ingestion and compliance. -keywords: docker sandboxes, audit log, audit logging, policy decision, SIEM, compliance, jsonl, splunk, filebeat ---- - -The sandbox daemon records a structured audit event for every policy decision -it makes. Each record captures who triggered the evaluation, when it happened, -which rule matched, and whether the resource was allowed or denied. Records are -written to disk as JSON Lines (`.jsonl`) so existing SIEM and log-shipping -tools can collect them. The records stay on the machine that produced them. -Docker doesn't collect or ingest audit data. - -> [!NOTE] -> Audit logging is part of Docker AI Governance and requires a separate paid -> subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. - -Audit logging is active only while your organization enforces a centralized -governance policy. The subscription alone doesn't produce records. If your -organization hasn't configured and enforced an [organization policy](org.md), -the daemon writes no audit logs. To confirm governance is active, run `sbx -policy ls` — the output begins with a `Governance: managed by <org>` header -when an organization policy is in effect. - -Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx -policy ls` and `sbx policy log` is for live, interactive debugging. Audit -logging produces a durable trail for security review and compliance. - -## What gets recorded - -The daemon writes two categories of record: - -- Evaluation records capture each policy decision: the resource, the - action, the verdict, and the reason for a denial. -- Session lifecycle records mark the start and end of each daemon run. - Evaluation records share the run's `audit_session_id`, so you can correlate - every decision back to a single daemon session. - -A network evaluation record looks like this: - -```json -{ - "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", - "timestamp": "2026-05-28T19:15:00.728933Z", - "schema_version": "1.82.0", - "category": "AUDIT_CATEGORY_EVALUATION", - "decision": "AUDIT_DECISION_DENY", - "username": "jordandoe", - "user_email": "jordandoe@example.com", - "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", - "org_name": "Acme Inc", - "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", - "resource_id": "example.com:443", - "os": "macos", - "app_version": "v0.31.0", - "client_name": "sbx", - "hostname": "host-machine", - "deny_reason": [ - "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" - ], - "action_type": "network_egress", - "network_egress": { "protocol": "tcp" } -} -``` - -Common fields include: - -| Field | Description | -| ------------------ | ------------------------------------------------------------------------------------------------------------ | -| `timestamp` | UTC time of the decision. | -| `schema_version` | Version of the record schema. Pin your SIEM field mappings to it, as the format is a stable contract. | -| `category` | `AUDIT_CATEGORY_EVALUATION` for policy decisions, `AUDIT_CATEGORY_MANAGEMENT` for session lifecycle records. | -| `audit_session_id` | Identifies the daemon run that produced the record. | -| `username` | The signed-in Docker user's Docker Hub username. | -| `user_email` | The signed-in Docker user's email address. | -| `org_id` | ID of the organization whose governance policy is in effect. | -| `org_name` | Display name of the organization whose governance policy is in effect. | -| `action_type` | The kind of access evaluated, such as `network_egress`. | -| `resource_id` | The target of the evaluation, such as a host and port. | -| `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | -| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | - -Each record is attributed to the signed-in Docker user and the organization -whose governance policy is in effect. - -## Where records are stored - -The daemon writes audit records, not the CLI. Running a command such as `sbx -create` sends a request to the daemon, and the daemon emits the resulting -record to its own audit directory. - -The default location depends on your operating system: - -| OS | Default path | -| ------- | ----------------------------------------------------------------- | -| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | -| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | -| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` | - -The directory layout differs by platform because each operating system places -application logs in its own conventional location. - -Files are named `audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl`. - -The daemon writes in-progress records to a temporary `.tmp` file and seals it -into a final `.jsonl` file by atomic rename. Sealing happens at a rotation -threshold (by default 5 minutes, 1000 events, or 50 MiB, whichever comes -first) or when the daemon shuts down cleanly. Only sealed `.jsonl` files are -complete. Treat `.tmp` files as incomplete and don't collect them. - -Sandboxes never delete sealed files. Retention and cleanup are the -responsibility of your log shipper or your own housekeeping. - -## Collect records with a SIEM - -Point your log shipper at the audit directory and configure it to collect -sealed `.jsonl` files only. Tools such as the Splunk Universal Forwarder, -Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each -line as an event. Because in-progress records live in `.tmp` files until they -are sealed, collectors never see partial records. diff --git a/content/manuals/ai/sandboxes/governance/audit/_index.md b/content/manuals/ai/sandboxes/governance/audit/_index.md new file mode 100644 index 000000000000..bff10587de80 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/_index.md @@ -0,0 +1,88 @@ +--- +title: AI Governance Audit Logs +linkTitle: Audit logs +weight: 30 +description: Capture, view, export, and collect structured audit records for Docker AI Governance policy decisions. +keywords: docker sandboxes, audit log, audit logging, AI Governance, policy decision, SIEM, compliance, jsonl +--- + +{{< summary-bar feature_name="AI Governance Audit Logs" >}} + +The Docker Sandboxes coverage on this page applies to local sandboxes. +Docker Cloud delivery stores their audit records in the cloud; it does not add +cloud sandbox coverage. For cloud network decisions, see +[Cloud policy logs](../../cloud/network-policy.md#inspect-network-policy). + +AI Governance Audit Logs record Docker AI Governance activity for your +organization. Each record captures the principal, action, target, decision, and +time for a governance event. Records contain metadata only. They don't contain +prompt content, agent output, or parameter values. + +Audit logs are exposed when AI Governance is enabled for your organization. +Docker Sandboxes send audit records only for signed-in users who have an AI +Governance license and are governed by an enforced centralized [organization +policy](../access-controls/organization.md). Docker Sandboxes users without both +don't send audit data to audit logs. + +> [!NOTE] +> AI Governance Audit Logs are part of Docker AI Governance and require a +> separate paid subscription. +> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +> to request access. + +## Requirements + +To use AI Governance Audit Logs, your organization needs: + +- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md) +- An enforced organization governance policy +- A Docker organization account +- An organization owner, or a user with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions, to configure delivery and view hosted events + +> [!NOTE] +> Other Docker subscriptions are not sufficient on their own to use AI Governance +> Audit Logs. Users without an AI Governance license and an enforced organization +> policy will not generate audit data and will not appear in audit events or SIEM +> forwarding output. Personal accounts are not supported. + +## Coverage + +AI Governance Audit Logs cover Docker Sandboxes policy decisions and sandbox +session events. Other Docker AI sources can emit records through the same schema +as they become available. + +## Delivery modes + +Docker supports two delivery modes for audit records: + +- **Local disk**: the sandbox daemon writes JSON Lines (`.jsonl`) + files on each host. Use this mode for host-local retention, air-gapped + collection, or collection through your own log shipper. +- **Docker Cloud**: Docker stores audit records in Docker Cloud. Cloud + delivery powers the hosted audit log view, CSV export, and SIEM streaming from + app.docker.com. Cloud delivery is on by default when AI Governance is enabled. + Organization owners can disable it in [audit delivery settings](configure.md). + +Organization owners and users with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions can configure local disk, Docker Cloud, or both. + +The hosted audit log view, CSV export, and SIEM forwarding all require Docker Cloud delivery to be enabled. Local delivery alone does not power these features. + +Organizations that used local audit logging before hosted audit logs were +available start with cloud delivery off until an owner opts in from +[audit delivery settings](configure.md). + +## Data handling + +When Docker Cloud delivery is enabled, Docker stores audit records in Docker +Cloud for the retention window configured by your organization. For legal and +privacy terms that govern Docker services, see Docker's [Terms of +Service](https://www.docker.com/legal/docker-terms-service/) and [Privacy +Policy](https://www.docker.com/legal/privacy/). + +## Learn more + +- [Local audit logs](local.md) +- [Configure audit delivery](configure.md) +- [View and export audit events](view-export.md) +- [SIEM forwarding](siem.md) +- [Audit record reference](record-reference.md) diff --git a/content/manuals/ai/sandboxes/governance/audit/configure.md b/content/manuals/ai/sandboxes/governance/audit/configure.md new file mode 100644 index 000000000000..5afa22949ab6 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/configure.md @@ -0,0 +1,73 @@ +--- +title: Configure audit delivery +linkTitle: Configure delivery +weight: 20 +description: Configure local and cloud delivery, retention, and history for Docker AI Governance Audit Logs. +keywords: docker sandboxes, audit delivery, AI Governance, audit logs, retention, cloud delivery, AI Platform +--- + +Organization owners and users with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions can configure where Docker writes audit events. +Two delivery destinations are available and can be used independently or +together: + +- **Local disk**: The sandbox daemon writes audit events to the local disk + on each host. +- **Docker Cloud**: Audit events are sent to Docker's cloud platform, enabling + the hosted log view, CSV export, and SIEM forwarding. + +## Before you begin + +Your organization needs: + +- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md) +- An enforced organization governance policy +- Organization owner access, or a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) with AI Governance audit permissions + +Only users who have an AI Governance license and are governed by the enforced +organization policy send Docker Sandboxes audit data. + +## Configure delivery + +To configure audit delivery: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Open your organization. +3. Go to **AI Platform** > **Audit logs**. +4. Open **Audit Delivery**. +5. Choose one or both delivery modes: + - **Local disk** writes audit records to JSON Lines files on each host. + - **Docker Cloud** stores audit records in Docker Cloud for hosted search, + CSV export, and SIEM forwarding. +6. Save your changes. + +Cloud delivery is on by default when AI Governance is enabled. To keep records +local to your hosts, turn off **Docker Cloud** and keep **Local disk** on. + +Organizations that used local audit logging before hosted audit logs were +available start with cloud delivery off until an owner opts in. + +## Configure retention + +When **Docker Cloud** is selected, you can also configure how long cloud-stored +events are retained: + +| Field | Description | Default | +| ------------------------------ | ------------------------------------------------------------------ | ------- | +| Searchable retention (days) | How long events stay searchable in the hosted audit log view. | 90 days | +| Archive retention (days) | How long events are kept in long-term archive storage. | 90 days | + +Archive retention must be greater than or equal to searchable retention. + +Retention reductions apply going forward. They don't delete records that were +already retained under a longer retention window. + +## Audit delivery change history + +Docker keeps a record of every change made to your organization's audit delivery +settings. Each entry captures the timestamp, the user who made the change, and +the delivery configuration that was set. Use this history to audit configuration +changes and verify when delivery modes or retention windows were modified. + +Open **History** to review delivery and retention changes for your organization. +History entries show who made the change, when it happened, and the before and +after values. diff --git a/content/manuals/ai/sandboxes/governance/audit/local.md b/content/manuals/ai/sandboxes/governance/audit/local.md new file mode 100644 index 000000000000..0e1931fe9272 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/local.md @@ -0,0 +1,99 @@ +--- +title: Local audit logs +linkTitle: Local audit logs +weight: 10 +description: Collect Docker AI Governance audit records from local JSON Lines files written by the sandbox daemon. +keywords: docker sandboxes, audit log, local audit logs, audit logging, jsonl, SIEM, splunk, filebeat +--- + +The sandbox daemon writes local audit records as JSON Lines (`.jsonl`) files. +Local audit logs stay on the host that produced them and can be collected by +your own log shipper. Local delivery is independent of +[cloud delivery](configure.md), so you can use local files with cloud delivery +on or off. + +The sandbox daemon writes local audit records only for signed-in users who have +an AI Governance license and are governed by an enforced centralized +[organization policy](../access-controls/organization.md). Docker Sandboxes +users without both do not send audit data to audit logs. To confirm governance +is active, run `sbx policy ls`. The output includes a `Governance: Managed by +<org>` line when an organization policy is in effect. + +## What gets recorded + +The daemon writes two categories of local record: + +- Evaluation records capture each policy decision: the resource, the action, + the verdict, and the reason for a denial. +- Session lifecycle records mark the start and end of each daemon run. + Evaluation records share the run's `audit_session_id`, so you can correlate + every decision back to a daemon session. + +Records contain metadata only. They don't contain prompt content, agent output, +or parameter values. For field details, see +[Audit record reference](record-reference.md). + +A network evaluation record looks like this: + +```json +{ + "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", + "timestamp": "2026-05-28T19:15:00.728933Z", + "schema_version": "1.82.0", + "category": "AUDIT_CATEGORY_EVALUATION", + "decision": "AUDIT_DECISION_DENY", + "username": "jordandoe", + "user_email": "jordandoe@example.com", + "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", + "org_name": "Acme Inc", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "resource_id": "example.com:443", + "os": "macos", + "app_version": "v0.31.0", + "client_name": "sbx", + "hostname": "host-machine", + "deny_reason": [ + "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" + ], + "action_type": "network_egress", + "network_egress": { "protocol": "tcp" }, + "agent": "claude" +} +``` + +## Where records are stored + +The daemon writes audit records, not the CLI. Running a command such as +`sbx create` sends a request to the daemon, and the daemon emits the resulting +record to its own audit directory. + +The default location depends on your operating system: + +| OS | Default path | +| ------- | ----------------------------------------------------------------- | +| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | +| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | +| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` | + +The directory layout differs by platform because each operating system places +application logs in its own conventional location. + +Files are named `audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl`. + +The daemon writes in-progress records to a temporary `.tmp` file and +finalizes it into a `.jsonl` file by atomic rename. Finalization happens at a +rotation threshold: by default, 5 minutes, 1000 events, or 50 MiB, whichever +comes first. Finalization also happens when the daemon shuts down cleanly. Only +`.jsonl` files are complete. Treat `.tmp` files as incomplete and don't collect +them. + +Sandboxes never delete `.jsonl` files. Retention and cleanup are the +responsibility of your log shipper or your own housekeeping. + +## Collect records with a SIEM + +Point your log shipper at the audit directory and configure it to collect +`.jsonl` files only. Tools such as the Splunk Universal Forwarder, +Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each +line as an event. Because in-progress records live in `.tmp` files until they +are finalized, collectors never see partial records. diff --git a/content/manuals/ai/sandboxes/governance/audit/record-reference.md b/content/manuals/ai/sandboxes/governance/audit/record-reference.md new file mode 100644 index 000000000000..ce547f4e7eef --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/record-reference.md @@ -0,0 +1,204 @@ +--- +title: Audit record reference +linkTitle: Record reference +weight: 50 +description: Reference fields, categories, decisions, and payload types for Docker AI Governance audit records. +keywords: docker sandboxes, audit record, audit schema, AI Governance, policy decision, action_type, jsonl +--- + +Docker AI Governance audit records use one schema across delivery modes. Local +JSON Lines files and cloud-delivered records contain the same metadata fields. + +Records capture metadata only. They don't contain prompt content, agent output, +or parameter values. Parameter keys may appear when they help identify an +action. + +## Common fields + +| Field | Description | +| ------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `audit_event_id` | Unique ID for the audit event. | +| `timestamp` | UTC time when Docker recorded the event. | +| `schema_version` | Version of the record schema. Pin SIEM field mappings to this value. | +| `category` | Event category, such as `AUDIT_CATEGORY_MANAGEMENT`, `AUDIT_CATEGORY_EVALUATION`, or `AUDIT_CATEGORY_EXECUTION`. | +| `decision` | Governance decision for evaluation records. | +| `username` | The signed-in Docker user's Docker Hub username. | +| `user_email` | The signed-in Docker user's email address. | +| `org_id` | ID of the organization whose governance policy is in effect. | +| `org_name` | Display name of the organization whose governance policy is in effect. | +| `audit_session_id` | Identifies the daemon session that produced the record. | +| `resource_id` | Target of the evaluation, such as a host and port, file path, or tool. | +| `os` | Operating system that produced the record. | +| `app_version` | Version of the Docker component that produced the record. | +| `client_name` | Source component, such as `sbx` for Docker Sandboxes. | +| `hostname` | Hostname of the machine that produced the record. | +| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | +| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). | +| `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). | +| `action_type` | Payload discriminator that identifies the action-specific object in the record. | +| `agent` | AI agent associated with the event, when Docker knows it. | + +## Categories + +| Category | Description | +| --------------------------- | ------------------------------------------------------------- | +| `AUDIT_CATEGORY_MANAGEMENT` | Session lifecycle, policy sync, and configuration events. | +| `AUDIT_CATEGORY_EVALUATION` | Governance policy decisions, such as allow, deny, or consent. | +| `AUDIT_CATEGORY_EXECUTION` | Outcomes after an evaluated action runs. | + +## Decisions + +| Decision | Description | +| ---------------------------------- | ------------------------------------------------- | +| `AUDIT_DECISION_ALLOW` | Docker allowed the action. | +| `AUDIT_DECISION_DENY` | Docker denied the action. | +| `AUDIT_DECISION_APPROVAL_REQUIRED` | The policy requires a user to approve the action. | +| `AUDIT_DECISION_APPROVAL_ALLOW` | A user approved a pending request. | +| `AUDIT_DECISION_APPROVAL_DENY` | A user denied a pending request. | + +## Enforcement modes + +The `enforcement_mode` field shows how governance applied to the request when +Docker evaluated it. + +| Mode | Description | +| --------- | ------------------------------------------------------------------------------- | +| `enforce` | Your organization's governance policy is enforced. | +| `audit` | Docker records the decision for observability but doesn't enforce policy. | +| `off` | Governance isn't active. Docker still writes the record to the local audit log. | + +A record that resolves a network approval doesn't include `enforcement_mode`, +and neither does the record of a declined MCP approval. An approved MCP request +is evaluated again, so its record includes `enforcement_mode`. + +## Approval fields + +When network access requires approval, Docker blocks the request and writes an +`AUDIT_DECISION_APPROVAL_REQUIRED` record. If the user approves, Docker writes +a second record with `AUDIT_DECISION_APPROVAL_ALLOW`. Both records carry the +same `approval.approval_request_id`, so you can join them to reconstruct the +full approval. The approval applies to later requests from the sandbox. It +doesn't retry the request that was blocked. If the user dismisses the request, +it isn't resolved, so no second record is written and the destination is +requested again the next time the sandbox reaches it. For how approval works, +see [Approval-required access](../access-controls/network.md#approval-required-access). + +For MCP approvals, an approved request is evaluated again and recorded with +`AUDIT_DECISION_APPROVAL_ALLOW`, and a declined request is recorded with +`AUDIT_DECISION_APPROVAL_DENY`. Neither record includes +`approval.approval_request_id` or `approval.grant_scope`. + +| Field | Description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `approval.reason_codes` | Policy reasons for requiring approval. Present on `AUDIT_DECISION_APPROVAL_REQUIRED` records when the policy supplies reasons, and on declined MCP approvals when reasons are available. | +| `approval.approval_request_id` | ID that links an approval required record to the record that resolves it. | +| `approval.grant_scope` | Scope the user accepted. Present only on `AUDIT_DECISION_APPROVAL_ALLOW` records. | +| `approval.context_digest` | SHA-256 digest of the request that was resolved, which shows it matches the request that was held. Present only on declined MCP approvals. | + +For network approvals, Docker Sandboxes records `approval.grant_scope` as +`AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT`, which means that the approval applies +to later requests. + +If a user approves a request but Docker can't apply the grant, the record has +an `AUDIT_DECISION_DENY` decision and includes the `approval` object. + +## Action types + +The `action_type` field identifies the action-specific payload in the record. + +| Action type | Description | +| ---------------------------- | --------------------------------------------------------------------------- | +| `session` | Sandbox daemon session lifecycle event. | +| `network_egress` | Network access evaluation. | +| `http_request` | HTTP request evaluation. See [HTTP request payload](#http-request-payload). | +| `filesystem_mount` | Filesystem mount or path access evaluation. | +| `tool_invocation` | Tool invocation evaluation. | +| `resource_read` | Resource read evaluation. | +| `server_registration` | Server registration event. | +| `prompt` | Prompt-related metadata event. | +| `network_egress_execution` | Outcome of a network action. | +| `filesystem_mount_execution` | Outcome of a filesystem action. | +| `tool_execution` | Outcome of a tool invocation. | +| `resource_read_execution` | Outcome of a resource read. | +| `prompt_execution` | Outcome of a prompt request. | +| `policy_sync` | Policy synchronization event. | +| `pii_detection` | Metadata event for a data detection result. | +| `c_score_report` | Metadata event for a C-score report. | +| `policy_action` | Policy configuration or policy action event. | + +## HTTP request payload + +When a network policy requires each HTTP request to be authorized, Docker +evaluates the request method and path in addition to the network connection. +These evaluations produce records with an `action_type` of `http_request`, +separate from the `network_egress` record for the connection. + +| Field | Description | +| --------------------- | --------------------------------------------------------------------------- | +| `http_request.method` | HTTP method, such as `HTTP_METHOD_GET` or `HTTP_METHOD_POST`. | +| `http_request.host` | Destination hostname or IP address. IPv6 addresses appear without brackets. | +| `http_request.port` | Destination port. | +| `http_request.path` | URL path, without the query string or fragment. | + +## Sample record + +```json +{ + "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", + "timestamp": "2026-05-28T19:15:00.728933Z", + "schema_version": "1.82.0", + "category": "AUDIT_CATEGORY_EVALUATION", + "decision": "AUDIT_DECISION_DENY", + "username": "jordandoe", + "user_email": "jordandoe@example.com", + "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", + "org_name": "Acme Inc", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "resource_id": "example.com:443", + "os": "macos", + "app_version": "v0.31.0", + "client_name": "sbx", + "hostname": "host-machine", + "deny_reason": [ + "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" + ], + "action_type": "network_egress", + "network_egress": { "protocol": "tcp" }, + "agent": "claude" +} +``` + +The following sample shows a user approving an HTTP request that required +approval: + +```json +{ + "audit_event_id": "3c1f6a2e-8b47-4d0a-9e55-2f7b1d6c9a04", + "timestamp": "2026-09-25T17:42:08.114502Z", + "schema_version": "1.216.0", + "category": "AUDIT_CATEGORY_EVALUATION", + "decision": "AUDIT_DECISION_APPROVAL_ALLOW", + "username": "jordandoe", + "user_email": "jordandoe@example.com", + "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", + "org_name": "Acme Inc", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "resource_id": "api.example.com:443", + "os": "macos", + "app_version": "v0.46.0", + "client_name": "sbx", + "hostname": "host-machine", + "approval": { + "approval_request_id": "b7e2c9d1-4f60-4a8e-93c2-5d1e8f7a6b30", + "grant_scope": "AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT" + }, + "action_type": "http_request", + "http_request": { + "method": "HTTP_METHOD_POST", + "host": "api.example.com", + "port": "443", + "path": "/v1/items" + }, + "agent": "claude" +} +``` diff --git a/content/manuals/ai/sandboxes/governance/audit/siem.md b/content/manuals/ai/sandboxes/governance/audit/siem.md new file mode 100644 index 000000000000..9a4dd503d290 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/siem.md @@ -0,0 +1,72 @@ +--- +title: SIEM forwarding +linkTitle: SIEM forwarding +weight: 40 +description: Forward Docker AI Governance audit events to Splunk, Dynatrace, Datadog, Sumo Logic, or CrowdStrike Falcon Next-Gen SIEM. +keywords: docker sandboxes, SIEM, audit logs, Splunk, Dynatrace, Datadog, Sumo Logic, CrowdStrike, Falcon Next-Gen SIEM, AI Governance, forwarding, NDJSON +--- + +{{< summary-bar feature_name="AI Governance Audit Logs" >}} + +Docker can forward audit events to your security information and event +management (SIEM) system, letting you centralize Docker governance data +alongside other security signals. Docker verifies the endpoint is reachable +with the supplied credential before saving. + +## Supported destinations + +| Destination | Description | +| -------------------------------- | --------------------------------------------------------------- | +| Splunk Cloud (HEC) | Hosted Splunk using the HTTP Event Collector | +| Dynatrace | Dynatrace Log Management using the Log Ingest API | +| Datadog | Datadog Logs using the HTTP log intake API | +| Sumo Logic | Sumo Logic using an HTTP Source | +| CrowdStrike Falcon Next-Gen SIEM | Falcon Next-Gen SIEM using an HEC / HTTP Event Connector | + +## Before you begin + +SIEM forwarding requires Docker Sandboxes +[0.39.0](/manuals/ai/sandboxes/release-notes.md) or later. Earlier versions +don't deliver audit records to a SIEM destination, even when forwarding is +configured. Update Docker Sandboxes before enabling a new destination. + +SIEM forwarding requires Docker Cloud delivery to be enabled for your +organization. If you haven't already, enable it under **AI Platform** > +**Audit logs** > **Audit delivery** before configuring a SIEM destination. See +[Configure audit delivery](configure.md). + +Gather the endpoint URL and credential from your SIEM before configuring +forwarding. Some destinations require you to create a connector or source +first: + +- **Splunk Cloud**: HEC ingest URL and an HEC token. Optionally, a Splunk index + name. See [Splunk documentation](https://docs.splunk.com/). +- **Dynatrace**: Log Ingest API URL and an API token with the `logs.ingest` + scope. See [Dynatrace documentation](https://docs.dynatrace.com/). +- **Datadog**: Logs intake URL for your Datadog site and an API key. See + [Datadog documentation](https://docs.datadoghq.com/). +- **Sumo Logic**: HTTP Source URL and an auth token from an HTTP Logs & + Metrics source. See [Sumo Logic documentation](https://www.sumologic.com/help/). +- **CrowdStrike Falcon Next-Gen SIEM**: API URL and an API key from an HEC / + HTTP Event Connector. Append `/raw` to the API URL when you add the + destination. See [CrowdStrike documentation](https://library.humio.com/logscale-api/log-shippers-hec-raw.html). + +## Add a SIEM destination + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Open your organization. +1. Go to **AI Platform** > **Audit logs**. +1. Open **Export & Connectors**. +1. Select **Add destination**. +1. Select your destination and complete the form. +1. Select **Save**. + +If verification fails, check that the URL and credential are correct and that +the endpoint is accessible from the internet. + +## Manage destinations + +From the **SIEM forwarding** list, select the menu next to a destination to +edit or delete it. The edit form lets you update credentials and toggle +forwarding on or off for that destination. Deleting a destination permanently +removes the endpoint and its stored credential and cannot be undone. diff --git a/content/manuals/ai/sandboxes/governance/audit/view-export.md b/content/manuals/ai/sandboxes/governance/audit/view-export.md new file mode 100644 index 000000000000..7b1e7adf67b0 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/view-export.md @@ -0,0 +1,50 @@ +--- +title: View and export audit events +linkTitle: View and export +weight: 30 +description: Search, filter, and export Docker AI Governance audit events from the hosted audit log UI. +keywords: docker sandboxes, audit events, audit logs, AI Governance, CSV export +--- + +Cloud delivery stores AI Governance audit records in Docker Cloud and makes +them available in the hosted audit log UI. Use the hosted view to investigate +policy decisions or export events to CSV. + +## View audit events + +To view audit events: + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Open your organization. +1. Go to **AI Platform** > **Audit logs**. +1. Open **Audit Events**. + +The **Audit Events** view includes summary tiles for total events, allowed +events, denied events, and consent-required events. The event table includes: + +| Column | Description | +| --------- | ------------------------------------------------------------- | +| Time | When Docker recorded the event. | +| Event | The event type or policy action. | +| Principal | The Docker user associated with the event. | +| Resource | The target resource, such as a domain, file path, or tool. | +| Decision | The governance decision, such as allow, deny, or consent. | +| Agent | The AI agent associated with the event, when Docker knows it. | + +## Filter and search events + +Use the audit log filters to narrow the event table by decision and time range. +Use search to find events by principal, resource, event type, or agent. + +The event table uses cursor pagination for large result sets. + +## Export events to CSV + +Use CSV export when you need an offline copy of filtered audit events: + +1. Open **Audit Events**. +1. Apply the filters and search terms for the events you want to export. +1. Select **Export**. +1. Download the generated CSV file from the link Docker provides. + +CSV exports include up to 1 000 000 rows. Download links expire after 24 hours. diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 469ec5dd7d8b..a7c2928256ea 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -1,10 +1,14 @@ --- title: Policy concepts -weight: 5 +weight: 10 description: The resource model, rule syntax, and evaluation logic behind Docker sandbox governance. -keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, precedence, rule evaluation +keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, mcp policy, cedar policy, precedence, rule evaluation --- +The governance described here applies to local sandboxes. Cloud sandboxes +use separate network policy configuration. See +[Cloud network policy](../cloud/network-policy.md) for cloud controls. + ## Resource model Docker sandbox governance is built around two resource types: **policies** and @@ -15,13 +19,15 @@ Policies exist at two levels: - **Local**: configured per machine using the `sbx policy` CLI. Applies to sandboxes on that machine only. -- **Organization**: configured in the Docker Admin Console or via the +- **Organization**: configured in Docker Home. Network and filesystem policies + can also be managed via the [Governance API](/reference/api/ai-governance/). Applies to sandboxes across the organization. An organization can have several policies, each applying either org-wide or to specific teams. See [Policy scope](#policy-scope). -When organization governance is active, organization policies replace local -policies entirely. See [Precedence](#precedence). +When organization governance is active, only organization allow rules can grant +access. Local and kit-defined deny rules still apply on top. See +[Precedence](#precedence). A **rule** is the unit of access control within a policy. Each rule has: @@ -30,8 +36,41 @@ A **rule** is the unit of access control within a policy. Each rule has: - **Resources**: the targets the rule matches against - **Decision**: `allow` or `deny` -Rules are grouped by domain: all rules in a policy must share the same domain, -either `network` or `filesystem`. +Rules are grouped by domain. Network and filesystem rules in a policy must +share the same domain, either `network` or `filesystem`. MCP policies use Cedar +statements written in the `MCP` namespace instead of the network and filesystem +rule format. + +An organization network policy can also require approval, which turns every +allow in that policy into a request the developer must confirm before access is +granted. Approval is set on the policy rather than on individual rules, so it +applies to all of the policy's allow rules at once. Without organization +governance, a request with no matching allow or deny rule also asks for +approval. See +[Approval-required access](access-controls/network.md#approval-required-access). + +Network approval is separate from the MCP `@requireApproval` annotation. An MCP +approval confirms a single call within the session and creates no rule, while +an approved network destination stays allowed until you remove the rule. See +[MCP access policies](access-controls/mcp.md). + +### Limits + +Organization policies have the following limits, which help ensure fair usage +and resource availability across organizations: + +| Limit | Value | +|---------------------------|-----------------------------------------------------| +| Policies per organization | 100 | +| Rules per policy | 250 | +| Policy size | 400 KB total, shared across all of a policy's rules | + +Typical policies use only a small fraction of the policy size limit. Domain +and file path values have no separate length limit beyond valid format. + +If these limits don't fit your organization's needs, +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +to discuss options. ## Policy scope @@ -43,7 +82,7 @@ to specific teams: - Team-scoped: with one or more teams assigned, the policy applies only to members of those teams. -Teams are the same [teams](/manuals/admin/organization/manage/manage-a-team.md) +Teams are the same [teams](/manuals/accounts/organization/manage/manage-a-team.md) you manage for your organization; Docker matches a policy's teams against each user's team membership. Because an organization can mix org-wide and team-scoped policies, a single user is often subject to several at once. The policies that @@ -55,17 +94,19 @@ plus every team-scoped policy for a team they belong to. See ### Network rules -Network rules use the actions `connect:tcp` and `connect:udp`. Resources are -hostnames, CIDR ranges, or ports. +Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are +hostnames, CIDR ranges, or ports. UDP requires +[experimental outbound UDP](access-controls/local.md#allow-outbound-udp). +ICMP is blocked. **Hostname patterns** -| Pattern | Example | Matches | -| --------------------- | ----------------- | -------------------------------------------------- | -| Exact hostname | `example.com` | `example.com` only, not subdomains | -| Single-level wildcard | `*.example.com` | One subdomain level: `api.example.com` | -| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` | -| Hostname with port | `example.com:443` | `example.com` on port 443 only | +| Pattern | Example | Matches | +| --------------------- | ----------------- | ------------------------------------------------------------- | +| Exact hostname | `example.com` | `example.com` on any port, not subdomains | +| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` | +| Multi-level wildcard | `**.example.com` | Any depth, any port: `api.example.com`, `v2.api.example.com` | +| Hostname with port | `example.com:443` | `example.com` on port 443 only | `example.com` and `*.example.com` don't cover each other. Specify both if you need to match the root domain and its subdomains. @@ -75,11 +116,78 @@ need to match the root domain and its subdomains. Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, `2001:db8::/32`. +#### HTTP method and path + +A network rule matches a destination host on its own. An HTTP rule is a network +rule that also names an HTTP method and URL path, so a policy can allow reads +from an API without allowing writes to it. + +An HTTP rule names one or more methods, a destination, and path patterns. What +each part accepts depends on where you configure the rule: + +| Part | Organization policy | Local policy | +| ----------- | ------------------------------------------ | --------------------------------- | +| Method | One or more listed methods | `ANY`, or one or more methods | +| Destination | A host or IP address | A host | +| Path | One or more absolute path patterns | One absolute path pattern | + +A destination can include a port, and a path pattern looks like `/api/**`. + +A local rule doesn't accept an IP address or a CIDR range. Use a plain network +rule for those destinations. To cover a second path in a local policy, add a +second rule. + +Every rule applies to at least one method. On the CLI, `--method ANY` covers +every HTTP method. In the composer, a rule with no methods selected covers +every method the composer lists. For the methods you can select individually, see +[Add a network rule](access-controls/organization.md#add-a-network-rule) for an +organization policy and +[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules) +for a local one. + +Path patterns follow the same wildcard rules as filesystem paths, where `*` +matches within one path segment and `**` matches any depth. A pattern without a +wildcard matches that path exactly, so `/repos` matches `/repos` and nothing +below it. Every pattern must start with `/` and can't contain a query string, a +fragment, or a `..` segment. A local rule's path must also be canonical, so it +can't contain percent-encoding, control characters, repeated or trailing +slashes, or a `.` segment. For the full list, see +[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules). + +HTTP requests are evaluated against both layers. A network rule sets the +baseline for a host, and HTTP rules adjust individual methods and paths within +it: + +| Rules that cover the host | Result for an HTTP request | +| --------------------------- | ----------------------------------------------------------------------- | +| Network allow only | Allowed at any method and path | +| HTTP allow only | Allowed only where a rule matches the method and path. Anything else is denied | +| Network allow and HTTP deny | The denied methods and paths are blocked. The rest stay allowed | +| Network deny | Blocked. An HTTP allow can't reopen a denied host | + +A network deny is therefore a floor that HTTP rules can't raise, while a +network allow is a ceiling that HTTP rules can carve into. + +When a rule requires a method and path decision, the sandbox HTTP proxy +evaluates each request separately instead of deciding once per connection. + +Those requests have to go through the proxy. A connection it can't inspect, +such as one it handles transparently, is blocked rather than evaluated. +Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules +never match it. Control those destinations with network rules. + +For local and organization policy configuration, see +[Network access policies](access-controls/network.md). + ### Filesystem rules Filesystem rules use the actions `read` and `write`. Resources are host paths that sandboxes can mount as workspaces. +A workspace mounted with write access must be allowed by both a `read` and a +`write` rule; a read-only workspace needs only `read`. When default deny blocks +a mount, the denial reason names whether read or write access was missing. + `~` expands to the user's home directory on every platform, including Windows, where it resolves to `%USERPROFILE%`. A single `~/**` rule therefore matches each user's home tree on macOS, Linux, and Windows. The policy engine expands @@ -111,6 +219,31 @@ Use `**` to match a directory tree recursively. A single `*` matches within one path segment and won't cross a path separator. For example, `~/**` matches all paths under the home directory, while `~/*` matches only its direct children. +For organization policy configuration and enforcement details, see +[Filesystem access policies](access-controls/filesystem.md). + +### MCP policies + +MCP policies control Model Context Protocol activity made available to a +sandbox through Docker's [MCP gateway](../mcp-gateway.md). They are +organization policies written in Cedar using the `MCP` namespace, rather than +the network and filesystem rule format. + +MCP policy applies when a developer registers a server and when an agent uses +the MCP gateway. Registration rules control future `sbx mcp add` operations. +Use-time rules control tool calls, gateway meta-tools, resource reads, and +prompt retrieval from servers that are already registered or loaded. + +Governed MCP activity is default deny: a request is blocked unless a matching +`permit` allows it. A matching `forbid` overrides any `permit`, including a +permit that requires approval. Policy scope supplies the principal, so use +organization or team scope instead of matching users, teams, tenants, or roles +in Cedar. + +For representative policies, see [MCP access policies](access-controls/mcp.md). +For exact action, resource, context, and approval behavior, see the +[MCP policy reference](reference/mcp-policy.md). + ## Rule evaluation When organization governance is active, the rules from all of a user's @@ -121,7 +254,8 @@ each request, following two principles: regardless of any matching allow rules. - Default deny: anything an allow rule doesn't match is blocked. Outbound network traffic is blocked unless a network rule allows the destination, and a - host path can't be mounted unless a filesystem rule allows it. + host path can't be mounted unless a filesystem rule allows it. MCP activity is + blocked unless an MCP `permit` allows it. Because every effective policy feeds the same evaluation, allows are additive (a request is allowed if any effective policy allows it) and denies are absolute (a @@ -129,20 +263,55 @@ request is blocked if any effective policy denies it). A deny rule in an org-wide policy therefore applies to everyone and can't be overridden by a team-scoped policy, which makes org-wide deny rules useful as guardrails. -Local rules take no part in this evaluation; see [Precedence](#precedence). +Local and kit-defined allow rules take no part in this evaluation. Deny rules +from those sources do still apply. See [Precedence](#precedence). + +A request that an approval-required policy allows produces a third outcome. +Rather than being allowed outright, it's held back until the developer confirms +the destination, and the confirmation governs later requests to it. This holds +even when another policy allows the same request without requiring approval. A +matching deny still wins, so a denied destination is blocked without asking. +See [Approval-required access](access-controls/network.md#approval-required-access). ## Precedence -Local and organization policies don't combine. Which one applies depends on -whether your organization has governance enabled: +What applies depends on whether your organization has governance enabled: -- No organization governance: local rules and any - [kit-defined network rules](../customize/kits.md#control-network-access) +- No organization governance: local rules and any kit-defined network rules determine what sandboxes can access. -- Organization governance active: organization rules apply across all developer - machines, and local and kit-defined rules are not evaluated. `sbx policy ls` - hides these inactive rules by default; see - [Monitoring](monitoring.md#showing-inactive-rules) for how to list them. +- Organization governance active: organization policy determines what access can + be granted. Only organization allow rules grant access, so local and + kit-defined allow rules are inactive and can't expand what the organization + permits. Deny rules apply from every source, so a local or kit-defined deny + can still restrict access further. + +For kit-defined rules, see +[Network policies](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) +in the kit specification. + +Precedence is decided by a rule's decision rather than its source: + +| Rule | Evaluated under organization governance | +| ------------------- | --------------------------------------- | +| Organization allow | Yes | +| Organization deny | Yes | +| Local allow | No | +| Local deny | Yes | +| Kit-defined allow | No | +| Kit-defined deny | Yes | + +Local and kit-defined rules cover network access only, so a deny that layers on +top of organization policy is always a network deny. `sbx policy ls` hides +inactive rules by default. See +[Monitoring](monitor-and-enforce/monitoring.md#showing-inactive-rules) for how +to list them. + +A local deny takes precedence over an organization approval requirement as +well, so the request is blocked and no approval is requested. Rules that a +developer gains by approving a request are the one exception to local allow +rules being inactive, because they record an answer to the organization's own +approval requirement rather than granting new access. See +[Approval-required access](access-controls/network.md#approval-required-access). When organization governance is active, a user's organization policies are evaluated together, as described in [Rule evaluation](#rule-evaluation). diff --git a/content/manuals/ai/sandboxes/governance/local.md b/content/manuals/ai/sandboxes/governance/local.md deleted file mode 100644 index 89224a8a4e03..000000000000 --- a/content/manuals/ai/sandboxes/governance/local.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Local policy -weight: 10 -description: Configure network access rules for sandboxes on your local machine. -keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy -aliases: - - /ai/sandboxes/security/policy/ ---- - -The `sbx policy` command manages network access rules on your local machine. -Rules apply to all sandboxes on the machine when you use the global scope, or -to a single sandbox when scoped by name. - -Local rules apply only when your organization doesn't enforce governance: - -- **No org governance**: local rules fully control what sandboxes can access. -- **Org governance active**: the organization policy replaces local policy. - Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have - no effect. To list the inactive local rules, run - `sbx policy ls --include-inactive`. See - [Monitoring](monitoring.md#showing-inactive-rules). - -See [Organization policy](org.md) for how organization governance works. - -For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see -[Policy concepts](concepts.md#rule-syntax). - -## Default preset - -The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on -your host, which enforces access rules on every outbound request. Non-HTTP TCP -traffic, including SSH, can be allowed by adding a policy rule for the -destination IP and port (for example, `sbx policy allow network "10.1.2.3:22"`). -UDP and ICMP are blocked at the network layer and can't be unblocked with policy -rules. - -On first start, and after running `sbx policy reset`, the daemon prompts you -to choose a network preset: - -```plaintext -Choose a default network policy: - - 1. Open — All network traffic allowed, no restrictions. - 2. Balanced — Default deny, with common dev sites allowed. - 3. Locked Down — All network traffic blocked unless you allow it. - - Use ↑/↓ to navigate, Enter to select, or press 1–3. -``` - -| Preset | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| Open | All outbound traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | -| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | -| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. | - -The **Balanced** preset's baseline allowlist is a good starting point for most -workflows. Run `sbx policy ls` to see exactly which rules it includes. - -> [!NOTE] -> If your organization manages sandbox policies centrally, organization rules -> take precedence over the preset you select here. See -> [Organization policy](org.md). - -### Non-interactive environments - -In non-interactive environments such as CI pipelines or headless servers, the -interactive prompt can't be displayed. Use `sbx policy set-default` to set the -preset before running any other `sbx` commands: - -```console -$ sbx policy set-default balanced -``` - -Available values are `allow-all`, `balanced`, and `deny-all`. - -## Managing rules - -Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and -[`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add or restrict access -on top of the active preset. Changes take effect immediately. Rules apply to -all sandboxes by default: - -```console -$ sbx policy allow network api.anthropic.com -$ sbx policy deny network ads.example.com -``` - -Pass `--sandbox <name>` to scope a rule to one sandbox: - -```console -$ sbx policy allow network --sandbox my-sandbox api.example.com -$ sbx policy deny network --sandbox my-sandbox ads.example.com -``` - -Specify multiple hosts in one command with a comma-separated list: - -```console -$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" -``` - -Remove a rule by resource or by rule ID: - -```console -$ sbx policy rm network --resource ads.example.com -$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 -``` - -To remove a sandbox-scoped rule, pass `--sandbox <name>`: - -```console -$ sbx policy rm network --sandbox my-sandbox --resource api.example.com -``` - -To inspect which rules are active and where they come from, use -`sbx policy ls`. See [Monitoring](monitoring.md). - -### Resetting - -To remove all custom rules and start fresh with a new preset, use -`sbx policy reset`: - -```console -$ sbx policy reset -``` - -This deletes the local policy store and stops the daemon. When the daemon -restarts on the next command, you are prompted to choose a new preset. Running -sandboxes stop when the daemon shuts down. Pass `--force` to skip the -confirmation prompt: - -```console -$ sbx policy reset --force -``` - -## Troubleshooting - -### Local rules have no effect - -If rules you add with `sbx policy allow` or `sbx policy deny` don't change -sandbox behavior, your organization likely has governance enabled. Run `sbx -policy ls` to check: if the output starts with a `Governance: managed by <org>` -header, org governance is active. When it's active, the organization policy -replaces local policy, so your rules have no effect. They're hidden from `sbx -policy ls` by default; run `sbx policy ls --include-inactive` to see them with -an `inactive` status. - -Organization policy can't be supplemented from your machine. To change what -your sandboxes can access, ask your admin to update the organization policy in -the Admin Console. - -### A domain is still blocked after adding an allow rule - -If a domain remains blocked after you add a local allow rule, your organization -likely enforces governance, which makes local rules inactive. Run `sbx policy -ls` to check whether org governance is active; if the output starts with a -`Governance: managed by <org>` header, it is. Add `--include-inactive` to -confirm your rule shows an `inactive` status. If so, the block can only be -lifted by updating the org policy in the Admin Console or via the -[API](/reference/api/ai-governance/). diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md new file mode 100644 index 000000000000..0ff58d417a22 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md @@ -0,0 +1,16 @@ +--- +title: Monitor and enforce +weight: 40 +description: Inspect active sandbox governance rules, collect audit records, and enforce organization sign-in. +keywords: docker sandboxes, governance monitoring, audit logs, sign-in enforcement, policy enforcement +--- + +After policies are configured, use monitoring, audit records, and sign-in +enforcement to verify how governance behaves across developer machines. + +- [Monitoring policies](monitoring.md): inspect active policy rules and monitor + sandbox network traffic. +- [Audit logs](../audit/): view, configure, export, and collect governance audit + records. +- [Sign-in enforcement](sign-in-enforcement.md): require users to sign in as + members of approved Docker organizations. diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md new file mode 100644 index 000000000000..223bc8600c7b --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -0,0 +1,238 @@ +--- +title: Monitoring policies +weight: 10 +description: Inspect active policy rules and monitor sandbox network traffic with sbx policy ls and sbx policy log. +keywords: docker sandboxes, policy monitoring, sbx policy ls, sbx policy log, network traffic, policy debugging +aliases: + - /ai/sandboxes/governance/monitoring/ +--- + +`sbx policy ls` and `sbx policy log` give you a combined view of all active +policy rules and sandbox network activity, regardless of whether those rules +come from local configuration or organization governance. They're useful both +for verifying rules you've written and for debugging why a request is being +blocked or allowed. + +## Listing rules + +Use `sbx policy ls` to see all active policies and their current status: + +```console +$ sbx policy ls +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all network: 42 allow, 1 deny; filesystem read: 1 allow; filesystem write: 1 allow +1b2633ea-e604-48bb-a5e6-3ac86ba383fe kit sandbox:my-sandbox network: 3 allow +``` + +The columns are: + +- `POLICY`: the policy name. +- `SOURCE`: where the policy came from. `local` means your local configuration + — a preset or rules you added with `sbx policy`. `kit` means a + [kit](/manuals/ai/sandboxes/governance/concepts.md#precedence). `org` means your + organization. +- `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy + is global. `sandbox:<name>` scopes it to a single sandbox; a profile name + scopes it to sandboxes using that profile. +- `SUMMARY`: a count of rule entries by type and decision, for example + `network: 5 allow, 1 deny`. A rule that names several destinations + contributes one entry per destination. When the listing includes rules that + match an HTTP method and path, the network count labels each part `(L4)` or + `(L7)`. See [HTTP rules](#http-rules). + +To see full rule-level detail including rule IDs and resources, pass `--wide`. +To inspect a single policy or rule, use `sbx policy inspect`: + +```console +$ sbx policy inspect Balanced +``` + +Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision` +to filter by outcome (`allow` or `deny`). + +Use `--protocol tcp` or `--protocol udp` to filter network rules. + +Use `--created-via` to filter by how a rule was created. Pass `default` for +preset rules, `added` for rules you added yourself, `provisioned` for rules a +kit or application added, or `approval` for rules recorded when you approved a +destination. A wide listing shows the same information per rule: + +```console +$ sbx policy ls --wide --created-via approval +``` + +See [Approval-required access](../access-controls/network.md#approval-required-access). + +A `STATUS` column also appears when you pass `--include-inactive`; see +[Showing inactive rules](#showing-inactive-rules). + +When organization governance is active, the output starts with a summary block +showing which organization manages the policy, the sync state, and how many +inactive rules are hidden: + +```console +$ sbx policy ls +POLICY RULES + Governance: Managed by my-org + Sync: OK, last synced 08:21:01 + Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive + +POLICY SOURCE APPLIES TO SUMMARY +default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny +default network org all network: 38 allow, 4 deny +``` + +`Governance` shows which organization manages the policy, and `Sync` confirms +the daemon has pulled the latest rules. `Hidden` reports how many inactive rules +are suppressed and how to reveal them. + +If the sync state shows an error or a stale timestamp, run `sbx policy refresh` +to fetch and apply the latest policy without restarting the daemon or stopping +sandboxes. The policy applies to new connections. To close existing connections +that the updated policy denies, restart the sandbox. + +If Docker can't determine which organization governs your account, policy +output shows `Governance: Unresolved`, and the dashboard shows the same +unresolved state. For example, this happens when your account belongs to +multiple organizations with governance enabled. Policy enforcement fails closed +until the conflict is resolved, so local allow rules can't grant access. Contact +an administrator for the affected organizations to resolve the conflicting +governance configuration. + +### Showing inactive rules + +When organization governance is active, local and kit-defined allow rules are +not evaluated, so `sbx policy ls` hides them by default. To list them too — for +example, to confirm which allow rules the organization policy overrides — pass +`--include-inactive`. This adds a `STATUS` column: + +```console +$ sbx policy ls --include-inactive +POLICY RULES + Governance: Managed by my-org + Sync: OK, last synced 08:41:06 + +POLICY SOURCE APPLIES TO SUMMARY STATUS +default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny active +default network org all network: 38 allow, 4 deny active +default-fs-read-allow-all local all filesystem read: 1 allow inactive +default-fs-write-allow-all local all filesystem write: 1 allow inactive +``` + +Inactive policies show `inactive` in the `STATUS` column. They have no effect +while organization governance is active. Local and kit-defined deny rules stay +active and aren't hidden, because a deny still applies on top of the +organization policy. See [Precedence](../concepts.md#precedence). + +Use `--type network`, `--type filesystem`, or `--type http` to show only +policies of that type. Without a sandbox argument, `sbx policy ls` shows every +policy across all sandboxes. Pass a sandbox name to filter to global policies +and those scoped to that sandbox: + +```console +$ sbx policy ls my-sandbox +``` + +### Filesystem rules + +`sbx policy ls` lists filesystem policies alongside network policies. Filesystem +rules control which host paths a sandbox can mount as a workspace. Pass +`--type filesystem` to show only them: + +```console +$ sbx policy ls --type filesystem +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all filesystem read: 1 allow; filesystem write: 1 allow +``` + +A writable workspace mount must be allowed by both a `filesystem:read` and a +`filesystem:write` rule; a read-only mount needs only `filesystem:read`. The +default local policy allows read and write access to all paths, shown as the +two `default-fs-*` rules above. For the rule syntax and path patterns, see +[Policy concepts](../concepts.md#filesystem-rules). + +### HTTP rules + +Rules that match an HTTP method and path are listed as type `http`. Pass +`--wide` to see the `METHOD` and `PATH` columns alongside network rules: + +```console +$ sbx policy ls --wide +TYPE METHOD PATH +network - - +http GET /repos/org/project/** +http POST /admin/** +``` + +Rules that match a whole destination show `-` in both columns. To list only +HTTP rules, pass `--type http`. + +HTTP rules are counted as network rules in the `SUMMARY` column, with each part +labeled by the network layer it matches on. `L4` counts entries that match a +whole destination, and `L7` counts those that also match an HTTP method and +path: + +```console +$ sbx policy ls +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all network: 2 allow (L4), 1 deny (L7) +``` + +When the same decision has entries at both layers, each layer gets its own +count, L4 first. Two host allows and one HTTP allow read +`network: 2 allow (L4), 1 allow (L7)`. + +The labels appear when the current listing includes at least one HTTP rule. +Because filters and hidden inactive rules change what the listing contains, a +filtered listing with no HTTP rules shows an unlabeled count, such as +`network: 42 allow`. + +For the rule syntax, see +[HTTP method and path](../concepts.md#http-method-and-path). + +## Monitoring traffic + +Use `sbx policy log` to see which hosts your sandboxes have contacted and +which rules matched: + +```console +$ sbx policy log +BLOCKED REQUESTS +SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT +my-sandbox network blocked.example.com transparent domain-blocked default-deny 10:15:25 29-Jan 1 + +ALLOWED REQUESTS +SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT +my-sandbox network api.anthropic.com forward domain-allowed 10:15:23 29-Jan 42 +my-sandbox network registry.npmjs.org forward-bypass domain-allowed 10:15:20 29-Jan 18 +my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1 +``` + +The `PROXY` column shows how the request left the sandbox: + +| Value | Description | +| ---------------- | -------------------------------------------------------------------------------------------------------------- | +| `forward` | Routed through the forward proxy. Supports [credential injection](../../configuration/credentials.md). | +| `forward-bypass` | Routed through the forward proxy without credential injection. | +| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | +| `network` | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. | +| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | + +The `RULE` column identifies the policy rule that matched the request. The +`REASON` column includes extra context when the daemon records one. + +Filter by sandbox name by passing it as an argument: + +```console +$ sbx policy log my-sandbox +``` + +Use `--limit N` to show only the last `N` entries, `--json` or `--format yaml` for +machine-readable output, or `--type network` to filter by policy type. +`sbx policy log` records network traffic only; filesystem mount decisions +aren't available in the log yet. + +Structured output uses the same document for local and cloud sandboxes: +`{updated_at, allowed: [...], blocked: [...]}`. Each entry includes `sandbox_id`, +`host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. +The `--limit` flag applies to structured output too. diff --git a/content/manuals/ai/sandboxes/governance/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md similarity index 94% rename from content/manuals/ai/sandboxes/governance/sign-in-enforcement.md rename to content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md index c783266f842c..8f60dac44d98 100644 --- a/content/manuals/ai/sandboxes/governance/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md @@ -1,9 +1,11 @@ --- title: Sign-in enforcement linkTitle: Sign-in enforcement -weight: 22 +weight: 20 description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management. keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs +aliases: + - /ai/sandboxes/governance/sign-in-enforcement/ --- Sign-in enforcement restricts Docker Sandboxes to users who are members of @@ -13,8 +15,9 @@ membership after the user authenticates. If the check fails, credentials are immediately revoked and the user can't run sandboxes. Without this enforcement, a developer can sign in with a personal account and -bypass organization [governance policies](org.md). Sign-in enforcement closes -that gap at the endpoint, where users can't override it. +bypass organization [governance policies](../access-controls/organization.md). +Sign-in enforcement closes that gap at the endpoint, where users can't override +it. > [!NOTE] > Sign-in enforcement is part of Docker's AI Governance offering. @@ -261,9 +264,10 @@ For access, contact ACME IT Security: ## Related pages -- [Organization policy](org.md): centrally manage sandbox network and - filesystem rules from the Docker Admin Console -- [Governance overview](_index.md): how local and organization governance fit +- [Organization policies](../access-controls/organization.md): centrally manage + sandbox network, filesystem, and MCP access controls from the Docker Admin + Console +- [Governance overview](../_index.md): how local and organization governance fit together -- [Enforce sign-in for Docker Desktop](/manuals/enterprise/security/enforce-sign-in/_index.md): +- [Enforce sign-in for Docker Desktop](/manuals/desktop/enterprise/enforce-sign-in/_index.md): the equivalent control for Docker Desktop diff --git a/content/manuals/ai/sandboxes/governance/monitoring.md b/content/manuals/ai/sandboxes/governance/monitoring.md deleted file mode 100644 index 1df88ada4c73..000000000000 --- a/content/manuals/ai/sandboxes/governance/monitoring.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Monitoring policies -weight: 25 -description: Inspect active policy rules and monitor sandbox network traffic with sbx policy ls and sbx policy log. -keywords: docker sandboxes, policy monitoring, sbx policy ls, sbx policy log, network traffic, policy debugging ---- - -`sbx policy ls` and `sbx policy log` give you a combined view of all active -policy rules and sandbox network activity, regardless of whether those rules -come from local configuration or organization governance. They're useful both -for verifying rules you've written and for debugging why a request is being -blocked or allowed. - -## Listing rules - -Use `sbx policy ls` to see all active rules and their current status: - -```console -$ sbx policy ls -NAME TYPE ORIGIN DECISION STATUS RESOURCES -balanced-dev network local allow active api.anthropic.com -ads-block network local deny active ads.example.com -kit:my-sandbox network sandbox:my-sandbox allow active api.example.com -kit:my-sandbox:deny network sandbox:my-sandbox deny active telemetry.example.com -``` - -The columns are: - -- `NAME`: the rule name. -- `TYPE`: the rule domain, such as `network`. -- `ORIGIN`: where the rule was configured. `local` means the rule is global - and applies to all sandboxes. `sandbox:<name>` means the rule is scoped to - the named sandbox. `remote` means the rule was set by your organization. -- `DECISION`: whether the rule allows or denies the resource. -- `STATUS`: whether the rule is in effect. A rule may be `inactive` if it's - overridden or suppressed — for example, when organization governance is - active, local rules are not evaluated. Inactive rules are hidden by default; - pass `--include-inactive` to list them. See - [Showing inactive rules](#showing-inactive-rules). -- `RESOURCES`: the hosts or patterns the rule applies to. - -When organization governance is active, the output starts with a governance -header showing which organization manages the policy and when it last synced: - -```console -$ sbx policy ls -Governance: managed by my-org -[OK] last synced 13:54:21 -NAME TYPE ORIGIN DECISION STATUS RESOURCES -allow AI services network remote allow active api.anthropic.com - api.openai.com -allow Docker services network remote allow active *.docker.com - *.docker.io -``` - -The governance header shows which organization is managing the policy and -confirms the daemon has successfully pulled the latest rules. If the sync -status shows an error or a stale timestamp, the daemon may not have the most -recent org policy. Run `sbx policy reset` to force a fresh pull. - -### Showing inactive rules - -When organization governance is active, local and kit-defined rules are not -evaluated, so `sbx policy ls` hides them by default. To list them too — for -example, to confirm which local rules the organization policy overrides — pass -`--include-inactive`: - -```console -$ sbx policy ls --include-inactive -Governance: managed by my-org -[OK] last synced 13:54:21 -NAME TYPE ORIGIN DECISION STATUS RESOURCES -balanced-dev network local allow inactive api.anthropic.com -allow AI services network remote allow active api.anthropic.com - api.openai.com -allow Docker services network remote allow active *.docker.com - *.docker.io -``` - -Inactive rules show with an `inactive` status. They have no effect while -organization governance is active. - -Use `--type network` to show only network rules. Without a sandbox argument, -`sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to -filter to global rules and rules scoped to that sandbox: - -```console -$ sbx policy ls my-sandbox -``` - -## Monitoring traffic - -Use `sbx policy log` to see which hosts your sandboxes have contacted and -which rules matched: - -```console -$ sbx policy log -Blocked requests: -SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT -my-sandbox network blocked.example.com transparent domain-blocked default-deny 10:15:25 29-Jan 1 - -Allowed requests: -SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT -my-sandbox network api.anthropic.com forward domain-allowed 10:15:23 29-Jan 42 -my-sandbox network registry.npmjs.org forward-bypass domain-allowed 10:15:20 29-Jan 18 -my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1 -``` - -The `PROXY` column shows how the request left the sandbox: - -| Value | Description | -| ----- | ----------- | -| `forward` | Routed through the forward proxy. Supports [credential injection](../security/credentials.md). | -| `forward-bypass` | Routed through the forward proxy without credential injection. | -| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | -| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule; UDP and ICMP are always blocked. | -| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | - -The `RULE` column identifies the policy rule that matched the request. The -`REASON` column includes extra context when the daemon records one. - -Filter by sandbox name by passing it as an argument: - -```console -$ sbx policy log my-sandbox -``` - -Use `--limit N` to show only the last `N` entries, `--json` for -machine-readable output, or `--type network` to filter by policy type. diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/org.md deleted file mode 100644 index 46e734a056b2..000000000000 --- a/content/manuals/ai/sandboxes/governance/org.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Organization policy -linkTitle: Org policy -weight: 20 -description: Centrally manage sandbox network and filesystem policies for your organization. -keywords: docker sandboxes, governance, organization policy, AI governance, admin console, network access, filesystem access -aliases: - - /ai/sandboxes/security/governance/ ---- - -[Local policies](local.md) give individual developers control over what their -sandboxes can access. Organization policy moves that control to the admin level: -rules defined in **Admin Console** apply to sandboxes across the organization, -either to every member or to specific teams. When organization governance is active, it replaces local `sbx policy` -rules entirely — local rules are no longer evaluated and can't be used to -supplement or override the organization policy. - -Admins can manage organization policies through the Admin Console UI or -programmatically using the [Governance API](/reference/api/ai-governance/). - -> [!NOTE] -> Sandbox organization governance is available on a separate paid -> subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. - -## Create a policy - -Manage policies under **Admin Console**, a section in the left-hand navigation -of [Docker Home](https://app.docker.com). Network and filesystem policies are -managed separately, under **Network access** and **Filesystem access**. - -To create a policy: - -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. -1. Select **Admin Console**, then **AI governance**. -1. Select **Network access** or **Filesystem access**, then **Create policy**. -1. Enter a **Policy name**. -1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, - choose the teams the policy applies to. See - [Scope policies to teams](#scope-policies-to-teams). -1. Select **Add rule** to add each rule. For rule syntax, see - [Policy concepts](concepts.md#rule-syntax). - -Existing policies are listed with their name, scope, rule count, and last -update. Use the action menu (⋮) to edit or delete a policy. - -## Network policies - -### Configuring org-level network rules - -A network rule takes a network target and an action (allow or deny). You can -add multiple entries at once, one per line. - -For the full syntax reference (exact hostnames, wildcard subdomains, port -suffixes, and CIDR ranges), see [Policy concepts](concepts.md#network-rules). - -When organization governance is active, local network rules are not evaluated. -The organization policy is the only policy in effect. `sbx policy ls` hides -these inactive local rules by default. See -[Monitoring](monitoring.md#showing-inactive-rules) for how to list them and read -the rule view. - -## Filesystem policies - -Filesystem policies control which host paths a sandbox can mount as -workspaces. By default, sandboxes can mount any directory the user has -access to. - -Admins can restrict which paths are mountable with filesystem allow and deny -rules. Each rule takes a path pattern and an action (allow or deny). - -For path pattern syntax including the difference between `*` and `**`, see -[Policy concepts](concepts.md#filesystem-rules). - -## Scope policies to teams - -An organization can have more than one policy, and each policy applies either -to the whole organization or to specific teams. Scoping lets you apply different -rules to different parts of the organization. - -A policy's [**Scope**](#create-a-policy) controls who it applies to. Set it to -**Organization** to apply the policy to every member, or to **Teams** to apply -it only to members of the teams you select. - -### Before you start - -Team scoping targets your organization's existing -[teams](/manuals/admin/organization/manage/manage-a-team.md), so a team must -exist before you can scope a policy to it. Create teams and manage their members -in one of two ways: - -- Manually, in the Admin Console. -- Automatically, by using - [group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md) - to synchronize your identity provider's groups with the teams in your - organization. Group mapping creates teams that don't already exist and keeps - their membership in step with your IdP groups. - -Because policies apply by team, a user's policies update automatically as their -team membership changes, including changes synced from your IdP. - -### How org-wide and team-scoped policies combine - -A user is governed by all of their -[effective policies](concepts.md#policy-scope) at once — every org-wide policy, -plus the team-scoped policies for the teams they belong to. The rules combine -into a single evaluation in which deny always wins, so a team-scoped policy can -grant access on top of the org-wide policies but can't loosen a restriction they -impose. For the full evaluation model, see -[Rule evaluation](concepts.md#rule-evaluation). - -This makes org-wide policies the natural home for guardrails that must hold -everywhere. For example, an org-wide policy can deny a category of domains for -all members, while a team-scoped policy grants a research team access to extra -package mirrors. Research-team members get the extra access, but the org-wide -deny still applies. - -## Precedence - -When organization governance is active, local rules are not evaluated. Only -organization rules set in the Admin Console determine what is allowed or denied, -and they can't be supplemented or overridden from a developer's machine. The -same applies to filesystem policies: organization rules replace local behavior -entirely. For how a user's organization policies are evaluated together, see -[Policy concepts](concepts.md#rule-evaluation). - -To unblock a domain when organization governance is active, update the rule in -the Admin Console or via the [API](/reference/api/ai-governance/). Without -organization governance, remove the local rule with `sbx policy rm`. - -## Troubleshooting - -### Policy changes not taking effect - -After updating organization policies in the Admin Console, changes take up -to 5 minutes to propagate to developer machines. To apply changes -immediately, users can run `sbx policy reset`, which stops the daemon and -forces it to pull the latest organization policies on the next `sbx` -command. - -> [!WARNING] -> `sbx policy reset` deletes all locally configured policy rules. The command -> prompts for confirmation before proceeding. - -### Sandbox cannot mount workspace - -If a sandbox fails to mount with a `mount policy denied` error, verify that -the filesystem allow rule in the Admin Console uses `**` rather than `*`. A -single `*` doesn't match across directory separators. diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md new file mode 100644 index 000000000000..5358776a0a49 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -0,0 +1,15 @@ +--- +title: Reference +weight: 50 +description: Reference material for Docker AI Governance policy APIs and policy syntax. +keywords: docker sandboxes, governance reference, governance API, policy reference +--- + +Use reference material when you need API details or exact policy syntax. + +- [Policy concepts](../concepts.md): resource model, rule syntax, policy + evaluation, and precedence. +- [AI Governance API](/reference/api/ai-governance/): HTTP API reference for + network and filesystem organization policies. +- [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, + attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/reference/api.md b/content/manuals/ai/sandboxes/governance/reference/api.md new file mode 100644 index 000000000000..36e6297f165b --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/api.md @@ -0,0 +1,11 @@ +--- +title: AI Governance API +linkTitle: API reference +description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON. +keywords: docker sandboxes, AI Governance API, governance API, policy API, organization policies +weight: 10 +build: + render: never +sidebar: + goto: /reference/api/ai-governance/ +--- diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md new file mode 100644 index 000000000000..2080e85a23ca --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -0,0 +1,201 @@ +--- +title: MCP policy reference +linkTitle: MCP policy +weight: 20 +description: Reference for Docker MCP policy actions, resources, attributes, context fields, and approval behavior. +keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources, requireApproval, AI Governance +--- + +MCP policies are organization policies written in Cedar using Docker's `MCP` +namespace. This reference defines the Docker-specific policy surface for Model +Context Protocol (MCP) activity made available to sandboxes through Docker's +[MCP gateway](../../mcp-gateway.md). + +Use this reference with [MCP access policies](../access-controls/mcp.md) for +common policy patterns. For the Cedar language, see the +[Cedar documentation](https://docs.cedarpolicy.com/). + +## Evaluation model + +Cedar evaluates MCP requests against a principal, action, resource, and context. +For Docker MCP policies, policy scope supplies the principal. Write policies +against the action, resource, and context. Clauses that reference principal +attributes, such as `principal in ...`, `principal.role`, or +`principal.tenant`, don't match. + +Governed MCP activity is default deny. A request is blocked unless a matching +`permit` allows it. A matching `forbid` overrides any `permit`, including a +permit annotated with `@requireApproval`. + +For details about when Docker Sandboxes evaluates MCP policies for a user, see +[Govern the server lifecycle](../access-controls/mcp.md#govern-the-server-lifecycle). + +An actionless `permit` matches every MCP action that reaches Cedar evaluation: + +```plaintext +permit (principal, action, resource); +``` + +## Actions + +| Action | Governs | Notes | +| ------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `register` | MCP server registration | Server registration needs an explicit `permit`. Use server attributes to scope registration. | +| `invokeTool` | MCP tool calls | Most tool access policies target this action. | +| `invokePrimordial` | Gateway meta-tool calls | Applies to built-in gateway tools such as `mcp-exec`, `mcp-add`, `code-mode`, and OAuth authorization helpers. | +| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. | +| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. | +| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. | +| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. | +| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. | + +## Resources + +Match resources with the MCP entity type and attributes for the request. + +| Entity | Match with | Notes | +| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `MCP::Server` | Registered server name | The canonical server identity is the `resource.identityURL` attribute, not the entity ID. | +| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. | +| `MCP::Resource` | Resource URI | Use `resource.uri`. | +| `MCP::Prompt` | Prompt name | Use `resource.name`. | +| `MCP::Primordial` | Gateway meta-tool name | Match a specific primordial with an entity reference. | + +Examples: + +```plaintext +resource in MCP::Server::"notion" +resource.name == "move_file" +resource.uri like "*/docs/*" +resource in MCP::Primordial::"code-mode" +``` + +## Resource attributes + +Tool annotation attributes come from MCP tool annotations or catalog metadata +and are advisory. + +| Attribute | Applies to | Notes | +| -------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `resource.name` | Tools and prompts | For tools, this is the bare tool name, not a display-prefixed name. | +| `resource.uri` | Resources | Use with string operators such as `like`. | +| `resource.readOnly` | Tools | Defaults to `false` when a tool doesn't declare it. | +| `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. | +| `resource.idempotent` | Tools | Defaults to `false` when a tool doesn't declare it. | +| `resource.openWorld` | Tools | Defaults to `true` when a tool doesn't declare it. | +| `resource.type` | Servers | Use for server registration rules. See [Server type values](#server-type-values). | +| `resource.identityURL` | Servers | Canonical server identity. The value depends on the registration type. See [Server identity values](#server-identity-values). | +| `resource.requiresOAuth` | Servers | Use for server registration rules. | +| `resource.requiresNetwork` | Servers | Use for server registration rules. | +| `resource.command` | Servers | Local stdio server command, such as `npx` or `docker`, when available. Empty for remote servers and registrations that don't include command details. | +| `resource.args` | Servers | Local stdio server arguments when available. This is a set, so `.contains()` can match values. Empty when no command details are available. | + +Use `like` for string attributes. In Cedar, `like` uses `*` as its wildcard, +matches the full string, treats `?` as a literal character, and treats `\*` as +a literal asterisk. + +Use `.contains()` only on set attributes, such as `resource.args`. On string +attributes, use `like`. + +### Server type values + +Local gateway registrations use these values: + +- `local-stdio`: a host-run stdio server. This includes explicit commands and + OCI-packaged stdio servers resolved from metadata with `--local`. +- `container-stdio`: an OCI-packaged server resolved from metadata without + `--local`. This value can appear in `register` decisions, but the local + gateway can't attach or run this server type. +- `remote-dcr`: a remote endpoint that doesn't require OAuth or supports OAuth + Dynamic Client Registration. +- `remote-no-dcr`: a remote OAuth endpoint that doesn't support Dynamic Client + Registration. + +### Server identity values + +For a remote server, `resource.identityURL` is the endpoint URL. For an explicit +local command, it is the resolved executable path on the host. For a `--local` +metadata registration, it is `local://stdio/<name>`, not the registry or +manifest URL. + +## Context fields + +| Field | Notes | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `context.request_time` | Bound for tool calls, built-in gateway tool calls, resource reads, and prompt retrieval. Registration requests don't include it. | +| `context.args` | Arguments for `invokeTool` and `invokePrimordial` requests evaluated by the gateway. Present when arguments are available as a JSON object. | + +A registration `permit` conditioned on `context.request_time` doesn't match, +so the registration falls to default deny. + +Guard tool-call argument rules with `context has args` and a field check: + +```plaintext +permit (principal, action == MCP::Action::"invokeTool", resource) +when { + resource.name == "approve_expense" && + context has args && + context.args has amount && + context.args.amount <= 500 +}; +``` + +A `permit` gated on missing arguments doesn't match, so the request falls to +default deny. A `forbid` gated on missing arguments doesn't match, so it +doesn't block the request. + +Only object-shaped tool arguments are represented in `context.args`. +Unsupported or malformed arguments are omitted. + +## Approval annotation + +Use `@requireApproval("reason")` on a `permit` statement to require in-session +confirmation through MCP elicitation before a matching request runs: + +```plaintext +@requireApproval("write tool call") +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == false }; +``` + +When a request matches the annotated `permit` and no `forbid` overrides it, the +policy engine returns an approval-required outcome. The annotation string is +shown as the elicitation reason. An approval-required outcome takes precedence +over a normal `permit`. A matching `forbid` denies the request without an +elicitation. + +For the request flow and trust model, see +[Require confirmation with MCP elicitation](../access-controls/mcp.md#require-confirmation-with-mcp-elicitation). + +Approval requires a client session that can present an MCP elicitation request +to the user. If the request can't be presented for approval, the request is +denied. Approval is an in-session confirmation, not an out-of-band approval +workflow. Each confirmation applies to one authorization request. After the +client confirms, the gateway re-evaluates the request with an approval digest. + +`sbx mcp add` can't present an elicitation request. A registration permit with +`@requireApproval` therefore results in a denial. + +Only the exact annotation name `@requireApproval` applies approval behavior. +Other annotation names, such as `@requireConsent` or `@requireConfirmation`, +don't require approval. + +## Limitations + +- Tool and resource listing actions aren't Cedar-gated. Listings can include + entries that a policy denies when the sandbox tries to use them. +- Approval-gated requests are denied when the execution context can't relay an + MCP elicitation to the originating client. This includes tool calls made from + inside `code-mode`. +- Registration policy is evaluated when a server is registered. It doesn't + remove existing registrations or stop an already-loaded server by itself. + Govern existing registrations with use-time rules such as `invokeTool`, + `readResource`, and `getPrompt`. +- Server command and argument rules using `resource.command` or `resource.args` + apply only when the resolved server registration includes local stdio command + details. Remote servers and metadata-resolved local servers can have empty + values for those attributes. Use `resource.type == "local-stdio"` to match + host-run servers independently of command details. +- Principal-based rules don't take effect. Use organization and team policy + scope to target users. +- Server groups aren't supported in MCP policy. Reference servers individually. diff --git a/content/manuals/ai/sandboxes/images/sbx-security.png b/content/manuals/ai/sandboxes/images/sbx-security.png deleted file mode 100644 index 0f86c436c507..000000000000 Binary files a/content/manuals/ai/sandboxes/images/sbx-security.png and /dev/null differ diff --git a/content/manuals/ai/sandboxes/install.md b/content/manuals/ai/sandboxes/install.md new file mode 100644 index 000000000000..cb4bcdfe1ebe --- /dev/null +++ b/content/manuals/ai/sandboxes/install.md @@ -0,0 +1,154 @@ +--- +title: Install Docker Sandboxes +linkTitle: Install +weight: 10 +description: Install the sbx CLI on macOS, Windows, or Linux and sign in to Docker Sandboxes. +keywords: sandbox, sbx, install, macOS, Windows, Linux, Ubuntu +--- + +Install the `sbx` CLI to run AI coding agents in local or cloud sandboxes. You +don't need Docker Desktop or Docker Engine to use `sbx`. Cloud sandboxes require +version 0.45.0 or later for the workflows in these guides. + +## Prerequisites + +The operating system and processor requirements apply to the CLI installation. +Hypervisor and KVM setup is required only to run local sandboxes. For cloud +account requirements, see [Cloud sandboxes](cloud/_index.md#prerequisites). + +### macOS + +- macOS Sonoma version 14 or later +- Apple silicon + +### Windows + +- Windows 11 +- A 64-bit Intel or AMD processor +- Windows Hypervisor Platform for local sandboxes + +To run local sandboxes, open an elevated PowerShell prompt and turn on Windows +Hypervisor Platform: + +```powershell +Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All +``` + +### Linux + +- Ubuntu 24.04 or later +- A 64-bit Intel or AMD processor, or a 64-bit Arm processor +- For local sandboxes, KVM hardware virtualization supported and turned on by + the CPU, and your user account in the `kvm` group + +To run local sandboxes inside a virtual machine or virtual desktop +infrastructure environment, the environment must support nested virtualization. +Cloud sandboxes don't require this setup. + +For local sandboxes, verify that KVM is available: + +```console +$ lsmod | grep kvm +``` + +A working setup shows `kvm_intel`, `kvm_amd`, `kvm_arm64`, or `kvm` in the +output. If the output is empty, run `kvm-ok` for diagnostics. The local sandbox +runtime requires KVM to start. + +Add your user to the `kvm` group: + +```console +$ sudo usermod -aG kvm $USER +``` + +Sign out and back in, or run `newgrp kvm`, for the group change to take effect. + +## Install on macOS + +Install `sbx` using Homebrew: + +```console +$ brew trust docker/tap +$ brew install docker/tap/sbx +``` + +## Install on Windows + +### Install for the current user + +Install `sbx` using Windows Package Manager: + +```powershell +winget install -h Docker.sbx +``` + +WinGet installs the per-user `DockerSandboxes.msi` package in +`%LOCALAPPDATA%\DockerSandboxes` and adds its `bin` directory to your user +`PATH`. You can install it without administrator privileges. + +### Install for all users + +For administrator-managed deployments, download +`DockerSandboxesMachine.msi` from the +[Docker Sandboxes releases](https://github.com/docker/sbx-releases/releases). +From an elevated PowerShell prompt, install the package silently: + +```powershell +msiexec.exe /i DockerSandboxesMachine.msi /quiet +``` + +The machine-wide package installs in `%ProgramFiles%\DockerSandboxes` and adds +its `bin` directory to the system `PATH`. + +A machine-wide upgrade might require restarting Windows if an `sbx` daemon in +another user's session is using the installed files. + +## Install on Ubuntu + +> [!NOTE] +> +> Docker does not test or support Docker Sandboxes on Ubuntu derivatives, such +> as Linux Mint and Pop!_OS. The convenience script can configure an incorrect +> package repository on these distributions. + +You can install `sbx` with Docker Engine or install only the `sbx` package. + +### Install Docker Engine and SBX + +Run Docker's convenience script with `SBX=1` to install Docker Engine and the +`docker-sbx` package together: + +```console +$ curl -fsSL https://get.docker.com | sudo SBX=1 sh +``` + +### Install SBX only + +To install `sbx` without Docker Engine on the host, add Docker's `apt` +repository and install the `docker-sbx` package: + +```console +$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh +$ sudo apt install docker-sbx +``` + +## Install from release artifacts + +To install `sbx` from a package or archive, follow the +[manual installation instructions](https://github.com/docker/sbx-releases#manual-install-from-release-artifacts). +The availability of a Linux release artifact does not indicate that Docker +tests or supports the corresponding distribution. + +## Sign in + +Sign in to Docker: + +```console +$ sbx login +``` + +The command opens a browser for Docker OAuth. See the [FAQ](faq.md) for why +sign-in is required and how Docker handles your data. + +After signing in, [run your first local sandbox](get-started.md) or +[get started with cloud sandboxes](cloud/_index.md#get-started). diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md new file mode 100644 index 000000000000..86624b79a9b0 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/_index.md @@ -0,0 +1,211 @@ +--- +title: Editor and app integrations +linkTitle: Integrations +weight: 70 +description: Connect editors and desktop apps to a Docker Sandbox over SSH. +keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote development, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These integrations use local sandbox SSH access. Cloud sandboxes use a +different SSH configuration and address: see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +You can connect an external editor or desktop app to a running sandbox over +SSH. This lets you use the tools you already know — VS Code, Cursor, Claude +Desktop, and others — while your code runs, builds, and executes inside the +isolated sandbox instead of on your host. + +Each sandbox is reachable at `<name>.sbx`, where `<name>` is the sandbox name. +Once SSH is set up, `<name>.sbx` behaves like any other SSH host, so any tool +that supports remote development over SSH can connect to it. + +## Prerequisites + +- The `sbx` CLI installed and signed in. See [Get started](../get-started.md). +- An SSH client. macOS and most Linux distributions include OpenSSH. On + Windows, install the OpenSSH client. +- The editor or app you want to connect, with its remote-over-SSH support + installed. + +## Enable SSH access + +Run the SSH setup command once: + +```console +$ sbx setup ssh +``` + +The command starts the Docker Sandboxes daemon if needed and configures your +SSH client. You can re-run it at any time. + +## Set up desktop app connections + +On macOS and Windows, Docker Sandboxes can add connections to ChatGPT and Claude +Desktop that create a dedicated sandbox on first use. This workflow uses a +workspace inside the sandbox. To work directly on a mounted host project, +[create a sandbox](#create-or-identify-a-sandbox) and connect to its hostname +instead. + +This setup requires Docker Sandboxes v0.48.0 or later. Launch each installed +app at least once, then quit the apps before running: + +```console +$ sbx setup ssh --auto-create +``` + +Setup adds the following connections to the apps and configures their SSH +hostnames. It creates the sandboxes when the connections are used. + +| App | Connection name | SSH hostname | Sandbox name | +| --- | --- | --- | --- | +| ChatGPT | Docker Sandbox (Codex) | `codex.sbx` | `ssh-codex` | +| Claude Desktop | Docker Sandbox (Claude) | `claude.sbx` | `ssh-claude` | + +Reopen each app and select its added connection. Connecting for the first time +creates the corresponding sandbox. Later connections reuse that sandbox and +its files, starting it if it is stopped. + +These sandboxes have no host workspace mounted. Clone your project inside the +sandbox and select its directory in the app's remote folder picker. Changes +stay inside the sandbox until you push them to a remote repository or copy +them out. + +Removing the sandbox with `sbx rm` leaves the app connection available. The +next connection creates a replacement sandbox without restoring deleted files. + +If setup reports that an app is running, quit it and rerun `sbx setup ssh`. +Setup also provides sign-in guidance if Docker or agent authentication is +missing. + +### Remove desktop app connections + +Quit ChatGPT and Claude Desktop, then run: + +```console +$ sbx setup ssh remove +``` + +This removes the managed SSH config and app connections. It leaves existing +sandboxes running or stopped as they were. Remove the sandboxes separately +with `sbx rm` if you no longer need them. + +## Create or identify a sandbox + +To connect using a sandbox name as `<name>.sbx`, create the sandbox first. +ChatGPT and Claude Desktop also support [creating a dedicated sandbox on first connection](#set-up-desktop-app-connections). +To create a named shell sandbox for the current directory: + +```console +$ sbx create --name demo shell . +``` + +To identify an existing sandbox, list your sandboxes: + +```console +$ sbx ls +``` + +## Connect to a sandbox over SSH + +Use the sandbox name with the `.sbx` suffix. For example, to connect to a +sandbox named `demo`: + +```console +$ ssh demo.sbx +``` + +## Select the workspace folder + +Connecting an app to a sandbox selects the remote environment, but it might not +open the primary workspace automatically. The initial folder depends on the +client. An interactive SSH shell starts in the sandbox workspace, matching +`sbx exec`. An editor's remote folder picker might open at the sandbox user's +home directory, `/home/agent`. Select the intended folder explicitly in the +editor instead of relying on its initial location. + +For a sandbox with a primary workspace, each workspace path appears inside the +sandbox at the same absolute path as on the host. For example, if you pass +`/Users/bob/src/my-project`, select that path in the remote folder picker. For +a mountless sandbox that uses a Docker-provided agent template, select +`/home/agent/workspace`. + +## Connect a specific tool + +- [VS Code](vscode.md) +- [Cursor](cursor.md) +- [Claude Desktop](claude-desktop.md) +- [ChatGPT](chatgpt.md) +- [T3 Code](t3-code.md) +- [Orca](orca.md) + +## How SSH connections work + +### Managed SSH configuration + +`sbx setup ssh` writes a managed block to your SSH config: `~/.ssh/config` on +macOS and Linux, or `%USERPROFILE%\.ssh\config` on Windows. The block is similar +to the following: + +```text +# >>> docker sandboxes (managed) >>> +Host *.sbx + User _default_user_ + ProxyCommand "sbx" ssh proxy %n + IdentityAgent none + IdentityFile /dev/null + IdentitiesOnly yes + ControlMaster no + ControlPath none + UserKnownHostsFile "~/.ssh/sbx_known_hosts" + KnownHostsCommand "sbx" ssh known-hosts %H + StrictHostKeyChecking yes +# <<< docker sandboxes (managed) <<< +``` + +You don't edit this block by hand. Its key entries work as follows: + +- `Host *.sbx` maps sandbox hostnames to the sandbox daemon. Application host + pickers don't discover individual sandbox names from this wildcard, so enter + the hostname, such as `demo.sbx`, manually when you configure an integration. +- `User _default_user_` tells the daemon to use the sandbox image's default + user, so your host username is never sent. + +### Connection and authentication + +Connections don't use a network port or an SSH key: + +- A `ProxyCommand` relays the SSH stream to the daemon over its local socket + (a Unix domain socket on macOS and Linux, a named pipe on Windows). +- The daemon accepts the connection only while you have an active Docker login. + Authentication is tied to your login, not to a stored key. +- The host key is verified on every connection, so a rotated daemon key never + triggers a host-key mismatch. + +Because SSH terminates at the daemon, no SSH server runs inside the sandbox. +For ordinary `<name>.sbx` connections, create the sandbox first. The +[desktop app connections](#set-up-desktop-app-connections) create their dedicated +sandboxes on first use. If a sandbox is stopped, connecting starts it +automatically. + +### Environment variables + +SSH connections don't forward client environment variables into the sandbox. +The daemon acknowledges SSH environment requests for compatibility but ignores +their names and values. + +### Port forwarding + +SSH clients can use local port forwarding to make a service listening on the +sandbox's loopback interface available on the host. For example, a remote +development client can map `127.0.0.1:4321` in the sandbox to +`127.0.0.1:55565` on the host, choosing an available host port automatically. +Traffic passes through the SSH connection instead of a published Docker port. + +The sandbox daemon accepts forwarded connections only to loopback addresses in +the sandbox, including `localhost`, `127.0.0.0/8`, and `::1`. The SSH client +chooses the bind address for the listener on the host. A listener bound to +`127.0.0.1` or `::1` is reachable only from the host. A client configured to +bind to a non-loopback address can make the forwarded service reachable from +other machines, subject to the host's network and firewall configuration. diff --git a/content/manuals/ai/sandboxes/integrations/chatgpt.md b/content/manuals/ai/sandboxes/integrations/chatgpt.md new file mode 100644 index 000000000000..32c8944fb9d2 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/chatgpt.md @@ -0,0 +1,75 @@ +--- +title: Connect ChatGPT to a sandbox +linkTitle: ChatGPT +weight: 40 +description: Run Codex in the ChatGPT desktop app against a Docker Sandbox over SSH. +keywords: docker sandboxes, chatgpt, codex, openai, remote ssh, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +Connect the ChatGPT desktop app to a sandbox over SSH so Codex works inside the +isolated environment instead of on your host. + +> [!NOTE] +> This page covers running Codex in the ChatGPT desktop app connected to a +> sandbox over SSH. To run the Codex CLI inside a sandbox directly, see +> [Codex](../agents/codex.md). + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- The ChatGPT desktop app installed. + +ChatGPT's remote server requires the `codex` command in the sandbox. The Codex +sandbox template used in the following section includes this command. + +## Connect + +For a dedicated sandbox created on first connection, see +[Set up desktop app connections](_index.md#set-up-desktop-app-connections). +The following steps connect to a sandbox with a mounted host workspace. + +Create a named Codex sandbox for the current directory if you don't already +have one: + +```console +$ sbx create --name demo codex . +``` + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +In the ChatGPT desktop app, open **Settings > Connections** and add an SSH +connection manually. Enter the sandbox hostname, such as `demo.sbx`, as the +host, then use the remote folder picker to +[select the mounted workspace](_index.md#select-the-workspace-folder) as the +remote project. + +For more connection options, see the OpenAI instructions to +[connect to an SSH host](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host). + +## Full access still prompts for approval + +ChatGPT controls Codex permissions separately from the Docker Sandbox. To run +commands without Codex approval prompts, select **Full access** from the +permissions menu for the remote chat. Enabling **Full access** under +**Settings > General** only adds the mode to the permissions menu. It doesn't +change an existing chat. + +If the chat continues to request approval while showing **Full access**, update +the ChatGPT desktop app, then stop and restart the active task. Approval prompts +that return after reconnecting can indicate a +[Codex remote-permission synchronization issue](https://github.com/openai/codex/issues/29054). + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up +- [Codex](../agents/codex.md) — run the Codex CLI inside a sandbox diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md new file mode 100644 index 000000000000..5439fff432e1 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md @@ -0,0 +1,99 @@ +--- +title: Connect Claude Desktop to a sandbox +linkTitle: Claude Desktop +weight: 30 +description: Run Claude Code from Claude Desktop against a Docker Sandbox over SSH. +keywords: docker sandboxes, claude desktop, claude code, remote ssh, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +Claude Desktop can run Claude Code on a remote machine over SSH. Point it at a +sandbox so the agent works inside the isolated environment instead of on your +host. + +> [!NOTE] +> This page covers Claude Desktop connecting to a sandbox over SSH. To run the +> Claude Code CLI inside a sandbox directly, see +> [Claude Code](../agents/claude-code.md). + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- Claude Desktop installed. + +Use a sandbox created with the Claude agent type. The Claude sandbox template +configures Anthropic credentials and network access for the remote Claude Code +session. + +## Connect + +> [!WARNING] +> Connecting Claude Desktop to a sandbox over SSH transmits Anthropic +> credentials into the Claude Code process within the sandbox, reducing +> isolation guarantees. + +For a dedicated sandbox created on first connection, see +[Set up desktop app connections](_index.md#set-up-desktop-app-connections). +The following steps connect to a sandbox with a mounted host workspace. + +Create a named Claude sandbox for the current directory if you don't already +have one: + +```console +$ sbx create --name demo claude . +``` + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +In Claude Desktop, open the environment drop-down before starting a session and +select **+ Add SSH connection**. Enter a name for the connection and enter the +sandbox hostname, such as `demo.sbx`, in **SSH Host**. Leave **SSH Port** and +**Identity File** empty because the managed SSH config supplies them. + +Select the connection from the environment drop-down, then use the remote +folder picker to +[select the mounted workspace](_index.md#select-the-workspace-folder). The +picker might initially open at `/home/agent`. + +For more connection options, see the Claude Desktop instructions for +[SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions). + +## Troubleshoot a broken SSH connection after token refresh + +The SSH connection drops when the Anthropic token expires and needs to be +refreshed. To work around this, run the sandbox manually from your host: + +```console +$ sbx run --name <sandbox-name> +``` + +## Troubleshoot SSH connection timeouts on Windows + +Claude Desktop requires Git on Windows. If an SSH connection times out and the +Claude Desktop logs include `ProxyCommand error: spawn sh ENOENT`, install +[Git for Windows](https://git-scm.com/download/win). + +If Git is already installed, verify that `sh.exe` is available on your `PATH`: + +```powershell +PS> where.exe sh +``` + +If the command doesn't find `sh.exe`, add the Git `bin` directory to your user +`Path`. The default directory is `C:\Program Files\Git\bin`. Quit and restart +Claude Desktop after updating `Path`. + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up +- [Claude Code](../agents/claude-code.md) — run the Claude Code CLI inside a + sandbox diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md new file mode 100644 index 000000000000..6ec238168806 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/cursor.md @@ -0,0 +1,50 @@ +--- +title: Connect Cursor to a sandbox +linkTitle: Cursor +weight: 20 +description: Use Cursor's Remote - SSH support to develop inside a Docker Sandbox. +keywords: docker sandboxes, cursor, remote ssh, remote development, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +Cursor is built on VS Code, so it connects to a sandbox the same way, using +Remote - SSH. Your editor stays on your host while files, terminals, and +extensions run in the isolated sandbox. + +> [!NOTE] +> This page covers the Cursor editor connecting to a sandbox over SSH. To run +> the Cursor agent CLI inside a sandbox instead, see +> [Cursor agent](../agents/cursor.md). + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- Cursor's Remote - SSH support installed. + +## Connect + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +1. Open the Command Palette and run **Remote-SSH: Connect to Host**. +2. Enter the sandbox host manually as `<name>.sbx`. +3. Cursor opens a new window connected to the sandbox. Use the remote folder + picker to [select the mounted workspace](_index.md#select-the-workspace-folder). + +## Notes + +- The first connection installs the editor server inside the sandbox, so it + can take a moment. Later connections are faster. + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up +- [Cursor agent](../agents/cursor.md) — run the Cursor CLI inside a sandbox diff --git a/content/manuals/ai/sandboxes/integrations/orca.md b/content/manuals/ai/sandboxes/integrations/orca.md new file mode 100644 index 000000000000..61d338ece311 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/orca.md @@ -0,0 +1,84 @@ +--- +title: Connect Orca to a sandbox +linkTitle: Orca +weight: 60 +description: Run Orca's coding agents and terminals against a Docker Sandbox over SSH. +keywords: docker sandboxes, orca, remote ssh, coding agents, remote development, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +Orca runs coding agents in parallel, each in its own git worktree. Orca has no +dedicated Docker Sandboxes integration: it treats the sandbox as an ordinary +SSH host, installs a small relay inside it, and runs agents, terminals, and git +there while the editor and diff views stay on your host. + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- Orca installed. + +Orca's remote terminals need `node-pty`, which ships prebuilt binaries only for +macOS and Windows. On a Linux sandbox it compiles from source, and that build +needs a C++ compiler. Docker-provided templates include one, so a sandbox +created from a template is ready to connect. + +A sandbox built from a custom +[base image](/manuals/ai/sandboxes/customize/author/base-images.md) without a +compiler still connects, and files, git, and the editor all work, but remote +terminals don't start. Add the toolchain to the image, or install it in the +running sandbox until you can: + +```console +$ sbx exec <sandbox> -- sudo apt-get update +$ sbx exec <sandbox> -- sudo DEBIAN_FRONTEND=noninteractive apt-get install -y build-essential +``` + +## Connect + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +1. In Orca, open **Settings → SSH** and select **Add Target**. +2. Enter the sandbox hostname, such as `demo.sbx`, as the host, and + `_default_user_` as the username. Keep the default port and leave the + identity file empty. +3. Select **Test** to check the connection, then **Save**. +4. Create a worktree and choose the sandbox under **Run on**. + +The first connection installs Orca's relay inside the sandbox, so it can take a +moment. Later connections are faster. + +`_default_user_` is the reserved username in the managed SSH configuration that +`sbx setup ssh` writes. It tells the daemon to run as the sandbox image's +default user. Any other username is taken literally as an in-sandbox user. + +## Run an agent + +Orca launches the agent you select for a worktree; a sandbox doesn't start one +for you. Orca pre-fills each agent's permission-bypass flag for new launches, +such as `--dangerously-skip-permissions` for Claude Code, which is how +`sbx run` starts the same agents. + +Orca only offers agents it finds installed on the host it connects to, so +create the sandbox with the agent you plan to drive: + +```console +$ sbx create --name demo claude . +``` + +Credentials stay on your host. If you store them as +[credentials](../configuration/credentials.md), the sandbox proxy injects them +when the agent makes a request, so the agent authenticates without the value +ever entering the sandbox. + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up diff --git a/content/manuals/ai/sandboxes/integrations/t3-code.md b/content/manuals/ai/sandboxes/integrations/t3-code.md new file mode 100644 index 000000000000..7d704206e461 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/t3-code.md @@ -0,0 +1,155 @@ +--- +title: Connect T3 Code to a sandbox +linkTitle: T3 Code +weight: 50 +description: Run T3 Code against a Docker Sandbox over SSH. +keywords: docker sandboxes, t3 code, remote ssh, remote development, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +T3 Code's SSH integration lets the desktop app drive coding agents inside a +sandbox. T3 Code has no dedicated Docker Sandboxes integration — it treats the +sandbox as an ordinary SSH host, connects to it, and starts a T3 server inside +that tunnels back to the app. + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- T3 Code installed. + +The first connection installs the T3 server in the sandbox. `t3` ships +prebuilt native modules for Linux, so nothing compiles, but those binaries +link against `libatomic1`. Docker-provided templates include it. + +The [`t3code` kit](https://github.com/docker/sbx-kits-contrib/tree/main/t3code) +goes further: it installs the `t3` npm package when the sandbox is created, +along with `libatomic1` if the base image lacks it, so the first connection +starts a server that is already there. Pair it with any agent whose base image ships +Node.js 18 or later, which all standard agent templates do: + +```console +$ sbx run claude --kit docker.io/sbx/t3code-kit:latest +``` + +A sandbox built from a custom +[base image](/manuals/ai/sandboxes/customize/author/base-images.md) without +`libatomic1` needs it installed before the first connection, unless you apply +the kit above, which installs it for you: + +```console +$ sbx exec <sandbox> -- sudo apt-get update +$ sbx exec <sandbox> -- sudo DEBIAN_FRONTEND=noninteractive apt-get install -y libatomic1 +``` + +Verify it's in place: + +```console +$ sbx exec <sandbox> -- sh -lc 'ldconfig -p | grep libatomic.so.1' +``` + +## Connect + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +In T3 Code, add an SSH environment and enter the sandbox hostname, such as +`demo.sbx`, as the host. The first connection installs the T3 server inside +the sandbox unless the `t3code` kit pre-installed it, so it can take a +moment. Later connections are faster. + +Then add a new project, select the SSH environment from the list, and +[choose the mounted workspace](_index.md#select-the-workspace-folder) as the +project directory inside the sandbox. + +## Troubleshoot a server that never becomes ready + +T3 Code can fail to connect with an error like the following, wrapped here +for readability. It concatenates the connection failure with npm's install +output from inside the sandbox into a single error dialog: + +```text +Could not prepare the SSH environment: ... SshCommandError: Connecting to +sandbox "sandboxes"… Remote T3 server did not become ready on +127.0.0.1:3773. npm WARN EBADENGINE Unsupported engine { package: +'ini@7.0.0', required: { node: '^22.22.2 || ^24.15.0 || >=26.0.0' }, +current: { node: 'v22.22.1', npm: '9.2.0' } } +``` + +The `npm WARN EBADENGINE` lines warn about the transitive `ini` dependency +and are separate from the failure: npm enforces engine requirements only +when `engine-strict` is set, which is off by default, so this warning alone +still lets the install proceed. + +The most common causes are a missing shared library and a full disk. Install +`t3` by hand and run it to tell them apart: + +```console +$ sbx exec <sandbox> -- sh -lc \ + 'rm -rf /tmp/t3probe && mkdir -p /tmp/t3probe && cd /tmp/t3probe \ + && npm init -y >/dev/null && npm install t3@latest 2>&1 | tail -20 \ + && ./node_modules/.bin/t3 --version' +``` + +A missing `libatomic1` lets the install finish and leaves a binary that can't +start: + +```text +node_modules/@t3code/t3-linux-x64/t3: error while loading shared libraries: +libatomic.so.1: cannot open shared object file: No such file or directory +``` + +Install it as described in [Prerequisites](#prerequisites). + +A full disk fails the install itself with `ENOSPC`: + +```text +npm ERR! code ENOSPC +npm ERR! nospc ENOSPC: no space left on device +``` + +Check free disk space: + +```console +$ sbx exec <sandbox> -- df -h / +``` + +A sandbox can have both problems at once. Fixing one still leaves the same +top-level error, so check the library and disk space before concluding the +sandbox is ready. Free up space or install `libatomic1` as needed, then +reconnect. + +## Troubleshoot `turn/setPermissionMode failed` + +If your organization manages Claude Code with a policy file, a local T3 Code +thread can fail to start with `turn/setPermissionMode failed`. T3 Code's +default runtime mode is Full access, which maps to the Claude Agent SDK's +`bypassPermissions` mode. A managed policy that disables that mode rejects +the request. + +On macOS, check whether this applies to you: + +```console +$ cat "/Library/Application Support/ClaudeCode/managed-settings.json" +``` + +If `permissions.disableBypassPermissionsMode` is set to `disable`, switch T3 +Code to a different runtime mode, such as Supervised, Auto-accept edits, or +Auto, then start a new thread. The permission mode is captured once when a +thread starts, so switching modes in an already-failing thread doesn't +recover it. + +This restriction applies to the host running Claude Code, not to a sandbox. +A thread connected to a sandbox isn't subject to the host's managed policy, +so Full access works normally there. + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md new file mode 100644 index 000000000000..28dcd329a352 --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/vscode.md @@ -0,0 +1,91 @@ +--- +title: Connect VS Code to a sandbox +linkTitle: VS Code +weight: 10 +description: Use VS Code Remote - SSH to develop inside a Docker Sandbox. +keywords: docker sandboxes, vs code, remote ssh, remote development, sbx +--- + +{{< summary-bar feature_name="Docker Sandboxes SSH" >}} + +These connection instructions use a local sandbox. For cloud SSH setup, see +[Connect with SSH](../cloud/usage.md#connect-with-ssh). + +Use the Remote - SSH extension to open a VS Code window that runs inside a +sandbox. Your editor stays on your host while files, terminals, and extensions +run in the isolated sandbox. + +## Prerequisites + +- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access). +- The [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) + extension (`ms-vscode-remote.remote-ssh`) installed in VS Code. + +## Connect + +Confirm that you can connect to the sandbox from a terminal: + +```console +$ ssh demo.sbx +``` + +In VS Code, open the Command Palette and run **Remote-SSH: Connect to Host...**. +Enter the sandbox hostname, such as `demo.sbx`, manually. After VS Code +connects, use the remote folder picker to +[select the mounted workspace](_index.md#select-the-workspace-folder). + +For more connection options, see the VS Code instructions to +[connect to a remote host](https://code.visualstudio.com/docs/remote/ssh#_connect-to-a-remote-host). + +## Notes + +- The first connection installs the VS Code server inside the sandbox, so it + can take a moment. Later connections are faster. + +### Reconnect loop on macOS + +Affected versions of VS Code can enter an infinite reconnect loop on macOS. If +this happens, set `remote.SSH.useLocalServer` to `false` in your VS Code user +settings: + +```json +{ + "remote.SSH.useLocalServer": false +} +``` + +For details, see +[microsoft/vscode-remote-release#11672](https://github.com/microsoft/vscode-remote-release/issues/11672). + +### SSH host key verification fails + +VS Code can leave duplicate or malformed `Host *.sbx` blocks in your SSH +config after you add an SSH host. If a VS Code connection reports a +`KnownHostsCommand` error or `Host key verification failed`, remove every SSH +config block marked `docker sandboxes (managed)`, including the marker +comments: + +```diff +-# >>> docker sandboxes (managed) >>> +-Host *.sbx +- User _default_user_ +- ProxyCommand "sbx" ssh proxy %n +- ... +- UserKnownHostsFile "~/.ssh/sbx_known_hosts" +- KnownHostsCommand "sbx" ssh known-hosts %H +- StrictHostKeyChecking yes +-# <<< docker sandboxes (managed) <<< +``` + +Then regenerate the managed block: + +```console +$ sbx setup ssh +``` + +Reconnect to the sandbox from VS Code. + +## Related + +- [Editor and app integrations](_index.md) — how SSH access works and how to + set it up diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md new file mode 100644 index 000000000000..12cee969dc3e --- /dev/null +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -0,0 +1,601 @@ +--- +title: MCP gateway +description: Register MCP servers, authorize OAuth-backed servers, and connect MCP tools to Docker Sandboxes. +keywords: docker sandboxes, sbx, MCP gateway, Model Context Protocol, MCP servers, sbx mcp, static MCP, OAuth +weight: 80 +--- + +This page describes the local MCP gateway. Cloud sandboxes use MCP servers +configured in Docker Agentic Platform: see +[Load an MCP server](cloud/usage.md#load-an-mcp-server). + +Docker Sandboxes includes an MCP gateway for connecting agents to Model Context +Protocol servers. The gateway gives the agent inside the sandbox one MCP +endpoint, while `sbx` manages the registered servers, OAuth credentials, and +sandbox lifecycle on the host. + +This is different from configuring an MCP server directly in an agent such as +Claude Code. Direct MCP setup configures that agent's own MCP client. With +Docker Sandboxes, you register MCP servers once on the host, and the sandbox +gateway exposes them to supported agents inside isolated sandboxes. That +host-managed gateway provides a single path for credentials, explicit server +loading, live updates, and organization governance. + +> [!NOTE] +> The Docker Sandboxes MCP gateway is separate from the Docker Desktop MCP +> Toolkit. You don't need the Docker Desktop MCP Toolkit to use `sbx mcp`, and +> MCP Toolkit server settings aren't shared with Docker Sandboxes. + +## Prerequisites + +- Sign in with `sbx login`. +- Use an agent integration that configures MCP at startup: Claude Code, Codex, + Devin, Gemini, Kiro, or OpenCode. +- For remote servers that require OAuth without Dynamic Client Registration, + register an OAuth client with the server provider. +- For `--local --url` registrations that resolve to OCI packages, use a host + with Docker installed and running. Docker is also required for explicit + `--command docker ...` registrations. + +## Quick start + +Start by registering one MCP server on the host: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +``` + +If the server requires OAuth, `sbx` opens an authorization flow before it stores +the registration. After registration, verify that the server is registered: + +```console +$ sbx mcp ls +``` + +The listing shows each server's transport, status, gateway, and details. + +Then start a sandbox and expose the registered server: + +```console +$ sbx run claude --name mcp-demo --static-mcp notion +``` + +The sandbox starts with an MCP gateway and pre-loads the `notion` server. The +registration remains on the host and can be reused by other sandboxes. + +## Register an MCP server + +`sbx mcp add` registers an MCP server by name. The registration records the +server definition on the host. It doesn't attach the server to a sandbox by +itself. To expose a registered server to a sandbox, pass it with +[`--static-mcp`](#use-static-mode) when you create the +sandbox, or use [`sbx mcp load`](#add-a-server-to-a-running-sandbox) for a +sandbox that's already running. + +Server names can contain letters, numbers, dots, hyphens, and underscores. + +The `--url` flag can point to different kinds of input. The execution location +depends on what you register: + +- A remote endpoint URL identifies a running MCP server. The server runs + remotely, and the sandbox gateway connects to it. +- A metadata URL with `--local` returns a registry entry, `server.json`, or + `server.yaml` that describes an OCI-packaged stdio server. `sbx` resolves the + image and runs it on the host with Docker. +- An explicit command runs on the host as a stdio MCP server. + +Local stdio servers run on the host, not inside the sandbox. The agent inside +the sandbox connects only to the MCP gateway. + +If a `--url` hostname resolves to a private, loopback, link-local, or cloud +metadata address, `sbx` registers the server but warns you about the resolved +address. Register only URLs you trust. Fetching a manifest from an untrusted +URL can expose internal services or cloud metadata, and DNS rebinding can +redirect a hostname after it has been checked. + +OAuth metadata discovery also warns and continues when it encounters these +addresses, including redirect destinations. +For a trusted internal server, pass `--skip-ssrf-check` to skip both the MCP +URL check and the OAuth metadata discovery checks and suppress their warnings. +Use the flag only when you trust the MCP host, OAuth provider, and all metadata +redirect destinations. + +### Remote endpoint URL + +For a remote MCP endpoint, pass the server URL: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +$ sbx mcp add linear --url https://mcp.linear.app/mcp +``` + +If requests to a remote server stall, see +[MCP server streams stall](troubleshooting.md#mcp-server-streams-stall). + +#### Custom request headers + +Use `--header 'Name: value'` to send custom HTTP headers to a remote MCP +endpoint, for example to authenticate with an API key. Repeat the flag for +each header, using each header name once: + +```console +$ sbx mcp add acme --url https://mcp.acme.com/mcp \ + --header 'Authorization: Bearer ${api-key}' \ + --header 'Accept: application/json, text/event-stream' +$ sbx secret set mcp:acme:api-key +``` + +Replace the example URL with your MCP endpoint. The `sbx secret set` command +prompts for the API key and stores it in the +[host credential store](configuration/credentials.md#where-secrets-are-stored). +The `${api-key}` placeholder stays in the registration. When a sandbox +connects, the gateway reads the secret and substitutes its value in the header. +Use single quotes around header values so your shell preserves placeholders. +Placeholders name stored secrets, not environment variables: `${api-key}` +reads `mcp:acme:api-key`, regardless of your shell environment. + +Store each placeholder with `sbx secret set mcp:<server>:<placeholder>`. +Credential headers such as `Authorization` must use a secret placeholder. +An explicit `Authorization` header takes precedence over an OAuth access token. + +After storing the secret, expose the server to a sandbox: + +```console +$ sbx run claude --name acme-demo --static-mcp acme +``` + +Custom headers require a remote HTTP endpoint and can't be used with +`--command` or `--local`. They also require the host to connect to the server. +The hosted gateway rejects these registrations unless you supply +`--oauth-authorization-server`, which routes the connection through the host. + +#### Manage header secrets + +Header secrets use the global scope on the host. Set them with +`sbx secret set mcp:<server>:<placeholder>` without `--sandbox`. +Header secrets require a stored value and don't support `--ref` or `--command` +dynamic sources. +To check the header templates and whether their secrets are set, run +`sbx mcp inspect acme`. The command doesn't display resolved secret values. + +The secret store also contains an automatically managed `:endpoint` record, +such as `mcp:acme:api-key:endpoint`. This metadata binds the secret to the +registered server's URLs so the gateway can detect an endpoint change before +sending the secret. You don't need to set this record yourself. If you change +the server's endpoint, follow the CLI guidance to set the secret again for +that endpoint. + +To rotate a header secret, run `sbx secret set` with the same name. After +setting, changing, or removing a header secret, stop and restart the sandbox +or restart `sandboxd` to apply the change to an existing gateway. An existing +connection keeps its previous value, and a server skipped because its secret +was missing isn't retried automatically. + +Removing a registration with `sbx mcp rm` keeps its header secrets and prints +commands to remove them. To remove the example secret: + +```console +$ sbx secret rm mcp:acme:api-key +``` + +### Local stdio server + +Some MCP servers communicate over stdio instead of exposing a remote HTTP +endpoint. Use a local stdio server when `sbx` should launch the MCP server on +the host. You can provide a metadata URL or an explicit command. + +#### From registry or manifest metadata + +Use `--local --url` when you have an MCP community registry URL or a URL that +returns a `server.json` or `server.yaml` document. The registry entry or +manifest must describe an OCI package that uses stdio transport. `sbx` doesn't +launch non-OCI package types, such as `npm`, from metadata. To use those +servers, register an explicit command. + +This path resolves the image from the metadata and starts it on the host with +Docker, so Docker must be installed and running on the host. + +```console +$ sbx mcp add fetch --local \ + --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest +``` + +If the entry doesn't publish an OCI stdio package, `sbx` rejects the +registration instead of starting it locally. + +A server manifest describes the MCP server package and how to start it. It can +be hosted on a GitHub raw URL, internal HTTP server, or CDN. + +```console +$ sbx mcp add opine --local --url https://example.com/mcp/opine/server.yaml +``` + +#### From an explicit command + +Use `--command` when you already know the executable and arguments, or when you +need custom Docker flags. The command can be a package runner such as `npx` or +a Docker container command: + +```console +$ sbx mcp add playwright --command npx --args @playwright/mcp@latest +$ sbx mcp add local-image-server --command docker \ + --args "run,-i,--rm,your/image" +``` + +To set the working directory for the host process, pass `--dir`. This flag is +only valid with `--command`: + +```console +$ sbx mcp add local-fs --command node --args server.js --dir /srv/data +``` + +Use registry or manifest metadata when you have a published server definition +and don't need to customize `docker run`. Use `--command` for local +development, private servers, or custom container flags. + +> [!WARNING] +> Local stdio servers run on the host, outside sandbox isolation. If the command +> starts a Docker container, that container uses host Docker isolation, not +> sandbox isolation. The process or container can access host files, host +> network resources, and credentials made available to it. Use trusted commands +> and images, and avoid mounting host paths or passing credentials unless the +> server needs them. + +### Docker Hardened Image + +For an MCP server packaged as a Docker Hardened Image, pass its `dhi.io` +reference instead of a registry or manifest URL: + +```console +$ sbx mcp add fetch --url dhi.io/fetch-mcp:latest +``` + +Use a tag or digest: `dhi.io/<IMAGE>:<TAG>` or +`dhi.io/<IMAGE>@sha256:<DIGEST>`. For images from other registries, use a +server-manifest URL or an [explicit command](#from-an-explicit-command). + +## Authorize OAuth-backed servers + +If a registered remote server requires OAuth, `sbx mcp add` starts the +authorization flow by default: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +``` + +OAuth credentials stay on the host. In local gateway mode, `sbx` stores tokens +in the host operating system's credential store. + +To register an OAuth-backed server without authorizing it, pass `--skip-auth`: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp --skip-auth +``` + +### Use a pre-registered OAuth client + +In local gateway mode, you can register a remote OAuth server that doesn't +support Dynamic Client Registration. If the server publishes OAuth metadata, +pass the client ID that you registered with the server provider: + +```console +$ sbx mcp add slack --url https://slack.example.com/mcp \ + --client-id <CLIENT_ID> +``` + +If the server doesn't publish OAuth metadata, pass +`--oauth-authorization-server` with the client ID. The flag accepts a local +file path or an HTTP or HTTPS URL to an RFC 8414 authorization server metadata +document. The document must define `authorization_endpoint` and +`token_endpoint`: + +```console +$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \ + --oauth-authorization-server ./serverx-authorization-server.json \ + --client-id <CLIENT_ID> +``` + +These flags are only valid with `--url`. + +For a confidential OAuth client, store the client secret before registering +the server. There is no `--client-secret` flag: + +```console +$ sbx secret set mcp:slack:client_secret +$ sbx mcp add slack --url https://slack.example.com/mcp \ + --client-id <CLIENT_ID> +``` + +The client secret stays in the host credential store and isn't +written to the MCP registration. If the server requires a confidential client +and no secret is stored, registration succeeds but authorization is skipped. +Store the secret, then run `sbx mcp auth <server>`. + +#### Change the OAuth client + +If you re-register a server name with a different client ID, issuer, or token +endpoint, `sbx` refuses to use the secret bound to the previous client. +After verifying that the registration points to the intended client and +provider, store that client's secret, clear the old binding, and authorize: + +```console +$ sbx secret set mcp:slack:client_secret +$ sbx secret rm mcp:slack:client_secret:identity +$ sbx mcp auth slack +``` + +Setting a secret alone doesn't clear the old binding. The `:identity` record +is metadata that binds the stored secret to its OAuth client. Authorization +records the binding for the new client. + +For secrets stored under the legacy name `mcp:<server>.client_secret`, set +the secret again using `mcp:<server>:client_secret`. + +### Set OAuth scopes + +Use the repeatable `--scope` flag to record the default scopes requested during +authorization: + +```console +$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \ + --scope read --scope write +``` + +The `sbx mcp auth` command accepts `--scope` to override the recorded defaults +for one authorization: + +```console +$ sbx mcp auth serverx --scope read +``` + +Unless you pass `--no-scope`, `sbx` requests the first available scope set in +the following order: + +1. Scopes passed to `sbx mcp auth --scope` +2. Default scopes recorded by `sbx mcp add --scope` +3. Scopes that the protected resource says it requires +4. Whichever of `openid`, `email`, `profile`, and `offline_access` the + authorization server advertises + +If none of these provide a scope set, `sbx` omits the OAuth `scope` parameter so +the authorization server applies its default grant. Other advertised scopes +aren't included in the fallback. + +When `sbx` uses recorded defaults or resource-required scopes, it also +requests `offline_access` if the authorization server advertises it. The +server can then issue a refresh token, so you don't have to authorize again +when the access token expires. Scopes passed to `sbx mcp auth --scope` are +requested exactly as given, without `offline_access`. Existing credentials +issued without a refresh token aren't upgraded; run `sbx mcp auth` again to +request a new grant. + +Pass `--no-scope` to suppress the recorded defaults, resource-required scopes, +and advertised scope fallback for one authorization, without changing the +stored defaults: + +```console +$ sbx mcp auth serverx --no-scope +``` + +You can't combine `--no-scope` with `--scope`. Scopes you choose are checked +against the authorization server's advertised scopes and the resource's +required scopes. If either source publishes scopes, a scope present in neither +produces a warning but is still requested. The authorization server can still +refuse an advertised scope for a particular +client. For a local authorization flow that requested scopes, `sbx` lists the +requested, advertised, and refused scopes and suggests a retry command. If the +server identifies the refused scopes, the command removes them. Otherwise, it +uses `--no-scope`. +`sbx` never retries automatically. + +For each OAuth-backed remote server exposed to a sandbox, the gateway exposes a +helper tool named `<server>-authorize`, such as `notion-authorize`. The agent can +call the tool to authorize or reauthorize the server. If the server isn't +authorized, the helper is the only tool exposed for that server. + +You can manage OAuth credentials from the host: + +```console +$ sbx mcp auth status notion +$ sbx mcp auth notion +$ sbx mcp auth rm notion +``` + +Use `--all` to apply `auth`, `auth status`, or `auth rm` to all registered +OAuth-backed servers. The `auth status` output reports the scopes granted by the +authorization server, the defaults recorded with `sbx mcp add --scope`, and the +scopes the server supports. It collapses duplicate scope names and highlights +granted scopes that weren't requested or are no longer in the supported set. +Use `--json` for machine-readable output: + +```console +$ sbx mcp auth status notion --json +``` + +### Override the OAuth resource indicator + +Use `--resource` when your OAuth provider requires a token audience that +differs from the resource identifier discovered by `sbx`. By default, `sbx` +uses the server's protected-resource metadata, or the endpoint URL if the +metadata is absent. Check the value with `sbx mcp inspect <SERVER>` before +setting an override: + +```console +$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \ + --resource https://api.serverx.example/mcp +``` + +Use the resource URI supplied by your provider. It must have a scheme and host +and no fragment. To change an existing registration's value, remove the +registration and add it again. + +This override requires OAuth authorization on the host. The hosted gateway +doesn't use it unless you also supply `--oauth-authorization-server` or +`--client-id` to route authorization through the host. Without those flags, +`sbx mcp add` warns that the hosted gateway won't use the override. + +## Choose an MCP mode + +Every sandbox starts an MCP gateway. When the sandbox starts, supported agent +integrations read the gateway URL and register it with the agent. + +Whether you pass `--static-mcp` when you create the sandbox determines its MCP +mode: + +- Static mode pre-loads the specified servers and doesn't expose dynamic + discovery tools to the agent. +- Dynamic mode pre-loads no servers and lets the agent find and attach + registered servers. + +This choice persists across sandbox restarts unless you +[unload every server in the static set](#remove-a-server-from-a-running-sandbox). + +### Use static mode + +Pass `--static-mcp` to pre-load registered MCP servers: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +$ sbx mcp add linear --url https://mcp.linear.app/mcp +$ sbx run claude --name my-session --static-mcp notion,linear +``` + +You can pass `--static-mcp` as a comma-separated list or repeat the flag: + +```console +$ sbx run claude --name my-session \ + --static-mcp notion --static-mcp linear +``` + +Every name in the static set must already be registered with `sbx mcp add`. The +gateway doesn't expose `mcp-find`, `mcp-add`, or `mcp-config-set` to the agent. + +You can't replace the initial set by passing `--static-mcp` when reconnecting to +an existing sandbox. To attach another server from the host, use +[`sbx mcp load`](#add-a-server-to-a-running-sandbox). + +### Use dynamic mode + +Omit `--static-mcp` to use dynamic mode. The gateway pre-loads no servers and +exposes `mcp-find`, `mcp-add`, and `mcp-config-set` to the agent. The agent can +search the registered server catalog and attach servers during the session. + +If you run `sbx mcp add` after a dynamic sandbox starts, its gateway refreshes +the searchable catalog. The agent can then find and attach the new registration +without restarting. The `sbx mcp add` command doesn't attach the server by +itself. + +## Add a server to a running sandbox + +To attach an already-registered server to a running sandbox, use +`sbx mcp load`. This works in both static and dynamic modes: + +```console +$ sbx mcp add linear --url https://mcp.linear.app/mcp +$ sbx mcp load linear --sandbox my-session +``` + +Connected agent sessions receive a tool-list update, so the added tools become +visible without reconnecting. The loaded server remains attached across sandbox +restarts. + +## Remove a server from a running sandbox + +In Docker Sandboxes v0.48.0 and later, use `sbx mcp unload` to detach a server +from a running sandbox's local MCP gateway. This works in both static and +dynamic modes. Cloud sandboxes and hosted MCP gateways don't support unloading +servers. + +```console +$ sbx mcp unload linear --sandbox my-session +``` + +Connected agent sessions receive a tool-list update, so the server's tools are +removed without restarting the agent. The command also removes the saved +attachment so the server isn't restored when the sandbox or daemon restarts. +The server's host registration and credentials remain available, and other +sandboxes that have loaded the server are unaffected. + +To attach the server again: + +```console +$ sbx mcp load linear --sandbox my-session +``` + +In dynamic mode, the agent can also find and attach the registered server +again. Unloading a server doesn't prevent the agent from reloading it. + +If you unload all servers from a static sandbox, it stays in static mode for +the current session. After restarting the Docker Sandboxes daemon and +reconnecting, the agent can find and attach registered servers. + +## Built-in gateway tools + +The local MCP gateway exposes a small set of built-in tools. These tools belong +to the gateway itself, not to a registered MCP server. Agents can see and call +them on the same MCP connection as server tools, so they can appear in agent +tool lists, logs, policy decisions, audit logs, or approval prompts. + +You don't need to call these tools directly for normal setup. Use `sbx mcp` +commands to register servers and manage credentials from the host. The tools +matter because agents can call them during a session, and admins can govern +them separately from tools provided by registered MCP servers. + +| Tool | Description | +| -------------------- | ------------------------------------------------------------------------------------------ | +| `mcp-exec` | Executes a tool by name through the gateway. | +| `code-mode` | Creates an ephemeral JavaScript tool that can call selected tools through the MCP gateway. | +| `mcp-find` | Searches the registered server catalog without changing sandbox state. Dynamic mode only. | +| `mcp-add` | Attaches a registered server to the sandbox. Dynamic mode only. | +| `mcp-config-set` | Sets per-session configuration overrides for an attached server. Dynamic mode only. | +| `<server>-authorize` | Starts or restarts OAuth authorization for an exposed OAuth-backed remote server. | + +Servers attached with `mcp-add` remain attached across sandbox restarts. The +gateway exposes `<server>-authorize` for OAuth-backed remote servers, even when +they already have a valid token. Local stdio servers don't expose this helper. +If `code-mode` creates a generated tool, the tool is shared by clients connected +to the sandbox's gateway and disappears when the gateway is replaced or stops. + +In MCP access policies, built-in gateway tools are `MCP::Primordial` resources +and use the `invokePrimordial` action. Tools from registered MCP servers are +`MCP::Tool` resources and use the `invokeTool` action. For details, see the +[MCP policy reference](governance/reference/mcp-policy.md). + +## Manage registrations + +List registered servers: + +```console +$ sbx mcp ls +``` + +Inspect a registered server: + +```console +$ sbx mcp inspect notion +``` + +Remove a registered server: + +```console +$ sbx mcp rm notion +``` + +Removing a registration doesn't detach the server from sandboxes that have +already loaded it. Use +[`sbx mcp unload`](#remove-a-server-from-a-running-sandbox) for each sandbox +before removing the registration. + +For OAuth-backed servers, `sbx mcp rm` removes the OAuth access token before it +removes the server registration. A client secret for a pre-registered OAuth +client and its identity binding remain in the host credential store so you can +reuse them when you re-add the same client. The command prints the +`sbx secret rm` commands for removing them. To remove only the OAuth access +token, use `sbx mcp auth rm`. + +## Governance + +Organizations with AI Governance can use +[MCP access policies](governance/access-controls/mcp.md) to control MCP server +registration, tool calls, gateway meta-tools, resources, prompts, and approval +requirements. MCP access policies are organization policies written in Cedar. diff --git a/content/manuals/ai/sandboxes/release-notes.md b/content/manuals/ai/sandboxes/release-notes.md index 19cb21f2c8ae..8646ebb8db09 100644 --- a/content/manuals/ai/sandboxes/release-notes.md +++ b/content/manuals/ai/sandboxes/release-notes.md @@ -3,6 +3,7 @@ title: Docker Sandboxes release notes linkTitle: Release notes description: New features, bug fixes, and changes in Docker Sandboxes keywords: docker sandboxes, sbx, release notes, changelog +weight: 150 toc_min: 1 toc_max: 2 tags: @@ -15,240 +16,277 @@ the full release history, including pre-releases and downloads, see the <!-- BEGIN GENERATED RELEASES --> -## 0.32.0 +## 0.49.1 -{{< release-date date="2026-06-09" >}} +{{< release-date date="2026-10-20" >}} -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.32.0) +[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.49.1) ### Highlights -**[Audit logging](https://docs.docker.com/ai/sandboxes/governance/audit/)**: Sandboxes now emit structured JSONL audit records for policy decisions. Records are written to a per-OS log directory and can be forwarded to any SIEM platform for enterprise compliance workflows. Requires a Docker AI Governance subscription. +Docker Sandboxes v0.49.1 improves kit compatibility, proxy support for cloud connections, and sandbox shutdown reliability. -**[Sign-in enforcement](https://docs.docker.com/ai/sandboxes/governance/sign-in-enforcement/)**: Administrators can now require Docker organization membership verification. Enforcement is deployed via standard endpoint management tooling: configuration profiles on macOS, the registry on Windows, and a JSON policy file on Linux. This closes the gap for organizations that need to ensure only authenticated, authorized users run AI coding agents. +> [!NOTE] +> v0.49.0 was skipped. These release notes cover all changes since v0.48.0. -### What's New - -#### CLI - -- Offer an interactive "Sign in with ChatGPT" OAuth flow on the first `sbx create`/`sbx run codex` when no Codex credentials are configured. -- Pre-select `balanced` as the highlighted default in the first-run network policy prompt, so pressing Enter accepts the recommended policy. -- Make global the default scope for `policy network allow|deny` and `policy rm`; add `--sandbox` to target a specific sandbox and drop the `-g/--global` flag. -- Simplify `sbx version` to a single line by default; gate detailed information behind `-D/--debug`. -- Unhide `sbx secret set-custom`, a command for [setting custom secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#custom-secrets), and mark it as experimental. - -#### Secrets - -- Add OpenRouter as a built-in service provider, so `sbx secret set <sandbox> openrouter` works without `set-custom` and the proxy injects `Authorization: Bearer <token>` automatically. -- Fall back to an encrypted on-disk secrets store on Linux/WSL hosts where no working keychain is available, with a one-time warning on secret-writing paths including `sbx login`. -- Substitute custom-secret sentinels inside HTTP Basic auth payloads, so credentials referenced in `Basic` Authorization headers are resolved like other sentinel shapes. - -#### Networking - -- Hide inactive governed policy rules by default in `sbx policy ls` and the TUI Network Rules view, with governance/sync status, hidden-rule indicators, and an `--include-inactive` flag (TUI `i` toggle) to reveal them. -- Route OAuth/browser-open requests to the caller's graphical session, fixing `/login` opening on the host's display instead of the SSH terminal that invoked it. +### What's new #### Kits -- Support the v2 OCI kit artifact format end-to-end, so kits are standard OCI images that registries and OCI tooling (Hub, `oras`, `crane`, `skopeo`) can introspect without kit-specific knowledge. -- Write `files/workspace/<path>` kit entries correctly when `sbx run --clone` is used; previously the file hook fired before the in-container clone populated the workspace and failed the sandbox start. - -#### Performance +- `sbx kit validate` and `sbx kit inspect` accept `--offline` to check a local directory or ZIP kit without starting the daemon or signing in. +- Creating sandboxes from local or Git v3 kits honors build-time `--kit-arg` values, including scoped overrides. +- Sandboxes combining multiple agent kits, such as Claude and Codex, start successfully and receive guidance in each agent's context file. +- On Windows, sandboxes can combine workload and mixin kits, including kits loaded through Windows junctions. +- Kits declaring multiple OAuth credentials authenticate every declared service. +- `sbx kit sign` warns when Git would change the signed file contents and invalidate signatures for `git+` references. +- Reading a kit directory rejects unsupported entries, such as named pipes and device nodes, instead of hanging. `sbx kit pack` rejects symlinks that would produce an archive Sandboxes cannot load. -- Keep virtiofs caching enabled for sandboxes using `--clone`, avoiding a FUSE round-trip on every `stat()` and speeding up `git status`, `grep -r`, and tree walks inside the sandbox. +#### Sandbox lifecycle and workspaces -#### Packaging +- SSH sessions start in the sandbox workspace, matching `sbx exec`. +- SSH-agent access granted by a kit continues working in running sandboxes after the daemon restarts. +- In newly created local sandboxes, Git preserves the host's ignore decisions for paths already present in the primary workspace. This applies to primary workspaces mounted at a Git repository root. +- Sandbox startup waits for Docker to become ready without launching competing Docker daemons. +- Daemon shutdown and sandbox reset no longer hang indefinitely when Docker is unresponsive or a kit registry operation stalls. +- Sandbox reset handles concurrent operations more reliably, avoids false cleanup warnings, and identifies sandboxes it could not fully remove. +- Port changes fail cleanly during sandbox creation or deletion, avoiding stale host bindings. +- SSH connection attempts fail cleanly when the daemon is shutting down. +- Cursor sandboxes no longer show an unexpected Workspace Trust prompt for workspace paths containing characters such as `.` or `_`. -- Require the system keyring dependency in Linux packages so credential storage works out of the box. +#### Networking and cloud sandboxes -#### Documentation +- Explicit CIDR deny rules take precedence over matching domain allow rules when Sandboxes resolves the destination address. +- Cloud commands, `sbx move`, the TUI, and cloud SSH honor configured proxies, including system and PAC proxies. Set `proxy.sshDirect` to `true` to connect cloud SSH directly on networks that permit direct SSH connections. +- `sbx mcp add` completes OAuth discovery on networks that require an HTTP proxy, without needing `--skip-ssrf-check`. +- Fixed uploads stalling while waiting for HTTP 100 Continue through intercepted HTTPS connections. +- Fixed a Windows system-proxy watcher hang that could prevent the daemon from stopping. +- Image pulls from `public.ecr.aws` work under the `balanced` network policy. +- `sbx policy refresh` immediately refreshes policy, for example after an AI Governance change, instead of waiting for the next polling interval. Existing connections remain open. +- `sbx policy ls` continues showing `default-deny-all` after a kit adds network rules. +- Cloud connection and authentication errors include guidance for resolving the problem. -- Replace stale `--branch`/worktree guidance in generated agent guidance (CLAUDE.md/AGENTS.md) with `--clone`, including how to sync host commits via `/run/sandbox/source`. +#### Authentication and MCP -#### Bug Fixes +- Custom secrets using `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` appear in the sandbox as expected. +- `sbx secret set-custom` warns before replacing a different host or environment-variable mapping under the same placeholder. +- `sbx secret rm` returns an error when no secret matches `--registry`, `--placeholder`, `--host`, or `--env-name`. +- MCP gateway code-mode tools work on Windows hosts. -- Fix an issue with `sbx secret set <sandbox> <service>` silently dropping credentials while reporting success. -- Migrate stale runtime `SocketPath` references on daemon restart, so sandboxes upgraded from v0.31.0 stay visible to `sbx ls` after `/tmp` is cleaned. -- Keep non-interactive `sbx exec` output intact by not tearing down the attach-exec bridge on stdin EOF (no more spurious empty output with exit code 0). -- Clear stale pending status in the TUI when a network deny rule is deleted, so a host no longer shows as Blocked after its rule is removed. -- Bind MCP gateway state to the daemon-assigned runtime instance so a same-name sandbox recreate cannot leave Claude pointed at a stale gateway port. -- Set the default network policy before launching the TUI to avoid spurious 412 errors from policy-rule requests. -- Stop counting expected `rm`/`stop`/list-ports "not found" 404s as analytics failures, so routine existence checks no longer inflate error dashboards. -- Require a daemon restart (instead of failing with `405 Method Not Allowed`) when downgrading the CLI below a newer running daemon. +#### CLI, settings, and diagnostics -## 0.31.3 +- `sbx policy ls`, `sbx settings ls`, and `sbx policy approval ls` accept `-q` to print only rule IDs, setting keys, or approval IDs. +- Configure daemon log size and retention with `sbx settings set` using `daemon.log.maxSizeMB`, `daemon.log.maxBackups`, and `daemon.log.maxAgeDays`. +- The `browser.enabled` setting controls whether sandboxes can open the host browser. +- `sbx env` reports unknown keys and invalid values with their source file, line, column, and field. Invalid values in a base file must be fixed even if a later file overrides them; this also applies to `~/.sbxenv.yaml` and `sbx env rm`. +- `sbx settings set` rejects incorrectly structured values for `kit.allowedSources` and `kit.trustedSigners` before saving them. +- `sbx cp` clearly reports a missing destination directory without extra tar errors. +- `sbx diagnose` reports running CLI and shim processes, warns when global network policy is not initialized, and detects a ZFS setting that can make image builds unusually slow. -{{< release-date date="2026-06-03" >}} +#### Templates and installation -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.3) +- Full templates now include a C/C++ toolchain for compiling native code inside the sandbox. +- The Linux tarball installer works for regular users on systems with AppArmor. -### Bug Fixes +## 0.48.0 -- Fix a failure to start sandboxes that were created with older versions of the CLI. -- Fix a file descriptor leak on Linux. Each credential lookup left a session - D-Bus socket open, so long-running processes (such as the daemon) could - gradually accumulate open file descriptors and eventually hit the session - bus's connection limit, failing with "The maximum number of active - connections has been reached." Connections are now closed after each - operation. macOS and Windows were not affected. +{{< release-date date="2026-10-13" >}} -## 0.31.2 +[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.48.0) -{{< release-date date="2026-06-01" >}} +### Highlights -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.2) +Docker Sandboxes v0.48.0 updates the CLI across all commands, with consistent terminal output and JSON/YAML formats. This changes flags, structured output, and prompts used by existing scripts. Review the migration details below before upgrading automated workflows. -### Highlights +The release also adds managed Codex and Claude Desktop SSH targets on macOS and Windows, additional v3 kit capabilities, and support for adding kits with startup commands to existing sandboxes. -This patch release resolves two reliability issues. It **fixes a Windows issue** where odd default sandbox memory values could lead to startup timeouts. It also includes a **daemon-compatibility fix** that prevents a silent failure (`405 Method Not Allowed`) when the `sbx` CLI is downgraded while a newer `sandboxd` daemon is still running — the CLI now requires a daemon restart instead. +### Breaking changes -### What's New +#### CLI flags, output, and automation -#### Bug Fixes +The CLI refactor changes both interactive use and scripting interfaces. Existing `--json` parsers may need updates even if their command lines still work. Scripts that parse human-readable output must switch to `--format json` or `--format yaml`. -- Fix a Windows issue where odd default sandbox memory values could lead to startup timeouts. -- Require a daemon restart when downgrading the CLI below a running daemon, instead of silently proceeding into a `405 Method Not Allowed` error. +##### Update command flags -## 0.31.1 +| Command | Previous spelling | Replacement or behavior | +| --- | --- | --- | +| `sbx run`, `sbx env run` | `--detached` | Use `--detach` or `-d`. `--detached` is rejected. | +| `sbx logout` | `--yes`, `-y` | Use `--force` or `-f`. | +| `sbx env plan`, `sbx env create`, `sbx env run` | `--auto-approve`, `-y` | Use `--force` or `-f`. | +| `sbx create` | `--quiet`, `-q` | Use `--no-progress`. This suppresses progress, but still prints the creation summary. | +| `sbx template save` | `-d` for the description | Use `--description`. | +| `sbx diagnose` | `--output`, `-o` | Use `--format table`, `--format json`, `--format yaml`, or `--format github-issue`. | +| `sbx secret ls`, `sbx secret rm` | `--env` | Use `--env-name`. | +| `sbx policy log` | `--quiet`, `-q` | Removed; there is no replacement. | -{{< release-date date="2026-05-29" >}} +`--format`, `--json`, and `-q` are mutually exclusive on commands that use the shared output flags. Even `--json --format json` is rejected. Unsupported format values fail during flag parsing instead of falling back to human-readable output. -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.1) +`sbx settings ls` is the primary spelling; `sbx settings list` remains an alias. `sbx kit builder history rm` keeps `--yes` / `-y` because its `--force` flag is forwarded to Buildx. The deprecated `--global` and `mcp add --skip_auth` flags remain accepted but hidden, with a deprecation warning on stderr; use `--skip-auth` instead of `--skip_auth`. -### Bug fixes +##### Update structured-output parsers -- Fixes a bug introduced in v0.31.0 where sandboxes from earlier versions were not listed by sbx ls and could fail to run. Upgrading to v0.31.1 restores them. +`--json` is an alias of `--format json` and emits the same document. JSON output structures have changed for the commands listed in the following table. Output uses `snake_case` field names; YAML is derived from the same representation. -## 0.31.0 +| Command | Output change | +| --- | --- | +| `sbx ls` | Returns the sandbox array directly instead of `{"sandboxes": [...]}`. Fields use `snake_case`, `created_at` and `last_used_at` use RFC 3339 timestamps, and rows include `detached`. | +| `sbx template ls` | Returns the image array directly instead of `{"images": [...]}`, for local and cloud sandboxes. | +| `sbx mcp ls` locally | Returns the server array directly instead of `{"gateway": {...}, "servers": [...]}`. Each server row carries `gateway`. | +| `sbx policy log` | Local and cloud output use `{updated_at, allowed: [...], blocked: [...]}`. Entries contain `sandbox_id`, `host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. `--limit` applies. This replaces local `allowed_hosts` / `blocked_hosts` and the cloud camelCase document. | +| `sbx --cloud policy ls` | Field names change from camelCase to `snake_case`. | +| `sbx ports` | Cloud rows use `sandbox_port` instead of `port`, alongside `url`. Local rows use `host_ip`, `host_port`, `sandbox_port`, and `protocol`. | +| `sbx ports --publish` / `--unpublish` locally | Structured formats emit result rows with `action: published` or `action: unpublished` instead of human-readable lines. Warnings go to stderr. | +| Cloud `volume create`, `volume ls`, and `volume inspect` | Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to a human-readable details view; request `--format json` for JSON. | +| `sbx rm`, `sbx stop`, `sbx template rm`, `sbx volume rm` | Structured formats return an array of results with `action`, `resource`, `name`, and optional `id` and `error`. Actions are lowercase: `removed`, `stopped`, `removing`, `stopping`, or `failed`. Missing and failed targets are included. | -{{< release-date date="2026-05-28" >}} +For example, a script that extracts sandbox names from `sbx ls --json` must change its filter from `.sandboxes[].name` to `.[].name`. -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.0) +Local and cloud output follow the same conventions. MCP list output still represents different resources: local registrations versus server usage across cloud sandboxes, so those rows differ beyond their shared `name` and `type` fields. -### Highlights +`sbx prune --dry-run` accepts `--format json` and `--format yaml`. Cloud `ttl --format yaml` emits YAML instead of JSON, and `sbx diagnose` supports YAML. `sbx events --json` remains an NDJSON stream, and `sbx mcp auth --format text|json` retains its command-specific formats. -#### Clone mode: `--clone` +##### Update non-interactive workflows -The `--branch` flag has been removed in favor of `--clone` (clone mode). Using `--branch` now fails with: +- Confirmation prompts require terminal input. Piping an answer, such as `echo y | sbx secret set …`, no longer confirms the operation. Use `--force` / `-f` where the command provides it. Commands that require confirmation fail with exit status 1 when stdin is not a terminal. +- Declining a confirmation returns a non-zero exit status consistently, including for removal, reset, and prune operations. +- Read-only invocations and runs with `--force` do not start an interactive sign-in flow. Sign in before running automation that requires authentication. Read-only examples include `ports SANDBOX`, `ttl SANDBOX`, `prune --dry-run`, and `diagnose`; their modifying or upload variants are not read-only. +- Without a terminal, `sbx diagnose --upload` saves the diagnostic bundle but skips uploading it and exits with status 0. A successful exit does not mean that an upload occurred. +- Without a terminal, `sbx create` and `sbx run` fail if the workspace directory does not exist and print a `mkdir -p` hint. Create the directory before invoking the command. +- Ctrl-D at a selection or free-text prompt cancels instead of accepting the default. Enter still accepts the default. -```console -$ sbx run claude --branch foo -ERROR: --branch is no longer supported; use --clone instead -``` +##### Terminal output and streams -Clone mode does not create a branch or worktree on your behalf — instead of a host-side worktree, the sandbox now runs against an in-container read-only clone. +Human-readable output changes across all commands: headings, status marks, indentation, progress, and result messages use a consistent format. `sbx ls` includes state marks and a creation-time column; `sbx ls` and `sbx inspect` identify detached sandboxes. -- Your source repository is mounted into the sandbox read-only, and the shallow clone sets that mount as a Git remote. The agent only ever writes to the in-container clone, never to your working tree or .git/ -- The clone lives on the sandbox's filesystem and is exposed back to the host as a `sandbox-<name>` Git remote served by `git-daemon` (no more `.sbx/<name>-worktrees/...` on the host). -- Forge remotes (`origin`, `upstream`, etc.) on the host are propagated into the in-container clone, so the agent can `git push origin` directly, the same way you would. Local-path remotes are skipped. -- Fetched sandbox refs are mirrored into `refs/sandboxes/<name>/*` on the host and persist after the sandbox is removed. Restore a branch from a removed sandbox with `git branch <local-name> refs/sandboxes/<name>/<branch>`. Commits that were never fetched, or uncommitted changes, are still lost on `sbx rm`. -- The `sandbox-<name>` remote is added to your host on `sbx create --clone` / `sbx run --clone` and removed on `sbx rm`, including across stop and restart. +Results go to stdout. Errors, warnings, corrective hints, daemon-start progress, image pulls, and kit-build progress go to stderr. Update scripts that depend on exact message text or capture only one stream. -### What's New +### What's new -#### CLI +#### Security -- `sbx create` auto-starts the daemon when it isn't already running. -- `sbx logout` now stops the daemon and running sandboxes. -- Unify terminal environment variables across `sbx run` and `sbx exec`. +- Fixed sign-in enforcement ignoring `allowedOrgs` on macOS. +- `sbx cp` blocks local paths that escape a sandbox workspace through symbolic links. +- Cloud `sbx cp` downloads and `sbx kit pack` preserve restrictive destination permissions without temporarily exposing the replacement file. They account for permissions at completion and do not widen them. On Unix, cloud `sbx cp` refuses to replace files owned by another user; on Windows, permission preservation covers the read-only attribute. Special permission bits are retained where the kernel permits. This cloud-copy change does not affect local `sbx cp`. +- `sbx kit add` checks the filesystem mount policy before recreating a sandbox and refuses the operation if its workspace or a saved mount is denied, matching `sbx start`. +- Fixed the daemon crashing on a malformed request sent through an intercepted HTTPS connection. -#### Policies +#### SSH and desktop integration -- Show policy and rule names in CLI list output and TUI details. -- Add filters to the policies listing. +- On macOS and Windows, `sbx setup ssh --auto-create` registers Docker Sandbox connections in Codex and Claude Desktop. Each connection creates a dedicated sandbox on first use and reuses it on subsequent connections. These sandboxes have no host workspace mounted. Clone or copy your project into the sandbox to work on it. +- Desktop SSH setup warns about missing authentication and provides local sign-in guidance for Codex and Claude. Repeating `sbx setup ssh` recognizes existing registrations even while the applications are running. +- Closing a Cursor or VS Code window connected over SSH no longer stops the daemon and other running sandboxes. +- SSH connections no longer fail because the CLI's initial feature lookup timed out before starting the daemon. +- SSH-agent forwarding supports Windows OpenSSH and 1Password agents when `SSH_AUTH_SOCK` is not set. #### Kits -- Mark kits as experimental. -- Verbose error reporting for kit apply failures. - -#### Sandboxes +- V3 kits support capability groups, `kit.env` references, bundled agent skills, and the `ssh-agent@1` and `git-identity@1` capabilities. Selected optional groups retain their network rules, lifecycle files, and context; unsupported optional groups are skipped. Bundled skills can use directories outside the agent's home. +- `sbx kit add` accepts kits with startup commands. Those commands run after the kit is added and on each subsequent sandbox start. +- Sandbox containers expose the provisioned agent's name through `SBX_AGENT` for kit hooks and scripts. +- `sbx kit validate` rejects kits whose credentials route the same host, identifying the conflicting services. The daemon logs the collision during sandbox creation. +- Sandbox creation supports kits whose resolved lock exceeds Docker's container-label size limit. +- `sbx kit pack` excludes its output from the archive, prevents writes into the kit's `files/` directory, and handles Windows 8.3 output paths without renaming the destination or including a previous archive. The output path must end in `.zip` and cannot be a named pipe, socket, or device node. +- An unresolvable kit-file path no longer causes `sbx kit push` to fail. +- Kits that declare an agent-context directory now have their agent instructions file written in that directory instead of beside the workspace, and large workload and mixin kit combinations no longer fail to create with "failed to run sandbox container". -- Opt a sandbox into virtiofs caching at create time via `DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=1` (off by default; the choice is persisted in the spec and survives daemon restarts). +#### Sandbox lifecycle and workspaces -#### Networking +- Creating a sandbox from a local snapshot saved with this version avoids registry requests by default, including when using the daemon API. +- `sbx exec`, `sbx run`, `sbx cp`, and SSH report an unresponsive guest with stop-and-start guidance instead of hanging. `sbx ls` marks the sandbox as not responding. +- Commands against an already-running sandbox reuse guest setup instead of repeating it on every `exec`, `run`, or `cp` invocation. Setup runs once per container start or daemon restart. +- `sbx reset` no longer leaves stray sandbox resources or stalls when another sandbox operation is in progress. +- Sandbox startup identifies files still in use from a previous run instead of reporting a generic failure. +- `sbx exec` accepts empty command arguments. +- `sbx cp` preserves dot-prefixed paths and restrictive directory permissions. On Windows, downloads can replace a read-only destination instead of failing with “Access is denied”. +- `sbx run` and `sbx create` support workspace directories whose names start with a dot. -- Allow public-CA CRL/OCSP/AIA endpoints in the balanced proxy preset. Applies to new installations or after `sbx policy reset` (which removes any user-added rules). +#### Cloud sandboxes -#### Telemetry +- `sbx move --to cloud` and `sbx --cloud env create` accept `--ttl` and `--on-timeout restart`, extending always-on support beyond `sbx --cloud create`. +- Fixed `on_timeout` response decoding errors when using `--on-timeout`. -- Surface `port_publish_failed` inner error detail. +#### Authentication, agents, and MCP -#### Secrets +- Sandbox-scoped custom secrets can override global secrets that use the same environment variable name. +- Fixed Docker Hub sign-outs on macOS when the host sleeps or wakes during login-token refresh. +- The built-in Codex kit registers the MCP gateway with supported settings, removing ignored-setting warnings and sending the gateway its Authorization header. Recreate existing Codex sandboxes with `sbx rm` and `sbx create` to receive the change. +- `sbx mcp unload NAME --sandbox SANDBOX` detaches a loaded MCP server without restarting the sandbox's agent. +- MCP connections and discovery probes identify as `docker-sbx`, and backend recovery respects rate limits to avoid reconnect storms. +- `sbx run --model --provider` uses the API key stored with `sbx secret set <provider>` without exposing it to the sandbox. `sbx run --variant` selects a model thinking variant. +- Fixed `sbx run --model` failing with “401 Unauthorized” when pulling from Docker Hub after a browser-based `docker login`. -- Store container-registry pull credentials with `sbx secret set --registry`, so `sbx run --template` and `sbx run --kit` can pull from private registries (GHCR, ACR, ECR, Quay, …) without a `docker login`. Manage entries with `sbx secret ls` and remove them with `sbx secret rm --registry <host>`. +#### Networking and policy -> [!WARNING] -> By default the credential is stored **host-side only** and is used just for pulling templates/kits. It is never placed inside a sandbox. If you pass `-g` (or scope it to a sandbox name), the credential is **injected into the sandbox in plaintext**, where the agent and any code running there can read it. Only use `-g`/sandbox scope when the sandbox itself needs to pull from the registry; otherwise omit `-g` to keep it host-only. +- The proxy handles trailing-dot hostnames and mixed-case `host.docker.internal` consistently, fixing refused requests and missing credential injection. +- Sandbox image pulls retry temporary registry failures reported as HTTP 5xx errors, including when the original error type is lost across API or progress-stream boundaries. +- Fixed WebSocket connections through the proxy occasionally losing the first bytes sent by the client. +- `sbx policy ls SANDBOX` returns an error when the sandbox does not exist. +- `sbx policy inspect` accepts policy names that match one of their own rule names, such as `default-deny-all`. +- Removing a kit-managed network rule by resource explains that the kit manages it instead of asking for a rule ID. -#### Bug Fixes +#### CLI and diagnostics -- Sort `template ls` output by repository, then tag. -- Retry `ExecResize` to keep the agent TUI in sync. -- Set `TERM=xterm-256color` when exec'ing with `-t`. -- Move the state directory symlink from `/tmp` to `~/.sbx/run/`. -- Stop `storageRootsGone` from locking the storagekit singleton. -- Use `engineError` and add retry debug logging in sandboxd. -- Retry transient shim start closures. -- Make Cursor session bootstrap proxy-local. -- Add bracketed `[::1]` to `NO_PROXY` for IPv6 loopback. -- Backdate proxy CA `NotBefore` to match the goproxy leaf cert window. +- Shell completion scripts generate without starting telemetry, reducing generation time. +- `sbx diagnose` checks for `mkfs.ext4`. -## 0.30.0 +## 0.47.0 -{{< release-date date="2026-05-19" >}} +{{< release-date date="2026-10-05" >}} -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.30.0) +[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.47.0) ### Highlights -The CLI gets **non-interactive Docker Hub login** for scripted workflows, and sandboxes now have **a configurable grace period before auto-stopping** when the last session exits. Plus a wave of fixes covering Linux packaging, macOS worktree compatibility, Windows installer paths, network isolation, and recoverable sandbox state when host directories vanish. +Docker Sandboxes v0.47.0 adds automatic cleanup after agent sessions with `sbx run --rm` and a kit capability for keeping local sandboxes running after sessions disconnect. -### What's New +### What's new -#### Governance & Policy +#### Security -- Allow `sbx policy` setup before login +- Fixed OAuth token interception when a provider hostname uses different capitalization or a trailing dot, preventing real tokens from reaching the sandbox instead of the proxy's placeholders. +- The proxy rejects unrecognized OAuth token grants and prevents their responses from replacing host-managed credentials. Supported in-sandbox sign-in flows remain available. +- The proxy returns an error when it cannot safely mask a successful Anthropic API-key creation response, instead of forwarding the unmasked response to the sandbox. +- Included since v0.46.0: fixed raw TCP connections to denied hostnames being permitted by an allow rule for the hostname's resolved IP address. This fix applies to TCP; the related UDP case with multiple tracked hostnames remains outside its scope. +- Included since v0.45.0: CLI-created cloud hostname allowlists no longer gain implicit `0.0.0.0/0` and `::/0` rules. Existing stored policies are unchanged; remove those rules or recreate the policy to apply the restriction. Explicit IP and CIDR allowances remain supported. +- The proxy rejects TLS handshakes that fill its inspection buffer before a complete ClientHello can be checked on a non-MITM CONNECT tunnel or during the transparent proxy's late handshake check. +- The proxy closes incomplete TLS handshakes on those paths after a two-minute timeout instead of retaining the connections for the sandbox's lifetime. +- Sandboxes reject UDP to multicast, link-local, and unspecified destinations, limited broadcast, and broadcast addresses derived from the host's interface prefixes, regardless of network policy. UDP to `host.docker.internal` is unaffected. Broadcast addresses configured outside that derivation and networks reachable only through routes are not covered by this check. +- Kit pulls enforce limits on registry-declared blob sizes, decompressed content, and archive entry counts. -#### Kits & Agents +#### Sandbox lifecycle and workspaces + +- `sbx run --rm` removes a local or cloud sandbox after its agent session ends. It cannot be combined with `--detached`. If a cloud session is interrupted, such as by a dropped connection, the sandbox is kept and the CLI prints the command to remove it. +- Running `sbx run -d` against an existing local sandbox keeps it running after sessions disconnect, until you stop or remove it. +- Dynamic mounts and permissions created through symlink paths can be removed without reappearing after a restart. Incompatible saved records include recovery guidance. + +#### Kits -- Re-run `commands.startup` on every container start so init hooks are idempotent across restarts -- Per-kit memory files for progressive disclosure -- Enumerate installed kits in the AI memory file's Kits section +- Local kit inspection, validation, and pulling require the daemon to be running. +- Kits can declare `com.docker.sandbox/long-running@1` to keep local sandboxes running after all sessions disconnect. Cloud sandboxes and `sbx kit add` cannot provide this capability: required entries are rejected, and optional entries are skipped. +- `sbx kit sign` and `sbx kit push --sign` succeed on registries that refuse manifest deletion, including GitHub Container Registry and Docker Hub, instead of reporting failure after attaching the signature. +- Adding a kit to a sandbox whose guest has stopped responding fails without leaving the sandbox unusable until the daemon restarts. -#### CLI & Auth +#### Cloud sandboxes -- Add non-interactive Docker Hub login for scripted workflows -- Migrate `/reset` to `/daemon/reset`; state-dir wipe is now daemon-side -- Print "Git repository detected" once when using `--branch` -- Skip implicit run options when the user provides explicit args +- `sbx --cloud ttl` reports stopped sandboxes as stopped instead of expired. The time-to-live restarts when the sandbox resumes. JSON output includes `stopped` and `ttl_paused`; while the sandbox is resuming, only `ttl_paused` is true. +- Creating a cloud sandbox or moving a local sandbox to the cloud applies cloud policy and the kit's network rules without copying locally added network rules. Moving a sandbox with local HTTP method or path restrictions warns that those restrictions will not apply in the cloud. -#### Networking & Sandboxd +#### Settings and proxies -- Bind both loopback stacks by default when publishing ports -- Allow raw TCP to `host.docker.internal` when localhost is allowed in policy -- Add grace period before auto-stopping a sandbox when the last session exits +- Upstream proxy recovery no longer blocks unrelated sandboxes or deletes isolated container data when credentials are unavailable. Local host services remain reachable. +- `sbx settings set` rejects invalid upstream proxy values before saving them. -#### Bug Fixes +#### MCP -- Build sailor's `ffi` crate instead of `ffi-krun` for packaged Linux release artifacts -- Keep sandboxes recoverable when workspace or worktree is deleted on the host -- Add macOS `/private` path compatibility for worktrees -- Probe canonical socket path for `sun_path` budget — fixes `krun_start_enter failed` on macOS with long usernames -- Namespace gVisor socket dir and auth/secret stores by `--app-name` so concurrent daemons don't collide -- Sanitize runtime ID when looking up gVisor network -- Check database version before starting the daemon; surface an instructive error instead of crashing -- Report Docker daemon startup time instead of the pre-start message in DinD -- Harden `BuildFileCredential` to check more than just file existence -- Open a sentinel connection in `cp` and `kit add` to prevent auto-stop race -- Remove redundant `ContainerKill` before `ContainerRemove` in sandboxlib -- Use a safe Windows `start` invocation for `OpenURL` in the TUI -- Rename WiX install directory id to `INSTALLFOLDER` +- MCP authorization requests `offline_access` when the server advertises it and authorization uses saved defaults or resource-required scopes, so the server can issue refresh tokens. Explicit `--scope` values are unchanged. Run `sbx mcp auth` again to obtain a grant with a refresh token for existing credentials. +- Fixed MCP gateway availability in sandboxes created from the TUI and when connecting over SSH after a daemon restart or automatic sandbox creation. -#### Documentation +#### CLI and updates -- Warn agents about worktree path traps with `--branch` -- Improve consistency and wording in CLI help strings +- `sbx env` reports the correct file, line, and column for unrecognized keys even when another entry in the file fails custom validation. Multiple validation errors appear on separate lines. +- Help remains available when the settings directory is unwritable or local settings cannot be opened, with a warning instead of a panic. +- Host-port collisions from `sbx ports --publish` identify the occupied binding and offer a retry with an automatically allocated port when safe. +- Windows update notices appear only after WinGet confirms that the version is available in its catalog. +<!-- release-notes:end --> <!-- END GENERATED RELEASES --> diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 50919e94faf4..463ceda6b988 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -1,14 +1,16 @@ --- title: Security model linkTitle: Security model -weight: 50 +weight: 110 description: Trust boundaries, isolation layers, and security properties of Docker Sandboxes. keywords: docker sandboxes, security model, isolation, trust boundaries, microVM --- +{{% include "sandboxes-local-scope.md" %}} + Docker Sandboxes run AI agents in microVMs so they can execute code, install -packages, and use tools without accessing your host system. Multiple isolation -layers protect your host system. +packages, and use tools without accessing host resources beyond those you +share. Multiple isolation layers protect your host system. ## Trust boundaries @@ -18,27 +20,56 @@ anything on your host except what is explicitly shared. What crosses the boundary into the VM: -- **Workspace directory:** mounted into the VM. The default direct mount is - read-write — the agent edits your working tree in place. With - [`--clone`](../usage.md#clone-mode), your repository is mounted read-only - and the agent works on a private clone. +- **Host workspace directory:** shared when you pass a workspace path or use + `sbx run`, which defaults to the current directory. A direct mount is + read-write, so the agent edits your working tree in place. With + [`--clone`](../usage.md#clone-mode), your repository is mounted read-only and + the agent works on a private clone. A mountless sandbox doesn't share a host + workspace. - **Credentials:** the host-side proxy injects authentication headers into outbound HTTP requests. The raw credential values never enter the VM. -- **Network access:** HTTP and HTTPS requests to - [allowed domains](defaults/) are proxied through the host. +- **Network access:** outbound TCP connections to destinations allowed by + [network policy](defaults/) are proxied through the host. +- Shared agent skills: sandboxes created for supported agents mount a + persistent host-side store read-only by default at the agent's skills + directory. Use `--skills` or + [`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode) + to choose another mode at + creation. Existing sandboxes retain their mounts until recreated. +- **MCP gateway traffic:** supported agents connect to a host-side MCP gateway + endpoint. The gateway brokers access to registered MCP servers. What crosses the boundary back to the host: -- **Workspace file changes:** visible on your host in real time with the - default direct mount. -- **HTTP/HTTPS requests:** sent to allowed domains through the host proxy. +- **Workspace file changes:** visible on your host in real time when you use a + direct mount. +- **Outbound TCP connections:** sent to allowed destinations through the host + proxy. +- Shared skill changes: sandboxes with `readwrite` access can write to the + host-side store. These changes are visible to other sandboxes that share it. + +Outside the workspace and shared skills store, the agent cannot access your +host filesystem. It also cannot access your host Docker daemon, your host +network directly, or any destination not allowed by network policy. Sandboxes +cannot communicate directly over the network. Outbound UDP is blocked unless +you turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp) +and allow it through network policy. ICMP is blocked. + +MCP servers are an explicit integration point. Remote MCP servers run outside +Docker Sandboxes, and local stdio MCP servers run on the host, not inside the +sandbox VM. An agent can invoke the tools those servers expose through the MCP +gateway, subject to MCP policies when organization governance is active. Treat +local MCP servers as trusted host integrations. -Everything else is blocked. The agent cannot access your host filesystem -(outside the workspace), your host Docker daemon, your host network or -localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP, -and ICMP are blocked at the network layer. +### MicroVM isolation -![Sandbox security model showing the hypervisor boundary between the sandbox VM and the host system. The workspace directory is shared read-write. The agent process, Docker Engine, packages, and VM filesystem are inside the VM. Host filesystem, processes, Docker Engine, and network are outside the VM and not accessible. A proxy enforces allow/deny policies and injects credentials into outbound requests.](../images/sbx-security.png) +This topology shows what is private to the microVM, what is explicitly mounted, +and which host resources remain outside the agent's reach. + +{{< interactive-diagram src="../diagrams/trust-boundary-topology.yaml" >}} + +To follow an outbound request through network policy and credential injection, +see [Architecture](../architecture.md#follow-an-authenticated-request). ## Isolation layers @@ -47,37 +78,39 @@ The sandbox security model has five layers. See - **Hypervisor isolation:** separate kernel per sandbox. No shared memory or processes with the host. -- **Network isolation:** all HTTP/HTTPS traffic proxied through the host. - [Deny-by-default policy](defaults/). Non-HTTP protocols blocked entirely. +- **Network isolation:** outbound TCP traffic is proxied through the host and + governed by a [deny-by-default policy](defaults/). Experimental UDP egress + also follows network policy. ICMP is blocked. - **Docker Engine isolation:** each sandbox has its own Docker Engine with no path to the host daemon. -- **Workspace isolation** (opt-in via `--clone`): the agent works on a - private in-VM clone and your repository is mounted read-only. The default - direct mode applies no workspace boundary — the agent edits your working - tree in place. +- **Workspace isolation:** a mountless sandbox has no host workspace mount. + Clone mode gives the agent a private in-VM clone and mounts your repository + read-only. Direct mode shares your working tree read-write. - **Credential isolation:** API keys are injected into HTTP headers by the host-side proxy. Credential values never enter the VM. ## What the agent can do inside the sandbox Inside the VM, the agent has full privileges: sudo access, package installation, -a private Docker Engine, and read-write access to the workspace. Installed -packages, Docker images, and other VM state persist across restarts. See +a private Docker Engine, and read-write access to its in-sandbox filesystem and +configured workspace. Installed packages, Docker images, and other VM state +persist across restarts. See [Default security posture](defaults/) for the full breakdown of what is permitted and what is blocked. -## What is not isolated by default +## Security considerations The sandbox isolates the agent from your host system, but the agent's actions -can still affect you through the shared workspace and allowed network channels. - -In direct mode, workspace changes are live on your host. With the default -direct mount, the agent edits the same files you see on your host. This -includes files that execute implicitly during normal development: Git hooks, -CI configuration, IDE task configs, `Makefile`, `package.json` scripts, and -similar build files. Review changes before running any modified code. Note -that Git hooks live inside `.git/` and do not appear in `git diff` output — -check them separately. See +can still affect you through explicitly shared resources and allowed network +channels. + +In direct mode, workspace changes are live on your host. The agent edits the +same files you see on your host. This includes files that execute implicitly +during normal development: Git hooks, CI configuration, IDE task configs, AI +project configuration and settings, `Makefile`, `package.json` scripts, and +similar build files. Review changes before running any modified code. Note that +Git hooks live inside `.git/` and do not appear in `git diff` output — check +them separately. See [Workspace isolation](isolation/#workspace-isolation) for the full list and for the alternative clone-mode boundary. @@ -86,6 +119,25 @@ The default allowed domains include broad wildcards. Some defaults like see the full list of active rules, and remove entries you don't need. See [Default security posture](defaults/). +Kits run install commands with root privileges inside the sandbox. To limit +supply-chain risk, `sbx` restricts kit installs to an allowlist of sources +that defaults to Docker Hub only. See +[Restrict kit sources](/manuals/ai/sandboxes/customize/use-kits.md#restrict-kit-sources). + +Shared agent skills create a narrow exception to cross-sandbox isolation. The +store can be mounted with `readwrite` access, so one sandbox can modify +instructions or scripts that an agent later uses in another sandbox, including +one with `readonly` access. This doesn't expose the rest of +the host filesystem or create a direct network path between sandboxes, but it +does put participating sandboxes in the same trust boundary. See +[Share agent skills](../workflows/agent-skills.md) for details and the +per-sandbox opt-out. + +Local stdio MCP servers run outside the sandbox VM. If you register a local MCP +server that starts a host process or host Docker container, that process or +container uses host permissions and host isolation, not sandbox isolation. See +[MCP gateway](../mcp-gateway.md). + ## Organization-wide control On a single developer's machine, security and policy are configured locally — @@ -103,6 +155,7 @@ admins. workspace, and credential isolation work - [Default security posture](defaults/): what a fresh sandbox permits and blocks -- [Credentials](credentials/): how to provide and manage API keys -- [Governance](../governance/): configure network and filesystem access rules, - locally or across your organization +- [Manage credentials](../configuration/credentials.md): provide and manage API + keys while keeping their values outside the sandbox +- [Governance](../governance/): configure network, filesystem, and MCP access + controls locally or across your organization diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md deleted file mode 100644 index 68f00d2abc7e..000000000000 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -title: Credentials -weight: 20 -description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents. -keywords: docker sandboxes, credentials, api keys, authentication, proxy, ssh agent, secrets ---- - -Most agents need an API key for their model provider. An HTTP/HTTPS proxy on -your host intercepts outbound requests from the sandbox, looks up the matching -credential on the host, and overwrites the auth header before forwarding. The -real credential stays on the host; the sandbox sees only a sentinel value. For -the security model behind this, see -[Credential isolation](isolation.md#credential-isolation). - -## How credential injection works - -The proxy needs three things to inject a credential: which outbound traffic to -match, what header to write, and what value to use. The kit (or built-in agent -definition) declares the first two. You provide the value on the host. - -There are two host-side stores, plus a host shell fallback: - -- Stored secrets, keyed on a service identifier: built-in agents declare - service identifiers (`anthropic`, `openai`, `github`, etc.) in their kit - specs; custom kits can declare their own. `sbx secret set` stores a value - keyed on that identifier. When a sandboxed request matches a service's - domain, the proxy reads the stored value and writes the configured header. - Inside the sandbox, the environment variable holds a sentinel like - `proxy-managed`, so SDKs that read the variable see something non-empty - without seeing the real secret. See [Stored secrets](#stored-secrets). - -- Stored secrets, keyed on a target domain and environment variable name: - `sbx secret set-custom` stores a value alongside a target domain, an - environment variable name, and an optional placeholder. The sandbox sees - the placeholder; the proxy substitutes it with the real value anywhere it - appears in outbound traffic to that domain. Use this when the - service-identifier model doesn't fit — for example, when the agent - validates the variable format at boot, or when the credential lands in a - request body. See [Custom secrets](#custom-secrets). - -- Host shell environment variables: as a fallback, the proxy reads from your - shell environment. Useful for one-off testing or development; stored - secrets are preferred because shell environment variables are plaintext - and visible to other processes running as your user. See - [Environment variables](#environment-variables). - -Registry credentials are a separate store with a different purpose. They -authenticate the `sbx` CLI (and optionally the sandbox itself) to private -OCI registries for template and kit pulls, and are not used by the -credential-injection proxy. See [Registry credentials](#registry-credentials). - -If both a stored secret and a host environment variable are set for the same -service, the stored secret takes precedence. For multi-provider agents -(OpenCode, Docker Agent), the proxy selects credentials based on the API -endpoint being called. See individual [agent pages](../agents/) for -provider-specific details. - -## Stored secrets - -`sbx secret set` stores credentials in your OS keychain, keyed on a service -identifier. Built-in agents declare a fixed set of services. Custom kits can -declare their own. The same `sbx secret set` flow works for both. - -### Where secrets are stored - -The store backing `sbx secret set` depends on your operating system: - -- macOS: the system Keychain. -- Windows: the Windows Credential Manager. -- Linux: the Secret Service exposed by your desktop keyring, such as GNOME - Keyring or KDE Wallet. - -The Ubuntu package depends on GNOME Keyring, so a standard desktop install -needs no extra setup. - -On Linux hosts without a running Secret Service — headless servers and some -WSL setups — `sbx` falls back to an encrypted file under your user config -directory `$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to -`~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. The fallback -is automatic and needs no configuration. When you store a secret this way, -`sbx` prints a notice: - -```text -No keychain detected - this secret will be stored in an encrypted file on disk -``` - -The file is encrypted at rest and protected by `0700` directory permissions, -the same posture as `~/.docker/config.json`. This is weaker than an OS -keychain, which also mediates access per application. If you start a Secret -Service on the host later, `sbx` stores new secrets in the keychain again. For -more on running sandboxes without a desktop keyring, see -[Can I use Docker Sandboxes on headless Linux?](../faq.md#can-i-use-docker-sandboxes-on-headless-linux) - -### Store a secret - -```console -$ sbx secret set -g anthropic -``` - -This prompts you for the secret value interactively. The `-g` flag stores the -secret globally so it's available to all sandboxes. To scope a secret to a -specific sandbox instead: - -```console -$ sbx secret set my-sandbox openai -``` - -> [!NOTE] -> A sandbox-scoped secret takes effect immediately, even if the sandbox is -> running. A global secret (`-g`) only applies when a sandbox is created. If -> you set or change a global secret while a sandbox is running, recreate the -> sandbox for the new value to take effect. - -You can also pipe in a value for non-interactive use: - -```console -$ echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic -``` - -### Built-in services - -Each built-in service name maps to a set of environment variables the proxy -checks and the API domains it authenticates requests to: - -| Service | Environment variables | API domains | -| ----------- | ---------------------------------- | ----------------------------------- | -| `anthropic` | `ANTHROPIC_API_KEY` | `api.anthropic.com` | -| `aws` | `AWS_ACCESS_KEY_ID` | AWS Bedrock endpoints | -| `github` | `GH_TOKEN`, `GITHUB_TOKEN` | `api.github.com`, `github.com` | -| `google` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `generativelanguage.googleapis.com` | -| `groq` | `GROQ_API_KEY` | `api.groq.com` | -| `mistral` | `MISTRAL_API_KEY` | `api.mistral.ai` | -| `nebius` | `NEBIUS_API_KEY` | `api.studio.nebius.ai` | -| `openai` | `OPENAI_API_KEY` | `api.openai.com` | -| `xai` | `XAI_API_KEY` | `api.x.ai` | - -When you store a secret with `sbx secret set -g <service>`, the proxy uses it -the same way it would use the corresponding environment variable. You don't -need to set both. - -### Services declared by kits - -Custom kits can declare their own service identifiers in `spec.yaml` — -they're not limited to the table above. To provide a credential for a -kit-declared service, run `sbx secret set` with the same identifier the kit -declares under `credentials.sources`: - -```console -$ sbx secret set -g my-service -``` - -There's no separate registration step; the keychain entry is keyed on the -identifier the kit already uses. See -[Authenticate to external services](../customize/kits.md#authenticate-to-external-services) -for the kit-side wiring. - -### List and remove secrets - -List all stored secrets: - -```console -$ sbx secret ls -SCOPE TYPE NAME SECRET -(global) service github gho_GCaw4o****...****43qy -``` - -Remove a secret: - -```console -$ sbx secret rm -g github -``` - -> [!NOTE] -> Running `sbx reset` deletes all stored secrets along with all sandbox state. -> You'll need to re-add your secrets after a reset. - -### GitHub token - -The `github` service gives the agent access to the `gh` CLI inside the -sandbox. Pass your existing GitHub CLI token: - -```console -$ echo "$(gh auth token)" | sbx secret set -g github -``` - -This is useful for agents that create pull requests, open issues, or interact -with GitHub APIs on your behalf. - -### SSH agent - -If your host has an SSH agent and `SSH_AUTH_SOCK` is set, Docker Sandboxes -forwards the agent into the sandbox and sets `SSH_AUTH_SOCK` there. The -private keys stay on your host. Processes inside the sandbox can request -signatures from the forwarded agent, but they can't read or copy the private -key. - -Use SSH agent forwarding for Git operations over SSH and SSH-based commit -signing. The signing key must be loaded in the host SSH agent for sandboxed -commit signing to work. Outbound SSH connections are still subject to sandbox -network policy. For details, see -[Signed commits](../usage.md#signed-commits). - -## Custom secrets - -> [!IMPORTANT] -> Custom secrets are experimental. Behavior, flags, and the placeholder format may -> change without notice. - -For credentials that don't fit the service-identifier model — for example, -when an agent validates the environment variable format at boot, or when the -credential lands in a request body rather than a header — use -`sbx secret set-custom`. The secret is keyed on a target domain, an -environment variable name, and an optional placeholder string, instead of a -service identifier. - -```console -$ sbx secret set-custom -g \ - --host api.example.com \ - --env API_KEY \ - --value <secret> -``` - -> [!WARNING] -> Passing the secret as `--value <secret>` records it in your shell history -> and exposes it to other processes running as your user. Avoid pasting -> real credentials inline — read the value from a variable that's already -> in your environment, and clear shell history if a real secret was passed -> on the command line. - -Inside the sandbox, `API_KEY` is set to a generated placeholder (for example, -`sbx-cs-<rand>`). When a sandboxed process sends a request to -`api.example.com` and the placeholder appears anywhere in the request, the -proxy replaces it with the real value. The agent never sees the real secret. - -Prefer the [service-based flow](#stored-secrets) whenever it's an option — -the kit handles the wiring; you only provide the value. - -## Registry credentials - -Registry credentials authenticate to private OCI registries when pulling -[templates](../customize/templates.md) or [kits](../customize/kits.md). Use -`sbx secret set --registry <host>` to store them. They are independent from -service secrets: the proxy doesn't touch them, and they're used directly by -the `sbx` CLI when resolving image references. - -For Docker Hub, `sbx` reuses your `sbx login` session — no registry secret -needed. For other registries (GitHub Container Registry, ECR, ACR, -self-hosted Nexus, and so on), store credentials with `sbx secret set ---registry`. - -### Store registry credentials - -Pipe a token from stdin and target the registry hostname: - -```console -$ gh auth token | sbx secret set --registry ghcr.io --password-stdin -``` - -For registries that require a username (for example, ACR with an admin -account), add `--username`: - -```console -$ echo "$ACR_PASSWORD" | sbx secret set \ - --registry myregistry.azurecr.io \ - --username myuser \ - --password-stdin -``` - -Three scopes control where the credential is used: - -- Host-only (no `-g`, no sandbox name): the `sbx` CLI uses it to pull - templates and kits when creating a sandbox. The credential is not - injected into the sandbox itself, so processes inside the sandbox can't - use it. -- Global (`-g`): same as host-only, plus written into `~/.docker/config.json` - in every new sandbox. Use this when agents need to pull or push from - inside the sandbox — for example, when an agent builds and publishes - container images. -- Sandbox-scoped (positional `SANDBOX` argument): credential applies only - to that named sandbox. Useful when only one sandbox needs access to a - private registry. - -```console -$ gh auth token | sbx secret set -g --registry ghcr.io --password-stdin -$ gh auth token | sbx secret set my-sandbox --registry ghcr.io --password-stdin -``` - -`sbx kit pull` also uses these credentials, with the Docker credential -store as a fallback. `sbx kit push` uses only the Docker credential store — -push targets still require a prior `docker login`. - -### Remove registry credentials - -Remove both the host-only and global entries for a registry: - -```console -$ sbx secret rm --registry ghcr.io -f -``` - -To remove only the global (sandbox-injected) entry and leave the -host-only credential in place, pass `-g`: - -```console -$ sbx secret rm -g --registry ghcr.io -f -``` - -To remove a sandbox-scoped credential, pass the sandbox name: - -```console -$ sbx secret rm my-sandbox --registry ghcr.io -f -``` - -## Environment variables - -As an alternative to stored secrets, export the relevant environment variable -in your shell before running a sandbox: - -```console -$ export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx -$ sbx run claude -``` - -The proxy reads the variable from your terminal session. See individual -[agent pages](../agents/) for the variable names each agent expects. - -> [!NOTE] -> These environment variables are set on your host, not inside the sandbox. -> Sandbox agents are pre-configured to use credentials managed by the -> host-side proxy. For custom environment variables not tied to a -> [built-in service](#built-in-services), see -> [Setting custom environment variables](../faq.md#how-do-i-set-custom-environment-variables-inside-a-sandbox). - -## Best practices - -- Use [stored secrets](#stored-secrets) over environment variables. Stored - secrets are encrypted at rest in the OS keychain (or an encrypted file on - Linux hosts without a keychain), while environment variables are plaintext in - your shell. See [Where secrets are stored](#where-secrets-are-stored). -- Don't set API keys manually inside the sandbox. Sandbox agents are - pre-configured to use proxy-managed credentials. -- For Claude Code and Codex, OAuth is another secure option: the flow runs on - the host, so the token is never exposed inside the sandbox. If you haven't - stored a credential, both agents prompt you to authenticate before the - sandbox launches — Codex prompts on the host from `sbx run codex`, and Claude - Code prompts inside the agent. To authenticate ahead of time, run - `sbx secret set -g openai --oauth` for Codex, or use `/login` inside Claude - Code. -- If you store credentials in 1Password, see - [Sourcing credentials from 1Password](../workflows.md#sourcing-credentials-from-1password) - for how to use `op read` and `op run` with `sbx`. - -## Custom templates and placeholder values - -When building custom templates or installing agents manually in a shell -sandbox, some agents require environment variables like `OPENAI_API_KEY` to be -set before they start. Set these to placeholder values (e.g. `proxy-managed`) -if needed. The proxy injects actual credentials regardless of the environment -variable value. diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index c3de741804e7..80cde27a73f4 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -1,35 +1,56 @@ --- title: Default security posture linkTitle: Defaults -weight: 15 +weight: 20 description: What a sandbox permits and blocks before you change any settings. -keywords: docker sandboxes, security defaults, network policy, credentials, sbx +keywords: docker sandboxes, security defaults, network policy, credentials, shared skills, sbx --- -A sandbox created with `sbx run` and no additional flags has the following -security posture. +{{% include "sandboxes-local-scope.md" %}} + +A sandbox created with `sbx run claude` and no additional flags has the +following security posture. ## Network defaults -All outbound HTTP and HTTPS traffic is blocked unless an explicit rule allows -it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and -ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback -addresses, and link-local addresses is also blocked. +All outbound TCP traffic, including HTTP, HTTPS, and SSH, is blocked unless an +explicit rule allows the destination. Outbound UDP is disabled by default. To +use it, turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp) +and add UDP allow rules. ICMP is blocked. DNS queries use the sandbox's internal +resolver, which enforces network policy. Run `sbx policy ls` to see the active network rules for your installation. Rules can be customized per machine with the `sbx policy` CLI, or managed -centrally across your organization from the Admin Console. Org-level rules -take precedence over local rules. See [Governance](../governance/). +centrally across your organization. Org-level rules take precedence over local +rules. See +[Network access policies](../governance/access-controls/network.md). ## Workspace defaults -Sandboxes use a direct mount by default. The agent sees and modifies your -working tree directly, and changes appear on your host immediately. - -The agent can read, write, and delete any file within the workspace directory, -including hidden files, configuration files, build scripts, and Git hooks. -See [Workspace isolation](isolation.md#workspace-isolation) for what to -review after an agent session. +`sbx run` mounts the current directory when you don't pass a workspace path. +The agent can read, write, and delete any file within that directory, including +hidden files, configuration files, build scripts, and Git hooks. + +When you omit the workspace path from `sbx create`, the sandbox doesn't mount a +host workspace. The agent uses the sandbox template's default working +directory. Docker-provided agent templates use `/home/agent/workspace`. If the +template doesn't define a usable absolute working directory, the daemon uses +that path. Files in this directory persist across stops and restarts and are +deleted when you remove the sandbox. See +[Workspace isolation](isolation.md#workspace-isolation) for the available +workspace modes and what to review after a direct-mount session. + +## Shared skills defaults + +Sandboxes created for supported agents mount a persistent shared skills store +read-only by default. The +[`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode) setting +can change this default, +and `--skills` overrides it for a sandbox at creation. A sandbox with `readwrite` access can change skills that other +participating sandboxes load, including those with `readonly` access. Use +`--skills=off` when creating a sandbox to omit the shared store. Existing +sandboxes retain their mounts until recreated. See +[Share agent skills](../workflows/agent-skills.md). ## Credential defaults @@ -38,7 +59,7 @@ No credentials are available to the sandbox unless you provide them using host-side proxy injects them into outbound HTTP headers. The agent cannot read the raw credential values. -See [Credentials](credentials.md) for setup instructions. +See [Credentials](../configuration/credentials.md) for setup instructions. ## Agent capabilities inside the sandbox @@ -50,21 +71,21 @@ The agent runs with full control inside the sandbox VM: - Full read and write access to the VM filesystem Everything the agent installs or creates inside the VM, including packages, -Docker images, and configuration changes, persists across stop and restart -cycles. When you remove the sandbox with `sbx rm`, the VM and its contents -are deleted. Only workspace files remain on the host. +Docker images, mountless workspace files, and configuration changes, persists +across stop and restart cycles. When you remove the sandbox with `sbx rm`, the +VM and its contents are deleted. Direct-mounted workspace files and the shared +skills store remain on the host, as do repositories used as clone sources. ## What is blocked by default The following are blocked for all sandboxes and cannot be changed through policy configuration: -- Host filesystem access outside the workspace directory +- Host filesystem access outside explicitly mounted workspaces and the shared + skills store - Host Docker daemon -- Host network and localhost -- Communication between sandboxes -- Raw TCP, UDP, and ICMP connections -- Traffic to private IP ranges and link-local addresses +- Direct network communication between sandboxes +- Direct external ICMP connections -Outbound HTTP/HTTPS to domains not in the allow list is also blocked by -default, but you can add allow rules with `sbx policy allow`. +Outbound TCP to destinations not in the allow list is also blocked by default, +but you can add allow rules with `sbx policy allow`. diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 10404d02313e..07070347a9ae 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -7,6 +7,8 @@ aliases: - /ai/sandboxes/security/workspace/ --- +{{% include "sandboxes-local-scope.md" %}} + AI coding agents need to execute code, install packages, and run tools on your behalf. Docker Sandboxes run each agent in its own microVM. Five isolation layers protect your host: hypervisor, network, Docker Engine, @@ -20,7 +22,10 @@ processes, files, or resources outside its defined boundaries. - **Process isolation:** separate kernel per sandbox; processes inside the VM are invisible to your host and to other sandboxes -- **Filesystem isolation:** only your workspace directory is shared with the +- **Filesystem isolation:** a host workspace is shared when you pass a + workspace path or use `sbx run`, which defaults to the current directory. + For supported agents that haven't opted out, the dedicated + [shared skills store](../workflows/agent-skills.md) is also shared with the host. The rest of the VM filesystem persists across restarts but is removed when you delete the sandbox. Symlinks pointing outside the workspace scope are not followed. @@ -30,25 +35,34 @@ processes, files, or resources outside its defined boundaries. The agent runs as a non-root user with sudo privileges inside the VM. The hypervisor boundary is the isolation control, not in-VM privilege separation. +Processes in a local sandbox can write text to your host clipboard, but can't +read existing clipboard text. Host clipboard image reads are a separate, +opt-in feature. After running untrusted code, check clipboard contents before +pasting them on the host. + ## Network isolation -Each sandbox has its own isolated network. Sandboxes cannot communicate with -each other and cannot reach your host's localhost. There is no shared network -between sandboxes or between a sandbox and your host. +Each sandbox has its own isolated network. Sandboxes cannot communicate +directly with each other or share a network with your host. To reach a service +running on the host through a policy-controlled connection, see +[Accessing host services from a sandbox](../workflows/development.md#accessing-host-services-from-a-sandbox). -All HTTP and HTTPS traffic leaving a sandbox passes through a proxy on your -host that enforces the [network policy](../governance/). The sandbox routes -traffic through either a forward proxy or a transparent proxy depending on the -client's configuration. Both enforce the network policy; only the forward proxy -[injects credentials](credentials.md) for AI services. +All outbound TCP traffic passes through a proxy on your host that enforces the +[network access policy](../governance/access-controls/network.md). The sandbox +routes traffic through either a forward proxy or a transparent proxy depending +on the client's configuration. Both enforce the network policy. Only the +forward proxy [injects credentials](../configuration/credentials.md) for AI services. -Raw TCP connections, UDP, and ICMP are blocked at the network layer. DNS -resolution is handled by the proxy; the sandbox cannot make raw DNS queries. -Traffic to private IP ranges, loopback, and link-local addresses is also -blocked. Only domains explicitly listed in the policy are reachable. +Outbound UDP is disabled by default. When you turn on +[experimental UDP egress](../governance/access-controls/local.md#allow-outbound-udp), +network policy controls its destinations. ICMP is blocked. DNS queries use the +sandbox's internal resolver, which enforces network policy. TCP connections +are allowed only when a policy rule matches the destination. For the default set of allowed domains, see -[Default security posture](defaults.md). +[Default security posture](defaults.md). To forward allowed traffic through a +corporate or upstream proxy, see +[Configure an upstream proxy](../configuration/upstream-proxy.md). ## Docker Engine isolation @@ -57,11 +71,17 @@ Mounting your host Docker socket into a container would give the agent full access to your environment. Docker Sandboxes avoid this by running a separate [Docker -Engine](https://docs.docker.com/engine/) inside the sandbox environment, isolated from +Engine](/manuals/engine/_index.md) inside the sandbox environment, isolated from your host. When the agent runs `docker build` or `docker compose up`, those commands execute against that engine. The agent has no path to your host Docker daemon. +This Docker Engine boundary applies to processes running inside the sandbox VM. +It doesn't apply to local stdio MCP servers registered through the +[MCP gateway](../mcp-gateway.md). Those servers run on the host, outside the +sandbox VM. If a local MCP server starts a Docker container, it uses Docker on +the host. + Each sandbox VM runs its own Docker Engine. The agent runs inside the VM, alongside that engine, and drives it to create containers, all within the VM: @@ -85,34 +105,66 @@ flowchart TB ## Workspace isolation -When you create a sandbox, you choose one of two ways to share your -workspace with it: +When you create a sandbox, choose how the agent receives a workspace: + +- **Mountless** (no path to `sbx create`): the sandbox doesn't receive a host + workspace. The agent works in the sandbox's own filesystem. +- **Direct mount** (a path such as `.`): the agent has read-write access to + your working tree. There is no boundary between the agent's edits and your + host filesystem. +- **Clone mode** (`--clone` and a Git path): your repository is mounted + read-only into the VM and the agent works on a private clone inside the VM. + The agent's edits never reach your host until you fetch them. + +See [Git workflows](../workflows/git.md) for direct-mount and clone-mode +workflows. + +### Mountless + +Omit the workspace path from `sbx create` to create a mountless sandbox, then +attach by name: + +```console +$ sbx create --name scratch claude +$ sbx run --name scratch +``` + +The agent uses the sandbox template's default working directory. +Docker-provided agent templates use `/home/agent/workspace`. If the template +doesn't define a usable absolute working directory, the daemon uses that path. +Files there stay within the sandbox, persist across stops and restarts, and are +deleted when you remove the sandbox. A mountless sandbox doesn't expose a host +project directory, but separately configured host resources such as the shared +skills store can still be mounted. -- **Direct mount** (the default): the agent has read-write access to - your working tree. There is no boundary between the agent's edits and - your host filesystem. -- **Clone mode** (`--clone`): your repository is mounted read-only into - the VM and the agent works on a private clone inside the VM. The - agent's edits never reach your host until you fetch them. +### Direct mount -See [Git workflow](../usage.md#git-workflow) for the workflow side of -each. +Pass a workspace path to share it into the VM as a read-write mount. The agent +and the host see the same files, and changes the agent makes appear on your +host as soon as they're written. `sbx run` mounts the current directory when +you don't pass a path: -### Direct mount (default) +```console +$ sbx run claude +``` -By default, your workspace is shared into the VM as a read-write mount. -The agent and the host see the same files, and changes the agent makes -appear on your host as soon as they're written. +Direct mounts enforce access by path. If a workspace file is a hard link to a +file outside the workspace, the agent can read and modify the underlying file +through the workspace path. Changes affect every hard link to that file, +including links outside the authorized workspace. Filesystem access policies +do not block this access because they evaluate the workspace path rather than +other paths to the same file. [Clone mode](#clone-mode) prevents writes through +the primary workspace by mounting the host repository read-only. -There is no isolation between the agent and your workspace in this mode. -The agent can create, modify, or delete any file in the workspace, -including: +Direct mount gives the agent broad write access to your workspace. The agent +can create, modify, or delete workspace files, including: - Source code and configuration files - Build files (`Makefile`, `package.json`, `Cargo.toml`) - Git hooks (`.git/hooks/`) - CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) - IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations) +- AI project configuration and settings (`.claude/`, `.codex/`, `.gemini/`) - Hidden files, shell scripts, and executables Some of these files execute code when you trigger normal development @@ -128,6 +180,19 @@ Review them after any agent session before performing those actions: during build or install steps. - IDE configuration (`.vscode/tasks.json`, `.idea/`) can run tasks when you open the project. +- AI project configuration and settings (`.claude/settings.json`, `.codex/config.toml`, + `.gemini/settings.json`) can define hooks and startup commands that + execute automatically. + +#### Sandbox environment files + +Sandbox environment files can declare lifecycle and credential commands that +run on the host with your privileges. Before running these commands, `sbx` +shows them in an environment plan and asks for approval. Review the plan before +you approve host commands. + +For file placement and read-only protection, see +[Sandbox environment files](../configuration/environment-files.md#workspace). > [!WARNING] > Treat sandbox-modified workspace files the same way you would treat a pull @@ -141,6 +206,13 @@ never works directly against your host repository. Even with full root inside the VM, it cannot modify your `.git` directory, your working tree, or any tracked file on your host. +> [!IMPORTANT] +> Clone mode protects your host repository from modification, **not from +> inspection**. Your repository is still mounted read-only into the sandbox, +> including untracked files and files excluded by `.gitignore`. Files such as +> `.env` remain readable by the agent. Store secrets outside your working +> directory or use [credential isolation](#credential-isolation) instead. + ```mermaid flowchart LR subgraph host["Host repository (untouched)"] @@ -163,8 +235,11 @@ flowchart LR How the boundary is enforced: - Your repository's Git root is mounted at `/run/sandbox/source` as - read-only. Nothing the agent does inside the VM can write back through - that mount. + read-only. The mount covers your entire working directory, including + untracked files and files excluded by `.gitignore`. Nothing the agent + does inside the VM can write back through that mount, but all files + under the Git root are readable inside the sandbox. This includes + credential files not tracked by Git, such as `.env`. - The agent works on a private clone that lives inside the sandbox. The clone has its own index, its own refs, and its own working tree. Writes to the clone never reach your host. @@ -182,7 +257,7 @@ The practical guarantees: into your working tree. - Concurrent `git` commands on the host and inside the sandbox cannot race on a shared `.git/index` or shared refs — there is no shared - writable state. + writable Git state. - Credentials, signing keys, and any settings in your repository's `.git/config` stay on the host. The agent's clone has its own independent configuration. @@ -203,4 +278,10 @@ environment variables or files inside the sandbox unless you explicitly set them. This means a compromised sandbox cannot read API keys from the local environment. -For how to store and manage credentials, see [Credentials](credentials.md). +SSH agent forwarding is enabled by default. Private keys stay on the host, but +any process inside the sandbox can ask the forwarded agent to authenticate or +sign data. Docker Sandboxes forwards only sockets it recognizes as SSH agents. +A sandbox receives no SSH agent when forwarding is disabled, the configuration +is unavailable, or the selected socket can't be used. + +For how to store and manage credentials, see [Credentials](../configuration/credentials.md). diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 240f96256a2d..2b84b98f5c57 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -1,36 +1,117 @@ --- title: Troubleshooting -weight: 60 +weight: 130 description: Resolve common issues when using Docker Sandboxes. keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh --- +The following diagnostics and recovery steps apply to local sandboxes. Use +[`sbx --cloud diagnose`](cloud/usage.md#diagnose-cloud-access) to check cloud +connectivity and account access. For cloud files, expiration, and network access, see +[Cloud sandboxes](cloud/). Local daemon restarts and `sbx reset` do not repair +cloud sandbox state. + ## Run diagnostics Before digging into a specific issue, run [`sbx diagnose`](/reference/cli/sbx/diagnose/) to check for common problems -with your installation, such as a missing CLI binary, an unresponsive daemon, -a CLI/daemon version mismatch, missing storage directories, or broken -authentication. +with your installation, such as a missing CLI binary, daemon reachability +problems, a CLI/daemon version mismatch, missing storage directories, or +broken authentication. ```console $ sbx diagnose ``` The command prints a summary of checks that passed, warned, or failed, along -with suggested fixes. Use `--output json` to get machine-readable output, or -`--output github-issue` to generate a Markdown snippet suitable for pasting +with suggested fixes. Use `--json` or `--format yaml` for machine-readable +output, or `--format github-issue` to generate a Markdown snippet suitable for pasting into a GitHub issue. +## Sandbox is not responding + +If `sbx ls` shows `running (not responding)`, Docker Sandboxes has detected +that the sandbox isn't responding to commands. Stop and start that sandbox, +then retry your command: + +```console +$ sbx stop <SANDBOX_NAME> +$ sbx start <SANDBOX_NAME> +``` + +Files saved in the sandbox are kept when you stop and start it. + +## Restart the sandbox daemon + +If sandbox commands hang, fail to connect to the daemon, or keep returning +daemon errors, restart the sandbox daemon before resetting sandbox state: + +```console +$ sbx daemon restart +``` + +Then retry the command that failed. Restarting the daemon doesn't delete +sandbox data. If the issue persists or state is corrupted, use +[`sbx reset`](/reference/cli/sbx/reset/). + ## Resetting sandboxes If you hit persistent issues or corrupted state, run [`sbx reset`](/reference/cli/sbx/reset/) to stop all VMs and delete all sandbox data. Create fresh sandboxes afterwards. +## Sandbox doesn't contain my project files + +Starting with `sbx` version 0.42.0, the workspace path is optional for +`sbx create`. When you omit it, the command creates a mountless sandbox. For +example, these commands create and attach to a sandbox without mounting your +host project files: + +```console +$ sbx create --name <sandbox-name> <agent> +$ sbx run --name <sandbox-name> +``` + +By contrast, `sbx run` mounts the current directory when you don't pass a +workspace path: + +```console +$ sbx run <agent> +``` + +A sandbox's workspace configuration is fixed when the sandbox is created. To +reuse the name of an existing mountless sandbox, first +[copy out any files you want to keep](usage.md#copy-files-between-host-and-sandbox), +then remove and recreate it with a workspace path: + +```console +$ sbx rm <sandbox-name> +$ sbx run --name <sandbox-name> <agent> +``` + +See [Choose a workspace](usage.md#choose-a-workspace) for mountless, direct, +and clone-mode behavior. + +## Kiro, Copilot, or Droid shorthand fails + +In Docker Sandboxes v0.42, `sbx run kiro`, `sbx run copilot`, and +`sbx run droid` fail because these agents moved from built-in agents to +public kits and their shorthand names aren't resolved in this release. + +[Upgrade Docker Sandboxes](install.md) to v0.43.0 or later to launch +these agents by name again. If you need to stay on v0.42, use the full kit +reference for your agent: + +```console +$ sbx run docker.io/sbx/kiro-kit:latest +$ sbx run docker.io/sbx/copilot-kit:latest +$ sbx run docker.io/sbx/droid-kit:latest +``` + ## Agent can't install packages or reach an API -Sandboxes use a [deny-by-default network policy](governance/local.md). +Sandboxes use [network access rules](governance/access-controls/network.md) to +control outbound traffic. If the agent fails to install packages or call an external API, the target domain is likely not in the allow list. Check which requests are being blocked: @@ -52,27 +133,52 @@ $ sbx policy allow network "**" If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See -[Organization governance](governance/org.md). +[Organization policies](governance/access-controls/organization.md). + +## Kit fails to install: source not in allowlist + +If loading a kit fails with a message like its source is not in your +allowlist: + +```console +$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" +``` + +`sbx` restricts kit installs to an allowlist of sources, which defaults to +Docker Hub (`docker.io/`) only. Add the kit's publisher to the +[`kit.allowedSources`](configuration/settings.md#kitallowedsources) setting, +keeping the entries you want to retain: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]' +``` + +Then run the command again. For details, including how to allow local kits or +any remote source, see [Restrict kit sources](/manuals/ai/sandboxes/customize/use-kits.md#restrict-kit-sources). ## SSH and other non-HTTP connections fail -Non-HTTP TCP connections like SSH can be allowed by adding a policy rule for -the destination IP address and port. For example, to allow SSH to a specific -host: +Non-HTTP TCP connections such as SSH can be allowed by adding a policy rule for +the destination. Hostname rules work for these connections because the sandbox +recovers the hostname from its DNS resolver when the protocol doesn't include +one: ```console -$ sbx policy allow network "10.1.2.3:22" +$ sbx policy allow network "myhost:22" ``` -Hostname-based rules (for example, `myhost:22`) don't work for non-HTTP -connections because the proxy can't resolve the hostname to an IP address in -this context. Use the IP address directly. +If the destination is reached by IP address without a DNS lookup, the hostname +can't be recovered. Use an address-based rule in that case: + +```console +$ sbx policy allow network "10.1.2.3:22" +``` -UDP and ICMP traffic is blocked at the network layer and can't be unblocked -with policy rules. +UDP requires [experimental UDP egress](governance/access-controls/local.md#allow-outbound-udp) +and UDP allow rules. ICMP is blocked and can't be unblocked with policy rules. For Git operations over SSH, you can either add an allow rule for the Git -server's IP address or use HTTPS URLs instead: +server's hostname or IP address, or use HTTPS URLs instead: ```console $ git clone https://github.com/owner/repo.git @@ -82,7 +188,7 @@ $ git clone https://github.com/owner/repo.git If a request to `127.0.0.1` or a local network IP returns "connection refused" from inside a sandbox, the address is not reachable from within the sandbox VM. -See [Accessing host services from a sandbox](usage.md#accessing-host-services-from-a-sandbox). +See [Accessing host services from a sandbox](workflows/development.md#accessing-host-services-from-a-sandbox). ## Docker authentication failure @@ -97,7 +203,7 @@ If the agent can't reach its model provider or you see API key errors, the key is likely invalid, expired, or not configured. Verify it's set in your shell configuration file and that you sourced it or opened a new terminal. -For agents that use the [credential proxy](security/credentials.md), make sure +For agents that use the [credential proxy](configuration/credentials.md), make sure you haven't set the API key to an invalid value inside the sandbox — the proxy injects credentials automatically on outbound requests. @@ -106,9 +212,23 @@ If credentials are configured correctly but API calls still fail, check the `transparent` proxy don't get credential injection. This can happen when a client inside the sandbox (such as a process in a Docker container) isn't configured to use the forward proxy. See -[Monitoring network activity](governance/monitoring.md) +[Monitoring network activity](governance/monitor-and-enforce/monitoring.md) for details. +## MCP server streams stall + +If a remote MCP server's HTTP/2 handling stalls long-lived streams, register +it with `--disable-http2` to use HTTP/1.1: + +```console +$ sbx mcp add acme --url https://mcp.acme.com/mcp --disable-http2 +``` + +Replace the example URL with your MCP endpoint. The setting applies to later +connections to this server. The flag requires `--url` and can't be used with +`--command` or `--local`. For registration options, see +[Register an MCP server](mcp-gateway.md#register-an-mcp-server). + ## API calls fail with a certificate error If your organization uses a proxy that inspects HTTPS traffic, agent requests @@ -118,9 +238,10 @@ your organization's internal root CA inside the sandbox so the agent and its SDKs trust certificates signed by the proxy. Certificate errors can stop a request before the credential proxy can inject credentials. -For repeatable setup, create a [sandbox kit](customize/kits.md) that installs -the CA when the sandbox is created. See -[Install an internal CA certificate](customize/kit-examples.md#install-an-internal-ca-certificate) +For repeatable setup with a built-in agent, create a +[v2 mixin kit](customize/kits-v2.md) that installs the CA when the +sandbox is created. See +[Install an internal CA certificate](customize/kits-v2.md#install-an-internal-ca-certificate) for an example kit. Use a PEM-encoded certificate with a `.crt` extension. If traffic can be signed @@ -163,40 +284,88 @@ the egress path in the **PROXY** column: internal CA applies. The only difference between them is whether the client knows it's talking to a proxy. -## Docker build export fails with an ownership error +### Certificate errors during Docker builds + +Containers started by the sandbox's Docker Engine have their own trust stores. +They don't inherit the sandbox's installed certificates. If an HTTPS download +in a Dockerfile fails with `self signed certificate in certificate chain`, +install the proxy CA in the build image before the download. + +From a shell inside the sandbox, write its proxy CA into your build context: + +```console +$ printf '%s' "$PROXY_CA_CERT_B64" | base64 -d > sbx-proxy-ca.crt +``` + +For a Debian-based image with `ca-certificates` installed, copy the certificate +and update the trust store before commands that make HTTPS requests: + +```dockerfile +FROM python:3.13-slim +COPY sbx-proxy-ca.crt /usr/local/share/ca-certificates/sbx-proxy-ca.crt +RUN update-ca-certificates +``` + +Build inside the sandbox, passing its proxy settings to the build: + +```console +$ docker build --build-arg HTTP_PROXY --build-arg HTTPS_PROXY --build-arg NO_PROXY -t my-app . +``` + +If your organization also inspects TLS, install its root CA in the build image +as a separate `.crt` file before `update-ca-certificates`. Keep the system CA +bundle intact so the image trusts both proxies and public certificate +authorities. The earlier [certificate troubleshooting](#api-calls-fail-with-a-certificate-error) +explains which proxy paths need each CA. + +Keep the generated proxy certificate out of version control. Regenerate it and +rebuild the image if the sandbox proxy CA changes. + +## Sandbox runs out of disk space -Running `docker build` with the local exporter (`--output=type=local` or `-o -<path>`) inside a sandbox fails because the exporter tries to `lchown` output -files to preserve ownership from the build. Processes inside the sandbox run as -an unprivileged user without `CAP_CHOWN`, so the operation is denied. +The sandbox root (`/`) filesystem defaults to 20 GB. To increase it, set +`DOCKER_SANDBOXES_ROOT_SIZE` before creating the sandbox: -Use the tar exporter and extract the archive instead: +```console +$ DOCKER_SANDBOXES_ROOT_SIZE=40g sbx run claude +``` + +`DOCKER_SANDBOXES_ROOT_SIZE` controls the root filesystem size. The Docker data +disk at `/var/lib/docker` is independent and defaults to 10 GB. To change the +Docker data disk size for a sandbox, set `DOCKER_SANDBOXES_DOCKER_SIZE` when you +create it: ```console -$ mkdir -p ./result -$ docker build --output type=tar,dest=- . | tar xf - -C ./result +$ DOCKER_SANDBOXES_DOCKER_SIZE=20g sbx run claude ``` -Extracting the tar archive as the current user avoids the `chown` call. +The Docker data disk must be at least 512 MiB. The environment variable doesn't +resize existing volumes. + +For a [clone-mode sandbox](usage.md#clone-mode), set +`DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE` before creating the sandbox to +configure the cloned workspace volume capacity. The variable accepts +human-readable size strings such as `100g`: + +```console +$ DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE=100g sbx run --clone claude . +``` ## Filesystem operations are slow in large repositories Filesystem operations such as `git status`, `git log`, or directory scans can -be noticeably slow when the sandbox workspace is mounted in direct mode (the -default for workspaces without `--clone`). The slowness occurs because virtiofs -caching is disabled by default to prevent data corruption. +be noticeably slow when you pass a workspace path and use direct mode. +Virtiofs caching speeds up these workloads. Clone-mode sandboxes always enable +it, so this tuning applies only to direct mode. -To speed up filesystem-intensive workloads, opt into virtiofs caching when -creating the sandbox: +Virtiofs caching is enabled by default on all operating systems. If you +experience Git index corruption or unexpected file content, disable caching +with the kill switch and recreate the sandbox: ```console -$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=1 sbx run <template> +$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent> ``` -The setting is persisted in the sandbox spec and applies for the lifetime of -that sandbox. If you experience Git index corruption or unexpected file content -after enabling the cache, remove the sandbox and recreate it without the flag. - ## Clone mode reports "not in a Git repository" on WSL On Windows, running [`sbx run --clone`](usage.md#clone-mode) against a @@ -205,7 +374,7 @@ though the directory is a valid Git repository: ```console > sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo -ERROR: --clone requires a Git repository, but \\wsl.localhost\Ubuntu\home\you\repo is not in a Git repository +error: --clone requires a Git repository, but \\wsl.localhost\Ubuntu\home\you\repo is not in a Git repository ``` The cause is Git's dubious ownership check. When Git on Windows accesses a @@ -223,25 +392,41 @@ the command again: ```console > git config --global --add safe.directory '%(prefix)///wsl.localhost/Ubuntu/home/you/repo' > sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo -✓ Git repository detected: \\wsl.localhost\Ubuntu\home\you\repo ``` -## Stale Git worktree after removing a sandbox +## SSH agent socket is missing -If you used `--branch`, worktree cleanup during `sbx rm` is best-effort. If -it fails, the sandbox is removed but the branch and worktree are left behind. -If `git worktree list` shows a stale worktree in `.sbx/` after removing a -sandbox, clean it up manually: +If `SSH_AUTH_SOCK` is set inside a sandbox but `ssh-add -L` reports +`No such file or directory`, check whether your custom template includes +`socat`. Docker Sandboxes uses it to create the socket that forwards requests +to your host SSH agent. Installing OpenSSH client tools alone isn't enough. -```console -$ git worktree remove .sbx/<sandbox-name>-worktrees/<branch-name> -$ git branch -D <branch-name> -``` +For an Ubuntu-based custom template, add `socat` to the packages installed as +root in your Dockerfile, then rebuild the template and create a sandbox from +it. Docker-provided sandbox templates already include `socat`. + +If the socket exists but forwarding still fails, check the +[SSH agent settings](configuration/credentials.md#ssh-agent). ## Sandbox commits aren't signed Docker Sandboxes can sign Git commits with SSH keys from your host agent. -For setup steps, see [Signed commits](usage.md#signed-commits). +For setup steps, see [Commit signing](workflows/git.md#commit-signing). + +Forwarding is enabled by default. Check +[`ssh.agentForwardingEnabled`](configuration/settings.md#sshagentforwardingenabled) +and [`ssh.agentSocketPath`](configuration/settings.md#sshagentsocketpath) to +confirm that forwarding is enabled and inspect the socket selection: + +```console +$ sbx settings get ssh.agentForwardingEnabled +$ sbx settings get ssh.agentSocketPath +``` + +If you use each client's current `SSH_AUTH_SOCK`, reconnect from a shell where +it points to the intended agent. If `ssh.agentSocketPath` returns a path, +confirm that it points to an active host agent. After changing forwarding or +the socket selection, run `sbx daemon restart`. If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach the forwarded agent, but the host agent doesn't have a loaded key. Load the @@ -292,7 +477,7 @@ If you downgrade `sbx` to a version older than the one that last managed your local state, the daemon may fail to start with a database version mismatch: ```text -ERROR: failed to start backend in-process: start backend: creating containerd +error: failed to start backend in-process: start backend: creating containerd server: ... database is at major version 6, but this binary only supports up to major version 1 ``` @@ -347,6 +532,21 @@ If you have set custom `XDG_STATE_HOME`, `XDG_CACHE_HOME`, or {{< /tab >}} {{< /tabs >}} +## Enable automatic diagnostics uploads + +To opt in to automatic diagnostics uploads after certain daemon errors, set +[`diagnostics.autoUpload`](configuration/settings.md#diagnosticsautoupload) to +`yes`: + +```console +$ sbx settings set diagnostics.autoUpload yes +``` + +Automatic bundles include basic system information and client, daemon, crash, +and MCP logs. Docker Sandboxes redacts recognized identity values and +credential patterns, but collected logs can still contain user content. Failed +uploads remain in a local queue for a later retry. + ## Report an issue If you've exhausted the steps above and the problem persists, file a GitHub @@ -363,3 +563,7 @@ The bundle contains daemon logs, diagnostic check results, and basic system information. When `--upload` is confirmed, the bundle is uploaded to Docker support and the command prints a diagnostics ID. Include this ID in your issue so the team can correlate it with the uploaded bundle. + +Without terminal input, `sbx diagnose --upload` saves the bundle locally and +skips the upload. Check for a diagnostics ID to confirm that the upload +succeeded. diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 5d6ba2c3d3ee..6864a99f9f0d 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -1,11 +1,30 @@ --- title: Usage -weight: 20 -description: Common patterns for working with sandboxes. -keywords: docker sandboxes, sbx, usage, run, policy, secrets, branches, git, workspaces, ssh +weight: 30 +description: Basic sbx commands for creating, managing, and connecting to Docker Sandboxes. +keywords: docker sandboxes, sbx, usage, run, create, stop, remove, ports, workspaces, templates, save, load --- -## Working with sandboxes +This page describes local sandboxes. For cloud commands, file transfers, ports, +and expiration, see [Use cloud sandboxes](cloud/usage.md). + +Use this page as a command-oriented guide to day-to-day `sbx` operations. For +scenario-based recommendations, see [Workflow patterns](workflows/). For script +output and the v0.48.0 CLI migration, see +[CI and headless use](workflows/automation.md#update-scripts-for-v0480). + +## Sign in + +Sign in from a terminal: + +```console +$ sbx login +``` + +For scripts or CI runners where a browser isn't available, see +[CI and headless use](workflows/automation.md). + +## Start, stop, and remove The basic workflow is [`run`](/reference/cli/sbx/run/) to start, [`ls`](/reference/cli/sbx/ls/) to check status, @@ -13,193 +32,314 @@ The basic workflow is [`run`](/reference/cli/sbx/run/) to start, [`rm`](/reference/cli/sbx/rm/) to clean up: ```console -$ sbx run claude # start an agent +$ sbx run claude # start an agent in the current directory $ sbx ls # see what's running $ sbx stop my-sandbox # pause it $ sbx rm my-sandbox # delete it entirely ``` -To get a shell inside a running sandbox — useful for inspecting the environment, -checking Docker containers, or manually installing something: +`sbx rm` asks for confirmation before deleting a sandbox. Use `--force` to +skip the prompt. This flag also permits removal when the sandbox has an active +session — an open attach, SSH connection, or in-flight SFTP transfer: ```console -$ sbx exec -it <sandbox-name> bash +$ sbx rm --force my-sandbox ``` -If you need a clean slate, remove the sandbox and re-run: +If you need a clean slate, remove the sandbox and run it again: ```console +$ sbx stop my-sandbox $ sbx rm my-sandbox $ sbx run claude ``` -## Non-interactive login +To remove all stopped local sandboxes, use `sbx prune`. Running sandboxes are +never removed. Preview the sandboxes that would be removed, or filter out +sandboxes stopped within the last week: + +```console +$ sbx prune --dry-run +$ sbx prune --filter until=168h +``` + +The `until` filter uses the time the sandbox stopped. It accepts a duration +such as `168h`, an RFC 3339 timestamp, or a Unix timestamp. The older +`since=<duration>` filter remains supported. + +Run `sbx prune` without flags to confirm and remove all stopped sandboxes. + +### Remove a sandbox when the agent exits -For CI environments and scripts where a browser is not available, use a -Docker Personal Access Token (PAT) with `--username` and `--password-stdin`: +Pass `--rm` to `sbx run` for a throwaway session. The sandbox is removed when +the agent exits, without a confirmation prompt: ```console -$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin +$ sbx run --rm claude ``` -`--password-stdin` reads the token from standard input to keep it out of -your shell history. Generate a PAT from your -[Docker account settings](https://app.docker.com/settings/personal-access-tokens) -with at least **Read** scope. +The sandbox is removed however the agent exits, and `sbx run` exits with the +agent's exit status. If `sbx run` created the sandbox and the agent fails +to start, the sandbox is also removed. If you reattach to an existing sandbox +with `--rm`, that sandbox is removed only after its agent session finishes. -## Interactive mode +`--rm` needs an attached agent session to know when to remove the sandbox, so +you can't combine it with `--detach` or `--detach-keys`. -Running `sbx` with no subcommands opens an interactive terminal dashboard: +## Choose a workspace + +`sbx run` mounts the current directory when you don't pass a workspace path. +Pass a path to mount another directory instead: ```console -$ sbx +$ sbx run claude +$ sbx run claude ~/my-project ``` -The dashboard shows all your sandboxes as cards with live status, CPU, and -memory usage. From here you can: +The first workspace path is the primary workspace. The agent starts there, and +`sbx exec` uses it as the default working directory. The host directory is +mounted at the same absolute path inside the sandbox. When you don't pass a +path to `sbx run`, the current directory is the primary workspace. -- **Create** a sandbox (`c`). -- **Start or stop** a sandbox (`s`). -- **Attach** to an agent session (`Enter`), same as `sbx run`. -- **Open a shell** inside the sandbox (`x`), same as `sbx exec`. -- **Remove** a sandbox (`r`). +Starting with `sbx` version 0.42.0, workspace paths are optional for +`sbx create`. Omit them to create a mountless sandbox without a host workspace +bind mount, then attach to the sandbox by name: -The dashboard also includes a network governance panel where you can monitor -outbound connections made by your sandboxes and manage network rules. Use `tab` -to switch between the sandboxes panel and the network panel. +```console +$ sbx create --name scratch claude +$ sbx run --name scratch +``` -From the network panel you can browse connection logs, allow or block specific -hosts, and add custom network rules. Press `?` to see all keyboard shortcuts. +In a mountless sandbox, the agent starts in the template image's working +directory. Docker-provided templates use `/home/agent/workspace`. Files there +persist across stops and restarts but are deleted when you remove the sandbox. +Assign the sandbox a name so you can reconnect to it, and use +[`sbx cp`](#copy-files-between-host-and-sandbox) to transfer files between the +sandbox and the host. -## Git workflow +## Reconnect and name sandboxes -When your workspace is a Git repository, you can choose one of two ways -to share it with a sandbox. You make the choice when you create the -sandbox: +Sandboxes persist after the agent exits. Running the same workspace path again +reconnects to the existing sandbox rather than creating another sandbox: -- **Direct mode (default)** — the agent has read-write access to your - working tree. Changes the agent makes appear on your host immediately. -- **[Clone mode](#clone-mode) (`--clone`)** — the agent works on a private - Git clone inside the sandbox, with your host repository mounted - read-only. The sandbox exposes its clone as a Git remote on your host, - so you fetch the agent's commits the same way you'd fetch from any - other remote. +```console +$ sbx run claude ~/my-project # creates sandbox +$ sbx run claude ~/my-project # reconnects to same sandbox +``` -For a comparison of approaches and step-by-step recipes, see -[Workflow patterns](workflows.md#git-workflows). For the security model -behind each mode, see -[Workspace isolation](security/isolation.md#workspace-isolation). +Use `--name` to give a sandbox an explicit identity: -### Direct mode (default) +```console +$ sbx run --name my-project claude +``` -The agent edits your working tree directly. Stage, commit, and push as you -normally would. If you run multiple agents on the same repository at the -same time, they may step on each other's changes — use -[clone mode](#clone-mode) to give each agent its own isolated workspace. +Once a named sandbox exists, reattach from any working directory with +`sbx run --name`. You can omit the agent name when reattaching: -### Clone mode +```console +$ sbx run --name my-project # re-attaches from anywhere +$ sbx run claude --name my-project # same, with agent confirmed +``` -In clone mode, the sandbox becomes a Git remote on your host. The agent -commits inside the sandbox; you pull its work back out by fetching from -that remote. +To run multiple sandboxes against the same workspace, give each a distinct +name: -> [!NOTE] -> Clone mode was introduced in `sbx` v0.31.0 and replaces the `--branch` -> flag used in earlier versions. If your CLI doesn't recognize `--clone`, -> update to the latest version. +```console +$ sbx run claude --name feature ~/my-project +$ sbx run claude --name spike ~/my-project +``` + +## Create without attaching + +[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to the +agent. To create a sandbox with the current directory mounted, without +attaching to it: ```console -$ sbx run --clone claude +$ sbx create --name my-project claude . ``` -You can also create the sandbox in the background and attach later: +Omit the path to create a mountless sandbox instead. Attach later with +`sbx run --name`: ```console -$ sbx create --clone --name my-sandbox claude . -$ sbx run my-sandbox +$ sbx create --name scratch claude +$ sbx run --name scratch +``` + +After `sbx create` finishes, the local sandbox stops automatically when no +sessions keep it running. Its files and configuration persist. Running +`sbx run --name <sandbox-name>` starts it again and attaches you to the agent. + +### Keep a sandbox running in the background + +To keep a sandbox running after every session ends, for example to serve an +application on a [published port](#publish-ports), start it with +`sbx run --detach` (`-d`). The command starts the sandbox, prints its ID, +and returns without opening an agent session: + +```console +$ sbx run -d --name my-project claude . ``` -The clone follows whichever ref your host repository has checked out at -create time. No new branch is created automatically. +A detached sandbox keeps running until you stop it with `sbx stop` or remove +it with `sbx rm`. You can attach to it with `sbx run --name` or run commands +with `sbx exec`, and it keeps running after those sessions end. + +Running `sbx run -d --name <sandbox-name>` against an existing sandbox, such +as one created with `sbx create`, switches it to detached mode permanently. To +return to the default behavior, remove the sandbox and create it again. + +## Set environment variables > [!NOTE] -> Clone mode is fixed at create time. To switch an existing sandbox to -> clone mode, remove it and recreate it with `sbx create --clone`. +> The `-e`/`--env` and `--env-file` flags require `sbx` version 0.39.0 or +> later. -The CLI copies the Git remotes from your host repository (`origin`, -`upstream`, and so on) into the in-sandbox clone. The agent can push to -your fork directly using the same remote names. Local-path remotes -(`file://` URLs, filesystem paths) aren't copied, since they aren't -reachable from inside the sandbox. +Pass `-e` or `--env` to `sbx run` or `sbx create` to set an environment +variable in the sandbox: -#### Sandbox lifecycle and the Git remote +```console +$ sbx run -e LOG_LEVEL=debug claude +``` -The Git daemon that exposes the in-sandbox clone runs as part of the -sandbox itself. It's only reachable while the sandbox is running: +Specify a variable name without a value to copy its value from the host +environment: -- `sbx stop` shuts down the daemon. `git fetch sandbox-<name>` fails until - the sandbox starts again. -- Restarting the sandbox assigns a new ephemeral port to the daemon. The - CLI updates the `sandbox-<name>` remote URL in your host repository's - Git config automatically, so fetching continues to work without manual - reconfiguration. -- `sbx rm` removes the sandbox, the daemon, the published port, and the - `sandbox-<name>` remote entry from your host repository. +```console +$ export API_URL=https://api.example.com +$ sbx run -e API_URL claude +``` -> [!WARNING] -> Removing a clone-mode sandbox drops the in-sandbox clone along with it. -> Any commits you haven't fetched (`git fetch sandbox-<name>`) or pushed -> to an upstream remote are lost. `sbx rm` prints a warning before -> deleting a clone-mode sandbox — review it before confirming. +To load multiple variables, pass one or more environment files: -#### Restrictions +```console +$ sbx create --name my-project --env-file .env.sandbox claude . +``` -Clone mode requires a Git repository as the primary workspace, and is -rejected at create time in two cases: +The flags follow `docker run` precedence rules. Values passed with `-e` +override values from environment files. When you pass multiple environment +files, a value in a later file overrides the same variable in an earlier file. -- `--clone` on a non-Git workspace. Omit `--clone` for non-Git workspaces. -- `--clone` from inside a Git worktree (other than the main one). The - read-only bind mount can't resolve the worktree's `.git` pointer file. - Run `sbx create --clone` from the main repository checkout instead. +When either command creates a sandbox, the variables are stored with the +sandbox. They are also available to the agent session started by `sbx run`. +When `sbx run` re-attaches to an existing sandbox, the variables apply to that +agent session without changing the sandbox's stored environment. To set +variables for one command instead, use `sbx exec -e` or +`sbx exec --env-file`. -You can also create a Git worktree yourself and run an agent inside it -without `--clone`, but the sandbox won't have access to the `.git` -directory in the parent repository, so the agent can't use Git at all. -See [Host worktree](workflows.md#host-worktree) in Workflow patterns. +To persist a variable across future sessions of an existing sandbox, append an +export to `/etc/sandbox-persistent.sh`: -## Reconnecting and naming +```console +$ sbx exec <sandbox-name> bash -c "echo 'export INTERNAL_API_URL=https://api.example.com' >> /etc/sandbox-persistent.sh" +``` -Sandboxes persist after the agent exits. Running the same workspace path again -reconnects to the existing sandbox rather than creating a new one: +The `bash -c` wrapper ensures the `>>` redirect runs inside the sandbox instead +of on your host. The file is sourced when Bash starts inside the sandbox, +including for interactive sessions and agents started with `sbx run`. A command +passed directly to `sbx exec` doesn't start a shell. Wrap that command in +`bash -c` if it needs variables from the persistent environment file. + +A variable added to the file only takes effect for sessions and agents started +afterward. Restart a running agent, or stop and start the sandbox, to pick up +the new value. + +Environment variables are readable by processes inside the sandbox. For API +keys and other credentials, use [`sbx secret set`](configuration/credentials.md#store-a-secret) +for a supported service or the experimental +[`sbx secret set-custom`](configuration/credentials.md#custom-secrets) for a +credential sent to known hosts. The host-side proxy can then inject the real +value without exposing it to the agent. + +## Run commands inside a sandbox + +To get a shell inside a running sandbox, use [`sbx exec`](/reference/cli/sbx/exec/): ```console -$ sbx run claude ~/my-project # creates sandbox -$ sbx run claude ~/my-project # reconnects to same sandbox +$ sbx exec -it <sandbox-name> bash ``` -Use `--name` to make this explicit and avoid ambiguity: +Without `--workdir`, the command starts in the sandbox's primary workspace. In +a mountless sandbox, it starts in the container image's working directory. + +`sbx exec` runs commands in the foreground. Detached execution (`-d` or +`--detach`) isn't supported. + +## Interactive mode + +Running `sbx` with no subcommands opens an interactive terminal dashboard: ```console -$ sbx run claude --name my-project +$ sbx ``` -## Creating without attaching +The dashboard shows all your sandboxes as cards with live status, CPU, and +memory usage. From here you can: + +- **Create** a sandbox (`c`). +- **Start or stop** a sandbox (`s`). +- **Attach** to an agent session (`Enter`), same as `sbx run`. +- **Open a shell** inside the sandbox (`x`), same as `sbx exec`. +- **Remove** a sandbox (`r`). + +The dashboard also includes a network governance panel where you can monitor +outbound connections made by your sandboxes and manage network rules. Use `tab` +to switch between the sandboxes panel and the network panel. + +From the network panel you can browse connection logs, allow or block specific +hosts, and add custom network rules. Press `?` to see all keyboard shortcuts. + +At selection and text prompts, Enter accepts the default. Ctrl-D cancels the +prompt. Declining a required confirmation returns a non-zero exit status. -[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to -the agent. To create a sandbox in the background without attaching: +## Git workspace modes + +When your primary workspace is a Git repository, choose how the sandbox receives +it when you create the sandbox: + +- Direct mode is the default for `sbx run`. It also applies when you pass a + workspace path to `sbx create`. The agent has read-write access to your + working tree, and changes appear on your host immediately. +- [Clone mode](#clone-mode) uses `--clone`. The agent edits a separate Git clone + inside the sandbox. Its changes stay there until you fetch them or the agent + pushes them. Your host repository is also available at + `/run/sandbox/source`, but only with read access. + +For guidance on branch strategy, fetching work from a sandbox, and parallel +agent workflows, see [Git workflows](workflows/git.md). For the +security model behind each mode, see +[Workspace isolation](security/isolation.md#workspace-isolation). + +### Clone mode + +To create a clone-mode sandbox, pass `--clone` when you run or create it: ```console -$ sbx create claude . +$ sbx run --clone claude . ``` -Unlike `run`, `create` requires an explicit workspace path. It uses direct -mode by default, or pass `--clone` for [clone mode](#clone-mode). Attach -later with `sbx run`: +You can also create the sandbox in the background and attach later: ```console -$ sbx run claude-my-project +$ sbx create --clone --name my-sandbox claude . +$ sbx run --name my-sandbox ``` +Clone mode has a few create-time constraints: + +- Clone mode is fixed at create time. To switch an existing sandbox to clone + mode, remove it and recreate it with `sbx create --clone`. +- The clone follows whichever ref your host repository has checked out at create + time. No branch is created automatically. +- The primary workspace must be a Git repository. Omit `--clone` for non-Git + workspaces. +- Clone mode is rejected from inside a Git worktree other than the main one. The + read-only bind mount can't resolve the worktree's `.git` pointer file. Run + `sbx create --clone <agent> .` from the main repository checkout instead. +- Removing a clone-mode sandbox drops the in-sandbox clone. Fetch or push any + commits you want to keep before you remove it. + ## Multiple workspaces You can mount extra directories into a sandbox alongside the main workspace. @@ -207,16 +347,16 @@ The first path is the primary workspace — the agent starts here, and the sandbox's in-container Git clone is populated from this directory if you use `--clone`. Extra workspaces are always mounted directly. -All workspaces appear inside the sandbox at their absolute host paths. Append -`:ro` to mount an extra workspace read-only — useful for reference material or -shared libraries the agent shouldn't modify: +Each workspace path appears inside the sandbox at the same absolute path as on +the host. Append `:ro` to mount an extra workspace read-only — useful for +reference material or shared libraries the agent shouldn't modify: ```console $ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro ``` -Each sandbox is completely isolated, so you can also run separate projects -side-by-side. Remove unused sandboxes when you're done to reclaim disk space: +You can also run separate projects side-by-side. Remove unused sandboxes when +you're done to reclaim disk space: ```console $ sbx run claude ~/project-a @@ -224,62 +364,64 @@ $ sbx run claude ~/project-b $ sbx rm <sandbox-name> # when finished ``` -## Copying files between host and sandbox +## Copy files between host and sandbox Use [`sbx cp`](/reference/cli/sbx/cp/) to copy files or directories between your host and a sandbox. This is useful for one-off files that aren't part of a -mounted workspace, such as generated output, logs, or setup files. +mounted workspace, such as generated output, logs, or setup files. The sandbox +path must be absolute. `sbx cp` doesn't resolve relative paths such as `.` +against the sandbox's default working directory. + +For example, copy files to or from the default working directory used by a +Docker-provided agent template: ```console -$ sbx cp ./config.json my-sandbox:/home/user/ -$ sbx cp my-sandbox:/home/user/output.log ./ -$ sbx cp ./src/ my-sandbox:/home/user/src +$ sbx cp ./config.json my-sandbox:/home/agent/workspace/ +$ sbx cp my-sandbox:/home/agent/workspace/output.log ./ +$ sbx cp ./src/ my-sandbox:/home/agent/workspace/src ``` One side of the copy must use `SANDBOX:PATH`. Copying directly between two sandboxes isn't supported. -## Installing dependencies and using Docker - -Ask the agent to install what's needed — it has sudo access, and installed -packages persist for the sandbox's lifetime. For teams or repeated setups, -see [Customize](customize/) for reusable templates and declarative kits. +## Publish ports -Agents can also build Docker images, run containers, and use -[Compose](https://docs.docker.com/compose/). Everything runs inside the sandbox's private Docker -daemon, so containers started by the agent never appear in your host's -`docker ps`. When you remove the sandbox, all images, containers, and volumes -inside it are deleted with it. +Sandboxes are [network-isolated](security/isolation.md) — your browser or local +tools can't reach a server running inside one by default. A port mapping of +`8080:3000` publishes sandbox port 3000 on host port 8080. -## Accessing services in the sandbox +If you know which ports you need, publish them when you create the sandbox: -Sandboxes are [network-isolated](security/isolation.md) — your browser or local -tools can't reach a server running inside one by default. Use -[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into -a running sandbox. +```console +$ sbx run --publish 8080:3000 --name my-sandbox claude +``` -The common case: an agent has started a dev server or API, and you want to open -it in your browser or run tests against it. +For an existing sandbox, use [`sbx ports`](/reference/cli/sbx/ports/) to +forward traffic from your host. Publishing a port on a stopped local sandbox +starts it first: ```console -$ sbx ports my-sandbox --publish 8080:3000 # host 8080 → sandbox port 3000 +$ sbx ports my-sandbox --publish 8080:3000 $ open http://localhost:8080 ``` -To let the OS pick a free host port instead of choosing one yourself: +To let the OS pick a free host port instead of choosing one yourself, specify +only the sandbox port. Then use `sbx ports` to check which host port was +assigned: ```console -$ sbx ports my-sandbox --publish 3000 # ephemeral host port -$ sbx ports my-sandbox # check which port was assigned +$ sbx ports my-sandbox --publish 3000 +$ sbx ports my-sandbox ``` -`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` -lists them in detail: +`sbx ls` shows active port mappings alongside each sandbox. `sbx ports` lists +them in detail. The `CREATED` column shows the sandbox age, and the `STATUS` +column identifies sandboxes kept running in detached mode with `(detached)`. ```console $ sbx ls -SANDBOX AGENT STATUS PORTS WORKSPACE -my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj +SANDBOX AGENT STATUS PORTS WORKSPACE CREATED +my-sandbox claude ● running 127.0.0.1:8080->3000/tcp4 /home/user/proj 2m ``` To stop forwarding a port: @@ -288,71 +430,162 @@ To stop forwarding a port: $ sbx ports my-sandbox --unpublish 8080:3000 ``` -A few things to keep in mind: +When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use +`sbx ports` to publish ports on that sandbox. For dev server and host-service +recipes, see +[Local services](workflows/development.md#local-services). + +## What persists + +While a sandbox exists, installed packages, Docker images, configuration +changes, command history, and mountless workspace files all persist across +stops and restarts. When you remove a sandbox, everything inside is deleted. +Host workspace files, including repositories used as clone sources, and the +[shared agent skills store](workflows/agent-skills.md) remain on your host. To +capture changes in the container filesystem, [save a template](#saving-a-sandbox-as-a-template). +For a reproducible environment defined in source, +[author a kit](/manuals/ai/sandboxes/customize/author/_index.md). + +## Saving a sandbox as a template + +Save a sandbox's container filesystem as a reusable template image after +setting up tools or configuration interactively. A template contains image +content; the agent kit still supplies runtime settings such as credentials +and network rules. The examples here reuse templates with built-in agents. + +A saved template isn't a backup of the whole sandbox. Mounted filesystems, +including host workspaces and the Docker store at `/var/lib/docker`, aren't +included. Save any data from those mounts separately. + +> [!WARNING] +> Saving a sandbox captures files in its container filesystem, including any +> secrets stored there. If you manually added API keys, tokens, or other +> credentials to the sandbox, they're embedded in the saved template and +> shared with anyone you distribute it to. To keep credentials out of +> templates, manage them with `sbx secret set` instead — the proxy injects +> them at runtime so they're never written to the filesystem. For more +> information, see [Manage credentials](configuration/credentials.md). + +### Save and reuse + +Stop the sandbox (or let the CLI prompt you), then save it with a name and +tag: + +```console +$ sbx template save my-sandbox my-template:v1 +``` + +The image is stored in the sandbox runtime's local image store. Create a +new sandbox from it with the `-t` flag: + +```console +$ sbx run -t my-template:v1 claude +``` -- **Services must listen on all interfaces** — a service listening only on - `127.0.0.1` inside the sandbox won't be reachable through a published port. - Bind to `0.0.0.0` for IPv4, or `[::]` to accept both IPv4 and IPv6. Most dev - servers default to `127.0.0.1`, so you'll usually need to pass a flag like - `--host 0.0.0.0` or `--host '[::]'` when starting them. -- **`localhost` on the host can resolve to IPv6** — by default, `--publish` - listens on both `127.0.0.1` and `::1`. Your browser or client may pick IPv6 - when resolving `localhost`. If the sandboxed service only listens on IPv4, - the IPv6 connection fails with "connection reset by peer" — even though - `http://127.0.0.1:<port>/` works. To fix it, bind the sandboxed service to - `[::]` so it accepts both families, or restrict the published port to one - family with `--publish 8080:3000/tcp4` (IPv4) or `/tcp6` (IPv6). -- **Not persistent** — published ports are lost when the sandbox stops or the - daemon restarts. Re-publish after restarting. -- **No create-time flag** — unlike `docker run -p`, there's no `--publish` - option on `sbx run` or `sbx create`. Ports can only be published after the - sandbox is running. -- **Unpublish requires the host port** — `--unpublish 3000` is rejected; you - must use `--unpublish 8080:3000`. Run `sbx ports my-sandbox` first if you - used an ephemeral port and need to find the assigned host port. +### List and remove templates -## Accessing host services from a sandbox +List all saved templates: -Services running on your host are reachable from inside a sandbox using the -hostname `host.docker.internal`. -Use this instead of `127.0.0.1` or your machine's local network IP address, -which are not reachable from inside the sandbox. +```console +$ sbx template ls +``` -The sandbox proxy translates `host.docker.internal` to `localhost` before -forwarding the request, so you must add the `localhost` address with the -specific port to your network policy allowlist: +Remove a template you no longer need: ```console -$ sbx policy allow network localhost:11434 +$ sbx template rm my-template:v1 ``` -Then use `host.docker.internal` in any configuration or request that points at -the host service. For example, to verify connectivity from a sandbox shell: +### Export and import + +To share a saved template or move it to another machine, export it as a +tar file: ```console -$ curl http://host.docker.internal:11434 +$ sbx template save my-sandbox my-template:v1 --output my-template.tar ``` -## Rolling out to a team +On the other machine, load the tar file and use it: -When rolling sandboxes out across a team, two features handle different -needs: +```console +$ sbx template load my-template.tar +$ sbx run -t my-template:v1 claude +``` -- [Custom templates and kits](customize/) let you package reusable agent - configurations, MCP servers, base images, and per-project policies. Every - developer pulls them down with their workspace. -- [Organization governance](governance/org.md) lets admins define - network and filesystem rules in the Docker Admin Console. The rules apply - across every developer's sandboxes and take precedence over local policy. - Available on a separate paid subscription. +### Limitations -Customization gives developers shared starting points. Governance gives -admins centralized enforcement. +Agent configuration files are always recreated when a sandbox is created. +Changes to user-level agent configuration files, such as +`/home/agent/.claude/settings.json` and `/home/agent/.claude.json`, do not +persist in saved templates. -## What persists +If the saved template was built for a different agent than the one you +specify in `sbx run`, the CLI prints a warning to stderr with a suggested +command. For example, saving a Claude sandbox and running it with `codex` +suggests `sbx run -t my-template:v1 claude`. -While a sandbox exists, installed packages, Docker images, configuration -changes, and command history all persist across stops and restarts. When you -remove a sandbox, everything inside is deleted — only your workspace files -remain on your host. To preserve a configured environment, create a -[custom template](customize/templates.md). +## Load a template + +To create a sandbox from a template image in a registry, pass its full image +reference to `--template`. Use the agent the image was prepared for: + +```console +$ sbx run --template docker.io/my-org/my-template:v1 claude +``` + +Unlike Docker commands, `sbx` doesn't automatically add the Docker Hub domain +(`docker.io`) to image references. For available images and the built-in agent +workflow, see [Base images](/manuals/ai/sandboxes/customize/author/base-images.md). + +> [!NOTE] +> The Docker daemon used by Docker Sandboxes pulls templates from a +> registry directly; it doesn't share the image store of your local Docker +> daemon on the host. To route Docker Hub image pulls through your +> organization's registry infrastructure, configure a +> [registry mirror](configuration/registry-mirror.md). + +> [!IMPORTANT] +> For Docker Hub, `sbx` reuses your `sbx login` session to pull private +> images. For other registries (GitHub Container Registry, ECR, ACR, a +> self-hosted Nexus, and so on), store pull credentials with +> [`sbx secret set --registry`](configuration/credentials.md#registry-credentials) +> before running the sandbox: +> +> ```console +> $ gh auth token | sbx secret set --registry ghcr.io --password-stdin +> ``` +> +> Without stored credentials, pulls from non-Docker Hub registries are +> anonymous and private images fail to pull. + +For locally-built images, save the image to a tar and load it directly +into the sandbox runtime instead of pulling from a registry: + +```console +$ docker image save my-org/my-template:v1 -o my-template.tar +$ sbx template load my-template.tar +$ sbx run --template my-org/my-template:v1 claude +``` + +`sbx template load` imports the tar into the sandbox runtime's image +store, so the image doesn't need to be reachable from a registry at +sandbox creation time. + +### Template caching + +When creating a sandbox, `sbx` checks the registry for the template image by +default and downloads missing or updated layers. If the pull fails and the +image is cached locally, it can use the cached image. Cached images persist +across sandbox creation and deletion, and are cleared when you run `sbx reset`. + +### Updating agents + +Agent templates include an agent version, which can differ from the agent's +latest release. Updating the `sbx` CLI or pulling an updated template doesn't +update agents inside existing sandboxes. + +To update an installed agent, run its documented update command inside the +sandbox, either from a sandbox shell or with `sbx exec`. Restart the agent +session to use the updated version. The update persists across sandbox stops +and starts, but is deleted when you remove the sandbox. To reuse the updated +agent in other sandboxes, [save a template](#saving-a-sandbox-as-a-template). diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md deleted file mode 100644 index 3151e93d6f2a..000000000000 --- a/content/manuals/ai/sandboxes/workflows.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -title: Workflow patterns -linkTitle: Workflows -weight: 30 -description: Common workflow patterns for Docker Sandboxes, covering git strategies, authenticated tools, commit signing, and CI integration. -keywords: docker sandboxes, sbx, workflows, clone mode, git, branches, commit signing, github cli, ci, headless ---- - -## Git workflows - -Sandboxes support three approaches for working with Git repositories. The -right choice depends on whether you want branch isolation and whether you -plan to run tasks in parallel: - -| | Direct mode | Clone mode (`--clone`) | Host worktree | -| ------------------------- | ---------------- | ---------------------------- | ----------------------------- | -| Branch management | You, on the host | Agent, inside the clone | You, on the host | -| Changes visible on host | Immediately | After fetch or agent push | Immediately | -| Agent can use Git | Yes | Yes | No | -| Parallelism | No | Multiple agents, one sandbox | One sandbox per parallel task | -| Mode fixed at create time | No | Yes | — | - -### Direct mode - -The simplest approach. The sandbox mounts your host working tree directly — -the agent edits files in place and changes appear immediately. You manage -branches yourself. - -1. Check out the branch you want to work on: - - ```console - $ git checkout -b feat/my-feature - ``` - -2. Start the sandbox. No special flags needed: - - ```console - $ sbx run claude - ``` - -3. The agent edits files in your working tree. Review diffs, stage, and - commit as you normally would: - - ```console - $ git diff - $ git add -p - $ git commit - $ git push -u origin feat/my-feature - ``` - -Because the sandbox mounts your working tree, switching branches on the host -also changes what the agent sees. This makes direct mode well-suited for -focused, single-branch work where you're collaborating with the agent -turn-by-turn. - -### Clone mode - -In clone mode, the sandbox gets a private Git clone. The agent manages its -own branches and commits inside that clone; your host working tree is never -touched. When the agent is done, you either fetch its branches to the host or -ask the agent to push directly to your fork. - -Clone mode is designed for parallelism: a single clone-mode sandbox can hold -many branches at once, and subagent orchestrators (such as Claude Code's -[agents view](agents/claude-code.md#agents-view)) can dispatch independent -tasks to separate agents, each working on its own branch or worktree inside -the clone. - -> [!NOTE] -> `--clone` is a create-time flag and cannot be changed on an existing -> sandbox. If you need to run additional non-clone sandboxes for the same -> repository, you would have to remove the clone-mode sandbox first. -> Keep a clone-mode sandbox running across multiple tasks rather than -> recreating it per task. - -#### Single task - -1. Start a clone-mode sandbox: - - ```console - $ sbx run --clone claude - ``` - -2. Ask the agent to create a branch before it starts editing: - - > Create a branch `feat/my-feature` and make the changes. - -3. Fetch the agent's branch when it's done: - - ```console - $ git fetch sandbox-<name> - $ git log sandbox-<name>/feat/my-feature - $ git diff main..sandbox-<name>/feat/my-feature - ``` - -4. Pull the branch to the host and push, or ask the agent to push directly: - - ```console - # Pull to host, then push - $ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature - $ git push -u origin feat/my-feature - $ gh pr create - - # Or ask the agent - # "Push feat/my-feature to origin and open a PR." - ``` - -#### Parallel tasks - -1. Start a clone-mode sandbox and open the - [agents view](agents/claude-code.md#agents-view): - - ```console - $ sbx run --clone claude - ``` - -2. Dispatch each independent task to a separate subagent. Claude Code handles - branch isolation for subagents automatically in agents view. For other - agents (such as Codex), add an instruction to `AGENTS.md` to get the same - behavior: - - ```markdown - Always start each task on a new git branch before making changes. - ``` - -3. Fetch all branches when the agents are done: - - ```console - $ git fetch sandbox-<name> - $ git log sandbox-<name>/feat/task-a - $ git log sandbox-<name>/feat/task-b - ``` - -4. Check out the branches you want to keep and open PRs as normal. - -### Host worktree - -You can create a Git worktree on your host and point the sandbox at it. The -agent edits files directly in the worktree — but because the sandbox mounts -only the worktree directory (not the parent repository), it can't resolve the -`.git` pointer file and has no Git access. The agent can read and write files, -but can't commit, branch, or check status. - -This is useful when you want branch isolation without the create-time -commitment of clone mode, and you're comfortable committing from the host -yourself after reviewing the changes. - -1. Create the worktree on the host: - - ```console - $ git worktree add -b feat/my-feature ../my-feature-work - ``` - -2. Start the sandbox with the worktree as the workspace: - - ```console - $ sbx run claude ../my-feature-work - ``` - -3. The agent edits files. When it's done, commit and push from the host: - - ```console - $ cd ../my-feature-work - $ git diff - $ git add -p && git commit - $ git push -u origin feat/my-feature - $ gh pr create - ``` - -## Commit signing - -Sandboxes forward your host SSH agent into the sandbox, so the agent can -sign commits with your SSH key without the private key ever leaving your -host. - -1. On your host, make sure the signing key is loaded in your SSH agent: - - ```console - $ ssh-add ~/.ssh/id_ed25519 - $ ssh-add -L # confirm the key appears - ``` - -2. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key - directly rather than a file path, since host paths don't exist inside the - sandbox: - - ```console - $ git config --global gpg.format ssh - $ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)" - ``` - -3. Sign commits as usual: - - ```console - $ git commit -S -m "feat: my change" - ``` - -To apply this configuration automatically to every sandbox, use the -[`git-ssh-sign`](https://github.com/docker/sbx-kits-contrib/tree/main/git-ssh-sign) -community kit, which handles all of the above setup. See [Kits](customize/kits.md) -if you want to package it alongside other sandbox customizations. - -For troubleshooting, see -[Sandbox commits aren't signed](troubleshooting.md#sandbox-commits-arent-signed). - -## Authenticated CLI tools - -The sandbox proxy handles API credentials for model providers automatically, -but agents often also need credentials for tools like `gh`, `docker`, or a -secrets manager. The pattern is the same in each case: configure the -credential on your host once, and the sandbox either forwards it via the -proxy or via SSH agent forwarding. - -> [!NOTE] -> The `-g` flag stores a secret globally so all future sandboxes can use it. -> Sandboxes that already exist when you run `sbx secret set -g` do not -> receive the new value. To update a running sandbox, scope the secret to -> it directly: `sbx secret set <sandbox-name> <service>`. - -### GitHub CLI - -Store your GitHub token as a sandbox secret. The proxy injects it into -outbound requests, so `gh` works inside the sandbox without any additional -configuration: - -```console -$ echo "$(gh auth token)" | sbx secret set -g github -``` - -The agent can then create pull requests, open issues, comment on PRs, and -interact with the GitHub API the same way it would from your host: - -```console -# Inside the sandbox -$ gh pr create --title "feat: my feature" --body "..." -$ gh issue list -``` - -The token is never stored in plaintext inside the sandbox. See -[GitHub token](security/credentials.md#github-token) for details. - -### Docker registry - -To push or pull private images, including [templates](customize/templates.md), -configure registry credentials for `sbx` to use. The agent can then run `docker -build` and `docker push`, and `sbx` can resolve private image references, -without any extra authentication: - -```console -$ gh auth token | sbx secret set --registry ghcr.io \ - --username <github-username> --password-stdin -$ echo "$ACR_PASSWORD" | sbx secret set --registry myregistry.azurecr.io \ - --username myuser --password-stdin -``` - -Images and containers built inside the sandbox run on the sandbox's private -Docker daemon, not your host's. They're deleted when the sandbox is removed. - -Docker Hub needs no registry credentials; `sbx` reuses your `sbx login` -session. For information on how registry credentials differ from other secrets, -per-registry username requirements, and global versus per-sandbox scoping, see -[Registry credentials](security/credentials.md#registry-credentials). - -### Sourcing credentials from 1Password - -#### Populating stored secrets with `op read` - -Use `op read` to populate stored secrets without pasting values manually. Store -the value once and it's available to all future sandboxes: - -```console -$ op read "op://Work/GitHub/token" | sbx secret set -g github -$ op read "op://Work/Anthropic/credential" | sbx secret set -g anthropic -``` - -The real value stays on your host; the sandbox sees the proxy-managed -placeholder as usual. - -#### Per-launch injection with `op run` - -To resolve credentials fresh from your vault on each launch without storing -them via `sbx secret set`, use `op run`: - -```console -$ ANTHROPIC_API_KEY="op://Work/Anthropic/credential" op run -- sbx run claude -$ OPENAI_API_KEY="op://Work/OpenAI/key" op run -- sbx run codex -$ GEMINI_API_KEY="op://Work/Google/key" op run -- sbx run gemini -``` - -`op run` resolves each `op://` reference in the environment before executing -`sbx`. The sandbox reads the -[built-in service environment variables](security/credentials.md#built-in-services) -at launch and routes them through its proxy — the credential is never stored in -sbx's state and never appears inside the sandbox container. - -This only applies to those specific credential variables. The sandbox does not -forward arbitrary environment variables from the host into the sandbox. - -For multiple credentials at once, use `--env-file` with a file of `op://` -references: - -```console -$ cat .sbx-secrets.env -ANTHROPIC_API_KEY=op://Work/Anthropic/credential -GITHUB_TOKEN=op://Work/GitHub/token - -$ op run --env-file=.sbx-secrets.env -- sbx run claude -``` - -## CI and headless use - -For CI environments and scripts where a browser isn't available, authenticate -with a Docker Personal Access Token (PAT): - -```console -$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin -``` - -Generate a PAT from your -[Docker account settings](https://app.docker.com/settings/personal-access-tokens) -with at least **Read** scope. - -From there, the rest of the `sbx` workflow is the same as interactive use. -Create the sandbox in the background with `sbx create`, run agent tasks with -`sbx exec`, and clean up with `sbx rm`: - -```console -$ sbx create --name ci-task --clone claude -$ sbx run ci-task # attach and give instructions, or use sbx exec for one-off commands -$ git fetch sandbox-ci-task -$ sbx rm ci-task -``` - -Agent credentials (API keys, GitHub token) can be pre-configured as global -secrets so they're available to any sandbox the CI runner creates: - -```console -$ echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic -$ echo "$GITHUB_TOKEN" | sbx secret set -g github -``` diff --git a/content/manuals/ai/sandboxes/workflows/_index.md b/content/manuals/ai/sandboxes/workflows/_index.md new file mode 100644 index 000000000000..bcbbf6d45deb --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/_index.md @@ -0,0 +1,49 @@ +--- +title: Workflow patterns +linkTitle: Workflows +weight: 50 +description: Choose a Docker Sandboxes workflow for agent skills, Git, local development, authenticated tools, or headless automation. +keywords: docker sandboxes, sbx, workflows, agent skills, shared skills, clone mode, git, local development, authentication, ci, headless +toc_max: 2 +--- + +Choose a workflow based on how you want to develop, authenticate tools, or run +local sandboxes in automation. For command syntax and lifecycle basics, see +[Usage](../usage.md). + +## Choose how code moves + +Your workspace strategy determines when an agent's changes appear on the host. +Direct mode edits the host working tree in place. Clone mode keeps changes in a +private clone until you fetch or push them. Host worktrees provide branch +isolation while keeping Git operations on the host. Mountless sandboxes keep +repositories inside the sandbox, with branches pushed to a Git remote for +review or use on the host. See [Git workflows](git.md) +to choose a strategy for single or parallel tasks. + +## Develop in the sandbox + +Each sandbox has a private Docker daemon and runtime for building images, +installing dependencies, and running tests. You can publish services from the +sandbox or connect to services on the host. See +[Develop and test locally](development.md). + +Tools inside the sandbox can use credentials configured on the host without +copying secret values into the VM. See +[Authenticate command-line tools](authentication.md) for GitHub CLI, registry, +and external secret-provider workflows. + +## Reuse and automate workflows + +Sandbox environment files work like Compose files for sandboxes: they capture +project configuration in a versioned YAML file. Use `sbxenv.yaml` to define +the agent, workspaces, tools, resources, credentials, and ports so contributors +can start a consistent environment without reproducing CLI flags and setup +steps. See [Sandbox environment files](../configuration/environment-files.md). + +You can also add skills from Git repositories or import them from supported +host agents into a persistent store shared with new sandboxes. See +[Share agent skills](agent-skills.md). + +For unattended jobs, use headless authentication and manage the sandbox +lifecycle from scripts. See [Run sandboxes in CI](automation.md). diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md new file mode 100644 index 000000000000..e2d2c067bb3b --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -0,0 +1,167 @@ +--- +title: Share agent skills +linkTitle: Agent skills +weight: 40 +description: Add skills from Git repositories or import them from supported host agents into a store shared with Docker Sandboxes. +keywords: docker sandboxes, sbx, agent skills, shared skills, git repository, claude code, codex, copilot, cursor, devin, droid +--- + +Shared agent skills let you install skills from Git repositories or import +skills from supported agents on your host for use in local sandboxes. `sbx` +keeps installed skills in a persistent store that survives sandbox deletion +and is shared by default with new sandboxes that run a supported agent. + +> [!NOTE] +> Shared agent skills are experimental. + +## Add skills from a repository + +Add every skill from a Git repository: + +```console +$ sbx skills add anthropics/skills +``` + +The repository must contain one or more valid `SKILL.md` files. You can use +GitHub `owner/repository` shorthand or a Git URL, including HTTPS and SSH URLs. + +To add specific skills, use `--skill` with each name or pass a comma-separated +list: + +```console +$ sbx skills add https://github.com/anthropics/skills --skill frontend-design --skill pdf +``` + +When a skill with the same name is already installed, `sbx` prompts before +replacing it. Use `--force` to replace existing skills without prompts. + +## Manage installed skills + +List the skills in the shared store: + +```console +$ sbx skills ls +``` + +Update every skill installed from a repository: + +```console +$ sbx skills update +``` + +To update specific skills, pass one or more names: + +```console +$ sbx skills update frontend-design pdf +``` + +`sbx skills update` only refreshes skills installed with `sbx skills add`. To +refresh a skill imported from the host, run `sbx skills import` again. To manage +it with `sbx skills update`, install it from a repository instead. + +Remove one or more installed skills: + +```console +$ sbx skills rm frontend-design pdf +``` + +`sbx` asks for confirmation before removing skills that running agents may be +using. Use `--force` to skip confirmation in scripts. + +## Import skills from the host + +Preview the skills that `sbx` finds without copying them: + +```console +$ sbx skills import --dry-run +``` + +The preview scans the host sources in the following order. The table also +shows where supported agents read the shared store inside the sandbox: + +| Agent | Host source | Sandbox mount target | +| ----------- | ------------------- | ----------------------------- | +| Codex and Devin | `~/.agents/skills` | `/home/agent/.agents/skills` | +| Claude Code | `~/.claude/skills` | `/home/agent/.claude/skills` | +| OpenCode | `~/.config/opencode/skills` | `/home/agent/.config/opencode/skills` | +| Copilot | `~/.copilot/skills` | `/home/agent/.copilot/skills` | +| Cursor | `~/.cursor/skills` | `/home/agent/.cursor/skills` | +| Droid | `~/.factory/skills` | `/home/agent/.factory/skills` | + +All imported skills go into the same store, regardless of their source. If +more than one source contains a skill with the same directory name, the skill +from the first source in the table wins and `sbx` warns about the others. + +Copy the skills into the shared store: + +```console +$ sbx skills import +``` + +Import copies each skill directory, including directories reached through a +symlink at the top level of a source. It skips symlinks inside skill directories +and loose files in the source directory. If a skill depends on linked files, +replace those links with files before importing it. + +The final output reports the shared store path. The default locations are: + +| Platform | Shared store path | +| -------- | --------------------------------------------------------------------------- | +| macOS | `~/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills` | +| Linux | `~/.local/state/sandboxes/sandboxes/agent-skills` | +| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills` | + +On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when +`XDG_STATE_HOME` is set. + +When a skill already exists in the store, `sbx` prompts before replacing it. +Use `--force` to replace existing skills without prompts. Importing replaces +the complete skill directory rather than merging files. Run the import command +again when you want to copy updates from the host. If an import replaces a +repository-installed skill, `sbx` no longer associates that skill with its +repository, so `sbx skills update` won't refresh it. + +## Shared store behavior + +Running `sbx reset` clears the shared store. + +Sandboxes created for a supported agent mount the shared store read-only by +default. These sandboxes mount the contents of the store each time they start, +so you can install skills before or after creating them. + +Use `--skills` with `sbx run` or `sbx create` to choose the access mode when +creating a sandbox: + +- `readonly`: Mount the store so the agent can read skills but cannot modify them. +- `readwrite`: Mount the store so the agent can read and modify shared skills. +- `off`: Omit the shared store mount. + +For example, create a sandbox without the shared store: + +```console +$ sbx run --skills=off claude +``` + +To change the default for future sandboxes, set +[`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode) to `off`, +`readonly`, or `readwrite`: + +```console +$ sbx settings set skills.defaultMode readonly +``` + +The mode is applied only when a sandbox is created. Upgrading `sbx` or changing +`skills.defaultMode` leaves existing sandbox mounts unchanged. Remove and +recreate a sandbox to change its mode. Sandboxes created without shared skills +also need to be recreated to mount the store. + +> [!WARNING] +> A sandbox with `readwrite` access can modify skills that other sandboxes load, +> including sandboxes with `readonly` access. Read-only access prevents writes +> from that sandbox but does not isolate it from changes to the store. The store +> is dedicated sandbox state, so this does not by itself execute modified skills +> on your host. Use `--skills=off` when creating a sandbox to keep it outside +> this shared trust boundary. + +Some agents scan for skills when a session starts. If installed skills don't +appear in an existing session, start another agent session. diff --git a/content/manuals/ai/sandboxes/workflows/authentication.md b/content/manuals/ai/sandboxes/workflows/authentication.md new file mode 100644 index 000000000000..e61170232a9f --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/authentication.md @@ -0,0 +1,109 @@ +--- +title: Authenticate command-line tools +linkTitle: Authenticate tools +weight: 30 +description: Use authenticated command-line tools and dynamic secret sources inside Docker Sandboxes. +keywords: docker sandboxes, sbx, authentication, github cli, registry, 1password, aws secrets manager +--- + +These workflows resolve credentials on the host for local sandboxes. For +cloud secret setup, see [Authenticate cloud agents](../cloud/credentials.md). + +The sandbox proxy handles API credentials for model providers automatically, +but agents often also need credentials for tools like `gh`, `docker`, or a +secrets manager. Configure the credential source on your host, and the proxy +injects the resolved value into matching requests from the sandbox. Dynamic +secret sources can retrieve a value from an authenticated host CLI without +copying the value into the secret store. + +For secret scope and how changes apply to existing sandboxes, see +[Store a secret](../configuration/credentials.md#store-a-secret). + +## GitHub CLI + +Store your GitHub token as a sandbox secret. The proxy injects it into +outbound requests, so `gh` works inside the sandbox without any additional +configuration: + +```console +$ sbx secret set github --command 'gh auth token' +``` + +The daemon runs `gh auth token` on the host and caches its output for 55 minutes +by default. After the cache expires, it runs the command again, so token updates +from `gh` don't need to be copied into `sbx` manually. Use `--refresh on-demand` +to run the command for every credential use. + +The agent can then create pull requests, open issues, comment on PRs, and +interact with the GitHub API the same way it would from your host: + +```console +# Inside the sandbox +$ gh pr create --title "feat: my feature" --body "..." +$ gh issue list +``` + +The token is never stored in plaintext inside the sandbox. See +[GitHub token](../configuration/credentials.md#github-token) for details. + +## Docker registry + +When using Docker Hub, authentication is handled automatically; `sbx` reuses +your existing login session. For other registries, you need to configure +credentials for `sbx` so it can pull private [templates](../usage.md#load-a-template) +and kits when creating a sandbox: + +```console +$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io \ + --username <github-username> --password-stdin +$ echo "$ACR_PASSWORD" | sbx secret set --all-sandboxes \ + --registry myregistry.azurecr.io \ + --username myuser --password-stdin +``` + +Add `-g` or a sandbox name when the agent needs to run authenticated +`docker pull` or `docker push` commands from inside the sandbox. The host-side +proxy handles the registry login without writing the credential into the +sandbox. + +Images and containers built inside the sandbox run on the sandbox's private +Docker daemon, not your host's. They're deleted when the sandbox is removed. + +For information on how registry credentials differ from other secrets, +per-registry username requirements, and all-sandbox versus per-sandbox scoping, see +[Registry credentials](../configuration/credentials.md#registry-credentials). + +## Source credentials from 1Password + +Install the 1Password CLI, sign in on the host, and pass an `op://` reference to +`sbx secret set`. The secret store records the reference, and the daemon uses +`op read` on the host when the proxy needs the credential: + +```console +$ sbx secret set github --ref 'op://Work/GitHub/token' +$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential' +``` + +The real value stays on your host, and the sandbox sees the proxy-managed +placeholder. Service secrets are cached for 55 minutes by default. To retrieve +the value from 1Password for every credential use, set the refresh policy: + +```console +$ sbx secret set anthropic \ + --ref 'op://Work/Anthropic/credential' \ + --refresh on-demand +``` + +## Source credentials from AWS Secrets Manager + +Install and authenticate the AWS CLI on the host, then register the secret's +ARN. The daemon calls AWS Secrets Manager when the proxy needs the value: + +```console +$ sbx secret set anthropic \ + --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key' +``` + +See [Use a dynamic secret source](../configuration/credentials.md#use-a-dynamic-secret-source) +for refresh policies, verification options, custom secrets, and provider +account or profile selection. diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md new file mode 100644 index 000000000000..78567684a2d1 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/automation.md @@ -0,0 +1,136 @@ +--- +title: Run sandboxes in CI +linkTitle: CI and headless +weight: 50 +description: Authenticate and run Docker Sandboxes in CI systems and other headless environments. +keywords: docker sandboxes, sbx, ci, headless, automation, personal access token +--- + +This page describes local sandboxes in CI. For cloud execution without local +virtualization, see [Run without attaching](../cloud/usage.md#run-without-attaching). + +For CI environments and scripts where a browser isn't available, authenticate +with a Docker Personal Access Token (PAT): + +```console +$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin +``` + +Generate a PAT from your +[Docker account settings](https://app.docker.com/settings/personal-access-tokens) +with at least **Read** scope. + +Sign in before running commands that require authentication. Read-only commands +and commands run with `--force` do not open an interactive sign-in flow. +Create workspace directories before calling `sbx create` or `sbx run`: without +a terminal, these commands fail if a workspace directory does not exist. + +Create the sandbox in the background with `sbx create`, run agent tasks with +`sbx exec`, and remove the sandbox when finished: + +```console +$ sbx create --name ci-task --clone claude . +$ sbx exec ci-task -- claude --dangerously-skip-permissions -p "Review the code and commit your changes" +$ git fetch sandbox-ci-task +$ sbx rm --force ci-task +``` + +Agent credentials (API keys, GitHub token) can be preconfigured as global +secrets so they're available to any sandbox the CI runner creates. If the +relevant environment variables are already set in the CI environment (see the +[built-in services table](../configuration/credentials.md#built-in-services) for which +variables each service reads), import them all at once: + +```console +$ sbx secret import --all +``` + +To overwrite an existing stored entry, add `--force`. To pass a value from your +CI provider's secret store, use `-t`. For example, in a GitHub Actions step: + +```yaml +- run: sbx secret set anthropic --force -t "${{ secrets.ANTHROPIC_API_KEY }}" +``` + +## Cleanup and exit codes + +Confirmations require terminal input. Piping an answer, such as `echo y`, does +not confirm an operation. Use `--force` on commands that provide it to skip +confirmation in scripts. `sbx kit builder history rm` uses `--yes` or `-y` +instead, because its `--force` flag is passed to Buildx. + +A command that requires confirmation fails with exit status 1 when stdin is +not a terminal. Declining a confirmation also returns a non-zero exit code. +Treat this as an incomplete operation when deciding whether to continue a +script. + +For repeatable cleanup, check which resources exist before removing them. For +example, use `sbx mcp ls` before `sbx mcp rm`, which fails for an unregistered +server even with `--force`. Likewise, `sbx secret rm` fails if no secret matches +the selector; check for matches with `sbx secret ls` before removing secrets. + +## Parse command output + +Use `--format json` or `--format yaml` on commands that support structured +output. Human-readable tables and messages can change between releases. +Results go to stdout. Errors, warnings, hints, and progress go to stderr. + +```console +$ sbx ls --json | jq -r '.[].name' +$ sbx prune --dry-run --format yaml +``` + +`--json` is an alias for `--format json`. On commands with shared output flags, +`--format`, `--json`, and `--quiet` (`-q`) are mutually exclusive, even when +`--json` and `--format json` request the same format. Unsupported format values +are rejected. `sbx events --json` emits newline-delimited JSON, and +`sbx mcp auth --format text|json` uses command-specific formats. + +For lists of identifiers without table headings, use `--quiet` or `-q`: + +| Command | Output | +| --- | --- | +| `sbx policy ls -q` | Local rule IDs. With `--cloud`, network patterns instead. | +| `sbx settings ls -q` | Setting keys. | +| `sbx policy approval ls -q` | Approval IDs. | + +### Update scripts for v0.48.0 + +{{< copy-as-prompt instruction="Update this repository's Docker Sandboxes CLI usage for v0.48.0 using the migration reference below. Inspect scripts and documentation, update affected commands and output parsers, and verify the changes. Preserve unrelated behavior." >}} + +Docker Sandboxes v0.48.0 changes flags and structured output. Update scripts +that use the following flags: + +| Command | Previous flag | Replacement | +| --- | --- | --- | +| `sbx run`, `sbx env run` | `--detached` | `--detach` or `-d` | +| `sbx logout` | `--yes`, `-y` | `--force` or `-f` | +| `sbx env create`, `sbx env run` | `--auto-approve`, `-y` | `--force` or `-f` | +| `sbx create` | `--quiet`, `-q` | `--no-progress` suppresses progress but still prints the creation summary | +| `sbx template save` | `-d` for a description | `--description` | +| `sbx diagnose` | `--output`, `-o` | `--format table`, `json`, `yaml`, or `github-issue` | +| `sbx policy log` | `--quiet`, `-q` | Removed without a replacement | + +`sbx settings ls` is the primary command spelling. `sbx settings list` remains +an alias. Replace the deprecated `sbx mcp add --skip_auth` with `--skip-auth`. +Secret commands that default to global scope still accept the deprecated +`--global` flag but print a warning to stderr. Omit the flag for those commands. + +JSON field names use `snake_case`. YAML uses the same representation. Update +parsers for these commands: + +| Command | Structured output in v0.48.0 | +| --- | --- | +| `sbx ls` | A sandbox array, replacing `{sandboxes: [...]}`. `created_at` and `last_used_at` use RFC 3339 timestamps. Rows include `detached`. | +| `sbx template ls` | An image array, replacing `{images: [...]}`. | +| Local `sbx mcp ls` | A server array, replacing `{gateway: {...}, servers: [...]}`. Each row includes `gateway`. Cloud rows describe server usage across sandboxes and differ from local registration rows. | +| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Monitoring traffic](/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md#monitoring-traffic). | +| `sbx --cloud policy ls` | Field names use `snake_case` instead of camelCase. | +| `sbx ports` | Local rows contain `host_ip`, `host_port`, `sandbox_port`, and `protocol`. Cloud rows contain `sandbox_port` and `url`, replacing `port`. Local publish and unpublish results include `action: published` or `action: unpublished`. | +| Cloud `sbx volume create`, `sbx volume ls`, `sbx volume inspect` | Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to human-readable details, so request a structured format explicitly. | +| `sbx rm`, `sbx stop`, `sbx template rm`, `sbx volume rm` | An array of results with `action`, `resource`, `name`, and optional `id` and `error`, including missing or failed targets. Actions are lowercase: `removed`, `stopped`, `removing`, `stopping`, or `failed`. | + +For example, replace the jq filter `.sandboxes[].name` with `.[].name` when +extracting sandbox names from `sbx ls --json`. + +{{< /copy-as-prompt >}} diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md new file mode 100644 index 000000000000..0dc5bc781b26 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -0,0 +1,132 @@ +--- +title: Develop and test locally +linkTitle: Local development +weight: 20 +description: Build, test, and connect to development services in Docker Sandboxes. +keywords: docker sandboxes, sbx, local development, build, test, ports, host services +--- + +This page describes local sandboxes, host services, and local port mappings. +For cloud endpoints, see [Expose a port](../cloud/usage.md#expose-a-port). + +Use a sandbox's private runtime to build images, run tests, and connect local +tools to development services across the sandbox boundary. + +## Build and test inside a sandbox + +Agents have sudo access inside the sandbox, so they can install packages, +start databases, run test dependencies, and prepare the environment they need. +Installed packages persist for the sandbox's lifetime. For repeated setup, use +[Customize](../customize/) to package the environment as a template or kit. + +Agents can also build Docker images, run containers, and use +[Compose](/manuals/compose/_index.md). Everything runs inside the sandbox's +private Docker daemon, so containers started by the agent never appear in your +host's `docker ps`. When you remove the sandbox, all images, containers, and +volumes inside it are deleted with it. + +This pattern works well for tasks where the agent needs to run the project's +test suite or inspect a service it started. If you need to reach that service +from your host, publish the port when you create the sandbox, or publish it +later with `sbx ports`. + +## Local services + +Use this workflow when a sandboxed agent starts a dev server, or when the agent +needs to call a service running on your host. + +### Accessing services in the sandbox + +Sandboxes are [network-isolated](../security/isolation.md) — your browser or local +tools can't reach a server running inside one by default. A port mapping of +`8080:3000` publishes sandbox port 3000 on host port 8080. + +If you know which ports you need, publish them when you create the sandbox: + +```console +$ sbx run --publish 8080:3000 --name my-sandbox claude +``` + +For an existing sandbox, use [`sbx ports`](/reference/cli/sbx/ports/) to +forward traffic from your host. Publishing a port on a stopped local sandbox +starts it first. + +The common case: an agent has started a dev server or API, and you want to open +it in your browser or run tests against it. + +```console +$ sbx ports my-sandbox --publish 8080:3000 +$ open http://localhost:8080 +``` + +To let the OS pick a free host port instead of choosing one yourself, specify +only the sandbox port. Then use `sbx ports` to check which host port was +assigned: + +```console +$ sbx ports my-sandbox --publish 3000 +$ sbx ports my-sandbox +``` + +`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` +lists them in detail: + +```console +$ sbx ls +SANDBOX AGENT STATUS PORTS WORKSPACE CREATED +my-sandbox claude ● running 127.0.0.1:8080->3000/tcp4 /home/user/proj 2m +``` + +To stop forwarding a port: + +```console +$ sbx ports my-sandbox --unpublish 8080:3000 +``` + +For a service to be reachable, it must listen on all interfaces inside the +sandbox, not only `127.0.0.1`. Bind it to `0.0.0.0` for IPv4 or `[::]` for both +IPv4 and IPv6. Most dev servers need a flag like `--host 0.0.0.0` to do this. + +On the host, a published port binds IPv4 (`127.0.0.1`) unless you name another +protocol, so `http://localhost:<port>/` reaches a service listening on IPv4 +whichever address your resolver picks for `localhost`. Naming an explicit IPv6 +host address, such as `--publish [::1]:8080:3000`, defaults the protocol to +`tcp6` instead. To publish on both families use `--publish 8080:3000/tcp`, and +for IPv6 alone `/tcp6`. Both of +those require the sandboxed service to listen on IPv6 as well — bind it to +`[::]` — or a client arriving over `::1` has its connection accepted and then +reset. + +Published ports survive restarts: `sbx` re-publishes them when the sandbox or +the daemon restarts. Explicit host ports are reused, while a port published with +an OS-assigned host port, such as `--publish 3000`, gets a different host port +on each start. Check `sbx ports my-sandbox` to find it. If an explicit host port +is already in use at restart, the CLI or the dashboard prompts you to choose +another. Removing the sandbox releases its ports. + +When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use +`sbx ports` to publish ports on that sandbox. To stop forwarding, +`--unpublish 8080:3000` removes a single mapping, and `--unpublish 3000` +removes every host port mapped to sandbox port 3000. + +### Accessing host services from a sandbox + +Services running on your host are reachable from inside a sandbox using the +hostname `host.docker.internal`. Use this instead of `127.0.0.1` or your +machine's local network IP address, which are not reachable from inside the +sandbox. + +The sandbox proxy translates `host.docker.internal` to `localhost` before +forwarding the request, so you must add the `localhost` address with the +specific port to your network policy allowlist: + +```console +$ sbx policy allow network localhost:11434 +``` + +Then use `host.docker.internal` in any configuration or request that points at +the host service. For example, to verify connectivity from a sandbox shell: + +```console +$ curl http://host.docker.internal:11434 +``` diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md new file mode 100644 index 000000000000..958f3c65d488 --- /dev/null +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -0,0 +1,301 @@ +--- +title: Use Git with sandboxes +linkTitle: Git workflows +weight: 10 +description: Choose where your Git checkout lives and manage branches, parallel tasks, and signed commits with Docker Sandboxes. +keywords: docker sandboxes, sbx, git, clone mode, direct mode, worktrees, branches, commit signing +--- + +These workspace modes apply to local sandboxes. In cloud sandboxes, +[transfer files or clone a remote repository](../cloud/usage.md#transfer-files). +To copy a sandbox filesystem between environments, see +[Move a sandbox](../cloud/move.md). Host mounts and clone-mode volumes are not +included in that snapshot. + +Choose where your checkout lives based on how you want to review and run the +agent's changes: + +- Share a host checkout with [direct mode](#direct-mode) to see edits in your + local editor as they happen. A [host worktree](#host-worktree) gives a task + its own branch and directory while keeping edits visible on the host. +- Use [clone mode](#clone-mode) to give the agent a separate checkout based on + your local repository. Fetch or push committed work to bring it back. +- Use a [mountless sandbox](#mountless-sandbox) to clone repositories inside + the sandbox without attaching a host workspace. Push branches to a Git + remote to share the results. + +| Checkout | Changes visible in host checkout | Agent can use Git | +| --- | --- | --- | +| Direct mount | Immediately | Yes | +| Mounted host worktree | Immediately, in the worktree | No | +| Clone mode (`--clone`) | After checking out or merging a fetched branch | Yes | +| Mountless sandbox | After pulling committed work from a Git remote | Yes | + +As you give the agent more responsibility for managing work, consider a +mountless sandbox. The agent can manage branches, create worktrees, and push +results for review without coordinating changes in your host checkout. You +review and bring back committed work through Git, and run previews through +published sandbox ports. + +For simultaneous tasks, have the agent create a separate worktree or clone +for each task inside the sandbox. This works in both mountless sandboxes and +clone mode, and keeps Git available to the agent. Branches alone don't isolate +edits in a shared working directory. Worktrees inside one sandbox share its +tools and services. Use separate sandboxes when tasks also need independent +environments. + +## Direct mode + +The sandbox mounts your host working tree directly. The agent edits files in +place, and changes appear immediately. Both you and the agent can use Git, +so agree on who manages branches and commits. Switching branches from either +side changes the files both sides see. + +To manage Git operations from the host: + +1. Check out the branch you want to work on: + + ```console + $ git checkout -b feat/my-feature + ``` + +2. Start the sandbox. No special flags needed: + + ```console + $ sbx run claude + ``` + +3. The agent edits files in your working tree. Review diffs, stage, and + commit as you normally would: + + ```console + $ git diff + $ git add -p + $ git commit + $ git push -u origin feat/my-feature + ``` + +Direct mode suits focused, single-branch work where you collaborate with the +agent turn-by-turn. + +## Clone mode + +In clone mode, `sbx` creates a separate Git clone inside the sandbox. The agent +edits this clone instead of your host working tree. Its changes stay inside the +sandbox until you fetch a branch or the agent pushes one to a remote. Your host +repository is also available at `/run/sandbox/source`, but only with read +access. The sandbox clone is not a Git worktree linked to your host checkout. + +A single clone-mode sandbox can hold multiple branches and worktrees for +parallel tasks. The `--clone` flag creates the clone, but it doesn't separate +one task from another. To keep parallel tasks isolated, instruct your agent tool +to create a separate worktree or clone for each task. + +> [!NOTE] +> `--clone` is a create-time flag and cannot be changed on an existing +> sandbox. To change a sandbox from clone mode to direct mode, remove and +> recreate it. To run both modes against the same repository, create separate +> sandboxes with distinct names. + +### Sandbox remote behavior + +The CLI copies Git remotes from your host repository, such as `origin` and +`upstream`, into the in-sandbox clone. Local-path remotes, such as `file://` +URLs and filesystem paths, aren't copied because they aren't reachable from +inside the sandbox. + +The Git daemon that exposes the in-sandbox clone runs as part of the sandbox. +It's only reachable while the sandbox is running: + +- `sbx stop` shuts down the daemon. `git fetch sandbox-<name>` fails until the + sandbox starts again. +- Restarting the sandbox assigns another ephemeral port to the daemon. The CLI + updates the `sandbox-<name>` remote URL in your host repository's Git config, + so fetching continues without manual reconfiguration. +- `sbx rm` removes the sandbox, the daemon, the published port, and the + `sandbox-<name>` remote entry from your host repository. + +### Single task + +1. Start a clone-mode sandbox: + + ```console + $ sbx run --clone claude . + ``` + +2. Ask the agent to create a branch before it starts editing: + + > Create a branch `feat/my-feature` and make the changes. + +3. Fetch the agent's branch when it's done: + + ```console + $ git fetch sandbox-<name> + $ git log sandbox-<name>/feat/my-feature + $ git diff main..sandbox-<name>/feat/my-feature + ``` + +4. Pull the branch to the host and push, or ask the agent to push directly: + + ```console + # Pull to host, then push + $ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature + $ git push -u origin feat/my-feature + $ gh pr create + + # Or ask the agent + # "Push feat/my-feature to origin and open a PR." + ``` + +### Parallel tasks + +1. Start a clone-mode sandbox and open the + [agents view](../agents/claude-code.md#agents-view): + + ```console + $ sbx run --clone claude . + ``` + +2. Dispatch each independent task to a separate background session. Your agent + tool controls how it separates their working directories. To require a + separate worktree for each task, add a project instruction such as: + + ```markdown + For each simultaneous task, create a separate Git worktree with its own branch + and make all changes for that task in that worktree. + ``` + +3. Fetch all branches when the agents are done: + + ```console + $ git fetch sandbox-<name> + $ git log sandbox-<name>/feat/task-a + $ git log sandbox-<name>/feat/task-b + ``` + +4. Check out the branches you want to keep and open PRs as normal. + +## Host worktree + +You can create a Git worktree on your host and point the sandbox at it. The +agent edits files directly in the worktree — but because the sandbox mounts +only the worktree directory (not the parent repository), it can't resolve the +`.git` pointer file and has no Git access. The agent can read and write files, +but can't commit, branch, or check status. + +Use this approach when you want edits visible in a separate host directory +and prefer to handle Git operations yourself. To give the agent Git access in +each working directory, use worktrees inside a mountless or clone-mode sandbox. + +1. Create the worktree on the host: + + ```console + $ git worktree add -b feat/my-feature ../my-feature-work + ``` + +2. Start the sandbox with the worktree as the workspace: + + ```console + $ sbx run claude ../my-feature-work + ``` + +3. The agent edits files. When it's done, commit and push from the host: + + ```console + $ cd ../my-feature-work + $ git diff + $ git add -p && git commit + $ git push -u origin feat/my-feature + $ gh pr create + ``` + +## Mountless sandbox + +A mountless sandbox has no host workspace attached. Clone repositories inside +it to keep the checkout, dependencies, and development tools in the sandbox. +Files persist across stops and restarts, but removing the sandbox deletes them. + +You can keep one sandbox per project and reuse it across tasks. The agent can +prepare its tools and create worktrees as needed, so starting another task +doesn't require another host checkout or sandbox. + +1. Create a named sandbox without a workspace path, then attach: + + ```console + $ sbx create --name my-project claude + $ sbx run --name my-project + ``` + + Omitting the path from `sbx create` creates a mountless sandbox. Omitting + it from `sbx run claude` mounts your current host directory instead. + See [Choose a workspace](../usage.md#choose-a-workspace). + +2. Ask the agent to clone your repository inside the sandbox and create a + branch before editing. For simultaneous tasks, ask it to create a separate + worktree for each task. + +3. Review and commit the changes inside the sandbox, then push the branch to + your Git remote. You can fetch that branch in a host checkout or review it + in a pull request. Push any work you want to keep before removing the sandbox. + +You can also create a mountless sandbox with an `sbxenv.yaml` environment file. +Omit `workspace` and any `additionalWorkspaces` mounts, then run `sbx env run`. +See [Sandbox environment files](../configuration/environment-files.md#workspace) +for configuration options. + +For running the application and opening a preview from your host browser, see +[Develop and test locally](development.md#accessing-services-in-the-sandbox). +To work with several host repositories in one sandbox instead, see +[Multiple workspaces](../usage.md#multiple-workspaces). + +## Git ignore rules + +Git inside a local sandbox preserves host-specific ignore decisions for paths +that exist when you create the sandbox. This applies when the primary workspace +is at a Git repository root. + +The sandbox receives a snapshot of ignored paths, not the host-specific patterns. +Those patterns don't apply to files created later, but ignored directories still +cover files added inside them. Additional repositories and primary workspaces +below a repository root don't receive this snapshot. Repository `.gitignore` +files continue to work as usual. + +Git ignore rules don't restrict the agent's access to files in the workspace. + +## Commit signing + +SSH agent forwarding is enabled by default. When `SSH_AUTH_SOCK` is set, +sandboxes forward your host SSH agent into the sandbox, so the agent can sign +commits with your SSH key without the private key ever leaving your host. If +you turned off forwarding or use a fixed SSH agent socket, see +[SSH agent configuration](../configuration/credentials.md#ssh-agent). + +1. Make sure the signing key is loaded in your host SSH agent: + + ```console + $ ssh-add ~/.ssh/id_ed25519 + $ ssh-add -L # confirm the key appears + ``` + +2. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key + directly rather than a file path, since host paths don't exist inside the + sandbox: + + ```console + $ git config --global gpg.format ssh + $ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)" + ``` + +3. Sign commits as usual: + + ```console + $ git commit -S -m "feat: my change" + ``` + +To apply this configuration automatically to every sandbox, use the +[`git-ssh-sign`](https://github.com/docker/sbx-kits-contrib/tree/main/git-ssh-sign) +community kit, which handles all of the above setup. For using it with the +built-in agents, see [Kits v2](../customize/kits-v2.md). + +For troubleshooting, see +[Sandbox commits aren't signed](../troubleshooting.md#sandbox-commits-arent-signed). diff --git a/content/manuals/ai/skills/_index.md b/content/manuals/ai/skills/_index.md new file mode 100644 index 000000000000..265a393f191c --- /dev/null +++ b/content/manuals/ai/skills/_index.md @@ -0,0 +1,33 @@ +--- +title: Docker Skills +description: Use Docker's official skills to give compatible AI coding agents guidance for Docker tasks. +keywords: [docker skills, agent skills, ai coding agents, dockerfile, compose] +weight: 70 +params: + sidebar: + group: AI and agents +--- + +Docker Skills are Docker's official, open-source guidance for compatible AI +coding agents. They help agents with Docker tasks, such as improving a Dockerfile +or setting up a Compose application. The collection evolves and doesn't cover +every Docker product. Browse the [repository catalog](https://github.com/docker/skills#readme) +for available skills and their descriptions. + +## Get started + +1. [Install Docker Skills](install.md) with a method supported by your agent, + and start a new agent session. +2. Ask for an outcome in plain language, for example, “Make this Dockerfile + smaller and run as a non-root user.” +3. Review the proposed changes and commands, run your project's tests, and + confirm destructive operations before approving them. Skills guide the + agent; they don't replace validation. + +## How agents use skills + +A compatible agent matches your request to descriptions of skills it can +access, then loads the relevant instructions. You don't need to name a skill in +your prompt. A skill is a directory containing a `SKILL.md` file that describes +when and how to use it, with optional references or assets. An agent can use +more than one skill when a task spans Docker products. diff --git a/content/manuals/ai/skills/install.md b/content/manuals/ai/skills/install.md new file mode 100644 index 000000000000..8ccd6353e33d --- /dev/null +++ b/content/manuals/ai/skills/install.md @@ -0,0 +1,195 @@ +--- +title: Install Docker Skills +linkTitle: Install +description: Install Docker's official skills in compatible coding agents, Docker Sandboxes, or Docker Agent, and verify that your agent can use them. +keywords: [docker skills, install skills, agent skills, docker sandboxes, docker agent] +weight: 10 +--- + +Choose the installation method managed by your agent or organization. Native +plugins, the Gemini CLI extension, and the cross-client skills CLI are separate +options; the skills CLI is not a prerequisite. + +## Claude Code {#claude-code} + +In Claude Code, add Docker's marketplace, then install its plugin: + +```text +/plugin marketplace add docker/skills +/plugin install docker-skills@docker +``` + +See [Claude Code's plugin +docs](https://code.claude.com/docs/en/discover-plugins) for marketplace setup. + +<!-- vale off --> +## GitHub Copilot CLI {#github-copilot-cli} +<!-- vale on --> + +Add Docker's marketplace in the GitHub Copilot CLI, then install its plugin: + +```console +$ copilot plugin marketplace add docker/skills +$ copilot plugin install docker-skills@docker +``` + +See [Copilot CLI's plugin +documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing) +for marketplace setup. + +## Cursor {#cursor} + +In Cursor, repository-backed marketplaces require a Teams or Enterprise plan +and someone with permission to add a team marketplace (an admin on Enterprise). +Ask that person to open **Dashboard → Plugins & MCPs → Team Marketplaces → Add +Marketplace**, choose **Import from Repo**, enter +`https://github.com/docker/skills`, add the Docker plugin to the marketplace, +and save its access settings. Once the marketplace is available to you, open +**Customize**, find `docker-skills`, select **Install**, and choose a project or +user scope. If your team can't import a marketplace, use the +[skills CLI](#skills-cli). See [Cursor's plugin +instructions](https://cursor.com/docs/plugins) for marketplace permissions and +installation modes. + +## Codex {#codex} + +In Codex CLI, add Docker's repository as a plugin marketplace: + +```console +$ codex plugin marketplace add docker/skills +``` + +Enter `/plugins` in Codex CLI, find the `docker-skills` plugin in the Docker +marketplace, and install it through the plugin browser. Start a new session to +use its skills. Plugins are available in Codex CLI and the ChatGPT desktop app, +not the Codex IDE extension. If plugins aren't available in your client, use +the [skills CLI](#skills-cli). See the [Codex plugin +instructions](https://developers.openai.com/codex/plugins/) and +[marketplace setup](https://developers.openai.com/codex/plugins/build/). + +## Gemini CLI {#gemini-cli} + +Install the repository as a Gemini CLI extension: + +```console +$ gemini extensions install https://github.com/docker/skills +``` + +See the [Gemini CLI extension docs](https://geminicli.com/docs/extensions/) +for extension configuration. + +## Google Antigravity {#google-antigravity} + +Antigravity reads standard `SKILL.md` directories from your workspace's +`.agents/skills/`. From the project directory, use the [skills CLI](#skills-cli) +and select Antigravity and the skills you need: + +```console +$ npx skills add docker/skills --agent antigravity +``` + +Alternatively, [clone a reviewed Docker Skills tag](#git-clone-or-manual-copy) +and copy each selected directory from its `skills/` folder into +`<workspace-root>/.agents/skills/<skill-folder>/`, keeping its `SKILL.md` and +supporting files together. See Google's [Antigravity agent skills +docs](https://antigravity.google/docs/skills) for other discovery locations. +The Gemini CLI extension is a separate installation method, not an Antigravity +plugin. + +## Other supported agents with the skills CLI {#skills-cli} + +From your project directory, run the interactive installer: + +```console +$ npx skills add docker/skills +``` + +Select your supported agent and the skills you need when prompted. The default +installation is project-scoped; use `--global` for user scope. See the +[skills CLI docs](https://skills.sh/docs) for supported agents and options. + +## Docker Sandboxes {#docker-sandboxes} + +> [!NOTE] +> The `sbx skills` installer is experimental and may change or be removed. +> Check `sbx skills --help` in your installed release before automating it. + +Install from the repository into the shared sandbox skill store: + +```console +$ sbx skills add docker/skills +``` + +For shared-store management, mounting behavior, and host imports, see +[Share agent skills](../sandboxes/workflows/agent-skills.md). + +## Docker Agent {#docker-agent} + +Docker Agent consumes skills installed in its documented +[discovery paths](/ai/docker-agent/features/skills/); it doesn't install or +update them. Install with the [skills CLI](#skills-cli) or +[copy the selected skills](#git-clone-or-manual-copy) to one of those paths, +then select them in `agent.yaml`: + +```yaml +agents: + root: + model: dmr/ai/qwen3 + instruction: Help with Docker development tasks. + skills: true + toolsets: + - type: filesystem +``` + +`skills: true` includes all discovered skills; use a list of skill names to +limit the selection. See [Docker Agent skill +discovery](/ai/docker-agent/features/skills/) for paths and configuration. + +## Git clone or manual copy {#git-clone-or-manual-copy} + +When a managed installer doesn't fit your client, select a reviewed +[tagged revision](https://github.com/docker/skills/tags) of Docker Skills and +replace `vX.Y.Z` with that tag: + +```console +$ git clone --branch vX.Y.Z --depth 1 https://github.com/docker/skills.git +``` + +Copy each selected directory under `skills/` into a discovery path documented +by your agent. Keep its `SKILL.md` and all supporting files together. + +## Verify the installation + +First, check the installed-plugin or extension view, `npx skills list`, or +`sbx skills ls`, as appropriate. For a manual copy, check that the destination +contains a readable `SKILL.md` and its supporting files. This confirms the +files are installed, not that the agent loaded a skill. + +Start a new agent session and ask for a matching Docker task, such as “Review my +Dockerfile for cache efficiency and non-root execution. Tell me which installed +skill you loaded, and show its `SKILL.md` path.” If your client displays skill +activity, check that it loaded the expected file. Otherwise, ask for a specific +instruction from that file and compare it with the installed copy. If the +skill isn't available, check the installation path and scope. + +## Update and troubleshoot + +- Update native plugins and extensions with their client, CLI-managed skills + with `npx skills update` in the matching scope (add `--global` for user scope), + and repository-installed sandbox skills with `sbx skills update` when + available. For host-imported sandbox skills, update the host files and run + `sbx skills import` again, then restart the sandbox. Docker Agent relies on + the installer that owns its discovered files. +- For a fixed snapshot, choose a [Docker Skills + tag](https://github.com/docker/skills/tags) and use that tagged revision + instead of a rolling repository URL. Manually copied directories don't + update themselves; replace the complete directory when moving to another + reviewed tag. +- If a plugin or extension doesn't appear, check that it is enabled in the + intended scope and that your organization permits the repository. +- If the agent doesn't find an installed skill, check its discovery path and + selected agent and scope, then start a new session. For Docker Agent, also + check the `skills:` filter; for Sandboxes, check that the shared store is + mounted and the skill was added or imported into it. +- If a link isn't followed or supporting files are missing, reinstall with a + physical copy of the complete skill directory. diff --git a/content/manuals/billing/3d-secure.md b/content/manuals/billing/3d-secure.md deleted file mode 100644 index 9b1b2efdca39..000000000000 --- a/content/manuals/billing/3d-secure.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Use 3D Secure authentication for Docker billing -linkTitle: 3D Secure authentication -description: Docker billing supports 3D Secure (3DS) for secure payment authentication. Learn how 3DS works with Docker subscriptions. -keywords: billing, renewal, payments, subscriptions, 3DS, credit card verification, secure payments, Docker billing security -weight: 40 ---- - -Docker supports 3D Secure (3DS), an extra layer of authentication required -for certain credit card payments. If your bank or card issuer requires 3DS, you -may need to verify your identity before your payment can be completed. - -## How it works - -When a 3DS check is triggered during checkout, your bank or card issuer -may ask you to verify your identity. This can include: - -- Entering a one-time password sent to your phone -- Approving the charge through your mobile banking app -- Answering a security question or using biometrics - -The exact verification steps depend on your financial institution's -requirements. - -## When you need to verify - -You may be asked to verify your identity when performing any of the following -actions: - -- Starting a [paid subscription](../subscription/setup.md) -- Changing your [billing cycle](/manuals/billing/cycle.md) from monthly to annual -- [Upgrading your subscription](../subscription/change.md) -- [Adding seats](../admin/organization/manage/manage-seats.md) to an existing subscription - -If 3DS is required and your payment method supports it, the verification prompt -will appear during checkout. - -## Troubleshooting payment verification - -If you're unable to complete your payment due to 3DS: - -1. Retry your transaction. Make sure you're completing the verification - prompt in the same browser tab. -1. Use a different payment method. Some cards may not support 3DS properly - or be blocked. -1. Contact your bank. Your bank may be blocking the payment or the 3DS - verification attempt. - -> [!NOTE] -> -> Disabling ad blockers or browser extensions that block pop-ups can help -> the 3DS prompt display correctly. diff --git a/content/manuals/billing/_index.md b/content/manuals/billing/_index.md deleted file mode 100644 index 6202bc2310a5..000000000000 --- a/content/manuals/billing/_index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Manage billing and payments -linkTitle: Billing -description: Find information about managing billing and payments for Docker subscriptions. -keywords: billing, invoice, payment, subscription, Docker billing, update payment method, billing history, invoices, payment verification, tax exemption -weight: 10 -params: - sidebar: - group: Platform -grid_core: -- title: Add or update a payment method - description: Learn how to add or update a payment method for your personal account or organization. - link: /billing/payment-method/ - icon: credit-card -- title: Update billing information - description: Discover how to update the billing information for your personal account or organization. - link: /billing/details/ - icon: pencil-square -- title: View billing history - description: Learn how to view billing history and download past invoices. - link: /billing/history/ - icon: credit-card -- title: Billing FAQs - description: Find the answers you need and explore common questions. - link: /billing/faqs/ - icon: question-mark-circle -- title: Register a tax certificate - description: Learn how to register a tax exemption certificate. - link: /billing/tax-certificate/ - icon: book-open -- title: 3D Secure authentication - description: Discover how Docker billing supports 3DS and how to troubleshoot potential issues. - link: /billing/3d-secure/ - icon: wallet -aliases: - - /billing/docker-hub-pricing/ ---- - -Use the resources in this section to manage billing and payments for your Docker -subscriptions. - -{{< grid items="grid_core" >}} diff --git a/content/manuals/billing/cycle.md b/content/manuals/billing/cycle.md deleted file mode 100644 index d8b6b3f492d8..000000000000 --- a/content/manuals/billing/cycle.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Change your billing cycle -weight: 50 -description: Learn to change your billing cycle for your Docker subscription -keywords: billing, cycle, payments, subscription ---- - -You can choose between a monthly or annual billing cycle when purchasing a -subscription. If you have a monthly billing cycle, you can choose to -switch to an annual billing cycle. - -If you're on a monthly plan, you can switch to a yearly plan at any time. -However, switching from a yearly to a monthly cycle isn't supported. - -When you change your billing cycle: - -- Your next billing date reflects the new cycle. To find your next billing date, - see [View renewal date](history.md#view-renewal-date). -- Your subscription's start date resets. For example, if the monthly - subscription started on March 1 and ended on April 1, switching the billing - duration on March 15, 2024, resets the new start date to March 15, 2024, with - an end date of March 15, 2025. -- Any unused portion of your monthly subscription is prorated and applied as - credit toward an annual subscription. For example, if your monthly cost is $10 - and you're used value is $5, when you switch to an annual cycle ($100), the - final charge is $95 ($100-$5). - -## Change personal account to an annual cycle - -Pay by invoice is not available for subscription upgrades or changes. - -To change your billing cycle: - -1. Sign in to [Docker Home](https://app.docker.com/) and select - your organization. -1. Select **Billing**. -1. On the plans and usage page, select **Switch to annual billing**. -1. Verify your billing information. -1. Select **Continue to payment**. -1. Verify payment information and select **Upgrade subscription**. If you choose to pay using a US bank account, you must verify the account. For more information, see [Verify a bank account](/manuals/billing/payment-method.md#verify-a-bank-account). - -The billing plans and usage page will now reflect your new annual plan details. - -## Change organization to an annual cycle - -You must be an organization owner to make changes to the payment information. - -Pay by invoice is not available for subscription upgrades or changes. - -Follow these steps to switch from a monthly to annual billing cycle for your -organization's Docker subscription: - -1. Sign in to [Docker Home](https://app.docker.com/) and select - your organization. -1. Select **Billing**. -1. On the plans and usage page, select **Switch to annual billing**. -1. Verify your billing information. -1. Select **Continue to payment**. -1. Verify payment information and select **Upgrade subscription**. If you choose to pay using a US bank account, you must verify the account. For more information, see [Verify a bank account](/manuals/billing/payment-method.md#verify-a-bank-account). diff --git a/content/manuals/billing/details.md b/content/manuals/billing/details.md deleted file mode 100644 index 2341798ecbd1..000000000000 --- a/content/manuals/billing/details.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Manage your billing information -weight: 30 -description: Learn how to update your billing information in Docker Hub -keywords: payments, billing, subscription, invoices, update billing email, change billing address, VAT ID, Docker billing account ---- - -You can update the billing information for your personal account or for an -organization. When you update your billing information, these changes apply to -future billing invoices. The email address you provide for a billing account is -where Docker sends all invoices and other billing related communications. - -> [!NOTE] -> -> Existing invoices, whether paid or unpaid, cannot be updated. -> Changes only apply to future invoices. - -## Manage billing information - -### Personal account - -To update your billing information: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Billing**. -1. Select **Billing information** from the left-hand navigation. -1. On your billing information card, select **Change**. -1. Update your billing contact and billing address information. -1. Optional. To add or update a VAT ID, select the **I'm purchasing as a business** checkbox and enter your Tax ID. - - > [!IMPORTANT] - > - > Your VAT number must include your country prefix. For example, if you are - > entering a VAT number for Germany, you would enter `DE123456789`. - -1. Select **Update**. - -### Organization - -> [!NOTE] -> -> You must be an organization owner to make changes to the billing information. - -To update your billing information: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Billing**. -1. Select **Billing information** from the left-hand navigation. -1. On your billing information card, select **Change**. -1. Update your billing contact and billing address information. -1. Optional. To add or update a VAT ID, select the **I'm purchasing as a business** checkbox and enter your Tax ID. - - > [!IMPORTANT] - > - > Your VAT number must include your country prefix. For example, if you are - > entering a VAT number for Germany, you would enter `DE123456789`. - -1. Select **Update**. - -## Update your billing email address - -Docker sends the following billing-related emails: - -- Confirmations (new subscriptions, paid invoices) -- Notifications (card failure, card expiration) -- Reminders (subscription renewal) - -You can update the email address that receives billing invoices at any time. - -### Personal account - -To update your billing email address: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Billing**. -1. Select **Billing information** from the left-hand navigation. -1. On your billing information card, select **Change**. -1. Update your billing contact information and select **Update**. - -### Organizations - -To update your billing email address: - -1. Sign in to [Docker Home](https://app.docker.com/) and select - your organization. -1. Select **Billing**. -1. Select **Billing information** from the left-hand navigation. -1. On your billing information card, select **Change**. -1. Update your billing contact information and select **Update**. diff --git a/content/manuals/billing/faqs.md b/content/manuals/billing/faqs.md deleted file mode 100644 index 3e9b3dd2fcd8..000000000000 --- a/content/manuals/billing/faqs.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Billing FAQs -linkTitle: FAQs -description: Frequently asked questions related to billing -keywords: billing, renewal, payments, faq -tags: [FAQ] -weight: 60 ---- - -### What happens if my subscription payment fails? - -If your subscription payment fails, there is a grace period of 15 days, -including the due date. Docker retries to collect the payment 3 times using the -following schedule: - -- 3 days after the due date -- 5 days after the previous attempt -- 7 days after the previous attempt - -Docker also sends an email notification -`Action Required - Credit Card Payment Failed` with an attached unpaid invoice -after each failed payment attempt. - -Once the grace period is over and the invoice is still not paid, the -subscription downgrades to a free subscription and all paid features are -disabled. - -### Can I manually retry a failed payment? - -No. Docker retries failed payments on a [retry schedule](/manuals/billing/faqs.md#what-happens-if-my-subscription-payment-fails). - -To ensure a retired payment is successful, verify your default payment is -updated. If you need to update your default payment method, see -[Manage payment method](/manuals/billing/payment-method.md#manage-payment-method). - -### Does Docker collect sales tax and/or VAT? - -Docker collects sales tax and/or VAT from the following: - -- For United States customers, Docker began collecting sales tax on July 1, 2024. -- For European customers, Docker began collecting VAT on March 1, 2025. -- For United Kingdom customers, Docker began collecting VAT on May 1, 2025. - -To ensure that tax assessments are correct, make sure that your billing -information and VAT/Tax ID, if applicable, are updated. See -[Update the billing information](/manuals/billing/details.md). - -If you're exempt from sales tax, see -[Register a tax certificate](/manuals/billing/tax-certificate.md). - -### Does Docker offer academic pricing? - -For academic pricing, contact the -[Docker Sales Team](https://www.docker.com/company/contact). - -### Can I use pay by invoice for upgrades or additional seats? - -No. Pay by invoice is only available for renewing annual subscriptions, not for -purchasing upgrades or additional seats. You must use card payment or US bank -accounts for these changes. - -For a list of supported payment methods, see -[Add or update a payment method](/manuals/billing/payment-method.md). diff --git a/content/manuals/billing/history.md b/content/manuals/billing/history.md deleted file mode 100644 index 66275e45b5e6..000000000000 --- a/content/manuals/billing/history.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Invoices and billing history -weight: 40 -description: Learn how to view invoices and your billing history -keywords: payments, billing, subscription, invoices, renewals, invoice management, billing administration, pay invoice -aliases: - - /billing/core-billing/history/ ---- - -Learn how to view and pay invoices, view your billing history, and verify -your billing renewal date. All monthly and annual subscriptions are -automatically renewed at the end of the subscription term using your default -payment method. - -## View an invoice - -Your invoice includes the following: - -- Invoice number -- Date of issue -- Due date -- Your "Bill to" information -- Amount due (in USD) -- Pay online: Select this link to pay your invoice online -- Description of your order, quantity if applicable, unit price, and - amount (in USD) -- Subtotal, discount (if applicable), and total - -The information listed in the "Bill to" section of your invoice is based on -your billing information. Not all fields are required. The billing information -includes the following: - -- Name (required): The name of the administrator or company -- Address (required) -- Email address (required): The email address that receives all billing-related - emails for the account -- Phone number -- Tax ID or VAT - -You can’t make changes to a paid or unpaid billing invoice. When you update -your billing information, this change won't update an existing invoice. - -If you need -to update your billing information, make sure you do so before your -subscription renewal date when your invoice is finalized. - -For more information, see [Update billing information](details.md). - -## Pay an invoice - -> [!NOTE] -> -> Pay by invoice is only available for subscribers on an annual billing cycle. -> To change your billing cycle, see [Change your billing cycle](/manuals/billing/cycle.md). - -If you've selected pay by invoice for your subscription, you'll receive email -reminders to pay your invoice at 10 days before the due date, on the due date, -and 15 days after the due date. - -You can pay an invoice from the Docker Billing Console: - -1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization. -1. Select **Billing**. -1. Select **Invoices** and locate the invoice you want to pay. -1. In the **Actions** column, select **Pay invoice**. -1. Fill out your payment details and select **Pay**. - -When your payment has processed, the invoice's **Status** column will update to -**Paid** and you will receive a confirmation email. - -If you choose to pay using a US bank account, you must verify the account. For -more information, see [Verify a bank account](/manuals/billing/payment-method.md#verify-a-bank-account). - -### View renewal date - -You receive your invoice when the subscription renews. To verify your renewal -date: - -1. Sign in to [Docker Home Billing](https://app.docker.com/billing). -1. Find your renewal date and amount on your subscription plan card. - -## Include your VAT number on your invoice - -> [!NOTE] -> -> If the VAT number field is not available, complete the -> [Contact Support form](https://hub.docker.com/support/contact/). This field -> may need to be manually added. - -To add or update your VAT number: - -1. Sign in to [Docker Home](https://app.docker.com/) and choose your - organization. -1. Select **Billing**. -1. Select **Billing information** from the left-hand menu. -1. Select **Change** on your billing information card. -1. Ensure the **I'm purchasing as a business** checkbox is checked. -1. Enter your VAT number in the Tax ID section. - - > [!IMPORTANT] - > - > Your VAT number must include your country prefix. For example, if you are - > entering a VAT number for Germany, you would enter `DE123456789`. - -1. Select **Update**. - -Your VAT number will be included on your next invoice. - -## View billing history - -You can view your billing history and download past invoices for a personal -account or organization. - -### Personal account - -To view billing history: - -1. Sign in to [Docker Home](https://app.docker.com/) and choose your - organization. -1. Select **Billing**. -1. Select **Invoices** from the left-hand menu. -1. Optional. Select the **Invoice number** to open invoice details. -1. Optional. Select the **Download** button to download an invoice. - -### Organization - -You must be an owner of the organization to view the billing history. - -To view billing history: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -1. Select **Billing**. -1. Select **Invoices** from the left-hand menu. -1. Optional. Select the **invoice number** to open invoice details. -1. Optional. Select the **download** button to download an invoice. diff --git a/content/manuals/billing/payment-method.md b/content/manuals/billing/payment-method.md deleted file mode 100644 index 8e11fbbf3e26..000000000000 --- a/content/manuals/billing/payment-method.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Add or update a payment method -weight: 20 -description: Learn how to add or update a payment method in Docker Hub -keywords: payments, billing, subscription, supported payment methods, failed payments, add credit card, bank transfer, Stripe Link, payment failure -aliases: - - /billing/core-billing/payment-method/ ---- - -Docker supports different payment methods for your paid personal -account or organization. This page describes supported payment types, how to make payments from [Docker Home](https://app.docker.com/), and how to set up pay by invoice. - -## Supported payment types - -You can add a payment method or update your account's existing payment method -at any time. All charges are in United States dollars (USD). The following payment methods are supported: - -| Category | Payment type | -| ------------- | ----------------------------------------------------------------------- | -| Cards | Visa, MasterCard, American Express, Discover, JCB, Diners, UnionPay | -| Wallets | Stripe Link | -| Bank accounts | Automated Clearing House (ACH) transfer with a verified US bank account | - -## Prerequisites - -Certain payment methods require additional steps before selecting them as a payment method: - -- You must [verify a bank account](/manuals/billing/payment-method.md#verify-a-bank-account) before choosing a bank account. -- You must have a Docker Business or Docker Team plan to [pay by invoice](/manuals/billing/payment-method.md#enable-and-disable-pay-by-invoice). -- You must be an existing Stripe Link customer, or fill out the card information form to use Link payments. - -## Manage payment method - -Paid personal accounts and organizations follow the same procedures to add, update, or remove payment methods. - -### Add payment method - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Select your account name for personal accounts, or select your organization name for organization accounts. -1. Select **Billing**, then **Payment methods**. -1. Select **Add payment method** and enter your new payment information: - - For first time setup, fill in your billing information. - - To purchase as a business, provide your tax ID. -1. Choose to add a card, a US bank account, or a Link payment. - - To pay with card, fill out the card information form. - - To pay with a US bank account: - - Verify your **Email** and **Full name**. - - If your bank is listed, select your bank's name. - - If your bank is not listed, select **Search for your bank**. - - To pay through Link, select an existing payment and choose **Use this card**. -1. Finish adding the payment method by selecting **Add payment method**. - -### Set default payment method - -After adding one or more payment methods, you can set one as a default method. - -1. From **Billing**, go to **Payment methods**. -1. Find the payment method you want to set as default from the **Payment method** table. -1. Select the three dots, then choose **Set as default**. - -### Remove payment method - -To remove a single payment method: - -1. From **Billing**, go to **Payment methods**. -1. Find the payment method you want to remove from the **Payment method** table. -1. Select the three dots, then choose **Remove**. - -To remove your default payment method, first set a different payment method as default, or [downgrade to a free subscription](/manuals/subscription/change.md). - -## Enable and disable pay by invoice - -> [!TIP] -> Do you need to pay by invoice? [Upgrade to a Docker Business or Docker Team plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsBillingPaymentMethod) and choose the annual subscription. - -Pay by invoice requires you to pay upfront for your first subscription period using a payment card or ACH bank transfer. At renewal time, instead of automatic payment, you'll receive an invoice via -email that you must pay manually. - -Follow these steps to enable or disable pay by invoice: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your - organization. -2. Select **Billing**, then **Payment methods**. -3. Select **Pay by invoice**, then select the pay by invoice toggle to enable or disable. -4. Confirm your billing contact details. If you need to change them, select - **Change** and enter your new details. - -Pay by invoice is not available for -subscription upgrades or changes. - -## Verify a bank account - -There are two ways to verify a bank account as a payment method: - -- Instant verification: Docker supports several major banks for instant - verification. -- Manual verification: All other banks must be verified manually. - -### Instant verification - -To verify your bank account instantly, you must sign in to your bank account -from the Docker billing flow: - -1. Choose **US bank account** as your payment method. -1. Verify your **Email** and **Full name**. -1. If your bank is listed, select your bank's name or - select **Search for your bank**. -1. Sign in to your bank and review the terms and conditions. This agreement - allows Docker to debit payments from your connected bank account. -1. Select **Agree and continue**. -1. Select an account to link and verify, and select **Connect account**. - -When the account is verified, you will see a success message in the pop-up -modal. - -### Manual verification - -To verify your bank account manually, you must enter the micro-deposit amount -from your bank statement: - -1. Choose **US bank account** as your payment method. -1. Verify your **Email** and **First and last name**. -1. Select **Enter bank details manually instead**. -1. Enter your bank details: **Routing number** and **Account number**. -1. Select **Submit**. -1. You will receive an email with instructions on how to manually verify. - -Manual verification uses micro-deposits. You’ll see a small deposit -(such as $0.01) in your bank account within 1–2 business days. Open your manual -verification email and enter the amount of this deposit to verify your account. - -## Failed payments - -If your payment fails, select **Pay now**. This redirects you from Docker Hub so you can manually retry the payment through Stripe. - -You have a grace period of 15 days -including the due date when your payment fails. Docker retries to collect the payment 3 times using the -following schedule: - -- 3 days after the due date -- 5 days after the previous attempt -- 7 days after the previous attempt - -Docker also sends an email notification -`Action Required - Credit Card Payment Failed` with an attached unpaid invoice -after each failed payment attempt. - -Once the grace period is over and the invoice is still not paid, the -subscription downgrades to a free subscription and all paid features are -disabled. diff --git a/content/manuals/billing/tax-certificate.md b/content/manuals/billing/tax-certificate.md deleted file mode 100644 index 246a12e4bbbc..000000000000 --- a/content/manuals/billing/tax-certificate.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Submit a tax exemption certificate -description: Learn how to submit a tax exemption or VAT certificate for Docker billing. -keywords: billing, renewal, payments, tax, exemption, VAT, billing support, Docker billing -weight: 50 ---- - -If you're a customer in the United States and are exempt from sales tax, you -can submit a valid tax exemption certificate to Docker Support. - -If you're a global customer subject to VAT, make sure to include your -[VAT number](/manuals/billing/history.md#include-your-vat-number-on-your-invoice) -along with your country prefix when you update your billing profile. - -## Prerequisites - -Before submitting your certificate: - -- The customer name must match the name on the certificate. -- The certificate must list Docker Inc. as the Seller or Vendor, with all - relevant fields completed. -- The certificate must be signed, dated, and not expired. -- You must include the Docker ID or namespace(s) for all accounts to - apply the certificate to. - -> [!IMPORTANT] -> -> You can use the same certificate for multiple namespaces, if applicable. - -## Contact information - -Use the following contact information on your certificate: - -Docker, Inc. -3790 El Camino Real #1052 -Palo Alto, CA 94306 -(415) 941-0376 - -## Register a tax certificate - -1. [Submit a Docker Support ticket](https://hub.docker.com/support/contact?topic=Billing&subtopic=Tax%20information) to initiate the process to register a tax certificate. -1. Enter **Tax certificate** as the support ticket **Subject**. -1. In the **Details** field, enter **Submitting a tax certificate**. -1. Instructions will populate on how to submit a tax certificate. -1. Fill out all required fields on the support form. -1. In the file upload section, add the tax certificate by dragging and dropping - the file, or selecting **Browse files**. -1. Select **Submit**. - -Docker's support team will reach out to you if any additional information is -required. You'll receive an e-mail confirmation from Docker once your tax -exemption status is applied to your account. diff --git a/content/manuals/build-cloud/_index.md b/content/manuals/build-cloud/_index.md index 85a2308b52b7..54af535bd8d5 100644 --- a/content/manuals/build-cloud/_index.md +++ b/content/manuals/build-cloud/_index.md @@ -52,16 +52,16 @@ data between cloud builders. ## Get Docker Build Cloud To get started with Docker Build Cloud, -[create a Docker account](/accounts/create-account/). There are two options +[create a Docker account](/accounts/individual/create-account/). There are two options to get access to Docker Build Cloud: - Users with a free Personal account can opt-in to a 7-day free trial, with the option -to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions. + to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions. - All users with a paid Docker subscription have access to Docker Build Cloud included -with their Docker suite of products. See [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsBuildCloud) for more information. + with their Docker suite of products. See [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsBuildCloud) for more information. Once you've signed up and created a builder, continue by [setting up the builder in your local environment](./setup.md). For information about roles and permissions related to Docker Build Cloud, see -[Roles and Permissions](/manuals/enterprise/security/roles-and-permissions.md#docker-build-cloud-permissions). +[Roles and Permissions](/manuals/security/roles-and-permissions/core-roles.md#docker-build-cloud). diff --git a/content/manuals/build-cloud/builder-settings.md b/content/manuals/build-cloud/builder-settings.md index fdae2806dbf9..ef8a653e98b4 100644 --- a/content/manuals/build-cloud/builder-settings.md +++ b/content/manuals/build-cloud/builder-settings.md @@ -25,7 +25,7 @@ Any changes take effect immediately. Your subscription includes the following Build cache space: | Subscription | Build cache space | -|--------------|-------------------| +| ------------ | ----------------- | | Personal | N/A | | Pro | 50GB | | Team | 100GB | @@ -43,19 +43,27 @@ two builders: > [!IMPORTANT] > > If you only build for one architecture, be aware that your effective cache -space is half of your subscription's total allocation. +> space is half of your subscription's total allocation. ### Get more build cache space -To get more Build cache space, [upgrade your subscription](/manuals/subscription/scale.md). +To get more Build cache space, [upgrade your subscription](/manuals/subscription-billing/manage/plans.md#upgrade-plans). > [!TIP] > > If you build large images, consider allocating less storage for caching to -leave more space for active builds. +> leave more space for active builds. ## Private resource access +> [!IMPORTANT] +> +> Private resource access requires the private Buildx client. The `cloud` +> driver in standard Buildx doesn't support this feature. If your cloud builder +> uses private resource access, continue using the +> [latest private Buildx release](https://github.com/docker/buildx-desktop/releases/latest) +> until the feature is supported in standard Buildx. + Private resource access lets cloud builders pull images and packages from private resources. This feature is useful when builds rely on self-hosted artifact repositories or private OCI registries. For example, if your organization hosts a private [PyPI](https://pypi.org/) repository on a private network, Docker Build Cloud would not be able to access it by default, since the cloud builder is not connected to your private network. diff --git a/content/manuals/build-cloud/ci.md b/content/manuals/build-cloud/ci.md index f3d0e476eb42..42227f6177f2 100644 --- a/content/manuals/build-cloud/ci.md +++ b/content/manuals/build-cloud/ci.md @@ -23,21 +23,23 @@ registry directly, rather than loading the image and then pushing it. Pushing directly speeds up your builds and avoids unnecessary file transfers. If you just want to build and discard the output, export the results to the -build cache or build without tagging the image. When you use Docker Build Cloud, -Buildx automatically loads the build result if you build a tagged image. -See [Loading build results](./usage/#loading-build-results) for details. +build cache or build without tagging the image. With no explicit output, Buildx +leaves an untagged result in the cloud build cache and automatically loads +eligible tagged images. See +[Loading build results](./usage/#loading-build-results) for details. > [!NOTE] > -> Builds on Docker Build Cloud have a timeout limit of 90 minutes. Builds that -> run for longer than 90 minutes are automatically cancelled. +> Builds on Docker Build Cloud have a timeout limit that depends on your +> subscription plan. Builds that run for longer than your limit are +> automatically cancelled. ## Setting up credentials for CI/CD To enable your CI/CD system to build and push images using Docker Build Cloud, provide both an access token and a username. The type of token and the username you use depend on your account type and permissions. -- If you are an organization administrator or have permission to create [organization access tokens (OAT)](/manuals/enterprise/security/access-tokens.md), use an OAT and set `DOCKER_ACCOUNT` to your Docker Hub organization name. -- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/access-tokens/) and set `DOCKER_ACCOUNT` to your Docker Hub username. +- If you are an organization administrator or have permission to create [organization access tokens (OAT)](/manuals/security/access-tokens/organization-access-tokens.md), use an OAT and set `DOCKER_ACCOUNT` to your Docker Hub organization name. +- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/access-tokens/personal-access-tokens/) and set `DOCKER_ACCOUNT` to your Docker Hub username. ### Creating access tokens @@ -45,7 +47,7 @@ To enable your CI/CD system to build and push images using Docker Build Cloud, p If you are an organization administrator: -- Create an [organization access token (OAT)](/manuals/enterprise/security/access-tokens.md). The token must have these permissions: +- Create an [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md). The token must have these permissions: 1. **cloud-connect** scope 2. **Read public repositories** permission 3. **Repository access** with **Image push** permission for the target repository: @@ -59,13 +61,28 @@ If you are not an organization administrator: #### For personal accounts -- Create a [personal access token (PAT)](/security/access-tokens/) with the following permissions: +- Create a [personal access token (PAT)](/security/access-tokens/personal-access-tokens/) with the following permissions: 1. **Read & write** access. - Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository. ## CI platform examples +> [!IMPORTANT] +> +> These examples require Buildx version 0.37.0 or later, which includes the +> `cloud` driver. The Docker CLI version doesn't determine the installed Buildx +> plugin version, and CI runner images may include an earlier Buildx release. +> +> Check the installed version: +> +> ```console +> $ docker buildx version +> ``` +> +> If the version is earlier than 0.37.0, install Buildx as a +> [Docker CLI plugin](https://github.com/docker/buildx#manual-download). + > [!NOTE] > > In your CI/CD configuration, set the following variables/secrets: @@ -77,6 +94,8 @@ If you are not an organization administrator: ### GitHub Actions +<!-- TODO: Confirm whether standard Buildx requires a minimum setup-buildx-action version. --> + ```yaml name: ci @@ -139,19 +158,12 @@ For more information about the `BUILDX_BUILDER` environment variable, see ```yaml default: - image: docker:24-dind + image: docker:cli services: - - docker:24-dind + - docker:dind before_script: - docker info - echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin - - | - apk add curl jq - ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/} - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - mkdir -vp ~/.docker/cli-plugins/ - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL - chmod a+x ~/.docker/cli-plugins/docker-buildx - docker buildx create --use --driver cloud ${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME} variables: @@ -194,13 +206,6 @@ jobs: steps: - checkout - - run: | - mkdir -vp ~/.docker/cli-plugins/ - ARCH=amd64 - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL - chmod a+x ~/.docker/cli-plugins/docker-buildx - - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" @@ -217,13 +222,6 @@ jobs: steps: - checkout - - run: | - mkdir -vp ~/.docker/cli-plugins/ - ARCH=amd64 - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL - chmod a+x ~/.docker/cli-plugins/docker-buildx - - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" @@ -280,28 +278,6 @@ steps: Create the `build.sh` script: ```bash -DOCKER_DIR=/usr/libexec/docker - -# Get download link for latest buildx binary. -# Set $ARCH to the CPU architecture (e.g. amd64, arm64) -UNAME_ARCH=`uname -m` -case $UNAME_ARCH in - aarch64) - ARCH="arm64"; - ;; - amd64) - ARCH="amd64"; - ;; - *) - ARCH="amd64"; - ;; -esac -BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - -# Download docker buildx with Build Cloud support -curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL -chmod a+x ~/.docker/cli-plugins/docker-buildx - # Connect to your builder and set it as the default builder docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" @@ -327,7 +303,6 @@ pipeline { agent any environment { - ARCH = 'amd64' DOCKER_ACCESS_TOKEN = credentials('docker-access-token') DOCKER_ACCOUNT = credentials('docker-account') CLOUD_BUILDER_NAME = '<CLOUD_BUILDER_NAME>' @@ -336,13 +311,7 @@ pipeline { stages { stage('Build') { - environment { - BUILDX_URL = sh (returnStdout: true, script: 'curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\\"linux-$ARCH\\"))"').trim() - } steps { - sh 'mkdir -vp ~/.docker/cli-plugins/' - sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL' - sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx' sh 'echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin' sh 'docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"' // Cache-only build @@ -371,12 +340,7 @@ env: before_install: | echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin -install: | - set -e - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))") - mkdir -vp ~/.docker/cli-plugins/ - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL - chmod a+x ~/.docker/cli-plugins/docker-buildx +before_script: | docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" script: | @@ -392,18 +356,13 @@ script: | # Prerequisites: $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN setup as deployment variables # This pipeline assumes $BITBUCKET_REPO_SLUG as the image name -image: atlassian/default-image:3 +image: docker:cli pipelines: default: - step: name: Build multi-platform image script: - - mkdir -vp ~/.docker/cli-plugins/ - - ARCH=amd64 - - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL - - chmod a+x ~/.docker/cli-plugins/docker-buildx - echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin - docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" - IMAGE_NAME=$BITBUCKET_REPO_SLUG @@ -420,15 +379,6 @@ pipelines: ```bash #!/bin/bash -# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64) -ARCH=amd64 -BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") - -# Download docker buildx with Build Cloud support -mkdir -vp ~/.docker/cli-plugins/ -curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL -chmod a+x ~/.docker/cli-plugins/docker-buildx - # Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin @@ -451,35 +401,18 @@ docker buildx build \ ### Docker Compose -Use this implementation if you want to use `docker compose build` with -Docker Build Cloud in CI. +This example requires Buildx version 0.37.0 or later. Set the cloud builder as +the default builder before running `docker compose build` in CI: ```bash #!/bin/bash -# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64) -ARCH=amd64 -BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))") -COMPOSE_URL=$(curl -sL \ - -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer <GITHUB_TOKEN>" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - https://api.github.com/repos/docker/compose-desktop/releases \ - | jq "[ .[] | select(.prerelease==false and .draft==false) ] | .[0].assets.[] | select(.name | endswith(\"linux-${ARCH}\")) | .browser_download_url") - -# Download docker buildx with Build Cloud support -mkdir -vp ~/.docker/cli-plugins/ -curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL -curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL -chmod a+x ~/.docker/cli-plugins/docker-buildx -chmod a+x ~/.docker/cli-plugins/docker-compose - # Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin # Connect to your builder and set it as the default builder docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}" -# Build the image build +# Build the images docker compose build ``` diff --git a/content/manuals/build-cloud/release-notes.md b/content/manuals/build-cloud/release-notes.md index d37174d8fdf2..5fb17e21881d 100644 --- a/content/manuals/build-cloud/release-notes.md +++ b/content/manuals/build-cloud/release-notes.md @@ -9,6 +9,140 @@ tags: [Release notes] This page contains information about the new features, improvements, known issues, and bug fixes in Docker Build Cloud releases. +## 2026-09-14 + +### Enhancements + +- Cloud builders now run BuildKit v0.33.0, upgraded from v0.32.2. Notable + changes: + + - The maximum size of an exported attestation, such as an SBOM, is raised + from 40 MiB to 80 MiB. Builds whose SBOM exceeded the previous limit failed + with an error ending in `sbom.spdx.json exceeds 41943040 bytes`. + - The built-in Dockerfile frontend is updated to + [v1.27.0](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.27.0). + This only affects builds that don't pin a frontend with a `# syntax=` + directive. + - Credentials embedded in HTTP source URLs and Git bundle checkouts are now + redacted from more places in build progress output and error messages. + Builds that pass credentials with + [build secrets](/manuals/build/building/secrets.md) weren't affected. + - Git advice messages, such as detached `HEAD` guidance, are no longer shown + in build output for Git contexts and `ADD` Git sources. To show them again, + set the build argument `BUILDKIT_GIT_ADVICE=1`. + + For the full list of changes, see the + [BuildKit release notes](https://github.com/moby/buildkit/releases/tag/v0.33.0). + +- Docker Build Cloud is verified against Buildx v0.37.0, up from v0.36.1. Buildx + is distributed with Docker Desktop and Docker Engine rather than with Docker + Build Cloud, so your client version depends on how you installed Docker. See + the [Buildx release notes](https://github.com/docker/buildx/releases) for + client-side changes. + +### Bug fixes + +- Fixed an error containing `no active session for` that could occur when + running concurrent builds that use a remote cache. +- Fixed a possible `failed to apply diffs: snapshot does not exist` error. +- Fixed a cache link that the remote cache exporter could silently drop. + +## 2026-08-18 + +### Enhancements + +- Cloud builders now run BuildKit v0.32.2, upgraded from v0.32.1. This release + reverts a v0.32.1 workaround that pushed each attestation manifest only after + the image manifest it refers to. BuildKit again follows the OCI distribution + specification, which lets a referrer be pushed before its subject. If your + registry rejects a manifest whose subject doesn't exist yet, build with + `--output type=image,oci-artifact=false`. For details, see the + [BuildKit release notes](https://github.com/moby/buildkit/releases/tag/v0.32.2). + +- Docker Build Cloud is verified against Buildx v0.36.1, up from v0.36.0. See + the [Buildx release notes](https://github.com/docker/buildx/releases) for + client-side changes. + +## 2026-08-03 + +### Enhancements + +- Cloud builders now run BuildKit v0.32.1, upgraded from v0.20.0. This spans + twelve minor BuildKit releases of new build features, performance + improvements, and bug fixes. For the full list of changes, see the + [BuildKit release notes](https://github.com/moby/buildkit/releases). + + This range includes the following changes to default behavior. Each of these + is an [exporter attribute](/manuals/build/exporters/image-registry.md) that + you pass with `--output`, or an + [attestation attribute](/manuals/build/metadata/attestations/_index.md) that + you pass with `--attest`: + + - Image results now use OCI media types by default. If your registry doesn't + support OCI media types, build with + `--output type=image,oci-mediatypes=false`. Treat this as a temporary + measure until your registry supports OCI media types. + - Attestations now use OCI artifact descriptors by default. If your registry + doesn't support OCI artifacts, build with + `--output type=image,oci-artifact=false`. Note that the attribute is + singular. + - [Provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md) + now default to SLSA v1 instead of v0.2, which changes both the predicate + type and the schema. If you verify provenance in your CI pipeline, confirm + that your verifier supports the SLSA v1 predicate before your next build. + A verifier that doesn't recognize the new predicate type may report that no + attestation was found rather than failing outright, which can silently + weaken a supply chain check. To keep the previous format while you update + your tooling, build with `--attest type=provenance,version=v0.2`. + +- Docker Build Cloud is verified against Buildx v0.36.0, up from v0.21.0. Buildx + is the client you build with, and it's distributed with Docker Desktop and + Docker Engine rather than with Docker Build Cloud, so your client version + depends on how you installed Docker. For the client-side features available + when building with a cloud builder, see the + [Buildx release notes](https://github.com/docker/buildx/releases). + +## 2025-12-19 + +### Bug fixes + +- Fixed an error when building + [Docker Hardened Images](/manuals/dhi/_index.md) with a cloud builder. +- Fixed builds failing with gRPC message size errors when transferring large + amounts of data. +- Fixed a 500 error when pulling images whose attestations or signatures are + resolved through the OCI referrers fallback, which registries use when they + don't implement the referrers API directly. + +## 2025-06-04 + +### Enhancements + +- Build timeouts are now determined by your subscription plan rather than by a + single fixed limit applied to every build. + +## 2025-04-29 + +### Enhancements + +- Improved build error messages. Failures caused by your Dockerfile or build + context are now reported as build errors rather than internal errors. This + includes denied base image pulls, invalid stage names, and invalid `chmod` + and `mkdir` targets. + +## 2025-04-09 + +### Enhancements + +- Added a consolidated cloud usage report covering all builds in your + organization. + +## 2025-03-05 + +### Enhancements + +- Build usage reports now support custom date ranges. + ## 2025-02-24 ### New diff --git a/content/manuals/build-cloud/setup.md b/content/manuals/build-cloud/setup.md index 88aca9d035b8..25b939a522a1 100644 --- a/content/manuals/build-cloud/setup.md +++ b/content/manuals/build-cloud/setup.md @@ -15,21 +15,24 @@ environment. To get started with Docker Build Cloud, you need to: -- Download and install Docker Desktop version 4.26.0 or later. +- Install Docker Desktop version 4.26.0 or later, or Buildx version 0.37.0 or + later. - Create a cloud builder on the [Docker Build Cloud Dashboard](https://app.docker.com/build/). - When you create the builder, choose a name for it (for example, `default`). You will use this name as `BUILDER_NAME` in the CLI steps below. ### Use Docker Build Cloud without Docker Desktop -To use Docker Build Cloud without Docker Desktop, you must download and install -a version of Buildx with support for Docker Build Cloud (the `cloud` driver). -You can find compatible Buildx binaries on the releases page of -[this repository](https://github.com/docker/buildx-desktop). +Buildx version 0.37.0 or later includes the +[`cloud` driver](/manuals/build/builders/drivers/cloud.md). To use Docker Build +Cloud without Docker Desktop, check your installed version: -If you plan on building with Docker Build Cloud using the `docker compose -build` command, you also need a version of Docker Compose that supports Docker -Build Cloud. You can find compatible Docker Compose binaries on the releases -page of [this repository](https://github.com/docker/compose-desktop). +```console +$ docker buildx version +``` + +If your Docker CLI installation doesn't include a compatible Buildx version, +[install Buildx](https://github.com/docker/buildx#manual-download) as a Docker +CLI plugin. ## Steps diff --git a/content/manuals/build-cloud/usage.md b/content/manuals/build-cloud/usage.md index a6970aeceb16..bfa80fc0c171 100644 --- a/content/manuals/build-cloud/usage.md +++ b/content/manuals/build-cloud/usage.md @@ -36,8 +36,6 @@ $ docker buildx use cloud-<ORG>-<BUILDER_NAME> --global 2. Find the cloud builder under **Available builders**. 3. Open the drop-down menu and select **Use**. - ![Selecting the cloud builder as default using the Docker Desktop GUI](/build/images/set-default-builder-gui.webp) - {{< /tab >}} {{< /tabs >}} @@ -46,8 +44,8 @@ builder for the `docker buildx build` command. The `docker build` command still uses the `default` builder, unless you specify the `--builder` flag explicitly. If you use build scripts, such as `make`, that use the `docker build` command, -we recommend updating your build commands to `docker buildx build`. Alternatively, -you can set the [`BUILDX_BUILDER` environment +update your build commands to `docker buildx build`. Alternatively, you can set +the [`BUILDX_BUILDER` environment variable](/manuals/build/building/variables.md#buildx_builder) to specify which builder `docker build` should use. @@ -58,7 +56,7 @@ cloud builder as your selected builder, then run your build. > [!NOTE] > -> Make sure you're using a supported version of Docker Compose, see +> Make sure Buildx version 0.37.0 or later is installed. See > [Prerequisites](setup.md#prerequisites). ```console @@ -72,13 +70,16 @@ variable](/manuals/build/building/variables.md#buildx_builder) to select the clo ## Loading build results -Building with `--tag` loads the build result to the local image store -automatically when the build finishes. To build without a tag and load the -result, you must pass the `--load` flag. +When you don't specify an output, Buildx leaves an untagged build result in the +cloud build cache and doesn't load it into Docker Engine. If you use `--tag`, +Buildx automatically loads the image when the build targets a single platform +and runs on one cloud node. Use `--load` to request loading explicitly. + +The target Docker context determines which Docker Engine image store receives +the result. For details about loading behavior and other output configurations, +see [Load results from Docker Build Cloud](/manuals/build/exporters/_index.md#load-results-from-docker-build-cloud). -Loading the build result for multi-platform images is not supported. Use the -`docker buildx build --push` flag when building multi-platform images to push -the output to a registry. +To push a multi-platform image to a registry instead of loading it: ```console $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \ @@ -87,8 +88,8 @@ $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \ --push . ``` -If you want to build with a tag, but you don't want to load the results to your -local image store, you can export the build results to the build cache only: +To keep a tagged result in the build cache instead of loading it into Docker +Engine, use the `cacheonly` exporter: ```console $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \ diff --git a/content/manuals/build/_index.md b/content/manuals/build/_index.md index c703c678dfb0..664b52b2bba7 100644 --- a/content/manuals/build/_index.md +++ b/content/manuals/build/_index.md @@ -29,6 +29,10 @@ grid: description: Configure where and how you run your builds. icon: wrench-screwdriver link: /build/builders/drivers/ +- title: Docker Build Cloud + description: Run builds on managed cloud builders with a shared cache. + icon: /icons/logo-build-cloud.svg + link: /build-cloud/ - title: Exporters description: Export any artifact you like, not just Docker images. icon: arrow-up-on-square diff --git a/content/manuals/build/bake/contexts.md b/content/manuals/build/bake/contexts.md index 490b20a469d5..6dd1f8b9c613 100644 --- a/content/manuals/build/bake/contexts.md +++ b/content/manuals/build/bake/contexts.md @@ -89,4 +89,4 @@ target "app" { In most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is only recommended when you have -multiple Dockerfiles that can't be easily merged into one. +multiple Dockerfiles that can't be merged into one. diff --git a/content/manuals/build/bake/introduction.md b/content/manuals/build/bake/introduction.md index e1387f2e6e0e..58a2e2536b9b 100644 --- a/content/manuals/build/bake/introduction.md +++ b/content/manuals/build/bake/introduction.md @@ -6,9 +6,9 @@ description: Get started with using Bake to build your project keywords: bake, quickstart, build, project, introduction, getting started --- -Bake is an abstraction for the `docker build` command that lets you more easily -manage your build configuration (CLI flags, environment variables, etc.) in a -consistent way for everyone on your team. +Bake is an abstraction for the `docker build` command that lets you manage your +build configuration (CLI flags, environment variables, etc.) in a consistent +way for everyone on your team. Bake is a command built into the Buildx CLI, so as long as you have Buildx installed, you also have access to bake, via the `docker buildx bake` command. @@ -44,7 +44,7 @@ $ docker buildx bake myapp For simple builds, the difference between `docker build` and `docker buildx bake` is minimal. However, as your build configuration grows more complex, Bake -provides a more structured way to manage that complexity, that would be +provides a more structured way to manage that complexity, which would be difficult to manage with CLI flags for the `docker build`. It also provides a way to share build configurations across your team, so that everyone is building images in a consistent way, with the same configuration. diff --git a/content/manuals/build/bake/overrides.md b/content/manuals/build/bake/overrides.md index 51ef54a9a76b..27cf0028251d 100644 --- a/content/manuals/build/bake/overrides.md +++ b/content/manuals/build/bake/overrides.md @@ -36,6 +36,7 @@ To override these attributes, you can use the following methods: - [File overrides](#file-overrides) - [CLI overrides](#command-line) +- [Variable overrides](#variables) - [Environment variable overrides](#environment-variables) ## File overrides @@ -247,6 +248,21 @@ Complete list of attributes that can be overridden with `--set` are: - `tags` - `target` +## Variables + +Use `--var NAME=value` to override a declared Bake variable for a single +invocation. For example, set `TAG` without exporting it in your shell: + +```console +$ docker buildx bake --var TAG=dev webapp +``` + +The value takes precedence over an environment variable with the same name. +Unlike `--set webapp.tags=...`, this changes the variable wherever the Bake +definition uses it. See +[Override variable values](./variables.md#override-variable-values) for +precedence, types, and repeated flags. + ## Environment variables You can also use environment variables to override configurations. diff --git a/content/manuals/build/bake/variables.md b/content/manuals/build/bake/variables.md index 120c18b3e848..10637ef80286 100644 --- a/content/manuals/build/bake/variables.md +++ b/content/manuals/build/bake/variables.md @@ -2,14 +2,14 @@ title: Variables in Bake linkTitle: Variables weight: 40 -description: +description: Define, override, and validate variables in Docker Bake files keywords: build, buildx, bake, buildkit, hcl, variables --- You can define and use variables in a Bake file to set attribute values, interpolate them into other values, and perform arithmetic operations. Variables can be defined with default values, and can be overridden with -environment variables. +the `--var` flag or environment variables. ## Using variables as attribute values @@ -31,6 +31,25 @@ target "webapp" { } ``` +## Override variable values + +Use `--var NAME=value` to override a declared variable for one Bake invocation +without changing your shell's environment: + +```console +$ docker buildx bake --var TAG=docker.io/username/webapp:dev webapp +``` + +Repeat the flag to set multiple variables. If you repeat a name, the last +value wins. Explicit `--var` values take precedence over environment variables +with the same name and over defaults in the Bake file. Values are converted +to the declared variable type. + +This flag also works when environment-based variable lookups are disabled +with `BUILDX_BAKE_DISABLE_VARS_ENV_LOOKUP=1`. Use `--var` to set a variable +used in expressions throughout the definition; use `--set` to override a +specific target attribute. See [Overriding configurations](./overrides.md). + ## Interpolate variables into values Bake supports string interpolation of variables into values. You can use the diff --git a/content/manuals/build/builders/drivers/_index.md b/content/manuals/build/builders/drivers/_index.md index a90261ca451a..f54bfbbf9468 100644 --- a/content/manuals/build/builders/drivers/_index.md +++ b/content/manuals/build/builders/drivers/_index.md @@ -1,7 +1,7 @@ --- title: Build drivers description: Build drivers are configurations for how and where the BuildKit backend runs. -keywords: build, buildx, driver, builder, docker-container, kubernetes, remote +keywords: build, buildx, driver, builder, cloud, docker-container, kubernetes, remote aliases: - /build/buildx/drivers/ - /build/building/drivers/ @@ -15,6 +15,7 @@ Buildx supports the following drivers: - `docker`: uses the BuildKit library bundled into the Docker daemon. - `docker-container`: creates a dedicated BuildKit container using Docker. +- `cloud`: connects to a managed builder in Docker Build Cloud. - `kubernetes`: creates BuildKit pods in a Kubernetes cluster. - `remote`: connects directly to a manually managed BuildKit daemon. @@ -25,25 +26,28 @@ provide more flexibility and are better at handling advanced scenarios. The following table outlines some differences between drivers. -| Feature | `docker` | `docker-container` | `kubernetes` | `remote` | -| :--------------------------- | :---------: | :----------------: | :----------: | :----------------: | -| **Automatically load image** | ✅ | | | | -| **Cache export** | ✅\* | ✅ | ✅ | ✅ | -| **Tarball output** | | ✅ | ✅ | ✅ | -| **Multi-arch images** | | ✅ | ✅ | ✅ | -| **BuildKit configuration** | | ✅ | ✅ | Managed externally | +| Feature | `docker` | `docker-container` | `cloud` | `kubernetes` | `remote` | +| :--------------------------- | :---------: | :----------------: | :--------------: | :----------: | :----------------: | +| **Automatically load image** | ✅ | | Conditional | | | +| **Cache export** | ✅\* | ✅ | ✅ | ✅ | ✅ | +| **Tarball output** | | ✅ | ✅ | ✅ | ✅ | +| **Multi-arch images** | | ✅ | ✅ | ✅ | ✅ | +| **BuildKit configuration** | | ✅ | Managed by Docker | ✅ | Managed externally | \* _The `docker` driver doesn't support all cache export options. See [Cache storage backends](/manuals/build/cache/backends/_index.md) for more information._ ## Loading to local image store -Unlike when using the default `docker` driver, images built using other drivers -aren't automatically loaded into the local image store. If you don't specify an -output, the build result is exported to the build cache only. +The `docker` driver automatically loads images into the local image store. +With Docker Build Cloud, an untagged result remains in the cloud build cache +when you don't specify an output. Using `--tag` instead automatically loads the +image when the build targets a single platform and runs on one cloud node. With +other drivers, the build result remains in the build cache if you don't specify +an output. -To build an image using a non-default driver and load it to the image store, - use the `--load` flag with the build command: +To build an image using a driver that doesn't load results automatically, use +the `--load` flag with the build command: ```console $ docker buildx build --load -t <image> --builder=container . @@ -85,7 +89,8 @@ flag. Read about each driver: - - [Docker driver](./docker.md) - - [Docker container driver](./docker-container.md) - - [Kubernetes driver](./kubernetes.md) +- [Docker driver](./docker.md) +- [Docker container driver](./docker-container.md) +- [Cloud driver](./cloud.md) +- [Kubernetes driver](./kubernetes.md) - [Remote driver](./remote.md) diff --git a/content/manuals/build/builders/drivers/cloud.md b/content/manuals/build/builders/drivers/cloud.md new file mode 100644 index 000000000000..7d38fa300cd7 --- /dev/null +++ b/content/manuals/build/builders/drivers/cloud.md @@ -0,0 +1,30 @@ +--- +title: Cloud driver +description: The cloud driver connects Buildx to managed builders in Docker Build Cloud. +keywords: build, buildx, driver, builder, cloud, Docker Build Cloud +--- + +The Buildx cloud driver connects to managed BuildKit instances in Docker Build +Cloud. Docker provisions and maintains the builder infrastructure, shared build +cache, and native `linux/amd64` and `linux/arm64` nodes. + +The cloud driver requires Buildx version 0.37.0 or later and access to Docker +Build Cloud. + +## Synopsis + +Before connecting Buildx, create a cloud builder on the +[Docker Build Cloud Dashboard](https://app.docker.com/build/). Then sign in and +connect to the builder: + +```console +$ docker login +$ docker buildx create --driver cloud <ORG>/<BUILDER_NAME> +``` + +The command adds the cloud builder to your local Buildx configuration. It does +not create a builder in Docker Build Cloud. + +For service prerequisites and authentication, see +[Docker Build Cloud setup](/manuals/build-cloud/setup.md). For build examples, +see [Building with Docker Build Cloud](/manuals/build-cloud/usage.md). diff --git a/content/manuals/build/builders/drivers/kubernetes.md b/content/manuals/build/builders/drivers/kubernetes.md index 946e014fde81..df40917dece8 100644 --- a/content/manuals/build/builders/drivers/kubernetes.md +++ b/content/manuals/build/builders/drivers/kubernetes.md @@ -355,7 +355,7 @@ Prerequisites: specified namespace (in this case, `buildkit`), while keeping your driver configuration locally. -5. Use your new builder by including the `--builder` flag when running buildx +5. Use your new builder by including the `--builder` flag when running Buildx commands. For example: : ```console diff --git a/content/manuals/build/building/base-images.md b/content/manuals/build/building/base-images.md index 1a13a039bb29..85886a53839a 100644 --- a/content/manuals/build/building/base-images.md +++ b/content/manuals/build/building/base-images.md @@ -99,7 +99,9 @@ the distribution you'd like to package as a base image, though that is not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap), which you can also use to build Ubuntu images. -For example, to create an Ubuntu base image: +For example, to create an Ubuntu base image using the `noble` codename for +Ubuntu 24.04, run the following commands. Replace `noble` with the codename +for the Ubuntu release you want to import: ```dockerfile $ sudo debootstrap noble noble > /dev/null diff --git a/content/manuals/build/building/best-practices.md b/content/manuals/build/building/best-practices.md index 4e4bba5b5c09..73e3a1ab1bb7 100644 --- a/content/manuals/build/building/best-practices.md +++ b/content/manuals/build/building/best-practices.md @@ -114,9 +114,11 @@ $ docker build --no-cache -t my-image:my-tag . ``` This gets the latest available versions of dependencies from package -managers like `apt-get` or `npm`. However, `--no-cache` doesn't pull a -fresh base image - it only prevents reusing cached layers. For a -completely fresh build with the latest base image, combine both flags: +managers like `apt-get` or `npm`. It does not pull a fresh base image — +for that, use `--pull`. + +The two flags serve distinct purposes and can be combined. Use both +together to get a fresh base image and re-execute all build steps: ```console $ docker build --pull --no-cache -t my-image:my-tag . @@ -250,22 +252,22 @@ to look up and include the image digest for base image versions manually each time you want to update it. And you're opting out of automated security fixes, which is likely something you want to get. -Docker Scout's default [**Up-to-Date Base Images** -policy](../../scout/policy/_index.md#up-to-date-base-images) checks whether the +Docker Scout's default [**No outdated base images** +policy](../../scout/policy/_index.md#no-outdated-base-images) checks whether the base image version you're using is in fact the latest version. This policy also checks if pinned digests in your Dockerfile correspond to the correct version. If a publisher updates an image that you've pinned, the policy evaluation returns a non-compliant status, indicating that you should update your image. -Docker Scout also supports an automated remediation workflow for keeping your -base images up-to-date. When a new image digest is available, Docker Scout can -automatically raise a pull request on your repository to update your -Dockerfiles to use the latest version. This is better than using a tag that -changes the version automatically, because you're in control and you have an -audit trail of when and how the change occurred. +To keep your base images up-to-date automatically, use +[GitHub Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) +with `package-ecosystem: "docker"`. Dependabot raises pull requests to update +your base image tags and digests on a schedule. This is better than using a tag +that changes the version automatically, because you're in control and you have +an audit trail of when and how the change occurred. -For more information about automatically updating your base images with Docker -Scout, see [Remediation](/manuals/scout/policy/remediation.md). +You can also review available base image updates from the CLI with +[`docker scout recommendations`](/reference/cli/docker/scout/recommendations/). ## Build and test your images in CI @@ -729,7 +731,7 @@ CMD ["postgres"] This script lets you interact with Postgres in several ways. -It can simply start Postgres: +It can start Postgres: ```console $ docker run postgres diff --git a/content/manuals/build/building/registry-auth.md b/content/manuals/build/building/registry-auth.md new file mode 100644 index 000000000000..4a190540d73b --- /dev/null +++ b/content/manuals/build/building/registry-auth.md @@ -0,0 +1,67 @@ +--- +title: Registry authentication +description: Select registry credentials by repository and scope for builds +keywords: build, buildx, registry, authentication, credentials, login, scope +weight: 35 +--- + +Buildx uses Docker's credential configuration to authenticate when pulling +images for a build and pushing build results. Sign in to the registry before +building: + +```console +$ docker login registry.example.com +``` + +See the [`docker login` reference](/reference/cli/docker/login/) for credential +stores and authentication methods. + +## Select credentials by repository and scope + +Buildx can load separate Docker credential configurations for specific +registry repositories and token scopes. Use this when a build needs different +credentials for repositories on the same registry, or for pull and push +requests. + +Store each Docker `config.json` in a directory under +`$BUILDX_CONFIG/config/<registry>[/<repository>][@<scope>[,<scope>...]]`. +If `BUILDX_CONFIG` isn't set, use the +[config directory lookup order](./variables.md#buildx_config). Repository +paths must match the full repository name. Scopes are registry token actions, +such as `pull` and `push`. + +For example, the default config directory can contain: + +```text +~/.docker/buildx/config/ +└── registry.example.com/ + └── team/ + ├── app@pull/ + │ └── config.json + └── app@pull,push/ + └── config.json +``` + +Populate these files with Docker credential configurations. For example, use +the Docker CLI's `--config` flag to store credentials in the pull config +directory: + +```console +$ docker --config \ + ~/.docker/buildx/config/registry.example.com/team/app@pull \ + login registry.example.com +``` + +Use a different config directory and credentials for the combined `pull,push` +scope. Buildx prefers repository-specific matches over registry-wide matches, +then prefers the match with more scope actions. Every action in a config's +directory suffix must be present in the requested scope. + +If no alternative matches, Buildx uses the normal Docker credential config. +Alternative matching applies when authentication requests contain a single +repository scope; requests involving multiple repositories use the normal +config. + +This is a Buildx-specific compatibility mechanism. Docker commands don't +automatically select these configs by repository or scope. The `--config` +example only chooses where `docker login` stores credentials. diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 8d2c535c7cd0..e466e27c1db4 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -194,6 +194,13 @@ To authenticate the builder to GitHub, set the `GIT_AUTH_TOKEN` environment variable to contain a valid GitHub access token, and pass it as a secret to the build: +> [!NOTE] +> +> `GIT_AUTH_TOKEN` and `GIT_AUTH_HEADER` are not compatible with GitLab's +> `CI_JOB_TOKEN`. GitLab CI job tokens require Basic authentication with the +> username `gitlab-ci-token`, but BuildKit always uses `x-access-token` as the +> username for Basic auth. Use a Personal Access Token instead. + ```console $ GIT_AUTH_TOKEN=$(gh auth token) docker build \ --secret id=GIT_AUTH_TOKEN \ diff --git a/content/manuals/build/building/variables.md b/content/manuals/build/building/variables.md index db41b830f035..a106fc17c7a8 100644 --- a/content/manuals/build/building/variables.md +++ b/content/manuals/build/building/variables.md @@ -326,6 +326,7 @@ They're used to configure the Buildx client, or the BuildKit daemon. | [BUILDX_METADATA_PROVENANCE](#buildx_metadata_provenance) | String \| Boolean | Customize provenance information included in the metadata file. | | [BUILDX_METADATA_WARNINGS](#buildx_metadata_warnings) | String | Include build warnings in the metadata file. | | [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | +| [BUILDX_NO_DEFAULT_OCI_ARTIFACT](#buildx_no_default_oci_artifact) | Boolean | Turn off OCI artifact storage for attestations by default. | | [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | | [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | @@ -553,6 +554,9 @@ Usage: $ export BUILDX_CONFIG=/usr/local/etc ``` +For repository- and scope-specific credentials stored under this directory, +see [Registry authentication](./registry-auth.md). + ### BUILDX_CPU_PROFILE {{< summary-bar feature_name="Buildx CPU profile" >}} @@ -686,6 +690,22 @@ Usage: $ export BUILDX_NO_DEFAULT_ATTESTATIONS=1 ``` +### BUILDX_NO_DEFAULT_OCI_ARTIFACT + +{{< summary-bar feature_name="Buildx no default OCI artifact" >}} + +Starting with BuildKit v0.32.0, BuildKit stores attestations as OCI artifacts +when OCI media types are enabled. Set `BUILDX_NO_DEFAULT_OCI_ARTIFACT=1` to +make Buildx set `oci-artifact=false` when the build uses an exporter that +supports attestations and you haven't explicitly set the `oci-artifact` +exporter attribute. + +Usage: + +```console +$ export BUILDX_NO_DEFAULT_OCI_ARTIFACT=1 +``` + ### BUILDX_NO_DEFAULT_LOAD When you build an image using the `docker` driver, the image is automatically diff --git a/content/manuals/build/buildkit/configure.md b/content/manuals/build/buildkit/configure.md index 367a62fe1d9b..8f86a824ed92 100644 --- a/content/manuals/build/buildkit/configure.md +++ b/content/manuals/build/buildkit/configure.md @@ -161,7 +161,7 @@ For more control over networking, build a custom BuildKit image with your own CNI configuration and plugins. The following Dockerfile example shows a custom BuildKit image with CNI support. -It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json) +It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master/hack/fixtures/cni.json) in BuildKit as an example. Feel free to include your own CNI configuration. ```dockerfile diff --git a/content/manuals/build/cache/backends/gha.md b/content/manuals/build/cache/backends/gha.md index 81b239995988..f223fd6d670a 100644 --- a/content/manuals/build/cache/backends/gha.md +++ b/content/manuals/build/cache/backends/gha.md @@ -15,8 +15,9 @@ recommended cache to use inside your GitHub Actions workflows, as long as your use case falls within the [size and usage limits set by GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). -This cache storage backend is not supported with the default `docker` driver. -To use this feature, create a new builder using a different driver. See +This cache storage backend works with the default `docker` driver only when the +[containerd image store](/manuals/desktop/features/containerd.md) is enabled. If +the containerd image store isn't enabled, use a different driver. See [Build drivers](/manuals/build/builders/drivers/_index.md) for more information. ## Synopsis @@ -32,7 +33,7 @@ The following table describes the available CSV parameters that you can pass to | Name | Option | Type | Default | Description | |----------------|-------------------------|-------------|------------------------------------------------|----------------------------------------------------------------------| -| `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` or `$ACTIONS_RESULTS_URL` | Cache server URL, see [authentication][1]. Ignored when `version=2`. | +| `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` or `$ACTIONS_RESULTS_URL` | Cache server URL, see [authentication][1] and [version][4]. | | `url_v2` | `cache-to`,`cache-from` | String | `$ACTIONS_RESULTS_URL` | Cache v2 server URL, see [authentication][1]. | | `token` | `cache-to`,`cache-from` | String | `$ACTIONS_RUNTIME_TOKEN` | Access token, see [authentication][1]. | | `scope` | `cache-to`,`cache-from` | String | `buildkit` | Which scope cache object belongs to, see [scope][2] | @@ -41,7 +42,7 @@ The following table describes the available CSV parameters that you can pass to | `timeout` | `cache-to`,`cache-from` | String | `10m` | Max duration for importing or exporting cache before it's timed out. | | `repository` | `cache-to` | String | | GitHub repository used for cache storage. | | `ghtoken` | `cache-to` | String | | GitHub token required for accessing the GitHub API. | -| `version` | `cache-to`,`cache-from` | String | `1` unless `$ACTIONS_CACHE_SERVICE_V2` is set, then `2` | Selects GitHub Actions cache version, see [version][4] | +| `version` | `cache-to`,`cache-from` | String | Inferred from the cache server URL | Selects GitHub Actions cache version, see [version][4] | [1]: #authentication [2]: #scope @@ -80,14 +81,30 @@ GitHub's [cache access restrictions](https://docs.github.com/en/actions/advanced still apply. Only the cache for the current branch, the base branch and the default branch is accessible by a workflow. +Cache writes also depend on the workflow's cache access. Some events receive +read-only access in the default-branch context. See +[Cache write restrictions](../../ci/github-actions/cache.md#cache-write-restrictions) +for affected triggers and how to configure cache imports and exports. + ## Version -If you don’t set `version` explicitly, the default is v1. However, if the environment variable `$ACTIONS_CACHE_SERVICE_V2` is set to a value interpreted as `true` ( `1`, `true`, `yes`), then v2 is used automatically. +If you set `version` explicitly, BuildKit uses that version. Otherwise it +selects the version from the cache server URL: + +- Setting `url_v2` selects v2. +- Otherwise a `url` that points at the v2 cache service + (`results-receiver.actions.githubusercontent.com`) selects v2, and any other + `url` selects v1. -Only one URL is relevant at a time: +Inside a workflow, Buildx fills unspecified URL parameters from the +environment. It sets `url_v2` from `$ACTIONS_RESULTS_URL` when you pass +`version=2`, or when you omit `version` and `$ACTIONS_CACHE_SERVICE_V2` +holds a true value such as `1` or `true`. It sets `url` from +`$ACTIONS_CACHE_URL`, falling back to `$ACTIONS_RESULTS_URL` when +`$ACTIONS_CACHE_URL` isn't set. - - With v1, use `url` (defaults to `$ACTIONS_CACHE_URL`). - - With v2, use `url_v2` (defaults to `$ACTIONS_RESULTS_URL`). +Only one URL applies to a build. With v2, BuildKit uses `url_v2`, falling back +to `url` when `url_v2` isn't set. With v1, it uses `url`. ### Using `docker/build-push-action` diff --git a/content/manuals/build/cache/backends/local.md b/content/manuals/build/cache/backends/local.md index 69f32107c3d5..2533dd510eca 100644 --- a/content/manuals/build/cache/backends/local.md +++ b/content/manuals/build/cache/backends/local.md @@ -1,6 +1,6 @@ --- title: Local cache -description: Manage build cache with Amazon S3 buckets +description: Manage build cache with a local directory keywords: build, buildx, cache, backend, local aliases: - /build/building/cache/backends/local/ @@ -13,6 +13,11 @@ for the underlying directory structure. Local cache is a good choice if you're just testing, or if you want the flexibility to self-manage a shared storage solution. +This cache storage backend works with the default `docker` driver only when the +[containerd image store](/manuals/desktop/features/containerd.md) is enabled. If +the containerd image store isn't enabled, use a different driver. See +[Build drivers](/manuals/build/builders/drivers/_index.md) for more information. + ## Synopsis ```console @@ -28,6 +33,7 @@ The following table describes the available CSV parameters that you can pass to |---------------------|--------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------| | `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. | | `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. | +| `tag` | `cache-to`,`cache-from` | String | `latest` | Tag of the cache manifest, see [cache versioning][4]. | | `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | | `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. | | `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | @@ -36,6 +42,7 @@ The following table describes the available CSV parameters that you can pass to | `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | | `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. | | `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. | +| `reset` | `cache-to` | `true`,`false` | `false` | Delete blobs that no tag references, see [cache versioning][4]. | [1]: _index.md#cache-mode [2]: _index.md#oci-media-types @@ -47,49 +54,52 @@ build continues. ## Cache versioning -<!-- FIXME: update once https://github.com/moby/buildkit/pull/3111 is released --> +A local cache directory uses an OCI image layout. Its `index.json` file +associates tags with cache manifests, while the `blobs` directory stores the +manifest and cache data. + +By default, BuildKit exports and imports the cache tagged `latest`. Use +different tags to keep multiple caches in the same directory: + +```console +$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v1 . +$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v2 . +``` + +Exporting another cache with the same tag updates that tag to reference the new +manifest. Manifests referenced by other tags remain unchanged. -This section describes how versioning works for caches on a local filesystem, -and how you can use the `digest` parameter to use older versions of cache. +Import a cache by specifying its tag: -If you inspect the cache directory manually, you can see the resulting OCI image -layout: +```console +$ docker buildx build --cache-from type=local,src=path/to/local/dir,tag=v1 . +``` + +A digest identifies an exact cache manifest. BuildKit reports the digest of +each exported manifest in the build output. Use `digest` instead of `tag` when +you need a specific manifest: ```console -$ ls cache -blobs index.json ingest -$ cat cache/index.json | jq -{ - "schemaVersion": 2, - "manifests": [ - { - "mediaType": "application/vnd.oci.image.index.v1+json", - "digest": "sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707", - "size": 1560, - "annotations": { - "org.opencontainers.image.ref.name": "latest" - } - } - ] -} +$ docker buildx build \ + --cache-from type=local,src=path/to/local/dir,digest=sha256:<DIGEST> . ``` -Like other cache types, local cache gets replaced on export, by replacing the -contents of the `index.json` file. However, previous caches will still be -available in the `blobs` directory. These old caches are addressable by digest, -and kept indefinitely. Therefore, the size of the local cache will continue to -grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896) -for more information). +If you specify both `digest` and `tag`, BuildKit uses `digest`. -When importing cache using `--cache-from`, you can specify the `digest` parameter -to force loading an older version of the cache, for example: +By default, updating a tag doesn't delete the blobs used by its previous +manifest. The previous manifest remains available by digest, so the local cache +directory grows over time. + +Buildx version 0.35.0 and later supports `reset=true` on export, which deletes +blobs that no tag references: ```console -$ docker buildx build --push -t <registry>/<image> \ - --cache-to type=local,dest=path/to/local/dir \ - --cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707 . +$ docker buildx build --cache-to type=local,dest=path/to/local/dir,reset=true . ``` +Blobs that other tags reference are kept. Manifests that no tag references are +deleted, so you can no longer import them by digest. + ## Further reading For an introduction to caching see [Docker build cache](../_index.md). diff --git a/content/manuals/build/cache/backends/registry.md b/content/manuals/build/cache/backends/registry.md index ce9a7d4ee0e3..4aacff60b451 100644 --- a/content/manuals/build/cache/backends/registry.md +++ b/content/manuals/build/cache/backends/registry.md @@ -18,8 +18,9 @@ everything that the inline cache can do, and more: - It works with other exporters for more flexibility, instead of only the `image` exporter. -This cache storage backend is not supported with the default `docker` driver. -To use this feature, create a new builder using a different driver. See +This cache storage backend works with the default `docker` driver only when the +[containerd image store](/manuals/desktop/features/containerd.md) is enabled. If +the containerd image store isn't enabled, use a different driver. See [Build drivers](/manuals/build/builders/drivers/_index.md) for more information. ## Synopsis diff --git a/content/manuals/build/cache/garbage-collection.md b/content/manuals/build/cache/garbage-collection.md index 7609bab11a08..ba89259dc866 100644 --- a/content/manuals/build/cache/garbage-collection.md +++ b/content/manuals/build/cache/garbage-collection.md @@ -47,12 +47,13 @@ you have 11GB worth of build cache, where: - 7GB of which is "stale" cache - 4GB is other, more valuable cache -A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a -remainder of 6GB, meaning the 2nd policy does not need to clear any more cache. +A GC sweep would delete 2GB of stale cache as part of the 1st policy, leaving +9GB of cache in total, meaning the 2nd policy does not need to clear any more +cache. The default GC policies are (approximately): -1. Remove cache that can be easily regenerated, such as build contexts from +1. Remove cache that can be regenerated, such as build contexts from local directories or remote Git repositories, and cache mounts, if hasn't been used for more than 48 hours. 2. Remove cache that hasn't been used in a build for more than 60 days. @@ -171,7 +172,7 @@ following policies: > `==`: > > | `daemon.json` | `buildkitd.toml` | -> |---------------------|----------------------| +> | ------------------- | -------------------- | > | `type=source.local` | `type==source.local` | > | `private=true` | `private==true` | > | `shared=true` | `shared==true` | diff --git a/content/manuals/build/cache/optimize.md b/content/manuals/build/cache/optimize.md index 7f9fe9c0aba7..efc696738c69 100644 --- a/content/manuals/build/cache/optimize.md +++ b/content/manuals/build/cache/optimize.md @@ -262,11 +262,15 @@ RUN --mount=type=cache,target=/root/.gem \ ```dockerfile RUN --mount=type=cache,target=/app/target/ \ - --mount=type=cache,target=/usr/local/cargo/git/db \ - --mount=type=cache,target=/usr/local/cargo/registry/ \ - cargo build + --mount=type=cache,target=/var/cache/cargo \ + CARGO_HOME=/var/cache/cargo cargo build ``` +The cache mount uses a single `CARGO_HOME` so concurrent builds coordinate +access through Cargo's cache lock. Setting `CARGO_HOME` also changes where +Cargo looks for global configuration and credentials. Project-level +`.cargo/config.toml` files are unaffected. + {{< /tab >}} {{< tab name=".NET" >}} diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md index ff3ed02f07bb..4b30d2d175cc 100644 --- a/content/manuals/build/ci/github-actions/cache.md +++ b/content/manuals/build/ci/github-actions/cache.md @@ -1,5 +1,6 @@ --- title: Cache management with GitHub Actions +description: Configure build cache backends for GitHub Actions and handle cache write restrictions. linkTitle: Cache management keywords: ci, github actions, gha, buildkit, buildx, cache --- @@ -179,6 +180,41 @@ jobs: > } > ``` +### Cache write restrictions + +Cache export requires write access to the GitHub Actions cache. GitHub gives +events such as `issue_comment` and `pull_request_target` read-only cache access +by default when they run in the default-branch context. These workflows can +restore existing cache entries, but exporting with `cache-to: type=gha` can fail +with `error writing layer blob: failed to reserve cache`, even after the image +has been built and pushed. + +This also affects `pull_request` workflows with `types: [closed]` when a pull +request is merged into the default branch: the run uses the target branch ref +instead of the pull request merge ref. Regular `pull_request` runs using a +merge ref retain read-write cache access by default. See GitHub's +[cache access policy](https://github.blog/changelog/2026-06-26-read-only-actions-cache-for-untrusted-triggers/). + +For workflows with read-only cache access, keep `cache-from: type=gha` and omit +`cache-to`. Populate the cache from a workflow with write access, such as a +`push` workflow on the default branch. For builds after a merge, use `push` on +the target branch instead of `pull_request` with `types: [closed]`. + +GitHub's workflow or job-level +[`cache-mode` setting](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#cache-mode) +can override the default cache access. Granting write access to untrusted +workflows increases the risk of cache poisoning. + +If cache export is optional, you can make export failures non-fatal: + +```yaml +cache-from: type=gha +cache-to: type=gha,mode=max,ignore-error=true +``` + +`ignore-error=true` suppresses all cache export errors, not only access errors. +It doesn't grant write access or save the cache when writes are denied. + ### Cache mounts BuildKit doesn't preserve cache mounts in the GitHub Actions cache by default. @@ -273,11 +309,12 @@ For more information about this workaround, refer to the ### Local cache -> [!WARNING] +> [!NOTE] > -> At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252). -> The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896) -> for more info). +> Exporting to a directory that already holds a cache leaves the blobs of the +> previous export behind, so the directory grows with every run. The following +> example passes `reset=true` to delete them. This parameter requires Buildx +> version 0.35.0 or later. You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md) @@ -316,13 +353,5 @@ jobs: push: true tags: user/app:latest cache-from: type=local,src=${{ runner.temp }}/.buildx-cache - cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache-new,mode=max - - - # Temp fix - # https://github.com/docker/build-push-action/issues/252 - # https://github.com/moby/buildkit/issues/1896 - name: Move cache - run: | - rm -rf ${{ runner.temp }}/.buildx-cache - mv ${{ runner.temp }}/.buildx-cache-new ${{ runner.temp }}/.buildx-cache + cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache,mode=max,reset=true ``` diff --git a/content/manuals/build/ci/github-actions/configure-builder.md b/content/manuals/build/ci/github-actions/configure-builder.md index 9ba29245364d..65da9f0df77a 100644 --- a/content/manuals/build/ci/github-actions/configure-builder.md +++ b/content/manuals/build/ci/github-actions/configure-builder.md @@ -140,7 +140,7 @@ fields: | Name | Type | Description | | ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | String | [Name of the node](/reference/cli/docker/buildx/create/#node). If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of you workflow. | +| `name` | String | [Name of the node](/reference/cli/docker/buildx/create/#node). If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of your workflow. | | `endpoint` | String | [Docker context or endpoint](/reference/cli/docker/buildx/create/#description) of the node to add to the builder | | `driver-opts` | List | List of additional [driver-specific options](/reference/cli/docker/buildx/create/#driver-opt) | | `buildkitd-flags` | String | [Flags for buildkitd](/reference/cli/docker/buildx/create/#buildkitd-flags) daemon | diff --git a/content/manuals/build/ci/github-actions/share-image-jobs.md b/content/manuals/build/ci/github-actions/share-image-jobs.md index c6615ca7fa51..c88fb0436c37 100644 --- a/content/manuals/build/ci/github-actions/share-image-jobs.md +++ b/content/manuals/build/ci/github-actions/share-image-jobs.md @@ -13,6 +13,14 @@ in a workflow using the [actions/upload-artifact](https://github.com/actions/upl and [actions/download-artifact](https://github.com/actions/download-artifact) actions: +> [!NOTE] +> +> This workflow supports only single-platform images because the Docker exporter +> doesn't support manifest lists. For multi-platform images, push the image to a +> registry. If a later job rebuilds the image before pushing it, configure a +> [shared cache backend](cache.md) to reuse the earlier build results. See also +> [Multi-platform image with GitHub Actions](multi-platform.md). + ```yaml name: ci diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index dffebe9f398f..3623602b34b7 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -294,7 +294,7 @@ $ docker buildx build 'https://github.com/user/myrepo.git?tag=v0.1.0&commit=dead By default, BuildKit doesn't keep the `.git` directory when using Git contexts. You can configure BuildKit to keep the directory by setting the [`BUILDKIT_CONTEXT_KEEP_GIT_DIR` build argument](/reference/dockerfile.md#buildkit-built-in-build-args). -This can be useful to if you want to retrieve Git information during your build: +This can be useful if you want to retrieve Git information during your build: ```dockerfile # syntax=docker/dockerfile:1 @@ -341,8 +341,8 @@ $ GIT_AUTH_TOKEN=<token> docker buildx build \ ### Remote context with Dockerfile from stdin -Use the following syntax to build an image using files on your local -filesystem, while using a Dockerfile from stdin. +Use the following syntax to build an image using files from a remote URL, +while using a Dockerfile from stdin. ```console $ docker build -f- <URL> @@ -542,6 +542,7 @@ The following code snippet shows an example `.dockerignore` file. */*/temp* temp? ``` + <!-- vale off --> This file causes the following build behavior: diff --git a/content/manuals/build/exporters/_index.md b/content/manuals/build/exporters/_index.md index 57f465191adc..a2c3f8a517ad 100644 --- a/content/manuals/build/exporters/_index.md +++ b/content/manuals/build/exporters/_index.md @@ -80,6 +80,34 @@ Images loaded to the image store are available to `docker run` immediately after the build finishes, and you'll see them in the list of images when you run the `docker images` command. +#### Load results from Docker Build Cloud + +Builds that use the [cloud driver](/manuals/build/builders/drivers/cloud.md) run +on remote Docker Build Cloud workers. You can still load an image into Docker +Engine so that it's available to `docker run` and `docker images` without first +pushing it to a registry. + +The [target Docker context](/manuals/engine/manage-resources/contexts.md) +determines which Docker Engine image store receives the image. A local context +loads it into a local image store. A remote context loads it into the remote +Docker daemon's image store. + +When you don't specify an output, Buildx leaves an untagged build result in the +cloud build cache and doesn't load it into Docker Engine. If you use `--tag`, +Buildx automatically loads the image when the build targets a single platform +and runs on one cloud node. Use `--load` to request loading explicitly. The +`--load` flag is shorthand for `--output type=docker`. + +To leave a tagged result in the build cache, use `--output type=cacheonly`. +Setting `default-load=false` doesn't turn off automatic loading for a tagged +cloud build with no explicit output. + +Buildx uses the standard exporter path when direct loading isn't available. +This includes multi-node or multi-platform builds, requests for more than one +distinct image output, outputs targeting different Docker contexts, and +outputs written to a file, standard output, or a directory. The standard path +also applies if the target context doesn't support direct loading. + ### Push to registry To push a built image to a container registry, you can use the `registry` or @@ -195,7 +223,7 @@ different exporters: - The `registry` exporter to push the image to a registry - The `local` exporter to extract the build results to the local filesystem -- The `--load` flag (a shorthand for the `image` exporter) to load the results to the local image store. +- The `--load` flag (a shorthand for the `docker` exporter) to load the results to the local image store. ```console $ docker buildx build \ diff --git a/content/manuals/build/exporters/image-registry.md b/content/manuals/build/exporters/image-registry.md index 159be14265fa..12fa29bff9d1 100644 --- a/content/manuals/build/exporters/image-registry.md +++ b/content/manuals/build/exporters/image-registry.md @@ -26,7 +26,7 @@ The following table describes the available parameters that you can pass to | Parameter | Type | Default | Description | | ---------------------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | String | | Specify image name(s) | +| `name` | String | | Image name. To specify multiple names, use a comma-separated list. | | `push` | `true`,`false` | `false` | Push after creating the image. | | `push-by-digest` | `true`,`false` | `false` | Push image without name. | | `registry.insecure` | `true`,`false` | `false` | Allow pushing to insecure registry. | @@ -48,6 +48,17 @@ The following table describes the available parameters that you can pass to [4]: https://github.com/moby/buildkit/blob/master/docs/build-repro.md [5]: /manuals/build/metadata/attestations/_index.md#attestations-as-oci-artifacts +The `name` parameter is a CSV value inside the `--output` value. To specify +multiple image names, quote the complete `name` field: + +```console +$ docker buildx build \ + --output 'type=image,"name=registry.example.com/myapp:1.0,registry.example.com/myapp:latest",push=true' . +``` + +To assign multiple names with CLI flags instead, repeat the +[`--tag` flag](/reference/cli/docker/buildx/build/#tag). + ## Annotations These exporters support adding OCI annotation using `annotation` parameter, diff --git a/content/manuals/build/exporters/oci-docker.md b/content/manuals/build/exporters/oci-docker.md index b9d13be064d5..e93a0a119a76 100644 --- a/content/manuals/build/exporters/oci-docker.md +++ b/content/manuals/build/exporters/oci-docker.md @@ -30,16 +30,16 @@ $ docker buildx build --output type=docker[,parameters] . The following table describes the available parameters: -| Parameter | Type | Default | Description | -| ------------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | String | | Specify image name(s) | -| `dest` | String | | Path | -| `tar` | `true`,`false` | `true` | Bundle the output into a tarball layout | -| `compression` | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [compression][1] | -| `compression-level` | `0..22` | | Compression level, see [compression][1] | -| `force-compression` | `true`,`false` | `false` | Forcefully apply compression, see [compression][1] | -| `oci-mediatypes` | `true`,`false` | | Use OCI media types in exporter manifests. Defaults to `true` for `type=oci`, and `false` for `type=docker`. See [OCI Media types][2] | -| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][3] | +| Parameter | Type | Default | Description | +| ------------------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | | Specify image name(s) | +| `dest` | String | | Path | +| `tar` | `true`,`false` | `true` | Bundle the output into a tarball layout | +| `compression` | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [compression][1] | +| `compression-level` | `0..22` | | Compression level, see [compression][1] | +| `force-compression` | `true`,`false` | `false` | Forcefully apply compression, see [compression][1] | +| `oci-mediatypes` | `true`,`false` | | Use OCI media types in exporter manifests. Defaults to `true` for `type=oci`, and `false` for `type=docker`. See [OCI Media types][2] | +| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image, see [annotations][3] | | `rewrite-timestamp` | `true`,`false` | `false` | Rewrite the file timestamps to the `SOURCE_DATE_EPOCH` value. See [build reproducibility][4] for how to specify the `SOURCE_DATE_EPOCH` value. | [1]: _index.md#compression diff --git a/content/manuals/build/images/set-default-builder-gui.webp b/content/manuals/build/images/set-default-builder-gui.webp deleted file mode 100644 index 138fdc4f1f5d..000000000000 Binary files a/content/manuals/build/images/set-default-builder-gui.webp and /dev/null differ diff --git a/content/manuals/build/metadata/annotations.md b/content/manuals/build/metadata/annotations.md index ee1f44a488f0..29683438d5c8 100644 --- a/content/manuals/build/metadata/annotations.md +++ b/content/manuals/build/metadata/annotations.md @@ -67,15 +67,16 @@ target "default" { For examples on how to add annotations to images built with GitHub Actions, see [Add image annotations with GitHub Actions](/manuals/build/ci/github-actions/annotations.md) -You can also add annotations to an image created using `docker buildx -imagetools create`. This command only supports adding annotations to an index +You can also add annotations to an image created using +`docker buildx imagetools create`. This command only supports adding annotations to an index or manifest descriptors, see [CLI reference](/reference/cli/docker/buildx/imagetools/create/#annotation). ## Inspect annotations -To view annotations on an **image index**, use the `docker buildx imagetools -inspect` command. This shows you any annotations for the index and descriptors +To view annotations on an **image index**, use the +`docker buildx imagetools inspect` command. This shows you any annotations for +the index and descriptors (references to manifests) that the index contains. The following example shows an `org.opencontainers.image.documentation` annotation on a descriptor, and an `org.opencontainers.image.authors` annotation on the index. @@ -105,8 +106,9 @@ $ docker buildx imagetools inspect <IMAGE> --raw } ``` -To inspect annotations on a manifest, use the `docker buildx imagetools -inspect` command and specify `<IMAGE>@<DIGEST>`, where `<DIGEST>` is the digest +To inspect annotations on a manifest, use the +`docker buildx imagetools inspect` command and specify `<IMAGE>@<DIGEST>`, +where `<DIGEST>` is the digest of the manifest: ```console {hl_lines="22-25"} @@ -170,7 +172,7 @@ exporter does not produce an index: $ docker build --output type=docker --annotation "index:foo=bar" . ``` -Likewise, the following example also does not work, because buildx creates a +Likewise, the following example also does not work, because Buildx creates a `docker` output by default under some circumstances, such as when provenance attestations are explicitly disabled: diff --git a/content/manuals/build/metadata/attestations/_index.md b/content/manuals/build/metadata/attestations/_index.md index 2d7959f3543f..7190094ad88e 100644 --- a/content/manuals/build/metadata/attestations/_index.md +++ b/content/manuals/build/metadata/attestations/_index.md @@ -65,6 +65,39 @@ You can also disable default provenance attestations by setting the environment variable. See [Provenance attestation](./slsa-provenance.md) for more details about provenance modes and options. +### Driver and image store support + +Attestations attach to an image index. The classic image store doesn't support +image indices, so it can't hold an image with attestations. + +The default `docker` driver builds with the BuildKit library bundled into the +Docker daemon, and writes the result to the daemon's image store. If the daemon +still uses the classic image store, the build fails: + +```text +ERROR: failed to build: Attestation is not supported for the docker driver. +Switch to a different driver, or turn on the containerd image store, and try again. +``` + +To build attestations with the `docker` driver, turn on the containerd image +store. See [containerd image store with Docker Desktop](/manuals/desktop/features/containerd.md) +or [containerd image store with Docker Engine](/manuals/engine/storage/containerd.md). + +| Driver | Attestation support | +| :------------------------ | :---------------------------------- | +| `docker` | Requires the containerd image store | +| `docker-container` | Supported | +| `kubernetes` and `remote` | Supported | + +The `docker-container`, `kubernetes`, and `remote` drivers run BuildKit outside +the Docker daemon, so they build attestations regardless of which image store +the daemon uses. Pushing the result to a registry with `--push` keeps the +attestations. If you load the result into the daemon with `--load` instead, the +same image store requirement applies. + +If you don't want to switch image stores or drivers, opt out of attestations +with `--provenance=false --sbom=false`. + ## Storage BuildKit produces attestations in the [in-toto format](https://github.com/in-toto/attestation), diff --git a/content/manuals/build/metadata/attestations/sbom.md b/content/manuals/build/metadata/attestations/sbom.md index ee34dc895665..04acd698bd87 100644 --- a/content/manuals/build/metadata/attestations/sbom.md +++ b/content/manuals/build/metadata/attestations/sbom.md @@ -7,7 +7,7 @@ aliases: - /build/attestations/sbom/ --- -SBOM attestations help ensure [software supply chain transparency](/guides/docker-scout/s3c.md) by verifying the software artifacts an image contains and the artifacts used to create the image. Metadata included in an [SBOM](/guides/docker-scout/sbom.md) for describing software artifacts may include: +SBOM attestations help ensure [software supply chain transparency](/manuals/build/metadata/attestations/_index.md) by verifying the software artifacts an image contains and the artifacts used to create the image. Metadata included in an [SBOM](/manuals/scout/how-tos/view-create-sboms.md) for describing software artifacts may include: - Name of the artifact - Version diff --git a/content/manuals/build/policies/inputs.md b/content/manuals/build/policies/inputs.md index 43aad88629c5..096f486e3039 100644 --- a/content/manuals/build/policies/inputs.md +++ b/content/manuals/build/policies/inputs.md @@ -19,6 +19,7 @@ Build inputs correspond to Dockerfile instructions: | `FROM alpine:latest` | Image | `input.image` | | `COPY --from=builder /app /app` | Image | `input.image` | | `ADD https://example.com/file.tar.gz /` | HTTP | `input.http` | +| `RUN curl https://example.com/` | HTTP | `input.http` | | `ADD git@github.com:user/repo.git /src` | Git | `input.git` | | Build context (`.`) | Local | `input.local` | @@ -27,7 +28,8 @@ Each input type has specific fields available for policy evaluation. ## HTTP inputs HTTP inputs represent files downloaded over HTTP or HTTPS using the `ADD` -instruction. +instruction, or requests from `RUN` instructions when BuildKit's proxy is +enabled. See [Block URLs in build steps](./usage.md#block-urls-in-build-steps). ### Example Dockerfile diff --git a/content/manuals/build/policies/usage.md b/content/manuals/build/policies/usage.md index c7ba7561611b..fae96064f881 100644 --- a/content/manuals/build/policies/usage.md +++ b/content/manuals/build/policies/usage.md @@ -6,9 +6,9 @@ keywords: build policies, policy eval, docker buildx, policy development, debugg weight: 20 --- -Build policies validate inputs before builds execute. This guide covers how to -develop policies iteratively and apply them to real builds with `docker buildx -build` and `docker buildx bake`. +Build policies validate build inputs and can check HTTP(S) requests during build +steps. This guide covers how to develop policies iteratively and apply them to +builds with `docker buildx build` and `docker buildx bake`. ## Prerequisites @@ -223,6 +223,74 @@ Use only your specified policy: $ docker buildx build --policy reset=true,filename=strict.rego . ``` +## Block URLs in build steps + +To check HTTP(S) requests from `RUN` instructions, add +`"caps": {"exec.proxy": true}` to the policy's `decision` object. This enables +BuildKit's proxy, which checks requests against your `input.http` rules. +By default, these rules only apply to `ADD` downloads. + +Save this policy as `Dockerfile.rego` alongside your Dockerfile to allow Debian +package downloads and block requests to other hosts: + +```rego {title="Dockerfile.rego"} +package docker + +default allow := false + +allow if input.local + +allow if { + input.image.repo == "debian" +} + +allow if { + input.http.host == "deb.debian.org" +} + +decision := { + "allow": allow, + "caps": {"exec.proxy": true}, +} +``` + +Test it with this Dockerfile: + +```dockerfile {title="Dockerfile"} +FROM debian:trixie +RUN apt-get update && apt-get install -y curl +RUN curl -f http://example.com/ +``` + +```console +$ docker buildx build --no-cache --progress=plain . +``` + +The package downloads from `deb.debian.org` succeed. The proxy denies the request +to `example.com` with HTTP 403, and `curl -f` fails the build. Use `--no-cache` +when testing to run the steps again. + +To restrict individual URLs, use `input.http.url` or match both `input.http.host` +and `input.http.path`. See the [HTTP input reference](./inputs.md#http-inputs). + +The proxy supports Linux build steps. Applications must use the injected proxy +environment variables and trust BuildKit's certificate for HTTPS. BuildKit adds +the certificate to the system trust store. Traffic that bypasses the proxy is +blocked. + +### Enable the proxy for a CI builder + +For a dedicated CI builder, enable the proxy for all builds with +`--buildkitd-flags '--proxy-network'`: + +```console +$ docker buildx create --name ci-policy --driver docker-container \ + --buildkitd-flags '--proxy-network' --use --bootstrap +``` + +This replaces the `exec.proxy` opt-in in each policy file. You still need a +policy to restrict URLs. + ## Using policies with bake [Bake](/build/bake/) supports automatic policy loading just like `docker buildx @@ -285,8 +353,26 @@ $ docker buildx bake production # Uses strict policies ### Bake with policy options -Currently, bake doesn't support policy options (reset, strict, disabled) in the -HCL file. Use command-line flags instead: +Use objects in the `policy` list to configure policy loading and evaluation +for a target. Each object supports `filename`, `reset`, `disabled`, `strict`, +and `log-level`, with the same meanings as the +[`docker buildx build --policy` options](#manual-policy-configuration). + +For example, load only the specified policy and require policy support from +the builder: + +```hcl {title="docker-bake.hcl"} +target "production" { + policy = [{ + filename = "policies/production.rego" + reset = true + strict = true + }] +} +``` + +Use `disabled = true` to disable policy evaluation for a target. For a +per-invocation override across the selected targets, use the `--policy` flag: ```console $ docker buildx bake --policy disabled=true production @@ -353,7 +439,7 @@ Buildx detects `Dockerfile.rego` and evaluates it before running the build. ### When policies don't load -If buildx can't find a matching `.rego` file, the build proceeds without policy +If Buildx can't find a matching `.rego` file, the build proceeds without policy evaluation. To require policies and fail if none are found, use strict mode: ```console @@ -444,14 +530,14 @@ fetch specific metadata (see [above](#testing-policies-with-policy-eval)). #### Test with specific policy files -The `--filename` flag specifies which policy file to load by providing the base +The `--file` flag (`-f`) specifies which policy file to load by providing the base Dockerfile name (without the `.rego` extension). This is useful for testing sources against policies associated with different Dockerfiles. For example, to test a source against the policy for `app.Dockerfile`: ```console -$ docker buildx policy eval --filename app.Dockerfile . +$ docker buildx policy eval --file app.Dockerfile . ``` This loads `app.Dockerfile.rego` and tests whether it allows the source `.` @@ -460,8 +546,30 @@ This loads `app.Dockerfile.rego` and tests whether it allows the source `.` Test different sources against your policy: ```console -$ docker buildx policy eval --filename app.Dockerfile https://github.com/org/repo.git -$ docker buildx policy eval --filename app.Dockerfile docker-image://alpine:3.19 +$ docker buildx policy eval --file app.Dockerfile \ + https://github.com/org/repo.git +$ docker buildx policy eval --file app.Dockerfile docker-image://alpine:3.19 +``` + +To read the policy from standard input instead, use `--file -`. Buildx reads +the policy directly, without appending `.rego` to the filename: + +```console +$ cat app.Dockerfile.rego | docker buildx policy eval --file - \ + docker-image://alpine:3.19 +``` + +#### Evaluate a specific platform + +Use `--platform` to choose the platform whose image metadata the policy +evaluates. Without it, Buildx uses the first platform of the builder's first +worker. + +```console +$ docker buildx policy eval --platform linux/arm64 \ + docker-image://alpine:3.19 +$ docker buildx policy eval --platform linux/arm64 --print \ + --fields image.labels docker-image://alpine:3.19 ``` ### Reset automatic loading diff --git a/content/manuals/compose/bridge/use-model-runner.md b/content/manuals/compose/bridge/use-model-runner.md index 1f976c8b4aef..7e3cb7923d18 100644 --- a/content/manuals/compose/bridge/use-model-runner.md +++ b/content/manuals/compose/bridge/use-model-runner.md @@ -85,7 +85,7 @@ When `modelRunner.enabled` is `true`, Compose Bridge uses the generated manifest - Service: Exposes port `80` (maps to container port `12434`) - `PersistentVolumeClaim`: Stores model files -The `modelRunner.enabled` setting also determines the number of replicas for the `model-runner-deployment`: +The `modelRunner.enabled` setting also determines the number of replicas for the in-cluster `model-runner-deployment`: -- When `true`, the deployment replica count is set to 1, and Docker Model Runner is deployed in the Kubernetes cluster. -- When `false`, the replica count is 0, and no Docker Model Runner resources are deployed. \ No newline at end of file +- When `true`, the Kubernetes deployment replica count is set to 1, and Docker Model Runner is deployed in the cluster. +- When `false`, the Kubernetes deployment replica count is 0 (no in-cluster Model Runner). On Docker Desktop, workloads still connect to the host Model Runner as described above. \ No newline at end of file diff --git a/content/manuals/compose/compose-sdk.md b/content/manuals/compose/compose-sdk.md index 09ac2335ad32..b2616a88b5db 100644 --- a/content/manuals/compose/compose-sdk.md +++ b/content/manuals/compose/compose-sdk.md @@ -4,11 +4,6 @@ keywords: docker compose sdk, compose api, Docker developer SDK title: Using the Compose SDK linkTitle: Compose SDK weight: 60 -params: - sidebar: - badge: - color: green - text: New --- {{< summary-bar feature_name="Compose SDK" >}} diff --git a/content/manuals/compose/gettingstarted.md b/content/manuals/compose/gettingstarted.md index ab1d4b15bb45..e1c1a0ad2fbc 100644 --- a/content/manuals/compose/gettingstarted.md +++ b/content/manuals/compose/gettingstarted.md @@ -64,16 +64,33 @@ Make sure you have: ```dockerfile # syntax=docker/dockerfile:1 - FROM python:3.12-alpine # Builds an image with the Python 3.12 image - WORKDIR /code # Sets the working directory to `/code` - ENV FLASK_APP=app.py # Sets environment variables used by the `flask` command + + # Build an image with the Python 3.12 image + FROM python:3.12-alpine + + # Set the working directory to `/code` + WORKDIR /code + + # Set environment variables used by the `flask` command + ENV FLASK_APP=app.py ENV FLASK_RUN_HOST=0.0.0.0 - RUN apk add --no-cache gcc musl-dev linux-headers # Installs `gcc` and other dependencies - COPY requirements.txt . # Copies `requirements.txt` - RUN pip install -r requirements.txt # Installs the Python dependencies - COPY . . # Copies the current directory `.` in the project to the workdir `.` in the image + + # Install `gcc` and other dependencies + RUN apk add --no-cache gcc musl-dev linux-headers + + # Copy `requirements.txt` + COPY requirements.txt . + + # Install the Python dependencies + RUN pip install -r requirements.txt + + # Copy the current directory `.` in the project to the workdir `.` in the image + COPY . . + EXPOSE 5000 - CMD ["flask", "run", "--debug"] # Sets the default command for the container to `flask run --debug` + + # Set the default command for the container to `flask run --debug` + CMD ["flask", "run", "--debug"] ``` > [!IMPORTANT] @@ -372,7 +389,7 @@ you want to reuse infrastructure definitions across projects. 1. Create a new file in your project directory called `infra.yaml` and move the Redis service and volume into it: ```yaml - services: + services: redis: image: redis:alpine volumes: diff --git a/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md b/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md index de6b7a558dfd..223c11ead25a 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md @@ -21,6 +21,15 @@ The order of precedence (highest to lowest) is as follows: 5. Set in a container image in the [ENV directive](/reference/dockerfile.md#env). Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is no Docker Compose entry for `environment`, `env_file` or `run --env`. +> [!NOTE] +> +> When `--env-file` is not set, Compose may load up to two `.env` files. +> It first loads one from the project directory (determined by `--project-directory` +> if set, otherwise the directory of the first `-f`/`--file` Compose file, otherwise +> `PWD`). If that file sets `COMPOSE_FILE` to a path in a different directory, Compose +> loads a second `.env` file from that directory with lower precedence. For more +> information, see [local `.env` file versus project directory `.env` file](variable-interpolation.md#local-env-file-versus-project-directory-env-file). + ## Simple example In the following example, a different value for the same environment variable in an `.env` file and with the `environment` attribute in the Compose file: diff --git a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md index 74140869546f..d53479a8d511 100644 --- a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md +++ b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md @@ -64,8 +64,12 @@ Docker Compose can interpolate variables into your Compose file from multiple so Note that when the same variable is declared by multiple sources, precedence applies: 1. Variables from your shell environment -2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`) -3. Variables from a file set by `--env-file` or an `.env` file in project directory +2. Variables from a file set by `--env-file` +3. If `--env-file` is not set, variables from an `.env` file in the project directory, + where the project directory is: + - `--project-directory` if set + - otherwise, the directory of the first Compose file specified with `-f`/`--file` + - otherwise, your shell's current directory (`PWD`) You can check variables and values used by Compose to interpolate the Compose model by running `docker compose config --environment`. @@ -110,7 +114,7 @@ services: > [!IMPORTANT] > - > Be aware of [Environment variables precedence](envvars-precedence.md) when using variables in an `.env` file that as environment variables in your container's environment. + > Be aware of [Environment variables precedence](envvars-precedence.md) when using variables in an `.env` file that are also used as environment variables in your container's environment. - You can place your `.env` file in a location other than the root of your project's directory, and then use the [`--env-file` option in the CLI](#substitute-with---env-file) so Compose can navigate to it. @@ -226,9 +230,13 @@ $ docker compose --env-file ./config/.env.dev up An `.env` file can also be used to declare [pre-defined environment variables](envvars.md) used to control Compose behavior and files to be loaded. -When executed without an explicit `--env-file` flag, Compose searches for an `.env` file in your working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and loads values -both for self-configuration and interpolation. If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results in a project directory being set to another folder, -Compose will load a second `.env` file, if present. This second `.env` file has a lower precedence. +When executed without an explicit `--env-file` flag, Compose searches for an `.env` file +in the project directory and loads values both for self-configuration and interpolation. +The project directory is determined by `--project-directory` if set, otherwise by the +directory of the first Compose file specified with `-f`/`--file`, otherwise `PWD`. +If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results +in a project directory being set to another folder, Compose loads a second `.env` file, +if present. This second `.env` file has a lower precedence. This mechanism makes it possible to invoke an existing Compose project with a custom set of variables as overrides, without the need to pass environment variables by the command line. diff --git a/content/manuals/compose/how-tos/file-watch.md b/content/manuals/compose/how-tos/file-watch.md index 624df4f87676..35e6ccb2f80b 100644 --- a/content/manuals/compose/how-tos/file-watch.md +++ b/content/manuals/compose/how-tos/file-watch.md @@ -91,6 +91,10 @@ The behavior is the same as running `docker compose up --build <svc>`. Rebuild is ideal for compiled languages or as a fallback for modifications to particular files that require a full image rebuild (e.g. `package.json`). +> [!NOTE] +> +> When a service is rebuilt, the previous image version becomes dangling. By default, Compose removes these superseded dangling images after each rebuild to avoid accumulating unused layers. To keep them, use `docker compose watch --prune=false`. + #### Sync + Restart If `action` is set to `sync+restart`, Compose synchronizes your changes with the service containers and restarts them. diff --git a/content/manuals/compose/how-tos/init-containers.md b/content/manuals/compose/how-tos/init-containers.md new file mode 100644 index 000000000000..bbc034cbfd29 --- /dev/null +++ b/content/manuals/compose/how-tos/init-containers.md @@ -0,0 +1,173 @@ +--- +title: Use init containers in Compose +linkTitle: Use init containers +weight: 120 +description: Use pre_start init containers to run setup tasks before a service starts in Docker Compose. +keywords: docker compose init containers, pre_start, docker compose migrations, volume permissions, docker compose lifecycle +params: + sidebar: + badge: + color: green + text: New +--- + +{{< summary-bar feature_name="Compose pre_start" >}} + +Init containers are short-lived containers that run before a service's main container starts. They execute sequentially, each running to completion before the next begins. If any step exits with a non-zero code, the service will not start. + +Use them for setup work that must finish before the application boots: running database migrations, fixing volume permissions, generating dynamic configuration, or executing any ordered sequence of prerequisites. + +Compose models init containers as [`pre_start`](/reference/compose-file/services.md#pre_start) lifecycle hooks. Unlike [`post_start`](/reference/compose-file/services.md#post_start) and [`pre_stop`](/reference/compose-file/services.md#pre_stop), which run a command inside the running service container, each `pre_start` step runs in its own ephemeral container created after the service container is created but before it is started. + +## When not to use init containers + +For static files and secrets, use the native [`configs`](/reference/compose-file/configs.md) and [`secrets`](/reference/compose-file/secrets.md) top-level elements instead. Compose mounts them directly into containers with a configurable target path, mode, UID, and GID. No init container required. + +For background tasks with their own lifecycle - scheduled backups, post-exit cleanup, periodic maintenance — init containers are the wrong tool. Those tasks run independently of service startup, not before it. + +## How `pre_start` containers run + +Each step in a service's `pre_start` list: + +- Runs in its own ephemeral container, created after the service container is created but before it starts. +- Inherits the service's image by default. Set `image` to override. The hook image follows the parent service's `pull_policy`, including refresh interval (`daily`, `weekly`, `every_<duration>`). This applies when starting services and when running `docker compose pull`. +- Joins the same networks as the service, so it can reach services declared in [`depends_on`](/reference/compose-file/services.md#depends_on). +- Shares the service's volume mounts, so files written to a shared volume are immediately visible to the service. +- Must exit `0` for the next step, and the service itself, to start. A non-zero exit aborts startup for the service and anything that depends on it. + +A `pre_start` step is skipped on subsequent `docker compose up` runs if it previously succeeded, its definition hasn't changed, or when the service container restarts under its `restart` policy. It reruns if the definition changes, the previous run failed, or the service is recreated with `--force-recreate`. + +## Examples + +### Run a database migration before the app starts + +In the following example, `app` waits for `db` to be healthy, then runs +`./manage.py migrate` in an ephemeral container that reuses the app's +image. The service container only starts once the migration exits `0`. + +```yaml +services: + app: + image: myapp:latest + depends_on: + db: + condition: service_healthy + pre_start: + - command: ["./manage.py", "migrate"] + + db: + image: postgres:18 + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] + interval: 10s + retries: 5 + start_period: 30s + timeout: 10s +``` + +If the migration fails, `app` does not start and the failure is reported in +the `docker compose up` output. + +### Fix volume ownership before a non-root service starts + +Named volumes are created with root ownership. When the service runs as a +non-root user, you can use a `pre_start` step to adjust ownership before +the service mounts the volume. + +```yaml +services: + app: + image: myapp:latest + user: "1000:1000" + volumes: + - data:/data + pre_start: + - image: busybox + user: root + command: sh -c 'chown -R 1000:1000 /data' + +volumes: + data: +``` + +The `pre_start` step uses a different image (`busybox`) and runs as `root`, +even though the service itself runs as user `1000`. + +### Chain multiple setup steps + +`pre_start` steps run in declared order. The next step only starts once the +previous one exits `0`. In the following example, the application waits +for migrations to finish, then for seed data to load, before starting. + +```yaml +services: + app: + image: myapp:latest + depends_on: + db: + condition: service_healthy + pre_start: + - command: ["./manage.py", "migrate"] + - command: ["./manage.py", "loaddata", "fixtures.json"] + + db: + image: postgres:18 +``` + +Each step runs in its own ephemeral container. If the second step fails, +the first step is not rolled back, but `app` does not start. + +### Replace the one-shot service pattern + +Before `pre_start`, the common way to express "run X before Y starts" was +to model the setup work as a service with `restart: "no"` and have the main +service `depends_on` it with `condition: service_completed_successfully`: + +```yaml +services: + migrate: + image: myapp:latest + command: ["./manage.py", "migrate"] + restart: "no" + + app: + image: myapp:latest + depends_on: + migrate: + condition: service_completed_successfully +``` + +The equivalent expressed with `pre_start`: + +```yaml +services: + app: + image: myapp:latest + pre_start: + - command: ["./manage.py", "migrate"] +``` + +`pre_start` is preferable because: + +- The setup work is modeled as a subordinate step of the service, not as a peer service that exits immediately. +- Completed steps do not appear as exited services in `docker compose ps`. +- Chaining several setup steps does not require a web of `depends_on` edges between one-shot services. +- The ephemeral container inherits the service's image by default, so no duplicate `image:` declaration is needed. + +The one-shot service pattern still has its place when the setup work is a shared concern that multiple services depend on, or when it needs to be addressable independently of any single service. + +## Limitations + +- `pre_start` runs once for the service as a whole, not once per replica (`per_replica: false`). Per-replica execution (`per_replica: true`) is not yet supported. +- Volume mounts shared across replicas (named volumes, bind mounts) are accessible from a `pre_start` step. Per-instance mounts such as `tmpfs` + or anonymous volumes cannot be addressed by a single shared run. +- `pre_start` does not re-trigger when you scale a service up. A step runs again only on definition change, prior failure, or `--force-recreate`. + +## Reference and additional information + +- [`pre_start`](/reference/compose-file/services.md#pre_start) +- [`post_start`](/reference/compose-file/services.md#post_start) +- [`pre_stop`](/reference/compose-file/services.md#pre_stop) +- [`depends_on`](/reference/compose-file/services.md#depends_on) +- [Use lifecycle hooks](/manuals/compose/how-tos/lifecycle.md) +- [Control startup order](/manuals/compose/how-tos/startup-order.md) diff --git a/content/manuals/compose/how-tos/lifecycle.md b/content/manuals/compose/how-tos/lifecycle.md index a5924ae3cfc3..65f1ebd992b3 100644 --- a/content/manuals/compose/how-tos/lifecycle.md +++ b/content/manuals/compose/how-tos/lifecycle.md @@ -1,9 +1,9 @@ --- title: Using lifecycle hooks with Compose linkTitle: Use lifecycle hooks -weight: 20 -description: Learn how to use Docker Compose lifecycle hooks like post_start and pre_stop to customize container behavior. -keywords: docker compose lifecycle hooks, post_start, pre_stop, docker compose entrypoint, docker container stop hooks, compose hook commands +weight: 110 +description: Learn how to use Docker Compose lifecycle hooks like pre_start, post_start, and pre_stop to customize container behavior. +keywords: docker compose lifecycle hooks, post_start, pre_stop, pre_start, docker compose entrypoint, docker container stop hooks, compose hook commands --- {{< summary-bar feature_name="Compose lifecycle hooks" >}} diff --git a/content/manuals/ai/compose/models-and-compose.md b/content/manuals/compose/how-tos/models-and-compose.md similarity index 99% rename from content/manuals/ai/compose/models-and-compose.md rename to content/manuals/compose/how-tos/models-and-compose.md index aa5502f6f8a7..55bea46e3709 100644 --- a/content/manuals/ai/compose/models-and-compose.md +++ b/content/manuals/compose/how-tos/models-and-compose.md @@ -1,9 +1,10 @@ --- +url: /ai/compose/models-and-compose/ title: Define AI Models in Docker Compose applications linkTitle: Use AI models in Compose description: Learn how to define and use AI models in Docker Compose applications using the models top-level element keywords: compose, docker compose, models, ai, machine learning, cloud providers, specification -weight: 10 +weight: 25 --- {{< summary-bar feature_name="Compose models" >}} diff --git a/content/manuals/compose/how-tos/multiple-compose-files/_index.md b/content/manuals/compose/how-tos/multiple-compose-files/_index.md index d7e9dc78a0da..d0520f3104b3 100644 --- a/content/manuals/compose/how-tos/multiple-compose-files/_index.md +++ b/content/manuals/compose/how-tos/multiple-compose-files/_index.md @@ -13,7 +13,10 @@ This section contains information on the ways you can work with multiple Compose Using multiple Compose files lets you customize a Compose application for different environments or workflows. This is useful for large applications that may use dozens of containers, with ownership distributed across multiple teams. For example, if your organization or team uses a monorepo, each team may have their own “local” Compose file to run a subset of the application. They then need to rely on other teams to provide a reference Compose file that defines the expected way to run their own subset. Complexity moves from the code in to the infrastructure and the configuration file. -The quickest way to work with multiple Compose files is to [merge](merge.md) Compose files using the `-f` flag in the command line to list out your desired Compose files. However, [merging rules](merge.md#merging-rules) means this can soon get quite complicated. +The simplest way to work with multiple Compose files is to [merge](merge.md) them using +the `-f` flag. This works well for straightforward overrides, but the +[merging rules](merge.md#merging-rules) can make it complex to manage as your +configuration grows. Docker Compose provides two other options to manage this complexity when working with multiple Compose files. Depending on your project's needs, you can: diff --git a/content/manuals/compose/how-tos/multiple-compose-files/merge.md b/content/manuals/compose/how-tos/multiple-compose-files/merge.md index 49f32136d2a5..ebadca7c40a7 100644 --- a/content/manuals/compose/how-tos/multiple-compose-files/merge.md +++ b/content/manuals/compose/how-tos/multiple-compose-files/merge.md @@ -356,8 +356,22 @@ For more information, see [Using Compose in production](../production.md). ## Limitations -Docker Compose supports relative paths for the many resources to be included in the application model: build context for service images, location of file defining environment variables, path to a local directory used in a bind-mounted volume. -With such a constraint, code organization in a monorepo can become hard as a natural choice would be to have dedicated folders per team or component, but then the Compose files relative paths become irrelevant. +When merging Compose files, all relative paths (for build contexts, environment files, +bind-mounted volumes, and other resources) are resolved relative to the base Compose file. The +first file specified with `-f`, or `compose.yaml` in the current directory if `-f` is +not used. Paths in override files are not resolved relative to the override file's own +location. + +This means that in a monorepo where Compose files are spread across team or component +subdirectories, relative paths in those files are resolved incorrectly when used as +override files. + +> [!TIP] +> +> If you need each Compose file's paths to resolve relative to its own location, +> use the [`include` top-level element](include.md) instead of merging with `-f`. Each +> included file is loaded with its own project directory, so relative paths resolve +> correctly. ## Reference information diff --git a/content/manuals/compose/how-tos/networking.md b/content/manuals/compose/how-tos/networking.md index 8e86f278a4ac..c025a080350f 100644 --- a/content/manuals/compose/how-tos/networking.md +++ b/content/manuals/compose/how-tos/networking.md @@ -12,7 +12,7 @@ Compose handles networking for you by default, but gives you fine-grained contro ## Default network and service discovery -By default, Compose sets up a single [network](/reference/cli/docker/network/create/) for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by its service name. This network uses the `bridge` driver. To understand when you'd use a different driver, see [Network drivers: bridge vs host](#change-the-network-mode). +By default, Compose sets up a single [network](/reference/cli/docker/network/create/) for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by its service name. This network uses the `bridge` driver. To attach services to a different Compose network or an external one, see [Specify custom networks](#specify-custom-networks). To change how a service uses the host network stack (`network_mode: host`), see [Change the network mode](#change-the-network-mode). For most development setups, the default network is sufficient. When you run `docker compose up`, Compose creates a network named `<project-name>_default` and attaches all services to it. Each service registers its name with an internal DNS server, so containers can reach each other using the service name directly. No IP addresses or manual configuration is needed. diff --git a/content/manuals/compose/how-tos/provider-services.md b/content/manuals/compose/how-tos/provider-services.md index 4d9eb7a58101..67f504c5fb8b 100644 --- a/content/manuals/compose/how-tos/provider-services.md +++ b/content/manuals/compose/how-tos/provider-services.md @@ -2,7 +2,7 @@ title: Use provider services description: Learn how to use provider services in Docker Compose to integrate external capabilities into your applications keywords: compose, docker compose, provider, services, platform capabilities, integration, model runner, ai -weight: 112 +weight: 130 --- {{< summary-bar feature_name="Compose provider services" >}} @@ -101,7 +101,7 @@ This information is then passed to dependent services as environment variables. > [!TIP] > -> If you're working with AI models in Compose, use the [`models` top-level element](/manuals/ai/compose/models-and-compose.md) instead. +> If you're working with AI models in Compose, use the [`models` top-level element](/manuals/compose/how-tos/models-and-compose.md) instead. ## Benefits of using provider services diff --git a/content/manuals/compose/how-tos/use-secrets.md b/content/manuals/compose/how-tos/use-secrets.md index 2afec05e530c..5fb86f06d9bc 100644 --- a/content/manuals/compose/how-tos/use-secrets.md +++ b/content/manuals/compose/how-tos/use-secrets.md @@ -19,6 +19,10 @@ Environment variables are often available to all processes, and it can be diffic Secrets are mounted as a file in `/run/secrets/<secret_name>` inside the container. +> [!NOTE] +> +> Secrets are supported on Linux containers only. Compose delivers each secret by bind-mounting a single file into the container, and Windows containers support bind-mounting directories only. + Getting a secret into a container is a two-step process. First, define the secret using the [top-level secrets element in your Compose file](/reference/compose-file/secrets.md). Next, update your service definitions to reference the secrets they require with the [secrets attribute](/reference/compose-file/services.md#secrets). Compose grants access to secrets on a per-service basis. Unlike the other methods, this permits granular access control within a service container via standard filesystem permissions. diff --git a/content/manuals/compose/support-and-feedback/faq.md b/content/manuals/compose/support-and-feedback/faq.md index e6033ec5a9b7..9955b065f3ac 100644 --- a/content/manuals/compose/support-and-feedback/faq.md +++ b/content/manuals/compose/support-and-feedback/faq.md @@ -15,6 +15,8 @@ Version one of the Docker Compose command-line binary was first released in 2014 Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with `docker compose`. Compose v2 ignores the version top-level element in the compose.yaml file. +Compose v5, released in 2025, uses the same `docker compose` command and is functionally identical to Compose v2. Its primary distinction is the introduction of an official [Go SDK](/manuals/compose/compose-sdk.md). + For further information, see [History and development of Compose](/manuals/compose/intro/history.md). ### What's the difference between `up`, `run`, and `start`? diff --git a/content/manuals/compose/trust-model.md b/content/manuals/compose/trust-model.md index be3f5cfd5e2a..ce1e2a9f1e95 100644 --- a/content/manuals/compose/trust-model.md +++ b/content/manuals/compose/trust-model.md @@ -85,9 +85,17 @@ implications when set by an untrusted author: | `pid: host` | Shares the host PID namespace | | `devices` | Exposes host devices to the container | | `image` | Pulls and runs an arbitrary container image | +| `env_file`, `label_file`, `secrets`/`configs` (`file:`), `include`, `extends` | Read files from the host, directly or through symlinks resolved from a remote checkout, and can surface their contents during configuration loading | +| `provider` | Runs the binary named by `provider.type` on the host, outside any container, when you run `up`, `down`, or `stop` | When in doubt, look up the effect of any unfamiliar field before running the configuration. +Like `volumes`, the file-reference fields read any file the user running Compose +can access, including through symlinks resolved from a remote checkout, and their +contents can appear in `docker compose config` output before any container starts. +Compose does not confine reads to the project directory. Treat a Compose project as +code you run, not data you inspect. + ### CI/CD environments Automated pipelines are particularly sensitive because they often run with diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index 9df80515cdf8..87942342e096 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -35,6 +35,12 @@ grid: description: Provide feedback on Docker Desktop or Docker Desktop features. icon: chat-bubble-left link: /desktop/troubleshoot-and-support/feedback/ +aliases: + - /desktop/mac/ + - /desktop/windows/ + - /docker-for-mac/ + - /docker-for-windows/ + - /desktop/get-started/ --- Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment @@ -58,7 +64,7 @@ Docker Desktop integrates with your preferred development tools and languages, a ## Products inside Docker Desktop -- [Docker MCP Toolkit and Catalog](/manuals/ai/mcp-catalog-and-toolkit/_index.md) +- [Docker MCP Toolkit and Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md) - [Docker Model Runner](/manuals/ai/model-runner/_index.md) - [Gordon](/manuals/ai/gordon/_index.md) - [Docker Offload](/manuals/offload/_index.md) diff --git a/content/manuals/desktop/enterprise/_index.md b/content/manuals/desktop/enterprise/_index.md index b8aecc99ff99..808b7f753b15 100644 --- a/content/manuals/desktop/enterprise/_index.md +++ b/content/manuals/desktop/enterprise/_index.md @@ -1,16 +1,6 @@ --- -title: Docker Desktop Enterprise -description: Docker Desktop Enterprise -keywords: Docker Desktop Enterprise -sitemap: false -aliases: -- /desktop/enterprise/admin/install/mac/ -- /desktop/enterprise/admin/configure/mac-admin/ -- /desktop/enterprise/admin/configure/windows-admin/ +build: + render: never +title: Enterprise +weight: 230 --- - -Docker Desktop Enterprise (DDE) has been deprecated and is no longer in active development. Please use [Docker Desktop](../_index.md) Community instead. - -If you are an existing DDE customer, use the [Support form](https://hub.docker.com/support/desktop/) to request a transition to one of the new [subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopEnterprise). - -If you are looking to deploy Docker Desktop at scale, contact us on [pricingquestions@docker.com](mailto:pricingquestions@docker.com). diff --git a/content/manuals/desktop/setup/allow-list.md b/content/manuals/desktop/enterprise/allow-list.md similarity index 90% rename from content/manuals/desktop/setup/allow-list.md rename to content/manuals/desktop/enterprise/allow-list.md index 30f7c4833789..0689e1b33893 100644 --- a/content/manuals/desktop/setup/allow-list.md +++ b/content/manuals/desktop/enterprise/allow-list.md @@ -4,9 +4,10 @@ keywords: Docker Desktop, allowlist, allow list, firewall, authentication URLs, title: Allowlist for Docker Desktop tags: [admin] linkTitle: Allowlist -weight: 100 +weight: 20 aliases: - /desktop/allow-list/ + - /desktop/setup/allow-list/ --- {{< summary-bar feature_name="Allow list" >}} @@ -30,5 +31,7 @@ This page contains the domain URLs that you need to add to a firewall allowlist | https://docker-pinata-support.s3.amazonaws.com | Troubleshooting | | https://api.dso.docker.com | Docker Scout service | | https://api.docker.com | New API | +| https://api.offload.docker.com | Docker Offload | | https://dhi.io | Docker Hardened Images | | https://registry.scout.docker.com | Docker Scout registry for DHI attestations | +| https://ai-backend-service.docker.com | [Gordon](/manuals/ai/gordon/_index.md) | diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/_index.md b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md new file mode 100644 index 000000000000..615d23b8719c --- /dev/null +++ b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md @@ -0,0 +1,95 @@ +--- +title: Enforce sign-in for Docker Desktop +linkTitle: Enforce sign-in +description: Require users to sign in to Docker Desktop to access organization benefits and security features +toc_max: 2 +keywords: authentication, registry.json, configure, enforce sign-in, docker desktop, security, .plist, registry key, mac, windows, organization +tags: [admin] +aliases: + - /security/for-admins/configure-sign-in/ + - /security/for-admins/enforce-sign-in/ + - /enterprise/security/enforce-sign-in/ +weight: 30 +--- + +{{< summary-bar feature_name="Enforce sign-in" >}} + +By default, users can access Docker Desktop without signing in to your organization. +When users don't sign in as organization members, they miss out on subscription benefits and can bypass security features configured for your organization. + +You can enforce sign-in using several methods, depending on your setup: + +- [Registry key method (Windows only)](methods.md#windows-registry-key-method) +- [Configuration profiles method (Mac only)](methods.md#mac-configuration-profiles-method-recommended) +- [`.plist` method (Mac only)](methods.md#mac-plist-file-method) +- [`registry.json` method (all platforms)](methods.md#all-platforms-registryjson-method) + +Deploying a `admin-settings.json` file with [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) also enforces sign-in. See [Settings Management and sign-in enforcement](methods.md#settings-management-and-sign-in-enforcement). + +This page provides an overview of how sign-in enforcement works. + +## How sign-in enforcement works + +When Docker Desktop detects a registry key, configuration profile, `.plist` file, or +`registry.json` file: + +- A **Sign in using your work email address** prompt appears, requiring users to + sign in as organization members to use Docker Desktop. The prompt states which + organizations are required and which method enforces it. +- If users sign in with accounts that aren't organization members, they're + automatically signed out and can't use Docker Desktop. The prompt changes to + **You have been signed out** and explains why. They can sign in again with a + different account. +- When users sign in with organization member accounts, they can use Docker + Desktop normally. +- When users sign out, the sign-in prompt reappears and they can + no longer use Docker Desktop unless they sign back in. + +### Impact on the Docker CLI + +Sign-in enforcement also blocks the Docker CLI. While the sign-in prompt is +showing, Docker Desktop's API proxy rejects almost every request with an +explanation at the terminal, for example: + +```text +Sign in to continue using Docker Desktop. Membership in the [myorg] organization +is required. Sign in enforced by your administrators (via registry.json). +``` + +- `docker run`, `docker pull`, `docker build`, `docker ps`, and other commands + that reach the engine fail until the user signs in. +- `docker version`, `docker info`, and `docker login` continue to work, so users + can sign in from the CLI. + +> [!IMPORTANT] +> +> Make sure you plan for blocking the Docker CLI before you roll out enforcement. Any scripted or CI use of the +> Docker CLI on an enforced machine stops working until that machine's user signs +> in as an organization member. + +Sign-in enforcement is separate from [SSO enforcement](#enforcing-sign-in-versus-enforcing-single-sign-on-sso), which governs how users authenticate as opposed to whether they must authenticate. + +### Impact on already-signed-in users + +When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop re-evaluates enforcement when it starts, and when a user signs in or out. It doesn't poll for new configuration while running, so a newly deployed registry key, configuration profile, `.plist`, or `registry.json` file takes effect on the next restart. + +On the next Docker Desktop restart: + +- Users signed in with an organization member account are automatically re-authenticated and continue working uninterrupted. +- Users signed in with a non-member account are immediately signed out on startup and see the **Sign in required!** prompt. + +## Enforcing sign-in versus enforcing single sign-on (SSO) + +Enforcing Docker Desktop sign-in and [enforcing SSO](/manuals/security/authentication/single-sign-on/connect.md#enforce-sso) are different features that serve different purposes: + +| Enforcement | Description | Benefits | +|:----------------------------------|:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Enforce sign-in only | Users must sign in before using Docker Desktop | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. | +| Enforce single sign-on (SSO) only | If users sign in, they must sign in using SSO | Centralizes authentication and enforces unified policies set by the identity provider. | +| Enforce both | Users must sign in using SSO before using Docker Desktop | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. It also centralizes authentication and enforces unified policies set by the identity provider. | +| Enforce neither | If users sign in, they can use SSO or their Docker credentials | Lets users access Docker Desktop without barriers, at the cost of reduced security and insights. | + +## Next steps + +- To set up sign-in enforcement, see [Configure sign-in enforcement](methods.md). +- To configure SSO enforcement, see [Enforce SSO](/manuals/security/authentication/single-sign-on/connect.md). diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/methods.md b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md new file mode 100644 index 000000000000..165ba3a0e38a --- /dev/null +++ b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md @@ -0,0 +1,374 @@ +--- +title: Configure sign-in enforcement +linkTitle: Configure +description: Configure sign-in enforcement for Docker Desktop using registry keys, configuration profiles, plist files, or registry.json files +keywords: authentication, registry.json, configure, enforce sign-in, docker desktop, security, .plist, registry key, mac, windows, linux +tags: [admin] +aliases: + - /security/for-admins/enforce-sign-in/methods/ + - /enterprise/security/enforce-sign-in/methods/ +--- + +{{< summary-bar feature_name="Enforce sign-in" >}} + +You can enforce sign-in for Docker Desktop using several methods. Choose the method that best fits your organization's infrastructure and security requirements. + +## Choose your method + +| Method | Platform | +|:-------|:---------| +| Registry key | Windows only | +| Configuration profiles | Mac only | +| `plist` file | Mac only | +| `registry.json` | All platforms | + +> [!TIP] +> +> For Mac, configuration profiles offer the highest security because they're +protected by Apple's System Integrity Protection (SIP). + +## Windows: Registry key method + +{{< tabs >}} +{{< tab name="Manual setup" >}} + +To configure the registry key method manually: + +1. Create the registry key: + + ```console + $ HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop + ``` +1. Create a multi-string value name `allowedOrgs`. +1. Use your organization names as string data. You can add multiple organizations: + - Use lowercase letters only + - Add each organization on a separate line + - Do not use spaces or commas as separators +1. Restart Docker Desktop. +1. Verify the **Sign in required!** prompt appears in Docker Desktop. + +You can also create this key at install time with the MSI installer's +`ALLOWEDORG` property, which accepts multiple organizations separated by +semicolons: + +```powershell +msiexec /i "DockerDesktop.msi" /quiet /norestart ALLOWEDORG="myorg1;myorg2" +``` + +For more information, see [MSI installer](/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md#configuration-options). + +{{< /tab >}} +{{< tab name="Group Policy deployment" >}} + +Deploy the registry key across your organization using Group Policy: + +1. Create a registry script with the following structure: + - Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop` + - Value name: `allowedOrgs` (multi-string) + - Value data: Your organization names, one per line, in lowercase only +1. In Group Policy Management, create or edit a GPO. +1. Navigate to **Computer Configuration** > **Preferences** > **Windows Settings** > **Registry**. +1. Right-click **Registry** > **New** > **Registry Item**. +1. Configure the registry item: + - Action: **Update** + - Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop` + - Value name: `allowedOrgs` + - Value data: Your organization names +1. Link the GPO to the target Organizational Unit. +1. Test on a small group using `gpupdate/force`. +1. Deploy organization-wide after verification. + +{{< /tab >}} +{{< /tabs >}} + +## Mac: Configuration profiles method (recommended) + +Configuration profiles provide the most secure enforcement method for Mac, as they're protected by Apple's System Integrity Protection. + +The payload is a dictionary of key-values. Docker Desktop supports the following keys: + +- `allowedOrgs`: Sets a list of organizations in one single string, where each organization is in lowercase only and is separated by a semi-colon. +- `overrideProxyHTTP`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. +- `overrideProxyHTTPS`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests. +- `overrideProxyExclude`: Bypasses proxy settings for the specified hosts and domains. Uses a comma-separated list. +- `overrideProxyPAC`: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy. +- `overrideProxyEmbeddedPAC`: Sets the content of an in-memory PAC file. It has precedence over `overrideProxyPAC`. + +> [!IMPORTANT] +> +> `allowedOrgs` must be a `<string>`, not an `<array>`. Docker Desktop only reads +> string values from a configuration profile, so an array is silently ignored and +> no enforcement happens. This differs from the +> [`.plist` method](#mac-plist-file-method), which does use an array. + +Setting at least one of the proxy keys puts Docker Desktop's proxy into manual +mode and locks the proxy settings, so developers can't change them. + +1. Create a file named `docker.mobileconfig` and include the following content: + ```xml + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> + <plist version="1.0"> + <dict> + <key>PayloadContent</key> + <array> + <dict> + <key>PayloadType</key> + <string>com.docker.config</string> + <key>PayloadVersion</key> + <integer>1</integer> + <key>PayloadIdentifier</key> + <string>com.docker.config</string> + <key>PayloadUUID</key> + <string>eed295b0-a650-40b0-9dda-90efb12be3c7</string> + <key>PayloadDisplayName</key> + <string>Docker Desktop Configuration</string> + <key>PayloadDescription</key> + <string>Configuration profile to manage Docker Desktop settings.</string> + <key>PayloadOrganization</key> + <string>Your company name</string> + <key>allowedOrgs</key> + <string>first_org;second_org</string> + <key>overrideProxyHTTP</key> + <string>http://company.proxy:port</string> + <key>overrideProxyHTTPS</key> + <string>https://company.proxy:port</string> + </dict> + </array> + <key>PayloadType</key> + <string>Configuration</string> + <key>PayloadVersion</key> + <integer>1</integer> + <key>PayloadIdentifier</key> + <string>com.yourcompany.docker.config</string> + <key>PayloadUUID</key> + <string>0deedb64-7dc9-46e5-b6bf-69d64a9561ce</string> + <key>PayloadDisplayName</key> + <string>Docker Desktop Config Profile</string> + <key>PayloadDescription</key> + <string>Config profile to enforce Docker Desktop settings for allowed organizations.</string> + <key>PayloadOrganization</key> + <string>Your company name</string> + </dict> + </plist> + ``` +1. Replace placeholders: + - Change `com.yourcompany.docker.config` to your company identifier + - Replace `Your company name` with your organization name making sure it is all lowercase + - Replace `PayloadUUID` with a randomly generated UUID + - Update the `allowedOrgs` value with your organization names (separated by semicolons) + - Replace `company.proxy:port` with http/https proxy server host(or IP address) and port +1. Deploy the profile using your MDM solution. +1. Verify the profile appears in **System Settings** > **General** > **Device Management** under **Device (Managed)**. Ensure the profile is listed with the correct name and settings. + +Some MDM solutions let you specify the payload as a plain dictionary of key-value settings without the full `.mobileconfig` wrapper: + +```xml +<dict> + <key>allowedOrgs</key> + <string>first_org;second_org</string> + <key>overrideProxyHTTP</key> + <string>http://company.proxy:port</string> + <key>overrideProxyHTTPS</key> + <string>https://company.proxy:port</string> +</dict> +``` + +## Mac: plist file method + +{{< tabs >}} +{{< tab name="Manual creation" >}} + +1. Create the file `/Library/Application Support/com.docker.docker/desktop.plist`. +1. Add this content, replacing `myorg1` and `myorg2` with your organization names and making sure they have lowercase letters only: + ```xml + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> + <plist version="1.0"> + <dict> + <key>allowedOrgs</key> + <array> + <string>myorg1</string> + <string>myorg2</string> + </array> + </dict> + </plist> + ``` +1. Set file permissions to prevent editing by non-administrator users. +1. Restart Docker Desktop. +1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop. + +{{< /tab >}} +{{< tab name="Shell script deployment" >}} + +Create and deploy a script for organization-wide distribution: + +```bash +#!/bin/bash + +# Create directory if it doesn't exist +sudo mkdir -p "/Library/Application Support/com.docker.docker" + +# Write the plist file +sudo defaults write "/Library/Application Support/com.docker.docker/desktop.plist" allowedOrgs -array "myorg1" "myorg2" + +# Set appropriate permissions +sudo chmod 644 "/Library/Application Support/com.docker.docker/desktop.plist" +sudo chown root:admin "/Library/Application Support/com.docker.docker/desktop.plist" +``` + +Deploy this script using SSH, remote support tools, or your preferred deployment method. + +{{< /tab >}} +{{< /tabs >}} + +## All platforms: registry.json method + +The registry.json method works across all platforms and offers flexible deployment options. + +### File locations + +Create the `registry.json` file (UTF-8) at the appropriate location: + +| Platform | Location | +| --- | --- | +| Windows | `%ProgramData%\DockerDesktop\registry.json` | +| Mac | `/Library/Application Support/com.docker.docker/registry.json` | +| Linux | `/usr/share/docker-desktop/registry/registry.json` | + +### Basic setup + +{{< tabs >}} +{{< tab name="Manual creation" >}} + +1. Ensure users are members of your Docker organization. +1. Create the `registry.json` file at the appropriate location for your platform. +1. Add this content, replacing organization names with your own and making sure they have lowercase letters only: + ```json + { + "allowedOrgs": ["myorg1", "myorg2"] + } + ``` +1. Set file permissions to prevent user editing. +1. Restart Docker Desktop. +1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop. + +If users have issues starting Docker Desktop after enforcing sign-in, +they may need to update to the latest version. + +{{< /tab >}} +{{< tab name="Command line setup" >}} + +#### Windows (PowerShell as Administrator) + +```shell +Set-Content /ProgramData/DockerDesktop/registry.json '{"allowedOrgs":["myorg1","myorg2"]}' +``` + +#### Mac + +```console +sudo mkdir -p "/Library/Application Support/com.docker.docker" +echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json" +``` + +#### Linux + +```console +sudo mkdir -p /usr/share/docker-desktop/registry +echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee /usr/share/docker-desktop/registry/registry.json +``` + +{{< /tab >}} +{{< tab name="Installation-time setup" >}} + +Create the registry.json file during Docker Desktop installation: + +#### Windows + +`--allowed-org` is a flag on the EXE installer. If you deploy with the MSI +installer, use the `ALLOWEDORG` property instead, which creates the +[registry key](#windows-registry-key-method). + +```shell +# PowerShell +Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg' + +# Command Prompt +"Docker Desktop Installer.exe" install --allowed-org=myorg1 +``` +The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. + +> [!IMPORTANT] +> +> With Docker Desktop version 4.83 and later, `--allowed-org` can't be combined +> with `--user`, and it can't be used for a Microsoft Store installation. Both +> are per-user installations and the installer rejects the combination. This +> matters because the Windows installer selects a per-user installation by +> default from version 4.83. For per-user installations, configure the +> `registry.json` file after installation. + +#### Mac + +```console +sudo hdiutil attach Docker.dmg +sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg +sudo hdiutil detach /Volumes/Docker +``` + +The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. + +{{< /tab >}} +{{< /tabs >}} + +## Method precedence + +When more than one configuration method exists on the same machine, Docker +Desktop evaluates them in order and stops at the first one that's configured. +The order depends on the platform. + +| Platform | Precedence order | +|:---------|:-----------------| +| Windows | 1. Registry key<br>2. `registry.json`<br>3. `admin-settings.json` | +| Mac | 1. Configuration profile<br>2. `desktop.plist`<br>3. `registry.json`<br>4. `admin-settings.json` | +| Linux | 1. `registry.json`<br>2. `admin-settings.json` | + +Lower-precedence methods are not consulted once a higher one applies. For +example, on a Mac with both a configuration profile and a `registry.json` file, +only the organizations in the configuration profile are enforced. + +## Settings Management and sign-in enforcement + +Deploying an `admin-settings.json` file enforces sign-in on its own, even if the +file contains no organization list. Users who aren't on a Docker Business +subscription see the sign-in prompt, and the Docker Engine is held until they +sign in. + +This differs from the four methods above in two ways: + +- It doesn't restrict sign-in to particular organizations, so any Docker account + satisfies it. Combine it with one of the methods above if you need organization + membership enforced. +- It's the lowest-precedence method, so any of the methods above overrides it. + +If you use [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md), account for this when planning your rollout: developers who are signed out will be prompted to sign in as soon as the file reaches their machine and Docker Desktop restarts. + +## Troubleshoot sign-in enforcement + +If sign-in enforcement doesn't work: + +- Verify file locations and permissions +- Check that organization names use lowercase letters and match your Docker Hub + organization name exactly. Matching is case-sensitive, so a mismatch signs out + every user +- Check for stray whitespace in the value. In the Windows registry key, put each + organization on its own line rather than separating them with spaces or commas +- Check whether a higher-precedence method is in effect. See + [Method precedence](#method-precedence) +- Restart Docker Desktop or reboot the system. Docker Desktop doesn't pick up new + configuration while running +- Confirm users are members of the specified organizations +- Update Docker Desktop to the latest version + +If enforcement works but developers report that the Docker CLI stopped working, +that's expected. See [Impact on the Docker CLI](_index.md#impact-on-the-docker-cli). \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/_index.md b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md new file mode 100644 index 000000000000..7479bc70ce54 --- /dev/null +++ b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md @@ -0,0 +1,40 @@ +--- +title: Deploy Docker Desktop +weight: 10 +description: If you're an IT admin, learn how to deploy Docker Desktop at scale +keywords: msi, docker desktop, windows, installation, mac, pkg, enterprise +grid: +- title: MSI installer + description: Learn how to install Docker Desktop with the MSI installer. + link: /desktop/enterprise/enterprise-deployment/msi-install-and-configure/ +- title: PKG installer + description: Learn how to install Docker Desktop with the PKG installer. + link: /desktop/enterprise/enterprise-deployment/pkg-install-and-configure/ +- title: MS Store + description: Learn how to install Docker Desktop through the Microsoft Store. + link: /desktop/enterprise/enterprise-deployment/ms-store/ +- title: Deploy with Intune + description: Learn how to deploy Docker Desktop on Windows and macOS devices using Microsoft Intune. + link: /desktop/enterprise/enterprise-deployment/use-intune/ +- title: Deploy with Jamf Pro + description: Learn how to deploy Docker Desktop for Mac using Jamf Pro + link: /desktop/enterprise/enterprise-deployment/use-jamf-pro/ +- title: Docker Desktop for Microsoft Dev Box + description: Install Docker Desktop for Microsoft Dev Box via the Microsoft Azure Marketlplace + link: /desktop/enterprise/enterprise-deployment/dev-box/ +- title: FAQs + description: Common questions when deploying Docker Desktop + link: /desktop/enterprise/enterprise-deployment/faq/ +aliases: + - /desktop/enterprise/admin/install/mac/ + - /desktop/enterprise/admin/configure/mac-admin/ + - /desktop/enterprise/admin/configure/windows-admin/ + - /desktop/enterprise/ + - /enterprise/enterprise-deployment/ +--- + +Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. + +Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, Mac, and Linux systems. + +{{< grid >}} \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md b/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md new file mode 100644 index 000000000000..d4db62ec1435 --- /dev/null +++ b/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md @@ -0,0 +1,65 @@ +--- +Title: Docker Desktop in Microsoft Dev Box +linkTitle: Microsoft Dev Box +description: Learn about the benefits of and how to setup Docker Desktop in Microsoft Dev Box +keywords: desktop, docker, windows, microsoft dev box +weight: 60 +aliases: + - /enterprise/enterprise-deployment/dev-box/ +--- + +> [!IMPORTANT] +> +> Microsoft has announced the retirement of Microsoft Dev Box. The service entered its closing-down period on 14 September 2026 and retires fully at 17:00 UTC on 18 September 2028. Microsoft recommends transitioning to Windows 365 or another solution. See the [Microsoft Dev Box retirement guide](https://learn.microsoft.com/en-us/azure/dev-box/dev-box-retirement-guide). +> +> To deploy Docker Desktop on Windows 365 Cloud PCs or other managed Windows machines, use the [MSI installer](msi-install-and-configure.md) with [Intune](use-intune.md). + +Docker Desktop is available as a pre-configured image in the Microsoft Azure Marketplace for use with Microsoft Dev Box, allowing developers to quickly set up consistent development environments in the cloud. + +Microsoft Dev Box provides cloud-based, pre-configured developer workstations that allow you to code, build, and test applications without configuring a local development environment. The Docker Desktop image for Microsoft Dev Box comes with Docker Desktop and its dependencies pre-installed, giving you a ready-to-use containerized development environment. + +## Key benefits + +- Docker Desktop, WSL2, and dependencies pre-installed +- Identical environment for every team member +- More compute and storage than a typical local machine +- Session state persists between uses +- Works with your existing Docker subscription + +## Setup + +### Prerequisites + +- An Azure subscription +- Access to Microsoft Dev Box +- A Docker subscription (Pro, Team, or Business). You can use Docker Desktop in Microsoft Dev Box with any of the following subscription options: + - An existing or new Docker subscription + - A new Docker subscription purchased through Azure Marketplace + - A Docker Business subscription with SSO configured for your organization + +### Set up Docker Desktop in Dev Box + +1. Navigate to the [Docker Desktop for Microsoft Dev Box](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/dockerinc1694120899427.devbox_azuremachine?tab=Overview) listing in Azure Marketplace. +1. Select **Get It Now** to add the virtual machine image to your subscription. +1. Follow the Azure workflow to complete the setup. +1. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup. + +### Activate Docker Desktop + +Once your Dev Box is provisioned with the Docker Desktop image: + +1. Start your Dev Box instance. +1. Launch Docker Desktop. +1. Sign in with your Docker ID. + +## Support + +For issues related to: + +- Docker Desktop configuration, usage, or licensing: Create a support ticket through [Docker Support](https://hub.docker.com/support). +- Dev Box creation, Azure portal configuration, or networking: Contact Azure Support. + +## Limitations + +- Microsoft Dev Box is only available on Windows 10 and 11 (Linux VMs are not supported). +- Performance may vary based on your Dev Box configuration and network conditions. diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/faq.md b/content/manuals/desktop/enterprise/enterprise-deployment/faq.md new file mode 100644 index 000000000000..8b95880abfeb --- /dev/null +++ b/content/manuals/desktop/enterprise/enterprise-deployment/faq.md @@ -0,0 +1,158 @@ +--- +title: Enterprise deployment FAQs +linkTitle: FAQs +description: Frequently asked questions for deploying Docker Desktop at scale +keywords: msi, deploy, docker desktop, faqs, pkg, mdm, jamf, intune, windows, mac, enterprise, admin +tags: [FAQ, admin] +weight: 70 +aliases: + - /enterprise/enterprise-deployment/faq/ +--- + +## MSI + +Common questions about installing Docker Desktop using the MSI installer. + +### What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)? + +Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `--keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs: + +```powershell +# For all-user installations +& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall --keep-data + +# For per-user installations +& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall --keep-data + +``` + +For all-users installations, you can have the MSI do this for you with the `REMOVEEXISTINGINSTALL` property, described in the next answer. + +### What happens if the user's machine has an older `.exe` installation? + +### What happens if the user's machine has an older `.exe` installation? + +The MSI installer detects existing `.exe` installations and, by default, blocks the installation. How you resolve it depends on whether the `.exe` was installed for all users or for a single user. + +#### All-users `.exe` installation + +The installation stops with: + +```text +You need to uninstall the previous Docker Desktop version in order to use the MSI installer. +``` + +Either uninstall it first with `--keep-data` as described in the previous answer, or let the MSI do it by setting `REMOVEEXISTINGINSTALL=1`: + +```powershell +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart REMOVEEXISTINGINSTALL=1 +``` + +This runs the existing uninstaller with `--keep-data`, so settings and container data are preserved. + +#### Per-user `.exe` installation + +Available with Docker Desktop version 4.84 and later, the installation stops with: + +```text +Docker Desktop is installed per-user for one or more accounts on this machine: <usernames>. +Please have each affected user uninstall Docker Desktop first before running the MSI installer. +``` + +`REMOVEEXISTINGINSTALL` doesn't help here. The MSI runs with machine-wide privileges and can't reliably uninstall software installed under another user's profile, so each listed user must uninstall Docker Desktop themselves before the MSI can proceed. + +With Docker Desktop version 4.83 and earlier, the MSI doesn't detect per-user installations. + +> [!NOTE] +> +> Per-user installations became more common with Docker Desktop version 4.83, when the EXE installer started selecting a per-user installation by default. Expect to encounter them on machines where developers installed Docker Desktop themselves. + +### Can I install the MSI per-user? + +No. The MSI installer only supports all-users installations. + +Available with Docker Desktop version 4.92 and later, passing `MSIINSTALLPERUSER` fails with: + +```text +Docker Desktop does not support per-user installation with the MSI installer. +``` + +With Docker Desktop version 4.91 and earlier, the MSI accepts `MSIINSTALLPERUSER` but produces an installation that later updates can't upgrade. + +Use the EXE installer with the `--user` flag if you need a per-user installation. + +### My installation failed, how do I find out what happened? + +MSI installations may fail silently, offering little diagnostic feedback. + +To debug a failed installation, run the install again with verbose logging enabled: + +```powershell +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" +``` + +After the installation has failed, open the log file and search for occurrences of `value 3`. This is the exit code Windows Installer outputs when it has failed. Just above the line, you will find the reason for the failure. + +### Why does the installer prompt for a reboot at the end of every fresh installation? + +The installer prompts for a reboot because it assumes that changes have been made to the system that require a reboot to finish their configuration. + +For example, if you select the WSL engine, the installer adds the required Windows features. After these features are installed, the system reboots to complete configurations so the WSL engine is functional. + +You can suppress reboots by using the `/norestart` option when launching the installer from the command line: + +```powershell +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /norestart +``` + +### Why isn't the `docker-users` group populated when the MSI is installed with Intune or another MDM solution? + +It's common for MDM solutions to install applications in the context of the system account. This means that the `docker-users` group isn't populated with the user's account, as the system account doesn't have access to the user's context. + +As an example, you can reproduce this by running the installer with `psexec` in an elevated command prompt: + +```powershell +psexec -i -s msiexec /i "DockerDesktop.msi" +``` +The installation should complete successfully, but the `docker-users` group won't be populated. + +As a workaround, you can create a script that runs in the context of the user account. + +The script would be responsible for ensuring the `docker-users` group exists and populating it with the correct user. + +> [!WARNING] +> +> Membership in `docker-users` grants access to the Docker daemon socket, which is equivalent to granting administrative privileges on the host. Only add users who require access to Windows containers or Hyper-V VM management. For Linux containers using the WSL 2 backend, this group membership is not required. See [Protect the Docker daemon socket](/manuals/engine/security/protect-access.md) for further information. + +Here's an example script that creates the `docker-users` group if needed and adds the current user to it (requirements may vary depending on environment): + +```powershell +$Group = "docker-users" +$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name + +# Create the group if it doesn't exist +if (-not (Get-LocalGroup -Name $Group -ErrorAction SilentlyContinue)) { + New-LocalGroup -Name $Group +} + +# Add the user to the group +Add-LocalGroupMember -Group $Group -Member $CurrentUser +``` + +> [!NOTE] +> +> After adding a new user to the `docker-users` group, the user must sign out and then sign back in for the changes to take effect. + +## MDM + +Common questions about deploying Docker Desktop using mobile device management +(MDM) tools such as Jamf, Intune, or Workspace ONE. + +### Why doesn't my MDM tool apply all Docker Desktop configuration settings at once? + +Some MDM tools, such as Workspace ONE, may not support applying multiple +configuration settings in a single XML file. In these cases, you may need to +deploy each setting in a separate XML file. + +Refer to your MDM provider's documentation for specific deployment +requirements or limitations. diff --git a/content/manuals/enterprise/enterprise-deployment/ms-store.md b/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md similarity index 79% rename from content/manuals/enterprise/enterprise-deployment/ms-store.md rename to content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md index 9011934183ee..02a392ebfc70 100644 --- a/content/manuals/enterprise/enterprise-deployment/ms-store.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md @@ -5,6 +5,8 @@ description: Install Docker Desktop for Windows through the Microsoft Store. Und keywords: microsoft store, windows, docker desktop, install, deploy, configure, admin, mdm, intune, winget tags: [admin] weight: 30 +aliases: + - /enterprise/enterprise-deployment/ms-store/ --- You can deploy Docker Desktop for Windows through the [Microsoft app store](https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB&gl=GB). @@ -26,7 +28,7 @@ For developers who install Docker Desktop directly: ### Intune-managed installations In environments managed with Intune: -- Intune checks for updates approximately every 8 hours. +- - Intune checks for updates periodically, typically several times a day. The exact interval is controlled by Intune, not by Docker. - When a new version is detected, Intune triggers a `winget` upgrade. - If appropriate policies are configured, updates can occur automatically without user intervention. - Updates are handled by Intune's management infrastructure rather than the Microsoft Store itself. @@ -43,3 +45,9 @@ If using Intune to manage Docker Desktop for Windows: - Ensure your Intune policies are configured to handle application updates - Be aware that the update process uses WinGet APIs rather than direct Store mechanisms - Consider testing the update process in a controlled environment to verify proper functionality + +## Installation mode + +Available with Docker Desktop version 4.85 and later, fresh installations from the Microsoft Store use per-user install mode by default, which removes the need for admin privileges. + +With version 4.97 and later, per-user installations from the Microsoft Store can use the Docker VMM (Beta) backend in addition to WSL 2. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). diff --git a/content/manuals/enterprise/enterprise-deployment/msi-install-and-configure.md b/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md similarity index 84% rename from content/manuals/enterprise/enterprise-deployment/msi-install-and-configure.md rename to content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md index 43c5b1aa62dd..56d05879e630 100644 --- a/content/manuals/enterprise/enterprise-deployment/msi-install-and-configure.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md @@ -6,6 +6,7 @@ tags: [admin] weight: 10 aliases: - /desktop/setup/install/enterprise-deployment/msi-install-and-configure/ + - /enterprise/enterprise-deployment/msi-install-and-configure/ --- {{< summary-bar feature_name="MSI installer" >}} @@ -15,35 +16,33 @@ The MSI package supports various MDM (Mobile Device Management) solutions, makin ## Install interactively 1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Admin Console**, then **Enterprise deployment**. -3. From the **Windows OS** tab, select the **Download MSI installer** button. -4. Once downloaded, double-click `Docker Desktop Installer.msi` to run the installer. -5. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`(all-user installations) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installations) -6. Configure the Docker Desktop installation. You can: +1. Select **Docker Desktop**, then **Deploy**. +1. From the **Windows OS** tab, select the **Download MSI installer** button. +1. Once downloaded, double-click `DockerDesktop.msi` to run the installer. +1. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. The MSI installer only supports all-users installations. If you need a per-user installation, use the EXE installer. +1. Configure the Docker Desktop installation. You can: - Create a desktop shortcut - Set the Docker Desktop service startup type to automatic - - Disable Windows Container usage + - Allow Windows Containers to be used with this installation. This is cleared by default in the installation wizard, so Windows containers are disabled unless you select it. - - Select the Docker Desktop backend: WSL or Hyper-V. If only one is supported by your system, you won't be able to choose. - -7. Follow the instructions on the installation wizard to authorize the installer and proceed with the install. -8. When the installation is successful, select **Finish** to complete the installation process. + - Select the Docker Desktop backend: WSL or Hyper-V. +1. Follow the instructions on the installation wizard to authorize the installer and proceed with the install. +1. When the installation is successful, select **Finish** to complete the installation process. If your administrator account is different from your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers: 1. Run **Computer Management** as an **administrator**. -2. Navigate to **Local Users and Groups** > **Groups** > **docker-users**. -3. Right-click to add the user to the group. -4. Sign out and sign back in for the changes to take effect. +1. Navigate to **Local Users and Groups** > **Groups** > **docker-users**. +1. Right-click to add the user to the group. +1. Sign out and sign back in for the changes to take effect. > [!NOTE] > -> When installing Docker Desktop with the MSI, in-app updates are automatically disabled by default. This ensures organizations can maintain version consistency and prevent unapproved updates. -> Starting with Docker Desktop version 4.60 and later, in-app updates from an MSI installation can be enabled by changing the `disableUpdate` setting to `false` through [Settings Management](../security/hardened-desktop/settings-management/). +> When installing Docker Desktop with the MSI, in-app updates are automatically disabled by default. This ensures organizations can maintain version consistency and prevent unapproved updates. In-app updates from an MSI installation can be enabled by changing the `disableUpdate` setting to `false` through [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). > -> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Enterprise deployment** page. +> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from Docker Home. Navigate to the **Deploy** page. > > To keep up to date with new releases, check the [release notes](/manuals/desktop/release-notes.md) page. @@ -99,7 +98,7 @@ msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ADMINSETTINGS="{""configurationFileVersion"":2,""enhancedContainerIsolation"":{""value"":true,""locked"":false}}" ALLOWEDORG="your-organization" ``` -#### Install interactively and allow users to switch to Windows containers without admin rights +#### Install non-interactively and allow users to switch to Windows containers without admin rights ```powershell msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ALLOWEDORG="your-organization" ALWAYSRUNSERVICE=1 @@ -200,11 +199,11 @@ In addition to the following custom properties, the Docker Desktop MSI installer | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `ENABLEDESKTOPSHORTCUT` | Creates a desktop shortcut. | 1 | | `INSTALLFOLDER` | Specifies a custom location where Docker Desktop will be installed. | C:\Program Files\Docker | -| `ADMINSETTINGS` | Automatically creates an `admin-settings.json` file which is used to [control certain Docker Desktop settings](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. | None | +| `ADMINSETTINGS` | Automatically creates an `admin-settings.json` file which is used to [control certain Docker Desktop settings](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. If you pass `ADMINSETTINGS` on its own, the installation still succeeds but no `admin-settings.json` file is written and no error is reported. | None | | `ALLOWEDORG` | Requires the user to sign in and be part of the specified Docker Hub organization when running the application. This creates a registry key called `allowedOrgs` in `HKLM\Software\Policies\Docker\Docker Desktop`. | None | | `ALWAYSRUNSERVICE` | Lets users switch to Windows containers without needing admin rights | 0 | -| `DISABLEWINDOWSCONTAINERS` | Disables the Windows containers integration | 0 | -| `ENGINE` | Sets the Docker Engine that's used to run containers. This can be either `wsl` , `hyperv`, or `windows` | `wsl` | +| `DISABLEWINDOWSCONTAINERS` | Disables the Windows containers integration | 1 | +| `ENGINE` | Sets the Docker Engine that's used to run containers. This can be `wsl`, `hyperv`, `windows`, or `docker-vmm`. The installation wizard only offers `wsl` and `hyperv`. The others are command line only. `docker-vmm` is available with Docker Desktop version 4.90 and later. | `wsl` | | `PROXYENABLEKERBEROSNTLM` | When set to 1, enables support for Kerberos and NTLM proxy authentication. | 0 | | `PROXYHTTPMODE` | Sets the HTTP Proxy mode. This can be either `system` or `manual` | `system` | | `OVERRIDEPROXYHTTP` | Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. | None | @@ -216,7 +215,7 @@ In addition to the following custom properties, the Docker Desktop MSI installer | `WINDOWSCONTAINERSDEFAULTDATAROOT` | Specifies the default location for Windows containers. | None | | `WSLDEFAULTDATAROOT` | Specifies the default location for the WSL distribution disk. | None | | `DISABLEANALYTICS` | When set to 1, analytics collection will be disabled for the MSI. For more information, see [Analytics](#analytics). | 0 | -| `REMOVEEXISTINGINSTALL` | When set to 1, any existing EXE installations are removed. Existing settings and content are preserved. Available with Docker Desktop version 4.61 and later. | 1 | +| `REMOVEEXISTINGINSTALL` | When set to 1, an existing all-users EXE installation is uninstalled before the MSI installs, and settings and content are preserved. Has no effect on per-user EXE installations, which must be removed by the users who own them. | 1 | Additionally, you can also use `/norestart` or `/forcerestart` to control reboot behaviour. @@ -239,7 +238,7 @@ When you install Docker Desktop from the default installer GUI, select the **Dis When you install Docker Desktop from the command line, use the `DISABLEANALYTICS` property. ```powershell -msiexec /i "win\msi\bin\en-US\DockerDesktop.msi" /L*V ".\msi.log" DISABLEANALYTICS=1 +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" DISABLEANALYTICS=1 ``` {{< /tab >}} @@ -261,4 +260,4 @@ When analytics is disabled, this key is set to `1`. ## Additional resources -- [Explore the FAQs](/manuals/enterprise/enterprise-deployment/faq.md) +- [Explore the FAQs](/manuals/desktop/enterprise/enterprise-deployment/faq.md) diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md new file mode 100644 index 000000000000..fbb11b3f75eb --- /dev/null +++ b/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md @@ -0,0 +1,51 @@ +--- +title: PKG installer +description: Understand how to use the PKG installer to deploy Docker Desktop for Mac at scale. +keywords: pkg, mac, docker desktop, install, deploy, configure, admin, mdm +tags: [admin] +weight: 20 +aliases: + - /enterprise/enterprise-deployment/pkg-install-and-configure/ +--- + +{{< summary-bar feature_name="PKG installer" >}} + +The PKG package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations. + +## Install interactively + +1. In [Docker Home](http://app.docker.com), choose your organization. +1. Select **Docker Desktop**, then **Deploy**. +1. From the **macOS** tab, select the **Download PKG installer** button. +1. Once downloaded, double-click `Docker.pkg` to run the installer. +1. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation. + - **Introduction**: Select **Continue**. + - **License**: Review the license agreement and select **Agree**. + - **Destination Select**: This step is optional. It is recommended that you keep the default installation destination (usually `Macintosh HD`). Select **Continue**. + - **Installation Type**: Select **Install**. + - **Installation**: Authenticate using your administrator password or Touch ID. + - **Summary**: When the installation completes, select **Close**. + +> [!NOTE] +> +> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This ensures organizations can maintain version consistency and prevent unapproved updates. For Docker Desktop installed with the `.dmg` installer, in-app updates remain supported. +> +> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Home. Navigate to the **Deploy** page. +> +> To keep up to date with new releases, check the [release notes](/manuals/desktop/release-notes.md) page. + +## Install from the command line + +1. In [Docker Home](http://app.docker.com), choose your organization. +1. Select **Docker Desktop**, then **Deploy**. +1. From the **macOS** tab, select the **Download PKG installer** button. +1. From your terminal, run the following command: + + ```console + $ sudo installer -pkg "/path/to/Docker.pkg" -target /Applications + ``` + +## Additional resources + +- See how you can deploy Docker Desktop for Mac using [Intune](use-intune.md) or [Jamf Pro](use-jamf-pro.md) +- Explore how to [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/methods.md#mac-plist-file-method) for your users. \ No newline at end of file diff --git a/content/manuals/enterprise/enterprise-deployment/use-intune.md b/content/manuals/desktop/enterprise/enterprise-deployment/use-intune.md similarity index 93% rename from content/manuals/enterprise/enterprise-deployment/use-intune.md rename to content/manuals/desktop/enterprise/enterprise-deployment/use-intune.md index 25fb74f7b7f4..58d5d449aea3 100644 --- a/content/manuals/enterprise/enterprise-deployment/use-intune.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/use-intune.md @@ -4,6 +4,8 @@ description: Use Intune, Microsoft's cloud-based device management tool, to depl keywords: microsoft, windows, docker desktop, deploy, mdm, enterprise, administrator, mac, pkg, dmg tags: [admin] weight: 40 +aliases: + - /enterprise/enterprise-deployment/use-intune/ --- {{< summary-bar feature_name="Intune" >}} @@ -52,4 +54,4 @@ Next, assign the app: ## Additional resources - [Explore the FAQs](faq.md). -- Learn how to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) for your users. \ No newline at end of file +- Learn how to [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/enterprise/enterprise-deployment/use-jamf-pro.md b/content/manuals/desktop/enterprise/enterprise-deployment/use-jamf-pro.md similarity index 87% rename from content/manuals/enterprise/enterprise-deployment/use-jamf-pro.md rename to content/manuals/desktop/enterprise/enterprise-deployment/use-jamf-pro.md index d2e4104f43b2..568a99961b35 100644 --- a/content/manuals/enterprise/enterprise-deployment/use-jamf-pro.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/use-jamf-pro.md @@ -4,6 +4,8 @@ description: Use Jamf Pro to deploy Docker Desktop for Mac keywords: jamf, mac, docker desktop, deploy, mdm, enterprise, administrator, pkg tags: [admin] weight: 50 +aliases: + - /enterprise/enterprise-deployment/use-jamf-pro/ --- {{< summary-bar feature_name="Jamf Pro" >}} @@ -29,4 +31,4 @@ For more information, see [Jamf Pro's official documentation](https://learn.jamf ## Additional resources -- Learn how to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) for your users. \ No newline at end of file +- Learn how to [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/hardened-desktop/_index.md b/content/manuals/desktop/enterprise/hardened-desktop/_index.md new file mode 100644 index 000000000000..aab198ba6476 --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/_index.md @@ -0,0 +1,67 @@ +--- +title: Hardened Docker Desktop +linkTitle: Hardened Docker Desktop +description: Security features that help organizations secure developer environments without impacting productivity +keywords: security, hardened desktop, enhanced container isolation, registry access management, settings management, admins, docker desktop, image access management, air-gapped containers +tags: [admin] +aliases: + - /security/for-admins/hardened-desktop/ + - /enterprise/security/ + - /enterprise/security/hardened-desktop/ +grid: + - title: "Settings Management" + description: Learn how Settings Management can secure your developers' workflows. + icon: shield-check + link: /desktop/enterprise/hardened-desktop/settings-management/ + - title: "Enhanced Container Isolation" + description: Understand how Enhanced Container Isolation can prevent container attacks. + icon: shield-check + link: /desktop/enterprise/hardened-desktop/enhanced-container-isolation/ + - title: "Registry Access Management" + description: Control the registries developers can access while using Docker Desktop. + icon: server + link: /desktop/enterprise/hardened-desktop/registry-access-management/ + - title: "Image Access Management" + description: Control the images developers can pull from Docker Hub. + icon: photo + link: /desktop/enterprise/hardened-desktop/image-access-management/ + - title: "Air-Gapped Containers" + description: Restrict containers from accessing unwanted network resources. + icon: lock-closed + link: /desktop/enterprise/hardened-desktop/air-gapped-containers/ + - title: "Namespace access" + description: Control whether organization members can push content to their personal namespaces. + icon: folder-open + link: /desktop/enterprise/hardened-desktop/namespace-access/ +weight: 40 +--- + +{{< summary-bar feature_name="Hardened Docker Desktop" >}} + +Hardened Docker Desktop provides a collection of security features designed to strengthen developer environments without compromising productivity or developer experience. + +With Hardened Docker Desktop, you can enforce strict security policies that prevent developers and containers from bypassing organizational controls. You can also enhance container isolation to protect against security threats like malicious payloads that might breach the Docker Desktop Linux VM or underlying host system. + +## Who should use Hardened Docker Desktop? + +Hardened Docker Desktop is ideal for security-focused organizations that: + +- Don't provide root or administrator access to developers' machines +- Want centralized control over Docker Desktop configurations +- Must meet specific compliance requirements + +## How Hardened Docker Desktop works + +Hardened Docker Desktop features work independently and together to create a defense-in-depth security strategy. They protect developer workstations against attacks across multiple layers, including Docker Desktop configuration, container image management, and container runtime security: + +- Registry Access Management and Image Access Management prevent access to unauthorized container registries and image types, reducing exposure to malicious payloads +- Enhanced Container Isolation runs containers without root privileges inside a Linux user namespace, limiting the impact of malicious containers +- Air-gapped containers let you configure network restrictions for containers, preventing malicious containers from accessing your organization's internal network resources +- Namespace access controls whether organization members can push content to their personal Docker Hub namespaces, preventing accidental publication of images outside approved locations +- Settings Management locks down Docker Desktop configurations to enforce company policies and prevent developers from introducing insecure settings, whether intentionally or accidentally + +## Next steps + +Explore Hardened Docker Desktop features to understand how they can strengthen your organization's security posture: + +{{< grid >}} diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md similarity index 80% rename from content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md rename to content/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md index 70393db82b0a..44a142efd61f 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md @@ -4,6 +4,7 @@ description: Restrict outbound container traffic using proxy rules, PAC files, a keywords: air gapped containers, network security, proxy configuration, container isolation, docker desktop, PAC file, network isolation aliases: - /security/for-admins/hardened-desktop/air-gapped-containers/ + - /enterprise/security/hardened-desktop/air-gapped-containers/ weight: 30 --- @@ -23,16 +24,17 @@ Use air-gapped containers if: ## How air-gapped containers work -Air-gapped containers operate by intercepting container network traffic and applying proxy rules: +`containersProxy` governs two distinct traffic paths: -1. Traffic interception: Docker Desktop intercepts all outgoing network connections from containers -1. Port filtering: Only traffic on specified ports (`transparentPorts`) is subject to proxy rules -1. Rule evaluation: PAC file rules or static proxy settings determine how to handle each connection -1. Connection handling: Traffic is allowed directly, routed through a proxy, or blocked based on the rules +- Image pulls (always enforced): Docker Desktop hardwires `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup, so all `docker pull` and Compose pull operations always go through `containersProxy`, including any PAC file rules. +- Running container outbound traffic (opt-in): Docker Desktop intercepts container TCP connections and applies proxy rules only for ports listed in `transparentPorts`. Without it, running container traffic bypasses `containersProxy` entirely. -Some important considerations include: +> [!IMPORTANT] +> +> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted. + +Other considerations: -- The existing `proxy` setting continues to apply to Docker Desktop application traffic on the host - If PAC file download fails, containers block requests to target URLs - Hostname is available for ports 80 and 443, but only IP addresses for other ports @@ -40,13 +42,13 @@ Some important considerations include: Before configuring air-gapped containers, you must have: -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) enabled to ensure users authenticate with your organization +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) enabled to ensure users authenticate with your organization - A Docker Business subscription -- Configured [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) with the `admin-settings.json` file to manage organization policies +- Configured [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) with the `admin-settings.json` file to manage organization policies ## Configure air-gapped containers -Add the container proxy to your [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md). For example: +Add the container proxy to your [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md). For example: ```json { @@ -65,7 +67,7 @@ Add the container proxy to your [`admin-settings.json` file](/manuals/enterprise ### Configuration parameters -The `containersProxy` setting controls network policies applied to container traffic: +The `containersProxy` setting controls network policies applied to `docker image pull` and, when `transparentPorts` is configured, running container outbound traffic: | Parameter | Description | Value | |-----------|-------------|-------| @@ -139,10 +141,11 @@ function FindProxyForURL(url, host) { ### General considerations - `FindProxyForURL` function URL parameter format is `http://host_or_ip:port` or `https://host_or_ip:port` - - If you have an internal container trying to access `https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers` the Docker proxy service will submit docs.docker.com for the host value and https://docs.docker.com:443 for the url value to `FindProxyForURL`, if you are using `shExpMatch` function in your PAC file as follows: + - If you have an internal container trying to access `https://docs.docker.com//desktop/enterprise/hardened-desktop/air-gapped-containers` the Docker proxy service will submit docs.docker.com for the host value and https://docs.docker.com:443 for the URL value to `FindProxyForURL`, if you are using `shExpMatch` function in your PAC file as follows: + <!-- vale off --> ```console - if(shExpMatch(url, "https://docs.docker.com:443/enterprise/security/*")) return "DIRECT"; + if(shExpMatch(url, "https://docs.docker.com:443//desktop/enterprise/hardened-desktop/*")) return "DIRECT"; ``` `shExpMatch` function will fail, instead use: @@ -150,6 +153,7 @@ function FindProxyForURL(url, host) { ```console if (host == docs.docker.com && url.indexOf(":443") > 0) return "DIRECT"; ``` + <!-- vale on --> ### PAC file return values @@ -226,5 +230,5 @@ $ docker run --rm alpine wget -O- https://docker.io ## Next steps -- [Explore Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) to further restrict what containers can do at runtime +- [Explore Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) to further restrict what containers can do at runtime - [Understand how Docker Desktop handles host and container networking](/manuals/desktop/features/networking/_index.md) \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md new file mode 100644 index 000000000000..03afd118fcbb --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md @@ -0,0 +1,216 @@ +--- +title: Enhanced Container Isolation +linkTitle: Enhanced Container Isolation +description: Enhanced Container Isolation provides additional security for Docker Desktop by preventing malicious containers from compromising the host +keywords: enhanced container isolation, container security, sysbox runtime, linux user namespaces, hardened desktop +aliases: + - /desktop/hardened-desktop/enhanced-container-isolation/ + - /security/for-admins/hardened-desktop/enhanced-container-isolation/ + - /enterprise/security/hardened-desktop/enhanced-container-isolation/ +weight: 10 +--- + +{{< summary-bar feature_name="Hardened Docker Desktop" >}} + +Enhanced Container Isolation (ECI) prevents malicious containers from compromising Docker Desktop or the host system. It applies advanced security techniques automatically while maintaining full developer productivity and workflow compatibility. + +- ECI strengthens container isolation and locks in security configurations created by administrators, such as [Registry Access Management policies](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) and [Settings Management](../settings-management/_index.md) controls. +- ECI works alongside other Docker security features like reduced Linux capabilities, seccomp, and AppArmor. + +If you are using WSL2 backend, ensure you’re running WSL version 2.6 or later. This is required because ECI depends on a Linux kernel version of at least 6.3.0, and WSL 2.6+ includes kernel version 6.6. + +## Who should use Enhanced Container Isolation? + +ECI is designed for: + +- Organizations that want to prevent container-based attacks and reduce security vulnerabilities in developer environments +- Security teams that need stronger container isolation without impacting developer workflows +- Enterprises that require additional protection when running untrusted or third-party container images + +## How Enhanced Container Isolation works + +Docker implements ECI using the [Sysbox container runtime](https://github.com/nestybox/sysbox), a +security-enhanced fork of the standard OCI runc runtime. When ECI is turned on, containers created through `docker run` or `docker create` automatically use Sysbox instead of runc without requiring any changes to developer workflows. Docker's default runtime remains runc, but all user containers +implicitly launch with Sysbox. + +When ECI is turned on, the Docker CLI `--runtime` flag is ignored. Even containers using the `--privileged` flag run securely with ECI, preventing them from breaching the Docker Desktop virtual machine or other containers. + +## Key security features + +### Linux user namespace isolation + +With Enhanced Container Isolation, all containers leverage Linux user namespaces for stronger isolation. Container root users map to unprivileged users in the Docker Desktop VM: + +```console +$ docker run -it --rm --name=first alpine +/ # cat /proc/self/uid_map + 0 100000 65536 +``` + +This output shows that container root (0) maps to unprivileged user 100000 in the VM, with a range of 64K user IDs. Each container gets exclusive mappings: + +```console +$ docker run -it --rm --name=second alpine +/ # cat /proc/self/uid_map + 0 165536 65536 +``` + +Without Enhanced Container Isolation, containers run as true root: + +```console +$ docker run -it --rm alpine +/ # cat /proc/self/uid_map + 0 0 4294967295 +``` + +By using Linux user namespaces, ECI ensures container processes never run with valid user IDs in the Linux VM, constraining their capabilities to resources within the container only. + +### Secured privileged containers + +Privileged containers (`docker run --privileged`) normally pose significant security risks because they provide unrestricted access to the Linux kernel. Without ECI, privileged containers can: + +- Run as true root with all capabilities +- Bypass seccomp and AppArmor restrictions +- Access all hardware devices +- Modify global kernel settings + +Organizations securing developer environments face challenges with privileged containers because they can gain control of the Docker Desktop VM and alter security settings like registry access management and network proxies. + +Enhanced Container Isolation transforms privileged containers by ensuring they can only access resources within their container boundary. For example, privileged containers can't access Docker Desktop's network configuration: + +```console +$ docker run --privileged djs55/bpftool map show +Error: can't get next map: Operation not permitted +``` + +Without ECI, privileged containers can easily access and modify these settings: + +```console +$ docker run --privileged djs55/bpftool map show +17: ringbuf name blocked_packets flags 0x0 + key 0B value 0B max_entries 16777216 memlock 0B +18: hash name allowed_map flags 0x0 + key 4B value 4B max_entries 10000 memlock 81920B +``` + +Advanced container workloads like Docker-in-Docker and Kubernetes-in-Docker still work with ECI but run much more securely. + +> [!NOTE] +> +> ECI doesn't prevent users from running privileged containers, but makes them secure by containing their access. Privileged workloads that modify global kernel settings (loading kernel modules, changing Berkeley Packet Filter settings) receive "permission denied" errors. + +### Namespace isolation enforcement + +Enhanced Container Isolation prevents containers from sharing Linux namespaces with the Docker Desktop VM, maintaining isolation boundaries: + +**PID namespace sharing blocked:** + +```console +$ docker run -it --rm --pid=host alpine +docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share namespaces [pid] with the host (because they use the linux user-namespace for isolation): unknown. +``` + +**Network namespace sharing blocked:** + +```console +$ docker run -it --rm --network=host alpine +docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown. +``` + +**User namespace override ignored:** + +```console +$ docker run -it --rm --userns=host alpine +/ # cat /proc/self/uid_map + 0 100000 65536 +``` + +Docker build operations using `--network-host` and Docker Buildx entitlements (`network.host`, +`security.insecure`) are also blocked. + +### Protected bind mounts + +Enhanced Container Isolation maintains support for standard file sharing while preventing access to sensitive VM directories: + +Host directory mounts continue to work: + +```console +$ docker run -it --rm -v $HOME:/mnt alpine +/ # ls /mnt +# Successfully lists home directory contents +``` + +VM configuration mounts are blocked: + +```console +$ docker run -it --rm -v /etc/docker/daemon.json:/mnt/daemon.json alpine +docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: can't mount /etc/docker/daemon.json because it's configured as a restricted host mount: unknown +``` + +This prevents containers from reading or modifying Docker Engine configurations, registry access management settings, proxy configurations, and other security-related VM files. + +> [!NOTE] +> +> By default, ECI blocks bind mounting the Docker Engine socket (/var/run/docker.sock) as this would grant containers control over Docker Engine. Administrators can create exceptions for trusted container images. + +### Advanced system call protection + +Enhanced Container Isolation intercepts sensitive system calls to prevent containers from using legitimate capabilities maliciously: + +```console +$ docker run -it --rm --cap-add SYS_ADMIN -v $HOME:/mnt:ro alpine +/ # mount -o remount,rw /mnt /mnt +mount: permission denied (are you root?) +``` + +Even with `CAP_SYS_ADMIN` capability, containers can't change read-only bind mounts to read-write, ensuring they can't breach container boundaries. + +Containers can still create internal mounts within their filesystem: + +```console +/ # mkdir /root/tmpfs +/ # mount -t tmpfs tmpfs /root/tmpfs +/ # mount -o remount,ro /root/tmpfs /root/tmpfs +/ # findmnt | grep tmpfs +├─/root/tmpfs tmpfs tmpfs ro,relatime,uid=100000,gid=100000 +``` + +ECI performs system call filtering efficiently by intercepting only control-path system calls (rarely used) while leaving data-path system calls unaffected, maintaining container performance. + +### Automatic filesystem user ID mapping + +Enhanced Container Isolation solves file sharing challenges between containers with different user ID ranges through automatic filesystem mapping. + +Each container gets exclusive user ID mappings, but Sysbox uses filesystem user ID remapping via Linux kernel ID-mapped mounts (added in 2021) or alternative shiftsfs module. This maps filesystem accesses from containers' real user IDs to standard ranges, enabling: + +- Volume sharing across containers with different user ID ranges +- Consistent file ownership regardless of container user ID mappings +- Transparent file access without user intervention + +### Information hiding through filesystem emulation + +ECI emulates portions of `/proc` and `/sys` filesystems within containers to hide sensitive host information and provide per-container views of kernel resources: + +```console +$ docker run -it --rm alpine +/ # cat /proc/uptime +5.86 5.86 +``` + +This shows container uptime instead of Docker Desktop VM uptime, preventing system information from leaking into containers. + +Several `/proc/sys` resources that aren't namespaced by the Linux kernel are emulated per-container, with Sysbox coordinating values when programming kernel settings. This enables container workloads that normally require privileged access to run securely. + +## Performance and compatibility + +Enhanced Container Isolation maintains optimized performance and full compatibility: + +- No performance impact: System call filtering targets only control-path calls, leaving data-path operations unaffected +- Full workflow compatibility: Existing development processes, tools, and container images work unchanged +- Advanced workload support: Docker-in-Docker, Kubernetes-in-Docker, and other complex scenarios work securely +- Automatic management: User ID mappings, filesystem access, and security policies are handled automatically +- Standard image support: No special container images or modifications required + +> [!IMPORTANT] +> +> ECI protection varies by Docker Desktop version and doesn't yet protect extension containers. Docker builds and Kubernetes in Docker Desktop have varying protection levels depending on the version. For details, see [Enhanced Container Isolation limitations](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md). diff --git a/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md new file mode 100644 index 000000000000..6745e3249615 --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md @@ -0,0 +1,283 @@ +--- +title: Configure Docker socket exceptions and advanced settings +linkTitle: Configure advanced settings +description: Configure Docker socket exceptions and advanced settings for Enhanced Container Isolation +keywords: enhanced container isolation, docker socket, configuration, testcontainers, admin settings +aliases: + - /security/for-admins/hardened-desktop/enhanced-container-isolation/config/ + - /enterprise/security/hardened-desktop/enhanced-container-isolation/config/ +weight: 20 +--- + +{{< summary-bar feature_name="Hardened Docker Desktop" >}} + +This page shows you how to configure Docker socket exceptions and other advanced settings for Enhanced Container Isolation (ECI). These configurations enable trusted tools like Testcontainers to work with ECI while maintaining security. + +## Docker socket mount permissions + +By default, Enhanced Container Isolation blocks containers from mounting the Docker socket to prevent malicious access to Docker Engine. However, some tools require Docker socket access. + +Common scenarios requiring Docker socket access include: + +- Testing frameworks: Testcontainers, which manages test containers +- Build tools: Paketo buildpacks that create ephemeral build containers +- CI/CD tools: Tools that manage containers as part of deployment pipelines +- Development utilities: Docker CLI containers for container management + +## Configure socket exceptions + +Configure Docker socket exceptions using Settings Management: + +{{< tabs >}} +{{< tab name="Docker Home" >}} + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. +1. Select **Docker Desktop**, then **Settings Management**. +1. [Create or edit a setting policy](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md). +1. Find **Enhanced Container Isolation** settings. +1. Configure **Docker socket access control** with your trusted images and +command restrictions. + +{{< /tab >}} +{{< tab name="JSON file" >}} + +Create an [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md) and add: + +```json +{ + "configurationFileVersion": 2, + "enhancedContainerIsolation": { + "locked": true, + "value": true, + "dockerSocketMount": { + "imageList": { + "images": [ + "docker.io/localstack/localstack:*", + "docker.io/testcontainers/ryuk:*", + "docker:cli" + ], + "allowDerivedImages": true + }, + "commandList": { + "type": "deny", + "commands": ["push", "build"] + } + } + } +} +``` + +{{< /tab >}} +{{< /tabs >}} + +## Image allowlist configuration + +The `imageList` defines which container images can mount the Docker socket. + +### Image reference formats + +| Format | Description | +| :---------------------- | :---------- | +| `<image_name>[:<tag>]` | Name of the image, with optional tag. If the tag is omitted, the `:latest` tag is used. If the tag is the wildcard `*`, then it means "any tag for that image." | +| `<image_name>@<digest>` | Name of the image, with a specific repository digest (e.g., as reported by `docker buildx imagetools inspect <image>`). This means only the image that matches that name and digest is allowed. | + +### Example configurations + +Basic allowlist for testing tools: + +```json +"imageList": { + "images": [ + "docker.io/testcontainers/ryuk:*", + "docker:cli", + "alpine:latest" + ] +} +``` + +Wildcard allowlist (Docker Desktop 4.36 and later): + +```json +"imageList": { + "images": ["*"] +} +``` + +> [!WARNING] +> +> Using `"*"` allows all containers to mount the Docker socket, which reduces security. Only use this when explicitly listing allowed images isn't feasible. + +### Security validation + +Docker Desktop validates allowed images by: + +1. Downloading image digests from registries for allowed images +1. Comparing container image digests against the allowlist when containers start +1. Blocking containers whose digests don't match allowed images + +This prevents bypassing restrictions by re-tagging unauthorized images: + +```console +$ docker tag malicious-image docker:cli +$ docker run -v /var/run/docker.sock:/var/run/docker.sock docker:cli +# This fails because the digest doesn't match the real docker:cli image +``` + +## Derived images support + +For tools like Paketo buildpacks that create ephemeral local images, you can +allow images derived from trusted base images. + +### Enable derived images + +```json +"imageList": { + "images": [ + "paketobuildpacks/builder:base" + ], + "allowDerivedImages": true +} +``` + +When `allowDerivedImages` is true, local images built from allowed base images (using `FROM` in Dockerfile) also gain Docker socket access. + +### Derived images requirements + +- Local images only: Derived images must not exist in remote registries +- Base image available: The parent image must be pulled locally first +- Performance impact: Adds up to 1 second to container startup for validation +- Version compatibility: Full wildcard support requires Docker Desktop 4.36+ + +## Command restrictions + +### Deny list (recommended) + +Blocks specified commands while allowing all others: + +```json +"commandList": { + "type": "deny", + "commands": ["push", "build", "image*"] +} +``` + +### Allow list + +Only allows specified commands while blocking all others: + +```json +"commandList": { + "type": "allow", + "commands": ["ps", "container*", "volume*"] +} +``` + +### Command wildcards + +| Wildcard | Blocks/allows | +| :---------------- | :---------- | +| `"container\*"` | All "docker container ..." commands | +| `"image\*"` | All "docker image ..." commands | +| `"volume\*"` | All "docker volume ..." commands | +| `"network\*"` | All "docker network ..." commands | +| `"build\*"` | All "docker build ..." commands | +| `"system\*"` | All "docker system ..." commands | + +### Command blocking example + +When a blocked command is executed: + +```console +/ # docker push myimage +Error response from daemon: enhanced container isolation: docker command "/v1.43/images/myimage/push?tag=latest" is blocked; if you wish to allow it, configure the docker socket command list in the Docker Desktop settings. +``` + +## Common configuration examples + +### Testcontainers setup + +For Java/Python testing with Testcontainers: + +```json +"dockerSocketMount": { + "imageList": { + "images": [ + "docker.io/testcontainers/ryuk:*", + "testcontainers/*:*" + ] + }, + "commandList": { + "type": "deny", + "commands": ["push", "build"] + } +} +``` + +### CI/CD pipeline tools + +For controlled CI/CD container management: + +```json +"dockerSocketMount": { + "imageList": { + "images": [ + "docker:cli", + "your-registry.com/ci-tools/*:*" + ] + }, + "commandList": { + "type": "allow", + "commands": ["ps", "container*", "image*"] + } +} +``` + +### Development environments + +For local development with Docker-in-Docker: + +```json +"dockerSocketMount": { + "imageList": { + "images": [ + "docker:dind", + "docker:cli" + ] + }, + "commandList": { + "type": "deny", + "commands": ["system*"] + } +} +``` + +## Security recommendations + +### Image allowlist best practices + +- Be restrictive: Only allow images you absolutely trust and need +- Use wildcards carefully: Tag wildcards (`*`) are convenient but less secure than specific tags +- Regular reviews: Periodically review and update your allowlist +- Digest pinning: Use digest references for maximum security in critical environments + +### Command restrictions + +- Default to deny: Start with a deny list blocking dangerous commands like `push` and `build` +- Principle of least privilege: Only allow commands your tools actually need +- Monitor usage: Track which commands are being blocked to refine your configuration + +### Monitoring and maintenance + +- Regular validation: Test your configuration after Docker Desktop updates, as image digests may change. +- Handle digest mismatches: If allowed images are unexpectedly blocked: + ```console + $ docker image rm <image> + $ docker pull <image> + ``` + +This resolves digest mismatches when upstream images are updated. + +## Next steps + +- Review [Enhanced Container Isolation limitations](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md). +- Review [Enhanced Container Isolation FAQs](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/faq.md). diff --git a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci.md b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/enable-eci.md similarity index 82% rename from content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci.md rename to content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/enable-eci.md index f7e65940bdb9..65a23d673133 100644 --- a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/enable-eci.md @@ -4,6 +4,8 @@ linkTitle: Enable ECI description: Enable Enhanced Container Isolation to secure containers in Docker Desktop keywords: enhanced container isolation, enable eci, container security, docker desktop setup weight: 15 +aliases: + - /enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci/ --- {{< summary-bar feature_name="Hardened Docker Desktop" >}} @@ -17,7 +19,7 @@ This page shows you how to turn on Enhanced Container Isolation (ECI) and verify Before you begin, you must have: - A Docker Business subscription -- [Enforced sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) (for administrators managing organization-wide settings only) +- [Enforced sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) (for administrators managing organization-wide settings only) ## Enable Enhanced Container Isolation @@ -47,17 +49,17 @@ a Docker Business subscription. Configure Enhanced Container Isolation organization-wide using Settings Management: {{< tabs >}} -{{< tab name="Admin Console" >}} +{{< tab name="Docker Home" >}} 1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Go to **Admin Console** > **Desktop Settings Management**. -1. [Create or edit a setting policy](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md). +1. Select **Docker Desktop**, then **Settings Management**. +1. [Create or edit a setting policy](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md). 1. Set **Enhanced Container Isolation** to **Always enabled**. {{< /tab >}} {{< tab name="JSON file" >}} -1. Create an [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md) and add: +1. Create an [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md) and add: ```json { @@ -88,7 +90,7 @@ For ECI settings to take effect: > > Restarting from the Docker Desktop menu isn't sufficient. Users must completely quit and reopen Docker Desktop. -You can also configure [Docker socket mount permissions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md) for trusted images that need Docker API access. +You can also configure [Docker socket mount permissions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md) for trusted images that need Docker API access. ## Verify Enhanced Container Isolation is active @@ -164,5 +166,5 @@ Docker Desktop settings. ## Next steps -- Review [Configure Docker socket exceptions and advanced settings](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md). -- Review [Enhanced Container Isolation limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md). +- Review [Configure Docker socket exceptions and advanced settings](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md). +- Review [Enhanced Container Isolation limitations](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md). diff --git a/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/faq.md b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/faq.md new file mode 100644 index 000000000000..06bcb90efdd5 --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/faq.md @@ -0,0 +1,86 @@ +--- +title: Enhanced Container Isolation FAQs +linkTitle: FAQs +description: Frequently asked questions about Enhanced Container Isolation +keywords: enhanced container isolation, faq, troubleshooting, docker desktop +toc_max: 2 +aliases: + - /security/for-admins/hardened-desktop/enhanced-container-isolation/faq/ + - /enterprise/security/hardened-desktop/enhanced-container-isolation/faq/ +weight: 40 +--- + +{{< summary-bar feature_name="Hardened Docker Desktop" >}} + +This page answers common questions about Enhanced Container Isolation (ECI) that aren't covered in the main documentation. + +## Do I need to change the way I use Docker when ECI is switched on? + +No. ECI works automatically in the background by creating more secure containers. You can continue using all your existing Docker commands, workflows, and development tools without any changes. + +## Do all container workloads work well with ECI? + +Most container workloads run without issues when ECI is turned on. However, some advanced workloads that require specific kernel-level access may not work. For details about which workloads are affected, see [ECI limitations](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md). + +## Why not just restrict usage of the `--privileged` flag? + +Privileged containers serve legitimate purposes like Docker-in-Docker, Kubernetes-in-Docker, and accessing hardware devices. ECI provides a better solution by allowing these advanced workloads to run securely while preventing them from compromising the Docker Desktop VM. + +## Does ECI affect container performance? + +ECI has minimal impact on container performance. The only exception is containers that perform many `mount` and `umount` system calls, as these are inspected by the Sysbox runtime for security. Most development workloads see no noticeable performance difference. + +## Can I override the container runtime with ECI turned on? + + +No. When ECI is turned on, all containers use the Sysbox runtime regardless of any `--runtime` flags: + +```console +$ docker run --runtime=runc alpine echo "test" +# This still uses sysbox-runc, not runc +``` + +The `--runtime` flag is ignored to prevent users from bypassing ECI security by running containers as true root in the Docker Desktop VM. + +## Does ECI protect containers created before turning it on? + +No. ECI only protects containers created after it's turned on. Remove existing containers before turning on ECI: + +```console +$ docker stop $(docker ps -q) +$ docker rm $(docker ps -aq) +``` + +For more details, see [Enable Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/enable-eci.md). + +## Which containers does ECI protect? + +ECI protection varies by container type and Docker Desktop version: + +### Always protected + +- Containers created with `docker run` and `docker create` +- Containers using the `docker-container` build driver +- Kubernetes with the `kind` provisioner + +### Platform dependent + +- Docker Build: Protected in Docker Desktop for Mac, Linux, and Windows with Hyper-V backend + +### Not protected + +- Docker Extensions +- Docker Debug containers +- Kubernetes with `kubeadm` provisioner + +For complete details, see [ECI limitations](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md). + +## Can I mount the Docker socket with ECI turned on? + +By default, no. ECI blocks Docker socket bind mounts for security. However, you can configure exceptions for trusted images like Testcontainers. + +For configuration details, see [Configure Docker socket exceptions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md). + +## What bind mounts does ECI restrict? + +ECI restricts bind mounts of Docker Desktop VM directories but allows host directory mounts configured in Docker Desktop Settings. diff --git a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md similarity index 93% rename from content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md rename to content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md index e7a2f63736b4..ecf411d24862 100644 --- a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/limitations.md @@ -7,6 +7,7 @@ toc_max: 3 weight: 30 aliases: - /security/for-admins/hardened-desktop/enhanced-container-isolation/limitations/ + - /enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/ --- {{< summary-bar feature_name="Hardened Docker Desktop" >}} @@ -78,7 +79,7 @@ The integrated Kubernetes feature, when used with the legacy Kubeadm provisioner ### Recommendation -Use the newer Docker Desktop Kubernetes "KinD" provisioner (see [Cluster provisioning method](/manuals/desktop/use-desktop/kubernetes.md#cluster-provisioning-method)). In this mode, and with ECI turned on, each Kubernetes node runs in an ECI-protected container, providing stronger isolation from the Docker Desktop VM. The KinD provisioner is also faster and allows for multi-node Kubernetes clusters. +Use the Docker Desktop Kubernetes `kind` provisioner (see [Cluster provisioning method](/manuals/desktop/use-desktop/kubernetes.md#cluster-provisioning-method)). In this mode, and with ECI turned on, each Kubernetes node runs in an ECI-protected container, providing stronger isolation from the Docker Desktop VM. The `kind` provisioner is also faster and allows for multi-node Kubernetes clusters. ## Unprotected container types diff --git a/content/manuals/enterprise/security/hardened-desktop/image-access-management.md b/content/manuals/desktop/enterprise/hardened-desktop/image-access-management.md similarity index 92% rename from content/manuals/enterprise/security/hardened-desktop/image-access-management.md rename to content/manuals/desktop/enterprise/hardened-desktop/image-access-management.md index 577bbe8b2030..5009f0c90f3b 100644 --- a/content/manuals/enterprise/security/hardened-desktop/image-access-management.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/image-access-management.md @@ -7,6 +7,7 @@ aliases: - /admin/organization/image-access/ - /security/for-admins/image-access-management/ - /security/for-admins/hardened-desktop/image-access-management/ + - /enterprise/security/hardened-desktop/image-access-management/ weight: 50 --- @@ -44,8 +45,8 @@ Use the repository allowlist when you need to: Before configuring Image Access Management, you must: -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). Image Access Management only takes effect when users are signed in to Docker Desktop with organization credentials. -- Use [personal access tokens (PATs)](/manuals/security/access-tokens.md) for authentication (Organization access tokens aren't supported) +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). Image Access Management only takes effect when users are signed in to Docker Desktop with organization credentials. +- Use [personal access tokens (PATs)](/manuals/security/access-tokens/personal-access-tokens.md) for authentication (Organization access tokens aren't supported) - Have a Docker Business subscription ## Configure image access @@ -57,7 +58,7 @@ Before configuring Image Access Management, you must: To configure Image Access Management: 1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **Image access**. +1. Select **Docker Desktop**, then **Image Access**. 1. Use the **toggle** to enable image access. 1. Select which image types to allow: - **Organization images**: Images from your organization (always allowed by default). These can be public or private images created by members within your organization. @@ -109,7 +110,7 @@ Image access restrictions apply to all Docker Hub operations including pulls, bu ## Scope and bypass considerations -- Image Access Management only controls access to Docker Hub images. Images from other registries aren't affected by these policies. Use [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) to control access to other registries. +- Image Access Management only controls access to Docker Hub images. Images from other registries aren't affected by these policies. Use [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) to control access to other registries. - Users can potentially bypass Image Access Management by signing out of Docker Desktop (unless sign-in is enforced), using images from other registries that aren't restricted, or using registry mirrors or proxies. Enforce sign-in and combine with Registry Access Management for comprehensive control. - Image restrictions apply to Dockerfile `FROM` instructions, Docker Compose services using restricted images will fail, multi-stage builds may be affected if intermediate images are restricted, and CI/CD pipelines using diverse image types may be impacted. diff --git a/content/manuals/enterprise/security/hardened-desktop/namespace-access.md b/content/manuals/desktop/enterprise/hardened-desktop/namespace-access.md similarity index 94% rename from content/manuals/enterprise/security/hardened-desktop/namespace-access.md rename to content/manuals/desktop/enterprise/hardened-desktop/namespace-access.md index b40593eeea9f..477b38d25243 100644 --- a/content/manuals/enterprise/security/hardened-desktop/namespace-access.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/namespace-access.md @@ -5,6 +5,8 @@ description: Control whether organization members can push content to their pers keywords: namespace access, docker hub, personal namespace, organization security, docker business tags: [admin] weight: 60 +aliases: + - /enterprise/security/hardened-desktop/namespace-access/ --- {{< summary-bar feature_name="Namespace access" >}} @@ -31,7 +33,7 @@ To configure namespace access control: 1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. -2. Select **Admin Console**, then **Namespace access**. +2. Select **Docker Desktop**, then **Namespace access**. 3. Use the toggle to enable or disable namespace access control. 4. Select **Save changes**. diff --git a/content/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md b/content/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md new file mode 100644 index 000000000000..2ddfd3ed8ed7 --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md @@ -0,0 +1,169 @@ +--- +title: Registry Access Management +linkTitle: Registry Access Management +description: Control which container registries developers can access through + Docker Desktop with Registry Access Management. +keywords: registry access management, RAM, container registry allowlist, Docker + Desktop security, Docker Business, admin controls, DNS filtering, registry + permissions, hardened desktop +tags: [admin] +aliases: + - /admin/organization/registry-access/ + - /security/for-admins/registry-access-management/ + - /security/for-admins/hardened-desktop/registry-access-management/ + - /docker-hub/registry-access-management/ + - /enterprise/security/hardened-desktop/registry-access-management/ +weight: 40 +--- + +{{< summary-bar feature_name="Registry access management" >}} + +Registry Access Management (RAM) lets administrators control which container +registries developers can access through Docker Desktop. This DNS-level +filtering limits pulls and pushes to approved registries. + +RAM works with cloud registries, on-premises registries, and registry mirrors. +You can allow any hostname or domain, but you must also include redirect +domains (for example, `s3.amazonaws.com` for some registries) in your +allowlist. + +## Supported registries + +Registry Access Management works with any container registry, including: + +- Docker Hub (allowed by default) +- Cloud registries: Amazon ECR, Google Artifact Registry, Azure Container + Registry +- Git-based registries: GitHub Container Registry, GitLab Container Registry +- On-premises solutions: Nexus, Artifactory, Harbor +- Registry mirrors: Including Docker Hub mirrors + +## Prerequisites + +Before configuring Registry Access Management, you must: + +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + Registry Access Management only takes effect when users are signed in to + Docker Desktop with organization credentials. +- Use + [Organization access tokens (OATs)](/manuals/security/access-tokens/organization-access-tokens.md) + for authentication +- Have a Docker Business subscription + +## Configure registry permissions + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization from the top-left account drop-down. +1. Select **Docker Desktop**, then **Registry Access**. +1. Use the toggle to turn on registry access. By default, Docker Hub is + enabled in the registry list. +1. To add registries, select **Add registry** and provide a **Registry + address** and **Registry nickname**. +1. Select **Create**. You can add up to 100 registries. +1. Verify your registry appears in the registry list and select **Save + changes**. + +> [!NOTE] +> +> Policy changes can take up to 24 hours to propagate. To apply changes +> immediately, ask developers to sign out and back in to Docker Desktop. + +If a developer belongs to multiple organizations with different RAM policies, +only the policy for the first organization in the configuration file is +enforced. + +> [!TIP] +> +> RAM restrictions also apply to Dockerfile `ADD` instructions that fetch +> content by URL. Include trusted registry domains in your allowlist when +> using `ADD` with URLs. +> +> RAM is designed for container registries, not general-purpose URLs such as +> package mirrors or storage services. Adding too many domains may cause +> errors or hit system limits. + +## Verify restrictions are working + +After users sign in to Docker Desktop with their organization credentials, +Registry Access Management takes effect immediately. + +When users try to pull from a blocked registry: + +```console +$ docker pull blocked-registry.com/image:tag +Error response from daemon: registry access to blocked-registry.com is not allowed +``` + +Allowed registry access works normally: + +```console +$ docker pull allowed-registry.com/image:tag +# Pull succeeds +``` + +Registry restrictions apply to all Docker operations including pulls, pushes, +and builds that reference external registries. + +## Registry limits and platform constraints + +Registry Access Management has these limits and platform-specific behaviors: + +- Maximum allowlist size: 100 registries or domains per organization +- DNS-based filtering: Restrictions work at the hostname level, not IP + addresses +- Redirect domains required: Include all domains a registry redirects to (CDN + endpoints, storage services) +- Windows containers: Windows image operations aren't restricted by default. + Turn on **Use proxy for Windows Docker daemon** in Docker Desktop settings + to apply restrictions +- WSL 2 requirements: Requires Linux kernel 5.4 or later. Restrictions apply + to all WSL 2 distributions + +## Build and deployment restrictions + +These scenarios aren't restricted by Registry Access Management: + +- Docker Buildx with the Kubernetes driver +- Docker Buildx with a custom Docker-container driver +- Some Docker Debug and Kubernetes image pulls (even if Docker Hub is blocked) +- Images previously cached by registry mirrors may still be blocked if the + source registry is restricted + +## Security bypass considerations + +Users can potentially bypass Registry Access Management through: + +- Local proxies or DNS manipulation +- Signing out of Docker Desktop (unless sign-in is enforced) +- Network-level modifications outside Docker Desktop's control + +To maximize security effectiveness: + +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) to + prevent bypass through sign-out +- Implement additional network-level controls for complete protection +- Use Registry Access Management as part of a broader security strategy + +## Registry allowlist best practices + +- Include all registry domains. Some registries redirect to multiple domains. + For AWS ECR, include: + + ```text + your-account.dkr.ecr.us-west-2.amazonaws.com + amazonaws.com + s3.amazonaws.com + ``` + +- Maintain the allowlist regularly: + - Remove unused registries periodically + - Add newly approved registries as needed + - Update domain names that may have changed + - Monitor registry usage through Docker Desktop analytics +- Test configuration changes: + - Verify registry access after allowlist updates + - Confirm all necessary redirect domains are included + - Ensure development workflows aren't disrupted +- Combine with + [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) + for broader Desktop security diff --git a/content/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md new file mode 100644 index 000000000000..565c3cd2c3ee --- /dev/null +++ b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md @@ -0,0 +1,120 @@ +--- +description: Understand how Settings Management works, who it's for, and the benefits it provides +keywords: Settings Management, rootless, docker desktop, hardened desktop, admin control, enterprise +tags: [admin] +title: Settings Management +linkTitle: Settings Management +aliases: + - /security/for-admins/hardened-desktop/settings-management/ + - /enterprise/security/hardened-desktop/settings-management/ +weight: 10 +--- + +{{< summary-bar feature_name="Hardened Docker Desktop" >}} + +Settings Management lets administrators configure and enforce Docker Desktop settings across end-user machines. It helps maintain consistent configurations and enhances security within your organization. + +## Who should use Settings Management? + +Settings Management is designed for organizations that: + +- Need centralized control over Docker Desktop configurations +- Want to standardize Docker Desktop environments across teams +- Operate in regulated environments and must enforce compliance policies + +## How Settings Management works + +Administrators can define settings using one of these methods: + +- [Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md): Create and assign settings policies via Docker Home. This provides a web-based interface for managing settings + across your organization. +- [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md): Place a configuration file on the + user's machine to enforce settings. This method works well for automated + deployments and scripted installations. + +Enforced settings override user-defined configurations and can't be modified by developers. + +## Configurable settings + +Settings Management supports a wide range of Docker Desktop features, including: + +- Proxy configurations +- Network settings +- Container isolation options +- Registry access controls +- Resource limits +- Security policies +- Cloud policies + +For a complete list of settings you can enforce, see the [Settings reference](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md). + +## Policy precedence + +When multiple policies exist, Docker Desktop applies them in this order: + +1. User-specific policies: Highest priority +1. Organization default policy: Applied when no user-specific policy exists +1. Local `admin-settings.json` file: Lowest priority, overridden by Docker Home policies +1. [Configuration profiles](/manuals/desktop/enterprise/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) when used to control proxy settings + +## Set up Settings Management + +You can create settings management policies at any time, but your organization needs to verify a domain before the policies take effect. + +1. Check that you have [added and verified](/manuals/security/provisioning/domain-management.md#add-and-verify-a-domain) your organization's domain. +2. [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) to + ensure all developers authenticate with your organization. +3. Choose a configuration method: + - Use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json`. + - Manually create and configure the [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md). + - Create a settings policy in the [Docker Home](configure-admin-console.md). + +After configuration, developers receive the enforced settings when they: + +- Quit and relaunch Docker Desktop, then sign in +- Launch and sign in to Docker Desktop for the first time + +> [!NOTE] +> +> Docker Desktop doesn't automatically prompt users to restart or re-authenticate after a settings change. You may need to communicate these requirements to your developers. + +## Developer experience + +When settings are enforced: + +- Settings options appear grayed out in Docker Desktop and can't be modified through the Dashboard, CLI, or configuration files +- If Enhanced Container Isolation is enabled, developers can't use privileged containers or similar methods to alter enforced settings within the Docker Desktop Linux VM + +This ensures consistent environments while maintaining a clear visual indication of which settings are managed by administrators. + +## View applied settings + +When administrators apply Settings Management policies, Docker Desktop greys out most enforced settings in the GUI. + +The Docker Desktop GUI doesn't currently display all centralized settings, +particularly Enhanced Container Isolation (ECI) settings that administrators +apply via Docker Home. + +As a workaround, you can check the `settings-store.json` file to view all +applied settings: + +- Mac: `~/Library/Application Support/Docker/settings-store.json` +- Windows: `%APPDATA%\Docker\settings-store.json` +- Linux: `~/.docker/desktop/settings-store.json` + +The `settings-store.json` file contains all settings, including those that +may not appear in the Docker Desktop GUI. + +## Limitations + +Settings Management has the following limitations: + +- Doesn't work in air-gapped or offline environments +- Not compatible with environments that restrict authentication with Docker Hub + +## Next steps + +Get started with Settings Management: + +- [Configure Settings Management with the `admin-settings.json` file](configure-json-file.md) +- [Configure Settings Management with Docker Home](configure-admin-console.md) diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/compliance-reporting.md b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/compliance-reporting.md similarity index 88% rename from content/manuals/enterprise/security/hardened-desktop/settings-management/compliance-reporting.md rename to content/manuals/desktop/enterprise/hardened-desktop/settings-management/compliance-reporting.md index 40c4d2554753..ad963eb11e04 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/compliance-reporting.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/compliance-reporting.md @@ -2,10 +2,11 @@ title: Desktop settings reporting linkTitle: Desktop settings reporting description: Track and monitor user compliance with Docker Desktop settings policies using the reporting dashboard -keywords: settings management, compliance reporting, admin console, policy enforcement, docker desktop +keywords: settings management, compliance reporting, docker home, policy enforcement, docker desktop weight: 30 aliases: - /security/for-admins/hardened-desktop/settings-management/compliance-reporting/ + - /enterprise/security/hardened-desktop/settings-management/compliance-reporting/ --- {{< summary-bar feature_name="Compliance reporting" >}} @@ -17,8 +18,8 @@ Desktop settings reporting tracks user compliance with Docker Desktop settings p Before you can use Docker Desktop settings reporting, make sure you have: - [Docker Desktop](/manuals/desktop/release-notes.md) installed across your organization -- [A verified domain](/manuals/enterprise/security/single-sign-on/connect.md) -- [Enforced sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) for your organization +- [A verified domain](/manuals/security/authentication/single-sign-on/connect.md) +- [Enforced sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for your organization - A Docker Business subscription - At least one settings policy configured @@ -28,7 +29,7 @@ To view compliance reporting: 1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -1. Select **Admin Console**, then **Desktop settings reporting**. +1. Select **Docker Desktop**, then **Settings Reporting**. The reporting dashboard provides these tools: @@ -118,4 +119,4 @@ Docker Desktop checks for policy updates: - Every 60 minutes while Docker Desktop is running - When users restart Docker Desktop -Changes to policies in the Admin Console are available immediately, but users must restart Docker Desktop to apply them. +Changes to policies in Docker Home are available immediately, but users must restart Docker Desktop to apply them. diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md similarity index 75% rename from content/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md rename to content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md index e9c3589e8fad..551e43856480 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md @@ -1,24 +1,25 @@ --- -title: Configure Settings Management with the Admin Console -linkTitle: Use the Admin Console -description: Configure and enforce Docker Desktop settings across your organization using the Docker Admin Console -keywords: admin console, settings management, policy configuration, enterprise controls, docker desktop +title: Configure Settings Management in Docker Home +linkTitle: Use Docker Home +description: Configure and enforce Docker Desktop settings across your organization in Docker Home +keywords: docker home, settings management, policy configuration, enterprise controls, docker desktop weight: 20 aliases: - /security/for-admins/hardened-desktop/settings-management/configure-admin-console/ + - /enterprise/security/hardened-desktop/settings-management/configure-admin-console/ --- {{< summary-bar feature_name="Admin Console" >}} -Use the Docker Admin Console to create and manage settings policies for Docker Desktop across your organization. Settings policies let you standardize configurations, enforce security requirements, and maintain consistent Docker Desktop environments. +Use Docker Home to create and manage settings policies for Docker Desktop across your organization. Settings policies let you standardize configurations, enforce security requirements, and maintain consistent Docker Desktop environments. ## Prerequisites Before you begin, make sure you have: - [Docker Desktop](/manuals/desktop/release-notes.md) installed -- [A verified domain](/enterprise/security/single-sign-on/connect/#step-1-add-a-domain) -- [Enforced sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) for your organization +- [A verified domain](/security/authentication/single-sign-on/connect/#step-1-add-a-domain) +- [Enforced sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for your organization - A Docker Business subscription > [!IMPORTANT] @@ -31,14 +32,14 @@ To create a new settings policy: 1. Sign in to [Docker Home](https://app.docker.com/) and select your organization. -1. Select **Admin Console**, then **Desktop Settings Management**. +1. Select **Docker Desktop**, then **Settings Management**. 1. Select **Create a settings policy**. 1. Provide a name and optional description. > [!TIP] > > You can upload an existing `admin-settings.json` file to pre-fill the form. - > Admin Console policies override local `admin-settings.json` files. + > Docker Home policies override local `admin-settings.json` files. 1. Choose who the policy applies to: - All users @@ -50,7 +51,7 @@ To create a new settings policy: 1. Configure each setting using a state: - | Admin Console state | Description | `admin-settings.json` equivalent | + | Docker Home state | Description | `admin-settings.json` equivalent | | :------------------ | :--------------------------------- |:---------------------------------- | | **User-defined** | Users can change the setting | Omit the setting | | **Always enabled** | Setting is on and locked | `"value": true`, `"locked": true` | @@ -96,7 +97,7 @@ After you apply policies: ## Manage existing policies -From the **Desktop Settings Management** page in the Admin Console, use the **Actions** menu to: +From the **Desktop Settings Management** page in Docker Home, use the **Actions** menu to: - Edit or delete an existing settings policy - Export a settings policy as an `admin-settings.json` file diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md similarity index 94% rename from content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md rename to content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md index 30267310a64f..26e3810e0727 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md @@ -7,6 +7,7 @@ weight: 10 aliases: - /security/for-admins/hardened-desktop/settings-management/configure/ - /security/for-admins/hardened-desktop/settings-management/configure-json-file/ + - /enterprise/security/hardened-desktop/settings-management/configure-json-file/ --- {{< summary-bar feature_name="Hardened Docker Desktop" >}} @@ -17,7 +18,7 @@ Settings Management lets you configure and enforce Docker Desktop settings acros Before you begin, make sure you have: -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) for +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for your organization - A Docker Business subscription @@ -297,7 +298,7 @@ The following tables describe all available settings in the `admin-settings.json | Parameter | OS | Description | Version | | :----------------------------------- | ---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `filesharingAllowedDirectories` | | Specify which paths your developers can add file shares to. Also accepts `$HOME`, `$TMP`, or `$TEMP` as `path` variables. When a path is added, its subdirectories are allowed. If `sharedByDefault` is set to `true`, that path will be added upon factory reset or when Docker Desktop first starts. | | -| `useVirtualizationFrameworkVirtioFS` | macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. Likewise, if both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `false`, osxfs is set as the file sharing mechanism. | | +| `useVirtualizationFrameworkVirtioFS` | macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. If both are set to `false`, Docker Desktop fails to start with an error, as at least one file sharing mechanism must be enabled. | | | `useGrpcfuse` | macOS only | If `value` is set to `true`, gRPC Fuse is set as the file sharing mechanism. | | | `useVirtualizationFrameworkRosetta` | macOS only | If `value` is set to `true`, Docker Desktop turns on Rosetta to accelerate x86_64/amd64 binary emulation on Apple Silicon. Note: This also automatically enables `Use Virtualization framework`. | | @@ -309,6 +310,11 @@ The following tables describe all available settings in the `admin-settings.json ### Proxy settings +Docker Desktop has two distinct proxy settings with different scopes: + +- `proxy` (App Proxy): Governs Docker Desktop host-level traffic — the Desktop application, Docker CLI, and extensions. It also serves as a fallback for the daemon when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic. +- [`containersProxy`](#container-proxy): Always governs `docker image pull`. All `docker image pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured. + | Parameter | OS | Description | Version | | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `proxy` | | If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores any values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. | | @@ -321,18 +327,18 @@ The following tables describe all available settings in the `admin-settings.json > > Proxy configuration is a special case because it must be configured in two places: > -> 1. In the Admin Console for your organization. +> 1. In Docker Home for your organization. > 2. On the user's system where Docker Desktop is installed. > > On the user's machine, configure the proxy either through the `admin-settings.json` file or by using installer flags during Docker Desktop installation. For detailed instructions, refer to the [installation guide](/manuals/desktop/setup/install/windows-install.md#proxy-configuration). > -> This additional configuration is required because Docker Desktop must know which proxy server to use before it can complete user sign-in and retrieve organization settings from the Admin Console. +> This additional configuration is required because Docker Desktop must know which proxy server to use before it can complete user sign-in and retrieve organization settings from Docker Home. ### Container proxy | Parameter | OS | Description | Version | | :---------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -| `containersProxy` | | Creates air-gapped containers. For more information see [Air-Gapped Containers](../air-gapped-containers.md). | | +| `containersProxy` | | Configures the proxy for `docker image pull` (always enforced) and running container outbound traffic (enforced when `transparentPorts` is set). For more information see [Air-Gapped Containers](../air-gapped-containers.md). | | | `pac` | | Specifies a PAC file URL. For example, `"pac": "http://containerproxy/proxy.pac"`. | | | `embeddedPac` | | Specifies an embedded PAC (Proxy Auto-config) script. For example, `"embeddedPac": "function FindProxyForURL(url, host) { return \"PROXY 192.168.92.1:2003\"; }"`. This setting takes precedence over HTTP, HTTPS, Proxy bypass and PAC server URL. | | @@ -354,7 +360,7 @@ The following tables describe all available settings in the `admin-settings.json > [!NOTE] > -> This setting is not available to configure via the Docker Admin Console. +> This setting is not available to configure via Docker Home. ### Kubernetes settings @@ -400,8 +406,8 @@ For more information, see [Networking](/manuals/desktop/features/networking.md#n | Parameter | OS | Description | Version | | :-------------------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `allowBetaFeatures` | | If `value` is set to `true`, beta features are enabled. | | -| `enableDockerAI` | | If `allowBetaFeatures` is true, setting `enableDockerAI` to `true` enables [Gordon](/manuals/ai/gordon/_index.md) by default. You can independently control this setting from the `allowBetaFeatures` setting. | | -| `enableDockerMCPToolkit` | | If `allowBetaFeatures` is true, setting `enableDockerMCPToolkit` to `true` enables the [MCP Toolkit feature](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) by default. You can independently control this setting from the `allowBetaFeatures` setting. | | +| `enableDockerAI` | | Controls whether [Gordon](/manuals/ai/gordon/_index.md) is enabled. Accepts `true`/`false` or Business tier options (`"Disabled"`, `"Enabled"`, `"Always Enabled"`). | | +| `enableDockerMCPToolkit` | | If `allowBetaFeatures` is true, setting `enableDockerMCPToolkit` to `true` enables the [MCP Toolkit feature](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md) by default. You can independently control this setting from the `allowBetaFeatures` setting. | | | `allowExperimentalFeatures` | | If `value` is set to `true`, experimental features are enabled. | | ### Enhanced Container Isolation diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md similarity index 81% rename from content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md rename to content/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md index eb703caa9fd3..77c9be1c7928 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/content/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md @@ -6,9 +6,10 @@ keywords: docker desktop settings, configuration reference, admin controls, sett toc_max: 2 aliases: - /security/for-admins/hardened-desktop/settings-management/settings-reference/ + - /enterprise/security/hardened-desktop/settings-management/settings-reference/ --- -This reference documents Docker Desktop settings that administrators can configure using [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). Use this page to understand which settings are available, their accepted values, platform compatibility, and which configuration methods apply. +This reference documents Docker Desktop settings that administrators can configure using [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). Use this page to understand which settings are available, their accepted values, platform compatibility, and which configuration methods apply. > [!NOTE] > @@ -27,7 +28,7 @@ as sign in timestamps, pulls, or builds. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `analyticsEnabled` | -| Admin Console | **Send usage statistics** | +| Docker Home | **Send usage statistics** | > [!NOTE] > @@ -46,7 +47,7 @@ Controls whether Docker Desktop checks for and notifies users about available up | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `disableUpdate` | -| Admin Console | **Disable update** | +| Docker Home | **Disable update** | > [!NOTE] > @@ -63,7 +64,7 @@ Allows Docker Desktop to automatically update components that do not require a r | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `silentModulesUpdate` | -| Admin Console | **Automatically update components** | +| Docker Home | **Automatically update components** | ### Enable Gordon @@ -73,11 +74,11 @@ Allows Docker Desktop to automatically update components that do not require a r | Accepted values (individuals) | `true`, `false` | | Accepted values (Business tier) | `"Disabled"`, `"Enabled"`, `"Always Enabled"` | | JSON key | `enableDockerAI` | -| Admin Console | **Enable Gordon** | +| Docker Home | **Enable Gordon** | > [!IMPORTANT] > -> Docker Business customers must set this to `"Enabled"` or `"Always Enabled"` in the Admin Console. Setting to `"User Defined"` alone will not activate Gordon. +> Docker Business customers must set this to `"Enabled"` or `"Always Enabled"` in Docker Home. Setting to `"User Defined"` alone will not activate Gordon. ### Block `docker load` @@ -89,7 +90,7 @@ Prevents users from loading local Docker images using the `docker load` command, | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `blockDockerLoad` | -| Admin Console | **Block Docker Load** | +| Docker Home | **Block Docker Load** | > [!NOTE] > @@ -106,7 +107,7 @@ Prevents the onboarding survey from being shown to new users. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `displayedOnboarding` | -| Admin Console | **Hide onboarding survey** | +| Docker Home | **Hide onboarding survey** | ### Enable Docker terminal @@ -119,7 +120,7 @@ Allows or restricts access to the built-in terminal for host system interaction. | Format | Boolean | | Docker Desktop GUI | **General** tab | | JSON key | `desktopTerminalEnabled` | -| Admin Console | Not available | +| Docker Home | Not available | ### Expose Docker API on TCP 2375 {{< badge color=blue text="Windows only" >}} @@ -131,7 +132,7 @@ Exposes the Docker API over an unauthenticated TCP socket on port 2375. Only rec | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `exposeDockerAPIOnTCP2375` | -| Admin Console | **Expose Docker API** | +| Docker Home | **Expose Docker API** | > [!NOTE] > @@ -150,7 +151,7 @@ Controls whether users can install and run Docker Extensions. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `extensionsEnabled` | -| Admin Console | **Allow Extensions** | +| Docker Home | **Allow Extensions** | > [!NOTE] > @@ -167,7 +168,7 @@ Prevents installation of third-party or locally developed extensions. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `onlyMarketplaceExtensions` | -| Admin Console | **Only marketplace extensions** | +| Docker Home | **Only marketplace extensions** | ### Enable a private marketplace @@ -179,7 +180,7 @@ Ensures Docker Desktop connects to content defined and controlled by the adminis | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `extensionsPrivateMarketplace` | -| Admin Console | **Extensions private marketplace** | +| Docker Home | **Extensions private marketplace** | ## AI @@ -193,7 +194,7 @@ Enables Docker Model Runner functionality for running AI models in containers. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enableInference` | -| Admin Console | **Enable Docker Model Runner** | +| Docker Home | **Enable Docker Model Runner** | #### Enable host-side TCP support @@ -205,7 +206,7 @@ Enables TCP connectivity for Docker Model Runner services, allowing external app | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enableInferenceTCP` | -| Admin Console | **Host-side TCP support** | +| Docker Home | **Host-side TCP support** | | Requires | Docker Model Runner enabled | ##### Port @@ -218,7 +219,7 @@ Specifies the port used for Model Runner TCP connections. | Accepted values | Integer | | Format | Integer | | JSON key | `enableInferenceTCPPort` | -| Admin Console | **Host-side TCP port** | +| Docker Home | **Host-side TCP port** | | Requires | Docker Model Runner and host-side TCP support enabled | ##### CORS Allowed Origins @@ -231,7 +232,7 @@ Controls cross-origin resource sharing for Model Runner web integration. | Accepted values | Empty string (deny all), `*` (accept all), or comma-separated list of origins | | Format | String | | JSON key | `enableInferenceCORS` | -| Admin Console | **CORS Allowed Origins** | +| Docker Home | **CORS Allowed Origins** | | Requires | Docker Model Runner and host-side TCP support enabled | ### Enable GPU-backed inference {{< badge color=blue text="Windows only" >}} @@ -244,7 +245,7 @@ Enables GPU-backed inference. Additional components will be downloaded to `~/.do | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enableInferenceGPUVariant` | -| Admin Console | **Enable GPU-backed inference** | +| Docker Home | **Enable GPU-backed inference** | ## File sharing and emulation @@ -258,7 +259,7 @@ Defines which host directories containers can access for development workflows. | Accepted values | List of file paths | | Format | Array of strings | | JSON key | `filesharingAllowedDirectories` | -| Admin Console | Yes — **Allowed file sharing directories** | +| Docker Home | Yes — **Allowed file sharing directories** | ### VirtioFS {{< badge color=blue text="Mac only" >}} @@ -270,7 +271,7 @@ Uses VirtioFS for fast, native file sharing between host and containers. If both | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `useVirtualizationFrameworkVirtioFS` | -| Admin Console | **Use VirtioFS for file sharing** tab | +| Docker Home | **Use VirtioFS for file sharing** tab | ### gRPC FUSE {{< badge color=blue text="Mac only" >}} @@ -282,7 +283,7 @@ Enables gRPC FUSE for macOS file sharing. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `useGrpcfuse` | -| Admin Console | **Use gRPC FUSE for file sharing** | +| Docker Home | **Use gRPC FUSE for file sharing** | ### Rosetta {{< badge color=blue text="Mac only" >}} @@ -294,7 +295,7 @@ Uses Rosetta for x86_64/amd64 emulation on Apple Silicon. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `useVirtualizationFrameworkRosetta` | -| Admin Console | **Use Rosetta for x86_64/amd64 emulation on Apple Silicon** | +| Docker Home | **Use Rosetta for x86_64/amd64 emulation on Apple Silicon** | ## Scout @@ -308,7 +309,7 @@ Turns on vulnerability scanning and software bill of materials (SBOM) analysis f | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `sbomIndexing` | -| Admin Console | **SBOM indexing** | +| Docker Home | **SBOM indexing** | ### Enable background Scout SBOM indexing @@ -320,7 +321,7 @@ Keeps image metadata current by indexing during idle time or after image operati | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `useBackgroundIndexing` | -| Admin Console | **Background indexing** | +| Docker Home | **Background indexing** | ## Proxy @@ -328,12 +329,12 @@ Keeps image metadata current by indexing during idle time or after image operati > > Proxy configuration is a special case because it must be configured in two places: > -> 1. In the Admin Console for your organization. +> 1. In the Docker Home for your organization. > 2. On the user's system where Docker Desktop is installed. > > On the user's machine, configure the proxy either through the `admin-settings.json` file or by using installer flags during Docker Desktop installation. For detailed instructions, refer to the [installation guide](/manuals/desktop/setup/install/windows-install.md#proxy-configuration). > -> This additional configuration is required because Docker Desktop must know which proxy server to use before it can complete user sign-in and retrieve organization settings from the Admin Console. +> This additional configuration is required because Docker Desktop must know which proxy server to use before it can complete user sign-in and retrieve organization settings from the Docker Home. ### Embedded PAC script @@ -345,7 +346,7 @@ Specifies an embedded Proxy Auto-Config (PAC) script. For example: `"embeddedPac | Accepted values | Embedded PAC script content | | Format | String | | JSON key | `embeddedPac` | -| Admin Console | Yes **Embedded PAC script** | +| Docker Home | Yes **Embedded PAC script** | ### PAC file URL @@ -357,7 +358,7 @@ Specifies a PAC file URL for Docker Desktop to use when routing network traffic. | Accepted values | PAC file URL | | Format | String | | JSON key | `pac` | -| Admin Console | **PAC file** | +| Docker Home | **PAC file** | ### Override Windows "dockerd" port {{< badge color=blue text="Windows only" >}} @@ -369,7 +370,7 @@ Exposes Docker Desktop's internal proxy locally on this port for the Windows Doc | Accepted values | `-1` `0` | | Format | String | | JSON key | `windowsDockerdPort` | -| Admin Console | **Override Windows “dockerd” port** | +| Docker Home | **Override Windows “dockerd” port** | ### Enable Kerberos and NTLM authentication @@ -381,7 +382,7 @@ Enables enterprise proxy authentication support for Kerberos and NTLM protocols. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `proxy.enableKerberosNtlm` | -| Admin Console | **Kerberos NTLM** | +| Docker Home | **Kerberos NTLM** | ### Proxy bypass @@ -394,13 +395,22 @@ Defines network addresses that containers should bypass when using proxy setting | Format | String | | Docker Desktop GUI | **Proxies** tab | | JSON key | `proxy` (with `manual` and `exclude` modes) | -| Admin Console | Yes — **Proxy** section | +| Docker Home | Yes — **Proxy** section | ## Containers proxy ### Air-gapped container proxy -Configures an HTTP/HTTPS proxy for containers in air-gapped environments, providing controlled network access in offline or restricted network environments. +Configures an HTTP/HTTPS proxy that governs two distinct traffic paths: + +- Daemon image pulls (always enforced): Docker Desktop always injects `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup. All `docker pull` and Compose pull operations are routed through `containersProxy`, including any PAC file rules. This applies regardless of whether `transparentPorts` is configured. +- Running container outbound traffic (opt-in): Container TCP traffic is only subject to `containersProxy` rules when `transparentPorts` is configured. Without it, running containers connect directly and PAC file rules do not apply to their outbound traffic. + +> [!IMPORTANT] +> +> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted. + +The [`proxy`](#proxy) setting governs Docker Desktop host-level traffic: the Desktop application, Docker CLI, and extensions. It serves as a fallback for the daemon only when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic. | Property | Value | |---|---| @@ -408,7 +418,7 @@ Configures an HTTP/HTTPS proxy for containers in air-gapped environments, provid | Accepted values | JSON object | | Format | JSON object | | JSON key | `containersProxy` | -| Admin Console | **Containers proxy** section | +| Docker Home | **Containers proxy** section | ```json "containersProxy": { @@ -422,7 +432,7 @@ Configures an HTTP/HTTPS proxy for containers in air-gapped environments, provid } ``` -For more information, see [Air-gapped containers](/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md). +For more information, see [Air-gapped containers](/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md). ## LinuxVM @@ -436,7 +446,7 @@ When set to `true`, Docker Desktop uses the WSL 2 based engine. Overrides any ba | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `wslEngineEnabled` | -| Admin Console | **Windows Subsystem for Linux (WSL) Engine** | +| Docker Home | **Windows Subsystem for Linux (WSL) Engine** | ### Docker daemon options @@ -448,7 +458,7 @@ Overrides the Docker daemon configuration used in containers, without modifying | Accepted values | JSON object | | Format | Stringified JSON | | JSON key | `linuxVM.dockerDaemonOptions` | -| Admin Console | **Docker Daemon options** in the LinuxVM dropdown | +| Docker Home | **Docker Daemon options** in the LinuxVM dropdown | ### VPNKit CIDR {{< badge color=blue text="Mac only" >}} @@ -460,7 +470,7 @@ Sets the network subnet used for Docker Desktop's internal VPNKit DHCP/DNS servi | Accepted values | CIDR notation | | Format | String | | JSON key | `vpnkitCIDR` | -| Admin Console | **VPNKit CIDR** | +| Docker Home | **VPNKit CIDR** | ## Windows containers @@ -474,7 +484,7 @@ Overrides the Docker daemon configuration used in Windows containers, without mo | Accepted values | JSON object | | Format | Stringified JSON | | JSON key | `windowsContainers.dockerDaemonOptions` | -| Admin Console | **Docker Daemon options** in the **Windows containers dropdown** | +| Docker Home | **Docker Daemon options** in the **Windows containers dropdown** | ## Kubernetes @@ -488,7 +498,7 @@ Enables the local Kubernetes cluster integration with Docker Desktop. | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `kubernetes` | -| Admin Console | **Enable Kubernetes** | +| Docker Home | **Enable Kubernetes** | ### Show system containers @@ -499,7 +509,7 @@ Controls visibility of Kubernetes system containers in the Docker Desktop Dashbo | Default | `false` | | Accepted values | `true`, `false` | | Format | Boolean | -| Admin Console | **Show system containers** | +| Docker Home | **Show system containers** | ### Kubernetes image repository @@ -511,7 +521,7 @@ Specifies a registry used for Kubernetes control plane images instead of Docker | Accepted values | Registry URL | | Format | String | | JSON key | `KubernetesImagesRepository` | -| Admin Console | **Kubernetes Images Repository** | +| Docker Home | **Kubernetes Images Repository** | > [!NOTE] > @@ -530,7 +540,7 @@ Controls Kubernetes cluster topology and node configuration. | Default | `kubeadm` | | Accepted values | `kubeadm`, `kind` | | Format | String | -| Admin Console | **Kubernetes mode** | +| Docker Home | **Kubernetes mode** | ### Node version @@ -541,7 +551,7 @@ Pins the Kubernetes version used for cluster nodes. | Default | `1.31.1` | | Accepted values | Semantic version (e.g. `1.29.1`) | | Format | String | -| Admin Console | **Node version** tab | +| Docker Home | **Node version** tab | ### Nodes count @@ -552,7 +562,7 @@ Sets the number of nodes in multi-node Kubernetes clusters. | Default | `1` | | Accepted values | Integer | | Format | Integer | -| Admin Console | **Nodes count** | +| Docker Home | **Nodes count** | ## Features in development @@ -566,11 +576,11 @@ Controls whether users can access all Docker Desktop features that are in public | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `allowBetaFeatures` | -| Admin Console | **Access beta features** | +| Docker Home | **Access beta features** | ### Enable Docker MCP Toolkit (Beta) -Enables [Docker MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/_index.md) in Docker Desktop for AI model development workflows. +Enables [Docker MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md) in Docker Desktop for AI model development workflows. | Property | Value | |---|---| @@ -578,7 +588,7 @@ Enables [Docker MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/_index.md) in D | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enableDockerMCPToolkit` | -| Admin Console | Not available | +| Docker Home | Not available | ## Enhance container isolation @@ -592,7 +602,7 @@ Prevents containers from modifying Docker Desktop VM configuration or accessing | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enhancedContainerIsolation` | -| Admin Console | **Enable enhanced container isolation** | +| Docker Home | **Enable enhanced container isolation** | ### Docker socket access control (ECI exceptions) @@ -603,7 +613,7 @@ Defines specific images and commands allowed to use the Docker socket when Enhan | Accepted values | JSON object | | Format | JSON object | | JSON key | ``dockerSocketMount` | -| Admin Console | **Image list**, **Command list** | +| Docker Home | **Image list**, **Command list** | ```json "enhancedContainerIsolation": { @@ -636,7 +646,7 @@ Sets the default IP protocol used when Docker creates new networks. | Accepted values | `ipv4only`, `ipv6only` | | Format | String | | JSON key | `defaultNetworkingMode` | -| Admin Console | **Default network IP mode** | +| Docker Home | **Default network IP mode** | For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows). @@ -650,7 +660,7 @@ Filters unsupported DNS record types to improve reliability in environments wher | Accepted values | `ipv4`, `ipv6`, `none` | | Format | String | | JSON key | `dnsInhibition` | -| Admin Console | **DNS filtering behavior** | +| Docker Home | **DNS filtering behavior** | For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows). @@ -664,7 +674,7 @@ Specify how port bindings are handled for new containers. | Accepted values | `default-local-port-binding`, `local-only-port-binding`, `default-port-binding` | | Format | String | | JSON key | `portBindingBehavior` | -| Admin Console | **Port binding behavior** | +| Docker Home | **Port binding behavior** | ## Other @@ -678,7 +688,7 @@ Controls Docker Offload availability. When enabled, users see the Docker Offload | Accepted values | `true`, `false` | | Format | Boolean | | JSON key | `enableCloud` | -| Admin Console | **Enable Docker Offload** | +| Docker Home | **Enable Docker Offload** | > [!NOTE] > diff --git a/content/manuals/desktop/enterprise/unassociated-machines/_index.md b/content/manuals/desktop/enterprise/unassociated-machines/_index.md new file mode 100644 index 000000000000..6007b66f2f01 --- /dev/null +++ b/content/manuals/desktop/enterprise/unassociated-machines/_index.md @@ -0,0 +1,183 @@ +--- +title: Manage unassociated machines +description: Learn how to manage unassociated machines in Docker Home +keywords: unassociated machines, insights, manage users, enforce sign-in +weight: 50 +aliases: + - /unassociated-machines/ +--- + +{{< summary-bar feature_name="Unassociated machines" >}} + +Organization owners can identify, view, and manage Docker Desktop machines +that are likely associated with their organization, based on usage, but aren't currently linked +to user accounts. This self-service capability helps you understand Docker +Desktop usage across your organization and streamline user onboarding without +IT involvement. + +## How Docker identifies unassociated machines + +Docker uses telemetry data to identify which machines likely belong to your +organization: + +- Domain matching: Users signed in with email domains associated with your + organization +- Registry patterns: Analysis of container registry access patterns that + indicate organizational usage + +## View unassociated machines + +To see detailed information about unassociated machines: + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. + +The machine list displays: + +- Machine ID (Docker-generated identifier) +- The registry address used to predict whether a user is part of your + organization +- User email (only displays if the user is signed into Docker Desktop while + using it) +- Docker Desktop version +- Operating system (OS) +- Last activity date +- Sign-in enforced status + +You can: + +- Export the list as CSV +- Take actions on individual or multiple machines + +## Enable sign-in enforcement for unassociated machines + +> [!IMPORTANT] +> +> Sign-in enforcement for unassociated machines is different from +> the [organization-level sign-in enforcement](/manuals/desktop/enterprise/enforce-sign-in/_index.md) +> available through `registry.json` and configuration profiles. This sign-in +> enforcement only requires users to sign in so admins can identify who is +> using the machine, meaning users can sign in with any email address. For more +> stringent security controls that limit sign-ins to users who are already part +> of your organization, see [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + +Sign-in enforcement helps you identify who is using unassociated machines in +your organization. When you enable enforcement, users on these machines will +be required to sign in to Docker Desktop. Once they sign in, their email +addresses will appear in the Unassociated list, allowing you to then add them +to your organization. + +You can enable sign-in enforcement using two methods: + +- For all unassociated machines in your organization +- For individual unassociated machines + +### Enable for all unassociated machines + +To enable sign-in enforcement for all unassociated machines: + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Turn on the **Enforce sign-in** toggle. +1. In the pop-up modal, select **Require sign-in** to confirm. + +The **Sign-in required** status updates all unassociated machines to +**Yes**. + +Sign-in enforcement only takes effect after Docker Desktop is restarted. +Users can continue using Docker Desktop until their next restart. + +> [!NOTE] +> +> When you enable sign-in enforcement for all unassociated machines, any new +> machines detected in the future automatically have sign-in enforcement +> enabled. + +### Enable for individual unassociated machines + +To enable sign-in enforcement for individual unassociated machines: + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Locate the machine you want to enable sign-in enforcement for. +1. Select the **Actions** menu and choose **Turn on sign-in enforcement**. +1. In the pop-up modal, select **Require sign-in** to confirm. + +The **Sign-in required** status updates for the individual machine to +**Yes**. + +### What happens when sign-in is enforced + +After you enable sign-in enforcement: + +- When users open Docker Desktop, they see a sign-in prompt. They must sign + in to continue using Docker Desktop. +- User email addresses appear in the **Unassociated** list. +- You can add users to your organization. + +Users can continue using Docker Desktop immediately after signing in, even +before being added to your organization. + +## Add unassociated machines to your organization + +When users in your organization use Docker without signing in, their machines +appear in the **Unassociated** list. You can add these users to your +organization in two ways: + +- Automatic addition: + - Auto-provisioning: If you have verified domains with auto-provisioning + enabled, users who sign in with a matching email domain will automatically + be added to your organization. For more information on verifying domains and + auto-provisioning, see [Domain management](/manuals/security/provisioning/domain-management.md). + - SSO user provisioning: If you have SSO configured with + [Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md), + users who sign in through your SSO connection will automatically be added + to your organization. +- Manual addition: If you don't have auto-provisioning or SSO set up, or if a + user's email domain doesn't match your configured domains, their email will + appear in the **Unassociated** list where you can choose to add them directly. + +> [!NOTE] +> +> If you add users and do not have enough seats in your organization, a +> pop-up appears prompting you to **Get more seats**. + +### Add individual users + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Locate the machine you want to add to your organization. +1. Select the **Actions** menu and choose **Add to organization**. +1. In the pop-up modal, select **Add user**. + +### Bulk add users + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Use the **checkboxes** to select the machines you want to add to your + organizations. +1. Select the **Add to organization** button. +1. In the pop-up modal, select **Add users** to confirm. + +## Disable sign-in enforcement + +### Disable for all unassociated machines + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Turn off the **Enforce sign-in** toggle. +1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. + +The **Sign-in required** status updates for all unassociated machines to +**No**. + +### Disable for specific unassociated machines + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +1. Select **Docker Desktop**, then **Unassociated**. +1. Locate the machine you want to disable sign-in enforcement for. +1. Select the **Actions** menu and choose **Turn off sign-in enforcement**. +1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. + +The **Sign-in required** status updates for the individual machine to +**No**. diff --git a/content/manuals/desktop/features/containerd.md b/content/manuals/desktop/features/containerd.md index 8b47f607f4c0..d11b9c824b8e 100644 --- a/content/manuals/desktop/features/containerd.md +++ b/content/manuals/desktop/features/containerd.md @@ -51,8 +51,7 @@ requirements. ## Switch image stores -The containerd image store is enabled by default in Docker Desktop version 4.34 -and later. To switch between image stores: +The containerd image store is enabled by default. To switch between image stores: 1. Navigate to **Settings** in Docker Desktop. 2. In the **General** tab, check or clear the **Use containerd for pulling and storing images** option. diff --git a/content/manuals/desktop/features/desktop-cli.md b/content/manuals/desktop/features/desktop-cli.md index 4f04bc07ac84..64a7f1cd8855 100644 --- a/content/manuals/desktop/features/desktop-cli.md +++ b/content/manuals/desktop/features/desktop-cli.md @@ -26,15 +26,16 @@ docker desktop COMMAND [OPTIONS] | `start` | Starts Docker Desktop | | `stop` | Stops Docker Desktop | | `restart` | Restarts Docker Desktop | -| `status` | Displays whether Docker Desktop is running or stopped. | +| `status` | Displays whether Docker Desktop is running or stopped | | `engine ls` | Lists available engines (Windows only) | | `engine use` | Switch between Linux and Windows containers (Windows only) | -| `update` | Manage Docker Desktop updates. | +| `update` | Manage Docker Desktop updates | | `logs` | Print log entries | | `disable` | Disable a feature | | `enable` | Enable a feature | | `version` | Show the Docker Desktop CLI plugin version information | -| `kubernetes` | List Kubernetes images used by Docker Desktop or restart the cluster. Available with Docker Desktop version 4.44 and later. | -| `diagnose` | Diagnose Docker Desktop and upload the diagnostics. Available with Docker Desktop 4.60 and later. | +| `kubernetes` | Manage Kubernetes | +| `diagnose` | Diagnose Docker Desktop and upload the diagnostics. | +| `auth status` | Show the current Docker Hub authentication status. Available with version 4.95 and later. | For more details on each command, see the [Docker Desktop CLI reference](/reference/cli/docker/desktop/). diff --git a/content/manuals/desktop/features/gpu.md b/content/manuals/desktop/features/gpu.md index 661d31e3566c..29409d2d0a65 100644 --- a/content/manuals/desktop/features/gpu.md +++ b/content/manuals/desktop/features/gpu.md @@ -11,7 +11,11 @@ aliases: > [!NOTE] > -> GPU support in Docker Desktop is only available on Windows with the WSL2 backend. +> This page covers GPU passthrough to Linux containers using `--gpus`, which is +> only available on Windows with the WSL 2 backend. Other forms of GPU +> acceleration in Docker Desktop, such as GPU-accelerated inference in +> [Docker Model Runner](/manuals/ai/model-runner/_index.md), are available on +> other platforms. Docker Desktop for Windows supports NVIDIA GPU Paravirtualization (GPU-PV) on NVIDIA GPUs, allowing containers to access GPU resources for compute-intensive workloads like AI, machine learning, or video processing. diff --git a/content/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md new file mode 100644 index 000000000000..56381adfb87f --- /dev/null +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md @@ -0,0 +1,91 @@ +--- +url: /ai/mcp-catalog-and-toolkit/ +title: Docker MCP Catalog and Toolkit +linkTitle: MCP Catalog and Toolkit +params: + sidebar: + badge: + color: blue + text: Beta +weight: 20 +description: Learn about Docker's MCP catalog on Docker Hub +keywords: Docker, ai, mcp servers, ai agents, extension, docker desktop, llm, docker hub +grid: + - title: Get started with MCP Toolkit + description: Learn how to quickly install and use the MCP Toolkit to set up servers and clients. + icon: magnifying-glass-plus + link: /ai/mcp-catalog-and-toolkit/get-started/ + - title: MCP Catalog + description: Browse Docker's curated collection of verified MCP servers + icon: globe-alt + link: /ai/mcp-catalog-and-toolkit/catalog/ + - title: MCP Profiles + description: Organize servers into profiles for different projects and share configurations + icon: folder + link: /ai/mcp-catalog-and-toolkit/profiles/ + - title: MCP Toolkit + description: Use Docker Desktop's UI to discover, configure, and manage MCP servers + icon: /icons/toolkit.svg + link: /ai/mcp-catalog-and-toolkit/toolkit/ + - title: MCP Gateway + description: Use the CLI and Gateway to run MCP servers with custom configurations + icon: cpu-chip + link: /ai/mcp-catalog-and-toolkit/mcp-gateway/ + - title: Dynamic MCP + description: Discover and add MCP servers on-demand using natural language. This feature is experimental. + icon: magnifying-glass + link: /ai/mcp-catalog-and-toolkit/dynamic-mcp/ + - title: Security FAQs + description: Common questions about MCP security, credentials, and server verification + icon: shield-check + link: /ai/mcp-catalog-and-toolkit/faqs/ +--- + +{{< summary-bar feature_name="Docker MCP Catalog and Toolkit" >}} + +[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is +an open protocol that standardizes how AI applications access external tools +and data sources. By connecting LLMs to local development tools, databases, +APIs, and other resources, MCP extends their capabilities beyond their base +training. + +The challenge is that running MCP servers locally creates operational friction. +Each server requires separate installation and configuration for every +application you use. You run untrusted code directly on your machine, manage +updates manually, and troubleshoot dependency conflicts yourself. Configure a +GitHub server for Claude, then configure it again for Cursor, and so on. Each +time you manage credentials, permissions, and environment setup. + +## Docker MCP features + +The [MCP Toolkit](/ai/mcp-catalog-and-toolkit/toolkit/) and [MCP +Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) solve these challenges +through centralized management. Instead of configuring each server for every AI +application separately, you set things up once and connect all your clients to +it. The workflow centers on three concepts: catalogs, profiles, and clients. + +![MCP overview](./images/mcp_toolkit.avif) + +[Catalogs](/ai/mcp-catalog-and-toolkit/catalog/) are curated collections of +MCP servers. The Docker MCP Catalog provides 300+ verified servers packaged as +container images with versioning, provenance, and security updates. Organizations +can create [custom +catalogs](/ai/mcp-catalog-and-toolkit/catalog/#custom-catalogs) with approved +servers for their teams. + +[Profiles](/ai/mcp-catalog-and-toolkit/profiles/) organize servers into named +collections for different projects. Your "web-dev" profile might use GitHub and +Playwright; your "backend" profile, database tools. Profiles support both +containerized servers from catalogs and remote MCP servers. Configure a profile +once, then share it across clients or with your team. + +Clients are the AI applications that connect to your profiles. Claude Code, +Cursor, Zed, and others connect through the MCP Gateway, which routes requests +to the right server and handles authentication and lifecycle management. + +> [!NOTE] +> MCP Gateway as part of Docker AI Governance is an invite-only feature. [Contact Docker Sales](https://www.docker.com/pricing/contact-sales/) to learn more. + +## Learn more + +{{< grid >}} diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/catalog.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md similarity index 92% rename from content/manuals/ai/mcp-catalog-and-toolkit/catalog.md rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md index 284d4198b31b..0163c9a7fa87 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/catalog.md +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md @@ -1,4 +1,5 @@ --- +url: /ai/mcp-catalog-and-toolkit/catalog/ title: Docker MCP Catalog linkTitle: Catalog description: Browse Docker's curated collection of verified MCP servers, and create custom catalogs for your team or organization. @@ -14,15 +15,10 @@ Hub. It solves common challenges with running MCP servers locally: environment conflicts, setup complexity, and security concerns. The catalog serves as the source of available MCP servers. When you add servers -to your [profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md), you select +to your [profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md), you select them from the catalog. Each server runs as an isolated container, making it portable and consistent across different environments. -> [!NOTE] -> E2B sandboxes now include direct access to the Docker MCP Catalog, giving -> developers access to over 200 tools and services to seamlessly build and run -> AI agents. For more information, see [E2B Sandboxes](e2b-sandboxes.md). - ## What's in the catalog The Docker MCP Catalog includes: @@ -116,7 +112,7 @@ its servers to your profiles. ### Create and manage custom catalogs Creating and managing custom catalogs requires the CLI. See -[Custom catalogs](/manuals/ai/mcp-catalog-and-toolkit/cli.md#custom-catalogs) +[Custom catalogs](/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md#custom-catalogs) in the CLI how-to for step-by-step instructions, including: - Curating a subset of the Docker catalog diff --git a/content/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md new file mode 100644 index 000000000000..ed035984e8ba --- /dev/null +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md @@ -0,0 +1,386 @@ +--- +url: /ai/mcp-catalog-and-toolkit/cli/ +title: Use MCP Toolkit from the CLI +linkTitle: Use with CLI +description: Manage MCP profiles, servers, and catalogs using Docker MCP CLI. +keywords: docker mcp, cli, profiles, servers, catalog, gateway +weight: 35 +--- + +{{< summary-bar feature_name="Docker MCP Toolkit" >}} + +> [!NOTE] +> The `docker mcp` commands documented here are available in Docker Desktop +> 4.62 and later. Earlier versions may not support all commands shown. + +The `docker mcp` commands let you manage MCP profiles, servers, OAuth +credentials, and catalogs from the terminal. Use the CLI for scripting, +automation, and headless environments. + +## Profiles + +### Create a profile + +```console +$ docker mcp profile create --name <profile-id> +``` + +The profile ID is used to reference the profile in subsequent commands: + +```console +$ docker mcp profile create --name web-dev +``` + +### List profiles + +```console +$ docker mcp profile list +``` + +### View a profile + +```console +$ docker mcp profile show <profile-id> +``` + +### Remove a profile + +```console +$ docker mcp profile remove <profile-id> +``` + +> [!CAUTION] +> Removing a profile deletes all its server configurations and settings. This +> action can't be undone. + +## Servers + +### Browse the catalog + +List available servers and their IDs: + +```console +$ docker mcp catalog server ls mcp/docker-mcp-catalog +``` + +The output lists each server by name. The name (for example, `playwright` or +`github-official`) is the server ID to use in `catalog://` URIs. + +To look up a server ID in Docker Desktop, open **MCP Toolkit** > **Catalog**, +select a server, and check the **Server ID** field. + +### Add servers to a profile + +Servers are referenced by URI. The URI format depends on where the server +comes from: + +| Format | Source | +| ------------------------------------- | -------------------------- | +| `catalog://<catalog-ref>/<server-id>` | An OCI catalog | +| `docker://<image>:<tag>` | A Docker image | +| `https://<url>/v0/servers/<uuid>` | The MCP community registry | +| `file://<path>` | A local YAML or JSON file | + +The most common format is `catalog://`, where `<catalog-ref>` matches the +**Catalog** field and `<server-id>` matches the **Server ID** field shown in +Docker Desktop or in the `catalog server ls` output: + +```console +$ docker mcp profile server add <profile-id> \ + --server catalog://<catalog-ref>/<server-id> +``` + +Add multiple servers in one command: + +```console +$ docker mcp profile server add web-dev \ + --server catalog://mcp/docker-mcp-catalog/github-official \ + --server catalog://mcp/docker-mcp-catalog/playwright +``` + +To add a server defined in a local YAML file: + +```console +$ docker mcp profile server add my-profile \ + --server file://./my-server.yaml +``` + +The YAML file defines the server image and configuration: + +```yaml +name: my-server +title: My Server +type: server +image: myimage:latest +description: Description of the server +``` + +If the server requires OAuth authentication, authorize it in Docker Desktop +after adding. See [OAuth authentication](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication). + +### List servers + +List all servers across all profiles: + +```console +$ docker mcp profile server ls +``` + +Filter by profile: + +```console +$ docker mcp profile server ls --filter profile=web-dev +``` + +### Remove a server + +```console +$ docker mcp profile server remove <profile-id> --name <server-name> +``` + +Remove multiple servers at once: + +```console +$ docker mcp profile server remove web-dev \ + --name github-official \ + --name playwright +``` + +### Configure server settings + +Set and retrieve configuration values for servers in a profile: + +```console +$ docker mcp profile config <profile-id> --set <server-id>.<key>=<value> +$ docker mcp profile config <profile-id> --get-all +$ docker mcp profile config <profile-id> --del <server-id>.<key> +``` + +Server configuration keys and their expected values are defined by each server. +Check the server's documentation or its entry in Docker Desktop under +**MCP Toolkit** > **Catalog** > **Configuration**. + +## Gateway + +Run the MCP Gateway with a specific profile: + +```console +$ docker mcp gateway run --profile <profile-id> +``` + +Omit `--profile` to use the default profile. + +### Connect a client manually + +To connect any client that isn't listed in Docker Desktop, configure it to run +the gateway over `stdio`. For example, in a JSON-based client configuration: + +```json +{ + "servers": { + "MCP_DOCKER": { + "command": "docker", + "args": ["mcp", "gateway", "run", "--profile", "web-dev"], + "type": "stdio" + } + } +} +``` + +For Claude Desktop, the format is: + +```json +{ + "mcpServers": { + "MCP_DOCKER": { + "command": "docker", + "args": ["mcp", "gateway", "run", "--profile", "web-dev"] + } + } +} +``` + +### Connect a named client + +Connect a supported client to a profile: + +```console +$ docker mcp client connect <client> --profile <profile-id> +``` + +For example, to connect VS Code to a project-specific profile: + +```console +$ docker mcp client connect vscode --profile my-project +``` + +This creates a `.vscode/mcp.json` file in the current directory. Because this +is a user-specific file, add it to `.gitignore`: + +```console +$ echo ".vscode/mcp.json" >> .gitignore +``` + +## Share profiles + +Share profiles with your team using OCI registries or version control. + +### Share via OCI registry + +Profiles are shared as OCI artifacts via any OCI-compatible registry. +Credentials are not included for security reasons. Team members configure +authentication credentials separately after pulling. + +To push an existing profile called `web-dev` to an OCI registry: + +```console +$ docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1 +``` + +To pull the same profile: + +```console +$ docker mcp profile pull registry.example.com/profiles/team-standard:latest +``` + +### Share via version control + +For project-specific profiles, you can use the `export` and `import` commands +and store the profiles in version control alongside your code. Team members can +import the file to get the same configuration. + +To export a profile to your project directory: + +```console +$ mkdir -p .docker +$ docker mcp profile export web-dev .docker/mcp-profile.json +``` + +Team members who clone the repository can import the profile: + +```console +$ docker mcp profile import .docker/mcp-profile.json +``` + +This creates a profile with the servers and configuration defined in the +file. Any authentication credentials must be configured separately if needed. + +## Custom catalogs + +Custom catalogs let you curate a focused collection of servers for your team +or organization. For an overview of what custom catalogs are and when to use +them, see [Custom catalogs](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md#custom-catalogs). + +Catalogs are referenced by OCI reference, for example +`registry.example.com/mcp/my-catalog:latest`. Servers within a catalog use +the same URI schemes as when +[adding servers to a profile](#add-servers-to-a-profile). + +### Customize the Docker catalog + +Use the Docker catalog as a base, then add or remove servers to fit your +organization's needs. Copy it first: + +```console +$ docker mcp catalog tag mcp/docker-mcp-catalog \ + registry.example.com/mcp/company-tools:latest +``` + +List the servers it contains: + +```console +$ docker mcp catalog server ls registry.example.com/mcp/company-tools:latest +``` + +Remove servers your organization doesn't approve: + +```console +$ docker mcp catalog server remove \ + registry.example.com/mcp/company-tools:latest \ + --name <server-name> +``` + +Add your own private servers, packaged as Docker images: + +```console +$ docker mcp catalog server add registry.example.com/mcp/company-tools:latest \ + --server docker://registry.example.com/mcp/internal-api:latest \ + --server docker://registry.example.com/mcp/data-pipeline:latest +``` + +Push when ready: + +```console +$ docker mcp catalog push registry.example.com/mcp/company-tools:latest +``` + +### Build a catalog from scratch + +To include exactly what you choose and nothing else, create a catalog from +scratch. You can include servers from the Docker catalog, your own private +images, or both. + +Create a catalog and specify which servers to include: + +```console +$ docker mcp catalog create registry.example.com/mcp/data-tools:latest \ + --title "Data Analysis Tools" \ + --server catalog://mcp/docker-mcp-catalog/sequentialthinking \ + --server catalog://mcp/docker-mcp-catalog/brave \ + --server docker://registry.example.com/mcp/analytics:latest +``` + +View the result: + +```console +$ docker mcp catalog show registry.example.com/mcp/data-tools:latest +``` + +Push to distribute: + +```console +$ docker mcp catalog push registry.example.com/mcp/data-tools:latest +``` + +### Distribute a catalog + +Push your catalog so team members can import it: + +```console +$ docker mcp catalog push <oci-reference> +``` + +Team members can pull it using the CLI: + +```console +$ docker mcp catalog pull <oci-reference> +``` + +Or import it using Docker Desktop: select **MCP Toolkit** > **Catalog** > +**Import catalog** and enter the OCI reference. + +### Use a custom catalog with the gateway + +Run the gateway with your catalog instead of the default Docker catalog: + +```console +$ docker mcp gateway run --catalog <oci-reference> +``` + +For [Dynamic MCP](/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md), where +agents discover and add servers during conversations, this limits what agents +can find to your curated set. + +To enable specific servers from your catalog without using a profile: + +```console +$ docker mcp gateway run --catalog <oci-reference> \ + --servers <name1> --servers <name2> +``` + +## Further reading + +- [Get started with MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md) +- [MCP Profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md) +- [MCP Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) +- [MCP Gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md similarity index 91% rename from content/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md index 4194002b1bc5..41589e2be70d 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md @@ -1,4 +1,5 @@ --- +url: /ai/mcp-catalog-and-toolkit/dynamic-mcp/ title: Dynamic MCP linkTitle: Dynamic discovery description: Discover and add MCP servers on-demand using natural language with Dynamic MCP servers @@ -9,11 +10,11 @@ weight: 40 Dynamic MCP enables AI agents to discover and add MCP servers on-demand during a conversation, without manual configuration. Instead of pre-configuring every MCP server before starting your agent session, clients can search the -[MCP Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) and add servers +[MCP Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) and add servers as needed. This capability is enabled automatically when you connect an MCP client to the -[MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md). The gateway +[MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md). The gateway provides a set of primordial tools that agents use to discover and manage servers during runtime. @@ -50,18 +51,18 @@ restart or manual configuration. Dynamically added servers and tools are associated with your _current session only_. They're not persisted to your profile. When you start a new session, only servers you've added to your profile through the -[MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) or -[Profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md) are available. +[MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md) or +[Profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md) are available. ## Prerequisites To use Dynamic MCP, you need: -- Docker Desktop version 4.50 or later, with [MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) enabled +- Docker Desktop version 4.50 or later, with [MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md) enabled - An LLM application that supports MCP (such as Claude Desktop, Visual Studio Code, or Claude Code) - Your client configured to connect to the MCP Gateway -See [Get started with Docker MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/get-started.md) +See [Get started with Docker MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md) for setup instructions. ## Usage diff --git a/content/manuals/desktop/features/mcp-catalog-and-toolkit/faqs.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/faqs.md new file mode 100644 index 000000000000..9ddc59f87d90 --- /dev/null +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/faqs.md @@ -0,0 +1,115 @@ +--- +url: /ai/mcp-catalog-and-toolkit/faqs/ +title: MCP Toolkit FAQs +linkTitle: FAQs +description: Frequently asked questions related to MCP Catalog and Toolkit security +keywords: MCP, Toolkit, MCP server, MCP client, security, faq +tags: [FAQ] +weight: 70 +--- + +Docker MCP Catalog and Toolkit is a solution for securely building, sharing, and +running MCP tools. This page answers common questions about MCP Catalog and Toolkit security. + +### What process does Docker follow to add a new MCP server to the catalog? + +Developers can submit a pull request to the [Docker MCP Registry](https://github.com/docker/mcp-registry) to propose new servers. Docker provides detailed [contribution guidelines](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md) to help developers meet the required standards. + +Currently, a majority of the servers in the catalog are built directly by Docker. Each server includes attestations such as: + +- Build attestation: Servers are built on Docker Build Cloud. +- Source provenance: Verifiable source code origins. +- Signed SBOMs: Software Bill of Materials with cryptographic signatures. + +> [!NOTE] +> When using the images with [Docker MCP gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md), +> you can verify attestations at runtime using the `docker mcp gateway run +--verify-signatures` CLI command. + + +In addition to Docker-built servers, the catalog includes select servers from trusted registries such as GitHub and HashiCorp. Each third-party server undergoes a verification process that includes: + +- Pulling and building the code in an ephemeral build environment. +- Testing initialization and functionality. +- Verifying that tools can be successfully listed. + +### Under what conditions does Docker reject MCP server submissions? + +Docker rejects MCP server submissions that fail automated testing and validation processes during pull request review. Additionally, Docker reviewers evaluate submissions against specific requirements and reject MCP servers that don't meet these criteria. + +### Does Docker take accountability for malicious MCP servers in the Toolkit? + +Docker’s security measures currently represent a best-effort approach. While Docker implements automated testing, scanning, and metadata extraction for each server in the catalog, these security measures are not yet exhaustive. Docker is actively working to enhance its security processes and expand testing coverage. Enterprise customers can contact their Docker account manager for specific security requirements and implementation details. + +### How are credentials managed for MCP servers? + +Starting with Docker Desktop version 4.43.0, credentials are stored securely in the Docker Desktop VM. The storage implementation depends on the platform (for example, macOS, WSL2). You can manage the credentials using the following CLI commands: + +- `docker mcp secret ls` - List stored credentials +- `docker mcp secret rm` - Remove specific credentials +- `docker mcp oauth revoke` - Revoke OAuth-based credentials + +In the upcoming versions of Docker Desktop, Docker plans to support pluggable storage for these secrets and additional out-of-the-box storage providers to give users more flexibility in managing credentials. + +### Are credentials removed when an MCP server is uninstalled? + +No. MCP servers are not technically uninstalled since they exist as Docker containers pulled to your local Docker Desktop. Removing an MCP server stops the container but leaves the image on your system. Even if the container is deleted, credentials remain stored until you remove them manually. + +### Why don't I see remote MCP servers in the catalog? + +If remote MCP servers aren't visible in the Docker Desktop catalog, your local +catalog may be out of date. Remote servers are indicated by a cloud icon and +include services like GitHub, Notion, and Linear. + +Update your catalog by running: + +```console +$ docker mcp catalog update +``` + +After the update completes, refresh the **Catalog** tab in Docker Desktop. + +### What's the difference between profiles and the catalog? + +The [catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) is the source of +available MCP servers - a library of tools you can choose from. +[Profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md) are collections of +servers you've added to organize your work. Think of the catalog as a library, +and profiles as your personal bookshelves containing the books you've selected +for different purposes. + +### Can I share profiles with my team? + +Yes. Profiles can be pushed to OCI-compliant registries using +`docker mcp profile push my-profile registry.example.com/profiles/my-profile:v1`. +Team members can pull your profile with +`docker mcp profile pull registry.example.com/profiles/my-profile:v1`. Note +that credentials aren't included in shared profiles for security reasons - team +members need to configure OAuth and other credentials separately. + +### Do I need to create a profile to use MCP Toolkit? + +Yes, MCP Toolkit requires a profile to run servers. If you're upgrading from a +version before profiles were introduced, a default profile is automatically +created for you with your existing server configurations. You can create +additional named profiles to organize servers for different projects or +environments. + +### What happens to servers when I switch profiles? + +Each profile contains its own set of servers and configurations. When you run +the gateway with `--profile profile-name`, only servers in that profile are +available to clients. The default profile is used when no profile is specified. +Switching between profiles changes which servers your AI applications can +access. + +### Can I use the same server in multiple profiles? + +Yes. You can add the same MCP server to multiple profiles, each with different +configurations if needed. This is useful when you need the same server with +different settings for different projects or environments. + +## Related pages + +- [Get started with MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md) +- [Open-source MCP Gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md new file mode 100644 index 000000000000..a858ac6ab647 --- /dev/null +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md @@ -0,0 +1,462 @@ +--- +url: /ai/mcp-catalog-and-toolkit/get-started/ +title: Get started with Docker MCP Toolkit +linkTitle: Get started +description: Learn how to quickly install and use the MCP Toolkit to set up servers and clients. +keywords: Docker MCP Toolkit, MCP server, MCP client, AI agents +weight: 5 +params: + test_prompt: Use the GitHub MCP server to show me my open pull requests +--- + +{{< summary-bar feature_name="Docker MCP Toolkit" >}} + +> [!NOTE] +> This page describes the MCP Toolkit interface in Docker Desktop 4.62 and +> later. Earlier versions have a different UI. Upgrade to follow these +> instructions exactly. + +The Docker MCP Toolkit makes it easy to set up, manage, and run containerized +Model Context Protocol (MCP) servers in profiles, and connect them to AI +agents. It provides secure defaults and support for a growing ecosystem of +LLM-based clients. This page shows you how to get started quickly with the +Docker MCP Toolkit. + +## Setup + +Before you begin, make sure you meet the following requirements to get started with Docker MCP Toolkit. + +1. Download and install the latest version of [Docker Desktop](/get-started/get-docker/). +2. Open the Docker Desktop settings and select **Beta features**. +3. Select **Enable Docker MCP Toolkit**. +4. Select **Apply**. + +The **Learning center** in Docker Desktop provides walkthroughs and resources +to help you get started with Docker products and features. On the **MCP +Toolkit** page, the **Get started** walkthrough guides you through installing +an MCP server, connecting a client, and testing your setup. + +Alternatively, follow the step-by-step instructions on this page: + +- [Create a profile](#create-a-profile) - Your workspace for organizing servers +- [Add MCP servers to your profile](#add-mcp-servers) - Select tools from the catalog +- [Connect clients](#connect-clients) - Link AI applications to your profile +- [Verify connections](#verify-connections) - Test that everything works + +Once configured, your AI applications can use all the servers in your profile. + +> [!TIP] +> Prefer working from the terminal? See [Use MCP Toolkit from the CLI](cli.md) +> for instructions on using the `docker mcp` commands. + +## Create a profile + +Profiles organize your MCP servers into collections. Create a profile for your +work: + +> [!NOTE] +> If you're upgrading from a previous version of MCP Toolkit, your existing +> server configurations are already in a `default` profile. You can continue +> using the default profile or create new profiles for different projects. + +1. In Docker Desktop, select **MCP Toolkit** and select the **Profiles** tab. +2. Select **Create profile**. +3. Enter a name for your profile (e.g., "Frontend development"). +4. Optionally, add servers and clients now, or add them later. +5. Select **Create**. + +Your new profile appears in the profiles list. + +## Add MCP servers + +1. In Docker Desktop, select **MCP Toolkit** and select the **Catalog** tab. +2. Browse the catalog and select the servers you want to add. +3. Select the **Add to** button and choose whether you want to add the servers + to an existing profile, or create a new profile. + +If a server requires configuration, a **Configuration Required** badge appears +next to the server's name. You must complete the mandatory configuration before +you can use the server. + +You've now successfully added MCP servers to your profile. Next, connect an MCP +client to use the servers in your profile. + +## Connect clients + +To connect a client to MCP Toolkit: + +1. In Docker Desktop, select **MCP Toolkit** and select the **Clients** tab. +2. Find your application in the list. +3. Select **Connect** to configure the client. + +If your client isn't listed, you can connect the MCP Toolkit manually over +`stdio` by configuring your client to run the gateway with your profile: + +```plaintext +docker mcp gateway run --profile my_profile +``` + +For example, if your client uses a JSON file to configure MCP servers, you may +add an entry like: + +```json {title="Example configuration" +{ + "servers": { + "MCP_DOCKER": { + "command": "docker", + "args": ["mcp", "gateway", "run", "--profile", "my_profile"], + "type": "stdio" + } + } +} +``` + +Consult the documentation of the application you're using for instructions on +how to set up MCP servers manually. + +## Verify connections + +Refer to the relevant section for instructions on how to verify that your setup +is working: + +- [Claude Code](#claude-code) +- [Claude Desktop](#claude-desktop) +- [OpenAI Codex](#codex) +- [Continue](#continue) +- [Cursor](#cursor) +- [Gemini](#gemini) +- [Goose](#goose) +- [LM Studio](#lm-studio) +- [OpenCode](#opencode) +- [Sema4.ai](#sema4) +- [Visual Studio Code](#vscode) +- [Zed](#zed) +- [Mistral Vibe](#mistral-vibe) + +### Claude Code + +If you configured the MCP Toolkit for a specific project, navigate to the +relevant project directory. Then run `claude mcp list`. The output should show +`MCP_DOCKER` with a "connected" status: + +```console +$ claude mcp list +Checking MCP server health... + +MCP_DOCKER: docker mcp gateway run - ✓ Connected +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ claude "{{% param test_prompt %}}" +``` + +### Claude Desktop + +Restart Claude Desktop and check the **Search and tools** menu in the chat +input. You should see the `MCP_DOCKER` server listed and enabled: + +![Claude Desktop](images/claude-desktop.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param test_prompt %}} +``` + +### Codex + +Run `codex mcp list` to view active MCP servers and their statuses. The +`MCP_DOCKER` server should appear in the list with an "enabled" status: + +```console +$ codex mcp list +Name Command Args Env Cwd Status Auth +MCP_DOCKER docker mcp gateway run - - enabled Unsupported +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ codex "{{% param test_prompt %}}" +``` + +### Continue + +Launch the Continue terminal UI by running `cn`. Use the `/mcp` command to view +active MCP servers and their statuses. The `MCP_DOCKER` server should appear in +the list with a "connected" status: + +```plaintext + MCP Servers + + ➤ 🟢 MCP_DOCKER (🔧75 📝3) + 🔄 Restart all servers + ⏹️ Stop all servers + 🔍 Explore MCP Servers + Back + + ↑/↓ to navigate, Enter to select, Esc to go back +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ cn "{{% param test_prompt %}}" +``` + +### Cursor + +Open Cursor. If you configured the MCP Toolkit for a specific project, open the +relevant project directory. Then navigate to **Cursor Settings > Tools & MCP**. +You should see `MCP_DOCKER` under **Installed MCP Servers**: + +![Cursor](images/cursor.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param test_prompt %}} +``` + +### Gemini + +Run `gemini mcp list` to view active MCP servers and their statuses. The +`MCP_DOCKER` should appear in the list with a "connected" status. + +```console +$ gemini mcp list +Configured MCP servers: + +✓ MCP_DOCKER: docker mcp gateway run (stdio) - Connected +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ gemini "{{% param test_prompt %}}" +``` + +### Goose + +{{< tabs >}} +{{< tab name="Desktop app" >}} + +Open the Goose desktop application and select **Extensions** in the sidebar. +Under **Enabled Extensions**, you should see an extension named `Mcpdocker`: + +![Goose desktop app](images/goose.avif) + +{{< /tab >}} +{{< tab name="CLI" >}} + +Run `goose info -v` and look for an entry named `mcpdocker` under extensions. +The status should show `enabled: true`: + +```console +$ goose info -v +… + mcpdocker: + args: + - mcp + - gateway + - run + available_tools: [] + bundled: null + cmd: docker + description: The Docker MCP Toolkit allows for easy configuration and consumption of MCP servers from the Docker MCP Catalog + enabled: true + env_keys: [] + envs: {} + name: mcpdocker + timeout: 300 + type: stdio +``` + +{{< /tab >}} +{{< /tabs >}} + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param "test_prompt" %}} +``` + +### LM Studio + +Restart LM Studio and start a new chat. Open the integrations menu and look for +an entry named `mcp/mcp-docker`. Use the toggle to enable the server: + +![LM Studio](images/lm-studio.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param "test_prompt" %}} +``` + +### OpenCode + +The OpenCode configuration file (at `~/.config/opencode/opencode.json` by +default) contains the setup for MCP Toolkit: + +```json +{ + "mcp": { + "MCP_DOCKER": { + "type": "local", + "command": ["docker", "mcp", "gateway", "run"], + "enabled": true + } + }, + "$schema": "https://opencode.ai/config.json" +} +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ opencode "{{% param "test_prompt" %}}" +``` + +### Sema4.ai Studio {#sema4} + +In Sema4.ai Studio, select **Actions** in the sidebar, then select the **MCP +Servers** tab. You should see Docker MCP Toolkit in the list: + +![Docker MCP Toolkit in Sema4.ai Studio](./images/sema4-mcp-list.avif) + +To use MCP Toolkit with Sema4.ai, add it as an agent action. Find the agent you +want to connect to the MCP Toolkit and open the agent editor. Select **Add +Action**, enable Docker MCP Toolkit in the list, then save your agent: + +![Editing an agent in Sema4.ai Studio](images/sema4-edit-agent.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param test_prompt %}} +``` + +### Visual Studio Code {#vscode} + +Open Visual Studio Code. If you configured the MCP Toolkit for a specific +project, open the relevant project directory. Then open the **Extensions** +pane. You should see the `MCP_DOCKER` server listed under installed MCP +servers. + +![MCP_DOCKER installed in Visual Studio Code](images/vscode-extensions.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param test_prompt %}} +``` + +### Zed + +Launch Zed and open agent settings: + +![Opening Zed agent settings from command palette](images/zed-cmd-palette.avif) + +Ensure that `MCP_DOCKER` is listed and enabled in the MCP Servers section: + +![MCP_DOCKER in Zed's agent settings](images/zed-agent-settings.avif) + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```plaintext +{{% param test_prompt %}} +``` + +### Mistral Vibe + +Mistral Vibe uses a TOML configuration file at `~/.vibe/config.toml`. Add the +MCP Toolkit as a stdio MCP server in the `[[mcp_servers]]` section: + +{{< tabs >}} +{{< tab name="Linux" >}} + +```toml +[[mcp_servers]] +name = "MCP_DOCKER" +transport = "stdio" +command = ["docker"] +args = ["mcp", "gateway", "run", "--profile", "my_profile"] +startup_timeout_sec = 60 +disabled = false +``` + +{{< /tab >}} +{{< tab name="macOS" >}} + +```toml +[[mcp_servers]] +name = "MCP_DOCKER" +transport = "stdio" +command = ["docker"] +args = ["mcp", "gateway", "run", "--profile", "my_profile"] +startup_timeout_sec = 60 +disabled = false +``` + +{{< /tab >}} +{{< tab name="Windows" >}} + +On Windows, the Docker installation path (`C:\Program Files\Docker\...`) +contains a space. Use a list for `command` with the full path to `docker.exe`, +and add `PROGRAMFILES` and `PROGRAMDATA` environment variables that the MCP +Python SDK doesn't inherit by default: + +```toml +[[mcp_servers]] +name = "MCP_DOCKER" +transport = "stdio" +command = ["C:/Program Files/Docker/Docker/resources/bin/docker.exe"] +args = ["mcp", "gateway", "run", "--profile", "my_profile"] +env = { PROGRAMFILES = "C:\\Program Files", PROGRAMDATA = "C:\\ProgramData" } +startup_timeout_sec = 60 +disabled = false +``` + +{{< /tab >}} +{{< /tabs >}} + +The `startup_timeout_sec = 60` is recommended because the Docker MCP Gateway +takes approximately 15-25 seconds to start. The default timeout is 10 seconds, +which isn't enough for the gateway to initialize. + +Restart Vibe. In a Vibe CLI session, run `/mcp` to view active MCP servers. +The `MCP_DOCKER` server should appear in the list: + +```console +$ vibe +> /mcp +``` + +Test the connection by submitting a prompt that invokes one of your installed +MCP servers: + +```console +$ vibe "{{% param test_prompt %}}" +``` + +## Further reading + +- [MCP Profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md) +- [MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md) +- [MCP Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) +- [MCP Gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/ask-gordon.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/ask-gordon.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/ask-gordon.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/ask-gordon.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/claude-desktop.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/claude-desktop.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/claude-desktop.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/claude-desktop.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/copilot-mode.png b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/copilot-mode.png similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/copilot-mode.png rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/copilot-mode.png diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/cursor.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/cursor.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/cursor.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/cursor.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/goose.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/goose.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/goose.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/goose.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/lm-studio.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/lm-studio.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/lm-studio.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/lm-studio.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/mcp_toolkit.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/mcp_toolkit.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/mcp_toolkit.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/mcp_toolkit.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/sema4-edit-agent.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/sema4-edit-agent.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/sema4-edit-agent.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/sema4-edit-agent.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/sema4-mcp-list.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/sema4-mcp-list.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/sema4-mcp-list.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/sema4-mcp-list.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/tools.png b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/tools.png similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/tools.png rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/tools.png diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/vscode-extensions.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/vscode-extensions.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/vscode-extensions.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/vscode-extensions.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/zed-agent-settings.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/zed-agent-settings.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/zed-agent-settings.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/zed-agent-settings.avif diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/images/zed-cmd-palette.avif b/content/manuals/desktop/features/mcp-catalog-and-toolkit/images/zed-cmd-palette.avif similarity index 100% rename from content/manuals/ai/mcp-catalog-and-toolkit/images/zed-cmd-palette.avif rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/images/zed-cmd-palette.avif diff --git a/content/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md new file mode 100644 index 000000000000..fac08e453587 --- /dev/null +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md @@ -0,0 +1,91 @@ +--- +url: /ai/mcp-catalog-and-toolkit/mcp-gateway/ +title: MCP Gateway +linkTitle: Gateway +description: "Docker's MCP Gateway provides secure, centralized, and scalable orchestration of AI tools through containerized MCP servers, empowering developers, operators, and security teams." +keywords: MCP Gateway +weight: 40 +aliases: + - /ai/mcp-gateway/ +--- + +> [!NOTE] +> MCP Gateway as part of Docker AI Governance is an invite-only feature. [Contact Docker Sales](https://www.docker.com/pricing/contact-sales/) to learn more. + +The MCP Gateway is Docker's open source solution for orchestrating Model +Context Protocol (MCP) servers. It acts as a centralized proxy between clients +and servers, managing configuration, credentials, and access control. + +When using MCP servers without the MCP Gateway, you need to configure +applications individually for each AI application. With the MCP Gateway, you +configure applications to connect to the Gateway. The Gateway then handles +server lifecycle, routing, and authentication across all servers in your +[profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md). + +If you use Docker Desktop with MCP Toolkit enabled, the Gateway runs +automatically in the background. You don't need to start or configure it +manually. This documentation is for users who want to understand how the Gateway works or run it directly for advanced use cases. + +## How it works + +MCP Gateway runs MCP servers in isolated Docker containers with restricted +privileges, network access, and resource usage. It includes built-in logging +and call-tracing capabilities to ensure full visibility and governance of AI +tool activity. + +The MCP Gateway manages the server's entire lifecycle. When an AI application +needs to use a tool, it sends a request to the Gateway. The Gateway identifies +which server handles that tool and, if the server isn't already running, starts +it as a Docker container. The Gateway then injects any required credentials, +applies security restrictions, and forwards the request to the server. The +server processes the request and returns the result through the Gateway back to +the AI application. + +The MCP Gateway solves a fundamental problem: MCP servers are just programs +that need to run somewhere. Running them directly on your machine means dealing +with installation, dependencies, updates, and security risks. By running them +as containers managed by the Gateway, you get isolation, consistent +environments, and centralized control. + +The Gateway works with profiles to determine which servers are available. When +you run the Gateway, you specify which profile to use with the `--profile` flag +to determine which servers are made available to clients. + +## Usage + +To use the MCP Gateway, you'll need Docker Desktop with MCP Toolkit enabled. +Follow the [MCP Toolkit guide](toolkit.md) to enable and configure servers +through the Docker Desktop interface, or see +[Use MCP Toolkit from the CLI](cli.md) for terminal-based workflows. + +### Install the MCP Gateway manually + +For Docker Engine without Docker Desktop, you'll need to download and install +the MCP Gateway separately before you can run it. + +1. Download the latest binary from the [GitHub releases page](https://github.com/docker/mcp-gateway/releases/latest). + +2. Move or symlink the binary to the destination matching your OS: + + | OS | Binary destination | + | ------- | ----------------------------------- | + | Linux | `~/.docker/cli-plugins/docker-mcp` | + | macOS | `~/.docker/cli-plugins/docker-mcp` | + | Windows | `%USERPROFILE%\.docker\cli-plugins` | + +3. Make the binaries executable: + + ```bash + $ chmod +x ~/.docker/cli-plugins/docker-mcp + ``` + +You can now use the `docker mcp` command: + +```bash +docker mcp --help +``` + +## Additional information + +For more details on how the MCP Gateway works and available customization +options, see the complete documentation [on GitHub](https://github.com/docker/mcp-gateway). diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/profiles.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md similarity index 90% rename from content/manuals/ai/mcp-catalog-and-toolkit/profiles.md rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md index 690db7775472..26c76126efcf 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/profiles.md +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md @@ -1,4 +1,5 @@ --- +url: /ai/mcp-catalog-and-toolkit/profiles/ title: MCP Profiles linkTitle: Profiles description: Organize MCP servers into profiles for different projects and environments @@ -18,7 +19,7 @@ your server configurations. A profile is a named collection of MCP servers with their configurations and settings. You select servers from the [MCP -Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) (the source of +Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) (the source of available servers) and add them to your profiles (your configured server collections for specific work). Think of the catalog as a library of tools, and profiles as your toolboxes organized for different jobs. @@ -41,6 +42,12 @@ database servers, while your "data-analysis" profile includes spreadsheet, API, and visualization servers. Create as many profiles as you need, each containing only the servers relevant to that context. +> [!NOTE] +> +> OAuth credentials are an exception to profile isolation — they are shared +> across all profiles. If you need to use different accounts for different +> projects, revoke and re-authorize when switching profiles. + You can connect different AI applications to different profiles. When you connect a client, you specify which profile it should use. This means Claude Desktop and VS Code can have access to different server collections if needed. @@ -123,7 +130,7 @@ From within a profile: 3. Search for and select servers to add. If a server requires OAuth authentication, you're prompted to authorize it. See -[OAuth authentication](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication) +[OAuth authentication](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication) for details. ### List servers in a profile @@ -157,7 +164,7 @@ This means all profiles use the same OAuth credentials for a given service. If you need to use different accounts for different projects, you'll need to revoke and re-authorize between switching profiles. -See [OAuth authentication](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication) +See [OAuth authentication](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md#oauth-authentication) for details on authorizing servers. ### Configuration persistence @@ -256,7 +263,7 @@ specify a different `--profile` value in the gateway command arguments. ## Further reading -- [Get started with MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/get-started.md) -- [Use MCP Toolkit from the CLI](/manuals/ai/mcp-catalog-and-toolkit/cli.md) -- [MCP Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) -- [MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) +- [Get started with MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/get-started.md) +- [Use MCP Toolkit from the CLI](/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md) +- [MCP Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) +- [MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md) diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md b/content/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md similarity index 94% rename from content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md rename to content/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md index 7a851c17effe..e416873f08c7 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md +++ b/content/manuals/desktop/features/mcp-catalog-and-toolkit/toolkit.md @@ -1,4 +1,5 @@ --- +url: /ai/mcp-catalog-and-toolkit/toolkit/ title: Docker MCP Toolkit linkTitle: Toolkit UI description: Use the MCP Toolkit to set up MCP servers and MCP clients. @@ -31,7 +32,7 @@ clients. It is the fastest way from MCP tool discovery to local execution. - Organizes MCP servers into profiles, acting as a gateway for clients to access the servers in each profile. > [!TIP] -> The MCP Toolkit includes [Dynamic MCP](/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md), +> The MCP Toolkit includes [Dynamic MCP](/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md), > which enables AI agents to discover, add, and compose MCP servers on-demand during > conversations, without manual configuration. Your agent can search the catalog and > add tools as needed when you connect to the gateway. @@ -194,6 +195,6 @@ For more information about the Agent mode, see the ## Further reading -- [Use MCP Toolkit from the CLI](/manuals/ai/mcp-catalog-and-toolkit/cli.md) -- [MCP Catalog](/manuals/ai/mcp-catalog-and-toolkit/catalog.md) -- [MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) +- [Use MCP Toolkit from the CLI](/manuals/desktop/features/mcp-catalog-and-toolkit/cli.md) +- [MCP Catalog](/manuals/desktop/features/mcp-catalog-and-toolkit/catalog.md) +- [MCP Gateway](/manuals/desktop/features/mcp-catalog-and-toolkit/mcp-gateway.md) diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index b0554e0361ee..4f69cc9800fb 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -21,7 +21,7 @@ The backend acts as: - On Linux, the `qemu` process performs this function. - File server: Handles file access from containers to the host filesystem. - When using gRPC FUSE, the backend performs the file sharing. - - When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process. + - When using `virtiofs`, or `krun`, file access is handled by those respective daemons rather than the backend process. - Control plane: Manages Docker API calls, port forwarding, and proxy configuration. The following table summarizes typical setups in more detail: @@ -32,7 +32,6 @@ The following table summarizes typical setups in more detail: | Windows (WSL 2) | WSL 2 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed | | Mac | Virtualization framework + gRPC FUSE | `com.docker.backend` | `com.docker.backend` | Recommended for performance and visibility | | Mac | Virtualization framework + `virtiofs` | `com.docker.backend` | Apple's Virtualization framework | Higher performance but no file access visibility from host | -| Mac | Virtualization framework + `osxfs` | `com.docker.backend` | `osxfs` | Legacy setup, not recommended | | Mac | DockerVMM + `virtiofs` | `com.docker.backend` | `krun` | Currently in Beta | | Linux | Native Linux VM | `qemu` | `virtiofsd` | No `com.docker.backend` process on Linux | @@ -66,13 +65,9 @@ Host firewalls can permit or deny inbound connections by filtering on `com.docke ## Using Docker Desktop with a proxy -Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop's proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies). All proxy traffic passes through `com.docker.backend.exe`. +Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop’s proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies). -When a proxy is enabled: - -- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`. -- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary. -- Docker Desktop then downloads the requested images or data through the proxy as usual. +Docker Desktop routes traffic through two separate proxies. The Containers proxy governs all `docker image pull` operations, as well as running container traffic when air-gapped container enforcement is enabled. The Docker Desktop proxy governs host-level traffic - the Desktop application, Docker CLI, and extensions — and is a fallback for image pulls only when the Containers proxy is not explicitly configured. Note that: diff --git a/content/manuals/desktop/features/networking/networking-how-tos.md b/content/manuals/desktop/features/networking/networking-how-tos.md index 15133e8352e9..1b25f20169e1 100644 --- a/content/manuals/desktop/features/networking/networking-how-tos.md +++ b/content/manuals/desktop/features/networking/networking-how-tos.md @@ -69,7 +69,7 @@ to give the container direct access to the network stack of the host. See the [run command](/reference/cli/docker/container/run/) for more details on publish options used with `docker run`. -All inbound connections pass through the Docker Desktop backend process (`com.docker.backend` (Mac), `com.docker.backend` (Windows), or `qemu` (Linux), which handles port forwarding into the VM. +All inbound connections pass through the Docker Desktop backend process (`com.docker.backend` (Mac), `com.docker.backend.exe` (Windows), or `qemu` (Linux)), which handles port forwarding into the VM. For more details, see [How exposed ports work](/manuals/desktop/features/networking/_index.md#how-exposed-ports-work) ### Working with VPNs @@ -97,7 +97,7 @@ For more details on proxies and proxy configurations, see the [Proxy settings do You can control how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks. -You can set the following settings on the **Network** tab in the Docker Desktop Dashboard settings, or if you're an admin, with Settings Management via the [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#networking), or the [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md) +You can set the following settings on the **Network** tab in the Docker Desktop Dashboard settings, or if you're an admin, with Settings Management via the [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#networking), or [Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) > [!NOTE] > diff --git a/content/manuals/desktop/features/synchronized-file-sharing.md b/content/manuals/desktop/features/synchronized-file-sharing.md index c039c56df8bd..496d20e9dec0 100644 --- a/content/manuals/desktop/features/synchronized-file-sharing.md +++ b/content/manuals/desktop/features/synchronized-file-sharing.md @@ -13,7 +13,7 @@ Synchronized file shares is an alternative file sharing mechanism that provides Synchronized file shares is ideal for developers who: - Have large repositories or monorepos with 100 000 files or more totaling hundreds of megabytes or even gigabytes. -- Are using virtual filesystems, such as VirtioFS, gRPC FUSE, and osxfs, which are no longer scaling well with their codebases. +- Are using virtual filesystems, such as VirtioFS and gRPC FUSE which are no longer scaling well with their codebases. - Regularly encounter performance limitations. - Don't want to worry about file ownership or spend time resolving conflicting file-ownership information when modifying multiple containers. @@ -29,7 +29,7 @@ After creating a file share instance, any container using a bind mount that poin > [!IMPORTANT] > -> Synchronized file shares isn't available on WSL or when using Windows containers. +> Synchronized file shares isn't available when using Windows containers. ## Create a file share instance diff --git a/content/manuals/desktop/features/vmm.md b/content/manuals/desktop/features/vmm.md index f3b3f04d349e..9f2aaefc85fe 100644 --- a/content/manuals/desktop/features/vmm.md +++ b/content/manuals/desktop/features/vmm.md @@ -1,59 +1,92 @@ --- -title: Virtual Machine Manager for Docker Desktop on Mac +title: Virtual Machine Manager linkTitle: Virtual Machine Manager -keywords: virtualization software, resource allocation, mac, docker desktop, vm monitoring, vm performance, apple silicon -description: Discover Docker Desktop for Mac's Virtual Machine Manager (VMM) options, including Docker VMM for Apple Silicon, offering enhanced performance and efficiency +keywords: virtualization software, resource allocation, mac, windows, docker desktop, vm performance, apple silicon, wsl, hyper-v +description: Learn about Docker Desktop's Virtual Machine Manager options, including Docker VMM for Mac and Windows weight: 110 +params: + sidebar: + badge: + color: blue + text: Updated --- -Docker Desktop supports multiple Virtual Machine Managers (VMMs) to power the Linux VM that runs containers. You can choose the most suitable option based on your system architecture (Intel or Apple Silicon), performance needs, and feature requirements. This page provides an overview of the available options. - -To change the VMM, go to **Settings** > **General** > **Virtual Machine Manager**. +Docker Desktop supports multiple Virtual Machine Managers (VMMs) to power the Linux VM that runs containers. The options available depend on your platform. ## Docker VMM {{< summary-bar feature_name="VMM" >}} -Docker VMM is a container-optimized hypervisor. By optimizing both the Linux kernel and hypervisor layers, Docker VMM delivers significant performance enhancements across common developer tasks. +Docker VMM is a container-optimized virtual machine manager. Starting with +Docker Desktop 4.86, it uses Docker's own VMM implementation instead of +`libkrun`, which was used in versions 4.35 through 4.85 on Mac. Built specifically for container workloads, Docker VMM: -Some key performance enhancements provided by Docker VMM include: +- Returns idle memory to the host when containers aren't active, so Docker Desktop doesn't hold RAM it's not using +- Improves file I/O between container and host, reducing latency in the edit-compile-test loop +- Reduces engine and container start-up time -- Faster I/O operations: With a cold cache, iterating over a large shared filesystem with `find` is 2x faster than when the Apple Virtualization framework is used. -- Improved caching: With a warm cache, performance can improve by as much as 25x, even surpassing native Mac operations. +Because Docker controls the virtualization layer, it can be monitored and governed in ways that aren't possible with third-party backends. On Windows, Docker VMM provides a stable alternative to WSL 2 with a real VM boundary between the container environment and the host. -These improvements directly impact developers who rely on frequent file access and overall system responsiveness during containerized development. Docker VMM marks a significant leap in speed, enabling smoother workflows and faster iteration cycles. +### Switch to Docker VMM -> [!NOTE] -> -> Docker VMM requires a minimum of 4GB of memory to be allocated to the Docker Linux VM. The memory needs to be increased before Docker VMM is enabled, and this can be done from the **Resources** tab in **Settings**. +Docker VMM requires a minimum of 4 GB of memory allocated to the Docker Linux VM. Increase memory in **Settings** > **Resources** before switching. -### Known issues +{{< tabs >}} +{{< tab name="Mac (Apple Silicon)" >}} -As Docker VMM is still in Beta, there are a few known limitations: +1. Go to **Settings** > **General** > **Virtual Machine Manager**. +2. Select **Docker VMM**. +3. Select **Apply & restart**. -- Docker VMM does not currently support Rosetta, so emulation of amd64 architectures is slow. Docker is exploring potential solutions. -- Certain databases, like MongoDB and Cassandra, may fail when using virtiofs with Docker VMM. This issue is expected to be resolved in a future release. +If you previously had Docker VMM selected, which engine runs depends on your version: -## Apple Virtualization framework +- Docker Desktop 4.35 and earlier is backed by `libkrun` +- Docker Desktop 4.86 and later uses Docker's own VMM implementation -The Apple Virtualization framework is a stable and well-established option for managing virtual machines on Mac. It has been a reliable choice for many Mac users over the years. This framework is best suited for developers who prefer a proven solution with solid performance and broad compatibility. +If you're upgrading from version 4.35 onwards, your setting is preserved and Docker Desktop switches to the new Docker VMM automatically on restart. -## QEMU (Legacy) for Apple Silicon +{{< /tab >}} +{{< tab name="Windows" >}} -> [!NOTE] -> -> QEMU has been deprecated in versions 4.44 and later. For more information, see the [blog announcement](https://www.docker.com/blog/docker-desktop-for-mac-qemu-virtualization-option-to-be-deprecated-in-90-days/) +1. Go to **Settings** > **General** > **Virtual Machine Manager**. +2. Select **Docker VMM**. +3. Select **Apply & restart**. + +{{< /tab >}} +{{< /tabs >}} + +### Known issues -QEMU is a legacy virtualization option for Apple Silicon Macs, primarily supported for older use cases. +- A restart of Docker Desktop may be required after switching to Docker VMM. +- Docker VMM does not support bind mount auto-shares. If you see a `file is not shared from the host` error, go to **Settings** > **Resources** > **File sharing** and add the directory you want to share. -Docker recommends transitioning to newer alternatives, such as Docker VMM or the Apple Virtualization framework, as they offer superior performance and ongoing support. Docker VMM, in particular, offers substantial speed improvements and a more efficient development environment, making it a compelling choice for developers working with Apple Silicon. +#### Mac only -Note that this is not related to using QEMU to emulate non-native architectures in [multi-platform builds](/manuals/build/building/multi-platform.md#qemu). +- Docker VMM does not currently support Rosetta, so emulation of amd64 architectures is slow. Docker is exploring potential solutions. +- Certain databases, such as MongoDB and Cassandra, may fail when using virtiofs with Docker VMM. This issue is expected to be resolved in a future release. + +## Alternative VMMs for Mac + +### Apple Virtualization framework -## HyperKit (Legacy) for Intel-based Macs +The Apple Virtualization framework is a stable and well-established option for managing virtual machines on Mac. It has been a reliable choice for many Mac users over the years. + +### HyperKit (Legacy) for Intel-based Macs > [!NOTE] > > HyperKit is deprecated. Docker recommends switching to the Apple Virtualization framework. HyperKit is a legacy virtualization option for Intel-based Macs. Docker recommends switching to modern alternatives for better performance and to future-proof your setup. + +## Alternative VMMs for Windows + +### WSL 2 + +WSL 2 (Windows Subsystem for Linux 2) is the default Windows backend for Docker Desktop. It runs a full Linux kernel inside a lightweight VM with tight integration into the Windows host file system and networking. WSL 2 is available in both per-user and all-users installation modes and does not require administrator privileges. + +For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). + +### Hyper-V + +Hyper-V is Windows' native hypervisor. It runs the Docker Linux VM in a fully isolated virtual machine, providing a strong boundary between the container environment and the Windows host. Hyper-V is only available in all-users installation mode and requires administrator privileges. diff --git a/content/manuals/desktop/features/wasm.md b/content/manuals/desktop/features/wasm.md index 7ea9942057e3..c8b8e9a2c619 100644 --- a/content/manuals/desktop/features/wasm.md +++ b/content/manuals/desktop/features/wasm.md @@ -37,9 +37,8 @@ then pre-existing images and containers will be inaccessible. 1. Navigate to **Settings** in Docker Desktop. 2. In the **General** tab, check **Use containerd for pulling and storing images**. -3. Go to **Features in development** and check the **Enable Wasm** option. +3. Go to **Beta features** and check the **Enable Wasm** option. 4. Select **Apply** to save the settings. -5. In the confirmation dialog, select **Install** to install the Wasm runtimes. Docker Desktop downloads and installs the following runtimes: - `io.containerd.slight.v1` @@ -69,7 +68,7 @@ If you are receiving an error message, see the [troubleshooting section](#troubl Note the `--runtime` and `--platform` flags used in this command: -- `--runtime=io.containerd.wasmedge.v1`: Informs the Docker engine that you want +- `--runtime=io.containerd.wasmedge.v1`: Informs Docker Engine that you want to use the Wasm containerd shim instead of the standard Linux container runtime - `--platform=wasi/wasm`: Specifies the architecture of the image you want to @@ -200,7 +199,7 @@ store](./containerd.md), an error similar to the following displays: docker: Error response from daemon: Unknown runtime specified io.containerd.wasmedge.v1. ``` -[Turn on the containerd feature](./containerd.md#enable-the-containerd-image-store) +[Turn on the containerd feature](./containerd.md#switch-image-stores) in Docker Desktop settings and try again. ### Failed to start shim: failed to resolve runtime path diff --git a/content/manuals/desktop/features/wsl/_index.md b/content/manuals/desktop/features/wsl/_index.md index 9b846303f750..ea7b6e252594 100644 --- a/content/manuals/desktop/features/wsl/_index.md +++ b/content/manuals/desktop/features/wsl/_index.md @@ -10,6 +10,7 @@ aliases: - /docker-for-windows/wsl/ - /desktop/windows/wsl/ - /desktop/wsl/ +- /docker-for-windows/wsl-tech-preview/ --- Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft that lets Linux distributions run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing, faster cold-start times, and dynamic resource allocation. @@ -34,8 +35,8 @@ Before you turn on the Docker Desktop WSL 2 feature, ensure you have: Before installing Docker Desktop, uninstall any version of Docker Engine or the Docker CLI that was installed directly inside a WSL Linux distribution. Running both can cause conflicts. -1. Download and install the latest version of [Docker Desktop for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows). -2. Follow the usual installation instructions to install Docker Desktop. Depending on which version of Windows you are using, Docker Desktop may prompt you to turn on WSL 2 during installation. Read the information displayed on the screen and turn on the WSL 2 feature to continue. +1. [Install Docker Desktop for Windows](/manuals/desktop/setup/install/windows-install.md). +2. During installation, Docker Desktop may prompt you to turn on WSL 2. Read the information displayed on the screen and turn on the WSL 2 feature to continue. 3. Start Docker Desktop from the **Windows Start** menu. 4. Navigate to **Settings**. 5. From the **General** tab, select **Use WSL 2 based engine**. @@ -96,7 +97,7 @@ WSL is designed to aid interoperability between Windows and Linux environments. For environments that require stricter isolation: - Run Docker Desktop in Hyper-V mode instead of WSL 2 to avoid the shared-kernel model entirely. -- Enable [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) to add an additional layer of protection around container workloads regardless of backend. +- Enable [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) to add an additional layer of protection around container workloads regardless of backend. ## Additional resources diff --git a/content/manuals/desktop/images/console.png b/content/manuals/desktop/images/console.png deleted file mode 100644 index 75ff7c104028..000000000000 Binary files a/content/manuals/desktop/images/console.png and /dev/null differ diff --git a/content/manuals/desktop/images/resource-saver-settings.webp b/content/manuals/desktop/images/resource-saver-settings.webp deleted file mode 100644 index c43a64df94ee..000000000000 Binary files a/content/manuals/desktop/images/resource-saver-settings.webp and /dev/null differ diff --git a/content/manuals/desktop/previous-versions/edge-releases-mac.md b/content/manuals/desktop/previous-versions/edge-releases-mac.md index 6ab358c1dcc6..841e3a661694 100644 --- a/content/manuals/desktop/previous-versions/edge-releases-mac.md +++ b/content/manuals/desktop/previous-versions/edge-releases-mac.md @@ -1104,7 +1104,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - Add daemon options validation - Diagnose can be cancelled & Improved help information. Fixes [docker/for-mac#1134](https://github.com/docker/for-mac/issues/1134), [docker/for-mac#1474](https://github.com/docker/for-mac/issues/1474) -- Support paging of Docker Cloud [repositories](../../docker-hub/repos/_index.md) and [organizations](../../admin/organization/setup/orgs.md). Fixes [docker/for-mac#1538](https://github.com/docker/for-mac/issues/1538) +- Support paging of Docker Cloud [repositories](../../docker-hub/repos/_index.md) and [organizations](../../accounts/organization/setup/orgs.md). Fixes [docker/for-mac#1538](https://github.com/docker/for-mac/issues/1538) ### Docker Community Edition 17.06.1-ce-mac20, 2017-07-18 @@ -1703,8 +1703,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of - large directory trees, may suffer from poor performance. More information is - available in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. + large directory trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart `Docker.app`. @@ -1733,8 +1732,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory - trees, may suffer from poor performance. More information is available in - [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. + trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app. @@ -1768,7 +1766,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory - trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. + trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart `Docker.app`. @@ -1794,7 +1792,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. +- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1817,7 +1815,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. More information is available in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). +- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1864,7 +1862,7 @@ events or unexpected unmounts. - Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks, and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in [Logs and Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md). +- There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks, and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. - Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1906,10 +1904,6 @@ events or unexpected unmounts. - `com.docker.slirp`: included the DNS TCP fallback fix, required when UDP responses are truncated - `docker build/events/logs/stats...` won't leak when interrupted with Ctrl-C -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). - ### Beta 18.1 Release Notes (2016-07-07 1.12.0-rc3-beta18.1) > [!NOTE] @@ -1934,10 +1928,6 @@ events or unexpected unmounts. - VPNKit: Improved scalability as number of network connections increases - The docker API proxy was failing to deal with some 1.12 features, such as health check. -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). - ### Beta 18 Release Notes (2016-07-06 1.12.0-rc3-beta18) **New** @@ -1955,9 +1945,6 @@ events or unexpected unmounts. - Interrupting a `docker build` with Ctrl-C will actually stop the build - The docker API proxy was failing to deal with some 1.12 features, such as health check. -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 17 Release Notes (2016-06-29 1.12.0-rc2-beta17) @@ -1974,9 +1961,6 @@ events or unexpected unmounts. - Fixed "failure: No error" message in diagnostic panel - Improved diagnostics for networking and logs for the service port openers -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 16 Release Notes (2016-06-17 1.12.0-rc2-beta16) @@ -1995,9 +1979,6 @@ events or unexpected unmounts. - HyperKit API: Improved error reporting - osxfs: fix sporadic EBADF due to fd access/release races (#3683) -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 15 Release Notes (2016-06-10 1.11.2-beta15) @@ -2019,10 +2000,6 @@ events or unexpected unmounts. - Hyperkit: `vsock` stability improvements - Fixed crash when user is admin -**Known issues** - -- See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). - ### Beta 14 Release Notes (2016-06-02 1.11.1-beta14) **New** diff --git a/content/manuals/desktop/previous-versions/edge-releases-windows.md b/content/manuals/desktop/previous-versions/edge-releases-windows.md index 1b8997283e07..ec1c10276a3d 100644 --- a/content/manuals/desktop/previous-versions/edge-releases-windows.md +++ b/content/manuals/desktop/previous-versions/edge-releases-windows.md @@ -1999,7 +1999,7 @@ work. Some insider builds may not work. **Known issues** * Only UTF-8 passwords are supported for host filesystem sharing -* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). +* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc`. ### Beta 22 Release (2016-08-11 1.12.0-beta22) @@ -2007,7 +2007,7 @@ Unreleased. See Beta 23 for changes. **Known issues** -* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). +* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc`. ### Beta 21 Release (2016-07-28 1.12.0-beta21) @@ -2308,7 +2308,7 @@ This Beta release includes some significant changes: **Known issues** -* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. See [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) for more details. +* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. * Logs for the windows service are not aggregated with logs from the GUI. This is expected to be fixed in future versions. diff --git a/content/manuals/desktop/release-notes.md b/content/manuals/desktop/release-notes.md index e8061bade6ec..c7c7b1148b6e 100644 --- a/content/manuals/desktop/release-notes.md +++ b/content/manuals/desktop/release-notes.md @@ -24,12 +24,991 @@ Docker Desktop versions older than 6 months from the latest release are not avai For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/releases.md). +## 4.97.0 + +{{< release-date date="2026-10-26" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.97.0" build_path="/244584/" >}} + + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed a spurious Resource Saver error when signing out while sign-in enforcement is enabled. +- Fixed diagnostics collection being slow when the backend is unresponsive, reducing worst-case wait time from several minutes to approximately 3 seconds. +- Fixed reliability issues with the container exec terminal: closing a container no longer triggers spurious error reports, and terminal resize now works correctly on startup. +- Fixed an issue where the Date header in Docker API responses was incorrect after Docker Desktop entered Resource Saver mode. +- Added the `-e`/`--env` flag to `docker pass run` for setting environment variables, including `se://` secret references. +- Fixed `docker pass set` printing "context canceled" on Ctrl-C at the value prompt. +- Improved responsiveness when searching the **Images**, **Containers** and **Volumes** lists. +- Fixed an unhandled error when viewing the files of a Compose project whose config file no longer exists. + +#### For Mac + +- Fixed adding Docker Desktop commands to the PATH failing for fish users without a `~/.config/fish` directory. +- Added a setting to allow privileged ports (1-1024) to be exposed to other machines on the LAN. + +#### For Windows + +- Added a Docker VMM (Beta) backend option to the Windows installer. +- Fixed an issue on Windows where a slow WSL version check asked to update WSL. +- Fixed Docker VMM requiring a Docker Desktop restart to share a new bind-mount directory from the host. +- Fixed WSL installer errors (e.g. `Wsl/CallMsi/`) being misidentified as disk-related failures, preventing misleading 'disk file has been deleted' recovery messages. +- Fixed Docker Desktop becoming unresponsive, with `docker` commands hanging and Quit not working, after the disk filled up or, on Windows, after the backend's console host process exited. Fixes [docker/desktop-feedback#429](https://github.com/docker/desktop-feedback/issues/429) and [docker/desktop-feedback#699](https://github.com/docker/desktop-feedback/issues/699). +- Fixed an issue where the installer rejected `--backend=docker-vmm` when combined with `--user` flag or Microsoft Store installs. +- Fixed factory reset to stop Docker engines before deleting data, surface cleanup failures as an error dialog, and clean up custom data-root directories. +- Fixed Windows containers failing to start with a "Path contains symlink" error on `callback.sock`. +- Fixed a bug where the installer could leave a file under `C:\ProgramData\DockerDesktop` with no permissions at all, making it unreadable to diagnostics and to later installs. +- Fixed a bug where the disk image location could not be moved back to a folder it had previously been moved out of. Fixes [docker/desktop-feedback#565](https://github.com/docker/desktop-feedback/issues/565). +- Fixed a bug where a failed update could put back Start Menu and desktop shortcuts that had been deleted on purpose. +- `--user` mode is now the default for new Docker Desktop `.EXE` installations. + +## 4.96.3 + +{{< release-date date="2026-10-22" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.96.3" build_path="/244472/" >}} + +### Updates + +- Docker Init `v1.4.1` +- Docker Offload `v0.7.19` +- Docker Model Runner `v1.2.9` +- Docker Debug `v0.49.0` +- Docker MCP `v0.44.2` +- `kubectl` `v1.36.1` + +### Security + +- Removed trust for certificates issued by the compromised [eMudhra intermediate CA compromise](https://emudhra.we-have-a-problem.com/). An attacker with network access could have used these certificates to intercept TLS connections made by non-browser clients, such as the Docker CLI and daemon. + +## 4.96.2 + +{{< release-date date="2026-10-22" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.96.2" build_path="/244353/" >}} + +### Updates + +- [Docker Compose v5.6.1](https://github.com/docker/compose/releases/tag/v5.6.1) +- Docker Offload `v0.7.6` +- [Docker Agent v1.152.0](https://github.com/docker/docker-agent/releases/tag/v1.152.0) +- [Docker Hardened Images CLI (`dhictl`) v0.0.9](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.9) +- Docker Desktop Build `v0.39.1` +- [Docker Scout CLI v1.27.0](https://github.com/docker/scout-cli/releases/tag/v1.27.0) +- Docker pass `v0.3.2` + +### Security + +- Removed trust for certificates issued by the compromised [eMudhra intermediate CA compromise](https://emudhra.we-have-a-problem.com/). An attacker with network access could have used these certificates to intercept TLS connections made by non-browser clients, such as the Docker CLI and daemon. + +> [!IMPORTANT] +> +> This fix is being rolled out in batches as individual Docker Desktop components are updated. Upcoming patch releases will cover the remaining components. We recommend updating to each patch release as soon as it’s available. + +## 4.96.1 + +{{< release-date date="2026-10-21" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.96.1" build_path="/244132/" >}} + +### Updates + +- [Docker Engine 29.9.2](https://github.com/docker/docker/releases/tag/29.9.2) +- [Docker Buildx v0.38.1](https://github.com/docker/buildx/releases/tag/v0.38.1) +- [Credential helpers to v0.9.12](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.12) +- Docker Offload `v0.7.16` + +### Security + +- Removed trust for certificates issued by the compromised [eMudhra intermediate CA compromise](https://emudhra.we-have-a-problem.com/). An attacker with network access could have used these certificates to intercept TLS connections made by non-browser clients, such as the Docker CLI and daemon. + +> [!IMPORTANT] +> +> This fix is being rolled out in batches as individual Docker Desktop components are updated. Upcoming patch releases will cover the remaining components. We recommend updating to each patch release as soon as it’s available. + +## 4.96.0 + +{{< release-date date="2026-10-19" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.96.0" build_path="/243774/" >}} + +### Updates + +- [Credential helpers v0.9.10](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.10) +- [containerd v2.4.2](https://github.com/containerd/containerd/releases/tag/v2.4.2) +- Docker Desktop Build `v0.39.0` +- Docker Offload `v0.7.4` +- `docker pass` v0.3.0 +- [Docker Engine v29.9.1](https://docs.docker.com/engine/release-notes/29/#2991) +- [Docker Buildx v0.38.0](https://github.com/docker/buildx/releases/tag/v0.38.0) +- [Docker Agent v1.149.0](https://github.com/docker/docker-agent/releases/tag/v1.149.0) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where the error dialog could close unexpectedly on systems under memory pressure. +- Fixed an issue where Docker Desktop's internal DHCP replies were sent onto the host's physical network. +- Fixed the reclaimable space on the **Images** view staying at 0 when a local image has no history. +- Improved telemetry for secrets injection by including the realm of each resolved environment variable secret reference in observability events. +- Fixed Docker Desktop getting stuck on "Starting the Docker Engine..." when a Docker network took addresses inside Docker Desktop's internal network (`192.168.65.0/24` by default). Such networks are now rejected, and an existing one can be removed from the error dialog. Fixes [docker/desktop-feedback#659](https://github.com/docker/desktop-feedback/issues/659). +- Fixed file ownership and transient `0:0` reporting on Apple Virtualization Framework + VirtioFS bind mounts. Fixes [docker/desktop-feedback#628](https://github.com/docker/desktop-feedback/issues/628) and [#649](https://github.com/docker/desktop-feedback/issues/649). +- Fixed the CLI error message when combining a leading `+` with a trailing `ago` in a time span to read as natural prose. +- Fixed a bug where uninstalling Docker Desktop could leave the installation directory behind. +- Added a **Check for updates** button to the **Software update** drawer when an update is available or ready to install, so newer releases can be found without installing the pending update first. +- Fixed the backend crashing, and the engine becoming unreachable, when a container's `--volumes-from` refers back to itself, for example after renaming a container to the name of the removed container it inherits volumes from. See [docker/desktop-feedback#286](https://github.com/docker/desktop-feedback/issues/286). +- Clearing Gordon sessions no longer deletes sessions that are still running. +- Improved buffered filesystem performance and fixed a FUSE issue that could expose stale bytes when extending files. + +#### For Mac + +- Fixed an issue where a misconfigured `allowedOrgs` type in a configuration profile was silently ignored; admins now see a log message explaining why sign-in enforcement is not applied. +- Fixed Docker Desktop on Mac not reporting an error when the VM stops unexpectedly. + +#### For Windows + +- Fixed an issue where tray icon light/dark theme detection could fail. +- Fixed disk full detection on Windows so that a full-disk error during startup now shows the disk full recovery dialog instead of a generic failure dialog. +- Fixed an issue on Windows where WSL distro startup failures showed a confusing 'bad magic string' error instead of the actual reason reported by wsl.exe. +- Improved the error shown when Docker VMM cannot use the Windows hypervisor, for example on some virtual machines where WSL 2 works. +- Fixed a bug where an unusable WSL data disk (e.g., already in use) would repeatedly trigger failed mkfs format attempts instead of reporting a clear error. + +## 4.95.0 + +{{< release-date date="2026-10-12" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.95.0" build_path="/242831/" >}} + +### Updates + +- [Docker Compose v5.6.0](https://github.com/docker/compose/releases/tag/v5.6.0) +- [Docker Offload v0.6.73](https://github.com/docker/cloud/releases/tag/v0.6.73) +- [Docker Scout CLI v1.26.0](https://github.com/docker/scout-cli/releases/tag/v1.26.0) +- [Docker Agent v1.145.0](https://github.com/docker/docker-agent/releases/tag/v1.145.0) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed the engine restarting right after Docker Desktop starts when an admin policy enables Enhanced Container Isolation. +- Fixed automatic update downloads starting before sign-in on machines that enforce sign-in, which could ignore an organization's policy disabling updates. +- Fixed long Ask Gordon conversations where the end of responses was hidden behind the user's message, and where scrolling up jumped around or got stuck. +- Fixed **Settings** accepting a disk image location inside the Docker Desktop installation directory, which the installer replaces on every update. Fixes [docker/desktop-feedback#667](https://github.com/docker/desktop-feedback/issues/667). +- Fixed **Quit** doing nothing in the error dialog shown when the Docker Engine fails, and the dialog taking around 2 minutes to appear when the engine fails while starting. +- Fixed an issue where Gordon AI chat displayed the final answer inside the collapsed Activity section instead of below it when token usage was hidden by the gateway. +- Fixed an issue where gathering diagnostics from the error dialog failed repeatedly when Docker Desktop could not start. +- Fixed Kubernetes occasionally failing to start when a Registry Access Management image pull hit a transient network timeout. +- Added `docker desktop auth status` CLI subcommand to display Docker Hub login status, username, email, plan, and organization membership, with `--format pretty|json` output options. + +#### For Mac + +- Fixed Docker Desktop being unable to start subprocesses after being launched a second time. + +#### For Windows + +- Fixed an issue on Windows with WSL 3.0.1 where `docker info` reported `Docker Desktop (containerized)` instead of `Docker Desktop`, causing `docker debug` to fail when Registry Access Management is enabled. +- Fixed a Windows update failure where `app.asar` was reported as locked by Docker Desktop. +- Fixed the Windows installer deleting the WSL data disk during an update when the data root was inside the installation directory. Fixes [docker/desktop-feedback#667](https://github.com/docker/desktop-feedback/issues/667). +- Fixed Docker Desktop failing to start with the Hyper-V backend when the Windows hosts file is protected by an antivirus or endpoint security tool. +- Fixed issues on Windows with WSL/MSYS2 native symlink (LX symlink) handling, sparse stream exports via backup tar, and a race condition in named pipe listener close. +- Added a dedicated error message when the Hyper-V virtual machine cannot start because the host does not have enough free memory. +- Fixed an intermittent MSI installation failure (error code 1603) on Windows caused by analytics custom actions racing with other installer steps. +- Fixed a per-user installation on Windows silently completing on machines where the Virtual Machine Platform feature is disabled, leaving Docker Desktop unable to start. +- The Windows installer now fails with an explicit error when a per-user installation is attempted from the SYSTEM account (e.g. deployed via SCCM or Intune), instead of silently installing into the SYSTEM profile. +- Fixed an issue where the Hyper-V VM could fail to start after a restart because its disk was still being compacted. + +## 4.94.0 + +{{< release-date date="2026-10-05" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.94.0" build_path="/241994/" >}} + +### Update + +- Docker Offload `v0.6.53` +- [containerd v2.3.6](https://github.com/containerd/containerd/releases/tag/v2.3.6) +- [Docker Agent v1.144.0](https://github.com/docker/docker-agent/releases/tag/v1.144.0) +- [NVIDIA Container Toolkit v1.20.1](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.20.1) +- [Docker Scout CLI v1.25.0](https://github.com/docker/scout-cli/releases/tag/v1.25.0) +- [Docker Engine v29.8.2](https://docs.docker.com/engine/release-notes/29/#2982) +- [Docker Buildx v0.37.2](https://github.com/docker/buildx/releases/tag/v0.37.2) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where Resource Saver could pause the VM before the Docker API was ready, causing transient errors during engine startup or restart. +- Fixed `kubectl logs` not working with `kubeadm`. +- Fixed the Docker Desktop service being left stopped after an update when it was running but not configured to auto-start. +- Fixed stored API keys being written in clear to Docker Desktop logs and included in diagnostics bundles. +- Fixed the account name and tier briefly showing as empty and personal after a restart when Docker Hub was slow to respond. +- Changed the default logging driver for new Linux containers to `local` to enable automatic log rotation and reduce disk usage. +- Fixed an issue in the **Images** view where the reclaimable disk space value could get stuck at **0 Bytes** while selecting images for deletion. +- Improved VM disk creation speed and reduced host disk space usage by skipping unnecessary inode table zeroing on sparse and pre-zeroed storage. +- Fixed Docker Desktop writing a multi-gigabyte error file and consuming excessive memory when the backend failed to start. +- Docker Desktop now names the settings file that needs correcting instead of reporting an unexpected error when it contains invalid JSON. +- Stopped Docker Desktop logs from recording unobfuscated values for IPC payloads that are JSON arrays or plain strings. +- Fixed a deadlock that caused Docker Desktop to hang indefinitely when quitting while an engine recovery or error dialog was displayed. +- Fixed the kindest/node tag showing blank in `docker desktop kubernetes images`. +- docker-pass: + - Removing a secret that does not exist is now consistent with other `docker remove` commands. + - Running the examples from the help text no longer prefixes the secret with a line break. +- Fixed long Ask Gordon conversations where the end of responses was hidden behind the user's message, and where scrolling up jumped around or got stuck. + +#### For Mac + +- Fixed the update tooltip suggesting to move Docker Desktop to `/Applications` when that is the folder the current user cannot modify. Fixes [docker/desktop-feedback#598](https://github.com/docker/desktop-feedback/issues/598). +- Fixed repeated privileged-access prompts when Docker Desktop starts automatically after a reboot. Fixes [docker/desktop-feedback#651](https://github.com/docker/desktop-feedback/issues/651). +- Fixed the "CLI tools installation" setting on macOS reverting to System when Docker Desktop could not update the login shell profile. +- Fixed zsh completions not being set up when `~/.zshrc` doesn't exist. + +#### For Windows + +- Improved WSL startup errors to explain when virtualization is disabled in firmware, nested virtualization is unavailable, or the Windows hypervisor is disabled at startup, with guidance for resolving each condition. +- Fixed the Docker Desktop service losing its automatic start mode after an update run by WinGet or another external installer when the service had been installed with `--always-run-service`. +- Fixed a bug introduced in 4.92.0 where WSL integration could fail to start with "timed out waiting for ... to be automounted". Fixes [docker/desktop-feedback#695](https://github.com/docker/desktop-feedback/issues/695). + +#### For Linux + +- Fixed a bug on Linux where quitting Docker Desktop could close unrelated applications, including all open terminal windows. Fixes [docker/desktop-linux#109](https://github.com/docker/desktop-linux/issues/109). + +## 4.93.0 + +{{< release-date date="2026-09-28" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.93.0" build_path="/240920/" >}} + +### Updates + +- Docker Offload `v0.6.33` +- [Docker Agent v1.141.0](https://github.com/docker/docker-agent/releases/tag/v1.141.0) +- [Docker Engine v29.8.1](https://docs.docker.com/engine/release-notes/29/#2981) +- Linux kernel `v7.0.14` + +### Bug fixes and enhancements + +#### For all platforms + +- CLI plugin updates are now managed directly from the app bundle and the **Automatically update components** setting has been removed. +- Fixed Enhanced Container Isolation not being enforced on an engine that was left running while another one was in use. +- Fixed Enhanced Container Isolation not being enforced when an administrator policy arrived after the engine had started. +Fixed Enhanced Container Isolation not being enforced when the sign-in completed after the engine had started. +- Fixed file sharing directories (and other list settings) reverting to their default after clearing them and restarting Docker Desktop. Fixes [docker/desktop-feedback#515](https://github.com/docker/desktop-feedback/issues/515). +- Fixed a security vulnerability that allowed VM-side code to request Unix socket port forwards, which could expose arbitrary host paths to manipulation. +- Fixed an issue where dismissing the walkthroughs lead-in on the **Containers** or **Images** screen was not reliably preserved across sessions. +- Fixed a silent failure when Docker Desktop cannot open an external URL by showing an error notification, and fixed ephemeral error notifications incorrectly appearing as unread in the notification bell. +- Fixed an issue where Docker Desktop continued showing Kubernetes as running after a cloud cluster stopped externally. +- Fixed cluster reconnect failures in Kubernetes Offload mode and updated the cluster creation dialog to show only relevant kind cluster options when in Offload mode. +- Fixed Docker Desktop failing to start with an unexpected error when the engine needed more than five minutes to recover after an unclean shutdown. +- Updated the Linux kernel to 7.0.14, fixing MongoDB 8 containers refusing to start. Fixes [docker/desktop-feedback#682]. + +#### For Mac + +- Fixed the command-line installer removing the privileged `vmnetd` helper when run without `--user`. +- Fixed a bug that could make Docker Desktop updates fail repeatedly when a leftover staging directory from a previous update couldn't be deleted. +- Added a clear error message when macOS denies Docker Desktop the virtualization entitlement, for example due to an MDM configuration profile. +- Fixed an issue where the Repair function showed no explanation when CLI plugins failed to be correctly set up. +- Docker Desktop no longer overwrites a more recent CLI plugin installed under `~/.docker/cli-plugins`, matching existing Windows behavior. +- Fixed "previous version restored" after a failed update even when the restore itself failed. + +#### For Windows + +- Fixed an issue where MSI installs never added the installing user to the `docker-users` group, requiring manual group membership configuration. +- Fixed an issue on Windows where update failures showed a generic error message instead of the actual installer error details. +- Fixed a bug where a failed read of a WSL distro's `config.json` caused the distro agent to crash, disabled WSL integration, and prevented factory reset from cleaning up `~/.docker` properly. +- Fixed an issue where the Docker CLI credential store in a WSL2 distro could be unexpectedly reset to the default on restart. +- Fixed an unhelpful error message when WSL timed out registering the Docker Desktop Linux distribution. +- Fixed spurious "WSL integration with distro unexpectedly stopped" dialogs when the Docker Desktop engine was being stopped or restarted. +- Fixed a false "Virtualization support not detected" error when starting the WSL2 backend on Windows systems with Virtual Machine Platform enabled but the vfpext service absent. +- Fixed a startup crash (exit code 151) on Windows when config files such as `settings-store.json` or `daemon.json` were saved with a UTF-8 BOM by an external editor or provisioning tool. +- Fixed a WSL integration issue where the proxy could fatally timeout at startup when restoring persisted bind mounts, especially with non-default `wsl.conf` automount root configurations. + +#### For Linux + +- Docker Desktop no longer overwrites a more recent CLI plugin installed under `~/.docker/cli-plugins`, matching existing Windows behavior. + +## 4.92.0 + +{{< release-date date="2026-09-21" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.92.0" build_path="/240144/" >}} + +### Updates + +- [containerd v2.3.5](https://github.com/containerd/containerd/releases/tag/v2.3.5) +- [Docker Agent v1.140.0](https://github.com/docker/docker-agent/releases/tag/v1.140.0) +- [Docker Buildx v0.37.1](https://github.com/docker/buildx/releases/tag/v0.37.1) +- Docker Offload `v0.6.27` + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed published ports staying unreachable for the life of the container when the host port was momentarily busy. +- Fixed in-app updates repeatedly failing when the update manifest contains no installer matching the current installation. +- Fixed Kubernetes staying on "Starting Kubernetes" indefinitely when the cluster failed to initialize. The error is now reported. +- Fixed **Send Diagnostics** hanging indefinitely, or showing an unhelpful error, when a proxy blocks the upload. +- Fixed container start, stop, and restart failures in the Docker Desktop Dashboard reporting only a generic HTTP error instead of the reason reported by Docker Engine. +- Fixed Docker Hub repository and tag browsing to use Docker Hub's current API, and removed the non-functional **Starred** and **Contributed** tabs from Docker Hub organization profiles. +- Fixed an issue where users signed out before a Docker Desktop update were not prompted to sign in after the app restarted. +- Fixed **Settings** section navigation to scroll to the selected section reliably, and added a divider between sections for easier visual parsing. +- Improved Kubernetes cloud cluster management by hiding the `kubeadm` option in the cluster dialog and resetting the cluster mode to kind when the dialog closes. +- Improved Ask Gordon so sessions start in the relevant project directory when launched from a volume or build history row, and added a banner that prompts you to select a project folder when chatting from an auto-generated scratch directory. +- Fixed Ask Gordon file diffs: edits that share a near-identical text prefix, the summary bar overlapping your message when scrolling, and row backgrounds and column width in the edit tool-call view. +- Fixed Ask Gordon chat: a blank command in the shell approval dialog, background job tool calls rendering as raw JSON, streamed command output jank, raw internal error details, and opening Ask Gordon from **Settings**, **Troubleshoot**, or **Support** corrupting drawer state for Ask Gordon, notifications, and the Learning Center. + +#### For Mac + +- Fixed moving the disk image to another location being slow on macOS 26. +- Fixed a macOS update failure where validating the staged app could fail even though the app was valid, and extended that validation to catch a staged app that fails to start. +- Fixed excessive idle CPU usage on Retina displays caused by a badge animation in the Ask Gordon interface. + +#### For Windows + +- Added support for migrating admin, per-machine installations to per-user installations when running the Docker VMM backend, in addition to WSL 2. +- Fixed an issue where Windows 10 users with the inbox `wsl.exe` saw a raw error instead of the prompt to update WSL when Docker Desktop checked the WSL version. +- Fixed `host.docker.internal` and `gateway.docker.internal` not being injected into Windows containers after Docker Desktop lost the container event stream. +- The MSI installer now refuses per-user installations, which are not supported, instead of installing a copy that later updates cannot upgrade. +- Fixed a misleading error message that claimed the WSL disk image had been deleted when WSL could not open it while registering the Docker Desktop distribution. +- Fixed Kubernetes failing to start after a WSL distro that had been integrated was unregistered. +- Fixed single-file bind mounts on Docker VMM. The "not shared from the host" error now points at the file's containing directory, and a file entry in the **File sharing** settings no longer prevents the engine from starting. +- Fixed Docker Desktop retrying the WSL engine indefinitely without reporting an error when WSL was unable to load its own kernel modules. +- Fixed disk image location moves always failing when moving to a different drive. Fixes [docker/desktop-feedback#548](https://github.com/docker/desktop-feedback/issues/548) and [docker/desktop-feedback#550](https://github.com/docker/desktop-feedback/issues/550). +- Fixed a failed incremental update not retrying with a full installer. +- Fixed the WSL 2 cross-distro bind-mount proxy serving stale or incomplete directory contents for host paths on slow-to-mount drives, such as Storage Pool volumes. + +### Security + +- Updated containerd to `v2.3.5`, addressing [CVE-2026-53495](https://github.com/advisories/GHSA-7jxh-36q5-gcqv). + +### Known issues + +- WSL integration can fail to start with `timed out waiting for ... to be automounted` when a distro's `wsl.conf` sets `[automount] root` to `/`, or after a container has bind-mounted a non-drive path under `/mnt`, such as WSLg's `/mnt/wslg`. As a workaround, downgrade to Docker Desktop 4.91.0, or remove the `root` setting from `wsl.conf` and run `wsl --shutdown`. + +## 4.91.0 + +{{< release-date date="2026-09-14" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.91.0" build_path="/239619/" >}} + +### Updates + +- [Docker Engine v29.8.0](https://docs.docker.com/engine/release-notes/29/#2980) +- [containerd v2.3.4](https://github.com/containerd/containerd/releases/tag/v2.3.4) +- [Docker Compose v5.5.1](https://github.com/docker/compose/releases/tag/v5.5.1) +- [Docker Agent v1.136.0](https://github.com/docker/docker-agent/releases/tag/v1.131.0) +- Docker Desktop Build `v0.38.0` +- [Docker Buildx v0.37.0](https://github.com/docker/buildx/releases/tag/v0.37.0) +- Docker Offload `v0.6.17` +- [Credential helpers v0.9.9](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.9) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where the **Last modified** column in the Volumes and container filesystem browsers displayed inaccurate timestamps like '57 years ago' instead of a blank when modification time was unavailable. +- Fixed Docker Desktop writing invalid export PATH syntax into csh/tcsh profiles when adding `~/.docker/bin` to PATH. +- Fixed an issue where Docker Scout CLI hints would persist after upgrading. +- Fixed a bug where a corrupt Docker network database, usually caused by an abrupt shutdown, prevented Docker Engine from starting and left a factory reset as the only recovery option. +- Fixed CLI plugin updates failing repeatedly when the plugin binary was locked by another process. The update is now retried automatically on the next start. +- Fixed Docker Desktop's interface getting stuck in an indefinite restart loop on machines with certain graphics driver issues, and added a message explaining when the interface can't be displayed due to a hardware compatibility problem. +- Improved startup experience in the new UI by showing a themed skeleton layout (header, sidebar, footer) immediately instead of a blank window while the app loads. +- Fixed Docker Desktop sometimes taking five extra minutes to report the engine as stopped when the virtual machine stopped unexpectedly. +- Fix Kubernetes (kubeadm) missing CNI loopback interface name. +- Fixed MCP profile tours getting stuck or rendering tooltips off-screen. +- Fixed a bug where changing the disk image location to a different volume could delete the existing disk image if the operation was interrupted before the copy started. +- Fixed Docker Compose rebuilding locally-built images on every Resource Saver wake. Fixes [docker/desktop-feedback#507](https://github.com/docker/desktop-feedback/issues/507). +- Fixed a regression where Hub image search and tag listing would break if the Docker Hub API response included unexpected or changed fields. +- Fixed an issue where the VM could be unexpectedly shut down when the idle timeout was set to 0. + +#### For Mac + +- Fixed Docker Desktop adding `~/.docker/bin` to the login-shell PATH even when CLI tools were installed to the system path, which could create a `~/.bash_profile` that hid the user's existing shell environment. +- Added `kubectl` shell completions. Fixes [docker/for-mac](https://github.com/docker/for-mac/issues/7205) + +#### For Windows + +- Fixed a bug where switching to Windows containers with the WSL engine still enabled could incorrectly offer to continue without starting the required privileged service. +- Fixed an issue where uninstalling Docker Desktop left a stale `FeaturesRequireReboot=1` registry key, which could cause unexpected reboot prompts on subsequent installs. +- Fixed Docker Desktop staying on "Starting..." indefinitely when WSL could not access the disk image location, and reported the access failure with actionable guidance instead of a generic WSL error. +- Fixed the Windows MSI installer reporting success even when the Docker Desktop service failed to install or start. +- Fixed a spurious failure when running a command right after switching to Windows containers. + +## 4.90.0 + +{{< release-date date="2026-09-07" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.90.0" build_path="/238679/" >}} + +### Updates + +- [Docker Agent v1.128.0](https://github.com/docker/docker-agent/releases/tag/v1.128.0) +- Docker Offload `v0.6.15` +- Docker Desktop CLI v0.4.4 + +### Bug fixes and enhancements + +#### For all platforms + +- Ask Gordon is now accessible as a right-side drawer, keeping users in context while chatting with Gordon alongside any page being viewed. +- A container, image, or volume row with a detected issue now shows an Ask Gordon symbol that starts a diagnosis in one click. +- Fixed a bug where generating a diagnostics bundle could hang until its timeout if a file it collects was on an unresponsive filesystem. +- Fixed an issue where changing the auto-pause timeout while Docker Desktop was already idle would not apply until the original timer expired. +- Fixed a crash in the **Images** view that occurred when many images loaded simultaneously on cold launch or after waking from Resource Saver mode. +- Fixed a Docker Desktop Dashboard crash issue. Fixes [docker/desktop-feedback#611](https://github.com/docker/desktop-feedback/issues/611). +- Added support for starting and stopping a Kubernetes cloud cluster via Docker Offload, with configurable Kubernetes version and node count. +- The Docker Desktop Dashboard now displays the specific reason Docker Engine failed to start, when available. +- Fixed a bug where `renameat2(RENAME_EXCHANGE)` on a shared folder overwrote the target instead of swapping the two files. +- Fixed a bug where `mmap()` of a file on a Synchronized File Share failed with "No such device", breaking git and pnpm. Fixes [docker/desktop-feedback#627](https://github.com/docker/desktop-feedback/issues/627). +- Fixed a bug where repeatedly replacing files on a shared folder leaked VM disk space until Docker Desktop was restarted. Fixes [docker/desktop-feedback#619](https://github.com/docker/desktop-feedback/issues/619). +- Fixed a bug where a bind-mount root intermittently reported ownership as 0:0, causing git to report "detected dubious ownership". Fixes [docker/desktop-feedback#628](https://github.com/docker/desktop-feedback/issues/628). + +#### For Mac + +- Fixed an installer crash that occurred when the user's home folder was on a different disk than `/Applications`. Fresh installs and auto-updates now complete successfully in this configuration. +- Fixed startup failures caused by `VZErrorInvalidVirtualMachineConfiguration` due to stale file locks on `Docker.raw` and APFS disk metadata sync races. + +#### For Windows + +- Fixed a startup hang where Docker Desktop would get stuck on 'Starting' after a WinGet upgrade due to conflicting engine settings in `install-settings.json`. +- The Docker VMM engine option is now always available and no longer flips engines shortly after startup while feature flags load. +- Fixed an issue where the `noWindowsContainers` setting in `install-settings.json` was cleared during a self-update, causing Windows containers to be re-enabled unexpectedly. +- Added a prompt during in-app updates for all-users installations, offering users the option to migrate to a per-user installation that requires no admin privileges for future updates. +- Fixed a bug where Docker Desktop could fail to start after an ungraceful shutdown left behind a stuck socket file. +- Docker Desktop now checks that a Windows host can run Docker VMM before switching to it, and offers to switch back instead of leaving no working engine. +- Fixed Docker VMM telling users to enable the Windows Hypervisor Platform feature when it was already enabled and the real cause was elsewhere. +- Fixed a bug where a failing third-party WSL plugin (for example the Microsoft Defender for Endpoint plug-in for WSL) was reported as a missing Docker Desktop disk instead of naming the plugin that blocked WSL from starting. +- Fixed the MSI installer ignoring `ENGINE=docker-vmm`, which left the Windows Hypervisor Platform feature disabled and the engine unselected. +- Fixed a bug where running the installer with only command-line flags and no `install` verb failed with exit code `4294967291` and no error message. +- Fixed a bug where Docker VMM did not explain how to fix an unavailable Windows Hypervisor Platform. + +### Security + +- Updated the Kind cloud provider image to `v0.7.0`, addressing [CVE-2026-46595](https://github.com/advisories/GHSA-x527-x647-q7gg) and [CVE-2026-39834](https://github.com/advisories/GHSA-rm3j-f69w-wqmq). + +## 4.89.0 + +{{< release-date date="2026-08-31" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.89.0" build_path="/238018/" >}} + +### Updates + +- [Docker Compose v5.5.0](https://github.com/docker/compose/releases/tag/v5.5.0) +- [NVIDIA Container Toolkit v1.20.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.20.0) +- [Docker Agent v1.127.0](https://github.com/docker/docker-agent/releases/tag/v1.127.0) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where background container and image polling was waking the Docker engine unnecessarily when Resource Saver mode was active. +- Fixed slow Zsh startup caused by duplicated Docker CLI completion setup in `.zshrc`. Docker Desktop now keeps a single completion block and removes existing duplicates. Fixes [docker/desktop-feedback#561](https://github.com/docker/desktop-feedback/issues/561). +- Sidebar customization permanently is now available to all users. Right-click the left-hand navigation, select **Customize**, and then select, deselect, or re-order the tabs. +- Fixed the **Disk usage** slider in **Settings** to no longer show duplicate tick marks at small ranges, now displaying values in GiB with one decimal place for ranges up to 8 TiB. +- Fixed excessive update notifications in the notification center so that pop-ups only appear for failures or when user action is required, not during in-progress update steps. +- Fixed a dashboard crash issue. Fixes [docker/desktop-feedback#611](https://github.com/docker/desktop-feedback/issues/611) + +#### For Windows + +- When `CONTAINERD_BUILDX_FOR_WINDOWS` is enabled, Windows Containers now uses `dockerd`'s embedded containerd and in-process BuildKit, replacing the standalone containerd and buildkitd services. +- Fixed a bug where Docker Desktop could fail to start after an ungraceful shutdown left behind a stuck socket file. +- Fixed a bug where Docker VMM did not explain how to fix an unavailable Windows Hypervisor platform. + +## 4.88.1 + +{{< release-date date="2026-08-25" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.88.1" build_path="/237512/" >}} + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where opening the Dashboard would incorrectly redirect unauthenticated users to the sign-in prompt page. + +## 4.88.0 + +{{< release-date date="2026-08-24" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.88.0" build_path="/237115/" >}} + +### Updates + +- [Docker Agent v1.124.0](https://github.com/docker/docker-agent/releases/tag/v1.124.0) +- Docker Offload `v0.6.13` +- [Docker Model Runner v1.2.8](https://github.com/docker/model-cli/releases/tag/v1.2.8) +- [containerd v2.3.3](https://github.com/containerd/containerd/releases/tag/v2.3.3) +- [Runc v1.4.3](https://github.com/opencontainers/runc/releases/tag/v1.4.3) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where Docker Desktop reported `enable fsverity failed: operation not supported` as the crash cause instead of the real underlying error. +- Fixed a bug where changing the hypervisor type in **Settings** had no effect when Docker Desktop was in Resource saver mode. +- Fixed port bindings reported by `docker ps` to accurately reflect active listeners when using 'Localhost by default' or 'Localhost only' settings, and added `[::1]` loopback listener alongside `127.0.0.1`. +- Fixed an HTTP 500 error that could occur during Docker Desktop startup or wake from idle-shutdown when the engine socket existed but was not yet listening. +- Fixed a bug where Docker Desktop would fail to start if `~/.docker/daemon.json` was corrupted with null bytes (typically caused by a crash or power-loss during a settings save). Docker Desktop now automatically recovers to default daemon settings. +- Fixed an issue in the Docker Engine config editor in settings where validation error messages would disappear immediately while typing invalid JSON. +- Fixed a Docker VMM regression that reduced container inbound network throughput to roughly 0.3 GB per second. +- Fixed error messages shown when the Docker Desktop VM exits unexpectedly to include the exit status code and surface the actual root cause of the crash. + +#### For Mac + +- Docker VMM can now use more than 28GiB of host memory. + +#### For Windows + +- Fixed a Windows auto-update failure when a self-updated CLI plugin (e.g `docker scout` or `docker agent`) newer than the bundled version was already present in the user's CLI-plugins folder. +- Fixed an issue on per-user Windows installs where Hyper-V, Windows containers, and related settings are now correctly disabled and grayed out, preventing broken behavior caused by the unavailable priveleged helper service. + +## 4.87.0 + +{{< release-date date="2026-08-17" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.87.0" build_path="/236836/" >}} + +### Updates + +- [Docker Agent v1.122.0](https://github.com/docker/docker-agent/releases/tag/v1.122.0) +- [Docker Buildx v0.36.1](https://github.com/docker/buildx/releases/tag/v0.36.1) +- Docker Offload `v0.6.10` +- [Docker Compose v5.4.0](https://github.com/docker/compose/releases/tag/v5.4.0) +- Linux kernel `v7.0.12` + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed a bug where the in-app update failed with `Source and destination path must have identical roots` when Docker Desktop was installed to a custom directory on another drive. +- Fixed a misleading proxy error that named the destination server instead of the unreachable upstream proxy, and included machine-wide proxy configuration in diagnostics. +- Fixed a bug where updating could keep failing with a `file exists` error after an earlier update had failed. +- Fixed an issue where Gordon would lose access to tools and show misleading sign-in prompts after a failed auto-login at startup, without requiring a restart of Docker Desktop. + +#### For Mac + +- Fixed a false `Docker Desktop encountered an unexpected error` dialog that could appear during VM shutdown on with the `libkrun` engine. +- Fixed a rare crash where the Docker Desktop with the Apple Virtualization Framework VM stopped unexpectedly right after a new connection was opened. + +#### For Windows + +- Fixed WSL error recovery on Windows not displaying specific, actionable error messages for errors like `HCS/0x80070569`, showing the generic fallback instead. +- Fixed an issue on Windows where per-user `.EXE` installs applying an auto-update wrote `install-settings.json` to the system-wide path instead of the correct per-user location. +- Fixed an issue on Windows where diagnostic bundles were missing network connection profile data due to an empty `Get-NetConnectionProfile.json` file. +- Fixed a bug on Windows where Docker Desktop repeatedly asked users to run `wsl --update` when WSL was installed via the Microsoft Store rather than the inbox optional component. +- Fixed an issue where the Resource Saver settings section was incorrectly shown when using Windows containers instead of Linux containers. +- Fixed an issue on Windows where the disk image usage limit was hidden in **Resources** settings when Hyper-V was selected as the hypervisor. +- Fixed an issue on Windows where installer logs from per-user installations were missing from diagnostic bundles. +- Fixed the virtual disk limit not being applied when lowered on Windows with Hyper-V. +- Fixed the disk usage limit slider being hidden and ignored for the Docker VMM backend on Windows, so users can now set and enforce disk size in **Settings** > **Resources** > **Advanced**. +- Fixed a Windows auto-update failure when a self-updated CLI plugin (`docker scout` or `docker agent`) newer than the bundled version was already present in the user's CLI-plugins folder. + +## 4.86.0 + +{{< release-date date="2026-08-10" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.86.0" build_path="/236216/" >}} + +### Updates + +- [Docker Engine v29.7.2](https://docs.docker.com/engine/release-notes/29/#2972) +- [Docker Buildx v0.36.0](https://github.com/docker/buildx/releases/tag/v0.36.0) +- [Docker Scout CLI v1.24.0](https://github.com/docker/scout-cli/releases/tag/v1.24.0) +- [Docker Agent v1.119.0](https://github.com/docker/docker-agent/releases/tag/v1.119.0) + +### Bug fixes and enhancements + +#### For all platforms + +- Docker VMM Beta performance improvements by Docker’s own container-optimized hypervisor. Available for Mac and Windows. +- Gordon now displays specific error messages for tool failures, policy-blocked actions, and loop detection instead of a generic **Agent error**. +- Fixed container stop timeouts and `unless-stopped` restart policies not being honored during engine shutdown. +- Fixed a bug where enabling Docker Offload from the Docker Desktop Dashboard failed when the proxy was configured by the operating system instead of by environment variables. +- Fixed a crash on startup after upgrading, for users whose settings file was written by a very old version. +- Fixed port forwarding for Swarm services that use automatically assigned published ports, including host-mode task ports and repeated ingress port definitions. +- Added a three-mode safety system (Strict, Balanced, Autonomous) to the Gordon AI agent's tool confirmation UI, replacing the previous binary approve/allow-all dialog, with risk-tier labels on confirmation. +- Fixed a flash of incorrect UI content on app launch, such as a brief 'Waiting for the Docker Engine...' screen or unexpected navigation away from gated pages. +- AF_UNIX sockets shared over VirtioFS now work in both directions (host to guest and guest to host). +- Fixed a bug where restarting the VM would steal the window focus. + +#### For Mac + +- Fixed a bug where a Kubernetes (kind) cluster with Enhanced Container Isolation could fail to recover after a Docker Desktop restart. +- Fixed nftables `fib` expressions failing with "Operation not supported" in `inet` tables on Apple Silicon. + +#### For Windows + +- Fixed an issue where the Windows installer reported success when it could not write its settings or enterprise policy files. +- Fixed Model Runner failing to start with `CreateJobObject: Access is denied` when Docker Desktop is launched via a Secondary Logon (run-as-user) session. +- Updated the bundled 7-Zip to 26.02 to avoid antivirus software quarantining it during an upgrade on Windows. + +#### For Linux + +- Fixed Docker Desktop failing to start on Linux arm64 hosts due to incorrect QEMU binary path resolution. + +### Security + +- Addressed CVE-2026-17106, a destination-escape flaw in `docker container cp`. + +## 4.85.0 + +{{< release-date date="2026-08-03" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.85.0" build_path="/235549/" >}} + +### Updates + +- [Docker AI Agent v1.115.0](https://github.com/docker/docker-agent/releases/tag/v1.115.0) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue where native crash reports were uploaded to Bugsnag even when analytics was disabled by the user. +- Fixed an issue where file content previews and diffs were hidden in the Gordon confirmation card when approving write or edit file actions. +- Fixed an issue where an invalid `install-settings.json` caused a ~7-minute startup delay before showing the error dialog. The error now appears immediately. +- Fixed an issue where Gordon's plan mode would silently revert to build mode after the first message, causing subsequent turns to run with full tool access despite plan mode appearing active. +- Fixed an issue where an invalid `config.json` at startup would delay the error dialog by up to 7 minutes instead of appearing within seconds. +- Fixed a Linux VM kernel panic that could hang Docker Desktop when a container's file watcher (inotify/fanotify) observed host-side changes to files on a bind mount. +- Fixed Docker Hardened Images CLI ampersands being encoded when outputting JSON to the console. +- Fixed a bug where extensions-related requests would fail on startup due to the extensions selector incorrectly defaulting to enabled before settings were loaded. +- Fixed an issue where sub-agent message attribution was lost when reloading a historical multi-agent Gordon session, causing sub-agent messages to appear as if produced by the main agent. +- Fixed Gordon's **Clean up Docker** suggestion prompt to propose a cleanup plan and wait for user confirmation before removing any resources, preventing unintended deletions. +- Fixed the Gordon AI plan-mode toggle visibility to accurately reflect backend support, showing only when the connected agent declares plan capability. + +#### For Windows + +- Fixed a bug where per-user uninstalls of Docker Desktop on Windows failed with an unauthorized access error when attempting to revert the hosts file. +- Added per-user install mode as the default for fresh Docker Desktop installations from the Microsoft Store on Windows, removing the need for admin privileges. +- Fixed an issue where Docker Desktop crashed when the `docker-users` group is missing, now showing a recoverable group membership dialog instead. + +#### For Linux + +- Removing files on a host bind mount inside an Enhanced Container Isolation container no longer fails with "Value too large for data type". + +## 4.84.0 + +{{< release-date date="2026-07-27" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.84.0" build_path="/234817/" >}} + + +### Updates + +- [Docker Agent v1.111.0](https://github.com/docker/docker-agent/releases/tag/v1.111.0) +- Kubernetes: + - cri-dockerd v0.4.4 +- [Docker Hardened Images CLI (`dhictl`) v0.0.7](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.7) +- Docker Desktop CLI `v0.4.3` + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed a bug where an invalid `~/.docker/config.json` caused Docker Desktop to hang with high CPU/memory and show no error dialog. Docker Desktop now surfaces an error dialog prompting the user to correct the file. +- Fixed a bug that prevented some Docker Hardened Images customizations from being created. +- Fixed a bug where deleting an unrelated credential ID could accidentally erase Docker Hub OAuth tokens, causing users to be unexpectedly signed out. +- Removed Docker Scout CLI hints that previously appeared after running `docker pull` or `docker buildx build` commands. + +#### For Windows + +- Fixed a bug on Windows where an empty or malformed `install-settings.json` caused Docker Desktop to hang with high CPU/memory usage and no error dialog on startup. +- The MSI installer now detects per-user Docker Desktop installations on the machine and blocks installation with a clear message naming the affected users. Affected users must uninstall their per-user Docker Desktop before the MSI can be installed. +- Fixed a bug where uninstalling Docker Desktop could permanently lock the user out of their own application data directories if the deletion failed mid-way. + +## 4.83.0 + +{{< release-date date="2026-07-20" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.83.0" build_path="/234302/" >}} + +### Updates + +- Docker Desktop CLI `v0.4.2` +- [Docker Model Runner v1.2.6](https://github.com/docker/model-runner/releases/tag/v1.2.6) +- Docker Offload `v0.6.9` +- [Docker Agent v1.103.0](https://github.com/docker/docker-agent/releases/tag/v1.103.0) +- [Docker Compose v5.3.1](https://github.com/docker/compose/releases/tag/v5.3.1) +- Docker Desktop Build `v0.36.0` +- [Docker Engine v29.6.2](https://docs.docker.com/engine/release-notes/29/#2962) + +### Bug fixes and enhancements + +#### For all platforms + +- Added support for migrating a per-machine Docker Desktop installation to a per-user installation in-place via `install --user` on Windows, preserving user data without requiring a manual uninstall. +- Fixed `kubectl exec` and `kubectl attach` functionality for v1.36. +- Fixed Docker Engine startup failures being reported as a generic `io: read/write on closed pipe` error instead of the underlying cause. +- Fixed the **Images** view showing **0 Bytes** reclaimable size for a while when many images are present. +- Fixed the volumes list not correctly sorting by size. +- Fixed an issue where a GPU process crash prevented the Docker Desktop Dashboard from loading by automatically disabling hardware acceleration and restarting the app. +- Fixed an issue where `docker ai` sessions launched directly from a terminal were killed when Docker Desktop was restarted. +- Fixed an issue where a malformed `daemon.json` would be silently overwritten with defaults on startup, causing users to lose their custom daemon configuration. +- Added a **Custom rules** tab to Gordon's permissions dialog. Users can now add allow/deny rules for specific commands or MCP tools. +- Added pulsing discovery badges to Gordon's **Plan mode** button, model selector, and **Feedback/Issues** button to help users find new features. + +#### For Mac + +- Fixed an issue where a stale `com.docker.virtualization` process could prevent Docker Desktop from starting a new VM with a `VZErrorInvalidVirtualMachineConfiguration` error. + +#### For Windows + +- Fixed an issue where a failed delta update would leave users stranded on an old version by automatically falling back to the full installer. +- Fixed the Windows MSI installer reporting success when the component installation step actually failed. +- Fixed an issue where the Windows installer wizard froze while enabling Windows features via DISM during Docker Desktop installation. +- Fixed a UI thread deadlock in the Windows installer that caused a blank or hung window when prerequisite services were registered but not running during admin installs. +- Fixed the Windows installer silently reporting success when it could not install the Docker CLI plugins. +- Fixed the Windows installer deleting a previously installed CLI plugin when re-linking it failed. +- Fixed a bug where registry policy download failures were silently ignored, so users now see proper error reporting when the admin helper exits with a non-zero code. +- Changed the Windows installer to select a per-user installation by default. +- Fixed a WSL integration issue on WSL 2.6.x and later where Docker Desktop failed to work in user distros due to a 0-byte proxy binary, causing **Permission denied** or **Exec format error**. +- Fixed the Docker CLI in integrated WSL distributions breaking after Resource Saver stopped the VM. The VM now stays running while a WSL integration is active and wakes when one is enabled. Fixes [docker/desktop-feedback#522](https://github.com/docker/desktop-feedback/issues/522). + +## 4.82.0 + +{{< release-date date="2026-07-13" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.82.0" build_path="/233772/" >}} + +### Updates + +- [Docker Compose v5.3.0](https://github.com/docker/compose/releases/tag/v5.3.0) +- [Docker Agent v1.98.0](https://github.com/docker/docker-agent/releases/tag/v1.98.0) +- [Docker Scout CLI v1.23.1](https://github.com/docker/scout-cli/releases/tag/v1.23.1) + +### Bug fixes and enhancements + +#### For all platforms + +- Added thumbs up and thumbs down feedback buttons to Gordon responses. Users can rate replies or report issues directly from the chat. +- Fixed a bug where containers created by Docker Desktop had their stop timeout set to 1 second instead of the Docker Engine default, causing `docker stop` to terminate processes too quickly. +- Fixed reset to factory defaults not clearing MCP Toolkit profiles, catalogs, and authorizations. +- Fixed an issue where selected thumbs up/down feedback buttons in Gordon were visually indistinguishable after selecting. +- Fixed reset to factory defaults not clearing downloaded LLM models. +- Fixed a bug where the Gordon chat area would go blank when the agent requested free-text input via elicitation. +- Fixed a delay in the Kubernetes screen where the progress UI did not appear immediately after confirming cluster creation or deletion. +- Fixed a bug where a Kubernetes kind cluster failed to start with a **Failed to get API server port** error after a Docker Desktop restart. +- With `docker pass`, the `ls` command now behaves consistently across all platforms. +- Fixed an issue where users signed out due to sign-in enforcement policies were shown a generic sign-in prompt instead of a clear explanation of why they were signed out. + +#### For Mac + +- Fixed an issue where Docker Desktop child processes could linger after an unexpected backend exit. +- Fixed an issue where Docker Desktop failed to start for users with long home directory paths that caused Unix socket paths to exceed OS length limits. +- Fixed an issue where vsock listener failures showed a cryptic crash instead of a clear, actionable recovery dialog. + +#### For Windows + +- Fixed an issue where `.log` files were missing from diagnostic bundles, ensuring the Docker Desktop service log is now included. +- Lowered the priority of Docker Desktop's background processes and enabled Windows Efficiency Mode while idle to reduce power and CPU usage. +- Fixed factory reset leaving containers and images behind on Hyper-V when Docker Desktop is run by a user other than the one that installed it. +- Fixed a multi-minute hang during WSL engine startup when the wsl-bootstrap process fails unexpectedly, surfacing the error promptly instead. +- Fixed an issue where auto-updates could leave Docker Desktop stuck in a 'connecting' state due to a successful installation being incorrectly rolled back. +- Fixed an issue where vsock listener failures on Windows Hyper-V showed a cryptic crash instead of a clear, actionable recovery dialog. +- Fixed a race condition where connecting to `com.docker.service` immediately after startup could result in a **File not found** error. +- Fixed an issue where a graphical installer window would flash during background auto-updates. Updates now run silently. +- Improved security by verifying the Authenticode signature of the downloaded installer before executing it during updates. +- Fixed an issue where missing or disabled Windows feature descriptions were not shown in diagnostic output. +- Improved the installer progress screen with a single continuous progress bar that smoothly advances from 0% to 100% throughout the entire installation. +- Fixed an issue where `~` in bind mount paths was not correctly resolved to the home directory when the `HOME` environment variable was not set. + +#### For Linux + +- Fixed an issue where Docker Desktop failed to start for users with long home directory paths that caused Unix socket paths to exceed OS length limits. + +## 4.81.0 + +{{< release-date date="2026-07-06" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.81.0" build_path="/232925/" >}} + +### Updates + +- [Docker Model Runner v1.2.5](https://github.com/docker/model-runner/releases/tag/v1.2.5) +- [Docker Agent v1.88.1](https://github.com/docker/docker-agent/releases/tag/v1.88.1) +- Docker Offload `v0.6.7` +- [Docker Compose v5.2.0](https://github.com/docker/compose/releases/tag/v5.2.0) +- [Docker Scout CLI v1.22.0](https://github.com/docker/scout-cli/releases/tag/v1.22.0) +- [DHI CLI (`dhictl`) v0.0.5](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.5) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an error that caused volumes, images, and containers to fail to load in the Docker Desktop Dashboard. +- Removed the deprecated `cagent` binary from Docker Desktop; use `docker agent` instead. +- Kubernetes kind cluster now works with Registry Access Management. +- Fixed a bug where the sign-in/update prompt was not shown when upgrading between versions that cross a version digit boundary (e.g., 4.9.x to 4.10.x). +- Fixed an issue in Ask Gordon where the tool call permission dialog blocked the chat view, replacing it with an inline approval card so users can read Gordon's full message before approving or rejecting. +- Fixed a rare case where Docker Desktop could shut down if the build service crashed, for example during a factory reset. +- Fixed an issue where containers ignored user-configured stop timeouts during normal operation due to a proxy-level override forcing a 1-second timeout on all containers. + +#### For Mac + +- Fixed Docker Desktop failing to start when the user's environment contained very long environment variables. +- Fixed a Docker Offload crash on Intel machines due to `SG_READ_ONLY` not being set in the `__DATA_CONST` segment, causing the system linker to fail to load the executable. Fixes [docker/desktop-feedback#471](https://github.com/docker/desktop-feedback/issues/471). + +#### For Windows + +- Fixed an issue on Windows where stopping Docker Desktop would immediately force off the Hyper-V VM without waiting for a graceful guest shutdown, reducing the risk of data corruption. +- Fixed a bug on Windows where `dockerd` failed to connect through the local HTTPS proxy due to a TLS handshake error caused by an incorrect proxy URL scheme. +- Fixed a Windows update that reverted and showed a **Mismatch patch version** error when it ran again after the target version was already installed. +- Fixed Resource Saver not stopping the Docker engine when running on WSL. +- Fixed a regression where Docker Desktop failed to start on WSL2 kernels that could not attach the Synchronized File Shares eBPF probes, such as Windows on Arm. Fixes [docker/desktop-feedback#470](https://github.com/docker/desktop-feedback/issues/470). + +#### For Linux + +- Fixed a bug where Docker Desktop would fail to start after a reset. + +## 4.80.0 + +{{< release-date date="2026-06-29" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.80.0" build_path="/232116/" >}} + +### Updates + +- Docker Offload `v0.6.6` +- [Docker Buildx v0.35.0](https://github.com/docker/buildx/releases/tag/v0.35.0) +- [Docker Model Runner v1.2.4](https://github.com/docker/model-runner/releases/tag/v1.2.4) +- [containerd v2.2.5](https://github.com/containerd/containerd/releases/tag/v2.2.5) +- [Docker Engine v29.6.1](https://docs.docker.com/engine/release-notes/29/#2961) +- [Runc v1.3.6](https://github.com/opencontainers/runc/releases/tag/v1.3.6) +- Kubernetes v1.36.1 + - CNI plugins v1.9.1 + - cri-tools v1.35.0 + - cri-dockerd v0.3.25 +- Updated Kubernetes images: + - Kubeadm: + - `docker/desktop-storage-provisioner:v4.0` + - `docker/desktop-vpnkit-controller:v4.0` + - `docker/desktop-kubernetes-etcd:3.6.8-0` + - `docker/desktop-kubernetes-coredns:v1.14.2` + - `docker/desktop-kubernetes-pause:3.10.2` + - `docker/desktop-kubernetes-apiserver:v1.36.1` + - `docker/desktop-kubernetes-controller-manager:v1.36.1` + - `docker/desktop-kubernetes-scheduler:v1.36.1` + - `docker/desktop-kubernetes-proxy:v1.36.1` + - Kind: + - `docker/desktop-containerd-registry-mirror:v0.0.4` + - `docker/desktop-cloud-provider-kind:v0.6.0` + - `envoyproxy/envoy:v1.36.7` + +### Bug fixes and enhancements + +#### For all platforms + +- The experimental `docker sandbox` plugin has been removed. Migrate to [`docker sbx`](/manuals/ai/sandboxes/_index.md). +- Fixed an issue where running out of disk space showed a generic error dialog instead of a clear **Disk full** message prompting users to free up space and restart. +- Fixed an issue where using `docker -c desktop-linux` while a cloud context was active would silently route commands to the cloud engine instead of the local desktop Linux engine. +- Fixed a bug where the backend would incorrectly report a stopped VM as running after an idle shutdown, especially when Enhanced Container Isolation was enabled. +- Fixed an OS update notification timing issue where users with auto-download enabled were notified when an update was available rather than when it was ready to install. + +#### For Mac + +- Removed the legacy osxfs file sharing. Users still on osxfs are migrated to VirtioFS. +- Increased VirtioFS filesharing performance by not persisting (fake) file ownership changes on the host. Calls to `chown` will succeed, but `stat` will not be affected. + +#### For Windows + +- Fixed an issue where the Windows installer failed when the destination directory contained leftover files from a previous interrupted installation. +- Fixed an issue on Windows where upgrading Docker Desktop would unnecessarily shut down and unregister unrelated WSL distros via `wsl --shutdown`. +- Fixed spurious Hyper-V job failures on Windows where operations briefly transitioning through suspended or shutting down states were incorrectly reported as failed. +- Fixed an issue where the WSL engine failed to start with a **Permission denied** error on machines where the cross-distro WSL mount was configured as `noexec`. +- Fixed an issue on Windows where end users could override the `NO_PROXY` exclusion list even when an admin had locked the proxy configuration. +- Fixed an issue on Windows where Docker Desktop would silently disappear on startup failure. An error dialog is now displayed instead. +- Fixed an issue on Windows where Docker Desktop showed a generic engine-start failure instead of routing to the WSL update recovery when an older wsl.exe did not support the --version flag. + +## 4.79.0 + +{{< release-date date="2026-06-22" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.79.0" build_path="/230596/" >}} + +### Updates + +- [Docker Agent v1.79.0](https://github.com/docker/docker-agent/releases/tag/v1.79.0) +- `docker pass` v0.1.5 +- Docker Desktop CLI v0.4.1 +- Docker Offload v0.6.4 + +### Bug fixes and enhancements + +#### For all platforms + +- Gordon improvements: + - Added context-aware suggested questions to the Ask Gordon menu in the **Containers**, **Images**, **Volumes**, and **Builds** tabs, surfacing relevant diagnostics first when items are in a problematic state. + - Added a **Give feedback** link to Gordon so you can report issues with a redacted conversation preview or share product feedback. + - Fixed a React warning in Gordon's sidebar search input that appeared on the first keystroke when typing a search query. +- Fixed an issue where the Docker Engine settings editor displayed minified JSON instead of formatted JSON when first opened. +- Fixed spurious 500 errors for Docker API calls made right after the VM woke from idle shutdown. +- Fixed spurious 'Integrity issue detected' notifications caused by leftover symlinks from previously bundled binaries. +- Fixed a broken documentation link in the error screen shown when the current user is not a member of the `docker-users` group. +- Fixed a breaking change to the `/app/settings/grouped` API that caused integrations such as NVIDIA to stop working correctly. +- Fixed high CPU usage (~30%) on macOS Retina displays caused by SVG animations in the Gordon landing page. +- Fixed an issue where OAuth network errors caused Docker Desktop to incorrectly show users as signed out. +- Fixed an issue where signing in via OAuth would not display the user's username and email in the UI after login. +- QEMU has been updated to v10.2.3 +- **Logs** view improvements + - Added copy buttons. Copy all visible filtered logs at once or copy individual log entries on hover, respecting the current timestamp visibility setting. + - Improved the toolbar with a reorganized layout, saved filter presets that now capture container selection and build log visibility, and the ability to persist container filter state. + - Added the ability to clear logs. + - Combined **copy** and **expand**/**collapse** buttons into a single pinned column that stays visible during horizontal scrolling, and fixed **copy** accidentally toggling the row detail pan. +- Fixed Registry Access Management policy downloads to avoid `permission denied` errors by fetching and caching policies in the user's own directory with tampering detection. + +#### For Windows + +- Fixed a bug where Docker Desktop on WSL failed to start with an 'is already mounted' error after a force-killed bootstrap left stale rootfs mounts behind. +- Fixed an issue on Windows where clicking "Quit Docker Desktop" had no effect when the backend had crashed or been killed. +- Fixed an issue on Windows where Docker Desktop processes could linger as orphans after an unexpected exit or crash. +- Fixed getting stuck on "Starting the Docker Engine…" after an in-place upgrade on Windows when the WSL virtual machine had not been shut down. +- Fixed the tray icon on Windows not matching the system taskbar theme, so the correct light or dark icon is now displayed. +- Fixed a silent failure on Windows where backend startup errors were only written to a log file. Users now see a visible error dialog box when Docker Desktop fails to start. + +## 4.78.0 + +{{< release-date date="2026-06-15" >}} + +{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.78.0" build_path="/229452/" >}} + +### Updates + +- [Docker Agent v1.73.0](https://github.com/docker/docker-agent/releases/tag/v1.73.0) +- `docker pass` v0.1.4 +- [Credential helpers v0.9.8](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.8) + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an out-of-memory crash that would cause Docker Desktop to become unresponsive or crash while streaming logs in the Docker Desktop Dashboard. +- Improved update reliability by retrying stalled and transient download failures and resuming from the partially downloaded file. +- Added live streaming output to Gordon tool calls so long-running commands like `docker compose up` display STDOUT/STDERR in real time instead of waiting until completion. +- Added color-coded labels to the **Logs** view so each container and build source is visually distinguished by a unique color in both the log grid and the container-filter dropdown. +- Improved the error message when the Docker Desktop VM fails to start. It now shows the underlying `VirtualizationFramework` / `libkrun` reason instead of the generic **Use of closed network connection**. +- Fixed a bug where Docker CLI error messages were shown as raw JSON instead of human-readable text while Docker Desktop was in Resource Saver mode. +- Fixed a crash that occurred in the **Logs** view when deselecting a container filter. +- Fixed an issue where the support page was replaced by the no-virtualization override screen when accessed from the troubleshooting popover. +- Fixed an issue where Docker Desktop failed to start on bare metal EC2 instances (e.g. `g4dn.metal`) with a **Nested virtualization not supported** error. +- Increased the retry delay to accommodate transient rename failures caused by antivirus software holding file locks. +- Gordon now shows clear network error messages with guidance to check VPN, proxy, or firewall settings when outbound HTTPS to Docker's services is blocked, instead of a generic agent error. +- Fixed the Gordon AI model picker incorrectly showing an internal model identifier instead of **Default** for sessions with no explicit model selection. + +#### For Windows + +- Fixed Docker Desktop getting stuck on **Starting the Docker Engine…** after an in-place upgrade. +- Fixed a bug where Docker Desktop was not restarted after a failed update was reverted to the previous version. +- Fixed delta updates failing to prepare. +- Fixed an issue on Hyper-V where Docker commands (e.g. `docker login`) would fail on the first attempt after the engine had been idle-shut-down or paused. +- Fixed an issue on Windows where Docker Desktop showed a generic engine-start failure instead of a clear, actionable error message when WSL is not installed. + ## 4.77.0 {{< release-date date="2026-06-08" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.77.0" build_path="/228796/" >}} - ### New - You can now export log data from the **Logs** view. @@ -49,6 +1028,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo #### For all platforms +- Increased the retry delay to accommodate transient rename failures caused by antivirus software holding file locks. - Marketplace extensions are now installed and updated by pinned manifest digest, instead of by tag, protecting against tag mutation after publication. - Added Buildx version information to the About window. - Added a case-sensitivity toggle to the **Logs** search bar which lets you switch between case-insensitive (default) and case-sensitive log filtering. @@ -70,8 +1050,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-06-01" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.76.0" build_path="/228118/" >}} - ### New - Docker Model Runner now supports registry mirrors. @@ -125,8 +1103,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-05-26" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.75.0" build_path="/227598/" >}} - ### Updates - Docker Offload v0.5.92 @@ -157,8 +1133,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-05-19" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.74.0" build_path="/227015/" >}} - ### New - [Gordon](/ai/gordon) is now generally available. New usage plans are also available. Paid Gordon plans unlock higher usage limits. @@ -192,8 +1166,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-05-13" >}} -{{< desktop-install-v2 win=true version="4.73.1" build_path="/226574/" >}} - ### Bug fixes and enhancements #### For Windows @@ -204,8 +1176,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-05-11" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.73.0" build_path="/226246/" >}} - ### Updates - [Docker Engine v29.4.3](https://docs.docker.com/engine/release-notes/29/#2943) @@ -230,8 +1200,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-05-06" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.72.0" build_path="/225998/" >}} - ### New - The **Logs** view is now generally available. @@ -274,8 +1242,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-04-27" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.71.0" build_path="/225177/" >}} - > [!IMPORTANT] > > Support for RHEL 8 has ended. Installing Docker Desktop will require RHEL 9 or RHEL 10 in the next release. @@ -317,8 +1283,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-04-20" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.70.0" build_path="/224270/" >}} - ### New - Added a CLI hint that surfaces the **Logs** view when running `logs`, `compose logs`, `compose attach`, or `compose up` commands, giving you quick access to logs across all running containers. Available with the **Logs** (Beta) feature enabled. @@ -356,8 +1320,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-04-13" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.69.0" build_path="/224084/" >}} - ### Updates - [Docker Agent v1.42.0](https://github.com/docker/docker-agent/releases/tag/v1.42.0) @@ -393,8 +1355,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-04-07" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.68.0" build_path="/223695/" >}} - ### New - Gordon now has persistent local memory, allowing it to remember your preferences and context across sessions. @@ -442,8 +1402,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-30" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.67.0" build_path="/222858/" >}} - ### New - Docker MCP Toolkit now has MCP profile template cards and an onboarding tour accessible via the **Profiles** tab. @@ -486,8 +1444,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-26" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.66.1" build_path="/222799/" >}} - ### Updates - [Docker Engine v29.3.1](/manuals/engine/release-notes/29.md#2931) @@ -496,8 +1452,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-23" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.66.0" build_path="/222299/" >}} - ### Updates - [Docker Engine v29.3.0](https://docs.docker.com/engine/release-notes/29/#2930) @@ -523,8 +1477,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-16" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.65.0" build_path="/221669/" >}} - ### New - Added a new **Logs** view where you can explore logs from all sources in one unified view. (Beta) @@ -557,8 +1509,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-11" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.64.0" build_path="/221278/" >}} - ### Updates - [Docker Compose v5.1.0](https://github.com/docker/compose/releases/tag/v5.1.0) @@ -592,8 +1542,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-03-02" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.63.0" build_path="/220185/" >}} - ### New - Added SLSA v1 provenance support in the **Builds** view. @@ -624,11 +1572,9 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-02-23" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.62.0" build_path="/219486/" >}} - ### New -- With Docker MCP Toolkit, you can now use [profiles](/manuals/ai/mcp-catalog-and-toolkit/profiles.md) to organize your MCP servers into named collections. You can also create custom catalogs — curated collections of servers for your team or organization. +- With Docker MCP Toolkit, you can now use [profiles](/manuals/desktop/features/mcp-catalog-and-toolkit/profiles.md) to organize your MCP servers into named collections. You can also create custom catalogs — curated collections of servers for your team or organization. ### Updates @@ -661,8 +1607,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-02-18" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.61.0" build_path="/219004/" >}} - ### New - You can now customize the left-hand navigation to show only the tabs that matter to you, and hide the ones that don’t. @@ -706,8 +1650,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-02-09" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.60.0" build_path="/218231/" >}} - ### New - Added a new `docker desktop diagnose` command to gather diagnostics. @@ -733,8 +1675,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-02-03" >}} -{{< desktop-install-v2 mac=true version="4.59.1" build_path="/217750/" >}} - ### Bug fixes and enhancements #### For Mac @@ -745,8 +1685,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-02-02" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.59.0" build_path="/217644/" >}} - ### Updates - Linux kernel `v6.12.67` @@ -790,8 +1728,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-01-26" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.58.0" build_path="/216728/" >}} - ### New - A new version of [Docker Sandboxes](/manuals/ai/sandboxes/_index.md) is now available on Docker Desktop. It provides a secure, isolated, microVM-based environment for running coding agents. @@ -838,8 +1774,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-01-19" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.57.0" build_path="/215387/" >}} - ### Security - Fixed [CVE-2025-14740](https://www.cve.org/cverecord?id=CVE-2025-14740) where the Docker Desktop for Windows installer contained multiple incorrect permission assignment vulnerabilities in the handling of the `C:\ProgramData\DockerDesktop` directory. @@ -863,8 +1797,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2026-01-12" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.56.0" build_path="/214940/" >}} - ### New - Docker Desktop now includes Docker Compose v5 which introduces a new official Go SDK. This SDK provides a comprehensive API that lets you integrate Compose functionality directly into your applications, allowing you to load, validate, and manage multi-container environments without relying on the Compose CLI. For more information, see the [Compose SDK docs](/manuals/compose/compose-sdk.md). @@ -900,8 +1832,6 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo {{< release-date date="2025-12-16" >}} -{{< desktop-install-v2 all=true win_arm_release="Early Access" version="4.55.0" build_path="/213807/" >}} - ### Updates - [Docker Engine v29.1.3](https://docs.docker.com/engine/release-notes/29/#2913) @@ -957,7 +1887,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo ### Security -- Added security patches to address CVEs [2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2), [2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm), and [2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r) when using [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation). +- Added security patches to address CVEs [2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2), [2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm), and [2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r) when using [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md). ## 4.52.0 @@ -1017,7 +1947,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo ### New -- [Dynamic MCP](/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md)(Experimental) is now available in Docker Desktop . +- [Dynamic MCP](/manuals/desktop/features/mcp-catalog-and-toolkit/dynamic-mcp.md)(Experimental) is now available in Docker Desktop . - Introduced a new Welcome Survey to improve onboarding. New users can now provide information to help tailor their Docker Desktop experience. ### Upgrades @@ -1083,7 +2013,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo ### New - You can now specify PAC files and Embedded PAC scripts with installer flags for [macOS](/manuals/desktop/setup/install/mac-install.md#proxy-configuration) and [Windows](/manuals/desktop/setup/install/windows-install.md#proxy-configuration). -- Administrators can set proxy settings via [macOS configuration profiles](/manuals/enterprise/security/enforce-sign-in/methods.md#macos-configuration-profiles-method-recommended). +- Administrators can set proxy settings via [macOS configuration profiles](/manuals/desktop/enterprise/enforce-sign-in/methods.md#macos-configuration-profiles-method-recommended). ### Upgrades @@ -1115,7 +2045,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo ### Security -- Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where the Enhanced Container Isolation [Docker Socket command restrictions](../enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#command-restrictions) feature was not working properly in Docker Desktop 4.46.0 only (the configuration for it was being ignored). +- Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where the Enhanced Container Isolation [Docker Socket command restrictions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#command-restrictions) feature was not working properly in Docker Desktop 4.46.0 only (the configuration for it was being ignored). ### New @@ -1160,7 +2090,7 @@ For more frequently asked questions, see the [FAQs](/manuals/desktop/troubleshoo ### New - Added a new Learning center walkthrough for Docker MCP Toolkit and other onboarding improvements. -- Administrators can now control [PAC configurations with Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#proxy-settings). +- Administrators can now control [PAC configurations with Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#proxy-settings). - The update experience has been redesigned to make it easier to understand and manage updates for Docker Desktop and its components. ### Upgrades @@ -1296,9 +2226,9 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Fixed an issue pulling images with zstd differential layers when the containerd image store is enabled. - Fixed a bug causing containers launching with the `--restart` flag to not restart properly when using Enhanced Container Isolation. -- Improved interaction between [Kubernetes custom registry images](/manuals/desktop/use-desktop/kubernetes.md#configuring-a-custom-image-registry-for-kubernetes-control-plane-images) and Enhanced Container Isolation (ECI), so the [ECI Docker Socket image list](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md) no longer needs to be manually updated when using a custom registry for Kubernetes control plane images. +- Improved interaction between [Kubernetes custom registry images](/manuals/desktop/use-desktop/kubernetes.md#configuring-a-custom-image-registry-for-kubernetes-control-plane-images) and Enhanced Container Isolation (ECI), so the [ECI Docker Socket image list](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md) no longer needs to be manually updated when using a custom registry for Kubernetes control plane images. - Fixed a bug where a Docker Desktop Kubernetes cluster in kind mode fails to start after restarting Docker Desktop if the user is required to be signed in but is currently signed out. -- Fixed a bug that prevented the mounting of MCP secrets into containers when [Enhanced Container Isolation](/enterprise/security/hardened-desktop/enhanced-container-isolation/) is enabled. +- Fixed a bug that prevented the mounting of MCP secrets into containers when [Enhanced Container Isolation](/desktop/enterprise/hardened-desktop/enhanced-container-isolation/) is enabled. - Fixed a bug preventing the use of `--publish-all` when `--publish` was already specified. - Fixed a bug causing the **Images** view to scroll infinitely. Fixes [docker/for-mac#7725](https://github.com/docker/for-mac/issues/7725). - Fixed a bug which caused the **Volumes** tab to be blank while in Resource Saver mode. @@ -1462,7 +2392,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Improved the sign-in enforcement message when more than 10 organizations are enforced. - Changed the way ports are mapped by Docker Desktop to fully support IPv6 ports. - Fixed a bug in the Dashboard container logs screen causing the scrollbar to disappear as the mouse approaches. -- [Enforced sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) fixed for Teams subscription users. +- [Enforced sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) fixed for Teams subscription users. - `llama.cpp` server now supports streaming and tool calling in Model Runner. - Sign-in Enforcement capability is now available to all subscriptions. @@ -1529,7 +2459,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Docker Model Runner is now available on x86 Windows machines with NVIDIA GPUs. - You can now [push models](/manuals/ai/model-runner.md#push-a-model-to-docker-hub) to Docker Hub with Docker Model Runner. - Added support for Docker Model Runner's model management and chat interface in Docker Desktop for Mac and Windows (on hardware supporting Docker Model Runner). Users can now view, interact with, and manage local AI models through a new dedicated interface. -- [Docker Compose](/manuals/ai/compose/models-and-compose.md) and Testcontainers [Java](https://java.testcontainers.org/modules/docker_model_runner/) and [Go](https://golang.testcontainers.org/modules/dockermodelrunner/) now support Docker Model Runner. +- [Docker Compose](/manuals/compose/how-tos/models-and-compose.md) and Testcontainers [Java](https://java.testcontainers.org/modules/docker_model_runner/) and [Go](https://golang.testcontainers.org/modules/dockermodelrunner/) now support Docker Model Runner. - Introducing Docker Desktop in the [Microsoft App Store](https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB&gl=GB). ### Upgrades @@ -1557,7 +2487,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Improved error messages when downloading Registry Access Management configuration. - If Docker can't bind an ICMPv4 socket, it now logs an error and continues rather than quits. - Enabled the memory protection keys mechanism in the Docker Desktop Linux VM, allowing containers like Oracle database images to run correctly. -- Fixed a problem with containers accessing `/proc/sys/kernel/shm*` sysctls when [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) is enabled on Mac, Windows Hyper-V, or Linux. +- Fixed a problem with containers accessing `/proc/sys/kernel/shm*` sysctls when [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) is enabled on Mac, Windows Hyper-V, or Linux. - Added kernel module `nft_fib_inet`, required for running firewalld in a Linux container. - MacOS QEMU Virtualization option is being deprecated on July 14, 2025. @@ -1714,7 +2644,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 #### For all platforms - Fixed a bug where access tokens generated by the `docker login` web flow could not be refreshed by Docker Desktop. -- Fixed a bug where container creation via the Docker API using `curl` failed when [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) was enabled. +- Fixed a bug where container creation via the Docker API using `curl` failed when [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) was enabled. - Fixed a bug where the RAM policy was not refreshed after the refresh period had elapsed. - Fixed a bug in Enhanced Container Isolation when mounting the Docker socket into a container, and then creating Docker containers with bind-mounts from within that container. - Fixed an issue that caused a discrepancy between the GUI and the CLI, the former forcing the `0.0.0.0` HostIP in port-mappings. This caused default binding IPs configured through Engine's `ip` flag, or through the bridge option `com.docker.network.bridge.host_binding_ipv4`, to not be used. @@ -1773,7 +2703,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 #### For all platforms - Fixed an issue that caused the AI Catalog in Docker Hub to be unavailable in Docker Desktop. -- Fixed an issue that caused Docker Desktop to panic with `index out of range [0] with length 0` when using [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md). +- Fixed an issue that caused Docker Desktop to panic with `index out of range [0] with length 0` when using [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md). ### Known issues @@ -1863,13 +2793,13 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Existing Docker Desktop installations using the WSL2 engine on Windows are now automatically migrated to a unified single-distribution architecture for enhanced consistency and performance. - Administrators can now: - - Enforce sign-in with macOS [configuration profiles](/manuals/enterprise/security/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) (Early Access). + - Enforce sign-in with macOS [configuration profiles](/manuals/desktop/enterprise/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) (Early Access). - Enforce sign-in for more than one organization at a time (Early Access). - - Deploy Docker Desktop for Mac in bulk with the [PKG installer](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) (Early Access). + - Deploy Docker Desktop for Mac in bulk with the [PKG installer](/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md) (Early Access). - Use Desktop Settings Management to manage and enforce defaults via admin.docker.com (Early Access). - Enhance Container Isolation (ECI) has been improved to: - - Allow admins to [turn off Docker socket mount restrictions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#allowing-all-containers-to-mount-the-docker-socket). - - Support wildcard tags when using the [`allowedDerivedImages` setting](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images). + - Allow admins to [turn off Docker socket mount restrictions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#allowing-all-containers-to-mount-the-docker-socket). + - Support wildcard tags when using the [`allowedDerivedImages` setting](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images). ### Upgrades @@ -1973,7 +2903,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Fixed a bug where the **Push to Docker Hub** action in the **Images** view would result in an `invalid tag format` error. Fixes [docker/for-win#14258](https://github.com/docker/for-win/issues/14258). - Fixed an issue where Docker Desktop startup failed when ICMPv6 setup was not successful. - Added drivers that allow USB/IP to work. -- Fixed a bug in Enhanced Container Isolation (ECI) [Docker socket mount permissions for derived images](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md) where it was incorrectly denying Docker socket mounts for some images when Docker Desktop uses the containerd image store. +- Fixed a bug in Enhanced Container Isolation (ECI) [Docker socket mount permissions for derived images](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md) where it was incorrectly denying Docker socket mounts for some images when Docker Desktop uses the containerd image store. - Enable `NFT_NUMGEN`, `NFT_FIB_IPV4` and `NFT_FIB_IPV6` kernel modules. - Build UI: - Highlight build check warnings in the **Completed builds** list. @@ -1981,7 +2911,7 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - Image tags added to **Build results** section under the **Info** tab. - Improved efficiency of host-side disk utilization for fresh installations on Mac and Linux. - Fixed a bug that prevented the Sign in enforcement popup to be triggered when token expires. -- Fixed a bug where containers would not be displayed in the GUI immediately after signing in when using [enforced sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). +- Fixed a bug where containers would not be displayed in the GUI immediately after signing in when using [enforced sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). - `settings.json` has been renamed to `settings-store.json` - The host networking feature no longer requires users to be signed-in in order to use it. @@ -2082,8 +3012,8 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 - [Host networking](/manuals/engine/network/drivers/host.md#docker-desktop) support on Docker Desktop is now generally available. - If you authenticate via the CLI, you can now authenticate through a browser-based flow, removing the need for manual PAT generation. - Windows now supports automatic reclamation of disk space in Docker Desktop for WSL2 installations [using a managed virtual hard disk](/manuals/desktop/features/wsl/best-practices.md). -- Deploying Docker Desktop via the [MSI installer](/manuals/enterprise/enterprise-deployment/msi-install-and-configure.md) is now generally available. -- Two new methods to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) (windows registry key and `.plist` file) are now generally available. +- Deploying Docker Desktop via the [MSI installer](/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md) is now generally available. +- Two new methods to [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) (windows registry key and `.plist` file) are now generally available. - Fresh installations of Docker Desktop now use the containerd image store by default. - [Compose Bridge](/manuals/compose/bridge/_index.md) (Experimental) is now available from the Compose file viewer. Easily convert and deploy your Compose project to a Kubernetes cluster. @@ -2130,8 +3060,8 @@ We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266 > [!NOTE] > Using `docker login` with an address that includes URL path segments is not a documented use case and is considered unsupported. The recommended usage is to specify only a registry hostname, and optionally a port, as the address for `docker login`. - When running `docker compose up` and Docker Desktop is in the Resource Saver mode, the command is unresponsive. As a workaround, manually exit the Resource Saving mode and Docker Compose becomes responsive again. -- When [Enhanced Container Isolation (ECI)](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) is enabled, Docker Desktop may not enter Resource Saver mode. This will be fixed in a future Docker Desktop release. -- The new [ECI Docker socket mount permissions for derived images](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images) feature does not yet work when Docker Desktop is configured with the **Use containerd for pulling and storing images**. This will be fixed in the next Docker Desktop release. +- When [Enhanced Container Isolation (ECI)](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) is enabled, Docker Desktop may not enter Resource Saver mode. This will be fixed in a future Docker Desktop release. +- The new [ECI Docker socket mount permissions for derived images](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images) feature does not yet work when Docker Desktop is configured with the **Use containerd for pulling and storing images**. This will be fixed in the next Docker Desktop release. ## 4.33.2 @@ -2277,7 +3207,7 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL - Improved instructions for `watch` in the Compose File Viewer - Added support for Golang projects that don't have dependencies in Docker Init. Addresses [docker/roadmap#611](https://github.com/docker/roadmap/issues/611) -- [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) now lets admins set the default value to `ProxyEnableKerberosNTLM`. +- [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) now lets admins set the default value to `ProxyEnableKerberosNTLM`. - Removed a temporary compatibility fix for older versions of Visual Studio Code. - Builds view: - Changed icon for imported build record to a "files" icon. @@ -2332,7 +3262,7 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL ### New -- [Air-Gapped Containers](/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md) is now generally available. +- [Air-Gapped Containers](/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md) is now generally available. - Docker Compose File Viewer shows your Compose YAML with syntax highlighting and contextual links to relevant docs (Beta, progressive rollout). - New Sidebar user experience. @@ -2356,7 +3286,7 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL - Added `proxyEnableKerberosNTLM` config to `settings.json` to enable fallback to basic proxy authentication if Kerberos/NTLM environment is not properly set up. - Fixed a bug where Docker Debug was not working properly with Enhanced Container Isolation enabled. - Fixed a bug where UDP responses were not truncated properly. -- Fixed a bug where the **Update** screen was hidden when using [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- Fixed a bug where the **Update** screen was hidden when using [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). - Fixed a bug where proxy settings defined in `admin-settings.json` were not applied correctly on startup. - Fixed a bug where the **Manage Synchronized file shares with Compose** toggle did not correctly reflect the value with the feature. - Fixed a bug where a bind mounted file modified on host is not updated after the container restarts, when gRPC FUSE file sharing is used on macOS and on Windows with Hyper-V. Fixes [docker/for-mac#7274](https://github.com/docker/for-mac/issues/7274), [docker/for-win#14060](https://github.com/docker/for-win/issues/14060). @@ -2419,7 +3349,7 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL #### For all platforms - Docker Desktop now supports [SOCKS5 proxies](/manuals/desktop/features/networking.md#socks5-proxy-support). Requires a Business subscription. -- Added a new setting to manage the onboarding survey in [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- Added a new setting to manage the onboarding survey in [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). #### For Windows @@ -2496,14 +3426,14 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- You can now enforce Rosetta usage via [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). -- [Docker socket mount restrictions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md) with ECI is now generally available. +- You can now enforce Rosetta usage via [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). +- [Docker socket mount restrictions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md) with ECI is now generally available. - Docker Engine and CLI updated to [Moby 26.0](https://github.com/moby/moby/releases/tag/v26.0.0). This includes Buildkit 0.13, sub volumes mounts, networking updates, and improvements to the containerd multi-platform image store UX. - New and improved Docker Desktop error screens: swift troubleshooting, easy diagnostics uploads, and actionable remediation. - Compose supports [Synchronized file shares (experimental)](/manuals/desktop/features/synchronized-file-sharing.md). - New [interactive Compose CLI (experimental)](/manuals/compose/how-tos/environment-variables/envvars.md#compose_menu). - Beta release of: - - Air-Gapped Containers with [Settings Management](/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md). + - Air-Gapped Containers with [Settings Management](/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md). - [Host networking](/manuals/engine/network/drivers/host.md#docker-desktop) in Docker Desktop. - [Docker Debug](use-desktop/container.md#integrated-terminal) for running containers. - [Volumes Backup & Share extension](use-desktop/volumes.md) functionality available in the **Volumes** tab. @@ -2574,7 +3504,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) now allows admins to set the default file-sharing implementation and specify which paths developer can add file shares to. +- [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) now allows admins to set the default file-sharing implementation and specify which paths developer can add file shares to. - Added support for `socks5://` HTTP and HTTPS proxy URLs when the [`SOCKS` proxy support beta feature](/manuals/desktop/features/networking.md) is enabled. - Users can now filter volumes to see which ones are in use in the **Volumes** tab. @@ -2693,7 +3623,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Docker init now supports Java and is generally available to all users. - [Synchronized File Shares](/manuals/desktop/features/synchronized-file-sharing.md) provides fast and flexible host-to-VM file sharing within Docker Desktop. Utilizing the technology behind [Docker’s acquisition of Mutagen](https://www.docker.com/blog/mutagen-acquisition/), this feature provides an alternative to virtual bind mounts that uses synchronized filesystem caches, improving performance for developers working with large codebases. -- Organization admins can now [configure Docker socket mount permissions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md) when ECI is enabled. +- Organization admins can now [configure Docker socket mount permissions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md) when ECI is enabled. - [Containerd Image Store](/manuals/desktop/features/containerd.md) support is now generally available to all users. - Get a debug shell into any container or image with the new [`docker debug` command](/reference/cli/docker/debug/) (Beta). - Organization admins, with a Docker Business subscription, can now configure a custom list of extensions with [Private Extensions Marketplace](/manuals/extensions/private-marketplace.md) enabled (Beta) @@ -2794,7 +3724,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Administrators can now control access to beta and experimental features in the **Features in development** tab with [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- Administrators can now control access to beta and experimental features in the **Features in development** tab with [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). - Introduced four new version update states in the footer. - `docker init` (Beta) now supports PHP with Apache + Composer. - The [**Builds** view](use-desktop/builds.md) is now GA. You can now inspect builds, troubleshoot errors, and optimize build speed. @@ -2904,7 +3834,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Rosetta is now Generally Available for all users on macOS 13 or later. It provides faster emulation of Intel-based images on Apple Silicon. To use Rosetta, see [Settings](/manuals/desktop/settings-and-maintenance/settings.md). Rosetta is enabled by default on macOS 14.1 and later. - Docker Desktop now detects if a WSL version is out of date. If an out dated version of WSL is detected, you can allow Docker Desktop to automatically update the installation or you can manually update WSL outside of Docker Desktop. - New installations of Docker Desktop for Windows now require a Windows version of 19044 or later. -- Administrators now have the ability to control Docker Scout image analysis in [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- Administrators now have the ability to control Docker Scout image analysis in [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). ### Upgrades @@ -3165,7 +4095,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For all platforms -- [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) now lets you turn off Docker Extensions for your organisation. +- [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) now lets you turn off Docker Extensions for your organisation. - Fixed a bug where turning on Kubernetes from the UI failed when the system was paused. - Fixed a bug where turning on Wasm from the UI failed when the system was paused. - Bind mounts are now shown when you [inspect a container](use-desktop/container.md). @@ -3417,7 +4347,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Fixed a bug where `docker run --gpus=all` hangs. Fixes [docker/for-win#13324](https://github.com/docker/for-win/issues/13324). - Fixed a bug where Registry Access Management policy updates were not downloaded. - Docker Desktop now allows Windows containers to work when BitLocker is enabled on `C:`. -- Docker Desktop with the WSL backend no longer requires the `com.docker.service` privileged service to run permanently. For more information see [Permission requirements for Windows](https://docs.docker.com/desktop/windows/permission-requirements/). +- Docker Desktop with the WSL backend no longer requires the `com.docker.service` privileged service to run permanently. For more information see [Permission requirements for Windows](/manuals/desktop/setup/install/windows-permission-requirements.md). ### For Mac @@ -3797,7 +4727,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Two new security features have been introduced for Docker Business users, Settings Management and Enhanced Container Isolation. Read more about Docker Desktop’s new [Hardened Docker Desktop security model](/manuals/enterprise/security/hardened-desktop/_index.md). +- Two new security features have been introduced for Docker Business users, Settings Management and Enhanced Container Isolation. Read more about Docker Desktop’s new [Hardened Docker Desktop security model](/manuals/desktop/enterprise/hardened-desktop/_index.md). - Added the new Dev Environments CLI `docker dev`, so you can create, list, and run Dev Envs via command line. Now it's easier to integrate Dev Envs into custom scripts. - Docker Desktop can now be installed to any drive and folder using the `--installation-dir`. Partially addresses [docker/roadmap#94](https://github.com/docker/roadmap/issues/94). @@ -4494,7 +5424,7 @@ Installing Docker Desktop 4.5.0 from scratch has a bug which defaults Docker Des ### New - Easy, Secure sign in with Auth0 and Single Sign-on - - Single Sign-on: Users with a Docker Business subscription can now configure SSO to authenticate using their identity providers (IdPs) to access Docker. For more information, see [Single Sign-on](/manuals/enterprise/security/single-sign-on/_index.md). + - Single Sign-on: Users with a Docker Business subscription can now configure SSO to authenticate using their identity providers (IdPs) to access Docker. For more information, see [Single Sign-on](/manuals/security/authentication/single-sign-on/_index.md). - Signing in to Docker Desktop now takes you through the browser so that you get all the benefits of auto-filling from password managers. ### Upgrades @@ -4506,7 +5436,7 @@ Installing Docker Desktop 4.5.0 from scratch has a bug which defaults Docker Des ### Security -- Fixed [CVE-2021-45449](../security/_index.md#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1. +- Fixed [CVE-2021-45449](../security/security-announcements.md#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1. Docker Desktop version 4.3.0 and 4.3.1 has a bug that may log sensitive information (access token or password) on the user's machine during login. This only affects users if they are on Docker Desktop 4.3.0, 4.3.1 and the user has logged in while on 4.3.0, 4.3.1. Gaining access to this data would require having access to the user’s local files. @@ -4546,7 +5476,7 @@ This only affects users if they are on Docker Desktop 4.3.0, 4.3.1 and the user ### Security -- Fixed [CVE-2021-45449](../security/_index.md#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1. +- Fixed [CVE-2021-45449](../security/security-announcements.md#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1. Docker Desktop version 4.3.0 and 4.3.1 has a bug that may log sensitive information (access token or password) on the user's machine during login. This only affects users if they are on Docker Desktop 4.3.0, 4.3.1 and the user has logged in while on 4.3.0, 4.3.1. Gaining access to this data would require having access to the user’s local files. @@ -4610,7 +5540,7 @@ CVE-2021-44228](https://www.docker.com/blog/apache-log4j-2-cve-2021-44228/). #### For Mac -- Docker Desktop on Apple silicon no longer requires Rosetta 2, with the exception of [three optional command line tools](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). +- Docker Desktop on Apple silicon no longer requires Rosetta 2, with the exception of three optional command line tools. #### For Windows @@ -4773,7 +5703,7 @@ The updated [Docker Subscription Service Agreement](https://www.docker.com/legal - **No changes** to Docker Engine or any other upstream **open source** Docker or Moby project. To understand how these changes affect you, read the [FAQs](https://www.docker.com/pricing/faq). -For more information, see [Docker subscription overview](../subscription/_index.md). +For more information, see [Docker subscription overview](../subscription-billing/_index.md). ### Upgrades diff --git a/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md b/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md index 292b5d4d9047..00fa77c5d29d 100644 --- a/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md +++ b/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md @@ -28,7 +28,7 @@ Use this procedure to back up and restore your images and container data. This i If you used a [named volume](/manuals/engine/storage/_index.md#more-details-about-mount-types) to store container data, such as databases, refer to the [back up, restore, or migrate data volumes](/manuals/engine/storage/volumes.md#back-up-restore-or-migrate-data-volumes) page in the storage section. -2. Use [`docker push`](/reference/cli/docker/image/push/) to push any +1. Use [`docker push`](/reference/cli/docker/image/push/) to push any images you have built locally and want to keep to the [Docker Hub registry](/manuals/docker-hub/_index.md). > [!TIP] @@ -57,7 +57,7 @@ and [install a different version](/manuals/desktop/release-notes.md) or reset Do $ docker image load -i images.tar ``` -2. Re-create your containers if needed, using [`docker run`](/reference/cli/docker/container/run/), +1. Re-create your containers if needed, using [`docker run`](/reference/cli/docker/container/run/), or [Docker Compose](/manuals/compose/_index.md). To restore volume data, refer to [backup, restore, or migrate data volumes](/manuals/engine/storage/volumes.md#back-up-restore-or-migrate-data-volumes). @@ -66,26 +66,45 @@ To restore volume data, refer to [backup, restore, or migrate data volumes](/man If Docker Desktop cannot launch and must be reinstalled, you can back up its VM disk and image data directly from disk. Docker Desktop must be fully stopped before backing up these files. +> [!NOTE] +> +> The paths below are the default locations. If you've customized the +> **Disk image location** setting (**Settings** > **Resources** > **Advanced**), +> back up the file at your configured location instead. + {{< tabs >}} {{< tab name="Windows" >}} +Docker Desktop on Windows stores VM data in a different location depending on +which backend you're using. Check **Settings** > **General** > **Choose +Virtual Machine Manager (VMM)** to see which one applies to you. + 1. Back up Docker containers/images. - Backup the following file: + For WSL 2, back up the following file: ```console - %LOCALAPPDATA%\Docker\wsl\data\docker_data.vhdx + %LOCALAPPDATA%\Docker\wsl\disk\docker_data.vhdx ``` - Copy it to a safe location. + If you're running any WSL Linux distributions (Ubuntu, Alpine, etc.), back + them up separately using [Microsoft's guide](https://learn.microsoft.com/en-us/windows/wsl/export-import). + + For Hyper-V, back up the following file: -1. Back up WSL distributions. + ```console + %ProgramData%\DockerDesktop\vm-data\DockerDesktop.vhdx + ``` - If you're running any WSL Linux distributions (Ubuntu, Alpine, etc.), back them up using [Microsoft's guide](https://learn.microsoft.com/en-us/windows/wsl/faq#how-can-i-back-up-my-wsl-distributions-). + For Docker VMM (Beta), back up the following file: -1. Restore. + ```console + %LOCALAPPDATA%\Docker\vm-data\DockerDesktop.vhdx + ``` + +1. Copy your back-up to a safe location. - After reinstalling Docker Desktop, restore the `docker_data.vhdx` to the same location and re-import your WSL distributions if needed. +1. After reinstalling Docker Desktop, restore the `.vhdx` file to the same location for your backend, and re-import your WSL distributions if needed. {{< /tab >}} {{< tab name="Mac" >}} diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index ca8b053b9185..2ef684fbff0f 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -24,7 +24,7 @@ You can also locate the `settings-store.json` file at: - Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` - Linux: `~/.docker/desktop/settings-store.json` -For information on enforcing settings at an organization level, see [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md). +For information on enforcing settings at an organization level, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md). ## General @@ -36,7 +36,7 @@ Configure startup behavior, UI appearance, terminal preferences, and feature def | **Open Docker Dashboard when Docker Desktop starts** | Automatically open the dashboard when starting Docker Desktop. | Disabled | All | | | **Choose theme for Docker Desktop** | Apply a **Light** or **Dark** theme to Docker Desktop. | **Use system settings**. | All | | | **Configure shell completions** | Edits your shell configuration to enable word completion for commands, flags, and Docker objects when you press `<Tab>` in your terminal. For more information, see [Completion](/manuals/engine/cli/completion.md). | Disabled | All | | -| **Choose container terminal** | Sets which terminal opens when you select a container terminal. Use the integrated terminal to run commands in a running container from the Dashboard. For more information, see [Explore containers](/manuals/desktop/use-desktop/container.md). | Disabled | All | | +| **Choose container terminal** | Sets which terminal opens when you select a container terminal. Use the integrated terminal to run commands in a running container from the Dashboard. For more information, see [Explore containers](/manuals/desktop/use-desktop/container.md). | Integrated | All | | | **Enable Docker terminal**. | Interact with your host machine and execute commands directly from Docker Desktop. | Disabled | All | | | **Enable Docker Debug by default** | Use Docker Debug by default opening the integrated terminal. For more information, see [Explore containers](/manuals/desktop/use-desktop/container.md#integrated-terminal). | Disabled | All | | | **Include VM in Time Machine backups** | Back up the Docker Desktop virtual machine. | Disabled | Mac | | @@ -44,11 +44,11 @@ Configure startup behavior, UI appearance, terminal preferences, and feature def | **Expose daemon on tcp://localhost:2375 without TLS** | Allow legacy clients to connect to the Docker daemon. Use with caution as exposing the daemon without TLS can result in remote code execution attacks. | Disabled | Windows (Hyper-V backend only) | | | **Use the WSL 2 based engine** | WSL 2 provides better performance than the Hyper-V backend. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). | Disabled | Windows | | | **Add \*.docker.internal to host file** | Adds internal DNS entries. | Enabled | Windows | Helps resolve Docker-internal domains | -| **Choose Virtual Machine Manager (VMM)** | Choose the VMM for creating and managing the Docker Desktop Linux VM. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). | | Mac | Select **Docker VMM** for the latest and most performant Hypervisor/Virtual Machine Manager. This option is available only on Apple Silicon Macs and is in Beta.| -| **Choose file sharing implementation for your containers** | Choose whether you want to share files using **VirtioFS**, **gRPC FUSE**, or **osxfs (Legacy)** | **VirtioFS** | Mac | Use VirtioFS for speedy file sharing. VirtioFS has reduced the time taken to complete filesystem operations by [up to 98%](https://github.com/docker/roadmap/issues/7#issuecomment-1044452206). It is the only file sharing implementation supported by Docker VMM. | -|**Use Rosetta for x86_64/amd64 emulation on Apple Silicon** | Accelerate x86/AMD64 binary emulation on Apple Silicon. This option is only available if you have selected **Apple Virtualization framework** as the Virtual Machine Manager. | Disabled | Mac | | +| **Choose Virtual Machine Manager (VMM)** | Choose the VMM for creating and managing the Docker Desktop Linux VM. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). | | Mac, Windows | Select **Docker VMM** for optimized container performance. Docker VMM is in Beta. | +| **Choose file sharing implementation for your containers** (Available with the Apple Virtualization framework VMM) | Choose whether you want to share files using **VirtioFS**, or **gRPC FUSE** | **VirtioFS** | Mac | Use VirtioFS for speedy file sharing. VirtioFS has reduced the time taken to complete filesystem operations by [up to 98%](https://github.com/docker/roadmap/issues/7#issuecomment-1044452206). It is the only file sharing implementation supported by Docker VMM. | +|**Use Rosetta for x86_64/amd64 emulation on Apple Silicon** (Available with the Apple Virtualization framework VMM) | Accelerate x86/AMD64 binary emulation on Apple Silicon. | Disabled | Mac | | | **Send usage statistics** | Send diagnostics, crash reports, and usage data to Docker to improve and troubleshoot the application. Docker may periodically prompt you for more information. | Enabled | All | | -| **Use Enhanced Container Isolation** | Prevent containers from breaching the Linux VM. For more information, see [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md). | Disabled | All | Must be signed in and have a Docker Business subscription. | +| **Use Enhanced Container Isolation** | Prevent containers from breaching the Linux VM. For more information, see [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md). | Disabled | All | Must be signed in and have a Docker Business subscription. | | **Show CLI hints** | Display helpful CLI suggestions in terminal. | Enabled | All | Improves discoverability | | **Enable Docker Scout image analysis** | Show a **Start analysis** button when inspecting an image, which analyzes the image with Docker Scout. | Enabled | All | | | **Enable background SBOM indexing** | Automatically analyze images that you build or pull. | Disabled | All | | @@ -119,11 +119,11 @@ For more information, see [Volume mounting requires file sharing for any project Docker Desktop supports HTTP/HTTPS and SOCKS5 proxies. SOCKS5 requires a Business subscription. To prevent developers from accidentally changing the proxy settings, see -[Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md#what-features-can-i-configure-with-settings-management). +[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md#what-features-can-i-configure-with-settings-management). #### Docker Desktop proxy -Used for signing in to Docker, pulling and pushing images, fetching artifacts during image builds, and reporting error diagnostics. +Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for `docker image pull` only when [Containers proxy](#containers-proxy) is not configured. | Proxy mode | Description | |------------|-------------| @@ -131,13 +131,20 @@ Used for signing in to Docker, pulling and pushing images, fetching artifacts du | **No proxy** | Connect directly without a proxy. | | **Manual configuration** | Enter a **Web Server (HTTP)** and **Secure Web Server (HTTPS)** URL manually. Use the format `http://proxy:port` or `https://proxy:port`. You can also specify hosts and domains that should bypass the proxy, for example: `registry-1.docker.com,*.docker.com,10.0.0.0/8`. | +Docker Desktop reads a proxy or PAC URL that is statically configured on the +host. For example a manual proxy setting, a static PAC file URL, or a +GPO-managed override. WPAD (Web Proxy Auto-Discovery Protocol) auto-discovery +is untested on both Windows and Mac and isn't officially supported. If your +proxy is only discoverable via WPAD (DHCP option 252 or the `wpad.<domain>` +DNS convention), configure a static PAC URL or proxy address instead. + > [!NOTE] > -> If you use a PAC file hosted on a web server, add the MIME type `application/x-ns-proxy-autoconfig` for the `.pac` extension. Without this, the PAC file may not parse correctly. See [Hardened Docker Desktop](/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md#proxy-auto-configuration-files). +> If you use a PAC file hosted on a web server, add the MIME type `application/x-ns-proxy-autoconfig` for the `.pac` extension. Without this, the PAC file may not parse correctly. See [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md#proxy-auto-configuration-files). #### Containers proxy -Used for outbound traffic from running containers. +Used for `docker image pull` (always enforced - all `docker pull` and Compose pull operations go through this proxy) and for outbound traffic from running containers when air-gapped container enforcement is configured. If a PAC file is configured here, ensure it returns an appropriate proxy server for Docker registry endpoints, or image pulls will fail. | Proxy mode | Description | |------------|-------------| @@ -150,6 +157,16 @@ Used for outbound traffic from running containers. > > The HTTPS proxy used for image scanning is configured using the `HTTPS_PROXY` environment variable. +#### Windows Docker daemon proxy + +When you run Windows containers, enable **Use proxy for Windows Docker daemon** +to let the Windows Docker daemon connect to Docker Desktop's internal proxy. +This allows Windows containers to use the configured Docker Desktop proxy, and +it is required if you want [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) +restrictions to apply to Windows image operations. Administrators can manage +the same behavior with +[**Override Windows "dockerd" port**](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#override-windows-dockerd-port). + #### Proxy authentication | Method | Behavior | Notes | @@ -286,7 +303,7 @@ Manage how and when Docker Desktop checks for and downloads updates. | ------------------- | ----------------------------------------- | ------------------------------------- | | **Automatically check for updates** | Notifies you of available updates in the Docker menu and Dashboard footer. | Enabled | | **Always download updates** | Automatically download new versions of Docker Desktop in the background. | Disabled | -| **Automatically update components** | Update Docker Desktop components (such as Docker Compose, Docker Scout, and the Docker CLI) independently, without a full restart. | Enabled | +| **Automatically update components** | Update Docker Desktop components (such as Docker Compose, Docker Scout, and the Docker CLI) independently, without a full restart. Available with Docker Desktop version 4.92 and earlier. | Enabled | ## Extensions @@ -329,14 +346,15 @@ Notifications appear briefly in the lower-right of the Docker Desktop Dashboard, ## Advanced (Mac only) -Reconfigure CLI tool installation paths and privileged system permissions set during initial install. +Reconfigure CLI tool installation paths and privileged system permissions. With Docker Desktop version 4.88.0 and earlier, these can be set during installation. | Setting | Description | Notes | | ------------------- | ----------------------------------------- | ------------------------------------- | -| CLI tools installation — **System** | Install Docker CLI tools to `/usr/local/bin`. | | -| CLI tools installation — **User** | Install Docker CLI tools to `$HOME/.docker/bin` | Add `$HOME/.docker/bin` to your PATH by appending `export PATH=$PATH:~/.docker/bin` to `~/.bashrc` or `~/.zshrc`, then restart your shell. | +| CLI tools installation — **System** | Install Docker CLI tools to `/usr/local/bin`. | Requires password with version 4.89.0 and later. | +| CLI tools installation — **User** | Install Docker CLI tools to `$HOME/.docker/bin`. This is the default with version 4.89.0 and later. | Automatically added to your PATH in version 4.89.0 and later. | | **Allow the default Docker socket to be used** | Creates `/var/run/docker.sock` which some third party clients may use to communicate with Docker Desktop. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#installing-symlinks). | Requires password | -| **Allow privileged port mapping** | Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#binding-privileged-ports). | Requires password | +| **Allow privileged port mapping** | Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#binding-privileged-ports). | Available with version 4.88.0 and earlier. Requires password | +| **Allow privileged port forwarding to external machines** | Allows privileged ports (1 to 1024) to be exposed to other machines on your local network. When turned off, privileged ports are only reachable through loopback addresses. For more information, see [permission requirements for Mac](/manuals/desktop/setup/install/mac-permission-requirements.md#binding-privileged-ports). | Available with version 4.97 and later. Doesn't require a password | ## Docker Offload @@ -345,5 +363,5 @@ Enable Docker Offload and configure idle timeout and GPU support for cloud-based | Setting | Description | Notes | | ------------------- | ----------------------------------------- | ------------------------------------- | | **Enable Docker Offload** | Run your containers in the cloud. | Requires sign-in and an Offload subscription | -| **Idle timeout** | Set the duration of time between no activity and Docker Offload entering idle mode. For details about idle timeout, see [Active and idle states](../../offload/configuration.md#understand-active-and-idle-states). | | +| **Idle timeout** | Set the duration of time between no activity and Docker Offload entering idle mode. For details about idle timeout, see [Session management and idle state](/manuals/offload/about.md#session-management-and-idle-state). | | | **Enable GPU support** | Let your workloads use cloud GPU if available. | | diff --git a/content/manuals/desktop/setup/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md index 6440f2a6a943..5b335ad27702 100644 --- a/content/manuals/desktop/setup/install/linux/_index.md +++ b/content/manuals/desktop/setup/install/linux/_index.md @@ -13,6 +13,7 @@ aliases: - /desktop/linux/install/ - /desktop/install/linux-install/ - /desktop/install/linux/ + - /desktop/linux/ --- > **Docker Desktop terms** @@ -143,7 +144,7 @@ To install Docker Desktop successfully, your Linux host must meet the following - For many Linux distributions, the GNOME environment does not support tray icons. To add support for tray icons, you need to install a GNOME extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/). - At least 4 GB of RAM. - Enable configuring ID mapping in user namespaces, see [File sharing](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore. -- Recommended: [Initialize `pass`](/manuals/desktop/setup/sign-in.md#credentials-management-for-linux-users) for credentials management. +- [Initialize `pass`](#signing-in-with-docker-desktop-for-linux) for credentials management. Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm). @@ -201,6 +202,53 @@ $ sudo usermod -aG kvm $USER Sign out and sign back in so that your group membership is re-evaluated. +## Signing in with Docker Desktop for Linux + +Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in GPG-encrypted files. +Before signing in to Docker Desktop with your [Docker ID](/accounts/individual/create-account/), you must initialize `pass`. +Docker Desktop displays a warning if `pass` is not configured. + +1. Generate a GPG key. You can initialize pass by using a gpg key. To generate a gpg key, run: + + ``` console + $ gpg --generate-key + ``` +2. Enter your name and email once prompted. + + Once confirmed, GPG creates a key pair. Look for the `pub` line that contains your GPG ID, for example: + + ```text + ... + pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30] + 3ABCD1234EF56G78 + uid Molly <molly@example.com> + ``` +3. Copy the GPG ID and use it to initialize `pass`. For example + + ```console + $ pass init 3ABCD1234EF56G78 + ``` + + You should see output similar to: + + ```text + mkdir: created directory '/home/molly/.password-store/' + Password store initialized for <generated_gpg-id_public_key> + ``` + +Once you initialize `pass`, you can sign in and pull your private images. +When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the GPG key generation. + +```console +$ docker pull molly/privateimage +Using default tag: latest +latest: Pulling from molly/privateimage +3b9cc81c3203: Pull complete +Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96 +Status: Downloaded newer image for molly/privateimage:latest +docker.io/molly/privateimage:latest +``` + ## Using Docker SDKs with Docker Desktop Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. Docker SDKs and tools that connect directly to the Docker daemon need the `DOCKER_HOST` environment variable set to connect to Docker Desktop. For configuration details, see [How do I use Docker SDKs with Docker Desktop for Linux?](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-use-docker-sdks-with-docker-desktop-for-linux). diff --git a/content/manuals/desktop/setup/install/linux/archlinux.md b/content/manuals/desktop/setup/install/linux/archlinux.md index 92092ccea699..7493970a690c 100644 --- a/content/manuals/desktop/setup/install/linux/archlinux.md +++ b/content/manuals/desktop/setup/install/linux/archlinux.md @@ -50,7 +50,7 @@ To install Docker Desktop successfully, you must meet the [general system requir ## Next steps - Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopArchlinuxInstall) to see what Docker can offer you. -- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Take a look at [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. - [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. diff --git a/content/manuals/desktop/setup/install/linux/debian.md b/content/manuals/desktop/setup/install/linux/debian.md index 329e3a004b1c..93cd5a9ac851 100644 --- a/content/manuals/desktop/setup/install/linux/debian.md +++ b/content/manuals/desktop/setup/install/linux/debian.md @@ -84,7 +84,7 @@ $ sudo apt-get install ./docker-desktop-amd64.deb ## Next steps - Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopDebianInstall) to see what Docker can offer you. -- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Take a look at [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. - [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. diff --git a/content/manuals/desktop/setup/install/linux/fedora.md b/content/manuals/desktop/setup/install/linux/fedora.md index b9ccfda4d9a4..aee783ac872a 100644 --- a/content/manuals/desktop/setup/install/linux/fedora.md +++ b/content/manuals/desktop/setup/install/linux/fedora.md @@ -24,7 +24,7 @@ This page contains information on how to install, launch and upgrade Docker Desk To install Docker Desktop successfully, you must: - Meet the [general system requirements](_index.md#general-system-requirements). -- Have a 64-bit version of Fedora 42 or Fedora 43. +- Have a 64-bit version of Fedora 43 or later. - For a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). - If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop: @@ -74,7 +74,7 @@ $ sudo dnf install ./docker-desktop-x86_64.rpm ## Next steps - Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopFedoraInstall) to see what Docker can offer you. -- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Take a look at [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. - [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. diff --git a/content/manuals/desktop/setup/install/linux/rhel.md b/content/manuals/desktop/setup/install/linux/rhel.md index 68e7e3ce586d..321a22764a12 100644 --- a/content/manuals/desktop/setup/install/linux/rhel.md +++ b/content/manuals/desktop/setup/install/linux/rhel.md @@ -127,7 +127,7 @@ $ sudo dnf install ./docker-desktop-<arch>-rhel.rpm ## Next steps - Review [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopRhelInstall) to see what Docker can offer you. -- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Take a look at [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. - [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. diff --git a/content/manuals/desktop/setup/install/linux/ubuntu.md b/content/manuals/desktop/setup/install/linux/ubuntu.md index fea93c456c24..b673fc27c167 100644 --- a/content/manuals/desktop/setup/install/linux/ubuntu.md +++ b/content/manuals/desktop/setup/install/linux/ubuntu.md @@ -30,6 +30,7 @@ To install Docker Desktop successfully, you must: - Meet the [general system requirements](_index.md#general-system-requirements). - Have an x86-64 system with Ubuntu 26.04 LTS or 24.04 LTS. +- For a GNOME desktop environment, you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). - If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop: ```console $ sudo apt install gnome-terminal @@ -87,7 +88,7 @@ $ sudo apt install ./docker-desktop-amd64.deb ## Next steps - Review [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopUbuntuInstall) to see what Docker can offer you. -- Follow the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Follow [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. - [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. diff --git a/content/manuals/desktop/setup/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md index 3c065841aa15..097533928815 100644 --- a/content/manuals/desktop/setup/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -23,8 +23,8 @@ aliases: This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Mac. -{{< button text="Docker Desktop for Mac with Apple silicon" url="https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64" >}} -{{< button text="Docker Desktop for Mac with Intel chip" url="https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64" >}} +{{< button text="Docker Desktop for Mac with Apple silicon" url="https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64" marlin_label="download_dmg_click" >}} +{{< button text="Docker Desktop for Mac with Intel chip" url="https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64" marlin_label="download_dmg_click" >}} *For checksums, see [Release notes](/manuals/desktop/release-notes.md).* @@ -40,7 +40,7 @@ This page provides download links, system requirements, and step-by-step install > Docker Desktop is supported on the current and two previous major macOS releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases). - At least 4 GB of RAM. -- For the best experience, it's recommended that you install Rosetta 2. Rosetta 2 is no longer strictly required, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). To install Rosetta 2 manually from the command line, run the following command: +- For the best experience, it's recommended that you install Rosetta 2. Rosetta 2 is no longer strictly required, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. To install Rosetta 2 manually from the command line, run the following command: ```console $ softwareupdate --install-rosetta @@ -63,11 +63,11 @@ This page provides download links, system requirements, and step-by-step install > > - Quit tools that might call Docker in the background (Visual Studio Code, terminals, agent apps). > -> - If you manage fleets or install via MDM, use the [**PKG installer**](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md). +> - If you manage fleets or install via MDM, use the [**PKG installer**](/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md). > > - Keep the installer volume mounted until the installation completes. > -> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md). +> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md). ## Install and run Docker Desktop on Mac @@ -79,11 +79,11 @@ This page provides download links, system requirements, and step-by-step install 1. Download the installer using the download buttons at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). -2. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`. +1. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`. -3. Double-click `Docker.app` in the **Applications** folder to start Docker. +1. Double-click `Docker.app` in the **Applications** folder to start Docker. -4. The Docker menu displays the Docker Subscription Service Agreement. +1. The Docker menu displays the Docker Subscription Service Agreement. Here’s a summary of the key points: - Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects. @@ -91,16 +91,24 @@ This page provides download links, system requirements, and step-by-step install - Paid subscriptions are also required for government entities. - Docker Pro, Team, and Business subscriptions include commercial use of Docker Desktop. -5. Select **Accept** to continue. +1. Select **Accept** to continue. Note that Docker Desktop won't run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop. For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). It is recommended that you also read the [FAQs](https://www.docker.com/pricing/faq). -6. From the installation window, select either: - - **Use recommended settings (Requires password)**. This lets Docker Desktop automatically set the necessary configuration settings. - - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See [Settings](/manuals/desktop/settings-and-maintenance/settings.md#advanced), for more information and how to set the location of the Docker CLI tools. -7. Select **Finish**. If you have applied any of the previous configurations that require a password in step 6, enter your password to confirm your choice. +1. Docker Desktop starts. No further configuration is needed and you aren't asked for a password. + + Docker Desktop applies a default configuration that requires no privileged access: Docker CLI tools are installed under `$HOME/.docker/bin`, which is added to your `PATH`, and the default Docker socket isn't created. To change either of these, go to **Settings** > **Advanced** after installation. See [Advanced (Mac only)](/manuals/desktop/settings-and-maintenance/settings.md#advanced-mac-only). + + > [!NOTE] + > + > With Docker Desktop version 4.88.0 and earlier, these options are presented during installation instead. From the installation window, select either: + > + > - **Use recommended settings (requires password)**. This lets Docker Desktop automatically set the necessary configuration settings. + > - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. + > + > Then select **Finish**. If you applied any configuration that requires a password, enter your password to confirm your choice. ### Install from the command line @@ -122,12 +130,12 @@ The `install` command accepts the following flags: - `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run. - `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI. +- `--backend=docker-vmm`: Selects the Docker VMM engine at install time. `docker-vmm` is the only supported value on Mac; any other value fails the installation. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). ##### Security and access - `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application -- `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI. -- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). - It must be used together with the `--allowed-org=<org name>` flag. - For example: `--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"` @@ -139,6 +147,15 @@ The `install` command accepts the following flags: - `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. It's a comma-separated list. - `--override-proxy-pac=<PAC file URL>`: Sets the PAC file URL. This setting takes effect only when using `manual` proxy mode. - `--override-proxy-embedded-pac=<PAC script>`: Specifies an embedded PAC (Proxy Auto-Config) script. This setting takes effect only when using `manual` proxy mode and has precedence over the `--override-proxy-pac` flag. +- `--proxy-enable-kerberosntlm`: Enables Kerberos and NTLM proxy authentication. If you are enabling this, ensure your proxy server is properly configured for Kerberos/NTLM authentication. + +> [!IMPORTANT] +> +> Addresses passed to `--override-proxy-http` and `--override-proxy-https` are validated during installation, and an invalid value fails the install: +> +> - The address must include a port, for example `http://proxy.example.com:3128`. An address with no port is rejected. +> - The address must not include credentials. Use `--proxy-enable-kerberosntlm` for authenticated proxies. +> - If you omit the scheme, `http://` is added for you. `http://`, `https://`, and `socks5://` are accepted. ###### Example of specifying PAC file @@ -154,7 +171,7 @@ $ sudo /Applications/Docker.app/Contents/MacOS/install --user testuser --proxy-h > [!TIP] > -> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). +> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). > - [Intune](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps) > - [Jamf](https://docs.jamf.com/10.25.0/jamf-pro/administrator-guide/Application_Usage.html) > - [Kandji](https://support.kandji.io/support/solutions/articles/72000559793-view-a-device-application-list) @@ -164,7 +181,7 @@ $ sudo /Applications/Docker.app/Contents/MacOS/install --user testuser --proxy-h ## Where to go next - Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopMacInstall) to see what Docker can offer you. -- [Get started with Docker](/get-started/introduction/_index.md). +- [Build and share a containerized application](/get-started/tutorials/run-an-app.md). - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. diff --git a/content/manuals/desktop/setup/install/mac-permission-requirements.md b/content/manuals/desktop/setup/install/mac-permission-requirements.md index 4f08136c65de..e5413e787491 100644 --- a/content/manuals/desktop/setup/install/mac-permission-requirements.md +++ b/content/manuals/desktop/setup/install/mac-permission-requirements.md @@ -19,42 +19,45 @@ Docker Desktop on Mac is designed with security in mind. Administrative rights a Docker Desktop for Mac is run as an unprivileged user. However, Docker Desktop requires certain functionalities to perform a limited set of privileged configurations such as: - [Installing symlinks](#installing-symlinks) in`/usr/local/bin`. - - [Binding privileged ports](#binding-privileged-ports) that are less than 1024. Although privileged ports (ports below 1024) are not typically used as a security boundary, operating systems still prevent unprivileged processes from binding to them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`. - [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs don't have `localhost` in `/etc/hosts`, which causes Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers. - - Securely caching the Registry Access Management policy which is read-only for the developer. + - [Binding privileged ports](#binding-privileged-ports) that are less than 1024. Although privileged ports (ports below 1024) are not typically used as a security boundary, operating systems still prevent unprivileged processes from binding to them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`. (Applies to version 4.88 and earlier). + - Securely caching the Registry Access Management policy which is read-only for the developer. (Applies to version 4.88 and earlier). -Privileged access is granted during installation. +Privileged access, when needed, is granted through the **Advanced** page in **Settings**. With version 4.88 and earlier, this is granted during installation. -The first time Docker Desktop for Mac launches, it presents an installation window where you can choose to either use the default settings, which work for most developers and requires you to grant privileged access, or use advanced settings. - -If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can use the advanced settings to remove the need for granting privileged access. You can configure: +From the **Advanced** page, you can enable: - The location of the Docker CLI tools either in the system or user directory - The default Docker socket -- Privileged port mapping -Depending on which advanced settings you configure, you must enter your password to confirm. +If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can leave these settings at their defaults to avoid granting privileged access. -You can change these configurations at a later date from the **Advanced** page in **Settings**. +Depending on which advanced settings you configure, you must enter your password to confirm. ### Installing symlinks -The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop creates symlinks for the binaries in `/usr/local/bin`, which means they're automatically included in `PATH` on most systems. +The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. By default, Docker Desktop creates symlinks for the binaries in `$HOME/.docker/bin`, which is automatically added to your terminal's `PATH`. -You can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop. +You can change the symlink location to `/usr/local/bin` from the **Advanced** page in **Settings**. If `/usr/local/bin` is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created there. -If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings-and-maintenance/settings.md#advanced) to your PATH. +You are also given the option to enable the installation of the `/var/run/docker.sock` symlink from the **Advanced** page in **Settings**. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes. -You are also given the option to enable the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes. +As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the you aren't prompted on each startup to create the symlink. If you don't enable this option, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` environment variable to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup. -As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the you aren't prompted on each startup to create the symlink. If you don't enable this option at installation, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` environment variable to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup. +### Ensuring `localhost` and `kubernetes.docker.internal` are defined + +It is your responsibility to ensure that localhost is resolved to `127.0.0.1` and if Kubernetes is used, that `kubernetes.docker.internal` is resolved to `127.0.0.1`. ### Binding privileged ports -You can choose to enable privileged port mapping during installation, or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice. +You can choose to enable privileged port mapping during installation (version 4.88.0 and earlier), or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice. -### Ensuring `localhost` and `kubernetes.docker.internal` are defined +With version 4.97 and later, Docker Desktop binds privileged ports directly and doesn't require authorization. By default, privileged ports are only reachable through loopback addresses, such as `127.0.0.1`. Publishing a privileged port on a specific non-loopback IP address, for example `-p 192.168.1.10:80:80`, fails with an error. -It is your responsibility to ensure that localhost is resolved to `127.0.0.1` and if Kubernetes is used, that `kubernetes.docker.internal` is resolved to `127.0.0.1`. +To expose privileged ports to other machines on your local network, go to **Settings** > **Advanced** and select **Allow privileged port forwarding to external machines**. + +## Local Network permission + +For containers to reach devices on your local network, Docker Desktop needs the macOS **Local Network** permission. You can check it in **System Settings** > **Privacy & Security** > **Local Network**. See [Containers can't reach devices on my local network](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#containers-cant-reach-devices-on-my-local-network). ## Installing from the command line @@ -65,9 +68,9 @@ Privileged configurations are applied during the installation with the `--user` The limitation of this approach is that Docker Desktop can only be run by one user-account per machine, namely the one specified in the `-–user` flag. -## Privileged helper +## Privileged helper (version 4.88 and earlier) -In the limited situations when the privileged helper is needed, for example binding privileged ports or caching the Registry Access Management policy, the privileged helper is started by `launchd` and runs in the background unless it is disabled at runtime as previously described. The Docker Desktop backend communicates with the privileged helper over the UNIX domain socket `/var/run/com.docker.vmnetd.sock`. The functionalities it performs are: +In the limited situations when the privileged helper is needed, for example binding privileged ports or caching the Registry Access Management policy, the privileged helper is started by `launchd` and runs in the background unless it is disabled at runtime as previously described. The Docker Desktop backend communicates with the privileged helper over the Unix domain socket `/var/run/com.docker.vmnetd.sock`. The functionalities it performs are: - Binding privileged ports that are less than 1024. - Securely caching the Registry Access Management policy which is read-only for the developer. - Uninstalling the privileged helper. @@ -90,6 +93,16 @@ $ rm /Library/LaunchDaemons/com.docker.vmnetd.plist $ rm /Library/PrivilegedHelperTools/com.docker.vmnetd ``` +## Backend helper socket + +The Docker Desktop backend process (`com.docker.backend`) uses an internal helper socket +(`~/Library/Containers/com.docker.docker/Data/forkexecd.sock`) to fork and execute +helper processes as part of running Docker Desktop. + +This socket does not run as `root` and grants no elevated privileges. It is owned by, +and accessible only to, the same macOS user running Docker Desktop, and is contained +in Docker Desktop's application container. + ## Containers running as root within the Linux VM With Docker Desktop, the Docker daemon and containers run in a lightweight Linux @@ -102,7 +115,7 @@ retain their original permissions. ## Enhanced Container Isolation In addition, Docker Desktop supports [Enhanced Container Isolation -mode](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) (ECI), +mode](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) (ECI), available to Business customers only, which further secures containers without impacting developer workflows. diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index 0d3ee78e8bf2..b3cf61196fe9 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -24,15 +24,15 @@ aliases: This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Windows. -{{< button text="Docker Desktop for Windows - x86_64" url="https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64" >}} +{{< button text="Docker Desktop for Windows - x86_64" url="https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64" marlin_label="download_exe_click" >}} {{< button text="Docker Desktop for Windows - x86_64 on the Microsoft Store" url="https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB&gl=GB" >}} -{{< button text="Docker Desktop for Windows - Arm (Early Access)" url="https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-arm64" >}} +{{< button text="Docker Desktop for Windows - Arm (Early Access)" url="https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-arm64" marlin_label="download_exe_click" >}} _For checksums, see [Release notes](/manuals/desktop/release-notes.md)_ ## Installation modes -Docker Desktop supports two installation modes. Per-user installation (Beta) is recommended for most users. It does not require administrator privileges to install or update, and the WSL 2 backend it uses covers the needs of the vast majority of Docker Desktop users. +Docker Desktop supports two installation modes. Per-user installation is recommended for most users and is selected by default in the installer. It does not require administrator privileges to install or update, and the WSL 2 backend it uses covers the needs of the vast majority of Docker Desktop users. | | Per-user (recommended) | All users | |---|---|---| @@ -40,19 +40,19 @@ Docker Desktop supports two installation modes. Per-user installation (Beta) is | Registry keys | Current User (HKCU) | Local Machine (HKLM) | | Admin rights to install | Not required | Required | | Admin rights to update | Not required | Required | -| Linux containers backend | WSL 2 only | WSL 2 or Hyper-V | +| Linux containers backend | WSL 2 or Docker VMM | WSL 2, Hyper-V, or Docker VMM | | Windows containers | Not supported | Supported | | Security | Smaller attack surface; no privileged system service installed | Requires privileged system service; broader access to host resources | -For more information, see [Understand permission requirements for Windows](windows-install.md). +For more information, see [Understand permission requirements for Windows](./windows-permission-requirements.md). ## System requirements > [!TIP] > -> **Should I use Hyper-V or WSL?** +> **Which backend should I use?** > -> Docker Desktop's functionality remains consistent on both WSL and Hyper-V, without a preference for either architecture. Hyper-V and WSL have their own advantages and disadvantages, depending on your specific setup and your planned use case. Note that Hyper-V is only available with all-users installation. If you install Docker Desktop in per-user mode, WSL 2 is the only supported backend. +> Docker Desktop for Windows supports three backends: WSL 2, Hyper-V, and Docker VMM (Beta). WSL 2 is the default and works for most users without administrator privileges. Hyper-V is only available with all-users installation. Docker VMM is a container-optimized hypervisor that reclaims idle memory and improves file I/O. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). {{< tabs >}} {{< tab name="WSL 2 backend, x86_64" >}} @@ -144,21 +144,23 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m 1. Download the installer using the download button at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). -2. Double-click `Docker Desktop Installer.exe` to run the installer. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. Choosing all users will prompt for elevation. +1. Double-click `Docker Desktop Installer.exe` to run the installer. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. Choosing all users will prompt for elevation. > [!NOTE] > >If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop. -3. When prompted, ensure the **Use WSL 2 instead of Hyper-V** option on the Configuration page is selected or not depending on your choice of backend. +1. When prompted, select your backend on the **Configuration page**: **Use WSL 2 instead of Hyper-V** for WSL 2, or leave it unselected for Hyper-V. You can switch to Docker VMM after installation from **Settings** > **General**. + + With version 4.97 and later, the **Configuration** page lists the backends as options. Per-user installation offers WSL 2 and Docker VMM (Beta). All-users installation offers WSL 2 and Hyper-V. On systems that support only one backend, Docker Desktop automatically selects the available option. -4. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation. +1. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation. -5. When the installation is successful, select **Close** to complete the installation process. +1. When the installation is successful, select **Close** to complete the installation process. -6. [Start Docker Desktop](#start-docker-desktop). +1. [Start Docker Desktop](#start-docker-desktop). ### Install from the command line @@ -202,6 +204,12 @@ If using all-users installation and your administrator account is different to y $ net localgroup docker-users <user> /add ``` +> [!WARNING] +> +> Membership in `docker-users` grants access to the Docker daemon socket, which is equivalent to granting administrative privileges on the host. Only add users who require access to Windows containers or Hyper-V VM management. For Linux containers using the WSL 2 backend, this group membership is not required. See [Protect the Docker daemon socket](/manuals/engine/security/protect-access.md) for more information. + +If you're deploying via MDM (such as Intune) and the `docker-users` group isn't populated automatically, see [Why isn't the `docker-users` group populated when the MSI is installed with Intune or another MDM solution?](/manuals/desktop/enterprise/enterprise-deployment/faq.md#why-isnt-the-docker-users-group-populated-when-the-msi-is-installed-with-intune-or-another-mdm-solution). + See the [Installer flags](#installer-flags) section to see what flags the `install` command accepts. > [!NOTE] @@ -226,7 +234,7 @@ Docker Desktop does not start automatically after installation. To start Docker > [!TIP] > -> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). +> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). > - [Intune](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps) > - [Jamf](https://docs.jamf.com/10.25.0/jamf-pro/administrator-guide/Application_Usage.html) > - [Kandji](https://support.kandji.io/support/solutions/articles/72000559793-view-a-device-application-list) @@ -277,21 +285,20 @@ If Microsoft Store access is blocked due to security policies: #### Installation behavior - - `--user`: Installs Docker Desktop in per-user mode, to `%LOCALAPPDATA%\Programs\DockerDesktop`. No administrator privileges are required. This is the recommended mode for most users. See [Installation modes](#installation-modes). - `--quiet`: Suppresses information output when running the installer - `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run - `--installation-dir=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`) -- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default) +- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop: `wsl-2` (default), `hyper-v`, `windows`, or `docker-vmm`. With version 4.97 and later, `docker-vmm` can be combined with the `--user` flag. `hyper-v` and `windows` can't be combined with `--user`. - `--always-run-service`: After installation completes, starts `com.docker.service` and sets the service startup type to Automatic. This circumvents the need for administrator privileges, which are otherwise necessary to start `com.docker.service`. `com.docker.service` is required by Windows containers and Hyper-V backend. #### Security and access control - `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application -- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). - It must be used together with the `--allowed-org=<org name>` flag. - For example:`--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"` -- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers). +- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. Can't be combined with `--backend=windows`. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers). #### Proxy configuration @@ -370,7 +377,7 @@ again when you switch back. ## Where to go next - Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopWindowsInstall) to see what Docker can offer you. -- [Get started with Docker](/get-started/introduction/_index.md). +- [Build and share a containerized application](/get-started/tutorials/run-an-app.md). - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. - [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, and how to get support. diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index 690ee63c6d12..36c2e7a1fe5e 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -4,6 +4,8 @@ keywords: Docker Desktop, Windows, security, install title: Understand permission requirements for Windows linkTitle: Windows permission requirements weight: 40 +aliases: + - /desktop/windows/permission-requirements/ --- This page contains information about the permission requirements for running and installing Docker Desktop on Windows, the functionality of the privileged helper process `com.docker.service`, and the reasoning behind this approach. @@ -16,7 +18,7 @@ Docker Desktop on Windows is designed with security in mind. Administrative righ The permissions required to install and run Docker Desktop depend on which [installation mode](/manuals/desktop/setup/install/windows-install.md#installation-modes) you use. -### Per-user installation (Beta) +### Per-user installation In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and writes only to current-user registry keys (`HKCU`). This means: @@ -24,7 +26,7 @@ In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesk - After installation, Docker Desktop can be run without administrator privileges. - Some settings marked **Requires password** in **Settings** still require elevation. When you change one of these settings and select **Apply**, Docker Desktop opens a UAC prompt for administrator access. -Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. For most users this is not a limitation, as the WSL 2 backend covers the majority of use cases. +Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. Docker VMM (Beta) is available in per-user mode and does not require the privileged helper. For most users, the WSL 2 or Docker VMM backend covers the majority of use cases. ### All-users installation @@ -56,22 +58,22 @@ Docker Desktop needs to perform a limited set of privileged operations which are > [!NOTE] > -> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which instead relies solely on the WSL 2 backend and does not support Hyper-V or Windows containers. +> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which relies on the WSL 2 or Docker VMM backend and does not support Hyper-V or Windows containers. The privileged helper `com.docker.service` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it. The service performs the following functionalities: - Ensuring that `kubernetes.docker.internal` is defined in the Win32 hosts file. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers. - Ensuring that `host.docker.internal` and `gateway.docker.internal` are defined in the Win32 hosts file. They point to the host local IP address and allow an application to resolve the host IP using the same name from either the host itself or a container. -- Securely caching the Registry Access Management policy which is read-only for the developer. - Creating the Hyper-V VM `"DockerDesktopVM"` and managing its lifecycle - starting, stopping, and destroying it. The VM name is hard coded in the service code so the service cannot be used for creating or manipulating any other VMs. - Moving the VHDX file or folder. -- Starting and stopping the Windows Docker engine and querying whether it's running. +- Starting and stopping Windows Docker Engine and querying whether it's running. - Deleting all Windows containers data files. - Checking if Hyper-V is enabled. - Checking if the bootloader activates Hyper-V. - Checking if required Windows features are both installed and enabled. - Conducting healthchecks and retrieving the version of the service itself. +- Securely caching the Registry Access Management policy which is read-only for the developer. (Applies to version 4.88.0 and earlier) The service start mode depends on which container engine is selected, and, for WSL, on whether it is needed to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file. This is controlled by a setting under `Use the WSL 2 based engine` in the settings page. When this is set, WSL engine behaves the same as Hyper-V. So: - With Windows containers, or Hyper-v Linux containers, the service is started when the system boots and runs all the time, even when Docker Desktop isn't running. This is required so you can launch Docker Desktop without admin privileges. @@ -91,7 +93,7 @@ into Docker containers still retain their original permissions. Containers don' ## Enhanced Container Isolation In addition, Docker Desktop supports [Enhanced Container Isolation -mode](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) (ECI), +mode](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md) (ECI), available to Business customers only, which further secures containers without impacting developer workflows. @@ -111,7 +113,7 @@ isolated from the Docker daemon and other services running inside the VM. > > Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user. See [Installation modes](/manuals/desktop/setup/install/windows-install.md#installation-modes). -Unlike the Linux Docker Engine and containers which run in a VM, Windows containers are implemented using operating system features, and run directly on the Windows host. If you enable Windows containers during installation, the `ContainerAdministrator` user used for administration inside the container is a local administrator on the host machine. Enabling Windows containers during installation makes it so that members of the `docker-users` group are able to elevate to administrators on the host. For organizations who don't want their developers to run Windows containers, a `-–no-windows-containers` installer flag is available to disable their use. +Unlike the Linux Docker Engine and containers which run in a VM, Windows containers are implemented using operating system features, and run directly on the Windows host. If you enable Windows containers during installation, the `ContainerAdministrator` user used for administration inside the container is a local administrator on the host machine. Enabling Windows containers during installation makes it so that members of the `docker-users` group are able to elevate to administrators on the host. For organizations who don't want their developers to run Windows containers, a `--no-windows-containers` installer flag is available to disable their use. ## Networking diff --git a/content/manuals/desktop/setup/sign-in.md b/content/manuals/desktop/setup/sign-in.md deleted file mode 100644 index 01b04cab60d5..000000000000 --- a/content/manuals/desktop/setup/sign-in.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Explore the Learning center and understand the benefits of signing in - to Docker Desktop -keywords: Docker Dashboard, manage, containers, gui, dashboard, images, user manual, - learning center, guide, sign in -title: Sign in to Docker Desktop -linkTitle: Sign in -weight: 40 -aliases: -- /desktop/linux/ -- /desktop/mac/ -- /desktop/windows/ -- /docker-for-mac/ -- /docker-for-windows/ -- /desktop/get-started/ ---- - -Docker recommends signing in with the **Sign in** option in the top-right corner of the Docker Dashboard. - -In large enterprises where admin access is restricted, administrators can [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). - -> [!TIP] -> -> Explore [Docker's core subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopSignIn) to see what else Docker can offer you. - -## Benefits of signing in - -- Access your Docker Hub repositories directly from Docker Desktop. - -- Increase your pull rate limit compared to anonymous users. See [Usage and limits](/manuals/docker-hub/usage/_index.md). - -- Enhance your organization’s security posture for containerized development with [Hardened Desktop](/manuals/enterprise/security/hardened-desktop/_index.md). - -> [!NOTE] -> -> Docker Desktop automatically signs you out after 90 days, or after 30 days of inactivity. - -## Signing in with Docker Desktop for Linux - -Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in GPG-encrypted files. -Before signing in to Docker Desktop with your [Docker ID](/accounts/create-account/), you must initialize `pass`. -Docker Desktop displays a warning if `pass` is not configured. - -1. Generate a GPG key. You can initialize pass by using a gpg key. To generate a gpg key, run: - - ``` console - $ gpg --generate-key - ``` -2. Enter your name and email once prompted. - - Once confirmed, GPG creates a key pair. Look for the `pub` line that contains your GPG ID, for example: - - ```text - ... - pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30] - 3ABCD1234EF56G78 - uid Molly <molly@example.com> - ``` -3. Copy the GPG ID and use it to initialize `pass`. For example - - ```console - $ pass init 3ABCD1234EF56G78 - ``` - - You should see output similar to: - - ```text - mkdir: created directory '/home/molly/.password-store/' - Password store initialized for <generated_gpg-id_public_key> - ``` - -Once you initialize `pass`, you can sign in and pull your private images. -When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the GPG key generation. - -```console -$ docker pull molly/privateimage -Using default tag: latest -latest: Pulling from molly/privateimage -3b9cc81c3203: Pull complete -Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96 -Status: Downloaded newer image for molly/privateimage:latest -docker.io/molly/privateimage:latest -``` - -## What's next? - -- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and its features. -- Change your [Docker Desktop settings](/manuals/desktop/settings-and-maintenance/settings.md). -- [Browse common FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md). diff --git a/content/manuals/desktop/setup/vm-vdi.md b/content/manuals/desktop/setup/vm-vdi.md index bfc5f4c495c1..d443c385a06a 100644 --- a/content/manuals/desktop/setup/vm-vdi.md +++ b/content/manuals/desktop/setup/vm-vdi.md @@ -32,7 +32,7 @@ cloud-based resources as if they were local. When you run a container, Docker provisions a secure, isolated, and ephemeral cloud environment connected to Docker Desktop via an SSH tunnel. Despite running remotely, features like bind mounts and port forwarding continue to work seamlessly, providing a local-like -experience. To use Docker Offload: +experience. For more information, see the [Docker Offload product page](https://www.docker.com/products/docker-offload/) and the [Docker Offload @@ -42,9 +42,25 @@ documentation](/offload/). > [!NOTE] > -> Support for running Docker Desktop on a virtual desktop is available to Docker Business customers, on VMware ESXi or Azure VMs only. +> Support for running Docker Desktop on a virtual desktop is available to Docker Business customers only. -Docker support includes installing and running Docker Desktop within the VM, provided that nested virtualization is correctly enabled. The only hypervisors successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](/manuals/support/_index.md). +Docker support includes installing and running Docker Desktop within the VM, provided that nested virtualization is correctly enabled. + +| Platform | Support status | +| :--- | :--- | +| VMware ESXi | Supported. Tested by Docker. | +| Azure VM | Supported. Tested by Docker. | +| Nutanix-powered VDI | Supported, provided the underlying Windows environment supports WSL 2 or Windows container mode. | +| Any other hypervisor | Not supported. | + +For more information on Docker Desktop support, see [Get support](/manuals/support/_index.md). + +### Persistent and non-persistent environments + +Whichever platform you use, Docker Desktop support depends on the virtual desktop persisting between sessions: + +- Persistent VDI environments: supported. You receive the same virtual desktop instance across sessions, preserving installed software and configurations. +- Non-persistent VDI environments: not supported. Docker Desktop doesn't support environments where the OS resets between sessions, requiring re-installation or reconfiguration each time. For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMware ESXi. @@ -59,13 +75,13 @@ Docker does not support running multiple instances of Docker Desktop on the same ## Turn on nested virtualization You must turn on nested virtualization before you install Docker Desktop on a -virtual machine that will not use Docker Cloud. +virtual machine that will not use Docker Offload. ### Turn on nested virtualization on VMware ESXi Nested virtualization of other hypervisors like Hyper-V inside a vSphere VM [is not a supported scenario](https://kb.vmware.com/s/article/2009916). However, running Hyper-V VM in a VMware ESXi VM is technically possible and, depending on the version, ESXi includes hardware-assisted virtualization as a supported feature. A VM that had 1 CPU with 4 cores and 12GB of memory was used for internal testing. -For steps on how to expose hardware-assisted virtualization to the guest OS, [see VMware's documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/7-0/expose-hardware-assisted-virtualization.html). +For steps on how to expose hardware-assisted virtualization to the guest OS, [see VMware's documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration/configuring-virtual-machine-hardwarevsphere-vm-admin/configure-virtual-machine-cpu-resourcesvsphere-vm-admin.html#GUID-58028e27-5353-4bc0-9808-4ff3ca399e49-en_GUID-2A98801C-68E8-47AF-99ED-00C63E4857F6__GUID-CF3C6412-1260-4EE2-9997-4019A1D136FD). ### Turn on nested virtualization on an Azure Virtual Machine @@ -75,22 +91,8 @@ For Azure virtual machines, [check that the VM size chosen supports nested virtu ## Docker Desktop support on Nutanix-powered VDI -Docker Desktop can be used within Nutanix-powered VDI environments provided that the underlying Windows environment supports WSL 2 or Windows container mode. Since Nutanix officially supports WSL 2, Docker Desktop should function as expected, as long as WSL 2 operates correctly within the VDI environment. - If using Windows container mode, confirm that the Nutanix environment supports Hyper-V or alternative Windows container backends. -### Supported configurations - -Docker Desktop follows the VDI support definitions outlined [previously](#virtual-desktop-support-when-using-nested-virtualization): - -- Persistent VDI environments (Supported): You receive the same virtual desktop instance across sessions, preserving installed software and configurations. - -- Non-persistent VDI environments (Not supported): Docker Desktop does not support environments where the OS resets between sessions, requiring re-installation or reconfiguration each time. - -### Support scope and responsibilities +As with any virtual desktop, only persistent environments are supported. See [Persistent and non-persistent environments](#persistent-and-non-persistent-environments). For WSL 2-related issues, contact Nutanix support. For Docker Desktop-specific issues, contact Docker support. - -## Additional resources - -- [Docker Desktop on Microsoft Dev Box](/manuals/enterprise/enterprise-deployment/dev-box.md) diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/general.md b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md index 47bb67013ed5..d48c320f324d 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/general.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md @@ -96,7 +96,7 @@ Docker Desktop requires administrator privileges only for installation. Once ins {{< tabs >}} {{< tab name="Mac" >}} -To run Docker Desktop on Mac without requiring administrator privileges, install via the command line and pass the `—user=<userid>` installer flag: +To run Docker Desktop on Mac without requiring administrator privileges, install via the command line and pass the `--user=<userid>` installer flag: ```console $ /Applications/Docker.app/Contents/MacOS/install --user=<userid> @@ -115,13 +115,12 @@ You can then sign in to your machine with the user ID specified, and launch Dock > > If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](/manuals/desktop/features/wsl/best-practices.md) for WSL 2. Otherwise, update WSL 2 first. -To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `—always-run-service` installer flag. +To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `--always-run-service` installer flag. ```console -$ "Docker Desktop Installer.exe" install —always-run-service +$ "Docker Desktop Installer.exe" install --always-run-service ``` {{< /tab >}} {{< /tabs >}} - diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md index 55ca9f8d27d1..de6b694b9c47 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md @@ -39,60 +39,11 @@ Docker Desktop for Linux runs a Virtual Machine (VM) for the following reasons: ### How do I enable file sharing? Docker Desktop for Linux uses [VirtioFS](https://virtio-fs.gitlab.io/) as the -default (and currently only) mechanism to enable file sharing between the host -and Docker Desktop VM. - -{{< accordion title="Additional information for Docker Desktop version 4.34 and earlier" >}} - -In order not to require elevated privileges, without -unnecessarily restricting operations on the shared files, Docker Desktop runs -the file sharing service (`virtiofsd`) inside a user namespace (see -`user_namespaces(7)`) with UID and GID mapping configured. As a result Docker -Desktop relies on the host being configured to enable the current user to use -subordinate ID delegation. For this to be true `/etc/subuid` (see `subuid(5)`) -and `/etc/subgid` (see `subgid(5)`) must be present. Docker Desktop only -supports subordinate ID delegation configured via files. Docker Desktop maps the -current user ID and GID to 0 in the containers. It uses the first entry -corresponding to the current user in `/etc/subuid` and `/etc/subgid` to set up -mappings for IDs greater than 0 in the containers. - -| ID in container | ID on host | -| --------------- | -------------------------------------------------------------------------------- | -| 0 (root) | ID of the user running Docker Desktop (e.g. 1000) | -| 1 | 0 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100000) | -| 2 | 1 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100001) | -| 3 | 2 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100002) | -| ... | ... | - -If `/etc/subuid` and `/etc/subgid` are missing, they need to be created. -Both should contain entries in the form - -`<username>:<start of id range>:<id range size>`. For example, to allow the current user -to use IDs from 100 000 to 165 535: - -```console -$ grep "$USER" /etc/subuid >> /dev/null 2&>1 || (echo "$USER:100000:65536" | sudo tee -a /etc/subuid) -$ grep "$USER" /etc/subgid >> /dev/null 2&>1 || (echo "$USER:100000:65536" | sudo tee -a /etc/subgid) -``` - -To verify the configs have been created correctly, inspect their contents: - -```console -$ echo $USER -exampleuser -$ cat /etc/subuid -exampleuser:100000:65536 -$ cat /etc/subgid -exampleuser:100000:65536 -``` - -In this scenario if a shared file is `chown`ed inside a Docker Desktop container -owned by a user with a UID of 1000, it shows up on the host as owned by -a user with a UID of 100999. This has the unfortunate side effect of preventing -easy access to such a file on the host. The problem is resolved by creating -a group with the new GID and adding our user to it, or by setting a recursive -ACL (see `setfacl(1)`) for folders shared with the Docker Desktop VM. - -{{< /accordion >}} +default mechanism to enable file sharing between the host +and Docker Desktop VM. Synchronized file shares, a faster, +cache-based alternative for bind-mount-heavy workloads like PHP/JS +projects, is also available on Linux with a Pro, Team, or Business +subscription. For more details, see [File sharing](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing)/desktop/settings-and-maintenance/settings/#file-sharing. ### How do I use Docker SDKs with Docker Desktop for Linux? @@ -150,11 +101,12 @@ To move the disk image file to a different location: 3. Select **Apply** for the changes to take effect. -Do not move the file directly in Finder as this can cause Docker Desktop to lose track of the file. +Do not move the file directly using your file manager, as this can cause +Docker Desktop to lose track of the file. ##### How do I delete unnecessary containers and images? -Check whether you have any unnecessary containers and images. If your client and daemon API are running version 1.25 or later (use the `docker version` command on the client to check your client and daemon API versions), you can see the detailed space usage information by running: +Check whether you have any unnecessary containers and images. You can see the detailed space usage information by running: ```console $ docker system df -v @@ -197,7 +149,7 @@ To query the actual size of the file on the host from a terminal, run: ```console $ cd ~/.docker/desktop/vms/0/data $ ls -klsh Docker.raw -2333548 -rw-r--r--@ 1 username staff 64G Dec 13 17:42 Docker.raw +2333548 -rw-r--r--@ 1 username username 64G Dec 13 17:42 Docker.raw ``` In this example, the actual size of the disk is `2333548` KB, whereas the maximum size of the disk is `64` GB. diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md index 44641460daa4..4009fd5ae7eb 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md @@ -12,14 +12,18 @@ weight: 20 ### What is HyperKit? -HyperKit is a hypervisor built on top of the Hypervisor.framework in macOS. It runs entirely in userspace and has no other dependencies. +HyperKit is a legacy hypervisor built on top of Hypervisor.framework in macOS. +Previous versions of Docker Desktop for Mac used HyperKit to run the Linux VM. -Docker uses HyperKit to eliminate the need for other VM products, such as Oracle -VirtualBox or VMware Fusion. +Current versions of Docker Desktop use the Apple Virtualization framework by +default. HyperKit is retained here as historical context for older +configurations. ### What is the benefit of HyperKit? -HyperKit is thinner than VirtualBox and VMware fusion, and the version included is customized for Docker workloads on Mac. +When HyperKit was the default hypervisor, it provided a lightweight +virtualization layer customized for Docker workloads and eliminated the need +for third-party VM products such as Oracle VirtualBox or VMware Fusion. ### Where does Docker Desktop store Linux containers and images? @@ -55,7 +59,7 @@ To move the disk image file to a different location: ##### How do I delete unnecessary containers and images? -Check whether you have any unnecessary containers and images. If your client and daemon API are running version 1.25 or later (use the `docker version` command on the client to check your client and daemon API versions), you can see the detailed space usage information by running: +Check whether you have any unnecessary containers and images. You can see the detailed space usage information by running: ```console $ docker system df -v @@ -81,10 +85,7 @@ $ docker system prune This command removes all stopped containers, unused networks, dangling images, and build cache. -It might take a few minutes to reclaim space on the host depending on the format of the disk image file. If the file is named: - -- `Docker.raw`, space on the host is reclaimed within a few seconds. -- `Docker.qcow2`, space is freed by a background process after a few minutes. +It might take a few minutes to reclaim space on the host. Space is only freed when images are deleted. Space is not freed automatically when files are deleted inside running containers. To trigger a space reclamation at any point, run the command: @@ -162,8 +163,7 @@ You can put your client certificates in `~/.docker/certs.d/<MyRegistry>:<Port>/client.key`. When the Docker Desktop application starts, it copies the `~/.docker/certs.d` -folder on your Mac to the `/etc/docker/certs.d` directory on Moby (the Docker -Desktop `xhyve` virtual machine). +folder on your Mac to the `/etc/docker/certs.d` directory inside the Docker Desktop Linux VM. > [!NOTE] > diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/releases.md b/content/manuals/desktop/troubleshoot-and-support/faqs/releases.md index da2270f5bae1..503368a12c25 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/releases.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/releases.md @@ -1,23 +1,91 @@ --- -description: Frequently asked Docker Desktop questions for all platforms -keywords: desktop, mac, windows, faqs +description: Answers to common questions about Docker Desktop release frequency, + supported versions, installing older versions, and download errors +keywords: desktop, mac, windows, faqs, releases, support, install, 403, version, + older version, old version, previous version, downgrade title: FAQs on Docker Desktop releases linkTitle: Releases tags: [FAQ] --- -### How frequent will new releases be? +### How often will new releases be? -New releases are available every week, unless there are critical fixes that need to be released sooner. +New releases are available every week, unless there are critical fixes that +need to be released sooner. -The **Automatically check for updates** setting in the **Software updates** tab is turned on by default. This means you receive notifications in the Docker menu and a notification badge on the Docker Desktop Dashboard when a new version is available. +The **Automatically check for updates** setting in the **Software updates** +tab is turned on by default. This means you receive notifications in the +Docker menu and a notification badge on the Docker Desktop Dashboard when a +new version is available. -You can also let Docker Desktop automatically download new updates in the background by selecting the **Always download updates** checkbox. +On Mac and Windows, you can also let Docker Desktop automatically download +new updates in the background by selecting the **Always download updates** +checkbox. -Sometimes new versions are rolled out gradually over a few days. Therefore, if you wait, it will turn up soon. Alternatively, you can select **Check for updates** in the Docker menu to get the latest version immediately. +Sometimes new versions are rolled out gradually over a few days. Therefore, +if you wait, it will turn up soon. Alternatively, you can select **Check for +updates** in the Docker menu to get the latest version immediately. ### How do I ensure that all users in my organization are using the same version? -This is managed through your IT administrator's endpoint management software. +This is managed through your IT administrator's endpoint management software. +### Which Docker Desktop versions are supported? +> [!IMPORTANT] +> +> Docker Desktop versions older than six months from the latest release aren't +> available for download. Previous release notes are available in the +> [documentation repository](https://github.com/docker/docs/tree/main/content/manuals/desktop/previous-versions). + +Docker Support covers: + +- Docker Business: Versions up to six months older than the latest version. + Fixes apply to the latest version only. +- Docker Pro and Team: The latest version only. + +For details, see [Supported versions](/manuals/support/_index.md#supported-versions). + +Docker recommends running the latest Docker Desktop release. See the +[release notes](/manuals/desktop/release-notes.md) for the latest version and +download links. + +### How do I install an older version? + +Installers are limited to the +[six-month download window](#which-docker-desktop-versions-are-supported). +Choose a version that still includes **Download Docker Desktop** links in the +[release notes](/manuals/desktop/release-notes.md). + +The install commands don't take a version number. Choose the version by +downloading that release's installer, then run the install steps for your +operating system. + +1. Open the [release notes](/manuals/desktop/release-notes.md). +1. Go to the version you want. Under the version heading and date, look for + a **Download Docker Desktop** section with links for Windows, Mac, and + Linux. +1. If that section is missing, Docker doesn't provide an installer for that + entry from the docs. Choose another version that includes **Download Docker + Desktop**. +1. Download the installer for your platform. +1. If a newer version of Docker Desktop is already installed, + [uninstall](/manuals/desktop/uninstall.md) it before installing the older + version. +1. Install the version you downloaded: + + - [Install Docker Desktop on Windows](/manuals/desktop/setup/install/windows-install.md) + - [Install Docker Desktop on Mac](/manuals/desktop/setup/install/mac-install.md) + - [Install Docker Desktop on Linux](/manuals/desktop/setup/install/linux/_index.md) + +### Why do I get a 403 download error? + +A `403 Forbidden` response means the installer for that build isn't available +to download. This usually means the build is outside the +[six-month download window](#which-docker-desktop-versions-are-supported). +This applies on Windows, Mac, and Linux, whether you use a browser, a package +manager, or another download tool. The failure happens when fetching the +installer, not when running the install command. + +Download a version that includes a **Download Docker Desktop** section in the +[release notes](/manuals/desktop/release-notes.md). diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md index 8349042948bc..a7c6f7ce5b59 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md @@ -53,7 +53,7 @@ in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and When the Docker Desktop application starts, it copies the `~/.docker/certs.d` folder on your Windows system to the `/etc/docker/certs.d` -directory on Moby (the Docker Desktop virtual machine running on Hyper-V). +directory inside the Docker Desktop Linux VM. You need to restart Docker Desktop after making any changes to the keychain or to the `~/.docker/certs.d` directory in order for the changes to take effect. diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md index 65390501b3f6..59f72f0ffa9f 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md @@ -7,6 +7,7 @@ toc_max: 2 title: Troubleshoot Docker Desktop linkTitle: Troubleshoot and diagnose aliases: + - /docker-for-windows/troubleshoot/ - /desktop/troubleshoot/overview/ - /desktop/troubleshoot/ tags: [Troubleshooting] @@ -20,65 +21,61 @@ This page contains information on how to diagnose and troubleshoot Docker Deskto To navigate to **Troubleshoot** either: - Select the Docker menu Docker menu {{< inline-image src="../../images/whale-x.svg" alt="whale menu" >}} and then **Troubleshoot**. -- Select the **Troubleshoot** icon near the top-right corner of Docker Dashboard. +- Select the **question mark** icon near the top-right corner of the Docker Desktop Dashboard. -The **Troubleshooting** menu contains the following options: +The **Troubleshoot** menu contains the following options: -- **Restart Docker Desktop**. +- **Restart Docker Desktop** + +- **Support** - **Reset Kubernetes cluster**. Select to delete all stacks and Kubernetes resources. For more information, see [Kubernetes](/manuals/desktop/settings-and-maintenance/settings.md#kubernetes). -- **Clean / Purge data**. This option resets all Docker data without a - reset to factory defaults. Selecting this option results in the loss of existing settings. +- **Clean up data**. A disk image reset destroys all Docker containers and images local to the machine, preserving all settings. - **Reset to factory defaults**: Choose this option to reset all options on Docker Desktop to their initial state, the same as when Docker Desktop was first installed. -If you are a Mac or Linux user, you also have the option to **Uninstall** Docker Desktop from your system. +If you are a Mac user, you also have the option to **Uninstall** Docker Desktop from your system. ## Diagnose -> [!TIP] +> [!NOTE] > -> If you do not find a solution in troubleshooting, browse the GitHub repositories or create a new issue on the [Docker Desktop issue tracker](https://github.com/docker/desktop-feedback). +> Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected. ### Diagnose from the app 1. From **Troubleshoot**, select **Get support**. This opens the in-app Support page and starts collecting the diagnostics. - > [!NOTE] - > - > Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected. 2. When the diagnostics collection process is complete, select **Upload to get a Diagnostic ID**. 3. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID. 4. Use your diagnostics ID to get help: - - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. - > [!NOTE] - > - > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](/manuals/support/_index.md). - - If you don't have a paid Docker subscription, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied in step three. + - If you have a Docker subscription and are signed in, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. + - If you don't have a Docker subscription, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied in step three. ### Diagnose from an error message -1. When an error message appears, select **Gather diagnostics**. - > [!NOTE] - > - > Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected. +1. When an error message appears, select **Gather diagnostics**. Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected. 2. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID. 3. Use your diagnostics ID to get help: - - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. - > [!NOTE] - > - > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](/manuals/support/_index.md). - - If you don't have a paid Docker subscription, you can open a new [Docker Desktop issue on GitHub](https://github.com/docker/desktop-feedback). Complete the information required and ensure you add the diagnostic ID printed in step two. + - If you have a Docker subscription and are signed in, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. + - If you don't have a Docker subscription, you can open a new [Docker Desktop issue on GitHub](https://github.com/docker/desktop-feedback). Complete the information required and ensure you add the diagnostic ID printed in step two. ### Diagnose from the terminal -In some cases, it's useful to run the diagnostics yourself, for instance, if -Docker Desktop cannot start. +In some cases, it's useful to run the diagnostics yourself, for instance, if the Docker Desktop Dashboard cannot start. -> [!NOTE] -> -> Gathering diagnostics may take several minutes. Wait for the process to complete before closing the terminal. +Run the [`docker desktop diagnose`](/manuals/desktop/features/desktop-cli.md) command: + +```console +$ docker desktop diagnose +``` + +Gathering diagnostics may take several minutes. Wait for the process to complete before closing the terminal. + +After the diagnostics have finished, the terminal displays your diagnostics ID and the path to the diagnostics file. The diagnostics ID is composed of your user ID and a timestamp. For example `BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051`. + +Alternatively, you can use the `com.docker.diagnose` tool: {{< tabs group="os" >}} {{< tab name="Windows" >}} @@ -142,10 +139,6 @@ After the diagnostics have finished, the terminal displays your diagnostics ID a {{< /tab >}} {{< /tabs >}} -> [!TIP] -> -> You can also use the [`docker desktop diagnose` command](/manuals/desktop/features/desktop-cli.md) to diagnose Docker Desktop and upload the diagnostics ID. - To view the contents of the diagnostic file: {{< tabs group="os" >}} @@ -186,79 +179,20 @@ $ unzip –l /tmp/<your-diagnostics-ID>.zip #### Use your diagnostics ID to get help -If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. - -If you don't have a paid Docker subscription, create an issue on [GitHub](https://github.com/docker/desktop-feedback). - -### Self-diagnose tool +If you have a Docker subscription, [Contact support](https://app.docker.com/support/contact). Fill in the information required and add your diagnostics ID. -> [!IMPORTANT] -> -> This tool has been deprecated. +If you don't have a Docker subscription, create an issue on [GitHub](https://github.com/docker/desktop-feedback). ## Check the logs In addition to using the diagnose option to submit logs, you can browse the logs yourself. -{{< tabs group="os" >}} -{{< tab name="Windows" >}} - -In PowerShell, run: - -```powershell -$ code $Env:LOCALAPPDATA\Docker\log -``` - -This opens up all the logs in your preferred text editor for you to explore. - -{{< /tab >}} -{{< tab name="Mac" >}} - -### From terminal - -To watch the live flow of Docker Desktop logs in the command line, run the following script from your preferred shell. - -```console -$ pred='process matches ".*(ocker|vpnkit).*" || (process in {"taskgated-helper", "launchservicesd", "kernel"} && eventMessage contains[c] "docker")' -$ /usr/bin/log stream --style syslog --level=debug --color=always --predicate "$pred" -``` - -Alternatively, to collect the last day of logs (`1d`) in a file, run: - -```console -$ /usr/bin/log show --debug --info --style syslog --last 1d --predicate "$pred" >/tmp/logs.txt -``` - -### From the Console app - -Mac provides a built-in log viewer, named **Console**, which you can use to check -Docker logs. - -The Console lives in `/Applications/Utilities`. You can search for it with -Spotlight Search. - -To read the Docker app log messages, type `docker` in the Console window search bar and press Enter. Then select `ANY` to expand the drop-down list next to your `docker` search entry, and select `Process`. - -![Mac Console search for Docker app](../../images/console.png) - -You can use the Console Log Query to search logs, filter the results in various -ways, and create reports. - -{{< /tab >}} -{{< tab name="Linux" >}} - -You can access Docker Desktop logs by running the following command: +To access Docker Desktop logs, run: ```console -$ journalctl --user --unit=docker-desktop +$ docker desktop diagnose ``` -You can also find the logs for the internal components included in Docker -Desktop at `$HOME/.docker/desktop/log/`. - -{{< /tab >}} -{{< /tabs >}} - ## View the Docker daemon logs Refer to the [Read the daemon logs](/manuals/engine/daemon/logs.md) section @@ -267,6 +201,4 @@ to learn how to view the Docker Daemon logs. ## Further resources - View specific [troubleshoot topics](topics.md). -- View information on [known issues](known-issues.md) -- [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) - Resolve macOS installation issues - [Get support for Docker products](/manuals/support/_index.md) diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md deleted file mode 100644 index 91235e55c0d3..000000000000 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -description: Find known issues for Docker Desktop -keywords: mac, troubleshooting, known issues, Docker Desktop -title: Known issues -tags: [ Troubleshooting ] -weight: 20 -aliases: - - /desktop/troubleshoot/known-issues/ ---- - -{{< tabs >}} -{{< tab name="For Mac with Intel chip" >}} -- The Mac Activity Monitor reports that Docker is using twice the amount of memory it's actually using. This is due to a [bug in macOS](https://docs.google.com/document/d/17ZiQC1Tp9iH320K-uqVLyiJmk4DHJ3c4zgQetJiKYQM/edit?usp=sharing). - -- **"Docker.app is damaged" dialog**: If you see a "Docker.app is damaged and can't be opened" dialog during installation or updates, this is typically caused by non-atomic copy operations when other applications are using the Docker CLI. See [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) for resolution steps. - -- Force-ejecting the `.dmg` after running `Docker.app` from it can cause the - whale icon to become unresponsive, Docker tasks to show as not responding in the Activity Monitor, and for some processes to consume a large amount of CPU resources. Reboot and restart Docker to resolve these issues. - -- Docker Desktop uses the `HyperKit` hypervisor - (https://github.com/docker/hyperkit) in macOS 10.10 Yosemite and higher. If - you are developing with tools that have conflicts with `HyperKit`, such as - [Intel Hardware Accelerated Execution Manager - (HAXM)](https://software.intel.com/en-us/android/articles/intel-hardware-accelerated-execution-manager/), - the current workaround is not to run them at the same time. You can pause - `HyperKit` by quitting Docker Desktop temporarily while you work with HAXM. - This allows you to continue work with the other tools and prevent `HyperKit` - from interfering. - -- If you are working with applications like [Apache - Maven](https://maven.apache.org/) that expect settings for `DOCKER_HOST` and - `DOCKER_CERT_PATH` environment variables, specify these to connect to Docker - instances through Unix sockets. For example: - - ```console - $ export DOCKER_HOST=unix:///var/run/docker.sock - ``` - -{{< /tab >}} -{{< tab name="For Mac with Apple silicon" >}} - -- Some command line tools do not work when Rosetta 2 is not installed. - - The old version 1.x of `docker-compose`. Use Compose V2 instead - type `docker compose`. - - The `docker-credential-ecr-login` credential helper. -- Some images do not support the ARM64 architecture. You can add `--platform linux/amd64` to run (or build) an Intel image using emulation. - - However, attempts to run Intel-based containers on Apple silicon machines under emulation can crash as QEMU sometimes fails to run the container. In addition, filesystem change notification APIs (`inotify`) do not work under QEMU emulation. Even when the containers do run correctly under emulation, they will be slower and use more memory than the native equivalent. - - In summary, running Intel-based containers on Arm-based machines should be regarded as "best effort" only. We recommend running `arm64` containers on Apple silicon machines whenever possible, and encouraging container authors to produce `arm64`, or multi-arch, versions of their containers. This issue should become less common over time, as more and more images are rebuilt [supporting multiple architectures](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/). -- Users may occasionally experience data drop when a TCP stream is half-closed. - -{{< /tab >}} -{{< /tabs >}} diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md deleted file mode 100644 index 68586e882401..000000000000 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -description: Fix "Docker.app is damaged and can't be opened. You should move it to the Trash" dialog on macOS -keywords: docker desktop mac, damaged app, move to trash, gatekeeper, installation issues, troubleshooting -title: Fix "Docker.app is damaged and can't be opened" on macOS -linkTitle: MacOS app damaged dialog -tags: [Troubleshooting] -weight: 30 ---- - -## Error message - -macOS shows the following dialog when you try to open Docker Desktop: - -```text -Docker.app is damaged and can't be opened. You should move it to the Trash. -``` - -This error prevents Docker Desktop from launching and can occur during installation or after updates. - -## Possible cause - -This issue occurs due to a non-atomic copy during a drag/drop installation. When you drag and drop `Docker.app` from a DMG file while another application, like VS Code, is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged". - -## Solution - -Follow these steps to resolve the issue: - -### Step one: Quit third-party software - -Close any applications that might call Docker in the background: - -- Visual Studio Code and other IDEs -- Terminal applications -- Agent apps or development tools -- Any scripts or processes that use the Docker CLI - -### Step two: Remove any partial installation - -1. Move `/Applications/Docker.app` to Trash and empty Trash. -2. If you used a DMG installer, eject and re-mount the Docker DMG. - -### Step three: Reinstall Docker Desktop - -Follow the instructions in the [macOS installation guide](/manuals/desktop/setup/install/mac-install.md) to reinstall Docker Desktop. - -### If the dialog persists - -If you continue to see the "damaged" dialog after following the recovery steps: - -1. Gather diagnostics using the terminal. Follow the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal). - - - Note down the your diagnostics ID displayed in the terminal after running diagnostics. - -2. Get help: - - If you have a paid Docker subscription, [contact support](/manuals/support/_index.md) and include your diagnostics ID - - For community users, [open an issue on GitHub](https://github.com/docker/desktop-feedback) and include your diagnostics ID - -## Prevention - -To avoid this issue in the future: - -- If your organization allows, update Docker Desktop via the in-app update flow -- Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach -- In managed environments, use PKG installations over DMG drag-and-drop -- Keep installer volumes mounted until installation is complete - -## Related information - -- [Install Docker Desktop on Mac](/manuals/desktop/setup/install/mac-install.md) -- [PKG installer documentation](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) -- [Troubleshoot Docker Desktop](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) -- [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md index 0e37f9d33ec9..02bae3f03c81 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md @@ -1,6 +1,6 @@ --- description: Explore common troubleshooting topics for Docker Desktop -keywords: Linux, Mac, Windows, troubleshooting, topics, Docker Desktop +keywords: Linux, Mac, Windows, troubleshooting, topics, Docker Desktop, known issues title: Troubleshoot topics for Docker Desktop linkTitle: Common topics toc_max: 3 @@ -8,6 +8,9 @@ tags: [ Troubleshooting ] weight: 10 aliases: - /desktop/troubleshoot/topics/ + - /desktop/troubleshoot/known-issues/ + - /desktop/troubleshoot-and-support/troubleshoot/known-issues/ + - /desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog/ --- > [!TIP] @@ -60,13 +63,13 @@ Disable hardware acceleration: - Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` - Linux: `~/.docker/desktop/settings-store.json.` -2. Add the following entry: +1. Add the following entry: ```JSON - $ "disableHardwareAcceleration": true + "disableHardwareAcceleration": "always" ``` -3. Save the file and restart Docker Desktop. +1. Save the file and restart Docker Desktop. ### Using mounted volumes and getting runtime errors indicating an application file is not found, access to a volume mount is denied, or a service cannot start @@ -79,12 +82,12 @@ If your project directory is located outside your home directory (`/home/<user>` Enable file sharing in Docker Desktop for Mac and Linux: 1. Navigate to **Settings**, select **Resources** and then **File sharing**. -2. Add the drive or folder that contains the Dockerfile and volume mount paths. +1. Add the drive or folder that contains the Dockerfile and volume mount paths. Enable file sharing in Docker Desktop for Windows: 1. From **Settings**, select **Shared Folders**. -2. Share the folder that contains the Dockerfile and volume mount paths. +1. Share the folder that contains the Dockerfile and volume mount paths. ### `port already allocated` errors @@ -117,45 +120,13 @@ currently using the port (the PID is the number in the rightmost column). Then, decide whether to shut the other process down, or to use a different port in your Docker app. -## Topics for Linux and Mac - -### Docker Desktop fails to start on Mac or Linux platforms - -#### Error message - -Docker fails to start due to Unix domain socket path length limitations: - -```console -[vpnkit-bridge][F] listen unix <HOME>/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument -``` - -```console -[com.docker.backend][E] listen(vsock:4099) failed: listen unix <HOME>/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument -``` - -#### Cause - -On Mac and Linux, Docker Desktop creates Unix domain sockets used for inter-process communication. These sockets are created under the user's home directory. - -Unix domain sockets have a maximum path length: - - 104 characters on Mac - - 108 characters on Linux - -If your home directory path is too long, Docker Desktop fails to create necessary sockets. - -#### Solution - -Ensure your username is short enough to keep paths within the allowed limit: - - Mac: Username should be ≤ 33 characters - - Linux: Username should be ≤ 55 characters - ## Topics for Mac ### Upgrade requires administrator privileges #### Cause -On macOS, users without administrator privileges cannot perform in-app upgrades from the Docker Desktop Dashboard. +On Mac, users without administrator privileges cannot perform in-app upgrades from the Docker Desktop Dashboard. #### Solution @@ -166,7 +137,7 @@ On macOS, users without administrator privileges cannot perform in-app upgrades To upgrade Docker Desktop: - Ask an administrator to install the newer version over the existing one. -- Use the []`--user` install flag](/manuals/desktop/setup/install/mac-install.md#security-and-access) if appropriate for your setup. +- Use the [`--user` install flag](/manuals/desktop/setup/install/mac-install.md#security-and-access) if appropriate for your setup. ### Persistent notification telling me an application has changed my Desktop configurations @@ -215,6 +186,70 @@ See also, [Hypervisor Framework Reference](https://developer.apple.com/library/mac/documentation/DriversKernelHardware/Reference/Hypervisor/) in the Apple documentation, and Docker Desktop [Mac system requirements](/manuals/desktop/setup/install/mac-install.md#system-requirements). +### Docker.app is damaged and can't be opened + +#### Cause + +This issue occurs due to a non-atomic copy during a drag/drop installation. When you drag and drop `Docker.app` from a DMG file while another application, like VS Code, is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged". + +#### Solution + +1. Quit third-party software + + Close any applications that might call Docker in the background: + + - Visual Studio Code and other IDEs + - Terminal applications + - Agent apps or development tools + - Any scripts or processes that use the Docker CLI + +1. Remove any partial installation: + + 1. Move `/Applications/Docker.app` to Trash and empty Trash. + 2. If you used a DMG installer, eject and re-mount the Docker DMG. + +1. Reinstall Docker Desktop + + Follow the instructions in the [Mac installation guide](/manuals/desktop/setup/install/mac-install.md) to reinstall Docker Desktop. + +If you continue to see the "damaged" dialog after following the recovery steps: + + 1. Gather diagnostics using the terminal. Follow the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal). + + - Note down the your diagnostics ID displayed in the terminal after running diagnostics. + + 1. Get help: + - If you have a paid Docker subscription, [contact support](/manuals/support/_index.md) and include your diagnostics ID + - For community users, [open an issue on GitHub](https://github.com/docker/desktop-feedback) and include your diagnostics ID + +To avoid this issue in the future: + +- If your organization allows, update Docker Desktop via the in-app update flow +- Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach +- In managed environments, use PKG installations over DMG drag-and-drop +- Keep installer volumes mounted until installation is complete + +### Containers can't reach devices on my local network + +Containers can reach the internet, but not other devices on your local network +(LAN), such as a NAS, a printer, or another computer at a `192.168.x.x` +address. The device itself can reach them. + +#### Cause + +Docker Desktop doesn't have the Mac **Local Network** permission. Mac then +blocks container traffic to devices on your local network, including your +router, while traffic to the internet still works. + +#### Solution + +To give Docker Desktop the Local Network permission: + +1. On your device, open **System Settings** > **Privacy & Security** > **Local Network**. +2. Turn on **Docker**. + +The change applies immediately, without needing to restart Docker Desktop. + ## Topics for Windows ### Docker Desktop fails to start when anti-virus software is installed @@ -231,6 +266,15 @@ manifests as an error response from the Docker daemon and a Docker Desktop start For a temporary workaround, uninstall the anti-virus software, or add Docker to the exclusions/exceptions in your antivirus software. +Some anti-virus software, such as Avast, also has its own hardware-assisted +virtualization or hardened mode that claims exclusive access to +Hyper-V, which blocks Docker Desktop and WSL from using it. If your Docker +Desktop start failure includes an error such as +`Wsl/Service/RegisterDistro/CreateVm/HCS/ERROR_NOT_SUPPORTED`, disable this +feature in your anti-virus software. For example, in Avast, go to **Menu** > +**Settings** > **Troubleshooting** and clear **Enable hardware-assisted +virtualization**. + ### Permissions errors on data directories for shared volumes #### Cause @@ -342,7 +386,8 @@ Portability of the scripts is not affected as Linux treats multiple `/` as a sin #### Error message A typical error message is "Docker Desktop - Unexpected WSL error" mentioning the error code -`Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands +`Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED` or +`Wsl/Service/RegisterDistro/CreateVm/HCS/ERROR_NOT_SUPPORTED`. Manually executing `wsl` commands also fails with the same error code. #### Cause @@ -359,10 +404,10 @@ Your machine must have the following features for Docker Desktop to function cor ##### WSL 2 and Windows Home 1. Virtual Machine Platform -2. [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) -3. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) +1. [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +1. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) Note that many Windows devices already have virtualization enabled, so this may not apply. -4. Hypervisor enabled at Windows startup +1. Hypervisor enabled at Windows startup ![WSL 2 enabled](../../images/wsl2-enabled.png) @@ -387,9 +432,9 @@ On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following fea 1. [Hyper-V](https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-technology-overview) installed and working -2. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) +1. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) Note that many Windows devices already have virtualization enabled, so this may not apply. -3. Hypervisor enabled at Windows startup +1. Hypervisor enabled at Windows startup ![Hyper-V on Windows features](../../images/hyperv-enabled.png) @@ -424,8 +469,8 @@ but not launched during Windows startup. Some tools (such as older versions of Virtual Box) and video game installers turn off hypervisor on boot. To turn it back on: 1. Open an administrative console prompt. -2. Run `bcdedit /set hypervisorlaunchtype auto`. -3. Restart Windows. +1. Run `bcdedit /set hypervisorlaunchtype auto`. +1. Restart Windows. You can also refer to the [Microsoft TechNet article](https://social.technet.microsoft.com/Forums/en-US/ee5b1d6b-09e2-49f3-a52c-820aafc316f9/hyperv-doesnt-work-after-upgrade-to-windows-10-1809?forum=win10itprovirt) on Code flow guard (CFG) settings. @@ -490,6 +535,6 @@ The user is not part of the `docker-users` group, which is required for permissi If your admin account is different to your user account, add it: 1. Run **Computer Management** as an administrator. -2. Navigate to **Local Users and Groups** > **Groups** > **docker-users**. -3. Right-click to add the user to the group. -4. Sign out and sign back in for the changes to take effect +1. Navigate to **Local Users and Groups** > **Groups** > **docker-users**. +1. Right-click to add the user to the group. +1. Sign out and sign back in for the changes to take effect diff --git a/content/manuals/desktop/use-desktop/_index.md b/content/manuals/desktop/use-desktop/_index.md index 1697050bc81b..3495f7a6243c 100644 --- a/content/manuals/desktop/use-desktop/_index.md +++ b/content/manuals/desktop/use-desktop/_index.md @@ -8,79 +8,47 @@ aliases: - /desktop/dashboard/ --- -When you open Docker Desktop, the Docker Desktop Dashboard displays. +When you open Docker Desktop, the Docker Desktop Dashboard is the first thing you see. It provides a centralized interface to manage your [containers](container.md), [images](images.md), [volumes](volumes.md), [builds](builds.md), [Kubernetes resources](kubernetes.md), and [logs](logs.md). -In addition, the Docker Desktop Dashboard lets you: - -- Use [Gordon](/manuals/ai/gordon/_index.md), a personal AI assistant embedded in Docker Desktop and the Docker CLI. It's designed to streamline your workflow and help you make the most of the Docker ecosystem. -- Navigate to the **Settings** menu to configure your Docker Desktop settings. Select the **Settings** icon in the Dashboard header. -- Access the **Troubleshoot** menu to debug and perform restart operations. Select the **Troubleshoot** icon in the Dashboard header. -- Be notified of new releases, installation progress updates, and more in the **Notifications center**. Select the bell icon in the bottom-right corner of the Docker Desktop Dashboard to access the notification center. -- Access the **Learning center** from the Dashboard header. It helps you get started with quick in-app walkthroughs and provides other resources for learning about Docker. - - For a more detailed guide about getting started, see [Get started](/get-started/introduction/_index.md). -- Access [Docker Hub](/manuals/docker-hub/_index.md) to search, browse, pull, run, or view details - of images. -- Navigate to [Docker Extensions](/manuals/extensions/_index.md) if you have enabled it. +The Dashboard also gives you quick access to AI tooling, extensions, settings, and help, so you rarely need to leave Docker Desktop. Use Quick search in the header any time to jump straight to a container, image, extension, volume, or doc. > [!TIP] > > You can customize the left-hand navigation to show only the tabs that matter to you, and hide the ones that don’t. Right-click the left-hand navigation, select **Customize**, and then select, deselect, or re-order the tabs. -## Docker terminal - -From the Docker Dashboard footer, you can use the integrated terminal directly within Docker Desktop. - -The integrated terminal: - -- Persists your session if you navigate to another - part of the Docker Desktop Dashboard and then return. -- Supports copy, paste, search, and clearing your session. - -#### Open the integrated terminal +## Sign in -To open the integrated terminal, either: +Docker recommends signing in with the **Sign in** option in the top-right corner of the Dashboard. Signing in lets you: -- Hover over your running container and under the **Actions** column, select the **Show container actions** - menu. From the drop-down menu, select **Open in terminal**. -- Or, select the **Terminal** icon located in the bottom-right corner, next to the version number. +- Access your Docker Hub repositories directly from Docker Desktop. +- Increase your pull rate limit compared to anonymous users. See [Usage and limits](/manuals/docker-hub/usage/_index.md). +- Enhance your organization's security posture for containerized development with [Hardened Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md). -To use your external terminal, navigate to the **General** tab in **Settings** -and select the **System default** option under **Choose your terminal**. +Docker Desktop automatically signs you out after 90 days, or after 30 days of inactivity. -## Quick search +In large enterprises where admin access is restricted, administrators can [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). -Use Quick Search, which is located in the Docker Dashboard header, to search for: - -- Any container or Compose application on your local system. You can see an overview of associated environment variables or perform quick actions, such as start, stop, or delete. - -- Public Docker Hub images, local images, and images from remote repositories (private repositories from organizations you're a part of in Hub). Depending on the type of image you select, you can either pull the image by tag, view documentation, go to Docker Hub for more details, or run a new container using the image. - -- Extensions. From here, you can learn more about the extension and install it with a single click. Or, if you already have an extension installed, you can open it straight from the search results. +> [!TIP] +> +> Explore [Docker's core subscriptions](https://www.docker.com/pricing?ref=Docs&refAction=DocsDesktopSignIn) to see what else Docker can offer you. -- Any volume. From here you can view the associated container. +## Use AI features -- Docs. Find help from Docker's official documentation straight from Docker Desktop. +- [Gordon](/manuals/ai/gordon/_index.md): A personal AI assistant built into Docker Desktop and the Docker CLI, designed to streamline your workflow and help you get more out of the Docker ecosystem. +- [Docker Model Runner](/manuals/ai/model-runner/_index.md): Manage, run, and deploy AI models using Docker. +- [Docker MCP Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md): A management interface integrated into Docker Desktop that lets you set up, manage, and run containerized MCP servers in profiles and connect them to AI agents. -## The Docker menu +### Extend Docker Desktop -Docker Desktop also includes a tray icon, referred to as the Docker menu {{< inline-image src="../../assets/images/whale-x.svg" alt="whale menu" >}} for quick access. +- [Docker Offload](/manuals/offload/_index.md): Run builds and containers in the cloud when local resources aren't enough. +- [Docker Hub](/manuals/docker-hub/_index.md): Search, browse, pull, run, or view details for images. +- [Docker Extensions](/manuals/extensions/_index.md): Add third-party tools directly into Docker Desktop. -Select the {{< inline-image src="../../assets/images/whale-x.svg" alt="whale menu" >}} icon in your taskbar to open options such as: +### Configure, troubleshoot, and stay updated -- **Dashboard**. This takes you to the Docker Desktop Dashboard. -- **Sign in/Sign up** -- **Settings** -- **Check for updates** -- **Troubleshoot** -- **Give feedback** -- **Switch to Windows containers** (if you're on Windows) -- **About Docker Desktop**. Contains information on the versions you are running, and links to the Subscription Service Agreement for example. -- **Docker Hub** -- **Documentation** -- **Extensions** -- **Kubernetes** -- **Restart** -- **Quit Docker Desktop** +- **Settings**: Select the Settings icon in the Dashboard header to configure Docker Desktop. +- **Troubleshoot**: Select the Troubleshoot icon in the Dashboard header to debug issues or restart Docker Desktop. +- **Notifications center**: Select the bell icon in the bottom-right corner to see new releases, installation progress, and other updates. +- Learning center: Open it from the Dashboard header for in-app walkthroughs and other learning resources. diff --git a/content/manuals/desktop/use-desktop/builds.md b/content/manuals/desktop/use-desktop/builds.md index 5a47b1332bb4..114549b725cf 100644 --- a/content/manuals/desktop/use-desktop/builds.md +++ b/content/manuals/desktop/use-desktop/builds.md @@ -27,6 +27,8 @@ Open the **Builds** view from the Docker Dashboard to access: Only builds from active, running builders are listed. Builds from removed or stopped builders are not shown. +If Gordon is available, build history rows can offer AI-suggested questions, such as "Why did this build fail?" + ### Builder settings The top-right corner shows the name of your currently selected builder, and the diff --git a/content/manuals/desktop/use-desktop/container.md b/content/manuals/desktop/use-desktop/container.md index 1017939ebce5..e82b577a048e 100644 --- a/content/manuals/desktop/use-desktop/container.md +++ b/content/manuals/desktop/use-desktop/container.md @@ -8,6 +8,18 @@ weight: 10 The **Containers** view lists all running and stopped containers and applications. It provides a clean interface to manage the lifecycle of your containers, interact with running applications, and inspect Docker objects—including Docker Compose apps. +## Toolbar and grid + +Use the **Search** field to find a specific container or Compose project by name. + +The toolbar also lets you: + +- Toggle **Only show running containers** to hide stopped containers from the grid. +- Customize the grid using the **Columns** button. You can show, hide, or reorder columns, including live stats like CPU %, memory usage/limit, memory %, disk read/write, network I/O, PIDs, and last-started time. Column choices persist between sessions. +- Select multiple containers or Compose projects using the row checkboxes, then use the bulk actions toolbar to start, pause, stop, or delete everything selected at once. + +Compose apps are grouped in the grid with an expand/collapse control. Selecting a project's checkbox selects or deselects all of its containers together. + ## Container actions Use the **Search** field to find a specific container by name. @@ -16,11 +28,15 @@ From the **Containers** view you can: - Start, stop, pause, resume, or restart containers - View image packages and CVEs - Delete containers -- Open the application in VS code +- Open a terminal in the container - Open the port exposed by the container in a browser - Copy the `docker run` command for reuse or modification - Use [Docker Debug](#execdebug) +From a Compose project's row, you get a similar set of actions scoped to the whole project: start/stop, pause, restart, view details, delete, and if [VS Code](https://code.visualstudio.com/) is set as your default editor, **Open in VS Code**. + +If [Gordon](/manuals/ai/gordon/_index.md) is available, each row can surface AI-suggested diagnostic questions and flag detected issues, such as "Container exited with an error" or "Container keeps restarting." + ## Resource usage From the **Containers** view you can monitor your containers' CPU and memory usage over time. This can help you understand if something is wrong with your containers or if you need to allocate additional resources. @@ -89,7 +105,7 @@ default** option. ### Files -Select **Files** to explore the filesystem of running or stopped containers. You +Select **Files** to explore the filesystem of running containers. You can also: - See which files have been recently added, modified, or deleted diff --git a/content/manuals/desktop/use-desktop/images.md b/content/manuals/desktop/use-desktop/images.md index b99038c6d25f..356d632e2d0e 100644 --- a/content/manuals/desktop/use-desktop/images.md +++ b/content/manuals/desktop/use-desktop/images.md @@ -7,33 +7,36 @@ weight: 20 --- -The **Images** view displays a list of your Docker images and allows you to run an image as a container, pull the latest version of an image from Docker Hub, and inspect images. It also displays a summary of image vulnerabilities. In addition, the **Images** view contains clean-up options to remove unwanted images from the disk to reclaim space. If you are logged in, you can also see the images you and your organization have shared on Docker Hub. For more information, see [Explore your images](images.md). +The **Images** view displays a list of your Docker images and allows you to run an image as a container, pull the latest version of an image from Docker Hub, and inspect images. It also displays a summary of image vulnerabilities. In addition, the **Images** view contains clean-up options to remove unwanted images from the disk to reclaim space. If you are signed in, you can also see the images you and your organization have shared on Docker Hub. -The **Images** view lets you manage Docker images without having to use the CLI. By default, it displays a list of all Docker images on your local disk. +By default, the **Images** view displays a list of all Docker images on your local disk. You can view Docker Hub images once you've signed in to Docker Hub. -You can also view Hub images once you have signed in to Docker Hub. This allows you to collaborate with your team and manage your images directly through Docker Desktop. +## Manage your images + +Use the **Search** field to search for any specific image. -The **Images** view lets you perform core operations such as running an image as a container, pulling the latest version of an image from Docker Hub, pushing the image to Docker Hub, and inspecting images. +You can sort images by: + +- In use +- Unused +- Dangling + +An unused image is an image that isn't used by any running or stopped container. An image becomes dangling when you build a new version of the image with the same tag. + +Select the **Columns** icon to choose which columns are displayed, and toggle each one on or off according to your preference. By default, the grid shows: -It also displays metadata about the image such as the: - Tag - Image ID - Date created - Size of the image. -An **In Use** tag displays next to images used by running and stopped containers. You can choose what information you want displayed by selecting the **More options** menu to the right of the search bar, and then use the toggle switches according to your preferences. +A status icon next to each image indicates whether it's **In use** or **Unused**. Hover over an image's name, tag, or ID to reveal a copy-to-clipboard button. An architecture warning chip (for example, `amd64`) appears next to an image's name when it's running under emulation, which can cause poor performance or failures. -The **Images on disk** status bar displays the number of images and the total disk space used by the images and when this information was last refreshed. +Above the grid, a header shows the total number of images, the disk space they use, and when this information was last refreshed. -## Manage your images +Select the checkbox on one or more images to select them, then use the bulk **Delete** action to remove them all at once. While images are selected, the toolbar shows how much disk space you'd reclaim by deleting them. -Use the **Search** field to search for any specific image. - -You can sort images by: - -- In use -- Unused -- Dangling +If Gordon is available, each image row can surface AI-suggested diagnostic questions and flag issues, such as an image being dangling, unused, or unusually large. ## Run an image as a container @@ -46,9 +49,9 @@ When prompted you can either: ## Inspect an image -To inspect an image, select the image row. Inspecting an image displays detailed information about the image such as the: +To inspect an image, select the image row, or select **View packages and CVEs** from its actions menu. The image's detail page shows information such as: -- Image history +- Image history (with a copy button) - Image ID - Date the image was created - Size of the image @@ -57,8 +60,7 @@ To inspect an image, select the image row. Inspecting an image displays detailed - Vulnerabilities found - Packages inside the image -[Docker Scout](/manuals/scout/_index.md) powers this vulnerability information. -For more information about this view, see [Image details view](/manuals/scout/explore/image-details-view.md) +From an image's row, you can also select **View container usage** to jump to the Containers view, filtered to containers using that image. ## Pull the latest image from Docker Hub @@ -78,29 +80,26 @@ Select the image from the list, select the **More options** button and select ** ## Remove an image +To remove an individual image, select the bin icon on its row. To remove several at once, select their checkboxes and use the bulk **Delete** action. + > [!NOTE] > > To remove an image used by a running or a stopped container, you must first remove the associated container. -An unused image is an image which is not used by any running or stopped containers. An image becomes dangling when you build a new version of the image with the same tag. - -To remove individual images, select the bin icon. - ## Docker Hub repositories The **Images** view also allows you to manage and interact with images in Docker Hub repositories. By default, when you go to **Images** in Docker Desktop, you see a list of images that exist in your local image store. -The **Local** and **Docker Hub repositories** tabs near the top toggles between viewing images in your local image store, +The **Local** and **My Hub** tabs near the top toggles between viewing images in your local image store, and images in remote Docker Hub repositories that you have access to. -Switching to the **Docker Hub repositories** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. +Switching to the **My Hub** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. When signed in, it shows you a list of images in Docker Hub organizations and repositories that you have access to. Select an organization from the drop-down to view a list of repositories for that organization. If you have enabled [Docker Scout](../../scout/_index.md) on the repositories, -image analysis results (and [health scores](/manuals/scout/policy/scores.md) if -your Docker organization is eligible) appear next to the image tags. +image analysis results appear next to the image tags. Hovering over an image tag reveals two options: diff --git a/content/manuals/desktop/use-desktop/kubernetes.md b/content/manuals/desktop/use-desktop/kubernetes.md index c5429aebc88d..a20390c8b817 100644 --- a/content/manuals/desktop/use-desktop/kubernetes.md +++ b/content/manuals/desktop/use-desktop/kubernetes.md @@ -15,8 +15,6 @@ The Kubernetes server runs as a single or multi-node cluster, within Docker cont ## Enable Kubernetes -With Docker Desktop version 4.51 and later, you can manage Kubernetes directly from the **Kubernetes** view in the Docker Desktop Dashboard. - 1. Open the Docker Desktop Dashboard and select the **Kubernetes** view. 2. Select **Create cluster**. 3. Choose your cluster type: @@ -53,7 +51,7 @@ Docker Desktop Kubernetes can be provisioned with either the `kubeadm` or `kind` provisioners. `kubeadm` is the older provisioner. It supports a single-node cluster, you can't select the kubernetes -version, it's slower to provision than `kind`, and it's not supported by [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/index.md) (ECI), +version, it's slower to provision than `kind`, and it's not supported by [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/index.md) (ECI), meaning that if ECI is enabled the cluster works but it's not protected by ECI. `kind` is the newer provisioner. It supports multi-node clusters (for @@ -151,12 +149,12 @@ factors, including the version of Kubernetes being used. The tags vary for each > [!NOTE] > -> In Docker Desktop versions 4.44 or later you can run `docker desktop kubernetes images list` to list Kubernetes images used by the currently installed version of Docker Desktop. +> You can run `docker desktop kubernetes images list` to list Kubernetes images used by the currently installed version of Docker Desktop. > For more information, see the [Docker Desktop CLI](/reference/cli/docker/desktop/kubernetes/images). To accommodate scenarios where access to Docker Hub is not allowed, admins can configure Docker Desktop to pull the above listed images from a different registry (e.g., a mirror) -using the [KubernetesImagesRepository](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#kubernetes) setting as follows. +using the [KubernetesImagesRepository](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#kubernetes) setting as follows. An image name can be broken into `[registry[:port]/][namespace/]repository[:tag]` components. The `KubernetesImagesRepository` setting allows users to override the `[registry[:port]/][namespace]` @@ -180,7 +178,7 @@ The recommended approach to set this up is the following: 1. Start Kubernetes using the desired cluster provisioning method: `kubeadm` or `kind`. 2. After Kubernetes has started, use either: - - (Docker Desktop version 4.44 or later) `docker desktop kubernetes images list` to list the image tags that will be pulled by the current Docker Desktop installation + - `docker desktop kubernetes images list` to list the image tags that will be pulled by the current Docker Desktop installation - `docker ps` to view the container images used by Docker Desktop for the Kubernetes control plane 3. Clone or mirror those images (with matching tags) to your custom registry. 4. Stop the Kubernetes cluster. @@ -188,22 +186,6 @@ The recommended approach to set this up is the following: 6. Restart Docker Desktop. 7. Verify that the Kubernetes cluster is using the custom registry images using the `docker ps` command. -> [!NOTE] -> -> The `KubernetesImagesRepository` setting only applies to control plane images used by Docker Desktop -> to set up the Kubernetes cluster. It has no effect on other Kubernetes pods. - -> [!NOTE] -> -> In Docker Desktop versions 4.43 or earlier, when using `KubernetesImagesRepository` and [Enhanced Container Isolation (ECI)](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) -> is enabled, add the following images to the [ECI Docker socket mount image list](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#enhanced-container-isolation): -> -> `[imagesRepository]/desktop-cloud-provider-kind:` -> `[imagesRepository]/desktop-containerd-registry-mirror:` -> -> These containers mount the Docker socket, so you must add the images to the ECI images list. If not, -> ECI will block the mount and Kubernetes won't start. - ## Troubleshooting - If Kubernetes fails to start, make sure Docker Desktop is running with enough allocated resources. Check **Settings** > **Resources**. diff --git a/content/manuals/desktop/use-desktop/logs.md b/content/manuals/desktop/use-desktop/logs.md index 6152feed5c8a..0dc31e8aacbd 100644 --- a/content/manuals/desktop/use-desktop/logs.md +++ b/content/manuals/desktop/use-desktop/logs.md @@ -29,24 +29,30 @@ Use the **Search** field at the top of the Logs view to find specific entries. T - Plain-text terms for exact match searches - Regular expressions (for example, `/error|warn/`) -You can save your search terms for easy-access later. +You can save your current filters as a preset for easy access later. Presets capture your container selection, build log visibility, and case sensitivity settings, as well as any active search terms. If no containers are selected, the preset is named all; otherwise it is named after the first selected container. To refine the log stream further, select the **Filter** icon in the toolbar to open the container filter panel. From here you can: - Check individual containers to show only their output - Check Compose stacks to show or hide entire groups -- Use **Select all** or **Clear all** to quickly toggle every container at once +- Toggle off **View build logs** to exclude build-related log output in the stream +- Use **Select all** or **Clear container filters** to quickly toggle every container at once Use the **Export** button in the top-right corner (available with Docker Desktop version 4.77 and later) to export all logs or only the logs that match your filters. ## Display settings Select the **Display settings** icon in the toolbar to toggle the following: - -- **View build logs**: Include or exclude build-related log output in the stream - **Wrap lines** - **Show timestamps** +You can also choose **Clear logs** to remove log entries from the view (available with Docker Desktop 4.79 and later). A dialog lets you choose between two options: + +- **Clear all logs**: Immediately hides all current log entries. +- **Clear logs before**: Activates a date and time picker. Only entries at or before the selected timestamp are hidden. + +The cleared state persists across Docker Desktop restarts. Once entries are cleared, they cannot be restored. + ## Feedback Select **Give feedback** at the top of the view to share suggestions or report issues. diff --git a/content/manuals/desktop/use-desktop/pause.md b/content/manuals/desktop/use-desktop/pause.md deleted file mode 100644 index 14265255c558..000000000000 --- a/content/manuals/desktop/use-desktop/pause.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: understand what pausing Docker Desktop Dashboard means -keywords: Docker Desktop Dashboard, manage, containers, gui, dashboard, pause, user manual -title: Pause Docker Desktop -weight: 80 ---- - -Pausing Docker Desktop temporarily suspends the Linux VM running Docker Engine. This saves the current state of all containers in memory and freezes all running processes, significantly reducing CPU and memory usage which is helpful for conserving battery on laptops. - -To pause Docker Desktop, select the **Pause** icon to the left of the footer in the Docker Dashboard. To manually resume Docker Desktop, select the **Resume** option in the Docker menu, or run any Docker CLI command. - -When you manually pause Docker Desktop, a paused status displays on the Docker menu and on the Docker Desktop Dashboard. You can still access the **Settings** and the **Troubleshoot** menu. - -> [!TIP] -> -> The Resource Saver feature is enabled by default and provides better CPU and memory savings than the manual Pause feature. See [Resource Saver mode](resource-saver.md) for more info. diff --git a/content/manuals/desktop/use-desktop/resource-saver.md b/content/manuals/desktop/use-desktop/resource-saver.md index 746db0ab3fa8..0c86f02d0a5b 100644 --- a/content/manuals/desktop/use-desktop/resource-saver.md +++ b/content/manuals/desktop/use-desktop/resource-saver.md @@ -4,6 +4,8 @@ keywords: Docker Dashboard, resource saver, manage, containers, gui, dashboard, title: Docker Desktop's Resource Saver mode linkTitle: Resource Saver mode weight: 70 +aliases: + - /desktop/use-desktop/pause/ --- Resource Saver mode significantly reduces Docker @@ -15,16 +17,18 @@ With Resource Saver mode, Docker Desktop uses minimal system resources when it's allowing you to save battery life on your laptop and improve your multi-tasking experience. +> [!NOTE] +> +> If you have any WSL integration enabled, Docker Desktop treats that as ongoing activity and won't enter Resource Saver mode, even after the idle timer would otherwise have elapsed. + ## Configure Resource Saver Resource Saver is enabled by default but can be disabled by navigating to the **Resources** tab, in **Settings**. You can also configure the idle timer as shown below. -![Resource Saver Settings](../images/resource-saver-settings.webp) - If the values available aren't sufficient for your needs, you can reconfigure it to any value, as long as the value is larger than 30 seconds, by -changing `autoPauseTimeoutSeconds` in the Docker Desktop `settings-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier): +changing `autoPauseTimeoutSeconds` in the Docker Desktop `settings-store.json` file: - Mac: `~/Library/Group Containers/group.com.docker/settings-store.json` - Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` @@ -48,7 +52,7 @@ the system tray. ## Resource Saver mode versus Pause -Resource Saver has higher precedence than the older [Pause](pause.md) feature, +Resource Saver has higher precedence than the older Pause feature, meaning that while Docker Desktop is in Resource Saver mode, manually pausing Docker Desktop is not possible (nor does it make sense since Resource Saver actually stops the Docker Desktop Linux VM). In general, we recommend keeping @@ -65,8 +69,7 @@ the WSL Linux VM is not owned by Docker Desktop). As a result, Resource Saver reduces CPU utilization on WSL, but it does not reduce Docker's memory utilization. -To reduce memory utilization on WSL, we instead recommend that -users enable WSL's `autoMemoryReclaim` feature as described in the +To reduce memory utilization on WSL, enable WSL's `autoMemoryReclaim` feature as described in the [Docker Desktop WSL docs](/manuals/desktop/features/wsl/_index.md). Finally, since Docker Desktop does not stop the Linux VM on WSL, exit from Resource Saver mode is immediate (there's no exit delay). diff --git a/content/manuals/desktop/use-desktop/volumes.md b/content/manuals/desktop/use-desktop/volumes.md index 6b3cafd7eec8..d8bf2b694858 100644 --- a/content/manuals/desktop/use-desktop/volumes.md +++ b/content/manuals/desktop/use-desktop/volumes.md @@ -46,24 +46,25 @@ To use the volume with a container, see [Use volumes](/manuals/engine/storage/vo ## Inspect a volume -To explore the details of a specific volume, select a volume from the list. This -opens the detailed view. +### Inspect a volume -The **Container in-use** tab displays the name of the container using the -volume, the image name, the port number used by the container, and the target. A -target is a path inside a container that gives access to the files in the -volume. +To explore the details of a specific volume, select a volume from the list. This opens the detailed view, with three tabs. -The **Stored data** tab displays the files and folders in the volume and the -file size. To save a file or a folder, right-click on the file or folder to -display the options menu, select **Save as...**, and then specify a location to -download the file. +#### Container in-use -To delete a file or a folder from the volume, right-click on the file or folder -to display the options menu, select **Delete**, and then select **Delete** again -to confirm. +The **Container in-use** tab displays the name of the container using the volume, the image name, the port number used by the container, and the target. A target is a path inside a container that gives access to the files in the volume. -The **Exports** tab lets you [export the volume](#export-a-volume). +#### Stored data + +The **Stored data** tab displays the files and folders in the volume and their file size. + +- Right-click a file or folder to save it, select **Save as...**, and then specify a location to download it to. +- To delete a file or folder from the volume, right-click it, select **Delete**, and then confirm. +- To edit a text file directly, double-click it to open it in the built-in editor. Unsaved changes are indicated in the editor, and you can save them back to the volume. + +#### Exports + +The **Exports** tab lets you export the volume, view a log of past exports, and manage a scheduled export. See [export the volume](#export-a-volume). ## Clone a volume diff --git a/content/manuals/dhi/_index.md b/content/manuals/dhi/_index.md index 7f90e5eefaaf..0e7d4386c7ef 100644 --- a/content/manuals/dhi/_index.md +++ b/content/manuals/dhi/_index.md @@ -2,6 +2,14 @@ title: Docker Hardened Images description: Secure, minimal, and production-ready base images weight: 8 +aliases: + - /dhi/features/ + - /dhi/features/secure/ + - /dhi/features/integration/ + - /dhi/features/support/ + - /dhi/features/patching/ + - /dhi/features/flexible/ + - /dhi/features/helm/ params: sidebar: group: Supply chain security @@ -14,26 +22,26 @@ params: description: Learn what Docker Hardened Images are, how they're built, and what sets them apart from typical base images. icon: information-circle link: /dhi/explore/ - - title: Features - description: Discover the security, compliance, and enterprise-readiness features built into Docker Hardened Images. - icon: lock-closed - link: /dhi/features/ - title: How-tos description: Step-by-step guides for using, verifying, scanning, and migrating to Docker Hardened Images. icon: play link: /dhi/how-to/ - - title: Core concepts + - title: Security concepts description: Understand the secure supply chain principles that make Docker Hardened Images production-ready. icon: clipboard-document-check - link: /dhi/core-concepts/ - - title: Troubleshoot - description: Resolve common issues with building, running, or debugging Docker Hardened Images. - icon: question-mark-circle - link: /dhi/troubleshoot/ - - title: Additional resources - description: Guides, blog posts, Docker Hub catalog, GitHub repositories, and more. + link: /dhi/explore/security-concepts/ + - title: Tools + description: Browse and manage Docker Hardened Images using Docker Hub, the CLI, MCP server, or Terraform. + icon: wrench-screwdriver + link: /dhi/tools/ + - title: Resources and feedback + description: Guides, GitHub repositories, community channels, and how to give feedback. icon: link link: /dhi/resources/ + - title: Release notes + description: New features, improvements, and changes in Docker Hardened Images. + icon: newspaper + link: /dhi/release-notes/platform/ --- Docker Hardened Images (DHI) provide minimal, secure, and production-ready @@ -64,9 +72,48 @@ DHI is available in the following three subscriptions. For pricing and more details, see the [Docker Hardened Images subscription comparison](https://www.docker.com/products/hardened-images/#compare). +## Community features + +DHI's core features are free to use, share, and build on under Apache 2.0. + +- [Near-zero CVEs](/dhi/explore/security-concepts/cves/): continuously scanned and patched + to maintain minimal known vulnerabilities +- [Distroless variants](/dhi/explore/security-concepts/distroless/): remove unnecessary + components, reducing attack surface by up to 95% +- Non-root execution: containers run as non-root by default +- [Hardened system packages](/dhi/how-to/hardened-packages/): system packages + built from source, cryptographically signed, and verified by Docker +- [SLSA Build Level 3 provenance](/dhi/explore/security-concepts/slsa/), [signed + SBOMs](/dhi/explore/security-concepts/sbom/), [VEX statements](/dhi/explore/security-concepts/vex/), + and [cryptographic signatures](/dhi/explore/security-concepts/signatures/) on every image +- Built on Alpine and Debian with [glibc and musl + variants](/dhi/explore/security-concepts/glibc-musl/); dev and runtime image variants + available +- Works with existing Docker workflows, CI/CD pipelines, and tools with no + retooling required +- [Helm charts](/dhi/how-to/helm/): Docker-provided charts built from upstream + sources, tested for compatibility with DHI, and available as OCI artifacts in + the DHI catalog; include SLSA Level 3 provenance, SBOMs, and cryptographic + signing + +## Select and Enterprise features + +For organizations with strict security or compliance requirements: + +- [7-day SLA](https://docs.docker.com/go/dhi-sla/) for critical and high + severity CVE remediation +- [FIPS-enabled](/dhi/explore/security-concepts/fips/) and + [STIG-ready](/dhi/explore/security-concepts/stig/) compliance variants +- [Customization](/dhi/how-to/customize/): add packages, tools, certificates, + and configurations (up to 5 with Select, unlimited with Enterprise) +- [Enterprise package repository](/dhi/how-to/hardened-packages/) access and + full catalog access (Enterprise) +- Extended Lifecycle Support: post-EOL security patches, updated SBOMs, + provenance, and signing (Enterprise add-on) + +## Get started + Explore the sections below to get started with Docker Hardened Images, integrate them into your workflow, and learn what makes them secure and enterprise-ready. -{{< grid - items="grid_sections" ->}} +{{< grid items="grid_sections" >}} diff --git a/content/manuals/dhi/core-concepts/_index.md b/content/manuals/dhi/core-concepts/_index.md deleted file mode 100644 index 677498cdf0fd..000000000000 --- a/content/manuals/dhi/core-concepts/_index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Core concepts -description: Learn the core concepts behind Docker Hardened Images, including security metadata, vulnerability management, image structure, and verification. -weight: 30 -params: - grid_concepts_metadata: - - title: Attestations - description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results. - icon: clipboard-document-list - link: /dhi/core-concepts/attestations/ - - title: Software Bill of Materials (SBOMs) - description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance. - icon: list-bullet - link: /dhi/core-concepts/sbom/ - - title: Supply-chain Levels for Software Artifacts (SLSA) - description: Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds. - icon: clipboard-document-check - link: /dhi/core-concepts/slsa/ - - title: Image provenance - description: Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA. - icon: pencil-square - link: /dhi/core-concepts/provenance/ - - grid_concepts_compliance: - - title: FIPS - description: Learn how Docker Hardened Images support FIPS 140 by using validated cryptographic modules and providing signed attestations for compliance audits. - icon: check-badge - link: /dhi/core-concepts/fips/ - - title: STIG - description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. - icon: shield-check - link: /dhi/core-concepts/stig/ - - title: CIS Benchmarks - description: Learn how Docker Hardened Images help you meet Center for Internet Security (CIS) Docker Benchmark requirements for secure container configuration and deployment. - icon: check-circle - link: /dhi/core-concepts/cis/ - - grid_concepts_risk: - - title: Common Vulnerabilities and Exposures (CVEs) - description: Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools. - icon: exclamation-circle - link: /dhi/core-concepts/cves/ - - title: Vulnerability Exploitability eXchange (VEX) - description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable. - icon: exclamation-triangle - link: /dhi/core-concepts/vex/ - - title: Software Supply Chain Security - description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface. - icon: shield-check - link: /dhi/core-concepts/sscs/ - - title: Secure Software Development Lifecycle (SSDLC) - description: See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools. - icon: wrench-screwdriver - link: /dhi/core-concepts/ssdlc/ - - grid_concepts_structure: - - title: Distroless images - description: Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components. - icon: squares-2x2 - link: /dhi/core-concepts/distroless/ - - title: glibc and musl support in Docker Hardened Images - description: Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs. - icon: arrows-up-down - link: /dhi/core-concepts/glibc-musl/ - - title: Image immutability - description: Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable. - icon: minus-circle - link: /dhi/core-concepts/immutability/ - - title: Image hardening - description: Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations. - icon: shield-check - link: /dhi/core-concepts/hardening/ - - grid_concepts_verification: - - title: Digests - description: Learn how to use immutable image digests to guarantee consistency and verify the exact Docker Hardened Image you're running. - icon: finger-print - link: /dhi/core-concepts/digests/ - - title: Code signing - description: Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance. - icon: key - link: /dhi/core-concepts/signatures/ ---- - -Docker Hardened Images (DHIs) are built on a foundation of secure software -supply chain practices. This section explains the core concepts behind that -foundation, from signed attestations and immutable digests to standards like SLSA -and VEX. - -Start here if you want to understand how Docker Hardened Images support compliance, -transparency, and security. - - -## Security metadata and attestations - -{{< grid items="grid_concepts_metadata" >}} - -## Compliance standards - -{{< grid items="grid_concepts_compliance" >}} - -## Vulnerability and risk management - -{{< grid items="grid_concepts_risk" >}} - -## Image structure and behavior - -{{< grid items="grid_concepts_structure" >}} - -## Verification and traceability - -{{< grid items="grid_concepts_verification" >}} \ No newline at end of file diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/core-concepts/attestations.md deleted file mode 100644 index af72fd2e6661..000000000000 --- a/content/manuals/dhi/core-concepts/attestations.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Attestations -description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results. -keywords: container image attestations, signed sbom, build provenance, slsa compliance, vex document ---- - -Docker Hardened Images (DHIs) and charts include comprehensive, signed security -attestations that verify the image's build process, contents, and security -posture. These attestations are a core part of secure software supply chain -practices and help users validate that an image is trustworthy and -policy-compliant. - -## What is an attestation? - -An attestation is a signed statement that provides verifiable information -about an image or chart, such as how it was built, what's inside it, and what security -checks it has passed. Attestations are typically signed using Sigstore tooling -(such as Cosign), making them tamper-evident and cryptographically verifiable. - -Attestations follow standardized formats (like [in-toto](https://in-toto.io/), -[CycloneDX](https://cyclonedx.org/), and [SLSA](https://slsa.dev/)) and are -attached to the image or chart as OCI-compliant metadata. They can be generated -automatically during image builds or added manually to document extra tests, -scan results, or custom provenance. - -## Why are attestations important? - -Attestations provide critical visibility into the software supply chain by: - -- Documenting *what* went into an image (e.g., SBOMs) -- Verifying *how* it was built (e.g., build provenance) -- Capturing *what security scans* it has passed or failed (e.g., CVE reports, - secrets scans, test results) -- Helping organizations enforce compliance and security policies -- Supporting runtime trust decisions and CI/CD policy gates - -They are essential for meeting industry standards such as SLSA, -and help teams reduce the risk of supply chain attacks by making build and -security data transparent and verifiable. - -## How Docker Hardened Images and charts use attestations - -All DHIs and charts are built using [SLSA Build Level -3](https://slsa.dev/spec/latest/levels) practices, and each image variant is -published with a full set of signed attestations. These attestations allow users -to: - -- Verify that the image or chart was built from trusted sources in a secure environment -- View SBOMs in multiple formats to understand component-level details -- Review scan results to check for vulnerabilities or embedded secrets -- Confirm the build and deployment history of each image - -Attestations are automatically published and associated with each DHI -and chart. They can be inspected using tools like [Docker -Scout](../how-to/verify.md) or -[Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD -tooling or security platforms. - -## Image attestations - -While every DHI variant includes a set of attestations, the attestations may -vary based on the image variant. For example, some images may include a STIG -scan attestation. The following table is a comprehensive list of all -attestations that may be included with a DHI. To see which attestations are -available for a specific image variant, including the specific predicate type URIs, -use Docker Scout: - -```console -$ docker scout attest list dhi.io/<image>:<tag> -``` - -For more details, see [Verify image attestations](../how-to/verify.md#verify-image-attestations). - -| Attestation type | Description | -|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | -| STIG scan | Results of a STIG scan, with output in HTML and XCCDF formats. | -| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning. | -| VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | -| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the image. | -| Scout provenance | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details. | -| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | -| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | -| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | -| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../explore/malware-scanning.md). | -| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | -| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | -| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. | -| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | -| FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | -| DHI Image Sources | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. | - -## Package attestations - -In addition to image-level attestations, Docker hardened packages also include -their own attestations. These package-level attestations provide provenance and -build information for individual packages within an image, allowing you to -trace the supply chain at a granular level. - -Package attestations include similar information as image attestations, such as -SLSA provenance, showing how each package was built and what materials were -used. You can extract package information from an image's attestations and then -retrieve the package's own attestations recursively. - -For detailed instructions on how to access and verify package attestations, see -[Package attestations](../how-to/hardened-packages.md#package-attestations). - -## Helm chart attestations - -Docker Hardened Image (DHI) charts also include comprehensive signed attestations -that provide transparency and verification for your Kubernetes deployments. Like -DHI container images, these charts are built following SLSA Build Level 3 -practices and include extensive security metadata. - -DHI Helm charts include the following attestations. To view the specific predicate -type URIs for these attestations, use Docker Scout: - -```console -$ docker scout attest list dhi.io/<chart>:<version> -``` - -For more details, see [Verify Helm chart attestations](../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). - -| Attestation type | Description | -|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart. | -| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart. | -| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the chart and its referenced images. | -| Scout provenance | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters. | -| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | -| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | -| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | -| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../explore/malware-scanning.md). | -| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | -| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | -| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | - -## View and verify attestations - -To view and verify attestations, see [Verify a Docker Hardened -Image](../how-to/verify.md). - -## Add your own attestations - -In addition to the comprehensive attestations provided by Docker Hardened -Images, you can add your own signed attestations when building derivative -images. This is especially useful if you’re building new applications on top of -a DHI and want to maintain transparency, traceability, and trust in your -software supply chain. - -By attaching attestations such as SBOMs, build provenance, or custom metadata, -you can meet compliance requirements, pass security audits, and support policy -evaluation tools like Docker Scout. - -These attestations can then be verified downstream using tools -like Cosign or Docker Scout. - -To learn how to attach custom attestations during the build process, see [Build -attestations](/manuals/build/metadata/attestations.md). diff --git a/content/manuals/dhi/core-concepts/sbom.md b/content/manuals/dhi/core-concepts/sbom.md deleted file mode 100644 index 40b99f153b11..000000000000 --- a/content/manuals/dhi/core-concepts/sbom.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Software Bill of Materials (SBOMs) -linktitle: SBOMs -description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance. -keywords: sbom docker image, software bill of materials, signed sbom, container sbom verification, sbom compliance ---- - -## What is an SBOM? - -An SBOM is a detailed inventory that lists all components, libraries, and -dependencies used in building a software application. It provides transparency -into the software supply chain by documenting each component's version, origin, -and relationship to other components. Think of it as a "recipe" for your -software, detailing every ingredient and how they come together. - -Metadata included in an SBOM for describing software artifacts may include: - -- Name of the artifact -- Version -- License type -- Authors -- Unique package identifier - -## Why are SBOMs important? - -In today's software landscape, applications often comprise numerous components -from various sources, including open-source libraries, third-party services, and -proprietary code. This complexity can obscure visibility into potential -vulnerabilities and complicate compliance efforts. SBOMs address these -challenges by providing a detailed inventory of all components within an -application. - - -The significance of SBOMs is underscored by several key factors: - -- Enhanced transparency: SBOMs offer a comprehensive view of all components that - constitute an application, enabling organizations to identify and assess risks - associated with third-party libraries and dependencies. - -- Proactive vulnerability management: By maintaining an up-to-date SBOM, - organizations can swiftly identify and address vulnerabilities in software - components, reducing the window of exposure to potential exploits. - -- Regulatory compliance: Many regulations and industry standards now require - organizations to maintain control over the software components they use. An - SBOM facilitates compliance by providing a clear and accessible record. - -- Improved incident response: In the event of a security breach, an SBOM - enables organizations to quickly identify affected components and take - appropriate action, minimizing potential damage. - -## Docker Hardened Image SBOMs - -Docker Hardened Images have SBOMs, ensuring that every component -in the image is documented and verifiable. These SBOMs are cryptographically -signed, providing a tamper-evident record of the image's contents. This -integration simplifies audits and enhances trust in the software supply chain. - -## View SBOMs in Docker Hardened Images - -To view the SBOM of a Docker Hardened Image, you can use the `docker scout sbom` -command. Replace `<image-name>:<tag>` with the image name and tag. - -```console -$ docker scout sbom dhi.io/<image-name>:<tag> -``` - -## Verify the SBOM of a Docker Hardened Image - -Since Docker Hardened Images come with signed SBOMs, you can use Docker Scout to -verify the authenticity and integrity of the SBOM attached to the image. This -ensures that the SBOM has not been tampered with and that the image's contents -are trustworthy. - -To verify the SBOM of a Docker Hardened Image using Docker Scout, use the following command: - -```console -$ docker scout attest get dhi.io/<image-name>:<tag> \ - --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform <platform> -``` - -For example, to verify the SBOM attestation for the `node:20.19-debian12` image: - -```console -$ docker scout attest get dhi.io/node:20.19-debian12 \ - --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform linux/amd64 -``` - -## Resources - -For more details about SBOM attestations and Docker Build, see [SBOM -attestations](/build/metadata/attestations/sbom/). - -To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../scout/how-tos/view-create-sboms.md). \ No newline at end of file diff --git a/content/manuals/dhi/explore/_index.md b/content/manuals/dhi/explore/_index.md index bc5ade0beecc..c217ea77aea6 100644 --- a/content/manuals/dhi/explore/_index.md +++ b/content/manuals/dhi/explore/_index.md @@ -33,10 +33,15 @@ params: description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain. icon: user-group link: /dhi/explore/responsibility/ - - title: Give feedback - icon: question-mark-circle - description: Docker welcomes all contributions and feedback. - link: /dhi/explore/feedback + - title: EU data residency + description: Learn how Docker stores your mirrored and customized images in the EU when your subscription is in the EU region. + icon: globe-alt + link: /dhi/explore/eu-region/ + - title: Security concepts + description: Learn the core concepts behind Docker Hardened Images — signed attestations, immutable digests, SLSA, VEX, and more. + icon: clipboard-document-check + link: /dhi/explore/security-concepts/ + aliases: - /dhi/about/ --- @@ -48,8 +53,7 @@ existing Docker-based workflows with little to no retooling required. This section helps you understand what Docker Hardened Images are, how they're built and tested, the different types available, and how responsibility is -shared between Docker and you as a user. For a complete list of DHI features and -capabilities, see [Features](/dhi/features/). +shared between Docker and you as a user. ## Learn more about Docker Hardened Images diff --git a/content/manuals/dhi/explore/available.md b/content/manuals/dhi/explore/available.md index e8540691d8f1..3db9c8c5c539 100644 --- a/content/manuals/dhi/explore/available.md +++ b/content/manuals/dhi/explore/available.md @@ -12,7 +12,7 @@ Docker Hardened Images (DHI) is a comprehensive catalog of security-hardened container images built to meet diverse development and production needs. -You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/hardened-images/catalog) or use the [DHI CLI](../how-to/cli.md) to browse +You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/hardened-images/catalog) or use the [DHI CLI](../tools/cli.md) to browse available images, tags, and metadata from the command line. ## Framework and application images @@ -85,7 +85,7 @@ For example, you might find tags like the following in a DHI repository: Some Docker Hardened Images include a `-fips` variant. These variants use cryptographic modules that have been validated under [FIPS -140](../core-concepts/fips.md), a U.S. government standard for secure +140](security-concepts/fips.md), a U.S. government standard for secure cryptographic operations. FIPS variants are designed to help organizations meet regulatory and compliance diff --git a/content/manuals/dhi/explore/build-process.md b/content/manuals/dhi/explore/build-process.md index 01cd6541eb7c..e2bcd2930ee4 100644 --- a/content/manuals/dhi/explore/build-process.md +++ b/content/manuals/dhi/explore/build-process.md @@ -35,7 +35,7 @@ contents, build pipeline steps, security configurations, and runtime settings. Every Docker Hardened Image includes a SLSA Build Level 3 attestation that provides verifiable build provenance. For details on SLSA attestations and how to -verify them, see [SLSA](../core-concepts/slsa.md). +verify them, see [SLSA](security-concepts/slsa.md). ## Build triggers diff --git a/content/manuals/dhi/explore/eu-region.md b/content/manuals/dhi/explore/eu-region.md new file mode 100644 index 000000000000..bf6834b8413c --- /dev/null +++ b/content/manuals/dhi/explore/eu-region.md @@ -0,0 +1,80 @@ +--- +title: EU data residency for Docker Hardened Images +linkTitle: EU data residency +description: Learn how Docker stores your mirrored and customized Docker Hardened Images in the EU when your DHI subscription is in the EU region, and what works differently in that region. +keywords: docker hardened images, dhi, eu region, data residency, europe, mirror, customization +weight: 48 +--- + +{{< summary-bar feature_name="Docker Hardened Images EU data residency" >}} + +Docker can provision your organization's Docker Hardened Images (DHI) +subscription in the EU region. When your subscription is in the EU region, +Docker stores your mirrored and customized images in the EU. + +## How your region is set + +Docker sets the region on your DHI subscription. Docker doesn't detect your +region automatically. To have your subscription provisioned in the EU region, +or to change its region, contact your Docker account representative or <a +href="https://www.docker.com/pricing/contact-sales/" +id="dkr_docs_cs_dhi_eu_region" class="link" rel="noopener">Docker +sales</a>. + +If you plan to use the EU region, request it before you start mirroring. +Mirrors that you create before your subscription moves to the EU region stay +in their original region. + +## Check your region + +1. Sign in to [Docker Hub](https://hub.docker.com). +1. Select **My Hub**. +1. In the namespace drop-down, select your organization. +1. Select **Hardened Images** > **Manage**. + +When your subscription is in the EU region, the subscription label shows +**Your subscription (Region EU)**. When it shows only **Your subscription**, +your subscription is in the default US region. + +## What Docker stores in the EU + +When your subscription is in the EU region, Docker stores the following in the +EU: + +- The repositories that Docker creates when you [mirror a DHI + repository](../how-to/mirror.md) to your organization on Docker Hub, and + their attestations +- Your [customized images](../how-to/customize.md) and their attestations + +OCI artifacts that you use in customizations are stored in the region of the +repository that you push them to. To keep them in the EU, push them to +repositories in the EU region. + +Your region doesn't apply to repositories that you [mirror to a third-party +registry](../how-to/mirror.md#mirror-a-dhi-repository-to-a-third-party-registry). +Where that content is stored depends on the registry you use. + +## Attestations in the EU region + +Docker stores attestations with the images in your Docker Hub repository. For +mirrored repositories, Docker copies only the attestations created when the +image is built. Attestations that Docker Scout generates, such as VEX +statements and vulnerability reports, aren't available in the EU region. To +see which attestations are available, see [Image +attestations](./security-concepts/attestations.md#image-attestations). + +## Limitations in the EU region + +Mirroring and customization in the EU region work the same as in other regions, +with the following differences: + +- You can't [add files](../how-to/customize.md#inject-files-into-the-image) + that you write directly in a customization, such as configuration files or + setup scripts. This doesn't affect files that come from OCI artifacts. You can + still add packages, OCI artifacts, and symlinks. +- Docker doesn't provide VEX statements or vulnerability reports for your + mirrored repositories or customized images. +- Docker doesn't turn on Docker Scout image analysis for your mirrored + repositories or customized images in the EU region. If you turn on Docker + Scout image analysis for a repository in the EU region, the data that Docker + Scout processes is stored in the US. diff --git a/content/manuals/dhi/explore/feedback.md b/content/manuals/dhi/explore/feedback.md deleted file mode 100644 index 48fa91833689..000000000000 --- a/content/manuals/dhi/explore/feedback.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Give feedback -linkTitle: Feedback -description: How to interact with the DHI team -keywords: software supply chain security, feedback, bugs, discussion, questions -weight: 999 -aliases: - - /dhi/about/feedback/ ---- - -Committed to maintaining the quality, security, and reliability of the Docker Hardened Images (DHI) -a repository has been created as a point of contact to encourage the community to collaborate -in improving the Hardened Images ecosystem. - -## Questions or discussions - -You can use the [GitHub Discussions -board](https://github.com/orgs/docker-hardened-images/discussions) to engage -with the DHI team for: - -- General questions about DHIs -- Best practices and recommendations -- Security tips and advice -- Show and tell your implementations -- Community announcements - -## Reporting bugs or issues - -You can [open a new issue](https://github.com/docker-hardened-images/catalog/issues) for topics such as: - -- Bug reports -- Feature requests -- Documentation improvements -- Security vulnerabilities (see security policy) - -It's encouraged to first search existing issues to see if it’s already been reported. -The DHI team reviews reports regularly and appreciates clear, actionable feedback. - -## Responsible security disclosure - -It is forbidden to post details of vulnerabilities before coordinated disclosure and resolution. - -If you discover a security vulnerability, report it responsibly by following Docker’s [security disclosure](https://www.docker.com/trust/vulnerability-disclosure-policy/). diff --git a/content/manuals/dhi/explore/responsibility.md b/content/manuals/dhi/explore/responsibility.md index e4e816dd0321..92663ce716cf 100644 --- a/content/manuals/dhi/explore/responsibility.md +++ b/content/manuals/dhi/explore/responsibility.md @@ -50,7 +50,7 @@ securely. and is responsible for validating core features. - Docker: Validates that DHIs start, run, and behave consistently with upstream expectations. Docker also runs security scans and includes a [testing - attestation](../core-concepts/attestations.md) with each image. + attestation](security-concepts/attestations.md) with each image. - You: Test your application on top of DHIs and validate that any changes or customizations function as expected in your environment. diff --git a/content/manuals/dhi/explore/scanner-integrations.md b/content/manuals/dhi/explore/scanner-integrations.md index 0992c50aa644..a2928ccde516 100644 --- a/content/manuals/dhi/explore/scanner-integrations.md +++ b/content/manuals/dhi/explore/scanner-integrations.md @@ -1,11 +1,11 @@ --- title: Scanner integrations description: Learn which vulnerability scanners work with Docker Hardened Images and how to choose the right scanner for accurate vulnerability assessment. -keywords: scanner integration, vulnerability scanning, docker scout, trivy, grype, mend.io, black duck, container security scanners +keywords: scanner integration, vulnerability scanning, docker scout, trivy, grype, wiz, black duck, aikido, aws inspector, container security scanners weight: 40 --- -Docker Hardened Images work with various vulnerability scanners. However, to get +Docker Hardened Images (DHI) work with various vulnerability scanners. However, to get accurate results that reflect the actual security posture of these images, your scanner needs to understand the VEX (Vulnerability Exploitability eXchange) attestations included with each image. @@ -13,23 +13,20 @@ attestations included with each image. ## Scanners with VEX support The following scanners can read and apply VEX attestations included with Docker -Hardened Images to deliver more accurate vulnerability assessments: - -- [Docker Scout](/scout/): Automatically applies VEX statements with - zero configuration. Integrated directly into Docker Desktop and the Docker CLI. -- [Trivy](https://trivy.dev/): Supports VEX through VEX Hub for automatic - updates or local VEX files for air-gapped environments. -- [Grype](https://github.com/anchore/grype): Supports VEX via the `--vex` - flag for local VEX file processing. -- [Wiz](https://www.wiz.io/): Automatically applies VEX statements with - zero configuration. -- [Mend.io](https://www.mend.io/): Automatically retrieves and applies VEX - statements with zero configuration. Combines VEX data with reachability - analysis. -- [Black Duck](https://www.blackduck.com/): Identifies Docker Hardened Images - and applies VEX statements with zero configuration. - -For step-by-step instructions, see [Scan Docker Hardened Images](/manuals/dhi/how-to/scan.md). +Hardened Images: + +| Scanner | VEX application | +|---------|-----------------| +| [Docker Scout](/scout/) | Automatic, zero configuration | +| [Trivy](https://trivy.dev/) | VEX Hub (recommended) or local VEX file | +| [Grype](https://github.com/anchore/grype) | Via `--vex` flag with local VEX file | +| [Wiz](https://docs.wiz.io/) | Automatic, zero configuration | +| [Mend.io](https://docs.mend.io/platform/latest/docker-hardened-images) | Automatic, zero configuration | +| [Black Duck](https://documentation.blackduck.com/bundle/bd-hub/page/Reporting/vexReport_global.html) | Automatic, zero configuration | +| [Aikido](https://help.aikido.dev/container-image-scanning/standalone-registries/docker-hub-images) | Automatic, zero configuration | +| [AWS Inspector](https://docs.aws.amazon.com/inspector/latest/user/supported.html) | Automatic, zero configuration | + +For step-by-step instructions for Docker Scout, Trivy, and Grype, see [Scan Docker Hardened Images](/manuals/dhi/how-to/scan.md). For Wiz, Mend.io, Black Duck, Aikido, and AWS Inspector, refer to their respective documentation. ## Choosing a scanner for Docker Hardened Images @@ -42,7 +39,7 @@ the minimum requirements for VEX defined by CISA (Cybersecurity and Infrastructure Security Agency), the U.S. government agency responsible for cybersecurity guidance. These attestations document which vulnerabilities don't apply to the image and why, helping you focus on real risks. To understand what -VEX is and how it works, see the [VEX core concept](/manuals/dhi/core-concepts/vex.md). +VEX is and how it works, see the [VEX core concept](/manuals/dhi/explore/security-concepts/vex.md). Because OpenVEX is an open standard with government backing, it has strong industry momentum and any tool can implement it without vendor-specific @@ -68,8 +65,7 @@ from Docker Hardened Images offer the following benefits: aren't flagged; security teams and compliance officers can review the reasoning rather than trusting a vendor's black box. - Scanner flexibility: Switch between any VEX-enabled scanner (Docker Scout, - Trivy, Grype, Wiz, Mend.io, Black Duck, etc.) without losing vulnerability - context or rebuilding exclusion lists. + Trivy, Grype, etc.) without losing vulnerability context or rebuilding exclusion lists. - Consistent results: VEX-enabled scanners interpret the same data the same way, eliminating discrepancies between tools. - Faster workflows: Focus on real risks rather than researching why reported @@ -101,7 +97,7 @@ The image includes signed attestations that explain which vulnerabilities don't apply and why. Any VEX-enabled scanner can read these attestations, giving you: - Tool flexibility: Use any scanner that supports OpenVEX (Docker Scout, - Trivy, Grype, Wiz, Mend.io, Black Duck, etc.) + Trivy, Grype, etc.) - Complete transparency: Review the exact reasoning for each vulnerability assessment - Full auditability: Security teams and compliance officers can independently @@ -173,4 +169,3 @@ exceptions. This requires: Learn how to [scan Docker Hardened Images](/manuals/dhi/how-to/scan.md) with VEX-compliant scanners. - diff --git a/content/manuals/dhi/explore/security-concepts/_index.md b/content/manuals/dhi/explore/security-concepts/_index.md new file mode 100644 index 000000000000..03b7c1e1c6bd --- /dev/null +++ b/content/manuals/dhi/explore/security-concepts/_index.md @@ -0,0 +1,115 @@ +--- +aliases: + - /dhi/core-concepts/ +title: Security concepts +linkTitle: Security concepts +description: Learn the core concepts behind Docker Hardened Images, including security metadata, vulnerability management, image structure, and verification. +weight: 60 +params: + grid_concepts_metadata: + - title: Attestations + description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results. + icon: clipboard-document-list + link: /dhi/explore/security-concepts/attestations/ + - title: Software Bill of Materials (SBOMs) + description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance. + icon: list-bullet + link: /dhi/explore/security-concepts/sbom/ + - title: Supply-chain Levels for Software Artifacts (SLSA) + description: Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds. + icon: clipboard-document-check + link: /dhi/explore/security-concepts/slsa/ + - title: Image provenance + description: Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA. + icon: pencil-square + link: /dhi/explore/security-concepts/provenance/ + + grid_concepts_compliance: + - title: FIPS + description: Learn how Docker Hardened Images support FIPS 140 by using validated cryptographic modules and providing signed attestations for compliance audits. + icon: check-badge + link: /dhi/explore/security-concepts/fips/ + - title: STIG + description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. + icon: shield-check + link: /dhi/explore/security-concepts/stig/ + - title: CIS Benchmarks + description: Learn how Docker Hardened Images help you meet Center for Internet Security (CIS) Docker Benchmark requirements for secure container configuration and deployment. + icon: check-circle + link: /dhi/explore/security-concepts/cis/ + + grid_concepts_risk: + - title: Common Vulnerabilities and Exposures (CVEs) + description: Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools. + icon: exclamation-circle + link: /dhi/explore/security-concepts/cves/ + - title: Vulnerability Exploitability eXchange (VEX) + description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable. + icon: exclamation-triangle + link: /dhi/explore/security-concepts/vex/ + - title: Software Supply Chain Security + description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface. + icon: shield-check + link: /dhi/explore/security-concepts/sscs/ + - title: Secure Software Development Lifecycle (SSDLC) + description: See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools. + icon: wrench-screwdriver + link: /dhi/explore/security-concepts/ssdlc/ + + grid_concepts_structure: + - title: Distroless images + description: Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components. + icon: squares-2x2 + link: /dhi/explore/security-concepts/distroless/ + - title: glibc and musl support in Docker Hardened Images + description: Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs. + icon: arrows-up-down + link: /dhi/explore/security-concepts/glibc-musl/ + - title: Image immutability + description: Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable. + icon: minus-circle + link: /dhi/explore/security-concepts/immutability/ + - title: Image hardening + description: Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations. + icon: shield-check + link: /dhi/explore/security-concepts/hardening/ + + grid_concepts_verification: + - title: Digests + description: Learn how to use immutable image digests to guarantee consistency and verify the exact Docker Hardened Image you're running. + icon: finger-print + link: /dhi/explore/security-concepts/digests/ + - title: Code signing + description: Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance. + icon: key + link: /dhi/explore/security-concepts/signatures/ +--- + +Docker Hardened Images (DHIs) are built on a foundation of secure software +supply chain practices. This section explains the core concepts behind that +foundation, from signed attestations and immutable digests to standards like SLSA +and VEX. + +Start here if you want to understand how Docker Hardened Images support compliance, +transparency, and security. + + +## Security metadata and attestations + +{{< grid items="grid_concepts_metadata" >}} + +## Compliance standards + +{{< grid items="grid_concepts_compliance" >}} + +## Vulnerability and risk management + +{{< grid items="grid_concepts_risk" >}} + +## Image structure and behavior + +{{< grid items="grid_concepts_structure" >}} + +## Verification and traceability + +{{< grid items="grid_concepts_verification" >}} \ No newline at end of file diff --git a/content/manuals/dhi/explore/security-concepts/attestations.md b/content/manuals/dhi/explore/security-concepts/attestations.md new file mode 100644 index 000000000000..0fde980e854e --- /dev/null +++ b/content/manuals/dhi/explore/security-concepts/attestations.md @@ -0,0 +1,170 @@ +--- +aliases: + - /dhi/core-concepts/attestations/ +title: Attestations +description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results. +keywords: container image attestations, signed sbom, build provenance, slsa compliance, vex document +--- + +Docker Hardened Images (DHIs) and charts include comprehensive, signed security +attestations that verify the image's build process, contents, and security +posture. These attestations are a core part of secure software supply chain +practices and help users validate that an image is trustworthy and +policy-compliant. + +## What is an attestation? + +An attestation is a signed statement that provides verifiable information +about an image or chart, such as how it was built, what's inside it, and what security +checks it has passed. Attestations are typically signed using Sigstore tooling +(such as Cosign), making them tamper-evident and cryptographically verifiable. + +Attestations follow standardized formats (like [in-toto](https://in-toto.io/), +[CycloneDX](https://cyclonedx.org/), and [SLSA](https://slsa.dev/)) and are +attached to the image or chart as OCI-compliant metadata. They can be generated +automatically during image builds or added manually to document extra tests, +scan results, or custom provenance. + +## Why are attestations important? + +Attestations provide critical visibility into the software supply chain by: + +- Documenting *what* went into an image (e.g., SBOMs) +- Verifying *how* it was built (e.g., build provenance) +- Capturing *what security scans* it has passed or failed (e.g., CVE reports, + secrets scans, test results) +- Helping organizations enforce compliance and security policies +- Supporting runtime trust decisions and CI/CD policy gates + +They are essential for meeting industry standards such as SLSA, +and help teams reduce the risk of supply chain attacks by making build and +security data transparent and verifiable. + +## How Docker Hardened Images and charts use attestations + +All DHIs and charts are built using [SLSA Build Level +3](https://slsa.dev/spec/latest/levels) practices, and each image variant is +published with a full set of signed attestations. These attestations allow users +to: + +- Verify that the image or chart was built from trusted sources in a secure environment +- View SBOMs in multiple formats to understand component-level details +- Review scan results to check for vulnerabilities or embedded secrets +- Confirm the build and deployment history of each image + +Attestations are automatically published and associated with each DHI +and chart. They can be inspected using tools like [Docker +Scout](../../how-to/verify.md) or +[Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD +tooling or security platforms. + +## Image attestations + +While every DHI variant includes a set of attestations, the attestations may +vary based on the image variant. For example, some images may include a STIG +scan attestation. The following table lists attestations that may be included with a DHI; the +actual set varies by image variant. To see which attestations are available +for a specific image variant, including the specific predicate type URIs, use +Docker Scout: + +```console +$ docker scout attest list dhi.io/<image>:<tag> +``` + +For more details, see [Verify image attestations](../../how-to/verify.md#verify-image-attestations). + +The **Available in the EU region** column applies only if your organization's +DHI subscription is in the EU region. It shows which attestations are available +for your mirrored repositories in that region. For details, see [EU data +residency](../eu-region.md#attestations-in-the-eu-region). + +| Attestation type | Description | Available in the EU region | +|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | No | +| STIG scan | Results of a STIG scan, with output in HTML and XCCDF formats. | Yes | +| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning. | No | +| VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | No | +| Scout provenance | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details. | No | +| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | No | +| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | Yes | +| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | Yes | +| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../malware-scanning.md). | Yes | +| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | No | +| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | Yes | +| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. | Yes | +| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | Yes | +| FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | Yes | +| DHI Changelog | A record of changes made to the image across versions. | Yes | +| DHI Image Sources | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. | Yes | + +## Package attestations + +In addition to image-level attestations, Docker hardened packages also include +their own attestations. These package-level attestations provide provenance and +build information for individual packages within an image, allowing you to +trace the supply chain at a granular level. + +Package attestations include similar information as image attestations, such as +SLSA provenance, showing how each package was built and what materials were +used. You can extract package information from an image's attestations and then +retrieve the package's own attestations recursively. + +For detailed instructions on how to access and verify package attestations, see +[Package attestations](../../how-to/hardened-packages.md#package-attestations). + +## Helm chart attestations + +Docker Hardened Image (DHI) charts also include comprehensive signed attestations +that provide transparency and verification for your Kubernetes deployments. Like +DHI container images, these charts are built following SLSA Build Level 3 +practices and include extensive security metadata. + +DHI Helm charts include the following attestations. To view the specific predicate +type URIs for these attestations, use Docker Scout: + +```console +$ docker scout attest list dhi.io/<chart>:<version> +``` + +For more details, see [Verify Helm chart attestations](../../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). + +The **Available in the EU region** column applies only if your organization's +DHI subscription is in the EU region. It shows which attestations are available +for your mirrored Helm charts in that region. For details, see [EU data +residency](../eu-region.md#attestations-in-the-eu-region). + +| Attestation type | Description | Available in the EU region | +|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart. | No | +| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart. | No | +| Scout provenance | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters. | No | +| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | No | +| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | Yes | +| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | Yes | +| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../malware-scanning.md). | Yes | +| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | No | +| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | Yes | +| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | Yes | + +## View and verify attestations + +To view and verify attestations, see [Verify a Docker Hardened +Image](../../how-to/verify.md). + +## Add your own attestations + +In addition to the comprehensive attestations provided by Docker Hardened +Images, you can add your own signed attestations when building derivative +images. This is especially useful if you’re building new applications on top of +a DHI and want to maintain transparency, traceability, and trust in your +software supply chain. + +By attaching attestations such as SBOMs, build provenance, or custom metadata, +you can meet compliance requirements, pass security audits, and support policy +evaluation tools like Docker Scout. + +These attestations can then be verified downstream using tools +like Cosign or Docker Scout. + +To learn how to attach custom attestations during the build process, see [Build +attestations](/manuals/build/metadata/attestations.md). diff --git a/content/manuals/dhi/core-concepts/cis.md b/content/manuals/dhi/explore/security-concepts/cis.md similarity index 91% rename from content/manuals/dhi/core-concepts/cis.md rename to content/manuals/dhi/explore/security-concepts/cis.md index 0298a140655e..a4aa644c4aa4 100644 --- a/content/manuals/dhi/core-concepts/cis.md +++ b/content/manuals/dhi/explore/security-concepts/cis.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/cis/ title: CIS Benchmark description: Learn how Docker Hardened Images comply with the CIS Docker Benchmark to help organizations harden container images for secure deployments. keywords: docker cis benchmark, cis docker compliance, cis docker images, docker hardened images, secure container images @@ -31,7 +33,7 @@ configuration. CIS-compliant DHIs are compliant with all controls in Section 4, with the sole exception of the control requiring Docker Content Trust (DCT), which [Docker officially retired](https://www.docker.com/blog/retiring-docker-content-trust/). -Instead, DHIs are [signed](/manuals/dhi/core-concepts/signatures.md) using +Instead, DHIs are [signed](/manuals/dhi/explore/security-concepts/signatures.md) using Cosign, providing an even higher level of authenticity and integrity. By starting from a CIS-compliant DHI, teams can adopt image-level best practices from the benchmark more quickly and confidently. @@ -46,7 +48,7 @@ from the benchmark more quickly and confidently. ## Identify CIS-compliant images CIS-compliant images are labeled as **CIS** in the Docker Hardened Images catalog. -To find them, [search the catalog](../how-to/explore.md) and look for the **CIS** +To find them, [search the catalog](../../how-to/search-evaluate.md) and look for the **CIS** designation on individual listings. ## Get the benchmark diff --git a/content/manuals/dhi/core-concepts/cves.md b/content/manuals/dhi/explore/security-concepts/cves.md similarity index 99% rename from content/manuals/dhi/core-concepts/cves.md rename to content/manuals/dhi/explore/security-concepts/cves.md index da7a1140cb6d..1d7f0576a22e 100644 --- a/content/manuals/dhi/core-concepts/cves.md +++ b/content/manuals/dhi/explore/security-concepts/cves.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/cves/ title: Common Vulnerabilities and Exposures (CVEs) linktitle: CVEs description: Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools. diff --git a/content/manuals/dhi/core-concepts/digests.md b/content/manuals/dhi/explore/security-concepts/digests.md similarity index 99% rename from content/manuals/dhi/core-concepts/digests.md rename to content/manuals/dhi/explore/security-concepts/digests.md index 27bdc244b45d..fe31aafd7c28 100644 --- a/content/manuals/dhi/core-concepts/digests.md +++ b/content/manuals/dhi/explore/security-concepts/digests.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/digests/ title: Image digests description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface. keywords: docker image digest, pull image by digest, immutable container image, secure container reference, multi-platform manifest diff --git a/content/manuals/dhi/core-concepts/distroless.md b/content/manuals/dhi/explore/security-concepts/distroless.md similarity index 95% rename from content/manuals/dhi/core-concepts/distroless.md rename to content/manuals/dhi/explore/security-concepts/distroless.md index c5b8a5d0b698..e886b5e6e388 100644 --- a/content/manuals/dhi/core-concepts/distroless.md +++ b/content/manuals/dhi/explore/security-concepts/distroless.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/distroless/ title: Minimal or distroless images linktitle: Distroless images description: Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components. @@ -11,9 +13,9 @@ stripped of unnecessary components such as package managers, shells, or even the underlying operating system distribution. Docker Hardened Images (DHI) embrace this minimal approach to reduce vulnerabilities and enforce secure software delivery. [Docker Official -Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) +Images](../../../docker-hub/image-library/trusted-content.md#docker-official-images) and [Docker Verified Publisher -Images](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) +Images](../../../docker-hub/image-library/trusted-content.md#verified-publisher-images) follow similar best practices for minimalism and security but may not be as stripped down to ensure compatibility with a wider range of use cases. diff --git a/content/manuals/dhi/core-concepts/fips.md b/content/manuals/dhi/explore/security-concepts/fips.md similarity index 95% rename from content/manuals/dhi/core-concepts/fips.md rename to content/manuals/dhi/explore/security-concepts/fips.md index 3e425e645513..f6bc1b140bfc 100644 --- a/content/manuals/dhi/core-concepts/fips.md +++ b/content/manuals/dhi/explore/security-concepts/fips.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/fips/ title: FIPS description: Learn how Docker Hardened Images support FIPS 140 through validated cryptographic modules to help organizations meet compliance requirements. keywords: docker fips, fips 140 images, fips docker images, docker compliance, secure container images @@ -66,9 +68,9 @@ compliance requirements by incorporating components that meet the standard. Docker Hardened Images that support FIPS are marked as **FIPS** compliant in the Docker Hardened Images catalog. -To find DHI repositories with FIPS image variants, [search the catalog](../how-to/explore.md) and: +To find DHI repositories with FIPS image variants, [search the catalog](../../how-to/search-evaluate.md) and: -- Use the **FIPS** filter on the catalog page +- Use the **Compliance** filter on the catalog page and select **FIPS** - Look for **FIPS** compliant on individual image listings These indicators help you quickly locate repositories that support FIPS-based @@ -77,7 +79,7 @@ ending with `-fips`, such as `3.13-fips`. ## Use a FIPS variant -To use a FIPS variant, you must [mirror](../how-to/mirror.md) the repository +To use a FIPS variant, you must [mirror](../../how-to/mirror.md) the repository and then pull the FIPS image from your mirrored repository. ## View the FIPS attestation diff --git a/content/manuals/dhi/core-concepts/glibc-musl.md b/content/manuals/dhi/explore/security-concepts/glibc-musl.md similarity index 98% rename from content/manuals/dhi/core-concepts/glibc-musl.md rename to content/manuals/dhi/explore/security-concepts/glibc-musl.md index 1ef7cdfa45f4..9a6a865c32b5 100644 --- a/content/manuals/dhi/core-concepts/glibc-musl.md +++ b/content/manuals/dhi/explore/security-concepts/glibc-musl.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/glibc-musl/ title: glibc and musl support in Docker Hardened Images linktitle: glibc and musl description: Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs. diff --git a/content/manuals/dhi/core-concepts/hardening.md b/content/manuals/dhi/explore/security-concepts/hardening.md similarity index 95% rename from content/manuals/dhi/core-concepts/hardening.md rename to content/manuals/dhi/explore/security-concepts/hardening.md index 105b527eff66..ddf6c7fb7067 100644 --- a/content/manuals/dhi/core-concepts/hardening.md +++ b/content/manuals/dhi/explore/security-concepts/hardening.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/hardening/ title: Base image hardening linktitle: Hardening description: Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations. @@ -17,9 +19,9 @@ privileges inside the container. Hardening also involves applying best practices like running as a non-root user, reducing writable surfaces, and ensuring consistency through immutability. While [Docker Official -Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) +Images](../../../docker-hub/image-library/trusted-content.md#docker-official-images) and [Docker Verified Publisher -Images](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) +Images](../../../docker-hub/image-library/trusted-content.md#verified-publisher-images) follow best practices for security, they may not be as hardened as Docker Hardened Images, as they are designed to support a broader range of use cases. diff --git a/content/manuals/dhi/core-concepts/immutability.md b/content/manuals/dhi/explore/security-concepts/immutability.md similarity index 98% rename from content/manuals/dhi/core-concepts/immutability.md rename to content/manuals/dhi/explore/security-concepts/immutability.md index c6cfb1144684..f03f3261fc6c 100644 --- a/content/manuals/dhi/core-concepts/immutability.md +++ b/content/manuals/dhi/explore/security-concepts/immutability.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/immutability/ title: Immutable infrastructure linktitle: Immutability description: Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable. diff --git a/content/manuals/dhi/core-concepts/provenance.md b/content/manuals/dhi/explore/security-concepts/provenance.md similarity index 98% rename from content/manuals/dhi/core-concepts/provenance.md rename to content/manuals/dhi/explore/security-concepts/provenance.md index 5c8adcb425e4..7db3c9e72917 100644 --- a/content/manuals/dhi/core-concepts/provenance.md +++ b/content/manuals/dhi/explore/security-concepts/provenance.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/provenance/ title: Image provenance description: Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA. keywords: image provenance, container build traceability, slsa compliance, signed container image, software supply chain trust diff --git a/content/manuals/dhi/explore/security-concepts/sbom.md b/content/manuals/dhi/explore/security-concepts/sbom.md new file mode 100644 index 000000000000..07360ee072d6 --- /dev/null +++ b/content/manuals/dhi/explore/security-concepts/sbom.md @@ -0,0 +1,96 @@ +--- +aliases: + - /dhi/core-concepts/sbom/ +title: Software Bill of Materials (SBOMs) +linktitle: SBOMs +description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance. +keywords: sbom docker image, software bill of materials, signed sbom, container sbom verification, sbom compliance +--- + +## What is an SBOM? + +An SBOM is a detailed inventory that lists all components, libraries, and +dependencies used in building a software application. It provides transparency +into the software supply chain by documenting each component's version, origin, +and relationship to other components. Think of it as a "recipe" for your +software, detailing every ingredient and how they come together. + +Metadata included in an SBOM for describing software artifacts may include: + +- Name of the artifact +- Version +- License type +- Authors +- Unique package identifier + +## Why are SBOMs important? + +In today's software landscape, applications often comprise numerous components +from various sources, including open-source libraries, third-party services, and +proprietary code. This complexity can obscure visibility into potential +vulnerabilities and complicate compliance efforts. SBOMs address these +challenges by providing a detailed inventory of all components within an +application. + + +The significance of SBOMs is underscored by several key factors: + +- Enhanced transparency: SBOMs offer a comprehensive view of all components that + constitute an application, enabling organizations to identify and assess risks + associated with third-party libraries and dependencies. + +- Proactive vulnerability management: By maintaining an up-to-date SBOM, + organizations can swiftly identify and address vulnerabilities in software + components, reducing the window of exposure to potential exploits. + +- Regulatory compliance: Many regulations and industry standards now require + organizations to maintain control over the software components they use. An + SBOM facilitates compliance by providing a clear and accessible record. + +- Improved incident response: In the event of a security breach, an SBOM + enables organizations to quickly identify affected components and take + appropriate action, minimizing potential damage. + +## Docker Hardened Image SBOMs + +Docker Hardened Images have SBOMs, ensuring that every component +in the image is documented and verifiable. These SBOMs are cryptographically +signed, providing a tamper-evident record of the image's contents. This +integration simplifies audits and enhances trust in the software supply chain. + +## View SBOMs in Docker Hardened Images + +To view the SBOM of a Docker Hardened Image, you can use the `docker scout sbom` +command. Replace `<image-name>:<tag>` with the image name and tag. + +```console +$ docker scout sbom dhi.io/<image-name>:<tag> +``` + +## Verify the SBOM of a Docker Hardened Image + +Since Docker Hardened Images come with signed SBOMs, you can use Docker Scout to +verify the authenticity and integrity of the SBOM attached to the image. This +ensures that the SBOM has not been tampered with and that the image's contents +are trustworthy. + +To verify the SBOM of a Docker Hardened Image using Docker Scout, use the following command: + +```console +$ docker scout attest get dhi.io/<image-name>:<tag> \ + --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform <platform> +``` + +For example, to verify the SBOM attestation for the `node:20.19-debian12` image: + +```console +$ docker scout attest get dhi.io/node:20.19-debian12 \ + --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform linux/amd64 +``` + +## Resources + +For more details about SBOM attestations and Docker Build, see [SBOM +attestations](/build/metadata/attestations/sbom/). + +To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../../scout/how-tos/view-create-sboms.md). \ No newline at end of file diff --git a/content/manuals/dhi/core-concepts/signatures.md b/content/manuals/dhi/explore/security-concepts/signatures.md similarity index 98% rename from content/manuals/dhi/core-concepts/signatures.md rename to content/manuals/dhi/explore/security-concepts/signatures.md index 6922f3507cf2..d766d850ae2d 100644 --- a/content/manuals/dhi/core-concepts/signatures.md +++ b/content/manuals/dhi/explore/security-concepts/signatures.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/signatures/ title: Code signing description: Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance. keywords: container image signing, cosign docker image, verify image signature, signed container image, sigstore cosign diff --git a/content/manuals/dhi/core-concepts/slsa.md b/content/manuals/dhi/explore/security-concepts/slsa.md similarity index 99% rename from content/manuals/dhi/core-concepts/slsa.md rename to content/manuals/dhi/explore/security-concepts/slsa.md index ad4b254bdab7..303da61f8ad0 100644 --- a/content/manuals/dhi/core-concepts/slsa.md +++ b/content/manuals/dhi/explore/security-concepts/slsa.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/slsa/ title: Supply-chain Levels for Software Artifacts (SLSA) linktitle: SLSA description: Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds. diff --git a/content/manuals/dhi/core-concepts/sscs.md b/content/manuals/dhi/explore/security-concepts/sscs.md similarity index 98% rename from content/manuals/dhi/core-concepts/sscs.md rename to content/manuals/dhi/explore/security-concepts/sscs.md index 8606b6c377ba..fab3f1dafe5c 100644 --- a/content/manuals/dhi/core-concepts/sscs.md +++ b/content/manuals/dhi/explore/security-concepts/sscs.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/sscs/ title: Software Supply Chain Security linktitle: Software Supply Chain Security description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface. diff --git a/content/manuals/dhi/core-concepts/ssdlc.md b/content/manuals/dhi/explore/security-concepts/ssdlc.md similarity index 97% rename from content/manuals/dhi/core-concepts/ssdlc.md rename to content/manuals/dhi/explore/security-concepts/ssdlc.md index c1d2c864c166..88221ae0f3fd 100644 --- a/content/manuals/dhi/core-concepts/ssdlc.md +++ b/content/manuals/dhi/explore/security-concepts/ssdlc.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/ssdlc/ title: Secure Software Development Lifecycle linktitle: SSDLC description: See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools. @@ -37,7 +39,7 @@ Docker provides tools and secure content that make SSDLC practices easier to adopt across the container lifecycle. With [Docker Hardened Images](../_index.md) (DHIs), [Docker Debug](/reference/cli/docker/debug/), and [Docker -Scout](../../../manuals/scout/_index.md), teams can add security without losing +Scout](../../../scout/_index.md), teams can add security without losing velocity. ### Plan and design diff --git a/content/manuals/dhi/core-concepts/stig.md b/content/manuals/dhi/explore/security-concepts/stig.md similarity index 92% rename from content/manuals/dhi/core-concepts/stig.md rename to content/manuals/dhi/explore/security-concepts/stig.md index 632654054637..60beba309509 100644 --- a/content/manuals/dhi/core-concepts/stig.md +++ b/content/manuals/dhi/explore/security-concepts/stig.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/stig/ title: STIG description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. keywords: docker stig, stig-ready images, stig guidance, openscap docker, secure container images @@ -58,23 +60,23 @@ Docker Hardened Images that include STIG scan results are labeled as **STIG** in the Docker Hardened Images catalog. To find DHI repositories with STIG image variants, [explore -images](../how-to/explore.md#image-variants) and: +images](../../tools/hub.md#images-page) and: -- Use the **STIG** filter on the catalog page +- Use the **Compliance** filter on the catalog page and select **STIG** - Look for **STIG** labels on individual image listings -To find a STIG image variant within a repository, go to the **Tags** tab in the +To find a STIG image variant within a repository, go to the **Images** tab in the repository, and find images labeled with **STIG** in the **Compliance** column. ## Use a STIG variant -To use a STIG variant, you must [mirror](../how-to/mirror.md) the repository +To use a STIG variant, you must [mirror](../../how-to/mirror.md) the repository and then pull the STIG image from your mirrored repository. ## View and verify STIG scan results Docker provides a signed [STIG scan -attestation](../core-concepts/attestations.md) for each STIG-ready image. +attestation](attestations.md) for each STIG-ready image. These attestations include: - A summary of the scan results, including the number of passed, failed, and not diff --git a/content/manuals/dhi/core-concepts/vex.md b/content/manuals/dhi/explore/security-concepts/vex.md similarity index 86% rename from content/manuals/dhi/core-concepts/vex.md rename to content/manuals/dhi/explore/security-concepts/vex.md index 33ffe390229b..cd25e86b191a 100644 --- a/content/manuals/dhi/core-concepts/vex.md +++ b/content/manuals/dhi/explore/security-concepts/vex.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/vex/ title: Vulnerability Exploitability eXchange (VEX) linktitle: VEX description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable. @@ -24,17 +26,20 @@ VEX support, see [Scan Docker Hardened Images](/manuals/dhi/how-to/scan.md). ## VEX status reference Each VEX statement includes a `status` field that records Docker's -exploitability assessment for a given CVE and image. DHI uses three of the four -OpenVEX status values. +exploitability assessment for a given CVE and image. OpenVEX defines four +status values. DHI uses three of them: | Status | Meaning | |---|---| | `not_affected` | The CVE was reported against a package in the image, but Docker has assessed it is not exploitable as shipped | | `under_investigation` | Docker is aware of the CVE and is actively evaluating whether it affects the image | | `affected` | Docker has confirmed the CVE is exploitable in the image and a fix is not yet available | +| `fixed` | The vulnerability has been remediated in this version. DHI does not use this status (see below). | You can view the VEX statements for any DHI using Docker Scout. See [Scan Docker -Hardened Images](/manuals/dhi/how-to/scan.md). +Hardened Images](/manuals/dhi/how-to/scan.md). To query suppressed CVEs +programmatically by image digest, see [Query suppressed CVEs for a DHI by +digest](/manuals/dhi/how-to/vex-api.md). ### `not_affected` justification codes diff --git a/content/manuals/dhi/explore/what.md b/content/manuals/dhi/explore/what.md index b834f88113a2..962276f8858e 100644 --- a/content/manuals/dhi/explore/what.md +++ b/content/manuals/dhi/explore/what.md @@ -29,7 +29,8 @@ A hardened image is a container image that has been deliberately minimized and secured to reduce vulnerabilities and meet stringent security and compliance requirements. Unlike standard images, which may include non-essential components that increase risk, hardened images are streamlined to include only what’s -needed to run your application securely. +needed to run your application securely. For a deeper look at the techniques +involved, see [Base image hardening](security-concepts/hardening.md). ## Benefits of hardened images @@ -55,25 +56,25 @@ so you don’t have to. ## How Docker Hardened Images differ from generic hardened images - SLSA-compliant builds: Docker Hardened Images are built to meet [SLSA Build - Level 3](../core-concepts/slsa.md), ensuring a tamper-resistant, verifiable, + Level 3](security-concepts/slsa.md), ensuring a tamper-resistant, verifiable, and auditable build process that protects against supply chain threats. - Distroless approach: Unlike traditional base images that bundle an entire OS with shells, package managers, and debugging tools, [distroless - images](../core-concepts/distroless.md) retain only the minimal OS components + images](security-concepts/distroless.md) retain only the minimal OS components required to run your application. By excluding unnecessary tooling and libraries, they reduce the attack surface by up to 95% and can improve performance and image size. - Continuous maintenance: All DHIs are continuously monitored and updated to - maintain near-zero known exploitable [CVEs](../core-concepts/cves.md), helping + maintain near-zero known exploitable [CVEs](security-concepts/cves.md), helping your teams avoid patch fatigue and surprise alerts. - Compliance-ready: Each image includes cryptographically signed metadata: - - [SBOMs](../core-concepts/sbom.md) that show what's in the image - - [VEX documents](../core-concepts/vex.md) to identify which vulnerabilities + - [SBOMs](security-concepts/sbom.md) that show what's in the image + - [VEX documents](security-concepts/vex.md) to identify which vulnerabilities are actually exploitable - - [Build provenance](../core-concepts/provenance.md) that proves how and where + - [Build provenance](security-concepts/provenance.md) that proves how and where the image was built - Compatibility-focused design: Docker Hardened Images provide a minimal runtime diff --git a/content/manuals/dhi/features.md b/content/manuals/dhi/features.md deleted file mode 100644 index f08b4d782414..000000000000 --- a/content/manuals/dhi/features.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Docker Hardened Images features -linktitle: Features -description: Docker Hardened Images provide total transparency, minimal attack surface, and enterprise-grade security for every application—free and open source. -weight: 5 -aliases: - - /dhi/features/secure/ - - /dhi/features/integration/ - - /dhi/features/support/ - - /dhi/features/patching/ - - /dhi/features/flexible/ - - /dhi/features/helm/ ---- - -Docker Hardened Images (DHI) are minimal, secure, and production-ready container -base and application images maintained by Docker. Designed to reduce -vulnerabilities and simplify compliance, DHI integrates easily into your -existing Docker-based workflows with little to no retooling required. - -DHI provides security for everyone: - -- [DHI Community](#dhi-community-features) provides core security features available to - everyone with no licensing restrictions under Apache 2.0. -- [DHI Select and DHI Enterprise](#dhi-select-and-enterprise-features) add SLA-backed - security updates, FIPS/STIG compliance variants, and customization - capabilities, with DHI Enterprise offering unlimited customization, full - catalog access, and optional Extended Lifecycle Support (ELS) for post-EOL - coverage. - -## DHI Community features - -DHI's core features are open and free to use, share, and build on with no -licensing surprises, backed by an Apache 2.0 license. - -### Security by default - -- Near-zero CVEs: Continuously scanned and patched to maintain minimal known - exploitable vulnerabilities, with no SLA-backed time commitments for DHI Community users -- Minimal attack surface: Distroless variants reduce attack surface by up to 95% by removing unnecessary components -- Non-root execution: Run as non-root by default, following the principle of least privilege -- Transparent vulnerability reporting: Every CVE is visible and assessed using public data—no suppressed feeds or proprietary scoring - -### Hardened system packages - -Docker Hardened Images maintain supply chain integrity throughout the entire -image stack with hardened system packages: - -- Source-built packages: For supported distributions, system packages are built - from source code by Docker -- Cryptographic signatures: Every package is cryptographically signed and verified -- Supply chain security: Eliminates risk from potentially compromised public packages - -Hardened system packages are included in supported distributions of DHI images. -Community users can also configure their package manager to use Docker's public -hardened package repository in their own images for the same packages included -in the base images. See [Use hardened system packages](./how-to/hardened-packages.md) -for details. - -### Total transparency - -Every image includes complete, verifiable security metadata: - -- SLSA Build Level 3 provenance: Verifiable, tamper-resistant builds that meet supply chain security standards -- Signed SBOMs: Complete Software Bill of Materials for every component -- VEX statements: Vulnerability Exploitability eXchange documents provide context about known CVEs -- Cryptographic signatures: All images and metadata are signed for authenticity - -### Built for developers - -- Familiar foundations: Built on Alpine and Debian, requiring minimal changes to adopt -- glibc and musl support: Available in both variants for broad application compatibility -- Development and runtime variants: Use dev images for building, minimal runtime images for production -- Drop-in compatibility: Works seamlessly with existing Docker workflows, CI/CD pipelines, and tools - -### Continuous maintenance - -- Automatic patching: Images are rebuilt and updated when upstream security - patches become available, with no SLA-backed time commitments for DHI - Community users -- Scanner integration: Direct integration with scanners and other security platforms - -### Kubernetes and Helm chart support - -Docker Hardened Image (DHI) charts are Docker-provided Helm charts built from -upstream sources, designed for compatibility with Docker Hardened Images. These -charts are available as OCI artifacts within the DHI catalog on Docker Hub. DHI -charts are robustly tested after building to ensure they work out-of-the-box -with Docker Hardened Images. This removes friction in migration and reduces -developer workload in implementing the charts, ensuring seamless compatibility. - -Like the hardened images, DHI charts incorporate multiple layers of security -metadata to ensure transparency and trust: - -- SLSA Level 3 compliance: Each chart is built with Docker's SLSA Build Level 3 - system, including a detailed build provenance, and meeting the standards set - by the Supply-chain Levels for Software Artifacts (SLSA) framework. -- Software Bill of Materials (SBOMs): Comprehensive SBOMs are provided, - detailing all components referenced within the chart to facilitate - vulnerability management and compliance audits. -- Cryptographic signing: All associated metadata is cryptographically signed by - Docker, ensuring integrity and authenticity. -- Hardened configuration: Charts automatically reference Docker hardened images, - ensuring security in deployments. - -## DHI Select and Enterprise features - -For organizations with strict security requirements, regulatory demands, or -operational needs, DHI Select and Enterprise deliver additional capabilities. - -DHI Select offers customizations, compliance variants, and SLA-backed updates -for teams and organizations with production workloads. DHI Enterprise includes -everything in Select with unlimited customizations, plus an optional Extended -Lifecycle Support add-on and full catalog access for large enterprises with -advanced security needs. - -For a detailed comparison, see [Docker Hardened Images subscription -comparison](https://www.docker.com/products/hardened-images/#compare). - -### SLA-backed security {tier="DHI Select or DHI Enterprise"} - -- CVE remediation SLA: 7-day SLA for critical and high severity vulnerabilities -- Continuous patching: Regular security updates backed by SLA commitments -- Enterprise support: Access to Docker's support team for mission-critical applications - -For complete details, see the [Support Service Level Agreement](https://docs.docker.com/go/dhi-sla/). - -### Compliance variants {tier="DHI Select or DHI Enterprise"} - -- FIPS-enabled images: For regulated industries and government systems -- STIG-ready images: Meet DoD Security Technical Implementation Guide requirements - -### Customization and control {tier="DHI Select or DHI Enterprise"} - -- Build custom images: Add your own packages, tools, certificates, and configurations - - DHI Select: Up to 5 customizations - - DHI Enterprise: Unlimited customizations -- Hardened packages: Access to additional compliance-specific packages (such as - FIPS variants) and Docker-patched packages not available in the public repository - - DHI Select: Add these packages through the customization UI when customizing hardened images - - DHI Enterprise: Add these packages through the customization UI, or configure - your package manager to use the enterprise package repository in your own images -- Secure build infrastructure: Customizations built on Docker's trusted infrastructure -- Full chain of trust: Customized images maintain provenance and cryptographic signing -- Automatic updates: Custom images are automatically rebuilt when base images are patched - -### Extended Lifecycle Support {tier="DHI Enterprise add-on"} - -- Post-EOL security coverage: Continue receiving patches for years after upstream support ends -- Continuous compliance: Updated SBOMs, provenance, and signing for audit requirements -- Production continuity: Keep production running securely without forced migrations - -## Learn more - -- [Explore how DHI images are built and more](/dhi/explore/) -- [Get started using DHIs](/dhi/get-started/) -- <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_dhi_features" class="link" rel="noopener">Contact Docker for DHI Enterprise</a> diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 9ad8d9981bc6..00cedadc7135 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -31,7 +31,7 @@ Docker account, pull and run an image, and compare it with a Docker Official Ima 3. Select the Python repository to view its details. Continue to the next step to pull and run the image. To dive deeper into searching -and evaluating images, see [Search and evaluate Docker Hardened Images](./how-to/explore.md). +and evaluating images, see [Search and evaluate Docker Hardened Images](./how-to/search-evaluate.md). ## Step 2: Pull and run the image @@ -121,7 +121,7 @@ The `## Overview` section of the output looks similar to the following: Docker maintains near-zero CVEs in Docker Hardened Images. For DHI Select and Enterprise subscriptions, when new CVEs are discovered, the CVEs are remediated within the industry-leading SLA time frame. Learn more about the [SLA-backed -security features](./features.md#sla-backed-security). +security features](./_index.md#sla-backed-security). This comparison shows that the Docker Hardened Image: @@ -129,7 +129,7 @@ This comparison shows that the Docker Hardened Image: - Reduces size: From 412 MB down to 35 MB (91% reduction) - Minimizes packages: From 610 packages down to 80 (87% reduction) -To dive deeper into comparing images see [Search and evaluate Docker Hardened Images](./how-to/explore.md#compare-and-evaluate-images). +To dive deeper into comparing images see [Search and evaluate Docker Hardened Images](./how-to/search-evaluate.md#compare-and-evaluate-images). ## What's next diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 2b1177955014..79c8d0af758d 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -7,18 +7,14 @@ aliases: params: grid_discover: - title: Search and evaluate Docker Hardened Images - description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub. + description: Learn how to find and compare image repositories, variants, and metadata in the DHI catalog. icon: globe-alt - link: /dhi/how-to/explore/ + link: /dhi/how-to/search-evaluate/ grid_adopt: - title: Get started with DHI Select and Enterprise description: Learn how to mirror repositories, customize images, and access compliance variants with DHI Select and Enterprise subscriptions. icon: rocket-launch link: /dhi/how-to/select-enterprise/ - - title: Use the DHI CLI - description: Use the dhictl command-line tool to manage and interact with Docker Hardened Images. - icon: command-line - link: /dhi/how-to/cli/ - title: Mirror a Docker Hardened Image repository description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry. icon: arrows-right-left @@ -48,11 +44,20 @@ params: description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy. icon: bug-ant link: /dhi/how-to/scan/ + - title: Query VEX for a Docker Hardened Image + description: Use the DHI GraphQL API to fetch VEX statements and suppressed CVEs for a Docker Hardened Image by digest, at scale. + icon: bug-ant + link: /dhi/how-to/vex-api/ grid_govern: - - title: Enforce Docker Hardened Image usage with policies - description: Learn how to use image policies with Docker Scout for Docker Hardened Images. + - title: Apply Docker Hardened Image policies to your images + description: Learn how to hold your own images to Docker Hardened Image security and compliance standards using the Docker Scout CLI. icon: shield-check link: /dhi/how-to/policies/ + grid_troubleshoot: + - title: Troubleshoot + description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access. + icon: question-mark-circle + link: /dhi/how-to/troubleshoot/ --- This section provides practical, task-based guidance for working with Docker @@ -96,3 +101,9 @@ Enforce policies to maintain security and compliance. {{< grid items="grid_govern" >}} + +## Troubleshoot + +{{< grid + items="grid_troubleshoot" +>}} diff --git a/content/manuals/dhi/how-to/build.md b/content/manuals/dhi/how-to/build.md index 56cb45aebac3..d8b4f141c9a2 100644 --- a/content/manuals/dhi/how-to/build.md +++ b/content/manuals/dhi/how-to/build.md @@ -46,6 +46,7 @@ The frontend version corresponds to the base distribution: |---------------------|----------------------------------------| | Alpine 3.22 | `# syntax=dhi.io/build:2-alpine3.22` | | Alpine 3.23 | `# syntax=dhi.io/build:2-alpine3.23` | +| Alpine 3.24 | `# syntax=dhi.io/build:2-alpine3.24` | | Debian 12 (Bookworm)| `# syntax=dhi.io/build:2-debian12` | | Debian 13 (Trixie) | `# syntax=dhi.io/build:2-debian13` | diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md deleted file mode 100644 index 18a71245312c..000000000000 --- a/content/manuals/dhi/how-to/cli.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: Use the DHI CLI -linkTitle: Use the CLI -weight: 50 -keywords: docker dhi, CLI, command line, docker hardened images -description: Learn how to install and use docker dhi, the command-line interface for managing Docker Hardened Images. ---- - -The `docker dhi` command-line interface (CLI) is a tool for managing Docker Hardened Images: -- Browse the catalog of available DHI images and their metadata -- View attestations for DHI images, including SBOMs and provenance -- Mirror DHI images to your Docker Hub organization -- Create and manage customizations of DHI images -- Generate authentication for enterprise package repositories -- Monitor customization builds - -## Installation - -The `docker dhi` CLI is available in [Docker Desktop](https://docs.docker.com/desktop/) version 4.65 and later. -You can also install the standalone `dhictl` binary. - -### Docker Desktop - -The `docker dhi` command is included in Docker Desktop 4.65 and later. No additional installation is required. - -### Standalone binary - -1. Download the `dhictl` binary for your platform from the - [releases](https://github.com/docker-hardened-images/dhictl/releases) page. -2. Move it to a directory in your `PATH`: - - `mv dhictl /usr/local/bin/` on _Linux_ and _macOS_ - - Move `dhictl.exe` to a directory in your `PATH` on _Windows_ - -## Usage - -Every command has built-in help accessible with the `--help` flag: - -```console -$ docker dhi --help -$ docker dhi catalog list --help -``` - -### Browse the DHI catalog - -List all available DHI images: - -```console -$ docker dhi catalog list -``` - -Filter by type, name, or compliance: - -```console -$ docker dhi catalog list --type image -$ docker dhi catalog list --filter golang -$ docker dhi catalog list --fips -$ docker dhi catalog list --stig -``` - -Get details of a specific image, including available tags and CVE counts: - -```console -$ docker dhi catalog get <image-name> -``` - -### View attestations - -List all attestations attached to a DHI image: - -```console -$ docker dhi attestation list dhi/nginx:1.27 -$ docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64 -$ docker dhi attestation list dhi/nginx:1.27 --predicate-type https://slsa.dev/provenance/v1 -$ docker dhi attestation list dhi/nginx:1.27 --json -``` - -Get a specific attestation by its referrer digest: - -```console -$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> -$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> -o provenance.json -``` - -Display the SPDX SBOM for an image: - -```console -$ docker dhi attestation sbom dhi/nginx:1.27 -$ docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64 -``` - -### Mirror DHI images - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -Start mirroring one or more DHI images to your Docker Hub organization: - -```console -$ docker dhi mirror start --org my-org \ - dhi/golang,my-org/dhi-golang \ - dhi/nginx,my-org/dhi-nginx \ - dhi/prometheus-chart,my-org/dhi-prometheus-chart -``` - -Mirror with dependencies: - -```console -$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies -``` - -List mirrored images in your organization: - -```console -$ docker dhi mirror list --org my-org -``` - -Filter mirrored images by name or type: - -```console -$ docker dhi mirror list --org my-org --filter python -$ docker dhi mirror list --org my-org --type image -$ docker dhi mirror list --org my-org --type helm-chart -``` - -Stop mirroring one or more images: - -```console -$ docker dhi mirror stop dhi-golang --org my-org -$ docker dhi mirror stop dhi-python dhi-golang --org my-org -``` - -Stop mirroring and delete the repositories: - -```console -$ docker dhi mirror stop dhi-golang --org my-org --delete -$ docker dhi mirror stop dhi-golang --org my-org --delete --force -``` - -### Customize DHI images - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -The CLI can be used to create and manage DHI image customizations. For detailed -instructions on creating customizations using the GUI, see [Customize a Docker -Hardened Image](./customize.md). - -The following is a quick reference for CLI commands. For complete details on all -options and flags, see the -[CLI reference](/reference/cli/docker/dhi/). - -```console -# Prepare a single customization scaffold -$ docker dhi customization prepare golang 1.25 \ - --org my-org \ - --destination my-org/dhi-golang \ - --name "golang with git" \ - > my-customization.yaml - -# Prepare a bulk customization scaffold (pipe JSON array via stdin) -$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \ - | docker dhi customization prepare --name "golang with git" --org my-org \ - > my-customization.yaml - -# Create a customization -$ docker dhi customization create my-customization.yaml --org my-org - -# Create with flag overrides (flags take precedence over the YAML file) -$ docker dhi customization create my-customization.yaml --org my-org \ - --destination my-org/dhi-golang \ - --name "golang with git" - -# List customizations -$ docker dhi customization list --org my-org - -# Filter customizations by name, repository, or source -$ docker dhi customization list --org my-org --filter git -$ docker dhi customization list --org my-org --repo dhi-golang -$ docker dhi customization list --org my-org --source golang - -# Get a customization by ID -$ docker dhi customization get <id> --org my-org - -# Update a customization -# The YAML file must include the 'id' field to identify the customization to update -$ docker dhi customization edit my-customization.yaml --org my-org - -# Delete a customization by ID -$ docker dhi customization delete <id> --org my-org - -# Delete multiple customizations -$ docker dhi customization delete <id1> <id2> --org my-org - -# Delete without confirmation prompt -$ docker dhi customization delete <id> --org my-org --force -``` - -For a complete reference of all YAML fields, see -[Image customization YAML file](/dhi/how-to/customize/#image-customization-yaml-file). - -### Enterprise package authentication - -{{< summary-bar feature_name="Docker Hardened Images Enterprise" >}} - -Generate authentication credentials for accessing the enterprise hardened -package repository. These credentials are used when configuring your package -manager to install compliance and security-patched packages in your own images. For detailed -instructions, see [Enterprise -repository](./hardened-packages.md#enterprise-repository). - -For Alpine-based images: - -```console -$ docker dhi auth apk -``` - -For Debian-based images: - -```console -$ docker dhi auth deb -``` - -### Monitor customization builds - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -List builds for a customization: - -```console -$ docker dhi customization build list <customization-id> --org my-org -$ docker dhi customization build list <customization-id> --org my-org --json -``` - -Get details of a specific build: - -```console -$ docker dhi customization build get <customization-id> <build-id> --org my-org -$ docker dhi customization build get <customization-id> <build-id> --org my-org --json -``` - -View build logs: - -```console -$ docker dhi customization build logs <customization-id> <build-id> --org my-org -$ docker dhi customization build logs <customization-id> <build-id> --org my-org --json -``` - -### JSON output - -Most list and get commands support a `--json` flag for machine-readable output: - -```console -$ docker dhi catalog list --json -$ docker dhi catalog get golang --json -$ docker dhi attestation list dhi/nginx:1.27 --json -$ docker dhi mirror list --org my-org --json -$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --json -$ docker dhi customization list --org my-org --json -$ docker dhi customization build list <customization-id> --org my-org --json -``` - -## Configuration - -The `docker dhi` CLI can be configured with a YAML file located at: -- `$HOME/.config/dhictl/config.yaml` on _Linux_ and _macOS_ -- `%USERPROFILE%\.config\dhictl\config.yaml` on _Windows_ - -If `$XDG_CONFIG_HOME` is set, the configuration file is located at `$XDG_CONFIG_HOME/dhictl/config.yaml` (see the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/spec/latest/)). - -Available configuration options: - -| Option | Environment Variable | Description | -|-------------|----------------------|---------------------------------------------------------------------------------------------------------------------------| -| `org` | `DHI_ORG` | Default Docker Hub organization for mirror and customization commands. | -| `api_token` | `DHI_API_TOKEN` | Docker token for authentication. You can generate a token in your [Docker Hub account settings](https://hub.docker.com/). | - -Environment variables take precedence over configuration file values. diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 0f6e2374bb02..687a638a72b0 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -16,8 +16,9 @@ add OCI artifacts (such as custom certificates or additional tools), and configure settings. For charts, this lets you customize the image references. Your customizations stay secure automatically. When the base Docker Hardened -Image or chart receives a security patch or your OCI artifacts are updated, -Docker automatically rebuilds your customizations in the background. This +Image or chart receives a security patch, your OCI artifacts are updated, or a +[hardened system package](./hardened-packages.md) you added is updated, Docker +automatically rebuilds your customizations in the background. This ensures continuous compliance and protection by default, with no manual work required. The rebuilt artifacts are signed and attested to the same SLSA Build Level 3 standard as the base images and charts, ensuring a secure and verifiable @@ -66,8 +67,8 @@ You can create customizations using either the DHI CLI or the Docker Hub web int image. The packages available in the drop-down are OS system packages for the - selected image variant. For version 3.23 Alpine-based images, these are - hardened packages that have been built from source by Docker with + selected image variant. For version 3.23 and later Alpine-based images, + these are hardened packages that have been built from source by Docker with cryptographic signatures and full supply chain security. For version 3.22 Alpine-based images and Debian-based images, these are standard system packages. @@ -81,8 +82,7 @@ You can create customizations using either the DHI CLI or the Docker Hub web int built and pushed to a repository in the same namespace as the mirrored DHI. For example, you can add a custom root CA certificate or another image that contains a tool you need, like adding Python to a Node.js - image. For more details on how to create an OCI artifact image, see - [Create an OCI artifact image](#create-an-oci-artifact-image). + image. You can add multiple OCI artifact images to a single customization. When you add more than one, they're applied in the order you add them in the @@ -102,18 +102,38 @@ You can create customizations using either the DHI CLI or the Docker Hub web int > image build still succeeds, but you may have issues when running the > image. - 1. In the **Scripts** section, you can add, edit, or remove scripts. + For more details, see [OCI artifacts](#oci-artifacts). + + 1. In the **Files** section, you can add, edit, or remove files. - Scripts let you add files to the container image that you can access at runtime. They are not executed during - the build process. This is useful for services that require pre-start initialization, such as setup scripts or + Files let you add static content to the container image that you can + access at runtime, such as configuration files or setup scripts. Files + are not executed during the build process. This is useful for services + that require initialization before they start, such as setup scripts or file writes to directories like `/var/lock` or `/out`. You must specify the following: - - The path where the script will be placed - - The script content - - The UID and GID ownership of the script - - The octal file permissions of the script + - The path where the file will be placed + - The file content + - The UID and GID ownership of the file + - The octal file permissions of the file + + > [!NOTE] + > + > If your organization's DHI subscription is in the EU region, the + > **Add** option in the **Files** section is greyed out. File content + > isn't supported in the EU region. For details, see [EU data + > residency](../explore/eu-region.md). + + 1. In the **Symlinks** section, you can add, edit, or remove symbolic links. + + You must specify the following: + + - The path where the symlink will be placed + - The source path that the symlink points to + + Optionally, you can specify the UID and GID ownership of the symlink. 1. Select **Next: Configure** to configure the following image settings: @@ -160,9 +180,9 @@ You can create customizations using either the DHI CLI or the Docker Hub web int {{< tab name="CLI" >}} Authenticate with `docker login` using your Docker credentials or a [personal -access token (PAT)](../../security/access-tokens.md) with **Read & Write** +access token (PAT)](../../security/access-tokens/personal-access-tokens.md) with **Read & Write** permissions, or an [organization access token -(OAT)](../../enterprise/security/access-tokens.md). When using an OAT, the +(OAT)](../../security/access-tokens/organization-access-tokens.md). When using an OAT, the available operations depend on the token's permission scope: - To list or get customizations, or to view build logs, the OAT must have read @@ -218,10 +238,9 @@ For a complete reference of all YAML fields, see {{< tab name="Terraform" >}} You can manage DHI customizations as infrastructure-as-code using the [DHI -Terraform -provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). -If you haven't configured the provider yet, see the Terraform tab in [Mirror a -repository](./mirror.md) for setup instructions. +Terraform provider](/dhi/tools/terraform/). If you haven't configured the +provider yet, see [DHI Terraform provider](/dhi/tools/terraform/) for setup +instructions. Define a `dhi_customization` resource for each customization: @@ -351,8 +370,9 @@ contents: | `includes` | Paths to copy from the artifact. No files are included by default. You must list at least one path. | | `excludes` | Paths to exclude after applying `includes`. | -For instructions on building an OCI artifact image, see -[Create an OCI artifact image](#create-an-oci-artifact-image). +To learn more about OCI artifacts, including how to create them, best +practices, and how environment variables behave, see +[OCI artifacts](#oci-artifacts). #### Inject files into the image @@ -378,6 +398,13 @@ paths: | `uid` | User ID of the file owner. | | `gid` | Group ID of the file owner. | +> [!NOTE] +> +> If your organization's DHI subscription is in the EU region, you can't add +> files with `contents` in the `paths` field. File content isn't supported in +> the EU region. For details, see [EU data +> residency](../explore/eu-region.md). + #### Configure user accounts To add users or groups to the image, or to change which user the container @@ -481,14 +508,16 @@ tooling. compression: ZSTD ``` -### Create an OCI artifact image +## OCI artifacts + +In DHI customization, OCI artifacts are Docker images containing files you +want to layer into your image, such as custom certificates, internal tools, or +configuration files. -An OCI artifact image is a Docker image that contains files or directories that -you want to include in your customized Docker Hardened Image (DHI). This can -include additional tools, libraries, or configuration files. +### Create an OCI artifact image -When creating an image to use as an OCI artifact, it should ideally be as -minimal as possible and contain only the necessary files. +Keep artifact images as minimal as possible and include only the necessary +files. For example, to distribute a custom root CA certificate as part of a trusted CA bundle, you can use a multi-stage build. This approach registers your @@ -545,13 +574,31 @@ Once pushed to a repository in your organization's namespace, the OCI artifact automatically appears in the customization workflow when you select OCI artifacts to add to your customized Docker Hardened Image. -#### Best practices for OCI artifacts +### Environment variables + +When you include OCI artifacts in a customization, the environment variables +defined in those artifacts are merged into the final image. The merge follows +these rules: + +- Your customization's environment settings take precedence. An artifact's + variable is only applied if the corresponding key is absent or empty in your + customization. +- `PATH` is an exception. Artifact `PATH` entries are added to the front of + the existing `PATH`, giving them runtime precedence. + +This differs from `COPY --from` in a Dockerfile, which copies files without +inheriting environment variables from the source image. To avoid inheriting +environment variables, build the artifact using a `FROM scratch` final stage. +See [Create an OCI artifact image](#create-an-oci-artifact-image). + +### Best practices Follow these best practices when creating OCI artifacts for DHI customizations: - Use multi-stage builds: Build or install dependencies in a builder stage, then copy only the necessary files to a `FROM scratch` final stage. This keeps - the OCI artifact minimal and free of unnecessary build tools. + the OCI artifact minimal and avoids inheriting environment variables from the + builder image into your customization. - Include only essential files: OCI artifacts should contain only the files you need to add to the customized image. Avoid including package managers, diff --git a/content/manuals/dhi/how-to/explore.md b/content/manuals/dhi/how-to/explore.md deleted file mode 100644 index 258c38ccd206..000000000000 --- a/content/manuals/dhi/how-to/explore.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Search and evaluate Docker Hardened Images -linktitle: Search and evaluate -description: Learn how to find, compare, and evaluate Docker Hardened Images using the catalog on Docker Hub and Docker Scout comparison tools. -keywords: search docker images, image variants, docker hub catalog, compare docker images, docker scout compare, image comparison, vulnerability comparison -weight: 10 -aliases: - - /dhi/how-to/compare/ ---- - -Docker Hardened Images (DHI) are a curated set of secure, production-ready -container images designed to provide enhanced security, minimized attack -surfaces, and production-ready foundations for your applications. - -This page explains how to search available DHI repositories, review image -metadata, examine variant details, and compare images to evaluate security -improvements and differences. - -## Search the catalog - -You can browse, search, or filter images by category in the [Hardened Image -catalog](https://hub.docker.com/hardened-images/catalog) on Docker Hub. - -Alternatively, use the [DHI CLI](/reference/cli/docker/dhi/), included in -[Docker Desktop](/desktop/), to browse the catalog from the command line: - -```console -$ docker dhi catalog list -``` - -Filter by image type, name, or compliance requirements: - -```console -$ docker dhi catalog list --type image -$ docker dhi catalog list --filter python -$ docker dhi catalog list --fips -$ docker dhi catalog list --stig -``` - -### Repository details - -When you select a repository from the catalog, the repository details page -provides the following: - - - Overview: A brief explanation of the image. - - Guides: Several guides on how to use the image and migrate your existing application. - - Images: Select this option to [view image variants](#image-variants). - - Security summary: Select a tag name to view a quick security summary, - including package count, total known vulnerabilities, and Scout health score. - - Recently pushed tags: A list of recently updated image variants and when they - were last updated. - - Use this image: After selecting an image variant, you can select this option to - view instructions on how to pull and use the image variant. - -To view repository details from the command line, use the DHI CLI: - -```console -$ docker dhi catalog get python -``` - -This shows available tags, CVE counts, and other repository metadata. - -### Image variants - -Tags are used to identify image variants. Image variants are different builds of -the same application or framework tailored for different use-cases. - -From the [repository details](#repository-details), select **Images** to view -the available image variants. - -The **Images** page provides a table with the following columns: - -- Image version: The image name with its base distribution (for example, `debian - 13`) and associated tags. -- Type: The support lifecycle status of the variant. -- Compliance: Relevant compliance designations. For example, `CIS`, `FIPS`, or - `STIG (100%)`. -- Package manager: Whether a package manager is available. A checkmark indicates - a package manager is present (for example, `apt` or `apk`), a dash indicates - none. -- Shell: Whether a shell is available. A checkmark indicates a shell is present - (for example, `bash` or `busybox`), a dash indicates none. -- User: The user that the container runs as. For example, `root` or `nonroot - (65532)`. -- Last pushed: When the image variant was last updated. -- Vulnerabilities: Vulnerability counts by severity level. -- Health: The Scout health score. Select the score to view more details. - -### Image variant details - -On the [**Images** page](#image-variants), select an image version from the -table to view detailed information about that specific variant. - -The image variant details page provides the following information: - -- Packages: A list of all packages included in the image variant. This section - includes details about each package, including its name, version, - distribution, and licensing information. -- Specifications: The specifications for the image variant include the following - key details: - - Source & Build Information: The image is built from the Dockerfile found - here and the Git commit. - - Build parameters - - Entrypoint - - CMD - - User - - Working directory - - Environment Variables - - Labels - - Platform -- Vulnerabilities: The vulnerabilities section provides a list of known CVEs for - the image variant, including: - - CVE - - Severity - - Package - - Fix version - - Last detected - - Status - - Suppressed CVEs -- Attestations: Variants include comprehensive security attestations to verify - the image's build process, contents, and security posture. These attestations - are signed and can be verified using cosign. For a list of available - attestations, see [Attestations](../core-concepts/attestations.md). - -## Compare and evaluate images - -Docker Scout lets you analyze the differences between two images. Comparing a -DHI to a standard image helps you understand the security improvements, package -differences, and overall benefits of adopting hardened images. - -Comparison is useful for: - -- Evaluating the security improvements when migrating from a standard image to a - DHI -- Understanding package and vulnerability differences between image variants -- Assessing the impact of customizations or updates - -### Prerequisites - -Before comparing images: - -- Install [Docker Desktop](/desktop/) to use Docker Scout comparison features. -- Sign in to the registries containing the images you want to compare. Sign in - to `dhi.io` for Docker Hardened Images: - - ```console - $ docker login dhi.io - ``` - -### Basic comparison - -To compare a Docker Hardened Image with another image, use the [`docker scout -compare`](/reference/cli/docker/scout/compare/) command: - -```console -$ docker scout compare dhi.io/<image>:<tag> \ - --to <comparison-image>:<tag> \ - --platform <platform> -``` - -For example, to compare a DHI Node.js image with the official Node.js image: - -```console -$ docker scout compare dhi.io/node:22-debian13 \ - --to node:22 \ - --platform linux/amd64 -``` - -The output shows an overview at the top with key comparison metrics, followed by -detailed package and vulnerability information. Example overview: - -```console - ## Overview - - │ Analyzed Image │ Comparison Image - ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────── - Target │ dhi.io/node:22-debian13 │ node:22 - digest │ 55d471f61608 │ 9ee3220f602f - platform │ linux/amd64 │ linux/amd64 - vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4? - │ -1 -3 -153 -4 │ - size │ 41 MB (-367 MB) │ 408 MB - packages │ 19 (-726) │ 745 -``` - -### Filter unchanged packages - -To focus only on the differences and ignore unchanged packages, use the -`--ignore-unchanged` flag: - -```console -$ docker scout compare dhi.io/node:22-debian13 \ - --to node:22 \ - --platform linux/amd64 \ - --ignore-unchanged -``` - -This output highlights only the packages and vulnerabilities that differ between -the two images, making it easier to identify the security improvements and -changes. diff --git a/content/manuals/dhi/how-to/hardened-packages.md b/content/manuals/dhi/how-to/hardened-packages.md index 4a9b1a29c8ad..0cb0de1ebaa1 100644 --- a/content/manuals/dhi/how-to/hardened-packages.md +++ b/content/manuals/dhi/how-to/hardened-packages.md @@ -21,6 +21,16 @@ Access to hardened packages varies by subscription: the enterprise package repository directly in your own images for full access to compliance and security-patched packages. +To browse the packages currently available in Docker's public hardened package +repositories, see the following indexes: + +- [Debian package index](https://dhi.io/deb/debian/main/index.html) +- [Alpine package index](https://dhi.io/apk/alpine/v3.24/main/index.html) + +Docker is constantly adding new hardened packages. If a package you need isn't +available yet, you can [request it in the DHI catalog +repository](https://github.com/docker-hardened-images/catalog/issues). + ## Built-in packages Supported distributions of Docker Hardened Images (DHI) automatically include @@ -83,6 +93,7 @@ RUN apk update && \ ``` Replace `3.23` with your Alpine version in both the base image tag and repository URL. +Supported versions include Alpine 3.23 and 3.24. To verify the configuration, build and run the image: diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index 6fac70ba5d1b..ee65e52d596b 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -6,11 +6,8 @@ keywords: use hardened image, helm, k8s, kubernetes, dhi chart, chart weight: 31 --- -Docker Hardened Image (DHI) charts are Docker-provided [Helm -charts](https://helm.sh/docs/) built from upstream sources, designed for -compatibility with Docker Hardened Images. These charts are available as OCI -artifacts within the DHI catalog on Docker Hub. For more details, see [Docker -Hardened Image charts](/dhi/features/helm/). +Docker Hardened Image (DHI) charts are Docker-provided Helm charts built from upstream sources, designed for +compatibility with Docker Hardened Images. These charts are available in the [DHI catalog on Docker Hub](https://hub.docker.com/hardened-images/catalog?types=helmChart). DHI charts incorporate multiple layers of supply chain security that aren't present in upstream charts: @@ -26,15 +23,6 @@ charts to reference customized images and mirrored repositories. The customized chart build pipeline ensures that your customizations are built securely, use the latest base charts, and include attestations. -## Find a Docker Helm chart - -To find a Docker Helm chart for DHI: - -1. Go to the Hardened Images catalog in [Docker Hub](https://hub.docker.com/hardened-images/catalog) and sign in. -2. In the left sidebar, select **Hardened Images** > **Catalog**. -3. Select **Filter by** for **Helm Charts**. -4. Select a Helm chart repository to view its details. - ## Mirror a Helm chart and/or its images to a third-party registry If you want to mirror to your own third-party registry, you can follow the @@ -65,8 +53,8 @@ registry, you still need to create this secret if the registry requires authentication. 1. For `dhi.io` or Docker Hub, create a [personal access token - (PAT)](/security/access-tokens/) using your Docker account or an - [organization access token (OAT)](/enterprise/security/access-tokens/). + (PAT)](/security/access-tokens/personal-access-tokens/) using your Docker account or an + [organization access token (OAT)](/security/access-tokens/organization-access-tokens/). Ensure the token has at least read-only access to the Docker Hardened Image repositories. 2. Create a secret in Kubernetes using the following command. Replace `<your-secret-name>`, `<your-username>`, diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index e67d252037f6..3a4828206942 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -34,9 +34,23 @@ repositories: ## Mirror a DHI repository to your organization -To mirror repositories, you must be an organization owner or editor, or use a -personal access token (PAT) or organization access token (OAT). See the CLI and -Terraform tabs in the following sections for required permission scopes. +Organization owners, editors, and members with a [custom role](../../security/roles-and-permissions/custom-roles/_index.md) +that includes the DHI mirroring permission can create, view, and manage mirrors. +When using the CLI or Terraform, you can also mirror using an [organization +access token (OAT)](../../security/access-tokens/organization-access-tokens.md) with the +appropriate permission scopes, without requiring role-based access. + +When a member with a custom role that includes the DHI mirroring permission +creates a mirror, Docker automatically creates and manages the +`dhi-mirroring-admins` team in your organization, adds that member to it, and +grants the team access to the new mirror. This lets the member manage mirrors +they create without organization owner or editor access. Mirrors created by +organization owners or editors don't use this team. Removing members from this +team may affect their ability to view and manage mirrors. + +You can mirror image and chart repositories to your organization's namespace on +Docker Hub. Mirroring makes the repositories available within your organization +and lets you customize them for your environment: - Image repositories: Mirroring lets you customize images by adding packages, OCI artifacts (such as custom certificates or additional tools), environment @@ -61,7 +75,7 @@ Terraform tabs in the following sections for required permission scopes. - To mirror an image repository, select **Use this image** > **Mirror repository**, and then follow the on-screen instructions. If you have the ELS add-on, you can also select **Enable support for end-of-life versions**. - - To mirror a Helm chart repository, select **Get Helm chart**, and then follow the on-screen instructions. + - To mirror a Helm chart repository, select **Use this chart**, and then follow the on-screen instructions. It may take a few minutes for all the tags to finish mirroring. @@ -69,9 +83,9 @@ It may take a few minutes for all the tags to finish mirroring. {{< tab name="CLI" >}} Authenticate with `docker login` using your Docker credentials, a [personal -access token (PAT)](../../security/access-tokens.md) with **Read & Write** +access token (PAT)](../../security/access-tokens/personal-access-tokens.md) with **Read & Write** permissions, or an [organization access token -(OAT)](../../enterprise/security/access-tokens.md). When using an OAT, the +(OAT)](../../security/access-tokens/organization-access-tokens.md). When using an OAT, the available operations depend on the token's permission scope: - To list mirrored repositories, the OAT must have read (pull) access to the @@ -118,37 +132,9 @@ $ docker dhi mirror list --org my-org --type helm-chart {{< tab name="Terraform" >}} You can manage DHI mirrors as infrastructure-as-code using the [DHI Terraform -provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). +provider](/dhi/tools/terraform/). -First, install and configure the provider: - -```hcl -terraform { - required_providers { - dhi = { - source = "docker-hardened-images/dhi" - } - } -} - -provider "dhi" { - docker_hub_username = var.docker_username - docker_hub_password = var.docker_password - organization = var.org_name -} -``` - -> [!NOTE] -> -> Instead of specifying credentials in the provider block, you can set the -> `DOCKER_USERNAME`, `DOCKER_PASSWORD`, and `DHI_ORG` environment variables. You -> can also authenticate using an organization access token (OAT) in place of a -> password. Set `DOCKER_USERNAME` to your organization namespace and -> `DOCKER_PASSWORD` to the OAT. When using an OAT, the same permission scopes -> apply as with the CLI: read (pull) access is required to list mirrors, and -> push access is required to create or delete them. - -Then, define a `dhi_mirror` resource for each repository you want to mirror: +Define a `dhi_mirror` resource for each repository you want to mirror: ```hcl resource "dhi_mirror" "golang" { @@ -189,6 +175,14 @@ other Docker Hub repository, so you can manage access and permissions, configure webhooks, and use other standard Hub features. See [Docker Hub repositories](/manuals/docker-hub/repos/_index.md) for details. +### Mirrors in the EU region + +If your organization's DHI subscription is in the EU region, Docker creates +your mirrored repositories on Docker Hub in the EU. Mirrors created before your +subscription moved to the EU region stay in their original region. For +details, including how to get a subscription in the EU region, see [EU data +residency](../explore/eu-region.md). + ### Stop mirroring a repository After you stop mirroring, the repository remains, but it no longer receives @@ -214,9 +208,9 @@ updates. You can still use the last images or charts that were mirrored. {{< tab name="CLI" >}} Authenticate with `docker login` using your Docker credentials, a [personal -access token (PAT)](../../security/access-tokens.md) with **Read & Write** +access token (PAT)](../../security/access-tokens/personal-access-tokens.md) with **Read & Write** permissions, or an [organization access token -(OAT)](../../enterprise/security/access-tokens.md) with push access to the +(OAT)](../../security/access-tokens/organization-access-tokens.md) with push access to the relevant repository. Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: @@ -246,10 +240,20 @@ You can use any standard workflow to mirror the image, such as the API](/reference/api/registry/latest/), third-party registry tools, or CI/CD automation. -However, to preserve the full security context, including attestations, you must -also mirror its associated OCI artifacts. DHI repositories store the image -layers on `dhi.io` (or `docker.io` for customized images) and the signed -attestations in a separate registry (`registry.scout.docker.com`). +Mirroring an image requires copying both the image and its associated signed +attestations, including SBOMs, provenance, and VEX. Copying only the image does +not preserve these attestations in your destination registry. + +The `dhi.io` proxy provides access to DHI catalog images and their associated +attestations. It retrieves image manifests and layers from Docker Hub, and +attestations from `registry.scout.docker.com`. + +Customer mirrors and customized images are accessed through your organization's +repositories on Docker Hub. These repositories are not available through +`dhi.io`. The following examples therefore use two source locations: +`docker.io/<your-org>/<repository>` for the image and +`registry.scout.docker.com/<your-org>/<repository>` for its attestations. Both +are copied into the same repository in your destination registry. To copy both, you can use [`regctl`](https://regclient.org/cli/regctl/), an OCI-aware CLI that supports mirroring images along with attached artifacts such @@ -276,26 +280,165 @@ Other common webhook use cases include: - Signing or promoting images - Sending notifications to downstream systems -#### Example webhook payload +When a webhook fires, Docker Hub sends the standard [webhook +payload](/docker-hub/repos/manage/webhooks/#example-webhook-payload). For a +mirrored DHI repository, the payload also includes an additional +`dhi_metadata` object. This object describes what changed between the newly +pushed build and the previous build of the same tag, including vulnerability +fixes, package changes, and configuration changes. + +> [!NOTE] +> +> Docker Hub adds `dhi_metadata` only to pushes on mirrored DHI repositories. +> Webhooks on other repositories deliver the standard payload. + +Each DHI build produces a signed changelog attestation. At webhook delivery +time, Docker Hub retrieves the changelog for the pushed image and embeds it in +the payload as `dhi_metadata`. + +DHI changelogs are generated per architecture, so `dhi_metadata` is a map +keyed by the architecture-specific manifest digest. A multi-platform image +push contains an entry for each platform that has a changelog. Match the +digest key against the platform you care about instead of assuming a single +entry. -When a webhook is triggered, Docker Hub sends a JSON payload like the following: +#### `dhi_metadata` fields -```json{collapse=true} +Each platform entry contains the following fields. + +| Field | Type | Description | +| :---- | :---- | :---- | +| `schema_version` | integer | Version of the `dhi_metadata` schema. | +| `change_categories` | array of strings | High-level summary of what changed in this build. See [Change categories](#change-categories). | +| `previous_version` | object | The prior build this one is compared against. Contains `tag` and `digest`. | +| `changes` | object | Detailed diff versus the previous version. See the following table. | + +The `changes` object contains: + +| Field | Type | Description | +| :---- | :---- | :---- | +| `vulnerabilities_fixed` | array | CVEs resolved in this build. Each entry has `cve_id`, `severity`, `package`, and `fixed_in_version`. | +| `packages_updated` | array | Packages whose version changed. Each entry has `name`, `type`, `old_version`, and `new_version`. | +| `packages_added` | array | Packages added in this build. Each entry has `name`, `type`, and `version`. | +| `packages_removed` | array | Packages removed in this build. Each entry has `name`, `type`, and `version`. | +| `environment_variables_changed` | array | Changes to environment variables. Each entry has `change`, `key`, and `from_value` or `to_value` as applicable. | +| `labels_changed` | array | Changes to image labels, in the same shape as environment variable changes. | +| `configuration_changed` | array | Changes to other image configuration. For example, the entrypoint. | + +When a change type has no entries, its array is present but empty, shown as `[]`. + +#### Change categories + +`change_categories` gives a quick, machine-readable summary of the build. + +| Value | Meaning | +| :---- | :---- | +| `vulnerability_fix` | The build resolves one or more CVEs. See `changes.vulnerabilities_fixed`. | +| `version_upgrade` | One or more packages changed version. See `changes.packages_updated`. | +| `other` | The build has package, environment variable, label, or configuration changes that don't fall into either category above. | + +A build can have more than one category. For example, a build that fixes a CVE +and also bumps a package version returns both `vulnerability_fix` and +`version_upgrade`. A build with no changes at all returns an empty array. + +#### Example: vulnerability fix and version upgrade + +The following excerpt shows the `dhi_metadata` object from a webhook payload +for a push to a mirrored DHI repository. The example is trimmed to a single +platform and a subset of changes for readability. A real payload contains one +`dhi_metadata` entry per architecture. + +```json {collapse=true} +{ + ... + "dhi_metadata": { + "sha256:04639747b6d72bcf1d0322f2a5b122ee76d963e31bb4a070891b25f15a5001c5": { + "schema_version": 1, + "change_categories": ["vulnerability_fix", "version_upgrade"], + "previous_version": { + "tag": "2-compat-fips-dev", + "digest": "sha256:1738aa35838f520431c898b85d7cd60da71d8f997965287db4f3be27c1df32a1" + }, + "changes": { + "vulnerabilities_fixed": [ + { + "cve_id": "CVE-2019-9192", + "severity": "low", + "package": "glibc", + "fixed_in_version": "2.41-12+deb13u4+dhi0" + }, + { + "cve_id": "CVE-2018-20796", + "severity": "low", + "package": "glibc", + "fixed_in_version": "2.41-12+deb13u4+dhi0" + } + ], + "packages_updated": [ + { + "name": "glibc", + "type": "deb", + "old_version": "2.41-12+deb13u4", + "new_version": "2.41-12+deb13u4+dhi0" + }, + { + "name": "libc6", + "type": "deb", + "old_version": "2.41-12+deb13u4", + "new_version": "2.41-12+deb13u4+dhi0" + } + ], + "packages_added": [], + "packages_removed": [], + "environment_variables_changed": [], + "labels_changed": [ + { + "change": "changed", + "key": "com.docker.dhi.chain-id", + "from_value": "sha256:4567092c648d813b8c4c60c7d100fc34df817dd5cb4c7968e9a5c43bafb9e7a5", + "to_value": "sha256:62d4e2090951e812a87fb599db362677f72dee095f85889ea56df63c0999b02a" + } + ], + "configuration_changed": [] + } + } + } +} +``` + +#### Example: version bump with no CVEs + +When a build only bumps package versions, `change_categories` contains +`version_upgrade` and `vulnerabilities_fixed` is empty. + +```json {collapse=true} { - "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/", - "push_data": { - "pushed_at": 1712345678, - "pusher": "trustedbuilder", - "tag": "3.13-alpine3.21" - }, - "repository": { - "name": "dhi-python", - "namespace": "exampleorg", - "repo_name": "exampleorg/dhi-python", - "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python", - "is_private": true, - "status": "Active", - ... + ... + "dhi_metadata": { + "sha256:2982980b6bb3cdedafa9377bcc37405c20ed48702deef11faf13ec99d596057d": { + "schema_version": 1, + "change_categories": ["version_upgrade"], + "previous_version": { + "tag": "5-fips-dev", + "digest": "sha256:81355a1301ecc5f78dd87b68a284642d7b6bfbd86f3a37f3932fad7ecf1141e6" + }, + "changes": { + "vulnerabilities_fixed": [], + "packages_updated": [ + { + "name": "sqlite3", + "type": "deb", + "old_version": "3.46.1-7+deb13u2+dhi0", + "new_version": "3.46.1-7+deb13u2+dhi1" + } + ], + "packages_added": [], + "packages_removed": [], + "environment_variables_changed": [], + "labels_changed": [], + "configuration_changed": [] + } + } } } ``` @@ -317,11 +460,11 @@ same steps to a non-mirrored image by updating the `SRC_ATT_REPO` and In this example, you authenticate as your Docker organization using an [organization access token - (OAT)](../../enterprise/security/access-tokens.md). The OAT must have at + (OAT)](../../security/access-tokens/organization-access-tokens.md). The OAT must have at least pull access to every DHI repository you want to mirror. Only repositories in the token's scope are accessible. Alternatively, you can authenticate as a Docker Hub user with a [personal access token - (PAT)](../../security/access-tokens.md) that has `read only` access. + (PAT)](../../security/access-tokens/personal-access-tokens.md) that has `read only` access. > [!WARNING] > diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 80f9589bc024..152aa454dc1b 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -1,115 +1,227 @@ --- -title: Enforce Docker Hardened Image usage with policies -linktitle: Enforce image usage -description: Learn how to use image policies with Docker Scout for Docker Hardened Images. +title: Apply Docker Hardened Image policies to your images +linktitle: Apply image policies +description: Learn how to hold your own images to Docker Hardened Image security and compliance standards using the Docker Scout CLI. weight: 50 -keywords: docker scout policies, enforce image compliance, container security policy, image provenance, vulnerability policy check +keywords: docker scout policies, image security policy, container compliance, dhi policies, vulnerability policy check --- -When you have a Docker Hardened Images Enterprise subscription, mirroring a -Docker Hardened Image (DHI) repository automatically enables [Docker -Scout](/scout/), allowing you to start enforcing security and compliance -policies for your images without additional setup. Using Docker Scout policies, -you can define and apply rules that ensure only approved and secure images, such -as those based on DHIs, are used across your environments. +Docker publishes the set of security and compliance policies that Docker +Hardened Images (DHIs) are built to meet, so you can hold your own images to the +same standards. You evaluate images against these policies with the +[`docker scout policy`](../../scout/policy/local.md) command. + +These policies encode requirements such as running as a non-root user, being +free of fixable critical and high vulnerabilities, containing no embedded +malware or secrets, and shipping signed supply chain attestations. They don't +verify whether an image is a DHI or built on a DHI base image; they check +whether an image meets the same bar that DHIs are held to. + +Unlike the built-in Docker Scout policies, the DHI policies aren't embedded in +the CLI. They're maintained as Rego source in the +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository and published as an OCI policy bundle at +[`dhi/policies`](https://hub.docker.com/repository/docker/dhi/policies/general). +You pull the bundle at evaluation time with the `--policy-bundle` flag, so you +can apply DHI standards locally, in CI, or both, without sending any data to the +Docker Scout service. + +## Policies in the DHI bundle + +The `dhi/policies` bundle includes the following policies: + +| Policy | Policy name | What it checks | +| --- | --- | --- | +| No default root user for non-dev images | `dhi-default-non-root-user` | The image is configured to run as a non-root user. | +| No fixable vulnerabilities past their remediation SLA | `fixable-vulnerabilities` | No fixable CVEs remain unaddressed past their remediation SLA (7 days for critical and high, 30 days for others). | +| No high-profile vulnerabilities | `high-profile-vulnerabilities` | The image is free of a curated list of well-known CVEs, optionally including the CISA KEV catalog. | +| No embedded malware | `dhi-no-embedded-malware` | A malware scan attestation is present and passing. | +| No embedded secrets | `dhi-no-embedded-secrets` | A secret scan attestation is present and passing. | +| No failing tests | `dhi-no-failing-tests` | A test attestation is present and passing. | +| Signed supply chain attestations | `dhi-signed-supply-chain-attestations` | SBOM and provenance attestations are attached and signed. | +| Unintentional shell or package manager | `dhi-unintentional-shell-or-package-manager` | No undeclared shell or package manager is present in the image. | +| STIG scan | `dhi-stig-scan-score` | For FIPS-compliant images, the STIG scan meets the required score. | + +The **Policy name** is the stable ID you reference in a `--policy-config` file to +enable, disable, or tune a policy. + +For the authoritative list and the Rego source for each policy, see the +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository. + +## Prerequisites + +- The [Docker Scout CLI plugin](/manuals/scout/install.md). It's included with + Docker Desktop. +- Access to pull the `dhi/policies` bundle from Docker Hub. Authentication uses + your existing Docker registry credentials, so sign in first: + + ```console + $ docker login + ``` + +## Evaluate an image against the DHI policies + +To evaluate an image against the DHI policy bundle, pass the bundle reference to +`docker scout policy` with the `--policy-bundle` flag: -Docker Scout includes a dedicated [**Valid Docker Hardened Image (DHI) or DHI -base -image**](../../scout/policy/_index.md#valid-docker-hardened-image-dhi-or-dhi-base-image) -policy type that validates whether your images are Docker Hardened Images or are -built using a DHI as the base image. This policy checks for valid Docker signed -verification summary attestations. - -With policy evaluation built into Docker Scout, you can monitor image compliance -in real time, integrate checks into your CI/CD workflows, and maintain -consistent standards for image security and provenance. - -## View existing policies - -To see the current policies applied to a mirrored DHI repository: - -1. Go to the mirrored DHI repository in [Docker Hub](https://hub.docker.com). -2. Select **View on Scout**. - - This opens the [Docker Scout dashboard](https://scout.docker.com), where you - can see which policies are currently active and whether your images meet the - policy criteria. - -Docker Scout automatically evaluates policy compliance when new images are -pushed. Each policy includes a compliance result and a link to the affected -images and layers. - -## Evaluate DHI policy compliance for your images - -When you enable Docker Scout for your repositories, you can configure the -[**Valid Docker Hardened Image (DHI) or DHI base -image**](../../scout/policy/_index.md#valid-docker-hardened-image-dhi-or-dhi-base-image) -policy. This optional policy validates whether your images are DHIs or built with DHI -base images by checking for Docker signed verification summary attestations. +```console +$ docker scout policy <image> --policy-bundle dhi/policies:latest +``` -The following example shows how to build an image using a DHI base image and -evaluate its compliance with the DHI policy. +The CLI pulls the bundle, indexes the image into an SBOM, enriches it with CVE +and VEX data, and evaluates each policy in the bundle against that data. Bundles +are cached by digest, so re-running against the same bundle doesn't re-download +it. ### Example: Build and evaluate a DHI-based image +The following example builds an image from a DHI base image and evaluates it +against the DHI policy bundle. + #### Step 1: Use a DHI base image in your Dockerfile -Create a Dockerfile that uses a Docker Hardened Image mirrored repository as the -base. For example: +Create a Dockerfile that uses a Docker Hardened Image from the DHI catalog as +the base. For example: ```dockerfile # Dockerfile -FROM <your-namespace>/dhi-python:3.13-alpine3.21 +FROM dhi.io/python:3.13 ENTRYPOINT ["python", "-c", "print('Hello from a DHI-based image')"] ``` -#### Step 2: Build and push the image +#### Step 2: Build the image Open a terminal and navigate to the directory containing your Dockerfile. Then, -build and push the image to your Docker Hub repository: +build the image and load it into your local image store: ```console -$ docker build \ - --push \ - -t <your-namespace>/my-dhi-app:v1 . +$ docker build --load -t my-dhi-app:v1 . ``` -#### Step 3: Enable Docker Scout +#### Step 3: Evaluate the image against the DHI policies -To enable Docker Scout for your organization and the repository, run the -following commands in your terminal: +Sign in and evaluate the local image against the DHI policy bundle: ```console $ docker login -$ docker scout enroll <your-namespace> -$ docker scout repo enable --org <your-namespace> <your-namespace>/my-dhi-app +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest ``` -#### Step 4: Configure the DHI policy +The command prints a compliance result for each policy in the bundle, along with +the details of any violations. + +## Customize the DHI policies + +You can tune which policies run and their thresholds with a `--policy-config` +file. The +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository includes an example `config.json` you can start from. + +```console +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest \ + --policy-config ./config.json +``` -Once Docker Scout is enabled, you can configure the **Valid Docker Hardened -Image (DHI) or DHI base image** policy for your organization: +The config file matches policies by the **Policy name** listed in +[Policies in the DHI bundle](#policies-in-the-dhi-bundle) and lets you disable +individual policies or adjust their settings. For example, the following config +disables the STIG scan policy and opts out of CISA KEV checks in the +high-profile vulnerabilities policy: + +```json +{ + "policies": [ + { + "name": "dhi-stig-scan-score", + "enabled": false + }, + { + "name": "high-profile-vulnerabilities", + "config": { + "include_cisa_kev": false + } + } + ] +} +``` -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Policies**. -3. Configure the **Valid Docker Hardened Image (DHI) or DHI base image** policy - to enable it for your repositories. +For the full config file format, see +[Configure built-in policies](../../scout/policy/local.md#configure-built-in-policies). -For more information on configuring policies, see -[Configure policies](../../scout/policy/configure.md). +You can also combine the DHI bundle with the built-in Docker Scout policies, +additional bundles, or your own custom Rego files. `--policy-bundle`, +`--policy-file`, and `--policy-dir` are all repeatable: -#### Step 5: View policy compliance +```console +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest \ + --policy-file ./custom.rego +``` -Once the DHI policy is configured and active, you can view compliance results: +For more on authoring custom policies and combining policy sources, see +[Evaluate policies](../../scout/policy/local.md). + +## Enforce policy compliance in CI + +Use the [Docker Scout GitHub Action](https://github.com/docker/scout-action) to +evaluate the DHI policies on every push and fail the workflow when an image +doesn't meet them. The following workflow builds the image, then evaluates it +against the DHI policy bundle: + +```yaml +name: DHI policy check + +on: + push: + +env: + IMAGE_NAME: my-dhi-app:${{ github.sha }} + +jobs: + policy: + runs-on: ubuntu-latest + steps: + - name: Check out the repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKER_USER }} + password: ${{ secrets.DOCKER_PAT }} + + - name: Build the image + uses: docker/build-push-action@v6 + with: + context: . + load: true + tags: ${{ env.IMAGE_NAME }} + + - name: Evaluate DHI policies + uses: docker/scout-action@v1.23.1 + with: + command: policy + image: ${{ env.IMAGE_NAME }} + policy-bundle: dhi/policies:latest + exit-code: true +``` -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Images**. -3. Find your image, `<your-namespace>/my-dhi-app:v1`, and select the link in the **Compliance** column. +The `docker/login-action` step authenticates with Docker Hub so the runner can +pull the DHI base image and the `dhi/policies` bundle. Store your Docker Hub +username and a [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) as the +`DOCKER_USER` and `DOCKER_PAT` repository secrets. -This shows the policy compliance results for your image. The **Valid Docker -Hardened Image (DHI) or DHI base image** policy evaluates whether your image has -a valid Docker signed verification summary attestation or if its base image has -such an attestation. +Set `exit-code: true` to fail the step when any policy isn't met. The +`policy-bundle` input accepts a comma-separated list of bundles, and you can +combine it with the `policy-file`, `policy-dir`, and `policy-config` inputs, the +same as the CLI flags. -You can now [evaluate policy compliance in your CI](/scout/policy/ci/). \ No newline at end of file +For more on running policy evaluation in CI, see +[Evaluate policies](../../scout/policy/local.md#use-in-ci). diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md index 81d602e35e94..3f325b0fc552 100644 --- a/content/manuals/dhi/how-to/scan.md +++ b/content/manuals/dhi/how-to/scan.md @@ -1,8 +1,8 @@ --- title: Scan Docker Hardened Images linktitle: Scan an image -description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, Trivy, Wiz, Mend.io, or Black Duck. -keywords: scan container image, docker scout cves, grype scanner, trivy container scanner, mend.io, black duck, vex attestation +description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy. +keywords: scan container image, docker scout cves, grype scanner, trivy container scanner, vex attestation weight: 46 --- @@ -13,22 +13,14 @@ vulnerability management process. ## Scan with OpenVEX-compliant scanners To get accurate vulnerability assessments, use scanners that support -[VEX](/manuals/dhi/core-concepts/vex.md) attestations. The following scanners can +[VEX](/manuals/dhi/explore/security-concepts/vex.md) attestations. The following scanners can read and apply the VEX statements included with Docker Hardened Images: - [Docker Scout](#docker-scout): Automatically applies VEX statements with zero configuration - [Trivy](#trivy): Supports VEX through VEX Hub or local VEX files - [Grype](#grype): Supports VEX via the `--vex` flag -- [Wiz](#wiz): Automatically applies VEX statements with - zero configuration -- [Mend.io](#mendio): Automatically applies VEX statements with - zero configuration -- [Black Duck](#black-duck): Automatically applies VEX statements with - zero configuration -For guidance on choosing the right scanner and understanding the differences -between VEX-enabled and non-VEX scanners, see [Scanner -integrations](/manuals/dhi/explore/scanner-integrations.md). +For a full list of supported scanners, see [Scanner integrations](/manuals/dhi/explore/scanner-integrations.md). ## Docker Scout @@ -360,57 +352,6 @@ Then scan the image with the local VEX file: $ trivy image --scanners vuln --vex vex.json dhi.io/<image>:<tag> ``` -## Wiz - -[Wiz](https://www.wiz.io/) is a cloud security platform that includes container -image scanning capabilities with support for DHI VEX attestations. Wiz CLI -automatically consumes VEX statements from Docker Hardened Images to provide -accurate vulnerability assessments. - -### Scan a DHI using Wiz CLI - -After acquiring a Wiz subscription and installing the Wiz CLI, you can scan a -Docker Hardened Image by pulling the image and running the scan command: - -```console -$ docker login dhi.io -$ docker pull dhi.io/<image>:<tag> -$ wizcli scan container-image dhi.io/<image>:<tag> -``` - -## Mend.io - -[Mend.io](https://www.mend.io/) is an application security platform that -includes container image scanning with support for DHI VEX attestations. -Mend Container automatically retrieves and applies VEX statements from Docker -Hardened Images and combines them with Mend's reachability analysis for -comprehensive vulnerability assessment. - -### Scan a DHI using Mend.io - -After acquiring a Mend.io subscription and configuring -[Mend Container](https://docs.mend.io/container/latest/), Mend automatically -detects Docker Hardened Images and applies their VEX data without requiring any -additional configuration. When you scan a Docker Hardened Image through the Mend -AppSec Platform, VEX statements are automatically retrieved and attached as risk -factors to each finding. - -You can view and filter DHI-specific findings in the Mend AppSec Platform under -**Security > Containers > Packages**, where a Docker badge identifies hardened -image packages. Use the **Risk Factors** column to filter by VEX statuses such -as Not Affected, Fixed, or Under Investigation. - -For more information, see the [Mend.io Docker Hardened Images -documentation](https://docs.mend.io/platform/latest/docker-hardened-images). - -## Black Duck - -[Black Duck](https://www.blackduck.com/) identifies Docker Hardened Images and -applies their VEX statements without additional configuration. - -For more information, see the [Black Duck -documentation](https://documentation.blackduck.com/bundle/bd-hub/page/Reporting/vexReport_global.html). - ## Export VEX attestations For scanners that need local VEX files (like Grype or Trivy with local files), diff --git a/content/manuals/dhi/how-to/search-evaluate.md b/content/manuals/dhi/how-to/search-evaluate.md new file mode 100644 index 000000000000..6b2f1bd53ec8 --- /dev/null +++ b/content/manuals/dhi/how-to/search-evaluate.md @@ -0,0 +1,113 @@ +--- +title: Search and evaluate Docker Hardened Images +linktitle: Search and evaluate +description: Learn how to find, compare, and evaluate Docker Hardened Images using the Docker Hub catalog, DHI CLI, and Docker Scout. +keywords: search docker images, image variants, docker hub catalog, compare docker images, docker scout compare, image comparison, vulnerability comparison +weight: 10 +aliases: + - /dhi/how-to/compare/ + - /dhi/how-to/explore/ +--- + +## Search the catalog + +You can browse, search, or filter images by category in the [Docker Hub +catalog](https://hub.docker.com/hardened-images/catalog). For details about +the catalog interface, see [Docker Hub](/dhi/tools/hub/). + +Alternatively, use the [DHI MCP server](/dhi/tools/mcp/) to search and +inspect the catalog directly from your AI assistant, or use the [DHI +CLI](/dhi/tools/cli/) to browse the catalog from the command line: + +```console +$ docker dhi catalog list +``` + +Filter by image type, name, or compliance requirements: + +```console +$ docker dhi catalog list --type image +$ docker dhi catalog list --filter python +$ docker dhi catalog list --fips +$ docker dhi catalog list --stig +``` + +To view repository details, including available tags and CVE counts: + +```console +$ docker dhi catalog get python +``` + +## Compare and evaluate images + +Docker Scout lets you analyze the differences between two images. Comparing a +DHI to a standard image helps you understand the security improvements, package +differences, and overall benefits of adopting hardened images. + +Comparison is useful for: + +- Evaluating the security improvements when migrating from a standard image to a DHI +- Understanding package and vulnerability differences between image variants +- Assessing the impact of customizations or updates + +### Prerequisites + +Before comparing images: + +- Install [Docker Desktop](/desktop/) to use Docker Scout comparison features. +- Sign in to `dhi.io` for Docker Hardened Images: + + ```console + $ docker login dhi.io + ``` + +### Basic comparison + +To compare a Docker Hardened Image with another image, use the [`docker scout +compare`](/reference/cli/docker/scout/compare/) command: + +```console +$ docker scout compare dhi.io/<image>:<tag> \ + --to <comparison-image>:<tag> \ + --platform <platform> +``` + +For example, to compare a DHI Node.js image with the official Node.js image: + +```console +$ docker scout compare dhi.io/node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 +``` + +The output shows an overview at the top with key comparison metrics, followed by +detailed package and vulnerability information. Example overview: + +```console + ## Overview + + │ Analyzed Image │ Comparison Image + ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────── + Target │ dhi.io/node:22-debian13 │ node:22 + digest │ 55d471f61608 │ 9ee3220f602f + platform │ linux/amd64 │ linux/amd64 + vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4? + │ -1 -3 -153 -4 │ + size │ 41 MB (-367 MB) │ 408 MB + packages │ 19 (-726) │ 745 +``` + +### Filter unchanged packages + +To focus only on the differences and ignore unchanged packages, use the +`--ignore-unchanged` flag: + +```console +$ docker scout compare dhi.io/node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 \ + --ignore-unchanged +``` + +This output highlights only the packages and vulnerabilities that differ between +the two images. diff --git a/content/manuals/dhi/how-to/select-enterprise.md b/content/manuals/dhi/how-to/select-enterprise.md index 02f0886901a0..af660ca1269c 100644 --- a/content/manuals/dhi/how-to/select-enterprise.md +++ b/content/manuals/dhi/how-to/select-enterprise.md @@ -20,7 +20,7 @@ To use this workflow, you need: - One of the following: - A DHI Select or Enterprise subscription. [Contact Docker sales](https://www.docker.com/products/hardened-images/#compare) to purchase DHI Enterprise - or [learn more about DHI Select](../../subscription/scale.md#add-dhi-select-to-organization-accounts). + or [learn more about DHI plans](../../subscription-billing/plans/dhi.md). - An active DHI trial. [Start a free DHI trial](https://hub.docker.com/hardened-images/start-free-trial). - [Docker Desktop](../../desktop/release-notes.md) 4.65 or later to use the @@ -41,7 +41,7 @@ can use either interface. `node`, or `golang`). For this example, search for `python`. To search for an image with a compliance variant (FIPS or STIG), select - **Filter by** and select the relevant compliance option. + **Compliance** and select the relevant compliance option. 5. Select the Python repository to view its details. @@ -72,7 +72,7 @@ can use either interface. {{< /tabs >}} Continue to the next step to mirror the image. To dive deeper into exploring -images see [Search and evaluate Docker Hardened Images](explore.md). +images see [Search and evaluate Docker Hardened Images](search-evaluate.md). ## Step 2: Mirror the repository @@ -97,7 +97,7 @@ can mirror repositories. To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI -CLI](cli.md#configuration). +CLI](../tools/cli.md#configuration). 1. Start mirroring the repository to your organization namespace. Replace `<your-org>` with your organization name. @@ -152,7 +152,7 @@ column to monitor the build status. To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI -CLI](cli.md#configuration). +CLI](../tools/cli.md#configuration). 1. Create a customization. Replace `<your-org>` with your organization name. This creates a file called `my-customization.yaml` with the customization diff --git a/content/manuals/dhi/how-to/troubleshoot.md b/content/manuals/dhi/how-to/troubleshoot.md new file mode 100644 index 000000000000..42d2a51400b7 --- /dev/null +++ b/content/manuals/dhi/how-to/troubleshoot.md @@ -0,0 +1,187 @@ +--- +title: Troubleshoot +description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access. +weight: 100 +tags: [Troubleshooting] +keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container +aliases: + - /dhi/how-to/debug/ + - /dhi/troubleshoot/ +--- + +This page covers debugging techniques and common issues you may encounter while +migrating to or using Docker Hardened Images (DHIs). + +## General debugging + +Docker Hardened Images prioritize minimalism and security, which means +they intentionally leave out many common debugging tools (like shells or package +managers). This makes direct troubleshooting difficult without introducing risk. +To address this, you can use [Docker +Debug](/reference/cli/docker/debug/), a secure workflow that +temporarily attaches an ephemeral debug container to a running service or image +without modifying the original image. + +This section shows how to debug Docker Hardened Images locally during development. +With Docker Debug, you can also debug containers remotely using the `--host` +option. + +### Use Docker Debug + +#### Step 1: Run a container from a Hardened Image + +Start with a DHI-based container that simulates an issue: + +```console +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" +``` + +This container doesn't include a shell or tools like `ps`, `top`, or `cat`. + +If you try: + +```console +$ docker exec -it myapp sh +``` + +You'll see: + +```console +exec: "sh": executable file not found in $PATH +``` + +#### Step 2: Use Docker Debug to inspect the container + +Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. + +```console +$ docker debug myapp +``` + +From here, you can inspect running processes, network status, or mounted files. + +For example, to check running processes: + +```console +$ ps aux +``` + +Type `exit` to leave the container when done. + +### Alternative debugging approaches + +In addition to using Docker Debug, you can also use the following approaches for +debugging DHI containers. + +#### Use the -dev variant + +Docker Hardened Images offer a `-dev` variant that includes a shell +and a package manager to install debugging tools. Simply replace the image tag +with `-dev`: + +```console +$ docker run -it --rm dhi.io/python:3.13-dev sh +``` + +Type `exit` to leave the container when done. Note that using the `-dev` variant +increases the attack surface and it is not recommended as a runtime for +production environments. + +#### Mount debugging tools with image mounts + +You can use the image mount feature to mount debugging tools into your container +without modifying the base image. + +##### Step 1: Run a container from a hardened image + +Start with a DHI-based container that simulates an issue: + +```console +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" +``` + +##### Step 2: Mount debugging tools into the container + +Run a new container that mounts a tool-rich image (like `busybox`) into +the running container's namespace: + +```console +$ docker run --rm -it --pid container:myapp \ + --mount type=image,source=busybox,destination=/dbg,ro \ + dhi.io/python:3.13 /dbg/bin/sh +``` + +This mounts the BusyBox image at `/dbg`, giving you access to its tools while +keeping your original container image unchanged. Since the hardened Python image +doesn't include standard utilities, you need to use the full path to the mounted +tools: + +```console +$ /dbg/bin/ls / +$ /dbg/bin/ps aux +$ /dbg/bin/cat /etc/os-release +``` + +Type `exit` to leave the container when done. + +## Common issues + +The following are specific issues you may encounter when working with Docker +Hardened Images, along with recommended solutions. + +### Permissions + +DHIs run as a nonroot user by default for enhanced security. This can result in +permission issues when accessing files or directories. Ensure your application +files and runtime directories are owned by the expected UID/GID or have +appropriate permissions. + +To find out which user a DHI runs as, check the repository page for the image on +Docker Hub. See [View image variant +details](../tools/hub.md#image-variant-details-page) for more information. + +### Privileged ports + +Nonroot containers cannot bind to ports below 1024 by default. This is enforced +by both the container runtime and the kernel (especially in Kubernetes and +Docker Engine < 20.10). + +Inside the container, configure your application to listen on an unprivileged +port (1025 or higher). For example `docker run -p 80:8080 my-image` maps +port 8080 in the container to port 80 on the host, allowing you to access it +without needing root privileges. + +### No shell + +Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or +tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev` +variant of the image in an earlier build stage and copy the final artifact into +the runtime image. + +To find out which shell, if any, a DHI has, check the repository page for the +image on Docker Hub. See [View image variant +details](../tools/hub.md#image-variant-details-page) for more information. + +Also, use Docker Debug when you need shell access to a running container. For +more details, see [General debugging](#general-debugging). + +### Entry point differences + +DHIs may define different entry points compared to Docker Official Images (DOIs) +or other community images. + +To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the +image on Docker Hub. See [View image variant +details](../tools/hub.md#image-variant-details-page) for more information. + +### No package manager + +Runtime Docker Hardened Images are stripped down for security and minimal attack +surface. As a result, they don't include a package manager such as `apk` or +`apt`. This means you can't install additional software directly in the runtime +image. + +If your build or application setup requires installing packages (for example, to +compile code, install runtime dependencies, or add diagnostic tools), use a `dev` +variant of the image in a build stage. Then, copy only the necessary artifacts +into the final runtime image. \ No newline at end of file diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index 329886801fb7..c969bacaa726 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -23,12 +23,12 @@ package manager, and may run as a non-root user by default. > pull DHI Community images. You can authenticate using either of the following: > > - **Docker ID and password:** Use your Docker Hub username and password. If -> you don't have a Docker account, [create one](../../accounts/create-account.md) +> you don't have a Docker account, [create one](../../accounts/individual/create-account.md) > for free. > - **Access token:** Use a [personal access token -> (PAT)](../../security/access-tokens.md) for personal accounts, or an +> (PAT)](../../security/access-tokens/personal-access-tokens.md) for personal accounts, or an > [organization access token -> (OAT)](../../enterprise/security/access-tokens.md) with your organization +> (OAT)](../../security/access-tokens/organization-access-tokens.md) with your organization > name as the username. > > Run `docker login dhi.io` to authenticate. @@ -81,7 +81,7 @@ For multi-stage builds: executables](#use-a-static-image-for-compiled-executables). To learn how to search for available variants, see [Search and evaluate -images](./explore.md). +images](./search-evaluate.md). ## Use a DHI in CI/CD pipelines @@ -90,7 +90,7 @@ You can reference them in Dockerfiles, pull them as part of a pipeline step, or run containers based on them during builds and tests. Unlike typical container images, DHIs also include signed -[attestations](../core-concepts/attestations.md) such as SBOMs and provenance +[attestations](../explore/security-concepts/attestations.md) such as SBOMs and provenance metadata. You can incorporate these into your pipeline to support supply chain security, policy checks, or audit requirements if your tooling supports it. @@ -109,14 +109,14 @@ attached to Docker Hardened Images. This is particularly useful in CI/CD pipelines for supply chain security validation and compliance checks. For automated workflows, authenticate using an [organization access token -(OAT)](../../enterprise/security/access-tokens.md). OATs are owned by the +(OAT)](../../security/access-tokens/organization-access-tokens.md). OATs are owned by the organization rather than an individual user, making them better suited for CI/CD pipelines. To discover attestations with ORAS: 1. [Generate an organization access - token](../../enterprise/security/access-tokens.md) with **Read public + token](../../security/access-tokens/organization-access-tokens.md) with **Read public repositories** scope. The following example shows how to discover attestations on DHI community @@ -268,8 +268,8 @@ For the `--docker-server` value: #### Using an access token Create a secret using a [Personal Access Token -(PAT)](../../security/access-tokens.md) or [Organization Access Token -(OAT)](../../enterprise/security/access-tokens.md). Ensure the token has at +(PAT)](../../security/access-tokens/personal-access-tokens.md) or [Organization Access Token +(OAT)](../../security/access-tokens/organization-access-tokens.md). Ensure the token has at least read-only access to the repositories. ```console diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index 1a96cec7f18c..1095c40176b8 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -27,7 +27,7 @@ attestation infrastructure. > You must authenticate to the Docker Hardened Images registry (`dhi.io`) to > pull images. Use your Docker ID credentials (the same username and password > you use for Docker Hub) when signing in. If you don't have a Docker account, -> [create one](../../accounts/create-account.md) for free. +> [create one](../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. @@ -62,11 +62,11 @@ This command shows all available attestations, including SBOMs, provenance, vuln First, authenticate to both registries. This example authenticates as your Docker organization using an [organization access token -(OAT)](../../enterprise/security/access-tokens.md). The OAT must have at least +(OAT)](../../security/access-tokens/organization-access-tokens.md). The OAT must have at least pull access to the DHI repositories you want to verify. Only repositories in the token's scope are accessible. Alternatively, you can authenticate as a Docker Hub user with a [personal access token -(PAT)](../../security/access-tokens.md) that has `read only` access. +(PAT)](../../security/access-tokens/personal-access-tokens.md) that has `read only` access. > [!WARNING] > @@ -388,15 +388,15 @@ attestations when needed. ## Available DHI attestations See [available -attestations](../core-concepts/attestations.md#image-attestations) for a list +attestations](../explore/security-concepts/attestations.md#image-attestations) for a list of attestations available for each DHI image and [Helm chart -attestations](../core-concepts/attestations.md#helm-chart-attestations) for a +attestations](../explore/security-concepts/attestations.md#helm-chart-attestations) for a list of attestations available for each DHI chart. ## Explore attestations on Docker Hub You can also browse attestations visually when [exploring an image -variant](./explore.md#image-variant-details). The **Attestations** section +variant](./search-evaluate.md#image-variant-details). The **Attestations** section lists each available attestation with its: - Type (e.g. SBOM, VEX) diff --git a/content/manuals/dhi/how-to/vex-api.md b/content/manuals/dhi/how-to/vex-api.md new file mode 100644 index 000000000000..9739e2a8ca34 --- /dev/null +++ b/content/manuals/dhi/how-to/vex-api.md @@ -0,0 +1,208 @@ +--- +title: Query VEX for a Docker Hardened Image +linktitle: Query VEX suppressions via API +description: Use the DHI GraphQL API to fetch VEX statements and suppressed CVEs for a Docker Hardened Image by digest. +keywords: dhi vex api, graphql api, suppressed cves, base vex, image digest, docker hardened images +weight: 47 +--- + +This is a guided example of using the [DHI API](/manuals/dhi/tools/api.md) +to fetch VEX statements and suppressed CVEs for a Docker Hardened Image (DHI) +by digest, using the `imagePackagesForImageCoords` query. The query takes an +image digest and returns every package, every CVE reported against it, +whether Docker suppresses that CVE, and why. + +> [!NOTE] +> For one-off lookups or local scanning workflows, [`docker scout vex +> get`](/manuals/dhi/how-to/scan.md#export-vex-attestations) may be simpler. +> Use the API described here when you need to query many images +> programmatically. + +For the API endpoint and authentication, see [Use the DHI +API](/manuals/dhi/tools/api.md). This page assumes you already have a valid +token. + +## Query suppressed CVEs + +This is the `imagePackagesForImageCoords` query used in this example. It +fetches every package in an image, every CVE reported against it, and +whether Docker suppresses that CVE: + +```graphql +query BaseVex($ctx: Context!, $q: IpImagePackagesForImageCoordsQuery!) { + imagePackagesForImageCoords(context: $ctx, query: $q) { + imagePackages { + packages { + package { + purl + name + version + vulnerabilities { + sourceId + isExcepted + fixedBy + cvss { + severity + } + vulnerabilityExceptions { + id + sourceType + type + justification + additionalDetails + isDhiStatement + } + } + } + } + } + } +} +``` + +With variables: + +```json +{ + "ctx": { "organization": "your-org" }, + "q": { + "digest": "sha256:<platform-manifest-digest>", + "hostName": "hub.docker.com", + "repoName": "your-org/your-repo", + "includeExcepted": true, + "includeNodsa": true + } +} +``` + +For the full argument reference, see +[`imagePackagesForImageCoords`](/manuals/dhi/tools/api.md#imagepackagesforimagecoords). + +### Get an access token + +Exchange your organization access token (OAT) or personal access token (PAT) +for an access token, as described in [Use the DHI +API](/manuals/dhi/tools/api.md#authentication): + +```console +$ DHI_API_TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \ + -H "Content-Type: application/json" \ + -d "{\"identifier\": \"<identifier>\", \"secret\": \"<token>\"}" \ + | jq -r .access_token) +``` + +Use your Docker Hub username as `identifier` for a PAT, or your organization +name for an OAT. + +### Send the request + +Combine the query and variables into the request body described in [Use the +DHI API](/manuals/dhi/tools/api.md#request-format). The following example +uses `jq` to build the body safely, since the query spans multiple lines: + +```console +$ QUERY='query BaseVex($ctx: Context!, $q: IpImagePackagesForImageCoordsQuery!) { + imagePackagesForImageCoords(context: $ctx, query: $q) { + imagePackages { + packages { + package { + purl + name + version + vulnerabilities { + sourceId + isExcepted + fixedBy + cvss { + severity + } + vulnerabilityExceptions { + id + sourceType + type + justification + additionalDetails + isDhiStatement + } + } + } + } + } + } +}' + +$ curl https://api.dso.docker.com/v1/graphql \ + -H "Authorization: Bearer $DHI_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg query "$QUERY" '{ + query: $query, + variables: { + ctx: { organization: "your-org" }, + q: { + digest: "sha256:<platform-manifest-digest>", + hostName: "hub.docker.com", + repoName: "your-org/your-repo", + includeExcepted: true, + includeNodsa: true + } + } + }')" +``` + +Substitute your organization, digest, host, and repository. + +## Sample response + +The following example is trimmed to a single package: + +```json +{ + "package": { + "purl": "pkg:deb/debian/tar@1.35%2Bdfsg-3.1%2Bdhi1?os_distro=trixie&os_name=debian&os_version=13", + "name": "tar", + "version": "1.35+dfsg-3.1+dhi1", + "vulnerabilities": [ + { + "sourceId": "CVE-2025-45582", + "cvss": { "severity": "MEDIUM" }, + "fixedBy": null, + "isExcepted": false, + "vulnerabilityExceptions": [] + }, + { + "sourceId": "CVE-2026-18477", + "cvss": { "severity": "MEDIUM" }, + "fixedBy": null, + "isExcepted": true, + "vulnerabilityExceptions": [ + { + "id": "debian-nodsa-CVE-2026-18477", + "sourceType": "EXTERNAL", + "type": "FALSE_POSITIVE", + "justification": null, + "additionalDetails": "Debian NODSA", + "isDhiStatement": false + } + ] + } + ] + } +} +``` + +Use `isExcepted` to tell whether a CVE is suppressed. For the full response +field reference and the OpenVEX mapping, see +[`imagePackagesForImageCoords`](/manuals/dhi/tools/api.md#imagepackagesforimagecoords). + +## Query customization images + +DHI VEX statements apply directly to images built with the [customization +feature](/manuals/dhi/how-to/customize.md). Query the customized image's own +digest to get its packages, CVEs, and suppressions in a single call. You +don't need to query the base image separately. + +## Caveats + +The suppression set for a given digest can change as new advisories and +assessments are published. Cache results per digest with a short TTL rather +than treating a response as permanent. diff --git a/content/manuals/dhi/migration/examples/dotnet.md b/content/manuals/dhi/migration/examples/dotnet.md index 79cdee998e1a..129d2f937788 100644 --- a/content/manuals/dhi/migration/examples/dotnet.md +++ b/content/manuals/dhi/migration/examples/dotnet.md @@ -23,7 +23,7 @@ Hardened Images. Each example includes four variations: > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../../accounts/create-account.md) for free. +> one](../../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. diff --git a/content/manuals/dhi/migration/examples/go.md b/content/manuals/dhi/migration/examples/go.md index 3a42bdc50a9d..b79ba0d407a6 100644 --- a/content/manuals/dhi/migration/examples/go.md +++ b/content/manuals/dhi/migration/examples/go.md @@ -24,7 +24,7 @@ Hardened Images. Each example includes five variations: > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../../accounts/create-account.md) for free. +> one](../../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. diff --git a/content/manuals/dhi/migration/examples/java.md b/content/manuals/dhi/migration/examples/java.md index bfae595dc48a..2b26fbeb1d74 100644 --- a/content/manuals/dhi/migration/examples/java.md +++ b/content/manuals/dhi/migration/examples/java.md @@ -24,7 +24,7 @@ Hardened Images. Each example includes five variations: > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../../accounts/create-account.md) for free. +> one](../../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. diff --git a/content/manuals/dhi/migration/examples/node.md b/content/manuals/dhi/migration/examples/node.md index 3019df3f8d16..23425e726437 100644 --- a/content/manuals/dhi/migration/examples/node.md +++ b/content/manuals/dhi/migration/examples/node.md @@ -24,7 +24,7 @@ Hardened Images. Each example includes five variations: > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../../accounts/create-account.md) for free. +> one](../../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. diff --git a/content/manuals/dhi/migration/examples/python.md b/content/manuals/dhi/migration/examples/python.md index 4ee4d327551c..bf11e9bc4bfd 100644 --- a/content/manuals/dhi/migration/examples/python.md +++ b/content/manuals/dhi/migration/examples/python.md @@ -24,7 +24,7 @@ Hardened Images. Each example includes five variations: > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../../accounts/create-account.md) for free. +> one](../../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. diff --git a/content/manuals/dhi/migration/migrate-from-doi.md b/content/manuals/dhi/migration/migrate-from-doi.md index 521733545f86..5908e3a4c2c9 100644 --- a/content/manuals/dhi/migration/migrate-from-doi.md +++ b/content/manuals/dhi/migration/migrate-from-doi.md @@ -48,7 +48,7 @@ replaced by the new hardened image. > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../accounts/create-account.md) for free. +> one](../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. @@ -58,7 +58,7 @@ replaced by the new hardened image. - FROM golang:1.25 + ## Updated to use hardened base image -+ FROM dhi.io/golang:1.25-debian12-dev ++ FROM dhi.io/golang:1.25-debian13-dev ``` Note that DHI does not have a `latest` tag in order to promote best practices @@ -89,20 +89,20 @@ The following example shows a multi-stage Dockerfile with a build stage and runt ```dockerfile # Build stage -FROM dhi.io/golang:1.25-debian12-dev AS builder +FROM dhi.io/golang:1.25-debian13-dev AS builder WORKDIR /app COPY . . RUN go build -o myapp # Runtime stage -FROM dhi.io/golang:1.25-debian12 +FROM dhi.io/golang:1.25-debian13 WORKDIR /app COPY --from=builder /app/myapp . ENTRYPOINT ["/app/myapp"] ``` After updating your Dockerfile, build and test your application. If you encounter -issues, see the [Troubleshoot](/manuals/dhi/troubleshoot.md) guide for common +issues, see the [Troubleshoot](/manuals/dhi/how-to/troubleshoot.md) guide for common problems and solutions. ## Language-specific examples diff --git a/content/manuals/dhi/migration/migrate-from-ubuntu.md b/content/manuals/dhi/migration/migrate-from-ubuntu.md index 09674e8484c6..b28d8cecdc18 100644 --- a/content/manuals/dhi/migration/migrate-from-ubuntu.md +++ b/content/manuals/dhi/migration/migrate-from-ubuntu.md @@ -20,9 +20,9 @@ When migrating from Ubuntu-based images to DHI Debian, be aware of these key dif | Item | Ubuntu-based images | Docker Hardened Images | |:-------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Package management | Varies by image. Some include APT package manager, others don't | Package managers generally only available in images with a `dev` tag. Runtime images don't contain package managers. Use multi-stage builds and copy necessary artifacts from the build stage to the runtime stage. | -| Non-root user | Varies by image. Some run as root, others as non-root | Runtime variants run as the non-root user by default. Ensure that necessary files and directories are accessible to the non-root user. | +| Non-root user | Varies by image. Some run as root, others as non-root | Runtime variants run as the nonroot user by default. Ensure that necessary files and directories are accessible to the nonroot user. | | Multi-stage build | Recommended | Recommended. Use images with a `dev` or `sdk` tags for build stages and non-dev images for runtime. | -| Ports | Can bind to privileged ports (under 1024) when running as root | Run as a non-root user by default. Applications can't bind to privileged ports (under 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. Configure your application to listen on port 1025 and up inside the container. | +| Ports | Can bind to privileged ports (under 1024) when running as root | Run as a nonroot user by default. Applications can't bind to privileged ports (under 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. Configure your application to listen on port 1025 or higher inside the container. | | Entry point | Varies by image | May have different entry points than Ubuntu-based images. Inspect entry points and update your Dockerfile if necessary. | | Shell | Varies by image. Some include a shell, others don't | Runtime images don't contain a shell. Use `dev` images in build stages to run shell commands and then copy artifacts to the runtime stage. | | Package repositories | Uses Ubuntu package repositories | Uses Debian package repositories. Most packages have similar names, but some may differ. | @@ -43,7 +43,7 @@ replaced by the new DHI Debian image. > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../accounts/create-account.md) for free. +> one](../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. @@ -53,7 +53,7 @@ replaced by the new DHI Debian image. - FROM ubuntu/go:1.22-24.04 + ## Updated to use hardened Debian-based image -+ FROM dhi.io/golang:1-debian13-dev ++ FROM dhi.io/golang:1.25-debian13-dev ``` To find the right tag, explore the available tags in the [DHI @@ -74,7 +74,7 @@ contain package managers. - && rm -rf /var/lib/apt/lists/* + ## DHI: Use a language-specific dev image with package manager -+ FROM dhi.io/golang:1-debian13-dev ++ FROM dhi.io/golang:1.25-debian13-dev + RUN apt-get update && apt-get install -y \ + git \ + && rm -rf /var/lib/apt/lists/* @@ -105,7 +105,7 @@ The following example shows a multi-stage Dockerfile migrating from Ubuntu to DH ```dockerfile # Build stage -FROM dhi.io/golang:1-debian13-dev AS builder +FROM dhi.io/golang:1.25-debian13-dev AS builder WORKDIR /app # Install system dependencies (only available in dev images) @@ -121,7 +121,7 @@ COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main . # Runtime stage -FROM dhi.io/golang:1-debian13 +FROM dhi.io/golang:1.25-debian13 WORKDIR /app # Copy compiled binary from builder diff --git a/content/manuals/dhi/migration/migrate-from-wolfi.md b/content/manuals/dhi/migration/migrate-from-wolfi.md index 5896451dba40..59de5e0e3f1f 100644 --- a/content/manuals/dhi/migration/migrate-from-wolfi.md +++ b/content/manuals/dhi/migration/migrate-from-wolfi.md @@ -10,7 +10,7 @@ Images (DHI). Generally, the migration process is straightforward since Wolfi is Alpine-like and DHI provides an Alpine-based hardened image. Like other hardened images, DHI provides comprehensive -[attestations](/dhi/core-concepts/attestations/) including SBOMs and provenance, +[attestations](/dhi/explore/security-concepts/attestations/) including SBOMs and provenance, allowing you to [verify](/manuals/dhi/how-to/verify.md) image signatures and [scan](/manuals/dhi/how-to/scan.md) for vulnerabilities to ensure the security and integrity of your images. @@ -34,7 +34,7 @@ replaced by the new hardened image. > You must authenticate to `dhi.io` before you can pull Docker Hardened Images. > Use your Docker ID credentials (the same username and password you use for > Docker Hub). If you don't have a Docker account, [create -> one](../../accounts/create-account.md) for free. +> one](../../accounts/individual/create-account.md) for free. > > Run `docker login dhi.io` to authenticate. @@ -43,7 +43,7 @@ replaced by the new hardened image. - FROM cgr.dev/chainguard/go:latest-dev + ## Updated to use hardened base image -+ FROM dhi.io/golang:1.25-alpine3.22-dev ++ FROM dhi.io/golang:1.25-alpine3.24-dev ``` Note that DHI does not have a `latest` tag in order to promote best practices @@ -70,20 +70,20 @@ The following example shows a multi-stage Dockerfile with a build stage and runt ```dockerfile # Build stage -FROM dhi.io/golang:1.25-alpine3.22-dev AS builder +FROM dhi.io/golang:1.25-alpine3.24-dev AS builder WORKDIR /app COPY . . RUN go build -o myapp # Runtime stage -FROM dhi.io/golang:1.25-alpine3.22 +FROM dhi.io/golang:1.25-alpine3.24 WORKDIR /app COPY --from=builder /app/myapp . ENTRYPOINT ["/app/myapp"] ``` After updating your Dockerfile, build and test your application. If you encounter -issues, see the [Troubleshoot](/manuals/dhi/troubleshoot.md) guide for common +issues, see the [Troubleshoot](/manuals/dhi/how-to/troubleshoot.md) guide for common problems and solutions. ## Language-specific examples diff --git a/content/manuals/dhi/migration/migrate-with-ai.md b/content/manuals/dhi/migration/migrate-with-ai.md index edc075c03ea9..f0056a7dfe7b 100644 --- a/content/manuals/dhi/migration/migrate-with-ai.md +++ b/content/manuals/dhi/migration/migrate-with-ai.md @@ -3,7 +3,7 @@ title: Migrate using Gordon linktitle: AI-assisted migration description: Use Gordon to automatically migrate your Dockerfile to Docker Hardened Images weight: 15 -keywords: ai assistant, migrate dockerfile, docker hardened images, automated migration +keywords: ai assistant, migrate Dockerfile, docker hardened images, automated migration params: sidebar: badge: diff --git a/content/manuals/dhi/release-notes/_index.md b/content/manuals/dhi/release-notes/_index.md new file mode 100644 index 000000000000..851969c4d894 --- /dev/null +++ b/content/manuals/dhi/release-notes/_index.md @@ -0,0 +1,6 @@ +--- +build: + render: never +title: Release notes +weight: 999 +--- diff --git a/content/manuals/dhi/release-notes/cli.md b/content/manuals/dhi/release-notes/cli.md new file mode 100644 index 000000000000..fb51db6e001c --- /dev/null +++ b/content/manuals/dhi/release-notes/cli.md @@ -0,0 +1,112 @@ +--- +title: DHI CLI release notes +linkTitle: CLI release notes +description: New features, bug fixes, and changes in the DHI CLI +keywords: docker hardened images, dhi, dhictl, cli, release notes, changelog +toc_min: 1 +toc_max: 2 +tags: + - Release notes +--- + +This page lists changes in recent stable releases of the DHI CLI (`docker dhi`). For +the full release history, including pre-releases and downloads, see the +[dhictl releases on GitHub](https://github.com/docker-hardened-images/dhictl/releases). + +<!-- BEGIN GENERATED RELEASES --> + +## 0.0.7 + +{{< release-date date="2026-07-21" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.7) + +### Bug Fixes + +- Fixes JSON output incorrectly escaping ampersands as `\u0026` — values such as catalog categories containing `&` now appear as-is in output + +## 0.0.6 + +{{< release-date date="2026-07-13" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.6) + +This release fixes an issue that prevented customizations from being created via the CLI. + +### Bug Fixes + +- Fixes `dhictl customization create` failing when GraphQL rejected mutation inputs that incorrectly included the output-only `__typename` field from OCI artifact data + +## 0.0.5 + +{{< release-date date="2026-06-29" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.5) + +Maintenance release with dependency updates. + +## 0.0.4 + +{{< release-date date="2026-05-25" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.4) + +### What's New + +- Adds `deb` subcommand for DHI DEB repositories that emits netrc-style credentials for authenticating against DHI DEB repositories + +## 0.0.3 + +{{< release-date date="2026-04-22" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.3) + +### What's New + +- Adds attestation list and get commands for managing attestations +- Adds SBOM subcommand for software bill of materials attestation +- Adds bulk support to prepare command for customizations +- Adds compression field support for customizations +- Adds tag-definition-id column to catalog get output + +### Breaking change + +We removed the `--output` flags from the few commands that had it (`customization prepare` and `customization get`) in favor of stdout redirections. +```console +# before +dhictl customization prepare --org my-org golang 1.25 --output my-customization.yaml + +# after +dhictl customization prepare --org my-org golang 1.25 > my-customization.yaml +``` + +## 0.0.2 + +{{< release-date date="2026-03-19" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.2) + +This is a maintenance release focused on build system improvements. + +### Technical Changes + +- Disables CGO globally to fix macOS 16 dyld crash and simplify build process + +## 0.0.1 + +{{< release-date date="2026-03-12" >}} + +[GitHub release](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.1) + +This release improves the mirroring functionality in dhictl by allowing command arguments. + +### Improvements + +- Mirror start command now accepts arguments for more flexible mirroring operations + +<!-- END GENERATED RELEASES --> + +## Earlier releases + +For older versions, see the +[dhictl releases on GitHub](https://github.com/docker-hardened-images/dhictl/releases). diff --git a/content/manuals/dhi/release-notes/platform.md b/content/manuals/dhi/release-notes/platform.md new file mode 100644 index 000000000000..5164ff99e00e --- /dev/null +++ b/content/manuals/dhi/release-notes/platform.md @@ -0,0 +1,122 @@ +--- +title: Docker Hardened Images release notes +linkTitle: Platform release notes +description: Learn about the latest features and changes in Docker Hardened Images +keywords: docker hardened images, dhi, release notes, changelog, features, changes, new, releases +tags: [Release notes] +--- + + +This page contains information about the new features, improvements, and changes +in the Docker Hardened Images (DHI) platform. Release notes are aggregated by +quarter and include only notable product changes. + +## Q4 2026 + +New features and enhancements released in the fourth quarter of 2026. + +- EU data residency (early access): Docker can provision your DHI + subscription in the EU region. When your subscription is in the EU region, + Docker stores your mirrored and customized images in the EU. For more + information, see [EU data residency](../explore/eu-region.md). + +## Q3 2026 + +New features and enhancements released in the third quarter of 2026. + +- DHI MCP server: The DHI catalog is now accessible via a remote MCP server at + `https://dhi.io/mcp`. Connect any MCP-capable AI assistant to search + repositories, inspect image metadata, retrieve SBOMs, check CVEs, and manage + mirrors using plain language. For more information, see [Use the DHI MCP + server](/dhi/tools/mcp/). +- DHI API: VEX statements and suppressed CVEs for a Docker Hardened Image are + now available to query by digest through the DHI GraphQL API. For more + information, see [Use the DHI API](../tools/api.md). +- DHI webhook payloads: Webhooks on a mirrored Docker Hardened Image repository + now include a `dhi_metadata` object describing the vulnerability fixes, + package changes, and configuration changes between builds. For more + information, see [Automate syncing with + webhooks](../how-to/mirror.md#automate-syncing-with-webhooks). + +## Q2 2026 + +New features and enhancements released in the second quarter of 2026. + +- Debian Hardened System Packages: Added support for Debian-based Docker + Hardened System Packages (HSP), including new CLI workflows for authenticating + to the Debian HSP repository. +- Mend.io scanner integration: Mend.io is now a supported scanner for consuming + DHI VEX data. +- Black Duck scanner integration: Black Duck is now a supported scanner for + consuming DHI VEX data. +- DHI Select self-serve purchase: DHI Select is now available for self-serve + purchase directly through the Docker website. +- Bulk customization: Apply customizations to multiple images in a single + operation through the Docker Hub UI and the CLI. +- Terraform provider: Manage DHI resources, including customizations and + mirrors, using the official Terraform provider. + +## Q1 2026 + +New features and enhancements released in the first quarter of 2026. + +- Docker Hardened System Packages (HSP): Announced Docker Hardened System + Packages, a new offering that provides individually hardened packages for use + in your own base images. For more information, see the [announcement blog + post](https://www.docker.com/blog/announcing-docker-hardened-system-packages/). +- Wiz scanner integration: Wiz is now a supported scanner for consuming DHI VEX + data. + +## Q4 2025 + +New features and enhancements released in the fourth quarter of 2025. + +- Docker Hardened Images Community (Free): Docker Hardened Images are now + available for every developer through a Community subscription tier. The + subscription tiers are now Community, Select, and Enterprise. For more + information, see the [announcement blog + post](https://www.docker.com/blog/docker-hardened-images-for-every-developer/). +- Independent security validation by SRLabs: SRLabs published an independent + security validation of Docker Hardened Images. See the + [validation announcement](https://www.docker.com/blog/docker-hardened-images-security-independently-validated-by-srlabs/). +- Docker Scout scoring for DHI: Docker Scout image scoring now accounts for the + security improvements provided by DHI. +- Trivy VEX repository: VEX data for DHI is published in a Trivy-compatible OCI + VEX repository, making it easier for Trivy and other scanners to consume. +- Docker Scout DHI policy: New Docker Scout policy that evaluates whether images + use Docker Hardened Images. +- Hardened Helm charts (Beta): Beta release of Docker Hardened Helm Charts. For + more information, see the [announcement blog + post](https://www.docker.com/blog/docker-hardened-images-helm-charts-beta/). +- Mirroring UX: Updated the mirroring experience in Docker Hub with a refreshed + UI and clearer flows. + +## Q3 2025 + +New features and enhancements released in the third quarter of 2025. + +- Next evolution release: A major release that introduced customizations, + FedRAMP-ready images, the AI Migration Agent, and deeper scanner integrations. + See the [announcement blog + post](https://www.docker.com/blog/the-next-evolution-of-docker-hardened-images/) + and the [FedRAMP compliance blog + post](https://www.docker.com/blog/fedramp-compliance-with-hardened-images/). +- DHI customizations: Customize DHI images directly from the Docker Hub UI, + with options for adding packages, files, and configuration on top of a base + hardened image. +- AI Migration Agent: AI-assisted Dockerfile migration to help convert existing + Dockerfiles to use Docker Hardened Images. +- CIS compliance attestations: CIS benchmark compliance attestations are now + included with DHI images. +- STIG variants: STIG-hardened image variants for U.S. Department of Defense + compliance use cases. + +## Q2 2025 + +New features and enhancements released in the second quarter of 2025. + +- Docker Hardened Images launch: Docker announced Docker Hardened Images, a new + family of secure, minimal, and production-ready container images maintained by + Docker. For more information, see the [launch blog + post](https://www.docker.com/blog/introducing-docker-hardened-images/). +- FIPS variants: FIPS-validated image variants for Docker Hardened Images. diff --git a/content/manuals/dhi/resources.md b/content/manuals/dhi/resources.md index 9f55a2566af8..78619da5414d 100644 --- a/content/manuals/dhi/resources.md +++ b/content/manuals/dhi/resources.md @@ -1,39 +1,20 @@ --- -title: Docker Hardened Images resources -linktitle: Additional resources -description: Additional resources including product information, blog posts, and GitHub repositories for Docker Hardened Images +title: Resources and feedback +linktitle: Resources and feedback +description: Additional resources, community links, GitHub repositories, and how to give feedback for Docker Hardened Images. +keywords: docker hardened images resources, dhi feedback, dhi github, dhi community, report issue, dhi support weight: 999 +aliases: + - /dhi/about/feedback/ + - /dhi/explore/feedback/ --- -This page provides links to additional resources related to Docker Hardened -Images (DHI), including blog posts, guides, Docker Hub resources, and GitHub -repositories. +This page provides links to additional resources, community channels, and ways +to give feedback on Docker Hardened Images (DHI). For product information and feature comparison, visit the [Docker Hardened Images product page](https://www.docker.com/products/hardened-images/). -## Blog posts - -The following blog posts provide insights into Docker Hardened Images, security -features, and announcements: - -| Date published | Title | -|------|-------| -| May 5, 2026 | [Precision Container Security with Docker and Black Duck](https://www.docker.com/blog/precision-container-security-with-docker-and-black-duck/) | -| April 14, 2026 | [Why We Chose the Harder Path: Docker Hardened Images, One Year Later](https://www.docker.com/blog/why-we-chose-the-harder-path-docker-hardened-images-one-year-later/) | -| April 8, 2026 | [Reclaim Developer Hours through Smarter Vulnerability Prioritization with Docker and Mend.io](https://www.docker.com/blog/reclaim-developer-hours-through-smarter-vulnerability-prioritization-with-docker-and-mend-io/) | -| March 3, 2026 | [Announcing Docker Hardened System Packages](https://www.docker.com/blog/announcing-docker-hardened-system-packages/) | -| January 25, 2026 | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 3](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-enterprise-trial-part-3/) | -| January 24, 2026 | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 2](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-enterprise-trial-part-2/) | -| December 19, 2025 | [Docker Hardened Images: Security Independently Validated by SRLabs](https://www.docker.com/blog/docker-hardened-images-security-independently-validated-by-srlabs/) | -| December 17, 2025 | [A Safer Container Ecosystem with Docker: Free Docker Hardened Images](https://www.docker.com/blog/docker-hardened-images-for-every-developer/) | -| November 14, 2025 | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 1](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-trial-part-1/) | -| October 15, 2025 | [Docker Hardened Images: Crafted by Humans, Protected by AI](https://www.docker.com/blog/docker-hardened-images-crafted-by-humans-protected-by-ai/) | -| September 29, 2025 | [Expanding Docker Hardened Images: Secure Helm Charts for Deployments](https://www.docker.com/blog/docker-hardened-images-helm-charts-beta/) | -| August 6, 2025 | [The Next Evolution of Docker Hardened Images: Customizable, FedRAMP Ready, AI Migration Agent, and Deeper Integrations](https://www.docker.com/blog/the-next-evolution-of-docker-hardened-images/) | -| August 6, 2025 | [Accelerating FedRAMP Compliance with Docker Hardened Images](https://www.docker.com/blog/fedramp-compliance-with-hardened-images/) | -| May 19, 2025 | [Introducing Docker Hardened Images: Secure, Minimal, and Ready for Production](https://www.docker.com/blog/introducing-docker-hardened-images/) | - ## Guides For guides that demonstrate how to use Docker Hardened Images in various @@ -65,13 +46,14 @@ organization: keys and verification tools - [Log](https://github.com/docker-hardened-images/log): Log of references (tag > digest) for Docker Hardened Images +- [Policies](https://github.com/docker-hardened-images/policies): Rego source + for the Docker Scout policies used to enforce DHI security and compliance + standards - [dhictl](https://github.com/docker-hardened-images/dhictl): Command-line interface for managing and interacting with Docker Hardened Images - [Terraform Provider](https://github.com/docker-hardened-images/terraform-provider-dhi): Terraform provider for managing DHI resources ([Terraform Registry](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs)) -- [Discussions](https://github.com/orgs/docker-hardened-images/discussions): - Community forum and product discussions ## Additional resources @@ -84,8 +66,28 @@ organization: personalized demo and information about DHI Select and Enterprise subscriptions - [Request an image](https://github.com/docker-hardened-images/catalog/issues): Submit a request for a specific Docker Hardened Image +- [Debian package index](https://dhi.io/deb/debian/main/index.html): + Browse hardened Debian packages in Docker's public repository +- [Alpine package index](https://dhi.io/apk/alpine/v3.24/main/index.html): + Browse hardened Alpine packages in Docker's public repository - <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_dhi_resources" class="link" rel="noopener">Contact Sales</a>: Connect with Docker sales team for enterprise inquiries - [Docker Support](https://www.docker.com/support/): Access support resources for DHI Select and Enterprise customers +## Feedback and community + +Use the [GitHub Discussions board](https://github.com/orgs/docker-hardened-images/discussions) +to engage with the DHI team for general questions, best practices, security +tips, and community announcements. + +To report a bug, request a feature, or suggest a documentation improvement, +[open an issue](https://github.com/docker-hardened-images/catalog/issues) in +the catalog repository. + +## Security disclosure + +Do not post details of vulnerabilities before coordinated disclosure and +resolution. If you discover a security vulnerability, report it responsibly +by following Docker's [security disclosure +policy](https://www.docker.com/trust/vulnerability-disclosure-policy/). diff --git a/content/manuals/dhi/tools/_index.md b/content/manuals/dhi/tools/_index.md new file mode 100644 index 000000000000..32e39ce4aa32 --- /dev/null +++ b/content/manuals/dhi/tools/_index.md @@ -0,0 +1,32 @@ +--- +title: Tools +description: Interfaces and tools for browsing, managing, and automating Docker Hardened Images. +weight: 25 +params: + grid_tools: + - title: Use Docker Hub + description: Browse the DHI catalog on Docker Hub to search repositories, inspect image metadata, and view SBOMs, CVEs, and attestations. + icon: squares-2x2 + link: /dhi/tools/hub/ + - title: CLI + description: Install and use the `docker dhi` command-line interface to browse the catalog, inspect images, and manage mirrors from your terminal. + icon: command-line + link: /dhi/tools/cli/ + - title: MCP server + description: Connect an AI assistant to the DHI catalog to search repositories, inspect images, retrieve SBOMs, and check CVEs using plain language. + icon: cpu-chip + link: /dhi/tools/mcp/ + - title: Use the DHI Terraform provider + description: Use the DHI Terraform provider to manage mirrors and automate DHI configuration as infrastructure as code. + icon: wrench-screwdriver + link: /dhi/tools/terraform/ + - title: Use the DHI API + description: Query Docker Hardened Images data programmatically using the DHI GraphQL API. + icon: code-bracket + link: /dhi/tools/api/ +--- + +Docker Hardened Images can be accessed and managed through several interfaces. +Choose the tool that fits your workflow. + +{{< grid items="grid_tools" >}} diff --git a/content/manuals/dhi/tools/api.md b/content/manuals/dhi/tools/api.md new file mode 100644 index 000000000000..e52f50e5b5cc --- /dev/null +++ b/content/manuals/dhi/tools/api.md @@ -0,0 +1,142 @@ +--- +title: Use the DHI API +linktitle: API +description: Query Docker Hardened Images data programmatically using the DHI GraphQL API. +weight: 50 +keywords: dhi api, docker hardened images api, graphql api, dhi endpoint, dhi authentication +--- + +The DHI API is a GraphQL API for querying Docker Hardened Images data +programmatically, for use cases like building automation or dashboards on +top of DHI data. + +## Endpoint + +Send requests as `POST` requests to: + +```text +https://api.dso.docker.com/v1/graphql +``` + +## Request format + +The API accepts standard GraphQL requests: a JSON body with a `query` and, +optionally, `variables`. + +```console +$ curl https://api.dso.docker.com/v1/graphql \ + -H "Authorization: Bearer <token>" \ + -H "Content-Type: application/json" \ + -d '{"query": "...", "variables": { ... }}' +``` + +Every query takes a `Context` argument (conventionally named `ctx` in the +`variables` object) alongside its query-specific arguments: + +| Argument | Type | Required | Description | +|---|---|---|---| +| `ctx` | `Context` | Yes | Scopes the request to an organization. | +| `ctx.organization` | `String` | Yes | The Docker organization the token belongs to. | + +## Authentication + +An [organization access token](/manuals/security/access-tokens/organization-access-tokens.md) +(OAT) or personal access token (PAT) isn't used directly as the bearer +token. Exchange it first for an access token: + +```console +$ curl -X POST https://hub.docker.com/v2/auth/token \ + -H "Content-Type: application/json" \ + -d '{"identifier": "<identifier>", "secret": "<token>"}' +``` + +For `identifier`, use your Docker Hub username with a PAT, or the +organization name with an OAT. The response contains the access token: + +```json +{ "access_token": "..." } +``` + +Pass that `access_token` as `Authorization: Bearer <access_token>`. Also set +`ctx.organization` in `variables` to the organization the token belongs to +(see [Request format](#request-format)). + +## Response format + +Responses follow the standard GraphQL envelope: + +| Key | Description | +|---|---| +| `data` | The requested fields. A field is `null` if it couldn't be resolved, for example due to an authorization failure. | +| `errors` | Present when a field failed to resolve. Includes a `message` and a `path` identifying which field failed. | +| `extensions` | Metadata such as a `correlation_id`, useful when reporting an issue. | + +For example, an unauthenticated request, or a request for data your token +can't access, returns a `null` result under `data` alongside an authorization +error in `errors`, rather than an HTTP-level failure: + +```json +{ + "errors": [ + { + "message": "You are not allowed to read data for this team", + "path": ["someQuery"], + "extensions": { "code": "DOWNSTREAM_SERVICE_ERROR", "status": 403 } + } + ], + "data": { "someQuery": null }, + "extensions": { "correlation_id": "..." } +} +``` + +## Queries + +### `imagePackagesForImageCoords` + +Fetches every package in an image, every CVE reported against it, and +whether Docker suppresses that CVE, by digest. See [Query VEX for a Docker +Hardened Image](/manuals/dhi/how-to/vex-api.md) for a guided example. + +| Argument | Type | Required | Description | +|---|---|---|---| +| `digest` | `String` | Yes | The image's platform manifest digest, not the multi-arch index digest. | +| `hostName` | `String` | Yes | `hub.docker.com` or `docker.io`. | +| `repoName` | `String` | Yes | Repository name, with or without the namespace prefix. | +| `includeExcepted` | `Boolean` | No | Include suppressed CVEs in the response alongside the reason for suppression. Without it, the response only shows the netted list, with no visibility into what was suppressed. | +| `includeNodsa` | `Boolean` | No | Include Debian NODSA exclusions, which make up most suppressions on a Debian-based image. | +| `includePublic` | `Boolean` | No | Also include public images when `ctx.organization` scopes the request to an organization. Not needed for a typical lookup. | + +Keep the requested response fields limited to what you plan to render. +Fields such as `locations`, `description`, `vulnerableRange`, and `epss` +increase response size substantially and aren't needed for a CVE-count or +suppressed-CVE view. + +#### Response fields + +`vulnerabilityExceptions` only contains records that actually suppress a +CVE, so it always lines up with `isExcepted`: an empty array means the CVE +is live. Use `isExcepted` as your filter for "is this CVE suppressed." + +| Field | Meaning | +|---|---| +| `isExcepted` | Docker suppresses this CVE for this image. Use this to filter. | +| `sourceType` | `EXTERNAL` (Debian NODSA), `MANUAL_EXCEPTION` (Docker analyst exception), or `VEX_STATEMENT` (an ingested VEX document). | +| `type` | `FALSE_POSITIVE` and `ACCEPTED_RISK` suppress the CVE. `UNDER_INVESTIGATION` and `AFFECTED` don't. | +| `justification` | The OpenVEX justification value. Always `null` for NODSA exclusions. | +| `additionalDetails` | Free-text rationale for the suppression. | +| `isDhiStatement` | Whether the statement is inherited from the DHI base image. | +| `id` | Stable identifier for the statement. | + +#### Mapping to OpenVEX + +If your pipeline consumes OpenVEX documents (for example, Trivy's `--vex` +flag), each suppressed record maps as follows: + +| OpenVEX field | Source | +|---|---| +| `vulnerability.name` | `sourceId` | +| `products[].@id` | The parent package's `purl` | +| `status` | `not_affected` (from `type: FALSE_POSITIVE`) | +| `justification` | `justification`, defaulting to `vulnerable_code_cannot_be_controlled_by_adversary` for NODSA exclusions | +| `status_notes` | `additionalDetails` | +| `@id` | `id` | diff --git a/content/manuals/dhi/tools/cli.md b/content/manuals/dhi/tools/cli.md new file mode 100644 index 000000000000..083e4045dcb3 --- /dev/null +++ b/content/manuals/dhi/tools/cli.md @@ -0,0 +1,291 @@ +--- +title: Use the DHI CLI +linkTitle: CLI +weight: 20 +keywords: docker dhi, CLI, command line, docker hardened images +description: Learn how to install and use docker dhi, the command-line interface for managing Docker Hardened Images. +aliases: + - /dhi/how-to/cli/ +--- + +The `docker dhi` command-line interface (CLI) is a tool for managing Docker Hardened Images: +- Browse the catalog of available DHI images and their metadata +- View attestations for DHI images, including SBOMs and provenance +- Mirror DHI images to your Docker Hub organization +- Create and manage customizations of DHI images +- Generate authentication for enterprise package repositories +- Monitor customization builds + +## Installation + +The `docker dhi` CLI is available in [Docker Desktop](https://docs.docker.com/desktop/) version 4.65 and later. +You can also install the standalone `dhictl` binary. + +### Docker Desktop + +The `docker dhi` command is included in Docker Desktop 4.65 and later. No additional installation is required. + +### Standalone binary + +1. Download the `dhictl` binary for your platform from the + [releases](https://github.com/docker-hardened-images/dhictl/releases) page. +2. Move it to a directory in your `PATH`: + - `mv dhictl /usr/local/bin/` on _Linux_ and _macOS_ + - Move `dhictl.exe` to a directory in your `PATH` on _Windows_ + +## Usage + +Every command has built-in help accessible with the `--help` flag: + +```console +$ docker dhi --help +$ docker dhi catalog list --help +``` + +### Browse the DHI catalog + +List all available DHI images: + +```console +$ docker dhi catalog list +``` + +Filter by type, name, or compliance: + +```console +$ docker dhi catalog list --type image +$ docker dhi catalog list --filter golang +$ docker dhi catalog list --fips +$ docker dhi catalog list --stig +``` + +Get details of a specific image, including available tags and CVE counts: + +```console +$ docker dhi catalog get <image-name> +``` + +### View attestations + +List all attestations attached to a DHI image: + +```console +$ docker dhi attestation list dhi/nginx:1.27 +$ docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64 +$ docker dhi attestation list dhi/nginx:1.27 --predicate-type https://slsa.dev/provenance/v1 +$ docker dhi attestation list dhi/nginx:1.27 --json +``` + +Get a specific attestation by its referrer digest: + +```console +$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> +$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> -o provenance.json +``` + +Display the SPDX SBOM for an image: + +```console +$ docker dhi attestation sbom dhi/nginx:1.27 +$ docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64 +``` + +### Mirror DHI images + +{{< summary-bar feature_name="Docker Hardened Images" >}} + +Start mirroring one or more DHI images to your Docker Hub organization: + +```console +$ docker dhi mirror start --org my-org \ + dhi/golang,my-org/dhi-golang \ + dhi/nginx,my-org/dhi-nginx \ + dhi/prometheus-chart,my-org/dhi-prometheus-chart +``` + +Mirror with dependencies: + +```console +$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies +``` + +List mirrored images in your organization: + +```console +$ docker dhi mirror list --org my-org +``` + +Filter mirrored images by name or type: + +```console +$ docker dhi mirror list --org my-org --filter python +$ docker dhi mirror list --org my-org --type image +$ docker dhi mirror list --org my-org --type helm-chart +``` + +Stop mirroring one or more images: + +```console +$ docker dhi mirror stop dhi-golang --org my-org +$ docker dhi mirror stop dhi-python dhi-golang --org my-org +``` + +Stop mirroring and delete the repositories: + +```console +$ docker dhi mirror stop dhi-golang --org my-org --delete +$ docker dhi mirror stop dhi-golang --org my-org --delete --force +``` + +### Customize DHI images + +{{< summary-bar feature_name="Docker Hardened Images" >}} + +The CLI can be used to create and manage DHI image customizations. For detailed +instructions on creating customizations using the GUI, see [Customize a Docker +Hardened Image](../how-to/customize.md). + +The following is a quick reference for CLI commands. For complete details on all +options and flags, see the +[CLI reference](/reference/cli/docker/dhi/). + +```console +# Prepare a single customization scaffold +$ docker dhi customization prepare golang 1.25 \ + --org my-org \ + --destination my-org/dhi-golang \ + --name "golang with git" \ + > my-customization.yaml + +# Prepare a bulk customization scaffold (pipe JSON array via stdin) +$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \ + | docker dhi customization prepare --name "golang with git" --org my-org \ + > my-customization.yaml + +# Create a customization +$ docker dhi customization create my-customization.yaml --org my-org + +# Create with flag overrides (flags take precedence over the YAML file) +$ docker dhi customization create my-customization.yaml --org my-org \ + --destination my-org/dhi-golang \ + --name "golang with git" + +# List customizations +$ docker dhi customization list --org my-org + +# Filter customizations by name, repository, or source +$ docker dhi customization list --org my-org --filter git +$ docker dhi customization list --org my-org --repo dhi-golang +$ docker dhi customization list --org my-org --source golang + +# Get a customization by ID +$ docker dhi customization get <id> --org my-org + +# Update a customization +# The YAML file must include the 'id' field to identify the customization to update +$ docker dhi customization edit my-customization.yaml --org my-org + +# Delete a customization by ID +$ docker dhi customization delete <id> --org my-org + +# Delete multiple customizations +$ docker dhi customization delete <id1> <id2> --org my-org + +# Delete without confirmation prompt +$ docker dhi customization delete <id> --org my-org --force +``` + +For a complete reference of all YAML fields, see +[Image customization YAML file](/dhi/how-to/customize/#image-customization-yaml-file). + +### Enterprise package authentication + +{{< summary-bar feature_name="Docker Hardened Images Enterprise" >}} + +Generate authentication credentials for accessing the enterprise hardened +package repository. These credentials are used when configuring your package +manager to install compliance and security-patched packages in your own images. For detailed +instructions, see [Enterprise +repository](../how-to/hardened-packages.md#enterprise-repository). + +For Alpine-based images: + +```console +$ docker dhi auth apk +``` + +For Debian-based images: + +```console +$ docker dhi auth deb +``` + +### Monitor customization builds + +{{< summary-bar feature_name="Docker Hardened Images" >}} + +List builds for a customization: + +```console +$ docker dhi customization build list <customization-id> --org my-org +$ docker dhi customization build list <customization-id> --org my-org --json +``` + +Get details of a specific build: + +```console +$ docker dhi customization build get <customization-id> <build-id> --org my-org +$ docker dhi customization build get <customization-id> <build-id> --org my-org --json +``` + +View build logs: + +```console +$ docker dhi customization build logs <customization-id> <build-id> --org my-org +$ docker dhi customization build logs <customization-id> <build-id> --org my-org --json +``` + +### JSON output + +Most list and get commands support a `--json` flag for machine-readable output: + +```console +$ docker dhi catalog list --json +$ docker dhi catalog get golang --json +$ docker dhi attestation list dhi/nginx:1.27 --json +$ docker dhi mirror list --org my-org --json +$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --json +$ docker dhi customization list --org my-org --json +$ docker dhi customization build list <customization-id> --org my-org --json +``` + +## Configuration + +The `docker dhi` CLI can be configured with a YAML file located at: +- `$HOME/.config/dhictl/config.yaml` on _Linux_ and _macOS_ +- `%USERPROFILE%\.config\dhictl\config.yaml` on _Windows_ + +If `$XDG_CONFIG_HOME` is set, the configuration file is located at `$XDG_CONFIG_HOME/dhictl/config.yaml`. + +Available configuration options: + +| Option | Environment Variable | Description | +|-------------|----------------------|---------------------------------------------------------------------------------------------------------------------------| +| `org` | `DHI_ORG` | Default Docker Hub organization for mirror and customization commands. | +| `api_token` | `DHI_API_TOKEN` | Access token for authentication, obtained by exchanging a personal access token (PAT) or organization access token (OAT) for an access token. | + +Environment variables take precedence over configuration file values. + +To get an access token, exchange a [personal access token +(PAT)](/manuals/security/access-tokens/personal-access-tokens.md) or +[organization access token +(OAT)](/manuals/security/access-tokens/organization-access-tokens.md): + +```console +$ export DHI_API_TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \ + -H "Content-Type: application/json" \ + -d '{"identifier": "<identifier>", "secret": "<token>"}' \ + | jq -r .access_token) +``` + +Use your Docker Hub username as `identifier` for a PAT, or your organization name for an OAT. diff --git a/content/manuals/dhi/tools/hub.md b/content/manuals/dhi/tools/hub.md new file mode 100644 index 000000000000..384ccbce576b --- /dev/null +++ b/content/manuals/dhi/tools/hub.md @@ -0,0 +1,109 @@ +--- +title: Use Docker Hub +linktitle: Docker Hub +description: Browse the DHI catalog on Docker Hub to search repositories, inspect image metadata, and view SBOMs, CVEs, and attestations. +weight: 10 +keywords: docker hub dhi catalog, hardened images hub, dhi repository details, image variants hub +--- + +The [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) +on Docker Hub is the primary web interface for browsing, searching, and inspecting +DHI repositories and their metadata. + +## Catalog page + +The catalog lists all available DHI repositories. Use the search bar to find a +repository by name, and use the following filters to narrow the list: + +- Categories +- Compliance: FIPS or STIG. +- Types: Image or Helm chart. +- OS: Alpine or Debian. +- Versions: Extended Lifecycle Support. + +Use **Sort by** to order the results by popularity, recently updated, recently +added, or alphabetical. + +## Repository details page + +When you select a repository from the catalog, the repository details page +provides the following: + +- Overview: A brief explanation of the image. +- Guides: Several guides on how to use the image and migrate your existing application. +- Images: Select this tab to [view image variants](#images-page). Helm chart + repositories have a Tags tab instead. +- Use this image: Select this button to view instructions on how to pull and use + the image, or select **Mirror repository** to mirror it to your organization. + For Helm chart repositories, the button reads **Use this chart**. + +## Images page + +From the repository details page, select **Images** to see all available image +variants for that repository. The table includes: + +- Image version: The image name with its base distribution (for example, `debian + 13`) and associated tags. +- Type: The support lifecycle status of the variant. +- Compliance: Relevant compliance designations, for example `CIS`, `FIPS`, or + `STIG (100%)`. +- Package manager: Whether a package manager is available. A checkmark indicates + a package manager is present (for example, `apt` or `apk`), a dash indicates + none. +- Shell: Whether a shell is available. A checkmark indicates a shell is present + (for example, `bash` or `busybox`), a dash indicates none. +- User: The user that the container runs as, for example `root` or `nonroot + (65532)`. +- Last pushed: When the image variant was last updated. +- Vulnerabilities: Vulnerability counts by severity level. + +## Image variant details page + +Select an image version from the Images table to view detailed information about +that specific variant: + +- Packages: A list of all packages included in the image variant, with each + package's name, version, distribution, and licensing information. +- Specifications: + - Source and build information: The Dockerfile and Git commit used to build the image. + - Build parameters, entrypoint, CMD, user, working directory, environment + variables, labels, and platform. +- Vulnerabilities: A list of known CVEs for the image variant, including CVE ID, + severity, affected package, fix version, last detected date, status, and + suppressed CVEs. +- Attestations: Signed security attestations covering the image's build process, + contents, and security posture. For the full list, see + [Attestations](/dhi/explore/security-concepts/attestations/). + +## Manage page + +The Manage page (**My Hub** > **Hardened Images** > **Manage**) is the central +place for administering your organization's mirrored DHI repositories. It has +two tabs: + +- Mirrored Images: Lists all image repositories currently mirrored to your + organization, with their source DHI repository, destination repository name, + and mirroring status. From here you can stop mirroring or open a repository's + settings. +- Mirrored Helm charts: The same view for Helm chart repositories. + +Selecting a mirrored repository opens its settings, where you can enable or +disable Extended Lifecycle Support (ELS) and access customizations. + +For step-by-step instructions, see [Mirror a Docker Hardened Image +repository](/dhi/how-to/mirror/). + +## Customizations + +Customizations are accessible from **My Hub** > **Hardened Images** > **Manage** > **Mirrored Images**. +Select the menu icon next to a mirrored repository and +then **Customize**. Each customization defines +additional packages, OCI artifacts, environment variables, or labels to layer +onto the base DHI during a rebuild. + +The customizations view shows each customization's name, status, and last build +time. Selecting a customization opens its configuration, where you can edit the +definition, trigger a rebuild, or delete it. + +For step-by-step instructions, see [Customize a Docker Hardened +Image](/dhi/how-to/customize/). diff --git a/content/manuals/dhi/tools/mcp.md b/content/manuals/dhi/tools/mcp.md new file mode 100644 index 000000000000..d894d26e0efd --- /dev/null +++ b/content/manuals/dhi/tools/mcp.md @@ -0,0 +1,211 @@ +--- +title: Use the DHI MCP server +linktitle: MCP server +description: Connect an AI assistant to the Docker Hardened Images catalog using the DHI MCP server to search repositories, inspect images, view SBOMs, and check CVEs. +weight: 30 +keywords: docker hardened images mcp, ai assistant dhi, mcp server docker, dhi catalog ai, claude cursor docker images, sbom mcp, cve mcp +aliases: + - /dhi/how-to/mcp/ +--- + +The Docker Hardened Images (DHI) MCP server exposes the DHI catalog through the +Model Context Protocol (MCP), letting you query repositories, inspect image +metadata, retrieve SBOMs, and check CVEs directly from your AI assistant in +plain language. + +The MCP server is: + +- Remote. No local binary to install. Your AI assistant connects directly to + `https://dhi.io/mcp`. +- Compatible with any MCP-capable AI assistant, including Claude, + Cursor, and others. + +Most tools are public and require no credentials. The mirror management tools +(`dhi_list_mirrors`, `dhi_create_mirror`, `dhi_remove_mirror`) require a Docker +Hub username and personal access token (PAT) with owner access to the target +organization. Credentials are passed as an HTTP Basic auth header in the MCP +client configuration — they are never passed as tool arguments. + +## Connect your AI assistant + +Configuration varies by client. Select the tab for your AI assistant. + +{{< tabs >}} +{{< tab name="Claude Desktop" >}} + +Add the following to your Claude Desktop configuration file: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +The configuration file is located at: +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\Claude\claude_desktop_config.json` + +{{< /tab >}} +{{< tab name="Cursor" >}} + +Add the following to `.cursor/mcp.json` in your project, or +`~/.cursor/mcp.json` globally: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +{{< /tab >}} +{{< tab name="Claude Code" >}} + +Run the following command to add the DHI MCP server: + +```console +$ claude mcp add dhi --url https://dhi.io/mcp +``` + +Or add it manually to `.claude/mcp.json` in your project: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +{{< /tab >}} +{{< tab name="Docker Agent" >}} + +In your [Docker Agent](/manuals/ai/docker-agent/_index.md) YAML configuration, add the +DHI MCP server as a remote toolset: + +```yaml +toolsets: + - type: mcp + remote: + url: "https://dhi.io/mcp" + transport_type: streamable +``` + +For example, to create an agent that can answer questions about the DHI catalog: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: DHI catalog assistant + instruction: | + Help me find and evaluate Docker Hardened Images. + Search the DHI catalog, inspect image details, check CVEs, + and retrieve SBOMs and attestations as needed. + toolsets: + - type: mcp + remote: + url: "https://dhi.io/mcp" + transport_type: streamable +``` + +Run the agent with: + +```console +$ docker agent run dhi-agent.yaml +``` + +{{< /tab >}} +{{< /tabs >}} + +## Available tools + +The DHI MCP server provides ten tools that your AI assistant calls automatically +based on what you ask: + +| Tool | What it does | +|------|-------------| +| `dhi_list_repositories` | Search and filter the DHI catalog by name, type, category, FIPS, or STIG compliance | +| `dhi_get_repository` | Get full details for a repository: tag definitions, build config, platforms, and per-manifest vulnerability counts | +| `dhi_get_tag_definition` | Get the deep view of a single tag definition | +| `dhi_get_image_details` | Get per-digest details: tags, platform, size, layer and package counts, vulnerability severity counts, and attestation types | +| `dhi_get_image_packages` | Retrieve the full software bill of materials (SBOM): package name, version, type, purl, licenses, and file locations | +| `dhi_get_image_cves` | List CVEs with severity, CVSS score, fix version, EPSS score, and CISA-exploited flag; filter by minimum severity or fixable-only | +| `dhi_get_image_attestations` | List SBOM, provenance, signature, and other attestations for a specific image digest | +| `dhi_list_mirrors` | List mirrored DHI repositories for a Docker Hub organization — requires authentication | +| `dhi_create_mirror` | Start mirroring a DHI repository into a Docker Hub organization — requires authentication | +| `dhi_remove_mirror` | Stop mirroring a repository by its mirror ID — requires authentication | + +## Authenticate for mirror tools + +The mirror tools require a Docker Hub username and [personal access token +(PAT)](/security/access-tokens/personal-access-tokens/) with owner access to the target organization, +passed as an HTTP Basic auth header. Generate the value with: + +```console +$ printf 'USERNAME:dckr_pat_...' | base64 | tr -d '\n' +``` + +Then add it to your MCP client configuration: + +> [!WARNING] +> Base64 encoding is not encryption. The value in your configuration file +> is effectively a plaintext password. Do not commit this file to version +> control or share it. + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp", + "headers": { + "Authorization": "Basic <base64-value>" + } + } + } +} +``` + +Without credentials, the read-only catalog tools work normally and the mirror +tools return an authentication error. + +## What the tools return + +Each tool returns structured data that your AI assistant can summarize, +compare, or act on: + +- `dhi_list_repositories` returns a list of repositories with display + name, distributions, platforms, FIPS/STIG flags, included tools, and category. +- `dhi_get_repository` returns the full repository record, including all tag + definitions with their tags, build configuration, image indexes, and + per-platform manifest digests with vulnerability counts. +- `dhi_get_tag_definition` returns tags, build parameters, entrypoint, + environment variables, run-as user, and per-platform manifests for a single + tag definition. +- `dhi_get_image_details` returns the image platform, compressed size, layer + count, package count, vulnerability severity counts by level, labels, and + a list of attestation predicate types. +- `dhi_get_image_packages` returns each package in the image with its name, + version, type (`deb`, `rpm`, `apk`, etc.), purl, licenses, and the file paths where + it was found. +- `dhi_get_image_cves` returns each CVE affecting the image with its + severity, CVSS score and vector, affected package, fix version (if any), EPSS + probability score, and a flag indicating whether CISA lists it as + actively exploited. +- `dhi_get_image_attestations` returns the predicate type and OCI reference + for each attestation attached to the image digest. +- `dhi_list_mirrors` returns each mirror's ID, source DHI repository, + destination repository, and mirroring status for the given organization. +- `dhi_create_mirror` starts mirroring a DHI source repository into the + specified organization and destination repository name. +- `dhi_remove_mirror` stops mirroring for the given mirror ID. It does not + delete the destination repository — only stops new images from being synced. diff --git a/content/manuals/dhi/tools/terraform.md b/content/manuals/dhi/tools/terraform.md new file mode 100644 index 000000000000..176ad2f0ccd6 --- /dev/null +++ b/content/manuals/dhi/tools/terraform.md @@ -0,0 +1,65 @@ +--- +title: Use the DHI Terraform provider +linktitle: Terraform +description: Use the DHI Terraform provider to manage mirrors and customizations as infrastructure as code. +weight: 40 +keywords: dhi terraform, docker hardened images terraform, infrastructure as code, dhi mirror terraform, dhi provider +--- + +The [DHI Terraform provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs) +lets you manage Docker Hardened Image mirrors and customizations as +infrastructure as code. + +## Install and configure the provider + +Add the provider to your Terraform configuration: + +```hcl +terraform { + required_providers { + dhi = { + source = "docker-hardened-images/dhi" + } + } +} + +provider "dhi" { + docker_hub_username = var.docker_username + docker_hub_password = var.docker_password + organization = var.org_name +} +``` + +Instead of specifying credentials in the provider block, you can set environment +variables: + +| Variable | Description | +|----------|-------------| +| `DOCKER_USERNAME` | Docker Hub username or organization namespace | +| `DOCKER_PASSWORD` | Docker Hub password or personal/organization access token | +| `DHI_ORG` | Target organization namespace | + +You can authenticate using a personal access token (PAT) or an organization +access token (OAT) in place of a password. When using an OAT, permission scopes +apply: + +- Read (pull) access is required to list mirrors. +- Push access is required to create or delete mirrors. + +## Resources + +### `dhi_mirror` + +Manages a mirrored DHI repository in your organization. See [Mirror a Docker +Hardened Image repository](/dhi/how-to/mirror/) for task-based examples. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/mirror). + +### `dhi_customization` + +Manages image customizations applied to a mirrored repository. See [Customize a +Docker Hardened Image](/dhi/how-to/customize/) for task-based examples. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/customization). diff --git a/content/manuals/dhi/troubleshoot.md b/content/manuals/dhi/troubleshoot.md deleted file mode 100644 index f3d86b07c823..000000000000 --- a/content/manuals/dhi/troubleshoot.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Troubleshoot -description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access. -weight: 40 -tags: [Troubleshooting] -keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container -aliases: -- /dhi/how-to/debug/ ---- - -This page covers debugging techniques and common issues you may encounter while -migrating to or using Docker Hardened Images (DHIs). - -## General debugging - -Docker Hardened Images prioritize minimalism and security, which means -they intentionally leave out many common debugging tools (like shells or package -managers). This makes direct troubleshooting difficult without introducing risk. -To address this, you can use [Docker -Debug](/reference/cli/docker/debug/), a secure workflow that -temporarily attaches an ephemeral debug container to a running service or image -without modifying the original image. - -This section shows how to debug Docker Hardened Images locally during development. -With Docker Debug, you can also debug containers remotely using the `--host` -option. - -### Use Docker Debug - -#### Step 1: Run a container from a Hardened Image - -Start with a DHI-based container that simulates an issue: - -```console -$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" -``` - -This container doesn't include a shell or tools like `ps`, `top`, or `cat`. - -If you try: - -```console -$ docker exec -it myapp sh -``` - -You'll see: - -```console -exec: "sh": executable file not found in $PATH -``` - -#### Step 2: Use Docker Debug to inspect the container - -Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. - -```console -$ docker debug myapp -``` - -From here, you can inspect running processes, network status, or mounted files. - -For example, to check running processes: - -```console -$ ps aux -``` - -Type `exit` to leave the container when done. - -### Alternative debugging approaches - -In addition to using Docker Debug, you can also use the following approaches for -debugging DHI containers. - -#### Use the -dev variant - -Docker Hardened Images offer a `-dev` variant that includes a shell -and a package manager to install debugging tools. Simply replace the image tag -with `-dev`: - -```console -$ docker run -it --rm dhi.io/python:3.13-dev sh -``` - -Type `exit` to leave the container when done. Note that using the `-dev` variant -increases the attack surface and it is not recommended as a runtime for -production environments. - -#### Mount debugging tools with image mounts - -You can use the image mount feature to mount debugging tools into your container -without modifying the base image. - -##### Step 1: Run a container from a hardened image - -Start with a DHI-based container that simulates an issue: - -```console -$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" -``` - -##### Step 2: Mount debugging tools into the container - -Run a new container that mounts a tool-rich image (like `busybox`) into -the running container's namespace: - -```console -$ docker run --rm -it --pid container:myapp \ - --mount type=image,source=busybox,destination=/dbg,ro \ - dhi.io/python:3.13 /dbg/bin/sh -``` - -This mounts the BusyBox image at `/dbg`, giving you access to its tools while -keeping your original container image unchanged. Since the hardened Python image -doesn't include standard utilities, you need to use the full path to the mounted -tools: - -```console -$ /dbg/bin/ls / -$ /dbg/bin/ps aux -$ /dbg/bin/cat /etc/os-release -``` - -Type `exit` to leave the container when done. - -## Common issues - -The following are specific issues you may encounter when working with Docker -Hardened Images, along with recommended solutions. - -### Permissions - -DHIs run as a nonroot user by default for enhanced security. This can result in -permission issues when accessing files or directories. Ensure your application -files and runtime directories are owned by the expected UID/GID or have -appropriate permissions. - -To find out which user a DHI runs as, check the repository page for the image on -Docker Hub. See [View image variant -details](./how-to/explore.md#image-variant-details) for more information. - -### Privileged ports - -Nonroot containers cannot bind to ports below 1024 by default. This is enforced -by both the container runtime and the kernel (especially in Kubernetes and -Docker Engine < 20.10). - -Inside the container, configure your application to listen on an unprivileged -port (1025 or higher). For example `docker run -p 80:8080 my-image` maps -port 8080 in the container to port 80 on the host, allowing you to access it -without needing root privileges. - -### No shell - -Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or -tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev` -variant of the image in an earlier build stage and copy the final artifact into -the runtime image. - -To find out which shell, if any, a DHI has, check the repository page for the -image on Docker Hub. See [View image variant -details](./how-to/explore.md#image-variant-details) for more information. - -Also, use Docker Debug when you need shell access to a running container. For -more details, see [General debugging](#general-debugging). - -### Entry point differences - -DHIs may define different entry points compared to Docker Official Images (DOIs) -or other community images. - -To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the -image on Docker Hub. See [View image variant -details](./how-to/explore.md#image-variant-details) for more information. - -### No package manager - -Runtime Docker Hardened Images are stripped down for security and minimal attack -surface. As a result, they don't include a package manager such as `apk` or -`apt`. This means you can't install additional software directly in the runtime -image. - -If your build or application setup requires installing packages (for example, to -compile code, install runtime dependencies, or add diagnostic tools), use a `dev` -variant of the image in a build stage. Then, copy only the necessary artifacts -into the final runtime image. \ No newline at end of file diff --git a/content/manuals/docker-hub/_index.md b/content/manuals/docker-hub/_index.md index e3fccabe715f..59b549bbae3b 100644 --- a/content/manuals/docker-hub/_index.md +++ b/content/manuals/docker-hub/_index.md @@ -27,11 +27,15 @@ grid: - title: Organizations description: Learn about organization administration. icon: building-storefront - link: /admin/ + link: /accounts/organization/ - title: Usage and limits description: Explore usage limits and how to better utilize Docker Hub. icon: chart-bar link: /docker-hub/usage/ +- title: MCP server + description: Use the Docker Hub MCP server to access image metadata and manage repositories with AI agents. + icon: server-stack + link: /docker-hub/mcp-server/ - title: Release notes description: Find out about new features, improvements, and bug fixes. icon: document-plus @@ -56,7 +60,8 @@ Key features of Docker Hub: * Trusted content featuring high-quality, secure images In addition to the graphical interface, you can interact with Docker Hub using -the [Docker Hub API](../../reference/api/hub/latest.md) or experimental [Docker -Hub CLI tool](https://github.com/docker/hub-tool#readme). +the [Docker Hub API](../../reference/api/hub/latest.md), the experimental [Docker +Hub CLI tool](https://github.com/docker/hub-tool#readme), or the [Docker Hub +MCP server](/docker-hub/mcp-server/) for AI agent integrations. {{< grid >}} diff --git a/content/manuals/docker-hub/image-library/_index.md b/content/manuals/docker-hub/image-library/_index.md index ff2847b0e7bb..5a4ad0c1212f 100644 --- a/content/manuals/docker-hub/image-library/_index.md +++ b/content/manuals/docker-hub/image-library/_index.md @@ -15,8 +15,10 @@ In this section, learn about: - [Search](./search.md): Discover how to browse and search Docker Hub's extensive resources. - [Trusted content](./trusted-content.md): Dive into Docker Hardened Images, - Docker Official Images, Verified Publisher content, and Sponsored Open Source - images, all vetted for security and reliability to streamline your workflows. -- [Catalogs](./catalogs.md): Explore specialized collections like the generative AI catalogs. + Docker Official Images, Verified Publisher content, and Docker-Sponsored Open + Source Software images, all vetted for security and reliability to streamline + your workflows. +- [Generative AI](./catalogs.md): Explore Docker Hub's generative AI catalogs + and sandbox kits. - [Mirroring](./mirror.md): Learn how to create a mirror of Docker Hub's - container image library as a pull-through cache. \ No newline at end of file + container image library as a pull-through cache. diff --git a/content/manuals/docker-hub/image-library/catalogs.md b/content/manuals/docker-hub/image-library/catalogs.md index 104543ffe457..1cd2a2bab425 100644 --- a/content/manuals/docker-hub/image-library/catalogs.md +++ b/content/manuals/docker-hub/image-library/catalogs.md @@ -1,16 +1,17 @@ --- -description: Explore specialized Docker Hub collections like the generative AI catalogs. -keywords: Docker Hub, Hub, catalog -title: Docker Hub catalogs -linkTitle: Catalogs +description: Explore Docker Hub's generative AI catalogs and sandbox kits. +keywords: Docker Hub, Hub, generative AI, catalog +title: Generative AI content +linkTitle: Generative AI weight: 60 --- -Docker Hub catalogs are your go-to collections of trusted, ready-to-use -container images and resources, tailored to meet specific development needs. -They make it easier to find high-quality, pre-verified content so you can -quickly build, deploy, and manage your applications with confidence. Catalogs in -Docker Hub: +Docker Hub groups its generative AI content, including curated catalogs and +sandbox kits, under Generative AI. Catalogs are your go-to collections of +trusted, ready-to-use container images and resources, tailored to meet +specific development needs. They make it easier to find high-quality, +pre-verified content so you can quickly build, deploy, and manage your +applications with confidence. Catalogs in Docker Hub: - Simplify content discovery: Organized and curated content makes it easy to discover tools and resources tailored to your specific domain or technology. @@ -19,7 +20,8 @@ Docker Hub: - Accelerate development: Quickly integrate advanced capabilities into your applications without the hassle of extensive research or setup. -The following sections provide an overview of the key catalogs available in Docker Hub. +The following sections provide an overview of the generative AI content +available in Docker Hub. ## MCP Catalog @@ -38,7 +40,7 @@ minimize configuration headaches. For developers working with Claude Desktop or other MCP clients, the catalog provides an easy way to extend functionality with drop-in tools. -To learn more about MCP servers, see [MCP Catalog and Toolkit](../../ai/mcp-catalog-and-toolkit/_index.md). +To learn more about MCP servers, see [MCP Catalog and Toolkit](/manuals/desktop/features/mcp-catalog-and-toolkit/_index.md). ## AI Models Catalog @@ -58,3 +60,16 @@ With the AI Models Catalog and Docker Model Runner, you can: Whether you're building generative AI applications, integrating LLMs into your workflows, or experimenting with machine learning tools, the AI Models Catalog simplifies the model management experience. + +## Sandbox kits + +[Sandbox kits](https://hub.docker.com/search?type=sbx_kit) package what an AI +coding agent needs to run in a [Docker Sandbox](../../ai/sandboxes/_index.md): +its image, tools, credentials, network rules, and startup commands. + +Follow the publisher's instructions for the kit's schema version and role. +A kit that defines a complete environment is the main reference passed to +`sbx run`. Add mixins with `--kit`. Components in one sandbox must use +compatible kit formats. See [Kits](/manuals/ai/sandboxes/customize/_index.md) for +the v3 model and [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md) for +kits used with built-in agents. diff --git a/content/manuals/docker-hub/image-library/search.md b/content/manuals/docker-hub/image-library/search.md index 8a3152918f09..b90414bfeafc 100644 --- a/content/manuals/docker-hub/image-library/search.md +++ b/content/manuals/docker-hub/image-library/search.md @@ -25,6 +25,7 @@ specific needs of developers and organizations. These products include: - Images - Extensions +- Sandbox kits - Helm charts - Compose files - AI models @@ -71,6 +72,23 @@ Desktop's interface. To learn more about extensions, see [Docker Extensions](/manuals/extensions/_index.md). +#### Sandbox kits + +Docker Hub hosts kits for [Docker Sandboxes](/manuals/ai/sandboxes/_index.md), +which run AI coding agents in isolated microVM sandboxes. A kit packages what +an agent needs to run in a sandbox, such as its image, tools, credentials, +network rules, and startup commands. In the v2 format, kits have two kinds: + +- Sandbox: Defines a full agent from scratch, including its image and + entrypoint. +- Mixin: Layers tools, credentials, or configuration onto an existing agent. + +For these kits, see the [v2 reference](/manuals/ai/sandboxes/customize/kits-v2.md). +The experimental v3 format uses workloads and mixins, and adds sets for +publishing a composition as one kit. See the +[Kits overview](/manuals/ai/sandboxes/customize/_index.md) for the v3 model and +version compatibility. + #### Helm charts Helm charts in Docker Hub provide a streamlined way to package, configure, and @@ -241,3 +259,16 @@ extension has been reviewed by Docker for quality and reliability. > > The **Reviewed by Docker** filter is only available for extensions. To make > the filter available, you must select only the **Extensions** filter in **Products**. + +### Sandbox Kit type + +The **Sandbox Kit type** filter lets you narrow sandbox kit results by kind. + +- **Sandbox**: Kits that define a full agent from scratch. +- **Mixin**: Kits that layer onto an existing agent's sandbox. + +> [!NOTE] +> +> The **Sandbox Kit type** filter is only available for sandbox kits. To make +> the filter available, you must select only the **Sandbox kits** filter in +> **Products**. diff --git a/content/manuals/docker-hub/image-library/trusted-content.md b/content/manuals/docker-hub/image-library/trusted-content.md index efa4ac235743..7d09a2d18f09 100644 --- a/content/manuals/docker-hub/image-library/trusted-content.md +++ b/content/manuals/docker-hub/image-library/trusted-content.md @@ -145,7 +145,7 @@ codename for Ubuntu 24.04 is "Noble Numbat". Linux distribution indicators are helpful because many Docker Official Images provide variants built upon multiple underlying distribution versions (for -example, `postgres:bookworm` and `postgres:bullseye`). +example, `postgres:bookworm` and `postgres:trixie`). ### Other tags @@ -159,11 +159,10 @@ variants. ### Troubleshooting failed pulls If you're experiencing failed pulls of Docker Official Images, check whether -the `DOCKER_CONTENT_TRUST` environment variable is set to `1`. Starting in -August 2025, Docker Content Trust signing certificates for Docker Official -Images began expiring. To resolve pull failures, unset the `DOCKER_CONTENT_TRUST` -environment variable. For more details, see the -[DCT retirement blog post](https://www.docker.com/blog/retiring-docker-content-trust/). +the `DOCKER_CONTENT_TRUST` environment variable is set to `1`. Docker Content +Trust is being retired and the service is no longer reliable for pulls. To +resolve pull failures, unset `DOCKER_CONTENT_TRUST`. For more information, see +[Docker Content Trust (DCT)](/manuals/retired.md#docker-content-trust-dct). ## Docker Hardened Images diff --git a/content/manuals/docker-hub/mcp-server.md b/content/manuals/docker-hub/mcp-server.md new file mode 100644 index 000000000000..1ade9e51d983 --- /dev/null +++ b/content/manuals/docker-hub/mcp-server.md @@ -0,0 +1,264 @@ +--- +title: Docker Hub MCP server +linkTitle: Hub MCP server +description: The Docker Hub MCP Server makes Docker Hub image metadata accessible to LLMs for content discovery. +keywords: Docker Hub MCP Server, Hub MCP server, Hub MCP +weight: 60 +aliases: + - /ai/mcp-catalog-and-toolkit/hub-mcp/ +--- + +The Docker Hub MCP Server is a Model Context Protocol (MCP) server that +interfaces with Docker Hub APIs to make rich image metadata accessible to LLMs, +enabling intelligent content discovery and repository management. + +For more information about MCP concepts and how MCP servers work, see the [Docker MCP Catalog and Toolkit](/ai/mcp-catalog-and-toolkit/) overview page. + +## Key features + +- Advanced LLM context: Docker's MCP Server provides LLMs with detailed, structured context for Docker Hub images, enabling smarter, more relevant recommendations for developers, whether they're choosing a base image or automating CI/CD workflows. +- Natural language image discovery: Developers can find the right container image using natural language, no need to remember tags or repository names. Just describe what you need, and Docker Hub will return images that match your intent. +- Simplified repository management: Hub MCP Server enables agents to manage repositories through natural language fetching image details, viewing stats, searching content, and performing key operations quickly and easily. + +## Install Docker Hub MCP server + +1. In Docker Desktop, select **MCP Toolkit** and select the **Profiles** tab, + then select **Create profile** to create a new profile, or select an existing + profile to use. +2. Select the **Catalog** tab, search for **Docker Hub**, and select **Add to** + to add it to your profile. +3. Select the **Profiles** tab, select the profile you added Docker Hub to, and + select the configuration icon on the Docker Hub MCP server. Enter your Docker + Hub username and personal access token (PAT). +4. Under the **Clients** section of the same profile, if you already have a + client connected it connects automatically. Otherwise, select the plus icon + to add a client. + +For more details on setting up profiles and connecting clients, see +[Get started with Docker MCP Toolkit](/ai/mcp-catalog-and-toolkit/get-started/). + +## Use Claude Desktop as a client + +1. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`: + + {{< tabs >}} + {{< tab name="For public repositories only">}} + + ```json + { + "mcpServers": { + "docker-hub": { + "command": "node", + "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"] + } + } + } + ``` + + Where : + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository + + {{< /tab >}} + {{< tab name="For authenticated access">}} + + ```json + { + "mcpServers": { + "docker-hub": { + "command": "node", + "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio", "--username=YOUR_DOCKER_HUB_USERNAME"], + "env": { + "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN" + } + } + } + } + ``` + + Where : + - `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username. + - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository + + + {{< /tab >}} + {{</tabs >}} + +1. Save the configuration file and completely restart Claude Desktop for the changes to take effect. + +## Usage with Visual Studio Code + +1. Add the Docker Hub MCP Server configuration to your User Settings (JSON) + file in Visual Studio Code. You can do this by opening the `Command Palette` and + typing `Preferences: Open User Settings (JSON)`. + + + {{< tabs >}} + {{< tab name="For public repositories only">}} + + ```json + { + "mcpServers": { + "docker-hub": { + "command": "node", + "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"] + } + } + } + ``` + + Where : + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository + + {{< /tab >}} + {{< tab name="For authenticated access">}} + + ```json + { + "mcpServers": { + "docker-hub": { + "command": "node", + "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"], + "env": { + "HUB_USERNAME": "YOUR_DOCKER_HUB_USERNAME", + "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN" + } + } + } + } + ``` + + Where : + - `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username. + - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository + + + {{< /tab >}} + {{</tabs >}} + +1. Open the `Command Palette` and type `MCP: List Servers`. +1. Select `docker-hub` and select `Start Server`. + +## Using other clients + +To integrate the Docker Hub MCP Server into your own development +environment, see the source code and installation instructions on the +[`hub-mcp` GitHub repository](https://github.com/docker/hub-mcp). + + +## Usage examples + +This section provides task-oriented examples for common operations with Docker Hub +tools. + +### Finding images + + +```console +# Search for official images +$ docker ai "Search for official nginx images on Docker Hub" + +# Search for lightweight images to reduce deployment size and improve performance +$ docker ai "Search for minimal Node.js images with small footprint" + +# Get the most recent tag of a base image +$ docker ai "Show me the latest tag details for go" + +# Find a production-ready database with enterprise features and reliability +$ docker ai "Search for production ready database images" + +# Compare Ubuntu versions to choose the right one for my project +$ docker ai "Help me find the right Ubuntu version for my project" +``` + +### Repository management + +```console +# Create a repository +$ docker ai "Create a repository in my namespace" + +# List all repositories in my namespace +$ docker ai "List all repositories in my namespace" + +# Find the largest repository in my namespace +$ docker ai "Which of my repositories takes up the most space?" + +# Find repositories that haven't been updated recently +$ docker ai "Which of my repositories haven't had any pushes in the last 60 days?" + +# Find which repositories are currently active and being used +$ docker ai "Show me my most recently updated repositories" + +# Get details about a repository +$ docker ai "Show me information about my '<repository-name>' repository" +``` + +### Pull/push images + + +```console +# Pull latest PostgreSQL version +$ docker ai "Pull the latest postgres image" + +# Push image to your Docker Hub repository +$ docker ai "Push my <image-name> to my <repository-name> repository" +``` + +### Tag management + +```console +# List all tags for a repository +$ $ docker ai "Show me all tags for my '<repository-name>' repository" + +# Find the most recently pushed tag +$ docker ai "What's the most recent tag pushed to my '<repository-name>' repository?" + +# List tags with architecture filtering +$ docker ai "List tags for in the '<repository-name>' repository that support amd64 architecture" + +# Get detailed information about a specific tag +$ docker ai "Show me details about the '<tag-name>' tag in the '<repository-name>' repository" + +# Check if a specific tag exists +$ docker ai "Check if version 'v1.2.0' exists for my 'my-web-app' repository" +``` + +### Docker Hardened Images + +```console +# List available hardened images +$ docker ai "What is the most secure image I can use to run a node.js application?" + +# Convert Dockerfile to use a hardened image +$ docker ai "Can you help me update my Dockerfile to use a docker hardened image instead of the current one" +``` +> [!NOTE] +> To access Docker Hardened Images, a subscription is required. If you're interested in using Docker Hardened Images, visit [Docker Hardened Images](https://www.docker.com/products/hardened-images/). + + +## Reference + +This section provides a comprehensive listing of the tools you can find +in the Docker Hub MCP Server. + +### Docker Hub MCP server tools + +Tools to interact with your Docker repositories and discover content on Docker Hub. + +| Name | Description | +|------|-------------| +| `check-repository` | Check repository | +| `check-repository-tag` | Check repository tag | +| `check-repository-tags` | Check repository tags | +| `create-repository` | Creates a new repository | +| `docker-hardened-images` | Lists available [Docker Hardened Images](https://www.docker.com/products/hardened-images/) in specified namespace | +| `get-namespaces` | Get organizations/namespaces for a user | +| `get-repository-dockerfile` | Gets Dockerfile for repository | +| `get-repository-info` | Gets repository info | +| `list-repositories-by-namespace` | Lists repositories under namespace | +| `list-repository-tags` | List repository tags | +| `read-repository-tag` | Read repository tag | +| `search` | Search content on Docker Hub | +| `set-repository-dockerfile` | Sets Dockerfile for repository | +| `update-repository-info` | Updates repository info | diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md index de5906786744..179b175a5503 100644 --- a/content/manuals/docker-hub/release-notes.md +++ b/content/manuals/docker-hub/release-notes.md @@ -14,6 +14,26 @@ tags: [Release notes] Here you can learn about the latest changes, new features, bug fixes, and known issues for each Docker Hub release. +## 2026-08-20 + +### New + +- The [Docker Verified Publisher Program](./repos/manage/trusted-content/dvp-program.md) + is now available via self-serve. Apply directly on the [DVP application + page](https://hub.docker.com/publisher-program/apply). + +## 2026-06-29 + +### New + +- Docker Hub integrates with Cloudsmith, letting it handle authentication + for Docker Hub and Docker Hardened Images (DHI) upstreams using a managed + token. This removes the need to supply your own credentials during setup. + See Cloudsmith's announcement, [Set up Docker Hub and DHI upstreams with + Cloudsmith-managed + authentication](https://cloudsmith.com/changelog/set-up-docker-hub-and-dhi-upstreams-with-cloudsmith-managed-authentication), + for details. + ## 2026-05-20 ### Infrastructure updates @@ -26,7 +46,7 @@ known issues for each Docker Hub release. Most users are unaffected. You may need to take action if your environment uses an egress firewall with a domain allowlist, a TLS inspection proxy, or a managed CA trust store. See the [Docker Desktop - allowlist](/manuals/desktop/setup/allow-list.md) for updated domain + allowlist](/manuals/desktop/enterprise/allow-list.md) for updated domain requirements. If you see TLS errors, ensure your trust store includes the [Amazon Trust Services Root CAs](https://www.amazontrust.com/repository/). If you're a paid subscriber, you can [contact Docker @@ -90,7 +110,7 @@ known issues for each Docker Hub release. ### New -- Organizations can assign the [editor role](/manuals/enterprise/security/roles-and-permissions/_index.md) to members to grant additional permissions without full administrative access. +- Organizations can assign the [editor role](/manuals/security/roles-and-permissions/_index.md) to members to grant additional permissions without full administrative access. ## 2023-05-09 @@ -120,13 +140,13 @@ known issues for each Docker Hub release. ### Bug fixes and enhancements -- In Docker Hub, you can now download a [registry.json](/manuals/enterprise/security/enforce-sign-in/_index.md) file or copy the commands to create a registry.json file to enforce sign-in for your organization. +- In Docker Hub, you can now download a [registry.json](/manuals/desktop/enterprise/enforce-sign-in/_index.md) file or copy the commands to create a registry.json file to enforce sign-in for your organization. ## 2022-09-19 ### Bug fixes and enhancements -- You can now [export a CSV file of members](../admin/organization/manage/members.md#export-members-csv-file) from organizations that you own. +- You can now [export a CSV file of members](../accounts/organization/manage/members.md#export-members-csv-file) from organizations that you own. ## 2022-07-22 @@ -150,7 +170,7 @@ known issues for each Docker Hub release. ### New -- [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) is now available for all Docker Business subscriptions. When enabled, your users can access specific registries in Docker Hub. +- [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) is now available for all Docker Business subscriptions. When enabled, your users can access specific registries in Docker Hub. ## 2022-05-03 @@ -162,7 +182,7 @@ known issues for each Docker Hub release. ### New -- You can now purchase or upgrade to a Docker Business subscription using a credit card. To learn more, see [Upgrade your subscription](../subscription//change.md). +- You can now purchase or upgrade to a Docker Business subscription using a credit card. To learn more, see [Upgrade your subscription](../subscription-billing/plans/docker.md). ## 2021-08-31 @@ -179,7 +199,7 @@ The updated [Docker Subscription Service Agreement](https://www.docker.com/legal - The existing Docker Free subscription has been renamed **Docker Personal**. - **No changes** to Docker Engine or any other upstream **open source** Docker or Moby project. - To understand how these changes affect you, read the [FAQs](https://www.docker.com/pricing/faq). For more information, see [Docker subscription overview](../subscription/_index.md). + To understand how these changes affect you, read the [FAQs](https://www.docker.com/pricing/faq). For more information, see [Docker subscription overview](../subscription-billing/_index.md). ## 2021-05-05 @@ -187,7 +207,7 @@ The updated [Docker Subscription Service Agreement](https://www.docker.com/legal When managing the content of your repositories, you can now filter the results based on the currentness of the tags and more easily identify your untagged images. -For Docker Hub API documentation, see [Docker Hub API Reference](/reference/api/hub/latest.md#operation/GetNamespacesRepositoriesImages). +For Docker Hub API documentation, see [Docker Hub API Reference](/reference/api/hub/latest/). ## 2021-04-13 @@ -203,7 +223,7 @@ You can now specify any email address to receive billing-related emails for your To change the email address receiving billing-related emails, log into Docker Hub and navigate to the **Billing** tab of your organization. Select **Payment Methods** > **Billing Information**. Enter the new email address that you'd like to use in the **Email** field. Click **Update** for the changes to take effect. -For details on how to update your billing information, see [Update billing information](../billing/_index.md). +For details on how to update your billing information, see [Update billing information](../subscription-billing/_index.md). ## 2021-03-22 @@ -219,7 +239,7 @@ Docker introduces the Advanced Image Management dashboard that enables you to vi Docker introduces Audit logs, a new feature that allows team owners to view a list of activities that occur at organization and repository levels. This feature begins tracking the activities from the release date, that is, **from 25 January 2021**. -For more information about this feature and for instructions on how to use it, see [Activity logs](../admin/activity-logs.md). +For more information about this feature and for instructions on how to use it, see [Activity logs](../accounts/organization/activity-logs.md). ## 2020-11-10 @@ -237,7 +257,7 @@ Docker introduces Hub Vulnerability Scanning which enables you to automatically ### New features -- Docker has announced a new, per-seat pricing model to accelerate developer workflows for cloud-native development. The previous private repository/concurrent autobuild-based plans have been replaced with new **Pro** and **Team** plans that include unlimited private repositories. For more information, see [Docker subscription](../subscription/_index.md). +- Docker has announced a new, per-seat pricing model to accelerate developer workflows for cloud-native development. The previous private repository/concurrent autobuild-based plans have been replaced with new **Pro** and **Team** plans that include unlimited private repositories. For more information, see [Docker subscription](../subscription-billing/_index.md). - Docker has enabled download rate limits for downloads and pull requests on Docker Hub. This caps the number of objects that users can download within a specified timeframe. For more information, see [Usage and limits](/manuals/docker-hub/usage/_index.md). @@ -298,7 +318,7 @@ Docker introduces Hub Vulnerability Scanning which enables you to automatically ### New features -- You can now [create personal access tokens](/security/access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. +- You can now [create personal access tokens](/security/access-tokens/personal-access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. ### Known Issues @@ -308,7 +328,7 @@ Docker introduces Hub Vulnerability Scanning which enables you to automatically ### Enhancements -- The [billing page](../subscription/change.md) for personal accounts has been updated. You can access the page at its new URL: [https://hub.docker.com/billing/plan](https://hub.docker.com/billing/plan). +- The [billing page](../subscription-billing/plans/docker.md) for personal accounts has been updated. You can access the page at its new URL: [https://hub.docker.com/billing/plan](https://hub.docker.com/billing/plan). ### Known Issues diff --git a/content/manuals/docker-hub/repos/create.md b/content/manuals/docker-hub/repos/create.md index 9e20df6710c0..b2674644b9fc 100644 --- a/content/manuals/docker-hub/repos/create.md +++ b/content/manuals/docker-hub/repos/create.md @@ -39,7 +39,7 @@ weight: 20 is only accessible to you and collaborators. In addition, if you selected an organization's namespace, then the repository is accessible to those with applicable roles or permissions. For more details, see [Roles and - permissions](/manuals/enterprise/security/roles-and-permissions.md). + permissions](/manuals/security/roles-and-permissions.md). > [!NOTE] > diff --git a/content/manuals/docker-hub/repos/manage/access.md b/content/manuals/docker-hub/repos/manage/access.md index c88d3492cfb3..37d9c600b92e 100644 --- a/content/manuals/docker-hub/repos/manage/access.md +++ b/content/manuals/docker-hub/repos/manage/access.md @@ -94,7 +94,7 @@ repository from that repository's **Settings** page. Organizations can use roles for individuals, giving them different permissions in the organization. For more details, see [Roles and -permissions](/manuals/enterprise/security/roles-and-permissions.md). +permissions](/manuals/security/roles-and-permissions.md). ## Organization teams @@ -105,7 +105,7 @@ access. You must create a team before you are able to configure repository permissions. For more details, see [Create and manage a -team](/manuals/admin/organization/manage/manage-a-team.md). +team](/manuals/accounts/organization/manage/manage-a-team.md). To configure team repository permissions: @@ -131,45 +131,156 @@ To configure team repository permissions: Organizations can use OATs. OATs let you assign fine-grained repository access permissions to tokens. For more details, see [Organization access -tokens](/manuals/enterprise/security/access-tokens.md). +tokens](/manuals/security/access-tokens/organization-access-tokens.md). ## Gated distribution {{< summary-bar feature_name="Gated distribution" >}} -Gated distribution allows publishers to securely share private container images with external customers or partners, without giving them full organization access or visibility into your teams, collaborators, or other repositories. - -This feature is ideal for commercial software publishers who want to control who can pull specific images while preserving a clean separation between internal users and external consumers. - -If you are interested in Gated Distribution contact the <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_hub_gated_distribution" class="link" rel="noopener">Docker Sales Team</a> for more information. - -### Key features - -- **Private repository distribution**: Content is stored in private repositories and only accessible to explicitly invited users. - -- **External access without organization membership**: External users don't need to be added to your internal organization to pull images. - -- **Pull-only permissions**: External users receive pull-only access and cannot push or modify repository content. - -- **Invite-only access**: Access is granted through authenticated email invites, managed via API. +Gated distribution allows publishers to securely share private container images +with external customers or partners, without giving them full organization +access or visibility into your teams, collaborators, or other repositories. +Content stays in private repositories, and external users can pull from them +without being added to your internal organization. + +This feature is ideal for commercial software publishers who want to control who +can pull specific images while preserving a clean separation between internal +users and external consumers. + +If you are interested in Gated Distribution contact the <a +href="https://www.docker.com/pricing/contact-sales/" +id="dkr_docs_cs_hub_gated_distribution" class="link" rel="noopener">Docker Sales +Team</a> for more information. + +### Distributor members + +When you invite users to an organization entitled with gated distribution, you +assign them a role that determines their level of access. For gated +distribution, external users are invited as **distributor members** within a +specific team that you create. This role grants pull-only access to the +repositories assigned to that team, and nothing else in your organization. See +[Roles and permissions](/manuals/security/roles-and-permissions.md) +for details about the access permissions for other roles. + +Distributor members can't see other members in their team or organization, and +they can't see any repositories other than the ones their team has been granted +access to. This isolation is what makes the role suitable for distributing gated +images to external users, partners, or customers without exposing internal +collaborators, teams, or repositories. + +Because distributor members consume licenses allocated for that role, consider +provisioning a separate organization for gated distribution rather than adding +distributor members to your main organization. This keeps regular members from +inadvertently consuming the licenses set aside for external distribution. ### Invite distributor members via API -> [!NOTE] -> When you invite members, you assign them a role. See [Roles and permissions](/manuals/enterprise/security/roles-and-permissions.md) for details about the access permissions for each role. - -Distributor members (used for gated distribution) can only be invited using the Docker Hub API. UI-based invitations are not currently supported for this role. To invite distributor members, use the Bulk create invites API endpoint. +Distributor members can only be invited using the Docker Hub API. UI-based +invitations are not supported for this role. To invite distributor members: -1. Use the [Authentication API](https://docs.docker.com/reference/api/hub/latest/#tag/authentication-api/operation/AuthCreateAccessToken) to generate a bearer token for your Docker Hub account. - -2. Create a team in the Hub UI or use the [Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/groups/paths/~1v2~1orgs~1%7Borg_name%7D~1groups/post). - -3. Grant repository access to the team: - - In the Hub UI: Navigate to your repository settings and add the team with "Read-only" permissions - - Using the [Repository Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/repositories/paths/~1v2~1repositories~1%7Bnamespace%7D~1%7Brepository%7D~1groups/post): Assign the team to your repositories with "read-only" access level - -4. Use the [Bulk create invites endpoint](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) to send email invites with the distributor member role. In the request body, set the "role" field to "distributor_member". - -5. The invited user will receive an email with a link to accept the invite. After signing in with their Docker ID, they'll be granted pull-only access to the specified private repository as a distributor member. +1. Use the [authentication + API](/reference/api/hub/latest/operations/AuthCreateAccessToken/) + to generate a bearer token for your Docker Hub account. This token authorizes + the API requests you use to send invites. Replace `myusername` and + `dckr_pat_...` with your Docker ID and a [personal access + token](/manuals/security/access-tokens.md): + + ```console + $ TOKEN=$(curl -s -X POST "https://hub.docker.com/v2/auth/token" \ + -H "Content-Type: application/json" \ + -d '{"identifier": "myusername", "secret": "dckr_pat_..."}' \ + | jq -r .access_token) + ``` + +2. Create a team to group the distributor members and assign them a shared set + of repository permissions. + + {{< tabs >}} + {{< tab name="Hub" >}} + + 1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. + 2. Select **Teams**. + 3. Select **Create team**. + 4. Provide the team's information, then select **Create**. + + For more details, see [Create and manage a + team](/manuals/accounts/organization/manage/manage-a-team.md). + + {{< /tab >}} + {{< tab name="API" >}} + + Use the [teams + API](/reference/api/hub/latest/operations/postV2OrgsByOrgNameGroups/): + + ```console + $ curl -s -X POST "https://hub.docker.com/v2/orgs/example-org/groups" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name": "customer-team", "description": "External distributor members"}' + ``` + + The response includes the new team's `id`. Save it for the next step, for + example `GROUP_ID=12345`. + + {{< /tab >}} + {{< /tabs >}} + +3. Grant the team read-only access to the repositories you want distributor + members to access. + + {{< tabs >}} + {{< tab name="Hub" >}} + + 1. Sign in to [Docker Hub](https://hub.docker.com). + 2. Select **My Hub** > **Repositories**. + 3. Select the repository. + 4. Select the **Permissions** tab. + 5. Specify the **Team**, select **Read-only** as the **Permission**, and + then select **Add**. + + {{< /tab >}} + {{< tab name="API" >}} + + Use the [repository teams + API](/reference/api/hub/latest/operations/CreateRepositoryGroup/), + passing the team's `id` from the previous step as `group_id`: + + ```console + $ curl -s -X POST "https://hub.docker.com/v2/repositories/example-org/example-repo/groups" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"group_id\": $GROUP_ID, \"permission\": \"read\"}" + ``` + + {{< /tab >}} + {{< /tabs >}} + +4. Use the [bulk create invites + endpoint](/reference/api/hub/latest/operations/postV2InvitesBulk/) + to send email invites. In the request body, set `role` to + `distributor_member`, specify the `team`, and list the invitees' email + addresses: + + ```console + $ curl -s -X POST "https://hub.docker.com/v2/invites/bulk" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "org": "example-org", + "team": "customer-team", + "role": "distributor_member", + "invitees": ["user@example.com"] + }' + ``` + + This sends email invitations to the specified users and automatically assigns + them to the team. + +5. The invited user receives an email invitation from Docker Hub. When they + select the link in the email, they sign in with their Docker ID (or create + one if needed) to accept the invite. Once accepted, they're added to the + organization as a distributor member with pull-only access to the + repositories assigned to their team. diff --git a/content/manuals/docker-hub/repos/manage/builds/_index.md b/content/manuals/docker-hub/repos/manage/builds/_index.md index db9dc1836431..eb5af4c82790 100644 --- a/content/manuals/docker-hub/repos/manage/builds/_index.md +++ b/content/manuals/docker-hub/repos/manage/builds/_index.md @@ -17,12 +17,11 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. Docker Hub can automatically build images from source code in an external repository and automatically push the built image to your Docker repositories. -![An automated build dashboard](images/index-dashboard.png) - When you set up automated builds, also called autobuilds, you create a list of branches and tags that you want to build into Docker images. When you push code to a source-code branch, for example in GitHub, for one of those listed image diff --git a/content/manuals/docker-hub/repos/manage/builds/advanced.md b/content/manuals/docker-hub/repos/manage/builds/advanced.md index 5428e897af53..f72a9d02a72a 100644 --- a/content/manuals/docker-hub/repos/manage/builds/advanced.md +++ b/content/manuals/docker-hub/repos/manage/builds/advanced.md @@ -12,6 +12,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > @@ -36,7 +37,7 @@ processes and don't affect your service's run environment. * `SOURCE_COMMIT`: the SHA1 hash of the commit being tested. * `COMMIT_MSG`: the message from the commit being tested and built. * `DOCKER_REPO`: the name of the Docker repository being built. -* `DOCKERFILE_PATH`: the dockerfile currently being built. +* `DOCKERFILE_PATH`: the Dockerfile currently being built. * `DOCKER_TAG`: the Docker repository tag being built. * `IMAGE_NAME`: the name and tag of the Docker repository being built. (This variable is a combination of `DOCKER_REPO`:`DOCKER_TAG`.) diff --git a/content/manuals/docker-hub/repos/manage/builds/automated-testing.md b/content/manuals/docker-hub/repos/manage/builds/automated-testing.md index 4dabaee04263..b97b55df6536 100644 --- a/content/manuals/docker-hub/repos/manage/builds/automated-testing.md +++ b/content/manuals/docker-hub/repos/manage/builds/automated-testing.md @@ -10,6 +10,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > diff --git a/content/manuals/docker-hub/repos/manage/builds/images/build-cancelicon.png b/content/manuals/docker-hub/repos/manage/builds/images/build-cancelicon.png deleted file mode 100644 index 33fbc9e3cb2b..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/builds/images/build-cancelicon.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/builds/images/index-active.png b/content/manuals/docker-hub/repos/manage/builds/images/index-active.png deleted file mode 100644 index cb7ed20dc255..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/builds/images/index-active.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/builds/images/index-dashboard.png b/content/manuals/docker-hub/repos/manage/builds/images/index-dashboard.png deleted file mode 100644 index a97dd5de6d31..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/builds/images/index-dashboard.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/builds/images/index-report.png b/content/manuals/docker-hub/repos/manage/builds/images/index-report.png deleted file mode 100644 index 6f992450544b..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/builds/images/index-report.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/builds/images/retry-build.png b/content/manuals/docker-hub/repos/manage/builds/images/retry-build.png deleted file mode 100644 index 11fa6c97fc44..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/builds/images/retry-build.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/builds/link-source.md b/content/manuals/docker-hub/repos/manage/builds/link-source.md index 2cabd76c0a34..53bea727e357 100644 --- a/content/manuals/docker-hub/repos/manage/builds/link-source.md +++ b/content/manuals/docker-hub/repos/manage/builds/link-source.md @@ -14,6 +14,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > diff --git a/content/manuals/docker-hub/repos/manage/builds/manage-builds.md b/content/manuals/docker-hub/repos/manage/builds/manage-builds.md index 5bf33052290b..9137faf84301 100644 --- a/content/manuals/docker-hub/repos/manage/builds/manage-builds.md +++ b/content/manuals/docker-hub/repos/manage/builds/manage-builds.md @@ -9,6 +9,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > @@ -22,8 +23,6 @@ report link on the **General** tab and on the **Builds** tab. You can also selec **Cancel** on the **Build report** page, or from the **Timeline** tab's logs display for the build. -![List of builds showing the cancel icon](images/build-cancelicon.png) - ## Check your active builds A summary of a repository's builds appears both on the repository **General** @@ -32,8 +31,6 @@ bar chart of the build queue times and durations. Both views display the pending, in progress, successful, and failed builds for any tag of the repository. -![Active builds](images/index-active.png) - From either location, you can select a build job to view its build report. The build report shows information about the build job. This includes the source repository and branch, or tag, the build logs, the build duration, creation time and location, and the user account the build occurred in. @@ -42,8 +39,6 @@ repository and branch, or tag, the build logs, the build duration, creation time > > You can now view the progress of your builds every 30 seconds when you refresh the **Builds** page. With the in-progress build logs, you can debug your builds before they're finished. -![Build report](./images/index-report.png) - ## Disable an automated build Automated builds are enabled per branch or tag, and can be disabled and diff --git a/content/manuals/docker-hub/repos/manage/builds/migrate.md b/content/manuals/docker-hub/repos/manage/builds/migrate.md index c811015fc5b9..4a92547fc9a1 100644 --- a/content/manuals/docker-hub/repos/manage/builds/migrate.md +++ b/content/manuals/docker-hub/repos/manage/builds/migrate.md @@ -3,7 +3,7 @@ description: Migrate from Autobuilds to CI/CD workflows keywords: automated builds, autobuilds, migration, github actions, bitbucket pipelines title: Migrate from Autobuilds linkTitle: Migrate -weight: 80 +weight: 1 --- > [!WARNING] @@ -21,11 +21,11 @@ To grant your CI workflows the ability to pull and push images to and from Docker Hub, you first need to create access tokens: - For a personal repository: Create a [Personal - Access Token](../../../../security/access-tokens.md) with **Read & Write** + Access Token](../../../../security/access-tokens/personal-access-tokens.md) with **Read & Write** permissions. - For an organization repository: Create an [Organization Access - Token](../../../../enterprise/security/access-tokens.md) with the following + Token](../../../../security/access-tokens/organization-access-tokens.md) with the following permissions: - **Read public repositories** - **Image Pull** on any private repositories that the build needs to pull from diff --git a/content/manuals/docker-hub/repos/manage/builds/setup.md b/content/manuals/docker-hub/repos/manage/builds/setup.md index 667480e2a643..87f4d29a35a0 100644 --- a/content/manuals/docker-hub/repos/manage/builds/setup.md +++ b/content/manuals/docker-hub/repos/manage/builds/setup.md @@ -13,6 +13,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > diff --git a/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md b/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md index 45774fe5d879..16e4ce2f7981 100644 --- a/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md +++ b/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md @@ -11,6 +11,7 @@ aliases: > [!WARNING] > Docker Hub Automated Builds is a deprecated feature. > It will be fully retired on April 1, 2027. +> See the [migration guide](migrate.md) to move to a supported CI/CD workflow. > [!NOTE] > @@ -22,8 +23,6 @@ aliases: If a build fails, a **Retry** icon appears next to the build report line on the **General** and **Builds** tabs. The **Build report** page and **Timeline logs** also display a **Retry** button. -![Timeline view showing the retry build button](images/retry-build.png) - > [!NOTE] > > If you are viewing the build details for a repository that belongs to an @@ -60,7 +59,7 @@ system access to the repositories. > also do this for an individual account to limit Docker Hub's access to your > source repositories. -1. Generate a SSH keypair that you use for builds only, and add the public key to your source code provider account. +1. Generate an SSH keypair that you use for builds only, and add the public key to your source code provider account. This step is optional, but allows you to revoke the build-only keypair without removing other access. diff --git a/content/manuals/docker-hub/repos/manage/export.md b/content/manuals/docker-hub/repos/manage/export.md index 0dea2fe45dea..08b02c8613da 100644 --- a/content/manuals/docker-hub/repos/manage/export.md +++ b/content/manuals/docker-hub/repos/manage/export.md @@ -25,7 +25,7 @@ Before you begin, ensure you have: ## Create a personal access token -[Create a personal access token](/security/access-tokens/) from +[Create a personal access token](/security/access-tokens/personal-access-tokens/) from a user account that has access to the organization's repositories. When creating the token, select at minimum **Read-only** access permissions to list repositories. diff --git a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-artifact.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-artifact.png deleted file mode 100644 index 36848a177c06..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-artifact.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm-tagview.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm-tagview.png deleted file mode 100644 index 1b3d23e528f1..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm-tagview.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm.png deleted file mode 100644 index 6372f92d9f2d..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-volume.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-volume.png deleted file mode 100644 index 355d9fe1a99e..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/hub-images/images/oci-volume.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/hub-images/manage.md b/content/manuals/docker-hub/repos/manage/hub-images/manage.md index b0744339dcf3..4fd22e9bd538 100644 --- a/content/manuals/docker-hub/repos/manage/hub-images/manage.md +++ b/content/manuals/docker-hub/repos/manage/hub-images/manage.md @@ -28,7 +28,11 @@ The following objects are shown in the diagram. Use the following steps to delete one or more items via the graphical user interface. To delete in bulk, see the [deletion API -endpoint](/reference/api/registry/latest/#tag/delete). +endpoint](/reference/api/registry/latest/#tag-delete). + +> [!NOTE] +> Images associated with [immutable tags](./immutable-tags.md) can't be +> deleted. Only items associated with mutable tags can be deleted. 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **My Hub** > **Repositories**. @@ -60,4 +64,4 @@ endpoint](/reference/api/registry/latest/#tag/delete). > Deletion operations may take some time to complete. Timeout errors may > occur during the deletion process. The system automatically retries the > deletion in the background, and the items will be removed without requiring - > any action from you. \ No newline at end of file + > any action from you. diff --git a/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md b/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md index d8cd90ef6859..c3a932482f8c 100644 --- a/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md +++ b/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md @@ -100,14 +100,10 @@ Steps: 5. Go to the repository page on Docker Hub. The **Tags** section of the page shows the Helm chart tag. - ![List of repository tags](./images/oci-helm.png) - 6. Select the tag name to go to the page for that tag. The page lists a few useful commands for working with Helm charts. - ![Tag page of a Helm chart artifact](./images/oci-helm-tagview.png) - ### Push a volume The following procedure shows how to push container volume as an OCI artifact to @@ -146,8 +142,6 @@ Steps: 4. Go to the repository page on Docker Hub. The **Tags** section on that page shows the volume tag. - ![Repository page showing a volume in the tag list](./images/oci-volume.png) - ### Push a generic artifact file The following procedure shows how to push a generic OCI artifact to Docker Hub. @@ -178,5 +172,3 @@ Steps: 4. Go to the repository page on Docker Hub. The **Tags** section on that page shows the artifact tag. - - ![Repository page showing an artifact in the tag list](./images/oci-artifact.png) diff --git a/content/manuals/docker-hub/repos/manage/hub-images/tags.md b/content/manuals/docker-hub/repos/manage/hub-images/tags.md index 6768ce9d782b..4108e7e297b4 100644 --- a/content/manuals/docker-hub/repos/manage/hub-images/tags.md +++ b/content/manuals/docker-hub/repos/manage/hub-images/tags.md @@ -50,6 +50,10 @@ You can select a tag's digest to see more details. Only the repository owner or other team members with granted permissions can delete tags. +> [!NOTE] +> If your repository has [immutable tags](./immutable-tags.md) enabled, those +> tags can't be deleted. Only mutable tags can be deleted. + 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **My Hub** > **Repositories**. diff --git a/content/manuals/docker-hub/repos/manage/images/vuln-scan-details.png b/content/manuals/docker-hub/repos/manage/images/vuln-scan-details.png deleted file mode 100644 index 36581068e195..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/images/vuln-scan-details.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/images/vuln-scan-report.png b/content/manuals/docker-hub/repos/manage/images/vuln-scan-report.png deleted file mode 100644 index 31c73be4779f..000000000000 Binary files a/content/manuals/docker-hub/repos/manage/images/vuln-scan-report.png and /dev/null differ diff --git a/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md index c7ff5737a305..b7e2e89eab83 100644 --- a/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md @@ -18,8 +18,9 @@ toc_max: 2 --- [The Docker Verified Publisher -Program](https://hub.docker.com/search?badges=verified_publisher) provides -high-quality images from commercial publishers verified by Docker. +Program](https://hub.docker.com/search?badges=verified_publisher) is a paid +subscription program that provides high-quality images from commercial +publishers verified by Docker. These images help development teams build secure software supply chains, minimizing exposure to malicious content early in the process to save time and @@ -28,8 +29,8 @@ money later. ## Who's eligible to become a verified publisher? Any independent software vendor who distributes software on Docker Hub can join -the Verified Publisher Program. Find out more by heading to the [Docker Verified -Publisher Program](https://www.docker.com/partners/programs) page. +the Verified Publisher Program. To apply, see the [Verified Publisher Program +application](https://hub.docker.com/publisher-program/apply). > [!NOTE] > @@ -55,8 +56,6 @@ on participation tier: with Docker Scout - [Priority search ranking](#priority-search-ranking): Enhanced discoverability in Docker Hub search results -- [Co-marketing opportunities](#co-marketing-opportunities): Joint promotional - activities with Docker ### Enterprise-grade infrastructure @@ -116,13 +115,6 @@ results, making it easier for developers to discover your content. This improved discoverability helps drive adoption of your images within the developer community. -### Co-marketing opportunities - -Docker collaborates with verified publishers on joint marketing initiatives, -including blog posts, case studies, webinars, and conference presentations. -These opportunities help amplify your brand visibility within the Docker -ecosystem. - ### Insights and analytics The insights and analytics service provides usage metrics for how @@ -134,6 +126,13 @@ There is both a [web interface](./insights-analytics.md) and an The usage metrics show the number of image pulls by tag or by digest, geolocation, cloud provider, client, and more. +## Support + +The program doesn't change support for your organization. Support follows your +organization's Docker subscription, or your program tier if you don't have a paid +Docker subscription. For details, see [support response +times](/manuals/support/_index.md#support-response-times). + ## Manage repository logo After joining the Docker Verified Publisher Program, you can set a custom logo diff --git a/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md index 88c819c375ad..2cb03e662649 100644 --- a/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md @@ -6,6 +6,7 @@ aliases: - /docker-hub/publish/insights-analytics/ - /docker-hub/insights-analytics/ - /trusted-content/insights-analytics/ +toc_max: 3 --- Insights and analytics provides usage analytics for [Docker Verified Publisher @@ -15,52 +16,47 @@ images on Docker Hub. This includes self-serve access to image and extension usage metrics for a desired time span. You can see the number of image pulls by tag or by digest, geolocation, cloud provider, client, and more. -> [!NOTE] -> -> The Legacy DVP program applies to existing customers who have not yet renewed -> to DVP Core. The DVP Legacy program is deprecated and will be retired. Contact -> your Docker sales representative or -> [Docker](https://www.docker.com/partners/programs/) for more information. +- [DVP program](#dvp-program): Usage analytics for Docker Verified Publisher + organizations, including tiered reports and report configuration. +- [DSOS & Legacy DVP programs](#dsos--legacy-dvp-programs): Usage analytics for + Docker-Sponsored Open Source publishers, and for existing customers on the + deprecated Legacy DVP program. + +The Legacy DVP program applies to existing customers who have not yet renewed +to DVP Core. The DVP Legacy program is deprecated and will be retired. Contact +your Docker sales representative or +[Docker](https://www.docker.com/partners/programs/) for more information. -{{< tabs >}} -{{< tab name="DVP program" >}} +## DVP program All members of an organization have access to the analytics data. Members can access analytics data in the [Docker Hub](https://hub.docker.com/) web interface. -## Available reports +### Available reports -The following reports may be available for download as CSV files: +The following reports are available for download as CSV files, based on your +organization's DVP subscription tier: -- [Summary](#summary-report) -- [Trends](#trends-report) -- [Technographic](#technographic-report) -- [Technographic companies](#technographic-companies-report) -- [Tracked companies](#tracked-companies-report) +- Starter tier + - [Summary](#summary-report) +- Growth tier + - [Summary](#summary-report) + - [Trends](#trends-report) + - [Domain-level reports](#domain-level-reports) + - [Benchmark](#benchmark-report) -The reports available for download may vary based on your organization's -subscription. Contact your Docker sales representative or -[Docker](https://www.docker.com/partners/programs/) for more information. +The Domain-level reports and Benchmark report each provide a different slice +of reporting on consuming domains: -## Configure DVP analytics settings +- Domain-level reports show how those domains use your own images, and which + other images they use alongside yours. +- Benchmark shows how those domains use the specific images you've configured to + benchmark against, such as a single repository. -Organization owners and editors can configure DVP analytics settings through the -Admin Console to control tracked companies and benchmark report allocations for -your verified publisher namespaces. - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Admin Console** > **Verified Publisher**. -3. Configure the settings: - - **Tracked companies**: Set the number of companies to track for reporting - purposes. This setting determines how many company domains appear in your - [Tracked companies report](#tracked-companies-report). You can only set - this number up to the maximum included in your DVP subscription. - - **Benchmark report allocations**: If your organization has benchmark - reports enabled, enter the number of companies to include in the benchmark - report for each namespace listed. -4. Select **Save** to apply your changes. +After your organization is provisioned for DVP analytics, it takes up to one +week for the first reports to become available. -### Summary report +#### Summary report The summary report provides high-level usage metrics aggregated across all your Docker Hub content, organized by namespace and repository. This report gives you @@ -102,7 +98,7 @@ The summary report is a CSV file that contains the following data points: | `VERSION_CHECKS` | The number of version checks performed (HEAD requests to check for updates without downloading the full image). | | `EVENT_COUNT` | The total number of events, calculated as the sum of data downloads and version checks. | -### Trends report +#### Trends report The trends report helps you understand how adoption of your container images evolves over time. It provides visibility into pull activity across repositories @@ -143,67 +139,23 @@ The trends report is a CSV file that contains the following data points: | `UNIQUE_AUTHENTICATED_USERS` | The number of unique authenticated users who performed pulls. | | `UNIQUE_UNAUTHENTICATED_USERS` | The number of unique unauthenticated users who performed pulls. | -### Technographic report - -The technographic report provides insights into how your Docker Verified -Publisher (DVP) images are used alongside other container images in real-world -technology stacks. This report helps you understand the technical ecosystem -where your images operate and identify co-usage patterns with other images. - -You can use this report to answer questions like: - -- Which other images are commonly used together with your images? -- What percentage of your user base also uses specific complementary - technologies? -- How many companies in your ecosystem use both your image and other popular - images? -- What technology stacks are most popular among your users? - -To access the report: - -1. Sign in to [Docker Hub](https://hub.docker.com/). -2. Select **My Hub** in the top navigation. -3. Select your organization in the left navigation. -4. Select **Analytics** > **Technographic** in the left navigation. -5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity. -6. Select **Download report** for the desired week or month. - -The technographic report is a CSV file that contains the following data points: - -| Field | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------- | -| `DATE_GRANULARITY` | Weekly or monthly granularity of the data. | -| `DATE_REFERENCE` | The start date of the week or month in YYYY-MM-DD format. | -| `PUBLISHER_ID` | The unique identifier for the publisher organization. | -| `PUBLISHER_NAME` | The name of the organization that owns the DVP repository. | -| `DVPP_IMAGE` | Your Docker Verified Publisher image repository name. | -| `PAIRED_IMAGE` | The other image repository that is commonly used together with your DVP image. | -| `USERS` | The number of unique users who pulled both your DVP image and the paired image within the time period. | -| `TOTAL_PULLERS` | The total number of unique users who pulled your DVP image during the time period. | -| `PCT_USERS` | The percentage of your image's users who also use the paired image (users/total_pullers). | -| `DOMAINS` | The number of unique company domains that pulled both your DVP image and the paired image. | -| `TOTAL_DOMAINS` | The total number of unique company domains that pulled your DVP image. | -| `PCT_DOMAINS` | The percentage of company domains using your image that also use the paired image (domains/total_domains). | - -> [!NOTE] -> -> To protect user privacy and ensure statistical significance, the technographic -> report only includes image pairings that have at least 10 unique users. -> Personal, disposable, and university email domains are excluded from the -> company domain analysis. - -### Technographic companies report +#### Domain-level reports -The technographic companies report provides a detailed view of which specific -companies (identified by their domains) are using your Docker Verified Publisher -(DVP) images together with other container images. This report gives you -visibility into the actual organizations adopting your technology stack -combinations, enabling targeted business development and partnership -opportunities. +Domain-level reports provide detailed insights into how specific consuming +domains use your Docker Verified Publisher (DVP) images, both on their own and +alongside other container images. These reports help you understand usage +patterns, deployment environments, adoption trends, and technology stack +combinations across your customer base and potential prospects. -You can use this report to answer questions like: +You can use these reports to answer questions like: -- Which companies are using my image alongside specific complementary +- How are specific consuming domains using my images across different + environments? +- What deployment patterns do I see across local development, CI/CD, and + production? +- Which consuming domains are heavy users of my images? +- How does usage vary by geography and cloud providers for consuming domains? +- Which consuming domains are using my image alongside specific complementary technologies? - What technology stacks are adopted by enterprise customers in my target market? @@ -211,6 +163,14 @@ You can use this report to answer questions like: - How can I identify potential customers who are already using related technologies? +##### Technographic report + +The technographic report provides a detailed view of which specific consuming +domains are using your DVP images together with other container images. This +report gives you visibility into the actual organizations adopting your +technology stack combinations, enabling targeted business development and +partnership opportunities. + To access the report: 1. Sign in to [Docker Hub](https://hub.docker.com/). @@ -220,20 +180,21 @@ To access the report: 5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity. 6. Select **Download report** for the desired week or month. -The technographic companies report is a CSV file that contains the following +The technographic report is a CSV file that contains the following data points: -| Field | Description | -| ------------------ | ---------------------------------------------------------------------------------------------- | -| `DATE_GRANULARITY` | Weekly or monthly granularity of the data. | -| `DATE_REFERENCE` | The start date of the week or month in YYYY-MM-DD format. | -| `PUBLISHER_NAME` | The name of the organization that owns the DVP repository. | -| `DOMAIN` | The company domain that pulled both your DVP image and the paired image (e.g., `example.com`). | -| `DVPP_IMAGE` | Your Docker Verified Publisher image repository name. | -| `PAIRED_IMAGE` | The other image repository that was used together with your DVP image by this company. | +| Field | Description | +| ------------------ | ---------------------------------------------------------------------------------------------------- | +| `DATE_GRANULARITY` | Weekly or monthly granularity of the data. | +| `DATE_REFERENCE` | The start date of the week or month in YYYY-MM-DD format. | +| `PUBLISHER_NAME` | The name of the organization that owns the DVP repository. | +| `DOMAIN` | The consuming domain that pulled both your DVP image and the paired image (e.g., `example.com`). | +| `DVPP_IMAGE` | Your Docker Verified Publisher image repository name. | +| `PAIRED_IMAGE` | The other image repository that was used together with your DVP image by this domain. | -Each row represents a unique combination of a company domain, your DVP image, -and another image that were used together during the specified time period. +Each row represents a unique combination of a consuming domain, your DVP +image, and another image that were used together during the specified time +period. > [!NOTE] > @@ -241,31 +202,23 @@ and another image that were used together during the specified time period. > email domains, disposable email services, and university domains. Only > business and organizational domains are included in the analysis. -### Tracked companies report +##### Consuming domains report -The tracked companies report provides detailed insights into how specific -companies are using your Docker Verified Publisher (DVP) images. This report -helps you understand usage patterns, deployment environments, and adoption -trends across your customer base and potential prospects. - -You can use this report to answer questions like: - -- How are specific companies using my images across different environments? -- What deployment patterns do I see across local development, CI/CD, and - production? -- Which companies are heavy users of my images? -- How does usage vary by geography and cloud providers for tracked companies? +The consuming domains report provides detailed insights into how specific +consuming domains use your Docker Verified Publisher (DVP) images. This +report helps you understand usage patterns, deployment environments, and +adoption trends across your customer base and potential prospects. To access the report: 1. Sign in to [Docker Hub](https://hub.docker.com/). 2. Select **My Hub** in the top navigation. 3. Select your organization in the left navigation. -4. Select **Analytics** > **Tracked Companies** in the left navigation. +4. Select **Analytics** > **Consuming Domains** in the left navigation. 5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity. 6. Select **Download report** for the desired week or month. -The tracked companies report is a CSV file that contains the following data +The consuming domains report is a CSV file that contains the following data points: | Field | Description | @@ -273,7 +226,7 @@ points: | `DATE_GRANULARITY` | Weekly or monthly granularity of the data. | | `DATE_REFERENCE` | The start date of the week or month in YYYY-MM-DD format. | | `PUBLISHER_NAME` | The name of the organization that owns the DVP repository. | -| `DOMAIN` | The company domain (e.g., `docker.com`) associated with the image pulls. | +| `DOMAIN` | The consuming domain (e.g., `docker.com`) associated with the image pulls. | | `IP_COUNTRY` | The country code (ISO 3166-1 alpha-2) where the pull request originated from. | | `CLOUD_SERVICE_PROVIDER` | The cloud service provider used for the pull request or `no csp` for non-cloud providers. | | `USER_AGENT` | The client application or tool used to pull the image. | @@ -291,8 +244,65 @@ points: > are reclassified as CI/CD, and CI/CD tools used on cloud infrastructure are > reclassified as production to better reflect actual deployment patterns. -{{< /tab >}} -{{< tab name="DSOS & Legacy DVP programs" >}} +#### Benchmark report + +The benchmark report shows how consuming domains interact with the specific +images you've configured to benchmark against, such as a single repository. +The report is generated per repository, so each benchmark repository +you configure produces its own report. + +To access the report: + +1. Sign in to [Docker Hub](https://hub.docker.com/). +2. Select **My Hub** in the top navigation. +3. Select your organization in the left navigation. +4. Select **Analytics** > **Benchmark** in the left navigation. +5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity. +6. Select **Download report** for the desired week or month. + +The benchmark report is a CSV file that contains the following data points: + +| Field | Description | +| ----------------------------- | -------------------------------------------------------------------------------------------- | +| `DATE_GRANULARITY` | Weekly or monthly granularity of the data. | +| `DATE_REFERENCE` | The start date of the week or month in YYYY-MM-DD format. | +| `PUBLISHER_NAME` | The name of the organization that owns the DVP repository. | +| `DOMAIN` | The consuming domain associated with the pulls. | +| `IP_COUNTRY` | The country code (ISO 3166-1 alpha-2) where the pull request originated from. | +| `CLOUD_SERVICE_PROVIDER` | The cloud service provider used for the pull request, or `no csp` for non-cloud providers. | +| `USER_AGENT` | The client application or tool used to pull the image. | +| `INFERRED_USE_CASE` | The inferred deployment environment, using the same rules as the [consuming domains report](#consuming-domains-report). | +| `IMAGE_REPOSITORY` | The benchmark-configured image repository that was pulled. | +| `DATA_DOWNLOADS` | The number of actual image layer downloads for this combination. | +| `VERSION_CHECKS` | The number of version checks (HEAD requests) performed without downloading the full image. | +| `PULLS` | The total number of pull requests (data downloads + version checks). | +| `UNIQUE_AUTHENTICATED_USERS` | The number of unique authenticated users from this domain who performed pulls. | + +To configure which repositories are benchmarked, see [Configure DVP analytics +settings](#configure-dvp-analytics-settings). + +### Configure DVP analytics settings + +Organization owners and editors can configure DVP analytics settings through the +Admin Console to control consuming domain and benchmark report allocations for +your verified publisher namespaces. + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +2. Select **Admin Console** > **Verified Publisher**. +3. Configure the settings: + - **Consuming domains**: Set the number of consuming domains to track for + reporting purposes. This setting determines how many domains appear in + your [Domain-level reports](#domain-level-reports). You can only set this + number up to the maximum included in your DVP subscription. + - **Benchmark report allocations**: If your organization has benchmark + reports enabled, enter the number of consuming domains to include in the + benchmark report for each namespace listed. +4. Select **Save** to apply your changes. + +Changes to your report configuration take effect at the next reporting +cadence, either the next weekly or monthly report. + +## DSOS & Legacy DVP programs > [!IMPORTANT] > @@ -301,7 +311,7 @@ points: > your Docker sales representative or > [Docker](https://www.docker.com/partners/programs/) for more information. -## View the image's analytics data +### View the image's analytics data You can find analytics data for your repositories on the **Insights and analytics** dashboard at the following URL: @@ -322,7 +332,7 @@ To view data in the chart: > Hovering your cursor over the chart displays a tooltip, showing precise data > for points in time. -### Share analytics data +#### Share analytics data You can share the visualization with others using the **Share** icon at the top of the chart. This is a convenient way to share statistics with others in your @@ -335,7 +345,7 @@ preserves the display selections you made. When someone follows the link, the **Insights and analytics** page opens and displays the chart with the same configuration as you had set up when creating the link. -## Extension analytics data +### Extension analytics data If you have published Docker Extensions in the Extension marketplace, you can also get analytics about your extension usage, available as CSV files. You can @@ -345,7 +355,7 @@ the following URL: namespace contains extensions known in the marketplace, you will see an **Extensions** tab listing CSV files for your extension(s). -## Exporting analytics data +### Exporting analytics data You can export the analytics data either from the web dashboard, or using the [DVP Data API](/reference/api/dvp/latest.md). All members of an organization @@ -356,7 +366,7 @@ Sunday) or monthly format. Monthly data is available from the first day of the following calendar month. You can import this data into your own systems, or you can analyze it manually as a spreadsheet. -### Export data +#### Export data Export usage data for your organization's images using the Docker Hub website by following these steps: @@ -372,13 +382,13 @@ following these steps: ![Filtering options and download links for analytics data](../../../images/download-analytics-data.png) -### Export data using the API +#### Export data using the API The HTTP API endpoints are available at: `https://hub.docker.com/api/publisher/analytics/v1`. Learn how to export data using the API in the [DVP Data API documentation](/reference/api/dvp/latest.md). -## Data points +### Data points Export data in either raw or summary format. Each format contains different data points and with different structure. @@ -386,7 +396,7 @@ points and with different structure. The following sections describe the available data points for each format. The **Date added** column shows when the field was first introduced. -### Image pulls raw data +#### Image pulls raw data The raw data format contains the following data points. Each row in the CSV file represents an image pull. @@ -415,7 +425,7 @@ represents an image pull. [3]: /admin/organization/setup/orgs/ [4]: /docker-hub/repos/ -### Image pulls summary data +#### Image pulls summary data There are two levels of summary data available: @@ -434,7 +444,7 @@ span: | Version check | HEAD by tag, not followed by a GET | January 1, 2022 | | Owner | The name of the organization that owns the repository. | December 19, 2022 | -### Image pulls action classification rules +#### Image pulls action classification rules An action represents the multiple request events associated with a `docker pull`. Pulls are grouped by category to make the data more meaningful @@ -466,7 +476,7 @@ pulls. To provide feedback or ask questions about these rules, | HEAD | digest | GET by same digest | Pull by digest | Image is single-arch and/or image is multi-arch but some part of the image already exists on the local machine | | | HEAD | digest | GET by same digest, then a second GET by different digest | Pull by Digest | Image is multi-arch | | -### Extension Summary data +#### Extension Summary data There are two levels of extension summary data available: @@ -499,7 +509,7 @@ span: | Usage | Number of openings of the extension tab | Feb 1, 2024 | | UniqueUsers | Number of unique users openings the extension tab | Feb 1, 2024 | -## Changes in data over time +### Changes in data over time The insights and analytics service is continuously improved to increase the value it brings to publishers. Some changes might include adding new data @@ -511,9 +521,6 @@ from the date of when the field was first introduced, and going forward. Refer to the tables in the [Data points](#data-points) section to see from which date a given data point is available. -{{< /tab >}} -{{< /tabs >}} - ## Privacy This section contains information about privacy-protecting measures that ensures diff --git a/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md b/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md index 9a21813daa46..f49a66ffce96 100644 --- a/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md +++ b/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md @@ -140,8 +140,6 @@ To view the vulnerability report: It may take a couple of minutes for the vulnerability report to appear in your repository. - ![Vulnerability scan report](images/vuln-scan-report.png) - 4. Select the **Tags** tab, then **Digest**, then **Vulnerabilities** to view the detailed scan report. @@ -151,8 +149,6 @@ To view the vulnerability report: version in which it was introduced, and whether the vulnerability is fixed in a later version. - ![Vulnerability scan details](images/vuln-scan-details.png) - For more information on this view, see [Image details view](/manuals/scout/explore/image-details-view.md). diff --git a/content/manuals/docker-hub/repos/manage/webhooks.md b/content/manuals/docker-hub/repos/manage/webhooks.md index 0090bf5381e7..ed99a01cedd2 100644 --- a/content/manuals/docker-hub/repos/manage/webhooks.md +++ b/content/manuals/docker-hub/repos/manage/webhooks.md @@ -9,6 +9,23 @@ aliases: You can use webhooks to cause an action in another service in response to a push event in the repository. Webhooks are POST requests sent to a URL you define in Docker Hub. +## Prerequisites + +For a personal repository, only the repository owner can create webhooks. +Collaborators can't create webhooks. + +For an organization repository, you must be an organization owner or editor, +or a team member with admin permissions on the repository. For more details, +see [Organization teams](/manuals/docker-hub/repos/manage/access.md#organization-teams). + +To create a webhook using the Docker Hub API, authenticate with one of the +following: + +- A [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) + with delete permissions +- An [organization access token](/manuals/security/access-tokens/organization-access-tokens.md) + with the `scope-webhook-edit` scope or higher + ## Create a webhook To create a webhook: @@ -60,4 +77,9 @@ Webhook payloads have the following JSON format: > [!NOTE] > -> The `callback_url` field is a legacy field and is no longer supported. \ No newline at end of file +> The `callback_url` field is a legacy field and is no longer supported. + +Webhooks on a mirrored [Docker Hardened Image](/dhi/) repository include an +additional `dhi_metadata` object describing the vulnerability and package +changes in the pushed build. For details, see [Automate syncing with +webhooks](/dhi/how-to/mirror/#automate-syncing-with-webhooks). \ No newline at end of file diff --git a/content/manuals/docker-hub/troubleshoot.md b/content/manuals/docker-hub/troubleshoot.md index e0976f250d44..9cc1a60db0b5 100644 --- a/content/manuals/docker-hub/troubleshoot.md +++ b/content/manuals/docker-hub/troubleshoot.md @@ -33,7 +33,7 @@ You have reached your pull rate limit. You may increase the limit by authenticat You can use one of the following solutions: - [Authenticate](./usage/pulls.md#authentication) or - [upgrade](../subscription/change.md#upgrade-your-subscription) your Docker + [upgrade](../subscription-billing/manage/plans.md#upgrade-plans) your Docker account. - [View your pull rate limit](./usage/pulls.md#view-hourly-pull-rate-and-limit), wait until your pull rate limit decreases, and then try again. @@ -79,4 +79,4 @@ Unexpected status code 500 1. View the [Docker System Status Page](https://www.dockerstatus.com/) and verify that all services are operational. 2. Try accessing Docker Hub again. It may be a temporary issue. -3. [Contact Docker Support](https://www.docker.com/support/) to report the issue. \ No newline at end of file +3. [Contact Docker Support](https://www.docker.com/support/) to report the issue. diff --git a/content/manuals/docker-hub/usage/manage.md b/content/manuals/docker-hub/usage/manage.md index 14a01e7187ff..7b66b788fb2c 100644 --- a/content/manuals/docker-hub/usage/manage.md +++ b/content/manuals/docker-hub/usage/manage.md @@ -40,7 +40,7 @@ both individuals and organizations: following: - Routinely [view Docker Hub usage](https://hub.docker.com/usage) to monitor usage. - - [Enforce sign-in](/security/for-admins/enforce-sign-in/) to ensure that you + - [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) to ensure that you can monitor the usage of your users and users receive higher usage limits. - Look for duplicate user accounts in Docker and remove accounts from your organization as needed. \ No newline at end of file diff --git a/content/manuals/docker-hub/usage/pulls.md b/content/manuals/docker-hub/usage/pulls.md index c04e64c82ec0..74d5b83e168b 100644 --- a/content/manuals/docker-hub/usage/pulls.md +++ b/content/manuals/docker-hub/usage/pulls.md @@ -41,7 +41,7 @@ A pull is defined as the following: ## Pull attribution Pulls from authenticated users can be attributed to either a personal or an -[organization namespace](/manuals/accounts/general-faqs.md#whats-an-organization-name-or-namespace). +[organization namespace](/manuals/faqs/accounts.md#whats-an-organization-name-or-namespace). Attribution is based on the following: @@ -51,11 +51,11 @@ Attribution is based on the following: determined based on domain affiliation and organization membership. - Verified domain ownership: When pulling an image from an account linked to a verified domain, the attribution is set to be the owner of that - [domain](/manuals/enterprise/security/single-sign-on/faqs/domain-faqs.md). + [domain](/manuals/faqs/security.md). - Single organization membership: - If the owner of the verified domain is a company and the user is part of only one organization within that - [company](../../admin/company/company-faqs.md), + [company](/manuals/faqs/accounts.md), the pull is attributed to that specific organization. - If the user is part of only one organization, the pull is attributed to that specific organization. diff --git a/content/manuals/engine/containers/resource_constraints.md b/content/manuals/engine/containers/resource_constraints.md index 76df2f43cdad..b8cc7b9dae5e 100644 --- a/content/manuals/engine/containers/resource_constraints.md +++ b/content/manuals/engine/containers/resource_constraints.md @@ -115,7 +115,7 @@ Its setting can have complicated effects: [Prevent a container from using swap](#prevent-a-container-from-using-swap). - If `--memory-swap` is unset, and `--memory` is set, the container can use - as much swap as the `--memory` setting, if the host container has swap + as much swap as the `--memory` setting, if the host has swap memory configured. For instance, if `--memory="300m"` and `--memory-swap` is not set, the container can use 600m in total of memory and swap. diff --git a/content/manuals/engine/containers/runmetrics.md b/content/manuals/engine/containers/runmetrics.md index 62142d3cace9..eb1b69e5f1f0 100644 --- a/content/manuals/engine/containers/runmetrics.md +++ b/content/manuals/engine/containers/runmetrics.md @@ -17,7 +17,7 @@ You can use the `docker stats` command to live stream a container's runtime metrics. The command supports CPU, memory usage, memory limit, and network IO metrics. -The following is a sample output from the `docker stats` command +The following is a sample output from the `docker stats` command: ```console $ docker stats redis1 redis2 @@ -68,6 +68,14 @@ cgroup v2 is used by default on the following distributions: - Debian GNU/Linux (since 11) - Ubuntu (since 21.10) +> [!IMPORTANT] +> +> The detailed metrics examples later in this page describe the cgroup v1 file +> layout. On cgroup v2 hosts, use this page to find the container's cgroup +> directory and then inspect the controller files in that directory (for +> example, `memory.*`, `cpu.*`, and `io.*`). For controller semantics, refer to +> the [cgroup v2 kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html). + #### cgroup v1 You can look into `/proc/cgroups` to see the different control group subsystems @@ -137,12 +145,14 @@ container, take a look at the following paths: - `/sys/fs/cgroup/docker/<longid>/` on cgroup v2, `cgroupfs` driver - `/sys/fs/cgroup/system.slice/docker-<longid>.scope/` on cgroup v2, `systemd` driver -### Metrics from cgroups: memory, CPU, block I/O +### Metrics from cgroups: memory, CPU, block I/O (cgroup v1) > [!NOTE] > -> This section isn't yet updated for cgroup v2. -> For further information about cgroup v2, refer to [the kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html). +> This section documents the cgroup v1 metric files and formats. +> For cgroup v2, inspect the relevant controller files in the container's +> cgroup directory and refer to +> [the kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html). For each subsystem (memory, CPU, and block I/O), one or more pseudo-files exist and contain statistics. diff --git a/content/manuals/engine/containers/start-containers-automatically.md b/content/manuals/engine/containers/start-containers-automatically.md index c513208bf8f0..79bcf9493769 100644 --- a/content/manuals/engine/containers/start-containers-automatically.md +++ b/content/manuals/engine/containers/start-containers-automatically.md @@ -12,12 +12,12 @@ aliases: Docker provides [restart policies](/reference/cli/docker/container/run/#restart) to control whether your containers start automatically when they exit, or when -Docker restarts. Restart policies start linked containers in the correct order. +Docker restarts. Docker recommends that you use restart policies, and avoid using process managers to start containers. Restart policies are different from the `--live-restore` flag of the `dockerd` -command. Using `--live-restore` lets you to keep your containers running during +command. Using `--live-restore` lets you keep your containers running during a Docker upgrade, though networking and user input are interrupted. ## Use a restart policy @@ -33,11 +33,12 @@ any of the following: | `always` | Always restart the container if it stops. If it's manually stopped, it's restarted only when Docker daemon restarts or the container itself is manually restarted. (See the second bullet listed in [restart policy details](#restart-policy-details)) | | `unless-stopped` | Similar to `always`, except that when the container is stopped (manually or otherwise), it isn't restarted even after Docker daemon restarts. | -The following command starts a Redis container and configures it to always -restart, unless the container is explicitly stopped, or the daemon restarts. +The following command starts a Redis container with the `unless-stopped` +restart policy. Docker restarts the container if it exits or if the daemon +restarts, but not if you stopped the container yourself. ```console -$ docker run -d --restart unless-stopped redis +$ docker run -d --name redis --restart unless-stopped redis ``` The following command changes the restart policy for an already running diff --git a/content/manuals/engine/daemon/_index.md b/content/manuals/engine/daemon/_index.md index 32fcab96287a..a7308d944e93 100644 --- a/content/manuals/engine/daemon/_index.md +++ b/content/manuals/engine/daemon/_index.md @@ -84,6 +84,33 @@ $ dockerd --debug \ --host tcp://192.168.59.3:2376 ``` +#### Listen on a Unix socket on Windows + +Starting with Docker Engine 29.5, you can configure `dockerd` on Windows to +listen on a Unix socket. This setting is optional. The default Windows endpoint +remains the `npipe` named pipe. + +Run `dockerd` from an elevated PowerShell session: + +```powershell +PS C:\> dockerd -H unix://C:/Users/<USER>/docker.sock --group docker-users +``` + +Replace `<USER>` with the name of your Windows user profile directory. +Without `--group`, only members of the Administrators group and the `SYSTEM` +account can access the socket. Use a comma-separated list to grant access to +multiple users or groups. + +Use a path in the user profile when granting access with `--group`. A socket +created directly under `C:\` can inherit a high integrity level that blocks +access for the configured users and groups. + +Configure the Docker client to use the same socket: + +```powershell +PS C:\> docker -H unix://C:/Users/<USER>/docker.sock info +``` + Learn about the available configuration options in the [dockerd reference docs](/reference/cli/dockerd.md), or by running: @@ -143,6 +170,7 @@ Many specific configuration options are discussed throughout the Docker documentation. Some places to go next include: - [Automatically start containers](/manuals/engine/containers/start-containers-automatically.md) +- [Run containerd in the Docker daemon](/manuals/engine/daemon/embedded-containerd.md) - [Limit a container's resources](/manuals/engine/containers/resource_constraints.md) - [Configure storage drivers](/manuals/engine/storage/drivers/select-storage-driver.md) - [Container security](/manuals/engine/security/_index.md) diff --git a/content/manuals/engine/daemon/embedded-containerd.md b/content/manuals/engine/daemon/embedded-containerd.md new file mode 100644 index 000000000000..54f1efa9bf91 --- /dev/null +++ b/content/manuals/engine/daemon/embedded-containerd.md @@ -0,0 +1,118 @@ +--- +title: Run containerd in the Docker daemon +linkTitle: Embedded containerd +description: Configure Docker Engine to run an experimental containerd server in the Docker daemon process +keywords: docker, daemon, dockerd, containerd, configuration, experimental +weight: 35 +params: + sidebar: + badge: + color: blue + text: Experimental +--- + +Starting with Docker Engine 29.7.0, the Docker daemon can run containerd in +the same process as `dockerd`. By default, the daemon starts and manages +containerd as a separate process. + +> [!CAUTION] +> +> Embedded containerd is an experimental feature. Its behavior may change, or +> the feature may be removed from a future release. + +Embedded mode changes how the daemon starts and communicates with containerd. +The embedded server still listens on a containerd socket, but the daemon and +BuildKit reach it over an in-memory connection instead. Task shims continue to +run as separate processes and connect over a socket. + +The performance benefit is greatest when Docker uses the containerd image +store. +Any image interactions use containerd's content API for both metadata requests +and the bytes that make up image manifests, configurations, and layers. +A separate containerd process splits these reads and writes into gRPC messages +that cross a Unix socket or named pipe. +Embedded mode sends the same messages over an in-memory connection, avoiding +operating system socket calls and kernel transport for this data-heavy path. + +The embedded server doesn't include the container runtime interface (CRI). +You can't enable `embedded-containerd` and `cri-containerd` at the same time. + +## Enable embedded containerd + +Add the `embedded-containerd` feature to the +[daemon configuration file](./_index.md#configuration-file): + +```json +{ + "features": { + "embedded-containerd": true + } +} +``` + +Restart the Docker daemon: + +```console +$ sudo systemctl restart docker +``` + +The `embedded-containerd` feature takes precedence over a containerd address +set with the `--containerd` daemon flag. This behavior means that packaged +service configurations that set a containerd address don't prevent embedded +containerd from starting. + +> [!IMPORTANT] +> +> Embedded containerd keeps its state under the Docker data root, in +> `/var/lib/docker/containerd/daemon` by default. A containerd installed on the +> host keeps its own state elsewhere, such as `/var/lib/containerd`. If the +> daemon used such a containerd before, the containers and images stored there +> aren't available in embedded mode. + +You can also enable the feature when starting `dockerd` manually: + +```console +$ sudo dockerd --feature embedded-containerd +``` + +## Verify the configuration + +Run `docker info` and check for the experimental mode warning: + +```console +$ docker info +... +NOTE: Running with experimental embedded-containerd mode. In a future release, +this mode may be used by default when no system containerd is available, rather +than starting and supervising a separate containerd process. The option used to +enable this mode may also change. +``` + +## Connect directly to embedded containerd + +The embedded server provides an endpoint for containerd clients such as +`ctr` and `nerdctl`. On Linux, the endpoint is +`<exec-root>/containerd/containerd.sock`. With the default daemon +configuration, this path is: + +```text +/var/run/docker/containerd/containerd.sock +``` + +On Windows, the server uses a named pipe by default. Check the Docker daemon startup logs +for the endpoint address. + +Docker Engine stores containers in the `moby` containerd namespace by +default. For example, use `ctr` on Linux to list them: + +```console +$ sudo ctr --address /var/run/docker/containerd/containerd.sock \ + --namespace moby containers list +``` + +> [!WARNING] +> +> The endpoint is useful for debugging, but the daemon owns the state behind +> it. Don't treat it as a general-purpose containerd endpoint: its address and +> the layout of the namespaces can change, and changes that other clients make +> can conflict with the daemon. diff --git a/content/manuals/engine/daemon/proxy.md b/content/manuals/engine/daemon/proxy.md index 5f3ff0f609f7..ab08a3824066 100644 --- a/content/manuals/engine/daemon/proxy.md +++ b/content/manuals/engine/daemon/proxy.md @@ -110,7 +110,7 @@ systemd drop-in file that sets the variables for the `docker` service. ``` Multiple environment variables can be set; to set both an HTTP and an - HTTPS proxy; + HTTPS proxy: ```systemd [Service] @@ -196,7 +196,7 @@ systemd drop-in file that sets the variables for the `docker` service. ``` Multiple environment variables can be set; to set both an HTTP and an - HTTPS proxy; + HTTPS proxy: ```systemd [Service] diff --git a/content/manuals/engine/daemon/remote-access.md b/content/manuals/engine/daemon/remote-access.md index 721990498691..a33e75e8c582 100644 --- a/content/manuals/engine/daemon/remote-access.md +++ b/content/manuals/engine/daemon/remote-access.md @@ -71,6 +71,11 @@ and the `daemon.json` file causes a conflict that prevents Docker from starting. ### Configuring remote access with `daemon.json` +> [!IMPORTANT] +> +> Setting `hosts` in the `daemon.json` isn't supported on Docker Desktop for +> Windows or Docker Desktop for Mac. + 1. Set the `hosts` array in the `/etc/docker/daemon.json` to connect to the Unix socket and an IP address, as follows: diff --git a/content/manuals/engine/daemon/troubleshoot.md b/content/manuals/engine/daemon/troubleshoot.md index 770b2db6179d..e5a674f769d0 100644 --- a/content/manuals/engine/daemon/troubleshoot.md +++ b/content/manuals/engine/daemon/troubleshoot.md @@ -120,7 +120,7 @@ ExecStart=/usr/bin/dockerd ``` There are other times when you might need to configure `systemd` with Docker, -such as [configuring a HTTP or HTTPS proxy](./proxy.md). +such as [configuring an HTTP or HTTPS proxy](./proxy.md). > [!NOTE] > diff --git a/content/manuals/engine/install/_index.md b/content/manuals/engine/install/_index.md index 5b30fd279b62..de146358e073 100644 --- a/content/manuals/engine/install/_index.md +++ b/content/manuals/engine/install/_index.md @@ -48,8 +48,8 @@ aliases: - /installation/sles/ --- -This section describes how to install Docker Engine on Linux, also known as -Docker CE. Docker Engine is also available for Windows, macOS, and Linux, +This section describes how to install Docker Engine on Linux. Docker Engine is +also available for Windows, macOS, and Linux, through Docker Desktop. For instructions on how to install Docker Desktop, see: [Overview of Docker Desktop](/manuals/desktop/_index.md). @@ -137,4 +137,4 @@ Security reports are greatly appreciated, and Docker will publicly thank you for ## Get started After setting up Docker, you can learn the basics with -[Getting started with Docker](/get-started/introduction/_index.md). +[Build and share a containerized application](/get-started/tutorials/run-an-app.md). diff --git a/content/manuals/engine/install/debian.md b/content/manuals/engine/install/debian.md index 5ddc7d1f131c..816a141fc680 100644 --- a/content/manuals/engine/install/debian.md +++ b/content/manuals/engine/install/debian.md @@ -43,7 +43,6 @@ To install Docker Engine, you need one of these Debian versions: - Debian Trixie 13 (stable) - Debian Bookworm 12 (oldstable) -- Debian Bullseye 11 (oldoldstable) Docker Engine for Debian is compatible with x86_64 (or amd64), armhf (arm/v7), arm64, and ppc64le (ppc64el) architectures. @@ -61,6 +60,7 @@ The unofficial packages to uninstall are: - `docker.io` - `docker-compose` - `docker-doc` +- `docker-buildx` - `podman-docker` Moreover, Docker Engine depends on `containerd` and `runc`. Docker Engine @@ -71,7 +71,7 @@ conflicts with the versions bundled with Docker Engine. Run the following command to uninstall all conflicting packages: ```console -$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1) +$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc docker-buildx podman-docker containerd runc | cut -f1) ``` `apt` might report that you have none of these packages installed. diff --git a/content/manuals/engine/install/fedora.md b/content/manuals/engine/install/fedora.md index 205143baa678..8e97e8a45ef9 100644 --- a/content/manuals/engine/install/fedora.md +++ b/content/manuals/engine/install/fedora.md @@ -26,9 +26,9 @@ To get started with Docker Engine on Fedora, make sure you To install Docker Engine, you need a maintained version of one of the following Fedora versions: +- Fedora 45 - Fedora 44 - Fedora 43 -- Fedora 42 ### Uninstall old versions diff --git a/content/manuals/engine/install/linux-postinstall.md b/content/manuals/engine/install/linux-postinstall.md index f82fe4b61179..61caa7b79466 100644 --- a/content/manuals/engine/install/linux-postinstall.md +++ b/content/manuals/engine/install/linux-postinstall.md @@ -22,12 +22,14 @@ The Docker daemon binds to a Unix socket, not a TCP port. By default it's the `root` user that owns the Unix socket, and other users can only access it using `sudo`. The Docker daemon always runs as the `root` user. -If you don't want to preface the `docker` command with `sudo`, create a Unix -group called `docker` and add users to it. When the Docker daemon starts, it -creates a Unix socket accessible by members of the `docker` group. On some Linux -distributions, the system automatically creates this group when installing -Docker Engine using a package manager. In that case, there is no need for you to -manually create the group. +When the Docker daemon starts, it creates a Unix socket accessible by members of the `docker` group. +On some Linux distributions, the system automatically creates this group when installing Docker Engine using a package manager. +In that case, you don't need to create the group manually. + +There are two ways to run `docker` commands without `sudo` while the Docker daemon runs as `root`: + +- [Add your user to the `docker` group](#add-your-user-to-the-docker-group) for access throughout your login session. +- [Access the `docker` group on demand](#access-the-docker-group-on-demand) by entering a password-protected, Docker-enabled shell. <!-- prettier-ignore --> > [!WARNING] @@ -41,6 +43,8 @@ manually create the group. > To run Docker without root privileges, see > [Run the Docker daemon as a non-root user (Rootless mode)](../security/rootless.md). +### Add your user to the `docker` group + To create the `docker` group and add your user: 1. Create the `docker` group. @@ -95,6 +99,137 @@ To create the `docker` group and add your user: $ sudo chmod g+rwx "$HOME/.docker" -R ``` +### Access the `docker` group on demand + +Group passwords are a legacy Unix access-control mechanism, but they can be useful for gating Docker access on a single-user workstation. +Like `sudo`, this method adds an explicit password step before privileged access. +Unlike running `sudo docker`, `newgrp` keeps the Docker CLI running under your user ID and grants access through the shell's primary group, so the CLI doesn't access its configuration as `root`. + +Permanent membership in the `docker` group gives every process in your login session access to the Docker socket. +The Docker-enabled shell and its descendants inherit access to the Docker socket. +This reduces ambient access from applications running elsewhere in your login session. +To configure this access, keep your user out of the group, set a group password, and use `newgrp` to start a Docker-enabled shell. + +> [!WARNING] +> +> A group password reduces ambient access to the Docker socket, but it doesn't reduce the root-level privileges granted after access is authorized. +> Group passwords are also shared secrets and don't provide per-user accountability. +> This method isn't a security boundary against malicious code running as your user. +> Such code can modify user-writable shell configuration, commands, or scripts that you later use from the Docker-enabled shell and gain Docker access after you authenticate. +> Don't rely on a group password to contain untrusted code or protect a compromised login session. +> This configuration is most suitable for a single-user workstation. +> For stronger isolation, use [Rootless mode](../security/rootless.md) or run Docker in a virtual machine. + +This procedure requires `gpasswd` and `newgrp`. +The package names for these commands vary by Linux distribution. +Verify that both commands are available: + +```console +$ command -v gpasswd newgrp +/usr/bin/gpasswd +/usr/bin/newgrp +``` + +To require a password for Docker access: + +1. Create the `docker` group if it doesn't exist: + + ```console + $ sudo groupadd --force docker + ``` + + The `--force` option makes the command succeed when the group already exists. + +2. If your user is a member of the `docker` group, remove the membership: + + ```console + $ sudo gpasswd --delete "$USER" docker + ``` + + Sign out of the desktop or SSH session completely, then sign back in. + Group membership remains in the credentials of existing processes, so opening a new terminal isn't sufficient. + + Verify that `docker` is absent from the group list before continuing: + + ```console + $ id -nG + user wheel + ``` + + Your group list varies by system, but it must not include `docker`. + +3. Set a dedicated password for the `docker` group: + + ```console + $ sudo gpasswd docker + Changing the password for group docker + New Password: + Re-enter new password: + ``` + + Don't add your user back to the group. + Users configured as group members can use `newgrp` without entering the group password. + +4. Start a child shell with `docker` as its primary group: + + ```console + $ newgrp docker + Password: + ``` + + Verify that the shell still uses your user ID and has `docker` as its primary group, then test Docker access: + + ```console + $ id -un + user + $ id -gn + docker + $ docker run --rm hello-world + ``` + + Commands and applications started from this shell inherit access to the Docker socket. + Applications that were already running outside the shell don't gain access. + + > [!CAUTION] + > + > Files and directories created from this shell normally have `docker` as their group owner. + > Use this shell only for Docker-related commands, or verify the group ownership of files you create. + +5. Exit the Docker-enabled shell when you finish: + + ```console + $ exit + ``` + + Verify that `docker` is no longer in the original shell's group list: + + ```console + $ id -nG + user wheel + ``` + +> [!CAUTION] +> +> Exiting the shell doesn't revoke access from background, detached, or daemonized processes started inside it. +> Those processes retain the `docker` group until they exit. + +To change the group password, run `sudo gpasswd docker` again. + +#### Disable password-based entry + +To stop using the shared password and require configured group membership, run: + +```console +$ sudo gpasswd --restrict docker +``` + +This reverses the password-gated setup. +Afterward, only users configured as members of the `docker` group can enter it. +The change affects new authorization attempts; it doesn't terminate existing Docker-enabled shells or their descendant processes. + +`gpasswd` manages local `/etc/group` and `/etc/gshadow` files. +Systems using LDAP, NIS, or another identity service require that service's group-management mechanism. + ## Configure Docker to start on boot with systemd Many modern Linux distributions use [systemd](https://systemd.io/) to @@ -141,4 +276,4 @@ options: ## Next steps -- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. +- Take a look at [Get started with Docker](/get-started/tutorials/run-an-app.md) to learn how to build an image and run it as a containerized application. diff --git a/content/manuals/engine/install/ubuntu.md b/content/manuals/engine/install/ubuntu.md index 38d23463673b..bbc0cd5573f7 100644 --- a/content/manuals/engine/install/ubuntu.md +++ b/content/manuals/engine/install/ubuntu.md @@ -51,8 +51,8 @@ To get started with Docker Engine on Ubuntu, make sure you To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions: +- Ubuntu Stonking 26.10 - Ubuntu Resolute 26.04 (LTS) -- Ubuntu Questing 25.10 - Ubuntu Noble 24.04 (LTS) - Ubuntu Jammy 22.04 (LTS) @@ -78,6 +78,7 @@ The unofficial packages to uninstall are: - `docker-compose` - `docker-compose-v2` - `docker-doc` +- `docker-buildx` - `podman-docker` Moreover, Docker Engine depends on `containerd` and `runc`. Docker Engine @@ -88,7 +89,7 @@ conflicts with the versions bundled with Docker Engine. Run the following command to uninstall all conflicting packages: ```console -$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1) +$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc | cut -f1) ``` `apt` might report that you have none of these packages installed. diff --git a/content/manuals/engine/logging/configure.md b/content/manuals/engine/logging/configure.md index 596d27adb611..04499ccfa6f9 100644 --- a/content/manuals/engine/logging/configure.md +++ b/content/manuals/engine/logging/configure.md @@ -26,7 +26,7 @@ included with Docker, you can also implement and use [logging driver plugins](pl > [!TIP] > > Use the `local` logging driver to prevent disk-exhaustion. By default, no log-rotation is performed. As a result, log-files stored by the -> default [`json-file` logging driver](drivers/json-file.md) logging driver can cause +> default [`json-file` logging driver](drivers/json-file.md) can cause > a significant amount of disk space to be used for containers that generate much > output, which can lead to disk space exhaustion. > @@ -74,7 +74,19 @@ example sets four configurable options on the `json-file` logging driver: } ``` -Restart Docker for the changes to take effect for newly created containers. +Restart Docker Engine on a Linux system that uses `systemd`: + +```console +$ sudo systemctl restart docker +``` + +If you use Docker Desktop, restart it with the Docker Desktop CLI: + +```console +$ docker desktop restart +``` + +The changes take effect for newly created containers after the restart. Existing containers don't use the new logging configuration automatically. > [!NOTE] diff --git a/content/manuals/engine/logging/drivers/awslogs.md b/content/manuals/engine/logging/drivers/awslogs.md index 46fa73992768..8839f6075cfd 100644 --- a/content/manuals/engine/logging/drivers/awslogs.md +++ b/content/manuals/engine/logging/drivers/awslogs.md @@ -338,6 +338,14 @@ default AWS shared credentials file (`~/.aws/credentials` of the root user), or if you are running the Docker daemon on an Amazon EC2 instance, the Amazon EC2 instance profile. +> [!NOTE] +> Docker reads AWS credentials when the container starts. +> If you use a shared AWS credentials file with temporary credentials, +> updating the file later does not automatically update the credentials +> used by the running container. When the temporary credentials expire, +> log delivery to Amazon CloudWatch Logs can fail. Restart the container +> after refreshing the credentials so Docker can load the updated values. + Credentials must have a policy applied that allows the `logs:CreateLogStream` and `logs:PutLogEvents` actions, as shown in the following example. diff --git a/content/manuals/engine/logging/drivers/journald.md b/content/manuals/engine/logging/drivers/journald.md index 071d736787ac..abb3f8057b49 100644 --- a/content/manuals/engine/logging/drivers/journald.md +++ b/content/manuals/engine/logging/drivers/journald.md @@ -139,5 +139,5 @@ reader = systemd.journal.Reader() reader.add_match('CONTAINER_NAME=web') for msg in reader: - print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg) + print('{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg)) ``` diff --git a/content/manuals/engine/logging/drivers/json-file.md b/content/manuals/engine/logging/drivers/json-file.md index 2d2ce9ec86b0..834d6f6c14d6 100644 --- a/content/manuals/engine/logging/drivers/json-file.md +++ b/content/manuals/engine/logging/drivers/json-file.md @@ -74,7 +74,7 @@ The `json-file` logging driver supports the following logging options: | Option | Description | Example value | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- | -| `max-size` | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to -1 (unlimited). | `--log-opt max-size=10m` | +| `max-size` | The maximum size of the log before it is rolled. A positive integer plus a unit modifier (`k`, `m`, or `g`; case-insensitive). Defaults to -1 (unlimited). | `--log-opt max-size=10m` | | `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. **Only effective when `max-size` is also set.** A positive integer. Defaults to 1. | `--log-opt max-file=3` | | `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Used for advanced [log tag options](log_tags.md). | `--log-opt labels=production_status,geo` | | `labels-regex` | Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](log_tags.md). | `--log-opt labels-regex=^(production_status\|geo)` | diff --git a/content/manuals/engine/logging/drivers/local.md b/content/manuals/engine/logging/drivers/local.md index d5cd56fc6647..93df55251b27 100644 --- a/content/manuals/engine/logging/drivers/local.md +++ b/content/manuals/engine/logging/drivers/local.md @@ -64,7 +64,7 @@ The `local` logging driver supports the following logging options: | Option | Description | Example value | | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------- | -| `max-size` | The maximum size of the log before it's rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to 20m. | `--log-opt max-size=10m` | +| `max-size` | The maximum size of the log before it's rolled. A positive integer plus a unit modifier (`k`, `m`, or `g`; case-insensitive). Defaults to 20m. | `--log-opt max-size=10m` | | `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. A positive integer. Defaults to 5. | `--log-opt max-file=3` | | `compress` | Toggle compression of rotated log files. Enabled by default. | `--log-opt compress=false` | diff --git a/content/manuals/engine/logging/dual-logging.md b/content/manuals/engine/logging/dual-logging.md index 15a1887f2a11..188211f79e3d 100644 --- a/content/manuals/engine/logging/dual-logging.md +++ b/content/manuals/engine/logging/dual-logging.md @@ -122,7 +122,7 @@ options described below to customize these defaults. | Option | Default | Description | | :--------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | `cache-disabled` | `"false"` | Disable local caching. Boolean value passed as a string (`true`, `1`, `0`, or `false`). | -| `cache-max-size` | `"20m"` | The maximum size of the cache before it is rotated. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). | +| `cache-max-size` | `"20m"` | The maximum size of the cache before it is rotated. A positive integer plus a unit modifier (`k`, `m`, or `g`; case-insensitive). | | `cache-max-file` | `"5"` | The maximum number of cache files that can be present. If rotating the logs creates excess files, the oldest file is removed. A positive integer. | | `cache-compress` | `"true"` | Enable or disable compression of rotated log files. Boolean value passed as a string (`true`, `1`, `0`, or `false`). | diff --git a/content/manuals/engine/manage-resources/pruning.md b/content/manuals/engine/manage-resources/pruning.md index 9c6861d1bece..d5d6db2da9c9 100644 --- a/content/manuals/engine/manage-resources/pruning.md +++ b/content/manuals/engine/manage-resources/pruning.md @@ -10,12 +10,13 @@ aliases: --- Docker takes a conservative approach to cleaning up unused objects (often -referred to as "garbage collection"), such as images, containers, volumes, and -networks. These objects are generally not removed unless you explicitly ask -Docker to do so. This can cause Docker to use extra disk space. For each type of -object, Docker provides a `prune` command. In addition, you can use `docker -system prune` to clean up multiple types of objects at once. This topic shows -how to use these `prune` commands. +referred to as "garbage collection"), such as images, containers, volumes, +networks, and build cache. These objects are generally not removed unless you +explicitly ask Docker to do so. This can cause Docker to use extra disk space. +For each type of object, Docker provides a `prune` command. In addition, you can +use `docker system prune` to clean up multiple types of objects at once +(including unused build cache). This topic shows how to use these `prune` +commands. ## Prune images @@ -96,16 +97,18 @@ data. ```console $ docker volume prune -WARNING! This will remove all volumes not used by at least one container. +WARNING! This will remove anonymous local volumes not used by at least one container. Are you sure you want to continue? [y/N] y ``` By default, you are prompted to continue. To bypass the prompt, use the `-f` or `--force` flag. -By default, all unused volumes are removed. You can limit the scope using -the `--filter` flag. For instance, the following command only removes -volumes which aren't labelled with the `keep` label: +By default, only **anonymous** unused volumes are removed. Named volumes that +aren't attached to a container are left alone unless you pass `--all` / `-a`. +You can also limit the scope with the `--filter` flag. For instance, the +following command only removes volumes which aren't labelled with the `keep` +label: ```console $ docker volume prune --filter "label!=keep" @@ -166,8 +169,10 @@ for all options, including `--all` to also remove internal and frontend images. ## Prune everything The `docker system prune` command is a shortcut that prunes images, containers, -and networks. Volumes aren't pruned by default, and you must specify the -`--volumes` flag for `docker system prune` to prune volumes. +networks, and unused build cache (including BuildKit cache mounts). Volumes +aren't pruned by default. Add `--volumes` to also remove unused **anonymous** +volumes. Named unused volumes are left alone; use `docker volume prune --all` +if you intend to delete those too. ```console $ docker system prune @@ -181,7 +186,7 @@ WARNING! This will remove: Are you sure you want to continue? [y/N] y ``` -To also prune volumes, add the `--volumes` flag: +To also prune unused anonymous volumes, add the `--volumes` flag: ```console $ docker system prune --volumes @@ -189,9 +194,9 @@ $ docker system prune --volumes WARNING! This will remove: - all stopped containers - all networks not used by at least one container - - all volumes not used by at least one container + - all anonymous volumes not used by at least one container - all dangling images - - all build cache + - unused build cache Are you sure you want to continue? [y/N] y ``` @@ -199,9 +204,10 @@ Are you sure you want to continue? [y/N] y By default, you're prompted to continue. To bypass the prompt, use the `-f` or `--force` flag. -By default, all unused containers, networks, and images are removed. You can -limit the scope using the `--filter` flag. For instance, the following command -removes items older than 24 hours: +By default, unused containers and networks are removed, along with dangling +images. Unused tagged images are kept unless you also pass `-a` / `--all`. +You can further limit the scope with the `--filter` flag. For instance, the +following command removes items older than 24 hours: ```console $ docker system prune --filter "until=24h" diff --git a/content/manuals/engine/network/_index.md b/content/manuals/engine/network/_index.md index 35d6e11787de..e68950cc595b 100644 --- a/content/manuals/engine/network/_index.md +++ b/content/manuals/engine/network/_index.md @@ -267,6 +267,15 @@ The embedded DNS server address is `127.0.0.11`. There is no IPv6 equivalent; the IPv4 address works even in IPv6-only containers. If an application requires an explicit DNS server address, use `127.0.0.11`. +> [!NOTE] +> +> When you configure multiple DNS servers for a container on the default +> `bridge` network, the container's resolver library determines how it queries +> them. Some resolvers query the servers in order. Others query them in parallel +> and use the first response received, even if that response is `NXDOMAIN`. +> On a custom network, Docker's embedded DNS server queries upstream servers in +> order and stops after a successful response or an `NXDOMAIN` response. + You can configure DNS resolution on a per-container basis, using flags for the `docker run` or `docker create` command used to start the container. The following table describes the available `docker run` flags related to DNS diff --git a/content/manuals/engine/network/drivers/bridge.md b/content/manuals/engine/network/drivers/bridge.md index 17f3a6dea11a..74c452defd22 100644 --- a/content/manuals/engine/network/drivers/bridge.md +++ b/content/manuals/engine/network/drivers/bridge.md @@ -115,17 +115,17 @@ flag. The following table describes the driver-specific options that you can pass to `--opt` when creating a custom network using the `bridge` driver. -| Option | Default | Description | -| ----------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- | -| `com.docker.network.bridge.name` | | Interface name to use when creating the Linux bridge. | -| `com.docker.network.bridge.enable_ip_masquerade` | `true` | Enable IP masquerading. | -| `com.docker.network.host_ipv4`<br/>`com.docker.network.host_ipv6` | | Address to use for source NAT. See [Packet filtering and firewalls](packet-filtering-firewalls.md). | -| `com.docker.network.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Control external connectivity. See [Packet filtering and firewalls](packet-filtering-firewalls.md). | -| `com.docker.network.bridge.enable_icc` | `true` | Enable or Disable inter-container connectivity. | -| `com.docker.network.bridge.host_binding_ipv4` | all IPv4 and IPv6 addresses | Default IP when binding container ports. | -| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). | -| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. | -| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-bridge-ip-address-configuration) to the bridge. | +| Option | Default | Description | +| ----------------------------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `com.docker.network.bridge.name` | | Interface name to use when creating the Linux bridge. | +| `com.docker.network.bridge.enable_ip_masquerade` | `true` | Enable IP masquerading. | +| `com.docker.network.host_ipv4`<br/>`com.docker.network.host_ipv6` | | Address to use for source NAT. See [Port publishing](../port-publishing.md#masquerade-or-snat-for-outgoing-packets). | +| `com.docker.network.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Control external connectivity. See [Port publishing](../port-publishing.md#gateway-modes). | +| `com.docker.network.bridge.enable_icc` | `true` | Enable or Disable inter-container connectivity. | +| `com.docker.network.bridge.host_binding_ipv4` | all IPv4 and IPv6 addresses | Default IP when binding container ports. | +| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). | +| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. | +| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-bridge-ip-address-configuration) to the bridge. | Some of these options are also available as flags to the `dockerd` CLI, and you can use them to configure the default `docker0` bridge when starting the Docker diff --git a/content/manuals/engine/network/drivers/host.md b/content/manuals/engine/network/drivers/host.md index 86c53e01113c..50b94c03cabb 100644 --- a/content/manuals/engine/network/drivers/host.md +++ b/content/manuals/engine/network/drivers/host.md @@ -18,8 +18,8 @@ address. > [!NOTE] > > Given that the container does not have its own IP-address when using -> `host` mode networking, [port-mapping](overlay.md#publish-ports) doesn't -> take effect, and the `-p`, `--publish`, `-P`, and `--publish-all` option are +> `host` mode networking, [port mapping](../port-publishing.md) doesn't +> take effect, and the `-p`, `--publish`, `-P`, and `--publish-all` options are > ignored, producing a warning instead: > > ```console diff --git a/content/manuals/engine/network/drivers/ipvlan.md b/content/manuals/engine/network/drivers/ipvlan.md index 2bcd17f27eb2..71b23f17ea91 100644 --- a/content/manuals/engine/network/drivers/ipvlan.md +++ b/content/manuals/engine/network/drivers/ipvlan.md @@ -3,7 +3,7 @@ title: IPvlan network driver description: All about using IPvlan to make your containers appear like physical machines on the network -keywords: network, ipvlan, l2, l3, standalone +keywords: network, ipvlan, l2, l3, standalone, ipv6, slaac aliases: - /network/ipvlan/ - /network/drivers/ipvlan/ @@ -15,7 +15,7 @@ layer 2 VLAN tagging and even IPvlan L3 routing for users interested in underlay network integration. For overlay deployments that abstract away physical constraints see the [multi-host overlay](overlay.md) driver. -IPvlan is a new twist on the tried and true network virtualization technique. +IPvlan is a network virtualization technique that provides lightweight container networking. The Linux implementations are extremely lightweight because rather than using the traditional Linux bridge for isolation, they are associated to a Linux Ethernet interface or sub-interface to enforce separation between networks and @@ -286,7 +286,7 @@ An example being, NetOps provides VLAN ID and the associated subnets for VLANs being passed on the Ethernet link to the Docker host server. Those values are plugged into the `docker network create` commands when provisioning the Docker networks. These are persistent configurations that are applied every time -the Docker engine starts which alleviates having to manage often complex +Docker Engine starts which alleviates having to manage often complex configuration files. The network interfaces can also be managed manually by being pre-created and Docker networking will never modify them, and use them as parent interfaces. Example mappings from NetOps to Docker network commands @@ -512,6 +512,30 @@ $ docker run --net=ipvlan140 --ip=192.168.140.10 -it --rm alpine /bin/sh > subnet. However, IPvlan `L3` will route the unicast traffic between disparate > subnets as long as they share the same `-o parent` parent link. +### Use router-assigned IPv6 addresses + +The previous examples assign IPv6 addresses from a subnet managed by Docker's +IPAM. On an `ipvlan` network, you can instead let containers receive IPv6 +addresses directly from a router on the parent network, using stateless +address autoconfiguration (SLAAC). + +When an `ipvlan` network has no IPv6 subnet, Docker disables IPv6 on the +container's interface, so it can't accept the router advertisements that SLAAC +relies on. To re-enable IPv6 on the interface, set its `disable_ipv6` sysctl +to `0` when you connect the container to the network: + +```console +$ docker network connect \ + --driver-opt="com.docker.network.endpoint.sysctls=net.ipv6.conf.IFNAME.disable_ipv6=0" \ + my-ipvlan-net my-container +``` + +Use the literal string `IFNAME` in the sysctl name. Docker replaces it with +the name of the container's interface on this network. `disable_ipv6` is a +per-interface sysctl, so it must be set with the `endpoint.sysctls` +driver option rather than `docker run --sysctl`. For more details, see +[`docker network connect`](/reference/cli/docker/network/connect/#sysctl). + ### Dual stack IPv4 IPv6 IPvlan L3 mode Example: IPvlan L3 Mode Dual Stack IPv4/IPv6, Multi-Subnet w/ 802.1Q VLAN Tag:118 @@ -644,3 +668,4 @@ $ ip link del foo As with all of the Libnetwork drivers, they can be mixed and matched, even as far as running 3rd party ecosystem drivers in parallel for maximum flexibility to the Docker user. + diff --git a/content/manuals/engine/network/drivers/macvlan.md b/content/manuals/engine/network/drivers/macvlan.md index 88279aec6b34..2a65e19fc3ee 100644 --- a/content/manuals/engine/network/drivers/macvlan.md +++ b/content/manuals/engine/network/drivers/macvlan.md @@ -3,7 +3,7 @@ title: Macvlan network driver description: All about using Macvlan to make your containers appear like physical machines on the network -keywords: network, macvlan, standalone +keywords: network, macvlan, standalone, ipv6, slaac aliases: - /config/containers/macvlan/ - /engine/userguide/networking/get-started-macvlan/ @@ -147,6 +147,30 @@ $ docker network create -d macvlan \ -o macvlan_mode=bridge macvlan216 ``` +### Use router-assigned IPv6 addresses + +The previous example assigns IPv6 addresses from a subnet managed by Docker's +IPAM. On a `macvlan` network, you can instead let containers receive IPv6 +addresses directly from a router on the parent network, using stateless +address autoconfiguration (SLAAC). + +When a `macvlan` network has no IPv6 subnet, Docker disables IPv6 on the +container's interface, so it can't accept the router advertisements that SLAAC +relies on. To re-enable IPv6 on the interface, set its `disable_ipv6` sysctl +to `0` when you connect the container to the network: + +```console +$ docker network connect \ + --driver-opt="com.docker.network.endpoint.sysctls=net.ipv6.conf.IFNAME.disable_ipv6=0" \ + my-macvlan-net my-container +``` + +Use the literal string `IFNAME` in the sysctl name. Docker replaces it with +the name of the container's interface on this network. `disable_ipv6` is a +per-interface sysctl, so it must be set with the `endpoint.sysctls` +driver option rather than `docker run --sysctl`. For more details, see +[`docker network connect`](/reference/cli/docker/network/connect/#sysctl). + ## Usage examples This section provides hands-on examples for working with macvlan networks, diff --git a/content/manuals/engine/network/drivers/overlay.md b/content/manuals/engine/network/drivers/overlay.md index f2a5179b130c..da5e72fd2b3c 100644 --- a/content/manuals/engine/network/drivers/overlay.md +++ b/content/manuals/engine/network/drivers/overlay.md @@ -7,6 +7,7 @@ aliases: - /engine/userguide/networking/overlay-security-model/ - /network/overlay/ - /network/drivers/overlay/ + - /network/network-tutorial-overlay/ - /engine/network/tutorials/overlay/ - /engine/userguide/networking/get-started-overlay/ --- @@ -40,7 +41,7 @@ participating hosts: | Ports | Description | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | `2377/tcp` | The default Swarm control plane port, is configurable with [`docker swarm join --listen-addr`](/reference/cli/docker/swarm/join/#listen-addr) | -| `4789/udp` | The default overlay traffic port, configurable with [`docker swarm init --data-path-addr`](/reference/cli/docker/swarm/init/#data-path-port) | +| `4789/udp` | The default overlay traffic port, configurable with [`docker swarm init --data-path-port`](/reference/cli/docker/swarm/init/#data-path-port) | | `7946/tcp`, `7946/udp` | Used for communication among nodes, not configurable | ## Create an overlay network diff --git a/content/manuals/engine/network/firewall-iptables.md b/content/manuals/engine/network/firewall-iptables.md index 87d63e9cbbd9..b66c653dcc82 100644 --- a/content/manuals/engine/network/firewall-iptables.md +++ b/content/manuals/engine/network/firewall-iptables.md @@ -53,6 +53,31 @@ additional rules to filter these packets, use the `DOCKER-USER` chain. Rules appended to the `FORWARD` chain will be processed after Docker's rules. +> [!NOTE] +> +> By default, remote hosts can only reach a container through a port published +> to one of the Docker host's addresses. Sending packets to the container's own +> IP address instead ("direct routed" access) is not allowed. +> +> These packets are dropped by a rule in the `raw` table's `PREROUTING` chain, +> which is processed before the `filter` table. So, they never reach the +> `DOCKER-USER` chain, and a rule in `DOCKER-USER` cannot allow them. +> +> Any packet that reaches the host's firewall rules already addressed to a +> container is treated this way. For example, a Kubernetes CNI plugin may +> translate a Service address to a container address before the packet reaches +> the host's `PREROUTING` rules. Docker cannot distinguish the result from a +> packet routed to the container by a remote host. Which host interface these +> packets arrive on depends on the plugin's data path — for an overlay network +> it is normally the tunnel device. +> +> To allow direct routed access to a container's *published* ports, use network +> option `com.docker.network.bridge.trusted_host_interfaces`, or daemon option +> `allow-direct-routing`. Unpublished ports are still protected. See +> [Direct routing to containers in bridge networks](./port-publishing.md#direct-routing-to-containers-in-bridge-networks). +> To allow direct routed access to all container ports, published or not, see +> [Gateway modes](./port-publishing.md#gateway-modes). + ### Match the original IP and ports for requests When packets arrive to the `DOCKER-USER` chain, they have already passed through diff --git a/content/manuals/engine/network/firewall-nftables.md b/content/manuals/engine/network/firewall-nftables.md index f868e6c95e75..b3440a1f23de 100644 --- a/content/manuals/engine/network/firewall-nftables.md +++ b/content/manuals/engine/network/firewall-nftables.md @@ -210,6 +210,33 @@ The firewall mark must be added before Docker's rules run. So if the mark is added in a chain with type `filter` and hook `forward`, it must have priority `filter - 1` or lower. +> [!NOTE] +> +> By default, remote hosts can only reach a container through a port published +> to one of the Docker host's addresses. Sending packets to the container's own +> IP address instead ("direct routed" access) is not allowed. +> +> These packets are dropped by a rule in the `raw-PREROUTING` chain of the +> `docker-bridges` tables. Because a drop is final, a rule in one of your own +> tables cannot allow them. And, because that chain runs at the `prerouting` +> hook, before Docker's `filter-FORWARD` rules, a firewall mark added with +> `--bridge-accept-fwmark` has no effect on it. +> +> Any packet that reaches the host's firewall rules already addressed to a +> container is treated this way. For example, a Kubernetes CNI plugin may +> translate a Service address to a container address before the packet reaches +> the host's pre-routing rules. Docker cannot distinguish the result from a +> packet routed to the container by a remote host. Which host interface these +> packets arrive on depends on the plugin's data path — for an overlay network +> it is normally the tunnel device. +> +> To allow direct routed access to a container's *published* ports, use network +> option `com.docker.network.bridge.trusted_host_interfaces`, or daemon option +> `allow-direct-routing`. Unpublished ports are still protected. See +> [Direct routing to containers in bridge networks](./port-publishing.md#direct-routing-to-containers-in-bridge-networks). +> To allow direct routed access to all container ports, published or not, see +> [Gateway modes](./port-publishing.md#gateway-modes). + #### Replacing `DOCKER-USER` with an nftables table Because nftables doesn't have pre-defined chains, to replace the `DOCKER-USER` diff --git a/content/manuals/engine/network/links.md b/content/manuals/engine/network/links.md index e7133009fdb3..e63123cdb3d1 100644 --- a/content/manuals/engine/network/links.md +++ b/content/manuals/engine/network/links.md @@ -11,13 +11,11 @@ aliases: > [!WARNING] > -> The `--link` flag is a legacy feature of Docker. It may eventually -be removed. Unless you absolutely need to continue using it, we recommend that you use -user-defined networks to facilitate communication between two containers instead of using -`--link`. One feature that user-defined networks do not support that you can do -with `--link` is sharing environment variables between containers. However, -you can use other mechanisms such as volumes to share environment variables -between containers in a more controlled way. +> Links on the default `bridge` network are deprecated and scheduled for removal +> in Docker Engine 30.0. Starting with Docker Engine 29.6, Docker emits a +> deprecation warning when you create a container with these links. Links on +> non-default networks remain supported. Use user-defined networks instead of +> the legacy `--link` flag whenever possible. > > See [Differences between user-defined bridges and the default bridge](drivers/bridge.md#differences-between-user-defined-bridges-and-the-default-bridge) > for some alternatives to using `--link`. @@ -38,6 +36,10 @@ detail on container linking in default `bridge` network. ## Connect using network port mapping +Publishing a port with `-p` or `-P` is not container linking. It exposes a +container port on the host. For the current reference, see +[Published ports](port-publishing.md). + Let's say you used this command to run a simple Python Flask application: ```console @@ -252,6 +254,14 @@ recipient container in two ways: ### Environment variables +> [!WARNING] +> +> Legacy-link environment variables were deprecated in Docker Engine 28.4, are +> disabled by default in Docker Engine 29.0, and are scheduled for removal in +> Docker Engine 30.0. In Docker Engine 29.x, set +> `DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1` in the `dockerd` process +> environment and restart the daemon to temporarily re-enable them. + Docker creates several environment variables when you link containers. Docker automatically creates environment variables in the target container based on the `--link` parameters. It also exposes all environment variables diff --git a/content/manuals/engine/network/packet-filtering-firewalls.md b/content/manuals/engine/network/packet-filtering-firewalls.md index dfeabeedf116..dc2aabb9e982 100644 --- a/content/manuals/engine/network/packet-filtering-firewalls.md +++ b/content/manuals/engine/network/packet-filtering-firewalls.md @@ -90,9 +90,9 @@ forwarding from `ANY` zone to the `docker` zone. ## Docker and ufw [Uncomplicated Firewall](https://launchpad.net/ufw) -(ufw) is a frontend that ships with Debian and Ubuntu, -and it lets you manage firewall rules. Docker and ufw use firewall rules in -ways that make them incompatible with each other. +(ufw) is a frontend that ships with Ubuntu, and it lets you manage firewall +rules. Docker and ufw use firewall rules in ways that make them incompatible +with each other. When you publish a container's ports using Docker, traffic to and from that container gets diverted before it goes through the ufw firewall settings. diff --git a/content/manuals/engine/release-notes/29.md b/content/manuals/engine/release-notes/29.md index bfe99fec3910..671144b9f973 100644 --- a/content/manuals/engine/release-notes/29.md +++ b/content/manuals/engine/release-notes/29.md @@ -22,6 +22,451 @@ For more information about: - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md). - Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/). +## 29.9.2 + +{{< release-date date="2026-10-20" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.9.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.9.2) +- [moby/moby, 29.9.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.9.2) + +### Security + +The Go runtime update addresses [CVE-2026-111943](https://go.dev/issue/82345) by rejecting certificate chains that include eight revoked eMudhra intermediate certificates. +Image pulls and pushes fail TLS certificate verification if a registry's certificate chain relies on one of the affected TLS intermediates. +Affected registries need a replacement certificate chain that does not use these intermediates. + +The blocked intermediates are: + +- Domain-validated TLS: `EM DV TLS CA - G3B` and `EM DV TLS CA - G3C` +- Organization-validated TLS: `EM OV TLS CA - G3B` and `EM OV TLS CA - G3C` +- Extended-validation TLS: `EM EV TLS CA - G3B` and `EM EV TLS CA - G3C` +- Code signing: `EM OV CS CA - G3B` and `EM OV CS CA - G3C` + +The G3B intermediates belong to eMudhra BV, and the G3C intermediates belong to eMudhra Inc. +The keys for these intermediates were compromised. + +### Packaging updates + +- Update Go runtime to [1.26.10](https://go.dev/doc/devel/release#go1.26.10). [moby/moby#53989](https://github.com/moby/moby/pull/53989), [docker/cli#7418](https://github.com/docker/cli/pull/7418) + +## 29.9.1 + +{{< release-date date="2026-10-14" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.9.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.9.1) +- [moby/moby, 29.9.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.9.1) + +### Security + +The containerd update to v2.4.2 includes fixes for the following security vulnerabilities: + +- [CVE-2026-95839](https://github.com/containerd/containerd/security/advisories/GHSA-vwhp-8p66-mq4f): Pulling or importing an image through containerd's transfer service could crash containerd if a child descriptor contained the `io.containerd.manifest.subject` annotation and a malformed digest. +- [GHSA-8647-2jxj-p2rc](https://github.com/containerd/containerd/security/advisories/GHSA-8647-2jxj-p2rc): An untrusted registry returning a crafted `Content-Length` header could crash containerd when parallel layer fetching was enabled with `concurrent_layer_fetch_buffer`. +- [GHSA-hc94-p972-ch66](https://github.com/containerd/containerd/security/advisories/GHSA-hc94-p972-ch66): Pulling a crafted image or pulling from a malicious registry could exhaust host disk space because containerd did not limit incoming layer data to the declared size before validation. + +### Bug fixes and enhancements + +- Fix `--link-local-ip` accepting addresses that are not link-local (169.254.0.0/16 or fe80::/10) when creating a container or connecting it to a network, which made the container fail to start. [moby/moby#53923](https://github.com/moby/moby/pull/53923) +- Fix `COPY --from` in the classic builder failing for files not owned by root when userns-remap is enabled. [moby/moby#53859](https://github.com/moby/moby/pull/53859) +- Fix `docker ps -s` and container listing with sizes failing entirely when the size of one container cannot be computed. [moby/moby#53921](https://github.com/moby/moby/pull/53921) +- Fix `docker save` leaving image layers on disk after the image is removed, when the image contains the same layer more than once (graph-driver image store). [moby/moby#53927](https://github.com/moby/moby/pull/53927) +- Fix a daemon panic when using the `fluentd` log driver with a TLS address that cannot be connected to and `fluentd-async` enabled. [moby/moby#53922](https://github.com/moby/moby/pull/53922) +- Fix image digest resolution failing when a registry mirror succeeds but a subsequent registry lookup fails. [moby/moby#53933](https://github.com/moby/moby/pull/53933) +- Fix plugin privilege lookup reporting success when fetching the plugin fails. [moby/moby#53934](https://github.com/moby/moby/pull/53934) + +### Packaging updates + +- Update containerd (static binaries) to [v2.4.2](https://github.com/containerd/containerd/releases/tag/v2.4.2). [moby/moby#53936](https://github.com/moby/moby/pull/53936) + +### Networking + +- Don't add bridge network interfaces to firewalld's `docker` zone when `iptables` and `ip6tables` are both disabled. [moby/moby#53907](https://github.com/moby/moby/pull/53907) +- Fix bridge networks failing to restore on daemon startup when their bridge is bound to a firewalld zone other than `docker`. [moby/moby#53907](https://github.com/moby/moby/pull/53907) + +### Rootless + +- Fix `--domainname` with user namespaces and rootless mode; this requires an OCI runtime supporting the `domainname` field (such as runc >= v1.2.0). [moby/moby#53899](https://github.com/moby/moby/pull/53899) +- Update RootlessKit to [v3.3.0](https://github.com/rootless-containers/rootlesskit/releases/tag/v3.3.0). [moby/moby#53942](https://github.com/moby/moby/pull/53942) + +## 29.9.0 + +{{< release-date date="2026-10-08" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.9.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.9.0) +- [moby/moby, 29.9.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.9.0) + +### Security + +The Go runtime update fixes the following security vulnerabilities in Docker Engine: + +- **CVE-2026-97032**: An HTTP/2 client could crash the daemon by changing the HPACK header table size while sending requests. [golang/go#81867](https://go.dev/issue/81867) +- **CVE-2026-78659**: An HTTP/2 client could exhaust daemon memory by declaring a large number of fields in a `Trailer` header, bypassing the header size limits. [golang/go#81857](https://go.dev/issue/81857) +- **CVE-2026-78663**: An HTTP/2 client could bypass the connection-level flow control limit by resetting streams, making the daemon buffer more request data than the limit allows. [golang/go#81743](https://go.dev/issue/81743) +- **CVE-2026-78669**: An HTTP/2 client could cause excessive daemon CPU use by opening many streams and repeatedly changing the initial window size. [golang/go#81742](https://go.dev/issue/81742) +- **CVE-2026-56857**: On Windows, the daemon could create a directory outside its data root if someone with write access to the data root had placed a junction there. [golang/go#81739](https://go.dev/issue/81739) + +The `golang.org/x/net` update to v0.60.0 applies the same HTTP/2 fixes to the deprecated `/grpc` endpoint and to the gRPC server that BuildKit runs for frontend containers, such as images referenced by a `# syntax=` directive. + +### Bug fixes and enhancements + +- containerd image store: Add the `lazy-pull` daemon feature to control whether `docker pull` skips downloading layer content that the snapshotter already provides. Lazy pulls are enabled by default for known remote snapshotters (`nydus`, `overlaybd`, `soci`, `stargz`). [moby/moby#53877](https://github.com/moby/moby/pull/53877) +- containerd image store: Fix pulls skipping required layer blobs when unpacked layers already exist, leaving images runnable but incomplete for export or push. [moby/moby#53615](https://github.com/moby/moby/pull/53615) +- Fix `docker container create --name` reporting a misleading validation error mentioning invalid characters instead of invalid name length. [moby/moby#53484](https://github.com/moby/moby/pull/53484) +- Fix a connection leak to the RootlessKit API socket on every `GET /version` request in rootless mode. [moby/moby#53836](https://github.com/moby/moby/pull/53836) +- Improve Windows service registration and unregistration cleanup, including making service unregistration (`--unregister-service`) idempotent. [moby/moby#53845](https://github.com/moby/moby/pull/53845) + +### Packaging updates + +- Update BuildKit to [v0.34.0](https://github.com/moby/buildkit/releases/tag/v0.34.0). [moby/moby#53882](https://github.com/moby/moby/pull/53882) +- Update Go runtime to [1.26.9](https://go.dev/doc/devel/release#go1.26.9). [docker/cli#7363](https://github.com/docker/cli/pull/7363) +- Update containerd (static binaries) to [v2.4.1](https://github.com/containerd/containerd/releases/tag/v2.4.1). [moby/moby#53773](https://github.com/moby/moby/pull/53773) + +### Networking + +- Allow IPv6 Neighbour Discovery between containers on a bridge network with inter-container communication disabled, matching the existing IPv4 behaviour. [moby/moby#53723](https://github.com/moby/moby/pull/53723) +- Fix `docker ps` and `GET /containers/json` omitting published ports for networks using routed gateway mode. [moby/moby#53693](https://github.com/moby/moby/pull/53693) +- Fix a bug where a restarted daemon could be dropped from a peer's service discovery and load balancing until it rejoined the gossip cluster. [moby/moby#53688](https://github.com/moby/moby/pull/53688) +- Fix a published port being unreachable from another container on the same network when inter-container communication is disabled, including Swarm services published through the routing mesh. [moby/moby#53723](https://github.com/moby/moby/pull/53723) +- Fix an issue where errors programming the kernel to encrypt the overlay network data-plane could in some circumstances lead to encrypted-overlay-network traffic to some nodes being transmitted in cleartext. As the receiving peer would drop cleartext packets for encrypted overlay networks as spoofed, the loss of confidentiality is limited to unidirectional flows (e.g. UDP DNS queries) and handshake attempts that never proceed (e.g. TCP SYN). [moby/moby#53420](https://github.com/moby/moby/pull/53420) +- Fix connecting live-restored containers with an implicit `host-gateway` mapping to additional networks. [moby/moby#53093](https://github.com/moby/moby/pull/53093) +- Fix overlay peers becoming unreachable after a node rejoins the cluster or a service is redeployed, when the VXLAN device had already learned a dynamic FDB entry for the peer. [moby/moby#53663](https://github.com/moby/moby/pull/53663) +- Fix Swarm tasks on overlay networks being rejected when the daemon can't write to `/var/lib/docker`. [moby/moby#53848](https://github.com/moby/moby/pull/53848) +- Published Swarm-service ports are accessible at the host's IPv6 addresses when the userland proxy is enabled. A change introduced in v29.8.0 incidentally enabled this functionality; it is a tested and supported feature as of v29.9.0. [moby/moby#53727](https://github.com/moby/moby/pull/53727) +- Release a node's IPsec security associations and policies when the last container leaves an encrypted overlay network, instead of leaking them until the daemon restarts. [moby/moby#53420](https://github.com/moby/moby/pull/53420) +- Restore the logic to remove the empty `DOCKER-INGRESS` iptables chain, and the `FORWARD` rule that jumps to it, left behind by Docker Engine 28.0.0 and earlier. [moby/moby#53825](https://github.com/moby/moby/pull/53825) + +### Rootless + +- Update RootlessKit (3.2.0). [moby/moby#53607](https://github.com/moby/moby/pull/53607) + +## 29.8.2 + +{{< release-date date="2026-09-30" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.8.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.8.2) +- [moby/moby, 29.8.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.8.2) + +### Security + +This release fixes the following security vulnerabilities in Docker Engine: + +- **CVE-2026-53493**: Pulling a crafted OCI image index with deeply nested or widely fanned-out descriptors could cause unbounded CPU and memory use. [GHSA-pg57-6jwg-q645](https://github.com/containerd/containerd/security/advisories/GHSA-pg57-6jwg-q645) +- **CVE-2026-92543**: A malicious DNS response could make registry connections skip TLS certificate verification or fall back to HTTP, exposing registry credentials or allowing image substitution. [GHSA-7cfq-22r6-qp73](https://github.com/moby/moby/security/advisories/GHSA-7cfq-22r6-qp73) +- **CVE-2026-92542**: Unprivileged users on a Swarm node could inject forged Ethernet frames into encrypted overlay networks on peer nodes. [GHSA-6m9p-4h64-m6vh](https://github.com/moby/moby/security/advisories/GHSA-6m9p-4h64-m6vh) + +The BuildKit update fixes the following security vulnerabilities: + +- **CVE-2026-93315**: A build step could redirect proxy CA cleanup outside the build root filesystem, block it with a special file, or let the build succeed when cleanup failed. [GHSA-2f5p-x9ph-g97x](https://github.com/moby/buildkit/security/advisories/GHSA-2f5p-x9ph-g97x) +- **CVE-2026-93316**: A build that requested CDI devices could cause a daemon panic when CDI support was disabled, for example with `"features": {"cdi": false}` in `daemon.json`. [GHSA-r456-g3gm-cvxf](https://github.com/moby/buildkit/security/advisories/GHSA-r456-g3gm-cvxf) +- **CVE-2026-93317**: With the containerd image store, a client using the low-level LLB API could poison the build cache with container blob contents that did not match their claimed digest. [GHSA-p3rc-w3hc-pqvv](https://github.com/moby/buildkit/security/advisories/GHSA-p3rc-w3hc-pqvv) +- **CVE-2026-93318**: A malicious image could poison the build cache with layer DiffIDs that did not match the actual layer contents. [GHSA-f2v9-hprr-32q3](https://github.com/moby/buildkit/security/advisories/GHSA-f2v9-hprr-32q3) +- **CVE-2026-93319**: A malicious external frontend could crash the daemon through gateway container lifecycle races or malformed requests and definitions. [GHSA-4hgw-qrhw-fhg8](https://github.com/moby/buildkit/security/advisories/GHSA-4hgw-qrhw-fhg8) +- **CVE-2026-93320**: Daemon-side snapshot reads and LLB `mkfile` operations did not safely handle special files. [GHSA-9728-qjrv-2xh2](https://github.com/moby/buildkit/security/advisories/GHSA-9728-qjrv-2xh2) +- **CVE-2026-93321**: A malformed LLB file operation with invalid symlink owner inputs could crash the daemon. [GHSA-fjj4-h6vf-m9hj](https://github.com/moby/buildkit/security/advisories/GHSA-fjj4-h6vf-m9hj) +- **CVE-2026-93322**: A malformed LLB merge operation with mismatched input counts could crash the daemon. [GHSA-cv6p-7w7g-xjwq](https://github.com/moby/buildkit/security/advisories/GHSA-cv6p-7w7g-xjwq) +- **CVE-2026-93323**: An oversized Dockerfile, `.dockerignore`, gateway file, or nested LLB definition could exhaust daemon memory. [GHSA-mgqf-486f-49vp](https://github.com/moby/buildkit/security/advisories/GHSA-mgqf-486f-49vp) +- **CVE-2026-93326**: A crafted Git build source could bypass source policy rules that match on the repository URL, through a Git bundle locator or a full remote URL that did not match the source identifier. [GHSA-66hf-6vf5-87hc](https://github.com/moby/buildkit/security/advisories/GHSA-66hf-6vf5-87hc) + +### Bug fixes and enhancements + +- Fix `docker cp` failing on a container with a bind-mounted socket nested inside another bind mount. [moby/moby#53724](https://github.com/moby/moby/pull/53724) +- Fix `docker info` failing with an “invalid Prefix” error after reloading a daemon with custom default address pools. [moby/moby#53812](https://github.com/moby/moby/pull/53812) + +### Packaging updates + +- Update BuildKit to [v0.33.1](https://github.com/moby/buildkit/releases/tag/v0.33.1). [moby/moby#53823](https://github.com/moby/moby/pull/53823) +- Update containerd (static binaries) to [v2.3.6](https://github.com/containerd/containerd/releases/tag/v2.3.6). [moby/moby#53778](https://github.com/moby/moby/pull/53778) +- Update runc (in static binaries) to [v1.5.2](https://github.com/opencontainers/runc/releases/tag/v1.5.2). [moby/moby#53811](https://github.com/moby/moby/pull/53811) + +## 29.8.1 + +{{< release-date date="2026-09-15" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.8.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.8.1) +- [moby/moby, 29.8.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.8.1) + +### Bug fixes and enhancements + +- containerd image store: Fix `docker load` leaving dangling images after loading an image that already exists. [moby/moby#53595](https://github.com/moby/moby/pull/53595) +- Fix managed containerd logging a CRI pod-sandbox plugin dependency warning during startup. [moby/moby#53585](https://github.com/moby/moby/pull/53585) +- Fix user-namespace detection on OpenVZ, where namespace inode numbers are virtualized. [moby/moby#53605](https://github.com/moby/moby/pull/53605) +- Windows: Preserve hard links when committing a container, so a file with multiple names is stored once in the resulting image layer instead of once per name. [moby/moby#53624](https://github.com/moby/moby/pull/53624) + +### Packaging updates + +- Update containerd (static binaries) to [v2.3.5](https://github.com/containerd/containerd/releases/tag/v2.3.5). [moby/moby#53589](https://github.com/moby/moby/pull/53589) + +### Networking + +- Fix `GET /networks` returning a 500 status if an invalid 'type' filter was provided. [moby/moby#53678](https://github.com/moby/moby/pull/53678) + +## 29.8.0 + +{{< release-date date="2026-09-03" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.8.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.8.0) +- [moby/moby, 29.8.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.8.0) + +### New + +- Add `HostConfig.Umask` option and a corresponding `--umask <octal>` flag to `docker create`/`docker run` to set the umask for a container's main process, execs, and healthchecks. [moby/moby#53463](https://github.com/moby/moby/pull/53463), [docker/cli#7108](https://github.com/docker/cli/pull/7108) +- Add support for attaching service names, environments, and custom CloudWatch entity attributes to logs from the `awslogs` logging driver. [moby/moby#52632](https://github.com/moby/moby/pull/52632) + +### Security + +- Add daemon support for configuring the default container AppArmor profile template. [moby/moby#52771](https://github.com/moby/moby/pull/52771) + - See https://docker.docker.com/engine/security/apparmor/#customize-the-default-profile +- Prevent containers from using the 32-bit `socketcall(2)` path to create `AF_VSOCK` sockets and communicate with host virtual machines by adding AppArmor and SELinux policy rules. [moby/moby#53551](https://github.com/moby/moby/pull/53551) + +### Networking + +- Fix `docker network inspect` failing to find a healthy Swarm network when another Swarm network could not be allocated. [moby/moby#53325](https://github.com/moby/moby/pull/53325) +- Fix a node gossiping a superseded value for a Swarm service discovery entry after concurrent updates to the same key. [moby/moby#53479](https://github.com/moby/moby/pull/53479) +- Fix Swarm service names failing to resolve on a node indefinitely after it misses a network membership announcement. [moby/moby#53437](https://github.com/moby/moby/pull/53437) +- Fix Swarm service names failing to resolve on healthy nodes after a transient node failure. [moby/moby#53142](https://github.com/moby/moby/pull/53142) +- Prevent dockerd from hanging when the nft command produces enough stderr output to fill its pipe. [moby/moby#53517](https://github.com/moby/moby/pull/53517) +- Reduce gossip traffic generated by a node that repeatedly disconnects and rejoins the cluster. [moby/moby#53479](https://github.com/moby/moby/pull/53479) +- Remote network-driver plugins can now set the container-side interface name via the `DstName` field in their `Join` response. [moby/moby#52866](https://github.com/moby/moby/pull/52866) +- Reserve network names "container" and "container:" to prevent creation of unusable networks. [moby/moby#51973](https://github.com/moby/moby/pull/51973) +- Spread the daemon's periodic Swarm overlay network gossip and synchronization work over time, avoiding recurring bursts of CPU and network usage. [moby/moby#53475](https://github.com/moby/moby/pull/53475) +- Swarm service-mesh published ports now use the same infrastructure as published ports for local containers. [moby/moby#53118](https://github.com/moby/moby/pull/53118) + +### Rootless + +- Fix `--disable-host-loopback` not being enforced for the `pasta` network driver in rootless mode. [moby/moby#53358](https://github.com/moby/moby/pull/53358) +- Update RootlessKit to v3.1.0, adding support for the `pesto` port driver in rootless mode. Set `DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=pesto` to use it; it requires the `pasta` network driver and supports IPv4 only. [moby/moby#53358](https://github.com/moby/moby/pull/53358) + +### Go SDK + +- Update minimum supported Go version to 1.26. [docker/cli#7258](https://github.com/docker/cli/pull/7258) +### Bug fixes and enhancements + +- Add `annotation` filter to container listings (`docker ps`, `GET /containers/json`) allowing to filter containers by their annotations. [moby/moby#53538](https://github.com/moby/moby/pull/53538) +- containerd image store: Fix `docker image inspect` reporting a smaller image size than `docker image ls`. [moby/moby#53426](https://github.com/moby/moby/pull/53426) +- containerd image store: Fix slower image pulls caused by repeated registry authentication within a single pull. [moby/moby#53497](https://github.com/moby/moby/pull/53497) +- Do not log expected image signature identity misses as errors for containerd image store images. [moby/moby#53495](https://github.com/moby/moby/pull/53495) +- dockerd now uses the embedded containerd if no system containerd service is configured and containerd is not installed. [moby/moby#53388](https://github.com/moby/moby/pull/53388) +- Fix `GET /images/{name}/json` not including unpacked snapshot usage in `Size` when using the containerd image store. [moby/moby#53426](https://github.com/moby/moby/pull/53426) +- Fix classic-builder cache for Dockerfile stages that select a non-host platform with `FROM --platform`. [moby/moby#53503](https://github.com/moby/moby/pull/53503) +- Fix CLI panic when `DOCKER_HOST` or `-H` specifies an invalid host. [docker/cli#7280](https://github.com/docker/cli/pull/7280) +- Fix health checks being delayed for too long when the start interval is longer than the start period. [moby/moby#52317](https://github.com/moby/moby/pull/52317) +- Fix inconsistent mount ordering in `docker inspect` output (`GET /containers/{id}/json`) and container listings (`docker ps`, `GET /containers/json`). [moby/moby#53534](https://github.com/moby/moby/pull/53534) +- Fix NRI container metadata so `Container.Args` includes the resolved executable as `argv[0]`, matching the process launched in the container instead of only the Docker `Cmd`. [moby/moby#53423](https://github.com/moby/moby/pull/53423) +- Fix Swarm service creation failing when an automatically generated name is already in use. [moby/moby#53468](https://github.com/moby/moby/pull/53468) +- Fix the container root directory `/` being world-writable when using the `btrfs` storage driver. [moby/moby#53500](https://github.com/moby/moby/pull/53500) +- Fixed `docker ps` sorting published ports lexicographically instead of numerically. [docker/cli#7144](https://github.com/docker/cli/pull/7144) +- Preserve service mount order during forced updates to avoid an unnecessary rollout on the next stack deploy. [docker/cli#7227](https://github.com/docker/cli/pull/7227) +- Prevent containerd's v2 CRI plugins from loading when CRI is disabled. [moby/moby#53564](https://github.com/moby/moby/pull/53564) +- Print plugin hook output (e.g. the "What's next:" hint) after the command's error message instead of before it. [docker/cli#6976](https://github.com/docker/cli/pull/6976) +- Reject checkpoint IDs containing path separators to prevent access outside the container checkpoint directory. [moby/moby#53377](https://github.com/moby/moby/pull/53377) + +### Packaging updates + +- Update BuildKit to [v0.33.0](https://github.com/moby/buildkit/releases/tag/v0.33.0). [moby/moby#53554](https://github.com/moby/moby/pull/53554) +- Update containerd (static binaries) to [v2.3.4](https://github.com/containerd/containerd/releases/tag/v2.3.4). [moby/moby#53409](https://github.com/moby/moby/pull/53409) +- Update Go runtime to [1.26.8](https://go.dev/doc/devel/release#go1.26.8). [moby/moby#53550](https://github.com/moby/moby/pull/53550), [docker/cli#7274](https://github.com/docker/cli/pull/7274) +- Update runc (in static binaries) to [v1.5.1](https://github.com/opencontainers/runc/releases/tag/v1.5.1). [moby/moby#52306](https://github.com/moby/moby/pull/52306) + +## 29.7.2 + +{{< release-date date="2026-08-05" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.7.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.7.2) +- [moby/moby, 29.7.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.7.2) + +### Bug fixes and enhancements + +- Fix `docker service create` and `docker service update` panicking when the same environment variable is passed more than once. [docker/cli#7145](https://github.com/docker/cli/pull/7145) +- Fix a regression introduced in Docker Engine 29.7.0 that caused image pulls to reject images containing absolute hardlink targets, as produced by some image builders. [moby/moby#53305](https://github.com/moby/moby/pull/53305) +- Fix a regression introduced in Docker Engine 29.7.0 that could cause image pulls and `docker cp` to fail on older Linux kernels when applying file permissions, including for device nodes. [moby/moby#53305](https://github.com/moby/moby/pull/53305) + +### Packaging updates + +- Update BuildKit to [v0.32.2](https://github.com/moby/buildkit/releases/tag/v0.32.2). [moby/moby#53300](https://github.com/moby/moby/pull/53300) + +### Networking + +- Improve compatibility with more nftables releases by terminating base-chain policies with a semicolon. [moby/moby#53303](https://github.com/moby/moby/pull/53303) + +## 29.7.1 + +{{< release-date date="2026-07-31" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.7.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.7.1) +- [moby/moby, 29.7.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.7.1) + +### Bug fixes and enhancements + +- Fix a regression that prevented pulling images whose layers contain directories without explicit parent directory entries. [moby/moby#53260](https://github.com/moby/moby/pull/53260) +- Fix a regression where the `CopyToContainer` rejects container paths that traverse absolute symlinks, such as `/var/run` -> `/run`. [moby/moby#53261](https://github.com/moby/moby/pull/53261) + +## 29.7.0 + +{{< release-date date="2026-07-30" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.7.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.7.0) +- [moby/moby, 29.7.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.7.0) + +### New + +- Add an experimental `embedded-containerd` feature that runs containerd inside the daemon process instead of as a separate managed process. [moby/moby#52898](https://github.com/moby/moby/pull/52898) +- Mount type `image` is no longer experimental. [moby/moby#52998](https://github.com/moby/moby/pull/52998) +- Add the `default-stop-timeout` daemon option to configure the stop timeout assigned to containers without an explicit timeout. [moby/moby#53146](https://github.com/moby/moby/pull/53146) + +### Security + +This release includes a fix for a security vulnerability affecting Docker Engine and related components. + +- Update github.com/moby/go-archive to v0.3.0 to fix [CVE-2026-17106](https://www.cve.org/CVERecord?id=CVE-2026-17106) / [GHSA-hfg8-hc9c-6c3h](https://github.com/moby/go-archive/security/advisories/GHSA-hfg8-hc9c-6c3h). [moby/moby#53247](https://github.com/moby/moby/pull/53247), [docker/cli#7139](https://github.com/docker/cli/pull/7139) + +### Networking + +- Fix a daemon panic when cleanup of a container's network interface fails while the container is being disconnected from a network. [moby/moby#53237](https://github.com/moby/moby/pull/53237) +- Fix a daemon panic when removing swarm ingress ports after failing to bind an ingress proxy listener. [moby/moby#53022](https://github.com/moby/moby/pull/53022) + +### Rootless + +- Keep the cgroup mount for containers with `--net=host`. [moby/moby#52318](https://github.com/moby/moby/pull/52318) + +### Bug fixes and enhancements + + +- Add shell completion for `--filter` names and known values to `docker service ls`, `docker service ps`, and `docker node ps`. [docker/cli#7124](https://github.com/docker/cli/pull/7124) +- containerd image store: Fix daemon-wide concurrent download and upload limits for pulls and pushes not being honored. [moby/moby#53081](https://github.com/moby/moby/pull/53081) + - To preserve the previous unlimited startup behavior, configure "max-concurrent-downloads" and "max-concurrent-uploads" to 0 +- Fix `docker cp -a` using the wrong file owner when copying files into containers with user namespace remapping enabled. [moby/moby#53084](https://github.com/moby/moby/pull/53084) +- Fix `docker cp` from a Windows container silently returning a file instead of an error when the source path ends with a separator but is not a directory. [moby/moby#53123](https://github.com/moby/moby/pull/53123) +- Fix `docker stats` reporting all zeros for running Windows containers when using the containerd runtime. [moby/moby#53101](https://github.com/moby/moby/pull/53101) +- Fix `docker stats` reporting empty network stats for running Windows containers when using the containerd runtime. [moby/moby#53219](https://github.com/moby/moby/pull/53219) +- Fix a typo in the `docker create --pull` flag description. [docker/cli#7103](https://github.com/docker/cli/pull/7103) +- Fix Swarm service updates failing due to "file exists" errors when a VIP IP alias already exists on the LB endpoint interface. [moby/moby#51657](https://github.com/moby/moby/pull/51657) +- Fix Swarm tasks being rejected when their image could not be pulled from the registry but was already present on the node. [moby/moby#53212](https://github.com/moby/moby/pull/53212) +- Improve the error returned when a container hostname exceeds Linux's 64-byte limit. [moby/moby#53121](https://github.com/moby/moby/pull/53121) +- Prevent live-restored volumes from retaining active mount references when containers exit during daemon startup. [moby/moby#53115](https://github.com/moby/moby/pull/53115) +- Suppress the “No such container” error when `docker rm --force` succeeds for a nonexistent container. [docker/cli#7110](https://github.com/docker/cli/pull/7110) + +### Packaging updates + +- Update Go runtime to [1.26.5](https://go.dev/doc/devel/release#go1.26.5). [docker/cli#7087](https://github.com/docker/cli/pull/7087) +- Update BuildKit to [v0.32.0](https://github.com/moby/buildkit/releases/tag/v0.32.0). [moby/moby#53234](https://github.com/moby/moby/pull/53234) +- Update containerd (static binaries) to [v2.3.3](https://github.com/containerd/containerd/releases/tag/v2.3.3). [moby/moby#53050](https://github.com/moby/moby/pull/53050) +- Update runc (in static binaries) to [v1.4.3](https://github.com/opencontainers/runc/releases/tag/v1.4.3). [moby/moby#50960](https://github.com/moby/moby/pull/50960) + +## 29.6.2 + +{{< release-date date="2026-07-16" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.6.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.6.2) +- [moby/moby, 29.6.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.6.2) + +### Security + +This release includes fixes for multiple security vulnerabilities affecting Docker Engine. + +- **CVE-2026-15793**: Git source checkout from a bundle file could lead to command injection. [GHSA-hw3h-2gp9-cxpv](https://github.com/moby/buildkit/security/advisories/GHSA-hw3h-2gp9-cxpv) +- **CVE-2026-15792**: Incorrect parameters sent from a frontend could cause a panic. [GHSA-qx3x-mv6r-52p6](https://github.com/moby/buildkit/security/advisories/GHSA-qx3x-mv6r-52p6) +- **CVE-2026-15791**: An LLB file operation could be tricked into removing the contents of the `/tmp` directory. [GHSA-32pv-7hq5-qhwq](https://github.com/moby/buildkit/security/advisories/GHSA-32pv-7hq5-qhwq) +- **CVE-2026-15789**: A malicious client could bypass destination directory validation when uploading local sources. [GHSA-g2h8-426c-7976](https://github.com/moby/buildkit/security/advisories/GHSA-g2h8-426c-7976) +- **CVE-2026-15788**: A WCOW cache mount source selector could resolve NTFS junctions outside of the cache root. [GHSA-388v-wmr2-g2v2](https://github.com/moby/buildkit/security/advisories/GHSA-388v-wmr2-g2v2) + +### Packaging updates + +- Update containerd (static binaries) to [v2.2.6](https://github.com/containerd/containerd/releases/tag/v2.2.6). [moby/moby#53051](https://github.com/moby/moby/pull/53051) +- Update Go runtime to [1.26.5](https://go.dev/doc/devel/release#go1.26.5). [moby/moby#53027](https://github.com/moby/moby/pull/53027) + +### Rootless + +- Update RootlessKit to [v3.0.2](https://github.com/rootless-containers/rootlesskit/releases/tag/v3.0.2). [moby/moby#53054](https://github.com/moby/moby/pull/53054) + +## 29.6.1 + +{{< release-date date="2026-06-26" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.6.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.6.1) +- [moby/moby, 29.6.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.6.1) + +### Security + +This release includes fixes for multiple security vulnerabilities affecting Docker Engine. + +- A malicious image could supply a malicious `/etc/passwd` or `/etc/group`-style file causing excessive memory consumption, potentially resulting in process termination due to Out Of Memory (OOM) conditions. [GHSA-mjcv-p78q-w5fw](https://github.com/moby/sys/security/advisories/GHSA-mjcv-p78q-w5fw), [GHSA-jpcc-p29g-p8mq](https://github.com/containerd/containerd/security/advisories/GHSA-jpcc-p29g-p8mq), [GHSA-72x6-4j93-7w86](https://github.com/moby/buildkit/security/advisories/GHSA-72x6-4j93-7w86) +- A custom frontend could send a crafted build request that disabled Seccomp and AppArmor protections for the build container, even if the user did not explicitly allow the security.insecure entitlement. Other security measures, like Linux capabilities were still applied to these containers. [GHSA-7236-3392-c5c6](https://github.com/moby/buildkit/security/advisories/GHSA-7236-3392-c5c6) + +### Bug fixes and enhancements + +- Update containerd (static binaries) to [v2.2.5](https://github.com/containerd/containerd/releases/tag/v2.2.5). [moby/moby#52950](https://github.com/moby/moby/pull/52950) + +### Packaging updates + +- Update BuildKit to [v0.31.1](https://github.com/moby/buildkit/releases/tag/v0.31.1). [moby/moby#52954](https://github.com/moby/moby/pull/52954) + +## 29.6.0 + +{{< release-date date="2026-06-18" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 29.6.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.6.0) +- [moby/moby, 29.6.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.6.0) + +### New + +- `POST /containers/{id}/update` now supports per-device blkio resource settingss. [moby/moby#52651](https://github.com/moby/moby/pull/52651) +- Add `GET /images/{name}/attestations` endpoint to retrieve in-toto attestation statements (such as SLSA provenance and SPDX SBOM) attached to an image. Supports optional platform selection, predicate type filtering, and a statement query parameter for verbatim statement bodies. + +### Bug fixes and enhancements + +- `docker image push` now respects `NO_COLOR`. [docker/cli#6957](https://github.com/docker/cli/pull/6957) +- containerd image store: Fix `docker system prune` to include unpacked image data when reporting reclaimed space. [moby/moby#52905](https://github.com/moby/moby/pull/52905) +- Fix `docker system df` image size reporting to count only snapshots directly used by images. [moby/moby#52901](https://github.com/moby/moby/pull/52901) +- Fix a bug where registry authentication failures during worker image pulls were reported as a misleading “No such image” error. [moby/moby#52698](https://github.com/moby/moby/pull/52698) +- Fix default BuildKit GC policy to prune reproducible cache types as intended. [moby/moby#52814](https://github.com/moby/moby/pull/52814) +- Fix explicit file modes being filtered by the daemon umask, including `COPY --chmod` permissions. [moby/moby#52892](https://github.com/moby/moby/pull/52892) +- Fix image selection with the containerd image store on amd64 hosts when images provide amd64 variant-specific manifests. [moby/moby#52773](https://github.com/moby/moby/pull/52773) +- The `--password` flag on `docker login` now accepts `-` to pass the password through STDIN as alternative to `--password-stdin`. [docker/cli#7029](https://github.com/docker/cli/pull/7029) + +### Packaging updates + +- Update runc (in static binaries) to [v1.3.6](https://github.com/opencontainers/runc/releases/tag/v1.3.6). [moby/moby#52883](https://github.com/moby/moby/pull/52883) +- Update BuildKit to [v0.31.0](https://github.com/moby/buildkit/releases/tag/v0.31.0). [moby/moby#52904](https://github.com/moby/moby/pull/52904) + +### Networking + +- Allow the nftables firewall mode to be used with a daemon that is linked against libnftables when the `nft` command is not installed on the system. [moby/moby#52820](https://github.com/moby/moby/pull/52820) +- Don't publish container ports on host ports listed in `net.ipv4.ip_local_reserved_ports` when dynamically allocating ports. [moby/moby#52818](https://github.com/moby/moby/pull/52818) +- Fix a race condition in overlay network bulk sync that caused ~30s DNS resolution delays on newly joined swarm nodes. [moby/moby#52862](https://github.com/moby/moby/pull/52862) +- Mitigate a crash in libnftables when using nftables as the firewall backend by changing the default build option to execute the `nft` command instead. Users building dockerd from source can opt into linking against libnftables by building with the `libnftables` build tag. [moby/moby#52886](https://github.com/moby/moby/pull/52886) + +### Rootless + +- Silence the spurious warning "IPv4 forwarding is disabled". [moby/moby#52742](https://github.com/moby/moby/pull/52742) + +### Deprecations + +- The Engine now returns a deprecation warning when a container connected to the default bridge is created with links specified. [moby/moby#47427](https://github.com/moby/moby/pull/47427) + ## 29.5.3 {{< release-date date="2026-06-03" >}} diff --git a/content/manuals/engine/security/apparmor.md b/content/manuals/engine/security/apparmor.md index 8b6b1e0433dd..52573c092171 100644 --- a/content/manuals/engine/security/apparmor.md +++ b/content/manuals/engine/security/apparmor.md @@ -38,6 +38,89 @@ explicitly specifies the default policy: $ docker run --rm -it --security-opt apparmor=docker-default hello-world ``` +## Customize the default profile + +Starting with Docker Engine 29.8, you can configure the daemon to generate the +`docker-default` profile from a custom template. +This changes the policy for containers that use `docker-default`. +Privileged containers without an explicit AppArmor profile use `unconfined`, +and containers configured with another profile continue to use that setting. + +The template uses Go [text/template](https://pkg.go.dev/text/template) syntax. +Docker renders and loads it when the daemon starts. +Use the built-in +[`baseTemplate`](https://github.com/moby/profiles/blob/main/apparmor/template.go) +as a starting point because it includes the rules and template substitutions +required for compatibility across supported hosts. + +> [!CAUTION] +> +> A custom template can reduce container isolation. Review and test every +> change to the built-in policy. + +### Create a template + +Copy the contents between the `baseTemplate` backticks and save them as +`/etc/docker/apparmor/docker-default`. +The template isn't a complete AppArmor profile until Docker renders it. +Store the file outside the AppArmor profile directory (`/etc/apparmor.d`) +because the host AppArmor service can try to parse the template before Docker +renders it. + +Modify the policy rules as needed. Docker provides the following template data: + +- `.Abi`: `abi/3.0` when the host provides that AppArmor ABI, or an empty string +- `.Name`: the profile name, `docker-default` +- `.DaemonProfile`: the daemon's AppArmor profile, or `unconfined` +- `.Imports`: host-specific declarations and includes for the global scope +- `.InnerImports`: host-specific includes for the profile scope + +Keep the `.Abi`, `.Name`, `.Imports`, and `.InnerImports` substitutions from the +built-in template. +Use `.DaemonProfile` in rules that permit signals from the daemon. + +### Configure the daemon + +Set `apparmor-profile` to the template path in the daemon configuration: + +```json {title="/etc/docker/daemon.json"} +{ + "apparmor-profile": "/etc/apparmor.d/containers/my-custom-docker-profile.tpl" +} +``` + +You can instead pass the path with the +`dockerd --apparmor-profile=/etc/apparmor.d/containers/my-custom-docker-profile.tpl` flag. +Don't configure the option both as a flag and in `daemon.json`. + +### Restart and verify + +Restart the Docker daemon: + +```console +$ sudo systemctl restart docker +``` + +Check the daemon logs for errors while loading the rendered profile: + +```console +$ sudo journalctl -u docker.service --since "5 minutes ago" --no-pager +``` + +Confirm that the logs for the restart don't contain +`Failed to load default apparmor profile`. +If `apparmor_parser` rejects the rendered profile, the daemon continues running +and keeps the previously loaded `docker-default` profile. + +Confirm that the daemon is configured to use the template path: + +```console +$ docker info --format '{{json .SecurityOptions}}' +``` + +The output includes +`name=apparmor,profile=/etc/apparmor.d/containers/my-custom-docker-profile.tpl`. + ## Load and unload profiles To load a new profile into AppArmor for use with containers: diff --git a/content/manuals/engine/security/certificates.md b/content/manuals/engine/security/certificates.md index c55596f37738..43bc434d0c5e 100644 --- a/content/manuals/engine/security/certificates.md +++ b/content/manuals/engine/security/certificates.md @@ -21,10 +21,26 @@ for the registry and how to set the client TLS certificate for verification. ## Understand the configuration -A custom certificate is configured by creating a directory under -`/etc/docker/certs.d` using the same name as the registry's hostname, such as +A custom certificate is configured by creating a directory under the daemon's +certificate root using the same name as the registry's hostname, such as `localhost`. All `*.crt` files are added to this directory as CA roots. +Where that certificate root lives depends on the platform: + +- Native Linux Engine: `/etc/docker/certs.d/` +- Rootless Linux: `$XDG_CONFIG_HOME/docker/certs.d` (defaults to + `~/.config/docker/certs.d`), not `/etc/docker/certs.d` +- Native Windows Engine (Windows containers): + `%PROGRAMDATA%\docker\certs.d` (normally `C:\ProgramData\docker\certs.d`). + If the registry address includes a port, strip the colon from the directory + name because Windows filenames cannot contain `:`. For example, + `registry.example.com:5000` becomes `registry.example.com5000`. +- Docker Desktop with Linux containers: put client certificates in + `~/.docker/certs.d` on the host. Docker Desktop copies them into the VM; + don't configure `/etc/docker/certs.d` inside the VM yourself. Trusted CAs + can also come from the host certificate store (on Windows, the Windows + certificate store). + > [!NOTE] > > On Linux any root certificates authorities are merged with the system defaults, diff --git a/content/manuals/engine/security/protect-access.md b/content/manuals/engine/security/protect-access.md index c4066f3259ec..42b2bae0f7ce 100644 --- a/content/manuals/engine/security/protect-access.md +++ b/content/manuals/engine/security/protect-access.md @@ -67,7 +67,7 @@ $ docker info ### SSH Tips For the best user experience with SSH, configure `~/.ssh/config` as follows to allow -reusing a SSH connection for multiple invocations of the `docker` CLI: +reusing an SSH connection for multiple invocations of the `docker` CLI: ```text ControlMaster auto diff --git a/content/manuals/engine/security/rootless/tips.md b/content/manuals/engine/security/rootless/tips.md index d0f810e9d932..82eef156c4aa 100644 --- a/content/manuals/engine/security/rootless/tips.md +++ b/content/manuals/engine/security/rootless/tips.md @@ -152,15 +152,23 @@ $ cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup memory pids ``` -To allow delegation of all controllers, you need to change the systemd configuration as follows: +To allow delegation of all controllers, change the systemd configuration: ```console -# mkdir -p /etc/systemd/system/user@.service.d -# cat > /etc/systemd/system/user@.service.d/delegate.conf << EOF +$ sudo mkdir -p /etc/systemd/system/user@.service.d +``` + +Create `/etc/systemd/system/user@.service.d/delegate.conf`: + +```ini [Service] Delegate=cpu cpuset io memory pids -EOF -# systemctl daemon-reload +``` + +Then reload systemd: + +```console +$ sudo systemctl daemon-reload ``` > [!NOTE] diff --git a/content/manuals/engine/security/rootless/troubleshoot.md b/content/manuals/engine/security/rootless/troubleshoot.md index 4121847437c4..a683f71e6369 100644 --- a/content/manuals/engine/security/rootless/troubleshoot.md +++ b/content/manuals/engine/security/rootless/troubleshoot.md @@ -77,15 +77,23 @@ weight: 30 - Exposing SCTP ports - To use the `ping` command, see [Routing ping packets](./tips.md#routing-ping-packets). - To expose privileged TCP/UDP ports (< 1024), see [Exposing privileged ports](./tips.md#exposing-privileged-ports). +- `IPAddress` shown in `docker inspect` is namespaced inside RootlessKit's network namespace. + This means the IP address is not reachable from the host without `nsenter`-ing into the network namespace. +- Port forwarding with `docker run -p` does not propagate source IP addresses by default. + See [`docker run -p` does not propagate source IP addresses](#docker-run--p-does-not-propagate-source-ip-addresses) to enable source IP propagation. - NFS mounts as the docker "data-root" is not supported. This limitation is not specific to rootless mode. +- Capabilities added with `--cap-add` apply only to resources governed by the + container's user namespace. They don't grant privileges over host or other + global resources. As a result, operations that require capabilities in the + [initial user namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) + can still fail. ### Historical limitations #### Until Docker Engine v29.5 -- `IPAddress` shown in `docker inspect` is namespaced inside RootlessKit's network namespace. - This means the IP address is not reachable from the host without `nsenter`-ing into the network namespace. -- Host network (`docker run --net=host`) is also namespaced inside RootlessKit. +- Host network (`docker run --net=host`) was namespaced inside RootlessKit. + This meant that ports listened by containers with `--net=host` were not reachable from the real host network namespace. ## Troubleshooting @@ -236,6 +244,7 @@ the configurations supported by RootlessKit, and how they compare: | `gvisor-tap-vsock`| `gvisor-tap-vsock`| Slow | Slow | ❌ | ✅ | Not recommended. Use `builtin` port driver instead. | | `slirp4netns` | `slirp4netns` | Slow | Slow | ✅ | ✅ | | | `pasta` | `implicit` | Slow | Fast ✅ | ✅ | ✅ | Experimental; Needs pasta version 2023_12_04 or later | +| `pasta` | `pesto` | — | — | — | — | IPv4 only; needs Docker Engine 29.8+ | | `lxc-user-nic` | `builtin` | Fast ✅ | Fast ✅ | ✅ (*) | ❌ | Experimental | | `bypass4netns` | `bypass4netns` | Fast ✅ | Fast ✅ | ✅ | ✅ | **Note:** Not integrated to RootlessKit as it needs a custom seccomp profile | @@ -280,8 +289,8 @@ For details, see [Routing ping packets](./tips.md#routing-ping-packets). #### `IPAddress` shown in `docker inspect` is unreachable -This was an expected behavior until Docker Engine v29.5, as the daemon was namespaced inside RootlessKit's -network namespace. Use `docker run -p` instead, or upgrade to Docker Engine v29.5 or later. +This is an expected behavior, as the daemon is namespaced inside RootlessKit's +network namespace. Use `docker run -p` instead. #### `--net=host` doesn't listen ports on the host network namespace diff --git a/content/manuals/engine/security/seccomp.md b/content/manuals/engine/security/seccomp.md index 82a2cb65568f..ba8beb667685 100644 --- a/content/manuals/engine/security/seccomp.md +++ b/content/manuals/engine/security/seccomp.md @@ -48,6 +48,11 @@ $ docker run --rm \ hello-world ``` +The Docker CLI resolves a relative profile path from the working directory +where you invoke `docker`. The CLI reads the profile and sends its contents to +the daemon, so the profile must be available on the client host when the client +and daemon run on separate hosts. + ### Significant syscalls blocked by the default profile Docker's default seccomp profile is an allowlist which specifies the calls that @@ -98,8 +103,7 @@ the reason each syscall is blocked rather than white-listed. | `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | | `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | | `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `socket` | Blocked for `AF_ALG` to prevent in-container privilege escalation via the kernel cryptographic API ([CVE-2026-31431](https://nvd.nist.gov/vuln/detail/CVE-2026-31431)). Also blocked for `AF_VSOCK`. See [moby/moby#52494](https://github.com/moby/moby/pull/52494). | -| `socketcall` | Denied to prevent bypassing socket address family filters on architectures with the legacy `socketcall` multiplexer (i386, s390, MIPS o32). See [moby/moby#52494](https://github.com/moby/moby/pull/52494). | +| `socket` | Blocked for `AF_ALG` to prevent in-container privilege escalation via the kernel cryptographic API ([CVE-2026-31431](https://nvd.nist.gov/vuln/detail/CVE-2026-31431)). Also blocked for `AF_VSOCK`. Seccomp argument filtering doesn't cover `socketcall(2)`. The default AppArmor profile and SELinux policy module deny both address families through `socket(2)` and `socketcall(2)`. See [moby/moby#52494](https://github.com/moby/moby/pull/52494) and [moby/moby#53551](https://github.com/moby/moby/pull/53551). | | `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | | `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | | `sysfs` | Obsolete syscall. | @@ -113,6 +117,15 @@ the reason each syscall is blocked rather than white-listed. | `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | | `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +> [!IMPORTANT] +> +> The SELinux rule that blocks `AF_VSOCK` requires SELinux userspace 3.6 or +> later, the `container-selinux` policy, and SELinux enabled for the Docker +> daemon. RHEL 8 ships an older SELinux userspace, so its standard packages +> can't apply this rule. On affected hosts, use AppArmor or a custom seccomp +> profile that denies `socketcall`. Denying `socketcall` can break networking +> for 32-bit programs that use it. + ## Run without the default seccomp profile You can pass `unconfined` to run a container without the default seccomp diff --git a/content/manuals/engine/security/trust/_index.md b/content/manuals/engine/security/trust/_index.md index 4da95e33d9f3..62f79a91f00c 100644 --- a/content/manuals/engine/security/trust/_index.md +++ b/content/manuals/engine/security/trust/_index.md @@ -35,15 +35,11 @@ ensure that the images they pull are signed. Publishers could be individuals or organizations manually signing their content or automated software supply chains signing content as part of their release process. -> [!NOTE] -> -> Docker is retiring DCT for Docker Official Images -> (DOI). You should start planning to transition to a different image signing -> and verification solution (like [Sigstore](https://www.sigstore.dev/) or -> [Notation](https://github.com/notaryproject/notation#readme)). Timelines for the -> complete deprecation of DCT are being finalized and will be published soon. +> [!WARNING] > -> For more information, see [Retiring Docker Content Trust](https://www.docker.com/blog/retiring-docker-content-trust/). +> Docker Content Trust (DCT) is being retired. The Notary v1 service at +> `notary.docker.io` will shut down on December 8, 2026. For more information, see +> [Docker Content Trust (DCT)](/manuals/retired.md#docker-content-trust-dct). ### Image tags and DCT diff --git a/content/manuals/engine/security/trust/deploying_notary.md b/content/manuals/engine/security/trust/deploying_notary.md index 21de96527a71..4a24c04b84a1 100644 --- a/content/manuals/engine/security/trust/deploying_notary.md +++ b/content/manuals/engine/security/trust/deploying_notary.md @@ -27,6 +27,7 @@ for [Notary](https://github.com/docker/notary#using-notary) depending on which o ## If you want to use Notary in production -Check back here for instructions after Notary Server has an official -stable release. To get a head start on deploying Notary in production, see -[the Notary repository](https://github.com/theupdateframework/notary). +The Compose sample on this page is for local testing and uses sample +certificates. For a production deployment, follow the upstream +[instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) +and the rest of [the Notary repository](https://github.com/theupdateframework/notary). diff --git a/content/manuals/engine/security/trust/images/tag_signing.png b/content/manuals/engine/security/trust/images/tag_signing.png index 4dfdfb6709c7..52fa2952452d 100644 Binary files a/content/manuals/engine/security/trust/images/tag_signing.png and b/content/manuals/engine/security/trust/images/tag_signing.png differ diff --git a/content/manuals/engine/security/trust/images/trust_components.png b/content/manuals/engine/security/trust/images/trust_components.png index cf3913308f5f..4e7b90254f6e 100644 Binary files a/content/manuals/engine/security/trust/images/trust_components.png and b/content/manuals/engine/security/trust/images/trust_components.png differ diff --git a/content/manuals/engine/security/trust/images/trust_view.png b/content/manuals/engine/security/trust/images/trust_view.png index ea431ebfd964..f7eb7537eede 100644 Binary files a/content/manuals/engine/security/trust/images/trust_view.png and b/content/manuals/engine/security/trust/images/trust_view.png differ diff --git a/content/manuals/engine/security/trust/trust_sandbox.md b/content/manuals/engine/security/trust/trust_sandbox.md index 5da8d9323599..290a7e7e8bdc 100644 --- a/content/manuals/engine/security/trust/trust_sandbox.md +++ b/content/manuals/engine/security/trust/trust_sandbox.md @@ -19,11 +19,11 @@ These instructions assume you are running in Linux or macOS. You can run this sandbox on a local machine or on a virtual machine. You need to have privileges to run docker commands on your local machine or in the VM. -This sandbox requires you to install two Docker tools: Docker Engine >= 1.10.0 -and Docker Compose >= 1.6.0. To install the Docker Engine, choose from the -[list of supported platforms](../../install/_index.md). To install -Docker Compose, see the -[detailed instructions here](/manuals/compose/install/_index.md). +This sandbox requires a current Docker Engine and Docker Compose install. To +install Docker Engine, choose from the +[list of supported platforms](../../install/_index.md). To install Docker +Compose, see the +[Compose install instructions](/manuals/compose/install/_index.md). ## What is in the sandbox? diff --git a/content/manuals/engine/storage/_index.md b/content/manuals/engine/storage/_index.md index d1ed0a9ee8b4..f6c63bfb5ac2 100644 --- a/content/manuals/engine/storage/_index.md +++ b/content/manuals/engine/storage/_index.md @@ -42,6 +42,7 @@ of the writable layer of the container: - [Volume mounts](#volume-mounts) - [Bind mounts](#bind-mounts) - [tmpfs mounts](#tmpfs-mounts) +- [Image mounts](#image-mounts) - [Named pipes](#named-pipes) No matter which type of mount you choose to use, the data looks the same from @@ -85,6 +86,18 @@ such as caching intermediate data, handling sensitive information like credentials, or reducing disk I/O. Use tmpfs mounts only when the data does not need to persist beyond the current container session. +### Image mounts + +An image mount makes the contents of another image available inside a container +at a path you choose. The mounted image is read-only and isn't part of the +container's own image, so you can bring in tools or assets from one image +without rebuilding another. + +Use image mounts when you need to consume files packaged as an image, such as +mounting a tool-rich image to debug a minimal container, or sharing read-only +assets across containers running different images. Image mounts require the +[containerd image store](containerd.md). + ### Named pipes [Named pipes](https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes) @@ -99,6 +112,7 @@ Learn more about container data persistence: - [Volumes](./volumes.md) - [Bind mounts](./bind-mounts.md) - [tmpfs mounts](./tmpfs.md) +- [Image mounts](./image-mounts.md) Learn more about daemon storage backends: diff --git a/content/manuals/engine/storage/bind-mounts.md b/content/manuals/engine/storage/bind-mounts.md index f55e2bb8314d..e32c87137ad7 100644 --- a/content/manuals/engine/storage/bind-mounts.md +++ b/content/manuals/engine/storage/bind-mounts.md @@ -86,7 +86,9 @@ flag is more explicit and supports all the available options. If you use `--volume` to bind-mount a file or directory that does not yet exist on the Docker host, Docker automatically creates the directory on the -host for you. It's always created as a directory. +host for you. It's always created as a directory. If the Docker daemon doesn't +have permission to create the source directory, create it before starting the +container. By default, `--mount` does not automatically create a directory if the specified mount path does not exist on the host. Instead, it produces an error: @@ -115,8 +117,8 @@ $ docker run --mount type=bind,src=<host-path>,dst=<container-path>[,<key>=<valu Valid options for `--mount type=bind` include: -| Option | Description | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Option | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source`, `src` | The location of the file or directory on the host. This can be an absolute or relative path. | | `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. Must be an absolute path. | | `readonly`, `ro` | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount). | @@ -486,4 +488,5 @@ and - Learn about [volumes](./volumes.md). - Learn about [tmpfs mounts](./tmpfs.md). +- Learn about [image mounts](./image-mounts.md). - Learn about [storage drivers](/engine/storage/drivers/). diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md index 64bacd22b080..526cd108ccfd 100644 --- a/content/manuals/engine/storage/containerd.md +++ b/content/manuals/engine/storage/containerd.md @@ -113,6 +113,48 @@ Docker Engine uses the `overlayfs` containerd snapshotter by default. > image store, push them to a registry first, or use `docker save` to export > them. +## Lazy pulling + +With lazy pulling, containers can start before their images are fully downloaded. +Remote snapshotters fetch layer data from the registry as containers need it. + +Docker Engine enables lazy pulling by default when configured to use the `nydus`, `overlaybd`, `soci`, or `stargz` snapshotter. +With other snapshotters, including the default `overlayfs`, Docker downloads all layer content before the container starts unless you explicitly enable lazy pulling. + +During a lazy pull, Docker skips downloading a layer if the snapshotter can mount it remotely or already has its snapshot. +Docker downloads all other layers. +For example, the stargz snapshotter can mount eStargz layers remotely, but plain gzip layers must be downloaded unless their snapshots already exist. + +### Saving and pushing images + +Lazily pulled images can run even if some layer content is missing from the containerd content store. +However, missing content affects saving and pushing: + +- `docker save` can fail or produce an incomplete archive without reporting an error. +- `docker push` cannot upload missing layers, but can reuse them if the target registry supports mounting them from the source repository. + +Running the image is not guaranteed to fill in the missing content in the containerd content store. +For example, the stargz snapshotter keeps the data it fetches in its own cache. +See [moby#53878](https://github.com/moby/moby/issues/53878) for details. + +### Configuration + +To disable lazy-pulling, set the `lazy-pull` feature to `false` in `/etc/docker/daemon.json`: + +```json +{ + "features": { + "containerd-snapshotter": true, + "lazy-pull": false + } +} +``` + +Reload the daemon configuration to apply the setting to subsequent pulls. +For images you already pulled lazily, pull them again to download the missing content. + +To enable lazy pulling for a snapshotter outside the default list, set `lazy-pull` to `true` instead. + ## Experimental automatic migration Docker Engine includes an experimental feature that can automatically switch to @@ -138,7 +180,8 @@ To enable automatic migration, add the `containerd-migration` feature to your You can also set the `DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD` environment variable to make the daemon switch automatically if you have no containers and -your image count is at or below the threshold. For systemd: +the total size of all image layers is at or below the threshold. The value is a +human-readable size (for example, `200M` or `1G`). For systemd: ```console $ sudo systemctl edit docker.service @@ -148,11 +191,12 @@ Add: ```ini [Service] -Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=5" +Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=200M" ``` -If you have no running or stopped containers and 5 or fewer images, the daemon -switches to the containerd image store on restart. Your overlay2 data remains +If you have no running or stopped containers and the total size of all image +layers is 200M or less, the daemon switches to the containerd image store on +restart. Your overlay2 data remains on disk but becomes hidden. ## Additional resources diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md index 9c407581d09c..627ee6202eb1 100644 --- a/content/manuals/engine/storage/drivers/_index.md +++ b/content/manuals/engine/storage/drivers/_index.md @@ -19,7 +19,7 @@ aliases: > won't reflect how your system stores images. For operational guidance, see > [containerd image store](../containerd.md). -To use storage drivers effectively, it's important to know how Docker builds and +To use storage drivers effectively, you need to know how Docker builds and stores images, and how these images are used by containers. You can use this information to make informed choices about the best way to persist data from your applications and avoid performance problems along the way. diff --git a/content/manuals/engine/storage/drivers/aufs-driver.md b/content/manuals/engine/storage/drivers/aufs-driver.md index b966b5530ab5..2761989cb90d 100644 --- a/content/manuals/engine/storage/drivers/aufs-driver.md +++ b/content/manuals/engine/storage/drivers/aufs-driver.md @@ -1,6 +1,6 @@ --- description: Learn how to optimize your use of AUFS driver. -keywords: 'container, storage, driver, AUFS ' +keywords: "container, storage, driver, AUFS " title: AUFS storage driver sitemap: false aliases: @@ -14,7 +14,7 @@ aliases: > before upgrading to Docker Engine v24.0. Read the [Docker storage drivers](select-storage-driver.md) > page for supported storage drivers. -AUFS is a *union filesystem*. The `aufs` storage driver was previously the default +AUFS is a _union filesystem_. The `aufs` storage driver was previously the default storage driver used for managing images and layers on Docker for Ubuntu, and for Debian versions prior to Stretch. If your Linux kernel is version 4.0 or higher, and you use Docker Engine - Community, consider using the newer @@ -26,7 +26,7 @@ potential performance advantages over the `aufs` storage driver. - For Docker Engine - Community, AUFS is supported on Ubuntu, and on Debian versions prior to Stretch. - If you use Ubuntu, you need to add the AUFS module to the kernel. If you do - not install these packages, you need to use `overlay2`. + not install these packages, you need to use `overlay2`. - AUFS cannot use the following backing filesystems: `aufs`, `btrfs`, or `ecryptfs`. This means that the filesystem which contains `/var/lib/docker/aufs` cannot be one of these filesystem types. @@ -66,7 +66,7 @@ storage driver is configured, Docker uses it by default. ## How the `aufs` storage driver works -AUFS is a *union filesystem*, which means that it layers multiple directories on +AUFS is a _union filesystem_, which means that it layers multiple directories on a single Linux host and presents them as a single directory. These directories are called _branches_ in AUFS terminology, and _layers_ in Docker terminology. @@ -74,7 +74,7 @@ The unification process is referred to as a _union mount_. The diagram below shows a Docker container based on the `ubuntu:latest` image. -![Layers of an Ubuntu container](images/aufs_layers.webp) +![Layers of an Ubuntu container](images/aufs_layers.webp) Each image layer, and the container layer, are represented on the Docker host as subdirectories within `/var/lib/docker/`. The union mount provides the unified @@ -126,7 +126,7 @@ If a container is running, the contents of `/var/lib/docker/aufs/` change in the following ways: - `diff/`: Differences introduced in the writable container layer, such as new - or modified files. + or modified files. - `layers/`: Metadata about the writable container layer's parent layers. - `mnt/`: A mount point for each running container's unified filesystem, exactly as it appears from within the container. @@ -160,7 +160,7 @@ Consider some scenarios where files in a container are modified. - **Writing to a file for the first time**: The first time a container writes to an existing file, that file does not exist in the container (`upperdir`). - The `aufs` driver performs a *copy_up* operation to copy the file from the + The `aufs` driver performs a _copy_up_ operation to copy the file from the image layer where it exists to the writable container layer. The container then writes the changes to the new copy of the file in the container layer. @@ -169,13 +169,12 @@ Consider some scenarios where files in a container are modified. very large and only a small part of it is being modified. This can have a noticeable impact on container write performance. AUFS can suffer noticeable latencies when searching for files in images with many layers. - However, it is worth noting that the copy_up operation only occurs the first - time a given file is written to. Subsequent writes to the same file operate - against the copy of the file already copied up to the container. + However, the copy_up operation only occurs the first time a given file is + written to. Subsequent writes to the same file operate against the copy of + the file already copied up to the container. - **Deleting files and directories**: - - - When a _file_ is deleted within a container, a *whiteout* file is created + - When a _file_ is deleted within a container, a _whiteout_ file is created in the container layer. The version of the file in the image layer is not deleted (because the image layers are read-only). However, the whiteout file prevents it from being available to the container. diff --git a/content/manuals/engine/storage/drivers/btrfs-driver.md b/content/manuals/engine/storage/drivers/btrfs-driver.md index ecfa3179ea34..3450d16b267d 100644 --- a/content/manuals/engine/storage/drivers/btrfs-driver.md +++ b/content/manuals/engine/storage/drivers/btrfs-driver.md @@ -36,7 +36,7 @@ Btrfs Filesystem as Btrfs. `btrfs` is supported if you meet the following prerequisites: -- `btrfs` is only recommended with Docker CE on Ubuntu or Debian systems. +- `btrfs` is only recommended with Docker Engine on Ubuntu or Debian systems. - Changing the storage driver makes any containers you have already created inaccessible on the local system. Use `docker save` to save containers, @@ -274,7 +274,7 @@ storage driver. > Many of these factors are mitigated by using Docker volumes for write-heavy > workloads, rather than relying on storing data in the container's writable > layer. However, in the case of Btrfs, Docker volumes still suffer from these -> draw-backs unless `/var/lib/docker/volumes/` isn't backed by Btrfs. +> drawbacks if `/var/lib/docker/volumes/` is backed by Btrfs. ### Page caching diff --git a/content/manuals/engine/storage/drivers/overlayfs-driver.md b/content/manuals/engine/storage/drivers/overlayfs-driver.md index cdec2f68258f..ea5ce6126549 100644 --- a/content/manuals/engine/storage/drivers/overlayfs-driver.md +++ b/content/manuals/engine/storage/drivers/overlayfs-driver.md @@ -12,11 +12,9 @@ This page refers to the Linux kernel driver as `OverlayFS` and to the Docker storage driver as `overlay2`. > [!NOTE] -> Docker Engine 29.0 and later uses the -> [containerd image store](/manuals/engine/storage/containerd.md) by default. -> The `overlay2` driver is a legacy storage driver that is superseded by the -> `overlayfs` containerd snapshotter. For more information, see -> [Select a storage driver](/manuals/engine/storage/drivers/select-storage-driver.md). +> This page covers the classic `overlay2` storage driver. For the `overlayfs` +> snapshotter used by the containerd image store, see +> [containerd image store](/manuals/engine/storage/containerd.md). > [!NOTE] > For `fuse-overlayfs` driver, check [Rootless mode documentation](/manuals/engine/security/rootless.md). diff --git a/content/manuals/engine/storage/drivers/windowsfilter-driver.md b/content/manuals/engine/storage/drivers/windowsfilter-driver.md index a38f6d865d52..289b53cee01f 100644 --- a/content/manuals/engine/storage/drivers/windowsfilter-driver.md +++ b/content/manuals/engine/storage/drivers/windowsfilter-driver.md @@ -4,18 +4,18 @@ keywords: container, storage, driver, windows, windowsfilter title: windowsfilter storage driver --- -The windowsfilter storage driver is the default storage driver for Docker -Engine on Windows. The windowsfilter driver uses Windows-native file system -layers to for storing Docker layers and volume data on disk. The windowsfilter +The `windowsfilter` storage driver is the default storage driver for Docker +Engine on Windows. The `windowsfilter` driver uses Windows-native file system +layers to store Docker layers and volume data on disk. The `windowsfilter` storage driver only works on file systems formatted with NTFS. -## Configure the windowsfilter storage driver +## Configure the `windowsfilter` storage driver -For most use case, no configuring the windowsfilter storage driver is not +For most use cases, no configuration of the `windowsfilter` storage driver is necessary. -The default storage limit for Docker Engine on Windows is 127GB. To use a -different storage size, set the `size` option for the windowsfilter storage +The default storage limit for Docker Engine on Windows is 127 GB. To use a +different storage size, set the `size` option for the `windowsfilter` storage driver. See [windowsfilter options](/reference/cli/dockerd.md#windowsfilter-options). Data is stored on the Docker host in `image` and `windowsfilter` subdirectories diff --git a/content/manuals/engine/storage/image-mounts.md b/content/manuals/engine/storage/image-mounts.md new file mode 100644 index 000000000000..0d616670ff60 --- /dev/null +++ b/content/manuals/engine/storage/image-mounts.md @@ -0,0 +1,208 @@ +--- +description: Using image mounts +title: Image mounts +weight: 40 +keywords: storage, mounts, image mounts, image mount +--- + +[Volumes](volumes.md), [bind mounts](bind-mounts.md), and [tmpfs mounts](tmpfs.md) +all give a container a place to read and write data. An image mount is +different: instead of mounting a directory or a memory-backed filesystem, it +mounts the contents of another image into the container. + +When you use an image mount, the filesystem of a second image is mounted into +the container at a path you choose. The container can read the files from that +image alongside its own filesystem, without those files being part of the +container's own image. This is useful when you want to bring the tools or assets +from one image into a container that's running a different image. + +Image mounts are read-only. The mounted image is never modified, and the +container can't write to the mount. + +> [!NOTE] +> Image mounts require the [containerd image store](containerd.md). + +## When to use image mounts + +Image mounts are appropriate for the following types of use case: + +- Debugging a minimal or hardened image that doesn't include a shell or common + utilities. You can mount a tool-rich image, such as `busybox`, into the + running container's namespace and run those tools without changing the + original image. For a worked example, see + [Debug with Docker Hardened Images](/manuals/dhi/how-to/troubleshoot.md). + +- Sharing read-only assets, such as datasets, models, or static content, that + are distributed as an image and consumed by containers running a different + image. + +- Keeping application images small by packaging optional tooling in a separate + image and mounting it only when needed. + +## Mounting over existing data + +If you mount an image into a directory in the container in which files or +directories exist, the pre-existing files are obscured by the mount. This is +similar to if you were to save files into `/mnt` on a Linux host, and then +mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by the +contents of the USB drive until the USB drive was unmounted. + +With containers, there's no straightforward way of removing a mount to reveal +the obscured files again. Your best option is to recreate the container without +the mount. + +## Considerations and constraints + +- Image mounts are always read-only. The container can't modify the mounted + image, and changes aren't persisted anywhere. + +- The source image must already exist in the daemon's image store. Docker + doesn't pull the source image automatically when you create the mount. If the + image isn't present, the command fails: + + ```console + $ docker run --mount type=image,source=busybox:musl,destination=/dbg alpine + docker: Error response from daemon: No such image: busybox:musl + ``` + + Pull the image first with `docker pull`, then create the mount. + +- Image mounts require the [containerd image store](containerd.md). They aren't + available when the daemon uses the classic storage drivers. + +- You can only create an image mount with the `--mount` flag. There is no + `--volume` (`-v`) equivalent. + +- Running an executable from a mounted image requires a compatible runtime in + the container. A dynamically linked binary only runs if the container provides + a matching dynamic linker and shared libraries. For example, a glibc-based + binary fails in a musl-based image such as Alpine. Statically linked binaries, + or mounting only data from an image, avoid this constraint. + +## Syntax + +To mount an image with the `docker run` command, use the `--mount` flag with +`type=image`. + +```console +$ docker run --mount type=image,src=<image-reference>,dst=<container-path> +``` + +The `--mount` flag consists of multiple key-value pairs, separated by commas and +each consisting of a `<key>=<value>` tuple. The order of the keys isn't +significant. + +```console +$ docker run --mount type=image,src=<image-reference>,dst=<container-path>[,<key>=<value>...] +``` + +### Options for --mount + +Valid options for `--mount type=image` include: + +| Option | Description | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `source`, `src` | The reference of the image to mount, for example `busybox` or `busybox:musl`. The image must exist locally. | +| `destination`, `dst`, `target` | The path where the image is mounted in the container. Must be an absolute path. | +| `image-subpath` | Path inside the source image to mount instead of the image root. See [Mount a subpath of an image](#mount-a-subpath-of-an-image). | + +```console {title="Example"} +$ docker run --mount type=image,src=busybox,dst=/dbg,image-subpath=bin +``` + +## Use an image mount in a container + +The following example runs an Alpine container and mounts the `busybox:musl` +image at `/dbg`. Pull the source image first, since Docker doesn't pull it for +you when creating the mount. This example uses the musl-based BusyBox image so +its binaries are compatible with the musl-based Alpine container. + +```console +$ docker pull busybox:musl +$ docker run -d \ + -it \ + --name imgtest \ + --mount type=image,source=busybox:musl,destination=/dbg \ + alpine:latest +``` + +The container can now read the BusyBox tools from `/dbg` while running the Alpine +image: + +```console +$ docker exec imgtest /dbg/bin/echo "hello from busybox" +hello from busybox +``` + +Verify that the mount is an `image` mount by looking in the `Mounts` section of +the `docker inspect` output: + +```console +$ docker inspect imgtest --format '{{ json .Mounts }}' +[{"Type":"image","Name":"busybox:musl","Source":"/var/lib/docker/rootfs/overlayfs/...","Destination":"/dbg","Mode":"","RW":false,"Propagation":"rprivate"}] +``` + +This shows that the mount is an `image` mount, that its source is the +`busybox:musl` image, and that it's read-only (`"RW":false`). + +Stop and remove the container: + +```console +$ docker container rm -fv imgtest +``` + +## Mount a subpath of an image + +Use the `image-subpath` option to mount a specific directory from the source +image instead of its root. For example, to mount only the `bin` directory of the +`busybox` image at `/tools`: + +```console +$ docker run -d \ + -it \ + --name imgtest \ + --mount type=image,source=busybox,destination=/tools,image-subpath=bin \ + alpine:latest +``` + +The container sees the contents of the image's `bin` directory at `/tools`. + +## Use an image mount with Docker Compose + +A single Docker Compose service with an image mount looks like this: + +```yaml +services: + app: + image: alpine:latest + volumes: + - type: image + source: busybox + target: /dbg +``` + +To mount a subpath of the image, use the `subpath` option under `image`: + +```yaml +services: + app: + image: alpine:latest + volumes: + - type: image + source: busybox + target: /tools + image: + subpath: bin +``` + +The `image.subpath` option is available in Docker Compose version 2.35.0 and +later. For more information about using mounts of the `image` type with Compose, +see the +[Compose reference on the volume attribute](/reference/compose-file/services.md#volumes). + +## Next steps + +- Learn about [volumes](./volumes.md). +- Learn about [bind mounts](./bind-mounts.md). +- Learn about [tmpfs mounts](./tmpfs.md). +- Learn about [storage drivers](/engine/storage/drivers/). diff --git a/content/manuals/engine/storage/tmpfs.md b/content/manuals/engine/storage/tmpfs.md index 29473ada2bad..b942b417706d 100644 --- a/content/manuals/engine/storage/tmpfs.md +++ b/content/manuals/engine/storage/tmpfs.md @@ -20,6 +20,13 @@ As opposed to volumes and bind mounts, a tmpfs mount is temporary, and only persisted in the host memory. When the container stops, the tmpfs mount is removed, and files written there won't be persisted. +Because tmpfs stores data in memory, that usage counts against the container's +memory cgroup limit (`--memory` / Compose `mem_limit`). Setting a large +`tmpfs-size` (or host-mounted tmpfs) does not give the container extra RAM +outside that limit — filling the mount can still OOM the container. Memory +metrics for the container include tmpfs usage; see +[runtime metrics](/manuals/engine/containers/runmetrics.md). + tmpfs mounts are best used for cases when you do not want the data to persist either on the host machine or within the container. This may be for security reasons or to protect the performance of the container when your application @@ -47,6 +54,8 @@ the mount. - Unlike volumes and bind mounts, you can't share tmpfs mounts between containers. - This functionality is only available if you're running Docker on Linux. +- Data on a tmpfs mount counts toward the container memory limit. A large + `size=` value does not raise that limit. - Setting permissions on tmpfs may cause them to [reset after container restart](https://github.com/docker/for-linux/issues/138). In some cases [setting the uid/gid](https://github.com/docker/compose/issues/3425#issuecomment-423091370) can serve as a workaround. ## Syntax @@ -203,4 +212,5 @@ $ docker rm tmptest - Learn about [volumes](volumes.md) - Learn about [bind mounts](bind-mounts.md) +- Learn about [image mounts](image-mounts.md) - Learn about [storage drivers](/engine/storage/drivers/) diff --git a/content/manuals/engine/storage/volumes.md b/content/manuals/engine/storage/volumes.md index 3f5838d67030..1a7184c1ba92 100644 --- a/content/manuals/engine/storage/volumes.md +++ b/content/manuals/engine/storage/volumes.md @@ -403,9 +403,8 @@ $ docker volume rm nginx-vol ## Use a read-only volume -For some development applications, the container needs to write into the bind -mount so that changes are propagated back to the Docker host. At other times, -the container only needs read access to the data. Multiple +For some applications, the container needs to write to the volume. At other +times, the container only needs read access to the data. Multiple containers can mount the same volume. You can simultaneously mount a single volume as `read-write` for some containers and as `read-only` for others. @@ -809,5 +808,6 @@ $ docker volume prune - Learn about [bind mounts](bind-mounts.md). - Learn about [tmpfs mounts](tmpfs.md). +- Learn about [image mounts](image-mounts.md). - Learn about [storage drivers](/engine/storage/drivers/). - Learn about [third-party volume driver plugins](/engine/extend/legacy_plugins/). diff --git a/content/manuals/engine/swarm/configs.md b/content/manuals/engine/swarm/configs.md index 76502e97ef57..7c967ca630f7 100644 --- a/content/manuals/engine/swarm/configs.md +++ b/content/manuals/engine/swarm/configs.md @@ -244,7 +244,7 @@ This example assumes that you have PowerShell installed. <html lang="en"> <head><title>Hello Docker -

Hello Docker! You have deployed a HTML page.

+

Hello Docker! You have deployed an HTML page.

``` diff --git a/content/manuals/engine/swarm/how-swarm-mode-works/services.md b/content/manuals/engine/swarm/how-swarm-mode-works/services.md index 3536a2886794..9983832e6c63 100644 --- a/content/manuals/engine/swarm/how-swarm-mode-works/services.md +++ b/content/manuals/engine/swarm/how-swarm-mode-works/services.md @@ -32,7 +32,7 @@ For example, imagine you want to load balance between three instances of an HTTP listener. The diagram below shows an HTTP listener service with three replicas. Each of the three instances of the listener is a task in the swarm. -![ HTTP listener service with three replicas](../images/services-diagram.webp?w=550) +![HTTP listener service with three replicas](../images/services-diagram.webp?w=550) A container is an isolated process. In the Swarm mode model, each task invokes exactly one container. A task is analogous to a “slot” where the scheduler diff --git a/content/manuals/engine/swarm/key-concepts.md b/content/manuals/engine/swarm/key-concepts.md index c0833558fbd2..6f75eab41b51 100644 --- a/content/manuals/engine/swarm/key-concepts.md +++ b/content/manuals/engine/swarm/key-concepts.md @@ -46,7 +46,7 @@ including nodes, services, tasks, and load balancing. ## Nodes -A node is an instance of the Docker engine participating in the swarm. You can also think of this as a Docker node. You can run one or more nodes on a single physical computer or cloud server, but production swarm deployments typically include Docker nodes distributed across multiple physical and cloud machines. +A node is an instance of Docker Engine participating in the swarm. You can also think of this as a Docker node. You can run one or more nodes on a single physical computer or cloud server, but production swarm deployments typically include Docker nodes distributed across multiple physical and cloud machines. To deploy your application to a swarm, you submit a service definition to a manager node. The manager node dispatches units of work called diff --git a/content/manuals/engine/swarm/networking.md b/content/manuals/engine/swarm/networking.md index 8ffae7dfb2b7..d4257fc7a2ed 100644 --- a/content/manuals/engine/swarm/networking.md +++ b/content/manuals/engine/swarm/networking.md @@ -243,6 +243,26 @@ If you need more than 256 IP addresses, do not increase the IP block size. You c endpoint mode with an external load balancer, or use multiple smaller overlay networks. See [Configure service discovery](#configure-service-discovery) for more information about different endpoint modes. +#### Use direct server return + +Direct server return (DSR) changes east-west overlay load balancing so that +IPVS routes packets by changing the destination MAC address. The source IP and +destination virtual IP (VIP) remain unchanged. + +Create an overlay network that uses DSR: + +```console +$ docker network create \ + --driver overlay \ + --opt dsr \ + dsr-net +``` + +> [!NOTE] +> +> DSR is supported only for traffic between services on Linux nodes. The +> ingress routing mesh does not use DSR. + #### Configure encryption of application data {#encryption} Management and control plane data related to a swarm is always encrypted. diff --git a/content/manuals/engine/swarm/secrets.md b/content/manuals/engine/swarm/secrets.md index 1cc272b643e8..98e3d94ae358 100644 --- a/content/manuals/engine/swarm/secrets.md +++ b/content/manuals/engine/swarm/secrets.md @@ -125,6 +125,35 @@ Use these links to read about specific commands, or continue to the - [`--secret`](/reference/cli/docker/service/create/#secret) flag for `docker service create` - [`--secret-add` and `--secret-rm`](/reference/cli/docker/service/update/#secret-add) flags for `docker service update` +## Defining and using secrets in Compose files + +Using secrets in a Compose file alongside Docker Swarm is as simple as defining a secret +using `docker secret create`. + +```console +$ printf "my-secret" | docker secret create some_secret - +``` + +In the `compose.yml` file you can declare the secret as `external` in the top-level `secrets` attribute. + +```yaml +services: + api: + image: my-web-app + environment: + MY_ENV: /run/secrets/some_secret + secrets: + - some_secret + +secrets: + some_secret: + external: true +``` + +Both the `docker compose` and `docker stack` commands support defining secrets +in a Compose file. See +[the Compose file reference](/reference/compose-file/secrets.md) for details. + ## Examples This section includes three graduated examples which illustrate how to use @@ -139,12 +168,6 @@ a similar way, see > simplicity. The examples use Linux containers, but Windows containers also > support secrets. See [Windows support](#windows-support). -### Defining and using secrets in compose files - -Both the `docker-compose` and `docker stack` commands support defining secrets -in a compose file. See -[the Compose file reference](/reference/compose-file/legacy-versions.md) for details. - ### Simple example: Get started with secrets This simple example shows how secrets work in just a few commands. For a @@ -278,7 +301,7 @@ This example assumes that you have PowerShell installed. Hello Docker -

Hello Docker! You have deployed a HTML page.

+

Hello Docker! You have deployed an HTML page.

``` diff --git a/content/manuals/engine/swarm/swarm-tutorial/_index.md b/content/manuals/engine/swarm/swarm-tutorial/_index.md index 88c8ab6f9a87..492b920b7fd7 100644 --- a/content/manuals/engine/swarm/swarm-tutorial/_index.md +++ b/content/manuals/engine/swarm/swarm-tutorial/_index.md @@ -25,16 +25,18 @@ If you are brand new to Docker, see [About Docker Engine](../../_index.md). To run this tutorial, you need: -* [Three Linux hosts which can communicate over a network, with Docker installed](#three-networked-host-machines) -* [The IP address of the manager machine](#the-ip-address-of-the-manager-machine) -* [Open ports between the hosts](#open-protocols-and-ports-between-the-hosts) +- [Set up](#set-up) + - [Three networked host machines](#three-networked-host-machines) + - [Install Docker Engine on Linux machines](#install-docker-engine-on-linux-machines) + - [The IP address of the manager machine](#the-ip-address-of-the-manager-machine) + - [Open protocols and ports between the hosts](#open-protocols-and-ports-between-the-hosts) +- [Next steps](#next-steps) ### Three networked host machines This tutorial requires three Linux hosts which have Docker installed and can communicate over a network. These can be physical machines, virtual machines, -Amazon EC2 instances, or hosted in some other way. Check out -[Deploy to Swarm](/guides/swarm-deploy.md#prerequisites) for one possible set-up for the hosts. +Amazon EC2 instances, or hosted in some other way. One of these machines is a manager (called `manager1`) and two of them are workers (`worker1` and `worker2`). @@ -59,7 +61,7 @@ the IP address. Because other nodes contact the manager node on its IP address, you should use a fixed IP address. -You can run `ifconfig` on Linux or macOS to see a list of the +You can run `ip addr` on Linux, or `ifconfig` on macOS, to see a list of the available network interfaces. The tutorial uses `manager1` : `192.168.99.100`. diff --git a/content/manuals/enterprise/enterprise-deployment/_index.md b/content/manuals/enterprise/enterprise-deployment/_index.md deleted file mode 100644 index 8324d70ef201..000000000000 --- a/content/manuals/enterprise/enterprise-deployment/_index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Deploy Docker Desktop -weight: 10 -description: If you're an IT admin, learn how to deploy Docker Desktop at scale -keywords: msi, docker desktop, windows, installation, mac, pkg, enterprise -params: - sidebar: - group: Enterprise -grid: -- title: MSI installer - description: Learn how to install Docker Desktop with the MSI installer. - link: /enterprise/enterprise-deployment/msi-install-and-configure/ -- title: PKG installer - description: Learn how to install Docker Desktop with the PKG installer. - link: /enterprise/enterprise-deployment/pkg-install-and-configure/ -- title: MS Store - description: Learn how to install Docker Desktop through the Microsoft Store. - link: /enterprise/enterprise-deployment/ms-store/ -- title: Deploy with Intune - description: Learn how to deploy Docker Desktop on Windows and macOS devices using Microsoft Intune. - link: /enterprise/enterprise-deployment/use-intune/ -- title: Deploy with Jamf Pro - description: Learn how to deploy Docker Desktop for Mac using Jamf Pro - link: /enterprise/enterprise-deployment/use-jamf-pro/ -- title: Docker Desktop for Microsoft Dev Box - description: Install Docker Desktop for Microsoft Dev Box via the Microsoft Azure Marketlplace - link: /enterprise/enterprise-deployment/dev-box/ -- title: FAQs - description: Common questions when deploying Docker Desktop - link: /enterprise/enterprise-deployment/faq/ ---- - -Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, macOS, and Linux systems. - -{{< grid >}} \ No newline at end of file diff --git a/content/manuals/enterprise/enterprise-deployment/dev-box.md b/content/manuals/enterprise/enterprise-deployment/dev-box.md deleted file mode 100644 index c376eb18a7d7..000000000000 --- a/content/manuals/enterprise/enterprise-deployment/dev-box.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -Title: Docker Desktop in Microsoft Dev Box -linkTitle: Microsoft Dev Box -description: Learn about the benefits of and how to setup Docker Desktop in Microsoft Dev Box -keywords: desktop, docker, windows, microsoft dev box -weight: 60 ---- - -Docker Desktop is available as a pre-configured image in the Microsoft Azure Marketplace for use with Microsoft Dev Box, allowing developers to quickly set up consistent development environments in the cloud. - -Microsoft Dev Box provides cloud-based, pre-configured developer workstations that allow you to code, build, and test applications without configuring a local development environment. The Docker Desktop image for Microsoft Dev Box comes with Docker Desktop and its dependencies pre-installed, giving you a ready-to-use containerized development environment. - -## Key benefits - -- Docker Desktop, WSL2, and dependencies pre-installed -- Identical environment for every team member -- More compute and storage than a typical local machine -- Session state persists between uses -- Works with your existing Docker subscription - -## Setup - -### Prerequisites - -- An Azure subscription -- Access to Microsoft Dev Box -- A Docker subscription (Pro, Team, or Business). You can use Docker Desktop in Microsoft Dev Box with any of the following subscription options: - - An existing or new Docker subscription - - A new Docker subscription purchased through Azure Marketplace - - A Docker Business subscription with SSO configured for your organization - -### Set up Docker Desktop in Dev Box - -1. Navigate to the [Docker Desktop for Microsoft Dev Box](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/dockerinc1694120899427.devbox_azuremachine?tab=Overview) listing in Azure Marketplace. -2. Select **Get It Now** to add the virtual machine image to your subscription. -3. Follow the Azure workflow to complete the setup. -4. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup. - -### Activate Docker Desktop - -Once your Dev Box is provisioned with the Docker Desktop image: - -1. Start your Dev Box instance. -2. Launch Docker Desktop. -3. Sign in with your Docker ID. - -## Support - -For issues related to: - -- Docker Desktop configuration, usage, or licensing: Create a support ticket through [Docker Support](https://hub.docker.com/support). -- Dev Box creation, Azure portal configuration, or networking: Contact Azure Support. - -## Limitations - -- Microsoft Dev Box is only available on Windows 10 and 11 (Linux VMs are not supported). -- Performance may vary based on your Dev Box configuration and network conditions. diff --git a/content/manuals/enterprise/enterprise-deployment/faq.md b/content/manuals/enterprise/enterprise-deployment/faq.md deleted file mode 100644 index 4a7f96c1df34..000000000000 --- a/content/manuals/enterprise/enterprise-deployment/faq.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Enterprise deployment FAQs -linkTitle: FAQs -description: Frequently asked questions for deploying Docker Desktop at scale -keywords: msi, deploy, docker desktop, faqs, pkg, mdm, jamf, intune, windows, mac, enterprise, admin -tags: [FAQ, admin] -weight: 70 ---- - -## MSI - -Common questions about installing Docker Desktop using the MSI installer. - -### What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)? - -Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `-keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs: - -```powershell -# For all-user installations -& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -keep-data - -# For per-user installations -& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall -keep-data - -``` - -### What happens if the user's machine has an older `.exe` installation? - -The MSI installer detects older `.exe` installations and blocks the installation until the previous version is uninstalled. It prompts the user to uninstall their current/old version first, before retrying to install the MSI version. - -### My installation failed, how do I find out what happened? - -MSI installations may fail silently, offering little diagnostic feedback. - -To debug a failed installation, run the install again with verbose logging enabled: - -```powershell -msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" -``` - -After the installation has failed, open the log file and search for occurrences of `value 3`. This is the exit code Windows Installer outputs when it has failed. Just above the line, you will find the reason for the failure. - -### Why does the installer prompt for a reboot at the end of every fresh installation? - -The installer prompts for a reboot because it assumes that changes have been made to the system that require a reboot to finish their configuration. - -For example, if you select the WSL engine, the installer adds the required Windows features. After these features are installed, the system reboots to complete configurations so the WSL engine is functional. - -You can suppress reboots by using the `/norestart` option when launching the installer from the command line: - -```powershell -msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /norestart -``` - -### Why isn't the `docker-users` group populated when the MSI is installed with Intune or another MDM solution? - -It's common for MDM solutions to install applications in the context of the system account. This means that the `docker-users` group isn't populated with the user's account, as the system account doesn't have access to the user's context. - -As an example, you can reproduce this by running the installer with `psexec` in an elevated command prompt: - -```powershell -psexec -i -s msiexec /i "DockerDesktop.msi" -``` -The installation should complete successfully, but the `docker-users` group won't be populated. - -As a workaround, you can create a script that runs in the context of the user account. - -The script would be responsible for creating the `docker-users` group and populating it with the correct user. - -Here's an example script that creates the `docker-users` group and adds the current user to it (requirements may vary depending on environment): - -```powershell -$Group = "docker-users" -$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name - -# Create the group -New-LocalGroup -Name $Group - -# Add the user to the group -Add-LocalGroupMember -Group $Group -Member $CurrentUser -``` - -> [!NOTE] -> -> After adding a new user to the `docker-users` group, the user must sign out and then sign back in for the changes to take effect. - -## MDM - -Common questions about deploying Docker Desktop using mobile device management -(MDM) tools such as Jamf, Intune, or Workspace ONE. - -### Why doesn't my MDM tool apply all Docker Desktop configuration settings at once? - -Some MDM tools, such as Workspace ONE, may not support applying multiple -configuration settings in a single XML file. In these cases, you may need to -deploy each setting in a separate XML file. - -Refer to your MDM provider's documentation for specific deployment -requirements or limitations. \ No newline at end of file diff --git a/content/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md deleted file mode 100644 index cd90648c50ab..000000000000 --- a/content/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: PKG installer -description: Understand how to use the PKG installer. Also explore additional configuration options. -keywords: pkg, mac, docker desktop, install, deploy, configure, admin, mdm -tags: [admin] -weight: 20 ---- - -{{< summary-bar feature_name="PKG installer" >}} - -The PKG package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations. - -## Install interactively - -1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Admin Console**, then **Enterprise deployment**. -3. From the **macOS** tab, select the **Download PKG installer** button. -4. Once downloaded, double-click `Docker.pkg` to run the installer. -5. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation. - - **Introduction**: Select **Continue**. - - **License**: Review the license agreement and select **Agree**. - - **Destination Select**: This step is optional. It is recommended that you keep the default installation destination (usually `Macintosh HD`). Select **Continue**. - - **Installation Type**: Select **Install**. - - **Installation**: Authenticate using your administrator password or Touch ID. - - **Summary**: When the installation completes, select **Close**. - -> [!NOTE] -> -> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This ensures organizations can maintain version consistency and prevent unapproved updates. For Docker Desktop installed with the `.dmg` installer, in-app updates remain supported. -> -> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Enterprise deployment** page. -> -> To keep up to date with new releases, check the [release notes](/manuals/desktop/release-notes.md) page. - -## Install from the command line - -1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Admin Console**, then **Enterprise deployment**. -3. From the **macOS** tab, select the **Download PKG installer** button. -4. From your terminal, run the following command: - - ```console - $ sudo installer -pkg "/path/to/Docker.pkg" -target /Applications - ``` - -## Additional resources - -- See how you can deploy Docker Desktop for Mac using [Intune](use-intune.md) or [Jamf Pro](use-jamf-pro.md) -- Explore how to [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/methods.md#plist-method-mac-only) for your users. \ No newline at end of file diff --git a/content/manuals/enterprise/security/_index.md b/content/manuals/enterprise/security/_index.md deleted file mode 100644 index e767633ebf01..000000000000 --- a/content/manuals/enterprise/security/_index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -linkTitle: Security -title: Security for enterprises -description: Learn about enterprise level security features Docker has to offer and explore best practices -keywords: docker, docker hub, docker desktop, security, enterprises, scale -weight: 10 -params: - sidebar: - group: Enterprise -grid_admins: - - title: Settings Management - description: Learn how Settings Management can secure your developers' workflows. - icon: shield-check - link: /enterprise/security/hardened-desktop/settings-management/ - - title: Enhanced Container Isolation - description: Understand how Enhanced Container Isolation can prevent container attacks. - icon: shield-check - link: /enterprise/security/hardened-desktop/enhanced-container-isolation/ - - title: Registry Access Management - description: Control the registries developers can access while using Docker Desktop. - icon: server - link: /enterprise/security/hardened-desktop/registry-access-management/ - - title: Image Access Management - description: Control the images developers can pull from Docker Hub. - icon: photo - link: /enterprise/security/hardened-desktop/image-access-management/ - - title: "Air-Gapped Containers" - description: Restrict containers from accessing unwanted network resources. - icon: lock-closed - link: /enterprise/security/hardened-desktop/air-gapped-containers/ - - title: Enforce sign-in - description: Configure sign-in for members of your teams and organizations. - link: /enterprise/security/enforce-sign-in/ - icon: finger-print - - title: Domain management - description: Identify uncaptured users in your organization. - link: /enterprise/security/domain-management/ - icon: magnifying-glass - - title: Docker Scout - description: Explore how Docker Scout can help you create a more secure software supply chain. - icon: chart-bar - link: /scout/ - - title: SSO - description: Learn how to configure SSO for your company or organization. - icon: key - link: /enterprise/security/single-sign-on/ - - title: SCIM - description: Set up SCIM to automatically provision and deprovision users. - icon: clipboard-document-check - link: /enterprise/security/provisioning/scim/ - - title: Roles and permissions - description: Assign roles to individuals giving them different permissions within an organization. - icon: identification - link: /enterprise/security/roles-and-permissions/ - - title: Private marketplace for Extensions (Beta) - description: Learn how to configure and set up a private marketplace with a curated list of extensions for your Docker Desktop users. - icon: building-storefront - link: /extensions/private-marketplace/ - - title: Organization access tokens - description: Create organization access tokens as an alternative to a password. - link: /enterprise/security/access-tokens/ - icon: lock-closed ---- - -Docker provides security guardrails for both administrators and developers. - -If you're an administrator, you can enforce sign-in across Docker products for your developers, and -scale, manage, and secure your instances of Docker Desktop with DevOps security controls like Enhanced Container Isolation and Registry Access Management. - -## For administrators - -Explore the security features Docker offers to satisfy your company's security policies. - -{{< grid items="grid_admins" >}} diff --git a/content/manuals/enterprise/security/access-tokens.md b/content/manuals/enterprise/security/access-tokens.md deleted file mode 100644 index b275e8c956f4..000000000000 --- a/content/manuals/enterprise/security/access-tokens.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Organization access tokens -linkTitle: Organization access tokens -description: Create and manage organization access tokens to securely authenticate automated systems and CI/CD pipelines with Docker Hub -keywords: organization access tokens, OAT, docker hub security, programmatic access, automation -aliases: - - /security/for-admins/access-tokens/ ---- - -{{< summary-bar feature_name="OATs" >}} - -Organization access tokens (OATs) provide secure, programmatic access to Docker Hub for automated systems, CI/CD pipelines, and other business-critical tasks. Unlike personal access tokens tied to individual users, OATs are associated with your organization and can be managed by any organization owner. - -> [!WARNING] -> -> Organization access tokens are incompatible with Docker Desktop, Image Access Management, and Registry Access Management. If you use these features, use [personal access tokens](/manuals/security/access-tokens.md) instead. - -## Who should use organization access tokens? - -Use OATs for automated systems that need Docker Hub access without depending on individual user accounts: - -- CI/CD pipelines: Build and deployment systems that push and pull images -- Production systems: Applications that pull images during deployment -- Monitoring tools: Systems that need to check repository status or pull images -- Backup systems: Tools that periodically pull images for archival -- Integration services: Third-party tools that integrate with your Docker Hub repositories - -## Key benefits - -Benefits of using organization access tokens include: - -- Organizational ownership: Not tied to individual users who might leave the company -- Shared management: All organization owners can create and manage OATs -- Separate usage limits: OATs have their own Docker Hub rate limits, not counting against personal accounts -- Better security audit: Track when tokens were last used and identify suspicious activity -- Granular permissions: Limit access to specific repositories and operations - -## Prerequisites - -To create and use organization access tokens, you must have: - -- A Docker Team or Business subscription -- Owner permissions -- Repositories you want to grant access to - -## Create an organization access token - -Owners can create tokens with these limits: - -- Team subscription: Up to 10 OATs per organization -- Business subscription: Up to 100 OATs per organization - -Expired tokens count toward your total limit. - -To create an OAT: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your -organization. -1. Select **Admin Console**, then **Access tokens**. -1. Select **Generate access token**. -1. Configure token details: - - Label: Descriptive name indicating the token's purpose - - Description (optional): Additional details - - Expiration date: When the token should expire -1. Expand the **Repository** drop-down to set access permissions: - 1. Optional. Select **Read public repositories** for access to public repositories. - 1. Select **Add repository** and choose a repository from the drop-down. - 1. Set permissions for each repository: **Image Pull** or **Image Push**. - 1. Add up to 50 repositories as needed. -1. Optional. Configure organization management permissions by expanding the **Organization** drop-down and selecting the **Allow management access to this organization's resources**: - - **Member Edit**: Edit members of the organization - - **Member Read**: Read members of the organization - - **Invite Edit**: Invite members to the organization - - **Invite Read**: Read invites to the organization - - **Group Edit**: Edit groups of the organization - - **Group Read**: Read groups of the organization -1. Select **Generate token**. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen. - -> [!IMPORTANT] -> -> Treat organization access tokens like passwords. Store them securely in a credential manager and never commit them to source code repositories. - -## Use organization access tokens - -Sign in to the Docker CLI using your organization access token: - -```console -$ docker login --username -Password: [paste your OAT here] -``` - -When prompted for a password, enter your organization access token. - -## Modify existing tokens - -To manage existing tokens: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your -organization. -1. Select **Admin Console**, then **Access tokens**. -1. Select the actions menu in the token row, you can: - - **Edit** - - **Deactivate** - - **Delete** -1. Select **Save** after making changes to a token. - -## Organization access token best practices - -- Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks. -- Principle of least privilege: Grant only the minimum repository access and permissions needed for each use case. -- Monitor token usage: Regularly review when tokens were last used to identify unused or suspicious tokens. -- Secure storage: Store tokens in secure credential management systems, never in plain text or source code. -- Immediate revocation: Deactivate or delete tokens immediately if they're compromised or no longer needed. diff --git a/content/manuals/enterprise/security/domain-management.md b/content/manuals/enterprise/security/domain-management.md deleted file mode 100644 index 0de49e7184ea..000000000000 --- a/content/manuals/enterprise/security/domain-management.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Add and manage domains -description: Add, verify, and manage domains to control user access and enable auto-provisioning in Docker organizations -keywords: domain management, domain verification, auto-provisioning, user management, DNS, TXT record, Admin Console -weight: 10 -aliases: - - /security/for-admins/domain-management/ ---- - -{{< summary-bar feature_name="Domain management" >}} - -Domain management lets you add and verify domains for your organization, then enable auto-provisioning to automatically add users when they sign in with email addresses that match your verified domains. This approach simplifies user management, ensures consistent security settings, and reduces the risk of unmanaged users accessing Docker without visibility or control. - -This page provides steps to add and delete domains, configure auto-provisioning, and audit uncaptured users. - -## Add and verify a domain - -Adding a domain requires verification to confirm ownership. The verification process uses DNS records to prove you control the domain. - -### Add a domain - -1. Sign in to [Docker Home](https://app.docker.com) and select - your organization. If your organization is part of a company, select the company - and configure the domain for the organization at the company level. -1. Select **Admin Console**, then **Domain management**. -1. Select **Add a domain**. -1. Enter your domain and select **Add domain**. -1. In the pop-up modal, copy the **TXT Record Value** to verify your domain. - -### Verify a domain - -Verification confirms that you own the domain by adding a TXT record to your Domain Name System (DNS) host. It can take up to 72 hours for the DNS change to propagate. Docker automatically checks for the record and confirms ownership once the change is recognized. - -> [!TIP] -> -> The record name field determines where the TXT record is added in your domain (root or subdomain). For root domains like `example.com`, use `@` or leave the record name empty, depending on your provider. Don't enter values like docker, `docker-verification`, `www`, or your domain name, as these may direct to the wrong place. Check your DNS provider's documentation to verify record name requirements. - -Follow the steps for your DNS provider to add the **TXT Record Value**. If -your provider isn't listed, use the steps for "Other providers": - -{{< tabs >}} -{{< tab name="AWS Route 53" >}} - -1. Add your TXT record to AWS by following [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). -1. Wait up to 72 hours for TXT record verification. -1. Return to the **Domain management** page of the - [Admin Console](https://app.docker.com/admin) and select **Verify** next to - your domain name. - -{{< /tab >}} -{{< tab name="Google Cloud DNS" >}} - -1. Add your TXT record to Google Cloud DNS by following [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). -1. Wait up to 72 hours for TXT record verification. -1. Return to the **Domain management** page of the - [Admin Console](https://app.docker.com/admin) and select **Verify** next to - your domain name. - -{{< /tab >}} -{{< tab name="GoDaddy" >}} - -1. Add your TXT record to GoDaddy by following [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). -1. Wait up to 72 hours for TXT record verification. -1. Return to the **Domain management** page of the - [Admin Console](https://app.docker.com/admin) and select **Verify** next to - your domain name. - -{{< /tab >}} -{{< tab name="Other providers" >}} - -1. Sign in to your domain host. -1. Add a TXT record to your DNS settings using the **TXT Record Value** from Docker. -1. Wait up to 72 hours for TXT record verification. -1. Return to the **Domain management** page of the - [Admin Console](https://app.docker.com/admin) and select **Verify** next to - your domain name. - -{{< /tab >}} -{{< /tabs >}} - -## Audit domains for uncaptured users - -Domain audit identifies uncaptured users. Uncaptured users are Docker users who have authenticated using an email address associated with your verified domains but aren't members of your Docker organization. - -### Limitations - -Domain audit can't identify: - -- Users who access Docker Desktop without authenticating -- Users who authenticate using an account that doesn't have an - email address associated with one of your verified domains - -To prevent unidentifiable users from accessing Docker Desktop, [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). - -### Run a domain audit - -1. Sign in to [Docker Home](https://app.docker.com) and choose your - company. -1. Select **Admin Console**, then **Domain management**. -1. In **Domain audit**, select **Export Users** to export a CSV file - of uncaptured users. - -The CSV file contains the following columns: - -- Name: Docker user's display name -- Username: Docker ID of the user -- Email: Email address of the user - -### Invite uncaptured users - -You can bulk invite uncaptured users to your organization using the exported -CSV file. For more information on bulk inviting users, see -[Manage organization members](/manuals/admin/organization/manage/members.md). - -## Auto-provisioning - -[Auto-provisioning](/manuals/enterprise/security/provisioning/auto-provisioning.md) uses verified domains to associate organization members with email address that match the verified domains. To override auto-provisioning, you can configure one of the two alternative methods: - -- [Just-in-Time (JIT)](/manuals/enterprise/security/provisioning/just-in-time.md) provisioning -- [System for Cross-domain Identity Management (SCIM)](/manuals/enterprise/security/provisioning/scim/_index.md) - -## Delete a domain - -Deleting a domain removes its TXT record value and disables any associated auto-provisioning. - -> [!WARNING] -> -> Deleting a domain will disable auto-provisioning for that domain and remove verification. This action cannot be undone. - -To delete a domain: - -1. Sign in to [Docker Home](https://app.docker.com) and select - your organization. If your organization is part of a company, select the company - and configure the domain for the organization at the company level. -1. Select **Admin Console**, then **Domain management**. -1. For the domain you want to delete, select the **Actions** menu, then - **Delete domain**. -1. To confirm, select **Delete domain** in the pop-up modal. diff --git a/content/manuals/enterprise/security/enforce-sign-in/_index.md b/content/manuals/enterprise/security/enforce-sign-in/_index.md deleted file mode 100644 index 82497c724f6f..000000000000 --- a/content/manuals/enterprise/security/enforce-sign-in/_index.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Enforce sign-in for Docker Desktop -linkTitle: Enforce sign-in -description: Require users to sign in to Docker Desktop to access organization benefits and security features -toc_max: 2 -keywords: authentication, registry.json, configure, enforce sign-in, docker desktop, security, .plist, registry key, mac, windows, organization -tags: [admin] -aliases: - - /security/for-admins/configure-sign-in/ - - /security/for-admins/enforce-sign-in/ -weight: 30 ---- - -{{< summary-bar feature_name="Enforce sign-in" >}} - -By default, users can access Docker Desktop without signing in to your organization. -When users don't sign in as organization members, they miss out on subscription benefits and can bypass security features configured for your organization. - -You can enforce sign-in using several methods, depending on your setup: - -- [Registry key method (Windows only)](methods.md#registry-key-method-windows-only) -- [Configuration profiles method (Mac only)](methods.md#configuration-profiles-method-mac-only) -- [`.plist` method (Mac only)](methods.md#plist-method-mac-only) -- [`registry.json` method (All)](methods.md#registryjson-method-all) - -This page provides an overview of how sign-in enforcement works. - -## How sign-in enforcement works - -When Docker Desktop detects a registry key, `.plist` file, or -`registry.json` file: - -- A **Sign in required!** prompt appears, requiring users to sign - in as organization members to use Docker Desktop. -- If users sign in with accounts that aren't organization members, they're - automatically signed out and can't use Docker Desktop. They can select **Sign in** - to try again with a different account. -- When users sign in with organization member accounts, they can use Docker - Desktop normally. -- When users sign out, the **Sign in required!** prompt reappears and they can - no longer use Docker Desktop unless they sign back in. - -> [!NOTE] -> -> Enforcing sign-in for Docker Desktop doesn't affect Docker CLI access. CLI access is only restricted for organizations that enforce single sign-on (SSO). - -### Impact on already-signed-in users - -When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop only re-evaluates enforcement on restart. - -On the next Docker Desktop restart: - -- Users signed in with an organization member account are automatically re-authenticated and continue working uninterrupted. -- Users signed in with a non-member account are immediately signed out on startup and see the **Sign in required!** prompt. - -## Enforcing sign-in versus enforcing single sign-on (SSO) - -Enforcing Docker Desktop sign-in and [enforcing SSO](/manuals/enterprise/security/single-sign-on/connect.md#optional-enforce-sso) are different features that serve different purposes: - - -| Enforcement | Description | Benefits | -|:----------------------------------|:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Enforce sign-in only | Users must sign in before using Docker Desktop | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. | -| Enforce single sign-on (SSO) only | If users sign in, they must sign in using SSO | Centralizes authentication and enforces unified policies set by the identity provider. | -| Enforce both | Users must sign in using SSO before using Docker Desktop | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. It also centralizes authentication and enforces unified policies set by the identity provider. | -| Enforce neither | If users sign in, they can use SSO or their Docker credentials | Lets users access Docker Desktop without barriers, at the cost of reduced security and insights. | - -## Next steps - -- To set up sign-in enforcement, see [Configure sign-in enforcement](/manuals/enterprise/security/enforce-sign-in/methods.md). -- To configure SSO enforcement, see [Enforce SSO](/manuals/enterprise/security/single-sign-on/connect.md). diff --git a/content/manuals/enterprise/security/enforce-sign-in/methods.md b/content/manuals/enterprise/security/enforce-sign-in/methods.md deleted file mode 100644 index 09648085c141..000000000000 --- a/content/manuals/enterprise/security/enforce-sign-in/methods.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -title: Configure sign-in enforcement -linkTitle: Configure -description: Configure sign-in enforcement for Docker Desktop using registry keys, configuration profiles, plist files, or registry.json files -keywords: authentication, registry.json, configure, enforce sign-in, docker desktop, security, .plist, registry key, mac, windows, linux -tags: [admin] -aliases: - - /security/for-admins/enforce-sign-in/methods/ ---- - -{{< summary-bar feature_name="Enforce sign-in" >}} - -You can enforce sign-in for Docker Desktop using several methods. Choose the method that best fits your organization's infrastructure and security requirements. - -## Choose your method - -| Method | Platform | -|:-------|:---------| -| Registry key | Windows only | -| Configuration profiles | Mac only | -| `plist` file | Mac only | -| `registry.json` | All platforms | - -> [!TIP] -> -> For Mac, configuration profiles offer the highest security because they're -protected by Apple's System Integrity Protection (SIP). - -## Windows: Registry key method - -{{< tabs >}} -{{< tab name="Manual setup" >}} - -To configure the registry key method manually: - -1. Create the registry key: - - ```console - $ HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop - ``` -1. Create a multi-string value name `allowedOrgs`. -1. Use your organization names as string data. You can add multiple organizations: - - Use lowercase letters only - - Add each organization on a separate line - - Do not use spaces or commas as separators -1. Restart Docker Desktop. -1. Verify the **Sign in required!** prompt appears in Docker Desktop. - -{{< /tab >}} -{{< tab name="Group Policy deployment" >}} - -Deploy the registry key across your organization using Group Policy: - -1. Create a registry script with the following structure: - - Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop` - - Value name: `allowedOrgs` (multi-string) - - Value data: Your organization names, one per line, in lowercase only -1. In Group Policy Management, create or edit a GPO. -1. Navigate to **Computer Configuration** > **Preferences** > **Windows Settings** > **Registry**. -1. Right-click **Registry** > **New** > **Registry Item**. -1. Configure the registry item: - - Action: **Update** - - Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop` - - Value name: `allowedOrgs` - - Value data: Your organization names -1. Link the GPO to the target Organizational Unit. -1. Test on a small group using `gpupdate/force`. -1. Deploy organization-wide after verification. - -{{< /tab >}} -{{< /tabs >}} - -## Mac: Configuration profiles method (recommended) - -Configuration profiles provide the most secure enforcement method for Mac, as they're protected by Apple's System Integrity Protection. - -The payload is a dictionary of key-values. Docker Desktop supports the following keys: - -- `allowedOrgs`: Sets a list of organizations in one single string, where each organization is in lowercase only and is separated by a semi-colon. -- `overrideProxyHTTP`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. -- `overrideProxyHTTPS`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests. -- `overrideProxyExclude`: Bypasses proxy settings for the specified hosts and domains. Uses a comma-separated list. -- `overrideProxyPAC`: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy. -- `overrideProxyEmbeddedPAC`: Sets the content of an in-memory PAC file. It has precedence over `overrideProxyPAC`. - -Overriding at least one of the proxy settings via Configuration profiles will automatically lock the settings as they're managed by Mac. - - -1. Create a file named `docker.mobileconfig` and include the following content: - ```xml - - - - - PayloadContent - - - PayloadType - com.docker.config - PayloadVersion - 1 - PayloadIdentifier - com.docker.config - PayloadUUID - eed295b0-a650-40b0-9dda-90efb12be3c7 - PayloadDisplayName - Docker Desktop Configuration - PayloadDescription - Configuration profile to manage Docker Desktop settings. - PayloadOrganization - Your company name - allowedOrgs - first_org;second_org - overrideProxyHTTP - http://company.proxy:port - overrideProxyHTTPS - https://company.proxy:port - - - PayloadType - Configuration - PayloadVersion - 1 - PayloadIdentifier - com.yourcompany.docker.config - PayloadUUID - 0deedb64-7dc9-46e5-b6bf-69d64a9561ce - PayloadDisplayName - Docker Desktop Config Profile - PayloadDescription - Config profile to enforce Docker Desktop settings for allowed organizations. - PayloadOrganization - Your company name - - - ``` -1. Replace placeholders: - - Change `com.yourcompany.docker.config` to your company identifier - - Replace `Your company name` with your organization name making sure it is all lowercase - - Replace `PayloadUUID` with a randomly generated UUID - - Update the `allowedOrgs` value with your organization names (separated by semicolons) - - Replace `company.proxy:port` with http/https proxy server host(or IP address) and port -1. Deploy the profile using your MDM solution. -1. Verify the profile appears in **System Settings** > **General** > **Device Management** under **Device (Managed)**. Ensure the profile is listed with the correct name and settings. - -Some MDM solutions let you specify the payload as a plain dictionary of key-value settings without the full `.mobileconfig` wrapper: - -```xml - - allowedOrgs - first_org;second_org - overrideProxyHTTP - http://company.proxy:port - overrideProxyHTTPS - https://company.proxy:port - -``` - -## Mac: plist file method - -{{< tabs >}} -{{< tab name="Manual creation" >}} - -1. Create the file `/Library/Application Support/com.docker.docker/desktop.plist`. -1. Add this content, replacing `myorg1` and `myorg2` with your organization names and making sure they have lowercase letters only: - ```xml - - - - - allowedOrgs - - myorg1 - myorg2 - - - - ``` -1. Set file permissions to prevent editing by non-administrator users. -1. Restart Docker Desktop. -1. Verify the `Sign in required!` prompt appears in Docker Desktop. - -{{< /tab >}} -{{< tab name="Shell script deployment" >}} - -Create and deploy a script for organization-wide distribution: - -```bash -#!/bin/bash - -# Create directory if it doesn't exist -sudo mkdir -p "/Library/Application Support/com.docker.docker" - -# Write the plist file -sudo defaults write "/Library/Application Support/com.docker.docker/desktop.plist" allowedOrgs -array "myorg1" "myorg2" - -# Set appropriate permissions -sudo chmod 644 "/Library/Application Support/com.docker.docker/desktop.plist" -sudo chown root:admin "/Library/Application Support/com.docker.docker/desktop.plist" -``` - -Deploy this script using SSH, remote support tools, or your preferred deployment method. - -{{< /tab >}} -{{< /tabs >}} - -## All platforms: registry.json method - -The registry.json method works across all platforms and offers flexible deployment options. - -### File locations - -Create the `registry.json` file (UTF-8 without BOM) at the appropriate location: - -| Platform | Location | -| --- | --- | -| Windows | `/ProgramData/DockerDesktop/registry.json` | -| Mac | `/Library/Application Support/com.docker.docker/registry.json` | -| Linux | `/usr/share/docker-desktop/registry/registry.json` | - -### Basic setup - -{{< tabs >}} -{{< tab name="Manual creation" >}} - -1. Ensure users are members of your Docker organization. -1. Create the `registry.json` file at the appropriate location for your platform. -1. Add this content, replacing organization names with your own and making sure they have lowercase letters only: - ```json - { - "allowedOrgs": ["myorg1", "myorg2"] - } - ``` -1. Set file permissions to prevent user editing. -1. Restart Docker Desktop. -1. Verify the `Sign in required!` prompt appears in Docker Desktop. - -> [!TIP] -> -> If users have issues starting Docker Desktop after enforcing sign-in, -> they may need to update to the latest version. - -{{< /tab >}} -{{< tab name="Command line setup" >}} - -#### Windows (PowerShell as Administrator) - -```shell -Set-Content /ProgramData/DockerDesktop/registry.json '{"allowedOrgs":["myorg1","myorg2"]}' -``` - -#### Mac - -```console -sudo mkdir -p "/Library/Application Support/com.docker.docker" -echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json" -``` - -#### Linux - -```console -sudo mkdir -p /usr/share/docker-desktop/registry -echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee /usr/share/docker-desktop/registry/registry.json -``` - -{{< /tab >}} -{{< tab name="Installation-time setup" >}} - -Create the registry.json file during Docker Desktop installation: - -#### Windows - -```shell -# PowerShell -Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg' - -# Command Prompt -"Docker Desktop Installer.exe" install --allowed-org=myorg1 -``` - -> [!NOTE] -> -> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. - -#### Mac - -```console -sudo hdiutil attach Docker.dmg -sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg -sudo hdiutil detach /Volumes/Docker -``` -> [!NOTE] -> -> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. - -{{< /tab >}} -{{< /tabs >}} - -## Method precedence - -When multiple configuration methods exist on the same system, Docker Desktop uses this precedence order: - -1. Registry key (Windows only) -1. Configuration profiles (Mac only) -1. plist file (Mac only) -1. registry.json file - -## Troubleshoot sign-in enforcement - -If sign-in enforcement doesn't work: - -- Verify file locations and permissions -- Check that organization names use lowercase letters -- Restart Docker Desktop or reboot the system -- Confirm users are members of the specified organizations -- Update Docker Desktop to the latest version diff --git a/content/manuals/enterprise/security/hardened-desktop/_index.md b/content/manuals/enterprise/security/hardened-desktop/_index.md deleted file mode 100644 index 6fb7a7ae9749..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/_index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Hardened Docker Desktop -linkTitle: Hardened Docker Desktop -description: Security features that help organizations secure developer environments without impacting productivity -keywords: security, hardened desktop, enhanced container isolation, registry access management, settings management, admins, docker desktop, image access management, air-gapped containers -tags: [admin] -aliases: - - /security/for-admins/hardened-desktop/ -grid: - - title: "Settings Management" - description: Learn how Settings Management can secure your developers' workflows. - icon: shield-check - link: /enterprise/security/hardened-desktop/settings-management/ - - title: "Enhanced Container Isolation" - description: Understand how Enhanced Container Isolation can prevent container attacks. - icon: shield-check - link: /enterprise/security/hardened-desktop/enhanced-container-isolation/ - - title: "Registry Access Management" - description: Control the registries developers can access while using Docker Desktop. - icon: server - link: /enterprise/security/hardened-desktop/registry-access-management/ - - title: "Image Access Management" - description: Control the images developers can pull from Docker Hub. - icon: photo - link: /enterprise/security/hardened-desktop/image-access-management/ - - title: "Air-Gapped Containers" - description: Restrict containers from accessing unwanted network resources. - icon: lock-closed - link: /enterprise/security/hardened-desktop/air-gapped-containers/ - - title: "Namespace access" - description: Control whether organization members can push content to their personal namespaces. - icon: folder-open - link: /enterprise/security/hardened-desktop/namespace-access/ -weight: 60 ---- - -{{< summary-bar feature_name="Hardened Docker Desktop" >}} - -Hardened Docker Desktop provides a collection of security features designed to strengthen developer environments without compromising productivity or developer experience. - -With Hardened Docker Desktop, you can enforce strict security policies that prevent developers and containers from bypassing organizational controls. You can also enhance container isolation to protect against security threats like malicious payloads that might breach the Docker Desktop Linux VM or underlying host system. - -## Who should use Hardened Docker Desktop? - -Hardened Docker Desktop is ideal for security-focused organizations that: - -- Don't provide root or administrator access to developers' machines -- Want centralized control over Docker Desktop configurations -- Must meet specific compliance requirements - -## How Hardened Docker Desktop works - -Hardened Docker Desktop features work independently and together to create a defense-in-depth security strategy. They protect developer workstations against attacks across multiple layers, including Docker Desktop configuration, container image management, and container runtime security: - -- Registry Access Management and Image Access Management prevent access to unauthorized container registries and image types, reducing exposure to malicious payloads -- Enhanced Container Isolation runs containers without root privileges inside a Linux user namespace, limiting the impact of malicious containers -- Air-gapped containers let you configure network restrictions for containers, preventing malicious containers from accessing your organization's internal network resources -- Namespace access controls whether organization members can push content to their personal Docker Hub namespaces, preventing accidental publication of images outside approved locations -- Settings Management locks down Docker Desktop configurations to enforce company policies and prevent developers from introducing insecure settings, whether intentionally or accidentally - -## Next steps - -Explore Hardened Docker Desktop features to understand how they can strengthen your organization's security posture: - -{{< grid >}} diff --git a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md b/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md deleted file mode 100644 index 6651dcd4f208..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Enhanced Container Isolation -linkTitle: Enhanced Container Isolation -description: Enhanced Container Isolation provides additional security for Docker Desktop by preventing malicious containers from compromising the host -keywords: enhanced container isolation, container security, sysbox runtime, linux user namespaces, hardened desktop -aliases: - - /desktop/hardened-desktop/enhanced-container-isolation/ - - /security/for-admins/hardened-desktop/enhanced-container-isolation/ -weight: 10 ---- - -{{< summary-bar feature_name="Hardened Docker Desktop" >}} - -Enhanced Container Isolation (ECI) prevents malicious containers from compromising Docker Desktop or the host system. It applies advanced security techniques automatically while maintaining full developer productivity and workflow compatibility. - -- ECI strengthens container isolation and locks in security configurations created by administrators, such as [Registry Access Management policies](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) and [Settings Management](../settings-management/_index.md) controls. -- ECI works alongside other Docker security features like reduced Linux capabilities, seccomp, and AppArmor. - -If you are using WSL2 backend, ensure you’re running WSL version 2.6 or later. This is required because ECI depends on a Linux kernel version of at least 6.3.0, and WSL 2.6+ includes kernel version 6.6. - -## Who should use Enhanced Container Isolation? - -ECI is designed for: - -- Organizations that want to prevent container-based attacks and reduce security vulnerabilities in developer environments -- Security teams that need stronger container isolation without impacting developer workflows -- Enterprises that require additional protection when running untrusted or third-party container images - -## How Enhanced Container Isolation works - -Docker implements ECI using the [Sysbox container runtime](https://github.com/nestybox/sysbox), a -security-enhanced fork of the standard OCI runc runtime. When ECI is turned on, containers created through `docker run` or `docker create` automatically use Sysbox instead of runc without requiring any changes to developer workflows. Docker's default runtime remains runc, but all user containers -implicitly launch with Sysbox. - -When ECI is turned on, the Docker CLI `--runtime` flag is ignored. Even containers using the `--privileged` flag run securely with ECI, preventing them from breaching the Docker Desktop virtual machine or other containers. - -## Key security features - -### Linux user namespace isolation - -With Enhanced Container Isolation, all containers leverage Linux user namespaces for stronger isolation. Container root users map to unprivileged users in the Docker Desktop VM: - -```console -$ docker run -it --rm --name=first alpine -/ # cat /proc/self/uid_map - 0 100000 65536 -``` - -This output shows that container root (0) maps to unprivileged user 100000 in the VM, with a range of 64K user IDs. Each container gets exclusive mappings: - -```console -$ docker run -it --rm --name=second alpine -/ # cat /proc/self/uid_map - 0 165536 65536 -``` - -Without Enhanced Container Isolation, containers run as true root: - -```console -$ docker run -it --rm alpine -/ # cat /proc/self/uid_map - 0 0 4294967295 -``` - -By using Linux user namespaces, ECI ensures container processes never run with valid user IDs in the Linux VM, constraining their capabilities to resources within the container only. - -### Secured privileged containers - -Privileged containers (`docker run --privileged`) normally pose significant security risks because they provide unrestricted access to the Linux kernel. Without ECI, privileged containers can: - -- Run as true root with all capabilities -- Bypass seccomp and AppArmor restrictions -- Access all hardware devices -- Modify global kernel settings - -Organizations securing developer environments face challenges with privileged containers because they can gain control of the Docker Desktop VM and alter security settings like registry access management and network proxies. - -Enhanced Container Isolation transforms privileged containers by ensuring they can only access resources within their container boundary. For example, privileged containers can't access Docker Desktop's network configuration: - -```console -$ docker run --privileged djs55/bpftool map show -Error: can't get next map: Operation not permitted -``` - -Without ECI, privileged containers can easily access and modify these settings: - -```console -$ docker run --privileged djs55/bpftool map show -17: ringbuf name blocked_packets flags 0x0 - key 0B value 0B max_entries 16777216 memlock 0B -18: hash name allowed_map flags 0x0 - key 4B value 4B max_entries 10000 memlock 81920B -``` - -Advanced container workloads like Docker-in-Docker and Kubernetes-in-Docker still work with ECI but run much more securely. - -> [!NOTE] -> -> ECI doesn't prevent users from running privileged containers, but makes them secure by containing their access. Privileged workloads that modify global kernel settings (loading kernel modules, changing Berkeley Packet Filter settings) receive "permission denied" errors. - -### Namespace isolation enforcement - -Enhanced Container Isolation prevents containers from sharing Linux namespaces with the Docker Desktop VM, maintaining isolation boundaries: - -**PID namespace sharing blocked:** - -```console -$ docker run -it --rm --pid=host alpine -docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share namespaces [pid] with the host (because they use the linux user-namespace for isolation): unknown. -``` - -**Network namespace sharing blocked:** - -```console -$ docker run -it --rm --network=host alpine -docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown. -``` - -**User namespace override ignored:** - -```console -$ docker run -it --rm --userns=host alpine -/ # cat /proc/self/uid_map - 0 100000 65536 -``` - -Docker build operations using `--network-host` and Docker buildx entitlements (`network.host`, -`security.insecure`) are also blocked. - -### Protected bind mounts - -Enhanced Container Isolation maintains support for standard file sharing while preventing access to sensitive VM directories: - -Host directory mounts continue to work: - -```console -$ docker run -it --rm -v $HOME:/mnt alpine -/ # ls /mnt -# Successfully lists home directory contents -``` - -VM configuration mounts are blocked: - -```console -$ docker run -it --rm -v /etc/docker/daemon.json:/mnt/daemon.json alpine -docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: can't mount /etc/docker/daemon.json because it's configured as a restricted host mount: unknown -``` - -This prevents containers from reading or modifying Docker Engine configurations, registry access management settings, proxy configurations, and other security-related VM files. - -> [!NOTE] -> -> By default, ECI blocks bind mounting the Docker Engine socket (/var/run/docker.sock) as this would grant containers control over Docker Engine. Administrators can create exceptions for trusted container images. - -### Advanced system call protection - -Enhanced Container Isolation intercepts sensitive system calls to prevent containers from using legitimate capabilities maliciously: - -```console -$ docker run -it --rm --cap-add SYS_ADMIN -v $HOME:/mnt:ro alpine -/ # mount -o remount,rw /mnt /mnt -mount: permission denied (are you root?) -``` - -Even with `CAP_SYS_ADMIN` capability, containers can't change read-only bind mounts to read-write, ensuring they can't breach container boundaries. - -Containers can still create internal mounts within their filesystem: - -```console -/ # mkdir /root/tmpfs -/ # mount -t tmpfs tmpfs /root/tmpfs -/ # mount -o remount,ro /root/tmpfs /root/tmpfs -/ # findmnt | grep tmpfs -├─/root/tmpfs tmpfs tmpfs ro,relatime,uid=100000,gid=100000 -``` - -ECI performs system call filtering efficiently by intercepting only control-path system calls (rarely used) while leaving data-path system calls unaffected, maintaining container performance. - -### Automatic filesystem user ID mapping - -Enhanced Container Isolation solves file sharing challenges between containers with different user ID ranges through automatic filesystem mapping. - -Each container gets exclusive user ID mappings, but Sysbox uses filesystem user ID remapping via Linux kernel ID-mapped mounts (added in 2021) or alternative shiftsfs module. This maps filesystem accesses from containers' real user IDs to standard ranges, enabling: - -- Volume sharing across containers with different user ID ranges -- Consistent file ownership regardless of container user ID mappings -- Transparent file access without user intervention - -### Information hiding through filesystem emulation - -ECI emulates portions of `/proc` and `/sys` filesystems within containers to hide sensitive host information and provide per-container views of kernel resources: - -```console -$ docker run -it --rm alpine -/ # cat /proc/uptime -5.86 5.86 -``` - -This shows container uptime instead of Docker Desktop VM uptime, preventing system information from leaking into containers. - -Several `/proc/sys` resources that aren't namespaced by the Linux kernel are emulated per-container, with Sysbox coordinating values when programming kernel settings. This enables container workloads that normally require privileged access to run securely. - -## Performance and compatibility - -Enhanced Container Isolation maintains optimized performance and full compatibility: - -- No performance impact: System call filtering targets only control-path calls, leaving data-path operations unaffected -- Full workflow compatibility: Existing development processes, tools, and container images work unchanged -- Advanced workload support: Docker-in-Docker, Kubernetes-in-Docker, and other complex scenarios work securely -- Automatic management: User ID mappings, filesystem access, and security policies are handled automatically -- Standard image support: No special container images or modifications required - -> [!IMPORTANT] -> -> ECI protection varies by Docker Desktop version and doesn't yet protect extension containers. Docker builds and Kubernetes in Docker Desktop have varying protection levels depending on the version. For details, see [Enhanced Container Isolation limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md). diff --git a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md b/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md deleted file mode 100644 index 390f868a3543..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Configure Docker socket exceptions and advanced settings -linkTitle: Configure advanced settings -description: Configure Docker socket exceptions and advanced settings for Enhanced Container Isolation -keywords: enhanced container isolation, docker socket, configuration, testcontainers, admin settings -aliases: - - /security/for-admins/hardened-desktop/enhanced-container-isolation/config/ -weight: 20 ---- - -{{< summary-bar feature_name="Hardened Docker Desktop" >}} - -This page shows you how to configure Docker socket exceptions and other advanced settings for Enhanced Container Isolation (ECI). These configurations enable trusted tools like Testcontainers to work with ECI while maintaining security. - -## Docker socket mount permissions - -By default, Enhanced Container Isolation blocks containers from mounting the Docker socket to prevent malicious access to Docker Engine. However, some tools require Docker socket access. - -Common scenarios requiring Docker socket access include: - -- Testing frameworks: Testcontainers, which manages test containers -- Build tools: Paketo buildpacks that create ephemeral build containers -- CI/CD tools: Tools that manage containers as part of deployment pipelines -- Development utilities: Docker CLI containers for container management - -## Configure socket exceptions - -Configure Docker socket exceptions using Settings Management: - -{{< tabs >}} -{{< tab name="Admin Console" >}} - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Go to **Admin Console** > **Desktop Settings Management**. -1. [Create or edit a setting policy](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md). -1. Find **Enhanced Container Isolation** settings. -1. Configure **Docker socket access control** with your trusted images and -command restrictions. - -{{< /tab >}} -{{< tab name="JSON file" >}} - -Create an [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md) and add: - -```json -{ - "configurationFileVersion": 2, - "enhancedContainerIsolation": { - "locked": true, - "value": true, - "dockerSocketMount": { - "imageList": { - "images": [ - "docker.io/localstack/localstack:*", - "docker.io/testcontainers/ryuk:*", - "docker:cli" - ], - "allowDerivedImages": true - }, - "commandList": { - "type": "deny", - "commands": ["push", "build"] - } - } - } -} -``` - -{{< /tab >}} -{{< /tabs >}} - -## Image allowlist configuration - -The `imageList` defines which container images can mount the Docker socket. - -### Image reference formats - -| Format | Description | -| :---------------------- | :---------- | -| `[:]` | Name of the image, with optional tag. If the tag is omitted, the `:latest` tag is used. If the tag is the wildcard `*`, then it means "any tag for that image." | -| `@` | Name of the image, with a specific repository digest (e.g., as reported by `docker buildx imagetools inspect `). This means only the image that matches that name and digest is allowed. | - -### Example configurations - -Basic allowlist for testing tools: - -```json -"imageList": { - "images": [ - "docker.io/testcontainers/ryuk:*", - "docker:cli", - "alpine:latest" - ] -} -``` - -Wildcard allowlist (Docker Desktop 4.36 and later): - -```json -"imageList": { - "images": ["*"] -} -``` - -> [!WARNING] -> -> Using `"*"` allows all containers to mount the Docker socket, which reduces security. Only use this when explicitly listing allowed images isn't feasible. - -### Security validation - -Docker Desktop validates allowed images by: - -1. Downloading image digests from registries for allowed images -1. Comparing container image digests against the allowlist when containers start -1. Blocking containers whose digests don't match allowed images - -This prevents bypassing restrictions by re-tagging unauthorized images: - -```console -$ docker tag malicious-image docker:cli -$ docker run -v /var/run/docker.sock:/var/run/docker.sock docker:cli -# This fails because the digest doesn't match the real docker:cli image -``` - -## Derived images support - -For tools like Paketo buildpacks that create ephemeral local images, you can -allow images derived from trusted base images. - -### Enable derived images - -```json -"imageList": { - "images": [ - "paketobuildpacks/builder:base" - ], - "allowDerivedImages": true -} -``` - -When `allowDerivedImages` is true, local images built from allowed base images (using `FROM` in Dockerfile) also gain Docker socket access. - -### Derived images requirements - -- Local images only: Derived images must not exist in remote registries -- Base image available: The parent image must be pulled locally first -- Performance impact: Adds up to 1 second to container startup for validation -- Version compatibility: Full wildcard support requires Docker Desktop 4.36+ - -## Command restrictions - -### Deny list (recommended) - -Blocks specified commands while allowing all others: - -```json -"commandList": { - "type": "deny", - "commands": ["push", "build", "image*"] -} -``` - -### Allow list - -Only allows specified commands while blocking all others: - -```json -"commandList": { - "type": "allow", - "commands": ["ps", "container*", "volume*"] -} -``` - -### Command wildcards - -| Wildcard | Blocks/allows | -| :---------------- | :---------- | -| `"container\*"` | All "docker container ..." commands | -| `"image\*"` | All "docker image ..." commands | -| `"volume\*"` | All "docker volume ..." commands | -| `"network\*"` | All "docker network ..." commands | -| `"build\*"` | All "docker build ..." commands | -| `"system\*"` | All "docker system ..." commands | - -### Command blocking example - -When a blocked command is executed: - -```console -/ # docker push myimage -Error response from daemon: enhanced container isolation: docker command "/v1.43/images/myimage/push?tag=latest" is blocked; if you wish to allow it, configure the docker socket command list in the Docker Desktop settings. -``` - -## Common configuration examples - -### Testcontainers setup - -For Java/Python testing with Testcontainers: - -```json -"dockerSocketMount": { - "imageList": { - "images": [ - "docker.io/testcontainers/ryuk:*", - "testcontainers/*:*" - ] - }, - "commandList": { - "type": "deny", - "commands": ["push", "build"] - } -} -``` - -### CI/CD pipeline tools - -For controlled CI/CD container management: - -```json -"dockerSocketMount": { - "imageList": { - "images": [ - "docker:cli", - "your-registry.com/ci-tools/*:*" - ] - }, - "commandList": { - "type": "allow", - "commands": ["ps", "container*", "image*"] - } -} -``` - -### Development environments - -For local development with Docker-in-Docker: - -```json -"dockerSocketMount": { - "imageList": { - "images": [ - "docker:dind", - "docker:cli" - ] - }, - "commandList": { - "type": "deny", - "commands": ["system*"] - } -} -``` - -## Security recommendations - -### Image allowlist best practices - -- Be restrictive: Only allow images you absolutely trust and need -- Use wildcards carefully: Tag wildcards (`*`) are convenient but less secure than specific tags -- Regular reviews: Periodically review and update your allowlist -- Digest pinning: Use digest references for maximum security in critical environments - -### Command restrictions - -- Default to deny: Start with a deny list blocking dangerous commands like `push` and `build` -- Principle of least privilege: Only allow commands your tools actually need -- Monitor usage: Track which commands are being blocked to refine your configuration - -### Monitoring and maintenance - -- Regular validation: Test your configuration after Docker Desktop updates, as image digests may change. -- Handle digest mismatches: If allowed images are unexpectedly blocked: - ```console - $ docker image rm - $ docker pull - ``` - -This resolves digest mismatches when upstream images are updated. - -## Next steps - -- Review [Enhanced Container Isolation limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md). -- Review [Enhanced Container Isolation FAQs](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/faq.md). diff --git a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/faq.md b/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/faq.md deleted file mode 100644 index 3dee031d634c..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/faq.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Enhanced Container Isolation FAQs -linkTitle: FAQs -description: Frequently asked questions about Enhanced Container Isolation -keywords: enhanced container isolation, faq, troubleshooting, docker desktop -toc_max: 2 -aliases: - - /security/for-admins/hardened-desktop/enhanced-container-isolation/faq/ -weight: 40 ---- - -{{< summary-bar feature_name="Hardened Docker Desktop" >}} - -This page answers common questions about Enhanced Container Isolation (ECI) that aren't covered in the main documentation. - -## Do I need to change the way I use Docker when ECI is switched on? - -No. ECI works automatically in the background by creating more secure containers. You can continue using all your existing Docker commands, workflows, and development tools without any changes. - -## Do all container workloads work well with ECI? - -Most container workloads run without issues when ECI is turned on. However, some advanced workloads that require specific kernel-level access may not work. For details about which workloads are affected, see [ECI limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md). - -## Why not just restrict usage of the `--privileged` flag? - -Privileged containers serve legitimate purposes like Docker-in-Docker, Kubernetes-in-Docker, and accessing hardware devices. ECI provides a better solution by allowing these advanced workloads to run securely while preventing them from compromising the Docker Desktop VM. - -## Does ECI affect container performance? - -ECI has minimal impact on container performance. The only exception is containers that perform many `mount` and `umount` system calls, as these are inspected by the Sysbox runtime for security. Most development workloads see no noticeable performance difference. - -## Can I override the container runtime with ECI turned on? - - -No. When ECI is turned on, all containers use the Sysbox runtime regardless of any `--runtime` flags: - -```console -$ docker run --runtime=runc alpine echo "test" -# This still uses sysbox-runc, not runc -``` - -The `--runtime` flag is ignored to prevent users from bypassing ECI security by running containers as true root in the Docker Desktop VM. - -## Does ECI protect containers created before turning it on? - -No. ECI only protects containers created after it's turned on. Remove existing containers before turning on ECI: - -```console -$ docker stop $(docker ps -q) -$ docker rm $(docker ps -aq) -``` - -For more details, see [Enable Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci.md). - -## Which containers does ECI protect? - -ECI protection varies by container type and Docker Desktop version: - -### Always protected - -- Containers created with `docker run` and `docker create` -- Containers using the `docker-container` build driver -- Kubernetes with the Kind provisioner - -### Platform dependent - -- Docker Build: Protected in Docker Desktop for Mac, Linux, and Windows with Hyper-V backend - -### Not protected - -- Docker Extensions -- Docker Debug containers -- Kubernetes with Kubeadm provisioner - -For complete details, see [ECI limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md). - -## Can I mount the Docker socket with ECI turned on? - -By default, no. ECI blocks Docker socket bind mounts for security. However, you can configure exceptions for trusted images like Testcontainers. - -For configuration details, see [Configure Docker socket exceptions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md). - -## What bind mounts does ECI restrict? - -ECI restricts bind mounts of Docker Desktop VM directories but allows host directory mounts configured in Docker Desktop Settings. diff --git a/content/manuals/enterprise/security/hardened-desktop/registry-access-management.md b/content/manuals/enterprise/security/hardened-desktop/registry-access-management.md deleted file mode 100644 index b452b10b7c3e..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/registry-access-management.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Registry Access Management -description: Control access to approved container registries with Registry Access Management for secure Docker Desktop usage -keywords: registry access management, container registry, security controls, docker business, admin controls -tags: [admin] -aliases: - - /admin/organization/registry-access/ - - /security/for-admins/registry-access-management/ - - /security/for-admins/hardened-desktop/registry-access-management/ -weight: 40 ---- - -{{< summary-bar feature_name="Registry access management" >}} - -Registry Access Management (RAM) lets administrators control which container registries developers can access through Docker Desktop. This DNS-level filtering ensures developers only pull and push images from approved registries, improving supply chain security. - -RAM works with all registry types including cloud services, on-premises registries, and registry mirrors. You can allow any hostname or domain, but must include redirect domains (like `s3.amazonaws.com` for some registries) in your allowlist. - -## Supported registries - -Registry Access Management works with any container registry, including: - -- Docker Hub (allowed by default) -- Cloud registries: Amazon ECR, Google Artifact Registry, Azure Container Registry -- Git-based registries: GitHub Container Registry, GitLab Container Registry -- On-premises solutions: Nexus, Artifactory, Harbor -- Registry mirrors: Including Docker Hub mirrors - -## Prerequisites - -Before configuring Registry Access Management, you must: - -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). Registry Access Management only takes effect when users are signed in to Docker Desktop with organization credentials. -- Use [personal access tokens (PATs)](/manuals/security/access-tokens.md) for authentication (Organization access tokens aren't supported) -- Have a Docker Business subscription - -## Configure registry permissions - -To configure registry permissions: - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **Registry access**. -1. Use the **toggle** to enable registry access. By default, Docker Hub is enabled -in the registry list. -1. To add additional registries, select **Add registry** and provide -a **Registry address** and **Registry nickname**. -1. Select **Create**. You can add up to 100 registries. -1. Verify your registry appears in the registry list and select **Save changes**. - >[!NOTE] - > - > Policy changes can take up to 24 hours to propagate. To apply changes immediately, ask developers to sign out and back in to Docker Desktop. - -If a developer belongs to multiple organizations with different RAM policies, only the policy for the first organization in the configuration file is enforced. - -> [!TIP] -> -> RAM restrictions also apply to Dockerfile `ADD` instructions that fetch content via URL. Include trusted registry domains in your allowlist when using `ADD` with URLs. -> -> RAM is designed for container registries, not general-purpose URLs like package mirrors or storage services. Adding too many domains may cause errors or hit system limits. - - -## Verify restrictions are working - -After users sign in to Docker Desktop with their organization credentials, Registry Access Management takes effect immediately. - -When users try to pull from a blocked registry: - -```console -$ docker pull blocked-registry.com/image:tag -Error response from daemon: registry access to blocked-registry.com is not allowed -``` - -Allowed registry access works normally: - -```console -$ docker pull allowed-registry.com/image:tag -# Pull succeeds -``` - -Registry restrictions apply to all Docker operations including pulls, pushes, -and builds that reference external registries. - -## Registry limits and platform constraints - -Registry Access Management has these limits and platform-specific behaviors: - -- Maximum allowlist size: 100 registries or domains per organization -- DNS-based filtering: Restrictions work at the hostname level, not IP addresses -- Redirect domains required: Must include all domains a registry redirects to (CDN endpoints, storage services) -- Windows containers: Windows image operations aren't restricted by default. Turn on **Use proxy for Windows Docker daemon** in Docker Desktop settings to apply restrictions -- WSL 2 requirements: Requires Linux kernel 5.4 or later, restrictions apply to all WSL 2 distributions - -## Build and deployment restrictions - -These scenarios are not restricted by Registry Access Management: - -- Docker buildx with Kubernetes driver -- Docker buildx with custom Docker-container driver -- Some Docker Debug and Kubernetes image pulls (even if Docker Hub is blocked) -- Images previously cached by registry mirrors may still be blocked if the source registry is restricted - -## Security bypass considerations - -Users can potentially bypass Registry Access Management through: - -- Local proxies or DNS manipulation -- Signing out of Docker Desktop (unless sign-in is enforced) -- Network-level modifications outside Docker Desktop's control - -To maximize security effectiveness: - -- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) to prevent bypass through sign-out -- Implement additional network-level controls for complete protection -- Use Registry Access Management as part of a broader security strategy - -## Registry allowlist best practices - -- Include all registry domains: Some registries redirect to multiple -domains. For AWS ECR, include: - - ```text - your-account.dkr.ecr.us-west-2.amazonaws.com - amazonaws.com - s3.amazonaws.com - ``` - -- Practice regular allowlist maintenance: - - Remove unused registries periodically - - Add newly approved registries as needed - - Update domain names that may have changed - - Monitor registry usage through Docker Desktop analytics -- Test configuration changes: - - Verify registry access after making allowlist updates - - Check that all necessary redirect domains are included - - Ensure development workflows aren't disrupted - - Combine with [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md) for comprehensive protection - \ No newline at end of file diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/_index.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/_index.md deleted file mode 100644 index a31e8602ef27..000000000000 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/_index.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -description: Understand how Settings Management works, who it's for, and the benefits it provides -keywords: Settings Management, rootless, docker desktop, hardened desktop, admin control, enterprise -tags: [admin] -title: Settings Management -linkTitle: Settings Management -aliases: - - /security/for-admins/hardened-desktop/settings-management/ -weight: 10 ---- - -{{< summary-bar feature_name="Hardened Docker Desktop" >}} - -Settings Management lets administrators configure and enforce Docker Desktop settings across end-user machines. It helps maintain consistent configurations and enhances security within your organization. - -## Who should use Settings Management? - -Settings Management is designed for organizations that: - -- Need centralized control over Docker Desktop configurations -- Want to standardize Docker Desktop environments across teams -- Operate in regulated environments and must enforce compliance policies - -## How Settings Management works - -Administrators can define settings using one of these methods: - -- [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md): Create and assign settings policies through the - Docker Admin Console. This provides a web-based interface for managing settings - across your organization. -- [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md): Place a configuration file on the - user's machine to enforce settings. This method works well for automated - deployments and scripted installations. - -Enforced settings override user-defined configurations and can't be modified by developers. - -## Configurable settings - -Settings Management supports a wide range of Docker Desktop features, including: - -- Proxy configurations -- Network settings -- Container isolation options -- Registry access controls -- Resource limits -- Security policies -- Cloud policies - -For a complete list of settings you can enforce, see the [Settings reference](/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md). - -## Policy precedence - -When multiple policies exist, Docker Desktop applies them in this order: - -1. User-specific policies: Highest priority -1. Organization default policy: Applied when no user-specific policy exists -1. Local `admin-settings.json` file: Lowest priority, overridden by Admin Console policies -1. [Configuration profiles](/manuals/enterprise/security/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) when used to control proxy settings - -## Set up Settings Management - -You can create settings management policies at any time, but your organization needs to verify a domain before the policies take effect. - -1. Check that you have [added and verified](/manuals/enterprise/security/domain-management.md#add-and-verify-a-domain) your organization's domain. -2. [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) to - ensure all developers authenticate with your organization. -3. Choose a configuration method: - - Use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json`. - - Manually create and configure the [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md). - - Create a settings policy in the [Docker Admin Console](configure-admin-console.md). - -After configuration, developers receive the enforced settings when they: - -- Quit and relaunch Docker Desktop, then sign in -- Launch and sign in to Docker Desktop for the first time - -> [!NOTE] -> -> Docker Desktop doesn't automatically prompt users to restart or re-authenticate after a settings change. You may need to communicate these requirements to your developers. - -## Developer experience - -When settings are enforced: - -- Settings options appear grayed out in Docker Desktop and can't be modified through the Dashboard, CLI, or configuration files -- If Enhanced Container Isolation is enabled, developers can't use privileged containers or similar methods to alter enforced settings within the Docker Desktop Linux VM - -This ensures consistent environments while maintaining a clear visual indication of which settings are managed by administrators. - -## View applied settings - -When administrators apply Settings Management policies, Docker Desktop greys out most enforced settings in the GUI. - -The Docker Desktop GUI doesn't currently display all centralized settings, -particularly Enhanced Container Isolation (ECI) settings that administrators -apply via the Admin Console. - -As a workaround, you can check the `settings-store.json` file to view all -applied settings: - -- Mac: `~/Library/Application Support/Docker/settings-store.json` -- Windows: `%APPDATA%\Docker\settings-store.json` -- Linux: `~/.docker/desktop/settings-store.json` - -The `settings-store.json` file contains all settings, including those that -may not appear in the Docker Desktop GUI. - -## Limitations - -Settings Management has the following limitations: - -- Doesn't work in air-gapped or offline environments -- Not compatible with environments that restrict authentication with Docker Hub - -## Next steps - -Get started with Settings Management: - -- [Configure Settings Management with the `admin-settings.json` file](configure-json-file.md) -- [Configure Settings Management with the Docker Admin Console](configure-admin-console.md) diff --git a/content/manuals/enterprise/security/images/jit-disabled-flow.svg b/content/manuals/enterprise/security/images/jit-disabled-flow.svg deleted file mode 100644 index dcc425c5f367..000000000000 --- a/content/manuals/enterprise/security/images/jit-disabled-flow.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - Account exists in Docker Hub?Update profile (if needed)SSO sign inPending invites to the SSO org?Is the user in an SSO organization?Create new accountAccept invite and add user to SSO orgSSO successfulUser is not authorized to access orgYesNoNoYesNoYes \ No newline at end of file diff --git a/content/manuals/enterprise/security/images/jit-enabled-flow.svg b/content/manuals/enterprise/security/images/jit-enabled-flow.svg deleted file mode 100644 index e7f65d7592e8..000000000000 --- a/content/manuals/enterprise/security/images/jit-enabled-flow.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - Account exists in Docker Hub?Update profile (if needed)SSO sign inIdP Group mapping?Is the user in an SSO organization?Create new accountAdd user to org/groups according to IdPSSO successfulAdd user to default org/groupsYesNoNoYesNoYes \ No newline at end of file diff --git a/content/manuals/enterprise/security/provisioning/_index.md b/content/manuals/enterprise/security/provisioning/_index.md deleted file mode 100644 index 923731988856..000000000000 --- a/content/manuals/enterprise/security/provisioning/_index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -description: Learn about provisioning users for your SSO configuration. -keywords: provision users, provisioning, JIT, SCIM, group mapping, sso, docker admin, admin, security -title: Provision users -linkTitle: Provision -weight: 20 -aliases: - - /security/for-admins/provisioning/ -grid: - - title: "SCIM provisioning" - description: "Enable continuous user data synchronization between your IdP and Docker. Best for larger organizations." - icon: arrow-path - link: "scim/" - - title: "Just-in-Time (JIT) provisioning" - description: "Set up automatic user creation on first sign-in. Ideal for smaller teams with minimal setup requirements." - icon: clock - link: "just-in-time/" - - title: "Auto-provisioning" - description: "Associate members to an organization when email addresses match a verified domain." - icon: user-group - link: "auto-provisioning/" ---- - -{{< summary-bar feature_name="SSO" >}} - -After configuring your SSO connection, the next step is to provision users. This process ensures that users can access your organization through automated user management. - -This page provides an overview of user provisioning and the supported provisioning methods. - -## What is provisioning? - -Provisioning helps manage users by automating tasks like account creation, updates, and deactivation based on data from your identity provider (IdP). There are several methods for user provisioning, each offering benefits for different organizational needs: - -| Provisioning method | Description | Default setting in Docker | Recommended for | -| :--- | :--- | :------------- | :--- | -| System for Cross-domain Identity Management (SCIM) | Continuously syncs user data between your IdP and Docker, ensuring user attributes remain updated without manual intervention | Disabled by default | Larger organizations or environments with frequent changes in user information or roles | -| Group mapping | Maps user groups from your IdP to specific roles and permissions within Docker, enabling fine-grained access control based on group membership | Disabled by default | Organizations requiring strict access control and role-based user management | -| Just-in-Time (JIT) | Automatically creates and provisions user accounts when they first sign in via SSO | Enabled by default | Organizations needing minimal setup, smaller teams, or low-security environments | -| Auto-provision | Adds users when email addresses match a verified domain | Disabled by default | Orgs without SSO that need to add existing Docker users by domain | - -## Default provisioning setup - -By default, Docker enables JIT provisioning when you configure an SSO connection. With JIT enabled, user accounts are automatically created the first time a user signs in using your SSO flow. - -JIT provisioning may not provide sufficient control or security for some organizations. In such cases, SCIM or group mapping can be configured to give administrators more control over user access and attributes. - -## SSO attributes - -When a user signs in through SSO, Docker obtains several attributes from your IdP to manage the user's identity and permissions. These attributes include: - -- Email address: The unique identifier for the user -- Full name: The user's complete name -- Groups: Optional. Used for group-based access control -- Docker Org: Optional. Specifies the organization the user belongs to -- Docker Team: Optional. Defines the team the user belongs to within the organization -- Docker Role: Optional. Determines the user's permissions within Docker -- Docker session minutes: Optional. Sets the session duration before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If not provided, default session timeouts apply - -> [!NOTE] -> -> Default session timeouts apply when Docker session minutes is not specified. Docker Desktop sessions expire after 90 days or 30 days of inactivity. Docker Hub and Docker Home sessions expire after 24 hours. - -## SAML attribute mapping - -If your organization uses SAML for SSO, Docker retrieves these attributes from the SAML assertion message. Different IdPs may use different names for these attributes. - -| SSO Attribute | SAML Assertion Message Attributes | -| :--- | :--- | -| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` | -| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` | -| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` | -| Docker Org (optional) | `dockerOrg` | -| Docker Team (optional) | `dockerTeam` | -| Docker Role (optional) | `dockerRole` | -| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer > 0 | - -## Next steps - -Choose the provisioning method that best fits your organization's needs: - -{{< grid >}} \ No newline at end of file diff --git a/content/manuals/enterprise/security/provisioning/auto-provisioning.md b/content/manuals/enterprise/security/provisioning/auto-provisioning.md deleted file mode 100644 index b573cbfc55e7..000000000000 --- a/content/manuals/enterprise/security/provisioning/auto-provisioning.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Auto-provisioning -linkTitle: Auto-provision -description: Auto-provision users by associating members to your organization when email addresses match a verified domain. -keywords: user provisioning, just-in-time provisioning, JIT, autoprovision, Docker Admin, admin, security -weight: 30 ---- - -Auto-provisioning automatically adds users to your organization when they sign in with email addresses that match your verified domains. You must verify a domain before enabling auto-provisioning. - -> [!IMPORTANT] -> -> For domains that are part of an SSO connection, Just-in-Time (JIT) provisioning takes precedence over auto-provisioning when adding users to an organization. - -### Overview - -When auto-provisioning is enabled for a verified domain: - -- Users who sign in to Docker with matching email addresses are automatically added to your organization. -- Auto-provisioning only adds existing Docker users to your organization, it doesn't create new accounts. -- Users experience no changes to their sign-in process. -- Company and organization owners receive email notifications when new users are added. -- You may need to [manage seats](/manuals/admin/organization/manage/manage-seats.md) to accommodate new users. - -### Enable auto-provisioning - -Auto-provisioning is configured per domain. To enable it: - -1. Sign in to [Docker Home](https://app.docker.com) and select - your company or organization. -1. Select **Admin Console**, then **Domain management**. -1. Select the **Actions menu** next to the domain you want to enable - auto-provisioning for. -1. Select **Enable auto-provisioning**. -1. Optional. If enabling auto-provisioning at the company level, select an - organization. -1. Select **Enable** to confirm. - -The **Auto-provisioning** column will update to **Enabled** for the domain. - -### Disable auto-provisioning - -To disable auto-provisioning for a user: - -1. Sign in to [Docker Home](https://app.docker.com) and select - your organization. If your organization is part of a company, select the company - and configure the domain for the organization at the company level. -1. Select **Admin Console**, then **Domain management**. -1. Select the **Actions menu** next to your domain. -1. Select **Disable auto-provisioning**. -1. Select **Disable** to confirm. - -## Next steps - -To choose a different method to provision users, you can set up: - -- [SCIM provisioning](/manuals/enterprise/security/provisioning/scim/_index.md) for advanced user management. -- [Group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md) to assign users to teams automatically. diff --git a/content/manuals/enterprise/security/provisioning/just-in-time.md b/content/manuals/enterprise/security/provisioning/just-in-time.md deleted file mode 100644 index b54dd58bfde9..000000000000 --- a/content/manuals/enterprise/security/provisioning/just-in-time.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -description: Learn how Just-in-Time provisioning works with your SSO connection. -keywords: user provisioning, just-in-time provisioning, JIT, autoprovision, Docker Admin, admin, security -title: Just-in-Time provisioning -linkTitle: Just-in-Time -weight: 20 -aliases: - - /security/for-admins/provisioning/just-in-time/ ---- - -{{< summary-bar feature_name="SSO" >}} - -Just-in-Time (JIT) provisioning streamlines user onboarding by automatically creating and updating user accounts during SSO authentication. This eliminates manual account creation and ensures users have immediate access to your organization's resources. JIT verifies that users belong to the organization and assigns them to the appropriate teams based on your identity provider (IdP) configuration. When you create your SSO connection, JIT provisioning is turned on by default. - -This page explains how JIT provisioning works, SSO authentication flows, and how to disable JIT provisioning. - -## Prerequisites - -Before you begin, you must have: - -- SSO configured for your organization -- Administrator access to Docker Home and your identity provider - -## SSO authentication with JIT provisioning enabled - -When a user signs in with SSO and you have JIT provisioning enabled, the following steps occur automatically: - -1. The system checks if a Docker account exists for the user's email address. - - If an account exists: The system uses the existing account and updates the user's full name if necessary. - - If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform. - -2. The system checks for any pending invitations to the SSO organization. - - Invitation found: The invitation is automatically accepted. - - Invitation includes a specific group: The user is added to that group within the SSO organization. - -3. The system verifies if the IdP has shared group mappings during authentication. - - Group mappings provided: The user is assigned to the relevant organizations and teams. - - No group mappings provided: The system checks if the user is already part of the organization. If not, the user is added to the default organization and team configured in the SSO connection. - -The following graphic provides an overview of SSO authentication with JIT enabled: - -![JIT provisioning enabled workflow](../images/jit-enabled-flow.svg) - -## SSO authentication with JIT provisioning disabled - -When JIT provisioning is disabled, the following actions occur during SSO authentication: - -1. The system checks if a Docker account exists for the user's email address. - - If an account exists: The system uses the existing account and updates the user's full name if necessary. - - If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform. - -2. The system checks for any pending invitations to the SSO organization. - - Invitation found: If the user is a member of the organization or has a pending invitation, sign-in is successful, and the invitation is automatically accepted. - - No invitation found: If the user is not a member of the organization and has no pending invitation, the sign-in fails, and an `Access denied` error appears. The user must contact an administrator to be invited to the organization. - -With JIT disabled, group mapping is only available if you have [SCIM enabled](scim/#enable-scim-in-docker). If SCIM is not enabled, users won't be auto-provisioned to groups. - -The following graphic provides an overview of SSO authentication with JIT disabled: - -![JIT provisioning disabled workflow](../images/jit-disabled-flow.svg) - -## Disable JIT provisioning - -> [!WARNING] -> -> Disabling JIT provisioning may disrupt your users' access and workflows. With JIT disabled, users will not be automatically added to your organization. Users must already be a member of the organization or have a pending invitation to successfully sign in through SSO. To auto-provision users with JIT disabled, [use SCIM](./scim.md). - -You may want to disable JIT provisioning for reasons such as the following: - -- You have multiple organizations, have SCIM enabled, and want SCIM to be the source of truth for provisioning -- You want to control and restrict usage based on your organization's security configuration, and want to use SCIM to provision access - -Users are provisioned with JIT by default. If you enable SCIM, you can disable JIT: - -1. Go to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Action** icon, then select **Disable JIT provisioning**. -1. Select **Disable** to confirm. - -## Next steps - -- Configure [SCIM provisioning](/manuals/enterprise/security/provisioning/scim/_index.md) for advanced user management. -- Set up [group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md) to automatically assign users to teams. -- Review [Troubleshoot provisioning](/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/enterprise/security/provisioning/scim/_index.md b/content/manuals/enterprise/security/provisioning/scim/_index.md deleted file mode 100644 index ace0770e759d..000000000000 --- a/content/manuals/enterprise/security/provisioning/scim/_index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: SCIM overview -linkTitle: SCIM -weight: 10 -description: Learn how System for Cross-domain Identity Management works and how to set it up. -keywords: SCIM, SSO, user provisioning, de-provisioning, role mapping, assign users -aliases: - - /security/for-admins/scim/ - - /security/for-admins/provisioning/scim/ ---- - -{{< summary-bar feature_name="SSO" >}} - -Automate user management for your Docker organization using System for -Cross-domain Identity Management (SCIM). SCIM automatically provisions and -de-provisions users, synchronizes team memberships, and keeps your Docker -organization in sync with your identity provider. - -This page shows you how to automate user provisioning and de-provisioning for -Docker using SCIM. - -## Prerequisites - -Before you begin, you must have: - -- SSO configured for your organization -- Administrator access to Docker Home and your identity provider - -## How SCIM works - -SCIM automates user provisioning and de-provisioning for Docker through your -identity provider. After you enable SCIM, any user assigned to your -Docker application in your identity provider is automatically provisioned and -added to your Docker organization. When a user is removed from the Docker -application in your identity provider, SCIM deactivates and removes them from -your Docker organization. - -In addition to provisioning and removal, SCIM also syncs profile updates like -name changes made in your identity provider. You can use SCIM alongside Docker's -default Just-in-Time (JIT) provisioning or on its own with JIT disabled. - -SCIM automates: - -- Creating users -- Updating user profiles -- Removing and deactivating users -- Re-activating users -- Group mapping - -> [!NOTE] -> -> SCIM only manages users provisioned through your identity provider after -> SCIM is enabled. It cannot remove users who were manually added to your Docker -> organization before SCIM was set up. -> -> To remove those users, delete them manually from your Docker organization. -> For more information, see -> [Manage organization members](/manuals/admin/organization/manage/members.md). - -## Next steps - -- [Migrate JIT to SCIM](/manuals/enterprise/security/provisioning/scim/migrate-scim.md) if users were provisioned with Just-in-Time (JIT) before you enabled SCIM. -- [Group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md) to sync identity provider groups with members. -- [Troubleshoot provisioning](/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md) for SCIM, JIT, and attribute issues. diff --git a/content/manuals/enterprise/security/provisioning/scim/group-mapping.md b/content/manuals/enterprise/security/provisioning/scim/group-mapping.md deleted file mode 100644 index 308cad4a8e7e..000000000000 --- a/content/manuals/enterprise/security/provisioning/scim/group-mapping.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Group mapping -description: Automate team membership by syncing identity provider groups with Docker Teams -keywords: Group Mapping, SCIM, Docker Admin, admin, security, team management, user provisioning, identity provider -aliases: -- /admin/company/settings/group-mapping/ -- /admin/organization/security-settings/group-mapping/ -- /security/for-admins/group-mapping/ -- /security/for-admins/provisioning/scim/group-mapping/ -- /enterprise/security/provisioning/group-mapping/ -weight: 20 ---- - -{{< summary-bar feature_name="SSO" >}} - -Group mapping automatically synchronizes user groups from your identity provider (IdP) with teams in your Docker organization. For example, when you add a developer to the "backend-team" group in your IdP, they're automatically added to the corresponding team in Docker - -This page explains how group mapping works, and how to set up group mapping. - -> [!TIP] -> -> Group mapping is ideal for adding users to multiple organizations or multiple teams within one organization. If you don't need to set up multi-organization or multi-team assignment, SCIM [user-level attributes](provision-scim.md#set-up-role-mapping) may be a better fit for your needs. - -## Prerequisites - -Before you begin, you must have: - -- SSO configured for your organization -- Administrator access to Docker Home and your identity provider - -## How group mapping works - -Group mapping keeps your Docker Teams synchronized with your IdP groups through these key components: - -- Authentication flow: When users sign in through SSO, your IdP shares user attributes with Docker including email, name, and group memberships. -- Automatic updates: Docker uses these attributes to create or update user profiles and manage team assignments based on IdP group changes. -- Unique identification: Docker uses email addresses as unique identifiers, so each Docker account must have a unique email address. -- Team synchronization: Users' team memberships in Docker automatically reflect changes made in your IdP groups. - -## Set up group mapping - -Group mapping setup involves configuring your identity provider to share group -information with Docker. This requires: - -- Creating groups in your IdP using Docker's naming format -- Configuring attributes so your IdP sends group data during authentication -- Adding users to the appropriate groups -- Testing the connection to ensure groups sync properly - -You can use group mapping with SSO only, or with both SSO and SCIM for enhanced -user lifecycle management. - -### Group naming format - -Create groups in your IdP using the format: `organization:team`. - -For example: - -- For the "developers" team in the "moby" organization: `moby:developers` -- For multi-organization access: `moby:backend` and `whale:desktop` - -Docker creates teams automatically if they don't already exist when groups sync. - -### Supported attributes - -| Attribute | Description | -|:--------- | :---------- | -| `id` | Unique ID of the group in UUID format. This attribute is read-only. | -| `displayName` | Name of the group following the group mapping format: `organization:team`. | -| `members` | A list of users that are members of this group. | -| `members(x).value` | Unique ID of the user that is a member of this group. Members are referenced by ID. | - -## Configure group mapping with SSO - -Use group mapping with SSO connections that use the SAML authentication method. - -> [!NOTE] -> -> Group mapping with SSO isn't supported with the Azure AD (OIDC) authentication method. SCIM isn't required for these configurations. - -{{< tabs >}} -{{< tab name="Okta" >}} - -The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm) to verify. - -To set up group mapping: - -1. Sign in to Okta and open your application. -1. Navigate to the **SAML Settings** page for your application. -1. In the **Group Attribute Statements (optional)** section, configure like the following: - - **Name**: `groups` - - **Name format**: `Unspecified` - - **Filter**: `Starts with` + `organization:` where `organization` is the name of your organization - The filter option will filter out the groups that aren't affiliated with your Docker organization. -1. Create your groups by selecting **Directory**, then **Groups**. -1. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker. -1. Assign users to the group(s) that you create. - -The next time you sync your groups with Docker, your users will map to the Docker groups you defined. - -{{< /tab >}} -{{< tab name="Entra ID" >}} - -The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify. - -To set up group mapping: - -1. Sign in to Entra ID and open your application. -1. Select **Manage**, then **Single sign-on**. -1. Select **Add a group claim**. -1. In the Group Claims section, select **Groups assigned to the application** with the source attribute **Cloud-only group display names (Preview)**. -1. Select **Advanced options**, then the **Filter groups** option. -1. Configure the attribute like the following: - - **Attribute to match**: `Display name` - - **Match with**: `Contains` - - **String**: `:` -1. Select **Save**. -1. Select **Groups**, **All groups**, then **New group** to create your group(s). -1. Assign users to the group(s) that you create. - -The next time you sync your groups with Docker, your users will map to the Docker groups you defined. - -{{< /tab >}} -{{< /tabs >}} - -## Configure group mapping with SCIM - -Use group mapping with SCIM for more advanced user lifecycle management. Before you begin, make sure you [set up SCIM](./provision-scim.md#enable-scim) first. - -{{< tabs >}} -{{< tab name="Okta" >}} - -The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm) to verify. - -To set up your groups: - -1. Sign in to Okta and open your application. -1. Select **Applications**, then **Provisioning**, and **Integration**. -1. Select **Edit** to enable groups on your connection, then select **Push groups**. -1. Select **Save**. Saving this configuration will add the **Push Groups** tab to your application. -1. Create your groups by navigating to **Directory** and selecting **Groups**. -1. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker. -1. Assign users to the group(s) that you create. -1. Return to the **Integration** page, then select the **Push Groups** tab to open the view where you can control and manage how groups are provisioned. -1. Select **Push Groups**, then **Find groups by rule**. -1. Configure the groups by rule like the following: - - Enter a rule name, for example `Sync groups with Docker Hub` - - Match group by name, for example starts with `docker:` or contains `:` for multi-organization - - If you enable **Immediately push groups by rule**, sync will happen as soon as there's a change to the group or group assignments. Enable this if you don't want to manually push groups. - -Find your new rule under **By rule** in the **Pushed Groups** column. The groups that match that rule are listed in the groups table on the right-hand side. - -To push the groups from this table: - -1. Select **Group in Okta**. -1. Select the **Push Status** drop-down. -1. Select **Push Now**. - -{{< /tab >}} -{{< tab name="Entra ID" >}} - -The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify. - -Complete the following before configuring group mapping: - -1. Sign in to Entra ID and go to your application. -1. In your application, select **Provisioning**, then **Mappings**. -1. Select **Provision Microsoft Entra ID Groups**. -1. Select **Show advanced options**, then **Edit attribute list**. -1. Update the `externalId` type to `reference`, then select the **Multi-Value** checkbox and choose the referenced object attribute `urn:ietf:params:scim:schemas:core:2.0:Group`. -1. Select **Save**, then **Yes** to confirm. -1. Go to **Provisioning**. -1. Toggle **Provision Status** to **On**, then select **Save**. - -Next, set up group mapping: - -1. Go to the application overview page. -1. Under **Provision user accounts**, select **Get started**. -1. Select **Add user/group**. -1. Create your group(s) using the `organization:team` format. -1. Assign the group to the provisioning group. -1. Select **Start provisioning** to start the sync. - -To verify, select **Monitor**, then **Provisioning logs** to see that your groups were provisioned successfully. In your Docker organization, you can check that the groups were correctly provisioned and the members were added to the appropriate teams. - -{{< /tab >}} -{{< /tabs >}} - -Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP. - -> [!TIP] -> -> [Enable SCIM](provision-scim.md) to take advantage of automatic user provisioning and de-provisioning. If you don't enable SCIM users are only automatically provisioned. You have to de-provision them manually. - -## Next steps - -- [Assign roles](/manuals/enterprise/security/roles-and-permissions/core-roles.md) to members of your org. -- [Enforce sign in](/manuals/enterprise/security/enforce-sign-in.md), if needed. diff --git a/content/manuals/enterprise/security/provisioning/scim/migrate-scim.md b/content/manuals/enterprise/security/provisioning/scim/migrate-scim.md deleted file mode 100644 index a31124e83011..000000000000 --- a/content/manuals/enterprise/security/provisioning/scim/migrate-scim.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Migrate JIT to SCIM -linkTitle: Migrate -description: Learn how to migrate from just-in-time (JIT) to SCIM. -weight: 30 ---- - -If you already have users provisioned through Just-in-Time (JIT) and want to -enable full SCIM lifecycle management, you need to migrate them. Users -originally created by JIT cannot be automatically de-provisioned through SCIM, -even after SCIM is enabled. - -## Why migrate - -Organizations using JIT provisioning may encounter limitations with user -lifecycle management, particularly around de-provisioning. Migrating to SCIM -provides: - -- Automatic user de-provisioning when users leave your organization. This is - the primary benefit for large organizations that need full automation. -- Continuous synchronization of user attributes -- Centralized user management through your identity provider -- Enhanced security through automated access control - -> [!IMPORTANT] -> -> Users originally created through JIT provisioning cannot be automatically -> de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle -> management including automatic de-provisioning through your identity provider, -> you must manually remove these users so SCIM can re-create them with proper -> lifecycle management capabilities. - -This migration is most critical for larger organizations that require fully -automated user de-provisioning when employees leave the company. - -## Prerequisites - -Before migrating, ensure you have: - -- SCIM configured and tested in your organization -- A maintenance window for the migration - -> [!WARNING] -> -> This migration temporarily disrupts user access. Plan to perform this -> migration during a low-usage window and communicate the timeline to affected -> users. - -## Prepare for migration - -### Transfer ownership - -Before removing users, ensure that any repositories, teams, or organization -resources they own are transferred to another administrator or service account. -When a user is removed from the organization, any resources they own may -become inaccessible. - -1. Review repositories, organization resources, and team ownership for affected - users. -2. Transfer ownership to another administrator. - -> [!WARNING] -> -> If ownership is not transferred, repositories owned by removed users may -> become inaccessible when the user is removed. Ensure all critical resources -> are transferred before proceeding. - -### Verify identity provider configuration - -1. Confirm all JIT-provisioned users are assigned to the Docker application in - your identity provider. -2. Verify identity provider group to Docker Team mappings are configured and - tested. - -Users not assigned to the Docker application in your identity provider are not -re-created by SCIM after removal. - -### Export user records - -Export a list of JIT-provisioned users from Docker Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. -2. Select **Admin Console**, then **Members**. -3. Select **Export members** to download the member list as CSV for backup and - reference. - -Keep this CSV list of JIT-provisioned users as a rollback reference if needed. - -## Complete the migration - -### Disable JIT provisioning - -> [!IMPORTANT] -> -> Before disabling JIT, ensure SCIM is fully configured and tested in your -> organization. Do not disable JIT until you have verified SCIM is working -> correctly. - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Admin Console**, then **SSO and SCIM**. -3. In the SSO connections table, select the **Actions** menu for your connection. -4. Select **Disable JIT provisioning**. -5. Select **Disable** to confirm. - -Disabling JIT prevents new users from being automatically added through SSO -during the migration. - -### Remove JIT-origin users - -> [!IMPORTANT] -> -> Users originally created through JIT provisioning cannot be automatically -> de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle -> management including automatic de-provisioning through your identity provider, -> you must manually remove these users so SCIM can re-create them with proper -> lifecycle management capabilities. - -This step is most critical for large organizations that require fully automated -user de-provisioning when employees leave the company. - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Admin Console**, then **Members**. -3. Identify and remove JIT-provisioned users in manageable batches. -4. Monitor for any errors during removal. - -> [!TIP] -> -> To efficiently identify JIT users, compare the member list exported before -> SCIM was enabled with the current member list. Users who existed before SCIM -> was enabled were likely provisioned via JIT. - -### Verify SCIM re-provisioning - -After removing JIT users, SCIM automatically re-creates user accounts: - -1. In your identity provider system log, confirm "create app user" events for - Docker. -2. In Docker Admin Console, confirm users reappear with SCIM provisioning. -3. Verify users are added to the correct teams via group mapping. - -### Validate user access - -Perform post-migration validation: - -1. Select a subset of migrated users to test sign-in and access. -2. Verify team membership matches identity provider group assignments. -3. Confirm repository access is restored. -4. Test that de-provisioning works correctly by removing a test user from your - identity provider. - -Keep audit exports and logs for compliance purposes. - -## Migration results - -After completing the migration: - -- All users in your organization are SCIM-provisioned -- User de-provisioning works reliably through your identity provider -- No new JIT users are created -- Consistent identity lifecycle management is maintained - -## Troubleshoot migration issues - -If a user fails to reappear after removal: - -1. Check that the user is assigned to the Docker application in your identity - provider. -2. Verify SCIM is enabled in both Docker and your identity provider. -3. Trigger a manual SCIM sync in your identity provider. -4. Check provisioning logs in your identity provider for errors. - -For more troubleshooting guidance, see -[Troubleshoot provisioning](/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md). - -## Next steps - -- Set up [Group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md). -- [Assign roles](/manuals/enterprise/security/roles-and-permissions/core-roles.md) to members of your org. -- [Enforce sign in](/manuals/enterprise/security/enforce-sign-in.md), if needed. diff --git a/content/manuals/enterprise/security/provisioning/scim/provision-scim.md b/content/manuals/enterprise/security/provisioning/scim/provision-scim.md deleted file mode 100644 index 27058f15d0fc..000000000000 --- a/content/manuals/enterprise/security/provisioning/scim/provision-scim.md +++ /dev/null @@ -1,374 +0,0 @@ ---- -title: Set up SCIM provisioning -linkTitle: Setup -description: Learn how System for Cross-domain Identity Management works and how to set it up. -weight: 10 -aliases: - - /enterprise/security/provisioning/scim/ ---- - -{{< summary-bar feature_name="SSO" >}} - -## Supported attributes - -SCIM uses attributes (name, email, etc.) to sync user information between your -identity provider and Docker. Properly mapping these attributes in your identity -provider ensures that user provisioning works smoothly and prevents issues like -duplicate user accounts -when using single sign-on. - -Docker supports the following SCIM attributes: - -| Attribute | Description | -| :---------------- | :-------------------------------------------------------------------------------- | -| `userName` | User's primary email address, used as the unique identifier | -| `name.givenName` | User's first name | -| `name.familyName` | User's surname | -| `active` | Indicates if a user is enabled or disabled, set to "false" to de-provision a user | - -For additional details about supported attributes and SCIM, see -[Docker Hub API SCIM reference](/reference/api/hub/latest.md#tag/scim). - -> [!IMPORTANT] -> -> By default, Docker uses Just-in-Time (JIT) provisioning for SSO. If SCIM is -> enabled, JIT values still take precedence and will overwrite attribute values -> set by SCIM. To avoid conflicts, make sure your JIT attribute values match -> your SCIM values. -> -> Alternatively, you can disable JIT provisioning to rely solely on SCIM. -> For details, see [Just-in-Time](/manuals/enterprise/security/provisioning/just-in-time.md). - -## Enable SCIM in Docker - -To enable SCIM: - -1. Sign in to [Docker Home](https://app.docker.com). -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** icon for your - connection, then select **Setup SCIM**. -1. Copy the **SCIM Base URL** and **API Token** and paste the values into your - IdP. - -## Enable SCIM in your IdP - -The user interface for your identity provider may differ slightly from the -following steps. You can refer to the documentation for your identity provider -to verify. For additional details, see the documentation for your identity -provider: - -- [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm) -- [Entra ID/Azure AD SAML 2.0](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/user-provisioning) - -> [!NOTE] -> -> Microsoft does not currently support SCIM and OIDC in the same non-gallery -> application in Entra ID. This page provides a verified workaround using a -> separate non-gallery app for SCIM provisioning. While Microsoft does not -> officially document this setup, it is widely used and supported in practice. - -{{< tabs >}} -{{< tab name="Okta" >}} - -### Step one: Enable SCIM - -1. Sign in to Okta and select **Admin** to open the admin portal. -1. Open the application you created when you configured your SSO connection. -1. On the application page, select the **General** tab, then - **Edit App Settings**. -1. Enable SCIM provisioning, then select **Save**. -1. Navigate to the **Provisioning**, then select **Edit SCIM Connection**. -1. To configure SCIM in Okta, set up your connection using the following - values and settings: - - SCIM Base URL: SCIM connector base URL (copied from Docker Home) - - Unique identifier field for users: `email` - - Supported provisioning actions: **Push New Users** and - **Push Profile Updates** - - Authentication Mode: HTTP Header - - SCIM Bearer Token: HTTP Header Authorization Bearer Token - (copied from Docker Home) -1. Select **Test Connector Configuration**. -1. Review the test results and select **Save**. - -### Step two: Enable synchronization - -1. In Okta, select **Provisioning**. -1. Select **To App**, then **Edit**. -1. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. -1. Select **Save**. -1. Remove unnecessary mappings. The necessary mappings are: - - Username - - Given name - - Family name - - Email - -Next, [set up role mapping](#set-up-role-mapping). - -{{< /tab >}} -{{< tab name="Entra ID (OIDC)" >}} - -Microsoft does not support SCIM and OIDC in the same non-gallery application. -You must create a second non-gallery application in Entra ID for SCIM -provisioning. - -### Step one: Create a separate SCIM app - -1. In the Azure Portal, go to **Microsoft Entra ID** > - **Enterprise Applications** > **New application**. -1. Select **Create your own application**. -1. Name your application and choose - **Integrate any other application you don't find in the gallery**. -1. Select **Create**. - -### Step two: Configure SCIM provisioning - -1. In your new SCIM application, go to **Provisioning** > **Get started**. -1. Set **Provisioning Mode** to **Automatic**. -1. Under **Admin Credentials**: - - **Tenant URL**: Paste the **SCIM Base URL** from Docker Home. - - **Secret Token**: Paste the **SCIM API token** from Docker Home. -1. Select **Test Connection** to verify. -1. Select **Save** to store credentials. - -Next, [set up role mapping](#set-up-role-mapping). - -{{< /tab >}} -{{< tab name="Entra ID (SAML 2.0)" >}} - -1. In the Azure Portal, go to **Microsoft Entra ID** > - **Enterprise Applications**, and select your Docker SAML app. -1. Select **Provisioning** > **Get started**. -1. Set **Provisioning Mode** to **Automatic**. -1. Under **Admin Credentials**: - - **Tenant URL**: Paste the **SCIM Base URL** from Docker Home. - - **Secret Token**: Paste the **SCIM API token** from Docker Home. -1. Select **Test Connection** to verify. -1. Select **Save** to store credentials. - -Next, [set up role mapping](#set-up-role-mapping). - -{{< /tab >}} -{{< /tabs >}} - -## Set up role mapping - -You can assign [Docker roles](/manuals/enterprise/security/roles-and-permissions/_index.md) to -users by adding optional SCIM attributes in your IdP. These attributes override -default role and team values set in your SSO configuration. - -> [!NOTE] -> -> Role mappings are supported for both SCIM and Just-in-Time (JIT) -> provisioning. For JIT, role mapping applies only when the user is first -> provisioned. - -The following table lists the supported optional user-level attributes: - -| Attribute | Possible values | Notes | -| ------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dockerRole` | `member`, `editor`, or `owner` | If not set, the user defaults to the `member` role. Setting this attribute overrides the default.

For role definitions, see [Roles and permissions](/manuals/enterprise/security/roles-and-permissions/_index.md). | -| `dockerOrg` | Docker `organizationName` (e.g., `moby`) | Overrides the default organization configured in your SSO connection.

If unset, the user is provisioned to the default organization. If `dockerOrg` and `dockerTeam` are both set, the user is provisioned to the team within the specified organization. | -| `dockerTeam` | Docker `teamName` (e.g., `developers`) | Provisions the user to the specified team in the default or specified organization. If the team doesn't exist, it is automatically created.

You can still use [group mapping](group-mapping.md) to assign users to multiple teams across organizations. | - -The external namespace used for these attributes is: `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. -This value is required in your identity provider when creating custom SCIM attributes for Docker. - -{{< tabs >}} -{{< tab name="Okta" >}} - -### Step one: Set up role mapping in Okta - -1. Setup [SSO](/manuals/enterprise/security/single-sign-on/connect.md) and SCIM first. -1. In the Okta admin portal, go to **Directory**, select **Profile Editor**, - and then **User (Default)**. -1. Select **Add Attribute** and configure the values for the role, organization, - or team you want to add. Exact naming isn't required. -1. Return to the **Profile Editor** and select your application. -1. Select **Add Attribute** and enter the required values. The **External Name** - and **External Namespace** must be exact. - - The external name values for organization/team/role mapping are - `dockerOrg`, `dockerTeam`, and `dockerRole` respectively, as listed in the previous table. - - The external namespace is the same for all of them: - `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. -1. After creating the attributes, navigate to the top of the page and select - **Mappings**, then **Okta User to YOUR APP**. -1. Go to the newly created attributes and map the variable names to the external - names, then select **Save Mappings**. If you're using JIT provisioning, continue - to the following steps. -1. Navigate to **Applications** and select **YOUR APP**. -1. Select **General**, then **SAML Settings**, and **Edit**. -1. Select **Step 2** and configure the mapping from the user attribute to the - Docker variables. - -### Step two: Assign roles by user - -1. In the Okta Admin portal, select **Directory**, then **People**. -1. Select **Profile**, then **Edit**. -1. Select **Attributes** and update the attributes to the desired values. - -### Step three: Assign roles by group - -1. In the Okta Admin portal, select **Directory**, then **People**. -1. Select **YOUR GROUP**, then **Applications**. -1. Open **YOUR APPLICATION** and select the **Edit** icon. -1. Update the attributes to the desired values. - -If a user doesn't already have attributes set up, users who are added to the -group will inherit these attributes upon provisioning. - -{{< /tab >}} -{{< tab name="Entra ID/Azure AD (SAML 2.0 and OIDC)" >}} - -### Step one: Configure attribute mappings - -1. Complete the [SCIM provisioning setup](/manuals/enterprise/security/provisioning/scim/provision-scim.md#enable-scim-in-docker). -1. In the Azure Portal, open **Microsoft Entra ID** > - **Enterprise Applications**, and select your SCIM application. -1. Go to **Provisioning** > **Mappings** > - **Provision Azure Active Directory Users**. -1. Add or update the following mappings: - - `userPrincipalName` -> `userName` - - `mail` -> `emails.value` - - Optional. Map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the - [mapping methods](/manuals/enterprise/security/provisioning/scim/provision-scim.md#set-up-role-mapping). -1. Remove any unsupported attributes to prevent sync errors. -1. Optional. Go to **Mappings** > **Provision Azure Active Directory Groups**: - - If group provisioning causes errors, set **Enabled** to **No**. - - If enabling, test group mappings carefully. -1. Select **Save** to apply mappings. - -### Step two: Choose a role mapping method - -You can map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the -following methods: - -#### Expression mapping - -Use this method if you only need to assign Docker roles like `member`, `editor`, -or `owner`. - -1. In the **Edit Attribute** view, set the mapping type to **Expression**. -1. In the **Expression** field: - 1. If your App Roles match Docker roles exactly, use: - SingleAppRoleAssignment([appRoleAssignments]) - 1. If they don't match, use a switch expression: `Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")` -1. Set: - - **Target attribute**: `urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole` - - **Match objects using this attribute**: No - - **Apply this mapping**: Always -1. Save your changes. - -> [!WARNING] -> -> You can't use `dockerOrg` or `dockerTeam` with this method. Expression mapping -> is only compatible with one attribute. - -#### Direct mapping - -Use this method if you need to map multiple attributes (`dockerRole` + -`dockerTeam`). - -1. For each Docker attribute, choose a unique Entra extension attribute - (`extensionAttribute1`, `extensionAttribute2`, etc.). -1. In the **Edit Attribute** view: - - Set mapping type to **Direct**. - - Set **Source attribute** to your selected extension attribute. - - Set **Target attribute** to one of: - - `dockerRole: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole` - - `dockerOrg: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerOrg` - - `dockerTeam: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerTeam` - - Set **Apply this mapping** to **Always**. -1. Save your changes. - -To assign values, you'll need to use the Microsoft Graph API. - -### Step three: Assign users and groups - -For either mapping method: - -1. In the SCIM app, go to **Users and Groups** > **Add user/group**. -1. Select the users or groups to provision to Docker. -1. Select **Assign**. - -If you're using expression mapping: - -1. Go to **App registrations** > your SCIM app > **App Roles**. -1. Create App Roles that match Docker roles. -1. Assign users or groups to App Roles under **Users and Groups**. - -If you're using direct mapping: - -1. Go to [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) - and sign in as a tenant admin. -1. Use Microsoft Graph API to assign attribute values. Example PATCH request: - -```bash -PATCH https://graph.microsoft.com/v1.0/users/{user-id} -Content-Type: application/json - -{ - "extensionAttribute1": "owner", - "extensionAttribute2": "moby", - "extensionAttribute3": "developers" -} -``` - -> [!NOTE] -> -> You must use a different extension attribute for each SCIM field. - -{{< /tab >}} -{{< /tabs >}} - -See the documentation for your IdP for additional details: - -- [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) -- [Entra ID/Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application) - -## Test SCIM provisioning - -After completing role mapping, you can test the configuration manually. - -{{< tabs >}} -{{< tab name="Okta" >}} - -1. In the Okta admin portal, go to **Directory > People**. -1. Select a user you've assigned to your SCIM application. -1. Select **Provision User**. -1. Wait a few seconds, then check the Docker - [Admin Console](https://app.docker.com/admin) under **Members**. -1. If the user doesn't appear, review logs in **Reports > System Log** and - confirm SCIM settings in the app. - -{{< /tab >}} -{{< tab name="Entra ID/Azure AD (OIDC and SAML 2.0)" >}} - -1. In the Azure Portal, go to **Microsoft Entra ID** > **Enterprise Applications**, - and select your SCIM app. -1. Go to **Provisioning** > **Provision on demand**. -1. Select a user or group and choose **Provision**. -1. Confirm that the user appears in the Docker - [Admin Console](https://app.docker.com/admin) under **Members**. -1. If needed, check **Provisioning logs** for errors. - -{{< /tab >}} -{{< /tabs >}} - -## Disable SCIM - -If SCIM is disabled, any user provisioned through SCIM will remain in the -organization. Future changes for your users will not sync from your IdP. -User de-provisioning is only possible when manually removing the user from the -organization. - -To disable SCIM: - -1. Sign in to [Docker Home](https://app.docker.com). -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** icon. -1. Select **Disable SCIM**. - -## Next steps - -- Set up [Group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md). -- [Troubleshoot provisioning](/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md b/content/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md deleted file mode 100644 index 7076b90cfd83..000000000000 --- a/content/manuals/enterprise/security/provisioning/troubleshoot-provisioning.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Troubleshoot provisioning -linkTitle: Troubleshoot -description: Troubleshoot common user provisioning issues with SCIM and Just-in-Time provisioning -keywords: SCIM troubleshooting, user provisioning, JIT provisioning, group mapping, attribute conflicts -tags: [Troubleshooting] -toc_max: 2 -aliases: - - /enterprise/troubleshoot/troubleshoot-provisioning/ ---- - -This page helps troubleshoot common user provisioning issues including user roles, attributes, and unexpected account behavior with SCIM and Just-in-Time (JIT) provisioning. - -## SCIM attribute values are overwritten or ignored - -### Error message - -Typically, this scenario does not produce an error message in Docker or your -IdP. This issue usually surfaces as incorrect role or team assignment. - -### Causes - -- JIT provisioning is enabled, and Docker is using values from your IdP's - SSO sign in flow to provision the user, which overrides - SCIM-provided attributes. -- SCIM was enabled after the user was already provisioned via JIT, so SCIM - updates don't take effect. - -### Affected environments - -- Docker organizations using SCIM with SSO -- Users provisioned via JIT prior to SCIM setup - -### Steps to replicate - -1. Enable JIT and SSO for your Docker organization. -1. Sign in to Docker as a user via SSO. -1. Enable SCIM and set role/team attributes for that user. -1. SCIM attempts to update the user's attributes, but the role or team - assignment does not reflect changes. - -### Solutions - -#### Disable JIT provisioning (recommended) - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Select **Admin Console**, then **SSO and SCIM**. -1. Find the relevant SSO connection. -1. Select the **actions menu** and choose **Edit**. -1. Disable **Just-in-Time provisioning**. -1. Save your changes. - -With JIT disabled, Docker uses SCIM as the source of truth for user creation -and role assignment. - -**Keep JIT enabled and match attributes** - -If you prefer to keep JIT enabled: - -- Make sure your IdP's SSO attribute mappings match the values being sent - by SCIM. -- Avoid configuring SCIM to override attributes already set via JIT. - -This option requires strict coordination between SSO and SCIM attributes -in your IdP configuration. - -## SCIM updates don't apply to existing users - -### Causes - -User accounts were originally created manually or via JIT, and SCIM is not -linked to manage them. - -### Solution - -SCIM only manages users that it provisions. To allow SCIM to manage an -existing user: - -1. Remove the user manually from the Docker [Admin Console](https://app.docker.com/admin). -1. Trigger provisioning from your IdP. -1. SCIM will re-create the user with correct attributes. - -> [!WARNING] -> -> Deleting a user removes their resource ownership (e.g., repositories). -> Transfer ownership before removing the user. diff --git a/content/manuals/enterprise/security/roles-and-permissions/_index.md b/content/manuals/enterprise/security/roles-and-permissions/_index.md deleted file mode 100644 index e44efff4b449..000000000000 --- a/content/manuals/enterprise/security/roles-and-permissions/_index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Roles and permissions -linkTitle: Roles and permissions -description: Control access to content, registry, and organization management with Docker's role system -keywords: roles, permissions, custom roles, core roles, access control, organization management, docker hub, admin console, security -tags: [admin] -aliases: - - /admin/organization/roles/ - - /security/for-admins/roles-and-permissions/ - - /docker-hub/roles-and-permissions/ -grid: - - title: "Core roles" - description: Learn about Docker's built-in Member, Editor, and Owner roles with predefined permissions. - icon: shield-check - link: /enterprise/security/roles-and-permissions/core-roles/ - - title: "Custom roles" - description: Create tailored permission sets that match your organization's specific needs. - icon: adjustments-horizontal - link: /enterprise/security/roles-and-permissions/custom-roles/ -weight: 40 ---- - -{{< summary-bar feature_name="General admin" >}} - -Roles control what users can do in your Docker organization. When you invite users or create teams, you assign them roles that determine their permissions for repositories, teams, and organization settings. - -Docker provides two types of roles to meet different organizational needs: - -- [Core roles](/manuals/enterprise/security/roles-and-permissions/core-roles.md) with predefined permissions -- [Custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles.md) that you can tailor to your specific requirements - -## Docker roles - -### Core roles - -Core roles are Docker's built-in roles with predefined permission sets: - -- **Member**: Non-administrative role with basic access. Members can view other organization members and pull images from repositories they have access to. -- **Editor**: Partial administrative access. Editors can create, edit, and delete repositories, and manage team permissions for repositories. -- **Owner**: Full administrative access. Owners can manage all organization settings, including repositories, teams, members, billing, and security features. - -### Custom roles - -Custom roles allow you to create tailored permission sets by selecting specific permissions from categories like user management, team management, billing, and Hub permissions. Use custom roles when Docker's core roles don't fit your needs. - -## When to use each role - -Use core roles when: - -- Docker's predefined permission sets match your organizational structure -- You want simple, straightforward role assignments -- You're getting started with Docker organization management -- Your access control needs are standard and don't require fine-grained permissions - -Use custom roles when: - -- You need specific permission combinations not available in core roles -- You want to create specialized roles like billing administrators, security auditors, or repository managers -- You need department-specific access control -- You want to implement the principle of least privilege with precise permission grants - -## How roles work together - -You can assign users and teams either a core role or a custom role, but not both. However, roles work in combination with team permissions: - -1. **Role permissions**: Applied organization-wide (core or custom role). Custom roles can grant permissions to both organization-wide settings and repository access. -2. **Team permissions**: Additional repository-specific permissions when users are added to teams. This is a separate permission system from role-based permissions. - -This layered approach gives you flexibility to provide broad organizational access through roles and specific repository access through team memberships. - -## Next steps - -Choose the role type that best fits your organization's needs: - -{{< grid >}} diff --git a/content/manuals/enterprise/security/roles-and-permissions/core-roles.md b/content/manuals/enterprise/security/roles-and-permissions/core-roles.md deleted file mode 100644 index 9a0773c1fefe..000000000000 --- a/content/manuals/enterprise/security/roles-and-permissions/core-roles.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Core roles -description: Control access to content, registry, and organization management with roles in your organization. -keywords: members, teams, organization, company, roles, access, docker hub, admin console, security, permissions -aliases: - - /enterprise/security/roles-and-permissions/ ---- - -{{< summary-bar feature_name="General admin" >}} - -Core roles are Docker's built-in roles with predefined permission sets. -This page provides an overview of Docker's core roles and permissions for each role. - -## What are core roles? - -Docker organizations have three core roles: - -- **Member**: Non-administrative role with basic access. Members can view other organization members and pull images from repositories they have access to. -- **Editor**: Partial administrative access. Editors can create, edit, and delete repositories. They can also manage team permissions for repositories. -- **Owner**: Full administrative access. Owners can manage all organization settings, including repositories, teams, members, billing, and security features. - -A company owner has the same organization management permissions as an organization owner, but there are some content and registry permissions that company owners don't have (for example, repository pull/push). For more information, see [Company overview](/manuals/admin/company/_index.md). - -### Content and registry permissions - -These permissions apply organization-wide. - -| Permission | Member | Editor | Owner | -| :---------------------------------------------------- | :----- | :----- | :---- | -| Explore images and extensions | ✅ | ✅ | ✅ | -| Star, favorite, vote, and comment on content | ✅ | ✅ | ✅ | -| Pull images | ✅ | ✅ | ✅ | -| Create and publish an extension | ✅ | ✅ | ✅ | -| Become a Verified, Official, or Open Source publisher | ❌ | ❌ | ✅ | -| Edit and delete publisher repository logos | ❌ | ✅ | ✅ | -| Configure DVP analytics settings | ❌ | ✅ | ✅ | -| Observe content engagement as a publisher | ❌ | ❌ | ✅ | -| Create public and private repositories | ❌ | ✅ | ✅ | -| Disable public repositories | ❌ | ✅ | ✅ | -| Edit and delete repositories | ❌ | ✅ | ✅ | -| Manage tags | ❌ | ✅ | ✅ | -| View repository activity | ❌ | ❌ | ✅ | -| Set up Automated builds | ❌ | ❌ | ✅ | -| Edit build settings | ❌ | ❌ | ✅ | -| View teams | ✅ | ✅ | ✅ | -| Assign team permissions to repositories | ❌ | ✅ | ✅ | - -You can grant repository permissions to members -beyond their organization role: - -- Role permissions: Applied organization-wide (member or editor) -- Team permissions: Additional permissions for specific repositories - -To extend access to private repositories, assign a custom role to organization members or configure team permissions. - -### Organization management permissions - -| Permission | Member | Editor | Owner | -| :---------------------------------------------------------------- | :----- | :----- | :---- | -| Create teams | ❌ | ❌ | ✅ | -| Manage teams (including delete) | ❌ | ❌ | ✅ | -| Configure the organization's settings (including linked services) | ❌ | ❌ | ✅ | -| Add organizations to a company | ❌ | ❌ | ✅ | -| Invite members | ❌ | ❌ | ✅ | -| Manage members | ❌ | ❌ | ✅ | -| Manage member roles and permissions | ❌ | ❌ | ✅ | -| View member activity | ❌ | ❌ | ✅ | -| Export and reporting | ❌ | ❌ | ✅ | -| Image Access Management | ❌ | ❌ | ✅ | -| Registry Access Management | ❌ | ❌ | ✅ | -| Namespace access control | ❌ | ❌ | ✅ | -| Set up Single Sign-On (SSO) and SCIM | ❌ | ❌ | ✅ \* | -| Require Docker Desktop sign-in | ❌ | ❌ | ✅ \* | -| Manage billing information (for example, billing address) | ❌ | ❌ | ✅ | -| Manage payment methods (for example, credit card or invoice) | ❌ | ❌ | ✅ | -| View billing history | ❌ | ❌ | ✅ | -| Manage subscriptions | ❌ | ❌ | ✅ | -| Manage seats | ❌ | ❌ | ✅ | -| Upgrade and downgrade plans | ❌ | ❌ | ✅ | - -> [!TIP] -> -> If you want more granular access control, you can -> [upgrade to a Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsEnterpriseCoreRoles) -> for custom roles and advanced permissions. - -_\* If not part of a company_ - -### Docker Scout permissions - -| Permission | Member | Editor | Owner | -| :---------------------------------------------------- | :----- | :----- | :---- | -| View and compare analysis results | ✅ | ✅ | ✅ | -| Upload analysis records | ✅ | ✅ | ✅ | -| Activate and deactivate Docker Scout for a repository | ❌ | ✅ | ✅ | -| Create environments | ❌ | ❌ | ✅ | -| Manage registry integrations | ❌ | ❌ | ✅ | - -### Docker Build Cloud permissions - -| Permission | Member | Editor | Owner | -| -------------------------- | :----- | :----- | :---- | -| Use a cloud builder | ✅ | ✅ | ✅ | -| Create and remove builders | ✅ | ✅ | ✅ | -| Configure builder settings | ✅ | ✅ | ✅ | -| Buy minutes | ❌ | ❌ | ✅ | -| Manage subscription | ❌ | ❌ | ✅ | diff --git a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md b/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md deleted file mode 100644 index 44ba3adfd86d..000000000000 --- a/content/manuals/enterprise/security/roles-and-permissions/custom-roles.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Custom roles -description: Create tailored permission sets for your organization with custom roles -keywords: custom roles, permissions, access control, organization management, docker hub, admin console, security ---- - -{{< summary-bar feature_name="General admin" >}} - -Custom roles allow you to create tailored permission sets that match your -organization's specific needs. This page covers custom roles and steps -to create and manage them. - -## What are custom roles? - -Custom roles let you create tailored permission sets for your organization. You -can assign custom roles to individual users or teams. -Users and teams get either a core role or custom role, but not both. - -Use custom roles when Docker's core roles don't fit your needs. - -## Prerequisites - -To configure custom roles, you need owner permissions in your Docker -organization. - -## Create a custom role - -Before you can assign a custom role to users, you must create one in the -Admin Console: - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Admin Console**. -3. Under **User management**, select **Roles** > **Create role**. -4. Create a name and describe what the role is for: - - Provide a **Label** - - Enter a unique **Name** identifier (can't be changed later) - - Add an optional **Description** -5. Set permissions for the role by expanding permission categories and selecting - the checkboxes for permissions. For a full list of available permissions, see - the [custom roles permissions reference](#custom-roles-permissions-reference). -6. Select **Review** to review your custom roles configuration and see a summary - of selected permissions. -7. Select **Create**. - -With a custom role created, you can now [assign custom roles to users](#assign-custom-roles). - -## Edit a custom role - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Admin Console**. -3. Under **User management**, select **Roles**. -4. Find your custom role from the list, and select the **Actions menu**. -5. Select **Edit**. -6. You can edit the following custom role settings: - - Label - - Description - - Permissions -7. After you have finished editing, select **Save**. - -## Assign custom roles - -{{< tabs >}} -{{< tab name="Individual users" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Members**. -3. Locate the member you want to assign a custom role to, then select the - **Actions menu**. -4. In the drop-down, select **Change role**. -5. In the **Select a role** drop-down, select your custom role. -6. Select **Save**. - -{{< /tab >}} -{{< tab name="Bulk users" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Members**. -3. Use the checkboxes in the username column to select all users you want - to assign a custom role to. -4. Select **Change role**. -5. In the **Select a role** drop-down, select your custom role or a core role. -6. Select **Save**. - -{{< /tab >}} -{{< tab name="Teams" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Teams**. -3. Locate the team you want to assign a custom role to, then select - the **Actions menu**. -4. Select **Assign role**. -5. Select your custom role, then select **Assign**. - -The role column will update to the newly assigned role. - -{{< /tab >}} -{{< /tabs >}} - -## View role assignments - -To see which users and teams are assigned to roles: - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Admin Console**. -3. Under **User management**, select **Roles**. -4. In the roles list, view the **Users** and **Teams** columns to see - assignment counts. -5. Select a specific role to view its permissions and assignments in detail. - -## Reassign custom roles - -{{< tabs >}} -{{< tab name="Individual users" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Members**. -3. Locate the member you want to reassign, then select the **Actions menu**. -4. Select **Change role**. -5. In the **Select a role** drop-down, select the new role. -6. Select **Save**. - -{{< /tab >}} -{{< tab name="Bulk users" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Members**. -3. Use the checkboxes in the username column to select all users you want - to reassign. -4. Select **Change role**. -5. In the **Select a role** drop-down, select the new role. -6. Select **Save**. - -{{< /tab >}} -{{< tab name="Teams" >}} - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Teams**. -3. Locate the team, then select the **Actions menu**. -4. Select **Change role**. -5. In the pop-up window, select a role from the drop-down menu, then - select **Save**. - -{{< /tab >}} -{{< /tabs >}} - -## Delete a custom role - -Before deleting a custom role, you must reassign all users and teams to different roles. - -1. Sign in to [Docker Home](https://app.docker.com). -2. Select **Admin Console**. -3. Under **User management**, select **Roles**. -4. Find your custom role from the list, and select the **Actions menu**. -5. If the role has assigned users or teams: - - Navigate to the **Members** page and change the role for all users assigned to this custom role - - Navigate to the **Teams** page and reassign all teams that have this custom role -6. Once no users or teams are assigned, return to **Roles**. -7. Find your custom role and select the **Actions menu**. -8. Select **Delete**. -9. In the confirmation window, select **Delete** to confirm. - -## Custom roles permissions reference - -Custom roles are built by selecting specific permissions across different categories. The following tables list all available permissions you can assign to a custom role. - -### Organization management - -| Permission | Description | -| :-------------------------------- | :---------------------------------------------------------------------------------------------- | -| View teams | View teams and team members | -| Manage teams | Create, update, and delete teams and team members | -| Manage registry access | Control which registries members can access | -| Manage image access | Set policies for which images members can pull and use | -| Update organization information | Update organization information such as name and location | -| Member management | Manage organization members, invites, and roles | -| View custom roles | View existing custom roles and their permissions | -| Manage custom roles | Full access to custom role management and assignment | -| Manage organization access tokens | Create, update, and delete repositories in this org. Push/pull or registry actions not included | -| View activity logs | Access organization audit logs and activity history | -| View domains | View domains and domain audit settings | -| Manage domains | Manage verified domains and domain audit settings | -| View SSO and SCIM | View single sign-on and user provisioning configurations | -| Manage SSO and SCIM | Full access to SSO and SCIM management | -| Manage Desktop settings | Configure Docker Desktop settings policies and view usage reports | - -### Docker Hub - -| Permission | Description | -| :------------------ | :--------------------------------------------------------- | -| View repositories | View repository details and contents | -| Manage repositories | Create, update, and delete repositories and their contents | - -### Billing - -| Permission | Description | -| :------------- | :----------------------------------------------- | -| View billing | View organization billing information | -| Manage billing | Complete access to managing organization billing | diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/_index.md b/content/manuals/enterprise/security/single-sign-on/FAQs/_index.md deleted file mode 100644 index 224304008d4e..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: FAQs -weight: 50 ---- \ No newline at end of file diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/domain-faqs.md b/content/manuals/enterprise/security/single-sign-on/FAQs/domain-faqs.md deleted file mode 100644 index ace6b06cad66..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/domain-faqs.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: SSO domain FAQs -linkTitle: Domains -description: Frequently asked questions about domain verification and management for Docker single sign-on -keywords: SSO domains, domain verification, DNS, TXT records, single sign-on -tags: [FAQ] -aliases: -- /single-sign-on/domain-faqs/ -- /faq/security/single-sign-on/domain-faqs/ -- /security/faqs/single-sign-on/domain-faqs/ ---- - -## Can I add sub-domains? - -Yes, you can add sub-domains to your SSO connection. All email addresses must use domains you've added to the connection. Verify that your DNS provider supports multiple TXT records for the same domain. - -## Do I need to keep the DNS TXT record permanently? - -You can remove the TXT record after one-time verification to add the domain. However, if your organization changes identity providers and needs to set up SSO again, you'll need to verify the domain again. - -## Can I verify the same domain for multiple organizations? - -You can't verify the same domain for multiple organizations at the organization level. To verify one domain for multiple organizations, you must have a Docker Business subscription and create a company. Companies allow centralized management of organizations and domain verification at the company level. diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/enforcement-faqs.md b/content/manuals/enterprise/security/single-sign-on/FAQs/enforcement-faqs.md deleted file mode 100644 index 39e87fbb471c..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/enforcement-faqs.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: SSO enforcement FAQs -linkTitle: Enforcement -description: Frequently asked questions about Docker single sign-on enforcement and its effects on users -keywords: SSO enforcement, single sign-on, personal access tokens, CLI authentication, guest users -tags: [FAQ] -aliases: - - /single-sign-on/enforcement-faqs/ - - /faq/security/single-sign-on/enforcement-faqs/ - - /security/faqs/single-sign-on/enforcement-faqs/ ---- - -## Does Docker SSO support authenticating through the command line? - -When SSO is enforced, [passwords are prevented from accessing the Docker CLI](/manuals/security/security-announcements.md#deprecation-of-password-logins-on-cli-when-sso-enforced). You must use a personal access token (PAT) for CLI authentication instead. - -Each user must create a PAT to access the CLI. To learn how to create a PAT, see [Manage personal access tokens](/manuals/security/access-tokens.md). Users who already used a PAT before SSO enforcement can continue using that PAT. - -## How does SSO affect automation systems and CI/CD pipelines? - -Before enforcing SSO, you must [create personal access tokens](/manuals/security/access-tokens.md) to replace passwords in automation systems and CI/CD pipelines. - -## Can I turn on SSO without enforcing it immediately? - -Yes, you can turn on SSO without enforcement. Users can choose between Docker ID (standard email and password) or domain-verified email address (SSO) at the sign-in screen. - -## SSO is enforced, but a user can sign in using a username and password. Why is this happening? - -Guest users who aren't part of your registered domain but have been invited to your organization don't sign in through your SSO identity provider. SSO enforcement only applies to users who belong to your verified domain. - -## Can I test SSO functionality before going to production? - -Yes, you can create a test organization with a 5-seat Business subscription. When testing, turn on SSO but don't enforce it, or all domain email users will be forced to sign in to the test environment. - -## What is enforcing SSO versus enforcing sign-in? - -These are separate features you can use independently or together: - -- Enforcing SSO ensures users sign in using SSO credentials instead of their Docker ID, enabling better credential management. -- Enforcing sign-in to Docker Desktop ensures users always sign in to accounts that are members of your organization, so security settings and subscription benefits are always applied. - -For more details, see [Enforce sign-in for Desktop](/manuals/enterprise/security/enforce-sign-in/_index.md#enforcing-sign-in-versus-enforcing-single-sign-on-sso). diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/general.md b/content/manuals/enterprise/security/single-sign-on/FAQs/general.md deleted file mode 100644 index ce25481d4df8..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/general.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Frequently asked questions about Docker single sign-on -keywords: Docker, Docker Hub, SSO FAQs, single sign-on, administration, security -title: General SSO FAQs -linkTitle: General -weight: 20 -tags: [FAQ] -aliases: -- /single-sign-on/faqs/ -- /faq/security/single-sign-on/faqs/ -- /single-sign-on/saml-faqs/ -- /faq/security/single-sign-on/saml-faqs/ -- /security/faqs/single-sign-on/saml-faqs/ -- /security/faqs/single-sign-on/faqs/ ---- - -## What SSO flows does Docker support? - -Docker supports Service Provider Initiated (SP-initiated) SSO flow. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process. - -## Does Docker SSO support multi-factor authentication? - -When an organization uses SSO, multi-factor authentication is controlled at the identity provider level, not on the Docker platform. - -## Can I retain my Docker ID when using SSO? - -Users with personal Docker IDs retain ownership of their repositories, images, and assets. When SSO is enforced, existing accounts with company domain emails are connected to the organization. Users signing in without existing accounts automatically have new accounts and Docker IDs created. - -## Are there any firewall rules required for SSO configuration? - -No specific firewall rules are required as long as `login.docker.com` is accessible. This domain is commonly accessible by default, but some organizations may need to allow it in their firewall settings if SSO setup encounters issues. - -## Does Docker use my IdP's default session timeout? - -Yes, Docker supports your IdP's session timeout using a custom `dockerSessionMinutes` SAML attribute instead of the standard `SessionNotOnOrAfter` element. See [SSO attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes) for more information. diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/idp-faqs.md b/content/manuals/enterprise/security/single-sign-on/FAQs/idp-faqs.md deleted file mode 100644 index 410fb4311189..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/idp-faqs.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: SSO identity provider FAQs -linkTitle: Identity providers -description: Frequently asked questions about Docker SSO and identity provider configuration -keywords: identity providers, SSO IdP, SAML, Azure AD, Entra ID, certificate management -tags: [FAQ] -aliases: - - /single-sign-on/idp-faqs/ - - /faq/security/single-sign-on/idp-faqs/ - - /security/faqs/single-sign-on/idp-faqs/ ---- - -## Can I use multiple identity providers with Docker SSO? - -Yes, Docker supports multiple IdP configurations. A domain can be associated with multiple IdPs. Docker supports Entra ID (formerly Azure AD) and identity providers that support SAML 2.0. - -## Can I change my identity provider after configuring SSO? - -Yes. Delete your existing IdP configuration in your Docker SSO connection, then [configure SSO using your new IdP](/manuals/enterprise/security/single-sign-on/connect.md). If you had already turned on enforcement, turn off enforcement before updating the provider connection. - -## What information do I need from my identity provider to configure SSO? - -To turn on SSO in Docker, you need the following from your IdP: - -- SAML: Entity ID, ACS URL, Single Logout URL, and the public X.509 certificate -- Entra ID (formerly Azure AD): Client ID, Client Secret, AD Domain - -## What happens if my existing certificate expires? - -Contact your identity provider to retrieve a new X.509 certificate. Update with the new certificate in [SSO configuration settings](/manuals/enterprise/security/single-sign-on/manage.md#manage-sso-connections) from Docker Admin Console. - -- If your organization enforces SSO, username and password credentials won't work. -- If your organization doesn't enforce SSO, users can sign in with their username and password credentials. - -If you need additional help, contact [Docker support](https://app.docker.com/support/contact). - -## What happens if my IdP goes down when SSO is turned on? - -If SSO is enforced, users can't access Docker Hub when your IdP is down. Users can still access Docker Hub images from the CLI using personal access tokens. - -If SSO is turned on but not enforced, users can fall back to username/password authentication. - -## Do bot accounts need seats to access organizations using SSO? - -Yes, bot accounts need seats like regular users, requiring a non-aliased domain email in the IdP and using a seat in Docker Hub. You can add bot accounts to your IdP and create access tokens to replace other credentials. - -## Does SAML SSO use Just-in-Time provisioning? - -The SSO implementation uses Just-in-Time (JIT) provisioning by default. You can optionally turn off JIT in the Admin Console if you turn on auto-provisioning using SCIM. See [Just-in-Time provisioning](/manuals/enterprise/security/provisioning/just-in-time.md). - -## My Entra ID SSO connection isn't working and shows an error. How can I troubleshoot this? - -Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations). diff --git a/content/manuals/enterprise/security/single-sign-on/FAQs/users-faqs.md b/content/manuals/enterprise/security/single-sign-on/FAQs/users-faqs.md deleted file mode 100644 index f3fe64798eed..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/FAQs/users-faqs.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: SSO user management FAQs -linkTitle: User management -description: Frequently asked questions about managing users with Docker single sign-ons -keywords: SSO user management, user provisioning, SCIM, just-in-time provisioning, organization members -tags: [FAQ] -aliases: - - /single-sign-on/users-faqs/ - - /faq/security/single-sign-on/users-faqs/ - - /security/faqs/single-sign-on/users-faqs/ ---- - -## Do I need to manually add users to my organization? - -No, you don't need to manually add users to your organization. Just ensure user accounts exist in your IdP. When users sign in to Docker with their domain email address, they're automatically added to the organization after successful authentication. - -## Can users use different email addresses to authenticate through SSO? - -All users must authenticate using the email domain specified during SSO setup. Users with email addresses that don't match the verified domain can sign in as guests with username and password if SSO isn't enforced, but only if they've been invited. - -## How will users know they're being added to a Docker organization? - -When SSO is turned on, users are prompted to authenticate through SSO the next time they sign in to Docker Hub or Docker Desktop. The system detects their domain email and prompts them to sign in with SSO credentials instead. - -For CLI access, users must authenticate using personal access tokens. - -## Can I convert existing users from non-SSO to SSO accounts? - -Yes, you can convert existing users to SSO accounts. Ensure users have: - -- Company domain email addresses and accounts in your IdP -- Docker Desktop version 4.4.2 or later -- Personal access tokens created to replace passwords for CLI access -- CI/CD pipelines updated to use PATs instead of passwords - -For detailed instructions, see [Configure single sign-on](/manuals/enterprise/security/single-sign-on/connect.md). - -## Is Docker SSO fully synced with the IdP? - -Docker SSO provides Just-in-Time (JIT) provisioning by default. Users are provisioned when they authenticate with SSO. If users leave the organization, administrators must manually [remove the user](/manuals/admin/organization/manage/members.md#remove-members-from-teams) from the organization. - -[SCIM](/manuals/enterprise/security/provisioning/scim/_index.md) provides full synchronization with users and groups. When using SCIM, the recommended configuration is to turn off JIT so all auto-provisioning is handled by SCIM. - -Additionally, you can use the [Docker Hub API](/reference/api/hub/latest.md) to complete this process. - -## How does turning off Just-in-Time provisioning affect user sign-in? - -When JIT is turned off (available with SCIM in the Admin Console), users must be organization members or have pending invitations to access Docker. Users who don't meet these criteria get an "Access denied" error and need administrator invitations. - -See [SSO authentication with JIT provisioning disabled](/manuals/enterprise/security/provisioning/just-in-time.md#sso-authentication-with-jit-provisioning-disabled). - -## Can someone join an organization without an invitation? - -Not without SSO. Joining requires an invite from an organization owner. When SSO is enforced, users with verified domain emails can automatically join the organization when they sign in. - -## What happens to existing licensed users when SCIM is turned on? - -Turning on SCIM doesn't immediately remove or modify existing licensed users. They retain current access and roles, but you'll manage them through your IdP after SCIM is active. If SCIM is later turned off, previously SCIM-managed users remain in Docker but are no longer automatically updated based on your IdP. - -## Is user information visible in Docker Hub? - -All Docker accounts have public profiles associated with their namespace. If you don't want user information (like full names) to be visible, remove those attributes from your SSO and SCIM mappings, or use different identifiers to replace users' full names. diff --git a/content/manuals/enterprise/security/single-sign-on/_index.md b/content/manuals/enterprise/security/single-sign-on/_index.md deleted file mode 100644 index 1c24358a4817..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/_index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Single sign-on overview -linkTitle: Single sign-on -description: Learn how single sign-on works, how to set it up, and the required SSO attributes. -keywords: Single Sign-On, SSO, sign-in, admin, docker hub, admin console, security, identity provider, SSO configuration, enterprise login, Docker Business, user authentication -aliases: - - /single-sign-on/ - - /admin/company/settings/sso/ - - /admin/organization/security-settings/sso-management/ - - /security/for-admins/single-sign-on/ -weight: 10 ---- - -{{< summary-bar feature_name="SSO" >}} - -Single sign-on (SSO) lets users access Docker by authenticating through their -identity providers (IdPs). SSO can be configured for an entire company, -including all associated organizations, or for a single organization that has a -Docker Business subscription. - -## How SSO works - -When SSO is enabled, Docker supports a non-IdP-initiated flow for user sign-in. -Instead of signing in with a Docker username and password, users are redirected -to your IdP’s sign-in page. Users must initiate the SSO authentication process -by signing in to Docker Hub or Docker Desktop. - -The following diagram illustrates how SSO operates and is managed between -Docker Hub, Docker Desktop, and your IdP. - -![SSO architecture](images/SSO.png) - -## Set up SSO - -To configure SSO in Docker, follow these steps: - -1. [Configure your domain](connect.md) by creating and verifying it. -1. [Create your SSO connection](connect.md) in Docker and your IdP. -1. Link Docker to your identity provider. -1. Test your SSO connection. -1. Provision users in Docker. -1. Optional. [Enforce sign-in](../enforce-sign-in/_index.md). -1. [Manage your SSO configuration](manage.md). - -Once configuration is complete, users can sign in to Docker services using -their company email address. After signing in, users are added to your company, -assigned to an organization, and added to a team. - -> [!IMPORTANT] -> -> Docker plans to deprecate CLI password-based sign-in in future releases. -> Using a PAT ensures continued CLI access. For more information, see the -> [security announcement](/manuals/security/security-announcements.md#deprecation-of-password-logins-on-cli-when-sso-enforced). - -## Next steps - -- Start [configuring SSO](connect.md). -- Read the [FAQs](/manuals/enterprise/security/single-sign-on/FAQs/general.md). -- [Troubleshoot](/manuals/enterprise/security/single-sign-on/troubleshoot-sso.md) SSO issues. diff --git a/content/manuals/enterprise/security/single-sign-on/connect.md b/content/manuals/enterprise/security/single-sign-on/connect.md deleted file mode 100644 index 9a6af9df44aa..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/connect.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: Set up single sign-on -linkTitle: Setup -weight: 20 -description: Connect Docker and your identity provider, test the setup, and enable enforcement -keywords: configure sso, set up sso, docker sso setup, docker identity provider, sso enforcement, docker hub, security -aliases: - - /security/for-admins/single-sign-on/connect/ - - /docker-hub/domains/ - - /docker-hub/sso-connection/ - - /docker-hub/enforcing-sso/ - - /single-sign-on/configure/ - - /admin/company/settings/sso-configuration/ - - /admin/organization/security-settings/sso-configuration/ - - /security/for-admins/single-sign-on/configure/ - - /enterprise/security/single-sign-on/configure ---- - -{{< summary-bar feature_name="SSO" >}} - -To set up a single sign-on (SSO), you need to establish a connection between Docker -and your identity provider (IdP). While this guide -uses Okta and Microsoft Entra ID as a working example, the general process remains the same for other IdPs. - -If you're unfamiliar with the SSO process, first review [SSO overview](/manuals/enterprise/security/single-sign-on/_index.md) to learn about how SSO works. - -## Prerequisites - -Docker supports any SAML 2.0 or OIDC-compatible identity provider. Before you begin, make sure the following conditions are met: - -- Notify your company about the upcoming SSO sign-in process. -- Confirm that each Docker user has a valid IdP account using the same - email address as their Unique Primary Identifier (UPN). -- Ensure CI/CD pipelines use PATs or OATs instead of passwords. - -## Set up an SSO connection - -> [!TIP] -> These procedures have you copy and paste values between Docker and your IdP. Complete this guide in one session with separate browser windows open for Docker and your IdP. - -### Step 1: Add a domain - -To add a domain: - -1. Sign in to [app.docker.com](https://app.docker.com), then choose your - organization. If your organization is part of a company, then select the company to manage - the domain at the company level. -1. Select **Admin Console**, then **Domain management**. -1. Select **Add a domain**. -1. Enter your domain in the text box and select **Add domain**. -1. In the modal, copy the **TXT Record Value** provided for domain verification. - -### Step 2: Verify your domain - -To confirm domain ownership, add a TXT record to your Domain Name System (DNS) -host using the TXT Record Value from Docker. DNS propagation can take up to -72 hours. Docker automatically checks for the record during this time. - -> [!TIP] -> -> When adding a record name, use `@` or leave it empty for root domains like `example.com`. Avoid common values like `docker`, `docker-verification`, `www`, or your domain name itself. Always check your DNS provider's documentation to verify their specific record name requirements. - -{{< tabs >}} -{{< tab name="AWS Route 53" >}} - -1. To add your TXT record to AWS, see [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). -1. Wait up to 72 hours for TXT record verification. -1. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**. - -{{< /tab >}} -{{< tab name="Google Cloud DNS" >}} - -1. To add your TXT record to Google Cloud DNS, see [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). -1. Wait up to 72 hours for TXT record verification. -1. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**. - -{{< /tab >}} -{{< tab name="GoDaddy" >}} - -1. To add your TXT record to GoDaddy, see [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). -1. Wait up to 72 hours for TXT record verification. -1. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**. - -{{< /tab >}} -{{< tab name="Other providers" >}} - -1. Sign in to your domain host. -1. Add a TXT record to your DNS settings and save the record. -1. Wait up to 72 hours for TXT record verification. -1. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**. - -{{< /tab >}} -{{< /tabs >}} - -### Step 3: Create an SSO connection in Docker - -1. From [app.docker.com](https://app.docker.com), choose your - organization. Select **Admin Console**. -1. Choose **SSO and SCIM** from the **Security** section. -1. Select **Create Connection**. Name the connection, then choose **SAML 2.0**. -1. Keep this window open. You need to copy and paste these values in your Okta window: - - **Entity ID** - - **ACS URL** - - **Connection ID** - -You will return here to finish connecting after creating an SSO connection in your IdP. - -### Step 4: Create an SSO connection in your IdP - -Use the following tabs based on your IdP provider. - -{{< tabs >}} -{{< tab name="Okta SAML" >}} - -You need [super admin permissions](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) for the Okta org. - -1. Sign in to your Okta Admin account. From the top nav, select the **Admin** button to go to Okta's Admin Console. -1. From the **Applications** section in the left nav, choose **Applications**. Select **Create App Integration**. -1. Choose SAML 2.0 to match your selection from Docker's Admin Console. -1. For **General Settings**, name your app "Docker." Uploading a logo is optional. -1. For **Configure SAML**, input the following values: - - For the **Single Sign On URL** value, paste the Docker ACS URL. - - For the **Audience URI (SP Entity ID)** value, paste the Docker Entity ID. - - For **Name ID format**, choose `EmailAddress` - - For **Application username**, choose `Email` - - For **Update application username on**, choose `Create and update` - - Optional. Add [SAML attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes), if required by your org. -1. For **Feedback**, choose **This is an internal app that we have created** checkbox before finishing. - -Keep your Okta window open for the next step. - -{{< /tab >}} -{{< tab name="Entra ID SAML 2.0" >}} - -To enable SSO with Microsoft Entra, you need [Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) permissions. - -1. From Microsoft Entra admin center, select **Entra ID**, then go to **Enterprise apps**. Select **All applications**. -1. Choose **Create your own application** and name your app "Docker". Select **Non-gallery**. -1. After creating your app, go to **Single Sign-On** and select **SAML**. -1. Select **Edit** on the **Basic SAML configuration** section. From **Basic SAML configuration**, choose **Edit** and paste the values you copied from creating an SSO connection in Docker: - - For the **Identifier** value, paste the Docker Entity ID. - - For the **Reply URL** value, paste Docker ACS URL. -1. Optional. Add [SAML attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes), if required by your org. -1. From the **SAML Signing Certificate** section, download your **Certificate (Base64)**. - -{{< /tab >}} -{{< tab name="Azure OpenID Connect (OIDC)" >}} - -#### Register the app - -1. Sign in to [Microsoft Entra admin center](https://entra.microsoft.com/). -1. Go to **App Registration** and select **New Registration**. -1. Name the application "Docker". -1. Set account types and paste the **Redirect URI** from Docker. -1. Select **Register**. -1. Copy the **Client ID**. - -#### Create client secrets - -1. In your app, go to **Certificates & secrets**. -1. Select **New client secret**, describe and configure duration, then **Add**. -1. Copy the **value** of the new secret. - -#### Set API permissions - -1. In your app, go to **API permissions**. -1. Select **Grant admin consent** and confirm. -1. Select **Add a permissions** > **Delegated permissions**. -1. Search and select `User.Read`. -1. Confirm that admin consent is granted. - -{{< /tab >}} -{{< /tabs >}} - -### Step 5: Connect Docker to your IdP - -Complete the integration by pasting your IdP values into Docker. - -> [!IMPORTANT] -> When prompted to copy a certificate, copy the entire certificate starting with -> `----BEGIN CERTIFICATE----` and including the `----END CERTIFICATE----` lines. - -{{< tabs >}} -{{< tab name="Okta SAML" >}} - -1. Go to **Applications** and choose **Applications**. Choose your app from the **ACTIVE** table. -1. From **Sign on**, go to **View SAML setup instructions**. This page contains the **SAML Sign-in URL** and **x509 Certificate**. Keep this page open. -1. Return to your opened Docker window for the **Create single sign-on connection** step. Paste in the **SAML Sign-in URL** and **x509 Certificate** values. -1. Optional. Select a default team, if required by your org. -1. Review and select **Create connection**. - -{{< /tab >}} -{{< tab name="Entra ID SAML 2.0" >}} - -1. Open your downloaded **Certificate (Base64)** in a text editor. -1. Copy the following values: - - From Azure AD: **Login URL** - - **Certificate (Base64)** contents -1. Return to the Docker Admin Console, then paste the **Login URL** and **Certificate (Base64)** values. -1. Choose your domain from the drop-down. -1. Optional. Select a default team, if required by your org. -1. Review and select **Create connection**. - -{{< /tab >}} -{{< tab name="Azure OpenID Connect (OIDC)" >}} - -1. Return to the Docker Admin Console. -1. Paste the following values: - - **Client ID** - - **Client Secret** - - **Azure AD Domain** -1. Optional. Select a default team, if required by your org. -1. Review and select **Create connection**. - -{{< /tab >}} -{{< /tabs >}} - -### Step 6: Test the connection - -IdPs like Microsoft Entra and Okta may require that you assign a user to an application before testing SSO. You can review [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso#test-single-sign-on)'s documentation and [Okta](https://help.okta.com/wf/en-us/content/topics/workflows/connector-reference/okta/actions/assignusertoapplicationforsso.htm)'s documentation to learn how to assign yourself or other users to an app. - -After assigning yourself to an app: - -1. Open an incognito browser window and sign in to the Admin Console using your domain email address. -1. When redirected to your IdP's sign in page, authenticate with your domain email instead of using your Docker ID. - -If you have multiple IdPs, choose the sign-in option **Continue with SSO**. If you're using the CLI, you must authenticate using a personal access token. - -## Configure multiple IdPs - -Docker supports multiple identity provider (IdP) configurations by letting you associate one domain with more than one IdP. Each connection must use the same domain, which lets users choose their IdP when they select **Continue with SSO** at sign in. - -To add multiple IdPs: - -1. Use the same domain for each connection. -1. Repeat steps 3-6 from the [Set up an SSO connection](/manuals/enterprise/security/single-sign-on/connect.md#set-up-an-sso-connection) procedures on this page. Repeat these steps for each IdP your organization intends to use. - -Because you must use the same domain for each IdP, you won't need to repeat steps to add and verify your domains. - -## Enforce SSO - -If SSO is not enforced, users can still sign in using Docker usernames and passwords. Enforcing SSO requires users to use SSO when signing into Docker, which centralizes authentication and enforces policies set by the IdP. - -Before enforcing SSO, users accessing Docker through the CLI must [create a personal access token (PAT)](/manuals/security/access-tokens.md). The PAT replaces their username and password for authentication. - -1. Sign in to [Docker Home](https://app.docker.com/) and select - your organization or company. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the SSO connections table, select the **Action** menu, then **Enable enforcement**. -1. Follow the on-screen instructions. -1. Select **Turn on enforcement**. - -When you enforce SSO, your users cannot modify their email address and -password, convert a user account to an organization, or set up 2FA through -Docker Hub. If you want to use 2FA, you must enable 2FA through your IdP. - -## Next steps - -- [Provision users](/manuals/enterprise/security/provisioning/_index.md). -- [Enforce sign-in](../enforce-sign-in/_index.md). -- [Create personal access tokens](/manuals/security/access-tokens.md). -- [Troubleshoot SSO](/manuals/enterprise/security/single-sign-on/troubleshoot-sso.md) issues. diff --git a/content/manuals/enterprise/security/single-sign-on/images/SSO.png b/content/manuals/enterprise/security/single-sign-on/images/SSO.png deleted file mode 100644 index ea6f44f2c1be..000000000000 Binary files a/content/manuals/enterprise/security/single-sign-on/images/SSO.png and /dev/null differ diff --git a/content/manuals/enterprise/security/single-sign-on/manage.md b/content/manuals/enterprise/security/single-sign-on/manage.md deleted file mode 100644 index a3d867114d1a..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/manage.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Manage SSO domains and connections -linkTitle: Manage connections -weight: 30 -description: Learn how to manage Single Sign-On for your organization or company. -keywords: manage, single sign-on, SSO, sign-on, admin console, admin, security, domains, connections, users, provisioning -aliases: -- /admin/company/settings/sso-management/ -- /single-sign-on/manage/ -- /security/for-admins/single-sign-on/manage/ ---- - -{{< summary-bar feature_name="SSO" >}} - -This page covers how to manage single sign-on (SSO) after initial setup, -including managing domains, connections, users, and provisioning -settings. - -## Manage domains - -### Add a domain - -To add a domain to an existing SSO connection: - -1. Sign in to [Docker Home](https://app.docker.com) and select your company or -organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the SSO connections table, select the **Actions** menu for your -connection, then select **Edit connection**. -1. Select **Next** to navigate to the domains section. -1. In the **Domains** section, select **Add domain**. -1. Enter the domain you want to add to the connection. -1. Select **Next** to confirm or change the connected organizations. -1. Select **Next** to confirm or change the default organization and -team provisioning selections. -1. Review the connection details and select **Update connection**. - -### Remove a domain from an SSO connection - -> [!IMPORTANT] -> -> If you use multiple identity providers with the same domain, you must remove the domain from each SSO connection individually. - -1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** menu for your connection, then -**Edit connection**. -1. Select **Next** to navigate to the domains section. -1. In the **Domain** section, select the **X** icon next to the domain -you want to remove. -1. Select **Next** to confirm or change the connected organizations. -1. Select **Next** to confirm or change the default organization and -team provisioning selections. -1. Review the connection details and select **Update connection**. - -> [!NOTE] -> -> When you re-add a domain, Docker assigns a new TXT record value. You must complete domain verification again with the new TXT record. - -## Manage SSO connections - -### View connections - -To view all configured SSO connections: - -1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. View all configured connections in the **SSO connections** table. - -### Edit a connection - -To modify an existing SSO connection: - -1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** menu for your connection, then -**Edit connection**. -1. Follow the on-screen instructions to modify your connection settings. - -### Delete a connection - -To remove an SSO connection: - -1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** menu for your connection, then -**Delete connection**. -1. Follow the on-screen instructions to confirm the deletion. - -> [!WARNING] -> -> Deleting an SSO connection removes access for all users who authenticate through -that connection. - -## Manage users and provisioning - -Docker automatically provisions users through Just-in-Time (JIT) provisioning when they sign in via SSO. You can also manually manage users and configure different provisioning methods. - -### How provisioning works - -Docker supports the following provisioning methods: - -- JIT provisioning (default): Users are automatically added to your organization -when they sign in via SSO -- SCIM provisioning: Sync users and groups from your identity provider to Docker -- Group mapping: Sync user groups from your identity provider with teams in your Docker organization -- Manual provisioning: Turn off automatic provisioning and manually invite users - -For more information on provisioning methods, see [Provision users](/manuals/enterprise/security/provisioning/_index.md). - -### Add guest users - -To invite users who don't authenticate through your identity provider: - -1. Sign in to [Docker Home](https://app.docker.com/) and select -your organization. -1. Select **Members**. -1. Select **Invite**. -1. Follow the on-screen instructions to invite the user. - -The user receives an email invitation and can create a Docker account or sign -in with their existing account. - -### Remove users - -To remove a user from your organization: - -1. Sign in to [Docker Home](https://app.docker.com/) and select -your organization. -1. Select **Members**. -1. Find the user you want to remove and select the **Actions** menu next to their name. -1. Select **Remove** and confirm the removal. - -The user loses access to your organization immediately upon removal. diff --git a/content/manuals/enterprise/security/single-sign-on/troubleshoot-sso.md b/content/manuals/enterprise/security/single-sign-on/troubleshoot-sso.md deleted file mode 100644 index 5fe8304714b6..000000000000 --- a/content/manuals/enterprise/security/single-sign-on/troubleshoot-sso.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: Troubleshoot single sign-on -linkTitle: Troubleshoot -description: Troubleshoot common Docker single sign-on configuration and authentication issues -weight: 40 -keywords: sso troubleshooting, single sign-on errors, authentication issues, identity provider problems -tags: [Troubleshooting] -toc_max: 2 -aliases: - - /security/for-admins/single-sign-on/troubleshoot/ - - /security/troubleshoot/troubleshoot-sso/ - - /enterprise/troubleshoot/troubleshoot-sso/ ---- - -This page describes common single sign-on (SSO) errors and their solutions. Issues can stem from your identity provider (IdP) configuration or Docker settings. - -## Check for errors - -If you experience SSO issues, check both Docker and your identity provider for errors first. - -### Check Docker error logs - -1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the SSO connections table, select the **Action** menu and then **View error logs**. -1. For more details on specific errors, select **View error details** next to an error message. -1. Note any errors you see on this page for further troubleshooting. - -### Check identity provider errors - -1. Review your IdP’s logs or audit trails for any failed authentication or provisioning attempts. -2. Confirm that your IdP’s SSO settings match the values provided in Docker. -3. If applicable, confirm that you have configured user provisioning correctly and that it is enabled in your IdP. -4. If applicable, verify that your IdP correctly maps Docker's required user attributes. -5. Try provisioning a test user from your IdP and verify if they appear in Docker. - -For further troubleshooting, check your IdP's documentation or contact their support team. - -## Groups are not formatted correctly - -### Error message - -When this issue occurs, the following error message is common: - -```text -Some of the groups assigned to the user are not formatted as ':'. Directory groups will be ignored and user will be provisioned into the default organization and team. -``` - -### Causes - -- Incorrect group name formatting in your identity provider (IdP): Docker requires groups to follow the format `:`. If the groups assigned to a user do not follow this format, they will be ignored. -- Non-matching groups between IdP and Docker organization: If a group in your IdP does not have a corresponding team in Docker, it will not be recognized, and the user will be placed in the default organization and team. - -### Affected environments - -- Docker single sign-on setup using IdPs such as Okta or Azure AD -- Organizations using group-based role assignments in Docker - -### Steps to replicate - -To replicate this issue: - -1. Attempt to sign in to Docker using SSO. -2. The user is assigned groups in the IdP but does not get placed in the expected Docker Team. -3. Review Docker logs or IdP logs to find the error message. - -### Solutions - -Update group names in your IdP: - -1. Go to your IdP's group management section. -2. Check the groups assigned to the affected user. -3. Ensure each group follows the required format: `:` -4. Update any incorrectly formatted groups to match this pattern. -5. Save changes and retry signing in with SSO. - -## User is not assigned to the organization - -### Error message - -When this issue occurs, the following error message is common: - -```text -User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX -``` - -### Causes - -- User is not assigned to the organization: If Just-in-Time (JIT) provisioning is disabled, the user may not be assigned to your organization. -- User is not invited to the organization: If JIT is disabled and you do not want to enable it, the user must be manually invited. -- SCIM provisioning is misconfigured: If you use SCIM for user provisioning, it may not be correctly syncing users from your IdP. - -### Solutions - -**Enable JIT provisioning** - -JIT is enabled by default when you enable SSO. If you have JIT disabled and need -to re-enable it: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the SSO connections table, select the **Action** menu and then **Enable JIT provisioning**. -1. Select **Enable** to confirm. - -**Manually invite users** - -When JIT is disabled, users are not automatically added to your organization when they authenticate through SSO. -To manually invite users, see [Invite members](/manuals/admin/organization/manage/members.md#invite-members). - -**Configure SCIM provisioning** - -If you have SCIM enabled, troubleshoot your SCIM connection using the following steps: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. -1. Select **Admin Console**, then **SSO and SCIM**. -1. In the SSO connections table, select the **Action** menu and then **View error logs**. For more details on specific errors, select **View error details** next to an error message. Note any errors you see on this page. -1. Navigate back to the **SSO and SCIM** page of the Admin Console and verify your SCIM configuration: - - Ensure that the SCIM Base URL and API Token in your IdP match those provided in the Docker Admin Console. - - Verify that SCIM is enabled in both Docker and your IdP. -1. Ensure that the attributes being synced from your IdP match Docker's [supported attributes](/manuals/enterprise/security/provisioning/scim/provision-scim.md#supported-attributes) for SCIM. -1. Test user provisioning by trying to provision a test user through your IdP and verify if they appear in Docker. - -## IdP-initiated sign in is not enabled for connection - -### Error message - -When this issue occurs, the following error message is common: - -```text -IdP-Initiated sign in is not enabled for connection '$ssoConnection'. -``` - -### Causes - -Docker does not support an IdP-initiated SAML flow. This error occurs when a user attempts to authenticate from your IdP, such as using the Docker SSO app tile on the sign in page. - -### Solutions - -**Authenticate from Docker apps** - -The user must initiate authentication from Docker applications (Hub, Desktop, etc). The user needs to enter their email address in a Docker app and they will get redirected to the configured SSO IdP for their domain. - -**Hide the Docker SSO app** - -You can hide the Docker SSO app from users in your IdP. This prevents users from attempting to start authentication from the IdP dashboard. You must hide and configure this in your IdP. - -## Not enough seats in organization - -### Error message - -When this issue occurs, the following error message is common: - -```text -Not enough seats in organization '$orgName'. Add more seats or contact your administrator. -``` - -### Causes - -This error occurs when the organization has no available seats for the user when provisioning via Just-in-Time (JIT) provisioning or SCIM. - -### Solutions - -**Add more seats to the organization** - -Purchase additional Docker Business subscription seats. For details, see [Manage subscription seats](/manuals/admin/organization/manage/manage-seats.md). - -**Remove users or pending invitations** - -Review your organization members and pending invitations. Remove inactive users or pending invitations to free up seats. For more details, see [Manage organization members](/manuals/admin/organization/manage/members.md). - -## Domain is not verified for SSO connection - -### Error message - -When this issue occurs, the following error message is common: - -```text -Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX -``` - -### Causes - -This error occurs if the IdP authenticated a user through SSO and the User Principal Name (UPN) -returned to Docker doesn’t match any of the verified domains associated to the -SSO connection configured in Docker. - -### Solutions - -**Verify UPN attribute mapping** - -Ensure that the IdP SSO connection is returning the correct UPN value in the assertion attributes. - -**Add and verify all domains** - -Add and verify all domains and subdomains used as UPN by your IdP and associate them with your Docker SSO connection. For details, see [Configure single sign-on](/manuals/enterprise/security/single-sign-on/connect.md). - -## Unable to find session - -### Error message - -When this issue occurs, the following error message is common: - -```text -We couldn't find your session. You may have pressed the back button, refreshed the page, opened too many sign-in dialogs, or there is some issue with cookies. Try signing in again. If the issue persists, contact your administrator. -``` - -### Causes - -The following causes may create this issue: - -- The user pressed the back or refresh button during authentication. -- The authentication flow lost track of the initial request, preventing completion. - -### Solutions - -**Do not disrupt the authentication flow** - -Do not press the back or refresh button during sign-in. - -**Restart authentication** - -Close the browser tab and restart the authentication flow from the Docker application (Desktop, Hub, etc). - -## Name ID is not an email address - -### Error message - -When this issue occurs, the following error message is common: - -```text -The name ID sent by the identity provider is not an email address. Contact your company administrator. -``` - -### Causes - -The following causes may create this issue: - -- The IdP sends a Name ID (UPN) that does not comply with the email format required by Docker. -- Docker SSO requires the Name ID to be the primary email address of the user. - -### Solutions - -In your IdP, ensure the Name ID attribute format is correct: - -1. Verify that the Name ID attribute format in your IdP is set to `EmailAddress`. -2. Adjust your IdP settings to return the correct Name ID format. diff --git a/content/manuals/extensions/_index.md b/content/manuals/extensions/_index.md index 0e0cf3da144c..828053fadde0 100644 --- a/content/manuals/extensions/_index.md +++ b/content/manuals/extensions/_index.md @@ -16,8 +16,6 @@ You can seamlessly connect your favorite development tools to your application d Anyone can use Docker Extensions and there is no limit to the number of extensions you can install. -![Extensions Marketplace](/assets/images/extensions.webp) - ## What extensions are available? There is a mix of partner and community-built extensions and Docker-built extensions. diff --git a/content/manuals/extensions/extensions-sdk/_index.md b/content/manuals/extensions/extensions-sdk/_index.md index 57e127220be4..18ce40b39ed1 100644 --- a/content/manuals/extensions/extensions-sdk/_index.md +++ b/content/manuals/extensions/extensions-sdk/_index.md @@ -33,6 +33,10 @@ grid: link: "/extensions/extensions-sdk/extensions/multi-arch/" --- +> [!IMPORTANT] +> +> New submissions to the Docker Extensions Marketplace are paused while Docker reviews Marketplace security. You can still update existing extensions, and private Marketplace extensions are unaffected. Contact extensions@docker.com if you have additional questions. + The resources in this section help you create your own Docker extension. The Docker CLI tool provides a set of commands to help you build and publish your extension, packaged as a diff --git a/content/manuals/extensions/extensions-sdk/architecture/_index.md b/content/manuals/extensions/extensions-sdk/architecture/_index.md index 1153323bd2ec..ec02702d0007 100644 --- a/content/manuals/extensions/extensions-sdk/architecture/_index.md +++ b/content/manuals/extensions/extensions-sdk/architecture/_index.md @@ -72,7 +72,7 @@ Note that, if the Compose file defines many services, the SDK can only contact t > [!NOTE] > -> In some cases, it is useful to also interact with the Docker engine from the backend. +> In some cases, it is useful to also interact with Docker Engine from the backend. > See [How to use the Docker socket](../guides/use-docker-socket-from-backend.md) from the backend. To communicate with the backend, the Extension SDK provides [functions](../dev/api/backend.md#get) to make `GET`, diff --git a/content/manuals/extensions/extensions-sdk/build/backend-extension-tutorial.md b/content/manuals/extensions/extensions-sdk/build/backend-extension-tutorial.md index 1b56e0dfaca7..7a6ab8dd8ea6 100644 --- a/content/manuals/extensions/extensions-sdk/build/backend-extension-tutorial.md +++ b/content/manuals/extensions/extensions-sdk/build/backend-extension-tutorial.md @@ -275,14 +275,13 @@ Replace the `ui/src/App.tsx` file with the following code: ```tsx // ui/src/App.tsx -import React, { useEffect } from 'react'; +import React, { useEffect, useState } from 'react'; import { createDockerDesktopClient } from "@docker/extension-api-client"; //obtain docker desktop extension client const ddClient = createDockerDesktopClient(); export function App() { - const ddClient = createDockerDesktopClient(); const [hello, setHello] = useState(); useEffect(() => { diff --git a/content/manuals/extensions/extensions-sdk/build/frontend-extension-tutorial.md b/content/manuals/extensions/extensions-sdk/build/frontend-extension-tutorial.md index a523d5b672f9..d5b0b9b3c01b 100644 --- a/content/manuals/extensions/extensions-sdk/build/frontend-extension-tutorial.md +++ b/content/manuals/extensions/extensions-sdk/build/frontend-extension-tutorial.md @@ -195,8 +195,6 @@ provide you with type definitions for the extension APIs and auto-completion in npm install @docker/extension-api-client-types --save-dev ``` -![Auto completion in an IDE](images/types-autocomplete.png) - For example, you can use the `docker.cli.exec` function to get the list of all the containers via the `docker ps --all` command and display the result in a table. @@ -282,8 +280,6 @@ export function App() { ``` -![Screenshot of the container list.](images/react-extension.png) - {{< /tab >}} {{< tab name="Vue" >}} diff --git a/content/manuals/extensions/extensions-sdk/build/images/react-extension.png b/content/manuals/extensions/extensions-sdk/build/images/react-extension.png deleted file mode 100644 index 8edb1e7528e5..000000000000 Binary files a/content/manuals/extensions/extensions-sdk/build/images/react-extension.png and /dev/null differ diff --git a/content/manuals/extensions/extensions-sdk/build/images/types-autocomplete.png b/content/manuals/extensions/extensions-sdk/build/images/types-autocomplete.png deleted file mode 100644 index fcf183eddaf1..000000000000 Binary files a/content/manuals/extensions/extensions-sdk/build/images/types-autocomplete.png and /dev/null differ diff --git a/content/manuals/extensions/extensions-sdk/dev/api/backend.md b/content/manuals/extensions/extensions-sdk/dev/api/backend.md index 30bbb8326801..bfb5ebd18caa 100644 --- a/content/manuals/extensions/extensions-sdk/dev/api/backend.md +++ b/content/manuals/extensions/extensions-sdk/dev/api/backend.md @@ -17,7 +17,7 @@ Performs an HTTP GET request to a backend service. ```typescript ddClient.extension.vm.service .get("/some/service") - .then((value: any) => console.log(value) + .then((value: any) => console.log(value)); ``` See [Service API Reference](/reference/api/extensions-sdk/HttpService.md) for other HTTP methods. diff --git a/content/manuals/extensions/extensions-sdk/extensions/images/list-preview.png b/content/manuals/extensions/extensions-sdk/extensions/images/list-preview.png deleted file mode 100644 index 9836060742aa..000000000000 Binary files a/content/manuals/extensions/extensions-sdk/extensions/images/list-preview.png and /dev/null differ diff --git a/content/manuals/extensions/extensions-sdk/extensions/images/open-share.png b/content/manuals/extensions/extensions-sdk/extensions/images/open-share.png deleted file mode 100644 index 64b16a68a447..000000000000 Binary files a/content/manuals/extensions/extensions-sdk/extensions/images/open-share.png and /dev/null differ diff --git a/content/manuals/extensions/extensions-sdk/extensions/labels.md b/content/manuals/extensions/extensions-sdk/extensions/labels.md index bb670d513747..217b53e8d5b3 100644 --- a/content/manuals/extensions/extensions-sdk/extensions/labels.md +++ b/content/manuals/extensions/extensions-sdk/extensions/labels.md @@ -56,5 +56,3 @@ When you create and install your unpublished extension, you can preview the exte > > You can re-tag your image in order to have a different image name that's not listed as a published extension. > Use `docker tag org/published-extension unpublished-extension` and then `docker extension install unpublished-extension`. - -![List preview](images/list-preview.png) diff --git a/content/manuals/extensions/extensions-sdk/extensions/publish.md b/content/manuals/extensions/extensions-sdk/extensions/publish.md index a10b1f5cb5c1..522c53430375 100644 --- a/content/manuals/extensions/extensions-sdk/extensions/publish.md +++ b/content/manuals/extensions/extensions-sdk/extensions/publish.md @@ -7,6 +7,10 @@ aliases: weight: 50 --- +> [!IMPORTANT] +> +> New submissions to the Docker Extensions Marketplace are paused while Docker reviews Marketplace security. You can still update existing extensions, and private Marketplace extensions are unaffected. Contact extensions@docker.com if you have additional questions. + ## Submit your extension to the Marketplace Docker Desktop displays published extensions in the Extensions Marketplace on [Docker Desktop](https://open.docker.com/extensions/marketplace) and [Docker Hub](https://hub.docker.com/search?q=&type=extension). diff --git a/content/manuals/extensions/extensions-sdk/extensions/share.md b/content/manuals/extensions/extensions-sdk/extensions/share.md index 8e35c0e65695..587b2bd9d555 100644 --- a/content/manuals/extensions/extensions-sdk/extensions/share.md +++ b/content/manuals/extensions/extensions-sdk/extensions/share.md @@ -19,8 +19,6 @@ Docker lets you share your extensions using a URL. When people navigate to this URL, it opens Docker Desktop and displays a preview of your extension in the same way as an extension in the Marketplace. From the preview, users can then select **Install**. -![Navigate to extension link](images/open-share.png) - To generate this link you can either: - Run the following command: @@ -31,8 +29,6 @@ To generate this link you can either: - Once you have installed your extension locally, navigate to the **Manage** tab and select **Share**. - ![Share button](images/list-preview.png) - > [!NOTE] > > Previews of the extension description or screenshots, for example, are created using [extension labels](labels.md). diff --git a/content/manuals/extensions/extensions-sdk/guides/oauth2-flow.md b/content/manuals/extensions/extensions-sdk/guides/oauth2-flow.md index 0685bbcf3eb8..86e73911bbb9 100644 --- a/content/manuals/extensions/extensions-sdk/guides/oauth2-flow.md +++ b/content/manuals/extensions/extensions-sdk/guides/oauth2-flow.md @@ -79,7 +79,7 @@ POST https://authorization-server.com/token > [!NOTE] > -> The client's credentials are included in the `POST` query params in this example. OAuth authorization servers may require that the credentials are sent as a HTTP Basic Authentication header or might support different formats. See your OAuth provider docs for details. +> The client's credentials are included in the `POST` query params in this example. OAuth authorization servers may require that the credentials are sent as an HTTP Basic Authentication header or might support different formats. See your OAuth provider docs for details. ### Store the access token diff --git a/content/manuals/extensions/extensions-sdk/process.md b/content/manuals/extensions/extensions-sdk/process.md index d48f63698cf9..76476b485d98 100644 --- a/content/manuals/extensions/extensions-sdk/process.md +++ b/content/manuals/extensions/extensions-sdk/process.md @@ -38,6 +38,10 @@ For further inspiration, see the other examples in the [samples folder](https:// ## Part two: Publish and distribute your extension +> [!IMPORTANT] +> +> New submissions to the Docker Extensions Marketplace are paused while Docker reviews Marketplace security. You can still update existing extensions, and private Marketplace extensions are unaffected. Contact extensions@docker.com if you have additional questions. + Docker Desktop displays published extensions in the Extensions Marketplace. The Extensions Marketplace is a curated space where developers can discover extensions to improve their developer experience and upload their own extension to share with the world. If you want your extension published in the Marketplace, read the [publish documentation](extensions/publish.md). @@ -49,7 +53,3 @@ If you want your extension published in the Marketplace, read the [publish docum If you want to get up and running with creating a Docker Extension, see the [Quickstart guide](quickstart.md). Alternatively, get started with reading the "Part one: Build" section for more in-depth information about each step of the extension creation process. - -For an in-depth tutorial of the entire build process, we recommend the following video walkthrough from DockerCon 2022. - - diff --git a/content/manuals/extensions/extensions-sdk/quickstart.md b/content/manuals/extensions/extensions-sdk/quickstart.md index 2ddc031c9b41..c03704977056 100644 --- a/content/manuals/extensions/extensions-sdk/quickstart.md +++ b/content/manuals/extensions/extensions-sdk/quickstart.md @@ -77,6 +77,10 @@ hidden from the Docker Dashboard. You can change this in **Settings**, see ## Step four: Submit and publish your extension to the Marketplace +> [!IMPORTANT] +> +> New submissions to the Docker Extensions Marketplace are paused while Docker reviews Marketplace security. You can still update existing extensions, and private Marketplace extensions are unaffected. Contact extensions@docker.com if you have additional questions. + If you want to make your extension available to all Docker Desktop users, you can submit it for publication in the Marketplace. For more information, see [Publish](extensions/_index.md). ## Clean up diff --git a/content/manuals/extensions/private-marketplace.md b/content/manuals/extensions/private-marketplace.md index 60b954bca70e..9966e1dbeba6 100644 --- a/content/manuals/extensions/private-marketplace.md +++ b/content/manuals/extensions/private-marketplace.md @@ -11,7 +11,7 @@ weight: 30 Learn how to configure and set up a private marketplace with a curated list of extensions for your Docker Desktop users. -Docker Extensions' private marketplace is designed specifically for organizations who don’t give developers root access to their machines. It makes use of [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) so administrators have complete control over the private marketplace. +Docker Extensions' private marketplace is designed specifically for organizations who don’t give developers root access to their machines. It makes use of [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) so administrators have complete control over the private marketplace. ## Prerequisites @@ -65,7 +65,7 @@ This creates 2 files: > [!IMPORTANT] > -> If your org is using [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md) via the [Admin Console](manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console/_index.md), you will not need the `admins-settings.json` file. Delete the generated file and keep only the `extensions.txt` file. +> If your org is using [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) via [Docker Home](manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console/_index.md), you will not need the `admin-settings.json` file. Delete the generated file and keep only the `extensions.txt` file. ## Step two: Set the behaviour @@ -73,7 +73,7 @@ The generated `admin-settings.json` file includes various settings you can modif > [!IMPORTANT] > -> If your org is managing settings via the [Admin Console](manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console/_index.md), you will define the same settings in the Admin Console instead of the `admin-settings.json` file. +> If your org is managing settings via [Docker Home](manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console/_index.md), you will define the same settings in Docker Home instead of the `admin-settings.json` file. Each setting has a `value` that you can set, including a `locked` field that lets you lock the setting and make it unchangeable by your developers. @@ -89,7 +89,7 @@ Each setting has a `value` that you can set, including a `locked` field that let } ``` -To find out more information about the `admin-settings.json` file, see [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/_index.md). +To find out more information about the `admin-settings.json` file, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). ## Step three: List allowed extensions @@ -194,18 +194,16 @@ It's recommended that you try the private marketplace on your Docker Desktop ins > [!IMPORTANT] > -> > If your org is managing settings via the [Admin Console](manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console/_index.md), in Docker Desktop 4.59 and earlier, you must manually delete the `admin-settings.json` file created in the target folder by the `apply` command before step 2. In Docker Desktop 4.60 and later, this step is no longer necessary. +> > If your org is managing settings via [Docker Home](manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console/_index.md), in Docker Desktop 4.59 and earlier, you must manually delete the `admin-settings.json` file created in the target folder by the `apply` command before step 2. In Docker Desktop 4.60 and later, this step is no longer necessary. When you select the **Extensions** tab, you should see the private marketplace listing only the extensions you have allowed in `extensions.txt`. -![Extensions Private Marketplace](/assets/images/extensions-private-marketplace.webp) - ## Step six: Distribute the private marketplace Once you’ve confirmed that the private marketplace configuration works, the final step is to distribute the files to the developers’ machines with the MDM software your organization uses. For example, [Jamf](https://www.jamf.com/). The files to distribute are: -* `admin-settings.json` (except if your org is managing settings via the [Admin Console](manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console/_index.md)) +* `admin-settings.json` (except if your org is managing settings via [Docker Home](manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console/_index.md)) * the entire `extension-marketplace` folder and its subfolders These files must be placed on developer's machines. Depending on your operating system, the target location is (as mentioned above): @@ -214,7 +212,7 @@ These files must be placed on developer's machines. Depending on your operating - Windows: `C:\ProgramData\DockerDesktop` - Linux: `/usr/share/docker-desktop` -Make sure your developers are signed in to Docker Desktop in order for the private marketplace configuration to take effect. As an administrator, you should [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md). +Make sure your developers are signed in to Docker Desktop in order for the private marketplace configuration to take effect. As an administrator, you should [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). ## Feedback diff --git a/content/manuals/extensions/settings-feedback.md b/content/manuals/extensions/settings-feedback.md index c585fd009eaf..9d0451891097 100644 --- a/content/manuals/extensions/settings-feedback.md +++ b/content/manuals/extensions/settings-feedback.md @@ -19,12 +19,12 @@ Docker Extensions is switched off by default. To change your settings: > [!NOTE] > -> If you are an [organization owner](/manuals/admin/organization/manage/manage-a-team.md#what-is-an-organization-owner), you can turn off extensions for your users. Open the `settings-store.json` file, and set `"extensionsEnabled"` to `false`. +> If you are an [organization owner](/manuals/accounts/organization/manage/manage-a-team.md#what-is-an-organization-owner), you can turn off extensions for your users. Open the `settings-store.json` file, and set `"extensionsEnabled"` to `false`. > The `settings-store.json` file is located at: > - `~/Library/Group Containers/group.com.docker/settings-store.json` on Mac > - `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` on Windows > -> This can also be done with [Hardened Docker Desktop](/manuals/enterprise/security/hardened-desktop/_index.md) +> This can also be done with [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md) ### Turn on or turn off extensions not available in the Marketplace diff --git a/content/manuals/faqs/_index.md b/content/manuals/faqs/_index.md new file mode 100644 index 000000000000..910ee039c2bb --- /dev/null +++ b/content/manuals/faqs/_index.md @@ -0,0 +1,36 @@ +--- +title: FAQs +linkTitle: FAQs +description: Frequently asked questions about Docker accounts, subscriptions, billing, and security. +keywords: FAQ, FAQs, accounts, Docker ID, Docker Home, subscription FAQs, billing FAQs, security FAQs, SSO FAQs +weight: 45 +params: + sidebar: + group: Accounts and admin +aliases: + - /faq/security/ +grid: + - title: Account FAQs + description: FAQs about Docker IDs, account creation, organizations, and companies. + icon: question-mark-circle + link: /faqs/accounts/ + - title: Security FAQs + description: FAQs about single sign-on, identity providers, enforcement, and domains. + icon: lock-closed + link: /faqs/security/ + - title: Subscription and billing FAQs + description: FAQs about Docker plans, payments, taxes, and invoices. + icon: credit-card + link: /faqs/subscription-billing/ + - title: Platform FAQs + description: FAQs about Docker Desktop containers, networking, VMs, and general platform security. + icon: cpu-chip + link: /faqs/platform/ +--- + +Answers to common questions about Docker accounts, organizations, companies, +subscriptions, billing, and security. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/faqs/accounts.md b/content/manuals/faqs/accounts.md new file mode 100644 index 000000000000..0c92187442d7 --- /dev/null +++ b/content/manuals/faqs/accounts.md @@ -0,0 +1,297 @@ +--- +title: Account FAQs +linkTitle: Accounts +weight: 10 +description: >- + FAQs about Docker IDs, account creation, organizations, companies, seats, + members, and Insights +keywords: + - docker ID + - docker account FAQ + - change docker ID + - username taken + - trademark + - organization name + - organization namespace + - create account + - Google + - GitHub + - deactivate docker ID + - organizations + - members + - seats + - company + - company owners + - convert Docker account + - sign in after convert + - organization owner + - Insights + - Desktop insights + - analyticsEnabled + - personal access token + - auto-generated token + - incorrect authentication credentials +tags: [FAQ] +toc_max: 2 +aliases: + - /accounts/general-faqs/ + - /accounts/individual/general-faqs/ + - /docker-hub/general-faqs/ + - /docker-hub/onboarding-faqs/ + - /faq/admin/general-faqs/ + - /admin/faqs/general-faqs/ + - /admin/organization/organization-faqs/ + - /docker-hub/organization-faqs/ + - /faq/admin/organization-faqs/ + - /admin/faqs/organization-faqs/ + - /accounts/organization/organization-faqs/ + - /admin/company/company-faqs/ + - /docker-hub/company-faqs/ + - /faq/admin/company-faqs/ + - /admin/faqs/company-faqs/ + - /accounts/organization/company/company-faqs/ + - /faqs/general-faqs/ + - /faqs/organization-faqs/ + - /faqs/company-faqs/ +--- + +## Individual accounts + +### What is a Docker ID? + +A Docker ID is a username for your Docker account that lets you access Docker +products. To create a Docker ID you need one of the following: + +- An email address +- A Google account +- A GitHub account + +Your Docker ID must be between 4 and 30 characters long, and can only contain +numbers and lowercase letters. You can't use any special characters or spaces. + +For more information, see +[Create a Docker account](/manuals/accounts/individual/create-account.md). + +### Can I change my Docker ID? + +No. You can't change your Docker ID once it's created. If you need a different +Docker ID, you must create a new Docker account with a new Docker ID. + +Docker IDs can't be reused after deactivation. + +### What if my Docker ID is taken? + +All Docker IDs are first-come, first-served except for companies that have a +U.S. Trademark on a username. + +If you have a trademark for your Docker ID, +[Docker Support](https://hub.docker.com/support/contact/) can retrieve the +Docker ID for you. + +### Why did one of my personal access tokens disappear? + +Signing in to Docker Desktop creates an auto-generated personal access +token for CLI authentication. An account can have five of these tokens. +When Docker Desktop creates another one, it deletes the least recently +used auto-generated token. A token that has never been used is ranked +by when it was created. The deleted token is removed from your token +list. + +Tokens you create yourself are not deleted this way. They stay in the +list until you delete them. A revoked token stays in the list with a +status of **Revoked**. + +For how these tokens are created and how to tell them apart, see +[Auto-generated PATs](/manuals/security/access-tokens/personal-access-tokens.md#auto-generated-tokens). + +### Why does sign-in fail with "Incorrect authentication credentials"? + +`docker login` returns `Incorrect authentication credentials` when the +username and secret don't match a credential that can sign in. The +message is the same when a personal access token is wrong, expired, +inactive, or revoked, and when the username is not the account that +owns the token. + +Check the following: + +1. The username is the Docker ID of the account that owns the token. + Use an organization name only with an + [organization access token](/manuals/security/access-tokens/organization-access-tokens.md). +2. You pasted the full token, with no spaces or line breaks. Docker + shows a token only once. If you no longer have it, + [create a new personal access token](/manuals/security/access-tokens/personal-access-tokens.md#create). +3. On the **Personal access tokens** page, find the token and use its + status: + - **Expired:** Create a new token. You can't change the expiration + date. + - **Inactive:** Select **Activate**. + - **Revoked:** The token can't be used again. Delete it and create + a new one. + +## Organizations + +### What's an organization name or namespace? + +The organization namespace and the organization name are different. + +The namespace is the permanent identifier for the organization. Image names +use it as the first part, as in `namespace/image:tag`. You can't change it, +and it can't match an existing Docker ID. + +The organization name is the public name of the organization. You can change +it. + +For the fields you set when you create an organization, see +[Create a Docker organization](/manuals/accounts/organization/setup/orgs.md). + +### How can I see how many active users are in my organization? + +If your organization uses a Software Asset Management tool, you can use it to +find out how many users have Docker Desktop installed. If your organization +doesn't use this software, you can run an internal survey +to find out who is using Docker Desktop. + +For more information, see +[Identify your Docker users and their Docker accounts](/manuals/accounts/organization/setup/onboard.md#step-one-identify-your-docker-users). + +### Do users need to authenticate with Docker before an owner can add them to an organization? + +No. Organization owners can invite users with their email addresses, and also +assign them to a team during the invite process. + +### Can I force my organization's members to authenticate before using Docker Desktop and are there any benefits? + +Yes. You can +[enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + +Some benefits of enforcing sign-in are: + +- Ensures users receive the benefits of your subscription. +- Ensures security features like + [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md) + and + [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) + are applied. +- Ensures you gain insights into users' activity. + +### Can I convert my personal Docker ID to an organization account? + +Yes. You can convert your user account to an organization account. Once you +convert a user account into an organization, it's not possible to +revert it to a personal user account. + +For prerequisites and instructions, see +[Convert an account into an organization](/manuals/accounts/organization/setup/convert-account.md). + +### Can I convert an individual account that uses single sign-on? + +No. **Convert** shows "Your account uses single sign-on. Contact your +administrator to manage these settings." + +### Why can't I sign in after converting my account to an organization? + +Converting signs you out and removes your email address from every Docker +account, so you can no longer sign in with it. Sign in with the Docker ID you +named as the owner and select the organization in Docker Home. If you named +someone else as the owner, sign up again and ask that owner to invite you. See +[Convert a Docker account to an organization](/manuals/accounts/organization/setup/convert-account.md#conversion) +for the full explanation. + +### Do organization invitees take up seats? + +Yes. A user invited to an organization will take up one of the provisioned +seats, even if that user hasn’t accepted their invitation yet. + +To manage invites, see [Manage organization members](/manuals/accounts/organization/manage/members.md). + +### Do organization owners take a seat? + +Yes. Organization owners occupy a seat. + +### What is the difference between user, invitee, seat, and member? + +- User: Docker user with a Docker ID. +- Invitee: A user that an administrator has invited to join an organization but + has not yet accepted their invitation. +- Seats: The number of purchased seats in an organization. +- Member: A user who has received and accepted an invitation to join an + organization. Member can also refer to a member of a team within an + organization. + +### If I have two organizations and a user belongs to both organizations, do they take up two seats? + +Yes. In a scenario where a user belongs to two organizations, they take up one +seat in each organization. + +### Why is Insights data missing for some users? + +Older versions of Docker Desktop may omit some metrics. Update those users to +the latest Docker Desktop release. + +For prerequisites and how to open Insights, see +[Insights](/manuals/accounts/organization/insights.md). + +### Why are opted-out users missing from Insights? + +Insights includes a user only when **Send usage statistics** +(`analyticsEnabled`) is on. Turn the setting on for users who opted out. At +scale, use +[Settings +Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) +and set `analyticsEnabled` to `true`. + +### Why is Docker Engine usage missing from Insights? + +Only Docker Desktop sends Insights data. A standalone Docker Engine install +sends none. + +### Why are some users excluded from Insights? + +Insights includes users who sign in with an account associated with your +organization. To include the rest, +[enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + +### Why does Insights show no data? + +Insights may show no data until you verify your organization's domain. +[Verify the +domain](/manuals/security/provisioning/domain-management.md). + +### Companies + +#### Can I use a parent company if some of my organizations don’t have a Docker Business subscription? + +Yes, but you can only add organizations with a Docker Business subscription +to a company. For more details, see [Add more organizations](/manuals/accounts/company/manage.md#add-more-organizations). + +#### What happens if one of my organizations downgrades from Docker Business, but I still need access as a company owner? + +To access and manage a nested organization, it must have a Docker Business +subscription. If an organization downgrades from Docker Business, its owner must +manage it outside of the company. For more details, see +[Add more organizations](/manuals/accounts/company/manage.md#add-more-organizations). + +#### Do company owners occupy a subscription seat? + +Company owners don't occupy a seat unless one of the following is true: + +- They are added as a member of an organization under your company +- SSO is enabled and the company owner signs in through SSO, which + automatically adds them as an organization member + +When you first create a company, your account is both a company owner and an +organization owner, so it occupies a seat as long as you remain an organization +owner. To free up that seat, +[assign another user as the organization owner](/manuals/accounts/organization/manage/members.md#update-member-role) +and remove yourself from the organization. You keep full administrative access +as a company owner without using a subscription seat. + +#### What permissions does the company owner have in the associated/nested organizations? + +Company owners can navigate to the **Organizations** page to view all their +nested organizations in a single location. They can also view or edit +organization members and change single sign-on (SSO) and System for +Cross-domain Identity Management (SCIM) settings. Changes to company settings +impact all users in each organization under the company. + +For more information, see [Roles and permissions](/manuals/security/roles-and-permissions.md). diff --git a/content/manuals/faqs/platform.md b/content/manuals/faqs/platform.md new file mode 100644 index 000000000000..4591c6a0e82b --- /dev/null +++ b/content/manuals/faqs/platform.md @@ -0,0 +1,126 @@ +--- +title: Platform FAQs +linkTitle: Platform +description: Frequently asked questions about Docker platform security, containers, networking, and VMs. +keywords: Docker security, FAQs, authentication, vulnerability reporting, session management, container security, docker desktop isolation, enhanced container isolation, file sharing, docker desktop networking, virtualization, hyper-v, wsl2, network security, firewall +weight: 40 +tags: [FAQ] +toc_max: 2 +aliases: + - /faq/security/general/ + - /security/faqs/general/ + - /faq/security/containers/ + - /security/faqs/containers/ + - /faq/security/networking-and-vms/ + - /security/faqs/networking-and-vms/ +--- + +## General + +### How do I report a vulnerability? + +If you've discovered a security vulnerability in Docker, report it responsibly to security@docker.com so Docker can quickly address it. + +### Does Docker lockout users after failed sign-ins? + +Docker Hub locks out users after 10 failed sign-in attempts within 5 minutes. The lockout duration is 5 minutes. This policy applies to Docker Hub, Docker Desktop, and Docker Scout authentication. + +### Do you support physical multi-factor authentication (MFA) with YubiKeys? + +You can configure physical multi-factor authentication (MFA) through SSO using your identity provider (IdP). Check with your IdP if they support physical MFA devices like YubiKeys. + +### How are sessions managed and do they expire? + +Docker uses tokens to manage user sessions with different expiration periods: + +- Docker Desktop: Signs you out after 90 days, or 30 days of inactivity +- Docker Hub and Docker Home: Sign you out after 24 hours + +Docker also supports your IdP's default session timeout through SAML attributes. For more information, see [SSO attributes](/manuals/security/provisioning/_index.md#sso-attributes). + +### How does Docker distinguish between employee users and contractor users? + +Organizations use verified domains to distinguish user types. Team members with email domains other than verified domains appear as "Guest" users in the organization. + +### How long are activity logs available? + +Docker activity logs are available for 90 days. You're responsible for exporting logs or setting up drivers to send logs to your internal systems for longer retention. + +### Can I export a list of users with their roles and privileges? + +Yes, use the [Export Members](/manuals/accounts/organization/manage/members.md#export-members-csv-file) feature to export a CSV file containing your organization's users with role and team information. + +### How do I remove users who aren't part of my IdP when using SSO without SCIM? + +If SCIM isn't turned on, you must manually remove users from the organization. SCIM can automate user removal, but only for users added after SCIM is turned on. Users added before SCIM was turned on must be removed manually. + +For more information, see [Manage organization members](/manuals/accounts/organization/manage/members.md). + +### What metadata does Scout collect from container images? + +For information about metadata stored by Docker Scout, see [Data handling](/manuals/scout/deep-dive/data-handling.md). + +### How are Marketplace extensions vetted for security? + +Security vetting for extensions isn't implemented. Extensions aren't covered as part of Docker's Third-Party Risk Management Program. + +### Can I prevent users from pushing images to Docker Hub private repositories? + +No direct setting exists to disable private repositories. However, [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) lets administrators control which registries developers can access through Docker Desktop via Docker Home. + +## Docker Desktop + +### How does Docker Desktop handle authentication information? + +Docker Desktop uses the host operating system's secure key management to store authentication tokens: + +- macOS: [Keychain](https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web) +- Windows: [Security and Identity API via Wincred](https://learn.microsoft.com/en-us/windows/win32/api/wincred/) +- Linux: [Pass](https://www.passwordstore.org/). + +### Containers + +#### How are containers isolated from the host in Docker Desktop? + +Docker Desktop runs all containers inside a customized Linux virtual machine (except for native Windows containers). This adds strong isolation between containers and the host machine, even when containers run as root. + +Important considerations include: + +- Containers have access to host files configured for file sharing via Docker Desktop settings +- Containers run as root with limited capabilities inside the Docker Desktop VM by default +- Privileged containers (`--privileged`, `--pid=host`, `--cap-add`) run with elevated privileges inside the VM, giving them access to VM internals and Docker Engine + +With Enhanced Container Isolation turned on, each container runs in a dedicated Linux user namespace inside the Docker Desktop VM. Even privileged containers only have privileges within their container boundary, not the VM. ECI uses advanced techniques to prevent containers from breaching the Docker Desktop VM and Docker Engine. + +#### Which portions of the host filesystem can containers access? + +Containers can only access host files that are: + +1. Shared using Docker Desktop settings +1. Explicitly bind-mounted into the container (e.g., `docker run -v /path/to/host/file:/mnt`) + +#### Can containers running as root access admin-owned files on the host? + +No. Host file sharing uses a user-space file server (running in `com.docker.backend` as the Docker Desktop user), so containers can only access files that the Docker Desktop user already has permission to access. + +### Networking and VMs + +#### How can I limit container internet access? + +Docker Desktop doesn't have a built-in mechanism for this, but you can use process-level firewalls on the host. Apply rules to the `com.docker.vpnkit` user-space process to control where it can connect (DNS allowlists, packet filters) and which ports/protocols it can use. + +For enterprise environments, consider [Air-gapped containers](/manuals/desktop/enterprise/hardened-desktop/air-gapped-containers.md) which provide network access controls for containers. + +#### Can I apply firewall rules to container network traffic? + +Yes. Docker Desktop uses a user-space process (`com.docker.vpnkit`) for network connectivity, which inherits constraints like firewall rules, VPN settings, and HTTP proxy properties from the user that launched it. + +#### Does Docker Desktop for Windows with Hyper-V allow users to create other VMs? + +No. The `DockerDesktopVM` name is hard-coded in the service, so you cannot use Docker Desktop to create or manipulate other virtual machines. + +#### How does Docker Desktop achieve network isolation with Hyper-V and WSL 2? + +Docker Desktop uses the same VM processes for both WSL 2 (in the `docker-desktop` distribution) and Hyper-V (in `DockerDesktopVM`). Host/VM communication uses `AF_VSOCK` hypervisor sockets (shared memory) rather than network switches or interfaces. All host networking is performed using standard TCP/IP sockets from the `com.docker.vpnkit.exe` and `com.docker.backend.exe` processes. + +For more information, see [How Docker Desktop networking works under the hood](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood/). diff --git a/content/manuals/faqs/security.md b/content/manuals/faqs/security.md new file mode 100644 index 000000000000..c536ca560c34 --- /dev/null +++ b/content/manuals/faqs/security.md @@ -0,0 +1,240 @@ +--- +description: Frequently asked questions about Docker single sign-on, identity providers, user management, SSO enforcement, and domain verification +keywords: Docker, Docker Hub, SSO FAQs, single sign-on, identity providers, IdP, SAML, Entra ID, user management, SCIM, JIT, administration, security, SSO enforcement, SSO domains, domain verification, DNS, TXT records +title: Security FAQs +linkTitle: Security +weight: 20 +tags: [FAQ] +toc_max: 2 +aliases: + - /single-sign-on/faqs/ + - /faq/security/single-sign-on/faqs/ + - /single-sign-on/saml-faqs/ + - /faq/security/single-sign-on/saml-faqs/ + - /security/faqs/single-sign-on/saml-faqs/ + - /security/faqs/single-sign-on/faqs/ + - /enterprise/security/single-sign-on/FAQs/general/ + - /single-sign-on/idp-faqs/ + - /faq/security/single-sign-on/idp-faqs/ + - /security/faqs/single-sign-on/idp-faqs/ + - /enterprise/security/single-sign-on/FAQs/idp-faqs/ + - /single-sign-on/users-faqs/ + - /faq/security/single-sign-on/users-faqs/ + - /security/faqs/single-sign-on/users-faqs/ + - /enterprise/security/single-sign-on/FAQs/users-faqs/ + - /single-sign-on/enforcement-faqs/ + - /faq/security/single-sign-on/enforcement-faqs/ + - /security/faqs/single-sign-on/enforcement-faqs/ + - /enterprise/security/single-sign-on/FAQs/enforcement-faqs/ + - /single-sign-on/domain-faqs/ + - /faq/security/single-sign-on/domain-faqs/ + - /security/faqs/single-sign-on/domain-faqs/ + - /enterprise/security/single-sign-on/FAQs/domain-faqs/ + - /faqs/sso-faqs/ + - /faqs/domain-faqs/ +--- + +## SSO + +### What SSO flows does Docker support? + +Docker supports Service Provider Initiated (SP-initiated) SSO flow. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process. + +### Does Docker SSO support multi-factor authentication? + +When an organization uses SSO, multi-factor authentication is controlled at the identity provider level, not on the Docker platform. + +### Can I retain my Docker ID when using SSO? + +Users with personal Docker IDs retain ownership of their repositories, images, and assets. When SSO is enforced, existing accounts with company domain emails are connected to the organization. Users signing in without existing accounts automatically have new accounts and Docker IDs created. + +### Are there any firewall rules required for SSO configuration? + +No specific firewall rules are required as long as `login.docker.com` is accessible. This domain is commonly accessible by default, but some organizations may need to allow it in their firewall settings if SSO setup encounters issues. + +### Does Docker use my IdP's default session timeout? + +Yes, Docker supports your IdP's session timeout using a custom `dockerSessionMinutes` SAML attribute instead of the standard `SessionNotOnOrAfter` element. See [SSO attributes](/manuals/security/provisioning/_index.md#sso-attributes) for more information. + +### Can I use multiple identity providers with Docker SSO? + +Yes, Docker supports multiple IdP configurations. A domain can be associated with multiple IdPs. Docker supports Entra ID (formerly Azure AD) and identity providers that support SAML 2.0. + +### Can I change my identity provider after configuring SSO? + +Yes. Delete your existing IdP configuration in your Docker SSO connection, then [configure SSO using your new IdP](/manuals/security/authentication/single-sign-on/connect.md). If you had already turned on enforcement, turn off enforcement before updating the provider connection. + +### What information do I need from my identity provider to configure SSO? + +To turn on SSO in Docker, you need the following from your IdP: + +- SAML: Entity ID, ACS URL, Single Logout URL, and the public X.509 certificate +- Entra ID (formerly Azure AD): Client ID, Client Secret, AD Domain + +### What happens if my existing certificate expires? + +Contact your identity provider to retrieve a new X.509 certificate. Update with the new certificate in [SSO configuration settings](/manuals/security/authentication/single-sign-on/manage.md#manage-sso-connections) from Docker Home. + +- If your organization enforces SSO, username and password credentials won't work. +- If your organization doesn't enforce SSO, users can sign in with their username and password credentials. + +If you need additional help, contact [Docker support](https://app.docker.com/support/contact). + +### What happens if my IdP goes down when SSO is turned on? + +If SSO is enforced, users can't access Docker Hub when your IdP is down. Users can still access Docker Hub images from the CLI using personal access tokens. + +If SSO is turned on but not enforced, users can fall back to username/password authentication. + +### Do bot accounts need seats to access organizations using SSO? + +Yes, bot accounts need seats like regular users, requiring a non-aliased domain email in the IdP and using a seat in Docker Hub. You can add bot accounts to your IdP and create access tokens to replace other credentials. + +### How can I troubleshoot an Entra ID SSO connection error? + +Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations). + +## Provisioning + +### Does SAML SSO use Just-in-Time provisioning? + +Yes. Docker turns on Just-in-Time (JIT) provisioning when you configure an SSO +connection. You can turn off JIT after you configure and test SCIM. See +[Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md). + +### Can I use JIT and SCIM together? + +Yes, but Docker recommends using one provisioning source. When both are +enabled, sign-in and SCIM sync can each change a user's full name and team +memberships, so those values can move back and forth. Before you enable both, +review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). + +### How can I give a user immediate access with SCIM? + +If your IdP supports Provision on Demand, use it to synchronize the user +before the next scheduled SCIM synchronization. This provides immediate +provisioning without enabling JIT. + +### Do I need to manually add users to my organization? + +Not when JIT, SCIM, or auto-provisioning covers the user. If none of those +methods applies, for example when JIT is turned off and the user isn't +assigned to the Docker application in your IdP, an organization owner must +invite the user. + +### Can users use different email addresses to authenticate through SSO? + +All users must authenticate using the email domain specified during SSO setup. +Users with email addresses that don't match the verified domain can sign in as +guests with username and password if SSO isn't enforced, but only if they've +been invited. + +### How will users know they're being added to a Docker organization? + +When SSO is turned on, users are prompted to authenticate through SSO the next +time they sign in to Docker Hub or Docker Desktop. The system detects their +domain email and prompts them to sign in with SSO credentials instead. + +For CLI access, users must authenticate using personal access tokens. + +### Can I convert existing users from non-SSO to SSO accounts? + +Yes, you can convert existing users to SSO accounts. Ensure users have: + +- Company domain email addresses and accounts in your IdP +- Docker Desktop version 4.4.2 or later +- Personal access tokens created to replace passwords for CLI access +- CI/CD pipelines updated to use [PATs or OATs](/manuals/security/access-tokens/_index.md) instead of passwords, or an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) for GitHub Actions + +For detailed instructions, see [Configure single sign-on](/manuals/security/authentication/single-sign-on/connect.md). + +### Is Docker SSO fully synced with the IdP? + +Not with JIT alone. JIT provisions users when they authenticate, but it +doesn't deprovision users who leave your IdP. You must +[remove those users](/manuals/accounts/organization/manage/members.md#remove-member-from-organization) +manually. + +[SCIM](/manuals/security/provisioning/scim/_index.md) provides continuous user +and group synchronization, including automatic deprovisioning. + +### How does turning off Just-in-Time provisioning affect user sign-in? + +You can turn off JIT only while SCIM is enabled. With JIT turned off, users +must already be members, have a pending invitation, or be provisioned through +SCIM. Users who don't meet these criteria get an "Access denied" error and +need an administrator to invite them. + +See [Disable JIT provisioning](/manuals/security/provisioning/just-in-time.md#disable). + +### Can someone join an organization without an invitation? + +Yes. JIT can add users when they sign in through SSO, SCIM can provision users +assigned in the IdP, and auto-provisioning can add existing Docker users whose +email addresses match a verified domain. Without an automatic provisioning +method, an organization owner must invite the user. + +### What happens to existing licensed users when SCIM is turned on? + +SCIM can manage and deprovision organization members whose email domain is +verified on the SSO connection, including users created through JIT or added +manually. When your IdP pushes a user with a matching email address, SCIM +links the existing Docker account. Members whose email domain isn't verified +on the connection stay outside SCIM. To use SCIM as the only provisioning +source, see +[Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). + +### Is user information visible in Docker Hub? + +All Docker accounts have public profiles associated with their namespace. If +you don't want user information (like full names) to be visible, remove those +attributes from your SSO and SCIM mappings, or use different identifiers to +replace users' full names. + +## Enforcement + +### Does Docker SSO support authenticating through the command line? + +When SSO is enforced, [passwords are prevented from accessing the Docker CLI](/manuals/security/security-announcements.md#deprecation-of-password-logins-on-cli-when-sso-enforced). Each user must sign in with a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md). Users who already used a PAT before SSO enforcement can continue using that PAT. + +For CI/CD and other automation, use an [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md) or a PAT. For GitHub Actions, you can use an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) instead of storing a long-lived token. See [Access tokens](/manuals/security/access-tokens/_index.md). + +### How does SSO affect automation systems and CI/CD pipelines? + +Before enforcing SSO, replace passwords in automation and CI/CD with an access token. Prefer an [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md) for pipelines owned by the organization. Use a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md) when the job should run as a person. For GitHub Actions, you can use an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) instead of storing a long-lived token. + +### Can I turn on SSO without enforcing it immediately? + +Yes, you can turn on SSO without enforcement. Users can choose between Docker ID (standard email and password) or domain-verified email address (SSO) at the sign-in screen. + +### Why can a user sign in with a username and password when SSO is enforced? + +Guest users who aren't part of your registered domain but have been invited to your organization don't sign in through your SSO identity provider. SSO enforcement only applies to users who belong to your verified domain. + +### Can I test SSO functionality before going to production? + +Yes, you can create a test organization with a 5-seat Business subscription. When testing, turn on SSO but don't enforce it, or all domain email users will be forced to sign in to the test environment. + +### What is enforcing SSO versus enforcing sign-in? + +These are separate features you can use independently or together: + +- Enforcing SSO ensures users sign in using SSO credentials instead of their Docker ID, enabling better credential management. +- Enforcing sign-in to Docker Desktop ensures users always sign in to accounts that are members of your organization, so security settings and subscription benefits are always applied. + +For more details, see [Enforce sign-in for Desktop](/manuals/desktop/enterprise/enforce-sign-in/_index.md#enforcing-sign-in-versus-enforcing-single-sign-on-sso). + +## Domain + +### Can I add sub-domains? + +Yes, you can add sub-domains to your SSO connection. All email addresses must use domains you've added to the connection. Verify that your DNS provider supports multiple TXT records for the same domain. + +### Do I need to keep the DNS TXT record permanently? + +You can remove the TXT record after one-time verification to add the domain. However, if your organization changes identity providers and needs to set up SSO again, you'll need to verify the domain again. + +### Can I verify the same domain for multiple organizations? + +You can't verify the same domain for multiple organizations at the organization level. To verify one domain for multiple organizations, you must have a Docker Business subscription and create a company. Companies allow centralized management of organizations and domain verification at the company level. diff --git a/content/manuals/faqs/subscription-billing.md b/content/manuals/faqs/subscription-billing.md new file mode 100644 index 000000000000..0271fc39756e --- /dev/null +++ b/content/manuals/faqs/subscription-billing.md @@ -0,0 +1,112 @@ +--- +title: Subscription and billing FAQs +linkTitle: Subscription and billing +description: Frequently asked questions about Docker subscriptions, billing, failed payments, taxes, and plans. +keywords: subscription faqs, billing, docker plans, renewal, failed payments, sales tax, VAT, academic pricing, pay by invoice, subscription transfer +tags: [FAQ] +toc_max: 2 +weight: 35 +aliases: + - /subscription/faq/ + - /billing/faqs/ + - /subscription-billing/faqs/subscription/ + - /subscription-billing/faqs/billing/ +--- + +For more information on Docker subscriptions, see +[Subscription and billing](/manuals/subscription-billing/_index.md). + +## Subscriptions + +### Can I transfer my subscription from one user or organization account to another? + +Subscriptions are non-transferable between accounts or organizations. + +### Can I pause or delay my Docker subscription? + +You can't pause or delay a subscription, but you can downgrade your +subscription. If a subscription invoice isn't paid by the due date, there's a +15-day grace period starting from the due date. + +### Does Docker offer academic pricing? + +For academic pricing, contact the +[Docker Sales Team](https://www.docker.com/company/contact). + +### How can I contribute to Docker content? + +Docker offers two content contribution programs: + +- [Docker-Sponsored Open Source Program (DSOS)](/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md) + for open source projects +- [Docker Verified Publisher (DVP)](/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md) + for commercial publishers + +You can also join the +[Developer Preview Program](https://www.docker.com/community/get-involved/developer-preview/) +or sign up for early access programs to participate in research and try new +features. + +### How do I upgrade to Docker Pro? + +To upgrade to Docker Pro, go to the +Docker pricing page +and select **Buy now**. + +## Payments + +### What happens if my subscription payment fails? + +If your subscription payment fails, there is a grace period of 15 days, +including the due date. Docker attempts to collect the payment three times using +the following schedule: + +- 3 days after the due date +- 5 days after the previous attempt +- 7 days after the previous attempt + +Docker also sends an email notification +`Action Required - Credit Card Payment Failed` with an attached unpaid invoice +after each failed payment attempt. + +If the invoice remains unpaid after the grace period, the +subscription downgrades to a free subscription and all paid features are +disabled. + +### Can I manually retry a failed payment? + +Yes. If your payment fails, select **Pay now** to retry the payment through +Stripe. + +Before retrying, verify that your default payment method is up to date. For +instructions, see +[Manage a payment method](/manuals/subscription-billing/manage/payment-method.md#manage-payment-method). + +### Can I use pay by invoice for upgrades or additional seats? + +No. Pay by invoice is only available for renewing annual subscriptions, not for +purchasing upgrades or additional seats. You must use card payment or US bank +accounts for these changes. + +For a list of supported payment methods, see +[Add or update a payment method](/manuals/subscription-billing/manage/payment-method.md). + +> [!TIP] +> +> Need to upgrade? Compare Docker Team and Docker Business to choose the plan that best fits your team's needs. + +## Taxes + +### Does Docker collect sales tax and VAT? + +Docker collects sales tax or VAT from the following customers: + +- For United States customers, Docker began collecting sales tax on + July 1, 2024. +- For European customers, Docker began collecting VAT on March 1, 2025. +- For United Kingdom customers, Docker began collecting VAT on May 1, 2025. + +To help ensure correct tax assessments, keep your +[billing information](/manuals/subscription-billing/manage/details.md) up to date. For details on +adding a VAT number or submitting a US tax exemption certificate, see +[Taxes](/manuals/subscription-billing/manage/tax-certificate.md). diff --git a/content/manuals/offload/configuration.md b/content/manuals/offload/configuration.md index f0275bebbde5..83bf541a121c 100644 --- a/content/manuals/offload/configuration.md +++ b/content/manuals/offload/configuration.md @@ -17,7 +17,7 @@ settings when allowed by their organization. For organization owners, you can manage Docker Offload settings for all users in your organization. For more details, see [Manage Docker -products](../admin/organization/manage/manage-products.md). To view usage for Docker +products](../accounts/organization/manage/manage-products.md). To view usage for Docker Offload, see [Docker Offload usage](/offload/usage/). ## Configure settings in Docker Desktop diff --git a/content/manuals/offload/quickstart.md b/content/manuals/offload/quickstart.md index 27b864a2e132..a35e8b30b2ca 100644 --- a/content/manuals/offload/quickstart.md +++ b/content/manuals/offload/quickstart.md @@ -19,7 +19,7 @@ This quickstart covers the steps developers need to get started with Docker Offl > > If you're an organization owner, to get started you must contact sales and subscribe your > organization to use Docker Offload. After subscribing, see [Manage Docker -> products](../admin/organization/manage/manage-products.md) to learn how to manage +> products](../accounts/organization/manage/manage-products.md) to learn how to manage > access for the developers in your organization. diff --git a/content/manuals/platform-release-notes.md b/content/manuals/platform-release-notes.md index b080efd04e30..b604df6501e1 100644 --- a/content/manuals/platform-release-notes.md +++ b/content/manuals/platform-release-notes.md @@ -1,36 +1,334 @@ --- -title: Release notes for Docker Home, the Admin Console, billing, security, and subscription features +title: Accounts and admin release notes linkTitle: Release notes -description: Learn about the new features, bug fixes, and breaking changes for Docker Home, the Admin Console, and billing and subscription features -keywords: Docker Home, Docker Admin Console, billing, subscription, security, admin, releases, what's new +description: >- + Learn about new features, bug fixes, and breaking changes for Docker accounts + and admin features, including Docker Home, billing, security, and + subscriptions. +keywords: accounts, admin, Docker Home, billing, subscription, security, + release notes, what's new weight: 60 params: sidebar: - group: Platform + group: Accounts and admin tags: [Release notes, admin] --- -This page provides details on new features, enhancements, known issues, and bug fixes across Docker Home, the Admin Console, billing, security, and subscription functionalities. +This page lists new features, enhancements, known issues, and bug fixes for +Docker accounts and admin features, including Docker Home, billing, security, +and subscriptions. + +## 2026-09-30 + +### Bug fixes and enhancements + +- Accounts that already have cloud sandboxes skip + [Docker Agentic Platform](/manuals/subscription-billing/plans/docker-agentic-platform.md) + checkout. + +## 2026-09-29 + +### New + +- Organization owners can now + [assign a license to a team](/manuals/accounts/organization/manage/manage-licenses.md#teams). + Every member of the team receives the license, including people who join the + team later. Each member uses one license per product. +- The + [Licenses page](/manuals/accounts/organization/manage/manage-licenses.md#view-licenses) + in Docker Home shows how many licenses are available and whether they are + assigned to teams or to individual members. + +## 2026-09-28 + +### Bug fixes and enhancements + +- [Creating a team](/manuals/accounts/organization/manage/manage-a-team.md#create-a-team) + in Docker Home opens that team's page. +- The + [member list CSV](/manuals/accounts/organization/manage/members.md#export-a-member-list-csv) + includes a **Licenses** column when the organization has at least one active + license pool. The column lists each member's assigned licenses. + +## 2026-09-24 + +### New + +- You can now subscribe to the + [Docker Agentic Platform](/manuals/subscription-billing/plans/docker-agentic-platform.md) + pay-as-you-go plan with an individual account to run agents in cloud + sandboxes. Compute is metered by the second while a sandbox runs. + +### Bug fixes and enhancements + +- The [support request form](https://app.docker.com/support/contact) **Legal** + topic includes **PII/Sensitive information**, **Service abuse**, and + **Trademark takedowns**. + +## 2026-09-14 + +### New + +- Organization owners can now + [export a member list](/manuals/accounts/organization/manage/members.md#export-a-member-list-csv) + from Docker Home and receive the CSV by email. Docker generates the file + asynchronously and emails a download link to the owner. + +## 2026-08-20 + +### New + +- [Docker Verified Publisher](/manuals/subscription-billing/plans/docker-verified-publisher.md) + Starter and Growth plans are now available via self-serve. Organizations + can apply and subscribe without contacting sales. + +## 2026-08-14 + +### New + +- Administrators can now + [select a product license when inviting a member](/manuals/accounts/organization/manage/manage-licenses.md#licenses-and-invites). + Docker assigns the license when the invitee accepts. + +## 2026-07-31 + +### New + +- Administrators can now create + [OIDC connections](/manuals/security/authentication/oidc-connections/_index.md) + so GitHub Actions workflows authenticate to Docker with short-lived tokens + instead of stored personal or organization access tokens. Available for + Docker Team, Docker Business, Docker Hardened Images, and Docker Sponsored + Open Source organizations. + +## 2026-06-18 + +### New + +- Custom roles now include + [AI Governance permissions](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md#ai-governance) + so owners can delegate policy management to other users and teams. + +## 2026-06-02 + +### New + +- Administrators can now provision products to organization members with + [licenses](/manuals/accounts/organization/manage/manage-licenses.md). + Licenses were introduced with AI Governance. Owners can assign or revoke + them from the Members page, or turn on automatic assignment when a member + first uses a supported product. + +## 2026-05-19 + +### New + +- You can now purchase + [Gordon Plus, Max, and Ultra plans](/manuals/subscription-billing/plans/gordon.md) + for individual accounts from the billing portal in Docker Home. +- Organizations can now purchase + [DHI Select](/manuals/subscription-billing/plans/dhi.md) repositories via + self-serve from the billing portal in Docker Home. + +## 2026-05-12 + +### New + +- [AI Governance](/manuals/subscription-billing/plans/ai-governance.md) is + now available. Administrators can purchase licenses through sales, + [assign them to members](/manuals/accounts/organization/manage/manage-licenses.md), + and enforce + [organization policies](/manuals/ai/sandboxes/governance/_index.md) for + Docker AI products from Docker Home. + +## 2026-03-03 + +### New + +- [DHI Select](/manuals/subscription-billing/plans/dhi.md) is now available + as a Docker Hardened Images plan for organizations that need SLA-backed + patching and compliance-ready images. + +## 2026-02-18 + +### New + +- Administrators can now + [configure DVP analytics settings](/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md#configure-dvp-analytics-settings) + for consuming domain and benchmark report allocations in the Admin + Console. ## 2026-02-13 ### New - Administrators can now control whether organization members can push content - to their personal namespaces on Docker Hub with [namespace access - control](/manuals/enterprise/security/hardened-desktop/namespace-access.md). + to their personal namespaces on Docker Hub with + [namespace access control](/manuals/desktop/enterprise/hardened-desktop/namespace-access.md). - Administrators can now prevent creating public repositories within - organization namespaces using the [Disable public - repositories](/manuals/docker-hub/settings.md#disable-creation-of-public-repos) setting. + organization namespaces using the + [Disable public repositories](/manuals/docker-hub/settings.md#disable-creation-of-public-repos) + setting. ## 2026-01-27 ### New -- Administrators can now use an allow list with [Image Access - Management](/manuals/enterprise/security/hardened-desktop/image-access-management.md) +- Administrators can now use an allow list with + [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md) to approve specific repositories that bypass image access controls. +## 2025-11-04 + +### New + +- Owners can now create + [custom roles](/manuals/security/roles-and-permissions/custom-roles/_index.md) + and assign them to members and teams. + +## 2025-10-28 + +### New + +- Docker Business subscribers can now add + [Premium Support](/manuals/support/_index.md#paid-subscription-support), + with faster response times and 24/7 availability. + +## 2025-10-22 + +### New + +- Organizations can now + [pay by invoice](/manuals/subscription-billing/manage/payment-method.md#pay-by-invoice). + +## 2025-10-14 + +### Bug fixes and enhancements + +- Docker Home now keeps + [activity logs](/manuals/accounts/organization/activity-logs.md#access-activity-logs) + for 30 days. Use the Docker Hub API to retrieve older events. + +## 2025-10-07 + +### Bug fixes and enhancements + +- Organization management has moved out of Docker Hub. Manage organizations in + Docker Home. + +## 2025-06-30 + +### New + +- Organization owners can now + [export Docker Desktop user data](/manuals/accounts/organization/insights.md#export-docker-desktop-user-data) + from Insights as a CSV file. + +## 2025-06-23 + +### Bug fixes and enhancements + +- [Organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) + now work with Docker Scout. + +## 2025-06-18 + +### New + +- Organization owners can now + [resend invitations in bulk](/manuals/accounts/organization/manage/members.md#manage-invitations) + from the Members page. + +## 2025-06-10 + +### Bug fixes and enhancements + +- [Activity logs](/manuals/accounts/organization/activity-logs.md) now record + single sign-on connection changes, and changes to SCIM and just-in-time + provisioning. + +## 2025-05-12 + +### New + +- You can now connect + [more than one identity provider](/manuals/security/authentication/single-sign-on/connect.md#configure-multiple-idps) + to a single sign-on domain. Users choose a provider when they sign in with + SSO. + +## 2025-04-30 + +### New + +- You can now pay for a subscription with a + [verified US bank account](/manuals/subscription-billing/manage/payment-method.md#verify-a-bank-account). + +## 2025-04-22 + +### Bug fixes and enhancements + +- [Personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md) + now transfer to the organization owners when you + [convert a user account into an organization](/manuals/accounts/organization/setup/convert-account.md). + +## 2025-04-08 + +### New + +- Organization owners can now onboard an organization with + [guided setup](/manuals/accounts/organization/setup/onboard.md#onboard-with-guided-setup) + in Docker Home. + +## 2025-04-01 + +### New + +- [Organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) + are now generally available. +- Single sign-on now supports the + [`dockerSessionMinutes` attribute](/manuals/security/provisioning/_index.md#sso-attributes), + so a session can follow the identity provider timeout. +- Administrators can now + [track whether users comply with Docker Desktop settings policies](/manuals/desktop/enterprise/hardened-desktop/settings-management/compliance-reporting.md) + from Docker Home (Early Access). Compliance status is reported by Docker + Desktop version 4.40 and later. + +## 2025-03-12 + +### New + +- You can now + [disconnect a linked Google or GitHub account](/manuals/accounts/individual/manage-account.md#manage-connected-accounts) + from Account settings. + +## 2025-03-11 + +### New + +- [Organization access tokens](/manuals/security/access-tokens/reference.md#organization-access-token-scopes) + now include repository scopes and organization management scopes for members, + invites, and groups. + +## 2025-02-21 + +### Bug fixes and enhancements + +- Organization access tokens now work with Docker Build Cloud and the Docker + Hub APIs. Company owners can manage them. + +## 2025-02-11 + +### New + +- Docker Home and the Docker Admin Console are now generally available. + +## 2025-01-31 + +### Bug fixes and enhancements + +- Docker began collecting VAT for all European countries on March 1, 2025. See + [Sales tax exemption and VAT](/manuals/subscription-billing/manage/tax-certificate.md). + ## 2025-01-30 ### New @@ -38,58 +336,82 @@ This page provides details on new features, enhancements, known issues, and bug - Installing Docker Desktop via the PKG installer is now generally available. - Enforcing sign-in via configuration profiles is now generally available. +## 2025-01-10 + +### Bug fixes and enhancements + +- [Activity logs](/manuals/accounts/organization/activity-logs.md) now record + when a settings policy is created, updated, deleted, or transferred. + ## 2024-12-10 ### New -- New Docker subscriptions are now available. For more information, see [Docker - subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsPlatformReleaseNotes) and [Announcing - Upgraded Docker Plans: Simpler, More Value, Better Development and - Productivity](https://www.docker.com/blog/november-2024-updated-plans-announcement/). +- New Docker subscriptions are now available. For more information, see + [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsPlatformReleaseNotes) + and + [Announcing Upgraded Docker Plans: Simpler, More Value, Better Development and Productivity](https://www.docker.com/blog/november-2024-updated-plans-announcement/). ## 2024-11-18 ### New - Administrators can now: - - Enforce sign-in with [configuration profiles](/manuals/enterprise/security/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) (Early Access). + - Enforce sign-in with + [configuration profiles](/manuals/desktop/enterprise/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) + (Early Access). - Enforce sign-in for more than one organization at a time (Early Access). - - Deploy Docker Desktop for Mac in bulk with the [PKG installer](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) (Early Access). - - [Use Desktop Settings Management via the Docker Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md) (Early Access). + - Deploy Docker Desktop for Mac in bulk with the + [PKG installer](/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md) + (Early Access). + - [Use Desktop Settings Management via the Docker Admin Console](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) + (Early Access). ### Bug fixes and enhancements -- Enhance Container Isolation (ECI) has been improved to: - - Permit admins to [turn off Docker socket mount restrictions](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#allowing-all-containers-to-mount-the-docker-socket). - - Support wildcard tags when using the [`allowedDerivedImages` setting](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images). +- Enhanced Container Isolation (ECI) has been improved to: + - Permit administrators to + [turn off Docker socket mount restrictions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#allowing-all-containers-to-mount-the-docker-socket). + - Support wildcard tags when using the + [`allowedDerivedImages` setting](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images). ## 2024-11-11 ### New -- [Personal access tokens](/security/access-tokens/) (PATs) now support expiration dates. +- [Personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md) + (PATs) now support expiration dates. ## 2024-10-15 ### New -- Beta: You can now create [organization access tokens](/security/for-admins/access-tokens/) (OATs) to enhance security for organizations and streamline access management for organizations in the Docker Admin Console. +- Beta: You can now create + [organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) + (OATs) to enhance security for organizations and streamline access + management for organizations in the Docker Admin Console. ## 2024-08-29 ### New -- Deploying Docker Desktop via the [MSI installer](/manuals/enterprise/enterprise-deployment/msi-install-and-configure.md) is now generally available. -- Two new methods to [enforce sign-in](/manuals/enterprise/security/enforce-sign-in/_index.md) (Windows registry key and `.plist` file) are now generally available. +- Deploying Docker Desktop via the + [MSI installer](/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md) + is now generally available. +- Two new methods to + [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) + (Windows registry key and `.plist` file) are now generally available. ## 2024-08-24 ### New -- Administrators can now view [organization Insights](/manuals/admin/insights.md). +- Administrators can now view + [organization Insights](/manuals/accounts/organization/insights.md). ## 2024-07-17 ### New -- You can now centrally access and manage Docker products in [Docker Home](https://app.docker.com). \ No newline at end of file +- You can now centrally access and manage Docker products in + [Docker Home](https://app.docker.com). diff --git a/content/manuals/retired.md b/content/manuals/retired.md index d0049b3afa6f..71994d3ab6ab 100644 --- a/content/manuals/retired.md +++ b/content/manuals/retired.md @@ -63,6 +63,11 @@ aliases: - /toolbox/toolbox_install_mac/ - /toolbox/toolbox_install_windows/ - /desktop/features/dev-environments/ + - /scout/policy/scores/ + - /scout/integrations/environment/sysdig/ + - /scout/integrations/team-collaboration/slack/ + - /scout/integrations/code-quality/sonarqube/ + - /scout/integrations/source-code-management/github/ --- This document provides an overview of Docker features, products, and @@ -143,12 +148,46 @@ project requirements. ### Docker Desktop sandboxes Docker Desktop sandboxes let users run AI coding agents in isolated microVMs -through the `docker sandbox` command. The Docker Desktop integration is -deprecated. Use the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md) -instead. - -You can still view the -[Docker Desktop sandboxes documentation](/manuals/ai/sandboxes/docker-desktop.md). +through the `docker sandbox` command. The `docker sandbox` plugin was removed +in Docker Desktop 4.80.0. Use the standalone +[`sbx` CLI](/manuals/ai/sandboxes/_index.md) instead. + +### Docker Scout features + +The following Docker Scout features have been retired or deprecated. For +details, see the [Scout platform release notes](/manuals/scout/release-notes/platform.md). + +- Health scores and Scout Everywhere: graded Docker Hub images from A to F + based on policy compliance, surfaced across Docker Hub. Retired July 1, 2026. +- Sysdig integration: detected images running in your cluster via the Sysdig API. + Retired July 1, 2026. +- GitHub source code management integration: linked images to their source + repository and automated base-image updates via PRs. Retired July 1, 2026. + For base-image updates, use + [GitHub Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) + with `package-ecosystem: "docker"`. For image-to-source linkage, build with + `--provenance=mode=max`. This retirement doesn't affect the + [`docker/scout-action`](https://github.com/docker/scout-action) GitHub Action + for CI pipelines. +- Slack integration: sent vulnerability and policy compliance notifications to + Slack channels. Retired July 30, 2026. +- Notifications: alerted users to newly disclosed CVEs in-product and by + email. Retired September 1, 2026. To surface CVE and policy results without + push notifications, integrate `docker scout cves` or `docker scout policy` + into your CI pipeline. +- Native Amazon ECR integration: automatically analyzed images pushed to ECR + registries using a CloudFormation stack. Retired September 1, 2026. Docker + Scout still supports ECR through + [`docker scout watch`](/manuals/scout/integrations/registry.md). +- Native Azure Container Registry integration: automatically analyzed images + pushed to ACR registries using an ARM template. Retired September 1, 2026. + Docker Scout still supports ACR through + [`docker scout watch`](/manuals/scout/integrations/registry.md). +- Policies page in the Dashboard: the `docker scout policy` + CLI continues to work. Retired September 1, 2026. See + [Evaluate policies](/manuals/scout/policy/local.md). +- SonarQube integration: surfaced SonarQube quality gate results as a Docker + Scout policy. Retired September 1, 2026. ### GitHub Copilot extension @@ -167,7 +206,7 @@ Enhanced Service Account add-ons provided tiered pull rate limits for automated workflows and service accounts accessing Docker Hub. Docker recommends transitioning to [Organization Access Tokens -(OATs)](/manuals/enterprise/security/access-tokens.md), which provide secure, +(OATs)](/manuals/security/access-tokens/organization-access-tokens.md), which provide secure, programmatic access to Docker Hub with granular repository permissions, token expiration, and better security auditing. OATs are included with Docker Team and Business subscriptions and offer similar functionality without requiring @@ -180,6 +219,16 @@ Docker images from source code in an external repository and automatically pushi the built image to your Docker repositories. This feature has been deprecated and will be removed on April 1, 2027. +### Docker Content Trust (DCT) + +Docker Content Trust (DCT) and the Notary v1 service at `notary.docker.io` are +being fully retired. If you've never set `DOCKER_CONTENT_TRUST=1` or used +`docker trust` commands, this change doesn't affect you. The service shuts down +completely on December 8, 2026, following brownout windows in July and August. +For the timeline, migration guidance, and modern alternatives such as +Sigstore/Cosign and Notation, see the [Docker Content Trust retirement and +migration blog post](https://www.docker.com/blog/docker-content-trust-retirement-and-migration-guidance/). + ## Open source projects diff --git a/content/manuals/scout/_index.md b/content/manuals/scout/_index.md index 9f260dde57ce..7f5046903622 100644 --- a/content/manuals/scout/_index.md +++ b/content/manuals/scout/_index.md @@ -38,7 +38,7 @@ grid: Ensure that your artifacts align with supply chain best practices. icon: shield-check - title: Upgrade - link: /subscription/change/ + link: /subscription-billing/manage/plans/ description: | A Personal subscription includes up to 1 repository. Upgrade for more. icon: arrow-up-circle @@ -53,6 +53,5 @@ The SBOM is matched against a continuously updated vulnerability database to pin Docker Scout is a standalone service and platform that you can interact with using Docker Hub, the Docker CLI, and the Docker Scout Dashboard. -Docker Scout also facilitates integrations with third-party systems, such as container registries and CI platforms. {{< grid >}} diff --git a/content/manuals/scout/deep-dive/data-handling.md b/content/manuals/scout/deep-dive/data-handling.md index 92ae3d4af8b3..9811d4ebc1e7 100644 --- a/content/manuals/scout/deep-dive/data-handling.md +++ b/content/manuals/scout/deep-dive/data-handling.md @@ -70,7 +70,7 @@ and packages, and application-level packages such as maven, npm, and so on. ### Environment metadata If you integrate Docker Scout with your runtime environment via the -[Sysdig integration](/manuals/scout/integrations/environment/sysdig.md), +[CLI integration](/manuals/scout/integrations/environment/cli.md), Docker Scout collects the following data points about your deployments: - Kubernetes namespace diff --git a/content/manuals/scout/explore/analysis.md b/content/manuals/scout/explore/analysis.md index 655eb1022bc9..87d1d4b3ea0d 100644 --- a/content/manuals/scout/explore/analysis.md +++ b/content/manuals/scout/explore/analysis.md @@ -205,9 +205,10 @@ categorized as **Unspecified** (U). Docker Scout doesn't implement a proprietary vulnerability metrics system. All metrics are inherited from security advisories that Docker Scout integrates -with. Advisories may use different thresholds for classifying vulnerabilities, -but most of them adhere to the CVSS v3.0 specification, which maps CVSS scores -to severity ratings according to the following table: +with. Advisories may use different thresholds for classifying vulnerabilities. +When the selected advisory source provides both CVSS v4 and v3 data, Docker +Scout prefers CVSS v4. The qualitative severity ratings defined by CVSS v3.x +and v4.0 use the same score ranges: | CVSS score | Severity rating | | ---------- | ---------------- | diff --git a/content/manuals/scout/explore/dashboard.md b/content/manuals/scout/explore/dashboard.md index 032ae256d1d7..72c0455e75fa 100644 --- a/content/manuals/scout/explore/dashboard.md +++ b/content/manuals/scout/explore/dashboard.md @@ -19,8 +19,6 @@ they need to focus on. ## Overview -![A screenshot of the Docker Scout Dashboard overview](../images/dashboard-overview.webp?border=true) - The **Overview** tab provides a summary for the repositories in the selected organization. @@ -28,11 +26,6 @@ At the top of this page, you can select which **Environment** to view. By default, the most recently pushed images are shown. To learn more about environments, see [Environment monitoring](/manuals/scout/integrations/environment/_index.md). -The **Policy** boxes show your current compliance rating for each policy, and a -trend indication for the selected environment. The trend describes the policy -delta for the most recent images compared to the previous version. -For more information about policies, see [Policy Evaluation](/manuals/scout/policy/_index.md). - The vulnerability chart shows the total number of vulnerabilities for images in the selected environment over time. You can configure the timescale for the chart using the drop-down menu. @@ -40,52 +33,32 @@ chart using the drop-down menu. Use the header menu at the top of the website to access the different main sections of the Docker Scout Dashboard: -- **Policies**: shows the policy compliance for the organization, see [Policies](#policies) - **Images**: lists all Docker Scout-enabled repositories in the organization, see [Images](#images) - **Base images**: lists all base images used by repositories in an organization - **Packages**: lists all packages across repositories in the organization - **Vulnerabilities**: lists all CVEs in the organization's images, see [Vulnerabilities](#vulnerabilities) -- **Integrations**: create and manage third-party integrations, see [Integrations](#integrations) - **Settings**: manage repository settings, see [Settings](#settings) -## Policies - -The **Policies** view shows a breakdown of policy compliance for all of the -images in the selected organization and environment. You can use the **Image** -drop-down menu to view a policy breakdown for a specific environment. - -For more information about policies, see [Policy Evaluation](/manuals/scout/policy/_index.md). - ## Images The **Images** view shows all images in Scout-enabled repositories for the selected environment. You can filter the list by selecting a different environment, or by repository name using the text filter. -![Screenshot of the images view](../images/dashboard-images.webp) - For each repository, the list displays the following details: - The repository name (image reference without the tag or digest) - The most recent tag of the image in the selected environment - Operating systems and architectures for the most recent tag - Vulnerabilities status for the most recent tag -- Policy status for the most recent tag Selecting a repository link takes you to a list of all images in that repository that have been analyzed. From here you can view the full analysis results for a specific image, and compare tags to view the differences in packages and vulnerabilities Selecting an image link takes you to a details view for the selected tag or digest. -This view contains two tabs that detail the composition and policy compliance for the image: - -- **Policy status** shows the policy evaluation results for the selected image. - Here you also have links for details about the policy violations. - - For more information about policy, see [Policy Evaluation](/manuals/scout/policy/_index.md). - -- **Image layers** shows a breakdown of the image analysis results. - You can get a complete view of the vulnerabilities your image contains - and understand how they got in. +The **Image layers** tab shows a breakdown of the image analysis results. +You can get a complete view of the vulnerabilities your image contains +and understand how they got in. ## Vulnerabilities @@ -102,79 +75,16 @@ even if they're not a member of your Docker organization or signed in to Docker If you are signed in, the **My images** tab on this page lists all of your images affected by the CVE. -## Integrations - -The **Integrations** page lets you create and manage your Docker Scout -integrations, such as environment integrations and registry integrations. For -more information on how to get started with integrations, see -[Integrating Docker Scout with other systems](/manuals/scout/integrations/_index.md). - ## Settings The settings menu in the Docker Scout Dashboard contains: -- [**Repository settings**](#repository-settings) for enabling and disabling repositories -- [**Notifications**](#notification-settings) for managing your notification preferences for Docker Scout. +- [**Repository settings**](#repository-settings) for enabling and disabling repositories. ### Repository settings When you enable Docker Scout for a repository, Docker Scout analyzes new tags automatically when you push to that repository. -To enable repositories in Amazon ECR, Azure ACR, or other third-party registries, -you first need to integrate them. -See [Container registry integrations](/manuals/scout/integrations/_index.md#container-registries) - -### Notification settings - -The [Notification settings](https://scout.docker.com/settings/notifications) -page is where you can change the preferences for receiving notifications from -Docker Scout. Notification settings are personal, and changing notification -settings only affects your personal account, not the entire organization. - -The purpose of notifications in Docker Scout is to raise awareness about -upstream changes that affect you. Docker Scout will notify you about when a new -vulnerability is disclosed in a security advisory, and it affects one or more -of your images. You will not receive notifications about changes to -vulnerability exposure or policy compliance as a result of pushing a new image. - -> [!NOTE] -> -> Notifications are only triggered for the _last pushed_ image tags for each -> repository. "Last pushed" refers to the image tag that was most recently -> pushed to the registry and analyzed by Docker Scout. If the last pushed image -> is not affected by a newly disclosed CVE, then no notification will be -> triggered. - -The available notification settings are: - -- **Repository scope** - - Here you can select whether you want to enable notifications for all - repositories, or only for specific repositories. These settings apply to the - currently selected organization, and can be changed for each organization you - are a member of. - - **All repositories**: select this option to receive notifications for all - repositories that you have access to. - - **Specific repositories**: select this option to receive notifications for - specific repositories. You can then enter the names of repositories you - want to receive notifications for. - -- **Delivery preferences** - - These settings control how you receive notifications from Docker Scout. They - apply to all organizations that you're a member of. - - **Notification pop-ups**: select this check-box to receive notification - pop-up messages in the Docker Scout Dashboard. - - **OS notifications**: select this check-box to receive OS-level notifications - from your browser if you have the Docker Scout Dashboard open in a browser - tab. - - To enable OS notifications, Docker Scout needs permissions to send - notifications using the browser API. - -From this page, you can also go to the settings for Team collaboration -integrations, such as the [Slack](/manuals/scout/integrations/team-collaboration/slack.md) -integration. - -You can also configure your notification settings in Docker Desktop by going -to **Settings** > **Notifications**. +To enable repositories in third-party registries, you first need to integrate +them. See [Container registry integrations](/manuals/scout/integrations/_index.md#container-registries) + diff --git a/content/manuals/scout/explore/exceptions.md b/content/manuals/scout/explore/exceptions.md index 8a6eadea0a21..77b55af3e3de 100644 --- a/content/manuals/scout/explore/exceptions.md +++ b/content/manuals/scout/explore/exceptions.md @@ -84,8 +84,6 @@ Vulnerability exceptions are highlighted in the CLI when you run `docker scout cves `. If a CVE is suppressed by an exception, a `SUPPRESSED` label appears next to the CVE ID. Details about the exception are also displayed. -![SUPPRESSED label in the CLI output](/scout/images/suppressed-cve-cli.png) - > [!IMPORTANT] > In order to view exceptions in the CLI, you must configure the CLI to use > the same Docker organization that you used to create the exceptions. diff --git a/content/manuals/scout/explore/image-details-view.md b/content/manuals/scout/explore/image-details-view.md index 8d5a534854f9..9a56f985acdf 100644 --- a/content/manuals/scout/explore/image-details-view.md +++ b/content/manuals/scout/explore/image-details-view.md @@ -14,8 +14,6 @@ access the image view from the Docker Scout Dashboard, the Docker Desktop show a breakdown of the image hierarchy (base images), image layers, packages, and vulnerabilities. -![The image details view in Docker Desktop](../images/dd-image-view.png) - Docker Desktop first analyzes images locally, where it generates a software bill of materials (SBOM). Docker Desktop, Docker Hub, and the Docker Scout Dashboard and CLI all use the [package URL (PURL) links](https://github.com/package-url/purl-spec) in this SBOM to query for matching Common Vulnerabilities and Exposures (CVEs) in [Docker Scout's advisory database](/manuals/scout/deep-dive/advisory-db-sources.md). @@ -143,8 +141,6 @@ of `debian` to use. By providing more than one alternative to choose from, you can see for yourself how the options compare with each other, and decide which one to use. -![Base image recommendations](../images/change-base-image.png) - Select a tag recommendation to see further details of the recommendation. It shows the benefits and potential disadvantages of the tag, why it's a recommended, and how to update your Dockerfile to use this version. diff --git a/content/manuals/scout/explore/metrics-exporter.md b/content/manuals/scout/explore/metrics-exporter.md index 8141eef331a4..8109838b7f70 100644 --- a/content/manuals/scout/explore/metrics-exporter.md +++ b/content/manuals/scout/explore/metrics-exporter.md @@ -40,7 +40,7 @@ To export metrics from your organization, first make sure your organization is e Then, create a Personal Access Token (PAT) - a secret token that allows the exporter to authenticate with the Docker Scout API. The PAT does not require any specific permissions, but it must be created by a user who is an owner of the Docker organization. -To create a PAT, follow the steps in [Create an access token](/manuals/security/access-tokens.md). +To create a PAT, follow the steps in [Create an access token](/manuals/security/access-tokens/personal-access-tokens.md). Once you have created the PAT, store it in a secure location. You will need to provide this token to the exporter when scraping metrics. @@ -108,7 +108,7 @@ alongside Grafana with a pre-configured dashboard to visualize the vulnerability $ cd scout-metrics-exporter/prometheus ``` -2. [Create a Docker access token](/manuals/security/access-tokens.md) +2. [Create a Docker access token](/manuals/security/access-tokens/personal-access-tokens.md) and store it in a plain text file at `/prometheus/prometheus/token` under the template directory. ```plaintext {title=token} @@ -158,17 +158,11 @@ The Prometheus server runs in a Docker container and is accessible on port 9090. After a few seconds, you should see the metrics endpoint as a target in the Prometheus UI at . -![Docker Scout metrics exporter Prometheus target](../images/scout-metrics-prom-target.png "Docker Scout metrics exporter Prometheus target") - ### Viewing the metrics in Grafana To view the Grafana dashboards, go to , and sign in using the credentials defined in the Docker Compose file (username: `admin`, password: `grafana`). -![Vulnerability dashboard in Grafana](../images/scout-metrics-grafana-vulns.png "Vulnerability dashboard in Grafana") - -![Policy dashboard in Grafana](../images/scout-metrics-grafana-policy.png "Policy dashboard in Grafana") - The dashboards are pre-configured to visualize the vulnerability and policy metrics scraped by Prometheus. ## Datadog @@ -241,7 +235,7 @@ and a Datadog site. $ cd scout-metrics-exporter/datadog ``` -2. [Create a Docker access token](/manuals/security/access-tokens.md) +2. [Create a Docker access token](/manuals/security/access-tokens/personal-access-tokens.md) and store it in a plain text file at `/datadog/token` under the template directory. ```plaintext {title=token} @@ -347,7 +341,7 @@ To change the scrape interval: ## Revoke an access token If you suspect that your PAT has been compromised or is no longer needed, you can revoke it at any time. -To revoke a PAT, follow the steps in the [Create and manage access tokens](/manuals/security/access-tokens.md). +To revoke a PAT, follow the steps in the [Create and manage access tokens](/manuals/security/access-tokens/personal-access-tokens.md). Revoking a PAT immediately invalidates the token, and prevents Prometheus from scraping metrics using that token. You will need to create a new PAT and update the Prometheus configuration to use the new token. diff --git a/content/manuals/scout/images/Scout-ECR.png b/content/manuals/scout/images/Scout-ECR.png deleted file mode 100644 index 70b1fb178107..000000000000 Binary files a/content/manuals/scout/images/Scout-ECR.png and /dev/null differ diff --git a/content/manuals/scout/images/change-base-image.png b/content/manuals/scout/images/change-base-image.png deleted file mode 100644 index 9370699f9ae0..000000000000 Binary files a/content/manuals/scout/images/change-base-image.png and /dev/null differ diff --git a/content/manuals/scout/images/dashboard-images.webp b/content/manuals/scout/images/dashboard-images.webp deleted file mode 100644 index 6ed69926e947..000000000000 Binary files a/content/manuals/scout/images/dashboard-images.webp and /dev/null differ diff --git a/content/manuals/scout/images/dashboard-overview.webp b/content/manuals/scout/images/dashboard-overview.webp deleted file mode 100644 index 01d7f2b18fb2..000000000000 Binary files a/content/manuals/scout/images/dashboard-overview.webp and /dev/null differ diff --git a/content/manuals/scout/images/dd-image-view.png b/content/manuals/scout/images/dd-image-view.png deleted file mode 100644 index e9ff3fef97c5..000000000000 Binary files a/content/manuals/scout/images/dd-image-view.png and /dev/null differ diff --git a/content/manuals/scout/images/gha-output.webp b/content/manuals/scout/images/gha-output.webp deleted file mode 100644 index 9f0f613f7adb..000000000000 Binary files a/content/manuals/scout/images/gha-output.webp and /dev/null differ diff --git a/content/manuals/scout/images/gha-policy-eval.webp b/content/manuals/scout/images/gha-policy-eval.webp deleted file mode 100644 index 131b34b17742..000000000000 Binary files a/content/manuals/scout/images/gha-policy-eval.webp and /dev/null differ diff --git a/content/manuals/scout/images/policy-detailed-results.webp b/content/manuals/scout/images/policy-detailed-results.webp deleted file mode 100644 index c74365a73a8b..000000000000 Binary files a/content/manuals/scout/images/policy-detailed-results.webp and /dev/null differ diff --git a/content/manuals/scout/images/policy-image-list.webp b/content/manuals/scout/images/policy-image-list.webp deleted file mode 100644 index fd9d512d21ba..000000000000 Binary files a/content/manuals/scout/images/policy-image-list.webp and /dev/null differ diff --git a/content/manuals/scout/images/policy-overview.webp b/content/manuals/scout/images/policy-overview.webp deleted file mode 100644 index 5ea82e2e05b7..000000000000 Binary files a/content/manuals/scout/images/policy-overview.webp and /dev/null differ diff --git a/content/manuals/scout/images/policy-tag-view.webp b/content/manuals/scout/images/policy-tag-view.webp deleted file mode 100644 index 7c7ec91fd865..000000000000 Binary files a/content/manuals/scout/images/policy-tag-view.webp and /dev/null differ diff --git a/content/manuals/scout/images/release-notes/policy-ea.webp b/content/manuals/scout/images/release-notes/policy-ea.webp deleted file mode 100644 index 283c689e3fa9..000000000000 Binary files a/content/manuals/scout/images/release-notes/policy-ea.webp and /dev/null differ diff --git a/content/manuals/scout/images/remediation.png b/content/manuals/scout/images/remediation.png deleted file mode 100644 index 1ea18e46439f..000000000000 Binary files a/content/manuals/scout/images/remediation.png and /dev/null differ diff --git a/content/manuals/scout/images/score-a-shiny.png b/content/manuals/scout/images/score-a-shiny.png deleted file mode 100644 index 5db0254ecff5..000000000000 Binary files a/content/manuals/scout/images/score-a-shiny.png and /dev/null differ diff --git a/content/manuals/scout/images/score-badges-dd.png b/content/manuals/scout/images/score-badges-dd.png deleted file mode 100644 index f33374c1ec93..000000000000 Binary files a/content/manuals/scout/images/score-badges-dd.png and /dev/null differ diff --git a/content/manuals/scout/images/score-badges-repolist.png b/content/manuals/scout/images/score-badges-repolist.png deleted file mode 100644 index dcfb016bbb4e..000000000000 Binary files a/content/manuals/scout/images/score-badges-repolist.png and /dev/null differ diff --git a/content/manuals/scout/images/scout-metrics-grafana-policy.png b/content/manuals/scout/images/scout-metrics-grafana-policy.png deleted file mode 100644 index 99042b35fe63..000000000000 Binary files a/content/manuals/scout/images/scout-metrics-grafana-policy.png and /dev/null differ diff --git a/content/manuals/scout/images/scout-metrics-grafana-vulns.png b/content/manuals/scout/images/scout-metrics-grafana-vulns.png deleted file mode 100644 index a48a279bf29d..000000000000 Binary files a/content/manuals/scout/images/scout-metrics-grafana-vulns.png and /dev/null differ diff --git a/content/manuals/scout/images/scout-metrics-prom-target.png b/content/manuals/scout/images/scout-metrics-prom-target.png deleted file mode 100644 index 6b040fcec6a0..000000000000 Binary files a/content/manuals/scout/images/scout-metrics-prom-target.png and /dev/null differ diff --git a/content/manuals/scout/images/scout-policy-eval-ci.webp b/content/manuals/scout/images/scout-policy-eval-ci.webp deleted file mode 100644 index 6643e3232553..000000000000 Binary files a/content/manuals/scout/images/scout-policy-eval-ci.webp and /dev/null differ diff --git a/content/manuals/scout/images/scout-slack-notification.png b/content/manuals/scout/images/scout-slack-notification.png deleted file mode 100644 index 14c2207b0d4d..000000000000 Binary files a/content/manuals/scout/images/scout-slack-notification.png and /dev/null differ diff --git a/content/manuals/scout/images/scout-sq-commit-sha.webp b/content/manuals/scout/images/scout-sq-commit-sha.webp deleted file mode 100644 index 5d0170979664..000000000000 Binary files a/content/manuals/scout/images/scout-sq-commit-sha.webp and /dev/null differ diff --git a/content/manuals/scout/images/suppressed-cve-cli.png b/content/manuals/scout/images/suppressed-cve-cli.png deleted file mode 100644 index 6384eb66a9e8..000000000000 Binary files a/content/manuals/scout/images/suppressed-cve-cli.png and /dev/null differ diff --git a/content/manuals/scout/integrations/_index.md b/content/manuals/scout/integrations/_index.md index cda490917dea..4266c72558c6 100644 --- a/content/manuals/scout/integrations/_index.md +++ b/content/manuals/scout/integrations/_index.md @@ -1,5 +1,5 @@ --- -description: How to setup Docker Scout with other systems. +description: How to set up Docker Scout with other systems. keywords: supply chain, security, integrations, registries, ci, environments title: Integrating Docker Scout with other systems linkTitle: Integrations @@ -23,11 +23,9 @@ registries enables Docker Scout to run image analysis on those repositories, so that you can get insights into the composition of those images even if they aren't hosted on Docker Hub. -The following container registry integrations are available: - -- [Amazon Elastic Container Registry](./registry/ecr.md) -- [Azure Container Registry](./registry/acr.md) -- [JFrog Artifactory](./registry/artifactory.md) +Docker Scout integrates with any Docker/OCI-compliant registry using +[`docker scout watch`](./registry.md), including Amazon ECR, Azure +Container Registry, JFrog Artifactory, Harbor, and Sonatype Nexus. ### Continuous Integration @@ -52,45 +50,8 @@ This can give you information in real-time about your running container workload Integrating with environments lets you compare production workloads to other versions, in your image repositories or in your other environments. -The following environment monitoring integrations are available - -- [Sysdig](./environment/sysdig.md) - +The following environment monitoring integrations are available: +- [Docker Scout GitHub Action](./environment/_index.md) +- [Generic CLI integration](./environment/cli.md) For more information about environment integrations, see [Environments](./environment/_index.md). - -### Code quality - -Integrating Docker Scout with code analysis tools enables quality checks -directly on source code, helping you keep track of bugs, security issues, test -coverage, and more. In addition to image analysis and environment monitoring, -code quality gates let you shift left your supply chain management with Docker -Scout. - -Once you enable a code quality integration, Docker Scout includes the code -quality assessments as policy evaluation results for the repositories where -you've enabled the integration. - -The following code quality integrations are available: - -- [SonarQube](sonarqube.md) - -### Source code management - -Integrate Docker Scout with your version control system to get guided -remediation advice on how to address issues detected by Docker Scout image -analysis, directly in your repositories. - -The following source code management integrations are available: - -- [GitHub](source-code-management/github.md) {{< badge color=blue text=Beta >}} - -### Team collaboration - -Integrations in this category let you integrate Docker Scout with collaboration -platforms for broadcasting notifications about your software supply chain in -real-time to team communication platforms. - -The following team collaboration integrations are available: - -- [Slack](./team-collaboration/slack.md) diff --git a/content/manuals/scout/integrations/ci/_index.md b/content/manuals/scout/integrations/ci/_index.md index 965de3e16c4f..07b3298c2538 100644 --- a/content/manuals/scout/integrations/ci/_index.md +++ b/content/manuals/scout/integrations/ci/_index.md @@ -1,5 +1,5 @@ --- -description: How to setup Docker Scout in continuous integration pipelines +description: How to set up Docker Scout in continuous integration pipelines keywords: scanning, vulnerabilities, Hub, supply chain, security, ci, continuous integration, github actions, gitlab title: Using Docker Scout in continuous integration diff --git a/content/manuals/scout/integrations/ci/gha.md b/content/manuals/scout/integrations/ci/gha.md index 7fe6ea486c11..72163cbd1633 100644 --- a/content/manuals/scout/integrations/ci/gha.md +++ b/content/manuals/scout/integrations/ci/gha.md @@ -98,21 +98,22 @@ jobs: This creates workflow steps to: -1. Set up Docker buildx. +1. Set up Docker Buildx. 2. Authenticate to the registry. 3. Extract metadata from Git reference and GitHub events. 4. Build and push the Docker image to the registry. > [!NOTE] > -> This CI workflow runs a local analysis and evaluation of your image. To -> evaluate the image locally, you must ensure that the image is loaded the -> local image store of your runner. +> The Scout compare step only runs on pull requests +> (`if: github.event_name == 'pull_request'`). Those builds set `load: true` +> and leave `sbom` / `provenance` off so the image can land in the runner's +> local store. > -> This comparison doesn't work if you push the image to a registry, or if you -> build an image that can't be loaded to the runner's local image store. For -> example, multi-platform images or images with SBOM or provenance attestation -> can't be loaded to the local image store. +> On push events the same job turns SBOM and provenance on and pushes to +> the registry. Don't enable those attestations (or a multi-platform build) +> on the PR path — those images can't be loaded locally, and compare would +> have nothing to inspect. With this setup out of the way, you can add the following steps to run the image comparison: @@ -149,11 +150,7 @@ showing only what's changed. The GitHub Action outputs the comparison results in a pull request comment by default. -![A screenshot showing the results of Docker Scout output in a GitHub Action](../../images/gha-output.webp) - Expand the **Policies** section to view the difference in policy compliance between the two images. Note that while the new image in this example isn't fully compliant, the output shows that the standing for the new image has improved compared to the baseline. - -![GHA policy evaluation output](../../images/gha-policy-eval.webp) diff --git a/content/manuals/scout/integrations/code-quality/_index.md b/content/manuals/scout/integrations/code-quality/_index.md deleted file mode 100644 index 16f010710765..000000000000 --- a/content/manuals/scout/integrations/code-quality/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -build: - render: never -title: Code quality ---- diff --git a/content/manuals/scout/integrations/code-quality/sonarqube.md b/content/manuals/scout/integrations/code-quality/sonarqube.md deleted file mode 100644 index ba1b552ba41b..000000000000 --- a/content/manuals/scout/integrations/code-quality/sonarqube.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Integrate Docker Scout with SonarQube -linkTitle: SonarQube -description: Evaluate your images with the SonarQube quality gates defined in your projects -keywords: scout, supply chain, integration, code quality ---- - -The SonarQube integration enables Docker Scout to surface SonarQube quality -gate checks through Policy Evaluation, under a new [SonarQube Quality Gates -Policy](/manuals/scout/policy/_index.md#sonarqube-quality-gates-policy). - -## How it works - -This integration uses [SonarQube -webhooks](https://docs.sonarsource.com/sonarqube/latest/project-administration/webhooks/) -to notify Docker Scout of when a SonarQube project analysis has completed. When -the webhook is called, Docker Scout receives the analysis results, and stores -them in the database. - -When you push a new image to a repository, Docker Scout evaluates the results -of the SonarQube analysis record corresponding to the image. Docker Scout uses -Git provenance metadata on the images, from provenance attestations or an OCI -annotations, to link image repositories with SonarQube analysis results. - -> [!NOTE] -> -> Docker Scout doesn't have access to historic SonarQube analysis records. Only -> analysis results recorded after the integration is enabled will be available -> to Docker Scout. - -Both self-managed SonarQube instances and SonarCloud are supported. - -## Prerequisites - -To integrate Docker Scout with SonarQube, ensure that: - -- Your image repository is [integrated with Docker Scout](../_index.md#container-registries). -- Your images are built with [provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md), - or the `org.opencontainers.image.revision` annotation, - containing information about the Git repository. - -## Enable the SonarQube integration - -1. Go to the [SonarQube integrations page](https://scout.docker.com/settings/integrations/sonarqube/) - on the Docker Scout Dashboard. -2. In the **How to integrate** section, enter a configuration name for this - integration. Docker Scout uses this label as a display name for the - integration, and to name the webhook. -3. Select **Next**. -4. Enter the configuration details for your SonarQube instance. Docker Scout - uses this information to create SonarQube webhook. - - In SonarQube, [generate a new **User token**](https://docs.sonarsource.com/sonarqube/latest/user-guide/user-account/generating-and-using-tokens/#generating-a-token). - The token requires 'Administer' permission on the specified project, or - global 'Administer' permission. - - Enter the token, your SonarQube URL, and the ID of your SonarQube - organization. The SonarQube organization is required if you're using - SonarCloud. - -5. Select **Enable configuration**. - - Docker Scout performs a connection test to verify that the provided details - are correct, and that the token has the necessary permissions. - -6. After a successful connection test, you're redirected to the SonarQube - integration overview, which lists all your SonarQube integrations and their - statuses. - -From the integration overview page, you can go directly to the -**SonarQube Quality Gates Policy**. -This policy will have no results initially. To start seeing evaluation results -for this policy, trigger a new SonarQube analysis of your project and push the -corresponding image to a repository. For more information, refer to the -[policy description](../../policy/_index.md#sonarqube-quality-gates). diff --git a/content/manuals/scout/integrations/environment/_index.md b/content/manuals/scout/integrations/environment/_index.md index 4dfa8eb7fdc0..61b80e0d907d 100644 --- a/content/manuals/scout/integrations/environment/_index.md +++ b/content/manuals/scout/integrations/environment/_index.md @@ -37,7 +37,6 @@ Docker Scout supports the following runtime integrations: - [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout#record-an-image-deployed-to-an-environment) - [CLI client](./cli.md) -- [Sysdig integration](./sysdig.md) > [!NOTE] > diff --git a/content/manuals/scout/integrations/environment/cli.md b/content/manuals/scout/integrations/environment/cli.md index 9ed416c9a38c..bf63fb23dadb 100644 --- a/content/manuals/scout/integrations/environment/cli.md +++ b/content/manuals/scout/integrations/environment/cli.md @@ -5,8 +5,6 @@ title: Generic environment integration with CLI linkTitle: Generic (CLI) --- -{{% include "scout-early-access.md" %}} - You can create a generic environment integration by running the Docker Scout CLI client in your CI workflows. The CLI client is available as a binary on GitHub and as a container image on Docker Hub. Use the client to invoke the @@ -100,7 +98,6 @@ stages: pool: vmImage: ubuntu-latest steps: - - task: Docker@2 - script: docker run -it \ -e DOCKER_SCOUT_HUB_USER=$DOCKER_SCOUT_HUB_USER \ -e DOCKER_SCOUT_HUB_PASSWORD=$DOCKER_SCOUT_HUB_PASSWORD \ diff --git a/content/manuals/scout/integrations/environment/sysdig.md b/content/manuals/scout/integrations/environment/sysdig.md deleted file mode 100644 index 84415426b2f5..000000000000 --- a/content/manuals/scout/integrations/environment/sysdig.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Integrate Docker Scout with Sysdig -linkTitle: Sysdig -description: Integrate your runtime environments with Docker Scout using Sysdig -keywords: scout, sysdig, integration, image analysis, environments, supply chain ---- - -{{% include "scout-early-access.md" %}} - -The Sysdig integration enables Docker Scout to automatically detect the images -you're using for your running workloads. Activating this integration gives you -real-time insights about your security posture, and lets you compare your -builds with what's running in production. - -## How it works - -The Sysdig Agent captures the images of your container workloads. Docker Scout -integrates with the Sysdig API to discover the images in your cluster. This -integration uses Sysdig's Risk Spotlight feature. For more information, see -[Risk Spotlight Integrations (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/integrations-for-sysdig-secure/risk-spotlight-integrations/). - -> [!TIP] -> -> Sysdig offers a free trial for Docker users to try out the new Docker Scout integration. -> -> {{< button url=`https://sysdig.com/free-trial-for-docker-customers/` text="Sign up" >}} - -Each Sysdig integration maps to an environment. When you enable a Sysdig -integration, you specify the environment name for that cluster, such as -`production` or `staging`. Docker Scout assigns the images in the cluster to -the corresponding environment. This lets you use the environment filters to see -vulnerability status and policy compliance for an environment. - -Only images analyzed by Docker Scout can be assigned to an environment. The -Sysdig runtime integration doesn't trigger image analysis by itself. To analyze -images automatically, enable a [registry integration](../_index.md#container-registries). - -Image analysis must not necessarily precede the runtime integration, but the -environment assignment only takes place once Docker Scout has analyzed the -image. - -## Prerequisites - -- Install the Sysdig Agent in the cluster that you want to integrate, see [Install Sysdig Agent (Sysdig docs)](https://docs.sysdig.com/en/docs/installation/sysdig-monitor/install-sysdig-agent/). -- Enable profiling for Risk Spotlight Integrations in Sysdig, see [Profiling (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/policies/profiling/#enablement). -- You must be an organization owner to enable the integration in the Docker Scout Dashboard. - -## Integrate an environment - -1. Go to the [Sysdig integration page](https://scout.docker.com/settings/integrations/sysdig/) - on the Docker Scout Dashboard. -2. In the **How to integrate** section, enter a configuration name for this - integration. Docker Scout uses this label as a display name for the - integration. - -3. Select **Next**. - -4. Enter a Risk Spotlight API token and select the region in the drop-down list. - - The Risk Spotlight API token is the Sysdig token that Docker Scout needs to - integrate with Sysdig. For more instructions on how to generate a Risk - Spotlight token, See [Risk Spotlight Integrations (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/integrations-for-sysdig-secure/risk-spotlight-integrations/docker-scout/#generate-a-token-for-the-integration). - - The region corresponds to the `global.sysdig.region` configuration parameter - set when deploying the Sysdig Agent. - -5. Select **Next**. - - After selecting **Next**, Docker Scout connects to Sysdig and retrieves the - cluster names for your Sysdig account. Cluster names correspond to the - `global.clusterConfig.name` configuration parameter set when deploying - Sysdig Agents. - - An error displays if Docker Scout fails to connect to Sysdig using the - provided token. If there's an error, you won't be able to continue the - integration. Go back and verify that the configuration details are correct. - -6. Select a cluster name in the drop-down list. - -7. Select **Next**. - -8. Assign an environment name for this cluster. - - You can reuse an existing environment or create a new one. - -9. Select **Enable integration**. - -After enabling the integration, Docker Scout automatically detects images -running in the cluster, and assigns those images to the environment associated -with the cluster. For more information about environments, see [Environment -monitoring](./_index.md). - -> [!NOTE] -> -> Docker Scout only detects images that have been analyzed. To trigger an image -> analysis, enable a [registry integration](../_index.md#container-registries) -> and push an image to your registry. -> -> If you created a new environment for this integration, the environment -> appears in Docker Scout when at least one image has been analyzed. - -To integrate more clusters, go to the [Sysdig integrations page](https://scout.docker.com/settings/integrations/sysdig/) -and select the **Add** button. diff --git a/content/manuals/scout/integrations/registry.md b/content/manuals/scout/integrations/registry.md new file mode 100644 index 000000000000..372ef3cad1e7 --- /dev/null +++ b/content/manuals/scout/integrations/registry.md @@ -0,0 +1,191 @@ +--- +title: Integrate Docker Scout with a container registry +linkTitle: Container registries +description: Integrate Docker Scout with any container registry using the docker scout watch CLI command +keywords: docker scout, registry, integration, image analysis, security, cves, watch, ecr, acr, artifactory, harbor, nexus +aliases: + - /scout/integrations/registry/artifactory/ + - /scout/artifactory/ + - /scout/integrations/registry/ecr/ + - /scout/integrations/registry/acr/ +--- + +[`docker scout watch`](/reference/cli/docker/scout/watch/) is a long-running +CLI process that indexes images from a container registry and pushes the +results to Docker Scout. It works with any Docker/OCI-compliant registry, +including Amazon ECR, Azure Container Registry, JFrog Artifactory, Harbor, and +Sonatype Nexus. + +## How it works + +You run `docker scout watch` on a host you control. The process can: + +- Watch specific repositories or an entire registry +- Optionally ingest all existing images once, using `--all-images` +- Periodically refresh repository lists, using `--refresh-registry` +- Receive webhook callbacks from registries that support them, for + near-real-time analysis instead of polling + +After the integration, Docker Scout automatically pulls and analyzes images +that you push to the registry. Metadata about your images are stored on the +Docker Scout platform, but Docker Scout doesn't store the container images +themselves. For more information about how Docker Scout handles image data, +see [Data handling](/manuals/scout/deep-dive/data-handling.md). + +## Set up `docker scout watch` + +1. Pick a host on which to run `docker scout watch`. + + The host must have network access to your registry and be able to access + the Scout API (`https://api.scout.docker.com`) over the internet. If + you're using webhook callbacks, the registry must also be able to reach the + `docker scout watch` host on the configured port. + +2. Ensure you are running the latest version of Scout. + + ```console + $ docker scout version + ``` + + If necessary, [install the latest version of Scout](/manuals/scout/install.md). + +3. Authenticate Docker to your registry. + + ```console + $ docker login --username --password + ``` + + For Amazon ECR, authenticate using the AWS CLI instead: + + ```console + $ aws ecr get-login-password --region | \ + docker login --username AWS --password-stdin \ + .dkr.ecr..amazonaws.com + ``` + + The AWS identity used must have at least `ecr:GetAuthorizationToken` and + `ecr:BatchGetImage` permissions on the target registry. + + For Azure Container Registry: + + ```console + $ docker login .azurecr.io \ + --username \ + --password + ``` + + > [!TIP] + > + > As a best practice, use a dedicated user or token with read-only access + > to the registry. + +4. Set up your Scout credentials. + + 1. Generate an organization access token. For more details, see + [Create an organization access token](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token). + 2. Sign in to Docker using the organization access token. + + ```console + $ docker login --username + ``` + + When prompted for a password, paste the organization access token. + + 3. Connect your local Docker environment to your organization's Docker Scout service. + + ```console + $ docker scout enroll + ``` + +5. Index existing images. You only need to do this once. + + ```console + $ docker scout watch --registry --all-images + ``` + +6. Confirm the images have been indexed by viewing them on the + [Scout Dashboard](https://scout.docker.com/). + +7. Continuously watch for new images. + + ```console + $ docker scout watch --registry --refresh-registry + ``` + + `docker scout watch` is a long-running process. Run it as a system + service, for example using `systemd` or `nohup`, to ensure it continues + running in the background. Use `--interval` (default 60 seconds) to + control polling frequency, and `--repository` and `--tag` to narrow scope. + +Reference: [`docker scout watch`](/reference/cli/docker/scout/watch/) + +## Registry-specific options + +Some registries need extra configuration beyond a hostname, passed through +the `--registry` flag as a `key=value` string, for example a REST API +endpoint for webhook callbacks, or a non-standard repository layout. Built-in +adapters exist for `type=artifactory`, `type=harbor`, and `type=nexus`, and a +`type=oci` adapter covers any OCI-compliant registry that implements the +`_catalog` endpoint. For the full option reference for each type, see +[`docker scout watch`](/reference/cli/docker/scout/watch/). + +The following example walks through the `type=artifactory` adapter in detail. +See the CLI reference for equivalent Harbor, Nexus, and generic OCI examples. + +### Example: JFrog Artifactory + +These `type=artifactory` options override the generic registry handling for +the `--registry` option: + +| Key | Required | Description | +|------------------|:--------:|----------------------------------------------------------------------------------------| +| `type` | Yes | Must be `artifactory`. | +| `registry` | Yes | Docker/OCI registry hostname (e.g., `example.jfrog.io`). | +| `api` | Yes | Artifactory REST API base URL (e.g., `https://example.jfrog.io/artifactory`). | +| `repository` | Yes | Repository to watch (replaces `--repository`). | +| `includes` | No | Globs to include (e.g., `*/frontend*`). | +| `excludes` | No | Globs to exclude (e.g., `*/legacy/*`). | +| `port` | No | Local port to listen on for webhook callbacks. | +| `subdomain-mode` | No | `true` or `false`; matches Artifactory's Docker layout (subdomain versus repository-path). | + +Set up credentials for the Scout client to authenticate with Artifactory, and +a secret for Artifactory to authenticate its webhook callbacks: + +```console +$ export DOCKER_SCOUT_ARTIFACTORY_API_USER= +$ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD= +$ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET= +``` + +> [!TIP] +> +> As a best practice, create a dedicated user with read-only access and use an +> access token instead of a password. Generate the webhook secret as a +> high-entropy random string of 64-128 characters. + +Index existing images with the Artifactory-specific registry string: + +```console +$ docker scout watch --registry \ + "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \ + --all-images +``` + +Then configure Artifactory to call the webhook: in your Artifactory UI or via +REST API, set up a webhook for image push/update events, pointing to your +`docker scout watch` host and port, and include the +`DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET` for authentication. For more +information, see the [JFrog Artifactory Webhooks +documentation](https://jfrog.com/help/r/jfrog-platform-administration-documentation/webhooks) +or the [JFrog Artifactory REST API Webhooks +documentation](https://jfrog.com/help/r/jfrog-rest-apis/webhooks). + +Finally, run the same command with `--refresh-registry` instead of +`--all-images` as your long-running watch process, so new images are picked up +going forward: + +```console +$ docker scout watch --registry \ + "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \ + --refresh-registry +``` diff --git a/content/manuals/scout/integrations/registry/_index.md b/content/manuals/scout/integrations/registry/_index.md deleted file mode 100644 index 87f014cb712b..000000000000 --- a/content/manuals/scout/integrations/registry/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -build: - render: never -title: Container registries ---- diff --git a/content/manuals/scout/integrations/registry/acr.md b/content/manuals/scout/integrations/registry/acr.md deleted file mode 100644 index 745d04e85b96..000000000000 --- a/content/manuals/scout/integrations/registry/acr.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -description: Integrate Azure Container Registry with Docker Scout -keywords: docker scout, acr, azure, integration, image analysis, security, cves -title: Integrate Docker Scout with Azure Container Registry -linkTitle: Azure Container Registry ---- - -Integrating Docker Scout with Azure Container Registry (ACR) lets you view -image insights for images hosted in ACR repositories. After integrating Docker -Scout with ACR and activating Docker Scout for a repository, pushing an image -to the repository automatically triggers image analysis. You can view image -insights using the Docker Scout Dashboard, or the `docker scout` CLI commands. - -## How it works - -To help you integrate your Azure Container Registry with Docker Scout, you can -use a custom Azure Resource Manager (ARM) template that automatically creates -the necessary infrastructure in Azure for you: - -- An EventGrid Topic and Subscription for Image push and delete events. -- A read-only authorization token for the registry, used to list repositories, - and ingest the images. - -When the resources have been created in Azure, you can enable the integration -for image repositories in the integrated ACR instance. Once you've enabled a -repository, pushing new images triggers image analysis automatically. The -analysis results appear in the Docker Scout Dashboard. - -If you enable the integration on a repository that already contains images, -Docker Scout pulls and analyzes the latest image version automatically. - -### ARM template - -The following table describes the configuration resources. - -> [!NOTE] -> -> Creating these resources incurs a small, recurring cost on the Azure account. -> The **Cost** column in the table represents an estimated monthly cost of the -> resources, when integrating an ACR registry that gets 100 images pushed per -> day. -> -> The Egress cost varies depending on usage, but it’s around $0.1 per GB, and -> the first 100 GB are free. - -| Azure | Resource | Cost | -| ----------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------- | -| Event Grid system topic | Subscribe to Azure Container Registry events (image push and image delete) | Free | -| Event subscription | Send Event Grid events to Scout via a Webhook subscription | $0.60 for every 1M messages. First 100k for free. | -| Registry Token | Read-only token used for Scout to list the repositories, and pull images from the registry | Free | - -The following JSON document shows the ARM template Docker Scout uses to create -the Azure resources. - -{{< accordion title="JSON template" >}} - -{{< acr-template.inline >}} -{{ with resources.GetRemote "https://prod-scout-integration-templates.s3.amazonaws.com/latest/acr_token_template.json" }} -{{ $data := .Content | transform.Unmarshal }} - -```json -{{ transform.Remarshal "json" $data }} -``` - -{{ end }} -{{< /acr-template.inline >}} - -{{< /accordion >}} - -## Integrate a registry - -1. Go to [ACR integration page](https://scout.docker.com/settings/integrations/azure/) on the - Docker Scout Dashboard. -2. In the **How to integrate** section, enter the **Registry hostname** of the - registry you want to integrate. -3. Select **Next**. -4. Select **Deploy to Azure** to open the template deployment wizard in Azure. - - You may be prompted to sign in to your Azure account if you're not already - signed in. - -5. In the template wizard, configure your deployment: - - - **Resource group**: enter the same resource group as you're using for the - container registry. The Docker Scout resources must be deployed to the - same resource group as the registry. - - - **Registry name**: the field is pre-filled with the subdomain of the - registry hostname. - -6. Select **Review + create**, and then **Create** to deploy the template. - -7. Wait until the deployment is complete. -8. In the **Deployment details** section click on the newly created resource - of the type **Container registry token**. Generate a new password for this token. - - Alternatively, use the search function in Azure to navigate to the - **Container registry** resource that you're looking to integrate, and - generate the new password for the created access token. - -9. Copy the generated password and head back to the Docker Scout Dashboard to - finalize the integration. - -10. Paste the generated password into the **Registry token** field. -11. Select **Enable integration**. - -After selecting **Enable integration**, Docker Scout performs a connection test -to verify the integration. If the verification was successful, you're -redirected to the Azure registry summary page, which shows you all your Azure -integrations for the current organization. - -Next, activate Docker Scout for the repositories that you want to analyze in -[Repository settings](https://scout.docker.com/settings/repos/). - -After activating repositories, images that you push are analyzed by Docker -Scout. The analysis results appear in the Docker Scout Dashboard. -If your repository already contains images, Docker Scout pulls and analyzes the -latest image version automatically. - -## Remove an integration - -> [!IMPORTANT] -> -> Removing the integration in the Docker Scout Dashboard doesn't automatically -> remove the resources created in Azure. - -To remove an ACR integration: - -1. Go to the [ACR integration page](https://scout.docker.com/settings/integrations/azure/) - on the Docker Scout Dashboard. -2. Find the ACR integration that you want to remove, and select the **Remove** - button. -3. In the dialog that opens, confirm by selecting **Remove**. -4. After removing the integration in the Docker Scout Dashboard, also remove - the Azure resources related to the integration: - - - The `docker-scout-readonly-token` token for the container registry. - - The `docker-scout-repository` Event Grid System Topic. diff --git a/content/manuals/scout/integrations/registry/artifactory.md b/content/manuals/scout/integrations/registry/artifactory.md deleted file mode 100644 index 571d44d9c966..000000000000 --- a/content/manuals/scout/integrations/registry/artifactory.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -description: Integrate Artifactory Container Registry with Docker Scout -keywords: docker scout, artifactory, integration, image analysis, security, cves -title: Integrate Docker Scout with Artifactory Container Registry -linkTitle: Artifactory Container Registry -aliases: - - /scout/artifactory/ ---- - -Integrating Docker Scout with JFrog Artifactory lets you index and analyze -images from Artifactory. This integration is powered by a long-running -`docker scout watch` process. It pulls images from your selected repositories -(optionally filtered), can receive webhook callbacks from Artifactory, and -pushes image data to Docker Scout. View results in the Docker Scout Dashboard or -with `docker scout` CLI. - -## How it works - -You run [`docker scout watch`](/reference/cli/docker/scout/watch/) on a host you -control and configure the Artifactory-specific registry string via `--registry -"key=value,..."`. The watch process can: - -- Watch specific repositories or an entire registry -- Optionally ingest all existing images once -- Periodically refresh repository lists -- Receive webhook callbacks from Artifactory on a local port you choose - -After the integration, Docker Scout automatically pulls and analyzes images -that you push to the Artifactory registry. Metadata about your images are stored on the -Docker Scout platform, but Docker Scout doesn't store the container images -themselves. For more information about how Docker Scout handles image data, see -[Data handling](/manuals/scout/deep-dive/data-handling.md). - -### Artifactory-specific registry string options - -These `type=artifactory` options override the generic registry handling for the `--registry` option: - -| Key | Required | Description | -|------------------|:--------:|----------------------------------------------------------------------------------------| -| `type` | Yes | Must be `artifactory`. | -| `registry` | Yes | Docker/OCI registry hostname (e.g., `example.jfrog.io`). | -| `api` | Yes | Artifactory REST API base URL (e.g., `https://example.jfrog.io/artifactory`). | -| `repository` | Yes | Repository to watch (replaces `--repository`). | -| `includes` | No | Globs to include (e.g., `*/frontend*`). | -| `excludes` | No | Globs to exclude (e.g., `*/legacy/*`). | -| `port` | No | Local port to listen on for webhook callbacks. | -| `subdomain-mode` | No | `true` or `false`; matches Artifactory’s Docker layout (subdomain versus repository-path). | - -## Integrate an Artifactory registry - -Use the following steps to integrate your Artifactory registry with Docker -Scout. - -1. Pick the host on which to run `docker scout watch`. - - The host must have local or network access to your private registry and be able - to access the Scout API (`https://api.scout.docker.com`) over the internet. If - you're using webhook callbacks, Artifactory must also be able to reach the Scout - client host on the configured port. - Override the `--workers` option (default: `3`) for optimal performance based on - the size of the host and the expected workload. - -2. Ensure you are running the latest version of Scout. - - Check your current version: - - ```console - $ docker scout version - ``` - - If necessary, [install the latest version of Scout](https://docs.docker.com/scout/install/). - -3. Set up your Artifactory credentials. - - Store the credentials that the Scout client will use to authenticate with - Artifactory. The following is an example using environment variables. Replace - `` and `` with your actual values. - - ```console - $ export DOCKER_SCOUT_ARTIFACTORY_API_USER= - $ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD= - ``` - - > [!TIP] - > - > As a best practice, create a dedicated user with read-only access and use - > an access token instead of a password. - - Store the credential that Artifactory will use to authenticate webhook - callbacks. The following is an example using an environment variable. Replace - `` with an actual secret. - - ```console - $ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET= - ```` - - > [!TIP] - > - > As a best practice, generate a high-entropy random string of 64-128 characters. - -4. Set up your Scout credentials. - - 1. Generate an organization access token for accessing Scout. For more - details, see [Create an organization access - token](/enterprise/security/access-tokens/#create-an-organization-access-token). - 2. Sign in to Docker using the organization access token. - - ```console - $ docker login --username - ``` - - When prompted for a password, paste the organization access token you - generated. - - 3. Connect your local Docker environment to your organization's Docker Scout service. - - ```console - $ docker scout enroll - ``` - -5. Index existing images. You only need to do this once. - - Run `docker scout watch` with the `--all-images` option to index all images in the specified Artifactory repository. The following is an example command: - - ```console - $ docker scout watch --registry \ - "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \ - --all-images - ``` - -6. Confirm the images have been indexed by viewing them on the [Scout - Dashboard](https://scout.docker.com/). - -7. Configure Artifactory callbacks. - - In your Artifactory UI or via REST API, configure webhooks for image - push/update events. Set the endpoint to your `docker scout watch` host and - port, and include the `DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET` for - authentication. - - For more information, see the [JFrog Artifactory Webhooks - documentation](https://jfrog.com/help/r/jfrog-platform-administration-documentation/webhooks) - or the [JFrog Artifactory REST API Webhooks - documentation](https://jfrog.com/help/r/jfrog-rest-apis/webhooks). - -8. Continuously watch for new or updated images. - - Run `docker scout watch` with the `--refresh-registry` option to watch for - new images to index. - - The `docker scout watch` command is a long-running process that must - continue running indefinitely in the background to receive webhooks and - watch for new images. If you run it directly in a terminal and close the - session, the process will stop. - - The following is an example command. You can run the process as a system - service, for example using `systemd` or `nohup`, to ensure it continues - running in the background. - - ```console - $ docker scout watch --registry \ - "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \ - --refresh-registry - ``` - -9. Optional. Set up Scout integration for real-time notifications from popular - collaboration platforms. For details, see [Integrate Docker Scout with - Slack](../team-collaboration/slack.md). \ No newline at end of file diff --git a/content/manuals/scout/integrations/registry/ecr.md b/content/manuals/scout/integrations/registry/ecr.md deleted file mode 100644 index db5096ebab45..000000000000 --- a/content/manuals/scout/integrations/registry/ecr.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -description: Integrate Amazon Elastic Container Registry with Docker Scout -keywords: docker scout, ecr, integration, image analysis, security, cves -title: Integrate Docker Scout with Amazon ECR -linkTitle: Amazon ECR ---- - -Integrating Docker Scout with Amazon Elastic Container Registry (ECR) lets you -view image insights for images hosted in ECR repositories. After integrating -Docker Scout with ECR and activating Docker Scout for a repository, pushing an -image to the repository automatically triggers image analysis. You can view -image insights using the Docker Scout Dashboard, or the `docker scout` CLI -commands. - -## How it works - -To help you integrate Docker Scout with ECR, you can use a CloudFormation stack -template that creates and configures the necessary AWS resources for -integrating Docker Scout with your ECR registry. For more details about the AWS -resources, see [CloudFormation stack template](#cloudformation-stack-template). - -The following diagram shows how the Docker Scout ECR integration works. - -![How the ECR integration works](../../images/Scout-ECR.png) - -After the integration, Docker Scout automatically pulls and analyzes images -that you push to the ECR registry. Metadata about your images are stored on the -Docker Scout platform, but Docker Scout doesn't store the container images -themselves. For more information about how Docker Scout handles image data, see -[Data handling](/manuals/scout/deep-dive/data-handling.md). - -### CloudFormation stack template - -The following table describes the configuration resources. - -> [!NOTE] -> -> Creating these resources incurs a small, recurring cost on the AWS account. -> The **Cost** column in the table represents an estimated monthly cost of the -> resources, when integrating an ECR registry that gets 100 images pushed per day. -> -> Additionally, an egress cost also applies when Docker Scout pulls the images -> from ECR. The egress cost is around $0.09 per GB. - -| Resource type | Resource name | Description | Cost | -| ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ | ----- | -| `AWS::SNSTopic::Topic` | `SNSTopic` | SNS topic for notifying Docker Scout when the AWS resources have been created. | Free | -| `AWS::SNS::TopicPolicy` | `TopicPolicy` | Defines the topic for the initial setup notification. | Free | -| `AWS::SecretsManager::Secret` | `ScoutAPICredentials` | Stores the credentials used by EventBridge to fire events to Scout. | $0.42 | -| `AWS::Events::ApiDestination` | `ApiDestination` | Sets up the EventBridge connection to Docker Scout for sending ECR push and delete events. | $0.01 | -| `AWS::Events::Connection` | `Connection` | EventBridge connection credentials to Scout. | Free | -| `AWS::Events::Rule` | `DockerScoutEcrRule` | Defines the rule to send ECR pushes and deletes to Scout. | Free | -| `AWS::Events::Rule` | `DockerScoutRepoDeletedRule` | Defines the rule to send ECR repository deletes to Scout. | Free | -| `AWS::IAM::Role` | `InvokeApiRole` | Internal role to grant the event access to `ApiDestination`. | Free | -| `AWS::IAM::Role` | `AssumeRoleEcrAccess` | This role has access to `ScoutAPICredentials` for setting up the Docker Scout integration. | Free | - -## Integrate your first registry - -Create the CloudFormation stack in your AWS account to enable the Docker Scout -integration. - -Prerequisites: - -- You must have access to an AWS account with permission to create resources. -- You have be an owner of the Docker organization. - -To create the stack: - -1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) - on the Docker Scout Dashboard. -2. Select the **Create on AWS** button. - - This opens the **Create stack** wizard in the AWS CloudFormation console in - a new browser tab. If you're not already signed in to AWS, you're redirected - to the sign-in page first. - - If the button is grayed-out, it means you're lacking the necessary - permissions in the Docker organization. - -3. Follow the steps in the **Create stack** wizard until the end. Choose the - AWS region you want to integrate. Complete the procedure by creating the - resources. - - The fields in the wizard are pre-populated by the CloudFormation template, - so you don't need to edit any of the fields. - -4. When the resources have been created (the CloudFormation status shows - `CREATE_COMPLETE` in the AWS console), return to the ECR integrations page - in the Docker Scout Dashboard. - - The **Integrated registries** list shows the account ID and region for the - ECR registry that you just integrated. If successful, the integration status - is **Connected**. - -The ECR integration is now active. For Docker Scout to start analyzing images -in the registry, you need to activate it for each repository in -[Repository settings](https://scout.docker.com/settings/repos/). - -After activating repositories, images that you push are analyzed by Docker -Scout. The analysis results appear in the Docker Scout Dashboard. -If your repository already contains images, Docker Scout pulls and analyzes the -latest image version automatically. - -## Integrate additional registries - -To add additional registries: - -1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) - on the Docker Scout Dashboard. -2. Select the **Add** button at the top of the list. -3. Complete the steps for creating the AWS resources. -4. When the resources have been created, return to the ECR integrations page in - the Docker Scout Dashboard. - - The **Integrated registries** list shows the account ID and region for the - ECR registry that you just integrated. If successful, the integration status - is **Connected**. - -Next, activate Docker Scout for the repositories that you want to analyze in -[Repository settings](https://scout.docker.com/settings/repos/). - -## Remove integration - -To remove an integrated ECR registry, you must be an owner of the Docker -organization. - -1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) - on the Docker Scout Dashboard. -2. Find the registry that you want to remove in the list of integrated - registries, and select the remove icon in the **Actions** column. - - If the remove icon is disabled, it means that you're lacking the necessary - permissions in the Docker organization. - -3. In the dialog that opens, confirm by selecting **Remove**. - -> [!IMPORTANT] -> -> Removing the integration from the Docker Scout dashboard doesn't remove the -> AWS resources in your account. -> -> After removing the integration in Docker Scout, go to the AWS console and -> delete the **DockerScoutECRIntegration** CloudFormation stack for the integration -> that you want to remove. - -## Troubleshooting - -### Unable to integrate registry - -Check the **Status** of the integration on the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) -in the Docker Scout Dashboard. - -- If the status is **Pending** for a prolonged period of time, it's an - indication that the integration was not yet completed on the AWS side. Select - the **Pending** link to open the CloudFormation wizard, and complete all the - steps. - -- An **Error** status indicates that something's gone wrong in the back-end. - You can try [removing the integration](#remove-integration) and recreating it - again. - -### ECR images not showing in the dashboard - -If image analysis results for your ECR images aren't showing up in the Docker -Scout Dashboard: - -- Ensure that you've activated Docker Scout for the repository. View and manage - active repositories in [Repository settings](https://scout.docker.com/settings/repos/). - -- Ensure that the AWS account ID and region for your registry is listed on the - ECR integrations page. - - The account ID and region are included in the registry hostname: - `.dkr.ecr..amazonaws.com/` diff --git a/content/manuals/scout/integrations/source-code-management/_index.md b/content/manuals/scout/integrations/source-code-management/_index.md deleted file mode 100644 index aded6d7584e4..000000000000 --- a/content/manuals/scout/integrations/source-code-management/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -build: - render: never -title: Source code management ---- diff --git a/content/manuals/scout/integrations/source-code-management/github.md b/content/manuals/scout/integrations/source-code-management/github.md deleted file mode 100644 index cb9350ec2d22..000000000000 --- a/content/manuals/scout/integrations/source-code-management/github.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Integrate Docker Scout with GitHub -linkTitle: GitHub -description: Integrate Docker Scout using the GitHub app to get remediation advice directly in your repositories -keywords: scout, github, integration, image analysis, supply chain, remediation, source code ---- - -{{< summary-bar feature_name="Docker Scout GitHub" >}} - -The GitHub app integration for Docker Scout grants Docker Scout access to your -source code repository on GitHub. This improved visibility into how your image -gets created means Docker Scout can give you automated and contextual -remediation advice. - -## How it works - -When you enable the GitHub integration, Docker Scout can make a direct link -between the image analysis results and the source. - -When analyzing your image, Docker Scout checks for [provenance -attestations](/manuals/build/metadata/attestations/slsa-provenance.md) to detect the -location of the source code repository for the image. If the source location is -found, and you've enabled the GitHub app, Docker Scout parses the Dockerfile -used to create the image. - -Parsing the Dockerfile reveals the base image tag used to build the image. By -knowing the base image tags used, Docker Scout can detect whether the tag is -outdated, meaning it's been changed to a different image digest. For example, -say you're using `alpine:3.18` as your base image, and at a later point in -time, the image maintainers release a patch version for version `3.18`, -containing security fixes. The `alpine:3.18` tag you've been using becomes -out-of-date; the `alpine:3.18` you're using is no longer the latest. - -When this happens, Docker Scout detects the discrepancy and surfaces it through -the [Up-to-Date Base Images policy](/manuals/scout/policy/_index.md#up-to-date-base-images-policy). -When the GitHub integration's enabled, you'll also get automated suggestions on -how to update your base image. For more information about how Docker Scout can -help you automatically improve your supply chain conduct and security posture, -see [Remediation](../../policy/remediation.md). - -## Setup - -To integrate Docker Scout with your GitHub organization: - -1. Go to [GitHub integration](https://scout.docker.com/settings/integrations/github/) - on the Docker Scout Dashboard. -2. Select the **Integrate GitHub app** button to open GitHub. -3. Select the organization that you want to integrate. -4. Select whether you want to integrate all repositories in the GitHub - organization or a manual selection of repositories. -5. Select **Install & Authorize** to add the Docker Scout app to the - organization. - - This redirects you back to the Docker Scout Dashboard, which lists your - active GitHub integrations. - -The GitHub integration is now active. diff --git a/content/manuals/scout/integrations/team-collaboration/_index.md b/content/manuals/scout/integrations/team-collaboration/_index.md deleted file mode 100644 index 61a9f8b0040c..000000000000 --- a/content/manuals/scout/integrations/team-collaboration/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -build: - render: never -title: Team collaboration ---- diff --git a/content/manuals/scout/integrations/team-collaboration/slack.md b/content/manuals/scout/integrations/team-collaboration/slack.md deleted file mode 100644 index 5c9aecbd8a07..000000000000 --- a/content/manuals/scout/integrations/team-collaboration/slack.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Integrate Docker Scout with Slack -linkTitle: Slack -description: | - Integrate Docker Scout with Slack to receive real-time updates - about vulnerabilities and policy compliance in Slack channels -keywords: scout, team collaboration, slack, notifications, updates ---- - -You can integrate Docker Scout with Slack by creating a Slack webhook and -adding it to the Docker Scout Dashboard. Docker Scout will notify you about -when a new vulnerability is disclosed, and it affects one or more of your -images. - -![Slack notification from Docker Scout](../../images/scout-slack-notification.png?border=true "Example Slack notification from Docker Scout") - -## How it works - -After configuring the integration, Docker Scout sends notifications about -changes to policy compliance and vulnerability exposure for your repositories, -to the Slack channels associated with the webhook. - -> [!NOTE] -> -> Notifications are only triggered for the _last pushed_ image tags for each -> repository. "Last pushed" refers to the image tag that was most recently -> pushed to the registry and analyzed by Docker Scout. If the last pushed image -> is not affected by a newly disclosed CVE, then no notification will be triggered. - -For more information about Docker Scout notifications, -see [Notification settings](/manuals/scout/explore/dashboard.md#notification-settings) - -## Setup - -To add a Slack integration: - -1. Create a webhook, see [Slack documentation](https://api.slack.com/messaging/webhooks). -2. Go to the [Slack integration page](https://scout.docker.com/settings/integrations/slack/) in the Docker Scout Dashboard. -3. In the **How to integrate** section, enter a **Configuration name**. - Docker Scout uses this label as a display name for the integration, - so you might want to change the default name into something more meaningful. - For example the `#channel-name`, or the name of the team that this configuration belongs to. -4. Paste the webhook you just created in the **Slack webhook** field. - - Select the **Test webhook** button if you wish to verify the connection. - Docker Scout will send a test message to the specified webhook. - -5. Select whether you want to enable notifications for all your Scout-enabled image repositories, - or enter the names of the repositories that you want to send notifications for. -6. When you're ready to enable the integration, select **Create**. - -After creating the webhook, Docker Scout begins to send notifications updates -to the Slack channels associated with the webhook. - -## Remove a Slack integration - -To remove a Slack integration: - -1. Go to the [Slack integration page](https://scout.docker.com/settings/integrations/slack/) in the Docker Scout Dashboard. -2. Select the **Remove** icon for the integration that you want to remove. -3. Confirm by selecting **Remove** again in the confirmation dialog. diff --git a/content/manuals/scout/policy/_index.md b/content/manuals/scout/policy/_index.md index 63b6e4fccc19..b6742a752354 100644 --- a/content/manuals/scout/policy/_index.md +++ b/content/manuals/scout/policy/_index.md @@ -1,402 +1,122 @@ --- -title: Get started with Policy Evaluation in Docker Scout +title: Policy Evaluation linkTitle: Policy Evaluation weight: 70 keywords: scout, supply chain, vulnerabilities, packages, cves, policy description: | - Policies in Docker Scout let you define supply chain rules and thresholds - for your artifacts, and track how your artifacts perform against those - requirements over time + Policy Evaluation in Docker Scout lets you define supply chain rules for your + artifacts and evaluate image compliance --- -In software supply chain management, maintaining the security and reliability -of artifacts is a top priority. Policy Evaluation in Docker Scout introduces a -layer of control, on top of existing analysis capabilities. It lets you define -supply chain rules for your artifacts, and helps you track how your artifacts -perform, relative to your rules and thresholds, over time. - -Learn how you can use Policy Evaluation to ensure that your artifacts align -with established best practices. +Policy Evaluation in Docker Scout lets you define supply chain rules for your +artifacts and evaluate compliance using the `docker scout policy` command. Run +evaluations locally, in CI pipelines, with custom Rego policies, or using OCI +bundles. See [Evaluate policies](./local.md). ## How Policy Evaluation works -When you activate Docker Scout for a repository, images that you push are -[automatically analyzed](/manuals/scout/explore/analysis.md). The analysis gives you insights -about the composition of your images, including what packages they contain and -what vulnerabilities they're exposed to. Policy Evaluation builds on top of the -image analysis feature, interpreting the analysis results against the rules -defined by policies. - -A policy defines image quality criteria that your artifacts should fulfill. -For example, the **No AGPL v3 licenses** policy flags any image containing packages distributed under the AGPL v3 license. -If an image contains such a package, that image is non-compliant with this policy. -Some policies, such as the **No AGPL v3 licenses** policy, are configurable. -Configurable policies let you adjust the criteria to better match your organization's needs. - -In Docker Scout, policies are designed to help you ratchet forward your -security and supply chain stature. Where other tools focus on providing a pass -or fail status, Docker Scout policies visualizes how small, incremental changes -affect policy status, even when your artifacts don't meet the policy -requirements (yet). By tracking how the fail gap changes over time, you more -easily see whether your artifact is improving or deteriorating relative to -policy. - -Policies don't necessarily have to be related to application security and -vulnerabilities. You can use policies to measure and track other aspects of -supply chain management as well, such as open-source license usage and base -image up-to-dateness. +When you run `docker scout policy`, the CLI indexes the image into an SBOM and +enriches it with CVE and VEX data. It then evaluates each configured policy +in-process against that data. No data is sent to the Scout service, and an +organization is not required for most use cases. -## Policy types +A policy defines image quality criteria your artifacts should meet. For +example, the **No copyleft licenses** policy flags any image containing +packages distributed under a copyleft license. If an image contains such a +package, it's non-compliant with that policy. -In Docker Scout, a *policy* is derived from a *policy type*. Policy types are -templates that define the core parameters of a policy. You can compare policy -types to classes in object-oriented programming, with each policy acting as an -instance created from its corresponding policy type. +## Policy types -Docker Scout supports the following policy types: +Docker Scout includes the following built-in policy types: - [Severity-Based Vulnerability](#severity-based-vulnerability) -- [Compliant Licenses](#compliant-licenses) -- [Up-to-Date Base Images](#up-to-date-base-images) +- [No copyleft licenses](#no-copyleft-licenses) +- [No outdated base images](#no-outdated-base-images) - [High-Profile Vulnerabilities](#high-profile-vulnerabilities) - [Supply Chain Attestations](#supply-chain-attestations) - [Default Non-Root User](#default-non-root-user) - [Approved Base Images](#approved-base-images) -- [SonarQube Quality Gates](#sonarqube-quality-gates) -- [Valid Docker Hardened Image (DHI) or DHI base image](#valid-docker-hardened-image-dhi-or-dhi-base-image) - -Docker Scout automatically provides default policies for repositories where it -is enabled, except for the following policies, which are optional and must be -configured: - -- The **SonarQube Quality Gates** policy, which requires - [integration with SonarQube](/manuals/scout/integrations/code-quality/sonarqube.md) - before use. -- The **Valid Docker Hardened Image (DHI) or DHI base image** policy, which can - be configured if you want to enforce the use of Docker Hardened Images. -You can create custom policies from any of the supported policy types, or -delete a default policy if it isn't applicable to your project. For more -information, refer to [Configure policies](./configure.md). +For configuration options for each policy type, see +[Evaluate policies](./local.md#configure-built-in-policies). ### Severity-Based Vulnerability -The **Severity-Based Vulnerability** policy type checks whether your -artifacts are exposed to known vulnerabilities. - -By default, this policy only flags critical and high severity vulnerabilities -where there's a fix version available. Essentially, this means that there's an -easy fix that you can deploy for images that fail this policy: upgrade the -vulnerable package to a version containing a fix for the vulnerability. - -Images are deemed non-compliant with this policy if they contain one or more -vulnerabilities that fall outside the specified policy criteria. - -You can configure the parameters of this policy by creating a custom version of the policy. -The following policy parameters are configurable in a custom version: - -- **Age**: The minimum number of days since the vulnerability was first published - - The rationale for only flagging vulnerabilities of a certain minimum age is - that newly discovered vulnerabilities shouldn't cause your evaluations to - fail until you've had a chance to address them. +The **Severity-Based Vulnerability** policy type checks whether your artifacts +are exposed to known vulnerabilities. By default, it flags critical and high +severity vulnerabilities where a fix version is available. - -- **Severities**: Severity levels to consider (default: `Critical, High`) - +Configurable parameters include severity levels, a grace period for newly +disclosed CVEs, fixable-only filtering, and package type filtering. -- **Fixable vulnerabilities only**: Whether or not to only report - vulnerabilities with a fix version available (enabled by default). +### No copyleft licenses -- **Package types**: List of package types to consider. +The **No copyleft licenses** policy type checks whether your images contain +packages distributed under an inappropriate license. You can configure the +list of licenses to flag and add package-level exceptions. - This option lets you specify the package types, as [PURL package type definitions](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst), - that you want to include in the policy evaluation. By default, the policy - considers all package types. +### No outdated base images -For more information about configuring policies, see [Configure policies](./configure.md). +The **No outdated base images** policy type checks whether the base images you +use are current. Images are non-compliant if the tag you built from points to +a different digest than what you're using. -### Compliant Licenses - -The **Compliant Licenses** policy type checks whether your images contain -packages distributed under an inappropriate license. Images are considered -non-compliant if they contain one or more packages with such a license. - -You can configure the list of licenses that this policy should look out for, -and add exceptions by specifying an allow-list (in the form of PURLs). -See [Configure policies](./configure.md). - -### Up-to-Date Base Images - -The **Up-to-Date Base Images** policy type checks whether the base images you -use are up-to-date. - -Images are considered non-compliant with this policy if the tag you used to -build your image points to a different digest than what you're using. If -there's a mismatch in digests, that means the base image you're using is out of -date. - -Your images need provenance attestations for this policy to successfully -evaluate. For more information, see [No base image data](#no-base-image-data). +Your images need provenance attestations for this policy to evaluate +successfully. For more information, see [No base image data](#no-base-image-data). ### High-Profile Vulnerabilities The **High-Profile Vulnerabilities** policy type checks whether your images -contain vulnerabilities from Docker Scout’s curated list. This list is kept -up-to-date with newly disclosed vulnerabilities that are widely recognized to -be risky. - -The list includes the following vulnerabilities: - -- [CVE-2014-0160 (OpenSSL Heartbleed)](https://scout.docker.com/v/CVE-2014-0160) -- [CVE-2021-44228 (Log4Shell)](https://scout.docker.com/v/CVE-2021-44228) -- [CVE-2023-38545 (cURL SOCKS5 heap buffer overflow)](https://scout.docker.com/v/CVE-2023-38545) -- [CVE-2023-44487 (HTTP/2 Rapid Reset)](https://scout.docker.com/v/CVE-2023-44487) -- [CVE-2024-3094 (XZ backdoor)](https://scout.docker.com/v/CVE-2024-3094) -- [CVE-2024-47176 (OpenPrinting - `cups-browsed`)](https://scout.docker.com/v/CVE-2024-47176) -- [CVE-2024-47076 (OpenPrinting - `libcupsfilters`)](https://scout.docker.com/v/CVE-2024-47076) -- [CVE-2024-47175 (OpenPrinting - `libppd`)](https://scout.docker.com/v/CVE-2024-47175) -- [CVE-2024-47177 (OpenPrinting - `cups-filters`)](https://scout.docker.com/v/CVE-2024-47177) - -You can customize this policy to change which CVEs that are considered -high-profile by configuring the policy. Custom configuration options include: - -- **Excluded CVEs**: Specify the CVEs that you want this policy to ignore. +contain vulnerabilities from a [curated list of widely recognized, high-impact +CVEs](./local.md#default-high-profile-cves), including Log4Shell, Spring4Shell, +and XZ backdoor. The list is updated as new high-profile vulnerabilities are +disclosed. - Default: `[]` (none of the high-profile CVEs are ignored) - -- **CISA KEV**: Enable tracking of vulnerabilities from CISA's Known Exploited Vulnerabilities (KEV) catalog - - The [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) - includes vulnerabilities that are actively exploited in the wild. When enabled, - the policy flags images that contain vulnerabilities from the CISA KEV catalog. - - Enabled by default. - -For more information on policy configuration, see [Configure policies](./configure.md). +You can configure which CVEs are considered high-profile and enable tracking +of CISA's Known Exploited Vulnerabilities catalog. ### Supply Chain Attestations The **Supply Chain Attestations** policy type checks whether your images have [SBOM](/manuals/build/metadata/attestations/sbom.md) and -[provenance](/manuals/build/metadata/attestations/slsa-provenance.md) attestations. +[provenance](/manuals/build/metadata/attestations/slsa-provenance.md) +attestations. Images are non-compliant if they lack either attestation type. -Images are considered non-compliant if they lack either an SBOM attestation or -a provenance attestation with *max mode* provenance. To ensure compliance, -update your build command to attach these attestations at build-time: +To ensure compliance, build with attestations: ```console $ docker buildx build --provenance=true --sbom=true -t --push . ``` -For more information about building with attestations, see -[Attestations](/manuals/build/metadata/attestations/_index.md). - -If you're using GitHub Actions to build and push your images, -learn how you can [configure the action](/manuals/build/ci/github-actions/attestations.md) -to apply SBOM and provenance attestations. - ### Default Non-Root User -By default, containers run as the `root` superuser with full system -administration privileges inside the container, unless the Dockerfile specifies -a different default user. Running containers as a privileged user weakens their -runtime security, as it means any code that runs in the container can perform -administrative actions. - -The **Default Non-Root User** policy type detects images that are set to run as -the default `root` user. To comply with this policy, images must specify a -non-root user in the image configuration. Images are non-compliant with this -policy if they don't specify a non-root default user for the runtime stage. - -For non-compliant images, evaluation results show whether or not the `root` -user was set explicitly for the image. This helps you distinguish between -policy violations caused by images where the `root` user is implicit, and -images where `root` is set on purpose. - -The following Dockerfile runs as `root` by default despite not being explicitly set: - -```Dockerfile -FROM alpine -RUN echo "Hi" -``` - -Whereas in the following case, the `root` user is explicitly set: - -```Dockerfile -FROM alpine -USER root -RUN echo "Hi" -``` - -> [!NOTE] -> -> This policy only checks for the default user of the image, as set in the -> image configuration blob. Even if you do specify a non-root default user, -> it's still possible to override the default user at runtime, for example by -> using the `--user` flag for the `docker run` command. - -To make your images compliant with this policy, use the -[`USER`](/reference/dockerfile.md#user) Dockerfile instruction to set -a default user that doesn't have root privileges for the runtime stage. - -The following Dockerfile snippets shows the difference between a compliant and -non-compliant image. - -{{< tabs >}} -{{< tab name="Non-compliant" >}} - -```dockerfile -FROM alpine AS builder -COPY Makefile ./src / -RUN make build - -FROM alpine AS runtime -COPY --from=builder bin/production /app -ENTRYPOINT ["/app/production"] -``` - -{{< /tab >}} -{{< tab name="Compliant" >}} - -```dockerfile {hl_lines=7} -FROM alpine AS builder -COPY Makefile ./src / -RUN make build - -FROM alpine AS runtime -COPY --from=builder bin/production /app -USER nonroot -ENTRYPOINT ["/app/production"] -``` - -{{< /tab >}} -{{< /tabs >}} +The **Default Non-Root User** policy type detects images configured to run as +the `root` user. Use the +[`USER`](/reference/dockerfile.md#user) Dockerfile instruction to set a +non-root default user for the runtime stage. ### Approved Base Images -The **Approved Base Images** policy type ensures that the base images you use -in your builds are maintained and secure. - -This policy checks whether the base images used in your builds match any of the -patterns specified in the policy configuration. The following table shows a few -example patterns for this policy. - -| Use case | Pattern | -| --------------------------------------------------------------- | -------------------------------- | -| Allow all images from Docker Hub | `docker.io/*` | -| Allow all Docker Official Images | `docker.io/library/*` | -| Allow images from a specific organization | `docker.io/orgname/*` | -| Allow tags of a specific repository | `docker.io/orgname/repository:*` | -| Allow images on a registry with hostname `registry.example.com` | `registry.example.com/*` | -| Allow slim tags of NodeJS images | `docker.io/library/node:*-slim` | - -An asterisk (`*`) matches up until the character that follows, or until the end -of the image reference. Note that the `docker.io` prefix is required in order -to match Docker Hub images. This is the registry hostname of Docker Hub. - -This policy is configurable with the following options: - -- **Approved base image sources** - - Specify the image reference patterns that you want to allow. The policy - evaluates the base image references against these patterns. - - Default: `[*]` (any reference is an allowed base image) - -- **Only supported tags** - - Allow only supported tags when using Docker Official Images. - - When this option is enabled, images using unsupported tags of official images - as their base image trigger a policy violation. Supported tags for official - images are listed in the **Supported tags** section of the repository - overview on Docker Hub. - - Enabled by default. - -- **Only supported OS distributions** +The **Approved Base Images** policy type ensures the base images you use match +a configurable allowlist of glob patterns. Images are non-compliant if the +base image reference doesn't match any of the allowed patterns. - Allow only Docker Official Images of supported Linux distribution versions. +Your images need provenance attestations for this policy to evaluate +successfully. For more information, see [No base image data](#no-base-image-data). - When this option is enabled, images using unsupported Linux distributions - that have reached end of life (such as `ubuntu:18.04`) trigger a policy violation. - - Enabling this option may cause the policy to report no data - if the operating system version cannot be determined. - - Enabled by default. - -Your images need provenance attestations for this policy to successfully -evaluate. For more information, see [No base image data](#no-base-image-data). - -### SonarQube Quality Gates - -The **SonarQube Quality Gates** policy type builds on the [SonarQube -integration](../integrations/code-quality/sonarqube.md) to assess the quality -of your source code. This policy works by ingesting the SonarQube code analysis -results into Docker Scout. - -You define the criteria for this policy using SonarQube's [quality -gates](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/). -SonarQube evaluates your source code against the quality gates you've defined -in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout -policy. - -Docker Scout uses [provenance](/manuals/build/metadata/attestations/slsa-provenance.md) -attestations or the `org.opencontainers.image.revision` OCI annotation to link -SonarQube analysis results with container images. In addition to enabling the -SonarQube integration, you must also make sure that your images have either the -attestation or the label. - -![Git commit SHA links image with SonarQube analysis](../images/scout-sq-commit-sha.webp) - -Once you push an image and policy evaluation completes, the results from the -SonarQube quality gates display as a policy in the Docker Scout Dashboard, and -in the CLI. - -> [!NOTE] -> -> Docker Scout can only access SonarQube analyses created after the integration -> is enabled. Docker Scout doesn't have access to historic evaluations. Trigger -> a SonarQube analysis and policy evaluation after enabling the integration to -> view the results in Docker Scout. - -### Valid Docker Hardened Image (DHI) or DHI base image - -The **Valid Docker Hardened Image (DHI) or DHI base image** policy type ensures -that your images are either Docker Hardened Images (DHI) or are built using a -DHI as the base image. - -This policy validates images by checking for a valid Docker signed verification -summary attestation. The policy considers an image compliant if either: - -- The image itself is a Docker Hardened Image with a valid Docker signed - verification summary attestation, or -- The base image used in the build (identified from SLSA provenance - attestations) has a valid Docker signed verification summary attestation - -Images are non-compliant with this policy if they lack the required Docker -signed verification summary attestation and are not built from a base image -with such an attestation. - -This policy has no configurable parameters. + ## No base image data -There are cases when it's not possible to determine information about the base -images used in your builds. In such cases, the **Up-to-Date Base Images** and -**Approved Base Images** policies get flagged as having **No data**. - -This "no data" state occurs when: +The **No outdated base images** and **Approved Base Images** policies require +provenance attestations to determine the base image used in your build. Without +them, these policies report **No data**. -- Docker Scout doesn't know what base image tag you used -- The base image version you used has multiple tags, but not all tags are out - of date +To ensure Docker Scout always has base image information, attach provenance +attestations at build time: -To make sure that Docker Scout always knows about your base image, you can -attach [provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md) -at build-time. Docker Scout uses provenance attestations to find out the base -image version. +```console +$ docker buildx build --provenance=true -t --push . +``` diff --git a/content/manuals/scout/policy/ci.md b/content/manuals/scout/policy/ci.md deleted file mode 100644 index ce466973d7db..000000000000 --- a/content/manuals/scout/policy/ci.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Evaluate policy compliance in CI -description: | - Configure your continuous integration pipelines to fail - when Policy Evaluation for an image is worse compared to baseline -keywords: scout, supply chain, policy, ci ---- - -Adding Policy Evaluation to your continuous integration pipelines helps you -detect and prevent cases where code changes would cause policy compliance to -become worse compared to your baseline. - -The recommended strategy for Policy Evaluation in a CI setting involves -evaluating a local image and comparing the results to a baseline. If the policy -compliance for the local image is worse than the specified baseline, the CI run -fails with an error. If policy compliance is better or unchanged, the CI run -succeeds. - -This comparison is relative, meaning that it's only concerned with whether your -CI image is better or worse than your baseline. It's not an absolute check to -pass or fail all policies. By measuring relative to a baseline that you define, -you can quickly see if a change has a positive or negative impact on policy -compliance. - -## How it works - -When you do Policy Evaluation in CI, you run a local policy evaluation on the -image you build in your CI pipeline. To run a local evaluation, the image that -you evaluate must exist in the image store where your CI workflow is being run. -Either build or pull the image, and then run the evaluation. - -To run policy evaluation and trigger failure if compliance for your local image -is worse than your comparison baseline, you need to specify the image version -to use as a baseline. You can hard-code a specific image reference, but a -better solution is to use [environments](../integrations/environment/_index.md) -to automatically infer the image version from an environment. The example that -follows uses environments to compare the CI image with the image in the -`production` environment. - -## Example - -The following example on how to run policy evaluation in CI uses the [Docker -Scout GitHub Action](https://github.com/marketplace/actions/docker-scout) to -execute the `compare` command on an image built in CI. The compare command has -a `to-env` input, which will run the comparison against an environment called -`production`. The `exit-on` input is set to `policy`, meaning that the -comparison fails only if policy compliance has worsened. - -This example doesn't assume that you're using Docker Hub as your container -registry. As a result, this workflow uses the `docker/login-action` twice: - -- Once for authenticating to your container registry. -- Once more for authenticating to Docker to pull the analysis results of your - `production` image. - -If you use Docker Hub as your container registry, you only need to authenticate -once. - -> [!NOTE] -> -> Due to a limitation in the Docker Engine, loading multi-platform images or -> images with attestations to the image store isn't supported. -> -> For the policy evaluation to work, you must load the image to the local image -> store of the runner. Ensure that you're building a single-platform image -> without attestations, and that you're loading the build results. Otherwise, -> the policy evaluation fails. - -Also note the `pull-requests: write` permission for the job. The Docker Scout -GitHub Action adds a pull request comment with the evaluation results by -default, which requires this permission. For details, see -[Pull Request Comments](https://github.com/docker/scout-action#pull-request-comments). - -```yaml -name: Docker - -on: - push: - tags: ["*"] - branches: - - "main" - pull_request: - branches: ["**"] - -env: - REGISTRY: docker.io - IMAGE_NAME: - DOCKER_ORG: - -jobs: - build: - permissions: - pull-requests: write - - runs-on: ubuntu-latest - steps: - - name: Log into registry ${{ env.REGISTRY }} - uses: docker/login-action@{{% param "login_action_version" %}} - with: - registry: ${{ env.REGISTRY }} - username: ${{ secrets.REGISTRY_USER }} - password: ${{ secrets.REGISTRY_TOKEN }} - - - name: Setup Docker buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Extract metadata - id: meta - uses: docker/metadata-action@{{% param "metadata_action_version" %}} - with: - images: ${{ env.IMAGE_NAME }} - - - name: Build image - id: build-and-push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - sbom: ${{ github.event_name != 'pull_request' }} - provenance: ${{ github.event_name != 'pull_request' }} - push: ${{ github.event_name != 'pull_request' }} - load: ${{ github.event_name == 'pull_request' }} - - - name: Authenticate with Docker - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ secrets.DOCKER_USER }} - password: ${{ secrets.DOCKER_PAT }} - - - name: Compare - if: ${{ github.event_name == 'pull_request' }} - uses: docker/scout-action@v1 - with: - command: compare - image: ${{ steps.meta.outputs.tags }} - to-env: production - platform: "linux/amd64" - ignore-unchanged: true - only-severities: critical,high - organization: ${{ env.DOCKER_ORG }} - exit-on: policy -``` - -The following screenshot shows what the GitHub PR comment looks like when a -policy evaluation check fails because policy has become worse in the PR image -compared to baseline. - -![Policy evaluation comment in GitHub PR](../images/scout-policy-eval-ci.webp) - -This example has demonstrated how to run policy evaluation in CI with GitHub -Actions. Docker Scout also supports other CI platforms. For more information, -see [Docker Scout CI -integrations](../integrations/_index.md#continuous-integration). diff --git a/content/manuals/scout/policy/configure.md b/content/manuals/scout/policy/configure.md deleted file mode 100644 index 98d23fb4ca79..000000000000 --- a/content/manuals/scout/policy/configure.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Configure policies -description: Learn how to configure, disable, or delete policies in Docker Scout -keywords: scout, policy, configure, delete, enable, parametrize, thresholds ---- - -Some policy types are configurable. This means that you can create new, -customized version of that policy type with your own configuration parameters. -You can also disable a policy if you need to temporarily disregard it, or -delete a policy altogether if it doesn't match your needs. - -> [!NOTE] -> Historic evaluation results for the default policy configuration are removed -> if you delete or customize a policy. - -## Add a policy - -To add a new policy, select the policy type that you want to customize. All -custom policies use a policy type as a base. - -You can edit the display name and description of the new policy to help -better communicate the compliant and non-compliant states of the policy. -You can not change the name of the policy type, only its display names. - -The available configuration parameters for a policy depends on the -policy type that you're editing. For more information, refer to -[Policy types](/manuals/scout/policy/_index.md#policy-types). - -To add a policy: - -1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard. -2. Select the **Add policy** button to open the policy configuration screen. -3. On the policy configuration screen, locate the policy type that you want to - configure, and select **Configure** to open the policy configuration page. - - - If the **Configure** button is grayed out, it means the current policy - has no configurable parameters. - - If the button reads **Integrate**, it indicates that setup is required - before the policy can be enabled. Selecting **Integrate** will direct you - to the integration's setup guide. - -4. Update the policy parameters. -5. Save the changes: - - - Select **Save policy** to commit the changes and enable the policy for - your current organization. - - Select **Save and disable** to save the policy configuration without enabling - it. - -## Edit a policy - -Editing a policy lets you to modify its configuration without creating -a new one from scratch. This can be useful when policy parameters need adjustments -due to evolving requirements or changes in your organization's compliance goals. - -To edit a policy: - -1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard. -2. Select the policy you want to edit. -3. Select the **Edit** button. -4. Update the policy parameters. -5. Save the changes. - -## Disable a policy - -When you disable a policy, evaluation results for that policy are hidden, and -no longer appear in the Docker Scout Dashboard or in the CLI. Historic -evaluation results aren't deleted if you disable a policy, so if you change -your mind and re-enable a policy later, results from earlier evaluations will -still be available. - -To disable a policy: - -1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard. -2. Select the policy you want to disable. -3. Select the **Disable** button. - -## Delete a policy - -When you delete a policy, evaluation results for that policy are deleted as -well, and no longer appear in the Docker Scout Dashboard or in the CLI. - -To delete a policy: - -1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard. -2. Select the policy you want to delete. -3. Select the **Delete** button. - -## Recover a deleted policy - -If you've deleted a policy, you can recreate it by following the steps in [Add -a policy](#add-a-policy). On the policy configuration screen, select -**Configure** on the deleted policy that you wish to recreate. diff --git a/content/manuals/scout/policy/local.md b/content/manuals/scout/policy/local.md new file mode 100644 index 000000000000..7632453d0c8d --- /dev/null +++ b/content/manuals/scout/policy/local.md @@ -0,0 +1,527 @@ +--- +title: Evaluate policies +description: Evaluate Docker Scout policies using the CLI, with built-in and custom Rego policies +keywords: scout, policy, rego, opa, cli, custom policies, policy bundle +aliases: + - /scout/policy/dashboard/ + - /scout/policy/ci/ + - /scout/policy/view/ + - /scout/policy/configure/ + - /scout/policy/remediation/ +--- + +{{< summary-bar feature_name="Evaluate policies" >}} + +`docker scout policy` lets you evaluate images against a configurable policy +set using the CLI. You can use the built-in defaults, adjust thresholds to +match your requirements, or write custom policies in +[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/). + +## How it works + +When you run `docker scout policy`, the CLI indexes the image into an SBOM, +enriches it with CVE and VEX data, then evaluates each configured policy +in-process. No data is sent to the Scout service, and an +organization is not required for most use cases. + +Policies come from three sources, which can be combined: + +- Built-in defaults: a curated set embedded in the CLI, used when no other + source is given. +- OCI policy bundles: Rego packaged as an OCI artifact and pulled from a + registry with `--policy-bundle`. +- Local `.rego` files: for authoring and iterating on custom policies with + `--policy-file` or `--policy-dir`. + +## Use in CI + +Use the [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout) +to evaluate policies as part of your workflow: + +```yaml +- name: Evaluate policies + uses: docker/scout-action@v1 + with: + command: policy + image: ${{ env.IMAGE_NAME }} + organization: +``` + +For other CI platforms, install the +[Docker Scout CLI plugin](/manuals/scout/install.md) on your runner and run +`docker scout policy --exit-code`. + +To gate a build on policy compliance compared to an environment, use the +`compare` command with a policy configuration: + +```yaml +- uses: docker/scout-action@v1 + with: + command: compare + image: ${{ env.IMAGE_NAME }} + to-env: production + exit-on: policy + policy-config: policies.json + organization: +``` + +See [Configure built-in policies](#configure-built-in-policies) for the +`policy-config` file format. + +## Examples + +Evaluate an image against the built-in policy set: + +```console +$ docker scout policy myorg/app:latest +``` + +Use `--exit-code` to fail the pipeline when any policy is not met: + +```console +$ docker scout policy myorg/app:latest --exit-code +``` + +To customize which policies run and their thresholds, pass a policy-config +file: + +```console +$ docker scout policy myorg/app:latest --policy-config policies.json +``` + +Policy results are also surfaced by `docker scout quickview` and +`docker scout compare`, which accept the same `--policy-file`, +`--policy-dir`, `--policy-bundle`, and `--policy-config` flags. + +Other useful flags: + +```console +# Evaluate a specific platform for a multi-platform image +$ docker scout policy myorg/app:latest --platform linux/arm64 + +# Show results for a specific policy only +$ docker scout policy myorg/app:latest --only-policy "No copyleft licenses" + +# Write the report to a file +$ docker scout policy myorg/app:latest --output report.txt +``` + +## Health score + +`docker scout policy`, `docker scout quickview`, and `docker scout compare` also +report a health score alongside the policy results: a numeric percentage and an +A-F letter grade, computed entirely from the local policy evaluation. No data is +sent to the Scout service to compute it. + +```console +$ docker scout policy myorg/app:latest +... +Health score B (83%) +``` + +`docker scout compare` shows the score for both images: + +```console +Health score Analyzed B (83%) Comparison C (65%) +``` + +### How the score is calculated + +The score is a weighted pass ratio: + +- Each policy contributes a weight to the total, taken from its `custom.weight` + metadata annotation (see [Metadata annotations](#metadata-annotations)) or a + `weight` override in the policy-config file. Policies without a declared + weight default to `10`. +- A policy that passes (reports zero violations) contributes its full weight to + the scored points. +- A policy that fails still counts its weight toward the total, but contributes + nothing to the scored points, which lowers the score. +- A policy with no data to evaluate (unknown) also counts toward the total + without contributing to the scored points. +- A policy with a weight of `0` is excluded from the score entirely. + +The percentage is `scored / total * 100`, mapped to a letter grade using strict +greater-than thresholds: + +| Score | Grade | +| --- | --- | +| > 90% | A | +| > 70% | B | +| > 50% | C | +| > 30% | D | +| > 10% | E | +| <= 10% | F | + +Thresholds are exclusive of their lower bound, so an exact boundary value +grades down: a score of exactly 90% is a B, not an A; exactly 70% is a C, and +so on. + +If every policy is excluded from the score (for example, all policies are +configured with `weight: 0`), no health score is shown at all. + +To change a policy's contribution to the score, set `custom.weight` in the +policy's Rego metadata, or override it per policy in the policy-config file: + +```json +{ + "policies": [ + { + "name": "copyleft-license", + "weight": 0 + } + ] +} +``` + +## Built-in policies + +The following policies are available by default: + +| Policy | What it checks | +| --- | --- | +| No fixable critical or high vulnerabilities | Critical/high CVEs that have a fix available | +| No high-profile vulnerabilities | Curated list of well-known CVEs (Log4Shell, XZ backdoor, and others) | +| No copyleft licenses | Packages under AGPL, GPL, LGPL, MPL, and similar licenses | +| No outdated base images | Base image is behind the latest digest of its tag | +| Supply chain attestations | Provenance and SBOM attestations are attached | +| Default non-root user | Image is configured to run as a non-root user | +| No unapproved base images | Base image matches a configurable allowlist | + +## Configure built-in policies + +A JSON policy-config file controls which policies run and their thresholds. +Pass it with `--policy-config`. + +```json +{ + "policies": [ + { + "name": "fixable-vulnerabilities", + "config": { + "severities": ["CRITICAL"], + "grace_period_days": 14 + } + }, + { + "name": "no-stale-base-images", + "enabled": false + } + ] +} +``` + +- `policies[].name`: the policy's stable ID (see the following table). +- `policies[].enabled`: set to `false` to skip the policy. Policies not listed are enabled by default. +- `policies[].weight`: overrides the policy's `custom.weight` metadata annotation, + which determines its contribution to the [health score](#health-score). A + weight of `0` excludes the policy from the score. When omitted, the policy's + own annotation is used, or `10` if it has none. +- `policies[].config`: an object passed to the policy as `data.config`. + +### Configuration reference + +The following table lists the configurable keys for each built-in policy. + +| Policy (stable ID) | config key | Default | Description | +| --- | --- | --- | --- | +| `fixable-vulnerabilities` | `severities` | `["CRITICAL","HIGH"]` | Severity levels that count as a violation | +| `fixable-vulnerabilities` | `fixable_only` | `true` | When `true`, only vulnerabilities with a known fix count | +| `fixable-vulnerabilities` | `package_types` | `[]` | Allowlist of PURL package types to consider; empty means all | +| `fixable-vulnerabilities` | `grace_period_days` | `0` | Days a newly disclosed CVE is exempt | +| `high-profile-vulnerabilities` | `cves` | [Default high-profile CVEs](#default-high-profile-cves) | CVE IDs considered high-profile | +| `high-profile-vulnerabilities` | `ignored_cves` | `[]` | CVE IDs excluded from causing a failure | +| `high-profile-vulnerabilities` | `include_cisa_kev` | `true` | Also flag vulnerabilities in the CISA KEV catalog | +| `copyleft-license` | `licenses` | AGPL/GPL/LGPL/MPL/… | SPDX license IDs treated as copyleft | +| `copyleft-license` | `ignored_packages` | `[]` | Package URLs exempted from the check | +| `approved-base-images` | `allowed_base_images` | `["*"]` | Glob patterns of allowed base image references | +| `approved-base-images` | `allowed_distros_only` | `true` | When enabled, base image must use an allowed OS distribution | +| `approved-base-images` | `allowed_distros` | curated list | OS distributions considered allowed | +| `supply-chain-attestations` | `required_attestations` | provenance and SBOM predicate types | Attestation predicate types that must be present | + +#### Default high-profile CVEs + +The built-in `cves` list includes the following CVEs. Docker updates this list +as new high-profile vulnerabilities are disclosed. + +| CVE ID | Common name | +| --- | --- | +| CVE-2014-0160 | Heartbleed | +| CVE-2014-6271 | Shellshock | +| CVE-2021-44228 | Log4Shell | +| CVE-2021-45046 | Log4j follow-up | +| CVE-2022-22965 | Spring4Shell | +| CVE-2023-38545 | curl SOCKS5 heap overflow | +| CVE-2023-44487 | HTTP/2 Rapid Reset | +| CVE-2024-3094 | XZ Utils backdoor | + +To override the list, set `cves` in your policy-config file: + +```json +{ + "policies": [ + { + "name": "high-profile-vulnerabilities", + "config": { + "cves": ["CVE-2021-44228", "CVE-2024-3094"] + } + } + ] +} +``` + +## Write custom policies + +Policies are Rego modules in the `docker.scout` package. A policy declares a +boolean `pass` rule and a `violation` set. Use `--policy-file` for a single +file or `--policy-dir` to load a directory recursively. + +```rego +# METADATA +# title: No packages from internal registry +# description: Flags packages sourced from registry.internal.example.com. +# custom: +# name: no-internal-registry +# result_type: generic +# weight: 5 +# not_compliant_title: Packages from internal registry found +# details_order: +# - purl +# - reason +package docker.scout + +import rego.v1 + +default pass := false + +pass if { + count(violation) == 0 +} + +violation contains v if { + att := oci.referrer("https://scout.docker.com/sbom/v0.1") + some pkg in att.statement.predicate.artifacts + contains(pkg.purl, "registry.internal.example.com") + v := { + "message": sprintf("Package %s sourced from internal registry", [pkg.purl]), + "detail": { + "purl": pkg.purl, + "reason": "matches registry.internal.example.com", + }, + } +} +``` + +```console +# Single file +$ docker scout policy myorg/app:latest --policy-file ./no-internal-registry.rego + +# Directory of policies +$ docker scout policy myorg/app:latest --policy-dir ./rego + +# Custom policies combined with a config file +$ docker scout policy myorg/app:latest \ + --policy-dir ./rego \ + --policy-config ./policies.json +``` + +Both `--policy-file` and `--policy-dir` are repeatable. When either is +provided, the built-in defaults are not loaded automatically. To run both +built-in and custom policies together, publish the built-in set to a registry +with `docker scout policy publish`, then pass both bundles using +`--policy-bundle`: + +```console +$ docker scout policy myorg/app:latest \ + --policy-bundle registry.example.com/default-policies:latest \ + --policy-bundle registry.example.com/dhi-policies:latest \ + --policy-file ./custom.rego +``` + +`--policy-bundle` is repeatable, so you can combine as many bundles as needed +alongside local policy files. + +### Metadata annotations + +The CLI reads [OPA metadata annotations](https://www.openpolicyagent.org/docs/latest/annotations/) +to render results. Place them in a `# METADATA` block immediately above the +`package` declaration. + +| Annotation | Purpose | +| --- | --- | +| `title` | Human-readable policy name shown in the report | +| `description` | Longer explanation | +| `custom.name` | Stable ID used to match `--policy-config` entries. Defaults to the package path if omitted | +| `custom.result_type` | How violations are rendered: `vulnerability`, `license`, `boolean`, or `generic` (default) | +| `custom.weight` | Scoring weight and display sort order. Higher weights sort first in the report and contribute more to the [health score](#health-score). Defaults to `10` when omitted; a weight of `0` excludes the policy from the score | +| `custom.not_compliant_title` | Status label shown when the policy fails | +| `custom.details_order` | Ordered list of `detail` keys to display as columns | + +### Output contract + +- `pass`: `true` when the policy is met. The standard form is `pass if { count(violation) == 0 }`. +- `violation`: a set of objects. Each object should have a `message` string and + a `detail` object whose keys match `custom.details_order`. An optional + `remediation` string is shown as remediation guidance. + +### Input and built-in functions + +The evaluation input is the enriched SBOM. Key entry points: + +- `input.source.image`: image metadata, including `input.source.image.config.config.User`, + `input.source.image.name`, and `input.source.image.digest`. +- `data.config`: the per-policy `config` object from the policy-config file. + +The following built-in functions are available in policy Rego: + +| Function | Description | +| --- | --- | +| `oci.referrer(predicateType)` | Retrieve an attestation by predicate type | +| `oci.canonical_name(ref)` | Normalize an image reference, for example `"node:25"` to `"docker.io/library/node"` | +| `oci.image_digest(ref)` | Resolve the current digest of a tag from its registry | +| `oci.index(ref, digest)` | Get the OCI image index for an image | +| `oci.referrer_index(ref, digest)` | Get the OCI referrer index for an image | +| `oci.referrer_by_digest(ref, digest)` | Get a referrer for an image by digest | +| `scout.parse_purl(purl)` | Parse a PURL into its components | +| `scout.package_provenance(purl)` | Provenance of a package from the SBOM | +| `scout.vulnerabilities(purls)` | Vulnerabilities for the given PURLs | +| `scout.package_recommendation(purl)` | Recommended (fixed) version for a package | +| `scout.base_image()` | Base image matches recorded in the SBOM | +| `cosign.verify_dsse(envelope, opts)` | Verify an in-toto DSSE envelope's cosign signature | +| `cosign.verify_image(ref, opts)` | Verify an image's cosign signature | +| `gpg.verify_commit(...)` | Verify a detached commit signature | + +Common predicate types for `oci.referrer`: + +| Predicate type | Content | +| --- | --- | +| `https://scout.docker.com/vulnerabilities/v0.1` | CVEs per package | +| `https://scout.docker.com/sbom/v0.1` | SBOM artifacts, with `purl` and `licenses` | +| `https://scout.docker.com/provenance/v0.1` | Build provenance, including `base_image` | +| `https://openvex.dev/ns/v0.2.0` | VEX statements | + +## Debug policies + +Add `print()` statements to your Rego and enable debug output by setting +`"debug": true` in the policy-config file: + +```rego +violation contains v if { + att := oci.referrer("https://scout.docker.com/sbom/v0.1") + some pkg in att.statement.predicate.artifacts + print("checking", pkg.purl) + contains(pkg.purl, blocked) + # ... +} +``` + +```json +{ + "debug": true, + "policies": [ + { "name": "no-internal-registry" } + ] +} +``` + +Output is prefixed with the policy name and source line: + +```text +no-internal-registry#28: checking pkg:deb/debian/curl@7.88.1 +``` + +> [!NOTE] +> +> The `debug` field in the policy-config controls `print()` output from your +> Rego. The global `--debug` flag is separate: it enables CLI-level debug +> logging for bundle loading, registry resolution, and similar internals. + +### Inspect raw evaluation results + +Use `--result-file` to write the full evaluation result for every policy to a +JSON file. This is useful when iterating on a custom policy to inspect +intermediate values. + +```console +$ docker scout policy myorg/app:latest \ + --policy-file ./no-internal-registry.rego \ + --result-file result.json +``` + +Each entry in the output contains: + +- `pass`: the policy's boolean outcome. +- `violations`: the `detail` object of each reported violation. +- `bindings`: the raw `data.docker.scout` document, including the `violation` + set and any other complete rules, for inspecting intermediate values. +- `metrics`: OPA evaluation metrics (timers and counters). + +```json +{ + "no-internal-registry": { + "pass": false, + "violations": [ + { "purl": "pkg:deb/debian/curl@7.88.1", "reason": "matches \"registry.internal.example.com\"" } + ], + "bindings": { + "blocked": "registry.internal.example.com", + "violation": [ + { + "message": "Package pkg:deb/debian/curl@7.88.1 sourced from internal registry", + "detail": { + "purl": "pkg:deb/debian/curl@7.88.1", + "reason": "matches \"registry.internal.example.com\"" + } + } + ] + }, + "metrics": { + "timer_rego_query_eval_ns": 1234567 + } + } +} +``` + +## Share policies as OCI bundles + +Package `.rego` files as an OCI artifact and distribute them through any +registry. + +### Publish a bundle + +```console +# Publish a directory of policies +$ docker scout policy publish \ + --policy-dir ./rego \ + registry.example.com/my-policies:latest + +# Publish specific files +$ docker scout policy publish \ + --policy-file fixable.rego \ + --policy-file licenses.rego \ + registry.example.com/my-policies:latest + +# Publish the built-in default set +$ docker scout policy publish registry.example.com/my-policies:latest +``` + +Each module's metadata is validated before publishing. The command prints the +resulting digest and the list of bundled policies. + +### Use a bundle + +```console +$ docker scout policy myorg/app:latest \ + --policy-bundle registry.example.com/my-policies:latest + +# Combine a bundle with local files and a config +$ docker scout policy myorg/app:latest \ + --policy-bundle registry.example.com/my-policies:latest \ + --policy-file ./extra.rego \ + --policy-config ./policies.json +``` + +`--policy-bundle` is repeatable. Authentication uses your existing Docker +registry credentials. Bundles are cached by digest, so re-running against the +same bundle does not re-download it. A new digest (for example, after +re-publishing `:latest`) is fetched automatically. diff --git a/content/manuals/scout/policy/remediation.md b/content/manuals/scout/policy/remediation.md deleted file mode 100644 index a37c6ddad7f9..000000000000 --- a/content/manuals/scout/policy/remediation.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Remediation with Docker Scout -description: Learn how Docker Scout can help you improve your software quality automatically, using remediation -keywords: scout, supply chain, security, remediation, automation ---- - -{{< summary-bar feature_name="Remediation with Docker Scout" >}} - -Docker Scout helps you remediate supply chain or security issues by providing -recommendations based on policy evaluation results. Recommendations are -suggested actions you can take that improve policy compliance, or that add -metadata to images which enables Docker Scout to provide better evaluation -results and recommendations. - -Docker Scout provides remediation advice for the default policies of the -following policy types: - -- [Up-to-Date Base Images](#up-to-date-base-images-remediation) -- [Supply Chain Attestations](#supply-chain-attestations-remediation) - -> [!NOTE] -> Guided remediation is not supported for custom policies. - -For images that violate policy, the recommendations focus on addressing -compliance issues and fixing violations. For images where Docker Scout is -unable to determine compliance, recommendations show you how to meet the -prerequisites that ensure Docker Scout can successfully evaluate the policy. - -## View recommendations - -Recommendations appear on the policy details pages of the Docker Scout -Dashboard. To get to this page: - -1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard. -2. Select a policy in the list. - -The policy details page groups evaluation results into two different tabs -depending on the policy status: - -- Violations -- Compliance unknown - -The **Violations** tab lists images that don't comply with the selected policy. -The **Compliance unknown** tab lists images that Docker Scout is unable to -determine the compliance status for. When compliance is unknown, Docker Scout -needs more information about the image. - -To view recommended actions for an image, hover over one of the images in the -list to reveal a **View fixes** button. - -![Remediation for policy violations](../images/remediation.png) - -Select the **View fixes** button to opens the remediation side panel containing -recommended actions for your image. - -If there are more than one recommendations available, the primary -recommendation displays as the **Recommended fix**. Additional recommendations -are listed as **Quick fixes**. Quick fixes are usually actions that provide a -temporary solution. - -The side panel may also contain one or more help sections related to the -available recommendations. - -## Up-to-Date Base Images remediation - -The **Up-to-Date Base Images** policy checks whether the base image you use is -up-to-date. The recommended actions displayed in the remediation side panel -depend on how much information Docker Scout has about your image. The more -information that's available, the better the recommendations. - -The following scenarios outline the different recommendations depending on the -information available about the image. - -### No provenance attestations - -For Docker Scout to be able to evaluate this policy, you must add [provenance -attestations](/manuals/build/metadata/attestations/slsa-provenance.md) to your image. If -your image doesn't have provenance attestations, compliance is undeterminable. - -### Provenance attestations available - -With provenance attestations added, Docker Scout can correctly detect the base -image version that you're using. The version found in the attestations is -cross-referenced against the current version of the corresponding tag to -determine if it's up-to-date. - -If there's a policy violation, the recommended actions show how to update your -base image version to the latest version, while also pinning the base image -version to a specific digest. For more information, see [Pin base image -versions](/manuals/build/building/best-practices.md#pin-base-image-versions). - -### GitHub integration enabled - -If you're hosting the source code for your image on GitHub, you can enable the -[GitHub integration](../integrations/source-code-management/github.md). This -integration enables Docker Scout to provide even more useful remediation -advice, and lets you initiate remediation for violations directly from the -Docker Scout Dashboard. - -With the GitHub integration enabled, you can use the remediation side panel to -raise a pull request on the GitHub repository of the image. The pull request -automatically updates the base image version in your Dockerfile to the -up-to-date version. - -This automated remediation pins your base image to a specific digest, while -helping you stay up-to-date as new versions become available. Pinning the base -image to a digest is important for reproducibility, and helps avoid unwanted -changes from making their way into your supply chain. - -For more information about base image pinning, see [Pin base image -versions](/manuals/build/building/best-practices.md#pin-base-image-versions). - -## Supply Chain Attestations remediation - -The default **Supply Chain Attestations** policy requires full provenance and -SBOM attestations on images. If your image is missing an attestation, or if an -attestation doesn't contain enough information, the policy is violated. - -The recommendations available in the remediation side panel helps guide you to -what action you need to take to address the issues. For example, if your image -has a provenance attestation, but the attestation doesn't contain enough -information, you're recommended to re-build your image with -[`mode=max`](/manuals/build/metadata/attestations/slsa-provenance.md#max) provenance. diff --git a/content/manuals/scout/policy/scores.md b/content/manuals/scout/policy/scores.md deleted file mode 100644 index e6b2d7af80c1..000000000000 --- a/content/manuals/scout/policy/scores.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Docker Scout health scores -description: | - Docker Scout health scores provide a supply chain assessment for Docker Hub - images, grading them from A to F based on various security policies. -keywords: scout, health scores, evaluation, checks, grades, docker hub ---- - -{{< summary-bar feature_name="Docker Scout health scores" >}} - -Docker Scout health scores provide a security assessment, and overall supply -chain health, of images on Docker Hub, helping you determine whether an image -meets established security best practices. The scores range from A to F, where -A represents the highest level of security and F the lowest, offering an -at-a-glance view of the security posture of your images. - -Only users who are members of the organization that owns the repository, and -have at least “read” access to the repository, can view the health score. The -score is not visible to users outside the organization or members without -"read" access. - -## Viewing health scores - -{{< tabs >}} -{{< tab name="Docker Hub" >}} - -To view the health score of an image in Docker Hub: - -1. Go to Docker Hub and sign in. -2. Navigate to your organization's page. - -In the list of repositories, you can see the health score of each repository -based on the latest pushed tag. - -![Repository health score](../images/score-badges-repolist.png) - -{{< /tab >}} -{{< tab name="Docker Desktop" >}} - -To view the health score of an image in Docker Desktop: - -1. Open Docker Desktop and sign in to your Docker account. -2. Navigate to the **Images** view and select the **Hub** tab. - -In the list of repositories, the **Health** column displays the scores of the -different tags that have been pushed to Docker Hub. - -![Repository health score](../images/score-badges-dd.png) - -{{< /tab >}} -{{< /tabs >}} - -The health score badge is color-coded to indicate the overall health of the -repository: - -- **Green**: A score of A or B. -- **Yellow**: A score of C. -- **Orange**: A score of D. -- **Red**: A score of E or F. -- **Gray**: An `N/A` score. - -The score is also displayed on the Docker Hub page for a given repository, -along with each policy that contributed to the score. - -![Scout "A" health score](../images/score-a-shiny.png?w=450px) - -## Scoring system - -Health scores are determined by evaluating images against Docker Scout -[policies](./_index.md). These policies align with best practices for the -software supply chain. - -If your image repositories are already enrolled with Docker Scout, the health -score is calculated automatically based on the policies that are enabled for -your organization. This also includes any custom policies that you have -configured. - -If you're not using Docker Scout, the health scores show the compliance of your -images with the default policies, a set of supply chain rules recommended by -Docker as foundational standards for images. You can enable Docker Scout for -your organization and edit the policy configurations to get a more relevant -health score based on your specific policies. - -### Scoring process - -Each policy is assigned a points value based on its -[type](/manuals/scout/policy/_index.md#policy-types). If the image is compliant -with a policy, it is awarded the points value for that policy type. The health -score of an image is calculated based on the percentage of points achieved -relative to the total possible points. - -1. Policy compliance is evaluated for the image. -2. Points are awarded based on compliance with policies. -3. The points achieved percentage is calculated: - - ```text - Percentage = (Points / Total) * 100 - ``` - -4. The final score is assigned based on the percentage of points achieved, as - shown in the following table: - - | Points percentage (awarded out of total) | Score | - | ---------------------------------------- | ----- | - | More than 90% | A | - | 71% to 90% | B | - | 51% to 70% | C | - | 31% to 50% | D | - | 11% to 30% | E | - | Less than 10% | F | - -### N/A scores - -Images can also be assigned an `N/A` score, which can happen when: - -- The image is larger than 4GB (compressed size). -- The image architecture is not `linux/amd64` or `linux/arm64`. -- The image is too old and does not have fresh data for evaluation. - -If you see an `N/A` score, consider the following: - -- If the image is too large, try reducing the size of the image. -- If the image has an unsupported architecture, rebuild the image for a - supported architecture. -- If the image is too old, push a new tag to trigger a fresh evaluation. - -### Policy weights - -Different policy types carry varying weights, which impact the score assigned -to an image during evaluation, as shown in the following table. - -| Policy type | Points | -| -------------------------------------------------------------------------------------------- | ------ | -| [Severity-Based Vulnerability](/manuals/scout/policy/_index.md#severity-based-vulnerability) | 20 | -| [High-Profile Vulnerabilities](/manuals/scout/policy/_index.md#high-profile-vulnerabilities) | 20 | -| [Supply Chain Attestations](/manuals/scout/policy/_index.md#supply-chain-attestations) | 15 | -| [Approved Base Images](/manuals/scout/policy/_index.md#approved-base-images) | 15 | -| [Up-to-Date Base Images](/manuals/scout/policy/_index.md#up-to-date-base-images) | 10 | -| [SonarQube Quality Gates](/manuals/scout/policy/_index.md#sonarqube-quality-gates) \* | 10 | -| [Default Non-Root User](/manuals/scout/policy/_index.md#default-non-root-user) | 5 | -| [Compliant Licenses](/manuals/scout/policy/_index.md#compliant-licenses) | 5 | - -\* _This policy is not enabled by default and must be configured by the user._ - -### Evaluation - -Health scores are calculated for new images pushed to Docker Hub after the -feature is enabled. The health scores help you maintain high security standards -and ensure your applications are built on secure and reliable images. - -### Repository scores - -In addition to individual image scores (per tag or digest), each repository -receives a health score based on the latest pushed tag, providing an overall -view of the repository's security status. - -### Example - -For an image with a total possible score of 100 points: - -- If the image only deviates from one policy, worth 5 points, its score will be - 95 out of 100. Since this score is above the 90th percentile, the image - receives an A health score. -- If the image is non-compliant with more policies and scores 65 out of 100, it - receives a C health score, reflecting its lower compliance. - -## Improving your health score - -To improve the health score of an image, take steps to ensure that the image is -compliant with the Docker Scout recommended [policies](./_index.md). - -1. Go to the [Docker Scout Dashboard](https://scout.docker.com/). -2. Sign in using your Docker ID. -3. Go to [Repository settings](https://scout.docker.com/settings/repos) and - enable Docker Scout for your Docker Hub image repositories. -4. Analyze the [policy compliance](./_index.md) for your repositories, - and take actions to ensure your images are policy-compliant. - -Since policies are weighted differently, prioritize the policies with the -highest scores for a greater impact on your image's overall score. diff --git a/content/manuals/scout/policy/view.md b/content/manuals/scout/policy/view.md deleted file mode 100644 index bce0987eb9f1..000000000000 --- a/content/manuals/scout/policy/view.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: View Docker Scout policy status -description: | - The Docker Scout Dashboard and the `docker scout policy` command lets you - view policy status of images. -keywords: scout, policy, status, vulnerabilities, supply chain, cves, licenses ---- - -You can track policy status for your artifacts from the [Docker Scout -Dashboard](#dashboard), or using the [CLI](#cli). - -## Dashboard - -The **Overview** tab of the [Docker Scout Dashboard](https://scout.docker.com/) -displays a summary of recent changes in policy for your repositories. -This summary shows images that have seen the most change in their policy -evaluation between the most recent image and the previous image. - -![Policy overview](../images/policy-overview.webp) - -### Policy status per repository - -The **Images** tab shows the current policy status, and recent policy trend, -for all images in the selected environment. The **Policy status** column in the -list shows: - -- Number of fulfilled policies versus the total number of policies -- Recent policy trends - -![Policy status in the image list](../images/policy-image-list.webp) - -The policy trend, denoted by the directional arrows, indicates whether an image -is better, worse, or unchanged in terms of policy, compared to the previous -image in the same environment. - -- The green arrow pointing upwards shows the number of policies that got better - in the latest pushed image. -- The red arrow pointing downwards shows the number of policies that got worse - in the latest pushed image. -- The bidirectional gray arrow shows the number of policies that were unchanged - in the latest version of this image. - -If you select a repository, you can open the **Policy** tab for a detailed -description of the policy delta for the most recently analyzed image and its -predecessor. - -### Detailed results and remediation - -To view the full evaluation results for an image, navigate to the image tag in -the Docker Scout Dashboard and open the **Policy** tab. This shows a breakdown -for all policy violations for the current image. - -![Detailed Policy Evaluation results](../images/policy-detailed-results.webp) - -This view also provides recommendations on how to improve improve policy status -for violated policies. - -![Policy details in the tag view](../images/policy-tag-view.webp) - -For vulnerability-related policies, the policy details view displays the fix -version that removes the vulnerability, when a fix version is available. To fix -the issue, upgrade the package version to the fix version. - -For licensing-related policies, the list shows all packages whose license -doesn't meet the policy criteria. To fix the issue, find a way to remove the -dependency to the violating package, for example by looking for an alternative -package distributed under a more appropriate license. - -## CLI - -To view policy status for an image from the CLI, use the `docker scout policy` -command. - -```console -$ docker scout policy \ - --org dockerscoutpolicy \ - --platform linux/amd64 \ - dockerscoutpolicy/email-api-service:0.0.2 - - ✓ Pulled - ✓ Policy evaluation results found - - -​## Overview -​ -​ │ Analyzed Image -​─────────────┼────────────────────────────────────────────── -​ Target │ dockerscoutpolicy/email-api-service:0.0.2 -​ digest │ 17b1fde0329c -​ platform │ linux/amd64 -​ -​ -​## Policies -​ -​Policy status FAILED (2/8 policies met, 3 missing data) -​ -​ Status │ Policy │ Results -​─────────┼─────────────────────────────────────────────────────┼────────────────────────────── -​ ✓ │ No copyleft licenses │ 0 packages -​ ! │ Default non-root user │ -​ ! │ No fixable critical or high vulnerabilities │ 2C 1H 0M 0L -​ ✓ │ No high-profile vulnerabilities │ 0C 0H 0M 0L -​ ? │ No outdated base images │ No data -​ │ │ Learn more ↗ -​ ? │ SonarQube quality gates passed │ No data -​ │ │ Learn more ↗ -​ ! │ Supply chain attestations │ 2 deviations -​ ? │ No unapproved base images │ No data - -... -``` - -For more information about the command, refer to the [CLI -reference](/reference/cli/docker/scout/policy/). diff --git a/content/manuals/scout/quickstart.md b/content/manuals/scout/quickstart.md index 89ccd30cbdea..f473d07047f0 100644 --- a/content/manuals/scout/quickstart.md +++ b/content/manuals/scout/quickstart.md @@ -248,15 +248,9 @@ because the example image uses an old version `alpine` as a base image. Close the **Recommended fixes for base image** modal. In the policy listing, select **View fixes** button, next to the policy name for details about the violation, and recommendations on how to address it. -In this case, the recommended action is to enable -[Docker Scout's GitHub integration](./integrations/source-code-management/github.md), -which helps keep your base images up-to-date automatically. - -> [!TIP] -> -> You can't enable this integration for the demo app used in this guide. -> Feel free to push the code to a GitHub repository that you own, -> and try out the integration there! +In this case, the recommended action is to update the base image to a newer +version. You can use GitHub Dependabot with `package-ecosystem: "docker"` to +automate base image updates. ## Summary diff --git a/content/manuals/scout/release-notes/platform.md b/content/manuals/scout/release-notes/platform.md index 90c9ff8f1c03..81875349da95 100644 --- a/content/manuals/scout/release-notes/platform.md +++ b/content/manuals/scout/release-notes/platform.md @@ -15,6 +15,65 @@ issues, and bug fixes in Docker Scout releases. These release notes cover the Docker Scout platform, including the Dashboard. For CLI release notes, refer to [Docker Scout CLI release notes](./cli.md). +## Q2 2026 + +### 2026-09-01 + +The following Docker Scout features were retired: + +- Notifications: In-product and email notifications about newly disclosed CVEs. + Integrate `docker scout cves` or `docker scout policy` into your CI pipeline + to surface vulnerability and policy results without push notifications. +- Native Amazon ECR integration: ECR is still supported using + [`docker scout watch`](../integrations/registry.md) for continuous + polling, or by integrating Scout into your CI pipeline. +- Native Azure Container Registry integration: ACR is still supported using + the same options as ECR. +- Policies page in the Dashboard: The `docker scout policy` + command replaces this with more options for evaluating policies. You can run + evaluations locally, in CI, against custom Rego policies, or using OCI + bundles. See [Evaluate policies](../policy/local.md). +- SonarQube integration. + +### 2026-07-30 + +The following Docker Scout feature was retired: + +- Slack integration: Integrate `docker scout cves` or `docker scout policy` + into your CI pipeline to surface vulnerability and policy results without + push notifications. + +### 2026-07-01 + +The following Docker Scout features were retired: + +- Health scores and Scout Everywhere: Docker Hub and Docker Desktop no longer + display health scores or the always-on Scout experience. Use + `docker scout quickview` for a quick vulnerability and policy summary. This is + unrelated to the health score reported locally by `docker scout policy`, + `docker scout quickview`, and `docker scout compare`. See + [Health score](../policy/local.md#health-score). +- Sysdig integration: The Sysdig runtime environment integration has been removed. +- GitHub source code management integration: Migrate to GitHub Dependabot for + base-image updates and build with `--provenance=mode=max` for + image-to-source linkage. + +The following is deprecated and will be retired on July 30, 2026: + +- Slack integration: Vulnerability and policy compliance notifications to Slack + channels. + +The following are deprecated and will be retired on September 1, 2026: + +- Notifications: In-product and email notifications about newly disclosed CVEs. +- Amazon ECR integration: Automatically analyzed images pushed to ECR + registries. +- Azure Container Registry integration: Automatically analyzed images pushed + to ACR registries. +- Policies page in the Dashboard: Provided a visual interface in the Docker + Scout Dashboard for tracking policy compliance. +- SonarQube integration. + ## Q4 2024 New features and enhancements released in the fourth quarter of 2024. @@ -47,7 +106,7 @@ For more information, refer to [policy types](../policy/_index.md#policy-types). ### 2024-09-09 -This release changes how [health scores](/manuals/scout/policy/scores.md) are +This release changes how health scores are calculated in Docker Scout. The health score calculation now considers optional and custom policies that you have configured for your organization. @@ -61,7 +120,7 @@ calculation will be based on the out-of-the-box policies. ### 2024-08-13 This release changes the out-of-the-box policies to align with the policy -configurations used to evaluate Docker Scout [health scores](/manuals/scout/policy/scores.md). +configurations used to evaluate Docker Scout health scores. The default out-of-the-box policies are now: @@ -135,7 +194,7 @@ making the now-removed **All critical vulnerabilities** policy redundant. [General Availability](../../release-lifecycle.md#general-availability-ga). For more information and setup instructions, see -[Integrate Azure Container Registry](../integrations/registry/acr.md). +Integrate Azure Container Registry. ### 2024-01-23 @@ -168,11 +227,10 @@ more precise recommendations. For more information about the types of recommendations that Docker Scout can provide to help you improve policy compliance, see -[Remediation](../policy/remediation.md). +Use the Dashboard. For more information about how to authorize the Docker Scout GitHub app on your -source repositories, see -[Integrate Docker Scout with GitHub](../integrations/source-code-management/github.md). +source repositories, see Integrate Docker Scout with GitHub. ## Q4 2023 @@ -185,7 +243,7 @@ New features and enhancements released in the fourth quarter of 2023. [Early Access](../../release-lifecycle.md#early-access-ea). For more information and setup instructions, see -[Integrate Azure Container Registry](../integrations/registry/acr.md). +Integrate Azure Container Registry. ### 2023-12-06 @@ -203,7 +261,7 @@ Registry** (ACR) integration, which lets Docker Scout pull and analyze images in ACR repositories automatically. To learn more about the integration and how to get started, see -[Integrate Azure Container Registry](../integrations/registry/acr.md). +Integrate Azure Container Registry. ### 2023-11-21 @@ -216,7 +274,7 @@ policies for your organization include: - Customize the list of "high-profile vulnerabilities" - Add or remove software licenses to flag as "copyleft" -For more information, see [Configurable policies](../policy/configure.md). +For more information, see Configurable policies. ### 2023-11-10 @@ -247,8 +305,6 @@ Policy Evaluation is an early access feature that helps you ensure software integrity and track how your artifacts are doing over time. This release ships with four out-of-the-box policies, enabled by default for all organizations. -![Policy overview in Dashboard](../images/release-notes/policy-ea.webp) - - **Base images not up-to-date** evaluates whether the base images are out of date, and require updating. Up-to-date base images help you ensure that your environments are reliable and secure. @@ -276,8 +332,8 @@ metadata about the image contents, and not the container images themselves. The integration offers a straightforward process for adding additional repositories, activating Docker Scout for specific repositories, and removing -the integration if needed. To learn more, refer to the [Amazon ECR integration -documentation](../integrations/registry/ecr.md). +the integration if needed. To learn more, refer to the Amazon ECR integration +documentation. #### Sysdig integration @@ -289,8 +345,7 @@ used to run your production workloads. It also helps reduce monitoring noise, by automatically excluding vulnerabilities in programs that are never loaded into memory, using VEX documents. -For more information and getting started, see [Sysdig integration -documentation](../integrations/environment/sysdig.md). +For more information, see the [Scout platform release notes](#2026-07-01). #### JFrog Artifactory integration diff --git a/content/manuals/security/2fa/_index.md b/content/manuals/security/2fa/_index.md deleted file mode 100644 index 688c3449d800..000000000000 --- a/content/manuals/security/2fa/_index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Enable two-factor authentication for your Docker account -linkTitle: Two-factor authentication -description: Enable or disable two-factor authentication on your Docker account for enhanced security and account protection -keywords: two-factor authentication, 2FA, docker hub security, account security, TOTP, authenticator app, disable 2FA -weight: 20 -aliases: - - /docker-hub/2fa/ - - /security/2fa/disable-2fa/ - - /security/for-developers/2fa/ - - /security/for-developers/2fa/disable-2fa/ ---- - -Two-factor authentication (2FA) adds an essential security layer to your Docker account by requiring a unique security code in addition to your password when signing in. This prevents unauthorized access even if your password is compromised. - -When you turn on two-factor authentication, Docker provides a unique recovery code specific to your account. Store this code securely as it lets you recover your account if you lose access to your authenticator app. - -## Key benefits - -Two-factor authentication significantly improves your account security: - -- Protection against password breaches: Even if your password is stolen or leaked, attackers can't access your account without your second factor. -- Secure CLI access: Required for Docker CLI authentication when 2FA is turned on, ensuring automated tools use personal access tokens instead of passwords. -- Compliance requirements: Many organizations require 2FA for accessing development and production resources. -- Peace of mind: Know that your Docker repositories, images, and account settings are protected by industry-standard security practices. - -## Prerequisites - -Before turning on two-factor authentication, you need: - -- A smartphone or device with a Time-based One-time password (TOTP) authenticator app installed -- Access to your Docker account password - -## Enable two-factor authentication - -To turn on 2FA for your Docker account: - -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar and then from the drop-down menu, select **Account settings**. -1. Select **2FA**. -1. Enter your account password, then select **Confirm**. -1. Save your recovery code and store it somewhere safe. You can use your recovery code to recover your account in the event you lose access to your authenticator app. -1. Use a TOTP mobile app to scan the QR code or enter the text code. -1. Once you've linked your authenticator app, enter the six-digit code in the text-field. -1. Select **Enable 2FA**. - -Two-factor authentication is now active on your account. You'll need to enter a security code from your authenticator app each time you sign in. - -## Disable two-factor authentication - -> [!WARNING] -> -> Disabling two-factor authentication results in decreased security for your Docker account. - -1. Sign in to your [Docker account](https://app.docker.com/login). -2. Select your avatar and then from the drop-down menu, select **Account settings**. -3. Select **2FA**. -4. Enter your password, then select **Confirm**. -5. Select **Disable 2FA**. diff --git a/content/manuals/security/2fa/recover-hub-account.md b/content/manuals/security/2fa/recover-hub-account.md deleted file mode 100644 index 4535b6b77741..000000000000 --- a/content/manuals/security/2fa/recover-hub-account.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Recover your Docker account -description: Recover your Docker account and manage two-factor authentication recovery codes -keywords: account recovery, two-factor authentication, 2FA, recovery code, docker hub security -aliases: - - /docker-hub/2fa/recover-hub-account/ - - /security/for-developers/2fa/recover-hub-account/ - - /security/2fa/new-recovery-code/ -weight: 20 ---- - -This page explains how to recover your Docker account and manage recovery codes for two-factor authentication. - -## Generate a new recovery code - -If you lost your two-factor authentication recovery code but still have access to your Docker Hub account, you can generate a new recovery code. - -1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password. -1. Select your avatar and from the drop-down menu, select **Account settings**. -1. Select **2FA**. -1. Enter your password, then select **Confirm**. -1. Select **Generate new code**. - -This generates a new code. Select the visibility icon to view the code. Save your recovery code and store it somewhere safe. - -## Recover your account without access - -If you lost access to both your two-factor authentication application and your recovery code: - -1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password. -1. Select **I've lost my authentication device** and **I've lost my recovery code**. -1. Complete the [Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). - -You must enter the primary email address associated with your Docker ID in the Contact Support form for recovery instructions. diff --git a/content/manuals/security/_index.md b/content/manuals/security/_index.md index e8a3f9e8ad9c..126ff46aae10 100644 --- a/content/manuals/security/_index.md +++ b/content/manuals/security/_index.md @@ -1,66 +1,76 @@ --- -title: Security for developers +title: Secure Docker accounts and organizations linkTitle: Security -description: Learn about developer-level security features like 2FA and access tokens -keywords: docker, docker hub, docker desktop, security, developer security, 2FA, access tokens +description: >- + Secure Docker accounts, manage access, and control membership for + individuals and organizations in Docker Home. +keywords: docker, docker hub, security, account security, 2FA, access tokens, + SSO, OIDC, provisioning, roles, Docker Home weight: 40 +aliases: + - /security/for-developers/ params: sidebar: - group: Platform -grid_developers: -- title: Set up two-factor authentication - description: Add an extra layer of authentication to your Docker account. - link: /security/2fa/ - icon: device-phone-mobile -- title: Manage access tokens - description: Create personal access tokens as an alternative to your password. - icon: lock-closed - link: /security/access-tokens/ -- title: Static vulnerability scanning - description: Automatically run a point-in-time scan on your Docker images for vulnerabilities. - icon: magnifying-glass - link: /docker-hub/repos/manage/vulnerability-scanning/ -- title: Docker Engine security - description: Understand how to keep Docker Engine secure. - icon: shield-check - link: /engine/security/ -- title: Secrets in Docker Compose - description: Learn how to use secrets in Docker Compose. - icon: shield-exclamation - link: /compose/how-tos/use-secrets/ -grid_resources: -- title: Security FAQs - description: Explore common security FAQs. - icon: question-mark-circle - link: /faq/security/general/ -- title: Security best practices - description: Understand the steps you can take to improve the security of your container. - icon: squares-2x2 - link: /develop/security-best-practices/ -- title: Suppress CVEs with VEX - description: Learn how to suppress non-applicable or fixed vulnerabilities found in your images. - icon: chart-bar - link: /scout/guides/vex/ -- title: Docker Hardened Images - description: Learn how to use Docker Hardened Images to enhance your software supply security. - icon: lock-closed - link: /dhi/ + group: Accounts and admin +grid: + - title: Authentication + description: >- + Two-factor authentication, single sign-on, and OIDC connections. + icon: key + link: /security/authentication/ + - title: Access tokens + description: >- + Personal and organization access tokens for the Docker CLI and + automation. + icon: lock-closed + link: /security/access-tokens/ + - title: Provisioning + description: >- + Add users with SCIM, JIT, auto-provisioning, and domain management. + icon: arrow-path + link: /security/provisioning/ + - title: Roles and permissions + description: >- + Assign core or custom roles to control access in your organization. + icon: shield-check + link: /security/roles-and-permissions/ --- -Docker helps you protect your local environments, infrastructure, and networks -with its developer-level security features. +Security helps individual users and organization owners secure their +accounts, manage access, and control membership. You configure these +settings in [Docker Home](https://app.docker.com/). -Use tools like two-factor authentication (2FA), personal access tokens, and -Docker Scout to manage access and detect vulnerabilities early in your workflow. -You can also integrate secrets securely into your development stack using Docker Compose, -or enhance your software supply security with Docker Hardened Images. +## Individual accounts -Explore the following sections to learn more. +You sign in with your individual account. -## For developers +- [Two-factor authentication](/manuals/security/authentication/2fa/_index.md) + (2FA) adds a time-based one-time password (TOTP) from an authenticator + app to your password. +- A [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) + (PAT) authenticates the Docker CLI and tools without your password, and + is required for CLI sign-in when 2FA is on or single sign-on (SSO) is + enforced. -{{< grid items="grid_developers" >}} +## Organization accounts -## More resources +Organization and company owners set up how members sign in, add them to +the organization, configure automation, and control what members can do. -{{< grid items="grid_resources" >}} +- [Single sign-on](/manuals/security/authentication/single-sign-on/_index.md) + (SSO) federates sign-in through your identity provider, which can cover + one organization or every organization in a company. +- [Provisioning](/manuals/security/provisioning/_index.md) adds users with + System for Cross-domain Identity Management (SCIM), Just-in-Time (JIT) + provisioning, auto-provisioning, or domain matching. +- An [organization access token](/manuals/security/access-tokens/organization-access-tokens.md) + (OAT) stays with the organization when membership changes. +- [OIDC connections](/manuals/security/authentication/oidc-connections/_index.md) + use OpenID Connect to authenticate GitHub Actions with short-lived + tokens, as an alternative to a long-lived OAT. +- [Roles and permissions](/manuals/security/roles-and-permissions/_index.md) + control what members can do after they join. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/access-tokens.md b/content/manuals/security/access-tokens.md deleted file mode 100644 index 380b93383dd6..000000000000 --- a/content/manuals/security/access-tokens.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Personal access tokens -linkTitle: Personal access tokens -description: Create and manage personal Docker access tokens for secure CLI authentication and automation -keywords: personal access tokens, PAT, docker cli authentication, docker hub security, programmatic access -weight: 10 -aliases: - - /docker-hub/access-tokens/ - - /security/for-developers/access-tokens/ ---- - -Personal access tokens (PATs) provide a secure alternative to passwords for Docker CLI authentication. Use PATs to authenticate automated systems, CI/CD pipelines, and development tools without exposing your Docker Hub password. - -## Key benefits - -PATs offer significant security advantages over password authentication: - -- Enhanced security: Investigate token usage, disable suspicious tokens, and prevent administrative actions that could compromise your account if your system is compromised. -- Better automation: Issue multiple tokens for different integrations, each with specific permissions, and revoke them independently when no longer needed. -- Two-factor authentication compatibility: Required when you have two-factor authentication turned on, providing secure CLI access without bypassing 2FA protection. -- Usage tracking: Monitor when and how tokens are used to identify potential security issues or unused automation. - -## Who should use personal access tokens? - -Use PATs for these common scenarios: - -- Development workflows: Authenticate Docker CLI during local development -- CI/CD pipelines: Automate image builds and deployments in continuous integration systems -- Automation scripts: Push and pull images in automated deployment or backup scripts -- Development tools: Integrate Docker Hub access with IDEs, container management tools, or monitoring systems -- Two-factor authentication: Required for CLI access when 2FA is turned on - -> [!NOTE] -> -> For organization-wide automation, consider [organization access tokens](/manuals/enterprise/security/access-tokens.md) which aren't tied to individual user accounts. - -## Create a personal access token - -> [!IMPORTANT] -> -> Treat access tokens like passwords and keep them secure. Store tokens in credential managers and never commit them to source code repositories. - -To create a personal access token: - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**. -1. Select **Personal access tokens**. -1. Select **Generate new token**. -1. Configure your token: - - **Description:** Use a descriptive name that indicates the token's purpose - - **Expiration date:** Set an expiration date based on your security policies - - **Access permissions:** **Read**, **Write**, or **Delete**. -1. Select **Generate**. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen. - -## Use personal access tokens - -Sign in to the Docker CLI using your personal access token: - -```console -$ docker login --username -Password: [paste your PAT here] -``` - -When prompted for a password, enter your personal access token instead of your Docker Hub password. - -## Modify personal access tokens - -> [!NOTE] -> -> You can't edit the expiration date on an existing personal access token. You must create a new PAT if you need to set a new expiration date. - -You can rename, activate, deactivate, or delete a token as needed. You can manage your tokens in your account settings. - -1. Sign in to [Docker Home](https://app.docker.com/login). -1. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**. -1. Select **Personal access tokens**. - - This page shows an overview of all your tokens, and lists if the token was generated manually or if it was - [auto-generated](#auto-generated-tokens). You can also view the scope of the - tokens, which tokens are activate and inactive, when they were created, when - they were last used, and their expiration date. -1. Select the actions menu on the far right of a token row, then select **Deactivate** or **Activate**, **Edit**, or **Delete** to modify the token. -1. After editing the token, select **Save token**. - -## Auto-generated tokens - -Docker Desktop automatically creates authentication tokens when you sign in, with these characteristics: - -- Automatic creation: Generated when you sign in to Docker Desktop -- Full permissions: Include Read, Write, and Delete access -- Session-based: Automatically removed when Docker Desktop session expires -- Account limits: Up to 5 auto-generated tokens per account -- Automatic cleanup: Older tokens are deleted when new ones are created - -You can manually delete auto-generated tokens if needed, but they'll be recreated when you use Docker Desktop. - -## Fair use policy - -When using personal access tokens, be aware that excessive token creation may result in throttling or additional charges. Docker reserves the right to impose restrictions on accounts with excessive PAT usage to ensure fair resource allocation and maintain service quality. - -Best practices for fair use include: - -- Reuse tokens across similar use cases instead of creating many single-purpose tokens -- Delete unused tokens regularly -- Use [organization access tokens](/manuals/enterprise/security/access-tokens.md) for organization-wide automation -- Monitor token usage to identify optimization opportunities diff --git a/content/manuals/security/access-tokens/_index.md b/content/manuals/security/access-tokens/_index.md new file mode 100644 index 000000000000..52517ec8e064 --- /dev/null +++ b/content/manuals/security/access-tokens/_index.md @@ -0,0 +1,85 @@ +--- +title: Access tokens +linkTitle: Access tokens +description: >- + Choose a personal or organization access token to authenticate to + Docker Hub and Cloud Sandboxes. +keywords: >- + access tokens, personal access tokens, organization access tokens, + PAT, OAT, Docker Hub, Docker security, Cloud Sandboxes, + repository permissions, sandbox:use +weight: 10 +grid: + - title: Personal access tokens + description: >- + Authenticate the Docker CLI and tools with a token tied to your + account. + icon: lock-closed + link: /security/access-tokens/personal-access-tokens/ + - title: Organization access tokens + description: Grant org-owned Hub access to CI/CD and other automation. + icon: building-office-2 + link: /security/access-tokens/organization-access-tokens/ + - title: Reference + description: Look up PAT permissions, OAT scopes, and Hub API support. + icon: list-bullet + link: /security/access-tokens/reference/ +--- + +Access tokens authenticate to Docker Hub in place of a password. Docker +Hub offers two types: personal access tokens (PATs), tied to your +account, and organization access tokens (OATs), owned by an +organization. Both work with `docker login` and in automation, and you +can deactivate or delete a token at any time without changing a +password. + +## Choose a token type + +Pick a PAT for work that runs as you, or an OAT for organization-owned +automation. + +## Personal access tokens (PATs) {#pats} + +A PAT has +[one repository permission](/manuals/security/access-tokens/reference.md#personal-access-token-permissions) +for every repository the account can access. A PAT can also grant +[Cloud Sandboxes access](/manuals/security/access-tokens/reference.md#cloud-sandboxes-access), +which is a separate setting on the token. + +Use a PAT for Docker Desktop, for environments governed by +[Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md), +and for other tools that run as you. A PAT is also required to sign in +to the CLI when two-factor authentication (2FA) is turned on or single +sign-on (SSO) is enforced, because the CLI doesn't accept your password +in those cases. + +## Organization access tokens (OATs) {#oats} + +Use an OAT for production systems that pull images during deployment, +monitoring or backup tools that check repository status or pull images, +third-party services that integrate with your repositories, and scripts +that call the +[Docker Hub API](/manuals/security/access-tokens/reference.md#docker-hub-api). +OATs don't work with Docker Desktop or Image Access Management. + +An OAT can be limited to specific repositories and operations, and it +has its own Docker Hub usage limits, separate from individual accounts. +To see scopes, see +[Access token reference](/manuals/security/access-tokens/reference.md). + +## OIDC connections + +If your automation runs in GitHub Actions, you don't need to store a token. +An [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) +lets a workflow exchange GitHub's short-lived identity token for Docker +access on each run, so there is no long-lived credential to rotate, +scope, or leak. Organization owners set up OIDC connections, and they +require a Docker Team or Docker Business subscription. + +Use an OAT instead when the automation runs outside GitHub Actions, or +when you need a credential that works with `docker login` from any +system. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/access-tokens/organization-access-tokens.md b/content/manuals/security/access-tokens/organization-access-tokens.md new file mode 100644 index 000000000000..210fae59b463 --- /dev/null +++ b/content/manuals/security/access-tokens/organization-access-tokens.md @@ -0,0 +1,147 @@ +--- +title: Create and manage organization access tokens +linkTitle: Organization access tokens +description: >- + Create an organization access token, choose its repository and + organization scopes, and use it in CI/CD and the Docker Hub API. +keywords: >- + organization access token, OAT, Docker Hub, CI/CD authentication, + docker login, token scopes, repository permissions, Docker Hub API, + automation, Docker Team, Docker Business +weight: 20 +aliases: + - /security/for-admins/access-tokens/ + - /enterprise/security/access-tokens/ +--- + +{{< summary-bar feature_name="OATs" >}} + +An organization access token (OAT) lets automated systems sign in to +Docker Hub as your organization instead of as a person. Use an OAT for +CI/CD pipelines, deployment jobs, and other automation that must keep +working when people join or leave the organization. + +Unlike a personal access token (PAT), an OAT belongs to the +organization. Any organization owner can see, edit, deactivate, or +delete it. Each token has its own scopes, so it can only reach the +repositories and organization settings you choose. + +> [!WARNING] +> +> OATs don't work with Docker Desktop or Image Access Management. For +> those features, use +> [PATs](/manuals/security/access-tokens/personal-access-tokens.md) instead. + +## Best practices + +- Set an expiration date and rotate tokens on a schedule +- Grant only the repositories and scopes each job needs +- Review the **Last used** column to find unused or suspicious tokens +- Store tokens in a credential manager, never in plain text or source + code +- Deactivate or delete a token as soon as it's compromised or no longer + needed + +## Prerequisites + +To create and manage OATs, you need: + +- A Docker Team or Docker Business subscription +- One of these roles in the organization: + - Organization owner + - Company owner, for organizations that belong to a company + - A [custom role](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md) + that includes the **Manage organization access tokens** permission + +## Create an organization access token + +> [!IMPORTANT] +> +> Treat access tokens like passwords and keep them secure. Store tokens +> in a credential manager and never commit them to source code. + +To create an OAT: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Identity & auth**, then **Access tokens**. +1. Select **Generate access token**. +1. Configure the token: + - **Label:** A name that describes what the token is for. This field + is required. + - **Access token description:** Optional. Up to 200 characters. + - **Expiration date:** Select **30 days**, **90 days**, or + **Custom**. With **Custom**, choose a date and time up to one year + from today. The default, **None**, creates a token that doesn't + expire. You can't change the expiration date after you create the + token. +1. In **Resources**, expand **Repository** to choose which repositories + the token can reach: + - Optional. Select **Read public repositories** to let the token pull + from any public repository. + - Select **Add repository**, then choose a repository or + **All `` repositories** from the drop-down. + - Select one or more scopes for that repository. See + [Repository scopes](/manuals/security/access-tokens/reference.md#repository-scopes). + - Repeat for up to 50 repositories. Each repository has its own + scopes. +1. Optional. Expand **Organization** and select the organization-level + scopes the token needs, such as reading members or creating + repositories. See + [Organization scopes](/manuals/security/access-tokens/reference.md#organization-scopes). +1. Optional. Expand **Docker Build Cloud** or **Docker Governance** to + grant access to those products. See + [Product scopes](/manuals/security/access-tokens/reference.md#product-scopes). +1. Select **Generate token**. Copy the token and save it. Docker shows + the token once and doesn't store it. You can't retrieve it after you + leave the page. + +## Sign in + +Run `docker login` with your organization name as the username. When +the CLI asks for a password, paste the OAT. + +```console +$ docker login --username +Password: [paste your OAT here] +``` + +## Update, deactivate, or delete + +You can rename a token, change its description or scopes, deactivate +it, activate it again, or delete it. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Identity & auth**, then **Access tokens**. + + The list shows each token's label, status, who created it, when it + was created, when it was last used, and when it expires. + +1. Select the actions menu at the end of a token row, then select + **Deactivate**, **Activate**, **Edit**, or **Delete**. + + A deactivated token stops working until you activate it again. + Expired tokens can only be deleted. Deleting a token is permanent. + +1. If you selected **Edit**, change the label, description, or + resources, then select **Update token**. + +## Token limits + +Each organization can have a limited number of tokens: + +- Docker Team: Up to 10 tokens +- Docker Business: Up to 100 tokens + +Expired and deactivated tokens count toward the limit until you delete +them. When you reach the limit, the **Generate access token** button is +disabled until you delete a token. + +## Next steps + +- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md) +- [Look up scopes and Docker Hub API support](/manuals/security/access-tokens/reference.md) +- [Create a PAT](/manuals/security/access-tokens/personal-access-tokens.md) +- [Set up OIDC connections for GitHub Actions](/manuals/security/authentication/oidc-connections/_index.md) +- [Review custom role permissions](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md) diff --git a/content/manuals/security/access-tokens/personal-access-tokens.md b/content/manuals/security/access-tokens/personal-access-tokens.md new file mode 100644 index 000000000000..d9ca7739f3b1 --- /dev/null +++ b/content/manuals/security/access-tokens/personal-access-tokens.md @@ -0,0 +1,153 @@ +--- +title: Create and manage personal access tokens +linkTitle: Personal access tokens +description: >- + Create a personal access token, set repository permissions and Cloud + Sandboxes access, set expiration, and sign in to the Docker CLI. +keywords: >- + personal access token, PAT, Docker Hub, docker login, + CLI authentication, token permissions, repository permissions, + token expiration, two-factor authentication, SSO, Cloud Sandboxes, + sandbox:use, Allow Cloud Sandboxes access, No repository access +weight: 10 +aliases: + - /docker-hub/access-tokens/ + - /security/personal-access-tokens/ + - /security/for-developers/access-tokens/ +--- + +{{< summary-bar feature_name="PATs" >}} + +A personal access token (PAT) lets you sign in to Docker Hub without +your password. You can create several tokens and revoke one without +changing your password. From Docker Home, you can view the token list, +which shows when each token was last used. + +Treat PATs like passwords and keep them secure. Store tokens in a +credential manager and never commit them to source code. Before you +create a PAT, you must verify your email address. + +> [!TIP] +> +> For organization-wide automation, consider +> [organization access tokens (OATs)](/manuals/security/access-tokens/organization-access-tokens.md), +> which aren't tied to individual user accounts. + +## Create a personal access token {#create} + +When you create a PAT, you choose one repository permission and whether +the token can use Cloud Sandboxes. You can combine these to fit the +task. For example, a token can use Cloud Sandboxes with no repository +access, or it can push images and use Cloud Sandboxes. + +To create a PAT: + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Select your avatar in the top-right corner, then select + **Account settings**. +1. Select **Personal access tokens**. +1. Select **Generate new token**. +1. Configure your token: + - **Access token description:** Enter a name for the token, up to + 100 characters. This field is required. + - **Expiration date:** Optional. The default is **None**, which + creates a token that doesn't expire. + - Select **30 days**, **90 days**, or **Custom**. + - With **Custom**, choose a date and hour up to one year from + today. + - **Access permissions:** Set a repository permission and, if you + need it, Cloud Sandboxes access. Select at least + [one permission](/manuals/security/access-tokens/reference.md#personal-access-token-permissions). + - **Repository permissions:** The default is **Repo Public + Read-only**. + - Select one level. + - Select **No repository access** when the token should not + access repositories. + - **Allow Cloud Sandboxes access:** Select this to let the token + create and use Cloud Sandboxes. You can add it to any + repository permission, or use it with **No repository + access**. +1. Select **Generate**. Copy the token and save it. Docker shows the + token once and doesn't store it. You can't retrieve it after you + leave the page. + +## Sign in with a personal access token {#sign-in} + +Run `docker login` with your Docker ID. When the CLI asks for a +password, paste the PAT. + +```console +$ docker login --username +Password: [paste your PAT here] +``` + +If sign-in fails with `Incorrect authentication credentials`, see +[Why does sign-in fail with "Incorrect authentication credentials"?](/manuals/faqs/accounts.md#why-does-sign-in-fail-with-incorrect-authentication-credentials). + +## Update or delete a personal access token {#update-or-delete} + +You can rename a token, change its permissions, deactivate it, activate +it again, or delete it. You can't edit the expiration date on an +existing PAT. Create a new token if you need a different expiration +date. + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Select your avatar in the top-right corner, then select + **Account settings**. +1. Select **Personal access tokens**. + + The list shows each token's description, scope, and status + (**Active**, **Inactive**, or **Revoked**). It also shows whether + the token is **Manual** or + [**Auto-generated**](#auto-generated-tokens), when it was created, + when it was last used, and when it expires. + +1. Select the actions menu on the far right of a token row, then select + **Deactivate**, **Activate**, **Edit**, or **Delete**. + + A deactivated token stops working until you activate it again. + Expired and revoked tokens can only be deleted. + +1. If you selected **Edit**, change the **Access token description** or + **Access permissions**, then select **Save token**. + +## Auto-generated tokens + +Signing in to Docker Desktop creates a PAT for CLI +authentication. These tokens show **Auto-generated** in the **Source** +column. A token with no description is listed as "Generated by Docker +Desktop for CLI usage". + +You can have up to five auto-generated tokens on your account. When +Docker Desktop creates another one, the least recently used +auto-generated token is deleted. A token that has never been used is +ranked by when it was created. Tokens you create yourself are not +deleted. + +You can deactivate or delete an auto-generated token the same way as +any other token. + +## Fair use policy + +When using PATs, be aware that excessive token +creation may result in throttling or additional charges. Docker +reserves the right to impose restrictions on accounts with excessive +PAT usage to ensure fair resource allocation and maintain service +quality. + +Best practices for fair use include: + +- Reuse tokens across similar use cases instead of creating many + single-purpose tokens +- Delete unused tokens regularly +- Use [OATs](/manuals/security/access-tokens/organization-access-tokens.md) + for organization-wide automation +- Monitor token usage to identify optimization opportunities + +## Next steps + +- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md) +- [Look up PAT permissions](/manuals/security/access-tokens/reference.md#personal-access-token-permissions) +- [Authenticate to Cloud Sandboxes](/manuals/ai/sandboxes-api/authentication.md) +- [Create an OAT](/manuals/security/access-tokens/organization-access-tokens.md) +- [Turn on two-factor authentication](/manuals/security/authentication/2fa/_index.md) diff --git a/content/manuals/security/access-tokens/reference.md b/content/manuals/security/access-tokens/reference.md new file mode 100644 index 000000000000..2d9520a57c01 --- /dev/null +++ b/content/manuals/security/access-tokens/reference.md @@ -0,0 +1,210 @@ +--- +title: Access token reference +linkTitle: Reference +description: >- + Personal access token permissions, Cloud Sandboxes access, + organization access token scopes, and the Docker Hub API endpoints + an organization access token can call. +keywords: >- + access token reference, personal access token permissions, + repository permissions, organization access token scopes, + Docker Hub API, OAT, PAT, Cloud Sandboxes, sandbox:use, + Allow Cloud Sandboxes access, No repository access +weight: 30 +--- + +Look up what an access token is allowed to do. You choose a permission +or a set of scopes when you create the token. + +## Personal access token permissions + +A personal access token (PAT) has two separate access settings: +repository permissions and Cloud Sandboxes access. You set both when +you +[create the token](/manuals/security/access-tokens/personal-access-tokens.md#create). +Select at least one permission. + +### Repository permissions + +The repository permission applies to every repository your account can +access. You can't limit a token to a single repository. Select **No +repository access** when the token should not access repositories. + +- **Repo Public Read-only:** View, search, and pull images from public + repositories. This is the default. +- **Repo Read-only:** View, search, and pull images from public + repositories and from private repositories you have access to. +- **Repo Read & Write:** Everything in **Repo Read-only**, plus push + images to any repository your account manages. +- **Repo Read, Write, Delete:** Everything in **Repo Read & Write**, + plus delete images and manage your repositories. + +Choose the lowest repository permission that covers what the token +needs to do. For example, a CI job that only pulls a private base +image needs **Repo Read-only**. You can change PAT permissions at any +time if the PAT is active or inactive, but not expired. + +### Cloud Sandboxes access + +Cloud Sandboxes access is separate from the repository permission. + +- **Allow Cloud Sandboxes access:** Select this in Docker Home to let + the token create and use Docker Cloud Sandboxes. You can add it to + any repository permission in the list, or use it with **No + repository access**. +- `sandbox:use`: The scope a PAT needs to authenticate to Cloud + Sandboxes. Selecting **Allow Cloud Sandboxes access** adds this + scope to the token. See + [Cloud Sandboxes authentication](/manuals/ai/sandboxes-api/authentication.md). + +## Organization access token scopes + +Scopes control what an organization access token (OAT) can do. You choose +them when you +[create](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token) +or +[edit](/manuals/security/access-tokens/organization-access-tokens.md#update-deactivate-or-delete) +the token. In Docker +Home, each scope shows its name and a short description while the value +in the table is what the token carries. You can change OAT scopes at any +time if the OAT is active or inactive, but not expired. + +Within a related set of operations, selecting a more capable scope +also grants the less capable ones. For example: + +- **Image Delete** includes **Image Push** +- **Image Push** includes **Image Pull** + +If you select **Image Delete**, you don't need to select the other two. +The Grants column notes each inclusion. + +### Repository scopes + +Repository scopes apply to each repository you add, or to all +repositories in the organization if you select +**All `` repositories**. + +| Scope | Value | Grants | +| --- | --- | --- | +| Image Pull | `scope-image-pull` | Pull images | +| Image Push | `scope-image-push` | Push images. Includes Image Pull | +| Image Delete | `scope-image-delete` | Delete images and tags through registry endpoints. Includes Image Push | +| Repository Read | `scope-repository-read` | Read repository metadata, the Dockerfile, and stars | +| Repository Edit | `scope-repository-edit` | Edit privacy, categories, Dockerfile, description, and stars. Includes Repository Read | +| Repository Admin | `scope-repository-admin` | Delete the repository. Includes Repository Edit | +| Tag Read | `scope-tag-read` | List and read tags, image lists, attestations, and compose files | +| Tag Admin | `scope-tag-admin` | Delete tags. Includes Tag Read | +| Webhook Read | `scope-webhook-read` | List webhook pipelines and delivery history | +| Webhook Edit | `scope-webhook-edit` | Create webhook pipelines. Includes Webhook Read | +| Webhook Admin | `scope-webhook-admin` | Delete webhook pipelines. Includes Webhook Edit | +| Repository Group Read | `scope-repo-group-read` | List and read repository group assignments | +| Repository Group Edit | `scope-repo-group-edit` | Create and update repository group assignments. Includes Repository Group Read | +| Repository Group Admin | `scope-repo-group-admin` | Delete repository group assignments. Includes Repository Group Edit | +| Repository Settings Admin | `scope-repository-settings-admin` | Configure immutable tag rules | + +### Organization scopes + +Organization scopes apply to the whole organization. + +| Scope | Value | Grants | +| --- | --- | --- | +| Member Read | `scope-member-read` | Read organization members | +| Member Edit | `scope-member-edit` | Edit organization members. Includes Member Read | +| Invite Read | `scope-invite-read` | Read invitations | +| Invite Edit | `scope-invite-edit` | Edit invitations. Includes Invite Read | +| Group Read | `scope-group-read` | Read the organization's groups (teams) | +| Group Edit | `scope-group-edit` | Edit the organization's groups (teams). Includes Group Read | +| Audit Log Read | `scope-activity-read` | Read the organization's activity logs | +| SIEM Credentials Read | `scope-siem_credentials-read` | Read SIEM destination settings, including credentials | +| Registry Access Management Read | `scope-ram-read` | Read Registry Access Management settings | +| Registry Access Management Edit | `scope-ram-write` | Edit Registry Access Management settings. Includes Registry Access Management Read | +| Report Read | `scope-report-read` | Download organization usage reports | +| Repository Create | `scope-repository-create` | Create repositories in the organization namespace | +| Repository List | `scope-repository-list` | List all repositories in the namespace, including private ones | +| Registry Usage Read | `scope-registry-usage-read` | Read namespace-level registry usage metrics | + +Creating a repository requires the organization-level **Repository +Create** scope. No repository scope grants it, not even +**Repository Admin** on an existing repository. + +### Product scopes + +These sections appear alongside **Repository** and **Organization** in +the token's resources. + +| Section | Scope | Value | Grants | +| --- | --- | --- | --- | +| Docker Build Cloud | Cloud Connect | `scope-cloud-connect` | Connect to, build with, and run on Docker Build Cloud | +| Docker Governance | Audit Events Read | `scope-audit_events-read` | Read governance audit events | +| Docker Governance | Governance Policy Read | `scope-governance-policy-read` | Read governance policies | +| Docker Governance | Governance Policy Write | `scope-governance-policy-write` | Write governance policies. Includes Governance Policy Read | + +## Docker Hub API + +An OAT can authenticate most Docker Hub API endpoints under +`/v2/namespaces/{namespace}/repositories/`. First +[create an OAT](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token), +then exchange it for a short-lived bearer token with the +[Create access token](/reference/api/hub/latest/operations/AuthCreateAccessToken/) +API. Use your organization name as the identifier and the OAT as the +secret: + +```console +$ TOKEN=$(curl -s -X POST "https://hub.docker.com/v2/auth/token" \ + -H "Content-Type: application/json" \ + -d '{"identifier": "", "secret": ""}' \ + | jq -r .access_token) +``` + +Pass the bearer token in the `Authorization` header: + +```console +$ curl -s -H "Authorization: Bearer $TOKEN" \ + "https://hub.docker.com/v2/namespaces//repositories" +``` + +### Supported endpoints + +The following endpoint groups accept OAT authentication: + +- Repositories: list, create, get, update, and delete +- Tags: list, get, and delete; get tag images, attestations, and compose + files +- Dockerfile: get and update a repository's linked Dockerfile +- Repository groups: list, get, create, update, and delete assignments +- Stars: list, count, add, and remove +- Immutable tags: update and verify policies +- Repository categories, privacy, and webhook pipeline settings +- Namespace metrics + +### Listing behavior + +`GET /v2/namespaces/{namespace}/repositories` filters results by the +token's scopes: + +- With **Repository List** (`scope-repository-list`), the response + includes every repository, including private ones. +- Without it, the response includes only public repositories. + +The filtering is silent. The response is a normal `200` with no +indication that private repositories were left out. + +### Unsupported legacy endpoints + +OATs only work with the namespace-scoped routes described above. The +following legacy paths reject every OAT, regardless of its scopes, with +`403 token issued from organization access token is not allowed`. Use +the replacement endpoint instead: + +- `GET /v2/repositories/{namespace}/{repository}`: use + [Get repository](/reference/api/hub/latest/operations/GetRepository/) +- `GET /v2/repositories/{namespace}`: use + [List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/) +- `GET /v2/users/{username}/repositories`: use + [List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/) + +## Next steps + +- [Create a PAT](/manuals/security/access-tokens/personal-access-tokens.md#create) +- [Create an OAT](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token) +- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md new file mode 100644 index 000000000000..4f107547d2ec --- /dev/null +++ b/content/manuals/security/authentication/2fa/_index.md @@ -0,0 +1,70 @@ +--- +title: Two-factor authentication for your individual Docker account +linkTitle: Two-factor authentication +description: >- + Learn how two-factor authentication protects a Docker account, when Docker + asks for the code, and what the recovery code does. +keywords: two-factor authentication, 2FA, individual Docker account, TOTP, + authenticator app, authentication code, recovery code, personal access + token, docker login, Account settings, Docker Hub, account security +weight: 20 +aliases: + - /docker-hub/2fa/ + - /security/for-developers/2fa/ + - /security/2fa/ +grid: + - title: Turn 2FA on or off + description: >- + Set up an authenticator app, save the recovery code, or turn 2FA off. + icon: device-phone-mobile + link: /security/authentication/2fa/manage/ + - title: Recover your account + description: >- + Sign in with a recovery code, generate a new one, or contact Support. + icon: key + link: /security/authentication/2fa/recover-hub-account/ +--- + +{{< summary-bar feature_name="2FA" >}} + +Two-factor authentication (2FA) adds a code from an authenticator app to +your password when you sign in to your Docker account. Someone who knows +your password still needs the code from your device to sign in. + +> [!TIP] +> +> Organization and company settings do not include 2FA. To control how +> members sign in across an organization, use +> [single sign-on](/manuals/security/authentication/single-sign-on/_index.md). + +## How two-factor authentication works + +When you turn on 2FA, you pair a time-based one-time password (TOTP) +authenticator app with your account by scanning a QR code or entering a +text code. Any authenticator app that supports TOTP works. Docker keeps +one authenticator per account. + +After repeated wrong codes, Docker returns `Too many failed login +attempts` and blocks further attempts for a short time. + +## When Docker asks for the code + +| Sign-in | What Docker asks for | +| --- | --- | +| Browser sign-in to Docker Home or Docker Hub | Your password, then the code from your authenticator app | +| `docker login` with no username | The same browser sign-in, if the browser is not already signed in | +| `docker login -u`, scripts, and CI | A [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) in the password prompt. Password sign-in from the CLI is not supported when 2FA is on | + +## Recovery code + +Docker gives you one recovery code when you turn on 2FA. The code signs +you in if you lose your authenticator app, so copy, download, or print it +and store it somewhere safe. + +Docker emails the verified address on your account when you turn 2FA on +or off, when a recovery code is generated, and when a recovery code is +used to sign in. The email does not contain the code. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/authentication/2fa/manage.md b/content/manuals/security/authentication/2fa/manage.md new file mode 100644 index 000000000000..3284b09900cc --- /dev/null +++ b/content/manuals/security/authentication/2fa/manage.md @@ -0,0 +1,85 @@ +--- +title: Manage two-factor authentication for your Docker account +linkTitle: Manage +description: >- + Turn on two-factor authentication for your Docker account, save the + recovery code, move 2FA to a new device, or turn 2FA off. +keywords: enable 2FA, disable 2FA, turn on 2FA, turn off 2FA, two-factor + authentication, Docker account, TOTP, authenticator app, QR code, + recovery code, new device, personal access token, Docker Hub +weight: 10 +aliases: + - /security/2fa/disable-2fa/ + - /security/for-developers/2fa/disable-2fa/ +--- + +{{< summary-bar feature_name="2FA" >}} + +Turn two-factor authentication (2FA) on or off for your Docker account +in **Account settings**. For how 2FA works, when Docker asks for the +code, and what the recovery code does, see +[Two-factor authentication][overview]. + +## Prerequisites + +Before you turn on 2FA, you need: + +- A time-based one-time password (TOTP) authenticator app on your phone or + another device +- Your Docker account password +- A verified email address on your account + +## Enable two-factor authentication + +To turn on 2FA for your Docker account: + +1. Sign in to your [Docker account](https://app.docker.com/login). +1. Select your avatar in the top-right corner, then select **Account + settings**. +1. Select **2FA**. +1. Enter your account password, then select **Confirm**. +1. Save your recovery code. Select **Copy**, or open the menu next to + **Copy** and select **Download** or **Print**. +1. Open your authenticator app. Scan the code on the **QR Code** tab, or + enter the code from the **Text Code** tab. +1. Enter the six-digit code from your authenticator app in + **Authentication code**. +1. Select **Enable 2FA**. + +Two-factor authentication is on. When you sign in with your password, +Docker asks for a code from your authenticator app. Docker also emails +you a reminder to save your recovery code. + +## Disable two-factor authentication + +> [!WARNING] +> +> Turning off 2FA leaves your account protected by your password alone. + +1. Sign in to your [Docker account](https://app.docker.com/login). +1. Select your avatar in the top-right corner, then select **Account + settings**. +1. Select **2FA**. +1. Enter your password, then select **Confirm**. +1. Select **Disable 2FA**. + +Two-factor authentication is off. Docker emails you to confirm the +change. + +## Move 2FA to a new device + +To move 2FA to a new phone or device, +[turn 2FA off](#disable-two-factor-authentication), then +[turn it on again](#enable-two-factor-authentication) from the new +device. + +## Next steps + +- [Recover your account][recover] if you lose your authenticator app or + recovery code. +- Create a [personal access token][pat] to sign in from the Docker CLI, + scripts, and CI. + +[overview]: /manuals/security/authentication/2fa/_index.md +[pat]: /manuals/security/access-tokens/personal-access-tokens.md +[recover]: /manuals/security/authentication/2fa/recover-hub-account.md diff --git a/content/manuals/security/authentication/2fa/recover-hub-account.md b/content/manuals/security/authentication/2fa/recover-hub-account.md new file mode 100644 index 000000000000..240cc9105364 --- /dev/null +++ b/content/manuals/security/authentication/2fa/recover-hub-account.md @@ -0,0 +1,74 @@ +--- +title: Recover your Docker account and two-factor recovery code +linkTitle: Recover your account +description: >- + Sign in with a recovery code, generate a new recovery code, or contact + Support when you lose your authenticator app. +keywords: account recovery, two-factor authentication, 2FA, recovery code, + Lost Authentication Device, lost authenticator app, 2FA lockout, Docker + account, Generate new code, Docker Support +aliases: + - /docker-hub/2fa/recover-hub-account/ + - /security/for-developers/2fa/recover-hub-account/ + - /security/2fa/new-recovery-code/ + - /security/2fa/recover-hub-account/ +weight: 20 +--- + +{{< summary-bar feature_name="2FA" >}} + +Get back into your Docker account when you lose your authenticator app, +your recovery code, or both. Docker asks for your password before it +shows or replaces the recovery code. + +> [!IMPORTANT] +> +> The recovery code works once. Using it on the **Lost Authentication +> Device** page signs you in, turns 2FA off, and deletes the code. Turn +> 2FA on again from your new device as soon as you're signed in. + +## Generate a new recovery code + +If you lost your recovery code and can still sign in, generate a new one. +The new code replaces the previous code. + +1. Sign in to your [Docker account](https://app.docker.com/login). Enter + your password, then the code from your authenticator app. +1. Select your avatar in the top-right corner, then select **Account + settings**. +1. Select **2FA**. +1. Enter your password, then select **Confirm**. +1. Select **Generate new code**. + +Select the visibility icon to view the new code. Then select **Copy**, +**Download**, or **Print**, and store the code somewhere safe. + +## Sign in with your recovery code + +If you lost your authenticator app and still have your recovery code, use +the code to sign in. + +1. Sign in to your [Docker account](https://app.docker.com/login) with your + username and password. +1. On the **Two-Factor Authentication** page, select **I've lost my + authentication device**. +1. Enter your recovery code, then select **Verify**. + +You're signed in and 2FA is off. To protect your account again, follow +[Turn on 2FA][enable]. + +## Contact Docker Support + +If you lost both your authenticator app and your recovery code, open the +[Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). +The subject and description already describe a 2FA lockout. Enter the +email address on your Docker account, then follow the instructions from +Docker Support. + +## Next steps + +- [Turn on 2FA][enable] again after you recover your account. +- Create a [personal access token][pat] for the Docker CLI and automation. + +[enable]: /manuals/security/authentication/2fa/manage.md +[pat]: /manuals/security/access-tokens/personal-access-tokens.md diff --git a/content/manuals/security/authentication/_index.md b/content/manuals/security/authentication/_index.md new file mode 100644 index 000000000000..5c843ffd1eb3 --- /dev/null +++ b/content/manuals/security/authentication/_index.md @@ -0,0 +1,47 @@ +--- +title: Authentication +linkTitle: Authentication +description: Configure single sign-on, OIDC connections, and two-factor authentication. +keywords: authentication, SSO, OIDC, two-factor authentication, 2FA, Docker security +weight: 20 +grid: + - title: Single sign-on + description: Authenticate users through your identity provider. + icon: key + link: /security/authentication/single-sign-on/ + - title: Two-factor authentication + description: Add a TOTP security code to an individual Docker account. + icon: device-phone-mobile + link: /security/authentication/2fa/ + - title: OIDC connections + description: Authenticate GitHub Actions with short-lived tokens. + icon: lock-closed + link: /security/authentication/oidc-connections/ +--- + +Authentication in Docker Home is how users and workloads prove who they are +before they access Docker products. + +Two-factor authentication (2FA) protects an individual account. Single +sign-on (SSO) federates sign-in for an organization or company. OpenID +Connect (OIDC) connections authenticate CI workloads such as GitHub Actions. + +## Choose an authentication method + +| Method | Who it covers | Who configures it | How authentication works | +| --- | --- | --- | --- | +| Two-factor authentication (2FA) | An individual Docker account | The account holder | Password plus a time-based one-time password (TOTP) from an authenticator app | +| Single sign-on (SSO) | An organization or company | An organization or company owner | Users sign in through the organization's identity provider (IdP) | +| OIDC connections | GitHub Actions and similar workloads | An organization owner or editor | Docker exchanges short-lived tokens issued per workflow run | + +SSO requires a Docker Business subscription, or an +[AI Governance](/manuals/accounts/organization/manage/manage-licenses.md) +license. OIDC connections require a Docker Team or Business subscription. + +To require Docker Desktop users to sign in as organization members, see +[Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). +Enforce sign-in is configured in Enterprise, not in this section. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/authentication/oidc-connections/_index.md b/content/manuals/security/authentication/oidc-connections/_index.md new file mode 100644 index 000000000000..bbde0f6f64b7 --- /dev/null +++ b/content/manuals/security/authentication/oidc-connections/_index.md @@ -0,0 +1,64 @@ +--- +title: OIDC connections overview +linkTitle: OIDC connections +description: Authenticate GitHub Actions to Docker with short-lived OpenID Connect tokens +keywords: oidc connections, openid connect, github actions, jwt, subject claims, rulesets, connection limits, enterprise security, workload authentication +tags: [admin] +weight: 35 +aliases: + - /enterprise/security/oidc-connections/ +--- + +{{< summary-bar feature_name="OIDC connections" >}} + +OIDC connections create a trust relationship between Docker and a trusted +third party so you don't have to maintain long-lived credentials. When you +create an OIDC connection, Docker exchanges short-lived tokens with another +vendor that can grant fine-grained access to your Docker resources. + +## How OIDC connections work + +OIDC connections follow the OpenID Connect (OIDC) standard. Establishing a +trust relationship involves creating the connection, configuring a +workflow, and testing. A connection, then, is the named trust relationship +in Docker Home that workflows point to. For example, a trust relationship +between Docker and GitHub follows these steps: + +- GitHub issues a JWT ID token for the workflow run. +- During authentication, Docker: + - Verifies the token against GitHub's public key registry + - Matches subject claims against rulesets created in + [Docker Home](https://app.docker.com/) +- Docker returns an access token so the GitHub Action can sign in to Docker + and access resources. + +All tokens created and exchanged during an OIDC workflow are short-lived +and issued on a per-workflow basis. + +For how OIDC connections compare to organization access tokens, see +[Access tokens](/manuals/security/access-tokens/_index.md). + +## Connection limits + +The number of OIDC connections an organization can have depends on its +subscription: + +| Subscription | Maximum OIDC connections | +| :----------- | :----------------------- | +| Team | 10 | +| [Docker-Sponsored Open Source](/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md) | 10 | +| Business | 100 | + +Active and deactivated connections count toward the limit, but deleted +connections don't. When your organization reaches the limit, the +**Create OIDC connection** button is disabled. To create another +connection, delete one you no longer need. + +Each connection can have up to five rulesets. See +[Rulesets](/manuals/security/authentication/oidc-connections/rulesets-claims.md#rulesets). + +## Next steps + +- [Create an OIDC connection](/manuals/security/authentication/oidc-connections/create-manage.md) +- [OIDC rulesets and subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md) +- [Troubleshoot OIDC connections](/manuals/security/authentication/oidc-connections/troubleshoot.md) diff --git a/content/manuals/security/authentication/oidc-connections/create-manage.md b/content/manuals/security/authentication/oidc-connections/create-manage.md new file mode 100644 index 000000000000..2f847d6ba54a --- /dev/null +++ b/content/manuals/security/authentication/oidc-connections/create-manage.md @@ -0,0 +1,144 @@ +--- +title: Create and manage OIDC connections +linkTitle: Create and manage +description: Create and manage OIDC connections in Docker Home, then authenticate GitHub Actions to Docker Hub with docker/login-action and short-lived tokens +keywords: oidc connections, create oidc connection, github actions, docker/login-action, DOCKERHUB_OIDC_CONNECTIONID, openid connect, docker hub, enterprise security, admin +tags: [admin] +weight: 10 +aliases: + - /enterprise/security/oidc-connections/create-manage/ +--- + +{{< summary-bar feature_name="OIDC connections" >}} + +Organization owners and editors create and manage OIDC connections from +**OIDC connections** in Docker Home. After you create a connection, +configure your GitHub Actions workflow so it can sign in to Docker Hub +with a short-lived token. + +> [!NOTE] +> OIDC connections support only GitHub as a trusted third party. +> GitHub Enterprise Cloud (GHEC) and GitHub Enterprise Server (GHES) +> are not supported. + +## Create an OIDC connection + +1. Sign in to [Docker Home](https://app.docker.com/), select your + organization, then go to **Identity & auth**. +1. Select **OIDC connections**. +1. Select **Create OIDC connection** and fill in the form. + - **Connection name**, a **Ruleset name**, and a **Subject claim** are + required. **Description** is optional. + - For rulesets, subject claims, and resources, see + [OIDC connections rulesets and subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md). +1. Select **Create connection**. +1. Copy your OIDC connection ID. + +## Configure a GitHub Actions workflow + +Use `docker/login-action` version 4.5.0 or later. The action exchanges +the GitHub OIDC token and signs in to Docker Hub in a single step. + +1. Add the following to your workflow YAML. Replace `` + with your Docker organization name and `` with + the ID you copied from Docker Home: + + ```yaml + permissions: + contents: read + id-token: write + + jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Docker login + uses: docker/login-action@v4 # v4.5.0+ + with: + username: + env: + DOCKERHUB_OIDC_CONNECTIONID: + ``` + + The `username` value must be a Docker organization name. Only + organization accounts can sign in using OIDC. + +1. Run the workflow and confirm it can sign in to Docker. + +## Manage OIDC connections + +You can view, edit, deactivate, or delete connections from the **OIDC +connections** page. + +1. Select **Identity & auth**, then **OIDC connections**. +1. Find the row with your target connection ID. +1. Select the action menu icon for your options. + - **Edit** opens the **Edit OIDC connection** page where you can copy + your connection ID, update rulesets, or open the **Failures** tab. + See [View connection failures](#view-connection-failures). + - **Deactivate** temporarily disables access to your GitHub workflow. + - **Activate** restores access to your GitHub workflow. + - **Delete** permanently deletes a connection. + +## Deactivate or delete a connection + +Deactivate an OIDC connection to pause GitHub workflow access to your +Docker resources without deleting the connection. A deactivated +connection does not issue Docker access tokens, so `docker/login-action` +fails at the token-exchange step until you activate the connection. + +> [!WARNING] +> Deleting an OIDC connection is permanent. Any workflow that still sets +> `DOCKERHUB_OIDC_CONNECTIONID` to the deleted ID fails at the +> token-exchange step. Update that environment variable with a +> replacement connection ID in every affected workflow before it runs +> again. + +## View connection failures + +Docker records a failure when a workflow reaches the token-exchange step +for your connection and no ruleset matches the token's claims. For GitHub +Actions, Docker only logs the failure when the token's repository +namespace matches a namespace in a `sub` rule on the connection. An +unrelated repository can still receive `access denied` without a +**Failures** row. + +1. Sign in to [Docker Home](https://app.docker.com/), select your + organization, then go to **Identity & auth**. +1. Select **OIDC connections**. +1. Find the connection, open the action menu, and select **Edit**. +1. On the **Edit OIDC connection** page, select the **Failures** tab. + +The **Failures** tab is view-only. It lists past failed exchanges so you +can compare claims to rulesets. It does not run a test or accept inputs. + +If Docker has not recorded any failures for the connection, the tab shows +**No failures have been reported for this connection**. + +> [!NOTE] +> Wrong connection IDs, deactivated connections, and token problems that +> fail before claim matching do not appear on **Failures**. See +> [Troubleshoot OIDC connections](/manuals/security/authentication/oidc-connections/troubleshoot.md). + +### Read a failure entry + +Each failure row includes: + +- The date and time of the failed exchange +- The ruleset rule that did not match, shown as `claim = expected value` + (for example, `sub = repo:my-org/my-repo:ref:refs/heads/main`) +- The incoming claim value from the GitHub ID token, marked with ❌ when + it does not match + +To inspect every claim in the token, expand **Show all claims**. The +expanded table lists **Incoming claim** and **Value**. Claims that failed +validation appear with ❌. + +Use the unmatched expected value and the incoming value together to +decide whether to update the ruleset or the workflow that produced the +token. + +## Next steps + +- [OIDC connections rulesets and subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md) +- [Troubleshoot OIDC connections](/manuals/security/authentication/oidc-connections/troubleshoot.md) diff --git a/content/manuals/security/authentication/oidc-connections/rulesets-claims.md b/content/manuals/security/authentication/oidc-connections/rulesets-claims.md new file mode 100644 index 000000000000..08fb7e47b953 --- /dev/null +++ b/content/manuals/security/authentication/oidc-connections/rulesets-claims.md @@ -0,0 +1,147 @@ +--- +title: Configure OIDC rulesets and subject claims +linkTitle: Rulesets and subject claims +description: >- + Rulesets and subject claims control which GitHub Actions workflows can + push images, pull images, read public repositories, and connect to Docker + Build Cloud. +keywords: >- + oidc connections, rulesets, subject claims, github actions, openid connect, + image push, image pull, docker build cloud, wildcards, access control +tags: [admin] +weight: 20 +toc_max: 2 +aliases: + - /enterprise/security/oidc-connections/rulesets-claims/ +--- + +{{< summary-bar feature_name="OIDC connections" >}} + +Rulesets and subject claims authorize which GitHub workflows can use which +Docker resources on an OIDC connection. + +## Rulesets + +When a workflow triggers an OIDC exchange, Docker checks the token's +subject claim against every ruleset on the connection. If the subject +claim matches, Docker grants the resources and scopes on that ruleset. + +Each ruleset has these fields: + +- **Ruleset name**: A name for the ruleset. +- **Subject claim**: One `sub` string from the GitHub ID token. +- **Resources**: What the workflow can access. +- **Scopes**: The access granted on those resources. + +You can add one to five rulesets on a connection. If more than one +ruleset matches a token, Docker grants the union of their resources and +scopes. Your subscription also limits how many connections your +organization can have. See +[Connection limits](/manuals/security/authentication/oidc-connections/_index.md#connection-limits). + +## Subject claims + +A subject claim is the `sub` field in a GitHub-issued JWT ID token. It +encodes the workflow's organization, repository, branch, environment, and +related details into a single string. The repository, branch, tag, pull +request, or environment is part of that string, not a separate field. + +The default format is: + +```text +repo:/:ref:refs/heads/ +``` + +You can use wildcards to match across repositories or branches: + +| Pattern | Matches | +| :--------------------------------------------- | :--------------------------------------------------- | +| `repo:my-org/my-repo:ref:refs/heads/main` | Only the `main` branch of a specific repository | +| `repo:my-org/*` | All repositories in the organization | +| `repo:my-org/my-repo:ref:refs/heads/release-*` | All branches starting with `release-` | + +> [!NOTE] +> GitHub repositories created after July 15, 2026 use immutable +> identifiers for default subject claims. For example: +> `repo:octocat@123456/my-repo@456789:ref:refs/heads/main`. See the +> [GitHub changelog](https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/) +> for more details. + +For the full list of formats, see +[GitHub's OpenID Connect reference](https://docs.github.com/en/actions/reference/security/oidc). + +## Resources + +A resource is a Docker Hub repository or Docker Build Cloud builder. +Scopes on the matching ruleset decide what the workflow can do with a defined resource. + +- A repository resource is a Docker Hub repository in your organization. + **Image Pull** and **Image Push** apply to that repository. **Read + public repositories** applies to public repositories. +- A Docker Build Cloud resource uses the **Cloud Connect** scope, so the + workflow can connect and build in Docker Build Cloud. + +## Ruleset examples + +The following examples are working setups you can adapt. They are not +exhaustive, and they are not the only valid way to configure a +connection. Use them when you decide how to allocate your five +rulesets. + +Start with one ruleset. Add more when different branches or permissions +need to change independently. Each example is a complete setup on its +own. + +### Publish from main and use Build Cloud + +Use one ruleset when the same workflows need several permissions and +you want to change those permissions together. + +| Ruleset name | Subject claim | Resources and scopes | +| :----------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------- | +| `main` | `repo:octo-org/octo-repo:ref:refs/heads/main` | Repository `octo-org/octo-repo` with **Image Push**, and Docker Build Cloud with **Cloud Connect** | + +Other branches receive `access denied` unless you add another ruleset. + +### Different access for release branches and main + +Split into two rulesets when release work should only pull an image, +but `main` should publish it. You can then tighten release access +without editing the publish rule. + +| Ruleset name | Subject claim | Resources and scopes | +| :------------- | :------------------------------------------------- | :-------------------------------------------------- | +| `release-pull` | `repo:octo-org/octo-repo:ref:refs/heads/release-*` | Repository `octo-org/octo-repo` with **Image Pull** | +| `main-push` | `repo:octo-org/octo-repo:ref:refs/heads/main` | Repository `octo-org/octo-repo` with **Image Push** | + +With this setup: + +- Branches whose names start with `release-` can pull the image. +- Workflows on `main` can publish the image. +- Other branches, such as `feature-x`, receive `access denied`. + +### Combine a broad read rule with a narrow push rule + +Use two overlapping rulesets when every repository in the GitHub org +should read public images, but only `main` in one repository should +publish. + +| Ruleset name | Subject claim | Resources and scopes | +| :----------- | :-------------------------------------------- | :----------------------------------------------------- | +| `main-push` | `repo:octo-org/octo-repo:ref:refs/heads/main` | Repository `octo-org/octo-repo` with **Image Push** | +| `org-read` | `repo:octo-org/*` | Public repositories with **Read public repositories** | + +With this setup: + +- A workflow on `main` matches both rulesets, so it can publish the + image and read public repositories. +- A workflow on any other branch or repository in `octo-org` matches + `org-read` only, so it can read public repositories. +- Deleting `org-read` removes the shared read permission and leaves the + publish rule unchanged. + +## Next steps + +- [OIDC connections overview](/manuals/security/authentication/oidc-connections/_index.md) +- [Create or manage OIDC connections](/manuals/security/authentication/oidc-connections/create-manage.md) +- [Troubleshoot OIDC connections](/manuals/security/authentication/oidc-connections/troubleshoot.md) diff --git a/content/manuals/security/authentication/oidc-connections/troubleshoot.md b/content/manuals/security/authentication/oidc-connections/troubleshoot.md new file mode 100644 index 000000000000..4c8f2e960384 --- /dev/null +++ b/content/manuals/security/authentication/oidc-connections/troubleshoot.md @@ -0,0 +1,167 @@ +--- +title: Troubleshoot OIDC connections +linkTitle: Troubleshoot +description: >- + Troubleshoot common OIDC connection token-exchange errors with GitHub + Actions +weight: 30 +keywords: >- + oidc troubleshooting, oidc connection errors, Failures tab, github actions + oidc, subject claims, rulesets, docker login-action, + DOCKERHUB_OIDC_CONNECTIONID, access denied, connection_id is invalid, + subject_token +tags: [Troubleshooting, admin] +toc_max: 2 +--- + +{{< summary-bar feature_name="OIDC connections" >}} + +OIDC connection problems can stem from mismatched rulesets, an inactive +or incorrect connection ID, or your GitHub Actions workflow. The following +sections describe common errors and how to resolve them. + +To inspect failed token exchanges in Docker Home, see +[View connection failures](/manuals/security/authentication/oidc-connections/create-manage.md#view-connection-failures). + +## Subject claim does not match a ruleset + +### Error message + +In GitHub Actions, the login step fails during token exchange. Docker +returns: + +```text +access denied +``` + +When Docker records the failure, the **Failures** tab shows the expected +subject claim next to the incoming `sub` value from GitHub. If there is +no failure row, confirm the workflow uses the correct connection ID and +that a ruleset `sub` pattern covers that repository's namespace. See +[View connection failures](/manuals/security/authentication/oidc-connections/create-manage.md#view-connection-failures). + +### Causes + +- The workflow's repository, branch, tag, pull request, or environment + produces a different `sub` value than the ruleset expects. +- The ruleset uses a narrow pattern and the workflow runs from a + different ref (for example, a feature branch instead of `main`). +- The ruleset still uses a mutable `repo:org/repo:...` subject while the + GitHub repository issues an immutable subject claim. See + [Subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md#subject-claims). + +### Solutions + +1. Open the connection's **Failures** tab, if a row exists, and compare + the expected `sub` value with the incoming value marked ❌. +1. Update the ruleset's **Subject claim** on the **Rulesets** tab so it + matches the workflow, or use a wildcard where appropriate. See + [Rulesets and subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md). +1. Select **Save connection**, then re-run the GitHub Actions workflow. + +## Connection ID is invalid or the connection is inactive + +### Error message + +In GitHub Actions, the login step fails during token exchange. Docker +returns: + +```text +connection_id is invalid +``` + +If the workflow omits the connection ID entirely, Docker returns +`connection_id is required when subject_token_type is id_token` +instead. + +`connection_id is invalid` also appears when the ID is malformed, does +not exist, or the connection is deactivated or deleted. Deactivated and +deleted connections are not available for token exchange, so Docker +treats the ID as invalid. + +This failure does not add a row on the **Failures** tab. + +### Causes + +- `DOCKERHUB_OIDC_CONNECTIONID` is missing from the workflow, or its + value does not match the connection ID shown in Docker Home. +- The connection was deactivated from the **OIDC connections** action + menu. Inactive connections use the same invalid-ID error as unknown + IDs. +- The connection was deleted and the workflow still references the old + ID. + +### Solutions + +1. In Docker Home, open **OIDC connections** and confirm the connection + status. +1. If the connection is inactive, open the action menu and select + **Activate**. +1. If the connection was deleted, create a new connection and update + `DOCKERHUB_OIDC_CONNECTIONID` in every affected workflow. See + [Create and manage OIDC connections](/manuals/security/authentication/oidc-connections/create-manage.md). +1. If the connection is active, copy the connection ID from the **Edit + OIDC connection** page and confirm the workflow uses that exact + value. + +## Subject token errors + +### Error message + +In GitHub Actions, the login step fails before or during token exchange. +Docker may return one of: + +```text +subject_token is required +subject_token is invalid +subject_token has expired +subject_token audience mismatch +subject_token issuer mismatch +``` + +These failures do not appear on the **Failures** tab because the +exchange fails before Docker evaluates your rulesets. + +### Causes + +- The workflow does not supply a GitHub OIDC ID token to the login step. +- The token expired, is not yet valid, or does not match the expected + issuer or audience. +- The token cannot be verified against the provider's keys. + +### Solutions + +1. Confirm the job grants GitHub permission to issue an OIDC token: + + ```yaml + permissions: + contents: read + id-token: write + ``` + +1. Use `docker/login-action` version 4.5.0 or later with your + organization name and connection ID. See + [Configure a GitHub Actions workflow](/manuals/security/authentication/oidc-connections/create-manage.md#configure-a-github-actions-workflow). +1. Re-run the workflow so GitHub issues a fresh ID token. + +## Username is not an organization + +### Causes + +- The `username` input to `docker/login-action` is an individual Docker Hub + account instead of an organization name. +- Only organization accounts can sign in with OIDC connections. + +### Solutions + +1. Set `username` to the Docker organization that owns the OIDC + connection. +1. Confirm that organization matches the one where you created the + connection in Docker Home. + +## Related information + +- [Create and manage OIDC connections](/manuals/security/authentication/oidc-connections/create-manage.md) +- [View connection failures](/manuals/security/authentication/oidc-connections/create-manage.md#view-connection-failures) +- [OIDC rulesets and subject claims](/manuals/security/authentication/oidc-connections/rulesets-claims.md) +- [OIDC connections overview](/manuals/security/authentication/oidc-connections/_index.md) diff --git a/content/manuals/security/authentication/single-sign-on/_index.md b/content/manuals/security/authentication/single-sign-on/_index.md new file mode 100644 index 000000000000..504df6a132c9 --- /dev/null +++ b/content/manuals/security/authentication/single-sign-on/_index.md @@ -0,0 +1,100 @@ +--- +title: Single sign-on overview +linkTitle: Single sign-on +description: >- + How Docker single sign-on works for Business organizations and companies, + and the steps to configure a domain, IdP connection, and optional + enforcement. +keywords: single sign-on, SSO, sign-in, admin, Docker Hub, Docker Home, + security, identity provider, IdP, SSO configuration, SSO setup, Docker + Business, AI Governance, SAML, domain verification, enforce SSO, JIT + provisioning, personal access token +aliases: + - /single-sign-on/ + - /admin/company/settings/sso/ + - /admin/organization/security-settings/sso-management/ + - /security/for-admins/single-sign-on/ + - /enterprise/security/single-sign-on/ +weight: 10 +--- + +{{< summary-bar feature_name="SSO" >}} + +Single sign-on (SSO) lets users access Docker by authenticating through your +identity provider (IdP). You can configure SSO for an entire company, +including all associated organizations, or for a single organization. SSO +requires a Docker Business subscription or an +[AI Governance](/manuals/accounts/organization/manage/manage-licenses.md) +license. + +## How SSO works + +When a user signs in to Docker Desktop or Docker Hub, Docker sends them to +your IdP's sign-in page. The IdP accepts or denies the sign-in. + +```mermaid {title="Sign-in when the IdP accepts the user" caption="The user has no Docker session, and the IdP accepts them."} +sequenceDiagram + actor User + participant App as Docker Desktop
or
Docker Hub + participant Login as Docker Login + participant IdP as Your IdP + + User->>App: Open the app + App->>Login: Start authentication + Login->>IdP: Send the user to your IdP + IdP->>User: Prompt for credentials + User->>IdP: Enter credentials + IdP->>Login: Confirm the user + Login->>App: Return the user to the app +``` + +## Set up SSO + +Setting up SSO is a multi-step procedure that moves between Docker and your +IdP. + +```mermaid {title="SSO setup flow" caption="The hexagon marks the IdP step. After the connection works, complete the post-setup tasks."} +flowchart LR + %% Link the columns to each other. A link into a step inside a + %% column makes that column run left to right. + subgraph configure["Configure SSO"] + direction TB + A["1. Add a domain"] --> B["2. Verify your domain"] + B --> C["3. Create an SSO connection in Docker"] + C --> D{{"4. Create an SSO connection in your IdP"}} + D --> E["5. Connect Docker to your IdP"] + E --> F["6. Test the connection"] + end + + subgraph post["Post-setup"] + direction TB + G["Provision users"] + H["Optional: Enforce SSO / Desktop sign-in"] + I["Manage SSO configuration"] + G --> H --> I + end + + configure -->|"After the connection works"| post + + classDef step fill:#ffffff,stroke:#6b7280,color:#111827 + class A,B,C,D,E,F,G,H,I step + style configure fill:#dbeafe,stroke:#2563eb,stroke-width:2px + style post fill:#fef9c3,stroke:#ca8a04,stroke-width:2px +``` + +After you finish the setup, users sign in to Docker services with their +company email address. When +[Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md) +is turned on, which is the default for an SSO connection, Docker adds each +user to your organization and team on first sign-in. + +> [!IMPORTANT] +> +> When SSO is enforced, the Docker CLI rejects password sign-in. Use a +> personal access token (PAT) to sign in to the CLI. + +## Next steps + +- Start [configuring SSO](connect.md). +- Read the [FAQs](/manuals/faqs/security.md). +- [Troubleshoot SSO issues](troubleshoot-sso.md). diff --git a/content/manuals/security/authentication/single-sign-on/connect.md b/content/manuals/security/authentication/single-sign-on/connect.md new file mode 100644 index 000000000000..0f800d0e6f1b --- /dev/null +++ b/content/manuals/security/authentication/single-sign-on/connect.md @@ -0,0 +1,365 @@ +--- +title: Set up single sign-on +linkTitle: Setup +weight: 20 +description: >- + Connect Docker and your identity provider, test the setup, and enable + enforcement. +keywords: configure sso, set up sso, docker sso setup, + docker identity provider, sso enforcement, docker hub, security, + domain verification, SAML, OIDC +aliases: + - /security/for-admins/single-sign-on/connect/ + - /docker-hub/domains/ + - /docker-hub/sso-connection/ + - /docker-hub/enforcing-sso/ + - /single-sign-on/configure/ + - /admin/company/settings/sso-configuration/ + - /admin/organization/security-settings/sso-configuration/ + - /security/for-admins/single-sign-on/configure/ + - /enterprise/security/single-sign-on/connect/ +--- + +{{< summary-bar feature_name="SSO" >}} + +To set up a single sign-on (SSO), you need to establish a connection between +Docker and your identity provider (IdP). While this guide uses Okta and +Microsoft Entra ID as a working example, the general process remains the same +for other IdPs. + +If you're unfamiliar with the SSO process, first review +[SSO overview](/manuals/security/authentication/single-sign-on/_index.md) to +learn about how SSO works. + +## Prerequisites + +Docker supports any SAML 2.0 or OIDC-compatible identity provider. Before you +begin, make sure the following conditions are met: + +- Notify your company about the upcoming SSO sign-in process. +- Confirm that each Docker user has a valid IdP account using the same email + address as their Unique Primary Identifier (UPN). +- Ensure CI/CD pipelines use PATs or OATs instead of passwords. + +## Set up an SSO connection + +> [!TIP] +> +> These procedures have you copy and paste values between Docker and your IdP. +> Complete this guide in one session with separate browser windows open for +> Docker and your IdP. + +### Step 1: Add a domain + +To add a domain: + +1. Sign in to [app.docker.com](https://app.docker.com), then choose your + organization. If your organization is part of a company, then select the + company to manage the domain at the company level. +1. Select **Identity & auth**, then **Domain management**. +1. Select **Add a domain**. +1. Enter your domain in the text box and select **Add domain**. +1. In the modal, copy the **TXT Record Value** provided for domain verification. + +### Step 2: Verify your domain + +To confirm domain ownership, add a TXT record to your Domain Name System (DNS) +host using the TXT Record Value from Docker. DNS propagation can take up to 72 +hours. Docker automatically checks for the record during this time. + +> [!TIP] +> +> When adding a record name, use `@` or leave it empty for root domains like +> `example.com`. Avoid common values like `docker`, `docker-verification`, +> `www`, or your domain name itself. Always check your DNS provider's +> documentation to verify their specific record name requirements. + +{{< tabs >}} +{{< tab name="AWS Route 53" >}} + +1. To add your TXT record to AWS, see + [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). +1. Wait up to 72 hours for TXT record verification. +1. After the record is live, go to **Identity & auth**, then **Domain + management**, and select **Verify**. + +{{< /tab >}} +{{< tab name="Google Cloud DNS" >}} + +1. To add your TXT record to Google Cloud DNS, see + [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). +1. Wait up to 72 hours for TXT record verification. +1. After the record is live, go to **Identity & auth**, then **Domain + management**, and select **Verify**. + +{{< /tab >}} +{{< tab name="GoDaddy" >}} + +1. To add your TXT record to GoDaddy, see + [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). +1. Wait up to 72 hours for TXT record verification. +1. After the record is live, go to **Identity & auth**, then **Domain + management**, and select **Verify**. + +{{< /tab >}} +{{< tab name="Other providers" >}} + +1. Sign in to your domain host. +1. Add a TXT record to your DNS settings and save the record. +1. Wait up to 72 hours for TXT record verification. +1. After the record is live, go to **Identity & auth**, then **Domain + management**, and select **Verify**. + +{{< /tab >}} +{{< /tabs >}} + +### Step 3: Create an SSO connection in Docker + +1. From [app.docker.com](https://app.docker.com), choose your organization. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. Select **Create Connection** and name the connection. + +The dialog offers two connection types. Select the type that matches the +identity provider tab you use in the next step. + +{{< tabs >}} +{{< tab name="SAML 2.0" >}} + +Use this type for the Okta SAML and Entra ID SAML 2.0 tabs. + +1. Select **SAML 2.0**. +1. Copy **Entity ID**, **ACS URL**, and **Connection ID**. For SAML + configuration, paste these values into your identity provider. + +{{< /tab >}} +{{< tab name="Azure AD (OIDC)" >}} + +Use this type for the Azure OpenID Connect (OIDC) tab. + +1. Select **Azure AD (OIDC)**. +1. Copy **Redirect URI**. For Azure AD configuration, paste the Redirect + URI, also called the **Reply URL**, into your identity provider. + +{{< /tab >}} +{{< /tabs >}} + +Keep this window open. You will return here to finish connecting after +creating an SSO connection in your IdP. + +### Step 4: Create an SSO connection in your IdP + +Use the following tabs based on your IdP provider. + +{{< tabs >}} +{{< tab name="Okta SAML" >}} + +You need +[super admin permissions](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) +for the Okta org. + +1. Sign in to your Okta Admin account. From the top nav, select the **Admin** + button to go to Okta's Admin Console. +1. From the **Applications** section in the left nav, choose **Applications**. + Select **Create App Integration**. +1. Choose SAML 2.0 to match your selection from Docker Home. +1. For **General Settings**, name your app "Docker." Uploading a logo is + optional. +1. For **Configure SAML**, input the following values: + - For the **Single Sign On URL** value, paste the Docker ACS URL. + - For the **Audience URI (SP Entity ID)** value, paste the Docker Entity ID. + - For **Name ID format**, choose `EmailAddress` + - For **Application username**, choose `Email` + - For **Update application username on**, choose `Create and update` + - Optional. Add + [SAML attributes](/manuals/security/provisioning/_index.md#sso-attributes), + if required by your org. +1. For **Feedback**, choose **This is an internal app that we have created** + checkbox before finishing. + +Keep your Okta window open for the next step. + +{{< /tab >}} +{{< tab name="Entra ID SAML 2.0" >}} + +To enable SSO with Microsoft Entra, you need +[Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) +permissions. + +1. From Microsoft Entra admin center, select **Entra ID**, then go to + **Enterprise apps**. Select **All applications**. +1. Choose **Create your own application** and name your app "Docker". Select + **Non-gallery**. +1. After creating your app, go to **Single Sign-On** and select **SAML**. +1. Select **Edit** on the **Basic SAML configuration** section. From **Basic + SAML configuration**, choose **Edit** and paste the values you copied from + creating an SSO connection in Docker: + - For the **Identifier** value, paste the Docker Entity ID. + - For the **Reply URL** value, paste Docker ACS URL. +1. Optional. Add + [SAML attributes](/manuals/security/provisioning/_index.md#sso-attributes), + if required by your org. +1. From the **SAML Signing Certificate** section, download your **Certificate + (Base64)**. + +{{< /tab >}} +{{< tab name="Azure OpenID Connect (OIDC)" >}} + +#### Register the app + +1. Sign in to [Microsoft Entra admin center](https://entra.microsoft.com/). +1. Go to **App Registration** and select **New Registration**. +1. Name the application "Docker". +1. Set account types and paste the **Redirect URI** from Docker. +1. Select **Register**. +1. On the app registration **Overview** page, copy **Application (client) + ID**. This value is the Docker **Client ID**. + +#### Create client secrets + +1. In your app, go to **Certificates & secrets**. +1. Select **New client secret**, describe and configure duration, then **Add**. +1. Copy the secret **Value**, not the **Secret ID**. The **Value** is the + Docker **Client Secret**. + + **Value** is the secret string Entra generated. Docker uses it when someone + signs in with this connection. Entra shows the **Value** on this screen + only. If you leave the page or refresh it, the column is blank. Create a + new secret and copy its **Value** before you leave. + + **Secret ID** is the identifier for that row. It stays visible so you can + tell two secrets apart, see which secret is about to expire, or delete a + specific one. Entra does not accept the **Secret ID** as the **Client + Secret**. + +#### Set API permissions + +1. In your app, go to **API permissions**. +1. Select **Grant admin consent** and confirm. +1. Select **Add a permission**, then **Delegated permissions**. +1. Search and select `User.Read`. +1. Confirm that admin consent is granted. + +{{< /tab >}} +{{< /tabs >}} + +### Step 5: Connect Docker to your IdP + +Complete the integration by pasting your IdP values into Docker. + +> [!IMPORTANT] +> +> When prompted to copy a certificate, copy the entire certificate starting with +> `----BEGIN CERTIFICATE----` and including the `----END CERTIFICATE----` lines. + +{{< tabs >}} +{{< tab name="Okta SAML" >}} + +1. Go to **Applications** and choose **Applications**. Choose your app from the + **ACTIVE** table. +1. From **Sign on**, go to **View SAML setup instructions**. This page contains + the **SAML Sign-in URL** and **x509 Certificate**. Keep this page open. +1. Return to your opened Docker window for the **Create single sign-on + connection** step. Paste in the **SAML Sign-in URL** and **x509 Certificate** + values. +1. Optional. Select a default team, if required by your org. +1. Review and select **Create connection**. + +{{< /tab >}} +{{< tab name="Entra ID SAML 2.0" >}} + +1. Open your downloaded **Certificate (Base64)** in a text editor. +1. Copy the following values: + - From Azure AD: **Login URL** + - **Certificate (Base64)** contents +1. Return to Docker Home, then paste the **Login URL** and **Certificate + (Base64)** values. +1. Choose your domain from the drop-down. +1. Optional. Select a default team, if required by your org. +1. Review and select **Create connection**. + +{{< /tab >}} +{{< tab name="Azure OpenID Connect (OIDC)" >}} + +1. Return to Docker Home. +1. Paste the following values: + - **Client ID**: the **Application (client) ID** you copied + - **Client Secret**: the secret **Value** you copied + - **Azure AD Domain** +1. Optional. Select a default team, if required by your org. +1. Review and select **Create connection**. + +{{< /tab >}} +{{< /tabs >}} + +### Step 6: Test the connection + +IdPs like Microsoft Entra and Okta may require that you assign a user to an +application before testing SSO. You can review +[Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso#test-single-sign-on)'s +documentation and +[Okta](https://help.okta.com/wf/en-us/content/topics/workflows/connector-reference/okta/actions/assignusertoapplicationforsso.htm)'s +documentation to learn how to assign yourself or other users to an app. + +After assigning yourself to an app: + +1. Open an incognito browser window and sign in to Docker Home using your domain + email address. +1. When redirected to your IdP's sign-in page, authenticate with your domain + email instead of using your Docker ID. + +If you have multiple IdPs, choose the sign-in option **Continue with SSO**. If +you're using the CLI, you must authenticate using a personal access token. + +## Configure multiple IdPs + +Docker supports multiple identity provider (IdP) configurations by letting you +associate one domain with more than one IdP. Each connection must use the same +domain, which lets users choose their IdP when they select **Continue with SSO** +at sign in. + +To add multiple IdPs: + +1. Use the same domain for each connection. +1. Repeat steps 3-6 from the + [Set up an SSO connection](/manuals/security/authentication/single-sign-on/connect.md#set-up-an-sso-connection) + procedures on this page. Repeat these steps for each IdP your organization + intends to use. + +Because you must use the same domain for each IdP, you won't need to repeat +steps to add and verify your domains. + +## Enforce SSO + +If SSO isn't enforced, users can still sign in using Docker usernames and +passwords. Enforcing SSO requires users to use SSO when signing into Docker, +which centralizes authentication and enforces policies set by the IdP. + +Before enforcing SSO, users accessing Docker through the CLI must +[create a personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md). +The PAT replaces their password for authentication. For CI/CD and other +automation, replace passwords with a PAT or an +[organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md). +For GitHub Actions, you can use an +[OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) +instead of storing a long-lived token. + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization or company. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Action** menu, then **Enable + enforcement**. +1. Follow the on-screen instructions. +1. Select **Turn on enforcement**. + +When you enforce SSO, your users can't modify their email address and password, +convert a user account to an organization, or set up 2FA through Docker Hub. If +you want to use 2FA, you must enable 2FA through your IdP. + +## Next steps + +- [Provision users](/manuals/security/provisioning/_index.md). +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). +- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md). +- [Set up OIDC connections for GitHub Actions](/manuals/security/authentication/oidc-connections/_index.md). +- [Troubleshoot SSO](/manuals/security/authentication/single-sign-on/troubleshoot-sso.md) + issues. diff --git a/content/manuals/security/authentication/single-sign-on/manage.md b/content/manuals/security/authentication/single-sign-on/manage.md new file mode 100644 index 000000000000..abd5ea22e6a0 --- /dev/null +++ b/content/manuals/security/authentication/single-sign-on/manage.md @@ -0,0 +1,149 @@ +--- +title: Manage SSO domains and connections +linkTitle: Manage connections +weight: 30 +description: >- + Learn how to manage single sign-on domains, connections, users, and + provisioning for your organization or company. +keywords: manage, single sign-on, SSO, sign-on, docker home, admin, security, + domains, connections, users, provisioning +aliases: + - /admin/company/settings/sso-management/ + - /single-sign-on/manage/ + - /security/for-admins/single-sign-on/manage/ + - /enterprise/security/single-sign-on/manage/ +--- + +{{< summary-bar feature_name="SSO" >}} + +After you set up single sign-on (SSO), you can add or remove domains, edit or +delete connections, and change how users are provisioned. + +## Manage domains + +### Add a domain + +To add a domain to an existing SSO connection: + +1. Sign in to [Docker Home](https://app.docker.com) and select your company or + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Actions** menu for your + connection, then select **Edit connection**. +1. Select **Next** to navigate to the domains section. +1. In the **Domains** section, select **Add domain**. +1. Enter the domain you want to add to the connection. +1. Select **Next** to confirm or change the connected organizations. +1. Select **Next** to confirm or change the default organization and team + provisioning selections. +1. Review the connection details and select **Update connection**. + +### Remove a domain from an SSO connection + +> [!IMPORTANT] +> +> If you use multiple identity providers with the same domain, you must remove +> the domain from each SSO connection individually. + +1. Sign in to [Docker Home](https://app.docker.com) and select your company or + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** menu for your + connection, then **Edit connection**. +1. Select **Next** to navigate to the domains section. +1. In the **Domain** section, select the **X** icon next to the domain you want + to remove. +1. Select **Next** to confirm or change the connected organizations. +1. Select **Next** to confirm or change the default organization and team + provisioning selections. +1. Review the connection details and select **Update connection**. + +> [!NOTE] +> +> When you re-add a domain, Docker assigns a new TXT record value. You must +> complete domain verification again with the new TXT record. + +## Manage SSO connections + +### View connections + +To view all configured SSO connections: + +1. Sign in to [Docker Home](https://app.docker.com) and select your company or + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. View all configured connections in the **SSO connections** table. + +### Edit a connection + +To modify an existing SSO connection: + +1. Sign in to [Docker Home](https://app.docker.com) and select your company or + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** menu for your + connection, then **Edit connection**. +1. Follow the on-screen instructions to modify your connection settings. + +### Delete a connection + +To remove an SSO connection: + +1. Sign in to [Docker Home](https://app.docker.com) and select your company or + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** menu for your + connection, then **Delete connection**. +1. Follow the on-screen instructions to confirm the deletion. + +> [!WARNING] +> +> Deleting an SSO connection removes access for all users who authenticate +> through that connection. + +## Manage users and provisioning + +Docker automatically provisions users through Just-in-Time (JIT) provisioning +when they sign in via SSO. You can also manually manage users and configure +different provisioning methods. + +### How provisioning works + +Docker supports the following provisioning methods: + +- JIT provisioning (default): Users are automatically added to your organization + when they sign in via SSO +- SCIM provisioning: Sync users and groups from your identity provider to Docker +- Group mapping: Sync user groups from your identity provider with teams in your + Docker organization +- Manual invitations: Invite users directly. You can turn off JIT only after you + enable SCIM. + +For more information on provisioning methods, see +[Provision users](/manuals/security/provisioning/_index.md). + +### Add guest users + +To invite users who don't authenticate through your identity provider: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Select **Invite**. +1. Follow the on-screen instructions to invite the user. + +The user receives an email invitation and can create a Docker account or sign in +with their existing account. + +### Remove users + +To remove a user from your organization: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Members**. +1. Find the user you want to remove and select the **Actions** menu next to + their name. +1. Select **Remove** and confirm the removal. + +The user loses access to your organization immediately upon removal. diff --git a/content/manuals/security/authentication/single-sign-on/troubleshoot-sso.md b/content/manuals/security/authentication/single-sign-on/troubleshoot-sso.md new file mode 100644 index 000000000000..258d7ed43583 --- /dev/null +++ b/content/manuals/security/authentication/single-sign-on/troubleshoot-sso.md @@ -0,0 +1,339 @@ +--- +title: Troubleshoot single sign-on +linkTitle: Troubleshoot +description: >- + Troubleshoot common Docker single sign-on configuration and authentication + issues. +weight: 40 +keywords: sso troubleshooting, single sign-on errors, authentication issues, + identity provider problems, JIT provisioning, SCIM errors, domain + verification, AADSTS700016 +tags: [Troubleshooting] +toc_max: 2 +aliases: + - /security/for-admins/single-sign-on/troubleshoot/ + - /security/troubleshoot/troubleshoot-sso/ + - /enterprise/troubleshoot/troubleshoot-sso/ + - /enterprise/security/single-sign-on/troubleshoot-sso/ +--- + +Single sign-on (SSO) problems can stem from your identity provider (IdP) +configuration or from your Docker settings. The following sections describe +common errors and how to resolve them. + +## Check for errors + +If you experience SSO issues, check both Docker and your identity provider for +errors first. + +### Check Docker error logs + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Action** menu and then **View + error logs**. +1. For more details on specific errors, select **View error details** next to an + error message. +1. Note any errors you see on this page for further troubleshooting. + +### Check identity provider errors + +1. Review your IdP’s logs or audit trails for any failed authentication or + provisioning attempts. +1. Confirm that your IdP’s SSO settings match the values provided in Docker. +1. If applicable, confirm that you have configured user provisioning correctly + and that it is enabled in your IdP. +1. If applicable, verify that your IdP correctly maps Docker's required user + attributes. +1. Try provisioning a test user from your IdP and verify if they appear in + Docker. + +For further troubleshooting, check your IdP's documentation or contact their +support team. + +## Groups are not formatted correctly + +### Error message + +When this issue occurs, the following error message is common: + +```text +Some of the groups assigned to the user are not formatted as ':'. Directory groups will be ignored and user will be provisioned into the default organization and team. +``` + +### Causes + +- Incorrect group name formatting in your identity provider (IdP): Docker + requires groups to follow the format `:`. If the groups + assigned to a user do not follow this format, they will be ignored. +- Non-matching groups between IdP and Docker organization: If a group in your + IdP does not have a corresponding team in Docker, it will not be recognized, + and the user will be placed in the default organization and team. + +### Affected environments + +- Docker single sign-on setup using IdPs such as Okta or Azure AD +- Organizations using group-based role assignments in Docker + +### Steps to replicate + +To replicate this issue: + +1. Attempt to sign in to Docker using SSO. +1. The user is assigned groups in the IdP but does not get placed in the + expected Docker Team. +1. Review Docker logs or IdP logs to find the error message. + +### Solutions + +Update group names in your IdP: + +1. Go to your IdP's group management section. +1. Check the groups assigned to the affected user. +1. Ensure each group follows the required format: `:` +1. Update any incorrectly formatted groups to match this pattern. +1. Save changes and retry signing in with SSO. + +## User is not assigned to the organization + +### Error message + +When this issue occurs, the following error message is common: + +```text +User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX +``` + +### Causes + +- User is not assigned to the organization: If Just-in-Time (JIT) provisioning + is disabled, the user may not be assigned to your organization. +- User is not invited to the organization: If JIT is disabled and you don't want + to turn it on, the user must be manually invited. +- SCIM provisioning is misconfigured: If you use SCIM for user provisioning, it + may not be correctly syncing users from your IdP. + +### Solutions + +#### Enable JIT provisioning + +JIT is enabled by default when you enable SSO. If you have JIT disabled and need +to re-enable it: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Action** menu and then **Enable + JIT provisioning**. +1. Select **Enable** to confirm. + +#### Manually invite users + +When JIT is disabled, users are not automatically added to your organization +when they authenticate through SSO. To manually invite users, see +[Invite members](/manuals/accounts/organization/manage/members.md#invite-members). + +#### Configure SCIM provisioning + +If you have SCIM enabled, troubleshoot your SCIM connection using the following +steps: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Action** menu and then **View + error logs**. For more details on specific errors, select **View error + details** next to an error message. Note any errors you see on this page. +1. Navigate back to **Identity & auth**, then **SSO and SCIM**, and verify your + SCIM configuration: + - Ensure that the SCIM Base URL and API Token in your IdP match those + provided in Docker. + - Verify that SCIM is enabled in both Docker and your IdP. +1. Ensure that the attributes being synced from your IdP match Docker's + [supported attributes](/manuals/security/provisioning/scim/provision-scim.md#supported-attributes) + for SCIM. +1. Test user provisioning by trying to provision a test user through your IdP + and verify if they appear in Docker. + +## IdP-initiated sign in is not enabled for connection + +### Error message + +When this issue occurs, the following error message is common: + +```text +IdP-Initiated sign in is not enabled for connection '$ssoConnection'. +``` + +### Causes + +Docker doesn't support an IdP-initiated SAML flow. This error occurs when a user +attempts to authenticate from your IdP, such as using the Docker SSO app tile on +the sign-in page. + +### Solutions + +#### Authenticate from Docker apps + +The user must initiate authentication from a Docker application such as Docker +Hub or Docker Desktop. The user needs to enter their email address in a Docker +app and they will get redirected to the configured SSO IdP for their domain. + +#### Hide the Docker SSO app + +You can hide the Docker SSO app from users in your IdP. This prevents users from +attempting to start authentication from the IdP dashboard. You must hide and +configure this in your IdP. + +## Not enough seats in organization + +### Error message + +When this issue occurs, the following error message is common: + +```text +Not enough seats in organization '$orgName'. Add more seats or contact your administrator. +``` + +### Causes + +This error occurs when the organization has no available seats for the user when +provisioning via Just-in-Time (JIT) provisioning or SCIM. + +### Solutions + +#### Add more seats to the organization + +Purchase additional Docker Business subscription seats. For details, see +[Manage subscription seats](/manuals/accounts/organization/manage/manage-seats.md). + +#### Remove users or pending invitations + +Review your organization members and pending invitations. Remove inactive users +or pending invitations to free up seats. For more details, see +[Manage organization members](/manuals/accounts/organization/manage/members.md). + +## Domain is not verified for SSO connection + +### Error message + +When this issue occurs, the following error message is common: + +```text +Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX +``` + +### Causes + +This error occurs if the IdP authenticated a user through SSO and the User +Principal Name (UPN) returned to Docker doesn’t match any of the verified +domains associated to the SSO connection configured in Docker. + +### Solutions + +#### Verify UPN attribute mapping + +Ensure that the IdP SSO connection is returning the correct UPN value in the +assertion attributes. + +#### Add and verify all domains + +Add and verify all domains and subdomains used as UPN by your IdP and associate +them with your Docker SSO connection. For details, see +[Configure single sign-on](/manuals/security/authentication/single-sign-on/connect.md). + +## Unable to find session + +### Error message + +When this issue occurs, the following error message is common: + +```text +We couldn't find your session. You may have pressed the back button, refreshed the page, opened too many sign-in dialogs, or there is some issue with cookies. Try signing in again. If the issue persists, contact your administrator. +``` + +### Causes + +The following causes may create this issue: + +- The user pressed the back or refresh button during authentication. +- The authentication flow lost track of the initial request, preventing + completion. + +### Solutions + +#### Avoid disrupting the authentication flow + +Do not press the back or refresh button during sign-in. + +#### Restart authentication + +Close the browser tab and restart the authentication flow from the Docker +application, such as Docker Desktop or Docker Hub. + +## Name ID is not an email address + +### Error message + +When this issue occurs, the following error message is common: + +```text +The name ID sent by the identity provider is not an email address. Contact your company administrator. +``` + +### Causes + +The following causes may create this issue: + +- The IdP sends a Name ID (UPN) that does not comply with the email format + required by Docker. +- Docker SSO requires the Name ID to be the primary email address of the user. + +### Solutions + +In your IdP, ensure the Name ID attribute format is correct: + +1. Verify that the Name ID attribute format in your IdP is set to + `EmailAddress`. +1. Adjust your IdP settings to return the correct Name ID format. + +## Application was not found in the directory + +### Error message + +During Azure AD (OIDC) sign-in, Microsoft Entra can return: + +```text +AADSTS700016: Application with identifier '{identifier}' was not found in the directory '{directory}'. +``` + +### Causes + +The **Client ID** on the Docker SSO connection is not the **Application +(client) ID** from the app registration **Overview** page. Pasting the +**Secret ID** into **Client ID** makes Entra search for an application that +does not exist. + +Entra also returns this error when the sign-in request goes to a directory +that does not contain the app registration. + +### Solutions + +Replace the application identifier in Docker: + +1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), open + the app registration. +1. On the **Overview** page, copy **Application (client) ID**. +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the SSO connections table, select the **Action** menu, then **Edit + connection**. +1. Paste **Application (client) ID** into **Client ID**. The **Secret ID** + and the secret **Value** are not application identifiers. + +If the directory named in the error is not the tenant where you registered +the app, update **Azure AD Domain** on the Docker connection so sign-in uses +that tenant. For the connection steps, see +[Set up single sign-on](/manuals/security/authentication/single-sign-on/connect.md). diff --git a/content/manuals/security/faqs/_index.md b/content/manuals/security/faqs/_index.md deleted file mode 100644 index 4aebbca68bbb..000000000000 --- a/content/manuals/security/faqs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: FAQs -weight: 70 ---- diff --git a/content/manuals/security/faqs/containers.md b/content/manuals/security/faqs/containers.md deleted file mode 100644 index 5c3496f338eb..000000000000 --- a/content/manuals/security/faqs/containers.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Container security FAQs -linkTitle: Container -description: Frequently asked questions about Docker container security and isolation -keywords: container security, docker desktop isolation, enhanced container isolation, file sharing -weight: 20 -tags: [FAQ] -aliases: -- /faq/security/containers/ ---- - -## How are containers isolated from the host in Docker Desktop? - -Docker Desktop runs all containers inside a customized Linux virtual machine (except for native Windows containers). This adds strong isolation between containers and the host machine, even when containers run as root. - -Important considerations include: - -- Containers have access to host files configured for file sharing via Docker Desktop settings -- Containers run as root with limited capabilities inside the Docker Desktop VM by default -- Privileged containers (`--privileged`, `--pid=host`, `--cap-add`) run with elevated privileges inside the VM, giving them access to VM internals and Docker Engine - -With Enhanced Container Isolation turned on, each container runs in a dedicated Linux user namespace inside the Docker Desktop VM. Even privileged containers only have privileges within their container boundary, not the VM. ECI uses advanced techniques to prevent containers from breaching the Docker Desktop VM and Docker Engine. - -## Which portions of the host filesystem can containers access? - -Containers can only access host files that are: - -1. Shared using Docker Desktop settings -1. Explicitly bind-mounted into the container (e.g., `docker run -v /path/to/host/file:/mnt`) - -## Can containers running as root access admin-owned files on the host? - -No. Host file sharing uses a user-space file server (running in `com.docker.backend` as the Docker Desktop user), so containers can only access files that the Docker Desktop user already has permission to access. diff --git a/content/manuals/security/faqs/general.md b/content/manuals/security/faqs/general.md deleted file mode 100644 index 82422ca63958..000000000000 --- a/content/manuals/security/faqs/general.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -description: Frequently asked questions about Docker security, authentication, and organization management -keywords: Docker security, FAQs, authentication, SSO, vulnerability reporting, session management -title: General security FAQs -linkTitle: General -weight: 10 -tags: [FAQ] -aliases: -- /faq/security/general/ ---- - -## How do I report a vulnerability? - -If you've discovered a security vulnerability in Docker, report it responsibly to security@docker.com so Docker can quickly address it. - -## Does Docker lockout users after failed sign-ins? - -Docker Hub locks out users after 10 failed sign-in attempts within 5 minutes. The lockout duration is 5 minutes. This policy applies to Docker Hub, Docker Desktop, and Docker Scout authentication. - -## Do you support physical multi-factor authentication (MFA) with YubiKeys? - -You can configure physical multi-factor authentication (MFA) through SSO using your identity provider (IdP). Check with your IdP if they support physical MFA devices like YubiKeys. - -## How are sessions managed and do they expire? - -Docker uses tokens to manage user sessions with different expiration periods: - -- Docker Desktop: Signs you out after 90 days, or 30 days of inactivity -- Docker Hub and Docker Home: Sign you out after 24 hours - -Docker also supports your IdP's default session timeout through SAML attributes. For more information, see [SSO attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes). - -## How does Docker distinguish between employee users and contractor users? - -Organizations use verified domains to distinguish user types. Team members with email domains other than verified domains appear as "Guest" users in the organization. - -## How long are activity logs available? - -Docker activity logs are available for 90 days. You're responsible for exporting logs or setting up drivers to send logs to your internal systems for longer retention. - -## Can I export a list of users with their roles and privileges? - -Yes, use the [Export Members](../../admin/organization/manage/members.md#export-members-csv-file) feature to export a CSV file containing your organization's users with role and team information. - -## How does Docker Desktop handle authentication information? - -Docker Desktop uses the host operating system's secure key management to store authentication tokens: - -- macOS: [Keychain](https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web) -- Windows: [Security and Identity API via Wincred](https://learn.microsoft.com/en-us/windows/win32/api/wincred/) -- Linux: [Pass](https://www.passwordstore.org/). - -## How do I remove users who aren't part of my IdP when using SSO without SCIM? - -If SCIM isn't turned on, you must manually remove users from the organization. SCIM can automate user removal, but only for users added after SCIM is turned on. Users added before SCIM was turned on must be removed manually. - -For more information, see [Manage organization members](/manuals/admin/organization/manage/members.md). - -## What metadata does Scout collect from container images? - -For information about metadata stored by Docker Scout, see [Data handling](/manuals/scout/deep-dive/data-handling.md). - -## How are Marketplace extensions vetted for security? - -Security vetting for extensions isn't implemented. Extensions aren't covered as part of Docker's Third-Party Risk Management Program. - -## Can I prevent users from pushing images to Docker Hub private repositories? - -No direct setting exists to disable private repositories. However, [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) lets administrators control which registries developers can access through Docker Desktop via the Admin Console. diff --git a/content/manuals/security/faqs/networking-and-vms.md b/content/manuals/security/faqs/networking-and-vms.md deleted file mode 100644 index 668697d482a5..000000000000 --- a/content/manuals/security/faqs/networking-and-vms.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Network and VM FAQs -linkTitle: Network and VM -description: Frequently asked questions about Docker Desktop networking and virtualization security -keywords: docker desktop networking, virtualization, hyper-v, wsl2, network security, firewall -weight: 30 -tags: [FAQ] -aliases: -- /faq/security/networking-and-vms/ ---- - -## How can I limit container internet access? - -Docker Desktop doesn't have a built-in mechanism for this, but you can use process-level firewalls on the host. Apply rules to the `com.docker.vpnkit` user-space process to control where it can connect (DNS allowlists, packet filters) and which ports/protocols it can use. - -For enterprise environments, consider [Air-gapped containers](/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md) which provide network access controls for containers. - -## Can I apply firewall rules to container network traffic? - -Yes. Docker Desktop uses a user-space process (`com.docker.vpnkit`) for network connectivity, which inherits constraints like firewall rules, VPN settings, and HTTP proxy properties from the user that launched it. - -## Does Docker Desktop for Windows with Hyper-V allow users to create other VMs? - -No. The `DockerDesktopVM` name is hard-coded in the service, so you cannot use Docker Desktop to create or manipulate other virtual machines. - -## How does Docker Desktop achieve network isolation with Hyper-V and WSL 2? - -Docker Desktop uses the same VM processes for both WSL 2 (in the `docker-desktop` distribution) and Hyper-V (in `DockerDesktopVM`). Host/VM communication uses `AF_VSOCK` hypervisor sockets (shared memory) rather than network switches or interfaces. All host networking is performed using standard TCP/IP sockets from the `com.docker.vpnkit.exe` and `com.docker.backend.exe` processes. - -For more information, see [How Docker Desktop networking works under the hood](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood/). diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md new file mode 100644 index 000000000000..fff3281ce9f5 --- /dev/null +++ b/content/manuals/security/provisioning/_index.md @@ -0,0 +1,109 @@ +--- +description: >- + Provision Docker organization users with SCIM, JIT, group mapping, or + auto-provisioning, and map SSO and SAML attributes from your identity + provider. +keywords: provision users, user provisioning, JIT, SCIM, group mapping, + auto-provisioning, SSO, SAML, identity provider, dockerOrg, dockerRole, + dockerTeam, dockerSessionMinutes, Docker Home, admin, security +title: User provisioning overview +linkTitle: Provision +weight: 30 +aliases: + - /security/for-admins/provisioning/ + - /enterprise/security/provisioning/ +grid: + - title: Add and manage domains + description: Add, verify, and manage domains for auto-provisioning. + icon: globe-alt + link: "domain-management/" + - title: SCIM provisioning + description: Sync user data between your IdP and Docker with SCIM. + icon: arrow-path + link: "scim/" + - title: Just-in-Time (JIT) provisioning + description: Create user accounts automatically on first SSO sign-in. + icon: clock + link: "just-in-time/" + - title: Auto-provisioning + description: Add users whose email addresses match a verified domain. + icon: user-group + link: "auto-provisioning/" +--- + +{{< summary-bar feature_name="SSO" >}} + +After you configure single sign-on (SSO), provision users so they can +access your organization through automated account management. + +## Provisioning methods + +Provisioning automates account creation, updates, and deactivation using +data from your identity provider (IdP). Docker supports the following +methods: + +| Provisioning method | When it runs | Lifecycle management | Default setting | +| :--- | :--- | :--- | :--- | +| [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | On the IdP's synchronization schedule or through Provision on Demand | Creates and updates users, synchronizes configured groups, and deprovisions users | Disabled | +| [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | When a user signs in through SSO | Creates users and applies attributes from the SSO assertion. It doesn't deprovision users | Enabled when you configure SSO | +| [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) | When an existing Docker user signs in or verifies their email, and that address uses a verified domain | Adds the user to the organization. It doesn't create or deprovision accounts | Disabled | + +[Group mapping](/manuals/security/provisioning/scim/group-mapping.md) assigns +users to Docker organizations and teams. Use it with SAML SSO or SCIM. You can +also invite users manually when automatic provisioning isn't configured. + +## Default provisioning setup + +Docker turns on JIT provisioning when you configure an SSO connection. If you +also enable SCIM, Docker recommends choosing one provisioning source to manage +users and attributes. Before configuring SCIM, review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). + +For a domain that belongs to an SSO connection, JIT adds the user instead of +auto-provisioning. + +## SSO attributes + +Each time a user signs in through SSO, Docker reads attributes from your +IdP to set the user's identity and permissions: + +| Attribute | Required | Description | +| :--- | :--- | :--- | +| Email address | Yes | Unique identifier for the user | +| Full name | Yes | User's complete name | +| Groups | No | Group-based access control | +| Docker Org | No | Organization the user belongs to | +| Docker Team | No | Team within the organization | +| Docker Role | No | Permissions in Docker | +| Docker session minutes | No | Session duration, in minutes, before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If omitted, default session timeouts apply | + +> [!NOTE] +> +> Default session timeouts apply when Docker session minutes is not +> specified. Docker Desktop sessions expire after 90 days or 30 days of +> inactivity. Docker Hub and Docker Home sessions expire after 24 hours. + +## SAML attribute mapping + +If your organization uses SAML for SSO, Docker reads these attributes +from the SAML assertion. Identity providers may use different names for +the same attributes. + +| SSO attribute | SAML assertion attributes | +| :--- | :--- | +| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` | +| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` | +| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` | +| Docker Org (optional) | `dockerOrg` | +| Docker Team (optional) | `dockerTeam` | +| Docker Role (optional) | `dockerRole` | +| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer greater than 0 | + +## Next steps + +Choose the provisioning method that fits your organization: + +{{< grid >}} + +If users get the wrong role or team after you change methods, see +[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/security/provisioning/auto-provisioning.md b/content/manuals/security/provisioning/auto-provisioning.md new file mode 100644 index 000000000000..36afbb2f6f30 --- /dev/null +++ b/content/manuals/security/provisioning/auto-provisioning.md @@ -0,0 +1,71 @@ +--- +title: Auto-provisioning +linkTitle: Auto-provision +description: Auto-provision users by associating members to your organization when email addresses match a verified domain. +keywords: user provisioning, just-in-time provisioning, JIT, autoprovision, Docker Admin, admin, security +weight: 30 +aliases: + - /enterprise/security/provisioning/auto-provisioning/ +--- + +Auto-provisioning automatically adds users to your organization when they +sign in with email addresses that match your verified domains. You must verify +a domain before enabling auto-provisioning. + +> [!IMPORTANT] +> +> For domains that are part of an SSO connection, Just-in-Time (JIT) +> provisioning takes precedence over auto-provisioning when adding users to an +> organization. + +### Overview + +When auto-provisioning is enabled for a verified domain: + +- Users who sign in to Docker with matching email addresses are automatically + added to your organization. +- Auto-provisioning only adds existing Docker users to your organization, it + doesn't create new accounts. +- Users experience no changes to their sign-in process. +- Company and organization owners receive email notifications when new users + are added. +- You may need to + [manage seats](/manuals/accounts/organization/manage/manage-seats.md) to + accommodate new users. + +### Enable auto-provisioning + +Auto-provisioning is configured per domain. To enable it: + +1. Sign in to [Docker Home](https://app.docker.com) and select + your company or organization. +1. Select **Identity & auth**, then **Domain management**. +1. Select the **Actions menu** next to the domain you want to enable + auto-provisioning for. +1. Select **Enable auto-provisioning**. +1. Optional. If enabling auto-provisioning at the company level, select an + organization. +1. Select **Enable** to confirm. + +The **Auto-provisioning** column will update to **Enabled** for the domain. + +### Disable auto-provisioning + +To disable auto-provisioning for a domain: + +1. Sign in to [Docker Home](https://app.docker.com) and select + your organization. If your organization is part of a company, select the company + and configure the domain for the organization at the company level. +1. Select **Identity & auth**, then **Domain management**. +1. Select the **Actions menu** next to your domain. +1. Select **Disable auto-provisioning**. +1. Select **Disable** to confirm. + +## Next steps + +To choose a different method to provision users, you can set up: + +- [SCIM provisioning](/manuals/security/provisioning/scim/_index.md) for + advanced user management. +- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to + assign users to teams automatically. diff --git a/content/manuals/security/provisioning/domain-management.md b/content/manuals/security/provisioning/domain-management.md new file mode 100644 index 000000000000..b1eb09ef8691 --- /dev/null +++ b/content/manuals/security/provisioning/domain-management.md @@ -0,0 +1,164 @@ +--- +title: Add and manage domains +description: Add, verify, and manage domains to control user access and enable auto-provisioning in Docker organizations +keywords: domain management, domain verification, auto-provisioning, user management, DNS, TXT record, Docker Home +weight: 5 +aliases: + - /security/for-admins/domain-management/ + - /enterprise/security/domain-management/ +--- + +{{< summary-bar feature_name="Domain management" >}} + +Domain management lets you add and verify domains for your organization, then +enable auto-provisioning to automatically add users when they sign in with +email addresses that match your verified domains. This approach simplifies +user management, ensures consistent security settings, and reduces the risk of +unmanaged users accessing Docker without visibility or control. + +This page provides steps to add and delete domains, configure +auto-provisioning, and audit uncaptured users. + +## Add and verify a domain + +Adding a domain requires verification to confirm ownership. The verification +process uses DNS records to prove you control the domain. + +### Add a domain + +1. Sign in to [Docker Home](https://app.docker.com) and select + your organization. If your organization is part of a company, select the company + and configure the domain for the organization at the company level. +1. Select **Identity & auth**, then **Domain management**. +1. Select **Add a domain**. +1. Enter your domain and select **Add domain**. +1. In the pop-up modal, copy the **TXT Record Value** to verify your domain. + +### Verify a domain + +Verification confirms that you own the domain by adding a TXT record to your +Domain Name System (DNS) host. It can take up to 72 hours for the DNS change to +propagate. Docker automatically checks for the record and confirms ownership +once the change is recognized. + +> [!TIP] +> +> The record name field determines where the TXT record is added in your +> domain (root or subdomain). For root domains like `example.com`, use `@` or +> leave the record name empty, depending on your provider. Don't enter values +> like docker, `docker-verification`, `www`, or your domain name, as these may +> direct to the wrong place. Check your DNS provider's documentation to verify +> record name requirements. + +Follow the steps for your DNS provider to add the **TXT Record Value**. If +your provider isn't listed, use the steps for "Other providers": + +{{< tabs >}} +{{< tab name="AWS Route 53" >}} + +1. Add your TXT record to AWS by following + [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). +1. Wait up to 72 hours for TXT record verification. +1. Return to the **Domain management** page of the + **Identity & auth**, then **Domain management**, and select **Verify** next to + your domain name. + +{{< /tab >}} +{{< tab name="Google Cloud DNS" >}} + +1. Add your TXT record to Google Cloud DNS by following + [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). +1. Wait up to 72 hours for TXT record verification. +1. Return to the **Domain management** page of the + **Identity & auth**, then **Domain management**, and select **Verify** next to + your domain name. + +{{< /tab >}} +{{< tab name="GoDaddy" >}} + +1. Add your TXT record to GoDaddy by following + [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). +1. Wait up to 72 hours for TXT record verification. +1. Return to the **Domain management** page of the + **Identity & auth**, then **Domain management**, and select **Verify** next to + your domain name. + +{{< /tab >}} +{{< tab name="Other providers" >}} + +1. Sign in to your domain host. +1. Add a TXT record to your DNS settings using the **TXT Record Value** from Docker. +1. Wait up to 72 hours for TXT record verification. +1. Return to the **Domain management** page of the + **Identity & auth**, then **Domain management**, and select **Verify** next to + your domain name. + +{{< /tab >}} +{{< /tabs >}} + +## Audit domains for uncaptured users + +Domain audit identifies uncaptured users. Uncaptured users are Docker users who +have authenticated using an email address associated with your verified +domains but aren't members of your Docker organization. + +### Limitations + +Domain audit can't identify: + +- Users who access Docker Desktop without authenticating +- Users who authenticate using an account that doesn't have an + email address associated with one of your verified domains + +To prevent unidentifiable users from accessing Docker Desktop, +[enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). + +### Run a domain audit + +1. Sign in to [Docker Home](https://app.docker.com) and choose your + company. +1. Select **Identity & auth**, then **Domain management**. +1. In **Domain audit**, select **Export Users** to export a CSV file + of uncaptured users. + +The CSV file contains the following columns: + +- Name: Docker user's display name +- Username: Docker ID of the user +- Email: Email address of the user + +### Invite uncaptured users + +You can bulk invite uncaptured users to your organization using the exported +CSV file. For more information on bulk inviting users, see +[Manage organization members](/manuals/accounts/organization/manage/members.md). + +## Auto-provisioning + +[Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) adds +existing Docker users to an organization when their email addresses match a +verified domain. For domains that belong to an SSO connection, Just-in-Time +(JIT) provisioning takes precedence over auto-provisioning. + +To compare JIT, SCIM, and auto-provisioning, see the +[user provisioning overview](/manuals/security/provisioning/_index.md). + +## Delete a domain + +Deleting a domain removes its TXT record value and disables any associated +auto-provisioning. + +> [!WARNING] +> +> Deleting a domain will disable auto-provisioning for that domain and remove +> verification. This action cannot be undone. + +To delete a domain: + +1. Sign in to [Docker Home](https://app.docker.com) and select + your organization. If your organization is part of a company, select the company + and configure the domain for the organization at the company level. +1. Select **Identity & auth**, then **Domain management**. +1. For the domain you want to delete, select the **Actions** menu, then + **Delete domain**. +1. To confirm, select **Delete domain** in the pop-up modal. diff --git a/content/manuals/security/provisioning/just-in-time.md b/content/manuals/security/provisioning/just-in-time.md new file mode 100644 index 000000000000..096b3ba6b3be --- /dev/null +++ b/content/manuals/security/provisioning/just-in-time.md @@ -0,0 +1,139 @@ +--- +description: >- + Learn how Just-in-Time (JIT) provisioning creates and updates Docker + accounts during SSO sign-in and assigns teams, and how to turn it off or + back on. +keywords: user provisioning, just-in-time provisioning, JIT provisioning, JIT, + SSO, single sign-on, SCIM, enable JIT, disable JIT, enable JIT provisioning, + disable JIT provisioning, identity provider, IdP, group mapping, + SSO connection +title: Just-in-Time provisioning +linkTitle: Just-in-Time +weight: 20 +aliases: + - /security/for-admins/provisioning/just-in-time/ + - /enterprise/security/provisioning/just-in-time/ +--- + +{{< summary-bar feature_name="SSO" >}} + +Just-in-Time (JIT) provisioning creates and updates user accounts during SSO +authentication. JIT verifies that users belong to the organization and assigns +them to teams based on your identity provider (IdP) configuration. + +## How it works + +JIT fits organizations that want to give their users the quickest path to +access. JIT grants users access the first time they sign in with SSO without +needing an invitation. + +The following diagram shows SSO sign-in with and without JIT: + +```mermaid {title="SSO authentication with and without JIT provisioning" caption="With JIT, Docker adds users to organizations and teams at sign-in. Without it, only members can sign in. Highlighted steps happen only with JIT."} +--- +config: + themeVariables: + fontSize: 14px + flowchart: + wrappingWidth: 80 + nodeSpacing: 14 + rankSpacing: 22 + padding: 5 + curve: linear + subGraphTitleMargin: + top: 4 + bottom: 12 +--- +flowchart LR + start(["Sign in with SSO"]) --> invite["Accept pending invitation"] + invite --> jit{"JIT enabled?"} + jit -->|Yes| map{"IdP group mappings?"} + map -->|Yes| assign + map -->|No| default + subgraph jitbox["JIT provisioning"] + assign["Add to orgs and teams from IdP"] + default["Add to default org and team"] + end + assign --> ok(["SSO successful"]) + default --> ok + jit -->|No| member{"Member of org?"} + member -->|Yes| ok + member -->|No| denied(["Access denied"]) + + classDef success fill:#22c55e22,stroke:#22c55e + classDef failure fill:#ef444422,stroke:#ef4444 + class ok success + class denied failure + style jitbox fill:#3b82f622,stroke:#3b82f6 +``` + +When a user signs in with SSO, Docker looks for a Docker account with the +email address your IdP sent. If none exists, Docker creates one and generates +a unique username from the user's email, name, and random numbers. If one +exists, Docker updates the user's full name if it changed. + +If JIT is disabled, sign-in succeeds only for organization members and users +with a pending invitation, which Docker accepts at sign-in. Everyone else sees +an `Access denied` error and must ask an administrator for an invitation. + +## Set up + +When you create an SSO connection, Docker turns on JIT provisioning by +default. To set up JIT provisioning: + +1. Set up an + [SSO connection](/manuals/security/authentication/single-sign-on/connect.md) + for your organization. +1. Set the default organization and team that Docker uses for users + who sign in without IdP group mappings. You set these when you create the SSO + connection. +1. Optional. Set up + [group mapping](/manuals/security/provisioning/scim/group-mapping.md#configure-group-mapping-with-sso) + to assign users to organizations and teams from your IdP. +1. Have your users sign in with SSO. + +JIT doesn't remove users when they leave your IdP, so you must remove them +manually. To remove users automatically, use SCIM. + +## Disable + +> [!WARNING] +> +> Disabling JIT provisioning may disrupt your users' access and workflows. +> With JIT disabled, only existing organization members and users with a +> pending invitation can sign in with SSO. + +An SSO connection must keep at least one provisioning method enabled: +JIT, SCIM, or both. You can disable JIT only while +[SCIM is enabled](/manuals/security/provisioning/scim/provision-scim.md#enable-scim-in-docker), +and you can disable SCIM only while JIT is enabled. Before you add SCIM, +review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). +Disable JIT if you want SCIM to be the source of truth for provisioning. + +To disable JIT provisioning: + +1. Go to [Docker Home](https://app.docker.com/) and select your organization + from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** icon, then select + **Disable JIT provisioning**. +1. Select **Disable** to confirm. + +## Re-enable + +If you disabled JIT provisioning, you can turn it back on: + +1. Go to [Docker Home](https://app.docker.com/) and select your organization + from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** icon, then select + **Enable JIT provisioning**. +1. Select **Enable** to confirm. + +## Next steps + +- Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md) + to automatically assign users to teams. +- Review + [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/security/provisioning/scim/_index.md b/content/manuals/security/provisioning/scim/_index.md new file mode 100644 index 000000000000..00e0daf5d797 --- /dev/null +++ b/content/manuals/security/provisioning/scim/_index.md @@ -0,0 +1,128 @@ +--- +title: SCIM provisioning overview +linkTitle: SCIM +weight: 10 +description: >- + Provision, update, and deprovision Docker users with SCIM, and choose how + SCIM works with Just-in-Time provisioning. +keywords: SCIM, SSO, user provisioning, deprovisioning, JIT, role mapping, + group mapping, identity provider, Provision on Demand, Okta, Entra ID +aliases: + - /security/for-admins/scim/ + - /security/for-admins/provisioning/scim/ + - /enterprise/security/provisioning/scim/ +--- + +{{< summary-bar feature_name="SSO" >}} + +System for Cross-domain Identity Management (SCIM) synchronizes users and +groups between your identity provider (IdP) and Docker. It provisions +accounts, syncs profile updates, and deprovisions users throughout the +account lifecycle. + +## Prerequisites + +Before you begin, you must have: + +- SSO configured for your organization +- Administrator access to Docker Home and your identity provider + +## How SCIM works + +After you enable SCIM, any user assigned to your Docker application in the +identity provider is provisioned and added to your Docker organization. SCIM +syncs profile updates from the identity provider, such as name changes, and +reactivates users who are reassigned to the application. If group mapping is +configured, SCIM also synchronizes groups. + +When a user is no longer assigned to the Docker application in the IdP, +SCIM deactivates the Docker account. + +SCIM automates: + +- Creating users +- Updating user profiles +- Deactivating users +- Reactivating users +- Synchronizing groups when group mapping is configured + +> [!NOTE] +> +> After you enable SCIM, it can manage and deprovision any organization member +> whose email domain is verified on the SSO connection. That includes users +> created through JIT or added manually. When your IdP pushes a user with a +> matching email address, SCIM links the existing Docker account. Members +> whose email domain isn't verified on the connection stay outside SCIM. + +## Choose how SCIM works with JIT + +Docker turns on Just-in-Time (JIT) provisioning when you configure an SSO +connection. Before you enable SCIM, choose whether SCIM or JIT will own user +provisioning. + +Docker recommends using one provisioning source. Using SCIM without JIT keeps +the IdP directory authoritative for user creation, attributes, group +membership, and deprovisioning. + +### Use SCIM without JIT + +With JIT turned off, SCIM provisions users on the IdP's synchronization +schedule instead of when users sign in. This configuration provides continuous +attribute updates and automatic deprovisioning. + +If your IdP supports Provision on Demand, you can trigger an immediate sync +for a user who needs access before the next scheduled synchronization. +Configure and test SCIM before you +[turn off JIT](/manuals/security/provisioning/just-in-time.md#disable). + +### Use SCIM with JIT + +JIT and SCIM run independently. While JIT is on, you still assign users to +the Docker application and maintain group mappings in your IdP. + +Two values can change back and forth when both are enabled: + +- Full name. Each SSO sign-in writes the name from the SSO assertion to the + Docker account. If SCIM set a different name, for example the IdP profile + says "Jon Smith" but the assertion sends "Jonathan Smith", sign-in replaces + the SCIM value. The next SCIM sync can set it back. +- Team membership. At sign-in, JIT reads the `groups` or `dockerTeam` value + from the SSO assertion and adds the user to those teams. It never removes + teams. SCIM group sync makes each mapped group's membership match the IdP + group exactly. If JIT added a user to a team that the IdP group doesn't + include, the next sync of that group removes the user from the team, and + the next sign-in adds them back. + +Roles don't move back and forth. JIT sets the organization role only when it +first adds the user. A later SCIM update can change that role, and the next +sign-in leaves the SCIM role in place. + +When a user isn't assigned to the Docker application in the IdP, the next +synchronization deactivates the Docker account. Removing a user from a mapped +group removes that user from the team only. + +If you keep both enabled: + +- Match each user's email address exactly between the SSO assertion and SCIM. +- Assign every user who can sign in through SSO to the Docker application in + the IdP. +- Keep the IdP authoritative for roles, organizations, teams, and group + membership. +- After sign-in and after each SCIM synchronization, confirm that full names + and team memberships still match the IdP. + +SCIM links an existing account, including one created through JIT or added +manually, when the IdP pushes a user with a matching email address. To use +SCIM as the only provisioning source, see +[Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). + +## Next steps + +- [Set up SCIM provisioning](/manuals/security/provisioning/scim/provision-scim.md) + to enable SCIM in Docker and your identity provider. +- [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md) + to turn off JIT after SCIM is managing your users. +- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to + sync identity provider groups with Docker teams. +- [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md) + for SCIM, JIT, and attribute issues. diff --git a/content/manuals/security/provisioning/scim/group-mapping.md b/content/manuals/security/provisioning/scim/group-mapping.md new file mode 100644 index 000000000000..b06a994962bf --- /dev/null +++ b/content/manuals/security/provisioning/scim/group-mapping.md @@ -0,0 +1,226 @@ +--- +title: Map identity provider groups to Docker teams +linkTitle: Group mapping +description: >- + Automate Docker team membership by mapping groups from your identity + provider with SSO or SCIM. +keywords: group mapping, SCIM, SSO, Docker teams, team management, + user provisioning, identity provider, Okta, Microsoft Entra ID +aliases: + - /admin/company/settings/group-mapping/ + - /admin/organization/security-settings/group-mapping/ + - /security/for-admins/group-mapping/ + - /security/for-admins/provisioning/scim/group-mapping/ + - /enterprise/security/provisioning/scim/group-mapping/ +weight: 20 +--- + +{{< summary-bar feature_name="SSO" >}} + +Group mapping synchronizes groups from your identity provider (IdP) with teams +in your Docker organization. For example, when you add a developer to the +`moby:backend` group in your IdP, Docker adds them to the `backend` team in the +`moby` organization. + +Use group mapping to manage team membership through SAML SSO, SCIM, or both. + +> [!TIP] +> +> Use group mapping to add users to multiple organizations or teams. To assign +> each user to one organization or team, you can use SCIM +> [user-level attributes](provision-scim.md#set-up-role-mapping). + +## Prerequisites + +Before you begin, you must have: + +- SSO configured for your organization +- Administrator access to Docker Home and your identity provider + +## How group mapping works + +Group mapping uses IdP attributes to keep Docker Team membership synchronized: + +- With SAML SSO, the IdP sends group membership when a user signs in. +- With SCIM, the IdP synchronizes group membership on its provisioning + schedule. +- Docker identifies users by email address. Each Docker account must have a + unique email address. +- Docker creates teams when a mapped group references a team that doesn't + exist. + +## Set up group mapping + +To configure group mapping: + +- Create groups in your IdP using Docker's naming format +- Configure your IdP to send group data +- Add users to the groups +- Test that membership synchronizes + +You can use group mapping with SAML SSO alone or with SCIM for user lifecycle +management. + +### Group naming format + +Create groups in your IdP using the format: `organization:team`. + +For example: + +- For the "developers" team in the "moby" organization: `moby:developers` +- For multi-organization access: `moby:backend` and `whale:desktop` + +Docker creates teams automatically if they don't already exist when groups sync. + +### Supported attributes + +| Attribute | Description | +| :--- | :--- | +| `id` | Unique ID of the group in UUID format. This attribute is read-only. | +| `displayName` | Group name in the `organization:team` format. | +| `members` | A list of users that are members of this group. | +| `members(x).value` | Unique ID of a user in the group. | + +## Configure group mapping with SSO + +Use group mapping with SSO connections that use the SAML authentication method. + +> [!NOTE] +> +> Group mapping through SSO isn't supported with the Microsoft Entra ID OIDC +> authentication method. Use SCIM to synchronize groups for OIDC connections. + +{{< tabs >}} +{{< tab name="Okta" >}} + +The IdP interface may differ from these steps. For more information, see the +[Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm). + +To set up group mapping: + +1. Sign in to Okta and open your application. +1. Navigate to the **SAML Settings** page for your application. +1. In **Group Attribute Statements (optional)**, configure these values: + - **Name**: `groups` + - **Name format**: `Unspecified` + - **Filter**: **Starts with** and `organization:`, where `organization` is + your Docker organization name +1. Create your groups by selecting **Directory**, then **Groups**. +1. Add groups in the `organization:team` format that match your Docker + organization and team names. +1. Assign users to the groups. + +The next time users sign in, Docker maps them to the teams you defined. + +{{< /tab >}} +{{< tab name="Entra ID" >}} + +The IdP interface may differ from these steps. For more information, see the +[Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims). + +To set up group mapping: + +1. Sign in to Entra ID and open your application. +1. Select **Manage**, then **Single sign-on**. +1. Select **Add a group claim**. +1. In **Group Claims**, select **Groups assigned to the application** with the + source attribute **Cloud-only group display names**. +1. Select **Advanced options**, then the **Filter groups** option. +1. Configure the attribute like the following: + - **Attribute to match**: `Display name` + - **Match with**: `Contains` + - **String**: `:` +1. Select **Save**. +1. Select **Groups** > **All groups** > **New group** to create your groups. +1. Assign users to the groups. + +The next time users sign in, Docker maps them to the teams you defined. + +{{< /tab >}} +{{< /tabs >}} + +## Configure group mapping with SCIM + +Use group mapping with SCIM to synchronize membership on your IdP's +provisioning schedule. Before you begin, +[set up SCIM](./provision-scim.md#enable-scim-in-docker). + +{{< tabs >}} +{{< tab name="Okta" >}} + +The IdP interface may differ from these steps. For more information, see the +[Okta documentation](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm). + +To set up your groups: + +1. Sign in to Okta and open your application. +1. Select **Applications**, then **Provisioning**, and **Integration**. +1. Select **Edit**, enable **Push Groups**, then select **Save**. The + **Push Groups** tab appears in your application. +1. Create your groups by navigating to **Directory** and selecting **Groups**. +1. Add groups in the `organization:team` format that match your Docker + organization and team names. +1. Assign users to the groups. +1. Return to **Integration**, then select **Push Groups**. +1. Select **Push Groups**, then **Find groups by rule**. +1. Configure the groups by rule like the following: + - Enter a rule name, such as `Sync groups with Docker`. + - Match groups by name. For example, use **Starts with** and `moby:`, or + **Contains** and `:` for multiple organizations. + - To sync after changes to groups or assignments, enable + **Immediately push groups by rule**. + +Find the rule under **By rule** in the **Pushed Groups** column. Matching groups +appear in the groups table. + +To push the groups from this table: + +1. Select **Group in Okta**. +1. Select the **Push Status** drop-down. +1. Select **Push Now**. + +{{< /tab >}} +{{< tab name="Entra ID" >}} + +The IdP interface may differ from these steps. For more information, see the +[Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups). + +1. Sign in to Entra ID and go to your application. +1. In your application, select **Provisioning**, then **Mappings**. +1. Select **Provision Microsoft Entra ID Groups**. +1. Set **Enabled** to **Yes**. +1. Confirm these attribute mappings: + - `displayName` to `displayName` + - `objectId` to `externalId` + - `members` to `members` +1. Select **Save**. + +Next, set up group mapping: + +1. Go to **Users and groups**. +1. Select **Add user/group**. +1. Select groups that use the `organization:team` format. +1. Select **Assign**. +1. Go to **Provisioning** and select **Start provisioning**. + +To verify the sync, select **Monitor**, then **Provisioning logs**. In Docker +Home, confirm that members appear in the mapped teams. + +{{< /tab >}} +{{< /tabs >}} + +After synchronization, Docker adds users to the organizations and teams mapped +in the IdP. + +> [!TIP] +> +> [Enable SCIM](provision-scim.md) to provision and deprovision users +> automatically. Group mapping through SSO manages team membership but doesn't +> deprovision users. + +## Next steps + +- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to + organization members. +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for + your organization. diff --git a/content/manuals/security/provisioning/scim/migrate-scim.md b/content/manuals/security/provisioning/scim/migrate-scim.md new file mode 100644 index 000000000000..ae5d1c7308bf --- /dev/null +++ b/content/manuals/security/provisioning/scim/migrate-scim.md @@ -0,0 +1,128 @@ +--- +title: Migrate JIT to SCIM +linkTitle: Migrate +description: >- + Move from Just-in-Time provisioning to SCIM so your identity provider + manages Docker user lifecycle. +keywords: JIT to SCIM migration, SCIM provisioning, user deprovisioning, + identity provider, Docker Home, user lifecycle management +weight: 30 +aliases: + - /enterprise/security/provisioning/scim/migrate-scim/ +--- + +{{< summary-bar feature_name="SSO" >}} + +Move from Just-in-Time (JIT) provisioning to System for Cross-domain Identity +Management (SCIM) as the only source of user provisioning. After SCIM is +enabled, it can manage organization members whose email domain is verified on +the SSO connection, including users created through JIT. When your identity +provider (IdP) pushes a user with a matching email address, SCIM links the +existing Docker account. + +## Why migrate + +With JIT turned off, your identity provider stays authoritative for who has +access: + +- Users are deprovisioned when they leave your organization +- User attributes and group membership stay synchronized with the IdP + +Docker recommends SCIM with JIT turned off. If your IdP supports Provision +on Demand, use it when a user needs access before the next scheduled +synchronization. + +## Prerequisites + +Before you migrate: + +- [Set up and test SCIM](provision-scim.md) in Docker and your IdP. +- Confirm each user's email address matches exactly between the IdP and + Docker. +- In the IdP, set the group memberships and any `dockerRole` values you want + to keep. + +## Assign users in your IdP + +1. Assign every user who should belong to the Docker organization to the + Docker application in your IdP. +1. Confirm that group-to-team mappings are configured and tested. See + [Group mapping](group-mapping.md). + +When a user isn't assigned to the Docker application, the next +synchronization deactivates the Docker account. + +## Sync and verify + +Trigger a synchronization, or use Provision on Demand, so SCIM links the +existing accounts. + +1. In your IdP's provisioning logs, confirm that provisioning succeeded for + those users. +1. In [Docker Home](https://app.docker.com), select your organization, then + **Members**. +1. Confirm that the users are still members and that their roles and teams + match the IdP. + +To compare the Docker member list with the IdP, export it: + +1. On the **Members** page, select **Export members**. +1. Docker emails you a link to download the CSV file. + +## Disable JIT provisioning + +Turn off JIT after you have verified the linked accounts. You can turn off +JIT only while SCIM is enabled. + +1. Go to [Docker Home](https://app.docker.com/) and select your organization + from the top-left account drop-down. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Action** icon, then select + **Disable JIT provisioning**. +1. Select **Disable** to confirm. + +With JIT turned off, users must already be members, have a pending +invitation, or be provisioned through SCIM. + +## Resolve an unlinked account + +Members whose email domain isn't verified on the SSO connection stay outside +SCIM. A different email address in the IdP also leaves the existing Docker +account unlinked. + +1. Compare the email address in the IdP with the Docker account. +1. Confirm that the user's email domain is verified on the SSO connection. +1. Assign the user to the Docker application and run provisioning again. +1. Confirm the user under **Members**. + +If the account is still unlinked, remove that user so SCIM can provision +them again. + +> [!WARNING] +> +> Removing a user removes their resource ownership, such as repositories. +> Transfer ownership before you remove the user. Don't remove the only +> organization owner. Assign the Owner role to another member first. + +1. In Docker Home, select **Members** and remove the user. +1. Trigger provisioning from your IdP. +1. Confirm that the user reappears with the expected role and teams. + +For more troubleshooting guidance, see +[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). + +## Migration results + +After you turn off JIT: + +- SCIM manages linked users, including users originally created through JIT +- Your IdP deprovisions users by deactivating their Docker accounts +- Sign-in no longer adds users through JIT + +## Next steps + +- Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md). +- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to + organization members. +- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md) for + your organization. diff --git a/content/manuals/security/provisioning/scim/provision-scim.md b/content/manuals/security/provisioning/scim/provision-scim.md new file mode 100644 index 000000000000..5f806f0b3437 --- /dev/null +++ b/content/manuals/security/provisioning/scim/provision-scim.md @@ -0,0 +1,385 @@ +--- +title: Set up SCIM provisioning +linkTitle: Set up +description: >- + Configure SCIM user provisioning and role mapping for Docker with Okta or + Microsoft Entra ID. +keywords: SCIM setup, user provisioning, role mapping, Okta, Microsoft Entra ID, + identity provider, Docker Home +weight: 10 +aliases: + - /enterprise/security/provisioning/scim/provision-scim/ +--- + +{{< summary-bar feature_name="SSO" >}} + +## Supported attributes + +System for Cross-domain Identity Management (SCIM) uses attributes to sync user +information between your identity provider (IdP) and Docker. Map these +attributes to provision users and prevent duplicate accounts when using single +sign-on (SSO). + +Docker supports the following SCIM attributes: + +| Attribute | Description | +| :--- | :--- | +| `userName` | User's primary email address, used as the unique identifier | +| `externalId` | Identifier for the user in your IdP. Docker stores the value | +| `name.givenName` | User's first name | +| `name.familyName` | User's surname | +| `active` | Indicates whether a user is enabled. Set to `false` to deprovision a user | + +For additional details about supported attributes and SCIM, see +[Docker Hub API SCIM reference](/reference/api/hub/latest/#tag-scim). + +> [!IMPORTANT] +> +> Docker turns on Just-in-Time (JIT) provisioning by default when you configure +> SSO. Before setting up SCIM, review +> [how SCIM works with JIT](./_index.md#choose-how-scim-works-with-jit), then +> decide which method manages provisioning. + +## Enable SCIM in Docker + +To enable SCIM: + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** icon for your + connection, then select **Enable SCIM**. +1. In the **Enable SCIM provisioning** dialog, select **Enable**. +1. Copy the **SCIM Base URL** and **API Token**, then paste the values into + your IdP. + +To view the **SCIM Base URL** and **API Token** again, select the **Actions** +icon, then **Edit SCIM**. + +## Enable SCIM in your IdP + +The IdP interface may differ from these steps. For more information, see your +IdP's documentation: + +- [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm) +- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning) + +> [!NOTE] +> +> Microsoft Entra ID doesn't support SCIM and OIDC in the same non-gallery +> application. For OIDC connections, create a separate non-gallery application +> for SCIM provisioning. + +{{< tabs >}} +{{< tab name="Okta" >}} + +### Step one: Enable SCIM + +1. Sign in to Okta and select **Admin** to open the admin portal. +1. Open the application you created when you configured your SSO connection. +1. On the application page, select the **General** tab, then + **Edit App Settings**. +1. Enable SCIM provisioning, then select **Save**. +1. Select **Provisioning**, then **Edit SCIM Connection**. +1. To configure SCIM in Okta, set up your connection using the following + values and settings: + - **SCIM connector base URL**: The **SCIM Base URL** from Docker Home + - **Unique identifier field for users**: `email` + - **Supported provisioning actions**: **Push New Users** and + **Push Profile Updates** + - **Authentication Mode**: **HTTP Header** + - **Authorization**: The **API Token** from Docker Home +1. Select **Test Connector Configuration**. +1. Review the test results and select **Save**. + +### Step two: Enable synchronization + +1. In Okta, select **Provisioning**. +1. Select **To App**, then **Edit**. +1. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. +1. Select **Save**. +1. Remove unnecessary mappings. The necessary mappings are: + - Username + - Given name + - Family name + - Email + +Next, [set up role mapping](#set-up-role-mapping). + +{{< /tab >}} +{{< tab name="Entra ID (OIDC)" >}} + +Microsoft does not support SCIM and OIDC in the same non-gallery application. +You must create a second non-gallery application in Entra ID for SCIM +provisioning. + +### Step one: Create a separate SCIM app + +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > + **Enterprise Applications** > **New application**. +1. Select **Create your own application**. +1. Name your application and choose + **Integrate any other application you don't find in the gallery**. +1. Select **Create**. + +### Step two: Configure SCIM provisioning + +1. In your new SCIM application, go to **Provisioning** > **Get started**. +1. Set **Provisioning Mode** to **Automatic**. +1. Under **Admin Credentials**: + - **Tenant URL**: Paste the **SCIM Base URL** from Docker Home. + - **Secret Token**: Paste the **SCIM API token** from Docker Home. +1. Select **Test Connection** to verify. +1. Select **Save** to store credentials. + +Next, [set up role mapping](#set-up-role-mapping). + +{{< /tab >}} +{{< tab name="Entra ID (SAML 2.0)" >}} + +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > + **Enterprise Applications**, and select your Docker SAML app. +1. Select **Provisioning** > **Get started**. +1. Set **Provisioning Mode** to **Automatic**. +1. Under **Admin Credentials**: + - **Tenant URL**: Paste the **SCIM Base URL** from Docker Home. + - **Secret Token**: Paste the **SCIM API token** from Docker Home. +1. Select **Test Connection** to verify. +1. Select **Save** to store credentials. + +Next, [set up role mapping](#set-up-role-mapping). + +{{< /tab >}} +{{< /tabs >}} + +## Set up role mapping + +You can assign +[Docker roles](/manuals/security/roles-and-permissions/core-roles.md) to users +by adding optional SCIM attributes in your IdP. These attributes override +default role and team values set in your SSO configuration. + +> [!NOTE] +> +> Role mappings are supported for both SCIM and Just-in-Time (JIT) +> provisioning. For JIT, role mapping applies only when the user is first +> provisioned. + +The following table lists the supported optional user-level attributes: + +| Attribute | Possible values | Notes | +| :--- | :--- | :--- | +| `dockerRole` | `member`, `editor`, or `owner` | Overrides the default role. If unset, the user has the `member` role | +| `dockerOrg` | Docker organization name, such as `moby` | Overrides the default organization. If `dockerOrg` and `dockerTeam` are set, the user is provisioned to the team in this organization | +| `dockerTeam` | Docker Team name, such as `developers` | Provisions the user to the team in the default or specified organization. Docker creates the team if it doesn't exist. You can also use [group mapping](group-mapping.md) to assign users to multiple teams or organizations | + +The external namespace for these attributes is +`urn:ietf:params:scim:schemas:extension:docker:2.0:User`. Enter this value when +you create custom SCIM attributes for Docker in your IdP. + +{{< tabs >}} +{{< tab name="Okta" >}} + +### Step one: Set up role mapping in Okta + +1. Set up [SSO](/manuals/security/authentication/single-sign-on/connect.md) and + SCIM. +1. In the Okta admin portal, go to **Directory**, select **Profile Editor**, + and then **User (Default)**. +1. Select **Add Attribute** and configure the values for the role, organization, + or team you want to add. Exact naming isn't required. +1. Return to the **Profile Editor** and select your application. +1. Select **Add Attribute** and enter the required values. The **External Name** + and **External Namespace** must be exact. + - The external name values for organization/team/role mapping are + `dockerOrg`, `dockerTeam`, and `dockerRole`, as listed in the previous + table. + - The external namespace is the same for all of them: + `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. +1. After creating the attributes, navigate to the top of the page and select + **Mappings**, then **Okta User to YOUR APP**. +1. Go to the newly created attributes and map the variable names to the external + names, then select **Save Mappings**. If you're using JIT provisioning, + continue to the following steps. +1. Navigate to **Applications** and select **YOUR APP**. +1. Select **General**, then **SAML Settings**, and **Edit**. +1. Select **Step 2** and configure the mapping from the user attribute to the + Docker variables. + +### Step two: Assign roles by user + +1. In the Okta Admin portal, select **Directory**, then **People**. +1. Select **Profile**, then **Edit**. +1. Select **Attributes** and update the attributes to the desired values. + +### Step three: Assign roles by group + +1. In the Okta Admin portal, select **Directory**, then **People**. +1. Select **YOUR GROUP**, then **Applications**. +1. Open **YOUR APPLICATION** and select the **Edit** icon. +1. Update the attributes to the desired values. + +If a user doesn't already have attributes set up, users who are added to the +group will inherit these attributes upon provisioning. + +{{< /tab >}} +{{< tab name="Entra ID (SAML 2.0 and OIDC)" >}} + +### Step one: Configure attribute mappings + +1. Complete the [SCIM provisioning setup](/manuals/security/provisioning/scim/provision-scim.md#enable-scim-in-docker). +1. In the Microsoft Entra admin center, open **Microsoft Entra ID** > + **Enterprise Applications**, and select your SCIM application. +1. Go to **Provisioning** > **Mappings** > + **Provision Microsoft Entra ID Users**. +1. Add or update the following mappings: + - `userPrincipalName` -> `userName` + - `mail` -> `emails.value` + - Optional. Map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the + [mapping methods](/manuals/security/provisioning/scim/provision-scim.md#set-up-role-mapping). +1. Remove any unsupported attributes to prevent sync errors. +1. Optional. Go to **Mappings** > **Provision Microsoft Entra ID Groups**: + - If group provisioning causes errors, set **Enabled** to **No**. + - If enabling, test group mappings carefully. +1. Select **Save** to apply mappings. + +### Step two: Choose a role mapping method + +You can map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the +following methods: + +#### Expression mapping + +Use this method if you only need to assign Docker roles like `member`, `editor`, +or `owner`. + +1. In the **Edit Attribute** view, set the mapping type to **Expression**. +1. In the **Expression** field: + 1. If your App Roles match Docker roles exactly, use: + `SingleAppRoleAssignment([appRoleAssignments])` + 1. If they don't match, use a switch expression: + `Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")` +1. Set: + - **Target attribute**: `urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole` + - **Match objects using this attribute**: No + - **Apply this mapping**: Always +1. Save your changes. + +> [!WARNING] +> +> You can't use `dockerOrg` or `dockerTeam` with this method. Expression mapping +> is only compatible with one attribute. + +#### Direct mapping + +Use this method if you need to map multiple attributes (`dockerRole` + +`dockerTeam`). + +1. For each Docker attribute, choose a unique Entra extension attribute + (`extensionAttribute1`, `extensionAttribute2`, etc.). +1. In the **Edit Attribute** view: + - Set mapping type to **Direct**. + - Set **Source attribute** to your selected extension attribute. + - Set **Target attribute** to one of: + - `dockerRole: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole` + - `dockerOrg: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerOrg` + - `dockerTeam: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerTeam` + - Set **Apply this mapping** to **Always**. +1. Save your changes. + +Assign extension attribute values with Microsoft Graph. + +### Step three: Assign users and groups + +For either mapping method: + +1. In the SCIM app, go to **Users and Groups** > **Add user/group**. +1. Select the users or groups to provision to Docker. +1. Select **Assign**. + +If you're using expression mapping: + +1. Go to **App registrations** > your SCIM app > **App Roles**. +1. Create App Roles that match Docker roles. +1. Assign users or groups to App Roles under **Users and Groups**. + +If you're using direct mapping: + +1. Go to [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) + and sign in as a tenant admin. +1. Use Microsoft Graph API to assign attribute values. Example PATCH request: + +```bash +PATCH https://graph.microsoft.com/v1.0/users/{user-id} +Content-Type: application/json + +{ + "onPremisesExtensionAttributes": { + "extensionAttribute1": "owner", + "extensionAttribute2": "moby", + "extensionAttribute3": "developers" + } +} +``` + +> [!NOTE] +> +> You must use a different extension attribute for each SCIM field. Microsoft +> Graph can update these attributes for cloud-only users that haven't +> previously been synchronized from an on-premises directory. + +{{< /tab >}} +{{< /tabs >}} + +See the documentation for your IdP for additional details: + +- [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) +- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application) + +## Test SCIM provisioning + +After completing role mapping, you can test the configuration manually. + +{{< tabs >}} +{{< tab name="Okta" >}} + +1. In the Okta admin portal, go to **Directory > People**. +1. Select a user you've assigned to your SCIM application. +1. Select **Provision User**. +1. Wait a few seconds, then check the Docker + **Members** in [Docker Home](https://app.docker.com). +1. If the user doesn't appear, review logs in **Reports > System Log** and + confirm SCIM settings in the app. + +{{< /tab >}} +{{< tab name="Entra ID (OIDC and SAML 2.0)" >}} + +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > + **Enterprise Applications**, and select your SCIM app. +1. Go to **Provisioning** > **Provision on demand**. +1. Select a user or group and choose **Provision**. +1. Confirm that the user appears in the Docker + **Members** in [Docker Home](https://app.docker.com). +1. If needed, check **Provisioning logs** for errors. + +{{< /tab >}} +{{< /tabs >}} + +## Disable SCIM + +You can disable SCIM only while JIT provisioning is turned on. When SCIM is +off, users remain in the organization, but changes from your IdP stop +syncing. To deprovision these users, remove them manually from the +organization. + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** icon. +1. If JIT is off, select **Enable JIT provisioning**, then **Enable**. Open + the **Actions** menu again. +1. Select **Disable SCIM**. +1. Select **Disable** to confirm. + +## Next steps + +- Set up [Group mapping](/manuals/security/provisioning/scim/group-mapping.md). +- [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/security/provisioning/troubleshoot-provisioning.md b/content/manuals/security/provisioning/troubleshoot-provisioning.md new file mode 100644 index 000000000000..3fcf4c8d4918 --- /dev/null +++ b/content/manuals/security/provisioning/troubleshoot-provisioning.md @@ -0,0 +1,120 @@ +--- +title: Troubleshoot provisioning +linkTitle: Troubleshoot +description: Troubleshoot common user provisioning issues with SCIM and Just-in-Time provisioning +keywords: SCIM troubleshooting, user provisioning, JIT provisioning, group mapping, attribute conflicts +tags: [Troubleshooting] +toc_max: 2 +aliases: + - /enterprise/troubleshoot/troubleshoot-provisioning/ + - /enterprise/security/provisioning/troubleshoot-provisioning/ +--- + +This page helps troubleshoot common user provisioning issues including user +roles, attributes, and unexpected account behavior with SCIM and Just-in-Time +(JIT) provisioning. + +## Full name or team membership changes after sign-in + +### Error message + +This scenario doesn't usually produce an error message in Docker or your IdP. +A user's full name changes after they sign in, or a team membership +disappears after a SCIM sync and comes back the next time they sign in. + +### Causes + +JIT and SCIM are both enabled: + +- Each SSO sign-in writes the full name from the SSO assertion to the Docker + account, replacing a name that SCIM set. The next SCIM sync can set it + back. +- At sign-in, JIT adds the user to the teams the SSO assertion lists. SCIM + group sync makes each mapped group's membership match the IdP group + exactly. If the IdP group doesn't include the user, the next sync removes + the team JIT added, and the next sign-in adds it back. + +Roles aren't affected. JIT sets the organization role only when it first adds +the user. A later SCIM update can change that role, and the next sign-in +leaves the SCIM role in place. + +### Affected environments + +Docker organizations that use SCIM while JIT is still enabled. + +### Steps to replicate + +1. Enable SSO for your Docker organization. JIT is turned on by default. +1. Sign in through SSO with a user whose assertion includes a team. +1. Enable SCIM and synchronize groups that don't include that team. +1. The team membership from sign-in is removed. Signing in again adds it + back. + +### Solutions + +#### Turn off JIT provisioning (recommended) + +You can turn off JIT only while SCIM is enabled. Follow +[Disable JIT provisioning](/manuals/security/provisioning/just-in-time.md#disable). + +With JIT turned off, SCIM is the source for user creation, profile updates, +and group membership. + +#### Keep JIT enabled + +If you keep JIT enabled: + +- Match each user's email address exactly between the SSO assertion and SCIM. +- Send the same team memberships in the SSO assertion that SCIM group mapping + synchronizes. +- Expect each sign-in to update the full name from the SSO assertion. + +While JIT is on, you still assign users to the Docker application and +maintain group mappings in your IdP. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) +before you keep both enabled. + +## User is deactivated after a SCIM sync + +### Cause + +The user isn't assigned to the Docker application in the IdP. On the next +synchronization, Docker deactivates the Docker account. Removing the user +from a mapped group removes that user from the team only. + +### Solution + +1. Assign the user to the Docker application in your IdP. +1. Match the user's email address exactly between the SSO assertion and SCIM. +1. Trigger a SCIM synchronization in your IdP. +1. Confirm that the account is active and that the user belongs to the + expected teams. + +To use one provisioning source, turn off JIT after SCIM is working. You can +turn off JIT only while SCIM is enabled. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) +before you change the configuration. + +## SCIM updates don't apply to existing users + +### Cause + +SCIM can update any organization member whose email domain is verified on the +SSO connection, including users created through JIT or added manually. The +Docker account stays unchanged when that domain isn't verified on the +connection, or when the email address in the IdP differs from the account. + +### Solution + +1. Confirm that the user's email domain is verified on the SSO connection. +1. Match the email address in the IdP to the Docker account. +1. Assign the user to the Docker application and trigger provisioning. +1. In [Docker Home](https://app.docker.com), open **Members** and confirm the + user. + +If the account is still unlinked, remove that user and provision them again. + +> [!WARNING] +> +> Removing a user removes their resource ownership, such as repositories. +> Transfer ownership before you remove the user. diff --git a/content/manuals/security/roles-and-permissions/_index.md b/content/manuals/security/roles-and-permissions/_index.md new file mode 100644 index 000000000000..b3eb66bcbdba --- /dev/null +++ b/content/manuals/security/roles-and-permissions/_index.md @@ -0,0 +1,69 @@ +--- +title: Docker organization roles and permissions +linkTitle: Roles and permissions +description: >- + Choose core or custom roles to control access to repositories, teams, and + organization settings +keywords: >- + Docker organization roles, permissions, core roles, custom roles, Member, + Editor, Owner, access control, least privilege, Docker Business, security +tags: [admin] +weight: 40 +aliases: + - /admin/organization/roles/ + - /security/for-admins/roles-and-permissions/ + - /docker-hub/roles-and-permissions/ + - /enterprise/security/roles-and-permissions/ +grid: + - title: Core roles + description: >- + Compare permissions for the built-in Member, Editor, and Owner roles. + icon: shield-check + link: /security/roles-and-permissions/core-roles/ + - title: Custom roles + description: >- + Build permission sets that match your organization's access control needs. + icon: adjustments-horizontal + link: /security/roles-and-permissions/custom-roles/ + - title: Custom roles permissions + description: >- + Review every permission you can assign to a custom role. + icon: list-bullet + link: /security/roles-and-permissions/custom-roles/permissions-reference/ +--- + +{{< summary-bar feature_name="General admin" >}} + +Roles determine what members can do in your Docker organization. When you +invite a user or create a team, you assign a role that grants permissions +for repositories, teams, and organization settings. + +Docker provides two role types. Users and teams get either a core role or a +custom role, but not both. + +## Core roles + +Core roles are Docker's built-in Member, Editor, and Owner roles. Their +permissions are predefined. Use core roles when Docker's permission sets match +your organization's needs. + +## Custom roles + +Custom roles are permission sets you build by selecting individual +permissions, such as billing or team management. Use custom roles when you +need a combination that core roles don't offer. For example, you may create a custom role for a billing +administrator or a security auditor, or when you want to grant +least-privilege access. + +Custom roles require a Docker Business subscription. + +## Roles and team permissions + +Roles apply organization-wide. Team permissions apply to specific +repositories. The two systems work together: a user's role sets their +organization-wide access and team membership can extend their access to +individual repositories. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/roles-and-permissions/core-roles.md b/content/manuals/security/roles-and-permissions/core-roles.md new file mode 100644 index 000000000000..88cdc65f9098 --- /dev/null +++ b/content/manuals/security/roles-and-permissions/core-roles.md @@ -0,0 +1,140 @@ +--- +title: Docker core roles and permissions +linkTitle: Core roles +description: >- + Compare Member, Editor, and Owner permissions across Docker products +keywords: >- + Docker roles, core roles, Member role, Editor role, Owner role, organization + permissions, company owner, Docker Hub, Docker Scout, Docker Build Cloud, + OIDC, teams, access control, Docker Business, custom roles +weight: 10 +aliases: + - /enterprise/security/roles-and-permissions/core-roles/ +--- + +{{< summary-bar feature_name="General admin" >}} + +Docker organizations use built-in Member, Editor, and Owner roles with +predefined permissions. This reference compares their permissions across +Docker products. To assign a different combination of permissions, use +[custom roles](/manuals/security/roles-and-permissions/custom-roles/_index.md) +instead. + +## Core roles + +Docker organizations have three core roles: + +- Owner provides full administrative access. Owners can manage all + organization settings, including repositories, teams, members, billing, + and security features. +- Editor has partial administrative access. Editors can create, edit, and + delete repositories. They can also manage team permissions for + repositories. +- Member has basic, non-administrative access. Members can view + other organization members and pull images from repositories they have + access to. + +A company owner has the same organization-management permissions as an +organization owner. Content and registry permissions, such as repository +pull and push, don't apply to company owners. For more information, see +[Company overview](/manuals/accounts/company/_index.md). + +## Permissions reference + +### Content and registry + +These permissions apply organization-wide. + +| Permission | Member | Editor | Owner | +| :---------------------------------------------------- | :----- | :----- | :---- | +| Explore images and extensions | ✅ | ✅ | ✅ | +| Star, favorite, vote, and comment on content | ✅ | ✅ | ✅ | +| Pull images | ✅ | ✅ | ✅ | +| Create and publish an extension | ✅ | ✅ | ✅ | +| Become a Verified, Official, or Open Source publisher | ❌ | ❌ | ✅ | +| Edit and delete publisher repository logos | ❌ | ✅ | ✅ | +| Configure DVP analytics settings | ❌ | ✅ | ✅ | +| Observe content engagement as a publisher | ❌ | ❌ | ✅ | +| Create public and private repositories | ❌ | ✅ | ✅ | +| Disable public repositories | ❌ | ✅ | ✅ | +| Edit and delete repositories | ❌ | ✅ | ✅ | +| Manage tags | ❌ | ✅ | ✅ | +| View repository activity | ❌ | ❌ | ✅ | +| Set up Automated builds | ❌ | ❌ | ✅ | +| Edit build settings | ❌ | ❌ | ✅ | +| View teams | ✅ | ✅ | ✅ | +| Assign team permissions to repositories | ❌ | ✅ | ✅ | +| Manage OIDC connections | ❌ | ✅ | ✅ | + +You can grant repository permissions beyond a member's organization role: + +- Role permissions: Applied organization-wide (member or editor) +- Team permissions: Additional permissions for specific repositories + +To extend access to private repositories, configure team permissions. +Custom roles can grant organization-wide permissions to manage repositories +(create, edit, delete) but don't grant pull access to private repositories. +Use team permissions for that. + +### Organization management + +| Permission | Member | Editor | Owner | +| :---------------------------------------------------------------- | :----- | :----- | :---- | +| Create teams | ❌ | ❌ | ✅ | +| Manage teams (including delete) | ❌ | ❌ | ✅ | +| Configure the organization's settings (including linked services) | ❌ | ❌ | ✅ | +| Add organizations to a company | ❌ | ❌ | ✅ | +| Invite members | ❌ | ❌ | ✅ | +| Manage members | ❌ | ❌ | ✅ | +| Manage member roles and permissions | ❌ | ❌ | ✅ | +| View member activity | ❌ | ❌ | ✅ | +| Export and reporting | ❌ | ❌ | ✅ | +| Image Access Management | ❌ | ❌ | ✅ | +| Registry Access Management | ❌ | ❌ | ✅ | +| Namespace access control | ❌ | ❌ | ✅ | +| Set up Single Sign-On (SSO) and SCIM | ❌ | ❌ | ✅ \* | +| Require Docker Desktop sign-in | ❌ | ❌ | ✅ \* | +| Manage billing information (for example, billing address) | ❌ | ❌ | ✅ | +| Manage payment methods (for example, credit card or invoice) | ❌ | ❌ | ✅ | +| View billing history | ❌ | ❌ | ✅ | +| Manage subscriptions | ❌ | ❌ | ✅ | +| Manage seats | ❌ | ❌ | ✅ | +| Manage licenses | ❌ | ❌ | ✅ | +| Upgrade and downgrade plans | ❌ | ❌ | ✅ | + +> [!TIP] +> +> For more granular access control, +> [upgrade to a Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsEnterpriseCoreRoles) +> to use [custom roles](/manuals/security/roles-and-permissions/custom-roles/_index.md). + +_\* If not part of a company_ + +### Docker Scout + +| Permission | Member | Editor | Owner | +| :---------------------------------------------------- | :----- | :----- | :---- | +| View and compare analysis results | ✅ | ✅ | ✅ | +| Upload analysis records | ✅ | ✅ | ✅ | +| Activate and deactivate Docker Scout for a repository | ❌ | ✅ | ✅ | +| Create environments | ❌ | ❌ | ✅ | +| Manage registry integrations | ❌ | ❌ | ✅ | + +### Docker Build Cloud + +| Permission | Member | Editor | Owner | +| -------------------------- | :----- | :----- | :---- | +| Use a cloud builder | ✅ | ✅ | ✅ | +| Create and remove builders | ✅ | ✅ | ✅ | +| Configure builder settings | ✅ | ✅ | ✅ | +| Buy minutes | ❌ | ❌ | ✅ | +| Manage subscription | ❌ | ❌ | ✅ | + +## Next steps + +- [Custom roles](/manuals/security/roles-and-permissions/custom-roles/_index.md): + Create tailored permission sets on a Docker Business plan +- [Manage organization members](/manuals/accounts/organization/manage/members.md): + Invite users and assign roles +- [Company overview](/manuals/accounts/company/_index.md): Understand company + owner permissions versus organization owner permissions diff --git a/content/manuals/security/roles-and-permissions/custom-roles/_index.md b/content/manuals/security/roles-and-permissions/custom-roles/_index.md new file mode 100644 index 000000000000..a05c36638067 --- /dev/null +++ b/content/manuals/security/roles-and-permissions/custom-roles/_index.md @@ -0,0 +1,49 @@ +--- +title: Custom roles and permissions overview +linkTitle: Custom roles +description: >- + Use custom roles to assign tailored permissions to users and teams in + your Docker organization +keywords: >- + custom roles, custom permissions, permission sets, access control, + least privilege, Docker Business, Docker Home, organization + management, role assignment, teams, AI Governance, Docker Offload, + security +weight: 20 +grid: + - title: Manage custom roles + description: Create, edit, assign, and delete custom roles for users and teams. + icon: adjustments-horizontal + link: /security/roles-and-permissions/custom-roles/manage/ + - title: Permissions reference + description: Review every permission you can assign when building a custom role. + icon: list-bullet + link: /security/roles-and-permissions/custom-roles/permissions-reference/ +aliases: + - /enterprise/security/roles-and-permissions/custom-roles/ +--- + +{{< summary-bar feature_name="Custom roles" >}} + +Custom roles are permission sets that you choose to grant access to users +or teams based on specific use cases. Use custom roles when you need +specialized roles, department-specific access, or least-privilege grants. + +If Docker's predefined permission sets meet your needs, use +[core roles](/manuals/security/roles-and-permissions/_index.md) +instead. + +## Prerequisites + +- A Docker Business subscription +- Owner permissions in your Docker organization + +## Creating custom roles + +To create a custom role, you select permissions from organization management, +Docker Hub, billing, AI Governance, Docker Hardened Images, and Docker +Offload. You then assign custom roles you created to individual users or to teams. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/security/roles-and-permissions/custom-roles/manage.md b/content/manuals/security/roles-and-permissions/custom-roles/manage.md new file mode 100644 index 000000000000..d5292bfc586d --- /dev/null +++ b/content/manuals/security/roles-and-permissions/custom-roles/manage.md @@ -0,0 +1,166 @@ +--- +title: Manage custom roles in Docker Home +linkTitle: Manage +description: >- + Create, edit, assign, reassign, and delete custom roles in Docker Home + for organization users and teams +keywords: >- + custom roles, manage custom roles, role assignments, access control, + Docker Home, Docker Business, organization roles, permissions, teams +weight: 10 +aliases: + - /enterprise/security/roles-and-permissions/custom-roles/manage/ +--- + +{{< summary-bar feature_name="Custom roles" >}} + +Create custom roles, manage their permissions, and assign them to users +and teams. Use a custom role to grant only the permissions a user or +team needs. For a full list of permissions, see the +[custom roles permissions reference](permissions-reference.md). + +## Create a custom role + +Before you can assign a custom role, create one: + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Roles**, then **Create role**. +1. Define the role: + - Provide a **Label** + - Enter a unique **Name** identifier. The identifier is permanent. + - Add an optional **Description** +1. Set permissions for the role by expanding permission categories and + selecting the checkboxes for permissions. For a full list of available + permissions, see the + [custom roles permissions reference](permissions-reference.md). +1. Select **Review** to review the configuration and selected permissions. +1. Select **Create**. + +After you create a custom role, you can +[assign it to users or teams](#assign-custom-roles). + +## Edit a custom role + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Roles**. +1. Find your custom role in the list, then select the **Actions** menu. +1. Select **Edit**. +1. Edit any of the following settings: + - **Label** + - **Description** + - **Permissions** +1. Select **Save**. + +## Assign custom roles + +{{< tabs >}} +{{< tab name="Individual users" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Members**. +1. Locate the member you want to assign a custom role to, then select the + **Actions** menu. +1. Select **Change role**. +1. From the **Select a role** drop-down list, select your custom role. +1. Select **Save**. + +{{< /tab >}} +{{< tab name="Bulk users" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Members**. +1. Use the checkboxes in the username column to select the users you want + to assign a custom role to. +1. Select **Change role**. +1. From the **Select a role** drop-down list, select your custom role or + a core role. +1. Select **Save**. + +{{< /tab >}} +{{< tab name="Teams" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Teams**. +1. Locate the team you want to assign a custom role to, then select the + **Actions** menu. +1. Select **Assign role**. +1. Select your custom role, then select **Assign**. + +The role column updates to the newly assigned role. + +{{< /tab >}} +{{< /tabs >}} + +## View role assignments + +To see which users and teams are assigned to roles: + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Roles**. +1. In the roles list, view the **Users** and **Teams** columns for + assignment counts. +1. Select a role to view its permissions and assignments in detail. + +## Reassign custom roles + +{{< tabs >}} +{{< tab name="Individual users" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Members**. +1. Locate the member you want to reassign, then select the **Actions** + menu. +1. Select **Change role**. +1. From the **Select a role** drop-down list, select the new role. +1. Select **Save**. + +{{< /tab >}} +{{< tab name="Bulk users" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Members**. +1. Use the checkboxes in the username column to select the users you want + to reassign. +1. Select **Change role**. +1. From the **Select a role** drop-down list, select the new role. +1. Select **Save**. + +{{< /tab >}} +{{< tab name="Teams" >}} + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Teams**. +1. Locate the team, then select the **Actions** menu. +1. Select **Change role**. +1. From the drop-down list, select a role, then select **Save**. + +{{< /tab >}} +{{< /tabs >}} + +## Delete a custom role + +> [!IMPORTANT] +> +> Before you delete a custom role, reassign every user and team that uses +> it to a different role. + +1. Sign in to [Docker Home](https://app.docker.com). +1. Select **Roles**. +1. Find your custom role in the list, then select the **Actions** menu. +1. If the role has assigned users or teams: + - On the **Members** page, change the role for every user assigned to + this custom role + - On the **Teams** page, reassign every team that has this custom role +1. When no users or teams are assigned, return to **Roles**. +1. Find your custom role and select the **Actions** menu. +1. Select **Delete**. +1. In the confirmation window, select **Delete** to confirm. + +## Next steps + +- [Custom roles permissions reference](permissions-reference.md): Review + permissions you can grant to a custom role +- [Core roles and permissions](/manuals/security/roles-and-permissions/core-roles.md): + Compare built-in Member, Editor, and Owner permissions +- [Manage organization members](/manuals/accounts/organization/manage/members.md): + Invite and manage users in your organization diff --git a/content/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md b/content/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md new file mode 100644 index 000000000000..d0cafa418164 --- /dev/null +++ b/content/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md @@ -0,0 +1,101 @@ +--- +title: Custom role permissions reference +linkTitle: Permissions reference +description: >- + Permissions available for Docker custom roles across organization management, + Docker Hub, billing, licensing, AI Governance, Docker Hardened Images, + Docker Offload, and Docker Cloud Sandboxes. +keywords: >- + custom roles, custom role permissions, Docker, Docker Hub, organization + management, billing, licensing, licenses, AI Governance, access tokens, SSO, + SCIM, OIDC, DHI, Docker Offload, Cloud Sandboxes, security +weight: 20 +aliases: + - /enterprise/security/roles-and-permissions/custom-roles/permissions-reference/ +--- + +{{< summary-bar feature_name="Custom roles" >}} + +Custom roles use permissions from organization management, Docker Hub, +billing, licensing, AI Governance, Docker Hardened Images, Docker +Offload, and Docker Cloud Sandboxes. Use the following tables to [create +or edit a custom role](manage.md). + +## Organization management + +| Permission | Description | +| :-------------------------------- | :---------------------------------------------------------------------------------------------- | +| View teams | View teams and team members | +| Manage teams | Create, update, and delete teams and team members | +| Manage registry access | Control which registries members can access | +| Manage image access | Set policies for which images members can pull and use | +| Update organization information | Update organization information such as name and location | +| Member management | Manage organization members, invites, and roles | +| View custom roles | View existing custom roles and their permissions | +| Manage custom roles | Full access to custom role management and assignment | +| Manage organization access tokens | Create, update, and delete repositories in this org. Push/pull or registry actions not included | +| View activity logs | Access organization audit logs and activity history | +| View usage reports | Download organization usage reports (pulls, storage) | +| View domains | View domains and domain audit settings | +| Manage domains | Manage verified domains and domain audit settings | +| View SSO and SCIM | View single sign-on and user provisioning configurations | +| Manage SSO and SCIM | Full access to SSO and SCIM management | +| Manage Desktop settings | Configure Docker Desktop settings policies and view usage reports | +| View OIDC connections | View OIDC connections and their configuration | +| Manage OIDC connections | View, create, edit, and delete OIDC connections | + +## Docker Hub + +| Permission | Description | +| :--------------------------------- | :------------------------------------------------------------------------------------------- | +| View repositories | View repository details and contents | +| Manage repositories | Full repository management including settings, webhooks, privacy, Dockerfile, immutable tags | +| Manage repository team permissions | Add and remove teams from a repository, and manage team access level | + +## Billing + +| Permission | Description | +| :------------- | :----------------------------------------------- | +| View billing | View organization billing information | +| Manage billing | Complete access to managing organization billing | + +## Licensing + +| Permission | Description | +| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- | +| Manage licenses | Assign and revoke licenses for members and manage auto-assign rules. Does not include purchasing or changing the number of licenses | + +## AI Governance + +| Permission | Description | +| :-------------------- | :--------------------------------------------------- | +| View policies | View existing AI Governance policies and their rules | +| Manage policies | Full access to AI Governance policy management | +| View audit logs | View audit events for the organization | +| Manage audit settings | Update audit configuration for the organization | + +## DHI (Docker Hardened Images) + +| Permission | Description | +| :-------------------- | :-------------------------------------------------------------- | +| Create DHI mirrors | Create Docker Hardened Image mirror repositories | +| Manage customizations | Create, update, and delete Docker Hardened Image customizations | + +## Docker Offload + +| Permission | Description | +| :---------------- | :--------------------------------------------- | +| Offload Read-Only | View Offload account status, leases, and zones | + +## Cloud Sandboxes + +| Permission | Description | +| :------------------ | :------------------------------------ | +| Use Cloud Sandboxes | Create and use Docker Cloud Sandboxes | + +## Next steps + +- [Manage custom roles](manage.md): Create, assign, and delete custom + roles +- [Core roles and permissions](/manuals/security/roles-and-permissions/core-roles.md): + Compare built-in Member, Editor, and Owner permissions diff --git a/content/manuals/security/security-announcements.md b/content/manuals/security/security-announcements.md index d5931a860c01..5eb87c65bf14 100644 --- a/content/manuals/security/security-announcements.md +++ b/content/manuals/security/security-announcements.md @@ -1,206 +1,435 @@ --- -description: Docker security announcements -keywords: Docker, CVEs, security, notice, Log4J 2, Log4Shell, Text4Shell, announcements +description: >- + Security announcements for Docker products, including CVE fixes for Docker + Desktop, Docker Sandboxes, and Docker Official Images. +keywords: Docker security announcements, CVE, security advisory, vulnerability, + Docker Desktop security update, Log4j 2, Log4Shell, Text4Shell title: Docker security announcements -linkTitle: Security announcements +linkTitle: Announcements outputs: ["HTML", "markdown", "RSS"] layout: security-announcements -weight: 80 +weight: 1 toc_min: 1 toc_max: 2 +aliases: + - /security-announcements/ --- [Subscribe to security RSS feed](/security/security-announcements/index.xml) +## Docker Sandboxes response to eMudhra CA compromise + +_Last updated October 21, 2026_ + +Following the eMudhra certificate authority compromise, Docker rebuilt the +sandbox template images for all built-in kits with updated CA certificates. +Refresh cached images and update existing sandboxes to receive this protection. + +On October 20, 2026, researchers disclosed the compromise of private keys for +eight eMudhra intermediate certificate authorities. An attacker with these keys +could impersonate websites or services to clients that still trust the +compromised certificates. See the +[incident report](https://emudhra.we-have-a-problem.com/) for details. + +Updating the `sbx` CLI alone doesn't update existing sandboxes. + +### Recreate sandboxes with updated images + +Recreate each sandbox using `--pull always` to fetch the updated images instead +of reusing cached copies. For example, for a Codex sandbox, run these commands +on your host: + +```console +$ sbx stop +$ sbx rm +$ sbx create --name --pull always codex +``` + +Replace `codex` with your agent and restore any options you used to create the +sandbox, such as `--clone` or additional kits. Before removing a sandbox, save +any files you need from inside it, including unpushed commits in clone mode. +Removing a sandbox deletes its filesystem. + +Use `--pull always` when creating additional sandboxes from built-in kits. +Pulling updated images doesn't change sandboxes that already exist. + +### Update CA certificates in existing sandboxes + +If you need to keep an existing sandbox, update its `ca-certificates` package. +For Ubuntu-based Docker templates, run these commands on your host while the +sandbox is running: + +```console +$ sbx exec -- sudo apt-get update +$ sbx exec -- sudo apt-get install --only-upgrade -y ca-certificates +``` + +Restart applications in the sandbox after updating. Tools that bundle their +own CA certificates may also need updates. See the incident report's +[patched software versions](https://emudhra.we-have-a-problem.com/#developers). +For custom templates, update the trust store using the base distribution's +security updates and rebuild the images before creating more sandboxes. + +## Docker Sandboxes 0.42.0 security update: CVE-2026-77179 and CVE-2026-79994 + +Two vulnerabilities in Docker Sandboxes were fixed on September 7 in the +[0.42.0](/manuals/ai/sandboxes/release-notes.md#0420) release: + +- Addressed [CVE-2026-77179](https://www.cve.org/cverecord?id=CVE-2026-77179), + where the virtio-fs host server on macOS followed symlinks when reopening an + unlinked file from a stored path. A malicious guest could replace a parent + directory with a symlink, escape the shared workspace, and read or modify + arbitrary host files as the VMM user, potentially leading to code execution on + the host. Versions 0.28.0 up to but not including 0.42.0 on macOS are + affected. [Critical] +- Addressed [CVE-2026-79994](https://www.cve.org/cverecord?id=CVE-2026-79994), + where the guest-to-host Unix domain socket relay checked that a socket path + was inside an authorized workspace but reconnected using the path name. A + malicious guest could replace an intermediate directory with a symlink between + the check and the connection, causing the host to connect to an arbitrary + `AF_UNIX` socket outside the shared workspace and exposing data or host-side + capabilities provided by that socket. Versions 0.37.0 up to but not including + 0.42.0 are affected. [High] + +If you can't update to [0.42.0](/manuals/ai/sandboxes/release-notes.md#0420) or +later, use [clone mode](/manuals/ai/sandboxes/usage.md#clone-mode) and avoid +adding read-write host mounts. + +## Docker Desktop 4.86.0 security update: CVE-2026-17106 + +A vulnerability in Docker Desktop was fixed on August 10 in the +[4.86.0](/manuals/desktop/release-notes.md#4860) release: + +- Addressed CVE-2026-17106, a destination-escape flaw in `docker container cp`. + ## Docker Desktop 4.71.0 security update: CVE-2026-5843 -A vulnerability in Docker Desktop was fixed on April 27 in the [4.71.0](/manuals/desktop/release-notes.md#4710) release: +A vulnerability in Docker Desktop was fixed on April 27 in the +[4.71.0](/manuals/desktop/release-notes.md#4710) release: -- Addressed [CVE-2026-5843](https://www.cve.org/cverecord?id=CVE-2026-5843), container-to-host code execution in the Docker Model Runner MLX inference backend. +- Addressed [CVE-2026-5843](https://www.cve.org/cverecord?id=CVE-2026-5843), + container-to-host code execution in the Docker Model Runner MLX inference + backend. ## Docker Desktop 4.68.0 security update: CVE-2026-5817 -A vulnerability in Docker Desktop was fixed on April 7 in the [4.68.0](/manuals/desktop/release-notes.md#4680) release: +A vulnerability in Docker Desktop was fixed on April 7 in the +[4.68.0](/manuals/desktop/release-notes.md#4680) release: -- Addressed [CVE-2026-5817](https://www.cve.org/cverecord?id=CVE-2026-5817), container-to-host code execution in the Docker Model Runner vllm-metal inference backend. +- Addressed [CVE-2026-5817](https://www.cve.org/cverecord?id=CVE-2026-5817), + container-to-host code execution in the Docker Model Runner vllm-metal + inference backend. ## Docker Desktop 4.67.0 security update: CVE-2026-33990 -A vulnerability in Docker Desktop was fixed on March 30 in the [4.67.0](/manuals/desktop/release-notes.md#4670) release: - -- Addressed [CVE-2026-33990](https://www.cve.org/cverecord?id=CVE-2026-33990), SSRF in Docker Model Runner OCI Registry Client +A vulnerability in Docker Desktop was fixed on March 30 in the +[4.67.0](/manuals/desktop/release-notes.md#4670) release: +- Addressed [CVE-2026-33990](https://www.cve.org/cverecord?id=CVE-2026-33990), + SSRF in Docker Model Runner OCI Registry Client. ## Docker Desktop 4.62.0 security update: CVE-2026-28400 -A vulnerability in Docker Desktop was fixed on February 23 in the [4.62.0](/manuals/desktop/release-notes.md#4620) release: +A vulnerability in Docker Desktop was fixed on February 23 in the +[4.62.0](/manuals/desktop/release-notes.md#4620) release: -- Addressed [CVE-2026-28400](https://www.cve.org/cverecord?id=CVE-2026-28400), runtime flag injection in Docker Model Runner. +- Addressed [CVE-2026-28400](https://www.cve.org/cverecord?id=CVE-2026-28400), + runtime flag injection in Docker Model Runner. ## Docker Desktop 4.62.0 security update: CVE-2026-2664 -A vulnerability in Docker Desktop was fixed on February 23 in the [4.62.0](/manuals/desktop/release-notes.md#4620) release: +A vulnerability in Docker Desktop was fixed on February 23 in the +[4.62.0](/manuals/desktop/release-notes.md#4620) release: -- Fixed [CVE-2026-2664](https://www.cve.org/cverecord?id=CVE-2026-2664), out of bounds read in gRPC-FUSE kernel module. +- Fixed [CVE-2026-2664](https://www.cve.org/cverecord?id=CVE-2026-2664), out of + bounds read in gRPC-FUSE kernel module. ## Docker Desktop 4.54.0 security update: CVE-2025-13743 -A vulnerability in Docker Desktop was fixed on December 4 in the [4.54.0](/manuals/desktop/release-notes.md#4540) release: +A vulnerability in Docker Desktop was fixed on December 4 in the +[4.54.0](/manuals/desktop/release-notes.md#4540) release: -- Fixed [CVE-2025-13743](https://www.cve.org/cverecord?id=CVE-2025-13743) where Docker Desktop diagnostics bundles were found to include expired Hub PATs in log output due to error object serialization. +- Fixed [CVE-2025-13743](https://www.cve.org/cverecord?id=CVE-2025-13743) where + Docker Desktop diagnostics bundles were found to include expired Hub PATs in + log output due to error object serialization. ## Docker Desktop 4.49.0 security update: CVE-2025-9164 -A vulnerability in Docker Desktop for Windows was fixed on October 23 in the [4.49.0](/manuals/desktop/release-notes.md#4490) release: +A vulnerability in Docker Desktop for Windows was fixed on October 23 in the +[4.49.0](/manuals/desktop/release-notes.md#4490) release: -- Fixed [CVE-2025-9164](https://www.cve.org/cverecord?id=CVE-2025-9164) where the Docker Desktop for Windows installer was vulnerable to DLL hijacking due to insecure DLL search order. The installer searches for required DLLs in the user's Downloads folder before checking system directories, allowing local privilege escalation through malicious DLL placement. +- Fixed [CVE-2025-9164](https://www.cve.org/cverecord?id=CVE-2025-9164) where + the Docker Desktop for Windows installer was vulnerable to DLL hijacking due + to insecure DLL search order. The installer searches for required DLLs in the + user's Downloads folder before checking system directories, allowing local + privilege escalation through malicious DLL placement. ## Docker Desktop 4.47.0 security update: CVE-2025-10657 -A vulnerability in Docker Desktop was fixed on September 25 in the [4.47.0](/manuals/desktop/release-notes.md#4470) release: +A vulnerability in Docker Desktop was fixed on September 25 in the +[4.47.0](/manuals/desktop/release-notes.md#4470) release: -- Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where the Enhanced Container Isolation [Docker Socket command restrictions](../enterprise/security/hardened-desktop/enhanced-container-isolation/config.md#command-restrictions) feature was not working properly in Docker Desktop 4.46.0 only (the configuration for it was being ignored). +- Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where + the Enhanced Container Isolation + [Docker Socket command restrictions](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/config.md#command-restrictions) + feature was not working properly in Docker Desktop 4.46.0 only (the + configuration for it was being ignored). ## Docker Desktop 4.44.3 security update: CVE-2025-9074 _Last updated August 20, 2025_ -A vulnerability in Docker Desktop was fixed on August 20 in the [4.44.3](/manuals/desktop/release-notes.md#4443) release: - -- Fixed [CVE-2025-9074](https://www.cve.org/CVERecord?id=CVE-2025-9074) where a malicious container running on Docker Desktop could access the Docker Engine and launch additional containers without requiring the Docker socket to be mounted. This could allow unauthorized access to user files on the host system. Enhanced Container Isolation (ECI) does not mitigate this vulnerability. +A vulnerability in Docker Desktop was fixed on August 20 in the +[4.44.3](/manuals/desktop/release-notes.md#4443) release: +- Fixed [CVE-2025-9074](https://www.cve.org/CVERecord?id=CVE-2025-9074) where a + malicious container running on Docker Desktop could access the Docker Engine + and launch additional containers without requiring the Docker socket to be + mounted. This could allow unauthorized access to user files on the host + system. Enhanced Container Isolation (ECI) does not mitigate this + vulnerability. ## Docker Desktop 4.44.0 security update: CVE-2025-23266 _Last updated July 31, 2025_ -We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266), a critical vulnerability affecting the NVIDIA Container Toolkit in CDI mode up to version 1.17.7. Docker Desktop includes version 1.17.8, which is not impacted. However, older versions of Docker Desktop that bundled earlier toolkit versions may be affected if CDI mode was manually enabled. Upgrade to Docker Desktop 4.44 or later to ensure you're using the patched version. +Docker is aware of +[CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266), a critical +vulnerability affecting the NVIDIA Container Toolkit in CDI mode up to version +1.17.7. Docker Desktop includes version 1.17.8, which is not impacted. However, +older versions of Docker Desktop that bundled earlier toolkit versions may be +affected if CDI mode was manually enabled. Upgrade to Docker Desktop 4.44 or +later to ensure you're using the patched version. ## Docker Desktop 4.43.0 security update: CVE-2025-6587 -_Last updated July 03, 2025_ +_Last updated July 3, 2025_ -A vulnerability in Docker Desktop was fixed on July 03 in the [4.43.0](/manuals/desktop/release-notes.md#4430) release: +A vulnerability in Docker Desktop was fixed on July 3 in the +[4.43.0](/manuals/desktop/release-notes.md#4430) release: -- Fixed [CVE-2025-6587](https://www.cve.org/CVERecord?id=CVE-2025-6587) where sensitive system environment variables were included in Docker Desktop diagnostic logs, allowing for potential secret exposure. +- Fixed [CVE-2025-6587](https://www.cve.org/CVERecord?id=CVE-2025-6587) where + sensitive system environment variables were included in Docker Desktop + diagnostic logs, allowing for potential secret exposure. -## Docker Desktop 4.41.0 Security Update: CVE-2025-3224, CVE-2025-4095, and CVE-2025-3911 +## Docker Desktop 4.41.0 security update: CVE-2025-3224, CVE-2025-4095, and CVE-2025-3911 _Last updated May 15, 2025_ -Three vulnerabilities in Docker Desktop were fixed on April 28 in the [4.41.0](/manuals/desktop/release-notes.md#4410) release. +Three vulnerabilities in Docker Desktop were fixed on April 28 in the +[4.41.0](/manuals/desktop/release-notes.md#4410) release. -- Fixed [CVE-2025-3224](https://www.cve.org/CVERecord?id=CVE-2025-3224) allowing an attacker with access to a user machine to perform an elevation of privilege when Docker Desktop updates. -- Fixed [CVE-2025-4095](https://www.cve.org/CVERecord?id=CVE-2025-4095) where Registry Access Management (RAM) policies were not enforced when using a MacOS configuration profile, allowing users to pull images from unapproved registries. -- Fixed [CVE-2025-3911](https://www.cve.org/CVERecord?id=CVE-2025-3911) allowing an attacker with read access to a user's machine to obtain sensitive information from Docker Desktop log files, including environment variables configured for running containers. +- Fixed [CVE-2025-3224](https://www.cve.org/CVERecord?id=CVE-2025-3224) allowing + an attacker with access to a user machine to perform an elevation of privilege + when Docker Desktop updates. +- Fixed [CVE-2025-4095](https://www.cve.org/CVERecord?id=CVE-2025-4095) where + Registry Access Management (RAM) policies were not enforced when using a MacOS + configuration profile, allowing users to pull images from unapproved + registries. +- Fixed [CVE-2025-3911](https://www.cve.org/CVERecord?id=CVE-2025-3911) allowing + an attacker with read access to a user's machine to obtain sensitive + information from Docker Desktop log files, including environment variables + configured for running containers. -We strongly encourage you to update to Docker Desktop [4.41.0](/manuals/desktop/release-notes.md#4410). +Update to Docker Desktop +[4.41.0](/manuals/desktop/release-notes.md#4410). -## Docker Desktop 4.34.2 Security Update: CVE-2024-8695 and CVE-2024-8696 +## Docker Desktop 4.34.2 security update: CVE-2024-8695 and CVE-2024-8696 _Last updated September 13, 2024_ -Two remote code execution (RCE) vulnerabilities in Docker Desktop related to Docker Extensions were reported by [Cure53](https://cure53.de/) and were fixed on September 12 in the [4.34.2](/manuals/desktop/release-notes.md#4342) release. - -- [CVE-2024-8695](https://www.cve.org/cverecord?id=CVE-2024-8695): A remote code execution (RCE) vulnerability via crafted extension description/changelog could be abused by a malicious extension in Docker Desktop before 4.34.2. [Critical] -- [CVE-2024-8696](https://www.cve.org/cverecord?id=CVE-2024-8696): A remote code execution (RCE) vulnerability via crafted extension publisher-url/additional-urls could be abused by a malicious extension in Docker Desktop before 4.34.2. [High] - -No existing extensions exploiting the vulnerabilities were found in the Extensions Marketplace. The Docker Team will be closely monitoring and diligently reviewing any requests for publishing new extensions. - -We strongly encourage you to update to Docker Desktop [4.34.2](/manuals/desktop/release-notes.md#4342). If you are unable to update promptly, you can [disable Docker Extensions](/manuals/extensions/settings-feedback.md#turn-on-or-turn-off-extensions) as a workaround. +Two remote code execution (RCE) vulnerabilities in Docker Desktop related to +Docker Extensions were reported by [Cure53](https://cure53.de/) and were fixed +on September 12 in the [4.34.2](/manuals/desktop/release-notes.md#4342) release. + +- [CVE-2024-8695](https://www.cve.org/cverecord?id=CVE-2024-8695): A remote code + execution (RCE) vulnerability via crafted extension description/changelog + could be abused by a malicious extension in Docker Desktop before 4.34.2. + [Critical] +- [CVE-2024-8696](https://www.cve.org/cverecord?id=CVE-2024-8696): A remote code + execution (RCE) vulnerability via crafted extension + publisher-url/additional-urls could be abused by a malicious extension in + Docker Desktop before 4.34.2. [High] + +No existing extensions exploiting the vulnerabilities were found in the +Extensions Marketplace. The Docker Team will be closely monitoring and +diligently reviewing any requests for publishing new extensions. + +Update to Docker Desktop +[4.34.2](/manuals/desktop/release-notes.md#4342). If you are unable to update +promptly, you can +[disable Docker Extensions](/manuals/extensions/settings-feedback.md#turn-on-or-turn-off-extensions) +as a workaround. ## Deprecation of password logins on CLI when SSO enforced -_Last updated July, 2024_ +_Last updated July 2024_ -When [SSO enforcement](/manuals/enterprise/security/single-sign-on/connect.md) was first introduced, Docker provided a grace period to continue to let passwords be used on the Docker CLI when authenticating to Docker Hub. This was allowed so organizations could more easily use SSO enforcement. It is recommended that administrators configuring SSO encourage users using the CLI [to switch over to Personal Access Tokens](/manuals/enterprise/security/single-sign-on/_index.md#prerequisites) in anticipation of this grace period ending. +When +[SSO enforcement](/manuals/security/authentication/single-sign-on/connect.md) +was first introduced, Docker provided a grace period to continue to let +passwords be used on the Docker CLI when authenticating to Docker Hub. This was +allowed so organizations could adopt SSO enforcement. It is recommended that +administrators configuring SSO encourage users using the CLI +[to switch over to Personal Access Tokens](/manuals/security/authentication/single-sign-on/_index.md#prerequisites) +in anticipation of this grace period ending. -On September 16, 2024 the grace period will end and passwords will no longer be able to authenticate to Docker Hub via the Docker CLI when SSO is enforced. Affected users are required to switch over to using PATs to continue signing in. +On September 16, 2024, the grace period ended and passwords can no longer +authenticate to Docker Hub via the Docker CLI when SSO is enforced. Affected +users are required to switch over to using PATs to continue signing in. -At Docker, we want the experience to be the most secure for our developers and organizations and this deprecation is an essential step in that direction. +This deprecation is a step toward a secure experience for developers and +organizations. ## SOC 2 Type 2 attestation and ISO 27001 certification -_Last updated June, 2024_ +_Last updated June 2024_ -Docker is pleased to announce that we have received our SOC 2 Type 2 attestation and ISO 27001 certification with no exceptions or major non-conformities. +Docker received its SOC 2 Type 2 attestation and ISO 27001 certification with +no exceptions or major non-conformities. -Security is a fundamental pillar to Docker's operations, which is embedded into our overall mission and company strategy. Docker's products are core to our user community and our SOC 2 Type 2 attestation and ISO 27001 certification demonstrate Docker's ongoing commitment to security to our user base. +Security is part of Docker's operations, mission, and company strategy. +Docker's products are core to the user community, and the SOC 2 Type 2 +attestation and ISO 27001 certification demonstrate Docker's ongoing commitment +to security. -For more information, see the [Blog announcement](https://www.docker.com/blog/docker-announces-soc-2-type-2-attestation-iso-27001-certification/). +For more information, see the +[Blog announcement](https://www.docker.com/blog/docker-announces-soc-2-type-2-attestation-iso-27001-certification/). -## Docker Security Advisory: Multiple Vulnerabilities in runc, BuildKit, and Moby +## Docker security advisory: multiple vulnerabilities in runc, BuildKit, and Moby _Last updated February 2, 2024_ -We at Docker prioritize the security and integrity of our software and the trust of our users. Security researchers at Snyk Labs identified and reported four security vulnerabilities in the container ecosystem. One of the vulnerabilities, [CVE-2024-21626](https://scout.docker.com/v/CVE-2024-21626), concerns the runc container runtime, and the other three affect BuildKit ([CVE-2024-23651](https://scout.docker.com/v/CVE-2024-23651), [CVE-2024-23652](https://scout.docker.com/v/CVE-2024-23652), and [CVE-2024-23653](https://scout.docker.com/v/CVE-2024-23653)). We want to assure our community that our team, in collaboration with the reporters and open source maintainers, has been diligently working on coordinating and implementing necessary remediations. - -We are committed to maintaining the highest security standards. We have published patched versions of runc, BuildKit, and Moby on January 31 and released an update for Docker Desktop on February 1 to address these vulnerabilities. Additionally, our latest BuildKit and Moby releases included fixes for [CVE-2024-23650](https://scout.docker.com/v/CVE-2024-23650) and [CVE-2024-24557](https://scout.docker.com/v/CVE-2024-24557), discovered respectively by an independent researcher and through Docker's internal research initiatives. - -| | Versions Impacted | -|:-----------------------|:--------------------------| -| `runc` | <= 1.1.11 | -| `BuildKit` | <= 0.12.4 | -| `Moby (Docker Engine)` | <= 25.0.1 and <= 24.0.8 | -| `Docker Desktop` | <= 4.27.0 | +Docker prioritizes the security and integrity of its software and the trust of +its users. Security researchers at Snyk Labs identified and reported four +security vulnerabilities in the container ecosystem. One of the vulnerabilities, +[CVE-2024-21626](https://scout.docker.com/v/CVE-2024-21626), concerns the runc +container runtime, and the other three affect BuildKit +([CVE-2024-23651](https://scout.docker.com/v/CVE-2024-23651), +[CVE-2024-23652](https://scout.docker.com/v/CVE-2024-23652), and +[CVE-2024-23653](https://scout.docker.com/v/CVE-2024-23653)). Docker, in +collaboration with the reporters and open source maintainers, coordinated and +implemented the remediations. + +Docker published patched versions of runc, BuildKit, and Moby on January 31 and +released an update for Docker Desktop on February 1 to address these +vulnerabilities. The latest BuildKit and Moby releases also included fixes for +[CVE-2024-23650](https://scout.docker.com/v/CVE-2024-23650) and +[CVE-2024-24557](https://scout.docker.com/v/CVE-2024-24557), discovered +respectively by an independent researcher and through Docker's internal research +initiatives. + +| | Versions impacted | +| :--------------------- | :---------------------- | +| `runc` | <= 1.1.11 | +| `BuildKit` | <= 0.12.4 | +| `Moby (Docker Engine)` | <= 25.0.1 and <= 24.0.8 | +| `Docker Desktop` | <= 4.27.0 | ### What should I do if I'm on an affected version? -If you are using affected versions of runc, BuildKit, Moby, or Docker Desktop, make sure to update to the latest versions, linked in the following table: - -| | Patched Versions | -|:-----------------------|:--------------------------| -| `runc` | >= [1.1.12](https://github.com/opencontainers/runc/releases/tag/v1.1.12) | -| `BuildKit` | >= [0.12.5](https://github.com/moby/buildkit/releases/tag/v0.12.5) | -| `Moby (Docker Engine)` | >= [25.0.2](https://github.com/moby/moby/releases/tag/v25.0.2) and >= [24.0.9](https://github.com/moby/moby/releases/tag/v24.0.9) | -| `Docker Desktop` | >= [4.27.1](/manuals/desktop/release-notes.md#4271) | - - -If you are unable to update to an unaffected version promptly, follow these best practices to mitigate risk: - -* Only use trusted Docker images (such as [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images)). -* Don't build Docker images from untrusted sources or untrusted Dockerfiles. -* If you are a Docker Business customer using Docker Desktop and unable to update to v4.27.1, make sure to enable [Hardened Docker Desktop](/manuals/enterprise/security/hardened-desktop/_index.md) features such as: - * [Enhanced Container Isolation](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md), which mitigates the impact of CVE-2024-21626 in the case of running containers from malicious images. - * [Image Access Management](/manuals/enterprise/security/hardened-desktop/image-access-management.md), and [Registry Access Management](/manuals/enterprise/security/hardened-desktop/registry-access-management.md), which give organizations control over which images and repositories their users can access. -* For CVE-2024-23650, CVE-2024-23651, CVE-2024-23652, and CVE-2024-23653, avoid using BuildKit frontend from an untrusted source. A frontend image is usually specified as the #syntax line on your Dockerfile, or with `--frontend` flag when using the `buildctl build` command. -* To mitigate CVE-2024-24557, make sure to either use BuildKit or disable caching when building images. From the CLI this can be done via the `DOCKER_BUILDKIT=1` environment variable (default for Moby >= v23.0 if the buildx plugin is installed) or the `--no-cache flag`. If you are using the HTTP API directly or through a client, the same can be done by setting `nocache` to `true` or `version` to `2` for the [/build API endpoint](https://docs.docker.com/reference/api/engine/version/v1.44/#tag/Image/operation/ImageBuild). +If you are using affected versions of runc, BuildKit, Moby, or Docker Desktop, +make sure to update to the latest versions, linked in the following table: + +| | Patched versions | +| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | +| `runc` | >= [1.1.12](https://github.com/opencontainers/runc/releases/tag/v1.1.12) | +| `BuildKit` | >= [0.12.5](https://github.com/moby/buildkit/releases/tag/v0.12.5) | +| `Moby (Docker Engine)` | >= [25.0.2](https://github.com/moby/moby/releases/tag/v25.0.2) and >= [24.0.9](https://github.com/moby/moby/releases/tag/v24.0.9) | +| `Docker Desktop` | >= [4.27.1](/manuals/desktop/release-notes.md#4271) | + +If you are unable to update to an unaffected version promptly, follow these best +practices to mitigate risk: + +- Only use trusted Docker images (such as + [Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images)). +- Don't build Docker images from untrusted sources or untrusted Dockerfiles. +- If you are a Docker Business customer using Docker Desktop and unable to + update to v4.27.1, make sure to enable + [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md) + features such as: + - [Enhanced Container Isolation](/manuals/desktop/enterprise/hardened-desktop/enhanced-container-isolation/_index.md), + which mitigates the impact of CVE-2024-21626 in the case of running + containers from malicious images. + - [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md), + and + [Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md), + which give organizations control over which images and repositories their + users can access. +- For CVE-2024-23650, CVE-2024-23651, CVE-2024-23652, and CVE-2024-23653, avoid + using BuildKit frontend from an untrusted source. A frontend image is usually + specified as the #syntax line on your Dockerfile, or with `--frontend` flag + when using the `buildctl build` command. +- To mitigate CVE-2024-24557, make sure to either use BuildKit or disable + caching when building images. From the CLI this can be done via the + `DOCKER_BUILDKIT=1` environment variable (default for Moby >= v23.0 if the + Buildx plugin is installed) or the `--no-cache flag`. If you are using the + HTTP API directly or through a client, the same can be done by setting + `nocache` to `true` or `version` to `2` for the + [/build API endpoint](https://docs.docker.com/reference/api/engine/version/v1.44/#tag/Image/operation/ImageBuild). ### Technical details and impact #### CVE-2024-21626 (High) -In runc v1.1.11 and earlier, due to certain leaked file descriptors, an attacker can gain access to the host filesystem by causing a newly-spawned container process (from `runc exec`) to have a working directory in the host filesystem namespace, or by tricking a user to run a malicious image and allow a container process to gain access to the host filesystem through `runc run`. The attacks can also be adapted to overwrite semi-arbitrary host binaries, allowing for complete container escapes. Note that when using higher-level runtimes (such as Docker or Kubernetes), this vulnerability can be exploited by running a malicious container image without additional configuration or by passing specific workdir options when starting a container. The vulnerability can also be exploited from within Dockerfiles in the case of Docker. +In runc v1.1.11 and earlier, due to certain leaked file descriptors, an attacker +can gain access to the host filesystem by causing a newly-spawned container +process (from `runc exec`) to have a working directory in the host filesystem +namespace, or by tricking a user to run a malicious image and allow a container +process to gain access to the host filesystem through `runc run`. The attacks +can also be adapted to overwrite semi-arbitrary host binaries, allowing for +complete container escapes. Note that when using higher-level runtimes (such as +Docker or Kubernetes), this vulnerability can be exploited by running a +malicious container image without additional configuration or by passing +specific workdir options when starting a container. The vulnerability can also +be exploited from within Dockerfiles in the case of Docker. _The issue has been fixed in runc v1.1.12._ #### CVE-2024-23651 (High) -In BuildKit <= v0.12.4, two malicious build steps running in parallel sharing the same cache mounts with subpaths could cause a race condition, leading to files from the host system being accessible to the build container. This will only occur if a user is trying to build a Dockerfile of a malicious project. +In BuildKit <= v0.12.4, two malicious build steps running in parallel sharing +the same cache mounts with subpaths could cause a race condition, leading to +files from the host system being accessible to the build container. This will +only occur if a user is trying to build a Dockerfile of a malicious project. _The issue has been fixed in BuildKit v0.12.5._ #### CVE-2024-23652 (High) -In BuildKit <= v0.12.4, a malicious BuildKit frontend or Dockerfile using `RUN --mount` could trick the feature that removes empty files created for the mountpoints into removing a file outside the container from the host system. This will only occur if a user is using a malicious Dockerfile. +In BuildKit <= v0.12.4, a malicious BuildKit frontend or Dockerfile using +`RUN --mount` could trick the feature that removes empty files created for the +mountpoints into removing a file outside the container from the host system. +This will only occur if a user is using a malicious Dockerfile. _The issue has been fixed in BuildKit v0.12.5._ #### CVE-2024-23653 (High) -In addition to running containers as build steps, BuildKit also provides APIs for running interactive containers based on built images. In BuildKit <= v0.12.4, it is possible to use these APIs to ask BuildKit to run a container with elevated privileges. Normally, running such containers is only allowed if special `security.insecure` entitlement is enabled both by buildkitd configuration and allowed by the user initializing the build request. +In addition to running containers as build steps, BuildKit also provides APIs +for running interactive containers based on built images. In BuildKit <= +v0.12.4, it is possible to use these APIs to ask BuildKit to run a container +with elevated privileges. Normally, running such containers is only allowed if +special `security.insecure` entitlement is enabled both by buildkitd +configuration and allowed by the user initializing the build request. _The issue has been fixed in BuildKit v0.12.5._ #### CVE-2024-23650 (Medium) -In BuildKit <= v0.12.4, a malicious BuildKit client or frontend could craft a request that could lead to BuildKit daemon crashing with a panic. +In BuildKit <= v0.12.4, a malicious BuildKit client or frontend could craft a +request that could lead to BuildKit daemon crashing with a panic. _The issue has been fixed in BuildKit v0.12.5._ #### CVE-2024-24557 (Medium) -In Moby <= v25.0.1 and <= v24.0.8, the classic builder cache system is prone to cache poisoning if the image is built FROM scratch. Also, changes to some instructions (most important being `HEALTHCHECK` and `ONBUILD`) would not cause a cache miss. An attacker with knowledge of the Dockerfile someone is using could poison their cache by making them pull a specially crafted image that would be considered a valid cache candidate for some build steps. +In Moby <= v25.0.1 and <= v24.0.8, the classic builder cache system is prone to +cache poisoning if the image is built FROM scratch. Also, changes to some +instructions (most important being `HEALTHCHECK` and `ONBUILD`) would not cause +a cache miss. An attacker with knowledge of the Dockerfile someone is using +could poison their cache by making them pull a specially crafted image that +would be considered a valid cache candidate for some build steps. _The issue has been fixed in Moby >= v25.0.2 and >= v24.0.9._ @@ -208,49 +437,65 @@ _The issue has been fixed in Moby >= v25.0.2 and >= v24.0.9._ #### Docker Desktop -Docker Desktop v4.27.0 and earlier are affected. Docker Desktop v4.27.1 was released on February 1 and includes runc, BuildKit, and dockerd binaries patches. In addition to updating to this new version, we encourage all Docker users to diligently use Docker images and Dockerfiles and ensure you only use trusted content in your builds. +Docker Desktop v4.27.0 and earlier are affected. Docker Desktop v4.27.1 was +released on February 1 and includes runc, BuildKit, and dockerd binaries +patches. In addition to updating to this new version, use only trusted Docker +images and Dockerfiles in your builds. -As always, you should check Docker Desktop system requirements for your operating system ([Windows](/manuals/desktop/setup/install/windows-install.md#system-requirements), [Linux](/manuals/desktop/setup/install/linux/_index.md#general-system-requirements), [Mac](/manuals/desktop/setup/install/mac-install.md#system-requirements)) before updating to ensure full compatibility. +As always, you should check Docker Desktop system requirements for your +operating system +([Windows](/manuals/desktop/setup/install/windows-install.md#system-requirements), +[Linux](/manuals/desktop/setup/install/linux/_index.md#general-system-requirements), +[Mac](/manuals/desktop/setup/install/mac-install.md#system-requirements)) before +updating to ensure full compatibility. #### Docker Build Cloud -Any new Docker Build Cloud builder instances will be provisioned with the latest Docker Engine and BuildKit versions and will, therefore, be unaffected by these CVEs. Updates have also been rolled out to existing Docker Build Cloud builders. +Any new Docker Build Cloud builder instances will be provisioned with the latest +Docker Engine and BuildKit versions and will, therefore, be unaffected by these +CVEs. Updates have also been rolled out to existing Docker Build Cloud builders. _No other Docker products are affected by these vulnerabilities._ ### Advisory links -* Runc - * [CVE-2024-21626](https://github.com/opencontainers/runc/security/advisories/GHSA-xr7r-f8xq-vfvv) -* BuildKit - * [CVE-2024-23650](https://github.com/moby/buildkit/security/advisories/GHSA-9p26-698r-w4hx) - * [CVE-2024-23651](https://github.com/moby/buildkit/security/advisories/GHSA-m3r6-h7wv-7xxv) - * [CVE-2024-23652](https://github.com/moby/buildkit/security/advisories/GHSA-4v98-7qmw-rqr8) - * [CVE-2024-23653](https://github.com/moby/buildkit/security/advisories/GHSA-wr6v-9f75-vh2g) -* Moby - * [CVE-2024-24557](https://github.com/moby/moby/security/advisories/GHSA-xw73-rw38-6vjc) +- Runc + - [CVE-2024-21626](https://github.com/opencontainers/runc/security/advisories/GHSA-xr7r-f8xq-vfvv) +- BuildKit + - [CVE-2024-23650](https://github.com/moby/buildkit/security/advisories/GHSA-9p26-698r-w4hx) + - [CVE-2024-23651](https://github.com/moby/buildkit/security/advisories/GHSA-m3r6-h7wv-7xxv) + - [CVE-2024-23652](https://github.com/moby/buildkit/security/advisories/GHSA-4v98-7qmw-rqr8) + - [CVE-2024-23653](https://github.com/moby/buildkit/security/advisories/GHSA-wr6v-9f75-vh2g) +- Moby + - [CVE-2024-24557](https://github.com/moby/moby/security/advisories/GHSA-xw73-rw38-6vjc) ## Text4Shell CVE-2022-42889 _Last updated October 2022_ -[CVE-2022-42889](https://nvd.nist.gov/vuln/detail/CVE-2022-42889) has been discovered in the popular Apache Commons Text library. Versions of this library up to but not including 1.10.0 are affected by this vulnerability. +[CVE-2022-42889](https://nvd.nist.gov/vuln/detail/CVE-2022-42889) has been +discovered in the popular Apache Commons Text library. Versions of this library +up to but not including 1.10.0 are affected by this vulnerability. -We strongly encourage you to update to the latest version of [Apache Commons Text](https://commons.apache.org/proper/commons-text/download_text.cgi). +Update to the latest version of +[Apache Commons Text](https://commons.apache.org/proper/commons-text/download_text.cgi). ### Scan images on Docker Hub Docker Hub security scans triggered after 1200 UTC 21 October 2021 are now correctly identifying the Text4Shell CVE. Scans before this date do not -currently reflect the status of this vulnerability. Therefore, we recommend that -you trigger scans by pushing new images to Docker Hub to view the status of -the Text4Shell CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/repos/manage/vulnerability-scanning.md). +currently reflect the status of this vulnerability. Trigger scans by pushing +new images to Docker Hub to view the status of the Text4Shell CVE in the +vulnerability report. For detailed instructions, see +[Scan images on Docker Hub](/manuals/docker-hub/repos/manage/vulnerability-scanning.md). ### Docker Official Images impacted by CVE-2022-42889 -A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of -Apache Commons Text. The following lists Docker Official Images that -may contain the vulnerable versions of Apache Commons Text: +A number of +[Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images) +contain the vulnerable versions of Apache Commons Text. The following lists +Docker Official Images that may contain the vulnerable versions of Apache +Commons Text: - [bonita](https://hub.docker.com/_/bonita) - [Couchbase](https://hub.docker.com/_/couchbase) @@ -260,68 +505,82 @@ may contain the vulnerable versions of Apache Commons Text: - [solr](https://hub.docker.com/_/solr) - [xwiki](https://hub.docker.com/_/xwiki) -We have updated -Apache Commons Text in these images to the latest version. Some of these images may not be -vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites. +Docker updated Apache Commons Text in these images to the latest version. Some +of these images may not be vulnerable for other reasons. Also review the +guidelines published on the upstream websites. ## Log4j 2 CVE-2021-44228 _Last updated December 2021_ -The [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) vulnerability in Log4j 2, a very common Java logging library, allows remote code execution, often from a context that is easily available to an attacker. For example, it was found in Minecraft servers which allowed the commands to be typed into chat logs as these were then sent to the logger. This makes it a very serious vulnerability, as the logging library is used so widely and it may be simple to exploit. Many open source maintainers are working hard with fixes and updates to the software ecosystem. +The [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) +vulnerability in Log4j 2, a common Java logging library, allows remote code +execution, often from a context that is available to an attacker. For example, +it was found in Minecraft servers which allowed the commands to be typed into +chat logs as these were then sent to the logger. This makes it a serious +vulnerability, as the logging library is used so widely and it may be simple +to exploit. Many open source maintainers are working hard with fixes and +updates to the software ecosystem. -The vulnerable versions of Log4j 2 are versions 2.0 to version 2.14.1 inclusive. The first fixed version is 2.15.0. We strongly encourage you to update to the [latest version](https://logging.apache.org/log4j/2.x/download.html) if you can. If you are using a version before 2.0, you are also not vulnerable. +The vulnerable versions of Log4j 2 are versions 2.0 to version 2.14.1 inclusive. +The first fixed version is 2.15.0. Update to the +[latest version](https://logging.apache.org/log4j/2.x/download.html) if you can. +If you are using a version before 2.0, you are also not vulnerable. You may not be vulnerable if you are using these versions, as your configuration -may already mitigate this, or the things you -log may not include any user input. This may be difficult to validate however -without understanding all the code paths that may log in detail, and where they -may get input from. So you probably will want to upgrade all code using -vulnerable versions. +may already mitigate this, or the things you log may not include any user input. +This may be difficult to validate however without understanding all the code +paths that may log in detail, and where they may get input from. So you probably +will want to upgrade all code using vulnerable versions. > CVE-2021-45046 > > As an update to -> [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228), the fix made in version 2.15.0 was -> incomplete. Additional issues have been identified and are tracked with +> [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228), the fix +> made in version 2.15.0 was incomplete. Additional issues have been identified +> and are tracked with > [CVE-2021-45046](https://nvd.nist.gov/vuln/detail/CVE-2021-45046) and -> [CVE-2021-45105](https://nvd.nist.gov/vuln/detail/CVE-2021-45105). -> For a more complete fix to this vulnerability, we recommended that you update to 2.17.0 where possible. +> [CVE-2021-45105](https://nvd.nist.gov/vuln/detail/CVE-2021-45105). For a more +> complete fix to this vulnerability, update to 2.17.0 where possible. ### Scan images on Docker Hub Docker Hub security scans triggered after 1700 UTC 13 December 2021 are now -correctly identifying the Log4j 2 CVEs. Scans before this date do not -currently reflect the status of this vulnerability. Therefore, we recommend that -you trigger scans by pushing new images to Docker Hub to view the status of -Log4j 2 CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/repos/manage/vulnerability-scanning.md). +correctly identifying the Log4j 2 CVEs. Scans before this date do not currently +reflect the status of this vulnerability. Trigger scans by pushing new images +to Docker Hub to view the status of Log4j 2 CVE in the vulnerability report. +For detailed instructions, see +[Scan images on Docker Hub](/manuals/docker-hub/repos/manage/vulnerability-scanning.md). ## Docker Official Images impacted by Log4j 2 CVE _Last updated December 2021_ -A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of -Log4j 2 CVE-2021-44228. The following table lists Docker Official Images that -may contained the vulnerable versions of Log4j 2. We updated Log4j 2 in these images to the latest version. Some of these images may not be -vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites. - -| Repository | Patched version | Additional documentation | -|:------------------------|:-----------------------|:-----------------------| -| [couchbase](https://hub.docker.com/_/couchbase) | 7.0.3 | [Couchbase blog](https://blog.couchbase.com/what-to-know-about-the-log4j-vulnerability-cve-2021-44228/) | -| [Elasticsearch](https://hub.docker.com/_/elasticsearch) | 6.8.22, 7.16.2 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) | -| [Flink](https://hub.docker.com/_/flink) | 1.11.6, 1.12.7, 1.13.5, 1.14.2 | [Flink advice on Log4j CVE](https://flink.apache.org/2021/12/10/log4j-cve.html) | -| [Geonetwork](https://hub.docker.com/_/geonetwork) | 3.10.10 | [Geonetwork GitHub discussion](https://github.com/geonetwork/core-geonetwork/issues/6076) | -| [lightstreamer](https://hub.docker.com/_/lightstreamer) | Awaiting info | Awaiting info | -| [logstash](https://hub.docker.com/_/logstash) | 6.8.22, 7.16.2 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) | -| [neo4j](https://hub.docker.com/_/neo4j) | 4.4.2 | [Neo4j announcement](https://community.neo4j.com/t/log4j-cve-mitigation-for-neo4j/48856) | -| [solr](https://hub.docker.com/_/solr) | 8.11.1 | [Solr security news](https://solr.apache.org/security.html#apache-solr-affected-by-apache-log4j-cve-2021-44228) | -| [sonarqube](https://hub.docker.com/_/sonarqube) | 8.9.5, 9.2.2 | [SonarQube announcement](https://community.sonarsource.com/t/sonarqube-sonarcloud-and-the-log4j-vulnerability/54721) | -| [storm](https://hub.docker.com/_/storm) | Awaiting info | Awaiting info | +A number of +[Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images) +contain the vulnerable versions of Log4j 2 CVE-2021-44228. The following table +lists Docker Official Images that may contain the vulnerable versions of Log4j +2. Docker updated Log4j 2 in these images to the latest version. Some of these +images may not be vulnerable for other reasons. Also review the guidelines +published on the upstream websites. + +| Repository | Patched version | Additional documentation | +| :------------------------------------------------------ | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------- | +| [couchbase](https://hub.docker.com/_/couchbase) | 7.0.3 | [Couchbase blog](https://blog.couchbase.com/what-to-know-about-the-log4j-vulnerability-cve-2021-44228/) | +| [Elasticsearch](https://hub.docker.com/_/elasticsearch) | 6.8.22, 7.16.2 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) | +| [Flink](https://hub.docker.com/_/flink) | 1.11.6, 1.12.7, 1.13.5, 1.14.2 | [Flink advice on Log4j CVE](https://flink.apache.org/2021/12/10/log4j-cve.html) | +| [Geonetwork](https://hub.docker.com/_/geonetwork) | 3.10.10 | [Geonetwork GitHub discussion](https://github.com/geonetwork/core-geonetwork/issues/6076) | +| [lightstreamer](https://hub.docker.com/_/lightstreamer) | Awaiting info | Awaiting info | +| [logstash](https://hub.docker.com/_/logstash) | 6.8.22, 7.16.2 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) | +| [neo4j](https://hub.docker.com/_/neo4j) | 4.4.2 | [Neo4j announcement](https://community.neo4j.com/t/log4j-cve-mitigation-for-neo4j/48856) | +| [solr](https://hub.docker.com/_/solr) | 8.11.1 | [Solr security news](https://solr.apache.org/security.html#apache-solr-affected-by-apache-log4j-cve-2021-44228) | +| [sonarqube](https://hub.docker.com/_/sonarqube) | 8.9.5, 9.2.2 | [SonarQube announcement](https://community.sonarsource.com/t/sonarqube-sonarcloud-and-the-log4j-vulnerability/54721) | +| [storm](https://hub.docker.com/_/storm) | Awaiting info | Awaiting info | > [!NOTE] > -> Although [xwiki](https://hub.docker.com/_/xwiki) images may be detected as vulnerable -by some scanners, the authors believe the images are not vulnerable by Log4j 2 -CVE as the API jars do not contain the vulnerability. -> The [Nuxeo](https://hub.docker.com/_/nuxeo) -> image is deprecated and will not be updated. +> Although [xwiki](https://hub.docker.com/_/xwiki) images may be detected as +> vulnerable by some scanners, the authors believe the images are not vulnerable +> by Log4j 2 CVE as the API jars do not contain the vulnerability. The +> [Nuxeo](https://hub.docker.com/_/nuxeo) image is deprecated and will not be +> updated. diff --git a/content/manuals/subscription-billing/_index.md b/content/manuals/subscription-billing/_index.md new file mode 100644 index 000000000000..ef0991f9f339 --- /dev/null +++ b/content/manuals/subscription-billing/_index.md @@ -0,0 +1,77 @@ +--- +title: Docker subscriptions and billing +linkTitle: Subscription and billing +description: >- + Learn about Docker subscription plans, billing models, payment methods, + invoices, usage, credits, taxes, and how to manage plan changes in Docker + Home. +keywords: + docker subscription, docker billing, docker plans, billing models, pricing, + payment methods, invoices, usage, credits, taxes, auto-renewal, plan upgrades, + add-ons, seats, licenses, minutes +weight: 20 +params: + sidebar: + group: Accounts and admin +aliases: + - /subscription/ + - /billing/ + - /docker-hub/billing/ + - /docker-hub/billing/faq/ + - /billing/docker-hub-pricing/ +grid: + - title: Plans + description: >- + Compare billing models and tiers for Docker, Docker Hardened Images, + Gordon, Docker Agentic Platform, AI Governance, and DVP. + link: /subscription-billing/plans/ + icon: chart-bar + - title: Manage plans + description: >- + Subscribe to a new plan, upgrade an active plan, or cancel auto-renewal. + link: /subscription-billing/manage/plans/ + icon: shopping-cart + - title: Billing overview + description: >- + Open Billing in Docker Home to review active plans, usage, costs, and + credits for an account. + link: /subscription-billing/manage/ + icon: credit-card + - title: Payment methods + description: >- + Add or update a card, US bank account, or Stripe Link, or set up pay by + invoice for annual organization plans. + link: /subscription-billing/manage/payment-method/ + icon: banknotes + - title: Invoices + description: View billing history and download past invoices. + link: /subscription-billing/manage/history/ + icon: receipt-percent + - title: 3D Secure authentication + description: Learn how 3DS works and how to troubleshoot card verification. + link: /subscription-billing/manage/3d-secure/ + icon: shield-check +--- + +> [!TIP] +> +> Compare plan features and prices on the +> Docker pricing page. + +Docker subscriptions determine the products, features, and usage included with +an individual account or organization. This section explains the available +plans and how to manage subscriptions and billing. + +Use these docs to: + +- Compare Docker account plans and product-specific plans, including their + billing models, usage entitlements, and available add-ons. You can also + review Docker Desktop licensing requirements. +- Purchase a plan and manage an active subscription by upgrading, downgrading, + adding seats or usage, managing auto-renewal, or canceling the plan. +- Manage payment methods and billing details, review invoices and taxes, and + track usage, costs, and credits for an account in Docker Home. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/subscription-billing/desktop-license.md b/content/manuals/subscription-billing/desktop-license.md new file mode 100644 index 000000000000..29ca429ac9a1 --- /dev/null +++ b/content/manuals/subscription-billing/desktop-license.md @@ -0,0 +1,58 @@ +--- +title: Docker Desktop license agreement +description: >- + Learn how the Docker Subscription Service Agreement licenses Docker Desktop + and when commercial use requires a paid subscription. +keywords: docker desktop license, subscription service agreement, commercial + use, licensing terms, free for small business, paid subscription, + open source components +weight: 30 +aliases: + - /subscription/desktop-license/ + - /subscription/products/desktop-license/ + - /subscription/plans/desktop-license/ +--- + +Docker Desktop is licensed under the +[Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). +When you download and install Docker Desktop, you're asked to agree to these +terms. + +The Docker Subscription Service Agreement states: + +- Docker Desktop is free for: + - Small businesses (fewer than 250 employees AND less than $10 million in + annual revenue) + - Personal use + - Education + - Non-commercial open source projects +- Docker Desktop requires a paid subscription for: + - Professional use in larger organizations + - Government entities + - Commercial use beyond the free tier limits +- Paid subscriptions that include Docker Desktop: + - Docker Pro, Team, and Business subscriptions + +## Understand licensing terms + +For detailed information about how these terms may affect your organization, +see: + +- [Subscription updates blog post](https://www.docker.com/blog/updating-product-subscriptions/) +- [Docker subscription FAQs](https://www.docker.com/pricing/faq) to learn how + this may affect companies using Docker Desktop. + +> [!NOTE] +> +> The licensing and distribution terms for Docker and Moby open-source +> projects, such as Docker Engine, aren't changing. + +Docker Desktop is built using open-source software. For information about the +licensing of open-source components in Docker Desktop, select the whale menu > +**About Docker Desktop** > **Acknowledgements**. + +## Open source components + +Docker Desktop distributes some components that are licensed under the +GNU General Public License. +[Download the source code for these components here](https://download.docker.com/opensource/License.tar.gz). diff --git a/content/manuals/subscription-billing/manage/3d-secure.md b/content/manuals/subscription-billing/manage/3d-secure.md new file mode 100644 index 000000000000..7b17cacc7373 --- /dev/null +++ b/content/manuals/subscription-billing/manage/3d-secure.md @@ -0,0 +1,54 @@ +--- +title: Use 3D Secure authentication for Docker billing +linkTitle: 3D Secure +description: Learn how 3D Secure authentication works for Docker subscription payments and how to troubleshoot verification issues. +keywords: billing, payments, subscriptions, 3D Secure, 3DS, credit card verification, payment authentication +weight: 30 +aliases: + - /billing/3d-secure/ +--- + +Docker supports 3D Secure (3DS), an extra layer of authentication required +for certain credit card payments. If your bank or card issuer requires 3DS, you +may need to verify your identity before your payment can be completed. + +## How it works + +When a 3DS check is triggered during checkout, your bank or card issuer +may ask you to verify your identity. This can include: + +- Entering a one-time password sent to your phone +- Approving the charge through your mobile banking app +- Answering a security question or using biometrics + +The exact verification steps depend on your financial institution's +requirements. + +## When you need to verify + +You may be asked to verify your identity when performing any of the following +actions: + +- Starting a [paid subscription](/manuals/subscription-billing/manage/plans.md) +- Changing your [billing cycle](/manuals/subscription-billing/manage/details.md#billing-cycle) from monthly to annual +- [Upgrading your subscription](/manuals/subscription-billing/manage/plans.md#upgrade-plans) +- [Adding seats](/manuals/accounts/organization/manage/manage-seats.md) to an existing + subscription + +If 3DS is required and your payment method supports it, the verification prompt +will appear during checkout. + +## Troubleshooting payment verification + +If you're unable to complete your payment due to 3DS: + +1. Retry your transaction. Make sure you're completing the verification + prompt in the same browser tab. +1. Use a different payment method. +1. Contact your bank to confirm whether it's blocking the payment or the 3DS + verification attempt. + +> [!NOTE] +> +> Disabling ad blockers or browser extensions that block pop-ups can help +> the 3DS prompt display correctly. diff --git a/content/manuals/subscription-billing/manage/_index.md b/content/manuals/subscription-billing/manage/_index.md new file mode 100644 index 000000000000..f9c7008462c5 --- /dev/null +++ b/content/manuals/subscription-billing/manage/_index.md @@ -0,0 +1,116 @@ +--- +title: Manage billing +linkTitle: Manage +description: >- + Review Billing in Docker Home: plans, payment methods, invoices, usage, + costs, credits, and billing details, and what you can do on each page. +keywords: billing, docker home, billing overview, manage plans, payment + methods, invoices, usage, costs, credits, billing settings, subscription + totals, taxes, docker subscription +weight: 20 +grid: + - title: Manage plans + description: Add a new plan, upgrade an active plan, or cancel auto-renewal. + icon: shopping-cart + link: /subscription-billing/manage/plans/ + - title: Add or update a payment method + description: >- + Add or update a payment method for your individual account or + organization. + icon: credit-card + link: /subscription-billing/manage/payment-method/ + - title: Update billing information + description: >- + Update billing information for your individual account or + organization. + icon: pencil-square + link: /subscription-billing/manage/details/ + - title: Invoices + description: View billing history and download past invoices. + icon: receipt-percent + link: /subscription-billing/manage/history/ + - title: 3D Secure authentication + description: >- + Learn how 3DS works and how to troubleshoot verification issues. + icon: wallet + link: /subscription-billing/manage/3d-secure/ + - title: Taxes + description: Submit a US tax exemption certificate or add a VAT number. + icon: document-text + link: /subscription-billing/manage/tax-certificate/ +--- + +You manage Docker plans, payment methods, invoices, usage, costs, credits, and +billing details from **Billing** in Docker Home. Billing applies to the +account you select, either your individual account or an organization. + +For an organization, you must be an organization owner, or have a +[custom role](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md#billing) +with the **View billing** or **Manage billing** permission. Without it, Docker +Home shows **No access to billing**. + +## Overview + +**Overview** is the Billing home. It shows the default payment method, a tile +for each active plan, and your subscription totals with the next charge date. +The page also shows: + +* **Monthly subscriptions** when you have a monthly plan +* **Annual subscriptions** when you have an annual plan +* An alert for a + [failed payment](/manuals/subscription-billing/manage/payment-method.md#failed-payments) + or a + [bank account waiting for verification](/manuals/subscription-billing/manage/payment-method.md#verify-a-bank-account) + +> [!TIP] +> +> If Docker sales manages your subscription, the sidebar shows **Overview** +> only. Contact your Docker sales representative to renew, make changes, or +> request invoices. + +## Invoices + +**Invoices** lists every invoice with its date, number, description, status, +and amount. You can open an invoice or download a PDF when your Docker account +has a verified email address. + +## Usage + +**Usage** charts usage-based charges across billing periods. You can filter +by period, product, and meter, and export a CSV. + +Plans that report usage appear here, including Docker Build Cloud minutes, +Testcontainers Cloud minutes, and Docker Agentic Platform compute. With no +usage-based plan, the page shows **No usage-based products**. See +[Plans](/manuals/subscription-billing/plans/_index.md#choose-a-plan) +for which plans are metered. + +## Costs + +**Costs** shows charges for one billing period, grouped by the product each +charge is for. The page labels that column **Resource**. You can switch +billing periods and export a CSV. Costs also shows: + +* Period status +* Amounts excluding tax +* **Cost to date** for the current period +* The subtotal for a closed period +* Credits, when the account has them + +An invoice total can differ, because the invoice adds tax and any credits. + +## Credits + +**Credits** shows the credit balances for your products. Open a balance to +see each grant and its remaining amount. Docker applies these balances to +your costs at the end of the billing period. + +## Settings + +**Settings** shows the default payment method, billing address, tax ID, and +billing email. You can update the payment method, address, or billing email +on this page. + +## Next steps + +{{< grid >}} diff --git a/content/manuals/subscription-billing/manage/details.md b/content/manuals/subscription-billing/manage/details.md new file mode 100644 index 000000000000..15cb1381712f --- /dev/null +++ b/content/manuals/subscription-billing/manage/details.md @@ -0,0 +1,41 @@ +--- +title: Update your billing details +linkTitle: Billing details +weight: 40 +description: Learn how to update billing details, like contact information, addresses, and notification email for Docker subscriptions. +keywords: payments, billing, subscription, invoices, update billing email, change billing address, Docker billing account +aliases: + - /billing/details/ + - /billing/cycle/ +--- + +You can update your billing contact information, address, and notification email at any time. Existing invoices, whether paid or unpaid, cannot be updated. Changes only apply to future invoices. + +## Update billing details + +You can update your billing details for Docker individual accounts and Docker organization accounts using the same procedures. + +To update your billing information from **Settings** in Docker Home: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your individual or organization + account. +1. Select **Billing**, then go to **Settings**. +1. Select **Edit** to make your changes. +1. Verify your information, then select **Save as default**. + +For more information on changing your default payment method, see [Change default payment method](/manuals/subscription-billing/manage/payment-method.md#change-default-payment-method). + +## Billing notifications + +Docker sends invoices and other billing-related communications +to the billing account's email address. These communications include: + +- Confirmations, such as new subscriptions, paid invoices +- Notifications for card failure and card expiration errors +- Reminders for subscription renewal + +## Billing cycle + +Billing cycles are defined on a per-plan basis. Depending on the product you +subscribe to, your cycle can be monthly, annual, or another cadence. For +plan-specific billing cycle details, see [Plans](/manuals/subscription-billing/plans/_index.md). diff --git a/content/manuals/subscription-billing/manage/history.md b/content/manuals/subscription-billing/manage/history.md new file mode 100644 index 000000000000..62a8792697e4 --- /dev/null +++ b/content/manuals/subscription-billing/manage/history.md @@ -0,0 +1,80 @@ +--- +title: Billing and invoice history +linkTitle: Invoice history +weight: 60 +description: Learn how to view your Docker billing history, understand what's on an invoice, and pay by invoice. +keywords: payments, billing, subscription, invoices, renewals, billing history, pay by invoice +aliases: + - /billing/history/ + - /billing/core-billing/history/ +--- + +Docker issues an invoice each time a subscription to a Docker plan renews or changes. You can track invoices issued to your account so you can review the plans you've +subscribed to over time, check payment status, and download records as +needed. + +## View billing history + +Individual accounts and organization accounts use the same steps to view billing +history. To view your billing history: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your individual + account or organization account. +1. Select **Billing**, then **Invoices**. +1. View an individual invoice by selecting: + - **Invoice number** to open invoice details in your browser + - **Download** to download a copy of your invoice. + +> [!NOTE] +> +> If you want to view your organization account's +> billing history, you must be an organization owner. + +## Understand your invoice + +Your invoice includes the following information: + +| Invoice field | Description | +| -------------- | --------------------------------------------------------------------------------------------- | +| Invoice number | A unique identifier for the invoice | +| Date of issue | The date Docker generated the invoice | +| Due date | The date your payment is due | +| Bill to | Your billing name, address, and contact information | +| Line items | The description, quantity (if applicable), unit price, and amount for each item on your order | +| Subtotal | The total amount before any discounts | +| Total | The subtotal after any discounts, matching the amount due | +| Amount due | The total amount you owe, in USD | +| Pay online | A link to pay an unpaid invoice online | + +The information in the **Bill to** section comes from your billing +information. + +- Not all fields are required. +- You can't change a paid or unpaid invoice. +- Updating your billing information + doesn't update an existing invoice. + +If you want different billing information reflected in your invoice, update your billing information before your renewal date, when +Docker finalizes your invoice. For more information, see [Update billing information](details.md). + +## View renewal date + +Renewal dates are set on a per-plan basis, so check each plan individually if you subscribe to more than one. Depending on the product, your billing cycle can be monthly, annual, or another cadence. For plan-specific renewal and billing cycle details, see [Plans](/manuals/subscription-billing/plans/_index.md). + +## Pay by invoice + +> [!TIP] +> +> To pay by invoice, +> [upgrade to a Docker Team or Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsBillingPaymentMethod) +> and choose an annual subscription. + +Pay by invoice requires upfront payment for your first subscription period +using a payment card or ACH bank transfer. At renewal, Docker emails you an +invoice to pay manually instead of charging your default payment method. + +- To add pay by invoice as a payment method, contact your Docker sales + representative. +- You can only pay by invoice by choosing it as a payment method when + subscribing to Docker Team or Docker Business plans. +- Pay by invoice isn't available for subscription upgrades or changes. diff --git a/content/manuals/subscription-billing/manage/payment-method.md b/content/manuals/subscription-billing/manage/payment-method.md new file mode 100644 index 000000000000..1d3c7ba39cff --- /dev/null +++ b/content/manuals/subscription-billing/manage/payment-method.md @@ -0,0 +1,150 @@ +--- +title: Add or update a payment method +linkTitle: Payment methods +weight: 20 +description: >- + Manage cards, US bank accounts, and Stripe Link in Docker Home, and choose + pay by invoice when you subscribe an organization to an annual plan. +keywords: payments, billing, subscription, payment methods, credit card, ACH, + US bank account, Stripe Link, pay by invoice, annual renewal, failed + payments, organization billing +aliases: + - /billing/payment-method/ + - /billing/core-billing/payment-method/ +--- + +Docker supports several payment methods for paid individual accounts and +organizations. This page describes supported payment types, how to manage +payments from [Docker Home](https://app.docker.com/), and how to set up pay +by invoice. + +## Supported payment types + +You can add or update a payment method at any time. All charges are in United +States dollars (USD). Docker supports the following payment methods: + +| Category | Payment type | +| ------------- | ----------------------------------------------------------------------- | +| Cards | Visa, MasterCard, American Express, Discover, JCB, Diners, UnionPay | +| Wallets | Stripe Link | +| Bank accounts | Automated Clearing House (ACH) transfer with a verified US bank account | + +Some payment methods need extra setup before you can set them as default. For +example: + +- Verify a + [bank account](#verify-a-bank-account) before choosing it as a payment + method. +- Use an existing Stripe Link account, or enter your card information to set + up Stripe Link. + +## Manage payment method + +Paid individual accounts and organizations follow the same procedures to add, +update, or remove payment methods. + +### Add payment method + +You can add multiple payment methods in the billing portal. When you add a +new payment method, you set it as the default. + +1. Sign in to [Docker Home](https://app.docker.com/). +1. Select your username for an individual account, or select your organization + name for an organization. +1. Select **Billing** to go to the billing portal, then **Change** in the + **Payment method** tile. +1. From the **Change payment method** modal, choose to add a card, a US bank + account, or a Stripe Link payment. + - To pay with a card, enter your card information. + - To pay with a US bank account, verify your **Email** and **Full name**. + - If your bank is listed, select your bank's name. + - If your bank is not listed, select **Search for your bank**. + - To pay through Stripe Link, select an existing payment method, then + select **Use this card**. +1. For first-time setup, enter your billing information. +1. Finish adding the payment method by selecting **Save as default**. + +### Change default payment method + +After adding one or more payment methods, you can set one as a default +method. + +1. From **Billing**, go to the **Payment method** tile. +1. Select **Change** to open the **Change payment method** modal, then select + **Change** next to your current default method. +1. Choose the payment method you want to set as default. +1. Verify your information, then select **Save as default**. + +### Remove payment method + +You can only remove secondary payment methods. To remove a secondary payment +method: + +1. From **Billing**, go to the **Payment method** tile. +1. Select **Change** to open the **Change payment method** modal. +1. Select the **Actions** menu next to the payment method you want to remove, + then select **Remove**. +1. Verify your billing details, then select **Save as default**. + +To remove your default payment method, first set a different payment method +as default, or +[downgrade to a free subscription](/manuals/subscription-billing/plans/docker.md#cancel-a-docker-plan). + +## Pay by invoice + +> [!TIP] +> +> Pay by invoice is available when you subscribe an organization to an +> [annual Docker Team or Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsBillingPaymentMethod). + +Pay by invoice means you pay for the first subscription period with a card or +ACH bank transfer. At renewal, Docker emails an invoice to pay manually +instead of charging your default payment method automatically. + +You choose this option during organization subscribe checkout. It isn't +available when you upgrade or change an existing subscription. + +1. Start an annual organization subscription in + [Docker Home](https://app.docker.com/). +1. On the payment page, select **Pay by invoice for future renewals**. +1. Complete checkout with a card or US bank account for the first period. + +If Docker manages your subscription through sales, contact your Docker sales +representative to change how renewals are collected. + +## Verify a bank account + +You can verify your bank account with instant verification for supported +banks. You must sign in to your US bank account when adding your bank as a +payment method: + +1. From **Billing**, go to the **Payment method** tile and select **Change**. +1. Choose **US bank account** as your payment method. +1. Verify your **Email** and **Full name**. +1. Search for your bank, then select it to initiate the sign-in flow. +1. Review the terms and conditions. This agreement lets Docker debit + payments from your connected bank account. +1. Select **Agree and continue**. +1. Select an account to link and verify, then select **Connect account**. + +When the account is verified, a success message appears. + +## Failed payments + +If your payment fails, select **Pay now** to retry the payment through +Stripe. + +You have a grace period of 15 days, including the due date, when your payment +fails. Docker attempts to collect the payment three times using the following +schedule: + +- 3 days after the due date +- 5 days after the previous attempt +- 7 days after the previous attempt + +Docker also sends an email notification +`Action Required - Credit Card Payment Failed` with an attached unpaid +invoice after each failed payment attempt. + +If the invoice remains unpaid after the grace period, the subscription +downgrades to a free subscription and all paid features are disabled. diff --git a/content/manuals/subscription-billing/manage/plans.md b/content/manuals/subscription-billing/manage/plans.md new file mode 100644 index 000000000000..5c6429a4f1da --- /dev/null +++ b/content/manuals/subscription-billing/manage/plans.md @@ -0,0 +1,73 @@ +--- +title: Manage plans +linkTitle: Plans +description: > + Learn how to set up, upgrade, downgrade, or cancel plans, and how to + manage auto-renewal and credits. +keywords: + purchase subscription, buy docker subscription, product catalog, browse + products, upgrade subscription, downgrade subscription, docker billing, cancel auto-renewal, cancel, top up, manage +weight: 10 +aliases: + - /subscription/manage/ + - /subscription/change/ + - /subscription/setup/ + - /docker-hub/upgrade/ + - /docker-hub/billing/upgrade/ + - /subscription/upgrade/ + - /subscription/core-subscription/upgrade/ + - /billing/scout-billing/ + - /billing/subscription-management/ +--- + +You can add and manage your plans from the billing portal in Docker Home. Within the billing portal, you use the product catalog to view +self-serve Docker products, while the Overview page shows your active plans with options to upgrade or cancel. + +## Set up a new plan + +You can purchase Docker Team, Docker Business, and other products through the product catalog: + +1. Sign in to [Docker Home](https://app.docker.com/), then choose your individual + account or your organization account. +1. Go to **Billing**. +1. Select **Browse products**. + - The **Products** page contains products and upgrades available for self-serve. + - Some products in the catalog may apply to individual accounts, organization accounts, or both. + - Each product tile uses an account-type flag so you know the difference. +1. Select **View plans**, then choose the plan you want to add to your Docker subscription. +1. Verify your billing details, continue to payment, and complete checkout. + - Optional. To add a VAT number, select the **I'm purchasing as a business** + checkbox and enter your Tax ID. + - Your VAT number must include your country prefix. For example, enter + `DE123456789` for a German VAT number. + +To upgrade to Docker Pro, go to the +Docker pricing page +and select **Buy now**. + +## Change an active plan {#upgrade-plans} + +To change a plan you already have, sign in to +[Docker Home](https://app.docker.com/), go to **Billing**, then go to +**Active subscriptions**. Each plan tile has a control, such as an action +menu or a **Manage** button, that opens the options for that plan. + +The available options depend on the plan. For example, Docker plans let you +add seats or switch to annual billing, while product plans let you upgrade +or downgrade tiers, add units, or turn auto-renewal on or off. For the +steps for each plan and when the change takes effect, see the +[plans catalog](/manuals/subscription-billing/plans/_index.md). + +## Sales-led products + +Some products are sales-led. You must +contact sales to opt in. + +## Next steps + +- [Learn about available plans](/manuals/subscription-billing/plans/_index.md) +- [Set up payment information](/manuals/subscription-billing/manage/payment-method.md) +- [View invoices](/manuals/subscription-billing/manage/history.md) +- To learn more about managing your billing details, see [Billing](/manuals/subscription-billing/_index.md). +- To learn about sales tax and VAT, see + [Taxes](/manuals/subscription-billing/manage/tax-certificate.md). diff --git a/content/manuals/subscription-billing/manage/tax-certificate.md b/content/manuals/subscription-billing/manage/tax-certificate.md new file mode 100644 index 000000000000..4261c1af901d --- /dev/null +++ b/content/manuals/subscription-billing/manage/tax-certificate.md @@ -0,0 +1,93 @@ +--- +title: Sales tax exemption and VAT +linkTitle: Taxes +description: > + Learn how Docker collects sales tax and VAT, how to submit a US tax + exemption certificate, and how to add a VAT number at checkout. +keywords: + billing, sales tax, VAT, tax exemption certificate, tax ID, VAT number, + United States tax exemption, Docker Support, billing portal +weight: 70 +aliases: + - /billing/tax-certificate/ +--- + +Depending on your location, Docker may collect sales tax or VAT on your +subscription. Tax relief is the same idea in both cases, but the process +differs: + +- United States customers request exemption by submitting a tax exemption + certificate through Docker Support. The billing portal has no self-serve + tax ID field for US customers. +- Customers in VAT countries enter a tax ID or VAT number themselves when they + purchase a Docker plan. + +## United States tax exemption + +US customers submit a support ticket with a valid tax exemption certificate +to receive tax-exempt status. Docker reviews the certificate and applies the +exemption to your billing profile. You can apply for tax-exempt status: + +- Before you purchase, submit your certificate and wait for Docker to approve + it. After approval, you can purchase without sales tax. +- If you were charged sales tax, open a support ticket to coordinate with + Docker Support on exempt status. + +### Prerequisites + +Before submitting your certificate, confirm the following: + +- Customer name matches the name on the certificate. +- The certificate lists Docker, Inc. as the seller or vendor, with all + relevant fields completed. +- The certificate is signed, dated, and not expired. +- You've included the Docker ID or namespace(s) for all accounts the + certificate applies to. + +> [!TIP] +> +> You can use the same certificate for multiple namespaces when applicable. + +### Contact information + +Use the following contact information on your certificate: + +```text +Docker, Inc. +3790 El Camino Real #1052 +Palo Alto, CA 94306 +(415) 941-0376 +``` + +### Submit a tax exemption certificate + +1. [Submit a Docker Support ticket](https://hub.docker.com/support/contact?topic=Billing&subtopic=Tax%20information) + to start the tax certificate registration process. +1. Enter **Tax certificate** as the support ticket **Subject**. +1. In the **Details** field, enter **Submitting a tax certificate**. +1. Follow the instructions that appear for submitting a tax certificate. +1. Complete all required fields on the support form. +1. In the file upload section, add the tax certificate by dragging and dropping + the file, or selecting **Browse files**. +1. Select **Submit**. + +Docker Support contacts you if additional information is required. Docker sends +an email confirmation after applying the tax exemption status to your account. + +## Add a VAT number or tax ID + +When you select a VAT-applicable country during checkout, a tax ID field +appears. Customers in VAT countries enter their tax ID or VAT number +during checkout without opening a support ticket. + +Your VAT number must include your country prefix. For example, enter +`DE123456789` for a German VAT number. + +> [!NOTE] +> +> The tax ID field appears during checkout only when you select +> **I'm purchasing as a business**. It doesn't appear when you edit an +> existing payment method or billing details in billing settings. + +Add a VAT number or tax ID when you +[set up a new plan](/manuals/subscription-billing/manage/plans.md#set-up-a-new-plan). \ No newline at end of file diff --git a/content/manuals/subscription-billing/plans/_index.md b/content/manuals/subscription-billing/plans/_index.md new file mode 100644 index 000000000000..c3bf2e58d019 --- /dev/null +++ b/content/manuals/subscription-billing/plans/_index.md @@ -0,0 +1,89 @@ +--- +title: Plans +linkTitle: Plans +description: + Browse available Docker plans and add-ons for individuals, teams, and + organizations. +keywords: + docker products, docker subscriptions, docker team, docker business, + ai governance, dhi select, docker build cloud, gordon plans, + docker agentic platform, product catalog +weight: 10 +aliases: + - /subscription/plans/ + - /subscription/products/ + - /subscription/scale/ + - /subscription/details/ + - /subscription/downgrade/ + - /docker-hub/cancel-downgrade/ + - /docker-hub/billing/downgrade/ +grid: + - title: Docker + description: >- + Personal and organization plans, including build and runtime minutes. + link: /subscription-billing/plans/docker/ + icon: credit-card + - title: Gordon plans + description: Usage plans that increase your Gordon allowance. + link: /subscription-billing/plans/gordon/ + icon: /icons/gordon.svg + - title: Docker Agentic Platform + description: Pay-as-you-go cloud compute for individual accounts. + link: /subscription-billing/plans/docker-agentic-platform/ + icon: cloud + - title: Docker Hardened Images (DHI) + description: Hardened image repositories for organization accounts. + link: /subscription-billing/plans/dhi/ + icon: /icons/dhi.svg + - title: AI Governance + description: Licenses for organization-wide AI policy enforcement. + link: /subscription-billing/plans/ai-governance/ + icon: shield-check + - title: Docker Verified Publisher (DVP) + description: >- + Publisher analytics and reporting plans for organization accounts. + link: /subscription-billing/plans/docker-verified-publisher/ + icon: check-badge +--- + + +Docker plans attach to an individual account, an organization, or a specific +product. Plans make up your subscription. + +* Docker Personal and Docker Pro are subscriptions for individual accounts. +* Docker Team and Docker Business are subscriptions for organization + accounts. +* Product plans let you subscribe to a Docker product without altering + your account type plan. + +Each plan page covers usage entitlements, billing cycle, and management +options. + +## Choose a plan + +Compare billing models and tiers before you subscribe. + +| Plans | Billing model | Types | +| --- | --- | --- | +| [Docker](/manuals/subscription-billing/plans/docker.md) | Flat-rate plans for individual and organization accounts | Docker Personal, Docker Pro, Docker Team, Docker Business | +| [Docker Hardened Images (DHI)](/manuals/subscription-billing/plans/dhi.md) | Annual plans billed per repository. DHI Community is free. | DHI Community, DHI Select, DHI Enterprise | +| [Gordon](/manuals/subscription-billing/plans/gordon.md) | Monthly plans that raise your Gordon usage allowance | Gordon Plus, Gordon Max, Gordon Ultra | +| [Docker Agentic Platform](/manuals/subscription-billing/plans/docker-agentic-platform.md) | Pay-as-you-go cloud compute, billed monthly | Pay-as-you-go | +| [AI Governance](/manuals/subscription-billing/plans/ai-governance.md) | Licenses purchased through Docker sales. | AI Governance | +| [Docker Verified Publisher (DVP)](/manuals/subscription-billing/plans/docker-verified-publisher.md) | Flat-rate annual plans. DVP Growth lets you add consuming domains in blocks of 25. | DVP Starter, DVP Growth | + +## Add units to a plan {#top-up-your-plan} + +Add seats, minutes, or other units without changing the plan type. + +| Unit | Description | Examples | +| --- | --- | --- | +| [Seats](/manuals/accounts/organization/manage/manage-seats.md) | Each seat extends entitlements to one more member. | Docker Team, Docker Business | +| [Licenses](/manuals/accounts/organization/manage/manage-licenses.md) | Access to specific products or features. | AI Governance, Docker Offload | +| [Minutes](/manuals/subscription-billing/plans/docker.md#docker-build-cloud-minutes) | Build and test runtime capacity, sold in blocks and consumed within the billing period. | Docker Build Cloud, Testcontainers Cloud | +| [Repositories](/manuals/subscription-billing/plans/dhi.md) | Additional container repositories covered by security scanning and analysis features. | DHI | +| [Consuming domains](/manuals/subscription-billing/plans/docker-verified-publisher.md#add-consuming-domains) | Additional consuming domains tracked in publisher analytics. | DVP Growth | + +## Product catalog + +{{< grid >}} diff --git a/content/manuals/subscription-billing/plans/ai-governance.md b/content/manuals/subscription-billing/plans/ai-governance.md new file mode 100644 index 000000000000..8974be8af030 --- /dev/null +++ b/content/manuals/subscription-billing/plans/ai-governance.md @@ -0,0 +1,30 @@ +--- +title: AI Governance plan +linkTitle: AI Governance +description: + Manage AI Governance licenses for your organization, including purchasing, + assigning, and deactivating +keywords: + ai governance, licenses, organization licenses, ai policy, docker sandbox, + subscription management +weight: 50 +aliases: + - /subscription/plans/ai-governance/ + - /subscription/products/ai-governance/ + - /subscription/ai-governance/ +--- + +> [!TIP] +> To subscribe to AI Governance, contact sales. + +[AI Governance](/manuals/ai/sandboxes/governance/_index.md) lets organization owners enforce policies for members across supported Docker AI products, like [Docker Sandbox](/manuals/ai/sandboxes/_index.md). When you add an AI Governance plan, you work with your Docker sales representative to determine the number of licenses needed, which are applied to your account. + +## Usage + +AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/access-controls/organization.md) for license-holding members. Organization policies override a license-holding member's local policies. + +You can [assign AI Governance licenses](/manuals/accounts/organization/manage/manage-licenses.md) to a team or to an individual organization member, even if they don't occupy a Docker Team or Docker Business seat. For best practice, review available licenses as you add new members since members without an AI Governance license can still use Docker AI products. + +## Billing cycle + +AI Governance plan pricing is based on the number of licenses purchased. To add or remove licenses, contact your Docker sales representative. diff --git a/content/manuals/subscription-billing/plans/dhi.md b/content/manuals/subscription-billing/plans/dhi.md new file mode 100644 index 000000000000..8cccd147fa67 --- /dev/null +++ b/content/manuals/subscription-billing/plans/dhi.md @@ -0,0 +1,77 @@ +--- +title: DHI plans +linkTitle: Docker Hardened Images +description: + Manage Docker Hardened Images Select and Enterprise repositories for + organization accounts, including purchasing, adding repositories, and + deactivating +keywords: dhi select, dhi enterprise, docker hardened images, hardened images, + repositories, organization subscription, secure images +weight: 40 +aliases: + - /subscription/plans/dhi/ + - /subscription/products/dhi-select/ + - /subscription/dhi-select/ + - /subscription/plans/dhi-select/ +--- + +[Docker Hardened Images (DHI)](/manuals/dhi/_index.md) are secure, minimal, production-ready container images maintained by Docker. + +- DHI Community is free and available to every developer. +- DHI Select is a paid plan for organizations that need compliance-ready images and SLA-backed patching. You can self-serve it in the billing portal. +- DHI Enterprise is for organizations with advanced security and customization requirements. To subscribe, contact sales. + +For a full plan comparison, see the [Docker pricing page](https://www.docker.com/pricing/). + +## Usage + +DHI Community gives you access to hardened base images from a public registry at no cost or additional setup. Any organization can pull hardened base images directly from `dhi.io`. + +When you upgrade from DHI Community to DHI Select, you purchase a set number of repositories that are mirrored into your organization's namespace. Entitlements are scoped to the organization account that you assign them to during checkout. All organization members can then pull from those mirrored repositories. + +DHI Enterprise extends DHI Select with unlimited customizations, optional full catalog access, the Hardened System Packages repository, and an Extended Lifecycle Support add-on. + +For details on setting up and managing repositories, see [Get started with DHI Select and Enterprise](/manuals/dhi/how-to/select-enterprise.md). + +> [!TIP] +> +> EU data residency is in early access. Docker can provision your organization's DHI subscription in the EU region. To request it, contact your Docker account representative or Docker sales. For details, see [EU data residency for Docker Hardened Images](/manuals/dhi/explore/eu-region.md). + +## Billing cycle + +DHI Select is an annual plan billed per repository from the date your plan starts. Repositories added mid-cycle are prorated for the remainder of the billing period. For steps, see [Add repositories](#add-repositories). + +## Add repositories + +Repositories you add take effect immediately and are prorated for the rest +of the billing period. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active plans**, select **Manage** next to **Hardened Images**. +1. Select **Add repositories**. +1. Choose the number of repositories, verify your billing details, continue + to payment, and complete checkout. + +## Disable auto-renewal + +If you want to revert your plan to DHI Community, you must disable auto-renewal. Disabling auto-renewal is deferred to the end of the current billing cycle and your repository access remains active until then. To disable auto-renewal: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active plans**, select **Manage** next to **Hardened Images**. +1. Select **Disable auto-renewal**. + +If you disabled auto-renewal and the plan is still active, **Manage** includes **Enable auto-renewal**. + +## Remove repositories + +You may also remove repositories from your plan. Repository removals are deferred to the end of the current billing cycle. You can remove repositories at any time, but you cannot stop a plan mid-cycle to receive a partial refund. Repository access remains active until the cycle ends. + +To remove repositories: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active plans**, select **Manage** next to **Hardened Images**. + - Select **Remove repositories** to adjust your repository count. + - To keep your current repository count after renewal, select **Cancel scheduled change**. + - Cancellations and repository removals take effect at the end of the current annual billing cycle. + +If you're subscribed to DHI Enterprise, reach out to your sales representative to change your DHI plan. diff --git a/content/manuals/subscription-billing/plans/docker-agentic-platform.md b/content/manuals/subscription-billing/plans/docker-agentic-platform.md new file mode 100644 index 000000000000..e89373de23f7 --- /dev/null +++ b/content/manuals/subscription-billing/plans/docker-agentic-platform.md @@ -0,0 +1,100 @@ +--- +title: Docker Agentic Platform plans +linkTitle: Docker Agentic Platform +description: > + Learn about Docker Agentic Platform for individual developers, + including usage, pay-as-you-go billing cycle, and cancellation. +keywords: + docker agentic platform, cloud sandboxes, mcp gateway, + pay-as-you-go, paygo, metered billing, billing cycle, personal + subscription, promotional credit, cancel subscription, sandbox + compute, usage and billing +weight: 20 +aliases: + - /subscription/plans/docker-agentic-platform/ +--- + +> [!TIP] +> Docker Agentic Platform signups receive a one-time promotional +> credit toward cloud compute usage. To review your balance, see +> [Credits](/manuals/subscription-billing/manage/_index.md#credits). + +[Docker Agentic Platform](https://agentic-platform.docker.com/) is a +pay-as-you-go plan for running agent and tool workloads in isolated +sandboxes with Docker-managed cloud infrastructure. You pay for the usage you accrue without a recurring +subscription fee. + +To activate access for the Console, cloud sandbox CLI, or API and SDKs, follow +[Signup and billing](/manuals/agentic-platform/signup.md#activate-cloud-access). + +## Usage + +> [!NOTE] +> Subscribe using your individual Docker account, including if you belong to +> an organization. The subscription is attached to your individual account. + +Docker Agentic Platform requires bringing your own API keys for inference. Your inference provider +handles those costs. + +After you subscribe, your invoice reflects metered, pay-as-you-go +compute usage. Docker meters compute usage in seconds, based on sandbox +runtime and the vCPU plus memory configuration you choose at setup. +Different sandbox configurations can produce different costs. + +You can track usage and pricing from the +[Usage & billing](https://agentic-platform.docker.com/usage) page in Agentic Platform. + +To track usage for Docker Agentic Platform from Docker Home: + +1. Sign in to [Docker Home](https://app.docker.com/), then choose your + account. +1. Go to **Billing** to view the Overview page, then go to **Active + subscriptions**. +1. Select **Manage** next to **Docker Agentic Platform**. +1. View the estimated totals and usage for the current pay period. + +## Billing cycle + +Docker Agentic Platform is billed monthly on the day you subscribe. +Your invoice reflects compute usage accrued during the previous period. +For example: + +- If you subscribed on September 10, you are billed on October 10. +- Your invoice from October 10 reflects accrued usage from September 10 + through October 9. +- Your invoice can take up to 24 hours after your billing date to + appear. + +Credits are applied to your costs at the end of the billing period. + +## Cancel a plan + +Canceling Docker Agentic Platform disables subscription renewal at the +start of the next plan period. Docker bills you for usage at the end of +the plan period. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to + **Billing**. +1. From **Active subscriptions**, select **Manage** next to + **Docker Agentic Platform**. +1. Select **Cancel subscription**. +1. Review your usage, then select **Cancel subscription** to confirm. + +## Re-enable renewal + +After you cancel, you can re-enable renewal at any time before the +current period ends. Your subscription then continues past the renewal +date. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to + **Billing**. +1. From **Active subscriptions**, select **Manage** next to + **Docker Agentic Platform**. +1. Select **Re-enable renewal**. + +## Next steps + +- To add a plan, see + [Manage plans](/manuals/subscription-billing/manage/plans.md) +- To track usage across plans, see + [Usage](/manuals/subscription-billing/manage/_index.md#usage) diff --git a/content/manuals/subscription-billing/plans/docker-verified-publisher.md b/content/manuals/subscription-billing/plans/docker-verified-publisher.md new file mode 100644 index 000000000000..4e712d58b2a3 --- /dev/null +++ b/content/manuals/subscription-billing/plans/docker-verified-publisher.md @@ -0,0 +1,138 @@ +--- +title: Docker Verified Publisher plans +linkTitle: Docker Verified Publisher +description: + Manage DVP Starter and DVP Growth for organization accounts, + including how to apply, add consuming domains, and handle billing. +keywords: + docker verified publisher, dvp, dvp starter, dvp growth, consuming + domains, publisher analytics, organization subscription, apply + for dvp, auto-renewal, billing portal, docker hub +weight: 60 +aliases: + - /subscription/plans/docker-verified-publisher/ +--- + +> [!TIP] +> DVP plans require an approved application before you can subscribe. +> See [Apply for DVP Starter or Growth](#apply-for-dvp-starter-or-growth). + +[Docker Verified Publisher (DVP)](/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md) +is a program for commercial publishers who distribute content on Docker +Hub. DVP Starter and DVP Growth are paid organization plans that add +publisher analytics and reporting to verified publisher status. + +- DVP Starter includes a verified publisher badge, prioritized search + ranking, [Docker Scout](/manuals/scout/_index.md) vulnerability + scanning, and weekly and monthly summary reports. +- DVP Growth includes everything in DVP Starter, plus trends, + domain-level reports, and benchmark reports, with 25 consuming + domains included. + +For a plan comparison, see the +[DVP landing page](https://hub.docker.com/publisher-program). + +## Usage + +Organizations can hold a DVP plan and DVP entitlements apply per organization +namespace. If you operate multiple namespaces, each one needs its own DVP +application. If you only have a Docker Personal or Docker Pro account, you can +create an organization when you apply. + +Consuming domains are unique company domains that pull your images. +On DVP Growth, you can add more consuming domains in increments of +25 from the billing portal. For steps, see +[Add consuming domains](#add-consuming-domains). + +For details on the reports available to verified publishers, see +[Insights and analytics](/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md). + +## Apply for DVP Starter or Growth + +To add DVP Starter or DVP Growth, you must apply for a DVP plan. After Docker +approves your application, complete checkout to subscribe. + +1. Go to the [DVP landing page](https://hub.docker.com/publisher-program). + The page contains information about DVP Starter and DVP Growth. +1. Select **Apply for DVP**. Sign in if prompted. +1. Select an existing organization namespace, or create a new one if + needed. +1. Fill in the content you want to publish and select DVP Starter or + DVP Growth. +1. Submit your application for review with **Submit application**. +1. After approval, Docker emails you a checkout link. Open the link, + then select DVP Starter or DVP Growth. +1. Verify your billing details, continue to payment, and complete + checkout. + +> [!IMPORTANT] +> Docker emails a checkout link after it approves your application. +> You're charged when you complete payment. + +## Add consuming domains + +On a DVP Growth plan, you can add consuming domains from the billing +portal: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to + **Billing**. +1. From **Active plans**, select **Manage** next to **Docker Verified + Publisher**. +1. Select **Add consuming domains** under **Consuming Domains**. +1. Select the number of consuming domains you want to add to your + subscription. +1. Verify your billing details, continue to payment, and complete + checkout. + +## Billing cycle + +DVP Starter and DVP Growth are billed annually. You can upgrade from +DVP Starter to DVP Growth without a new application. Upgrades take +effect immediately. Downgrades take effect at the end of the annual +period. For steps, see +[Upgrade or downgrade](#upgrade-or-downgrade). + +On DVP Growth, consuming domain add-ons are prorated from the purchase +date through the rest of your billing period, and they expire at the +end of your annual subscription. You can reduce your add-on count at +any time. Removals take effect at the end of the current billing cycle. + +> [!IMPORTANT] +> No mid-cycle refunds are issued when you reduce consuming domain +> add-ons or end a DVP plan. + +## Upgrade or downgrade + +You can move between DVP Starter and DVP Growth from the billing portal. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to + **Billing**. +1. From **Active plans**, select **Manage** next to **Docker Verified + Publisher**. +1. Choose the change you want: + - To upgrade, select **Upgrade to Growth**, then verify your billing + details, continue to payment, and complete checkout. The upgrade + takes effect immediately. + - To downgrade, select **Downgrade to Starter**. The downgrade is + scheduled for the end of the annual period, and you keep DVP Growth + until then. + +If a downgrade is scheduled and you change your mind, select **Manage**, +then **Cancel scheduled downgrade** to keep DVP Growth after renewal. + +## Disable auto-renewal + +To end a DVP plan, disable automatic renewal. Your plan stays active +until the end of the billing period and then expires. To disable +auto-renewal: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to + **Billing**. +1. From **Active plans**, select **Manage** next to **Docker Verified + Publisher**. +1. Select **Disable auto-renewal**. +1. Optional. To remove consuming domains, select **Remove consuming + domains**, then choose the number to remove. + +If you disabled auto-renewal and the plan is still active, **Manage** +includes **Enable auto-renewal**. diff --git a/content/manuals/subscription-billing/plans/docker.md b/content/manuals/subscription-billing/plans/docker.md new file mode 100644 index 000000000000..70ce20132870 --- /dev/null +++ b/content/manuals/subscription-billing/plans/docker.md @@ -0,0 +1,182 @@ +--- +title: Docker plans +linkTitle: Docker +description: + Learn about Docker plans that upgrade individual and organization accounts, + including usage entitlements, billing cycle, and downgrade options. +keywords: + docker team, docker business, docker pro, docker personal, + subscription seats, upgrade subscription, downgrade subscription, docker + pricing, subscription changes, build cloud minutes, testcontainers minutes, + docker offload licenses, cancel subscription +weight: 10 +aliases: + - /subscription/plans/docker/ + - /subscription/plans/core/ + - /subscription/products/core/ + - /subscription/core/ + - /subscription/testcontainers-cloud/ + - /subscription/products/testcontainers-cloud/ + - /subscription/products/build-cloud/ + - /subscription/build-cloud/ + - /subscription/core-subscription/downgrade/ +--- + +Docker plans upgrade your account from the free Docker Personal plan to a +paid plan with higher usage limits, commercial licensing, and expanded +features. + +- Docker Personal is free for individual developers. Docker Pro adds + unlimited private repositories, Docker Build Cloud, and commercial Docker + Desktop use. +- Docker Team and Docker Business are plans for organizations. Team adds + audit logs and role-based access control. Business adds single sign-on + (SSO), SCIM, Hardened Docker Desktop, and Image Access Management. + +To upgrade to Docker Pro, go to the +Docker pricing page +and select **Buy now**. To upgrade to Docker Team or Docker Business, see +[Manage plans](/manuals/subscription-billing/manage/plans.md). + +## Usage + +Docker Personal and Docker Pro apply to individual accounts. Docker Team and +Docker Business apply to organization accounts. For a full feature and +pricing comparison, see the +Docker pricing page. + +> [!TIP] +> If you're upgrading from a Personal plan to a Team plan and want to keep +> your username, +> [convert your user account into an organization](/manuals/accounts/organization/setup/convert-account.md). + +## Billing cycle + +Docker plans are billed at a flat rate per user per month, with monthly or +annual billing options. Upgrading your plan immediately extends access to +all features and entitlements. + +### Switch to annual billing + +When you manage the subscription yourself and the plan is billed monthly, +the action menu includes **Switch to annual billing**. The review shows the +annual total and a **Prorated credit** for the unused part of the current +monthly period. The amount due today is labeled **Prorated for this year**. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active subscriptions**, select the action menu next to your Docker + plan. +1. Select **Switch to annual billing**. +1. Review the annual total and prorated credit, then complete checkout. + +### Organization seats + +For Docker Team and Docker Business, each seat extends your paid plan to one +more member. You can remove only unused seats. To remove more, first +[remove members](/manuals/accounts/organization/manage/members.md#remove-member-from-organization) +from your organization. + +To add or remove seats: + +1. Sign in to [Docker Home](https://app.docker.com/), then choose your + organization account. +1. Go to **Billing** to view the Overview page, then go to + **Active subscriptions**. +1. From the Docker Team or Docker Business tile, select the action menu, then + select **Add seats** or **Remove seats**. +1. Choose the number of seats and review your new total. +1. For added seats, verify your billing details, continue to payment, and + complete checkout. + +To learn how to manage seats from Docker Home, see +[Manage seats](/manuals/accounts/organization/manage/manage-seats.md). + +### Docker Offload licenses + +[Docker Offload](/manuals/offload/_index.md) licenses are available for +Docker Team and Docker Business plans. Once assigned to your account, +organization owners can +[manage licenses](/manuals/accounts/organization/manage/manage-licenses.md) +in Docker Home. + +To add Docker Offload licenses, you must +contact sales. + +### Docker Build Cloud minutes + +Each plan includes a base allocation of +[Docker Build Cloud](/manuals/build-cloud/_index.md) build minutes per +month. Base minutes reset on an annual or monthly cadence and don't +accumulate. Additional purchased minutes expire at the end of your billing +period. + +To purchase additional minutes: + +1. From [Docker Home](https://app.docker.com/), choose your organization. +1. Select **Build Cloud**, then **Build minutes**. +1. From the **Minute breakdown** table, select **Add minutes**. +1. Choose your additional minute amount. +1. Verify your billing details, continue to payment, and complete checkout. + +Your additional minutes appear on the Build minutes page immediately. + +### Testcontainers Cloud minutes + +Each plan includes a base allocation of Testcontainers Cloud runtime minutes +per month. Base minutes reset monthly and don't accumulate. + +You can add Testcontainers Cloud runtime minutes in two ways: + +- Contact sales to + pre-purchase runtime minutes at $3 per 100 minutes. Pre-purchased minutes + expire at the end of your billing period. +- Use on-demand runtime minutes at $4 per 100 minutes, billed at the end of + each monthly cycle. + +## Cancel a Docker plan + +> [!NOTE] +> If you have a sales-assisted Docker Business plan, contact your account +> manager to cancel. + +You can cancel at any time before your renewal date, but you can't pause or +delay a plan. The unused portion of your plan isn't refundable, but you keep +access to paid features until the end of the current billing cycle. If an +invoice isn't paid by the due date, a 15-day grace period starts from the +due date. + +> [!NOTE] +> +> Billing periods are calculated in UTC. If your time zone is behind UTC, +> for example US Pacific Time at UTC−7 or UTC−8, canceling or making changes +> late in your local day can fall into the next billing day. + +Canceling a paid plan can affect collaborators and organization members: + +- Docker Pro private repository collaborators are removed, and additional + private repositories are locked. +- Docker Team or Docker Business members provisioned through SCIM without a + password are locked out. Remove SSO connections and verified domains if + your organization uses single sign-on. +- For paid individual and organization plans, you must convert private + repositories to fit your new plan limits. + +Canceling a paid plan returns your account to Docker Personal or a basic +organization account. To cancel your plan: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active subscriptions**, select the action menu next to your Docker + plan. +1. Select **Cancel plan** and complete the feedback survey. + +If you cancel and the plan is still in its current billing cycle, the action +menu includes **Reactivate**. + +## Next steps + +- To add or upgrade a plan, see + [Manage plans](/manuals/subscription-billing/manage/plans.md) +- To manage seats for your organization, see + [Manage seats](/manuals/accounts/organization/manage/manage-seats.md) +- To track usage across plans, see + [Usage](/manuals/subscription-billing/manage/_index.md#usage) diff --git a/content/manuals/subscription-billing/plans/gordon.md b/content/manuals/subscription-billing/plans/gordon.md new file mode 100644 index 000000000000..0470a2ae610c --- /dev/null +++ b/content/manuals/subscription-billing/plans/gordon.md @@ -0,0 +1,69 @@ +--- +title: Gordon plans +linkTitle: Gordon +description: + Manage Gordon Plus, Max, and Ultra plans for individual accounts, including + purchasing, upgrading, and deactivating +keywords: + gordon, gordon plus, gordon max, gordon ultra, gordon usage, gordon plan, + personal subscription, ai assistant, usage allowance +weight: 30 +aliases: + - /subscription/plans/gordon/ + - /subscription/products/gordon/ + - /subscription/gordon/ +--- + +[Gordon](/manuals/ai/gordon/_index.md) is an AI assistant for Docker workflows. For pricing details, see the [Gordon product page](https://www.docker.com/products/gordon/). + +- Gordon Base is included at no cost with Docker plans. It covers everyday Docker workflow questions with a baseline monthly usage allowance. +- Gordon Plus is for developers who use Gordon regularly. It increases your monthly usage allowance above Base. +- Gordon Max is for power users who rely on Gordon throughout their workflow. It offers a significantly higher usage allowance than Plus. +- Gordon Ultra is for developers with the highest usage needs. It provides the maximum monthly allowance available on a self-serve plan. + +To subscribe to a Gordon paid plan, see [Manage plans](/manuals/subscription-billing/manage/plans.md). To move between paid tiers, see [Upgrade](#upgrade). + +## Usage + +Gordon usage is measured in questions. When you upgrade from Gordon Base to a paid plan, your usage multiplies the Base allowance. Usage is capped across three time windows: 4-hour, daily, and monthly. For full limit details, see [Gordon usage limits](/manuals/ai/gordon/usage-limits.md). + +> [!IMPORTANT] +> Gordon plans apply to individual Docker accounts only. If you purchase a Gordon +> plan while signed in with an organization account, the plan applies +> to your individual account automatically. + +## Billing cycle + +Gordon plans are billed monthly at the first of the month. If you purchase after the first of the month, your invoice reflects prorated charges for the remaining days in the cycle. Subscribing to a Gordon plan charges you at the time of purchase. When you upgrade your Gordon plan, usage limits are immediately effective after payment. + +## Upgrade + +You can move to a higher Gordon tier at any time. The new usage limits +take effect after payment. + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active plans**, select **Manage** next to your Gordon plan. +1. Select **Upgrade subscription**. +1. Choose the tier, verify your billing details, continue to payment, and + complete checkout. + +## Downgrade or disable auto-renewal + +When you downgrade a Gordon plan, the change takes effect on the 1st of the following month. Disabling auto-renewal for a Gordon plan returns your paid Gordon plan to Gordon Base in the same pattern. For example, if you downgrade from Gordon Ultra to Gordon Plus on April 15: + +- From April 15 through April 30, you retain Ultra access and usage limits. +- On May 1, you are charged the Gordon Plus plan rate and Gordon Plus usage limits take effect. + +To downgrade or disable auto-renewal: + +1. Sign in to [Docker Home](https://app.docker.com/) and go to **Billing**. +1. From **Active plans**, select **Manage** next to your Gordon plan. +1. Select **Downgrade plan** to switch to a lower tier, or **Disable auto renewal** to end your plan after the current billing cycle. + +If you disabled auto-renewal and the plan is still active, **Manage** includes **Enable auto-renewal**. + +If a downgrade is scheduled, **Manage** includes **Cancel scheduled change**. Selecting it keeps your current tier after renewal. + +> [!IMPORTANT] +> Docker does not issue refunds or credits +> for remaining days in the current cycle. diff --git a/content/manuals/subscription/_index.md b/content/manuals/subscription/_index.md deleted file mode 100644 index de09f553bbae..000000000000 --- a/content/manuals/subscription/_index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Subscription -description: Learn about Docker subscription features and how to manage your subscription -keywords: docker subscription, pricing, billing, pro, team, business, subscription management -weight: 50 -params: - sidebar: - group: Platform -grid_subscriptions: - - title: Compare Docker subscriptions - description: Visit the pricing page to see what's included in different Docker subscriptions. - link: "https://www.docker.com/pricing?ref=Docs&refAction=DocsSubscription" - icon: magnifying-glass - - title: Set up your subscription - description: Get started setting up a personal or organization subscription. - link: /subscription/setup/ - icon: shopping-cart - - title: Scale your subscription - description: Scale your subscription to fit your needs. - link: /subscription/scale/ - icon: chart-bar - - title: Change your subscription - description: Learn how to upgrade or downgrade your subscription. - link: /subscription/change/ - icon: arrow-up-circle - - title: Docker Desktop license agreement - description: Review the terms of the Docker Subscription Service Agreement. - link: /subscription/desktop-license/ - icon: document-text - - title: Subscription FAQs - description: Find the answers you need and explore common questions. - link: /subscription/faq/ - icon: question-mark-circle -aliases: - - /docker-hub/billing/ - - /docker-hub/billing/faq/ ---- - -Docker subscriptions provide licensing for commercial use of Docker products including Docker Desktop, Docker Hub, Docker Build Cloud, Docker Scout, and Testcontainers Cloud. - -Use these resources to choose the right subscription for your needs or manage your existing subscription. - -{{< grid items="grid_subscriptions" >}} diff --git a/content/manuals/subscription/change.md b/content/manuals/subscription/change.md deleted file mode 100644 index 2ba187eaccbc..000000000000 --- a/content/manuals/subscription/change.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Change your subscription -linkTitle: Upgrade or change -description: Upgrade or downgrade your Docker subscription and understand billing changes -keywords: upgrade subscription, downgrade subscription, docker pricing, subscription changes -aliases: - - /docker-hub/upgrade/ - - /docker-hub/billing/upgrade/ - - /subscription/upgrade/ - - /subscription/downgrade/ - - /subscription/core-subscription/upgrade/ - - /subscription/core-subscription/downgrade/ - - /docker-hub/cancel-downgrade/ - - /docker-hub/billing/downgrade/ - - /billing/scout-billing/ - - /billing/subscription-management/ -weight: 30 ---- - -You can upgrade or downgrade your Docker subscription at any time to match your changing needs. This page explains how to make subscription changes and what to expect with billing and feature access. - -## Upgrade your subscription - -When you upgrade your Docker subscription, you immediately get access to all features and entitlements in your new subscription tier. - -> [!TIP] -> If you're upgrading from a Personal subscription to a Team subscription -> and want to keep your username, [convert your user account into an organization](../admin/organization/setup/convert-account.md). - -To upgrade your subscription: - -1. Sign in to [Docker Home](https://app.docker.com/) and select the organization - you want to upgrade. -1. Select **Billing** to view your current plans. -1. Select **Browse products**. -1. Choose **View plans** from the Docker product tile on the products catalog page. -1. Choose a Docker Team or Docker Business plan for the organization. -1. Follow the on-screen instructions to complete your upgrade. - - If you choose to pay using a US bank account, you must verify the account. - - For more information, see [Verify a bank account](/manuals/billing/payment-method.md#verify-a-bank-account). - -For detailed feature information, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs&refAction=DocsSubscriptionChange). - -## Downgrade considerations - -Consider the following before downgrading: - -- Team size and repositories: You may need to reduce team members and convert private repositories to public or delete them based on your new subscription limits. -- SSO and SCIM: If downgrading from Docker Business and your organization uses single sign-on, remove your SSO connection and verified domains first. Organization members who were auto-provisioned through SCIM need to reset their passwords to sign in without SSO. -- Private repository collaborators: Personal subscriptions don't include collaborators for private repositories. When downgrading from Pro to Personal, all collaborators are removed and additional private repositories are locked. - -For feature limits in each tier, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs&refAction=DocsSubscriptionChange). - -## Downgrade your subscription - -You can downgrade your Docker subscription at any time before the renewal date. The unused portion isn't refundable, but you retain access to paid features until the end of the current billing cycle. - -To downgrade your subscription: - -1. Sign in to [Docker Home](https://app.docker.com/) and select - the organization you want to downgrade. -1. Select **Billing**. -1. Select the action menu, then **Cancel subscription**. -1. Fill out the feedback survey to continue with cancellation. - -> [!IMPORTANT] -> -> If you have a sales-assisted Docker Business subscription, contact your account manager to downgrade your subscription. - -## Subscription pause policy - -You can't pause or delay a subscription. If a subscription invoice isn't paid by the due date, there's a 15-day grace period starting from the due date. diff --git a/content/manuals/subscription/desktop-license.md b/content/manuals/subscription/desktop-license.md deleted file mode 100644 index 747223dbfc52..000000000000 --- a/content/manuals/subscription/desktop-license.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Docker Desktop license agreement -description: Information about Docker Desktop's license agreement and commercial use requirements -keywords: docker desktop license, subscription service agreement, commercial use, licensing terms -weight: 60 ---- - -Docker Desktop is licensed under the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). When you download and install Docker Desktop, you're asked to agree to these terms. - -The Docker Subscription Service Agreement states: - - - Docker Desktop is free for: - - Small businesses (fewer than 250 employees AND less than $10 million in annual revenue) - - Personal use - - Education - - Non-commercial open source projects -- Docker Desktop requires a paid subscription for: - - Professional use in larger organizations - - Government entities - - Commercial use beyond the free tier limits -- Paid subscriptions that include Docker Desktop: - - Docker Pro, Team, and Business subscriptions - -## Understanding licensing terms - -For detailed information about how these terms may affect your organization, see: - -- [Subscription updates blog post](https://www.docker.com/blog/updating-product-subscriptions/) -- [Docker subscription FAQs](https://www.docker.com/pricing/faq) to learn how this may affect companies using Docker Desktop. - -> [!NOTE] -> -> The licensing and distribution terms for Docker and Moby open-source projects, such as Docker Engine, aren't changing. - -Docker Desktop is built using open-source software. For information about the licensing of open-source components in Docker Desktop, select the whale menu > **About Docker Desktop** > **Acknowledgements**. - -## Open source components - -Docker Desktop distributes some components that are licensed under the -GNU General Public License. [Download the source code for these components here](https://download.docker.com/opensource/License.tar.gz). diff --git a/content/manuals/subscription/details.md b/content/manuals/subscription/details.md deleted file mode 100644 index 95c090d3278e..000000000000 --- a/content/manuals/subscription/details.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Compare subscription -linkTitle: Compare -weight: 10 -params: - sidebar: - goto: "https://www.docker.com/pricing?ref=Docs&refAction=DocsSubscriptionDetails" ---- diff --git a/content/manuals/subscription/faq.md b/content/manuals/subscription/faq.md deleted file mode 100644 index c12254c063c8..000000000000 --- a/content/manuals/subscription/faq.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Subscription FAQs -linkTitle: FAQs -description: Frequently asked questions about Docker subscriptions and billing -keywords: subscription faqs, docker billing, subscription transfer, academic pricing, docker programs -tags: [FAQ] -weight: 70 ---- - -For more information on Docker subscriptions, see [Docker subscription overview](_index.md). - -## Can I transfer my subscription from one user or organization account to another? - -Subscriptions are non-transferable between accounts or organizations. - -## Can I pause or delay my Docker subscription? - -You can't pause or delay a subscription, but you can downgrade your subscription. If a subscription invoice isn't paid by the due date, there's a 15-day grace period starting from the due date. - -## Does Docker offer academic pricing? - -Contact the [Docker Sales Team](https://www.docker.com/company/contact) for information about academic pricing options. - -## How can I contribute to Docker content? - -Docker offers two content contribution programs: - -- [Docker-Sponsored Open Source Program (DSOS)](../docker-hub/repos/manage/trusted-content/dsos-program.md) for open source projects -- [Docker Verified Publisher (DVP)](../docker-hub/repos/manage/trusted-content/dvp-program.md) for commercial publishers - -You can also join the [Developer Preview Program](https://www.docker.com/community/get-involved/developer-preview/) or sign up for early access programs to participate in research and try new features. - -> [!TIP] -> -> Need to upgrade? Compare Docker Team and Docker Business to choose the plan that best fits your team's needs. \ No newline at end of file diff --git a/content/manuals/subscription/scale.md b/content/manuals/subscription/scale.md deleted file mode 100644 index 03b4f8ab8485..000000000000 --- a/content/manuals/subscription/scale.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Scale your subscription -linkTitle: Scale -description: Scale Docker Build Cloud, Testcontainers Cloud, Gordon, and DHI consumption for your subscription -keywords: scale subscription, docker build cloud minutes, testcontainers cloud minutes, gordon plan, docker hardened images, dhi repositories, usage scaling -weight: 40 ---- - -Docker subscriptions include basic entitlements that you can scale with additional add-ons as your needs grow. You can purchase different add-ons that extend usage for your personal or organization accounts: - -- Docker Hardened Images (DHI) Select repositories for organization accounts -- Gordon Plus, Max, and Ultra plans for personal accounts -- Seats for Docker Core subscriptions like Docker Team and Docker Business -- Licenses for individual products, like AI Governance (available for Docker Sandboxes) and Docker Offload -- Build minutes for Docker Build Cloud -- Cloud runtime minutes for Testcontainers - -## Add DHI Select to organization accounts - -DHI Select lets organization admins assign DHI repositories to organization accounts. All organization members can then access those DHI repositories, including members you add to the organization after initial setup. - -To purchase hardened repositories with DHI Select: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your organization. -1. Select **Billing**, then **Browse products**. -1. Select **Hardened Images** from the products page. -1. Choose the organization account that should receive the DHI repository, then **Continue**. You can add repositories for one account at a time. -1. Select **Add repositories**, then add the number of new repositories you want to add to the account. -1. Verify your billing details, continue to payment, and complete checkout. - -To manage the repositories in your active DHI Select plan: - -1. From the Billing overview page, select **Manage** next to **Hardened Images**. -1. Choose from the available actions: - - **Add repositories** lets you add additional repositories to your active plan. You will verify your billing details, continue to payment, and complete checkout. - - **Remove repositories** lets you remove repositories. - - **Disable auto-renewal** cancels your DHI Select plan at the end of the current billing cycle. - -To learn more about DHI Select, see [Get started with DHI Select and Enterprise](/manuals/dhi/how-to/select-enterprise.md). Purchasing eight or more hardened repositories? [Contact Docker sales](https://www.docker.com/pricing/contact-sales/) to discuss an Enterprise plan. - -## Add a Gordon Plus, Max, or Ultra plan to personal accounts - -> [!IMPORTANT] -> Gordon subscriptions apply to personal Docker accounts only. -> If you purchase a Gordon plan while signed in with an organization account, -> the subscription applies to your personal account automatically. - -Gordon Plus, Max, and Ultra plans increase your maximum Gordon usage allowance for your personal account. Gordon plans are billed at a monthly rate at the first of the month. If you purchase a Gordon plan after the first of the month, you'll be billed on a prorated basis. - -To add a new Gordon plan to your account: - -1. Sign in to [Docker Home](https://app.docker.com/) and select your Docker personal account. -1. Select **Billing**, then **Browse products**. -1. Select **View plans** from the **Upgrade Gordon** section of the products page. -1. Choose the Gordon subscription plan you want to apply to your personal account. -1. Verify your billing details, continue to payment, and complete checkout. - -If you have an active Gordon plan and want to upgrade to a higher tier, your new usage allowance takes effect immediately. You pay a prorated charge for the higher tier for the rest of the current billing period. - -To upgrade your Gordon plan: - -1. From the Billing overview page, select **Manage** from the Gordon tile under your active plans. -1. Select **Upgrade plan** and choose the new plan you want to upgrade to. -1. Verify your billing details, continue to payment, and complete checkout. - -To learn about Gordon usage, see [Gordon usage limits and tiers](/manuals/ai/gordon/usage-limits.md). - -## Add licenses - -Licenses add a layer to your Docker subscriptions, letting you assign products to select members of your -organization without consuming a Docker Core seat. You can purchase licenses for some Docker products: - -- AI Governance -- Docker Offload - -Once you've purchased licenses for your organization, you can [manage license assignment](/manuals/admin/organization/manage/manage-licenses.md) from the **Members** page in Docker Home. - -> [!TIP] -> To purchase licenses for AI Governance and Docker Offload, contact sales. - -### AI Governance licenses - -AI Governance licenses let admins create and apply organization-wide AI Governance policies for license-holding members. - -- AI Governance licenses apply to Docker Sandbox usage. -- AI Governance licenses are separate from Docker Team or Business, so you can purchase AI Governance licenses without an existing subscription. -- When you purchase AI Governance licenses, you may assign them to organization members without a Docker Core seat. - -When a member who holds an AI Governance license uses Docker Sandbox, the organization policy overrides the member’s local policy rules. Members without AI Governance licenses can still use Docker Sandbox, but organization policies will not govern their usage. - -### Docker Offload licenses - -Docker Offload lets developers offload building and running containers to the cloud. - -- You must have a Docker Team or Docker Business subscription. -- You can only assign Docker Offload licenses to members with Docker Team or Docker Business. - -## Add minutes - -Minutes don't roll over. Base subscription minutes reset each billing period and don't accumulate. Additional purchased minutes expire at the end of your subscription period. - -For example, with an annual Docker Team subscription (500 included minutes), if you purchase 500 additional minutes, only the additional 500 minutes roll over until your annual renewal. - -### Docker Build Cloud build minutes - -Purchase additional build minutes through the Docker Build Cloud Dashboard: - -1. Sign in to [Docker Home](https://app.docker.com/) and choose - your organization. -1. Select **Build Cloud**, then **Build minutes**. -1. Select **Add minutes**. -1. Select your additional minute amount, then **Continue to payment**. -1. Enter your payment details and billing address. -1. Review your order and select **Pay**. - -Your additional minutes appear on the Build minutes page immediately. - -### Docker Testcontainers Cloud runtime minutes - -You can add Testcontainers Cloud runtime minutes in two ways: - -- Contact sales to pre-purchase runtime minutes at discounted rates -- Use unlimited runtime minutes on-demand with billing at the end of each monthly cycle - -On-demand usage is billed at higher rates than pre-purchased capacity. To avoid higher on-demand charges, pre-purchase additional minutes if you expect consistent usage over your subscription's included minutes. - -## What's next - -- [Manage licenses](/manuals/admin/organization/manage/manage-licenses.md) -- [Manage seats](/manuals/admin/organization/manage/manage-seats.md) -- [View your consumption](../admin/organization/manage/manage-products.md#monitor-product-usage-for-your-organization) -- [Docker Build Cloud overview](/manuals/build-cloud/_index.md) -- [DHI Select and Enterprise quickstart](/manuals/dhi/how-to/select-enterprise.md) -- [Testcontainers overview](/manuals/testcontainers.md) diff --git a/content/manuals/subscription/setup.md b/content/manuals/subscription/setup.md deleted file mode 100644 index 77d1333589ec..000000000000 --- a/content/manuals/subscription/setup.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Set up Docker subscriptions for personal accounts and organizations -keywords: subscription setup, docker pro, docker team, docker business, organization setup, gordon plan -title: Set up your subscription -linkTitle: Setup -weight: 20 ---- - -Docker subscriptions provide features and benefits for individual developers, teams, and enterprise businesses. This page explains how to set up subscriptions for personal accounts and organizations. - -Before you begin, make sure you have a [Docker ID](../accounts/create-account.md). To learn more about what's included in each tier, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs&refAction=DocsSubscriptionSetup). - -## Personal accounts - -When you [create your Docker ID](../accounts/create-account.md), you automatically get a Docker Personal subscription. This subscription includes essential Docker tools at no cost. - -- To learn about Docker Pro subscriptions, [compare Docker Personal and Docker Pro](https://www.docker.com/pricing/). -- To increase your Gordon usage allowance, see [Scale your subscription](/manuals/subscription/scale.md). - -## Organization accounts - -You can subscribe a new or existing organization to Docker Team or Business subscriptions. Only organization owners can manage billing for the organization. - -1. [Create your Docker ID](../accounts/create-account.md) if you don't already have one. -1. [Create your organization](../admin/organization/setup/orgs.md) or use an existing organization you own. -1. Select **Billing** to view your current plans, then select **Browse products**. -1. From the products catalog page, select **View plans** from the Docker tile. -1. Choose a Docker Team or Business subscription for the organization. -1. Fill in plan entitlements, verify your billing details, then continue to payment to complete checkout. - -## What's next - -- To upgrade an existing organization's subscription, see [Upgrade your subscription](./change.md#upgrade-your-subscription). -- To scale your subscription with add-ons like DHI Select, Gordon plans, licenses, or usage minutes, see [Scale your subscription](/manuals/subscription/scale.md). diff --git a/content/manuals/support/_index.md b/content/manuals/support/_index.md index 713a828b4830..89bf197388de 100644 --- a/content/manuals/support/_index.md +++ b/content/manuals/support/_index.md @@ -1,49 +1,67 @@ --- title: Get support for Docker products linkTitle: Support -description: Learn about support options for Docker products including paid subscriptions and community resources -keywords: support, help, docker desktop, subscriptions, community, troubleshooting -weight: 5 +description: >- + Find Docker support options, including paid subscription response times, + severity levels, Docker Desktop support scope, and community resources. +keywords: docker support, contact support, subscription support, premium + support, support response times, severity levels, community forums, + docker desktop support +weight: 50 params: sidebar: - group: Platform + group: Accounts and admin --- -Docker offers multiple support channels depending on your subscription level and needs. +Docker offers multiple support channels depending on your subscription level +and needs. ## Paid subscription support -All Docker Pro, Team, and Business subscribers receive email support for Docker products. +All Docker Pro, Team, and Business subscribers receive email support for +Docker products. ### Support response times -- Docker Pro: 3 business day response +- Docker Pro: 5 business day response - Docker Team: 2 business day response, 24×5 availability - Docker Business: 1 business day response, 24×5 availability +Docker Verified Publisher (DVP) organizations follow the response times for +their Docker Pro, Team, or Business subscription. Without one of those +subscriptions, the following response times apply: + +- DVP Starter: 3 business day response +- DVP Growth: 2 business day response, 24×5 availability + > [!TIP] > -> Premium Support with faster response times and 24×7 availability is available as an add-on for [Docker Business subscribers](https://www.docker.com/pricing?ref=Docs&refAction=DocsSupport). +> Premium Support with faster response times and 24×7 availability is +> available as an add-on for +> [Docker Business and Docker Hardened Images subscribers](https://www.docker.com/pricing?ref=Docs&refAction=DocsSupport). ### Support severity levels -| Level | Description | -| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Level | Description | +| :--- | :--- | | Critical | Widespread or company-wide service outage affecting many customers or all users within a single organization. Business operations are halted with no workaround available. | -| High | Team or department-level impact preventing significant users from accessing core functionality. Severe business impact with no workaround exists. | -| Medium | Individual user or small group impact causing partial loss of functionality. Business operations continue, often with workarounds available but reduced productivity. | +| High | Team or department-level impact preventing significant users from accessing core functionality. Severe business impact with no workaround available. | +| Medium | Individual user or small group impact causing partial loss of functionality. Business operations continue, often with workarounds available but reduced productivity. | ### Request support > [!TIP] > -> Before reaching out for support, review the troubleshooting documentation for your product. +> Before reaching out for support, review the troubleshooting documentation +> for your product. -If you have a paid Docker subscription, [contact the Support team](https://hub.docker.com/support/contact/). +If you have a paid Docker subscription, +[contact the Support team](https://hub.docker.com/support/contact/). ## Community support -All Docker users can seek support through community resources, where Docker or the community respond on a best effort basis: +All Docker users can seek support through community resources, where Docker +or the community respond on a best-effort basis: - [Docker Community Forums](https://forums.docker.com/) - [Docker Community Slack](http://dockr.ly/comm-slack) @@ -55,7 +73,7 @@ Docker Desktop support is available with a paid subscription. ### Scope of support {{< tabs >}} -{{< tab name="Covered">}} +{{< tab name="Covered" >}} Docker Desktop support includes: @@ -66,27 +84,29 @@ Docker Desktop support includes: - Push or pull issues, including rate limiting - Application crashes or unexpected behavior - Automated builds -- Basic product 'how to' questions +- Basic product how-to questions -**Windows-specific:** +On Windows, support also covers: - Turning on virtualization in BIOS - Turning on Windows features -- Running inside [certain VM or VDI environments](/manuals/desktop/setup/vm-vdi.md) (Docker Business only) +- Running inside + [certain VM or VDI environments](/manuals/desktop/setup/vm-vdi.md) + (Docker Business only) {{< /tab >}} -{{< tab name="Not covered">}} +{{< tab name="Not covered" >}} Docker Desktop support excludes: -- Unsupported operating systems, including beta/preview versions +- Unsupported operating systems, including beta and preview versions - Running containers of a different architecture using emulation - Docker Engine, Docker CLI, or other bundled Linux components - Kubernetes - Features labeled as experimental -- System/Server administration activities +- System and server administration activities - Desktop as a production runtime -- Scale deployment/multi-machine installation +- Scale deployment and multi-machine installation - Routine product maintenance (data backup, disk space, log rotation) - Third-party applications not provided by Docker - Altered or modified Docker software @@ -97,17 +117,20 @@ Docker Desktop support excludes: > [!NOTE] > -> Support for [running Docker Desktop in a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md) is only available to Docker Business customers. +> Support for +> [running Docker Desktop in a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md) +> is only available to Docker Business customers. {{< /tab >}} {{< /tabs >}} ### Supported versions -- Docker Business: Versions up to six months older than the latest version (fixes applied to latest version only) +- Docker Business: Versions up to six months older than the latest version + (fixes applied to latest version only) - Docker Pro and Team: Latest version only -### Number of machines +### Machines per subscription - Docker Pro: One machine - Docker Team: Number of machines equal to subscription seats @@ -119,14 +142,20 @@ Docker Desktop support excludes: - [Windows system requirements](/manuals/desktop/setup/install/windows-install.md#system-requirements) - [Linux system requirements](/manuals/desktop/setup/install/linux/_index.md#system-requirements) -### Community resources +### Docker Desktop community resources - [Docker Desktop issue tracker](https://github.com/docker/desktop-feedback) ### Diagnostic data and privacy -When uploading diagnostics, the bundle may contain personal data such as usernames and IP addresses. Diagnostics bundles are only accessible to Docker, Inc. employees directly involved in diagnosing issues. +When uploading diagnostics, the bundle may contain personal data such as +usernames and IP addresses. Diagnostics bundles are only accessible to +Docker, Inc. employees directly involved in diagnosing issues. -By default, Docker, Inc. deletes uploaded diagnostics bundles after 30 days. You may request removal of a diagnostics bundle by specifying the diagnostics ID or your GitHub ID. Docker, Inc. only uses the data to investigate specific user issues but may derive high-level (non-personal) metrics. +By default, Docker, Inc. deletes uploaded diagnostics bundles after 30 days. +You can request removal of a diagnostics bundle by specifying the diagnostics +ID or your GitHub ID. Docker, Inc. only uses the data to investigate specific +user issues but may derive high-level (non-personal) metrics. -For more information, see [Docker Data Processing Agreement](https://www.docker.com/legal/data-processing-agreement). +For more information, see +[Docker Data Processing Agreement](https://www.docker.com/legal/data-processing-agreement). diff --git a/content/manuals/testcontainers.md b/content/manuals/testcontainers.md index 3107688a0499..0f69fecf18c4 100644 --- a/content/manuals/testcontainers.md +++ b/content/manuals/testcontainers.md @@ -74,12 +74,3 @@ with different languages and popular frameworks: - [Replace H2 with a real database for testing](/guides/testcontainers-java-replace-h2/) - [Configuration of services running in a container](/guides/testcontainers-java-service-configuration/) - [Testing an ASP.NET Core web app](/guides/testcontainers-dotnet-aspnet-core/) -- [Testing Spring Boot Kafka Listener](/guides/testcontainers-java-spring-boot-kafka/) -- [Testing REST API integrations using MockServer](/guides/testcontainers-java-mockserver/) -- [Testing AWS service integrations using LocalStack](/guides/testcontainers-java-aws-localstack/) -- [Testing Quarkus applications with Testcontainers](/guides/testcontainers-java-quarkus/) -- [Working with jOOQ and Flyway using Testcontainers](/guides/testcontainers-java-jooq-flyway/) -- [Testing REST API integrations using WireMock](/guides/testcontainers-java-wiremock/) -- [Securing Spring Boot with Keycloak and Testcontainers](/guides/testcontainers-java-keycloak-spring-boot/) -- [Testing Micronaut REST API with WireMock](/guides/testcontainers-java-micronaut-wiremock/) -- [Testing Micronaut Kafka Listener](/guides/testcontainers-java-micronaut-kafka/) diff --git a/content/manuals/unassociated-machines/_index.md b/content/manuals/unassociated-machines/_index.md deleted file mode 100644 index c7b5e8b705e0..000000000000 --- a/content/manuals/unassociated-machines/_index.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Manage unassociated machines -description: Learn how to manage unassociated machines using the Docker Admin Console -keywords: unassociated machines, insights, manage users, enforce sign-in -sitemap: false -pagefind_exclude: true -noindex: true -params: - sidebar: - group: Enterprise ---- - -{{< restricted title="About unassociated machines" >}} -Unassociated machines is a private feature that may not be available to all -accounts. -{{< /restricted >}} - -Docker administrators can identify, view, and manage Docker Desktop machines -that are likely associated with their organization but aren't currently linked -to user accounts. This self-service capability helps you understand Docker -Desktop usage across your organization and streamline user onboarding without -IT involvement. - -## Prerequisites - -- Docker Business or Team subscription -- Organization owner access to your Docker organization - -## About unassociated machines - -Unassociated machines are Docker Desktop instances that Docker has identified -as likely belonging to your organization based on usage patterns, but the users -are not signed in to Docker Desktop with an account that is part of your -organization. - -## How Docker identifies unassociated machines - -Docker uses telemetry data to identify which machines likely belong to your -organization: - -- Domain matching: Users signed in with email domains associated with your - organization -- Registry patterns: Analysis of container registry access patterns that - indicate organizational usage - -## View unassociated machines - -To see detailed information about unassociated machines: - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. - -The machine list displays: - -- Machine ID (Docker-generated identifier) -- The registry address used to predict whether a user is part of your - organization -- User email (only displays if the user is signed into Docker Desktop while - using it) -- Docker Desktop version -- Operating system (OS) -- Last activity date -- Sign-in enforced status - -You can: - -- Export the list as CSV -- Take actions on individual or multiple machines - -## Enable sign-in enforcement for unassociated machines - -> [!NOTE] -> -> Sign-in enforcement for unassociated machines is different from -> the [organization-level sign-in enforcement](/enterprise/security/enforce-sign-in/) -> available through `registry.json` and configuration profiles. This sign-in -> enforcement only requires users to sign in so admins can identify who is -> using the machine, meaning users can sign in with any email address. For more -> stringent security controls that limit sign-ins to users who are already part -> of your organization, see [Enforce sign-in](/enterprise/security/enforce-sign-in/). - -Sign-in enforcement helps you identify who is using unassociated machines in -your organization. When you enable enforcement, users on these machines will -be required to sign in to Docker Desktop. Once they sign in, their email -addresses will appear in the Unassociated list, allowing you to then add them -to your organization. - -You can enable sign-in enforcement using two methods: - -- For all unassociated machines in your organization -- For individual unassociated machines - -> [!IMPORTANT] -> -> Sign-in enforcement only takes effect after Docker Desktop is restarted. -> Users can continue using Docker Desktop until their next restart. - -### Enable sign-in enforcement for all unassociated machines - -To enable sign-in enforcement for all unassociated machines: - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Turn on the **Enforce sign-in** toggle. -1. In the pop-up modal, select **Require sign-in** to confirm. - -The **Sign-in required** status will update for all unassociated machines to -**Yes**. - -> [!NOTE] -> -> When you enable sign-in enforcement for all unassociated machines, any new -> machines detected in the future will automatically have sign-in enforcement -> enabled. Sign-in enforcement requires Docker Desktop version 4.41 or later. -> Users with older versions will not be prompted to sign in and can continue -> using Docker Desktop normally until they update. Their status shows -> as **Pending** until they update to version 4.41 or later. - -### Enable sign-in enforcement for individual unassociated machines - -To enable sign-in enforcement for individual unassociated machines: - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Locate the machine you want to enable sign-in enforcement for. -1. Select the **Actions** menu and choose **Turn on sign-in enforcement**. -1. In the pop-up modal, select **Require sign-in** to confirm. - -The **Sign-in required** status will update for the individual machine to -**Yes**. - -> [!NOTE] -> -> Sign-in enforcement requires Docker Desktop version 4.41 or later. Users -> with older versions will not be prompted to sign in and can continue using -> Docker Desktop normally until they update. Their status shows as **Pending** -> until they update to version 4.41 or later. - -### What happens when users sign in - -After you enable sign-in enforcement: - -1. Users must restart Docker Desktop. Enforcement only takes effect after - restart. -1. When users open Docker Desktop, they see a sign-in prompt. They must sign - in to continue using Docker Desktop. -1. User email addresses appear in the **Unassociated** list. -1. You can add users to your organization. - -Users can continue using Docker Desktop immediately after signing in, even -before being added to your organization. - -## Add unassociated machines to your organization - -When users in your organization use Docker without signing in, their machines -appear in the **Unassociated** list. You can add these users to your -organization in two ways: - -- Automatic addition: - - Auto-provisioning: If you have verified domains with auto-provisioning - enabled, users who sign in with a matching email domain will automatically - be added to your organization. For more information on verifying domains and - auto-provisioning, see [Domain management](/enterprise/security/domain-management). - - SSO user provisioning: If you have SSO configured with - [Just-in-Time provisioning](/manuals/enterprise/security/provisioning/just-in-time.md), - users who sign in through your SSO connection will automatically be added - to your organization. -- Manual addition: If you don't have auto-provisioning or SSO set up, or if a - user's email domain doesn't match your configured domains, their email will - appear in the **Unassociated** list where you can choose to add them directly. - -> [!NOTE] -> -> If you add users and do not have enough seats in your organization, a -> pop-up will appear prompting you to **Get more seats**. - -### Add individual users - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Locate the machine you want to add to your organization. -1. Select the **Actions** menu and choose **Add to organization**. -1. In the pop-up modal, select **Add user**. - -### Bulk add users - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Use the **checkboxes** to select the machines you want to add to your - organizations. -1. Select the **Add to organization** button. -1. In the pop-up modal, select **Add users** to confirm. - -## Disable sign-in enforcement - -### Disable for all unassociated machines - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Turn off the **Enforce sign-in** toggle. -1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. - -The **Sign-in required** status will update for all unassociated machines to -**No**. - -### Disable for specific unassociated machines - -1. Sign in to the [Admin Console](https://app.docker.com/admin) and select - your organization. -1. In **User management**, select **Unassociated**. -1. Locate the machine you want to disable sign-in enforcement for. -1. Select the **Actions** menu and choose **Turn off sign-in enforcement**. -1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. - -The **Sign-in required** status will update for the individual machine to -**No**. diff --git a/content/reference/_index.md b/content/reference/_index.md index 67c45581e6cf..ddb8ca229e0d 100644 --- a/content/reference/_index.md +++ b/content/reference/_index.md @@ -3,6 +3,7 @@ title: Reference documentation linkTitle: Reference layout: wide description: Find reference documentation for the Docker platform’s various APIs, CLIs, and file formats +keywords: Docker reference, API, CLI, file formats params: icon: command-line notoc: true @@ -30,6 +31,10 @@ params: icon: cpu-chip link: /reference/cli/dockerd/ grid_apis: + - title: Sandboxes API + description: Create cloud sandboxes, run processes, and manage sandbox resources. + icon: code-bracket + link: /reference/api/sandboxes/latest/ - title: Engine API description: The main API for Docker, provides programmatic access to a daemon. icon: code-bracket diff --git a/content/reference/api/_content.gotmpl b/content/reference/api/_content.gotmpl new file mode 100644 index 000000000000..d3e104d9fa40 --- /dev/null +++ b/content/reference/api/_content.gotmpl @@ -0,0 +1,28 @@ +{{- $data := index hugo.Data "api-reference" -}} +{{- if not $data }} + {{ errorf "API reference data missing: regenerate data/api-reference.json with ./hack/api-docs/run.sh generate" }} +{{ end -}} +{{- if ne (int $data.modelVersion) 1 }} + {{ errorf "Unsupported API presentation model version" }} +{{ end -}} +{{- .AddPage (dict "path" "." "kind" "section" "title" "Docker APIs" "linkTitle" "API reference" "description" "Explore Docker HTTP APIs, connection requirements, and versioned references." "layout" "api-docs" "params" (dict "view" "catalog" "keywords" (slice "API" "HTTP" "OpenAPI"))) -}} +{{- range $api := $data.apis -}} + {{- $path := strings.TrimPrefix "/reference/api/" $api.url | strings.TrimSuffix "/" -}} + {{- $aliases := slice -}} + {{- if eq $api.id "dvp" }} + {{ $aliases = slice "/reference/api/hub/dvp/" }} + {{ end -}} + {{- if eq $api.id "ai-governance" }} + {{ $aliases = slice "/reference/api/ai-governance/" "/ai/sandboxes/governance/api/" }} + {{ end -}} + {{- if eq $api.id "sandboxes" }} + {{ $aliases = slice "/reference/api/sandboxes/" }} + {{ end -}} + {{- $.AddPage (dict "linkTitle" "Latest" "path" $path "url" $api.url "aliases" $aliases "kind" "section" "title" (printf "%s API %v" $api.title $api.version) "description" (printf "%s HTTP API reference, version %v." $api.title $api.version) "layout" "api-docs" "weight" 1 "params" (dict "view" "overview" "apiID" $api.id "keywords" (slice "API" $api.product))) -}} + {{- range $op := $api.operations -}} + {{- $.AddPage (dict "path" (printf "%s/operations/%s" $path (crypto.SHA256 $op.id)) "url" $op.url "title" $op.summary "description" (printf "%s %s — %s API %v." $op.method $op.path $api.title $api.version) "layout" "api-docs" "params" (dict "view" "operation" "apiID" $api.id "operationID" $op.id "keywords" (slice $op.method $op.path $op.id))) -}} + {{- end -}} + {{- range $schema := $api.schemas -}} + {{- $.AddPage (dict "path" (printf "%s/schemas/%s" $path (crypto.SHA256 $schema.name)) "url" $schema.url "title" $schema.name "description" (printf "%s schema in %s API %v." $schema.name $api.title $api.version) "layout" "api-docs" "params" (dict "view" "schema" "apiID" $api.id "schemaName" $schema.name "keywords" (slice "schema" $schema.name))) -}} + {{- end -}} +{{- end -}} diff --git a/content/reference/api/_index.md b/content/reference/api/_index.md deleted file mode 100644 index 53ae13d37bd4..000000000000 --- a/content/reference/api/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: API reference -build: - render: never ---- - diff --git a/content/reference/api/ai-governance/_index.md b/content/reference/api/ai-governance/_index.md new file mode 100644 index 000000000000..1a2f8d76b6bf --- /dev/null +++ b/content/reference/api/ai-governance/_index.md @@ -0,0 +1,7 @@ +--- +title: Docker AI Governance API +description: HTTP API reference for managing Docker AI Governance policies and rules programmatically. +keywords: docker sandboxes, governance API, policy API, organization policy, REST API, openapi +build: + render: never +--- diff --git a/content/reference/api/ai-governance/api.yaml b/content/reference/api/ai-governance/api.yaml index 891d0bce1b68..b14ba72ec835 100644 --- a/content/reference/api/ai-governance/api.yaml +++ b/content/reference/api/ai-governance/api.yaml @@ -1,4 +1,5 @@ -openapi: "3.1.0" +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base info: title: Docker AI Governance Policy API @@ -25,16 +26,20 @@ info: **Propagation.** Policy changes take up to five minutes to reach developer machines after being written. - See https://docs.docker.com/ai/sandboxes/governance/ for product - documentation. + See the [AI Governance documentation](https://docs.docker.com/ai/sandboxes/governance/) + for product documentation. contact: name: Docker url: https://www.docker.com/products/ai-governance/ tags: - name: policies + summary: Policies + kind: nav description: Policy lifecycle management - name: rules + summary: Rules + kind: nav description: Rule management within an allowlist policy servers: @@ -52,21 +57,52 @@ paths: tags: [policies] summary: List policies description: > - Returns a shallow summary of all policies for the org. + Returns a shallow summary of the organization's policies, one page at a time. The rule set is not included; use GetPolicy to fetch the full object. + + + Results are paginated with an opaque cursor. Pass `page_size` to bound + the page; if more policies remain, the response includes a non-null + `next_page_token` to pass as `page_token` on the next request. Iterate + until `next_page_token` is `null`. Treat the token as opaque; do not + parse or construct it. + parameters: + - name: page_size + in: query + required: false + description: > + Maximum number of policies to return. Defaults to 100 if omitted or + zero. The server caps values above 100 at 100. + schema: + type: integer + minimum: 0 + default: 100 + - name: page_token + in: query + required: false + description: > + Opaque cursor from a previous response's `next_page_token`. Omit to + fetch the first page. + schema: + type: string responses: "200": - description: Object wrapping an array of policy summaries under `data`. Rule sets are not included; use GetPolicy to fetch a full policy. + description: Object wrapping an array of policy summaries under `data` and a `next_page_token`, which is null on the last page. Rule sets are not included; use GetPolicy to fetch a full policy. content: application/json: schema: type: object - required: [data] + required: [data, next_page_token] properties: data: type: array items: $ref: "#/components/schemas/PolicySummary" + next_page_token: + type: [string, "null"] + description: > + The opaque cursor for the next page, or `null` on the last page. + example: AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ examples: default: value: @@ -79,6 +115,9 @@ paths: created_at: "2026-04-22T00:00:00Z" updated_at: "2026-04-22T00:00:00Z" type: allowlist_v0 + next_page_token: AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ + "400": + $ref: "#/components/responses/InvalidArgument" "401": $ref: "#/components/responses/Unauthenticated" "403": @@ -130,7 +169,7 @@ paths: "401": $ref: "#/components/responses/Unauthenticated" "403": - $ref: "#/components/responses/PermissionDenied" + $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": @@ -191,7 +230,7 @@ paths: while an omitted sub-field is left untouched and an empty list clears it (org-wide). - The rule set is not modified here — use the rule endpoints for that. + The rule set is not modified here. Use the rule endpoints for that. At least one field must be present. Returns the policy in both its old and new states. Changes may take up to five minutes to reach developer machines. @@ -259,7 +298,7 @@ paths: "401": $ref: "#/components/responses/Unauthenticated" "403": - $ref: "#/components/responses/PermissionDenied" + $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": @@ -319,7 +358,9 @@ paths: summary: Create rule description: | Adds a rule to the policy's rule set. All rules in a policy must share - the same domain (network or filesystem); mixing domains is rejected. + the same domain (`network`, which includes HTTP, or `filesystem`); + mixing domains is rejected. A single rule cannot mix L4 network and L7 + HTTP actions. **Network** actions: `connect:tcp`, `connect:udp`. Resources are hostnames (for example, `example.com`), wildcard subdomains (`*.example.com` @@ -331,9 +372,13 @@ paths: `/data`). Use `*` to match within a single path segment and `**` to match recursively across segments (for example, `/data/**`). + **HTTP** actions identify request methods, such as `request:get` and + `request:post`. Use `http_resources` to identify the host, optional port, + and absolute path glob. HTTP rules must not supply `resources`. + Changes may take up to five minutes to reach developer machines. requestBody: - description: Rule definition including actions, resources, and decision. + description: Rule definition including actions, matching resources, and decision. required: true content: application/json: @@ -354,6 +399,16 @@ paths: actions: [read, write] resources: [/data] decision: allow + http: + summary: HTTP rule + value: + name: read GitHub repositories + actions: [request:get, request:head] + http_resources: + - host: api.github.com + port: 443 + path: /repos/docker/** + decision: allow responses: "201": description: Rule created and added to the policy's rule set. @@ -378,12 +433,23 @@ paths: actions: [read, write] resources: [/data] decision: allow + http: + summary: HTTP rule + value: + id: rule_08gxuos1lo3rfum2c0pmgcz09lpc + name: read GitHub repositories + actions: [request:get, request:head] + http_resources: + - host: api.github.com + port: 443 + path: /repos/docker/** + decision: allow "400": $ref: "#/components/responses/InvalidArgument" "401": $ref: "#/components/responses/Unauthenticated" "403": - $ref: "#/components/responses/PermissionDenied" + $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": @@ -406,8 +472,10 @@ paths: old and new states. Changing `actions` across domains (for example, from network actions to - filesystem actions) is rejected. Changes may take up to five minutes to - reach developer machines. + filesystem actions) is rejected while other rules remain in the policy. + When changing a rule between L4 network and L7 HTTP, supply the matching + `resources` or `http_resources` in the same request. Changes may take up + to five minutes to reach developer machines. requestBody: description: Fields to update. Absent fields are left unchanged. required: true @@ -510,7 +578,7 @@ components: PAT and OAT strings can't be used directly as a bearer token. They must be exchanged at the token endpoint first. - See [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/#tag/authentication-api/operation/AuthCreateAccessToken) + See [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/) for full details. parameters: @@ -581,14 +649,17 @@ components: type: type: string description: > - Identifies the rule-set format. Always `allowlist_v0`, corresponding - to the `allowlist_v0` property on the full Policy object. + Identifies the policy type. `allowlist_v0` for network, HTTP, and + filesystem allowlist policies; `cedar_v1` for Cedar language policies. + enum: [allowlist_v0, cedar_v1] examples: - allowlist_v0 Policy: type: object - description: Full policy representation including the allowlist rule set. + description: > + Full policy representation. Exactly one of `allowlist_v0` or `cedar_v1` + is present, depending on the policy type. required: [id, name, org, scope, created_at, updated_at] properties: id: @@ -618,6 +689,8 @@ components: - "2026-04-22T00:00:00Z" allowlist_v0: $ref: "#/components/schemas/AllowlistV0" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" Scope: type: object @@ -627,14 +700,14 @@ components: type: array items: type: string - description: Team UUIDs the policy applies to. Each must be a valid team in the org. + description: Team IDs the policy applies to. Each must be a valid team in the organization. examples: - ["d290f1ee-6c54-4b01-90e6-d701748f0851"] AllowlistV0: type: object description: | - Network or filesystem allowlist containing a list of rules. Present on + Network, HTTP, or filesystem allowlist containing a list of rules. Present on Policy when `PolicySummary.type` is `allowlist_v0`; omitted when the policy has no rules yet. All rules in an allowlist share the same domain. All rules are evaluated on every request: `deny` always wins over `allow`. @@ -656,10 +729,42 @@ components: items: $ref: "#/components/schemas/Rule" + CedarV1Policy: + type: object + description: > + Cedar:V1 policy body. Present on `Policy` when `PolicySummary.type` is + `cedar_v1`. Cedar policies encode their rules directly in `text` rather + than in the rules sub-resource; the rules endpoints are not available for + Cedar policies. + required: [text, schema_url] + properties: + text: + type: string + description: > + One or more Cedar `permit` or `forbid` statements. Must be + syntactically valid Cedar and must not carry an `@id` annotation + (IDs are server-assigned). + examples: + - 'permit(principal, action == MCP::Action::"call_tool", resource is MCP::Tool);' + schema_url: + type: string + description: > + URL of the Cedar schema this policy was authored against. The + evaluator looks up the schema by this URL from its built-in + registry. Use `https://schemas.docker.com/policy/cedar/v1/mcp/v0` + for MCP policies. + examples: + - "https://schemas.docker.com/policy/cedar/v1/mcp/v0" + Rule: type: object description: A single allow or deny rule within an allowlist policy. - required: [id, name, actions, resources, decision] + required: [id, name, actions, decision] + oneOf: + - type: object + required: [resources] + - type: object + required: [http_resources] properties: id: type: string @@ -674,12 +779,18 @@ components: $ref: "#/components/schemas/RuleActions" resources: $ref: "#/components/schemas/RuleResources" + http_resources: + $ref: "#/components/schemas/HTTPResources" decision: $ref: "#/components/schemas/RuleDecision" CreatePolicyRequest: type: object - description: Fields required to create a new policy. + description: > + Fields required to create a new policy. Omitting `cedar_v1` creates an + `allowlist_v0` policy with an empty rule set. Supplying `cedar_v1` creates + a Cedar:V1 policy; rules are embedded in the Cedar text rather than managed + via the rules sub-resource. required: [name] properties: name: @@ -689,11 +800,18 @@ components: - "Security Research — hardened" scope: $ref: "#/components/schemas/Scope" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" CreateRuleRequest: type: object description: Fields required to create a new rule within a policy's rule set. - required: [name, actions, resources, decision] + required: [name, actions, decision] + oneOf: + - type: object + required: [resources] + - type: object + required: [http_resources] properties: name: type: string @@ -704,12 +822,17 @@ components: $ref: "#/components/schemas/RuleActions" resources: $ref: "#/components/schemas/RuleResources" + http_resources: + $ref: "#/components/schemas/HTTPResources" decision: $ref: "#/components/schemas/RuleDecision" UpdateRuleRequest: type: object description: Partial update. Only fields present in the body are updated; absent fields are left unchanged. + not: + type: object + required: [resources, http_resources] properties: name: type: string @@ -720,6 +843,8 @@ components: $ref: "#/components/schemas/RuleActions" resources: $ref: "#/components/schemas/RuleResources" + http_resources: + $ref: "#/components/schemas/HTTPResources" decision: $ref: "#/components/schemas/RuleDecision" @@ -744,9 +869,10 @@ components: UpdatePolicyRequest: type: object description: > - Partial update of a policy's metadata. Only fields present in the body - are updated; the rule set is not modified here. At least one field must - be present. + Partial update of a policy. Only fields present in the body are updated; + absent fields are left unchanged. At least one field must be present. + For `cedar_v1` policies, supply `cedar_v1` to replace the policy text; + `name` and `scope` may be combined freely. properties: name: type: string @@ -756,6 +882,8 @@ components: - Security Research scope: $ref: "#/components/schemas/ScopePatch" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" ScopePatch: type: object @@ -793,13 +921,29 @@ components: type: array items: type: string - enum: [connect:tcp, connect:udp, read, write] + enum: + - connect:tcp + - connect:udp + - read + - write + - request:get + - request:post + - request:put + - request:delete + - request:patch + - request:head + - request:options + - request:connect + - request:trace minItems: 1 description: > Network actions: `connect:tcp`, `connect:udp`. Filesystem actions: `read`, `write`. - All actions in a rule must belong to the same domain; mixing network - and filesystem actions in one rule is rejected. + HTTP actions: `request:get`, `request:post`, `request:put`, + `request:delete`, `request:patch`, `request:head`, `request:options`, + `request:connect`, `request:trace`. + All actions in a rule must belong to the same layer; mixing HTTP, + network, or filesystem actions in one rule is rejected. examples: - ["connect:tcp", "connect:udp"] @@ -815,9 +959,48 @@ components: (for example, `10.0.0.0/8` or `2001:db8::/32`). Filesystem domain: paths (for example, `/data`); `*` matches within one path segment, `**` matches recursively (for example, `/data/**`). + Required for network and filesystem rules and forbidden for HTTP rules. examples: - ["research.mitre.org", "cve.mitre.org"] + HTTPResources: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/HTTPResource" + description: > + HTTP request targets. Required for HTTP rules and forbidden for network + and filesystem rules. A request matches when any target matches. + + HTTPResource: + type: object + required: [host, path] + properties: + host: + type: string + minLength: 1 + description: > + Domain name or domain glob without a URL scheme or port. Use the + separate `port` field to restrict the target to one port. + examples: + - api.github.com + - "*.example.com" + port: + type: integer + minimum: 1 + maximum: 65535 + description: Optional destination port. Omit it to match every port. + examples: + - 443 + path: + type: string + pattern: ^/ + description: > + Absolute HTTP path glob. `*` matches one segment and `**` matches + any depth, including the bare path. + examples: + - /repos/docker/** + RuleDecision: type: string enum: [allow, deny] @@ -846,12 +1029,14 @@ components: description: > Machine-readable error code. `not_found`: the requested resource does not exist, the org does not exist, or the caller is not a - member of the org (the org's existence is not revealed to callers + member of the organization (the organization's existence is not revealed to callers who cannot access it). `conflict`: a resource with the same name already exists. `invalid_argument`: the request body is malformed or fails validation. `unauthenticated`: missing or invalid credentials. `permission_denied`: the org is not entitled to use - governance. `unimplemented`: the endpoint or feature is not yet + governance. `limit_exceeded`: the org has reached its maximum + number of policies, or the policy has reached its maximum number + of rules. `unimplemented`: the endpoint or feature is not yet available. `internal`: unexpected server error. enum: - not_found @@ -859,6 +1044,7 @@ components: - invalid_argument - unauthenticated - permission_denied + - limit_exceeded - unimplemented - internal message: @@ -932,6 +1118,29 @@ components: code: permission_denied message: permission denied + Forbidden: + description: > + Caller lacks the required permission for this org, the org is not + entitled to use governance (`permission_denied`), or a creation limit + has been reached (`limit_exceeded`): the org already has the maximum + number of policies, or the policy already has the maximum number of + rules. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + permission_denied: + value: + error: + code: permission_denied + message: permission denied + limit_exceeded: + value: + error: + code: limit_exceeded + message: organization has reached the maximum of 100 policies + InternalError: description: Internal server error content: diff --git a/content/reference/api/ai-governance/index.md b/content/reference/api/ai-governance/index.md deleted file mode 100644 index e9b5bc793612..000000000000 --- a/content/reference/api/ai-governance/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: api-reference -title: Docker AI Governance API -linkTitle: AI Governance -description: HTTP API reference for managing Docker AI Governance policies and rules programmatically. -keywords: docker sandboxes, governance API, policy API, organization policy, REST API, openapi -aliases: - - /ai/sandboxes/governance/api/ ---- diff --git a/content/reference/api/dvp/latest.md b/content/reference/api/dvp/latest.md deleted file mode 100644 index 1ef4fdf075ba..000000000000 --- a/content/reference/api/dvp/latest.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: api -description: Reference documentation and Swagger (OpenAPI) specification for the Docker Verified Publisher API. -title: Docker Verified Publisher API reference -linkTitle: Latest -weight: 1 -aliases: - - /reference/api/hub/dvp/ ---- diff --git a/content/reference/api/dvp/latest.yaml b/content/reference/api/dvp/latest.yaml index b1c5f441ac73..c99c588df8de 100644 --- a/content/reference/api/dvp/latest.yaml +++ b/content/reference/api/dvp/latest.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.2.0 info: title: DVP Data API version: 1.0.0 @@ -6,75 +6,79 @@ info: url: https://docs.docker.com/assets/images/logo-docker-main.png href: /reference description: | - The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces. Analytics data can be retrieved in a CSV as raw data, or in a summary format. - - #### Summary data + The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces. Analytics data can be retrieved in a CSV as raw data, or in a summary format. + + #### Summary data - In your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). + In your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). - There are two levels of summary data: + There are two levels of summary data: - - Repository-level, a summary of every namespace and repository - - Tag- or digest-level, a summary of every namespace, repository, and reference - (tag or digest) + - Repository-level, a summary of every namespace and repository + - Tag- or digest-level, a summary of every namespace, repository, and reference + (tag or digest) - The summary data formats contain the following data points: + The summary data formats contain the following data points: - - Unique IP address count - - Pulls by tag count - - Pulls by digest count - - Version check count + - Unique IP address count + - Pulls by tag count + - Pulls by digest count + - Version check count - #### Raw data + #### Raw data - In your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). **Note:** each action is represented as a single row. - - - Type (industry) - - Host (cloud provider) - - Country (geolocation) - - Timestamp - - Namespace - - Repository - - Reference (digest is always included, tag is provided when available) - - HTTP request method - - Action, one of the following: - - Pull by tag - - Pull by digest - - Version check - - User-Agent + In your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). **Note:** each action is represented as a single row. + - Type (industry) + - Host (cloud provider) + - Country (geolocation) + - Timestamp + - Namespace + - Repository + - Reference (digest is always included, tag is provided when available) + - HTTP request method + - Action, one of the following: + - Pull by tag + - Pull by digest + - Version check + - User-Agent servers: - url: https://hub.docker.com/api/publisher/analytics/v1 security: - HubAuth: [] - -features.openapi: - schemaDefinitionsTagName: Schemas - tags: - name: authentication - x-displayName: Authentication Endpoints + summary: Authentication Endpoints + kind: nav + description: Authentication Endpoints reference. - name: namespaces - x-displayName: Namespace data + summary: Namespace data + kind: nav + description: Namespace data reference. - name: discovery - x-displayName: Discovery + summary: Discovery + kind: nav + description: Discovery reference. - name: responseDataFile - x-displayName: ResponseDataFile description: | - + [ResponseDataFile](#schema-ResponseDataFile) + summary: ResponseDataFile + kind: info - name: yearModel - x-displayName: Year Data Model description: | - + [YearModel](#schema-YearModel) + summary: Year Data Model + kind: info - name: monthModel - x-displayName: Month Data Model description: | - + [MonthModel](#schema-MonthModel) + summary: Month Data Model + kind: info - name: weekModel - x-displayName: Week Data Model description: | - - + [WeekModel](#schema-WeekModel) + summary: Week Data Model + kind: info x-tagGroups: - name: API tags: @@ -87,10 +91,8 @@ x-tagGroups: - yearModel - monthModel - weekModel - paths: /v2/users/login: - security: [] servers: - url: https://hub.docker.com post: @@ -114,20 +116,19 @@ paths: description: Login details. required: true responses: - 200: + "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + "401": description: Authentication failed or second factor required content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginErrorResponse" /v2/users/2fa-login: - security: [] servers: - url: https://hub.docker.com post: @@ -153,53 +154,73 @@ paths: description: Login details. required: true responses: - 200: + "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + "401": description: Authentication failed or second factor required content: application/json: schema: $ref: "#/components/schemas/PostUsers2FALoginErrorResponse" - - /: get: - tags: [discovery] + tags: + - discovery summary: Get namespaces and repos description: Gets a list of your namespaces and repos which have data available. operationId: getNamespaces responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/NamespaceData' + $ref: "#/components/schemas/NamespaceData" /namespaces: get: - tags: [discovery] + tags: + - discovery summary: Get user's namespaces description: Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces. operationId: getUserNamespaces responses: - '200': + "200": description: Success content: application/json: schema: type: array items: - $ref: '#/components/schemas/NamespaceMetadata' - '401': + $ref: "#/components/schemas/NamespaceMetadata" + examples: + publishers: + summary: Namespace metadata + value: + - datasets: + - name: pulls + timespans: + - months + - weeks + views: + - raw + - summary + - repo-summary + - namespace-summary + - geo-repo-summary + extraRepos: null + namespace: org1 + publisherType: DVP + extensionPublisher: false + "401": description: Authentication failed or second factor required /namespaces/{namespace}: get: - tags: [discovery] + tags: + - discovery summary: Get namespace description: Gets metadata associated with specified namespace, including extra repos associated with the namespace. operationId: getNamespace @@ -211,15 +232,16 @@ paths: required: true description: Namespace to fetch data for responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/NamespaceMetadata' + $ref: "#/components/schemas/NamespaceMetadata" /namespaces/{namespace}/pulls: get: - tags: [namespaces] + tags: + - namespaces summary: Get pull data description: Gets pulls for the given namespace. operationId: getNamespacePulls @@ -233,33 +255,34 @@ paths: - in: query name: timespan schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: false description: Timespan type for fetching data - in: query name: period schema: - $ref: '#/components/schemas/PeriodType' + $ref: "#/components/schemas/PeriodType" required: false description: Relative period of the period to fetch data - in: query name: group schema: - $ref: '#/components/schemas/GroupType' + $ref: "#/components/schemas/GroupType" required: false description: Field to group the data by responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/PullData' - '404': + $ref: "#/components/schemas/PullData" + "404": description: Not found - namespace doesn't exist or user does not have permission to access it /namespaces/{namespace}/repos/{repo}/pulls: get: - tags: [namespaces] + tags: + - namespaces summary: Get pull data description: Gets pulls for the given repo. operationId: getRepoPulls @@ -279,33 +302,34 @@ paths: - in: query name: timespan schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: false description: Timespan type for fetching data - in: query name: period schema: - $ref: '#/components/schemas/PeriodType' + $ref: "#/components/schemas/PeriodType" required: false description: Relative period of the period to fetch data - in: query name: group schema: - $ref: '#/components/schemas/GroupType' + $ref: "#/components/schemas/GroupType" required: false description: Field to group the data by responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/PullData' - '404': + $ref: "#/components/schemas/PullData" + "404": description: Not found - repo doesn't exist or user does not have permission to access it /namespaces/{namespace}/pulls/exports/years: get: - tags: [namespaces] + tags: + - namespaces summary: Get years with data description: Gets a list of years that have data for the given namespace. operationId: getNamespaceYears @@ -317,15 +341,16 @@ paths: required: true description: Namespace to fetch data for responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/YearData' + $ref: "#/components/schemas/YearData" /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}: get: - tags: [namespaces] + tags: + - namespaces summary: Get timespans with data description: Gets a list of timespans of the given type that have data for the given namespace and year. operationId: getNamespaceTimespans @@ -345,19 +370,20 @@ paths: - in: path name: timespantype schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: true description: Type of timespan to fetch data for responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/TimespanData' + $ref: "#/components/schemas/TimespanData" /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}: get: - tags: [namespaces] + tags: + - namespaces summary: Get namespace metadata for timespan description: Gets info about data for the given namespace and timespan. operationId: getNamespaceTimespanMetadata @@ -377,7 +403,7 @@ paths: - in: path name: timespantype schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: true description: Type of timespan to fetch data for - in: path @@ -387,17 +413,18 @@ paths: required: true description: Timespan to fetch data for responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/TimespanModel' - '404': + $ref: "#/components/schemas/TimespanModel" + "404": description: Not Found /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}/{dataview}: get: - tags: [namespaces] + tags: + - namespaces summary: Get namespace data for timespan description: Gets a list of URLs that can be used to download the pull data for the given namespace and timespan. operationId: getNamespaceDataByTimespan @@ -417,7 +444,7 @@ paths: - in: path name: timespantype schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: true description: Type of timespan to fetch data for - in: path @@ -429,19 +456,28 @@ paths: - in: path name: dataview schema: - $ref: '#/components/schemas/DataviewType' + $ref: "#/components/schemas/DataviewType" required: true description: Type of data to fetch responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/ResponseData' + $ref: "#/components/schemas/ResponseData" + examples: + download: + summary: Illustrative download location + description: Use the signed URL returned by the API. The URL and file size in this example are illustrative. + value: + data: + - url: https://example.invalid/exports/pulls.csv.gz?X-Amz-Expires=21600&X-Amz-Signature=EXAMPLE + size: 1024 /repos/pulls: get: - tags: [namespaces] + tags: + - namespaces summary: Get pull data for multiple repos description: Gets pull for the given repos. operationId: getManyReposPulls @@ -457,32 +493,34 @@ paths: - in: query name: timespan schema: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" required: false description: Timespan type for fetching data - in: query name: period schema: - $ref: '#/components/schemas/PeriodType' + $ref: "#/components/schemas/PeriodType" required: false description: Relative period of the period to fetch data - in: query name: group schema: - $ref: '#/components/schemas/GroupType' + $ref: "#/components/schemas/GroupType" required: false description: Field to group the data by responses: - '200': + "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/ReposPullData' - + $ref: "#/components/schemas/ReposPullData" components: schemas: UsersLoginRequest: + examples: + - username: myusername + password: hunter2 description: User login details type: object required: @@ -494,12 +532,12 @@ components: type: string example: myusername password: - description: - The password or personal access token (PAT) of the Docker Hub - account to authenticate with. + description: The password or personal access token (PAT) of the Docker Hub account to authenticate with. type: string example: hunter2 PostUsersLoginSuccessResponse: + examples: + - token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c description: successful user login response type: object properties: @@ -510,8 +548,9 @@ components: This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - nullable: false PostUsersLoginErrorResponse: + examples: + - detail: Incorrect authentication credentials description: failed user login response or second factor required type: object required: @@ -521,16 +560,16 @@ components: description: Description of the error. type: string example: Incorrect authentication credentials - nullable: false login_2fa_token: - description: - Short-lived token to be used on `/v2/users/2fa-login` to - complete the authentication. This field is present only if 2FA is - enabled. - type: string + description: Short-lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled. + type: + - string + - "null" example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - nullable: true Users2FALoginRequest: + examples: + - login_2fa_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + code: "123456" description: Second factor user login details type: object required: @@ -542,12 +581,12 @@ components: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c code: - description: - The Time-based One-Time Password of the Docker Hub account to - authenticate with. + description: The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string - example: 123456 + example: "123456" PostUsers2FALoginErrorResponse: + examples: + - detail: Incorrect authentication credentials description: failed second factor login response. type: object properties: @@ -555,142 +594,306 @@ components: description: Description of the error. type: string example: Incorrect authentication credentials - nullable: false - ResponseData: properties: data: type: array - description: | - List of urls to download the data. When the data is large, the data will be split into multiple files. - items: - $ref: '#/components/schemas/ResponseDataFile' + description: Download URLs and file sizes for the export. + items: + $ref: "#/components/schemas/ResponseDataFile" + type: object + description: Download locations for the selected export. Large exports can span multiple files. ResponseDataFile: properties: url: type: string + format: uri + description: Signed download URL. URLs expire six hours after generation. size: type: integer format: int64 + description: Size of the file in bytes. + type: object NamespaceData: + examples: + - namespaces: + - myorganization properties: namespaces: type: array items: type: string + type: object NamespaceMetadata: properties: namespace: type: string extraRepos: - type: array + type: + - array + - "null" items: type: string + description: Additional repositories associated with the namespace. Null when none are configured. datasets: type: array items: - $ref: '#/components/schemas/DatasetModel' + $ref: "#/components/schemas/DatasetModel" + publisherType: + type: string + description: Publisher program associated with the namespace. + extensionPublisher: + type: boolean + description: Whether the namespace is an extension publisher. + type: object + examples: + - datasets: + - name: pulls + timespans: + - months + - weeks + views: + - raw + - summary + - repo-summary + - namespace-summary + - geo-repo-summary + extraRepos: null + namespace: org1 + publisherType: DVP + extensionPublisher: false + - datasets: + - name: pulls + timespans: + - months + - weeks + views: + - repo-summary + - namespace-summary + - name: extensions + timespans: + - months + - weeks + views: + - ext-summary + extraRepos: null + namespace: org4 + publisherType: DVP + extensionPublisher: true DatasetModel: properties: name: - $ref: '#/components/schemas/DatasetType' + $ref: "#/components/schemas/DatasetType" views: type: array items: - $ref: '#/components/schemas/DataviewType' + $ref: "#/components/schemas/DataviewType" timespans: type: array items: - $ref: '#/components/schemas/TimespanType' + $ref: "#/components/schemas/TimespanType" + type: object + description: Datasets and views available to the publisher, based on its entitlements. PullData: properties: pulls: - type: array + type: + - array + - "null" items: - $ref: '#/components/schemas/PullModel' + $ref: "#/components/schemas/PullModel" + description: Pull statistics for the selected interval. Null when no records are returned. + type: object + examples: + - pulls: + - end: "2022-08-07T00:00:00Z" + pullCount: 11 + repo: neo4j-admin + start: "2022-08-01T00:00:00Z" + ipCount: 10 + - end: "2022-08-14T00:00:00Z" + pullCount: 11 + repo: neo4j-admin + start: "2022-08-08T00:00:00Z" + ipCount: 10 + - pulls: null ReposPullData: properties: repos: type: object additionalProperties: - $ref: '#/components/schemas/PullData' + $ref: "#/components/schemas/PullData" + type: object + examples: + - repos: + org2/neo4j-admin: + pulls: + - end: "2022-08-07T00:00:00Z" + pullCount: 11 + repo: neo4j-admin + start: "2022-08-01T00:00:00Z" + ipCount: 10 + - end: "2022-08-14T00:00:00Z" + pullCount: 11 + repo: neo4j-admin + start: "2022-08-08T00:00:00Z" + ipCount: 10 + org2/neo4j: + pulls: + - end: "2022-08-07T00:00:00Z" + pullCount: 272407 + repo: neo4j + start: "2022-08-01T00:00:00Z" + ipCount: 41490 + - end: "2022-08-14T00:00:00Z" + pullCount: 272407 + repo: neo4j + start: "2022-08-08T00:00:00Z" + ipCount: 41490 PullModel: properties: start: type: string + format: date-time + description: Start of the reporting interval in RFC 3339 format. end: type: string + format: date-time + description: End of the reporting interval in RFC 3339 format. repo: type: string + description: Repository name. Present for results grouped by repository. namespace: type: string + description: Namespace name. Present for results grouped by namespace. pullCount: type: integer ipCount: type: integer country: type: string - + description: Country. Present for results grouped by geography and repository. + type: object YearData: + examples: + - years: + - year: 2025 properties: years: type: array items: - $ref: '#/components/schemas/YearModel' + $ref: "#/components/schemas/YearModel" + type: object YearModel: properties: year: type: integer + type: object MonthData: properties: months: type: array items: - $ref: '#/components/schemas/MonthModel' + $ref: "#/components/schemas/MonthModel" + type: object + required: + - months + examples: + - months: + - month: 5 + - month: 7 MonthModel: properties: month: type: integer + type: object + required: + - month + examples: + - month: 7 WeekData: properties: weeks: type: array items: - $ref: '#/components/schemas/WeekModel' + $ref: "#/components/schemas/WeekModel" + type: object + required: + - weeks + examples: + - weeks: + - week: 31 + - week: 32 WeekModel: properties: week: type: integer + type: object + required: + - week + examples: + - week: 31 TimespanType: type: string - enum: [months,weeks] + enum: + - months + - weeks PeriodType: type: string - enum: [last-2-months,last-3-months,last-6-months,last-12-months] + enum: + - last-2-months + - last-3-months + - last-6-months + - last-12-months DataviewType: type: string - enum: [raw,summary,repo-summary,namespace-summary] + enum: + - raw + - summary + - repo-summary + - namespace-summary + - geo-repo-summary + - ext-summary + - ext-premium-summary + - ext-premium-geo DatasetType: type: string - enum: [pulls] + enum: + - pulls + - extensions TimespanModel: oneOf: - - $ref: '#/components/schemas/MonthModel' - - $ref: '#/components/schemas/WeekModel' + - $ref: "#/components/schemas/MonthModel" + - $ref: "#/components/schemas/WeekModel" + examples: + - month: 7 + - week: 31 TimespanData: oneOf: - - $ref: '#/components/schemas/MonthData' - - $ref: '#/components/schemas/WeekData' + - $ref: "#/components/schemas/MonthData" + - $ref: "#/components/schemas/WeekData" + examples: + - months: + - month: 5 + - month: 7 + - weeks: + - week: 31 + - week: 32 GroupType: type: string - enum: [repo,namespace] + enum: + - repo + - namespace securitySchemes: HubAuth: - type: https + type: http scheme: bearer bearerFormat: JWT description: | JWT Bearer Authentication is required to access the Docker DVP Data API. - This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/#tag/authentication) + This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication) x-displayName: Docker Hub Authentication +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +x-features-openapi: + schemaDefinitionsTagName: Schemas diff --git a/content/reference/api/engine/_index.md b/content/reference/api/engine/_index.md index d2d40bd0236b..64b666e3bc2a 100644 --- a/content/reference/api/engine/_index.md +++ b/content/reference/api/engine/_index.md @@ -140,6 +140,9 @@ to provide full compatibility, some functionality may not be available. | Docker version | Maximum API version | Minimum API version | Change log | |:---------------|:---------------------------------------------|:---------------------------------------------|:-------------------------------------------------------------------| +| 29.8 | [1.55](/reference/api/engine/version/v1.56/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v156-api-changes) | +| 29.7 | [1.55](/reference/api/engine/version/v1.55/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v155-api-changes) | +| 29.6 | [1.55](/reference/api/engine/version/v1.55/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v155-api-changes) | | 29.5 | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) | | 29.4 | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) | | 29.3 | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) | diff --git a/content/reference/api/engine/latest.md b/content/reference/api/engine/latest.md index 5f69859b14c4..05b94cf3e13e 100644 --- a/content/reference/api/engine/latest.md +++ b/content/reference/api/engine/latest.md @@ -5,5 +5,5 @@ title: Latest params: sidebar: goto: /reference/api/engine/latest/ -weight: 20 +weight: 1 --- diff --git a/content/reference/api/engine/version/_index.md b/content/reference/api/engine/version/_index.md index b32c67b24e55..0d8209c77c09 100644 --- a/content/reference/api/engine/version/_index.md +++ b/content/reference/api/engine/version/_index.md @@ -1,5 +1,6 @@ --- title: API reference by version +weight: 4 build: render: never sidebar: diff --git a/content/reference/api/engine/version/v1.54.md b/content/reference/api/engine/version/v1.54.md index 264eb32e469e..ae3eca37cc08 100644 --- a/content/reference/api/engine/version/v1.54.md +++ b/content/reference/api/engine/version/v1.54.md @@ -1,7 +1,4 @@ --- linkTitle: v1.54 title: Docker Engine API v1.54 reference -aliases: - - /engine/api/latest/ - - /reference/api/engine/latest/ --- diff --git a/content/reference/api/engine/version/v1.55.md b/content/reference/api/engine/version/v1.55.md new file mode 100644 index 000000000000..a37d81537f35 --- /dev/null +++ b/content/reference/api/engine/version/v1.55.md @@ -0,0 +1,4 @@ +--- +linkTitle: v1.55 +title: Docker Engine API v1.55 reference +--- diff --git a/content/reference/api/engine/version/v1.56.md b/content/reference/api/engine/version/v1.56.md new file mode 100644 index 000000000000..98a61bb6b491 --- /dev/null +++ b/content/reference/api/engine/version/v1.56.md @@ -0,0 +1,7 @@ +--- +linkTitle: v1.56 +title: Docker Engine API v1.56 reference +aliases: + - /engine/api/latest/ + - /reference/api/engine/latest/ +--- diff --git a/content/reference/api/hub/changelog.md b/content/reference/api/hub/changelog.md index 5ba79d2063a6..2b7763e25c43 100644 --- a/content/reference/api/hub/changelog.md +++ b/content/reference/api/hub/changelog.md @@ -2,7 +2,9 @@ description: Docker Hub API changelog title: Docker Hub API changelog linkTitle: Changelog -keywords: docker hub, hub, whats new, release notes, api, changelog +keywords: >- + docker hub, hub, whats new, release notes, api, changelog, + personal access token, sandbox:use, Cloud Sandboxes weight: 2 toc_min: 1 toc_max: 2 @@ -15,17 +17,57 @@ issues for Docker Service APIs. --- +## 2026-10-15 + +### Updates + +- Add `sandbox:use` to personal access token scopes on + [Create personal access token](/reference/api/hub/latest/operations/postV2AccessTokens/). + A request can send `sandbox:use` alone, or `sandbox:use` with one + repository scope (`repo:admin`, `repo:write`, `repo:read`, or + `repo:public_read`). +- In Docker Home, **Allow Cloud Sandboxes access** is separate from + **Repository permissions**. The checkbox grants `sandbox:use`. + **No repository access** leaves the token without a repository scope. + +--- + +## 2026-09-01 + +### Updates + +- Document that [Update org member (role)](/reference/api/hub/latest/#tag-orgs) + accepts a custom role name in `role`. +- Document the `role` field on + [Update some details for an organization group](/reference/api/hub/latest/#tag-groups). +- Add `Editor` to `org_member.role` on + [organization members](/reference/api/hub/latest/#tag-orgs). + +--- + +## 2026-08-27 + +### Updates + +- Document organization access token (OAT) support for + [repository management](/reference/api/hub/latest/#tag-repositories) + endpoints, the scope-dependent behavior of + [List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/), + and legacy paths that are OAT unsupported. + +--- + ## 2025-11-21 ### Updates -- Add missing `expires_at` fields on [PAT management](/reference/api/hub/latest/#tag/access-tokens) endpoints. +- Add missing `expires_at` fields on [PAT management](/reference/api/hub/latest/#tag-access-tokens) endpoints. ## 2025-09-25 ### Updates -- Fix [Assign repository group](/reference/api/hub/latest/#tag/repositories/operation/CreateRepositoryGroup) endpoints request/response +- Fix [Assign repository group](/reference/api/hub/latest/operations/CreateRepositoryGroup/) endpoints request/response --- @@ -33,16 +75,16 @@ issues for Docker Service APIs. ### New -- Add [Create repository](/reference/api/hub/latest/#tag/repositories/operation/CreateRepository) endpoints for a given `namespace`. -- Add [Get repository](/reference/api/hub/latest/#tag/repositories/operation/GetRepository) endpoints for a given `namespace`. -- Add [Check repository](/reference/api/hub/latest/#tag/repositories/operation/CheckRepository) endpoints for a given `namespace`. +- Add [Create repository](/reference/api/hub/latest/operations/CreateRepository/) endpoints for a given `namespace`. +- Add [Get repository](/reference/api/hub/latest/operations/GetRepository/) endpoints for a given `namespace`. +- Add [Check repository](/reference/api/hub/latest/operations/CheckRepository/) endpoints for a given `namespace`. ### Deprecations -- [Deprecate POST /v2/repositories](/reference/api/hub/deprecated/#deprecate-legacy-createrepository) -- [Deprecate POST /v2/repositories/{namespace}](/reference/api/hub/deprecated/#deprecate-legacy-createrepository) -- [Deprecate GET /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-getrepository) -- [Deprecate HEAD /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-getrepository) +- [Deprecate POST /v2/repositories](/reference/api/hub/deprecated/#deprecate-legacy-createrepository-and-getrepository) +- [Deprecate POST /v2/repositories/{namespace}](/reference/api/hub/deprecated/#deprecate-legacy-createrepository-and-getrepository) +- [Deprecate GET /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-createrepository-and-getrepository) +- [Deprecate HEAD /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-createrepository-and-getrepository) --- @@ -50,8 +92,8 @@ issues for Docker Service APIs. ### New -- Add [Update repository immutable tags settings](/reference/api/hub/latest/#tag/repositories/operation/UpdateRepositoryImmutableTags) endpoints for a given `namespace` and `repository`. -- Add [Verify repository immutable tags](/reference/api/hub/latest/#tag/repositories/operation/VerifyRepositoryImmutableTags) endpoints for a given `namespace` and `repository`. +- Add [Update repository immutable tags settings](/reference/api/hub/latest/operations/UpdateRepositoryImmutableTags/) endpoints for a given `namespace` and `repository`. +- Add [Verify repository immutable tags](/reference/api/hub/latest/operations/VerifyRepositoryImmutableTags/) endpoints for a given `namespace` and `repository`. --- @@ -59,7 +101,7 @@ issues for Docker Service APIs. ### New -- Add [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories) endpoints for a given `namespace`. +- Add [List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/) endpoints for a given `namespace`. ### Deprecations @@ -71,7 +113,7 @@ issues for Docker Service APIs. ### New -- Add [APIs](/reference/api/hub/latest/#tag/org-access-tokens) for organization access token (OATs) management. +- Add [APIs](/reference/api/hub/latest/#tag-org-access-tokens) for organization access token (OATs) management. --- @@ -79,5 +121,5 @@ issues for Docker Service APIs. ### New -- Add access to [audit logs](/reference/api/hub/latest/#tag/audit-logs) for org +- Add access to [audit logs](/reference/api/hub/latest/#tag-audit-logs) for org access tokens. diff --git a/content/reference/api/hub/deprecated.md b/content/reference/api/hub/deprecated.md index a803afb1d6f9..bd5dbe3a531b 100644 --- a/content/reference/api/hub/deprecated.md +++ b/content/reference/api/hub/deprecated.md @@ -38,15 +38,15 @@ The endpoint may be removed, disabled, or change behavior in a future release. ### Deprecate legacy CreateRepository and GetRepository Deprecate undocumented endpoints : -- `POST /v2/repositories` and `POST /v2/repositories/{namespace}` replaced by [Create repository](/reference/api/hub/latest/#tag/repositories/operation/CreateRepository). -- `GET /v2/repositories/{namespace}/{repository}` replaced by [Get repository](/reference/api/hub/latest/#tag/repositories/operation/GetRepository). -- `HEAD /v2/repositories/{namespace}/{repository}` replaced by [Check repository](/reference/api/hub/latest/#tag/repositories/operation/CheckRepository). +- `POST /v2/repositories` and `POST /v2/repositories/{namespace}` replaced by [Create repository](/reference/api/hub/latest/operations/CreateRepository/). +- `GET /v2/repositories/{namespace}/{repository}` replaced by [Get repository](/reference/api/hub/latest/operations/GetRepository/). +- `HEAD /v2/repositories/{namespace}/{repository}` replaced by [Check repository](/reference/api/hub/latest/operations/CheckRepository/). --- ### Deprecate legacy ListNamespaceRepositories -Deprecate undocumented endpoint `GET /v2/repositories/{namespace}` replaced by [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories). +Deprecate undocumented endpoint `GET /v2/repositories/{namespace}` replaced by [List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/). --- @@ -72,9 +72,9 @@ If you want to continue using the Docker Hub API in your current applications, u | **OLD** | **NEW** | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| -| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags) | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest/#tag/repositories/operation/ListRepositoryTags) | -| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags) | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest.md/#tag/repositories/operation/ListRepositoryTags) | -| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/#tag/repositories/operation/GetRepositoryTag) | -| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/#tag/repositories/operation/GetRepositoryTag) | +| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags) | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest/operations/ListRepositoryTags/) | +| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags) | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest/operations/ListRepositoryTags/) | +| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/operations/GetRepositoryTag/) | +| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/operations/GetRepositoryTag/) | --- \ No newline at end of file diff --git a/content/reference/api/hub/latest.md b/content/reference/api/hub/latest.md deleted file mode 100644 index 15fd57a3db7f..000000000000 --- a/content/reference/api/hub/latest.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: api -description: Reference documentation and Swagger (OpenAPI) specification for the Docker Hub API. -title: Docker Hub API reference -linkTitle: Latest -weight: 1 ---- diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 38034331654a..b6ba7ddb5c00 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -1,6 +1,4 @@ -# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/schemas/v3.0/schema.yaml - -openapi: 3.0.3 +openapi: 3.2.0 info: title: Docker HUB API version: 2-beta @@ -21,16 +19,17 @@ servers: url: https://hub.docker.com tags: - name: changelog - x-displayName: Changelog description: | - See the [Changelog](/reference/api/hub/changelog) for a summary of changes across Docker Hub API versions. + See the [Changelog](https://docs.docker.com/reference/api/hub/changelog) for a summary of changes across Docker Hub API versions. + summary: Changelog + kind: info - name: resources - x-displayName: Resources description: | The following resources are available to interact with the documented API: - [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental) + summary: Resources + kind: info - name: rate-limiting - x-displayName: Rate Limiting description: | The Docker Hub API is limited on the amount of requests you can perform per minute against it. @@ -46,9 +45,10 @@ tags: **Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. To learn more about Docker Hub pull rate limiting, see [Usage and limits](https://docs.docker.com/docker-hub/usage/). + summary: Rate Limiting + kind: info - name: authentication - x-displayName: Authentication - description: | + description: |+ Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them. Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your subscription (Personal, Pro, or Team) and your account's permissions. @@ -85,25 +85,22 @@ tags: These tokens are meant for automation and are not meant to be used by users. - # Labels + Operations that support bearer tokens issued from OATs state this in their descriptions. - These labels will show up on routes in this reference that allow for use of bearer - tokens issued from them. - - - + summary: Authentication + kind: info - name: authentication-api - x-displayName: Authentication description: | The authentication endpoints allow you to authenticate with Docker Hub APIs. For more information, see [Authentication](#tag/authentication). + summary: Authentication + kind: nav - name: access-tokens - x-displayName: Personal Access Tokens description: | - The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/access-tokens/). + The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/access-tokens/personal-access-tokens/). - You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token. + You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/reference/cli/docker/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token. ### Scopes @@ -111,54 +108,72 @@ tags: For example: If you define `repo:write`, the API assumes the scope of both `repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and* `repo:read`, then `repo:read` is assumed by `repo:write` and ignored. + `sandbox:use` is a separate grouping for Cloud Sandboxes. A repository scope does not include it, and it does not include a repository scope. A request can include `sandbox:use` on its own or with one repository scope. + ***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.*** + summary: Personal Access Tokens + kind: nav - name: audit-logs - x-displayName: Audit Logs description: | The Audit Logs API endpoints allow you to query audit log events across a namespace. For more information, see [Audit Logs](https://docs.docker.com/admin/activity-logs/). + summary: Audit Logs + kind: nav - name: org-settings - x-displayName: Org Settings description: | The Org Settings API endpoints allow you to manage your organization's settings. + summary: Org Settings + kind: nav - name: repositories - x-displayName: Repositories description: | The repository endpoints allow you to access your repository's tags. + summary: Repositories + kind: nav - name: orgs - x-displayName: Organizations x-audience: public description: | The organization endpoints allow you to interact with and manage your organizations. For more information, see [Organization administration overview](https://docs.docker.com/admin/organization/). + summary: Organizations + kind: nav - name: groups - x-displayName: Groups (Teams) x-audience: public description: | The groups endpoints allow you to manage your organization's teams and their members. For more information, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/). + summary: Groups (Teams) + kind: nav - name: invites - x-displayName: Invites x-audience: public description: | The invites endpoints allow you to manage invites for users to join your Docker organization. - For more information, see [Invite members](https://docs.docker.com/admin/organization/manage/members/#invite-members). + For more information, see [Invite members](https://docs.docker.com/accounts/organization/manage/members/#invite-members). + summary: Invites + kind: nav - name: scim - x-displayName: SCIM x-audience: public description: | SCIM is a provisioning system that lets you manage users within your identity provider (IdP). For more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/). + summary: SCIM + kind: nav - name: org-access-tokens - x-displayName: Organization Access Tokens x-audience: public description: | The organization access token endpoints allow you to manage organization access tokens (OATs). See [Organization access tokens](https://docs.docker.com/security/for-admins/access-tokens/) for more information. + + OATs only authenticate requests to the modern namespace-scoped routes under `/v2/namespaces/{namespace}/repositories/`. Legacy repository paths are OAT unsupported, regardless of the token's scopes, and reject every OAT with `403 token issued from organization access token is not allowed`: + + - `GET /v2/repositories/{namespace}/{repository}` — use [Get repository](#tag/repositories/operation/GetRepository) instead. + - `GET /v2/repositories/{namespace}` — use [List repositories](#tag/repositories/operation/listNamespaceRepositories) instead. + - `GET /v2/users/{username}/repositories` — use [List repositories](#tag/repositories/operation/listNamespaceRepositories) instead. + summary: Organization Access Tokens + kind: nav paths: /v2/users/login: post: @@ -168,16 +183,16 @@ paths: operationId: PostUsersLogin security: [] deprecated: true - description: | + description: |+ Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. _**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_ -
- Deprecated: Use [Create access token] instead. -
+ + Deprecated: Use [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) instead. + requestBody: content: application/json: @@ -206,7 +221,7 @@ paths: operationId: PostUsers2FALogin security: [] description: | - When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call. + When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/auth/token` call. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. @@ -251,6 +266,9 @@ paths: content: application/json: schema: + examples: + - identifier: myusername + secret: dckr_pat_124509ugsdjga93 description: Request to create access token type: object required: @@ -304,6 +322,7 @@ paths: $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" + operationId: postV2AccessTokens get: summary: List personal access tokens description: Returns a paginated list of personal access tokens. @@ -312,16 +331,8 @@ paths: security: - bearerAuth: [] parameters: - - in: query - name: page - schema: - type: number - default: 1 - - in: query - name: page_size - schema: - type: number - default: 10 + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/page_size" responses: "200": description: OK @@ -333,9 +344,11 @@ paths: $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" + operationId: getV2AccessTokens /v2/access-tokens/{uuid}: parameters: - - in: path + - description: UUID of the personal access token. + in: path name: uuid required: true schema: @@ -365,6 +378,7 @@ paths: $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" + operationId: patchV2AccessTokensByUuid get: summary: Get personal access token description: Returns a personal access token by UUID. @@ -378,17 +392,32 @@ paths: content: application/json: schema: + examples: + - uuid: b30bbf97-506c-4ecd-aabc-842f3cb484fb + client_id: HUB + creator_ip: 127.0.0.1 + creator_ua: some user agent + created_at: "2021-07-20T12:00:00.000000Z" + last_used: null + generated_by: manual + is_active: true + token: "***" + token_label: My read only token + scopes: + - repo:read + expires_at: "2021-10-28T18:30:19.520861Z" allOf: - $ref: "#/components/schemas/accessToken" - type: object properties: token: type: string - example: "" + example: "***" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" + operationId: getV2AccessTokensByUuid delete: summary: Delete personal access token description: | @@ -404,13 +433,14 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" + operationId: deleteV2AccessTokensByUuid /v2/auditlogs/{account}/actions: get: summary: List audit log actions description: | List audit log actions for a namespace to be used as a filter for querying audit log events. - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. operationId: AuditLogs_ListAuditActions security: - bearerAuth: [] @@ -682,13 +712,26 @@ paths: description: "" content: application/json: - schema: {} + schema: + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: internal error + errinfo: null default: description: An unexpected error response. content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: internal error + errinfo: null parameters: - name: account description: Namespace to query audit log actions for. @@ -704,7 +747,7 @@ paths: description: | List audit log events for a given namespace. - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. operationId: AuditLogs_ListAuditLogs security: - bearerAuth: [] @@ -726,7 +769,7 @@ paths: data: digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa tag: latest - timestamp: "2021-02-19T01:34:35Z" + timestamp: 2021-02-19T01:34:35Z action_description: | pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example - account: docker @@ -736,12 +779,12 @@ paths: data: lease_id: l_3EgPuRCjtUqT279CFPOQWcO8zOf resource_type: run_4cpu_8mem - started_at: "2026-06-04T18:24:21Z" - updated_at: "2026-06-04T18:36:43Z" + started_at: 2026-06-04T18:24:21Z + updated_at: 2026-06-04T18:36:43Z org_id: b908ca6e-b9a9-4a53-a9a5-6bec96f72432 user_id: ecae6747-e42c-43cb-925d-cfce1ab32b02 - timestamp: "2026-06-04T18:36:43Z" - action_description: "offload lease 'l_3EgPuRCjtUqT279CFPOQWcO8zOf' ended, ran for '12m22s'" + timestamp: 2026-06-04T18:36:43Z + action_description: offload lease 'l_3EgPuRCjtUqT279CFPOQWcO8zOf' ended, ran for '12m22s' "429": description: "" content: @@ -756,13 +799,26 @@ paths: description: "" content: application/json: - schema: {} + schema: + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: internal error + errinfo: null default: description: An unexpected error response. content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: internal error + errinfo: null parameters: - name: account description: Namespace to query audit logs for. @@ -805,32 +861,13 @@ paths: schema: type: string format: date-time - - name: page - description: page - specify page number. Page number to get. - in: query - required: false - schema: - type: integer - format: int32 - default: 1 - - name: page_size - description: page_size - specify page size. Number of events to return per page. - in: query - required: false - schema: - type: integer - format: int32 - default: 25 + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/page_size" tags: - audit-logs - /v2/orgs/{name}/settings: + /v2/orgs/{org_name}/settings: parameters: - - in: path - name: name - description: Name of the organization. - required: true - schema: - type: string + - $ref: "#/components/parameters/org_name" get: summary: Get organization settings description: | @@ -852,6 +889,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: getV2OrgsByNameSettings put: summary: Update organization settings description: | @@ -869,6 +907,11 @@ paths: content: application/json: schema: + examples: + - restricted_images: + enabled: true + allow_official_images: true + allow_verified_publishers: true required: - restricted_images properties: @@ -894,7 +937,10 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - /v2/orgs/{name}/access-tokens: + operationId: putV2OrgsByNameSettings + /v2/orgs/{org_name}/access-tokens: + parameters: + - $ref: "#/components/parameters/org_name" post: summary: Create access token description: | @@ -924,6 +970,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: postV2OrgsByNameAccessTokens get: summary: List access tokens description: | @@ -933,16 +980,8 @@ paths: security: - bearerAuth: [] parameters: - - in: query - name: page - schema: - type: number - default: 1 - - in: query - name: page_size - schema: - type: number - default: 10 + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/page_size" responses: "200": description: OK @@ -956,7 +995,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" - + operationId: getV2OrgsByNameAccessTokens /v2/orgs/{org_name}/access-tokens/{access_token_id}: parameters: - $ref: "#/components/parameters/org_name" @@ -966,7 +1005,7 @@ paths: schema: type: string description: The ID of the access token to retrieve - example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" + example: a7a5ef25-8889-43a0-8cc7-f2a94268e861 get: summary: Get access token description: | @@ -988,6 +1027,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: getV2OrgsByOrgNameAccessTokensByAccessTokenId patch: summary: Update access token description: | @@ -1015,6 +1055,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: patchV2OrgsByOrgNameAccessTokensByAccessTokenId delete: summary: Delete access token description: | @@ -1032,6 +1073,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: deleteV2OrgsByOrgNameAccessTokensByAccessTokenId /v2/namespaces/{namespace}/repositories/{repository}/tags: parameters: - $ref: "#/components/parameters/namespace" @@ -1039,23 +1081,17 @@ paths: get: operationId: ListRepositoryTags summary: List repository tags + description: | + Returns the list of tags for the specified repository. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: - bearerAuth: [] parameters: - - in: query - name: page - required: false - schema: - type: integer - description: Page number to get. Defaults to 1. - - in: query - name: page_size - required: false - schema: - type: integer - description: Number of items to get per page. Defaults to 10. Max of 100. + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/page_size" responses: "200": $ref: "#/components/responses/list_tags" @@ -1065,6 +1101,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tags + description: | + Checks whether the repository has any tags. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: @@ -1076,6 +1116,7 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: headV2NamespacesByNamespaceRepositoriesByRepositoryTags /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}: parameters: - $ref: "#/components/parameters/namespace" @@ -1084,6 +1125,10 @@ paths: get: operationId: GetRepositoryTag summary: Read repository tag + description: | + Returns details for a specific tag in the specified repository. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: @@ -1097,6 +1142,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tag + description: | + Checks whether the specified tag exists in the repository. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: @@ -1108,17 +1157,20 @@ paths: $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" + operationId: headV2NamespacesByNamespaceRepositoriesByRepositoryTagsByTag /v2/namespaces/{namespace}/repositories/{repository}/immutabletags: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" patch: operationId: UpdateRepositoryImmutableTags - summary: "Update repository immutable tags" + summary: Update repository immutable tags description: | Updates the immutable tags configuration for this repository. **Only users with administrative privileges for the repository can modify these settings.** + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: @@ -1126,15 +1178,15 @@ paths: requestBody: $ref: "#/components/requestBodies/update_repository_immutable_tags_request" responses: - 200: + "200": $ref: "#/components/responses/update_repository_immutable_tags_response" - 400: + "400": $ref: "#/components/responses/bad_request" - 401: + "401": $ref: "#/components/responses/unauthorized" - 403: + "403": $ref: "#/components/responses/forbidden" - 404: + "404": $ref: "#/components/responses/not_found" /v2/namespaces/{namespace}/repositories/{repository}/immutabletags/verify: parameters: @@ -1142,11 +1194,13 @@ paths: - $ref: "#/components/parameters/repository" post: operationId: VerifyRepositoryImmutableTags - summary: "Verify repository immutable tags" + summary: Verify repository immutable tags description: | - Validates the immutable tags regex pass in parameter and returns a list of tags matching it in this repository. + Validates the immutable tags regex passed in the request body and returns a list of tags matching it in this repository. + + **Only users with administrative privileges for the repository can call this endpoint.** - **Only users with administrative privileges for the repository call this endpoint.** + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: @@ -1154,15 +1208,15 @@ paths: requestBody: $ref: "#/components/requestBodies/immutable_tags_verify_request" responses: - 200: + "200": $ref: "#/components/responses/immutable_tags_verify_response" - 400: + "400": $ref: "#/components/responses/bad_request" - 401: + "401": $ref: "#/components/responses/unauthorized" - 403: + "403": $ref: "#/components/responses/forbidden" - 404: + "404": $ref: "#/components/responses/not_found" /v2/repositories/{namespace}/{repository}/groups: parameters: @@ -1170,6 +1224,10 @@ paths: - $ref: "#/components/parameters/repository" post: summary: Assign a group (Team) to a repository for access + description: | + Assigns an organization group (team) to a repository with a specified permission level. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories operationId: CreateRepositoryGroup @@ -1183,7 +1241,7 @@ paths: $ref: "#/components/schemas/RepositoryGroupCreationRequest" example: group_id: 12345 - permission: "write" + permission: write responses: "200": description: Repository group permission created successfully @@ -1192,8 +1250,8 @@ paths: schema: $ref: "#/components/schemas/RepositoryGroup" example: - group_name: "developers" - permission: "write" + group_name: developers + permission: write group_id: 12345 "400": description: Bad Request - Invalid request parameters @@ -1201,6 +1259,12 @@ paths: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: bad request + errinfo: null "401": $ref: "#/components/responses/unauthorized" "403": @@ -1217,29 +1281,20 @@ paths: Returns a list of repositories within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + + + **OAT listing behavior**: an OAT with the `scope-repository-list` scope sees all repositories including private ones. An OAT without that scope only sees public repositories. This filtering is silent: the response is a normal `200` with no indication that private repositories were withheld. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: - bearerAuth: [] - - {} # Allow anonymous access for public repositories + - {} parameters: - - in: query - name: page - required: false - schema: - type: integer - minimum: 1 - default: 1 - description: Page number to get. Defaults to 1. - - in: query - name: page_size - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 10 - description: Number of repositories to get per page. Defaults to 10. Max of 100. + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/page_size" - in: query name: name required: false @@ -1275,59 +1330,59 @@ paths: repositories_list: value: count: 287 - next: "https://hub.docker.com/v2/namespaces/docker/repositories?page=2&page_size=2" + next: https://hub.docker.com/v2/namespaces/docker/repositories?page=2&page_size=2 previous: null results: - - name: "highland_builder" - namespace: "docker" - repository_type: "image" + - name: highland_builder + namespace: docker + repository_type: image status: 1 - status_description: "active" - description: "Image for performing Docker build requests" + status_description: active + description: Image for performing Docker build requests is_private: false star_count: 7 pull_count: 15722123 - last_updated: "2023-06-20T10:44:45.459826Z" - last_modified: "2024-10-16T13:48:34.145251Z" - date_registered: "2015-05-19T21:13:35.937763Z" + last_updated: 2023-06-20T10:44:45.459826Z + last_modified: 2024-10-16T13:48:34.145251Z + date_registered: 2015-05-19T21:13:35.937763Z affiliation: "" media_types: - - "application/octet-stream" - - "application/vnd.docker.container.image.v1+json" - - "application/vnd.docker.distribution.manifest.v1+prettyjws" + - application/octet-stream + - application/vnd.docker.container.image.v1+json + - application/vnd.docker.distribution.manifest.v1+prettyjws content_types: - - "unrecognized" - - "image" + - unrecognized + - image categories: - - name: "Languages & frameworks" - slug: "languages-and-frameworks" - - name: "Integration & delivery" - slug: "integration-and-delivery" - - name: "Operating systems" - slug: "operating-systems" + - name: Languages & frameworks + slug: languages-and-frameworks + - name: Integration & delivery + slug: integration-and-delivery + - name: Operating systems + slug: operating-systems storage_size: 488723114800 - - name: "whalesay" - namespace: "docker" + - name: whalesay + namespace: docker repository_type: null status: 1 - status_description: "active" - description: "An image for use in the Docker demo tutorial" + status_description: active + description: An image for use in the Docker demo tutorial is_private: false star_count: 757 pull_count: 130737682 - last_updated: "2015-06-19T19:06:27.388123Z" - last_modified: "2024-10-16T13:48:34.145251Z" - date_registered: "2015-06-09T18:16:36.527329Z" + last_updated: 2015-06-19T19:06:27.388123Z + last_modified: 2024-10-16T13:48:34.145251Z + date_registered: 2015-06-09T18:16:36.527329Z affiliation: "" media_types: - - "application/vnd.docker.distribution.manifest.v1+prettyjws" + - application/vnd.docker.distribution.manifest.v1+prettyjws content_types: - - "image" + - image categories: - - name: "Languages & frameworks" - slug: "languages-and-frameworks" - - name: "Integration & delivery" - slug: "integration-and-delivery" + - name: Languages & frameworks + slug: languages-and-frameworks + - name: Integration & delivery + slug: integration-and-delivery storage_size: 103666708 "400": description: Bad Request - Invalid request parameters @@ -1341,10 +1396,8 @@ paths: value: fields: ordering: - [ - "Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count", - ] - text: "Invalid ordering value" + - "Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count" + text: Invalid ordering value "401": $ref: "#/components/responses/unauthorized" "403": @@ -1355,16 +1408,24 @@ paths: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: not found + errinfo: null post: summary: Create a new repository description: | Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. operationId: CreateRepository tags: - repositories security: - - BearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -1372,26 +1433,26 @@ paths: schema: $ref: "#/components/schemas/repo_creation_request" example: - name: "my-app" - namespace: "myorganization" - description: "A sample application repository" - full_description: "This is a comprehensive description of my application repository that contains additional details about the project." - registry: "docker.io" + name: my-app + namespace: myorganization + description: A sample application repository + full_description: This is a comprehensive description of my application repository that contains additional details about the project. + registry: docker.io is_private: false responses: - 201: + "201": description: Repository created successfully content: application/json: schema: $ref: "#/components/schemas/repository_info" example: - name: "my-app" - namespace: "myorganization" - repository_type: "image" + name: my-app + namespace: myorganization + repository_type: image status: 1 - status_description: "Active" - description: "A sample application repository" + status_description: Active + description: A sample application repository is_private: false is_automated: false star_count: 0 @@ -1399,9 +1460,9 @@ paths: last_updated: "2025-01-20T10:30:00Z" date_registered: "2025-01-20T10:30:00Z" collaborator_count: 0 - hub_user: "myorganization" + hub_user: myorganization has_starred: false - full_description: "This is a comprehensive description of my application repository that contains additional details about the project." + full_description: This is a comprehensive description of my application repository that contains additional details about the project. media_types: [] content_types: [] categories: [] @@ -1410,15 +1471,20 @@ paths: rules: [] storage_size: null source: null - 400: + user: myorganization + permissions: + read: true + write: true + admin: true + "400": $ref: "#/components/responses/bad_request" - 401: + "401": $ref: "#/components/responses/unauthorized" - 403: + "403": $ref: "#/components/responses/forbidden" - 404: + "404": $ref: "#/components/responses/not_found" - 500: + "500": $ref: "#/components/responses/internal_error" /v2/namespaces/{namespace}/repositories/{repository}: parameters: @@ -1431,24 +1497,26 @@ paths: Returns a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: - bearerAuth: [] - - {} # Allow anonymous access for public repositories + - {} responses: - 200: + "200": content: application/json: schema: $ref: "#/components/schemas/repository_info" example: - name: "my-app" - namespace: "myorganization" - repository_type: "image" + name: my-app + namespace: myorganization + repository_type: image status: 1 - status_description: "Active" - description: "A sample application repository" + status_description: Active + description: A sample application repository is_private: false is_automated: false star_count: 0 @@ -1456,9 +1524,9 @@ paths: last_updated: "2025-01-20T10:30:00Z" date_registered: "2025-01-20T10:30:00Z" collaborator_count: 0 - hub_user: "myorganization" + hub_user: myorganization has_starred: false - full_description: "This is a comprehensive description of my application repository that contains additional details about the project." + full_description: This is a comprehensive description of my application repository that contains additional details about the project. media_types: [] content_types: [] categories: [] @@ -1467,13 +1535,18 @@ paths: rules: [] storage_size: null source: null - 401: + user: myorganization + permissions: + read: true + write: true + admin: true + "401": $ref: "#/components/responses/unauthorized" - 403: + "403": $ref: "#/components/responses/forbidden" - 404: + "404": $ref: "#/components/responses/not_found" - 500: + "500": $ref: "#/components/responses/internal_error" head: operationId: CheckRepository @@ -1482,49 +1555,22 @@ paths: Check a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - repositories security: - bearerAuth: [] - - {} # Allow anonymous access for public repositories + - {} responses: - 200: - content: - application/json: - schema: - $ref: "#/components/schemas/repository_info" - example: - name: "my-app" - namespace: "myorganization" - repository_type: "image" - status: 1 - status_description: "Active" - description: "A sample application repository" - is_private: false - is_automated: false - star_count: 0 - pull_count: 0 - last_updated: "2025-01-20T10:30:00Z" - date_registered: "2025-01-20T10:30:00Z" - collaborator_count: 0 - hub_user: "myorganization" - has_starred: false - full_description: "This is a comprehensive description of my application repository that contains additional details about the project." - media_types: [] - content_types: [] - categories: [] - immutable_tags_settings: - enabled: false - rules: [] - storage_size: null - source: null - 401: + "200": {} + "401": $ref: "#/components/responses/unauthorized" - 403: + "403": $ref: "#/components/responses/forbidden" - 404: + "404": $ref: "#/components/responses/not_found" - 500: + "500": $ref: "#/components/responses/internal_error" /v2/orgs/{org_name}/members: parameters: @@ -1546,9 +1592,9 @@ paths: - `last_seen_at` - `last_desktop_version` - To make visible, please see [View Insights for organization users](https://docs.docker.com/admin/insights/#view-insights-for-organization-users). + To make visible, please see [View Insights for organization users](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users). - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - orgs security: @@ -1559,9 +1605,7 @@ paths: content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/org_member_paginated" + $ref: "#/components/schemas/org_member_paginated" "400": $ref: "#/components/responses/bad_request" "401": @@ -1570,6 +1614,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameMembers /v2/orgs/{org_name}/members/export: parameters: - $ref: "#/components/parameters/org_name" @@ -1578,7 +1623,7 @@ paths: description: | Export members of an organization as a CSV - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - orgs security: @@ -1589,46 +1634,11 @@ paths: content: text/csv: schema: - type: array - items: - type: object - required: - - Name - - Username - - Email - - Type - - Role - - Date Joined - properties: - Name: - type: string - description: First and last name of the member - Username: - type: string - description: Username of the member - Email: - type: string - description: Email address of the member - Type: - type: string - description: Type of the member - enum: - - Invitee - - User - Permission: - type: string - description: Permission of the member - enum: - - Owner - - Member - Teams: - type: string - description: Comma-separated list of teams the member is part of - example: team-1, team-2 - Date Joined: - type: string - description: Date the member joined the organization - example: 2020-01-01 15:00:51.193355 +0000 UTC + type: string + description: "CSV columns: Name, Username, Email, Type, Role, Teams, and Date Joined. The Role column contains the assigned role label. When administrative insights are available, the export also includes Last Logged-in Date, Docker Desktop Version, Last Seen Date, and Opted Out Analytics." + example: | + Name,Username,Email,Type,Role,Teams,Date Joined + Jon Snow,dockeruser,example@docker.com,User,Owner,owners,2021-01-05 21:06:53.5064 +0000 UTC headers: Content-Disposition: schema: @@ -1642,6 +1652,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameMembersExport /v2/orgs/{org_name}/members/{username}: x-audience: public parameters: @@ -1653,7 +1664,7 @@ paths: Updates the role of a member in the organization. ***Only users in the "owners" group of the organization can use this endpoint.*** - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - orgs security: @@ -1663,16 +1674,19 @@ paths: content: application/json: schema: + examples: + - role: owner required: - role properties: role: type: string - description: Role of the member - enum: - - owner - - editor - - member + description: | + Role of the member. Valid values are the core roles + `owner`, `editor`, and `member`, or the name of an + existing [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/). + Use the custom role's name identifier, not its label or UUID. + example: owner responses: "200": description: Member role updated @@ -1688,12 +1702,13 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: putV2OrgsByOrgNameMembersByUsername delete: summary: Remove member from org description: | Removes the member from the org, ie. all groups in the org, unless they're the last owner - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - orgs security: @@ -1709,6 +1724,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: deleteV2OrgsByOrgNameMembersByUsername /v2/orgs/{org_name}/invites: x-audience: public parameters: @@ -1718,7 +1734,7 @@ paths: description: | Return all pending invites for a given org, only team owners can call this endpoint - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - invites security: @@ -1729,6 +1745,14 @@ paths: content: application/json: schema: + examples: + - data: + - id: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: moby + invitee: invitee@docker.com + org: docker + team: owners + created_at: "2021-10-28T18:30:19.520861Z" type: object properties: data: @@ -1741,6 +1765,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameInvites /v2/orgs/{org_name}/groups: x-audience: public parameters: @@ -1748,7 +1773,9 @@ paths: get: summary: Get groups of an organization description: | - + Get groups of an organization. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1777,27 +1804,44 @@ paths: type: number example: 1 next: - type: string + type: + - string + - "null" example: null previous: - type: string + type: + - string + - "null" example: null results: type: array items: $ref: "#/components/schemas/org_group" + type: object + examples: + - count: 1 + next: null + previous: null + results: + - id: 10 + uuid: e36eca69-4cc8-4f17-9845-ae8c2b832691 + name: developers + description: Development team + member_count: 1 + role: member "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameGroups post: summary: Create a new group description: | Create a new group within an organization. - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1806,6 +1850,9 @@ paths: content: application/json: schema: + examples: + - name: developers + description: Development team required: - name properties: @@ -1826,6 +1873,7 @@ paths: $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" + operationId: postV2OrgsByOrgNameGroups /v2/orgs/{org_name}/groups/{group_name}: x-audience: public parameters: @@ -1834,7 +1882,9 @@ paths: get: summary: Get a group of an organization description: | - + Get a group of an organization. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1852,10 +1902,13 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameGroupsByGroupName put: summary: Update the details for an organization group description: | - + Update the details for an organization group. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1864,6 +1917,9 @@ paths: content: application/json: schema: + examples: + - name: developers + description: Development team required: - name properties: @@ -1884,10 +1940,13 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: putV2OrgsByOrgNameGroupsByGroupName patch: summary: Update some details for an organization group description: | - + Update some details for an organization group. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1896,11 +1955,21 @@ paths: content: application/json: schema: + examples: + - description: Development team + role: member properties: name: type: string description: type: string + role: + type: string + description: | + Role assigned to the team. Valid values are the core roles + `owner`, `editor`, and `member`, or the name of an + existing [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/). + Use the custom role's name identifier, not its label or UUID. responses: "200": description: "" @@ -1914,10 +1983,13 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: patchV2OrgsByOrgNameGroupsByGroupName delete: summary: Delete an organization group description: | - + Delete an organization group. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -1931,6 +2003,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: deleteV2OrgsByOrgNameGroupsByGroupName /v2/orgs/{org_name}/groups/{group_name}/members: x-audience: public get: @@ -1941,17 +2014,13 @@ paths: - $ref: "#/components/parameters/group_name" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/page_size" - - in: query - name: search - schema: - type: string - description: Search members by username, full_name or email. + - $ref: "#/components/parameters/search" summary: List members of a group description: | List the members (users) that are in a group. If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups responses: @@ -1965,28 +2034,47 @@ paths: type: number example: 1 next: - type: string + type: + - string + - "null" example: null previous: - type: string + type: + - string + - "null" example: null results: type: array items: $ref: "#/components/schemas/group_member" + type: object + examples: + - count: 1 + next: null + previous: null + results: + - id: 0ab70deb065a43fcacd55d48caa945d8 + username: dockeruser + full_name: Jon Snow + type: User + date_joined: "2021-01-05T21:06:53.506400Z" + email: example@docker.com "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: getV2OrgsByOrgNameGroupsByGroupNameMembers post: parameters: - $ref: "#/components/parameters/org_name" - $ref: "#/components/parameters/group_name" summary: Add a member to a group description: | - + Add a member to a group. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -2004,6 +2092,7 @@ paths: $ref: "#/components/responses/not_found" "500": $ref: "#/components/responses/internal_error" + operationId: postV2OrgsByOrgNameGroupsByGroupNameMembers /v2/orgs/{org_name}/groups/{group_name}/members/{username}: x-audience: public parameters: @@ -2013,7 +2102,9 @@ paths: delete: summary: Remove a user from a group description: | - + Remove a user from a group. + + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - groups security: @@ -2027,10 +2118,12 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: deleteV2OrgsByOrgNameGroupsByGroupNameMembersByUsername /v2/invites/{id}: x-audience: public parameters: - - in: path + - description: ID of the invitation. + in: path name: id required: true schema: @@ -2040,7 +2133,7 @@ paths: description: | Mark the invite as cancelled so it doesn't show up on the list of pending invites - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - invites security: @@ -2054,10 +2147,12 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: deleteV2InvitesById /v2/invites/{id}/resend: x-audience: public parameters: - - in: path + - description: ID of the invitation. + in: path name: id schema: type: string @@ -2067,7 +2162,7 @@ paths: description: | Resend a pending invite to the user, any org owner can resend an invite - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - invites security: @@ -2081,6 +2176,7 @@ paths: $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not_found" + operationId: patchV2InvitesByIdResend /v2/invites/bulk: x-audience: public parameters: @@ -2090,7 +2186,7 @@ paths: description: | Create multiple invites by emails or DockerIDs. Only a team owner can create invites. - + This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes. tags: - invites requestBody: @@ -2103,14 +2199,12 @@ paths: content: application/json: schema: - type: object - properties: - invitees: - $ref: "#/components/schemas/bulk_invite" + $ref: "#/components/schemas/bulk_invite" "400": $ref: "#/components/responses/bad_request" "409": $ref: "#/components/responses/conflict" + operationId: postV2InvitesBulk /v2/scim/2.0/ServiceProviderConfig: x-audience: public get: @@ -2120,7 +2214,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_service_provider_config_resp" @@ -2128,6 +2222,7 @@ paths: $ref: "#/components/responses/scim_unauthorized" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20ServiceProviderConfig /v2/scim/2.0/ResourceTypes: x-audience: public get: @@ -2137,7 +2232,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_resource_types_resp" @@ -2145,6 +2240,7 @@ paths: $ref: "#/components/responses/scim_unauthorized" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20ResourceTypes /v2/scim/2.0/ResourceTypes/{name}: x-audience: public get: @@ -2154,14 +2250,15 @@ paths: tags: - scim parameters: - - name: name + - description: Name of the SCIM resource type. + name: name in: path schema: type: string example: User required: true security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_resource_type_resp" @@ -2171,6 +2268,7 @@ paths: $ref: "#/components/responses/scim_not_found" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20ResourceTypesByName /v2/scim/2.0/Schemas: x-audience: public get: @@ -2180,7 +2278,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_schemas_resp" @@ -2188,6 +2286,7 @@ paths: $ref: "#/components/responses/scim_unauthorized" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20Schemas /v2/scim/2.0/Schemas/{id}: x-audience: public get: @@ -2197,14 +2296,15 @@ paths: tags: - scim parameters: - - name: id + - description: URN identifying the SCIM schema. + name: id in: path schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User required: true security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_schema_resp" @@ -2214,6 +2314,7 @@ paths: $ref: "#/components/responses/scim_not_found" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20SchemasById /v2/scim/2.0/Users: x-audience: public get: @@ -2244,14 +2345,14 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] parameters: - name: startIndex in: query schema: type: integer minimum: 1 - description: "" + description: "One-based index of the first result to return." example: 1 - name: count in: query @@ -2259,16 +2360,17 @@ paths: type: integer minimum: 1 maximum: 200 - description: "" + description: "Maximum number of results to return." example: 10 - name: filter in: query schema: type: string - description: "" + description: "SCIM filter expression used to select users." example: userName eq "jon.snow@docker.com" - $ref: "#/components/parameters/scim_attributes" - - name: sortOrder + - description: Sort direction applied to the attribute specified by sortBy. + name: sortOrder in: query schema: type: string @@ -2294,6 +2396,7 @@ paths: $ref: "#/components/responses/scim_not_found" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20Users post: summary: Create user description: | @@ -2301,7 +2404,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] requestBody: $ref: "#/components/requestBodies/scim_create_user_request" responses: @@ -2319,6 +2422,7 @@ paths: $ref: "#/components/responses/scim_conflict" "500": $ref: "#/components/responses/scim_error" + operationId: postV2Scim20Users /v2/scim/2.0/Users/{id}: x-audience: public parameters: @@ -2330,7 +2434,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] responses: "200": $ref: "#/components/responses/scim_get_user_resp" @@ -2344,6 +2448,7 @@ paths: $ref: "#/components/responses/scim_not_found" "500": $ref: "#/components/responses/scim_error" + operationId: getV2Scim20UsersById put: summary: Update a user description: | @@ -2351,7 +2456,7 @@ paths: tags: - scim security: - - bearerSCIMAuth: [] + - scimToken: [] requestBody: $ref: "#/components/requestBodies/scim_update_user_request" responses: @@ -2369,6 +2474,7 @@ paths: $ref: "#/components/responses/scim_conflict" "500": $ref: "#/components/responses/scim_error" + operationId: putV2Scim20UsersById components: responses: BadRequest: @@ -2376,25 +2482,49 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ValueError" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: bad request + errinfo: null Unauthorized: description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: unauthorized + errinfo: null Forbidden: description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: permission denied + errinfo: null NotFound: description: Not Found content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: not found + errinfo: null list_tags: description: list repository tags content: @@ -2413,40 +2543,83 @@ components: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: bad request + errinfo: null unauthorized: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: unauthorized + errinfo: null forbidden: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: permission denied + errinfo: null not_found: description: Not Found content: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: not found + errinfo: null conflict: description: Conflict content: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: conflict + errinfo: null internal_error: description: Internal content: application/json: schema: $ref: "#/components/schemas/error" + examples: + error: + summary: Example error response + value: + message: internal error + errinfo: null scim_bad_request: description: Bad Request content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "400" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2460,6 +2633,13 @@ components: description: Unauthorized content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "401" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2470,6 +2650,13 @@ components: description: Forbidden content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "403" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2480,6 +2667,13 @@ components: description: Not Found content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "404" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2490,6 +2684,13 @@ components: description: Conflict content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "409" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2500,6 +2701,13 @@ components: description: Internal Error content: application/scim+json: + examples: + error: + summary: Example error envelope + value: + schemas: + - urn:ietf:params:scim:api:messages:2.0:Error + status: "500" schema: allOf: - $ref: "#/components/schemas/scim_error" @@ -2527,10 +2735,22 @@ components: totalResults: type: integer example: 1 - resources: + Resources: type: array items: $ref: "#/components/schemas/scim_resource_type" + examples: + - schemas: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + totalResults: 1 + Resources: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:ResourceType + id: User + name: User + description: User + endpoint: /Users + schema: urn:ietf:params:scim:schemas:core:2.0:User scim_get_resource_type_resp: description: "" content: @@ -2552,10 +2772,21 @@ components: totalResults: type: integer example: 1 - resources: + Resources: type: array items: $ref: "#/components/schemas/scim_schema" + examples: + - schemas: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + totalResults: 1 + Resources: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:Schema + id: urn:ietf:params:scim:schemas:core:2.0:User + name: User + description: User Account + attributes: [] scim_get_schema_resp: description: "" content: @@ -2584,10 +2815,38 @@ components: itemsPerPage: type: integer example: 10 - resources: + Resources: type: array items: $ref: "#/components/schemas/scim_user" + examples: + - schemas: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + totalResults: 1 + Resources: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + id: d80f7c79-7730-49d8-9a41-7c42fb622d9c + userName: jon.snow@docker.com + name: + givenName: Jon + familyName: Snow + displayName: jonsnow + active: true + emails: + - value: jon.snow@docker.com + display: jon.snow@docker.com + primary: true + groups: + - value: nightswatch + display: nightswatch + meta: + resourceType: User + location: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c + created: "2022-05-20T00:54:18Z" + lastModified: "2022-05-20T00:54:18Z" + startIndex: 1 + itemsPerPage: 1 scim_create_user_resp: description: "" content: @@ -2631,11 +2890,16 @@ components: type: string description: List of immutable tag rules example: - - "v.*" - - ".*-RELEASE" + - v.* + - .*-RELEASE required: - immutable_tags - immutable_tags_rules + examples: + - immutable_tags: true + immutable_tags_rules: + - v.* + - .*-RELEASE repo_creation_request: type: object required: @@ -2650,26 +2914,26 @@ components: Letters must be lowercase. minLength: 2 maxLength: 255 - pattern: "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" - example: "my-app" + pattern: ^[a-z0-9]+(?:[._-][a-z0-9]+)*$ + example: my-app namespace: type: string description: The namespace where the repository will be created - example: "myorganization" + example: myorganization description: type: string description: Short description of the repository maxLength: 100 - example: "A sample application repository" + example: A sample application repository full_description: type: string description: Detailed description of the repository maxLength: 25000 - example: "This is a comprehensive description of my application repository that contains additional details about the project, its purpose, usage instructions, and other relevant information." + example: This is a comprehensive description of my application repository that contains additional details about the project, its purpose, usage instructions, and other relevant information. registry: type: string description: The registry where the repository will be hosted - example: "docker.io" + example: docker.io is_private: type: boolean description: Whether the repository should be private @@ -2693,20 +2957,26 @@ components: - read: Can view and pull from the repository - write: Can view, pull, and push to the repository - admin: Can view, pull, push, and manage repository settings - enum: ["read", "write", "admin"] - example: "write" + enum: + - read + - write + - admin + example: write RepositoryGroup: type: object properties: group_name: type: string description: The name of the group - example: "developers" + example: developers permission: type: string description: The permission level granted to the group - enum: ["read", "write", "admin"] - example: "write" + enum: + - read + - write + - admin + example: write group_id: type: integer format: int64 @@ -2725,8 +2995,9 @@ components: type: string description: Repository namespace repository_type: - type: string - nullable: true + type: + - string + - "null" description: Type of the repository status: type: integer @@ -2757,10 +3028,11 @@ components: example: "2021-01-05T21:06:53.506400Z" description: ISO 8601 timestamp of when repository was last updated last_modified: - type: string + type: + - string + - "null" format: date-time example: "2021-01-05T21:06:53.506400Z" - nullable: true description: ISO 8601 timestamp of when repository was last modified date_registered: type: string @@ -2772,27 +3044,31 @@ components: format: int64 description: Number of collaborators affiliation: - type: string - nullable: true + type: + - string + - "null" description: Repository affiliation hub_user: - type: string - nullable: true + type: + - string + - "null" description: Hub user information has_starred: type: boolean description: Whether the current user has starred this repository full_description: - type: string - nullable: true + type: + - string + - "null" description: Full description of the repository permissions: $ref: "#/components/schemas/repo_permissions" media_types: type: array items: - type: string - nullable: true + type: + - string + - "null" description: Supported media types content_types: type: array @@ -2807,13 +3083,15 @@ components: immutable_tags_settings: $ref: "#/components/schemas/immutable_tags_settings" storage_size: - type: integer + type: + - integer + - "null" format: int64 - nullable: true description: Storage size in bytes source: - type: string - nullable: true + type: + - string + - "null" description: Source of the repository, where it was created from required: - user @@ -2835,6 +3113,36 @@ components: - content_types - categories - immutable_tags_settings + examples: + - name: my-app + namespace: myorganization + repository_type: image + status: 1 + status_description: Active + description: A sample application repository + is_private: false + is_automated: false + star_count: 0 + pull_count: 0 + last_updated: "2025-01-20T10:30:00Z" + date_registered: "2025-01-20T10:30:00Z" + collaborator_count: 0 + hub_user: myorganization + has_starred: false + full_description: This is a comprehensive description of my application repository that contains additional details about the project. + media_types: [] + content_types: [] + categories: [] + immutable_tags_settings: + enabled: false + rules: [] + storage_size: null + source: null + user: myorganization + permissions: + read: true + write: true + admin: true repo_permissions: type: object properties: @@ -2870,12 +3178,19 @@ components: properties: regex: type: string - pattern: '^[a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*(\\/[a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*)*$' - description: 'Immutable tags rule regex pattern. Must match format: [a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*(\\/[a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*)*' - example: "v.*" + pattern: ^[^,]*$ + description: Regular expression using Go regular expression syntax. Commas are not permitted. + example: v.* required: - regex + examples: + - regex: v.* immutable_tags_verify_response: + examples: + - tags: + - v1.0.0 + - v2.1.3 + - latest type: object properties: tags: @@ -2884,9 +3199,9 @@ components: type: string description: List of tags that match the provided regex pattern example: - - "v1.0.0" - - "v2.1.3" - - "latest" + - v1.0.0 + - v2.1.3 + - latest required: - tags repository_list_entry: @@ -2895,20 +3210,21 @@ components: name: type: string description: Name of the repository - example: "hello-world" + example: hello-world namespace: type: string description: Namespace (organization or username) that owns the repository - example: "docker" + example: docker repository_type: - type: string + type: + - string + - "null" description: Type of repository enum: - image - plugin - null - example: "image" - nullable: true + example: image status: type: integer description: Repository status code @@ -2919,12 +3235,13 @@ components: enum: - active - inactive - example: "active" + example: active description: - type: string + type: + - string + - "null" description: Repository description - nullable: true - example: "Hello World! (an example of minimal Dockerization)" + example: Hello World! (an example of minimal Dockerization) is_private: type: boolean description: Whether the repository is private @@ -2940,22 +3257,24 @@ components: minimum: 0 example: 50000000 last_updated: - type: string + type: + - string + - "null" format: date-time description: ISO 8601 timestamp of when the repository was last updated - example: "2023-12-01T10:30:00Z" - nullable: true + example: 2023-12-01T10:30:00Z last_modified: - type: string + type: + - string + - "null" format: date-time description: ISO 8601 timestamp of when the repository was last modified - example: "2023-12-01T10:30:00Z" - nullable: true + example: 2023-12-01T10:30:00Z date_registered: type: string format: date-time description: ISO 8601 timestamp of when the repository was created - example: "2013-06-19T19:07:54Z" + example: 2013-06-19T19:07:54Z affiliation: type: string description: User's affiliation with the repository (empty string if no affiliation) @@ -2966,14 +3285,14 @@ components: items: type: string example: - - "application/vnd.docker.plugin.v1+json" + - application/vnd.docker.plugin.v1+json content_types: type: array description: Content types supported by this repository items: type: string example: - - "plugin" + - plugin categories: type: array description: Categories associated with this repository @@ -2994,14 +3313,14 @@ components: name: type: string description: Human-readable name of the category - example: "Databases" + example: Databases minLength: 1 slug: type: string description: URL-friendly identifier for the category - example: "databases" + example: databases minLength: 1 - pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" + pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: Repository category for classification and discovery list_repositories_response: allOf: @@ -3013,6 +3332,9 @@ components: items: $ref: "#/components/schemas/repository_list_entry" UsersLoginRequest: + examples: + - username: myusername + password: p@ssw0rd description: User login details type: object required: @@ -3029,6 +3351,8 @@ components: type: string example: p@ssw0rd AuthCreateTokenResponse: + examples: + - access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c description: successful access token response type: object properties: @@ -3037,6 +3361,8 @@ components: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c PostUsersLoginSuccessResponse: + examples: + - token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c description: successful user login response type: object properties: @@ -3046,8 +3372,9 @@ components: This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - nullable: false PostUsersLoginErrorResponse: + examples: + - detail: Incorrect authentication credentials description: failed user login response or second factor required type: object required: @@ -3057,14 +3384,17 @@ components: description: Description of the error. type: string example: Incorrect authentication credentials - nullable: false login_2fa_token: description: | Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled. - type: string + type: + - string + - "null" example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - nullable: true Users2FALoginRequest: + examples: + - login_2fa_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + code: "123456" description: Second factor user login details type: object required: @@ -3072,15 +3402,17 @@ components: - code properties: login_2fa_token: - description: The intermediate 2FA token returned from `/v2/users/login` API. + description: The intermediate 2FA token returned from `/v2/auth/token` API. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c code: description: | The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string - example: 123456 + example: "123456" PostUsers2FALoginErrorResponse: + examples: + - detail: Incorrect authentication credentials description: failed second factor login response. type: object properties: @@ -3088,27 +3420,6 @@ components: description: Description of the error. type: string example: Incorrect authentication credentials - nullable: false - protobufAny: - type: object - properties: - type_url: - type: string - value: - type: string - format: byte - rpcStatus: - type: object - properties: - code: - type: integer - format: int32 - message: - type: string - details: - type: array - items: - $ref: "#/components/schemas/protobufAny" AuditLogAction: type: object properties: @@ -3172,23 +3483,6 @@ components: action_description: type: string description: Audit log event. - ValueError: - type: object - description: Used to error if input validation fails. - properties: - fields: - type: object - items: - type: string - text: - type: string - Error: - type: object - properties: - detail: - type: string - message: - type: string accessToken: type: object properties: @@ -3208,9 +3502,10 @@ components: type: string example: "2021-07-20T12:00:00.000000Z" last_used: - type: string + type: + - string + - "null" example: null - nullable: true generated_by: type: string example: manual @@ -3220,6 +3515,7 @@ components: token: type: string example: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + description: Token value returned on creation. Later responses redact the value as ***. token_label: type: string example: My read only token @@ -3230,10 +3526,16 @@ components: items: type: string expires_at: - type: string + type: + - string + - "null" format: date-time example: "2021-10-28T18:30:19.520861Z" createAccessTokenRequest: + examples: + - token_label: My read only token + scopes: + - repo:read type: object required: - token_label @@ -3248,7 +3550,7 @@ components: scopes: type: array description: | - Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read" + Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read", "sandbox:use". Include one repository scope, "sandbox:use", or both. example: - repo:read items: @@ -3259,8 +3561,22 @@ components: Optional expiration date for the token. If omitted, the token will remain valid indefinitely. format: date-time - example: "2021-10-28T18:30:19.520861Z" + example: 2021-10-28T18:30:19.520861Z createAccessTokensResponse: + examples: + - uuid: b30bbf97-506c-4ecd-aabc-842f3cb484fb + client_id: HUB + creator_ip: 127.0.0.1 + creator_ua: some user agent + created_at: "2021-07-20T12:00:00.000000Z" + last_used: null + generated_by: manual + is_active: true + token: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + token_label: My read only token + scopes: + - repo:read + expires_at: "2021-10-28T18:30:19.520861Z" $ref: "#/components/schemas/accessToken" getAccessTokensResponse: type: object @@ -3269,10 +3585,14 @@ components: type: number example: 1 next: - type: string + type: + - string + - "null" example: null previous: - type: string + type: + - string + - "null" example: null active_count: type: number @@ -3286,8 +3606,30 @@ components: properties: token: type: string - example: "" + example: "***" + examples: + - count: 1 + active_count: 1 + next: null + previous: null + results: + - uuid: b30bbf97-506c-4ecd-aabc-842f3cb484fb + client_id: HUB + creator_ip: 127.0.0.1 + creator_ua: some user agent + created_at: "2021-07-20T12:00:00.000000Z" + last_used: null + generated_by: manual + is_active: true + token: "***" + token_label: My read only token + scopes: + - repo:read + expires_at: "2021-10-28T18:30:19.520861Z" patchAccessTokenRequest: + examples: + - token_label: My read only token + is_active: false type: object properties: token_label: @@ -3300,7 +3642,26 @@ components: example: false patchAccessTokenResponse: $ref: "#/components/schemas/accessToken" + examples: + - uuid: b30bbf97-506c-4ecd-aabc-842f3cb484fb + client_id: HUB + creator_ip: 127.0.0.1 + creator_ua: some user agent + created_at: "2021-07-20T12:00:00.000000Z" + last_used: null + generated_by: manual + is_active: true + token: "***" + token_label: My read only token + scopes: + - repo:read + expires_at: "2021-10-28T18:30:19.520861Z" orgSettings: + examples: + - restricted_images: + enabled: true + allow_official_images: true + allow_verified_publishers: true type: object properties: restricted_images: @@ -3324,9 +3685,10 @@ components: type: object properties: digest: - type: string + type: + - string + - "null" description: image layer digest - nullable: true size: type: integer description: size of the layer @@ -3340,15 +3702,20 @@ components: type: string description: CPU architecture features: - type: string + type: + - string + - "null" description: CPU features variant: - type: string + type: + - string + - "null" description: CPU variant digest: - type: string + type: + - string + - "null" description: image digest - nullable: true layers: type: array items: @@ -3357,10 +3724,14 @@ components: type: string description: operating system os_features: - type: string + type: + - string + - "null" description: OS features os_version: - type: string + type: + - string + - "null" description: OS version size: type: integer @@ -3372,15 +3743,17 @@ components: - inactive description: Status of the image last_pulled: - type: string + type: + - string + - "null" example: "2021-01-05T21:06:53.506400Z" description: datetime of last pull - nullable: true last_pushed: - type: string + type: + - string + - "null" example: "2021-01-05T21:06:53.506400Z" description: datetime of last push - nullable: true tag: type: object properties: @@ -3388,16 +3761,20 @@ components: type: integer description: tag ID images: - type: object - $ref: "#/components/schemas/image" + type: + - array + - "null" + items: + $ref: "#/components/schemas/image" creator: type: integer description: ID of the user that pushed the tag last_updated: - type: string + type: + - string + - "null" example: "2021-01-05T21:06:53.506400Z" description: datetime of last update - nullable: true last_updater: type: integer description: ID of the last user that updated the tag @@ -3414,24 +3791,50 @@ components: type: integer description: compressed size (sum of all layers) of the tagged image v2: - type: string - description: repository API version - status: - type: string - enum: - - active - - inactive - description: whether a tag has been pushed to or pulled in the past month + type: boolean + description: Whether the tag uses the Registry V2 format. tag_last_pulled: - type: string + type: + - string + - "null" example: "2021-01-05T21:06:53.506400Z" description: datetime of last pull - nullable: true tag_last_pushed: - type: string + type: + - string + - "null" example: "2021-01-05T21:06:53.506400Z" description: datetime of last push - nullable: true + tag_status: + type: string + enum: + - active + - inactive + description: whether a tag has been pushed to or pulled in the past month + examples: + - id: 12345 + name: latest + last_updated: "2021-01-05T21:06:53.506400Z" + full_size: 123456 + v2: true + images: + - architecture: amd64 + features: null + variant: null + os: linux + os_features: null + os_version: null + size: 123456 + status: active + last_pulled: null + last_pushed: "2021-01-05T21:06:53.506400Z" + creator: 1234 + last_updater: 1234 + last_updater_username: dockeruser + repository: 5678 + tag_status: active + tag_last_pulled: null + tag_last_pushed: "2021-01-05T21:06:53.506400Z" paginated_tags: allOf: - $ref: "#/components/schemas/page" @@ -3441,6 +3844,34 @@ components: type: array items: $ref: "#/components/schemas/tag" + examples: + - count: 1 + next: null + previous: null + results: + - id: 12345 + name: latest + last_updated: "2021-01-05T21:06:53.506400Z" + full_size: 123456 + v2: true + images: + - architecture: amd64 + features: null + variant: null + os: linux + os_features: null + os_version: null + size: 123456 + status: active + last_pulled: null + last_pushed: "2021-01-05T21:06:53.506400Z" + creator: 1234 + last_updater: 1234 + last_updater_username: dockeruser + repository: 5678 + tag_status: active + tag_last_pulled: null + tag_last_pushed: "2021-01-05T21:06:53.506400Z" page: type: object properties: @@ -3448,13 +3879,15 @@ components: type: integer description: total number of results available across all pages next: - type: string + type: + - string + - "null" description: link to next page of results if any - nullable: true previous: - type: string + type: + - string + - "null" description: link to previous page of results if any - nullable: true scim_schema_attribute: type: object properties: @@ -3522,7 +3955,7 @@ components: example: owners created_at: type: string - example: "2021-10-28T18:30:19.520861Z" + example: 2021-10-28T18:30:19.520861Z bulk_invite: type: object properties: @@ -3551,7 +3984,7 @@ components: invitee: invitee@docker.com org: docker team: owners - created_at: "2021-10-28T18:30:19.520861Z" + created_at: 2021-10-28T18:30:19.520861Z - invitee: invitee2@docker.com status: existing_org_member - invitee: invitee3@docker.com @@ -3560,13 +3993,16 @@ components: type: object properties: errinfo: - type: object - items: - type: string + type: + - object + - "null" + additionalProperties: true + description: Additional error context, when available. detail: type: string message: type: string + description: Error details vary by endpoint. The message describes the failure; errinfo can contain additional context. scim_error: type: object properties: @@ -3593,7 +4029,7 @@ components: example: Docker Inc date_joined: type: string - example: "2021-01-05T21:06:53.506400Z" + example: 2021-01-05T21:06:53.506400Z full_name: type: string example: Jon Snow @@ -3624,9 +4060,12 @@ components: example: example@docker.com role: type: string - description: User's role in the Organization + description: | + The member's role in the organization (`Owner`, `Editor`, + `Member`, or `Invitee` for pending invites). enum: - Owner + - Editor - Member - Invitee example: Owner @@ -3648,26 +4087,40 @@ components: example: example@docker.com deprecated: true last_logged_in_at: - type: string + type: + - string + - "null" format: date-time description: | - Last time the user logged in. To access this field, you must have insights visible for your organization. See - [Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users). + Last time the user logged in. To access this field, you must have insights visible for your organization. See + [Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users). example: "2021-01-05T21:06:53.506400Z" last_seen_at: - type: string + type: + - string + - "null" format: date-time description: | - Last time the user was seen. To access this field, you must have insights visible for your organization. See - [Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users). + Last time the user was seen. To access this field, you must have insights visible for your organization. See + [Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users). example: "2021-01-05T21:06:53.506400Z" last_desktop_version: type: string description: | - Last desktop version the user used. To access this field, you must have insights visible for your organization. See - [Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users). + Last desktop version the user used. To access this field, you must have insights visible for your organization. See + [Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users). example: 4.29.0 - + examples: + - id: 0ab70deb065a43fcacd55d48caa945d8 + username: dockeruser + full_name: Jon Snow + type: User + date_joined: "2021-01-05T21:06:53.506400Z" + email: example@docker.com + role: Owner + groups: + - owners + is_guest: false org_member_paginated: type: object properties: @@ -3676,18 +4129,37 @@ components: description: The total number of items that match with the search. example: 120 previous: - type: string + type: + - string + - "null" description: The URL or link for the previous page of items. - example: https://hub.docker.com/v2/some/resources/items?page=1&page_size=20 + example: null next: - type: string + type: + - string + - "null" description: The URL or link for the next page of items. - example: https://hub.docker.com/v2/some/resources/items?page=3&page_size=20 + example: null results: type: array description: List of accounts. items: $ref: "#/components/schemas/org_member" + examples: + - count: 1 + next: null + previous: null + results: + - id: 0ab70deb065a43fcacd55d48caa945d8 + username: dockeruser + full_name: Jon Snow + type: User + date_joined: "2021-01-05T21:06:53.506400Z" + email: example@docker.com + role: Owner + groups: + - owners + is_guest: false org_group: type: object properties: @@ -3710,6 +4182,20 @@ components: type: number example: 10 description: Member count of the group + role: + type: + - string + - "null" + description: | + Role assigned to the team. A core role (`owner`, `editor`, or `member`) + or the name of a custom role (not the label or UUID). + examples: + - id: 10 + uuid: e36eca69-4cc8-4f17-9845-ae8c2b832691 + name: developers + description: Development team + member_count: 1 + role: member group_member: type: object properties: @@ -3723,7 +4209,7 @@ components: date_joined: type: string format: date-time - example: "2021-01-05T21:06:53.506400Z" + example: 2021-01-05T21:06:53.506400Z full_name: type: string example: John Snow @@ -3793,7 +4279,8 @@ components: properties: supported: type: boolean - example: false + example: true + type: object bulk: type: object properties: @@ -3812,7 +4299,7 @@ components: example: true maxResults: type: integer - example: 99999 + example: 200 changePassword: type: object properties: @@ -3832,21 +4319,53 @@ components: type: boolean example: false authenticationSchemes: - type: object - properties: - name: - type: string - example: OAuth 2.0 Bearer Token - description: - type: string - example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. - specUri: - type: string - example: http://tools.ietf.org/html/rfc6750 - type: - type: string - example: oauthbearertoken + type: array + items: + type: object + properties: + name: + type: string + example: OAuth 2.0 Bearer Token + description: + type: string + example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. + specUri: + type: string + example: http://tools.ietf.org/html/rfc6750 + type: + type: string + example: oauthbearertoken + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig + patch: + supported: true + bulk: + supported: false + maxOperations: 0 + maxPayloadSize: 0 + filter: + supported: true + maxResults: 200 + changePassword: + supported: false + sort: + supported: true + etag: + supported: false + authenticationSchemes: + - name: OAuth 2.0 Bearer Token + specUri: http://tools.ietf.org/html/rfc6750 + type: oauthbearertoken scim_resource_type: + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:ResourceType + id: User + name: User + description: User + endpoint: /Users + schema: urn:ietf:params:scim:schemas:core:2.0:User type: object properties: schemas: @@ -3871,6 +4390,13 @@ components: type: string example: urn:ietf:params:scim:schemas:core:2.0:User scim_schema: + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:Schema + id: urn:ietf:params:scim:schemas:core:2.0:User + name: User + description: User Account + attributes: [] type: object properties: schemas: @@ -3942,6 +4468,28 @@ components: example: d80f7c79-7730-49d8-9a41-7c42fb622d9c description: The unique identifier for the user. A v4 UUID. scim_user: + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + id: d80f7c79-7730-49d8-9a41-7c42fb622d9c + userName: jon.snow@docker.com + name: + givenName: Jon + familyName: Snow + displayName: jonsnow + active: true + emails: + - value: jon.snow@docker.com + display: jon.snow@docker.com + primary: true + groups: + - value: nightswatch + display: nightswatch + meta: + resourceType: User + location: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c + created: "2022-05-20T00:54:18Z" + lastModified: "2022-05-20T00:54:18Z" type: object properties: schemas: @@ -3978,41 +4526,43 @@ components: type: string format: date-time description: The creation date for the user as a RFC3339 formatted string. - example: "2022-05-20T00:54:18Z" + example: 2022-05-20T00:54:18Z lastModified: type: string format: date-time description: The date the user was last modified as a RFC3339 formatted string. - example: "2022-05-20T00:54:18Z" + example: 2022-05-20T00:54:18Z orgAccessToken: type: object properties: id: type: string - example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" + example: a7a5ef25-8889-43a0-8cc7-f2a94268e861 label: type: string - example: "My organization token" + example: My organization token created_by: type: string - example: "johndoe" + example: johndoe is_active: type: boolean example: true created_at: type: string format: date-time - example: "2022-05-20T00:54:18Z" + example: 2022-05-20T00:54:18Z expires_at: - type: string + type: + - string + - "null" format: date-time - example: "2023-05-20T00:54:18Z" - nullable: true + example: 2023-05-20T00:54:18Z last_used_at: - type: string + type: + - string + - "null" format: date-time - example: "2022-06-15T12:30:45Z" - nullable: true + example: 2022-06-15T12:30:45Z orgAccessTokenResource: type: object properties: @@ -4021,12 +4571,11 @@ components: enum: - TYPE_REPO - TYPE_ORG - example: "TYPE_REPO" + example: TYPE_REPO description: The type of resource - required: true path: type: string - example: "myorg/myrepo" + example: myorg/myrepo description: | The path of the resource. The format of this will change depending on the type of resource. @@ -4034,14 +4583,16 @@ components: - Must be an existing repository name (e.g., "myorg/myrepo") - Can use glob patterns (e.g., "myorg/*" for all repositories in the organization) - Use "*/*/public" to reference all public repositories - required: true scopes: type: array description: The scopes this token has access to items: type: string - example: "scope-image-pull" - required: true + example: scope-image-pull + required: + - type + - path + - scopes getOrgAccessTokensResponse: type: object properties: @@ -4049,16 +4600,45 @@ components: type: number example: 10 next: - type: string - example: https://hub.docker.com/v2/orgs/docker/access-tokens?page=2&page_size=10 + type: + - string + - "null" + example: null previous: - type: string - example: https://hub.docker.com/v2/orgs/docker/access-tokens?page=1&page_size=10 + type: + - string + - "null" + example: null results: type: array items: $ref: "#/components/schemas/orgAccessToken" + examples: + - total: 1 + next: null + previous: null + results: + - id: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + label: My organization token + created_by: johndoe + is_active: true + created_at: "2022-05-20T00:54:18Z" + expires_at: "2023-05-20T00:54:18Z" + last_used_at: "2022-06-15T12:30:45Z" getOrgAccessTokenResponse: + examples: + - id: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + label: My organization token + created_by: johndoe + is_active: true + created_at: "2022-05-20T00:54:18Z" + expires_at: "2023-05-20T00:54:18Z" + last_used_at: "2022-06-15T12:30:45Z" + resources: + - type: TYPE_REPO + path: myorg/myrepo + scopes: + - scope-image-pull allOf: - $ref: "#/components/schemas/orgAccessToken" - type: object @@ -4069,77 +4649,113 @@ components: items: $ref: "#/components/schemas/orgAccessTokenResource" createOrgAccessTokenRequest: + examples: + - label: My organization token + description: Token for CI/CD pipeline + resources: + - type: TYPE_REPO + path: myorg/myrepo + scopes: + - scope-image-pull type: object properties: label: type: string description: Label for the access token - example: "My organization token" - required: true + example: My organization token description: type: string description: Description of the access token - example: "Token for CI/CD pipeline" + example: Token for CI/CD pipeline resources: type: array + minItems: 1 description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" expires_at: - type: string + type: + - string + - "null" format: date-time description: Expiration date for the token - example: "2023-05-20T00:54:18Z" - nullable: true + example: 2023-05-20T00:54:18Z + required: + - label + - resources createOrgAccessTokenResponse: + examples: + - id: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + label: My organization token + is_active: true + created_at: "2022-05-20T00:54:18Z" + expires_at: "2023-05-20T00:54:18Z" + last_used_at: "2022-06-15T12:30:45Z" + token: dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo + resources: + - type: TYPE_REPO + path: myorg/myrepo + scopes: + - scope-image-pull type: object allOf: - type: object properties: id: type: string - example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" + example: a7a5ef25-8889-43a0-8cc7-f2a94268e861 label: type: string - example: "My organization token" + example: My organization token is_active: type: boolean example: true created_at: type: string format: date-time - example: "2022-05-20T00:54:18Z" + example: 2022-05-20T00:54:18Z expires_at: - type: string + type: + - string + - "null" format: date-time - example: "2023-05-20T00:54:18Z" - nullable: true + example: 2023-05-20T00:54:18Z last_used_at: - type: string + type: + - string + - "null" format: date-time - example: "2022-06-15T12:30:45Z" - nullable: true + example: 2022-06-15T12:30:45Z - type: object properties: token: type: string description: The actual token value that can be used for authentication - example: "dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo" + example: dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo resources: type: array items: $ref: "#/components/schemas/orgAccessTokenResource" updateOrgAccessTokenRequest: + examples: + - label: My organization token + description: Token for CI/CD pipeline + resources: + - type: TYPE_REPO + path: myorg/myrepo + scopes: + - scope-image-pull + is_active: true type: object properties: label: type: string description: Label for the access token - example: "My organization token" + example: My organization token description: type: string description: Description of the access token - example: "Token for CI/CD pipeline" + example: Token for CI/CD pipeline resources: type: array description: Resources this token has access to @@ -4150,6 +4766,19 @@ components: description: Whether the token is active example: true updateOrgAccessTokenResponse: + examples: + - id: a7a5ef25-8889-43a0-8cc7-f2a94268e861 + label: My organization token + created_by: johndoe + is_active: true + created_at: "2022-05-20T00:54:18Z" + expires_at: "2023-05-20T00:54:18Z" + last_used_at: "2022-06-15T12:30:45Z" + resources: + - type: TYPE_REPO + path: myorg/myrepo + scopes: + - scope-image-pull type: object allOf: - $ref: "#/components/schemas/orgAccessToken" @@ -4160,34 +4789,23 @@ components: description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" - team_repo: - allOf: - - $ref: "#/components/responses/team_repo" - properties: - group_name: - type: string - description: Name of the group - permission: - type: string - description: Repo access permission - enum: - - read - - write - - admin parameters: namespace: + description: Namespace of the repository, such as a user or organization name. in: path name: namespace required: true schema: type: string repository: + description: Name of the repository within the namespace. in: path name: repository required: true schema: type: string tag: + description: Name of the image tag. in: path name: tag required: true @@ -4220,15 +4838,19 @@ components: page: in: query name: page + required: false description: Page number (starts on 1). schema: type: integer + default: 1 page_size: in: query name: page_size + required: false description: Number of items (rows) per page. schema: type: integer + default: 10 invites: in: query name: invites @@ -4239,8 +4861,8 @@ components: in: query name: search schema: - type: integer - description: Search term. + type: string + description: Search members by username, full_name or email scim_attributes: in: query name: attributes @@ -4257,6 +4879,7 @@ components: example: d80f7c79-7730-49d8-9a41-7c42fb622d9c required: true type: + description: Filter members by membership type. in: query name: type schema: @@ -4267,6 +4890,7 @@ components: - member example: all role: + description: Filter members by their organization role. in: query name: role schema: @@ -4288,6 +4912,15 @@ components: content: application/json: schema: + examples: + - org: docker + team: owners + role: member + invitees: + - invitee1DockerId + - invitee2@docker.com + - invitee3@docker.com + dry_run: true type: object required: - org @@ -4324,6 +4957,13 @@ components: content: application/scim+json: schema: + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + userName: jon.snow@docker.com + name: + givenName: Jon + familyName: Snow type: object required: - schemas @@ -4343,22 +4983,33 @@ components: type: object required: - schemas + - userName properties: schemas: $ref: "#/components/schemas/scim_user_schemas" name: - allOf: - - $ref: "#/components/schemas/scim_user_name" - - description: If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. - enabled: + $ref: "#/components/schemas/scim_user_name" + userName: + $ref: "#/components/schemas/scim_user_username" + active: type: boolean default: false - description: If this is omitted from the request, it will default to false resulting in a deactivated user. + description: Whether the user is active. Defaults to false when omitted. + examples: + - schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + userName: jon.snow@docker.com + name: + givenName: Jon + familyName: Snow + active: true add_member_to_org_group: required: true content: application/json: schema: + examples: + - member: jonsnow type: object required: - member @@ -4386,6 +5037,10 @@ components: bearerSCIMAuth: type: http scheme: bearer + scimToken: + type: http + scheme: bearer + description: Use the SCIM provisioning token configured for the organization. x-tagGroups: - name: General tags: @@ -4406,3 +5061,5 @@ x-tagGroups: - org-access-tokens - groups - invites +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +security: [] diff --git a/content/reference/api/registry/auth.md b/content/reference/api/registry/auth.md index 601d50e4a6bc..934ecf8f248d 100644 --- a/content/reference/api/registry/auth.md +++ b/content/reference/api/registry/auth.md @@ -1,5 +1,6 @@ --- title: Registry authentication +weight: 10 description: "Specifies the Docker Registry v2 authentication" keywords: registry, images, tags, repository, distribution, Bearer authentication, advanced --- @@ -218,4 +219,4 @@ token placed in the HTTP `Authorization` header like so: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IkJWM0Q6MkFWWjpVQjVaOktJQVA6SU5QTDo1RU42Ok40SjQ6Nk1XTzpEUktFOkJWUUs6M0ZKTDpQT1RMIn0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJCQ0NZOk9VNlo6UUVKNTpXTjJDOjJBVkM6WTdZRDpBM0xZOjQ1VVc6NE9HRDpLQUxMOkNOSjU6NUlVTCIsImF1ZCI6InJlZ2lzdHJ5LmRvY2tlci5jb20iLCJleHAiOjE0MTUzODczMTUsIm5iZiI6MTQxNTM4NzAxNSwiaWF0IjoxNDE1Mzg3MDE1LCJqdGkiOiJ0WUpDTzFjNmNueXk3a0FuMGM3cktQZ2JWMUgxYkZ3cyIsInNjb3BlIjoiamxoYXduOnJlcG9zaXRvcnk6c2FtYWxiYS9teS1hcHA6cHVzaCxwdWxsIGpsaGF3bjpuYW1lc3BhY2U6c2FtYWxiYTpwdWxsIn0.Y3zZSwaZPqy4y9oRBVRImZyv3m_S9XDHF1tWwN7mL52C_IiA73SJkWVNsvNqpJIn5h7A2F8biv_S2ppQ1lgkbw ``` -This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1) \ No newline at end of file +This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1) diff --git a/content/reference/api/registry/latest.md b/content/reference/api/registry/latest.md deleted file mode 100644 index 7df6e5971659..000000000000 --- a/content/reference/api/registry/latest.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: api -title: Supported registry API for Docker Hub -linktitle: Latest -description: "Supported registry API endpoints." -keywords: registry, on-prem, images, tags, repository, distribution, api, advanced ---- diff --git a/content/reference/api/registry/latest.yaml b/content/reference/api/registry/latest.yaml index 445cc7f98f95..e28bb4506f9c 100644 --- a/content/reference/api/registry/latest.yaml +++ b/content/reference/api/registry/latest.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.3 +openapi: 3.2.0 info: title: Supported registry API for Docker Hub description: | @@ -11,14 +11,13 @@ info: It focuses on pulling, pushing, and deleting images. It does not cover the full OCI Distribution Specification. For the complete OCI specification, see [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). + version: "2" servers: - description: Docker Hub registry API x-audience: public url: https://registry-1.docker.io - tags: - name: overview - x-displayName: Overview description: | All endpoints in this API are prefixed by the version and repository name, for example: @@ -38,29 +37,28 @@ tags: 1. Consist of path components matching `[a-z0-9]+(?:[._-][a-z0-9]+)*` 2. If more than one component, they must be separated by `/` 3. Full repository name must be fewer than 256 characters - - + summary: Overview + kind: info - name: authentication - x-displayName: Authentication description: | Specifies registry authentication. externalDocs: description: Detailed authentication workflow and token usage url: https://docs.docker.com/reference/api/registry/auth/ - + summary: Authentication + kind: info - name: Manifests - x-displayName: Manifests description: | Image manifests are JSON documents that describe an image: its configuration blob, the digests of each layer blob, and metadata such as media‑types and annotations. - + summary: Manifests + kind: nav - name: Blobs - x-displayName: Blobs description: | Blobs are the binary objects referenced from manifests: the config JSON and one or more compressed layer tarballs. - + summary: Blobs + kind: nav - name: pull - x-displayName: Pulling Images description: | Pulling an image involves retrieving the manifest and downloading each of the image's layer blobs. This section outlines the general steps followed by a working example. @@ -79,94 +77,93 @@ tags: # Step 1: Get a bearer token TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull" | jq -r .token) - + # Step 2: Get the image manifest. In this example, an image manifest list is returned. curl -s -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \ https://registry-1.docker.io/v2/library/ubuntu/manifests/latest \ -o manifest-list.json - + # Step 3a: Parse the `manifests[]` array to locate the digest for your target platform (e.g., `linux/amd64`). IMAGE_MANIFEST_DIGEST=$(jq -r '.manifests[] | select(.platform.architecture == "amd64" and .platform.os == "linux") | .digest' manifest-list.json) - + # Step 3b: Get the platform-specific image manifest curl -s -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ https://registry-1.docker.io/v2/library/ubuntu/manifests/$IMAGE_MANIFEST_DIGEST \ -o manifest.json - + # Step 4: Send a HEAD request to check if the layer blob exists DIGEST=$(jq -r '.layers[0].digest' manifest.json) curl -I -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST - + # Step 5: Download the layer blob curl -L -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST ``` - - This example pulls the manifest and the first layer for the `ubuntu:latest` image on the `linux/amd64` platform. Repeat steps 4 and 5 for each digest in the `.layers[]` array in the manifest. - + This example pulls the manifest and the first layer for the `ubuntu:latest` image on the `linux/amd64` platform. Repeat steps 4 and 5 for each digest in the `.layers[]` array in the manifest. + summary: Pulling Images + kind: info - name: push - x-displayName: Pushing Images description: | Pushing an image involves uploading any image blobs (such as the config or layers), and then uploading the manifest that references those blobs. - + This section outlines the basic steps to push an image using the registry API. - + 1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/) - + 2. [Check if the blob exists](#operation/CheckBlobExists) using a `HEAD` request for each blob digest. - + 3. If the blob does not exist, [upload the blob](#operation/CompleteBlobUpload) using a monolithic `PUT` request: - First, [initiate the upload](#operation/InitiateBlobUpload) with `POST`. - Then [upload and complete](#operation/CompleteBlobUpload) with `PUT`. **Note**: Alternatively, you can upload the blob in multiple chunks by using `PATCH` requests to send each chunk, followed by a final `PUT` request to complete the upload. This is known as a [chunked upload](#operation/UploadBlobChunk) and is useful for large blobs or when resuming interrupted uploads. - + 4. [Upload the image manifest](#operation/PutImageManifest) using a `PUT` request to associate the config and layers. - + The following bash script example pushes a dummy config blob and manifest to `yourusername/helloworld:latest` on Docker Hub. You can replace `yourusername` with your Docker Hub username and `dckr_pat` with your Docker Hub personal access token. - + ```bash #!/bin/bash - + USERNAME=yourusername PASSWORD=dckr_pat REPO=yourusername/helloworld TAG=latest CONFIG=config.json MIME_TYPE=application/vnd.docker.container.image.v1+json - + # Step 1: Get a bearer token TOKEN=$(curl -s -u "$USERNAME:$PASSWORD" \ "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$REPO:push,pull" \ | jq -r .token) - + # Create a dummy config blob and compute its digest echo '{"architecture":"amd64","os":"linux","config":{},"rootfs":{"type":"layers","diff_ids":[]}}' > $CONFIG DIGEST="sha256:$(sha256sum $CONFIG | awk '{print $1}')" - + # Step 2: Check if the blob exists STATUS=$(curl -s -o /dev/null -w "%{http_code}" -I \ -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/$REPO/blobs/$DIGEST) - + if [ "$STATUS" != "200" ]; then # Step 3: Upload blob using monolithic upload LOCATION=$(curl -sI -X POST \ -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/$REPO/blobs/uploads/ \ | grep -i Location | tr -d '\r' | awk '{print $2}') - + curl -s -X PUT "$LOCATION&digest=$DIGEST" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/octet-stream" \ --data-binary @$CONFIG fi - + # Step 4: Upload the manifest that references the config blob MANIFEST=$(cat <` header. - + + Use the `Accept` header to select the manifest representation. Supported media types: + + - `application/vnd.docker.distribution.manifest.v2+json` + - `application/vnd.docker.distribution.manifest.list.v2+json` + - `application/vnd.oci.image.manifest.v1+json` + - `application/vnd.oci.image.index.v1+json` x-codeSamples: - lang: Bash label: cURL @@ -289,26 +292,6 @@ paths: value: sha256:abc123def456... schema: type: string - - name: Authorization - in: header - required: true - description: RFC7235-compliant authorization header (e.g., `Bearer `). - schema: - type: string - - name: Accept - in: header - required: false - description: | - Media type(s) the client supports for the manifest. - - The registry supports the following media types: - - application/vnd.docker.distribution.manifest.v2+json - - application/vnd.docker.distribution.manifest.list.v2+json - - application/vnd.oci.image.manifest.v1+json - - application/vnd.oci.image.index.v1+json - schema: - type: string - responses: "200": description: Manifest fetched successfully. @@ -367,28 +350,19 @@ paths: docker-manifest: summary: Docker image manifest (schema v2) value: - { - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "config": { - "mediaType": "application/vnd.docker.container.image.v1+json", - "size": 7023, - "digest": "sha256:123456abcdef..." - }, - "layers": [ - { - "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "size": 32654, - "digest": "sha256:abcdef123456..." - }, - { - "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "size": 16724, - "digest": "sha256:7890abcdef12..." - } - ] - } - + schemaVersion: 2 + mediaType: application/vnd.docker.distribution.manifest.v2+json + config: + mediaType: application/vnd.docker.container.image.v1+json + size: 7023 + digest: sha256:123456abcdef... + layers: + - mediaType: application/vnd.docker.image.rootfs.diff.tar.gzip + size: 32654 + digest: sha256:abcdef123456... + - mediaType: application/vnd.docker.image.rootfs.diff.tar.gzip + size: 16724 + digest: sha256:7890abcdef12... "400": description: Invalid name or reference. "401": @@ -399,8 +373,6 @@ paths: description: Repository or manifest not found. "429": description: Too many requests. - - put: tags: - Manifests @@ -446,20 +418,6 @@ paths: value: sha256:abc123def456... schema: type: string - - name: Authorization - in: header - required: true - description: RFC7235-compliant authorization header (e.g., `Bearer `). - schema: - type: string - - name: Content-Type - in: header - required: true - description: Media type of the manifest being uploaded. - schema: - type: string - example: application/vnd.docker.distribution.manifest.v2+json - requestBody: required: true content: @@ -512,28 +470,20 @@ paths: digest: type: string example: sha256:abcdef123456... - examples: sample-manifest: summary: Sample Docker image manifest (schema v2) value: - { - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "config": { - "mediaType": "application/vnd.docker.container.image.v1+json", - "size": 7023, - "digest": "sha256:123456abcdef..." - }, - "layers": [ - { - "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "size": 32654, - "digest": "sha256:abcdef123456..." - } - ] - } - + schemaVersion: 2 + mediaType: application/vnd.docker.distribution.manifest.v2+json + config: + mediaType: application/vnd.docker.container.image.v1+json + size: 7023 + digest: sha256:123456abcdef... + layers: + - mediaType: application/vnd.docker.image.rootfs.diff.tar.gzip + size: 32654 + digest: sha256:abcdef123456... responses: "201": description: Manifest created successfully. @@ -579,6 +529,12 @@ paths: This endpoint requires authentication with pull scope. + Use the `Accept` header to select the manifest representation. Supported media types: + + - `application/vnd.docker.distribution.manifest.v2+json` + - `application/vnd.docker.distribution.manifest.list.v2+json` + - `application/vnd.oci.image.manifest.v1+json` + - `application/vnd.oci.image.index.v1+json` parameters: - name: name in: path @@ -600,20 +556,6 @@ paths: value: sha256:abc123def456... schema: type: string - - name: Authorization - in: header - required: true - schema: - type: string - description: Bearer token for authentication - - name: Accept - in: header - required: false - schema: - type: string - example: application/vnd.docker.distribution.manifest.v2+json - description: | - Media type of the manifest to check. The response will match one of the accepted types. x-codeSamples: - lang: Bash label: cURL @@ -642,12 +584,12 @@ paths: schema: type: string example: application/vnd.docker.distribution.manifest.v2+json - "404": - description: Manifest not found. "401": description: Authentication required. "403": description: Access denied. + "404": + description: Manifest not found. "429": description: Too many requests. delete: @@ -680,12 +622,6 @@ paths: example: sha256:abc123def456... schema: type: string - - name: Authorization - in: header - required: true - description: Bearer token with `delete` access - schema: - type: string x-codeSamples: - lang: Bash label: cURL @@ -733,7 +669,6 @@ paths: curl -i -X POST \ -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/ - - lang: Bash label: cURL (Cross-Repository Blob Mount) source: | @@ -741,7 +676,6 @@ paths: curl -i -X POST \ -H "Authorization: Bearer $TOKEN" \ "https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/?mount=sha256:abc123def456...&from=library/busybox" - parameters: - name: name in: path @@ -764,13 +698,6 @@ paths: schema: type: string example: library/busybox - - name: Authorization - in: header - required: true - schema: - type: string - description: Bearer token for authentication with `push` scope - responses: "201": description: Blob successfully mounted from another repository. @@ -858,14 +785,6 @@ paths: schema: type: string example: sha256:abc123def4567890... - - name: Authorization - in: header - required: true - description: Bearer token with pull or push scope - schema: - type: string - example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6... - responses: "200": description: Blob exists @@ -885,32 +804,12 @@ paths: schema: type: string example: application/octet-stream - content: - application/json: - examples: - blob-check-request: - summary: Sample request - value: - method: HEAD - url: /v2/library/ubuntu/blobs/sha256:abc123def4567890... - headers: - Authorization: Bearer - Accept: '*/*' - blob-check-response: - summary: Sample 200 response headers - value: - status: 200 OK - headers: - Docker-Content-Digest: sha256:abc123def4567890... - Content-Length: 32654 - Content-Type: application/octet-stream - - "404": - description: Blob not found "401": description: Authentication required "403": description: Access denied + "404": + description: Blob not found "429": description: Too many requests get: @@ -950,14 +849,6 @@ paths: schema: type: string example: sha256:abc123def456... - - name: Authorization - in: header - required: true - schema: - type: string - description: Bearer token with pull scope - example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6... - responses: "200": description: Blob content returned directly @@ -985,8 +876,7 @@ paths: examples: small-layer: summary: Example binary blob (gzipped tar layer) - value: "" - + value: "307": description: Temporary redirect to blob location headers: @@ -1023,7 +913,7 @@ paths: label: cURL source: | # GET upload status - curl -I \ + curl --include --request GET \ -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123 parameters: @@ -1031,7 +921,7 @@ paths: in: path required: true description: Repository Name - example : library/ubuntu + example: library/ubuntu schema: type: string - name: uuid @@ -1041,13 +931,6 @@ paths: schema: type: string example: abc123 - - name: Authorization - in: header - required: true - schema: - type: string - example: Bearer eyJhbGciOi... - responses: "204": description: Upload in progress. No body is returned. @@ -1075,7 +958,6 @@ paths: description: Upload session not found "429": description: Too many requests - put: tags: - Blobs @@ -1089,7 +971,6 @@ paths: This endpoint supports: - Monolithic uploads (upload entire blob in this request) - Finalizing chunked uploads (last chunk plus `digest`) - x-codeSamples: - lang: Bash label: cURL @@ -1100,8 +981,6 @@ paths: -H "Content-Type: application/octet-stream" \ --data-binary @layer.tar.gz \ "https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123?digest=sha256:abcd1234..." - - parameters: - name: name in: path @@ -1124,13 +1003,6 @@ paths: schema: type: string example: sha256:abcd1234... - - name: Authorization - in: header - required: true - schema: - type: string - example: Bearer eyJhbGciOi... - requestBody: required: false content: @@ -1141,8 +1013,7 @@ paths: examples: layer-upload: summary: Layer tarball blob - value: "" - + value: responses: "201": description: Upload completed successfully @@ -1174,7 +1045,6 @@ paths: description: Requested range not satisfiable (if used in chunked mode) "429": description: Too many requests - patch: tags: - Blobs @@ -1216,12 +1086,6 @@ paths: schema: type: string example: abc123 - - name: Authorization - in: header - required: true - schema: - type: string - example: Bearer eyJhbGciOi... - name: Content-Range in: header required: false @@ -1229,7 +1093,6 @@ paths: type: string example: bytes 0-65535 description: Optional. Byte range of the chunk being sent - requestBody: required: true content: @@ -1240,8 +1103,7 @@ paths: examples: chunk-0: summary: Upload chunk 0 of a blob - value: "" - + value: responses: "202": description: Chunk accepted and stored @@ -1288,7 +1150,6 @@ paths: - The client wants to clean up unused upload sessions After cancellation, the UUID is no longer valid and a new `POST` must be issued to restart the upload. - x-codeSamples: - lang: Bash label: cURL @@ -1297,7 +1158,6 @@ paths: curl -X DELETE \ -H "Authorization: Bearer $TOKEN" \ https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123` - parameters: - name: name in: path @@ -1313,13 +1173,6 @@ paths: schema: type: string example: abc123 - - name: Authorization - in: header - required: true - schema: - type: string - example: Bearer eyJhbGciOi... - responses: "204": description: Upload session cancelled successfully. No body is returned. @@ -1337,8 +1190,6 @@ paths: description: Upload session not found "429": description: Too many requests - - x-tagGroups: - name: General tags: @@ -1351,3 +1202,12 @@ x-tagGroups: tags: - Manifests - Blobs +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +components: + securitySchemes: + registryToken: + type: http + scheme: bearer + description: Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication. +security: + - registryToken: [] diff --git a/content/reference/api/sandboxes/_index.md b/content/reference/api/sandboxes/_index.md new file mode 100644 index 000000000000..10d1cbdc29b2 --- /dev/null +++ b/content/reference/api/sandboxes/_index.md @@ -0,0 +1,7 @@ +--- +title: Docker Sandboxes API +description: HTTP API reference for Docker Cloud Sandboxes. +keywords: Docker Sandboxes, API reference, OpenAPI +build: + render: never +--- diff --git a/content/reference/api/sandboxes/api.yaml b/content/reference/api/sandboxes/api.yaml new file mode 100644 index 000000000000..988854dd9833 --- /dev/null +++ b/content/reference/api/sandboxes/api.yaml @@ -0,0 +1,9221 @@ +openapi: 3.2.0 +info: + title: Docker Sandboxes API + version: v1 + description: |- + Use this API to create sandboxes, run processes, work with files, and manage sandbox resources. Start with a kit through the SDK, or use the HTTP operations here directly. + + Management requests use an Authorization bearer token. File and process requests go to the sandbox endpoint in core.endpoint.uri and require a short-lived scoped endpoint credential, not the management token. The SDK obtains that credential for you. Each operation also checks its declared permissions. Direct Unix socket access uses the operating system's socket access controls instead of HTTP authentication. Interactive WebSocket operations describe their supported credential transports separately. + + The Docker Cloud API base URL is https://connect.docker.com/sandboxes. Append each /v1 path without removing the base URL's path prefix. For sandbox endpoint operations, use the sandbox endpoint as the base URL instead. + + Operations list their success and error responses. A 202 response means work is still in progress; read the resource until it reaches the expected state. Errors contain a stable code, a message, and optional details. Inspect the code as well as the HTTP status. + + Send the current ETag in If-Match when an operation requires it. Operations that accept Idempotency-Key use that HTTP header to identify retries: the same key and payload return the first result; a different payload fails. Keys are retained for at least 24 hours. + + Lists use pageSize and pageToken. Continue with nextPageToken until it is empty. Supported filters and ordering are listed on each operation. Resource names contain immutable identifiers; displayName is a label. A 64-bit integer is returned as a JSON string; inputs accept a number or a string. + contact: + name: Docker Cloud Sandboxes + url: https://github.com/docker/sandboxes-api +servers: + - url: https://connect.docker.com/sandboxes + description: The API base URL. Append the /v1 paths while preserving this URL's path prefix. +paths: + /v1/files: + get: + tags: + - Files + summary: List lists directory entries by path ascending. + description: List lists directory entries by path ascending. + operationId: list + parameters: + - name: path + in: query + description: path is the directory path. + required: true + schema: + type: string + title: path + minLength: 1 + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an optional continuation token. + schema: + type: string + title: page_token + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable field is + path. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesListResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Files + summary: Remove deletes a path. + description: |- + Remove deletes a path. Removing an absent path succeeds. A nonrecursive + removal of a nonempty directory returns FAILED_PRECONDITION unchanged. + A recursive removal that stops partway still answers OK: check + RemoveResponse.failed_path, not the operation status. Removed paths stay removed. + operationId: remove + parameters: + - name: path + in: query + description: path is the sandbox path to remove. + required: true + schema: + type: string + title: path + minLength: 1 + - name: recursive + in: query + description: recursive removes directory contents when true. + schema: + type: boolean + title: recursive + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesRemoveResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/files/content: + get: + tags: + - Files + summary: ReadFile returns raw file content over HTTP; Stat exposes file metadata. + description: |- + ReadFile returns raw file content over HTTP; Stat exposes file metadata. + Content above the unary message cap is refused, never truncated. + operationId: readFile + parameters: + - name: path + in: query + description: path is the sandbox path of a regular file. + required: true + schema: + type: string + title: path + minLength: 1 + responses: + "200": + description: Success + content: + application/octet-stream: + schema: + contentMediaType: application/octet-stream + headers: + Content-Length: + required: true + description: Exact byte count of the complete file; this response does not use chunked transfer encoding. + schema: + type: integer + minimum: 0 + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-http-transfer: + response: + mediaType: application/octet-stream + bytesField: data + x-sbx-request-schema: + $ref: "#/components/schemas/FilesReadFileRequest" + x-sbx-response-schema: + $ref: "#/components/schemas/FilesReadFileResponse" + put: + tags: + - Files + summary: WriteFile accepts raw content with path and mode query parameters. + description: |- + WriteFile accepts raw content with path and mode query parameters. + It replaces the complete target state and carries no request_id. + operationId: writeFile + parameters: + - name: path + in: query + description: path is the sandbox path. + required: true + schema: + type: string + title: path + minLength: 1 + - name: mode + in: query + description: |- + mode carries Unix permission bits. Upload applies mode & 0777, or 0644 when + that value is zero, without subtracting umask; Download reports stored bits. + schema: + type: integer + title: mode + required: false + requestBody: + required: true + content: + application/octet-stream: + schema: + contentMediaType: application/octet-stream + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesWriteFileResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-http-transfer: + request: + mediaType: application/octet-stream + bytesField: data + x-sbx-request-schema: + $ref: "#/components/schemas/FilesWriteFileRequest" + x-sbx-response-schema: + $ref: "#/components/schemas/FilesWriteFileResponse" + /v1/files/directories: + put: + tags: + - Files + summary: Mkdir creates a directory. + description: |- + Mkdir creates a directory. Without parents, a missing parent returns + NOT_FOUND without creating directories. A repeated Mkdir converges when + the leaf already exists as a directory. A converged call leaves + the directory's mode unchanged on every request. + operationId: mkdir + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/FilesMkdirRequest" + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesMkdirResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/files/download: + get: + tags: + - Files + summary: Download streams file headers, bytes, and per-file errors. + description: |- + Download streams file headers, bytes, and per-file errors. A path that + leaves the jail through a symlink, or names a non-regular object, reports + a FileError with a error reason instead of reading through it. + operationId: download + parameters: + - name: paths + in: query + description: |- + paths naming stable regular files or absent entries at canonical absolute paths + yield contiguous results in request order, including duplicates. + required: true + schema: + type: array + items: + type: string + title: paths + minItems: 1 + responses: + "200": + description: |- + Success + + Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures. + content: + multipart/mixed: + itemSchema: + anyOf: + - $ref: "#/components/schemas/FileHeader" + - contentMediaType: application/octet-stream + - $ref: "#/components/schemas/FileError" + - $ref: "#/components/schemas/Error" + itemEncoding: + contentType: application/json, application/octet-stream + headers: + Content-Disposition: + required: true + schema: + type: string + enum: + - attachment; name=metadata + - attachment; name=content + - attachment; name=error + - attachment; name=stream-error + x-sbx-framing: + description: Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures. + parts: + metadata: + contentType: application/json + schema: + $ref: "#/components/schemas/FileHeader" + content: + contentType: application/octet-stream + schema: + contentMediaType: application/octet-stream + error: + contentType: application/json + schema: + $ref: "#/components/schemas/FileError" + stream-error: + contentType: application/json + schema: + $ref: "#/components/schemas/Error" + repeatedItems: true + requiresClosingDelimiter: true + requiresTerminal: false + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-http-transfer: + response: + mediaType: multipart/mixed + bytesField: data + metadataField: header + errorField: error + repeatedItems: true + x-sbx-request-schema: + $ref: "#/components/schemas/FilesDownloadRequest" + x-sbx-response-schema: + $ref: "#/components/schemas/FilesDownloadResponse" + /v1/files/move: + post: + tags: + - Files + summary: Move renames or moves a path. + description: |- + Move renames or moves a path. The destination is exact: an existing regular + file is replaced, the source basename is never appended, and a directory + destination is refused unchanged. A source or destination that leaves the jail + through a symlink refuses with FAILED_PRECONDITION and a error reason. + operationId: move + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/FilesMoveRequest" + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesMoveResponse" + "409": + description: |- + The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + + The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + + `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it. + + `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing. + + `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + path_authority_symlink_escape: + summary: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + value: + code: failedPrecondition + message: "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + path_authority_nonregular_object: + summary: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + value: + code: failedPrecondition + message: "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + move_destination_is_directory: + summary: "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." + value: + code: failedPrecondition + message: "move_destination_is_directory: `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." + move_destination_occupied: + summary: "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." + value: + code: failedPrecondition + message: "move_destination_occupied: `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." + move_crosses_filesystem: + summary: "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + value: + code: failedPrecondition + message: "move_crosses_filesystem: `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + reason: path_authority_symlink_escape + - code: FAILED_PRECONDITION + description: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + reason: path_authority_nonregular_object + - code: FAILED_PRECONDITION + description: "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." + reason: move_destination_is_directory + - code: FAILED_PRECONDITION + description: "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." + reason: move_destination_occupied + - code: FAILED_PRECONDITION + description: "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + reason: move_crosses_filesystem + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/files/stat: + get: + tags: + - Files + summary: Stat reads metadata for one path. + description: |- + Stat reads metadata for one path. + A metadata read has a different response from the file-content resource. + operationId: stat + parameters: + - name: path + in: query + description: path is the sandbox path. + required: true + schema: + type: string + title: path + minLength: 1 + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesStatResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/files/upload: + post: + tags: + - Files + summary: Upload streams one or more files. + description: |- + Upload streams one or more files. The first frame must be FileHeader. + Writing through a symlink that leaves the jail, or onto an existing + non-regular object, refuses with FAILED_PRECONDITION and a error reason. + operationId: upload + requestBody: + required: true + content: + multipart/form-data: + itemSchema: + oneOf: + - type: object + properties: + metadata: + $ref: "#/components/schemas/FileHeader" + required: + - metadata + additionalProperties: false + - type: object + properties: + content: + contentMediaType: application/octet-stream + required: + - content + additionalProperties: false + itemEncoding: + contentType: application/json, application/octet-stream + x-sbx-framing: + description: Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path. + partOrder: + - metadata + - content + repeatedItems: true + requiresClosingDelimiter: true + description: Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path. + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/FilesUploadResponse" + "409": + description: |- + The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + + The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + path_authority_symlink_escape: + summary: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + value: + code: failedPrecondition + message: "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + path_authority_nonregular_object: + summary: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + value: + code: failedPrecondition + message: "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. + reason: path_authority_symlink_escape + - code: FAILED_PRECONDITION + description: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. + reason: path_authority_nonregular_object + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesFilesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-http-transfer: + request: + mediaType: multipart/form-data + bytesField: data + metadataField: header + repeatedItems: true + itemPathField: header.path + x-sbx-request-schema: + $ref: "#/components/schemas/FilesUploadRequest" + x-sbx-response-schema: + $ref: "#/components/schemas/FilesUploadResponse" + /v1/identity/exchange: + post: + tags: + - Credentials + summary: ExchangeDockerCredential consumes an identity token once for the authenticated owner. + description: |- + ExchangeDockerCredential consumes an identity token once for the authenticated owner. + The exchanged credential is stored for that owner; the response is empty. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: exchangeDockerCredential + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest" + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ExchangeCompositionCredentialResponse" + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - credentialsExchange + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/images: + get: + tags: + - Images + summary: ListImages lists images in the caller's owner scope. + description: ListImages lists images in the caller's owner scope. + operationId: listImages + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + name, display_name, uid and status. + schema: + type: string + title: filter + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable fields are + created_at and name. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListImagesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - imagesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Images + summary: CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox. + description: CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox. + operationId: createImage + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateImageRequest" + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Image" + - not: + properties: + status: + enum: + - pending + - waitingForPush + - preparing + required: + - status + headers: + Cache-Control: + required: true + schema: + type: string + const: no-store + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Image" + - properties: + status: + enum: + - pending + - waitingForPush + - preparing + required: + - status + headers: + Cache-Control: + required: true + schema: + type: string + const: no-store + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - imagesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Image" + parameters: + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + /v1/images/{image}: + get: + tags: + - Images + summary: GetImage reads one image by its resource name. + description: GetImage reads one image by its resource name. + operationId: getImage + parameters: + - name: image + in: path + description: The image id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Image" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - imagesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Images + summary: DeleteImage deletes an image; deleting an already absent image succeeds. + description: DeleteImage deletes an image; deleting an already absent image succeeds. + operationId: deleteImage + parameters: + - name: image + in: path + description: The image id. + required: true + schema: + type: string + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + responses: + "204": + description: Success. The response carries no body. + "409": + description: |- + The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + + An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + deletion_preparation_incomplete: + summary: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + value: + code: failedPrecondition + message: "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + deletion_content_lease_held: + summary: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + value: + code: failedPrecondition + message: "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + reason: deletion_preparation_incomplete + - code: FAILED_PRECONDITION + description: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + reason: deletion_content_lease_held + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - imagesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/images/{image}/pull-spec: + get: + tags: + - Images + summary: GetImagePullSpec returns short-lived pull material through registry-transfer support. + description: |- + GetImagePullSpec returns short-lived pull material through registry-transfer support. + Action: the pull spec is derived material about the image, not a sub-resource of it. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: getImagePullSpec + parameters: + - name: image + in: path + description: The image id. + required: true + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ImagePullSpec" + headers: + Cache-Control: + required: true + schema: + type: string + const: no-store + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - imagesPull + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/mcp-servers/{mcpServer}/authorization: + get: + tags: + - MCP gateways + summary: GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write. + description: GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write. + operationId: getMcpAuthorization + parameters: + - name: mcpServer + in: path + description: The mcpServer id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/McpAuthorization" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - mcpWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/mcp-servers/{mcpServer}/authorization/authorize: + post: + tags: + - MCP gateways + summary: AuthorizeMcpServer authorizes credentials for one named upstream. + description: |- + AuthorizeMcpServer authorizes credentials for one named upstream. + Action: authorization runs an interactive grant whose result is not the request body. + operationId: authorizeMcpServer + parameters: + - name: mcpServer + in: path + description: The mcpServer id. + required: true + schema: + type: string + - name: If-Match + in: header + description: Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization. + schema: + type: string + title: If-Match + description: (OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses. + requestBody: + content: + application/json: + schema: + type: object + properties: + remoteUrl: + type: + - string + - "null" + format: uri + description: remote_url binds authorization to a concrete upstream URL when supplied. + forceReauth: + type: boolean + description: |- + force_reauth starts a fresh flow while existing credentials serve until completion. + Repeating a pending flow converges without reminting. + title: AuthorizeMcpServerRequest + additionalProperties: false + description: AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/McpAuthorization" + - not: + properties: + status: + enum: + - pending + required: + - status + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/McpAuthorization" + - properties: + status: + enum: + - pending + required: + - status + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - mcpWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/McpAuthorization" + /v1/network-policies: + get: + tags: + - Network policies + summary: GetNetworkPolicies returns effective and exact views of the same installed generation. + description: GetNetworkPolicies returns effective and exact views of the same installed generation. + operationId: getNetworkPoliciesInOwnerScope + parameters: + - name: acceptedSelectorVersions + in: query + description: Omitted versions accept only destination.v1; an unsupported representation fails closed. + schema: + type: array + items: + type: string + minLength: 1 + description: "" + title: accepted_selector_versions + maxItems: 8 + uniqueItems: true + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/GetNetworkPoliciesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - networkPoliciesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/policy-logs: + get: + tags: + - Network policies + summary: ListPolicyLogEntries lists observed policy decisions. + description: ListPolicyLogEntries lists observed policy decisions. + operationId: listPolicyLogEntriesInOwnerScope + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable field is + domain. + schema: + type: string + title: filter + required: false + - name: since + in: query + description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. + schema: + type: string + examples: + - 2023-01-15T01:30:15.01Z + - 2024-12-25T12:00:00Z + format: date-time + required: false + - name: until + in: query + description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. + schema: + type: string + examples: + - 2023-01-15T01:30:15.01Z + - 2024-12-25T12:00:00Z + format: date-time + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListPolicyLogEntriesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - networkPoliciesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/processes: + get: + tags: + - Processes + summary: ListProcesses lists processes in creation order. + description: ListProcesses lists processes in creation order. + operationId: listProcesses + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an optional continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + session and state. + schema: + type: string + title: filter + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListProcessesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Processes + summary: CreateProcess starts a durable interactive process and returns its resource name. + description: CreateProcess starts a durable interactive process and returns its resource name. + operationId: createProcess + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateProcessRequest" + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Process" + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + parameters: + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + /v1/processes/exec: + post: + tags: + - Processes + summary: Exec runs one command to completion. + description: |- + Exec runs one command to completion. A retry after transport failure may run it again. + Action at the collection root: it runs a command to completion instead of creating a + process a caller can address. + operationId: exec + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ExecRequest" + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ExecResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/processes/{process}: + get: + tags: + - Processes + summary: GetProcess reads one process by its endpoint-scoped resource name. + description: GetProcess reads one process by its endpoint-scoped resource name. + operationId: getProcess + parameters: + - name: process + in: path + description: The process id. + required: true + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Process" + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/processes/{process}/interact: + get: + tags: + - Processes + summary: Interact binds the complete process name from the path to the first Attach frame. + description: |- + Interact binds the complete process name from the path to the first Attach frame. + A conflicting name is INVALID_ARGUMENT before any attach. + operationId: interact + parameters: + - name: process + in: path + description: The process id. + required: true + schema: + type: string + responses: + "101": + description: "The connection becomes a sandboxes.v1 session: one InteractRequest per inbound text frame and one ProcessOutput per outbound one. Path parameters identify the target; the first attach frame must agree. Refusals after upgrade carry an error frame followed by a close code." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-websocket: + subprotocol: sandboxes.v1 + firstRequestField: attach + resumeRequestField: attach.resumeFrom + resumeResponseField: chunk.streamSequence + bearerSubprotocolPrefix: sandboxes.bearer.v1. + maxBearerTokenBytes: 4096 + requestFrame: + $ref: "#/components/schemas/InteractRequest" + responseFrame: + $ref: "#/components/schemas/ProcessOutput" + terminalFrame: The last text frame before a close carries the one error body, because a close reason holds at most 123 bytes. + errorFrame: + $ref: "#/components/schemas/Error" + authentication: Use exactly one sandbox-scoped Authorization bearer credential or, when endpoint credentialTransports advertises webSocketSubprotocol, offer sandboxes.bearer.v1. followed by canonical unpadded base64url of that credential alongside sandboxes.v1. The decoded token is limited to 4096 bytes. The server echoes only sandboxes.v1; mixed or duplicate credentials, query credentials and cookie-only authentication are refused. + browser: Open a WSS endpoint using its scoped credential. Browsers may send cookies; the server ignores them as authority and permits cross-origin explicit bearer authentication. Browser WebSocket errors do not expose pre-upgrade HTTP status or bodies; only post-upgrade Error frames are typed. No reconnect or input replay is automatic. + reconnect: Acquire a fresh scoped credential, open a new connection, and send attach with attach.resumeFrom set to the last received chunk.streamSequence. Resume replays output only; never replay stdin or process creation. + preUpgradeStatus: + "400": The request has an invalid subprotocol offer, mixed or malformed credentials, an oversized credential, or a query parameter. + "401": The scoped credential is missing, invalid or expired. + "403": The scoped credential does not grant this endpoint permission. + "404": The scoped credential does not address this sandbox endpoint. + closeCode: + "1000": The service ended the stream, or the caller cancelled it. + "1002": The handshake negotiated no subprotocol. + "1003": A frame arrived as binary; every frame is text. + "1007": A frame was not the public JSON request message. + "1008": The service refused with a 4xx error, or the endpoint credential expired. + "1009": A frame exceeded the route’s frame limit. + "1011": The service failed with a code the front door maps to a 5xx. + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + - sandboxWebSocketBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-request-schema: + $ref: "#/components/schemas/InteractRequest" + x-sbx-response-schema: + $ref: "#/components/schemas/ProcessOutput" + /v1/processes/{process}/output: + get: + tags: + - Processes + summary: ReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed. + description: |- + ReadOutput returns one page of retained output after a stream_sequence, the + same cursor Interact resumes from, so a REST client can read what a process printed. + operationId: readOutput + parameters: + - name: process + in: path + description: The process id. + required: true + schema: + type: string + - name: resumeFrom + in: query + description: |- + resume_from returns output after this stream_sequence; 0 means from the start. + Missing output after this point fails with FAILED_PRECONDITION, as for Attach. + schema: + type: + - integer + - string + title: resume_from + format: int64 + required: false + - name: maxBytes + in: query + description: |- + max_bytes is a soft bound on the page's data: whole chunks only, and the first retained + chunk always fits so a caller always advances. 0 means the backend's default page. + schema: + type: integer + title: max_bytes + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ReadOutputResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/processes/{process}/signal: + post: + tags: + - Processes + summary: Signal sends one signal to an existing process. + description: |- + Signal sends one signal to an existing process. + Action: a signal is delivered to a running process and leaves no representation to + replace. + operationId: signal + parameters: + - name: process + in: path + description: The process id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + signal: + not: + enum: + - unspecified + description: signal is the signal to send. + $ref: "#/components/schemas/ProcessSignal" + title: SignalRequest + required: + - signal + additionalProperties: false + description: SignalRequest sends one signal. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/SignalResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + servers: + - url: "{endpoint}" + variables: + endpoint: + default: https://sandbox.invalid + description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. + security: + - sandboxBearer: [] + x-sbx-serving-surface: sandboxEndpoint + x-sbx-plane: data + x-sbx-required-permissions: + - sandboxesExec + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes: + get: + tags: + - Sandboxes + summary: ListSandboxes lists sandboxes in the caller's owner scope. + description: ListSandboxes lists sandboxes in the caller's owner scope. + operationId: listSandboxes + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + name, display_name, uid, status and agent. + schema: + type: string + title: filter + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable fields are + created_at and name. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListSandboxesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Sandboxes + summary: CreateSandbox admits a sandbox. + description: |- + CreateSandbox admits a sandbox. Unknown fields at any level are rejected before + replay lookup, reservation, policy binding, or workload effects. + operationId: createSandbox + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateSandboxRequest" + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - not: + properties: + core: + properties: + status: + enum: + - creating + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - properties: + core: + properties: + status: + enum: + - creating + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + Kit admission was refused; an available settled report describes the rejected fields. + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: Kit admission was refused; an available settled report describes the rejected fields. + detailType: docker.sandboxes.v1.KitFieldOutcomeReport + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesCreate + x-sbx-conditional-permissions: + - permission: mcpWrite + requestFieldPresent: mcp + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Sandbox" + parameters: + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + x-sbx-error-details: + KitFieldOutcomeReport: + $ref: "#/components/schemas/KitFieldOutcomeReport" + /v1/sandboxes/{sandbox}: + get: + tags: + - Sandboxes + summary: GetSandbox reads one sandbox by its resource name. + description: GetSandbox reads one sandbox by its resource name. + operationId: getSandbox + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Sandboxes + summary: DeleteSandbox returns the deleting resource while work remains, or an empty message when absent. + description: DeleteSandbox returns the deleting resource while work remains, or an empty message when absent. + operationId: deleteSandbox + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + - name: force + in: query + description: force requests deletion even when the backend would otherwise refuse the state. + schema: + type: boolean + title: force + required: false + responses: + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - properties: + core: + properties: + status: + enum: + - deleting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "204": + description: Success. The response carries no body. + "409": + description: The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesDelete + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Sandbox" + patch: + tags: + - Sandboxes + summary: UpdateSandbox changes only the display label under the observed etag. + description: |- + UpdateSandbox changes only the display label under the observed etag. + Its resource name, backing identity and child addresses remain unchanged. + operationId: updateSandbox + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + required: true + schema: + type: string + title: Idempotency-Key + minLength: 1 + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + requestBody: + content: + application/json: + schema: + type: object + properties: + displayName: + type: + - string + - "null" + maxLength: 64 + minLength: 1 + pattern: ^[a-zA-Z0-9_-]+$ + description: display_name must be present and retains the existing scoped label rules. + title: UpdateSandboxRequest + required: + - displayName + additionalProperties: false + description: UpdateSandboxRequest changes only the display label under the observed etag. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesRename + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/endpoint-credentials: + post: + tags: + - Sandboxes + summary: CreateEndpointCredential grants short-lived access to one sandbox endpoint. + description: |- + CreateEndpointCredential grants short-lived access to one sandbox endpoint. + Issuance checks current authority and never stores a token in the replay ledger. + operationId: createEndpointCredential + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + enum: + - sandboxesExec + - sandboxesFilesRead + - sandboxesFilesWrite + minItems: 1 + uniqueItems: true + description: "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite." + ttl: + description: ttl defaults to five minutes; supplied durations are clamped to one second through five minutes. + $ref: "#/components/schemas/Duration" + title: CreateEndpointCredentialRequest + required: + - permissions + additionalProperties: false + description: CreateEndpointCredentialRequest requests only endpoint permissions the caller holds. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/EndpointCredential" + headers: + Cache-Control: + required: true + schema: + type: string + const: no-store + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesCredential + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/mcp-gateway: + get: + tags: + - MCP gateways + summary: GetMcpGateway reads gateway state for the sandbox. + description: GetMcpGateway reads gateway state for the sandbox. + operationId: getMcpGateway + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/McpGateway" + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - mcpRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/mcp-gateway/servers: + post: + tags: + - MCP gateways + summary: AddMcpGatewayServer adds one server to an existing ready gateway. + description: AddMcpGatewayServer adds one server to an existing ready gateway. + operationId: addMcpGatewayServer + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + server: + type: string + minLength: 1 + description: |- + server is the external configured key; a supplied registration must define this same key. + A mismatch refuses FAILED_PRECONDITION before changing the gateway. + title: AddMcpGatewayServerRequest + required: + - server + additionalProperties: false + description: AddMcpGatewayServerRequest adds one server to an existing ready gateway. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/AddMcpGatewayServerResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - mcpWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/network-policies: + get: + tags: + - Network policies + summary: GetNetworkPolicies returns effective and exact views of the same installed generation. + description: GetNetworkPolicies returns effective and exact views of the same installed generation. + operationId: getNetworkPolicies + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: acceptedSelectorVersions + in: query + description: Omitted versions accept only destination.v1; an unsupported representation fails closed. + schema: + type: array + items: + type: string + minLength: 1 + description: "" + title: accepted_selector_versions + maxItems: 8 + uniqueItems: true + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/GetNetworkPoliciesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - networkPoliciesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/policy-logs: + get: + tags: + - Network policies + summary: ListPolicyLogEntries lists observed policy decisions. + description: ListPolicyLogEntries lists observed policy decisions. + operationId: listPolicyLogEntries + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable field is + domain. + schema: + type: string + title: filter + required: false + - name: since + in: query + description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. + schema: + type: string + examples: + - 2023-01-15T01:30:15.01Z + - 2024-12-25T12:00:00Z + format: date-time + required: false + - name: until + in: query + description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. + schema: + type: string + examples: + - 2023-01-15T01:30:15.01Z + - 2024-12-25T12:00:00Z + format: date-time + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListPolicyLogEntriesResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - networkPoliciesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/ports: + get: + tags: + - Sandboxes + summary: ListPorts lists currently published ports for one sandbox. + description: ListPorts lists currently published ports for one sandbox. + operationId: listPorts + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListPortsResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Sandboxes + summary: CreatePort makes one sandbox port reachable outside the sandbox. + description: CreatePort makes one sandbox port reachable outside the sandbox. + operationId: createPort + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + requestBody: + content: + application/json: + schema: + type: object + properties: + port: + description: port is the requested publication. + $ref: "#/components/schemas/CreatePortRequestPortInput" + title: CreatePortRequest + required: + - port + additionalProperties: false + description: CreatePortRequest publishes one sandbox port. + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Port" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The sandbox already publishes this port number. + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + alreadyExists: + summary: The sandbox already publishes this port number. + value: + code: alreadyExists + message: The sandbox already publishes this port number. + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: ALREADY_EXISTS + description: The sandbox already publishes this port number. + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesPorts + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/ports/{port}: + get: + tags: + - Sandboxes + summary: GetPort reads one published port by its resource name. + description: GetPort reads one published port by its resource name. + operationId: getPort + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: port + in: path + description: The port id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Port" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: No publication exists for this port resource name. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: No publication exists for this port resource name. + value: + code: notFound + message: No publication exists for this port resource name. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: No publication exists for this port resource name. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Sandboxes + summary: DeletePort withdraws one published port. + description: |- + DeletePort withdraws one published port. A name that is not published + succeeds, so a retried delete reports the same result as the first. + operationId: deletePort + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: port + in: path + description: The port id. + required: true + schema: + type: string + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: etag identifies the publication version the caller intends to delete. + responses: + "204": + description: Success. The response carries no body. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesPorts + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/renew-timeout: + post: + tags: + - Sandboxes + summary: RenewSandboxTimeout sets a TTL when timeout renewal is supported. + description: |- + RenewSandboxTimeout sets a TTL when timeout renewal is supported. The TTL starts at acceptance, and the response returns the new expires_at with the sandbox's timeout configuration preserved. + Action: the TTL restarts at acceptance, so the result is not a value the caller could + PUT. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: renewSandboxTimeout + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + timeout: + description: timeout is the new TTL relative to server acceptance time. + $ref: "#/components/schemas/Duration" + title: RenewSandboxTimeoutRequest + required: + - timeout + additionalProperties: false + description: RenewSandboxTimeoutRequest sets a new remaining TTL. + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesLifecycle + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/snapshots: + post: + tags: + - Snapshots + summary: CreateSnapshot checkpoints a running sandbox; a stopped source is rejected. + description: CreateSnapshot checkpoints a running sandbox; a stopped source is rejected. + operationId: createSnapshot + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + requestBody: + content: + application/json: + schema: + type: object + properties: + displayName: + type: string + not: + type: string + enum: + - . + - .. + minLength: 1 + pattern: ^[^/]+$ + description: display_name is a scoped label; the backend assigns the immutable resource ID. + description: + type: string + description: description is caller-supplied text. + captureMode: + description: |- + capture_mode selects disk-only or memory plus disk capture. A value this + enum does not define is rejected, never coerced to a capture. + $ref: "#/components/schemas/CaptureMode" + title: CreateSnapshotRequest + required: + - displayName + additionalProperties: false + description: CreateSnapshotRequest captures one running sandbox. + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Snapshot" + - not: + properties: + status: + enum: + - creating + required: + - status + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Snapshot" + - properties: + status: + enum: + - creating + required: + - status + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - snapshotsWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Snapshot" + /v1/sandboxes/{sandbox}/ssh-certificates: + post: + tags: + - Sandboxes + summary: IssueSSHCert signs a caller-held public key for sandbox SSH access. + description: |- + IssueSSHCert signs a caller-held public key for sandbox SSH access. + A create: each call mints one certificate under the sandbox's certificate collection. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: issueSSHCert + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + publicKey: + type: string + minLength: 1 + description: public_key is the caller-held SSH public key. + ttl: + description: ttl is the requested certificate lifetime. + $ref: "#/components/schemas/Duration" + title: IssueSSHCertRequest + required: + - publicKey + additionalProperties: false + description: IssueSSHCertRequest asks the backend to sign a caller-held public key. + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/IssueSSHCertResponse" + headers: + Cache-Control: + required: true + schema: + type: string + const: no-store + "409": + description: Creation conflicts with an existing resource (ALREADY_EXISTS). + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + headers: + Cache-Control: + required: true + schema: + type: string + enum: + - no-store + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesSsh + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/sandboxes/{sandbox}/start: + post: + tags: + - Sandboxes + summary: StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. + description: |- + StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. + Action: a lifecycle transition is not a representation a caller can PUT. + operationId: startSandbox + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + requestBody: + content: + application/json: + schema: + type: object + properties: {} + title: StartSandboxRequest + additionalProperties: false + description: StartSandboxRequest starts or resumes a sandbox. + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - not: + properties: + core: + properties: + status: + enum: + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - properties: + core: + properties: + status: + enum: + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesLifecycle + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Sandbox" + /v1/sandboxes/{sandbox}/stop: + post: + tags: + - Sandboxes + summary: StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it. + description: |- + StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it. + Action: a lifecycle transition is not a representation a caller can PUT. + operationId: stopSandbox + parameters: + - name: sandbox + in: path + description: The sandbox id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + requestBody: + content: + application/json: + schema: + type: object + properties: {} + title: StopSandboxRequest + additionalProperties: false + description: StopSandboxRequest stops a sandbox; a backend advertising memory preservation hibernates it. + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - not: + properties: + core: + properties: + status: + enum: + - stopping + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - properties: + core: + properties: + status: + enum: + - stopping + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - sandboxesLifecycle + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Sandbox" + /v1/secrets: + get: + tags: + - Secrets + summary: ListSecrets lists secret metadata in the caller's owner scope. + description: |- + ListSecrets lists secret metadata in the caller's owner scope. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: listSecrets + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + name, display_name and uid. + schema: + type: string + title: filter + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable fields are + created_at and name. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListSecretsResponse" + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - secretsRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Secrets + summary: CreateSecret stores new secret material. + description: |- + CreateSecret stores new secret material. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: createSecret + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateSecretRequest" + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Secret" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - secretsWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + parameters: + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + /v1/secrets/{secret}: + get: + tags: + - Secrets + summary: GetSecret reads one secret's metadata; material is never returned. + description: |- + GetSecret reads one secret's metadata; material is never returned. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: getSecret + parameters: + - name: secret + in: path + description: The secret id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Secret" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - secretsRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + put: + tags: + - Secrets + summary: UpdateSecret replaces secret metadata and material. + description: |- + UpdateSecret replaces secret metadata and material. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: updateSecret + parameters: + - name: secret + in: path + description: The secret id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateSecretBody" + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Secret" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - secretsWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Secrets + summary: DeleteSecret deletes a secret; deleting an already absent secret succeeds. + description: |- + DeleteSecret deletes a secret; deleting an already absent secret succeeds. + Its response carries the credential fence receipt, so it answers 200 with a + body rather than the 204 an empty-response delete declares. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: deleteSecret + parameters: + - name: secret + in: path + description: The secret id. + required: true + schema: + type: string + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteSecretResponse" + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - secretsWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/snapshots: + get: + tags: + - Snapshots + summary: ListSnapshots lists snapshots in the caller's owner scope. + description: ListSnapshots lists snapshots in the caller's owner scope. + operationId: listSnapshots + parameters: + - name: sandbox + in: query + description: (OPTIONAL) sandbox is the complete resource name, in the form sandboxes/{sandbox}. + required: false + schema: + type: string + title: sandbox + pattern: ^(?:sandboxes/[^/]+)?$ + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + name, display_name and uid. + schema: + type: string + title: filter + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable fields are + created_at and name. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListSnapshotsResponse" + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - snapshotsRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/snapshots/{snapshot}: + get: + tags: + - Snapshots + summary: GetSnapshot reads one snapshot by its resource name. + description: GetSnapshot reads one snapshot by its resource name. + operationId: getSnapshot + parameters: + - name: snapshot + in: path + description: The snapshot id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Snapshot" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - snapshotsRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Snapshots + summary: DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds. + description: DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds. + operationId: deleteSnapshot + parameters: + - name: snapshot + in: path + description: The snapshot id. + required: true + schema: + type: string + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + responses: + "204": + description: Success. The response carries no body. + "409": + description: |- + The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + + An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + deletion_preparation_incomplete: + summary: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + value: + code: failedPrecondition + message: "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + deletion_content_lease_held: + summary: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + value: + code: failedPrecondition + message: "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. + reason: deletion_preparation_incomplete + - code: FAILED_PRECONDITION + description: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. + reason: deletion_content_lease_held + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - snapshotsWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + /v1/snapshots/{snapshot}/restore: + post: + tags: + - Snapshots + summary: RestoreSnapshot forks a new sandbox from a snapshot. + description: |- + RestoreSnapshot forks a new sandbox from a snapshot. + Action: a restore creates a sandbox, so the snapshot in the path is the source and not + the created resource. + operationId: restoreSnapshot + parameters: + - name: snapshot + in: path + description: The snapshot id. + required: true + schema: + type: string + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + requestBody: + content: + application/json: + schema: + type: object + properties: + displayName: + type: string + maxLength: 64 + pattern: ^[a-zA-Z0-9_-]*$ + description: (OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID. + title: RestoreSnapshotRequest + additionalProperties: false + description: RestoreSnapshotRequest creates a new sandbox from one snapshot. + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - not: + properties: + core: + properties: + status: + enum: + - creating + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "202": + description: Accepted. The resource is still progressing; read it or follow its events until completion. + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Sandbox" + - properties: + core: + properties: + status: + enum: + - creating + - starting + required: + - status + required: + - core + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - snapshotsRead + - sandboxesCreate + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + x-sbx-resource-response: + $ref: "#/components/schemas/Sandbox" + /v1/volumes: + get: + tags: + - Volumes + summary: ListVolumes lists volumes in the caller's owner scope. + description: |- + ListVolumes lists volumes in the caller's owner scope. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: listVolumes + parameters: + - name: pageSize + in: query + description: |- + page_size is an optional page size. + + Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. + schema: + type: integer + title: page_size + required: false + - name: pageToken + in: query + description: page_token is an opaque continuation token. + schema: + type: string + title: page_token + required: false + - name: filter + in: query + description: |- + filter is comma-separated exact-match field=value terms; the portable fields are + name, display_name and uid. + schema: + type: string + title: filter + required: false + - name: orderBy + in: query + description: |- + order_by is a single order field with optional direction; the portable fields are + created_at and name. + schema: + type: string + title: order_by + required: false + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ListVolumesResponse" + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - volumesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + post: + tags: + - Volumes + summary: CreateVolume creates a persistent volume. + description: |- + CreateVolume creates a persistent volume. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: createVolume + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVolumeRequest" + required: true + responses: + "201": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Volume" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "409": + description: |- + Creation conflicts with an existing resource (ALREADY_EXISTS). + + The Idempotency-Key was already used with a different payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + failedPrecondition: + summary: The Idempotency-Key was already used with a different payload. + value: + code: failedPrecondition + message: The Idempotency-Key was already used with a different payload. + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + - code: FAILED_PRECONDITION + description: The Idempotency-Key was already used with a different payload. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - volumesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + parameters: + - name: Idempotency-Key + in: header + description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. + schema: + type: string + title: Idempotency-Key + description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. + /v1/volumes/{volume}: + get: + tags: + - Volumes + summary: GetVolume reads one volume by its resource name. + description: |- + GetVolume reads one volume by its resource name. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: getVolume + parameters: + - name: volume + in: path + description: The volume id. + required: true + schema: + type: string + - name: If-None-Match + in: header + description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. + schema: + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Volume" + headers: + ETag: + description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. + schema: + type: string + "304": + description: The resource's etag equals the If-None-Match value, so this response carries no body. + "404": + description: The target is absent or not visible within the caller's scope. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + notFound: + summary: The target is absent or not visible within the caller's scope. + value: + code: notFound + message: The target is absent or not visible within the caller's scope. + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: NOT_FOUND + description: The target is absent or not visible within the caller's scope. + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - volumesRead + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false + delete: + tags: + - Volumes + summary: DeleteVolume deletes a volume; deleting an already absent volume succeeds. + description: |- + DeleteVolume deletes a volume; deleting an already absent volume succeeds. + + Returns unimplemented when this operation is unavailable. Support does not grant permission. + operationId: deleteVolume + parameters: + - name: volume + in: path + description: The volume id. + required: true + schema: + type: string + - name: If-Match + in: header + description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." + required: true + schema: + type: string + title: If-Match + description: |- + etag is the required precondition, the value the target's last read returned. + An absent one refuses etag_required and a stale one etag_mismatch. + responses: + "204": + description: Success. The response carries no body. + "412": + description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_mismatch: + summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. + value: + code: failedPrecondition + message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + details: + - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch + currentEtag: v2 + "428": + description: No precondition was sent. The body carries failedPrecondition naming etag_required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + etag_required: + summary: No precondition was sent. The body carries failedPrecondition naming etag_required. + value: + code: failedPrecondition + message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + "501": + description: This operation is not available on this service. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + unimplemented: + summary: This operation is not available on this service. + value: + code: unimplemented + message: This operation is not available on this service. + default: + description: The structured Error body identifies the failure with a stable code and optional typed details. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-sbx-error-responses: + - code: UNIMPLEMENTED + description: This operation is not available on this service. + security: + - bearer: [] + x-sbx-serving-surface: management + x-sbx-plane: control + x-sbx-required-permissions: + - volumesWrite + x-sbx-conditional-permissions: [] + x-sbx-authenticated-only: false +components: + schemas: + Error: + type: object + title: Error + required: + - code + description: An HTTP refusal, resource failure, or terminal stream error. Clients preserve unknown codes and structured details. + properties: + code: + anyOf: + - $ref: "#/components/schemas/ErrorCode" + - type: string + message: + type: string + details: + type: array + items: + $ref: "#/components/schemas/ErrorDetail" + examples: + - code: notFound + details: [] + message: sandbox not found + ErrorCode: + type: string + enum: + - canceled + - unknown + - invalidArgument + - deadlineExceeded + - notFound + - alreadyExists + - permissionDenied + - resourceExhausted + - failedPrecondition + - aborted + - outOfRange + - unimplemented + - internal + - unavailable + - dataLoss + - unauthenticated + description: Known public failure categories. Error.code also accepts future strings. + ErrorDetail: + oneOf: + - $ref: "#/components/schemas/BadRequestErrorDetail" + - $ref: "#/components/schemas/DebugInfoErrorDetail" + - $ref: "#/components/schemas/ErrorInfoErrorDetail" + - $ref: "#/components/schemas/HelpErrorDetail" + - $ref: "#/components/schemas/LocalizedMessageErrorDetail" + - $ref: "#/components/schemas/PreconditionFailureErrorDetail" + - $ref: "#/components/schemas/QuotaFailureErrorDetail" + - $ref: "#/components/schemas/RequestInfoErrorDetail" + - $ref: "#/components/schemas/ResourceInfoErrorDetail" + - $ref: "#/components/schemas/RetryInfoErrorDetail" + - $ref: "#/components/schemas/ValidationViolationsErrorDetail" + - $ref: "#/components/schemas/EtagMismatchErrorDetail" + - $ref: "#/components/schemas/KitFieldOutcomeReportErrorDetail" + - $ref: "#/components/schemas/McpConfigurationReportErrorDetail" + - $ref: "#/components/schemas/UnknownErrorDetail" + discriminator: + propertyName: "@type" + mapping: + type.googleapis.com/google.rpc.BadRequest: "#/components/schemas/BadRequestErrorDetail" + type.googleapis.com/google.rpc.DebugInfo: "#/components/schemas/DebugInfoErrorDetail" + type.googleapis.com/google.rpc.ErrorInfo: "#/components/schemas/ErrorInfoErrorDetail" + type.googleapis.com/google.rpc.Help: "#/components/schemas/HelpErrorDetail" + type.googleapis.com/google.rpc.LocalizedMessage: "#/components/schemas/LocalizedMessageErrorDetail" + type.googleapis.com/google.rpc.PreconditionFailure: "#/components/schemas/PreconditionFailureErrorDetail" + type.googleapis.com/google.rpc.QuotaFailure: "#/components/schemas/QuotaFailureErrorDetail" + type.googleapis.com/google.rpc.RequestInfo: "#/components/schemas/RequestInfoErrorDetail" + type.googleapis.com/google.rpc.ResourceInfo: "#/components/schemas/ResourceInfoErrorDetail" + type.googleapis.com/google.rpc.RetryInfo: "#/components/schemas/RetryInfoErrorDetail" + type.googleapis.com/buf.validate.Violations: "#/components/schemas/ValidationViolationsErrorDetail" + type.googleapis.com/docker.sandboxes.v1.EtagMismatch: "#/components/schemas/EtagMismatchErrorDetail" + type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport: "#/components/schemas/KitFieldOutcomeReportErrorDetail" + type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport: "#/components/schemas/McpConfigurationReportErrorDetail" + UnknownErrorDetail: + type: object + required: + - "@type" + additionalProperties: true + description: A structured error detail identified by @type. Its decoded JSON fields appear beside the type URL. + properties: + "@type": + type: string + not: + enum: + - type.googleapis.com/google.rpc.BadRequest + - type.googleapis.com/google.rpc.DebugInfo + - type.googleapis.com/google.rpc.ErrorInfo + - type.googleapis.com/google.rpc.Help + - type.googleapis.com/google.rpc.LocalizedMessage + - type.googleapis.com/google.rpc.PreconditionFailure + - type.googleapis.com/google.rpc.QuotaFailure + - type.googleapis.com/google.rpc.RequestInfo + - type.googleapis.com/google.rpc.ResourceInfo + - type.googleapis.com/google.rpc.RetryInfo + - type.googleapis.com/buf.validate.Violations + - type.googleapis.com/docker.sandboxes.v1.EtagMismatch + - type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport + - type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport + ValidationFieldPath: + type: object + properties: + elements: + type: array + items: + $ref: "#/components/schemas/ValidationFieldPathElement" + description: "`elements` contains each element of the path, starting from the root and recursing downward." + title: FieldPath + description: A path to a field, including any parent fields. + ValidationFieldPathElement: + type: object + allOf: + - properties: + fieldNumber: + type: + - integer + - "null" + format: int32 + description: "`field_number` is the field number this path element refers to." + fieldName: + type: + - string + - "null" + description: |- + `field_name` contains the field name this path element refers to. + This can be used to display a human-readable path even if the field number is unknown. + fieldType: + oneOf: + - $ref: "#/components/schemas/ValidationFieldType" + - type: "null" + description: The type of the field that failed validation. + keyType: + oneOf: + - $ref: "#/components/schemas/ValidationFieldType" + - type: "null" + description: |- + `key_type` specifies the map key type of this field. This value is useful when traversing + unknown fields through wire data: specifically, it allows handling the differences between + different integer encodings. + valueType: + oneOf: + - $ref: "#/components/schemas/ValidationFieldType" + - type: "null" + description: |- + `value_type` specifies map value type of this field. This is useful if you want to display a + value inside unknown fields through wire data. + - oneOf: + - type: object + properties: + boolKey: + type: boolean + description: "`bool_key` specifies a map key of type bool." + title: bool_key + required: + - boolKey + - type: object + properties: + index: + type: + - integer + - string + format: int64 + description: "`index` specifies a 0-based index into a repeated field." + title: index + required: + - index + - type: object + properties: + intKey: + type: + - integer + - string + format: int64 + description: "`int_key` specifies a map key of type int32, int64, sint32, sint64, sfixed32 or sfixed64." + title: int_key + required: + - intKey + - type: object + properties: + stringKey: + type: string + description: "`string_key` specifies a map key of type string." + title: string_key + required: + - stringKey + - type: object + properties: + uintKey: + type: + - integer + - string + format: int64 + description: "`uint_key` specifies a map key of type uint32, uint64, fixed32 or fixed64." + title: uint_key + required: + - uintKey + title: FieldPathElement + description: One field in a validation path. For a map or list, the subscript identifies the selected element. + ValidationViolation: + type: object + properties: + field: + oneOf: + - $ref: "#/components/schemas/ValidationFieldPath" + - type: "null" + description: The field that failed validation, including its parent fields. + rule: + oneOf: + - $ref: "#/components/schemas/ValidationFieldPath" + - type: "null" + description: The validation rule that failed. + ruleId: + type: + - string + - "null" + description: |- + `rule_id` is the unique identifier of the `Rule` that was not fulfilled. + This is the same `id` that was specified in the `Rule` message, allowing easy tracing of which rule was violated. + message: + type: + - string + - "null" + description: |- + `message` is a human-readable error message that describes the nature of the violation. + This can be the default error message from the violated `Rule`, or it can be a custom message that gives more context about the violation. + forKey: + type: + - boolean + - "null" + description: "`for_key` indicates whether the violation was caused by a map key, rather than a value." + title: Violation + description: A validation failure, with the affected field, rule, and a human-readable message. + ValidationViolations: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/ValidationViolation" + description: "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected." + title: Violations + description: The validation failures returned for a request. + ValidationViolationsErrorDetail: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/ValidationViolation" + description: "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected." + "@type": + type: string + const: type.googleapis.com/buf.validate.Violations + title: ViolationsErrorDetail + description: The validation failures returned for a request. + required: + - "@type" + AppliedKit: + type: object + properties: + ref: + type: string + description: ref is the kit reference supplied or resolved by the backend. + kind: + type: string + enum: + - sandbox + - mixin + description: kind is normalized to "sandbox" or "mixin". + appliedAt: + description: applied_at is when the kit became active. + $ref: "#/components/schemas/Timestamp" + digest: + type: string + description: digest identifies the exact applied content. + title: AppliedKit + required: + - kind + description: AppliedKit records kit content that was applied to a sandbox. + EndpointAuthentication: + type: object + properties: + scheme: + not: + enum: + - unspecified + $ref: "#/components/schemas/EndpointAuthenticationScheme" + defaultTtl: + description: default_ttl and max_ttl describe CreateEndpointCredential's provider policy. + $ref: "#/components/schemas/Duration" + maxTtl: + $ref: "#/components/schemas/Duration" + credentialTransports: + type: array + items: + $ref: "#/components/schemas/EndpointCredentialTransport" + uniqueItems: true + description: Omission retains Authorization-header clients; browsers require an explicit subprotocol offer. + title: EndpointAuthentication + required: + - scheme + description: |- + EndpointAuthentication describes credential issuance without publishing a token. + local sockets cannot advertise bearer credential transports + scoped bearer discovery states the five-minute credential lifetime; local sockets carry no token lifetime + dependentSchemas: + scheme: + allOf: + - oneOf: + - required: + - defaultTtl + - maxTtl + properties: + scheme: + const: scopedBearer + defaultTtl: + pattern: ^300([.]0{1,9})?s$ + maxTtl: + pattern: ^300([.]0{1,9})?s$ + - properties: + scheme: + const: localSocket + not: + anyOf: + - required: + - defaultTtl + - required: + - maxTtl + credentialTransports: + allOf: + - if: + properties: + scheme: + const: localSocket + then: + properties: + credentialTransports: + maxItems: 0 + EndpointAuthenticationScheme: + type: string + title: EndpointAuthenticationScheme + enum: + - unspecified + - scopedBearer + - localSocket + description: |- + Values: + unspecified + scopedBearer + localSocket + EndpointCredentialTransport: + type: string + title: EndpointCredentialTransport + enum: + - unspecified + - authorizationHeader + - webSocketSubprotocol + description: |- + Values: + unspecified + authorizationHeader + webSocketSubprotocol + KitRef: + type: object + properties: + ref: + type: string + minLength: 1 + description: ref names the kit source. + kind: + type: string + enum: + - "" + - sandbox + - mixin + description: kind is "sandbox", "mixin", or empty to defer to the kit's own manifest. + title: KitRef + required: + - ref + additionalProperties: false + description: KitRef names a kit to apply. + Permission: + type: string + title: Permission + enum: + - unspecified + - sandboxesRead + - sandboxesCreate + - sandboxesExec + - sandboxesFilesRead + - sandboxesFilesWrite + - imagesPull + - secretsWrite + - sandboxesDelete + - sandboxesLifecycle + - sandboxesKits + - sandboxesPorts + - sandboxesCredential + - sandboxesSsh + - imagesRead + - imagesWrite + - secretsRead + - networkPoliciesRead + - volumesRead + - volumesWrite + - snapshotsRead + - snapshotsWrite + - mcpRead + - mcpWrite + - credentialsExchange + - sandboxesRename + - secretsResolve + - operator + description: The actions a credential is allowed to perform. Each operation declares its required permissions; service support does not grant permission. + Platform: + type: object + properties: + os: + type: string + description: os is the operating system, for example "linux". + architecture: + type: string + description: architecture is the CPU architecture, for example "amd64" or "arm64". + title: Platform + additionalProperties: false + description: Platform is the OCI platform tuple. + Protocol: + type: string + title: Protocol + enum: + - unspecified + - tcp + - udp + - tcp4 + - tcp6 + - udp4 + - udp6 + description: |- + Protocol names the transport protocol for a published port. + + Values: + unspecified: unspecified means the backend default, TCP. + tcp: tcp publishes TCP traffic. + udp: udp publishes UDP traffic. + tcp4: tcp4 publishes IPv4 TCP traffic. + tcp6: tcp6 publishes IPv6 TCP traffic. + udp4: udp4 publishes IPv4 UDP traffic. + udp6: udp6 publishes IPv6 UDP traffic. + PublishedPort: + type: object + properties: + hostIp: + type: string + description: host_ip is the local host bind address when relevant. + hostPort: + type: integer + description: host_port is the local host port when relevant. + sandboxPort: + type: integer + description: sandbox_port is the port inside the sandbox. + protocol: + description: protocol is the published protocol. + $ref: "#/components/schemas/Protocol" + url: + type: string + description: url is the required externally reachable address, including host-local addresses. + title: PublishedPort + description: PublishedPort reports external reachability for one sandbox port. + Resources: + type: object + properties: + cpus: + type: + - integer + - "null" + description: cpus is present only when the caller or backend chooses a CPU count. + memoryMib: + type: + - integer + - string + - "null" + format: int64 + description: memory_mib is present only when the caller or backend chooses memory. + title: Resources + additionalProperties: false + description: Resources describes sandbox CPU and memory allocation. + SandboxCore: + type: object + allOf: + - properties: + agent: + type: string + description: agent is the named agent profile, empty for raw image/start-command sandboxes. + status: + not: + enum: + - unspecified + description: status is the coarse lifecycle state. + readOnly: true + $ref: "#/components/schemas/SandboxStatus" + resources: + description: resources are the sandbox resources. + $ref: "#/components/schemas/Resources" + platform: + description: platform is the canonical placed platform. + $ref: "#/components/schemas/Platform" + environment: + type: object + additionalProperties: + type: string + title: value + description: environment is non-secret environment metadata. + ports: + type: array + items: + $ref: "#/components/schemas/PublishedPort" + description: ports are the currently published ports. + appliedKits: + type: array + items: + $ref: "#/components/schemas/AppliedKit" + description: applied_kits records kits active in the sandbox. + createdAt: + description: created_at is the creation time. + $ref: "#/components/schemas/Timestamp" + endpoint: + description: endpoint is where process and file services are served for this sandbox. + $ref: "#/components/schemas/SandboxEndpoint" + origin: + type: string + description: origin is set by merged views to identify the backend that owns this sandbox. + labels: + type: object + additionalProperties: + type: string + title: value + description: labels are non-secret caller-assigned key/value metadata. + etag: + type: string + minLength: 1 + pattern: ^"[^"\x00-\x20\x7f]*"$ + description: |- + etag identifies the observed version of this resource. It is opaque and strong, + changes on every visible change, and is what a mutation sends as its precondition. + readOnly: true + - properties: + image: + type: string + pattern: ^images/[^/]+$ + description: image is the managed Image resource name. + imageRef: + type: string + description: image_ref is an external OCI reference, with the existing backend validation. + dependentSchemas: + image: + not: + anyOf: + - required: + - imageRef + imageRef: + not: + anyOf: + - required: + - image + title: SandboxCore + required: + - status + - createdAt + - etag + description: SandboxCore is the backend-neutral sandbox view. At most one of image, imageRef is set. + SandboxEndpoint: + type: object + properties: + uri: + type: string + description: uri is the endpoint API base; preserve its path prefix when appending /v1 routes. + protocol: + description: protocol identifies the endpoint transport. + $ref: "#/components/schemas/SandboxEndpointProtocol" + credentialAudience: + type: string + description: credential_audience is server-controlled and required for network endpoints. + sandbox: + type: string + pattern: ^sandboxes/[^/]+$ + description: sandbox names the immutable sandbox incarnation served by this endpoint. + sandboxUid: + type: + - string + minLength: 1 + readOnly: true + apiVersion: + type: string + description: api_version identifies the /v1 endpoint contract before the client connects. + const: v1 + capabilities: + type: array + items: + type: string + pattern: ^[a-z][A-Za-z0-9]*$ + minItems: 1 + uniqueItems: true + description: capabilities lists supported public operation IDs, independently of caller grants. + authentication: + $ref: "#/components/schemas/EndpointAuthentication" + title: SandboxEndpoint + required: + - sandbox + - sandboxUid + - apiVersion + - capabilities + - authentication + description: |- + SandboxEndpoint tells a client where sandbox endpoint services are served. + network endpoints require scoped credentials; Unix sockets use actual socket access controls + sandbox must contain the endpoint's immutable sandbox UID + dependentSchemas: + authentication: + allOf: + - required: + - protocol + oneOf: + - required: + - credentialAudience + properties: + protocol: + const: http + credentialAudience: + minLength: 1 + authentication: + properties: + scheme: + const: scopedBearer + - properties: + protocol: + const: unixSocket + credentialAudience: + const: "" + authentication: + properties: + scheme: + const: localSocket + SandboxEndpointProtocol: + type: string + title: SandboxEndpointProtocol + enum: + - unspecified + - http + - unixSocket + description: |- + SandboxEndpointProtocol identifies the transport used by a sandbox endpoint. + + Values: + unspecified: unspecified is not a concrete endpoint protocol. + http: http is the REST API over HTTP. + unixSocket: unixSocket is a local unix socket. + SandboxStatus: + type: string + title: SandboxStatus + enum: + - unspecified + - creating + - starting + - running + - stopping + - stopped + - failed + - deleting + - degraded + description: |- + SandboxStatus is the backend-neutral lifecycle state. + + Values: + unspecified: unspecified is never a concrete known state. + creating: creating means provisioning has not completed. + starting: starting means a stopped sandbox is starting or resuming. + running: running means the sandbox is running. + stopping: stopping means the sandbox is stopping or hibernating. + stopped: stopped means the sandbox is not running and may be started. + failed: failed means the sandbox reached an unrecoverable failure. + deleting: deleting means deletion is accepted; reads continue until removal. + degraded: degraded means runtime contact is lost; recovery or failure may follow. + EffectiveCoreLifecycle: + type: object + properties: + stopMemoryOutcome: + not: + enum: + - unspecified + description: stop_memory_outcome is the selected stop/start guarantee for this sandbox. + $ref: "#/components/schemas/StopMemoryOutcome" + canCaptureMemory: + type: boolean + description: can_capture_memory is this sandbox's ALL snapshot support, independently set. + autoResume: + type: + - boolean + - "null" + description: |- + auto_resume is the configured authenticated auto-resume setting; absent means unknown. + Snapshot readback preserves the capture-time value, not current support or a resume guarantee. + title: EffectiveCoreLifecycle + required: + - stopMemoryOutcome + description: EffectiveCoreLifecycle is persisted at admission and cannot silently degrade. + EffectiveFeatures: + type: object + properties: + lifecycle: + description: lifecycle is required even when no optional feature is selected. + $ref: "#/components/schemas/EffectiveCoreLifecycle" + outputRetention: + description: output_retention is the persisted per-process reconnect guarantee. + $ref: "#/components/schemas/OutputRetention" + managedVolumes: + description: managed_volumes records stable volume identities and concrete attachment modes. + $ref: "#/components/schemas/EffectiveManagedVolumes" + timeouts: + description: timeouts records frozen defaults and the currently armed deadline, if any. + $ref: "#/components/schemas/EffectiveTimeouts" + title: EffectiveFeatures + required: + - lifecycle + - outputRetention + description: EffectiveFeatures is emitted only through the composition representation. + FeatureOptions: + type: object + properties: + managedVolumes: + description: managed_volumes selects persistent resources and guest targets. + $ref: "#/components/schemas/ManagedVolumeOptions" + timeouts: + description: timeouts enables an explicit deadline; omission enables none. + $ref: "#/components/schemas/TimeoutOptions" + storedSecrets: + description: stored_secrets selects authorized stored references, never raw material. + $ref: "#/components/schemas/StoredSecretOptions" + title: FeatureOptions + additionalProperties: false + description: FeatureOptions carries typed admission intent; unknown fields are refused. + OutputRetention: + type: object + properties: + minDuration: + description: min_duration retains each process's output for at least this age when set. + $ref: "#/components/schemas/Duration" + minBytes: + type: + - integer + - string + format: int64 + description: |- + min_bytes retains at least this many recent bytes per process when nonzero. + a byte retention floor must be zero or at least 64 KiB + title: OutputRetention + description: |- + OutputRetention records minimum reconnect coverage independently of location. + output retention requires a duration or byte floor + StopMemoryOutcome: + type: string + title: StopMemoryOutcome + enum: + - unspecified + - discard + - preserve + description: |- + StopMemoryOutcome records the stop/start guarantee independently of location. + + Values: + unspecified: unspecified is not an advertised or accepted guarantee. + discard: discard retains disk and starts a fresh process tree. + preserve: preserve restores the stopped process tree on start. + FilesDownloadRequest: + type: object + properties: + paths: + type: array + items: + type: string + minItems: 1 + description: |- + paths naming stable regular files or absent entries at canonical absolute paths + yield contiguous results in request order, including duplicates. + title: DownloadRequest + required: + - paths + additionalProperties: false + description: DownloadRequest asks for one or more paths. + FilesDownloadResponse: + type: object + title: DownloadResponse + unevaluatedProperties: false + description: DownloadResponse is one frame in a download stream. At most one of data, error, header is set. + properties: + data: + type: string + format: byte + description: data carries bytes for the current file. + error: + description: error reports a path-level failure without aborting the whole stream. + $ref: "#/components/schemas/FileError" + header: + description: header starts a downloaded file. + $ref: "#/components/schemas/FileHeader" + dependentSchemas: + data: + not: + anyOf: + - required: + - error + - required: + - header + error: + not: + anyOf: + - required: + - data + - required: + - header + header: + not: + anyOf: + - required: + - data + - required: + - error + FileError: + type: object + properties: + path: + type: string + description: path is the path that failed. + failure: + description: failure retains the shared typed code and details for this path. + $ref: "#/components/schemas/Error" + title: FileError + required: + - failure + description: FileError reports a path-level file error. + FileHeader: + type: object + properties: + path: + type: string + minLength: 1 + description: path is the sandbox path. + mode: + type: integer + description: |- + mode carries Unix permission bits. Upload applies mode & 0777, or 0644 when + that value is zero, without subtracting umask; Download reports stored bits. + title: FileHeader + required: + - path + additionalProperties: false + description: FileHeader starts a file in an upload or download stream. + FileInfo: + type: object + properties: + path: + type: string + description: path is the sandbox path. + size: + type: + - integer + - string + format: int64 + description: size is the file size in bytes. + mode: + type: integer + description: mode is the stored Unix permission bits (0777), without type or special bits. + isDir: + type: boolean + description: |- + is_dir reports whether the path is a directory and stays populated on + every backend and every caller. type is the richer authority, and + type == directory iff is_dir. + type: + description: |- + type classifies the object, and Stat and List populate it for every + caller. Stat and List resolve an in-jail symlink and report + the resolved target's type; a link that cannot be resolved in-jail + (dangling, looping, or escaping) reports symlink for itself + rather than disclosing an out-of-jail target. + $ref: "#/components/schemas/FileType" + linkTarget: + type: string + description: |- + link_target is the literal readlink() text when type is symlink, + since that is the only case where nothing else lets the caller learn what + the link names; empty otherwise. + title: FileInfo + description: FileInfo is file metadata. + FileType: + type: string + title: FileType + enum: + - unspecified + - regular + - directory + - symlink + - other + description: |- + FileType classifies the object at a path. + + Values: + unspecified: unspecified means the backend has not classified the object. Stat and List always classify it. + regular: regular is a regular file. + directory: directory is a directory. + symlink: symlink is a symbolic link that could not be resolved to a target inside the jail. + other: other is a socket, FIFO, device, or other non-regular, non-directory, non-symlink object. + FilesListResponse: + type: object + properties: + entries: + type: array + items: + $ref: "#/components/schemas/FileInfo" + description: entries is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListResponse + description: ListResponse returns directory entries and a next-page token. + FilesMkdirRequest: + type: object + properties: + path: + type: string + minLength: 1 + description: path is the directory path. + mode: + type: integer + description: |- + mode supplies the new leaf's Unix permission bits: mode & 0777, or 0755 + when that value is zero, without subtracting umask. + parents: + type: boolean + description: parents creates missing parents when true. + title: MkdirRequest + required: + - path + additionalProperties: false + description: MkdirRequest creates a directory. + FilesMkdirResponse: + type: object + title: MkdirResponse + description: MkdirResponse has no fields. + FilesMoveRequest: + type: object + properties: + from: + type: string + minLength: 1 + description: from is the source path. + to: + type: string + minLength: 1 + description: to is the exact destination path. + title: MoveRequest + required: + - from + - to + additionalProperties: false + description: MoveRequest moves or renames a path. + FilesMoveResponse: + type: object + title: MoveResponse + description: MoveResponse has no fields. + FilesReadFileRequest: + type: object + properties: + path: + type: string + minLength: 1 + description: path is the sandbox path of a regular file. + title: ReadFileRequest + required: + - path + additionalProperties: false + description: ReadFileRequest names one regular file. + FilesReadFileResponse: + type: object + properties: + info: + description: info remains available to the internal adapter; HTTP clients use Stat for metadata. + $ref: "#/components/schemas/FileInfo" + data: + type: string + format: byte + description: data is the complete content; a file above the message cap is refused. + title: ReadFileResponse + required: + - info + additionalProperties: false + description: ReadFileResponse carries the whole file; HTTP selects data as its raw response body. + FilesRemoveResponse: + type: object + properties: + completedPaths: + type: array + items: + type: string + description: |- + completed_paths lists removed paths in traversal order, bounded to the + first 1000; completed_count carries the + true total when it exceeds that bound. + completedCount: + type: integer + description: |- + completed_count is the total number of paths removed, which may exceed + len(completed_paths). + failedPath: + type: string + description: |- + failed_path is the path where a recursive removal stopped; empty on full + success. Every path in completed_paths was removed before this one. + title: RemoveResponse + description: |- + RemoveResponse reports partial recursive progress to every caller: check failed_path, + not the operation status, when Remove stops partway. Effects are never rolled back. + FilesStatResponse: + type: object + properties: + info: + description: info is metadata for the path. + $ref: "#/components/schemas/FileInfo" + title: StatResponse + description: StatResponse returns file metadata. + FilesUploadRequest: + type: object + oneOf: + - type: object + properties: + data: + type: string + format: byte + description: data appends bytes to the current file. + title: data + required: + - data + - type: object + properties: + header: + description: |- + header starts a new file. The first frame, and the first frame after each + completed file, must be this arm. + $ref: "#/components/schemas/FileHeader" + title: header + required: + - header + title: UploadRequest + unevaluatedProperties: false + description: UploadRequest is one frame in an upload stream. + FilesUploadResponse: + type: object + properties: + filesWritten: + type: integer + description: files_written is the number of files successfully written. + title: UploadResponse + description: UploadResponse reports completed file writes. + FilesWriteFileRequest: + type: object + properties: + header: + description: header names the path and mode, as an Upload header does. + $ref: "#/components/schemas/FileHeader" + data: + type: string + format: byte + description: data is the complete new content; empty writes an empty file. + title: WriteFileRequest + required: + - header + additionalProperties: false + description: WriteFileRequest replaces one file. + FilesWriteFileResponse: + type: object + properties: + info: + description: info is the file's metadata after the write. + $ref: "#/components/schemas/FileInfo" + title: WriteFileResponse + required: + - info + description: WriteFileResponse reports the written file. + AttachmentMode: + type: string + title: AttachmentMode + enum: + - unspecified + - exclusive + description: |- + AttachmentMode fixes attachment ownership independently of backend placement. + + Values: + unspecified: unspecified selects exclusive read-write attachment. + exclusive: exclusive permits one sandbox to attach the volume read-write. + EffectiveManagedVolumes: + type: object + properties: + attachments: + type: array + items: + $ref: "#/components/schemas/EffectiveVolumeAttachment" + minItems: 1 + description: attachments retains admission order and stable volume identities. + title: EffectiveManagedVolumes + required: + - attachments + description: EffectiveManagedVolumes records storage that is not deleted with the sandbox. + EffectiveVolumeAttachment: + type: object + properties: + volume: + type: string + description: volume is the resource name recorded for this reference. + volumeUid: + type: + - string + - "null" + description: volume_uid retains the observed backing incarnation when the backend provides one. + readOnly: true + target: + type: string + minLength: 1 + description: target is the accepted normalized absolute guest path. + mode: + not: + enum: + - unspecified + description: mode is explicit and survives sandbox stop/start and backend restart. + $ref: "#/components/schemas/AttachmentMode" + title: EffectiveVolumeAttachment + required: + - target + - mode + description: EffectiveVolumeAttachment retains the identity, not a reusable name lookup. + ManagedVolumeOptions: + type: object + properties: + attachments: + type: array + items: + $ref: "#/components/schemas/VolumeAttachment" + minItems: 1 + description: attachments cannot repeat a volume identity or overlap another mount target. + title: ManagedVolumeOptions + required: + - attachments + additionalProperties: false + description: ManagedVolumeOptions selects existing volumes; it does not create storage. + VolumeAttachment: + type: object + properties: + volume: + type: string + pattern: ^volumes/[^/]+$ + description: volume is the complete resource name, in the form volumes/{volume}. + target: + type: string + minLength: 1 + description: target is an absolute guest path and cannot overlap another mount target. + mode: + description: mode defaults to exclusive; it never silently enables shared writers. + $ref: "#/components/schemas/AttachmentMode" + title: VolumeAttachment + required: + - volume + - target + additionalProperties: false + description: VolumeAttachment binds an existing owner-scoped volume before guest execution. + StoredSecretOptions: + type: object + properties: + secrets: + type: array + items: + type: string + pattern: ^secrets/[^/]+$ + minItems: 1 + description: secrets are complete Secret resource names resolved once at admission. + title: StoredSecretOptions + required: + - secrets + additionalProperties: false + description: StoredSecretOptions resolves owner-scoped references before the workload can run. + EffectiveTimeouts: + type: object + properties: + onTimeout: + not: + enum: + - unspecified + description: on_timeout remains the accepted disposition through renewal and restart. + $ref: "#/components/schemas/TimeoutAction" + autoResume: + type: boolean + description: auto_resume is explicit; endpoint authorization still precedes any wake-up. + initialTimeout: + description: Records the accepted initial TTL, not the recurring interval for RESTART or KEEP. + $ref: "#/components/schemas/Duration" + expiresAt: + description: expires_at is present only while a deadline is armed, not before first readiness or while stopped. + $ref: "#/components/schemas/Timestamp" + resumeTimeout: + description: Freezes the action's default for later starts; RESTART and KEEP manage their own interval. + $ref: "#/components/schemas/Duration" + title: EffectiveTimeouts + required: + - onTimeout + - initialTimeout + description: |- + EffectiveTimeouts retains the selected behavior and current action deadline. + DELETE and STOP retain a resume timeout; RESTART (and its deprecated alias KEEP) does not use one + TimeoutAction: + type: string + title: TimeoutAction + enum: + - unspecified + - delete + - stop + - keep + - restart + description: |- + TimeoutAction selects the lifecycle action taken at the reported deadline. + + Values: + unspecified: unspecified is invalid when explicitly supplied. + delete: delete deletes the sandbox at expiry. + stop: stop applies the sandbox's persisted stop guarantee at expiry. + keep: Deprecated alias for the restart action, still accepted on input and output. New clients should use the canonical restart action. + restart: Preserves memory through backend-managed stop/resume cycles at expiry. Requires memory preservation and the always-on entitlement. + TimeoutOptions: + type: object + properties: + timeout: + description: timeout is the initial TTL; omission selects the advertised action default. + $ref: "#/components/schemas/Duration" + onTimeout: + oneOf: + - $ref: "#/components/schemas/TimeoutAction" + - type: "null" + not: + enum: + - unspecified + description: on_timeout defaults to DELETE; an explicit UNSPECIFIED is invalid. + autoResume: + type: + - boolean + - "null" + description: Omission selects the advertised default; false does not disable RESTART or KEEP cycles. + title: TimeoutOptions + additionalProperties: false + description: |- + TimeoutOptions selects deadline behavior; presence enables this feature for the sandbox. + an explicit RESTART (or its deprecated alias KEEP) initial timeout must be at least one hour + ProcessAttach: + type: object + properties: + name: + type: string + pattern: ^processes/[^/]+$ + description: name is the complete resource name, in the form processes/{process}. + resumeFrom: + type: + - integer + - string + format: int64 + description: resume_from resumes after a received or published stream_sequence; 0 means from the start. Missing output after this point fails with FAILED_PRECONDITION. + title: Attach + required: + - name + additionalProperties: false + description: Attach selects the process and output resume point. + ProcessChunk: + type: object + properties: + stream: + description: stream identifies stdout, stderr, or PTY output. + $ref: "#/components/schemas/StreamType" + data: + type: string + format: byte + description: data is output bytes. + streamSequence: + type: + - integer + - string + format: int64 + description: stream_sequence is one-based and strictly increases per process output stream. + title: Chunk + description: Chunk carries process output. + CreateProcessRequest: + type: object + properties: + cmd: + type: array + items: + type: string + minItems: 1 + description: cmd is the argv vector. + env: + type: object + additionalProperties: + type: string + title: value + description: env adds environment variables. + workingDir: + type: string + description: working_dir is the process working directory. + user: + type: string + description: user is the user to run as. + pty: + description: pty requests a pseudo-terminal; absence uses separate stdin/stdout/stderr pipes. + $ref: "#/components/schemas/PtyConfig" + session: + type: string + description: session is an optional opaque session tag stored verbatim; empty means untagged. + label: + type: + - string + - "null" + minLength: 1 + description: (OPTIONAL) label is unique within the sandbox; omission retains the server-generated default. + title: CreateProcessRequest + required: + - cmd + additionalProperties: false + description: CreateProcessRequest starts an interactive process. + ExecRequest: + type: object + properties: + cmd: + type: array + items: + type: string + minItems: 1 + description: cmd is the argv vector. + env: + type: object + additionalProperties: + type: string + title: value + description: env adds environment variables. + workingDir: + type: string + description: working_dir is the process working directory. + user: + type: string + description: user is the user to run as. + title: ExecRequest + required: + - cmd + additionalProperties: false + description: ExecRequest runs a command to completion. + ExecResponse: + type: object + properties: + exitCode: + type: integer + format: int32 + description: exit_code is the process exit code. + stdout: + type: string + format: byte + description: stdout is captured stdout, up to the capture limit when incomplete. + stderr: + type: string + format: byte + description: stderr is captured stderr, up to the capture limit when incomplete. + incomplete: + type: boolean + description: |- + incomplete is true when the combined capture limit forced stdout and/or + stderr to discard some of the command's real output; false whenever + every byte the command produced was retained, even if that total lands + exactly at the limit. exit_code is still the real, final exit code: the + command ran to completion, only its captured output was capped. A retry + would rerun the command, so this stays a normal successful response + rather than an error a client might retry. + title: ExecResponse + description: ExecResponse returns process output after the command exits. + ProcessExited: + type: object + properties: + exitCode: + type: integer + format: int32 + description: exit_code is the process exit code. + reason: + type: string + description: reason is backend-readable exit context. + title: Exited + description: Exited reports process completion. + ProcessHeartbeat: + type: object + title: Heartbeat + additionalProperties: false + description: Heartbeat is an idle keepalive frame. + InteractRequest: + type: object + oneOf: + - type: object + properties: + attach: + description: attach opens or resumes the interaction. + $ref: "#/components/schemas/ProcessAttach" + title: attach + required: + - attach + - type: object + properties: + closeStdin: + type: boolean + description: |- + close_stdin closes standard input when true; false has no effect, including on a PTY. + On a PTY, true delivers the terminal's VEOF input through the line discipline and + does not close the PTY master; subsequent stdin frames remain valid. Terminal mode + owns interpretation: canonical mode treats VEOF as marking the end of input, while + raw mode delivers it as an ordinary input byte, so this promises delivery, never + interpretation. Each true frame on a PTY delivers exactly one VEOF input; unlike the + pipe path, repeated frames are not a no-op. + title: close_stdin + required: + - closeStdin + - type: object + properties: + resize: + description: resize changes terminal size; portable-range dimensions on a running process without a PTY return FAILED_PRECONDITION. + $ref: "#/components/schemas/TerminalSize" + title: resize + required: + - resize + - type: object + properties: + stdin: + type: string + format: byte + description: stdin writes process standard input. + title: stdin + required: + - stdin + title: InteractRequest + unevaluatedProperties: false + description: InteractRequest is one frame on the bidirectional interaction stream. + ListProcessesResponse: + type: object + properties: + processes: + type: array + items: + $ref: "#/components/schemas/Process" + description: processes is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListProcessesResponse + description: ListProcessesResponse returns processes and a next-page token. + ProcessOutput: + type: object + title: Output + unevaluatedProperties: false + description: Output is one server frame on an interaction stream. At most one of chunk, exited, heartbeat is set. + properties: + chunk: + description: chunk carries ordered process output. + $ref: "#/components/schemas/ProcessChunk" + exited: + description: exited reports process completion. + $ref: "#/components/schemas/ProcessExited" + heartbeat: + description: heartbeat keeps an idle stream alive and carries no resume position. + $ref: "#/components/schemas/ProcessHeartbeat" + dependentSchemas: + chunk: + not: + anyOf: + - required: + - exited + - required: + - heartbeat + exited: + not: + anyOf: + - required: + - chunk + - required: + - heartbeat + heartbeat: + not: + anyOf: + - required: + - chunk + - required: + - exited + Process: + type: object + properties: + uid: + type: + - string + - "null" + description: (IMMUTABLE) uid is the existing process incarnation, also used as the resource name terminal. + readOnly: true + pid: + type: integer + format: int32 + description: pid is the process id inside the sandbox when available. + session: + type: string + description: session is the session tag from the create, empty when untagged. + state: + description: state is the process state, concrete in conforming responses. + $ref: "#/components/schemas/ProcessState" + lastStreamSequence: + type: + - integer + - string + format: int64 + description: last_stream_sequence is the highest stream_sequence emitted for the process when this report was assembled; 0 before any output. + receiptKind: + description: |- + receipt_kind classifies this response on CreateProcess; every other operation + returning a Process, including ListProcesses, always reports unspecified. + $ref: "#/components/schemas/ReceiptKind" + exitCode: + type: + - integer + - "null" + format: int32 + description: exit_code is the process exit code, set only when state is exited and absent otherwise. + label: + type: string + minLength: 1 + description: (IMMUTABLE) label retains the unique, immutable process label and its generated default. + name: + type: string + description: (IDENTIFIER) name is scoped to the discovered sandbox endpoint API base. + title: Process + required: + - label + description: Process is the handle returned before interaction begins. + ProcessState: + type: string + title: ProcessState + enum: + - unspecified + - running + - exited + description: |- + ProcessState is the coarse process lifecycle a process report carries. + + Values: + unspecified: unspecified is not a concrete state; conforming responses never use it. + running: running means the process has not exited. + exited: exited means the process has exited. + PtyConfig: + type: object + properties: + initialSize: + description: initial_size requests an initial terminal size; absence selects a backend-defined size. + $ref: "#/components/schemas/TerminalSize" + title: PtyConfig + additionalProperties: false + description: PtyConfig configures pseudo-terminal creation. + ReadOutputResponse: + type: object + properties: + chunks: + type: array + items: + $ref: "#/components/schemas/ProcessChunk" + description: chunks is retained output in stream_sequence order, possibly empty. + nextResumeFrom: + type: + - integer + - string + format: int64 + description: |- + next_resume_from is the stream_sequence to pass next; equal to resume_from + when nothing new was retained. + exited: + description: exited is set once the process has exited and no retained bytes follow next_resume_from. + $ref: "#/components/schemas/ProcessExited" + title: ReadOutputResponse + description: ReadOutputResponse is one page of ordered output. + ReceiptKind: + type: string + title: ReceiptKind + enum: + - unspecified + - fresh + - replay + description: |- + ReceiptKind classifies whether a CreateProcess response was freshly assembled or + is the retained receipt of an earlier accepted request. + + Values: + unspecified: unspecified is not a concrete classification; a backend or a client generated before this field existed reports or reads this. It asserts neither freshness nor replay. + fresh: fresh means this Process was assembled for this specific accepted request; last_stream_sequence reflects live state as of that acceptance. + replay: replay means the backend returned the retained result of an earlier accepted request under the synchronous mutation replay rule; last_stream_sequence is frozen at the value observed during that original acceptance. + ProcessSignal: + type: string + title: Signal + enum: + - unspecified + - term + - kill + - int + - hup + - quit + - usr1 + - usr2 + description: |- + Signal is a process signal. + + Values: + unspecified: unspecified is invalid. + term: term requests graceful termination. + kill: kill requests immediate termination. + int: int requests interrupt. + hup: hup requests hangup. + quit: quit requests quit. + usr1: usr1 requests user signal 1. + usr2: usr2 requests user signal 2. + SignalResponse: + type: object + title: SignalResponse + description: SignalResponse has no fields. + StreamType: + type: string + title: StreamType + enum: + - unspecified + - stdout + - stderr + - pty + description: |- + StreamType identifies the source of an output chunk. + + Values: + unspecified: unspecified is not a concrete output stream. + stdout: stdout is stdout. + stderr: stderr is stderr. + pty: pty is merged PTY output. + TerminalSize: + type: object + properties: + rows: + type: integer + description: rows is the terminal row count. + cols: + type: integer + description: cols is the terminal column count. + bounded: + type: boolean + description: |- + bounded requests the portable range enforced on this size, with no opt in + to perform first. Unset or false keeps the unenforced behavior. + title: TerminalSize + additionalProperties: false + description: |- + TerminalSize is a terminal rows/columns pair; 1 through 65535 is the portable range. + bounded requires rows and cols in 1..65535 + AddMcpGatewayServerResponse: + type: object + properties: + server: + description: server is the gateway server. + $ref: "#/components/schemas/McpServer" + title: AddMcpGatewayServerResponse + description: AddMcpGatewayServerResponse returns the added or already-present server. + AttributedRule: + type: object + properties: + network: + type: string + description: network is the network name or CIDR. + layer: + description: layer identifies where the rule came from. + $ref: "#/components/schemas/PolicyLayer" + title: AttributedRule + description: AttributedRule reports a rule and the layer that supplied it. + CaptureMode: + type: string + title: CaptureMode + enum: + - unspecified + - all + - disk + description: |- + CaptureMode selects whether captured images include memory. + + Values: + unspecified: unspecified means disk-only capture. + all: all captures memory and disk and requires memory-capture support. + disk: disk captures disk only. + CreateImageRequest: + type: object + allOf: + - properties: + displayName: + type: string + not: + type: string + enum: + - . + - .. + minLength: 1 + pattern: ^[^/]+$ + description: display_name is a scoped label; the backend assigns the immutable resource ID. + description: + type: string + description: description is caller-supplied text. + startCmd: + type: array + items: + type: string + description: start_cmd is used when the image is launched as a raw image sandbox. + readyCmd: + type: array + items: + type: string + description: ready_cmd is used to determine readiness for raw image sandboxes. + - oneOf: + - type: object + properties: + fromImage: + description: from_image registers an entry that will receive pushed OCI content. + $ref: "#/components/schemas/ImageFromImage" + title: from_image + required: + - fromImage + title: CreateImageRequest + required: + - displayName + unevaluatedProperties: false + description: CreateImageRequest creates a managed image. + CreatePortRequestPortInput: + type: object + properties: + number: + type: integer + maximum: 65535 + minimum: 1 + format: int32 + description: (IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS. + protocol: + type: string + title: PortInputProtocol + enum: + - unspecified + - tcp + description: (IMMUTABLE) protocol defaults to TCP when unspecified. + title: PortInput + required: + - number + additionalProperties: false + CreateSandboxRequest: + type: object + allOf: + - properties: + agent: + type: string + description: agent names an optional agent profile; unsupported profiles fail explicitly. + displayName: + type: string + maxLength: 64 + pattern: ^[a-zA-Z0-9_-]*$ + description: (OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID. + displayNamePrefix: + type: string + description: (OPTIONAL) display_name_prefix requests a generated label and excludes display_name. + environment: + type: object + additionalProperties: + type: string + title: value + description: environment is non-secret environment metadata. + resources: + description: resources requests CPU and memory within the selected placement's limits. + $ref: "#/components/schemas/Resources" + pullPolicy: + type: string + title: CreateSandboxRequestPullPolicy + enum: + - unspecified + - always + description: pull_policy retains shared image-pull semantics and explicit support errors. + kits: + type: array + items: + $ref: "#/components/schemas/KitInput" + description: kits are the kit inputs to apply before readiness, in composition order. + mcp: + description: mcp requests an MCP gateway wired before the workload starts. + $ref: "#/components/schemas/McpCreateSpec" + networkPolicies: + type: array + items: + $ref: "#/components/schemas/NetworkPolicy" + description: |- + network_policies are inline policies materialized in governance and enforced before the first guest process. + Omission or an empty list requests no inline policies; unsupported policies fail before create effects. + policyIds: + type: array + items: + type: string + minLength: 1 + description: policy_ids names existing governance policies, never raw policy content. + platform: + description: |- + platform selects an exact supported, image-compatible tuple when present. + explicit platform requires OS and architecture + $ref: "#/components/schemas/Platform" + startupExecution: + description: |- + startup_execution is ordinary create input and persists for + the sandbox lifetime. + $ref: "#/components/schemas/StartupExecution" + labels: + type: object + maxProperties: 64 + additionalProperties: + type: string + title: value + description: "" + description: |- + labels are non-secret caller-assigned key/value metadata recorded at admission. + This contract has no verb that changes labels afterwards. + features: + description: features carries typed inputs validated before admission can have effects. + $ref: "#/components/schemas/FeatureOptions" + - properties: + image: + type: string + pattern: ^images/[^/]+$ + description: image is the managed Image resource name. + imageRef: + type: string + description: image_ref is an external OCI reference, with the existing backend validation. + dependentSchemas: + image: + not: + anyOf: + - required: + - imageRef + imageRef: + not: + anyOf: + - required: + - image + title: CreateSandboxRequest + unevaluatedProperties: false + description: |- + CreateSandboxRequest validates typed composition intent before replay and + persists accepted guarantees, distinct enough from legacy create that old + servers cannot silently drop it. + display_name and display_name_prefix are mutually exclusive At most one of image, imageRef is set. + CreateSecretRequest: + type: object + allOf: + - properties: + displayName: + type: string + not: + type: string + enum: + - . + - .. + minLength: 1 + pattern: ^[^/]+$ + description: display_name is a scoped label; the backend assigns the immutable resource ID. + serviceType: + type: string + description: service_type identifies the consuming service. + - oneOf: + - type: object + properties: + custom: + description: |- + custom stores an opaque value with caller-authored injection metadata. + CreateSecretRequest.service_type is server-assigned for custom + material; leave it empty. + $ref: "#/components/schemas/CustomSecretMaterial" + title: custom + required: + - custom + - type: object + properties: + oauth: + description: oauth stores OAuth refresh material. + $ref: "#/components/schemas/OAuthRefreshMaterial" + title: oauth + required: + - oauth + - type: object + properties: + token: + description: token stores opaque token material. + $ref: "#/components/schemas/TokenSecretMaterial" + title: token + required: + - token + title: CreateSecretRequest + required: + - displayName + unevaluatedProperties: false + description: |- + CreateSecretRequest stores new secret material. + service_type must be empty for custom material (server-assigned) + CreateVolumeRequest: + type: object + properties: + displayName: + type: string + not: + type: string + enum: + - . + - .. + minLength: 1 + pattern: ^[^/]+$ + description: display_name is a scoped label; the backend assigns the immutable resource ID. + title: CreateVolumeRequest + required: + - displayName + additionalProperties: false + description: CreateVolumeRequest creates one volume. + CredentialFenceReceipt: + type: object + properties: + target: + type: string + pattern: ^(sandboxes|secrets)/[^/]+$ + description: target is the complete Sandbox or Secret resource name bound to this receipt. + generation: + exclusiveMinimum: 0 + type: + - integer + - string + format: int64 + description: generation increases for each accepted material/rule replacement on that target. + title: CredentialFenceReceipt + required: + - target + - generation + description: CredentialFenceReceipt acknowledges one completed generation without granting current use. + CustomInjection: + type: object + properties: + hosts: + type: array + items: + type: string + minLength: 1 + maxItems: 10 + minItems: 1 + description: |- + hosts are exact lowercase DNS names. Wildcards, IP literals, ports, + schemes, paths, and hosts a managed integration already serves are + rejected. + header: + type: string + minLength: 1 + description: |- + header is the HTTP header the value is written to. Routing, framing, + and cookie headers are rejected. + format: + type: string + description: |- + format renders the value with exactly one %s; %% escapes a literal + percent, and any other % sequence is rejected. Empty means "%s". + envVar: + type: string + description: |- + env_var optionally names a sandbox environment variable that carries the + secret's placeholder (never the value) as a delivery convenience. + placeholderTemplate: + type: string + description: |- + placeholder_template optionally shapes the placeholder for clients that + validate credential shape before sending (e.g. "sk-corp-{rand}"). Each + {rand} token is expanded server-side; {rand} is the only token. Empty + uses the backend default ("sbx-cs-{rand}"). + title: CustomInjection + required: + - hosts + - header + additionalProperties: false + description: |- + CustomInjection is caller-authored, non-secret metadata for a custom + secret: which exact hosts receive the value, in which header and format, + and how the placeholder is shaped and delivered. Unlike secret material, + reads return it. + CustomSecretMaterial: + type: object + properties: + value: + type: string + minLength: 1 + description: value is the secret value. + writeOnly: true + injection: + description: injection is the caller-authored routing. + $ref: "#/components/schemas/CustomInjection" + title: CustomSecretMaterial + required: + - value + - injection + additionalProperties: false + description: CustomSecretMaterial is an opaque secret value plus its injection routing. + DeleteSecretResponse: + type: object + properties: + credentialFence: + description: credential_fence remains the original historical receipt after deletion or name reuse. + $ref: "#/components/schemas/CredentialFenceReceipt" + title: DeleteSecretResponse + description: DeleteSecretResponse acknowledges deletion and optional consumer fencing. + EffectiveNetworkPolicy: + type: object + properties: + mode: + not: + enum: + - unspecified + description: mode is the effective mode and is always concrete in conforming responses. + $ref: "#/components/schemas/NetworkPolicyMode" + allowNetworks: + type: array + items: + $ref: "#/components/schemas/AttributedRule" + description: allow_networks are effective allowed rules with attribution. + denyNetworks: + type: array + items: + $ref: "#/components/schemas/AttributedRule" + description: deny_networks are effective denied rules with attribution. + title: EffectiveNetworkPolicy + required: + - mode + description: EffectiveNetworkPolicy is the policy after layering and fail-closed defaults. + EndpointCredential: + type: object + properties: + token: + type: string + minLength: 1 + expireTime: + $ref: "#/components/schemas/Timestamp" + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + enum: + - sandboxesExec + - sandboxesFilesRead + - sandboxesFilesWrite + minItems: 1 + uniqueItems: true + description: "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite." + sandbox: + type: string + pattern: ^sandboxes/[^/]+$ + audience: + type: string + minLength: 1 + title: EndpointCredential + required: + - token + - expireTime + - permissions + - sandbox + - audience + description: "EndpointCredential is returned once with Cache-Control: no-store; never log its token." + EtagMismatch: + type: object + properties: + currentEtag: + type: string + minLength: 1 + description: current_etag is informational; clients must not silently retry with it. + title: EtagMismatch + required: + - currentEtag + description: |- + EtagMismatch is the status detail a stale precondition carries, so a client learns the + current version for an explicit conflict-resolution decision. + EtagMismatchErrorDetail: + type: object + properties: + currentEtag: + type: string + minLength: 1 + description: current_etag is informational; clients must not silently retry with it. + "@type": + type: string + const: type.googleapis.com/docker.sandboxes.v1.EtagMismatch + title: EtagMismatchErrorDetail + required: + - currentEtag + - "@type" + description: |- + EtagMismatch is the status detail a stale precondition carries, so a client learns the + current version for an explicit conflict-resolution decision. + ExactDestination: + type: object + properties: + kind: + not: + enum: + - unspecified + description: kind selects a matching rule; dnsLabelPrefix requires destination.v2. + $ref: "#/components/schemas/ExactDestinationKind" + value: + type: string + minLength: 1 + description: |- + For dnsLabelPrefix, crl.digicert.com matches a first label starting with crl + and remaining labels exactly digicert.com; every value label is canonical ASCII DNS. + port: + type: + - integer + - "null" + maximum: 65535 + minimum: 1 + description: An absent port matches all numeric ports; zero is invalid when present. + title: ExactDestination + required: + - kind + - value + description: |- + ExactDestination uses canonical selector values, never legacy glob syntax. + dnsLabelPrefix requires a canonical DNS label prefix and suffix + ExactDestinationKind: + type: string + title: ExactDestinationKind + enum: + - unspecified + - dns + - dnsLabel + - dnsSubtree + - ip + - cidr + - dnsLabelPrefix + description: |- + ExactDestinationKind keeps DNS and IP-literal decisions distinct. + + Values: + unspecified + dns + dnsLabel + dnsSubtree + ip + cidr + dnsLabelPrefix + ExactNetworkPolicy: + type: object + properties: + revision: + type: string + minLength: 1 + description: revision binds authority, configuration and resolved conditions to the installed generation. + selectorVersion: + type: string + enum: + - destination.v1 + - destination.v2 + description: selector_version fixes matching semantics across implementations. + nodes: + type: array + items: + $ref: "#/components/schemas/ExactPolicyNode" + maxItems: 256 + minItems: 1 + description: nodes are complete and topologically ordered; the final node is the root. + title: ExactNetworkPolicy + required: + - revision + - selectorVersion + - nodes + description: |- + ExactNetworkPolicy is a complete consumer-installed generation; its last node is the root. + dnsLabelPrefix requires destination.v2 + ExactPolicyConstant: + type: string + title: ExactPolicyConstant + enum: + - unspecified + - "true" + - "false" + description: |- + ExactPolicyConstant makes both Boolean identities explicit. + + Values: + unspecified + true + false + ExactPolicyNode: + type: object + allOf: + - properties: + source: + description: source is required on constants and destinations and absent on Boolean operators. + $ref: "#/components/schemas/ExactPolicySource" + - oneOf: + - type: object + properties: + all: + description: all intersects every operand. + $ref: "#/components/schemas/ExactPolicyOperands" + title: all + required: + - all + - type: object + properties: + any: + description: any unions its operands without discarding enclosing ceilings. + $ref: "#/components/schemas/ExactPolicyOperands" + title: any + required: + - any + - type: object + properties: + constant: + not: + enum: + - unspecified + description: constant explicitly allows or denies independently of the destination. + $ref: "#/components/schemas/ExactPolicyConstant" + title: constant + required: + - constant + - type: object + properties: + destination: + description: destination matches only its declared DNS or IP kind. + $ref: "#/components/schemas/ExactDestination" + title: destination + required: + - destination + - type: object + properties: + not: + type: integer + description: not negates one earlier node. + title: not + required: + - not + title: ExactPolicyNode + description: ExactPolicyNode is topologically ordered; references must precede this node. + ExactPolicyOperands: + type: object + properties: + nodes: + type: array + items: + type: integer + maxItems: 64 + minItems: 1 + description: nodes must all precede the enclosing operator. + title: ExactPolicyOperands + required: + - nodes + description: ExactPolicyOperands contains earlier node indexes; empty Boolean groups are invalid. + ExactPolicyOrigin: + type: string + title: ExactPolicyOrigin + enum: + - unspecified + - organization + - owner + - attached + - kit + - gateway + - default + description: |- + ExactPolicyOrigin separates governance from attached and runtime-owned permissions. + + Values: + unspecified + organization + owner + attached + kit + gateway + default + ExactPolicySource: + type: object + properties: + origin: + not: + enum: + - unspecified + description: origin distinguishes the authority that supplied this leaf. + $ref: "#/components/schemas/ExactPolicyOrigin" + id: + type: string + minLength: 1 + description: id identifies that source without exposing credentials or policy content. + title: ExactPolicySource + required: + - origin + - id + description: ExactPolicySource identifies the nonsecret authority of a leaf expression. + ExchangeCompositionCredentialResponse: + type: object + title: ExchangeCompositionCredentialResponse + GetNetworkPoliciesResponse: + type: object + properties: + effective: + $ref: "#/components/schemas/EffectiveNetworkPolicy" + exact: + $ref: "#/components/schemas/ExactNetworkPolicy" + title: GetNetworkPoliciesResponse + required: + - effective + - exact + description: GetNetworkPoliciesResponse binds both views to exact.revision; a partial read fails. + IdentityExchangeServiceExchangeDockerCredentialRequest: + type: object + properties: + idToken: + type: string + minLength: 1 + description: id_token is single-use identity material, never an owner selector. + writeOnly: true + title: IdentityExchangeServiceExchangeDockerCredentialRequest + required: + - idToken + additionalProperties: false + Image: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^images/[^/]+$ + description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. + description: + type: string + description: description is caller-supplied text. + status: + not: + enum: + - unspecified + description: status is the image readiness state. + readOnly: true + $ref: "#/components/schemas/ImageStatus" + imageRef: + type: string + description: image_ref is the registry or backend image reference when available. + imageDigest: + type: string + description: image_digest is the content digest when known. + resources: + description: resources describes the image's preferred runtime resources. + $ref: "#/components/schemas/Resources" + startCmd: + type: array + items: + type: string + description: start_cmd is the command used by raw image sandboxes. + readyCmd: + type: array + items: + type: string + description: ready_cmd is the readiness command used by raw image sandboxes. + platform: + description: platform is the image platform. + $ref: "#/components/schemas/Platform" + totalSizeBytes: + type: + - integer + - string + format: int64 + description: total_size_bytes is the approximate stored image size. + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + updatedAt: + description: updated_at is the last update timestamp. + $ref: "#/components/schemas/Timestamp" + failure: + description: failure is set when status is FAILED. + $ref: "#/components/schemas/Error" + source: + description: source records how the image was created. + $ref: "#/components/schemas/ImageSource" + captureMode: + description: capture_mode records whether captured content includes memory. + $ref: "#/components/schemas/CaptureMode" + etag: + type: string + minLength: 1 + pattern: ^"[^"\x00-\x20\x7f]*"$ + description: |- + etag identifies the observed version of this resource. It is opaque and strong, + changes on every visible change, and is what a mutation sends as its precondition. + readOnly: true + pushTarget: + description: push_target appears only in from_image create responses awaiting upload, never reads. + readOnly: true + $ref: "#/components/schemas/ImagePushTarget" + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: Image + required: + - uid + - name + - status + - createdAt + - updatedAt + - etag + description: |- + Image is the detailed managed image view. + uid must equal the immutable resource ID in name + ImageBlobRef: + type: object + properties: + digest: + type: string + description: digest is the content digest. + mediaType: + type: string + description: media_type is the OCI media type. + size: + type: + - integer + - string + format: int64 + description: size is the blob size in bytes. + url: + type: string + description: url is a short-lived pull URL. + title: ImageBlobRef + description: ImageBlobRef describes one pullable blob. + ImageFromImage: + type: object + properties: + resources: + description: resources describes preferred runtime resources for the resulting image. + $ref: "#/components/schemas/Resources" + platform: + description: platform is the platform for the pushed content. + $ref: "#/components/schemas/Platform" + captureMode: + type: string + title: ImageFromImageCaptureMode + enum: + - unspecified + - disk + description: capture_mode must be unspecified or disk; pushed OCI content cannot include memory. + not: + enum: + - all + platformHint: + description: |- + platform_hint picks among a multi-platform push when platform is absent. + A hint the backend cannot honor is ignored, never an error. + $ref: "#/components/schemas/Platform" + kitStartup: + description: Startup commands copied from the source sandbox. Services with startup replay run these commands when a sandbox created from the image boots. Services without startup replay accept valid commands without running them. + $ref: "#/components/schemas/KitStartup" + title: ImageFromImage + additionalProperties: false + description: ImageFromImage registers a target for pushed OCI content. + ImagePullSpec: + type: object + properties: + manifestDigest: + type: string + description: manifest_digest is the manifest digest. + manifestMediaType: + type: string + description: manifest_media_type is the manifest media type. + config: + description: config is the image config blob. + $ref: "#/components/schemas/ImageBlobRef" + layers: + type: array + items: + $ref: "#/components/schemas/ImageBlobRef" + description: layers are the image layer blobs. + expiresAt: + description: expires_at is when the pull material expires. + $ref: "#/components/schemas/Timestamp" + title: ImagePullSpec + description: ImagePullSpec describes short-lived pull material for placement. + ImagePushTarget: + type: object + properties: + imageRef: + type: string + description: image_ref is the registry reference to push. + accessToken: + type: string + description: access_token is the short-lived push credential. + accessTokenExpiresAt: + description: access_token_expires_at is the token expiry. + $ref: "#/components/schemas/Timestamp" + title: ImagePushTarget + description: ImagePushTarget carries short-lived upload credentials. + ImageSource: + type: string + title: ImageSource + enum: + - unspecified + - image + - sandbox + description: |- + ImageSource records how the image was created. + + Values: + unspecified: unspecified means the source is unknown or not reported. + image: image means the image came from pushed or imported image bytes. + sandbox: sandbox means the image came from a sandbox capture. + ImageStatus: + type: string + title: ImageStatus + enum: + - unspecified + - pending + - waitingForPush + - preparing + - completed + - failed + - deleted + description: |- + ImageStatus is the image readiness state. + + Values: + unspecified: unspecified is never a concrete known state. + pending: pending means an asynchronous build has not started or reported progress. + waitingForPush: waitingForPush means the backend is waiting for OCI content upload. + preparing: preparing means the backend is preparing pushed or captured content. + completed: completed means the image is ready to use. + failed: failed means image preparation reached a terminal failure. + deleted: deleted means the backend exposes a retained delete tombstone. + ImageSummary: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^images/[^/]+$ + description: name ends in the immutable backing ID and never changes with display_name. + status: + not: + enum: + - unspecified + description: status is the image readiness state. + $ref: "#/components/schemas/ImageStatus" + source: + description: source records how the image was created. + $ref: "#/components/schemas/ImageSource" + totalSizeBytes: + type: + - integer + - string + format: int64 + description: total_size_bytes is the approximate stored image size. + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + updatedAt: + description: updated_at is the last update timestamp. + $ref: "#/components/schemas/Timestamp" + imageRef: + type: string + description: image_ref is the registry or backend image reference when available. + imageDigest: + type: string + description: image_digest is the content digest when known. + captureMode: + description: capture_mode records whether captured content includes memory. + $ref: "#/components/schemas/CaptureMode" + platform: + description: platform is the image platform. + $ref: "#/components/schemas/Platform" + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: ImageSummary + required: + - uid + - name + - status + - createdAt + - updatedAt + description: |- + ImageSummary is the list view of an image. + uid must equal the immutable resource ID in name + IssueSSHCertResponse: + type: object + properties: + certificate: + type: string + description: certificate is the signed SSH certificate. + sshConfig: + type: string + description: |- + ssh_config optionally renders the connection fields as OpenSSH client + configuration; the structured fields are canonical. + knownHosts: + type: string + description: known_hosts is host key material that authenticates the SSH endpoint. + expiresAt: + description: expires_at is the instant after which the certificate is invalid. + $ref: "#/components/schemas/Timestamp" + host: + type: string + description: host is the SSH endpoint host to connect to. + port: + type: integer + description: port is the SSH endpoint port to connect to. + username: + type: string + description: username is the SSH username to present; it carries no authorization. + title: IssueSSHCertResponse + description: IssueSSHCertResponse returns signed SSH client material, never a private key. + KitArtifactInput: + type: object + allOf: + - properties: + ref: + $ref: "#/components/schemas/KitRef" + - oneOf: + - type: object + properties: + inline: + type: string + format: byte + description: inline is the artifact in the pinned JSON encoding. + title: inline + required: + - inline + title: KitArtifactInput + required: + - ref + unevaluatedProperties: false + description: KitArtifactInput carries a v2 artifact inline or by staged digest. + KitFieldDisposition: + type: string + title: KitFieldDisposition + enum: + - unspecified + - skipped + - refused + description: |- + KitFieldDisposition describes a declaration that was not applied. + + Values: + unspecified: unspecified is invalid in a report. + skipped: skipped identifies a contract-permitted optional skip. + refused: refused prevents guest or kit effects. + KitFieldOutcome: + type: object + properties: + kitIndex: + exclusiveMaximum: 64 + type: integer + description: kit_index is the zero-based position in the originating request's kits. + ref: + type: string + description: ref preserves the exact requested kit reference. + digest: + type: string + description: digest is the resolved content identity when resolution succeeded. + fieldPath: + type: string + description: field_path is an RFC 6901 pointer into the pinned JSON artifact. + disposition: + not: + enum: + - unspecified + description: disposition never claims that an accepted declaration has executed. + $ref: "#/components/schemas/KitFieldDisposition" + reason: + not: + enum: + - unspecified + description: reason is a bounded category, not caller-controlled diagnostic content. + $ref: "#/components/schemas/KitFieldReason" + reasonText: + type: string + description: reason_text contains nonsecret explanatory text, never values or command content. + title: KitFieldOutcome + required: + - ref + - fieldPath + - disposition + - reason + description: KitFieldOutcome identifies one non-applied declaration without exposing its value. + KitFieldOutcomeReport: + type: object + properties: + complete: + type: boolean + description: complete means every refused or skipped declaration is accounted for; absence proves nothing. + outcomes: + type: array + items: + $ref: "#/components/schemas/KitFieldOutcome" + maxItems: 256 + description: outcomes follow request index then UTF-8 field-path order and are never truncated. + title: KitFieldOutcomeReport + description: KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal. + KitFieldOutcomeReportErrorDetail: + type: object + properties: + complete: + type: boolean + description: complete means every refused or skipped declaration is accounted for; absence proves nothing. + outcomes: + type: array + items: + $ref: "#/components/schemas/KitFieldOutcome" + maxItems: 256 + description: outcomes follow request index then UTF-8 field-path order and are never truncated. + "@type": + type: string + const: type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport + title: KitFieldOutcomeReportErrorDetail + description: KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal. + required: + - "@type" + KitFieldReason: + type: string + title: KitFieldReason + enum: + - unspecified + - unsupported + - unknownField + - credentialUnavailable + description: |- + KitFieldReason provides stable, nonsecret diagnostic categories. + + Values: + unspecified: unspecified is invalid in a report. + unsupported: unsupported means the backend cannot honor the declaration. + unknownField: unknownField means the pinned schema does not recognize the declaration. + credentialUnavailable: credentialUnavailable means the declared credential cannot be injected. + KitInput: + type: object + oneOf: + - type: object + properties: + artifact: + $ref: "#/components/schemas/KitArtifactInput" + title: artifact + required: + - artifact + title: KitInput + unevaluatedProperties: false + description: KitInput is one kit in either shape. + KitStartup: + type: object + properties: + kits: + type: array + items: + type: string + minLength: 1 + minItems: 1 + description: |- + kits names the kit identities the commands derive from, in composition + order. Required. + commands: + type: array + items: + $ref: "#/components/schemas/KitStartupCommand" + minItems: 1 + description: commands run in order at sandbox boot, on a backend that replays them. + title: KitStartup + required: + - kits + - commands + additionalProperties: false + description: Startup commands retained when creating an image. Services with startup replay run them at each boot; services without it accept valid commands without running them. + KitStartupCommand: + type: object + properties: + argv: + type: array + items: + type: string + minItems: 1 + description: |- + argv is the command and its arguments, exec-style. An argument other than + the executable itself may be empty (an intentional empty string, as in + `printf %s ""`); only the vector itself is required non-empty. + user: + type: string + description: user runs the command as this user; empty means the backend default. + background: + type: boolean + description: background launches the command detached instead of waiting for it. + title: KitStartupCommand + required: + - argv + additionalProperties: false + description: |- + KitStartupCommand is one startup command in a KitStartup set, run in order + by a backend that replays it at sandbox boot. + ListImagesResponse: + type: object + properties: + images: + type: array + items: + $ref: "#/components/schemas/ImageSummary" + description: images is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListImagesResponse + description: ListImagesResponse returns image results and a next-page token. + ListPolicyLogEntriesResponse: + type: object + properties: + entries: + type: array + items: + $ref: "#/components/schemas/PolicyLogEntry" + description: entries is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListPolicyLogEntriesResponse + description: ListPolicyLogEntriesResponse returns policy log entries and a next-page token. + ListPortsResponse: + type: object + properties: + published: + type: array + items: + $ref: "#/components/schemas/Port" + description: published is ordered by number ascending. + title: ListPortsResponse + description: ListPortsResponse returns currently published ports. + ListSandboxesResponse: + type: object + properties: + sandboxes: + type: array + items: + $ref: "#/components/schemas/Sandbox" + description: sandboxes is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListSandboxesResponse + description: ListSandboxesResponse returns sandbox results and a next-page token. + ListSecretsResponse: + type: object + properties: + secrets: + type: array + items: + $ref: "#/components/schemas/Secret" + description: secrets is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListSecretsResponse + description: ListSecretsResponse returns secrets and a next-page token. + ListSnapshotsResponse: + type: object + properties: + snapshots: + type: array + items: + $ref: "#/components/schemas/SnapshotSummary" + description: snapshots is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListSnapshotsResponse + description: ListSnapshotsResponse returns snapshot results and a next-page token. + ListVolumesResponse: + type: object + properties: + volumes: + type: array + items: + $ref: "#/components/schemas/Volume" + description: volumes is the current page. + nextPageToken: + type: string + description: next_page_token is empty when there are no more pages. + title: ListVolumesResponse + description: ListVolumesResponse returns volumes and a next-page token. + McpAuthorization: + type: object + properties: + server: + type: string + pattern: ^(?:mcp-servers/[^/]+)?$ + description: (OPTIONAL) server is the complete resource name, in the form mcp-servers/{server}. + uid: + type: + - string + - "null" + description: (IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available. + readOnly: true + status: + readOnly: true + $ref: "#/components/schemas/McpAuthorizationStatus" + authorizationUrl: + type: string + description: authorization_url is present only while interaction is pending. + readOnly: true + createdAt: + readOnly: true + $ref: "#/components/schemas/Timestamp" + updatedAt: + readOnly: true + $ref: "#/components/schemas/Timestamp" + expiresAt: + description: expires_at bounds the pending flow; expiry records FAILED on this incarnation. + readOnly: true + $ref: "#/components/schemas/Timestamp" + failure: + readOnly: true + $ref: "#/components/schemas/Error" + etag: + type: string + description: etag identifies this incarnation and changes with every visible authorization update. + readOnly: true + name: + type: string + description: (IDENTIFIER) name is the complete singleton resource name. + title: McpAuthorization + description: McpAuthorization is the current authorization incarnation for one named upstream. + McpAuthorizationStatus: + type: string + title: McpAuthorizationStatus + enum: + - unspecified + - pending + - authorized + - failed + description: |- + McpAuthorizationStatus reports the current upstream authorization outcome. + + Values: + unspecified + pending + authorized + failed + McpConfigurationMode: + type: string + title: McpConfigurationMode + enum: + - unspecified + - dynamic + - static + - attached + description: |- + McpConfigurationMode identifies desired hosting ownership and discovery behavior. + + Values: + unspecified: unspecified is not a concrete report mode. + dynamic: dynamic uses a backend-minted gateway with discovery. + static: static uses a backend-minted gateway without discovery. + attached: attached retains a read-only external binding. + McpConfigurationOutcome: + type: string + title: McpConfigurationOutcome + enum: + - unspecified + - pending + - applied + - skipped + - failed + description: |- + McpConfigurationOutcome describes one requested server in the reported generation. + + Values: + unspecified: unspecified is not a concrete outcome. + pending: pending has not settled and cannot establish completeness. + applied: applied is confirmed membership, not upstream authorization. + skipped: skipped requires an explicitly applicable compatibility rule. + failed: failed retains intent that could not be provisioned. + McpConfigurationReport: + type: object + properties: + generation: + type: string + description: generation is an opaque durable fence, never ordered or synthesized by callers. + mode: + not: + enum: + - unspecified + description: mode separates minted discovery behavior from read-only attachment. + $ref: "#/components/schemas/McpConfigurationMode" + complete: + type: boolean + description: complete means every active requested server is applied or explicitly permitted to skip. + servers: + type: array + items: + $ref: "#/components/schemas/McpConfiguredServer" + maxItems: 256 + description: servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers. + dormantServers: + type: array + items: + $ref: "#/components/schemas/McpServer" + maxItems: 256 + description: dormant_servers retains earlier minted intent while attached; it is empty in minted modes. + title: McpConfigurationReport + required: + - generation + - mode + description: McpConfigurationReport is also returned in Error.details on accepted provisioning failure. + McpConfigurationReportErrorDetail: + type: object + properties: + generation: + type: string + description: generation is an opaque durable fence, never ordered or synthesized by callers. + mode: + not: + enum: + - unspecified + description: mode separates minted discovery behavior from read-only attachment. + $ref: "#/components/schemas/McpConfigurationMode" + complete: + type: boolean + description: complete means every active requested server is applied or explicitly permitted to skip. + servers: + type: array + items: + $ref: "#/components/schemas/McpConfiguredServer" + maxItems: 256 + description: servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers. + dormantServers: + type: array + items: + $ref: "#/components/schemas/McpServer" + maxItems: 256 + description: dormant_servers retains earlier minted intent while attached; it is empty in minted modes. + "@type": + type: string + const: type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport + title: McpConfigurationReportErrorDetail + required: + - generation + - mode + - "@type" + description: McpConfigurationReport is also returned in Error.details on accepted provisioning failure. + McpConfiguredServer: + type: object + properties: + server: + description: server is the resolved requested server; its type cannot silently change within retained intent. + $ref: "#/components/schemas/McpServer" + outcome: + not: + enum: + - unspecified + description: outcome is concrete even when the gateway remains ready after a failed add. + $ref: "#/components/schemas/McpConfigurationOutcome" + reason: + type: string + description: reason is nonsecret context and never carries credentials or credential-bearing URLs. + title: McpConfiguredServer + required: + - server + - outcome + description: McpConfiguredServer preserves one canonical requested identity and its provisioning outcome. + McpCreateSpec: + type: object + properties: + servers: + type: array + items: + type: string + minLength: 1 + description: servers are initial server names for a backend-minted gateway. + static: + type: boolean + description: static pins the requested server set and closes gateway-side discovery. + gatewayUrl: + type: + - string + - "null" + format: uri + description: gateway_url attaches read-only to a pre-existing shareable gateway when supported. + title: McpCreateSpec + additionalProperties: false + description: |- + McpCreateSpec configures the sandbox's MCP gateway before the workload starts. + servers must be empty when gateway_url is set + McpGateway: + type: object + properties: + url: + type: string + description: url is the gateway endpoint. + state: + description: state is the gateway readiness state. + $ref: "#/components/schemas/McpGatewayState" + servers: + type: array + items: + $ref: "#/components/schemas/McpServer" + description: servers is the accumulated requested set, not live gateway truth. + reused: + type: boolean + description: reused is true when the response reused an existing gateway. + uid: + type: + - string + - "null" + description: (IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available. + readOnly: true + name: + type: string + description: (IDENTIFIER) name is the complete singleton resource name. + title: McpGateway + description: McpGateway is gateway state for one sandbox. + McpGatewayState: + type: string + title: McpGatewayState + enum: + - unspecified + - provisioning + - ready + - failed + description: |- + McpGatewayState reports gateway readiness. + + Values: + unspecified: unspecified is never a concrete known state. + provisioning: provisioning means the gateway is starting. + ready: ready means the gateway can accept server operations. + failed: failed means gateway setup failed. + McpServer: + type: object + properties: + name: + type: string + description: name is the external configured server key, not an API resource name. + type: + description: type is the configured server type. + $ref: "#/components/schemas/McpServerType" + title: McpServer + description: McpServer projects one external server key configured on a gateway. + McpServerType: + type: string + title: McpServerType + enum: + - unspecified + - remote + - container + - stdio + description: |- + McpServerType identifies a gateway server integration style. + + Values: + unspecified: unspecified is not a concrete server type. + remote: remote is an HTTP remote MCP server. + container: container is a container-backed MCP server. + stdio: stdio is a stdio-backed MCP server. + NetworkPolicy: + type: object + properties: + mode: + type: string + title: NetworkPolicyMode + enum: + - denyAll + description: mode is required and cannot be UNSPECIFIED. + not: + enum: + - unspecified + allowNetworks: + type: array + items: + type: string + description: allow_networks are exact network names or CIDRs allowed by this document. + denyNetworks: + type: array + items: + type: string + description: deny_networks are exact network names or CIDRs denied by this document. + title: NetworkPolicy + required: + - mode + additionalProperties: false + description: NetworkPolicy is an inline policy request materialized in the governance plane. + NetworkPolicyMode: + type: string + title: NetworkPolicyMode + enum: + - unspecified + - allowAll + - denyAll + description: |- + NetworkPolicyMode is the top-level egress disposition. + + Values: + unspecified: unspecified is invalid in policy documents and in conforming responses. + allowAll: allowAll allows egress unless denied by a narrower rule. + denyAll: denyAll denies egress unless allowed by a narrower rule. + OAuthConfig: + type: object + properties: + tokenEndpoint: + type: string + description: token_endpoint is the OAuth token endpoint. + clientId: + type: string + description: client_id is the OAuth client id. + title: OAuthConfig + description: OAuthConfig is non-secret OAuth metadata returned on reads. + OAuthRefreshMaterial: + type: object + properties: + refreshToken: + type: string + minLength: 1 + description: refresh_token is the OAuth refresh token. + writeOnly: true + initialAccessToken: + type: string + description: initial_access_token is an optional bootstrap access token. + writeOnly: true + expiresAt: + description: expires_at is the access token expiry when supplied. + $ref: "#/components/schemas/Timestamp" + scopes: + type: array + items: + type: string + description: scopes are requested OAuth scopes. + providerAccountId: + type: string + description: provider_account_id identifies the provider account. + idToken: + type: string + description: id_token is an optional OpenID Connect id token. + writeOnly: true + clientId: + type: string + description: client_id is the OAuth client id. + title: OAuthRefreshMaterial + required: + - refreshToken + additionalProperties: false + description: |- + OAuthRefreshMaterial is OAuth secret material. Unlike OAuthRefreshMaterialV2 it pairs + no bootstrap token with an expiry and stores client_id as the caller supplied it. + PolicyDecision: + type: string + title: PolicyDecision + enum: + - unspecified + - allowed + - blocked + description: |- + PolicyDecision is the outcome of an evaluated access attempt. + + Values: + unspecified: unspecified means the decision is unknown or not reported. + allowed: allowed means the attempt was allowed. + blocked: blocked means the attempt was blocked. + PolicyDomain: + type: string + title: PolicyDomain + enum: + - unspecified + - network + description: |- + PolicyDomain identifies a policy subsystem. + + Values: + unspecified: unspecified is not a concrete policy domain. + network: network is network egress policy. + PolicyLayer: + type: string + title: PolicyLayer + enum: + - unspecified + - org + - owner + - kit + - attached + - gateway + - default + description: |- + PolicyLayer identifies where an effective rule came from. ORG and OWNER are + the two governance scopes; exactly one governs a caller, so a conforming effective view never mixes them. + + Values: + unspecified: unspecified means the layer is unknown or not reported. + org: org is org-level governance policy. + owner: owner is owner-level governance policy. + kit: kit is the sandbox-scoped policy a kit contributes. + attached: attached is a governance policy bound to the sandbox: an inline document or a referenced policy id, materialized and bound by the governance plane at create. + gateway: gateway is an enforced runtime-owned gateway policy contribution, not a backend service-route exemption. + default: default is an explicit installed default-policy contribution, not a substitute for unknown provenance or an owner-level policy. + PolicyLogEntry: + type: object + properties: + resource: + type: string + description: resource is the requested destination or resource. + decision: + description: decision is the observed allow or block outcome. + $ref: "#/components/schemas/PolicyDecision" + proxyType: + type: string + description: proxy_type is the proxy or enforcement path that observed the decision. + rule: + type: string + description: rule is the matching rule when available. + reason: + type: string + description: reason is backend-readable context. + count: + type: + - integer + - string + format: int64 + description: count is the number of coalesced observations. + firstSeen: + description: first_seen is the first observation timestamp. + $ref: "#/components/schemas/Timestamp" + lastSeen: + description: last_seen is the most recent observation timestamp. + $ref: "#/components/schemas/Timestamp" + sandbox: + type: string + description: sandbox is the resource name recorded for this reference. + sandboxUid: + type: + - string + - "null" + description: sandbox_uid retains the observed backing incarnation when the backend provides one. + readOnly: true + domain: + description: domain is the policy domain that emitted the entry. + $ref: "#/components/schemas/PolicyDomain" + title: PolicyLogEntry + description: PolicyLogEntry is an aggregated observed policy decision. + Port: + type: object + properties: + number: + type: integer + maximum: 65535 + minimum: 1 + format: int32 + description: (IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS. + protocol: + description: (IMMUTABLE) protocol defaults to TCP when unspecified. + $ref: "#/components/schemas/Protocol" + url: + type: string + description: url is the required externally reachable address, including host-local addresses. + readOnly: true + etag: + type: string + description: etag identifies the observed version of this port. + readOnly: true + uid: + type: + - string + - "null" + description: (IMMUTABLE) uid is the durable publication incarnation when the backend provides one. + readOnly: true + name: + type: string + description: (IDENTIFIER) name identifies the published port number under its sandbox resource name. + title: Port + required: + - number + description: |- + Port is one sandbox port made reachable from outside the sandbox. The same + facts appear inline on SandboxCore.ports for a caller reading the sandbox. + RawImageStartup: + type: object + properties: + start: + description: start replaces the complete launch argv; omission uses the image command. + $ref: "#/components/schemas/StartupArgv" + title: RawImageStartup + additionalProperties: false + description: RawImageStartup resolves identity and working directory from the pinned image. + Sandbox: + type: object + properties: + core: + description: core is the backend-neutral sandbox view. + $ref: "#/components/schemas/SandboxCore" + effectiveFeatures: + description: effective_features is emitted only by the composition contract projection. + $ref: "#/components/schemas/EffectiveFeatures" + failure: + description: failure is present only while status is FAILED and clears on recovery. + readOnly: true + $ref: "#/components/schemas/Error" + name: + type: string + pattern: ^sandboxes/[^/]+$ + description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + displayName: + type: string + description: display_name is the scoped label; UpdateSandbox changes it without changing identity. + title: Sandbox + required: + - core + - name + - uid + description: |- + Sandbox carries shared core state and the effective state of its selected features. + uid must equal the immutable resource ID in name + Secret: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^secrets/[^/]+$ + description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. + serviceType: + type: string + description: service_type identifies the consuming service. + type: + description: type identifies the stored material shape. + $ref: "#/components/schemas/SecretType" + oauthConfig: + description: oauth_config is returned only for OAuth-shaped secrets. + $ref: "#/components/schemas/OAuthConfig" + scopes: + type: array + items: + type: string + description: scopes are non-secret OAuth scopes. + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + updatedAt: + description: updated_at is the last update timestamp. + $ref: "#/components/schemas/Timestamp" + injection: + description: injection is returned only for custom-shaped secrets. + $ref: "#/components/schemas/CustomInjection" + placeholder: + type: string + description: |- + placeholder is server-generated per custom secret and stable across value + rotation; it is not secret material. A client presents it where the + credential would go; for the configured hosts the backend replaces the + configured header's value at egress regardless of what was sent. + etag: + type: string + minLength: 1 + pattern: ^"[^"\x00-\x20\x7f]*"$ + description: |- + etag identifies the observed version of this resource. It is opaque and strong, + changes on every visible change, and is what a mutation sends as its precondition. + readOnly: true + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: Secret + required: + - uid + - name + - createdAt + - updatedAt + - etag + description: |- + Secret is returned metadata and never includes secret material. + uid must equal the immutable resource ID in name + SecretType: + type: string + title: SecretType + enum: + - unspecified + - token + - oauthRefresh + - custom + - registryV2 + - hostResolved + description: "The stored credential shape: token, OAuth refresh material, custom injection, registry credentials, or a credential resolved from an approved host-owned source. Secret material is never returned." + Snapshot: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^snapshots/[^/]+$ + description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. + description: + type: string + description: description is caller-supplied text. + sandbox: + type: string + description: sandbox is the resource name recorded for this reference. + sandboxUid: + type: + - string + - "null" + description: sandbox_uid retains the observed backing incarnation when the backend provides one. + readOnly: true + status: + not: + enum: + - unspecified + description: status is the snapshot readiness state. + readOnly: true + $ref: "#/components/schemas/SnapshotStatus" + totalSizeBytes: + type: + - integer + - string + format: int64 + description: total_size_bytes is the approximate stored snapshot size. + resources: + description: resources describes the captured sandbox resources. + $ref: "#/components/schemas/Resources" + platform: + description: platform is the captured sandbox platform. + $ref: "#/components/schemas/Platform" + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + failure: + description: failure is set when status is FAILED. + $ref: "#/components/schemas/Error" + captureMode: + description: capture_mode is the mode the snapshot was captured with. + $ref: "#/components/schemas/CaptureMode" + etag: + type: string + minLength: 1 + pattern: ^"[^"\x00-\x20\x7f]*"$ + description: |- + etag identifies the observed version of this resource. It is opaque and strong, + changes on every visible change, and is what a mutation sends as its precondition. + readOnly: true + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: Snapshot + required: + - uid + - name + - status + - createdAt + - etag + description: |- + Snapshot is the detailed snapshot view. + uid must equal the immutable resource ID in name + SnapshotStatus: + type: string + title: SnapshotStatus + enum: + - unspecified + - creating + - ready + - failed + - deleted + description: |- + SnapshotStatus is snapshot readiness state. + + Values: + unspecified: unspecified is never a concrete known state. + creating: creating means capture has not completed. + ready: ready means the snapshot can be restored. + failed: failed means capture reached a terminal failure. + deleted: deleted means the backend exposes a retained delete tombstone. + SnapshotSummary: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^snapshots/[^/]+$ + description: name ends in the immutable backing ID and never changes with display_name. + sandbox: + type: string + description: sandbox is the resource name recorded for this reference. + sandboxUid: + type: + - string + - "null" + description: sandbox_uid retains the observed backing incarnation when the backend provides one. + readOnly: true + status: + not: + enum: + - unspecified + description: status is the snapshot readiness state. + $ref: "#/components/schemas/SnapshotStatus" + totalSizeBytes: + type: + - integer + - string + format: int64 + description: total_size_bytes is the approximate stored snapshot size. + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + captureMode: + description: capture_mode is the mode the snapshot was captured with. + $ref: "#/components/schemas/CaptureMode" + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: SnapshotSummary + required: + - uid + - name + - status + - createdAt + description: |- + SnapshotSummary is the list view of a snapshot. + uid must equal the immutable resource ID in name + StartupArgv: + type: object + properties: + argv: + type: array + items: + type: string + minItems: 1 + description: |- + argv is executed without shell expansion. It carries at least one element, + and that first element is the executable and must not be empty. + title: StartupArgv + required: + - argv + additionalProperties: false + description: |- + StartupArgv preserves literal arguments, including empty positional arguments. + startup argv requires a nonempty executable + StartupExecution: + type: object + oneOf: + - type: object + properties: + rawImage: + description: raw_image executes image commands using OCI identity and directory defaults. + $ref: "#/components/schemas/RawImageStartup" + title: raw_image + required: + - rawImage + title: StartupExecution + unevaluatedProperties: false + description: |- + StartupExecution retains the accepted execution promise across fresh boots. + It is ordinary create input. + TokenSecretMaterial: + type: object + properties: + value: + type: string + minLength: 1 + description: value is the secret token. + writeOnly: true + title: TokenSecretMaterial + required: + - value + additionalProperties: false + description: TokenSecretMaterial is opaque token material. + Volume: + type: object + properties: + uid: + type: + - string + minLength: 1 + description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. + readOnly: true + name: + type: string + pattern: ^volumes/[^/]+$ + description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. + createdAt: + description: created_at is the creation timestamp. + $ref: "#/components/schemas/Timestamp" + etag: + type: string + minLength: 1 + pattern: ^"[^"\x00-\x20\x7f]*"$ + description: |- + etag identifies the observed version of this resource. It is opaque and strong, + changes on every visible change, and is what a mutation sends as its precondition. + readOnly: true + displayName: + type: string + description: display_name is a scoped label and never selects the resource. + title: Volume + required: + - uid + - name + - createdAt + - etag + description: |- + Volume is persistent storage metadata within its owner and contract scope. + uid must equal the immutable resource ID in name + Duration: + type: string + pattern: ^-?\d+(\.\d{1,9})?s$ + description: Seconds with a trailing s, for example 30s or 1.5s. + examples: + - 30s + - 1.5s + ValidationFieldType: + type: string + title: Type + enum: + - TYPE_DOUBLE + - TYPE_FLOAT + - TYPE_INT64 + - TYPE_UINT64 + - TYPE_INT32 + - TYPE_FIXED64 + - TYPE_FIXED32 + - TYPE_BOOL + - TYPE_STRING + - TYPE_GROUP + - TYPE_MESSAGE + - TYPE_BYTES + - TYPE_UINT32 + - TYPE_ENUM + - TYPE_SFIXED32 + - TYPE_SFIXED64 + - TYPE_SINT32 + - TYPE_SINT64 + Timestamp: + type: string + examples: + - 2023-01-15T01:30:15.01Z + - 2024-12-25T12:00:00Z + format: date-time + description: An RFC 3339 timestamp in UTC, for example 2026-01-02T03:04:05Z. + BadRequest: + type: object + properties: + fieldViolations: + type: array + items: + $ref: "#/components/schemas/BadRequestFieldViolation" + description: Describes all violations in a client request. + title: BadRequest + description: |- + Describes violations in a client request. This error type focuses on the + syntactic aspects of the request. + BadRequestFieldViolation: + type: object + properties: + field: + type: string + description: |- + A path that leads to a field in the request body. The value will be a + sequence of dot-separated identifiers that identify a protocol buffer + field. + + Consider the following: + + message CreateContactRequest { + message EmailAddress { + enum Type { + TYPE_UNSPECIFIED = 0; + HOME = 1; + WORK = 2; + } + + optional string email = 1; + repeated EmailType type = 2; + } + + string full_name = 1; + repeated EmailAddress email_addresses = 2; + } + + In this example, in proto `field` could take one of the following values: + + * `full_name` for a violation in the `full_name` value + * `email_addresses[0].email` for a violation in the `email` field of the + first `email_addresses` message + * `email_addresses[2].type[1]` for a violation in the second `type` + value in the third `email_addresses` message. + + In JSON, the same values are represented as: + + * `fullName` for a violation in the `fullName` value + * `emailAddresses[0].email` for a violation in the `email` field of the + first `emailAddresses` message + * `emailAddresses[2].type[1]` for a violation in the second `type` + value in the third `emailAddresses` message. + description: + type: string + description: A description of why the request element is bad. + reason: + type: string + description: |- + The reason of the field-level error. This is a constant value that + identifies the proximate cause of the field-level error. It should + uniquely identify the type of the FieldViolation within the scope of the + ErrorInfo.domain. This should be at most 63 + characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, + which represents UPPER_SNAKE_CASE. + localizedMessage: + description: |- + Provides a localized error message for field-level errors that is safe to + return to the API consumer. + $ref: "#/components/schemas/LocalizedMessage" + title: FieldViolation + description: A message type used to describe a single bad request field. + BadRequestErrorDetail: + type: object + properties: + fieldViolations: + type: array + items: + $ref: "#/components/schemas/BadRequestFieldViolation" + description: Describes all violations in a client request. + "@type": + type: string + const: type.googleapis.com/google.rpc.BadRequest + title: BadRequestErrorDetail + description: |- + Describes violations in a client request. This error type focuses on the + syntactic aspects of the request. + required: + - "@type" + DebugInfo: + type: object + properties: + stackEntries: + type: array + items: + type: string + description: The stack trace entries indicating where the error occurred. + detail: + type: string + description: Additional debugging information provided by the server. + title: DebugInfo + description: Describes additional debugging info. + DebugInfoErrorDetail: + type: object + properties: + stackEntries: + type: array + items: + type: string + description: The stack trace entries indicating where the error occurred. + detail: + type: string + description: Additional debugging information provided by the server. + "@type": + type: string + const: type.googleapis.com/google.rpc.DebugInfo + title: DebugInfoErrorDetail + description: Describes additional debugging info. + required: + - "@type" + ErrorInfo: + type: object + properties: + reason: + type: string + description: |- + The reason of the error. This is a constant value that identifies the + proximate cause of the error. Error reasons are unique within a particular + domain of errors. This should be at most 63 characters and match a + regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents + UPPER_SNAKE_CASE. + domain: + type: string + description: |- + The logical grouping to which the "reason" belongs. The error domain + is typically the registered service name of the tool or product that + generates the error. Example: "pubsub.googleapis.com". If the error is + generated by some common infrastructure, the error domain must be a + globally unique value that identifies the infrastructure. For Google API + infrastructure, the error domain is "googleapis.com". + metadata: + type: object + additionalProperties: + type: string + title: value + description: |- + Additional structured details about this error. + + Keys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should + ideally be lowerCamelCase. Also, they must be limited to 64 characters in + length. When identifying the current value of an exceeded limit, the units + should be contained in the key, not the value. For example, rather than + `{"instanceLimit": "100/request"}`, should be returned as, + `{"instanceLimitPerRequest": "100"}`, if the client exceeds the number of + instances that can be created in a single (batch) request. + title: ErrorInfo + description: |- + Describes the cause of the error with structured details. + + Example of an error when contacting the "pubsub.googleapis.com" API when it + is not enabled: + + { "reason": "API_DISABLED" + "domain": "googleapis.com" + "metadata": { + "resource": "projects/123", + "service": "pubsub.googleapis.com" + } + } + + This response indicates that the pubsub.googleapis.com API is not enabled. + + Example of an error that is returned when attempting to create a Spanner + instance in a region that is out of stock: + + { "reason": "STOCKOUT" + "domain": "spanner.googleapis.com", + "metadata": { + "availableRegions": "us-central1,us-east2" + } + } + ErrorInfoErrorDetail: + type: object + properties: + reason: + type: string + description: |- + The reason of the error. This is a constant value that identifies the + proximate cause of the error. Error reasons are unique within a particular + domain of errors. This should be at most 63 characters and match a + regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents + UPPER_SNAKE_CASE. + domain: + type: string + description: |- + The logical grouping to which the "reason" belongs. The error domain + is typically the registered service name of the tool or product that + generates the error. Example: "pubsub.googleapis.com". If the error is + generated by some common infrastructure, the error domain must be a + globally unique value that identifies the infrastructure. For Google API + infrastructure, the error domain is "googleapis.com". + metadata: + type: object + additionalProperties: + type: string + title: value + description: |- + Additional structured details about this error. + + Keys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should + ideally be lowerCamelCase. Also, they must be limited to 64 characters in + length. When identifying the current value of an exceeded limit, the units + should be contained in the key, not the value. For example, rather than + `{"instanceLimit": "100/request"}`, should be returned as, + `{"instanceLimitPerRequest": "100"}`, if the client exceeds the number of + instances that can be created in a single (batch) request. + "@type": + type: string + const: type.googleapis.com/google.rpc.ErrorInfo + title: ErrorInfoErrorDetail + description: |- + Describes the cause of the error with structured details. + + Example of an error when contacting the "pubsub.googleapis.com" API when it + is not enabled: + + { "reason": "API_DISABLED" + "domain": "googleapis.com" + "metadata": { + "resource": "projects/123", + "service": "pubsub.googleapis.com" + } + } + + This response indicates that the pubsub.googleapis.com API is not enabled. + + Example of an error that is returned when attempting to create a Spanner + instance in a region that is out of stock: + + { "reason": "STOCKOUT" + "domain": "spanner.googleapis.com", + "metadata": { + "availableRegions": "us-central1,us-east2" + } + } + required: + - "@type" + Help: + type: object + properties: + links: + type: array + items: + $ref: "#/components/schemas/HelpLink" + description: URL(s) pointing to additional information on handling the current error. + title: Help + description: |- + Provides links to documentation or for performing an out of band action. + + For example, if a quota check failed with an error indicating the calling + project hasn't enabled the accessed service, this can contain a URL pointing + directly to the right place in the developer console to flip the bit. + HelpLink: + type: object + properties: + description: + type: string + description: Describes what the link offers. + url: + type: string + description: The URL of the link. + title: Link + description: Describes a URL link. + HelpErrorDetail: + type: object + properties: + links: + type: array + items: + $ref: "#/components/schemas/HelpLink" + description: URL(s) pointing to additional information on handling the current error. + "@type": + type: string + const: type.googleapis.com/google.rpc.Help + title: HelpErrorDetail + description: |- + Provides links to documentation or for performing an out of band action. + + For example, if a quota check failed with an error indicating the calling + project hasn't enabled the accessed service, this can contain a URL pointing + directly to the right place in the developer console to flip the bit. + required: + - "@type" + LocalizedMessage: + type: object + properties: + locale: + type: string + description: |- + The locale used following the specification defined at + https://www.rfc-editor.org/rfc/bcp/bcp47.txt. + Examples are: "en-US", "fr-CH", "es-MX" + message: + type: string + description: The localized error message in the above locale. + title: LocalizedMessage + description: |- + Provides a localized error message that is safe to return to the user + which can be attached to an operation error. + LocalizedMessageErrorDetail: + type: object + properties: + locale: + type: string + description: |- + The locale used following the specification defined at + https://www.rfc-editor.org/rfc/bcp/bcp47.txt. + Examples are: "en-US", "fr-CH", "es-MX" + message: + type: string + description: The localized error message in the above locale. + "@type": + type: string + const: type.googleapis.com/google.rpc.LocalizedMessage + title: LocalizedMessageErrorDetail + description: |- + Provides a localized error message that is safe to return to the user + which can be attached to an operation error. + required: + - "@type" + PreconditionFailure: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/PreconditionFailureViolation" + description: Describes all precondition violations. + title: PreconditionFailure + description: |- + Describes what preconditions have failed. + + For example, if an operation failed because it required the Terms of Service to be + acknowledged, it could list the terms of service violation in the + PreconditionFailure message. + PreconditionFailureViolation: + type: object + properties: + type: + type: string + description: |- + The type of PreconditionFailure. We recommend using a service-specific + enum type to define the supported precondition violation subjects. For + example, "TOS" for "Terms of Service violation". + subject: + type: string + description: |- + The subject, relative to the type, that failed. + For example, "google.com/cloud" relative to the "TOS" type would indicate + which terms of service is being referenced. + description: + type: string + description: |- + A description of how the precondition failed. Developers can use this + description to understand how to fix the failure. + + For example: "Terms of service not accepted". + title: Violation + description: A message type used to describe a single precondition failure. + PreconditionFailureErrorDetail: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/PreconditionFailureViolation" + description: Describes all precondition violations. + "@type": + type: string + const: type.googleapis.com/google.rpc.PreconditionFailure + title: PreconditionFailureErrorDetail + description: |- + Describes what preconditions have failed. + + For example, if an operation failed because it required the Terms of Service to be + acknowledged, it could list the terms of service violation in the + PreconditionFailure message. + required: + - "@type" + QuotaFailure: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/QuotaFailureViolation" + description: Describes all quota violations. + title: QuotaFailure + description: |- + Describes how a quota check failed. + + For example if a daily limit was exceeded for the calling project, + a service could respond with a QuotaFailure detail containing the project + id and the description of the quota limit that was exceeded. If the + calling project hasn't enabled the service in the developer console, then + a service could respond with the project id and set `service_disabled` + to true. + + Also see RetryInfo and Help types for other details about handling a + quota failure. + QuotaFailureViolation: + type: object + properties: + subject: + type: string + description: |- + The subject on which the quota check failed. + For example, "clientip:" or "project:". + description: + type: string + description: |- + A description of how the quota check failed. Clients can use this + description to find more about the quota configuration in the service's + public documentation, or find the relevant quota limit to adjust through + developer console. + + For example: "Service disabled" or "Daily Limit for read operations + exceeded". + apiService: + type: string + description: |- + The API Service from which the `QuotaFailure.Violation` orginates. In + some cases, Quota issues originate from an API Service other than the one + that was called. In other words, a dependency of the called API Service + could be the cause of the `QuotaFailure`, and this field would have the + dependency API service name. + + For example, if the called API is Kubernetes Engine API + (container.googleapis.com), and a quota violation occurs in the + Kubernetes Engine API itself, this field would be + "container.googleapis.com". On the other hand, if the quota violation + occurs when the Kubernetes Engine API creates VMs in the Compute Engine + API (compute.googleapis.com), this field would be + "compute.googleapis.com". + quotaMetric: + type: string + description: |- + The metric of the violated quota. A quota metric is a named counter to + measure usage, such as API requests or CPUs. When an activity occurs in a + service, such as Virtual Machine allocation, one or more quota metrics + may be affected. + + For example, "compute.googleapis.com/cpus_per_vm_family", + "storage.googleapis.com/internet_egress_bandwidth". + quotaId: + type: string + description: |- + The id of the violated quota. Also know as "limit name", this is the + unique identifier of a quota in the context of an API service. + + For example, "CPUS-PER-VM-FAMILY-per-project-region". + quotaDimensions: + type: object + additionalProperties: + type: string + title: value + description: |- + The dimensions of the violated quota. Every non-global quota is enforced + on a set of dimensions. While quota metric defines what to count, the + dimensions specify for what aspects the counter should be increased. + + For example, the quota "CPUs per region per VM family" enforces a limit + on the metric "compute.googleapis.com/cpus_per_vm_family" on dimensions + "region" and "vm_family". And if the violation occurred in region + "us-central1" and for VM family "n1", the quota_dimensions would be, + + { + "region": "us-central1", + "vm_family": "n1", + } + + When a quota is enforced globally, the quota_dimensions would always be + empty. + quotaValue: + type: + - integer + - string + format: int64 + description: |- + The enforced quota value at the time of the `QuotaFailure`. + + For example, if the enforced quota value at the time of the + `QuotaFailure` on the number of CPUs is "10", then the value of this + field would reflect this quantity. + futureQuotaValue: + type: + - integer + - string + - "null" + format: int64 + description: |- + The new quota value being rolled out at the time of the violation. At the + completion of the rollout, this value will be enforced in place of + quota_value. If no rollout is in progress at the time of the violation, + this field is not set. + + For example, if at the time of the violation a rollout is in progress + changing the number of CPUs quota from 10 to 20, 20 would be the value of + this field. + title: Violation + description: |- + A message type used to describe a single quota violation. For example, a + daily quota or a custom quota that was exceeded. + QuotaFailureErrorDetail: + type: object + properties: + violations: + type: array + items: + $ref: "#/components/schemas/QuotaFailureViolation" + description: Describes all quota violations. + "@type": + type: string + const: type.googleapis.com/google.rpc.QuotaFailure + title: QuotaFailureErrorDetail + description: |- + Describes how a quota check failed. + + For example if a daily limit was exceeded for the calling project, + a service could respond with a QuotaFailure detail containing the project + id and the description of the quota limit that was exceeded. If the + calling project hasn't enabled the service in the developer console, then + a service could respond with the project id and set `service_disabled` + to true. + + Also see RetryInfo and Help types for other details about handling a + quota failure. + required: + - "@type" + RequestInfo: + type: object + properties: + requestId: + type: string + description: |- + An opaque string that should only be interpreted by the service generating + it. For example, it can be used to identify requests in the service's logs. + servingData: + type: string + description: |- + Any data that was used to serve this request. For example, an encrypted + stack trace that can be sent back to the service provider for debugging. + title: RequestInfo + description: |- + Contains metadata about the request that clients can attach when filing a bug + or providing other forms of feedback. + RequestInfoErrorDetail: + type: object + properties: + requestId: + type: string + description: |- + An opaque string that should only be interpreted by the service generating + it. For example, it can be used to identify requests in the service's logs. + servingData: + type: string + description: |- + Any data that was used to serve this request. For example, an encrypted + stack trace that can be sent back to the service provider for debugging. + "@type": + type: string + const: type.googleapis.com/google.rpc.RequestInfo + title: RequestInfoErrorDetail + description: |- + Contains metadata about the request that clients can attach when filing a bug + or providing other forms of feedback. + required: + - "@type" + ResourceInfo: + type: object + properties: + resourceType: + type: string + description: |- + A name for the type of resource being accessed, e.g. "sql table", + "cloud storage bucket", "file", "Google calendar"; or the type URL + of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". + resourceName: + type: string + description: |- + The name of the resource being accessed. For example, a shared calendar + name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current + error is + [CodePERMISSION_DENIED][CodePERMISSION_DENIED]. + owner: + type: string + description: |- + The owner of the resource (optional). + For example, "user:" or "project:". + description: + type: string + description: |- + Describes what error is encountered when accessing this resource. + For example, updating a cloud project may require the `writer` permission + on the developer console project. + title: ResourceInfo + description: Describes the resource that is being accessed. + ResourceInfoErrorDetail: + type: object + properties: + resourceType: + type: string + description: |- + A name for the type of resource being accessed, e.g. "sql table", + "cloud storage bucket", "file", "Google calendar"; or the type URL + of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". + resourceName: + type: string + description: |- + The name of the resource being accessed. For example, a shared calendar + name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current + error is + [CodePERMISSION_DENIED][CodePERMISSION_DENIED]. + owner: + type: string + description: |- + The owner of the resource (optional). + For example, "user:" or "project:". + description: + type: string + description: |- + Describes what error is encountered when accessing this resource. + For example, updating a cloud project may require the `writer` permission + on the developer console project. + "@type": + type: string + const: type.googleapis.com/google.rpc.ResourceInfo + title: ResourceInfoErrorDetail + description: Describes the resource that is being accessed. + required: + - "@type" + RetryInfo: + type: object + properties: + retryDelay: + description: Clients should wait at least this long between retrying the same request. + $ref: "#/components/schemas/Duration" + title: RetryInfo + description: |- + Describes when the clients can retry a failed request. Clients could ignore + the recommendation here or retry when this information is missing from error + responses. + + It's always recommended that clients should use exponential backoff when + retrying. + + Clients should wait until `retry_delay` amount of time has passed since + receiving the error response before retrying. If retrying requests also + fail, clients should use an exponential backoff scheme to gradually increase + the delay between retries based on `retry_delay`, until either a maximum + number of retries have been reached or a maximum retry delay cap has been + reached. + RetryInfoErrorDetail: + type: object + properties: + retryDelay: + description: Clients should wait at least this long between retrying the same request. + $ref: "#/components/schemas/Duration" + "@type": + type: string + const: type.googleapis.com/google.rpc.RetryInfo + title: RetryInfoErrorDetail + description: |- + Describes when the clients can retry a failed request. Clients could ignore + the recommendation here or retry when this information is missing from error + responses. + + It's always recommended that clients should use exponential backoff when + retrying. + + Clients should wait until `retry_delay` amount of time has passed since + receiving the error response before retrying. If retrying requests also + fail, clients should use an exponential backoff scheme to gradually increase + the delay between retries based on `retry_delay`, until either a maximum + number of retries have been reached or a maximum retry delay cap has been + reached. + required: + - "@type" + UpdateSecretBody: + type: object + allOf: + - properties: + serviceType: + type: string + description: service_type identifies the consuming service. + - oneOf: + - type: object + properties: + custom: + description: |- + custom stores an opaque value with caller-authored injection metadata. + UpdateSecretRequest.service_type is server-assigned for custom + material; leave it empty. + $ref: "#/components/schemas/CustomSecretMaterial" + title: custom + required: + - custom + - type: object + properties: + oauth: + description: oauth stores OAuth refresh material. + $ref: "#/components/schemas/OAuthRefreshMaterial" + title: oauth + required: + - oauth + - type: object + properties: + token: + description: token stores opaque token material. + $ref: "#/components/schemas/TokenSecretMaterial" + title: token + required: + - token + title: UpdateSecretRequest + unevaluatedProperties: false + description: |- + UpdateSecretRequest replaces secret material. + service_type must be empty for custom material (server-assigned) + securitySchemes: + bearer: + type: http + scheme: bearer + description: A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions. + sandboxBearer: + type: http + scheme: bearer + description: A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted. + sandboxWebSocketBearer: + type: apiKey + in: header + name: Sec-WebSocket-Protocol + description: Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization. +security: + - bearer: [] +tags: + - name: Files + description: Read, write, copy, and manage files inside a sandbox. + x-displayName: Files + kind: nav + summary: Files + - name: Processes + description: Run commands and interact with processes inside a sandbox. + x-displayName: Processes + kind: nav + summary: Processes + - name: Credentials + description: Exchange credentials for the authenticated owner. + x-displayName: Credentials + kind: nav + summary: Credentials + - name: Images + description: Manage images used to create sandboxes. + x-displayName: Images + kind: nav + summary: Images + - name: MCP gateways + description: Configure MCP gateways and authorize upstream servers. + x-displayName: MCP gateways + kind: nav + summary: MCP gateways + - name: Network policies + description: Read enforced outbound network policies and their decision logs. + x-displayName: Network policies + kind: nav + summary: Network policies + - name: Sandboxes + description: Create sandboxes and manage their lifecycle, ports, and SSH access. + x-displayName: Sandboxes + kind: nav + summary: Sandboxes + - name: Secrets + description: Store credentials and read their metadata without returning secret material. + x-displayName: Secrets + kind: nav + summary: Secrets + - name: Snapshots + description: Capture sandbox state and restore it into a new sandbox. + x-displayName: Snapshots + kind: nav + summary: Snapshots + - name: Volumes + description: Manage persistent storage and attach it to sandboxes. + x-displayName: Volumes + kind: nav + summary: Volumes +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md index 663292ca4b7b..1d49b79f0e4c 100644 --- a/content/reference/compose-file/build.md +++ b/content/reference/compose-file/build.md @@ -348,21 +348,19 @@ build: ### `network` -Set the network containers connect to for the `RUN` instructions during build. +Set the networking mode for `RUN` instructions during the build. This is +the same as [`docker build --network`](/reference/cli/docker/buildx/build/#network). +It is not a Compose network from the top-level [`networks`](networks.md) key. -```yaml -build: - context: . - network: host -``` +The value is a mode (`default`, `none`, or `host`), not a network name: ```yaml build: context: . - network: custom_network_1 + network: host ``` -Use `none` to disable networking during build: +Use `none` to disable networking during the build: ```yaml build: diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md index 4f49b0fa0186..4fd1edab779c 100644 --- a/content/reference/compose-file/develop.md +++ b/content/reference/compose-file/develop.md @@ -11,7 +11,7 @@ weight: 150 > > Develop is an optional part of the Compose Specification. It is available with Docker Compose version 2.22.0 and later. -{{% include "compose/develop.md" %}} +{{% include "compose/services-develop.md" %}} This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of Compose file services may require a `develop` subsection. diff --git a/content/reference/compose-file/models.md b/content/reference/compose-file/models.md index 631bdf8e6113..434f082468ec 100644 --- a/content/reference/compose-file/models.md +++ b/content/reference/compose-file/models.md @@ -66,4 +66,4 @@ In this advanced setup: ## Additional resources -For more examples and information on using `model`, see [Use AI models in Compose](/manuals/ai/compose/models-and-compose.md) \ No newline at end of file +For more examples and information on using `model`, see [Use AI models in Compose](/manuals/compose/how-tos/models-and-compose.md) \ No newline at end of file diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 9bbe421dc891..59ceb4e44fe7 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -1294,7 +1294,7 @@ There is a performance penalty for applications that swap memory to disk often. - If `memswap_limit` is set to a positive integer, then both `memory` and `memswap_limit` must be set. `memswap_limit` represents the total amount of memory and swap that can be used, and `memory` controls the amount used by non-swap memory. So if `memory`="300m" and `memswap_limit`="1g", the container can use 300m of memory and 700m (1g - 300m) swap. - If `memswap_limit` is set to 0, the setting is ignored, and the value is treated as unset. - If `memswap_limit` is set to the same value as `memory`, and `memory` is set to a positive integer, the container does not have access to swap. -- If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap. +- If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap. - If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system. ### `models` @@ -1752,13 +1752,56 @@ services: For more information, see [Use lifecycle hooks](/manuals/compose/how-tos/lifecycle.md). +### pre_start + +{{< summary-bar feature_name="Compose pre_start" >}} + +`pre_start` defines a sequence of init containers to run before the service container is started. Each step runs to completion, in declared order, and the service container only starts once every step has exited `0`. A non-zero exit fails the bring-up of the service and its dependents. + +Unlike `post_start` and `pre_stop`, which run a command inside the running service container, each `pre_start` step runs in its own ephemeral container, created after the service container is created but before it is started. Possible values are: + +- `command`: The command to run. Optional when the chosen image's entrypoint already runs the intended command. +- `image`: The image used for the ephemeral container. If omitted, the parent service's image is used. +- `user`: The user to run the command. If not set, defaults to the user declared in `image` (or to the main service command's user when `image` is omitted). +- `privileged`: Lets the `pre_start` command run with privileged access. +- `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command. +- `environment`: Sets the environment variables to run the `pre_start` command. The command inherits the `environment` set for the service's main command, and this section lets you append or override values. +- `per_replica: false`: Whether the step runs once for the service as a whole before any replica starts. + +`pre_start` steps only run once the service's `depends_on` conditions have been satisfied, so a step can rely on those dependencies the same way the main service command does. A`pre_start` container joins the same networks as the service, so it can reach services declared in `depends_on`, and shares the service's declared volume mounts so files it produces in a shared volume are visible to the service. + +With `per_replica: false` and a scaled service, only mounts that are shared across replicas (named volumes, bind mounts) are usable. Per-instance mounts (`tmpfs`, anonymous volumes) cannot be addressed by a single run. This is not an error. The steps run without access to per-instance mounts. Data a `per_replica: false` step must share with the service belongs in a named volume or bind mount. + +A `pre_start` step that has already succeeded for its current definition is not re-run on a subsequent `up`, nor when the service container restarts under its `restart` policy. A step runs again when its definition changes, when the previous run did not succeed, or when the service is recreated. For example, after a change to the service configuration or an explicit forced recreation. + +```yaml +services: + app: + image: myapp:latest + depends_on: + db: + condition: service_healthy + pre_start: + - command: ["./manage.py", "migrate"] + - image: busybox + command: sh -c 'chown -R 1000:1000 /data' + volumes: + - data:/data + + db: + image: postgres:16 + +volumes: + data: +``` + ### `pre_stop` {{< summary-bar feature_name="Compose pre stop" >}} `pre_stop` defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly. -Configuration is equivalent to [post_start](#post_start). +Configuration is equivalent to [`post_start`](#post_start). ### `privileged` diff --git a/data/api-reference.json b/data/api-reference.json new file mode 100644 index 000000000000..3481547983c6 --- /dev/null +++ b/data/api-reference.json @@ -0,0 +1,52642 @@ +{ + "apis": [ + { + "connection": "hosted", + "description": "Docker Hub is a service provided by Docker for finding and sharing container images with your team.\n\nIt is the world's largest library and community for container images.\n\nIn addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub.\n\nBrowse through the Docker Hub API documentation to explore the supported endpoints.\n", + "diagnostics": [], + "digest": "7c280db399f81e7eaaf40c86b7cdfd9317c819b7589353e3a26e78d6a5a8d373", + "exampleCount": 315, + "experimental": false, + "guides": [ + "/manuals/security/provisioning/scim/provision-scim.md" + ], + "id": "hub", + "manual": "/manuals/docker-hub/", + "operations": [ + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/access-tokens'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a paginated list of personal access tokens.", + "id": "getV2AccessTokens", + "line": 327, + "method": "GET", + "parameters": [ + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1access-tokens/get/parameters/0", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1access-tokens/get/parameters/1", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + } + ], + "path": "/v2/access-tokens", + "pointer": "/paths/~1v2~1access-tokens/get", + "raw": { + "description": "Returns a paginated list of personal access tokens.", + "operationId": "getV2AccessTokens", + "parameters": [ + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/getAccessTokensResponse" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List personal access tokens", + "tags": [ + "access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/responses/BadRequest", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/getAccessTokensResponse", + "url": "/reference/api/hub/latest/schemas/getAccessTokensResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List personal access tokens", + "tags": [ + "access-tokens" + ], + "url": "/reference/api/hub/latest/operations/getV2AccessTokens/", + "variants": [ + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"active_count\": 1,\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"client_id\": \"HUB\",\n \"created_at\": \"2021-07-20T12:00:00.000000Z\",\n \"creator_ip\": \"127.0.0.1\",\n \"creator_ua\": \"some user agent\",\n \"expires_at\": \"2021-10-28T18:30:19.520861Z\",\n \"generated_by\": \"manual\",\n \"is_active\": true,\n \"last_used\": null,\n \"scopes\": [\n \"repo:read\"\n ],\n \"token\": \"***\",\n \"token_label\": \"My read only token\",\n \"uuid\": \"b30bbf97-506c-4ecd-aabc-842f3cb484fb\"\n }\n ]\n}", + "value": { + "active_count": 1, + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/getAccessTokensResponse" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/get/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"scopes\": [\n \"repo:read\"\n ],\n \"token_label\": \"My read only token\"\n}' \\\n 'https://hub.docker.com/v2/access-tokens'", + "curlNotes": [], + "deprecated": null, + "description": "Creates and returns a personal access token.", + "id": "postV2AccessTokens", + "line": 302, + "method": "POST", + "parameters": [], + "path": "/v2/access-tokens", + "pointer": "/paths/~1v2~1access-tokens/post", + "raw": { + "description": "Creates and returns a personal access token.", + "operationId": "postV2AccessTokens", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/createAccessTokenRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/createAccessTokensResponse" + } + } + }, + "description": "Created" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create personal access token", + "tags": [ + "access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/BadRequest", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/createAccessTokenRequest", + "url": "/reference/api/hub/latest/schemas/createAccessTokenRequest/" + }, + { + "ref": "#/components/schemas/createAccessTokensResponse", + "url": "/reference/api/hub/latest/schemas/createAccessTokensResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/createAccessTokenRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create personal access token", + "tags": [ + "access-tokens" + ], + "url": "/reference/api/hub/latest/operations/postV2AccessTokens/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"scopes\": [\n \"repo:read\"\n ],\n \"token_label\": \"My read only token\"\n}", + "value": { + "scopes": [ + "repo:read" + ], + "token_label": "My read only token" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/createAccessTokenRequest" + }, + "status": "" + }, + { + "description": "Created", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"client_id\": \"HUB\",\n \"created_at\": \"2021-07-20T12:00:00.000000Z\",\n \"creator_ip\": \"127.0.0.1\",\n \"creator_ua\": \"some user agent\",\n \"expires_at\": \"2021-10-28T18:30:19.520861Z\",\n \"generated_by\": \"manual\",\n \"is_active\": true,\n \"last_used\": null,\n \"scopes\": [\n \"repo:read\"\n ],\n \"token\": \"a7a5ef25-8889-43a0-8cc7-f2a94268e861\",\n \"token_label\": \"My read only token\",\n \"uuid\": \"b30bbf97-506c-4ecd-aabc-842f3cb484fb\"\n}", + "value": { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/createAccessTokensResponse" + }, + "status": "201" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/access-tokens/\u003cUUID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a personal access token by UUID.", + "id": "getV2AccessTokensByUuid", + "line": 383, + "method": "GET", + "parameters": [ + { + "description": "UUID of the personal access token.", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/access-tokens/{uuid}", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/get", + "raw": { + "description": "Returns a personal access token by UUID.", + "operationId": "getV2AccessTokensByUuid", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/accessToken" + }, + { + "properties": { + "token": { + "example": "***", + "type": "string" + } + }, + "type": "object" + } + ], + "examples": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get personal access token", + "tags": [ + "access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/accessToken", + "url": "/reference/api/hub/latest/schemas/accessToken/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get personal access token", + "tags": [ + "access-tokens" + ], + "url": "/reference/api/hub/latest/operations/getV2AccessTokensByUuid/", + "variants": [ + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"client_id\": \"HUB\",\n \"created_at\": \"2021-07-20T12:00:00.000000Z\",\n \"creator_ip\": \"127.0.0.1\",\n \"creator_ua\": \"some user agent\",\n \"expires_at\": \"2021-10-28T18:30:19.520861Z\",\n \"generated_by\": \"manual\",\n \"is_active\": true,\n \"last_used\": null,\n \"scopes\": [\n \"repo:read\"\n ],\n \"token\": \"***\",\n \"token_label\": \"My read only token\",\n \"uuid\": \"b30bbf97-506c-4ecd-aabc-842f3cb484fb\"\n}", + "value": { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/accessToken" + }, + { + "properties": { + "token": { + "example": "***", + "type": "string" + } + }, + "type": "object" + } + ], + "examples": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/access-tokens/\u003cUUID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Deletes a personal access token permanently. This cannot be undone.\n", + "id": "deleteV2AccessTokensByUuid", + "line": 422, + "method": "DELETE", + "parameters": [ + { + "description": "UUID of the personal access token.", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/access-tokens/{uuid}", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/delete", + "raw": { + "description": "Deletes a personal access token permanently. This cannot be undone.\n", + "operationId": "deleteV2AccessTokensByUuid", + "responses": { + "204": { + "description": "A successful response." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Delete personal access token", + "tags": [ + "access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Delete personal access token", + "tags": [ + "access-tokens" + ], + "url": "/reference/api/hub/latest/operations/deleteV2AccessTokensByUuid/", + "variants": [ + { + "description": "A successful response.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/delete/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"is_active\": false,\n \"token_label\": \"My read only token\"\n}' \\\n 'https://hub.docker.com/v2/access-tokens/\u003cUUID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Updates a personal access token partially. You can either update the token's label or enable/disable it.\n", + "id": "patchV2AccessTokensByUuid", + "line": 357, + "method": "PATCH", + "parameters": [ + { + "description": "UUID of the personal access token.", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/access-tokens/{uuid}", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/patch", + "raw": { + "description": "Updates a personal access token partially. You can either update the token's label or enable/disable it.\n", + "operationId": "patchV2AccessTokensByUuid", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/patchAccessTokenRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/patchAccessTokenResponse" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update personal access token", + "tags": [ + "access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/BadRequest", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/patchAccessTokenRequest", + "url": "/reference/api/hub/latest/schemas/patchAccessTokenRequest/" + }, + { + "ref": "#/components/schemas/patchAccessTokenResponse", + "url": "/reference/api/hub/latest/schemas/patchAccessTokenResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/patchAccessTokenRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update personal access token", + "tags": [ + "access-tokens" + ], + "url": "/reference/api/hub/latest/operations/patchV2AccessTokensByUuid/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"is_active\": false,\n \"token_label\": \"My read only token\"\n}", + "value": { + "is_active": false, + "token_label": "My read only token" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/patchAccessTokenRequest" + }, + "status": "" + }, + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"client_id\": \"HUB\",\n \"created_at\": \"2021-07-20T12:00:00.000000Z\",\n \"creator_ip\": \"127.0.0.1\",\n \"creator_ua\": \"some user agent\",\n \"expires_at\": \"2021-10-28T18:30:19.520861Z\",\n \"generated_by\": \"manual\",\n \"is_active\": true,\n \"last_used\": null,\n \"scopes\": [\n \"repo:read\"\n ],\n \"token\": \"***\",\n \"token_label\": \"My read only token\",\n \"uuid\": \"b30bbf97-506c-4ecd-aabc-842f3cb484fb\"\n}", + "value": { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/patchAccessTokenResponse" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/patch/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1access-tokens~1{uuid}/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/auditlogs/\u003cACCOUNT\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "List audit log events for a given namespace.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "AuditLogs_ListAuditLogs", + "line": 746, + "method": "GET", + "parameters": [ + { + "description": "Namespace to query audit logs for.", + "in": "path", + "name": "account", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "action name one of [\"repo.tag.push\", ...]. Optional parameter to filter specific audit log actions.\n", + "in": "query", + "name": "action", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/1", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member.\n", + "in": "query", + "name": "name", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/2", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "actor name. Optional parameter to filter audit log events to the specific user who triggered the event.\n", + "in": "query", + "name": "actor", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/3", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Start of the time window you wish to query audit events for.", + "in": "query", + "name": "from", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/4", + "required": false, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "End of the time window you wish to query audit events for.", + "in": "query", + "name": "to", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/5", + "required": false, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/6", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/parameters/7", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + } + ], + "path": "/v2/auditlogs/{account}", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get", + "raw": { + "description": "List audit log events for a given namespace.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "AuditLogs_ListAuditLogs", + "parameters": [ + { + "description": "Namespace to query audit logs for.", + "in": "path", + "name": "account", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "action name one of [\"repo.tag.push\", ...]. Optional parameter to filter specific audit log actions.\n", + "in": "query", + "name": "action", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member.\n", + "in": "query", + "name": "name", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "actor name. Optional parameter to filter audit log events to the specific user who triggered the event.\n", + "in": "query", + "name": "actor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Start of the time window you wish to query audit events for.", + "in": "query", + "name": "from", + "required": false, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "End of the time window you wish to query audit events for.", + "in": "query", + "name": "to", + "required": false, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "response": { + "value": { + "logs": [ + { + "account": "docker", + "action": "repo.tag.push", + "action_description": "pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example\n", + "actor": "docker", + "data": { + "digest": "sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa", + "tag": "latest" + }, + "name": "docker/example", + "timestamp": "2021-02-19T01:34:35Z" + }, + { + "account": "docker", + "action": "offload.lease.end", + "action_description": "offload lease 'l_3EgPuRCjtUqT279CFPOQWcO8zOf' ended, ran for '12m22s'", + "actor": "docker", + "data": { + "lease_id": "l_3EgPuRCjtUqT279CFPOQWcO8zOf", + "org_id": "b908ca6e-b9a9-4a53-a9a5-6bec96f72432", + "resource_type": "run_4cpu_8mem", + "started_at": "2026-06-04T18:24:21Z", + "updated_at": "2026-06-04T18:36:43Z", + "user_id": "ecae6747-e42c-43cb-925d-cfce1ab32b02" + }, + "name": "docker", + "timestamp": "2026-06-04T18:36:43Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/GetAuditLogsResponse" + } + } + }, + "description": "A successful response." + }, + "429": { + "content": { + "application/json": { + "examples": { + "response": { + "value": { + "detail": "Rate limit exceeded", + "error": false + } + } + }, + "schema": {} + } + }, + "description": "" + }, + "500": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "internal error" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "" + }, + "default": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "internal error" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "An unexpected error response." + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List audit log events", + "tags": [ + "audit-logs" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/schemas/GetAuditLogsResponse", + "url": "/reference/api/hub/latest/schemas/GetAuditLogsResponse/" + }, + { + "ref": "#/components/schemas/error", + "url": "/reference/api/hub/latest/schemas/error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List audit log events", + "tags": [ + "audit-logs" + ], + "url": "/reference/api/hub/latest/operations/AuditLogs_ListAuditLogs/", + "variants": [ + { + "description": "A successful response.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "response", + "text": "{\n \"logs\": [\n {\n \"account\": \"docker\",\n \"action\": \"repo.tag.push\",\n \"action_description\": \"pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example\\n\",\n \"actor\": \"docker\",\n \"data\": {\n \"digest\": \"sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa\",\n \"tag\": \"latest\"\n },\n \"name\": \"docker/example\",\n \"timestamp\": \"2021-02-19T01:34:35Z\"\n },\n {\n \"account\": \"docker\",\n \"action\": \"offload.lease.end\",\n \"action_description\": \"offload lease 'l_3EgPuRCjtUqT279CFPOQWcO8zOf' ended, ran for '12m22s'\",\n \"actor\": \"docker\",\n \"data\": {\n \"lease_id\": \"l_3EgPuRCjtUqT279CFPOQWcO8zOf\",\n \"org_id\": \"b908ca6e-b9a9-4a53-a9a5-6bec96f72432\",\n \"resource_type\": \"run_4cpu_8mem\",\n \"started_at\": \"2026-06-04T18:24:21Z\",\n \"updated_at\": \"2026-06-04T18:36:43Z\",\n \"user_id\": \"ecae6747-e42c-43cb-925d-cfce1ab32b02\"\n },\n \"name\": \"docker\",\n \"timestamp\": \"2026-06-04T18:36:43Z\"\n }\n ]\n}", + "value": { + "logs": [ + { + "account": "docker", + "action": "repo.tag.push", + "action_description": "pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example\n", + "actor": "docker", + "data": { + "digest": "sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa", + "tag": "latest" + }, + "name": "docker/example", + "timestamp": "2021-02-19T01:34:35Z" + }, + { + "account": "docker", + "action": "offload.lease.end", + "action_description": "offload lease 'l_3EgPuRCjtUqT279CFPOQWcO8zOf' ended, ran for '12m22s'", + "actor": "docker", + "data": { + "lease_id": "l_3EgPuRCjtUqT279CFPOQWcO8zOf", + "org_id": "b908ca6e-b9a9-4a53-a9a5-6bec96f72432", + "resource_type": "run_4cpu_8mem", + "started_at": "2026-06-04T18:24:21Z", + "updated_at": "2026-06-04T18:36:43Z", + "user_id": "ecae6747-e42c-43cb-925d-cfce1ab32b02" + }, + "name": "docker", + "timestamp": "2026-06-04T18:36:43Z" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/GetAuditLogsResponse" + }, + "status": "200" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "response", + "text": "{\n \"detail\": \"Rate limit exceeded\",\n \"error\": false\n}", + "value": { + "detail": "Rate limit exceeded", + "error": false + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/responses/429/content/application~1json", + "required": null, + "schema": {}, + "status": "429" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + }, + { + "description": "An unexpected error response.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/auditlogs/\u003cACCOUNT\u003e/actions'", + "curlNotes": [], + "deprecated": null, + "description": "List audit log actions for a namespace to be used as a filter for querying audit log events.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "AuditLogs_ListAuditActions", + "line": 439, + "method": "GET", + "parameters": [ + { + "description": "Namespace to query audit log actions for.", + "in": "path", + "name": "account", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/auditlogs/{account}/actions", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get", + "raw": { + "description": "List audit log actions for a namespace to be used as a filter for querying audit log events.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "AuditLogs_ListAuditActions", + "parameters": [ + { + "description": "Namespace to query audit log actions for.", + "in": "path", + "name": "account", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "response": { + "value": { + "actions": { + "billing": { + "actions": [ + { + "description": "Occurs when your organization’s billing plan is upgraded to a higher tier plan.", + "label": "Plan Upgraded", + "name": "plan.upgrade" + }, + { + "description": "Occurs when your organization’s billing plan is downgraded to a lower tier plan.", + "label": "Plan Downgraded", + "name": "plan.downgrade" + }, + { + "description": "Occurs when a seat is added to your organization’s billing plan.", + "label": "Seat Added", + "name": "plan.seat_add" + }, + { + "description": "Occurs when a seat is removed from your organization’s billing plan.", + "label": "Seat Removed", + "name": "plan.seat_remove" + }, + { + "description": "Occurs when there is a change in the recurring interval that your organization is charged.", + "label": "Billing Cycle Changed", + "name": "plan.cycle_change" + }, + { + "description": "Occurs when a scheduled plan downgrade for your organization is canceled.", + "label": "Plan Downgrade Canceled", + "name": "plan.downgrade_cancel" + }, + { + "description": "Occurs when a scheduled seat removal for an organization’s billing plan is canceled.", + "label": "Seat Removal Canceled", + "name": "plan.seat_removal_cancel" + }, + { + "description": "Occurs when a user in your organization requests a plan upgrade.", + "label": "Plan Upgrade Requested", + "name": "plan.upgrade.request" + }, + { + "description": "Occurs when a user in your organization requests a plan downgrade.", + "label": "Plan Downgrade Requested", + "name": "plan.downgrade.request" + }, + { + "description": "Occurs when a user in your organization requests an increase in the number of seats.", + "label": "Seat Addition Requested", + "name": "plan.seat_add.request" + }, + { + "description": "Occurs when a user in your organization requests a decrease in the number of seats.", + "label": "Seat Removal Requested", + "name": "plan.seat_removal.request" + }, + { + "description": "Occurs when a user in your organization requests a change in the billing cycle.", + "label": "Billing Cycle Change Requested", + "name": "plan.cycle_change.request" + }, + { + "description": "Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade.", + "label": "Plan Downgrade Cancellation Requested", + "name": "plan.downgrade_cancel.request" + }, + { + "description": "Occurs when a user in your organization requests a cancellation of a scheduled seat removal.", + "label": "Seat Removal Cancellation Requested", + "name": "plan.seat_removal_cancel.request" + }, + { + "description": "Occurs when there is a change in the product that your organization subscribes to.", + "label": "Billing Product Changed", + "name": "plan.product_change" + } + ], + "label": "Billing" + }, + "enterprise": { + "actions": [ + { + "description": "Details of adding an admin settings policy", + "label": "Policy created", + "name": "setting.policy.create" + }, + { + "description": "Details of updating an admin settings policy", + "label": "Policy updated", + "name": "setting.policy.update" + }, + { + "description": "Details of deleting an admin settings policy", + "label": "Policy deleted", + "name": "setting.policy.delete" + }, + { + "description": "Details of transferring an admin settings policy to another owner", + "label": "Policy transferred", + "name": "setting.policy.transfer" + }, + { + "description": "Details of creating a new org/company SSO connection", + "label": "Create SSO Connection", + "name": "sso.connection.create" + }, + { + "description": "Details of updating an existing org/company SSO connection", + "label": "Update SSO Connection", + "name": "sso.connection.update" + }, + { + "description": "Details of deleting an existing org/company SSO connection", + "label": "Delete SSO Connection", + "name": "sso.connection.delete" + }, + { + "description": "Details of toggling enforcement on an existing org/company SSO connection", + "label": "Enforce SSO", + "name": "sso.connection.enforcement_toggle" + }, + { + "description": "Details of toggling SCIM on an existing org/company SSO connection", + "label": "Enforce SCIM", + "name": "sso.connection.scim_toggle" + }, + { + "description": "Details of a SCIM token refresh on an existing org/company SSO connection", + "label": "Refresh SCIM Token", + "name": "sso.connection.scim_token_refresh" + }, + { + "description": "Details of a connection type change on an existing org/company SSO connection", + "label": "Change SSO Connection Type", + "name": "sso.connection.connection_type_change" + }, + { + "description": "Details of a JIT toggle on an existing org/company SSO connection", + "label": "Toggle JIT provisioning", + "name": "sso.connection.jit_toggle" + } + ], + "label": "Enterprise" + }, + "offload": { + "actions": [ + { + "description": "Details of the started Offload lease.", + "label": "Offload lease start", + "name": "lease.start" + }, + { + "description": "Details of the ended Offload lease.", + "label": "Offload lease end", + "name": "lease.end" + } + ], + "label": "Offload" + }, + "oidc": { + "actions": [ + { + "description": "Details of creating an OIDC connection.", + "label": "OIDC connection created", + "name": "connection.create" + }, + { + "description": "Details of updating an OIDC connection.", + "label": "OIDC connection updated", + "name": "connection.update" + }, + { + "description": "Details of deleting an OIDC connection.", + "label": "OIDC connection deleted", + "name": "connection.delete" + } + ], + "label": "OIDC" + }, + "org": { + "actions": [ + { + "description": "Activities related to the creation of a new organization", + "label": "Organization Created", + "name": "create" + }, + { + "description": "Details of the member added to your organization", + "label": "Organization Member Added", + "name": "member.add" + }, + { + "description": "Details about the member removed from your organization", + "label": "Organization Member Removed", + "name": "member.remove" + }, + { + "description": "Details about the role changed for a member in your organization", + "label": "Member Role Changed", + "name": "member.role.change" + }, + { + "description": "Details of the member invited to your organization", + "label": "Org Member Invited", + "name": "member.invite.send" + }, + { + "description": "Activities related to the creation of a team", + "label": "Organization Created", + "name": "team.create" + }, + { + "description": "Activities related to the modification of a team", + "label": "Organization Deleted", + "name": "team.update" + }, + { + "description": "Activities related to the deletion of a team", + "label": "Organization Deleted", + "name": "team.delete" + }, + { + "description": "Details of the member added to your team", + "label": "Team Member Added", + "name": "team.member.add" + }, + { + "description": "Details of the member removed from your team", + "label": "Team Member Removed", + "name": "team.member.remove" + }, + { + "description": "Details of the single sign-on domain added to your organization", + "label": "Single Sign-On domain added", + "name": "domain.create" + }, + { + "description": "Details of the single sign-on domain verified for your organization", + "label": "Single Sign-On domain verified", + "name": "domain.verify" + }, + { + "description": "Details of the single sign-on domain removed from your organization", + "label": "Single Sign-On domain deleted", + "name": "domain.delete" + }, + { + "description": "Details of toggling the Auto-Provisioning feature on a domain on or off", + "label": "Organization Auto-Provisioning Toggled", + "name": "domain.auto-provisioning.toggle" + }, + { + "description": "Details related to the organization setting that was updated", + "label": "Organization Settings Updated", + "name": "settings.update" + }, + { + "description": "Activities related to enabling Registry Access Management", + "label": "Registry Access Management enabled", + "name": "registry_access.enabled" + }, + { + "description": "Activities related to disabling Registry Access Management", + "label": "Registry Access Management disabled", + "name": "registry_access.disabled" + }, + { + "description": "Activities related to the addition of a registry", + "label": "Registry Access Management registry added", + "name": "registry_access.registry_added" + }, + { + "description": "Details related to the registry that was updated", + "label": "Registry Access Management registry updated", + "name": "registry_access.registry_updated" + }, + { + "description": "Activities related to the removal of a registry", + "label": "Registry Access Management registry removed", + "name": "registry_access.registry_removed" + }, + { + "description": "Access token created in organization", + "label": "Access token created", + "name": "access_token.create" + }, + { + "description": "Access token updated in organization", + "label": "Access token updated", + "name": "access_token.update" + }, + { + "description": "Access token deleted in organization", + "label": "Access token deleted", + "name": "access_token.delete" + }, + { + "description": "A custom role was created", + "label": "Custom role created", + "name": "customrole.create" + }, + { + "description": "An existing custom role was updated", + "label": "Custom role updated", + "name": "customrole.update" + }, + { + "description": "A custom role was deleted", + "label": "Custom role deleted", + "name": "customrole.delete" + }, + { + "description": "A secure policy configuration was created", + "label": "Secure Policy Configuration created", + "name": "securepolicyconfigure.create" + }, + { + "description": "A secure policy configuration was updated", + "label": "Secure Policy Configuration updated", + "name": "securepolicyconfigure.update" + }, + { + "description": "A secure policy configuration was deleted", + "label": "Secure Policy Configuration deleted", + "name": "securepolicyconfigure.delete" + }, + { + "description": "A secure policy client was created", + "label": "Secure Policy Client created", + "name": "securepolicyclient.create" + }, + { + "description": "A secure policy client was updated", + "label": "Secure Policy Client updated", + "name": "securepolicyclient.update" + }, + { + "description": "A secure policy client was deleted", + "label": "Secure Policy Client deleted", + "name": "securepolicyclient.delete" + }, + { + "description": "A secure policy profile was created", + "label": "Secure Policy Profile created", + "name": "securepolicyprofile.create" + }, + { + "description": "A secure policy profile was updated", + "label": "Secure Policy Profile updated", + "name": "securepolicyprofile.update" + }, + { + "description": "A secure policy profile was deleted", + "label": "Secure Policy Profile deleted", + "name": "securepolicyprofile.delete" + } + ], + "label": "Organization" + }, + "repo": { + "actions": [ + { + "description": "Activities related to the creation of a new repository", + "label": "Repository Created", + "name": "create" + }, + { + "description": "Activities related to the modification of a repository", + "label": "Repository Updated", + "name": "update" + }, + { + "description": "Activities related to the deletion of a repository", + "label": "Repository Deleted", + "name": "delete" + }, + { + "description": "Details related to the privacy policies that were updated", + "label": "Privacy Changed", + "name": "change_privacy" + }, + { + "description": "Details related to updating a repository categories", + "label": "Categories updated", + "name": "category.updated" + }, + { + "description": "Details related to updating tag immutability of a repository", + "label": "Tag immutability updated", + "name": "immutable.tags.updated" + }, + { + "description": "Activities related to the tags pushed", + "label": "Tag Pushed", + "name": "tag.push" + }, + { + "description": "Activities related to the tags deleted", + "label": "Tag Deleted", + "name": "tag.delete" + } + ], + "label": "Repository" + } + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/GetAuditActionsResponse" + } + } + }, + "description": "A successful response." + }, + "429": { + "content": { + "application/json": { + "examples": { + "response": { + "value": { + "detail": "Rate limit exceeded", + "error": false + } + } + }, + "schema": {} + } + }, + "description": "" + }, + "500": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "internal error" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "" + }, + "default": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "internal error" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "An unexpected error response." + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List audit log actions", + "tags": [ + "audit-logs" + ] + }, + "references": [ + { + "ref": "#/components/schemas/GetAuditActionsResponse", + "url": "/reference/api/hub/latest/schemas/GetAuditActionsResponse/" + }, + { + "ref": "#/components/schemas/error", + "url": "/reference/api/hub/latest/schemas/error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List audit log actions", + "tags": [ + "audit-logs" + ], + "url": "/reference/api/hub/latest/operations/AuditLogs_ListAuditActions/", + "variants": [ + { + "description": "A successful response.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "response", + "text": "{\n \"actions\": {\n \"billing\": {\n \"actions\": [\n {\n \"description\": \"Occurs when your organization’s billing plan is upgraded to a higher tier plan.\",\n \"label\": \"Plan Upgraded\",\n \"name\": \"plan.upgrade\"\n },\n {\n \"description\": \"Occurs when your organization’s billing plan is downgraded to a lower tier plan.\",\n \"label\": \"Plan Downgraded\",\n \"name\": \"plan.downgrade\"\n },\n {\n \"description\": \"Occurs when a seat is added to your organization’s billing plan.\",\n \"label\": \"Seat Added\",\n \"name\": \"plan.seat_add\"\n },\n {\n \"description\": \"Occurs when a seat is removed from your organization’s billing plan.\",\n \"label\": \"Seat Removed\",\n \"name\": \"plan.seat_remove\"\n },\n {\n \"description\": \"Occurs when there is a change in the recurring interval that your organization is charged.\",\n \"label\": \"Billing Cycle Changed\",\n \"name\": \"plan.cycle_change\"\n },\n {\n \"description\": \"Occurs when a scheduled plan downgrade for your organization is canceled.\",\n \"label\": \"Plan Downgrade Canceled\",\n \"name\": \"plan.downgrade_cancel\"\n },\n {\n \"description\": \"Occurs when a scheduled seat removal for an organization’s billing plan is canceled.\",\n \"label\": \"Seat Removal Canceled\",\n \"name\": \"plan.seat_removal_cancel\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a plan upgrade.\",\n \"label\": \"Plan Upgrade Requested\",\n \"name\": \"plan.upgrade.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a plan downgrade.\",\n \"label\": \"Plan Downgrade Requested\",\n \"name\": \"plan.downgrade.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests an increase in the number of seats.\",\n \"label\": \"Seat Addition Requested\",\n \"name\": \"plan.seat_add.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a decrease in the number of seats.\",\n \"label\": \"Seat Removal Requested\",\n \"name\": \"plan.seat_removal.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a change in the billing cycle.\",\n \"label\": \"Billing Cycle Change Requested\",\n \"name\": \"plan.cycle_change.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade.\",\n \"label\": \"Plan Downgrade Cancellation Requested\",\n \"name\": \"plan.downgrade_cancel.request\"\n },\n {\n \"description\": \"Occurs when a user in your organization requests a cancellation of a scheduled seat removal.\",\n \"label\": \"Seat Removal Cancellation Requested\",\n \"name\": \"plan.seat_removal_cancel.request\"\n },\n {\n \"description\": \"Occurs when there is a change in the product that your organization subscribes to.\",\n \"label\": \"Billing Product Changed\",\n \"name\": \"plan.product_change\"\n }\n ],\n \"label\": \"Billing\"\n },\n \"enterprise\": {\n \"actions\": [\n {\n \"description\": \"Details of adding an admin settings policy\",\n \"label\": \"Policy created\",\n \"name\": \"setting.policy.create\"\n },\n {\n \"description\": \"Details of updating an admin settings policy\",\n \"label\": \"Policy updated\",\n \"name\": \"setting.policy.update\"\n },\n {\n \"description\": \"Details of deleting an admin settings policy\",\n \"label\": \"Policy deleted\",\n \"name\": \"setting.policy.delete\"\n },\n {\n \"description\": \"Details of transferring an admin settings policy to another owner\",\n \"label\": \"Policy transferred\",\n \"name\": \"setting.policy.transfer\"\n },\n {\n \"description\": \"Details of creating a new org/company SSO connection\",\n \"label\": \"Create SSO Connection\",\n \"name\": \"sso.connection.create\"\n },\n {\n \"description\": \"Details of updating an existing org/company SSO connection\",\n \"label\": \"Update SSO Connection\",\n \"name\": \"sso.connection.update\"\n },\n {\n \"description\": \"Details of deleting an existing org/company SSO connection\",\n \"label\": \"Delete SSO Connection\",\n \"name\": \"sso.connection.delete\"\n },\n {\n \"description\": \"Details of toggling enforcement on an existing org/company SSO connection\",\n \"label\": \"Enforce SSO\",\n \"name\": \"sso.connection.enforcement_toggle\"\n },\n {\n \"description\": \"Details of toggling SCIM on an existing org/company SSO connection\",\n \"label\": \"Enforce SCIM\",\n \"name\": \"sso.connection.scim_toggle\"\n },\n {\n \"description\": \"Details of a SCIM token refresh on an existing org/company SSO connection\",\n \"label\": \"Refresh SCIM Token\",\n \"name\": \"sso.connection.scim_token_refresh\"\n },\n {\n \"description\": \"Details of a connection type change on an existing org/company SSO connection\",\n \"label\": \"Change SSO Connection Type\",\n \"name\": \"sso.connection.connection_type_change\"\n },\n {\n \"description\": \"Details of a JIT toggle on an existing org/company SSO connection\",\n \"label\": \"Toggle JIT provisioning\",\n \"name\": \"sso.connection.jit_toggle\"\n }\n ],\n \"label\": \"Enterprise\"\n },\n \"offload\": {\n \"actions\": [\n {\n \"description\": \"Details of the started Offload lease.\",\n \"label\": \"Offload lease start\",\n \"name\": \"lease.start\"\n },\n {\n \"description\": \"Details of the ended Offload lease.\",\n \"label\": \"Offload lease end\",\n \"name\": \"lease.end\"\n }\n ],\n \"label\": \"Offload\"\n },\n \"oidc\": {\n \"actions\": [\n {\n \"description\": \"Details of creating an OIDC connection.\",\n \"label\": \"OIDC connection created\",\n \"name\": \"connection.create\"\n },\n {\n \"description\": \"Details of updating an OIDC connection.\",\n \"label\": \"OIDC connection updated\",\n \"name\": \"connection.update\"\n },\n {\n \"description\": \"Details of deleting an OIDC connection.\",\n \"label\": \"OIDC connection deleted\",\n \"name\": \"connection.delete\"\n }\n ],\n \"label\": \"OIDC\"\n },\n \"org\": {\n \"actions\": [\n {\n \"description\": \"Activities related to the creation of a new organization\",\n \"label\": \"Organization Created\",\n \"name\": \"create\"\n },\n {\n \"description\": \"Details of the member added to your organization\",\n \"label\": \"Organization Member Added\",\n \"name\": \"member.add\"\n },\n {\n \"description\": \"Details about the member removed from your organization\",\n \"label\": \"Organization Member Removed\",\n \"name\": \"member.remove\"\n },\n {\n \"description\": \"Details about the role changed for a member in your organization\",\n \"label\": \"Member Role Changed\",\n \"name\": \"member.role.change\"\n },\n {\n \"description\": \"Details of the member invited to your organization\",\n \"label\": \"Org Member Invited\",\n \"name\": \"member.invite.send\"\n },\n {\n \"description\": \"Activities related to the creation of a team\",\n \"label\": \"Organization Created\",\n \"name\": \"team.create\"\n },\n {\n \"description\": \"Activities related to the modification of a team\",\n \"label\": \"Organization Deleted\",\n \"name\": \"team.update\"\n },\n {\n \"description\": \"Activities related to the deletion of a team\",\n \"label\": \"Organization Deleted\",\n \"name\": \"team.delete\"\n },\n {\n \"description\": \"Details of the member added to your team\",\n \"label\": \"Team Member Added\",\n \"name\": \"team.member.add\"\n },\n {\n \"description\": \"Details of the member removed from your team\",\n \"label\": \"Team Member Removed\",\n \"name\": \"team.member.remove\"\n },\n {\n \"description\": \"Details of the single sign-on domain added to your organization\",\n \"label\": \"Single Sign-On domain added\",\n \"name\": \"domain.create\"\n },\n {\n \"description\": \"Details of the single sign-on domain verified for your organization\",\n \"label\": \"Single Sign-On domain verified\",\n \"name\": \"domain.verify\"\n },\n {\n \"description\": \"Details of the single sign-on domain removed from your organization\",\n \"label\": \"Single Sign-On domain deleted\",\n \"name\": \"domain.delete\"\n },\n {\n \"description\": \"Details of toggling the Auto-Provisioning feature on a domain on or off\",\n \"label\": \"Organization Auto-Provisioning Toggled\",\n \"name\": \"domain.auto-provisioning.toggle\"\n },\n {\n \"description\": \"Details related to the organization setting that was updated\",\n \"label\": \"Organization Settings Updated\",\n \"name\": \"settings.update\"\n },\n {\n \"description\": \"Activities related to enabling Registry Access Management\",\n \"label\": \"Registry Access Management enabled\",\n \"name\": \"registry_access.enabled\"\n },\n {\n \"description\": \"Activities related to disabling Registry Access Management\",\n \"label\": \"Registry Access Management disabled\",\n \"name\": \"registry_access.disabled\"\n },\n {\n \"description\": \"Activities related to the addition of a registry\",\n \"label\": \"Registry Access Management registry added\",\n \"name\": \"registry_access.registry_added\"\n },\n {\n \"description\": \"Details related to the registry that was updated\",\n \"label\": \"Registry Access Management registry updated\",\n \"name\": \"registry_access.registry_updated\"\n },\n {\n \"description\": \"Activities related to the removal of a registry\",\n \"label\": \"Registry Access Management registry removed\",\n \"name\": \"registry_access.registry_removed\"\n },\n {\n \"description\": \"Access token created in organization\",\n \"label\": \"Access token created\",\n \"name\": \"access_token.create\"\n },\n {\n \"description\": \"Access token updated in organization\",\n \"label\": \"Access token updated\",\n \"name\": \"access_token.update\"\n },\n {\n \"description\": \"Access token deleted in organization\",\n \"label\": \"Access token deleted\",\n \"name\": \"access_token.delete\"\n },\n {\n \"description\": \"A custom role was created\",\n \"label\": \"Custom role created\",\n \"name\": \"customrole.create\"\n },\n {\n \"description\": \"An existing custom role was updated\",\n \"label\": \"Custom role updated\",\n \"name\": \"customrole.update\"\n },\n {\n \"description\": \"A custom role was deleted\",\n \"label\": \"Custom role deleted\",\n \"name\": \"customrole.delete\"\n },\n {\n \"description\": \"A secure policy configuration was created\",\n \"label\": \"Secure Policy Configuration created\",\n \"name\": \"securepolicyconfigure.create\"\n },\n {\n \"description\": \"A secure policy configuration was updated\",\n \"label\": \"Secure Policy Configuration updated\",\n \"name\": \"securepolicyconfigure.update\"\n },\n {\n \"description\": \"A secure policy configuration was deleted\",\n \"label\": \"Secure Policy Configuration deleted\",\n \"name\": \"securepolicyconfigure.delete\"\n },\n {\n \"description\": \"A secure policy client was created\",\n \"label\": \"Secure Policy Client created\",\n \"name\": \"securepolicyclient.create\"\n },\n {\n \"description\": \"A secure policy client was updated\",\n \"label\": \"Secure Policy Client updated\",\n \"name\": \"securepolicyclient.update\"\n },\n {\n \"description\": \"A secure policy client was deleted\",\n \"label\": \"Secure Policy Client deleted\",\n \"name\": \"securepolicyclient.delete\"\n },\n {\n \"description\": \"A secure policy profile was created\",\n \"label\": \"Secure Policy Profile created\",\n \"name\": \"securepolicyprofile.create\"\n },\n {\n \"description\": \"A secure policy profile was updated\",\n \"label\": \"Secure Policy Profile updated\",\n \"name\": \"securepolicyprofile.update\"\n },\n {\n \"description\": \"A secure policy profile was deleted\",\n \"label\": \"Secure Policy Profile deleted\",\n \"name\": \"securepolicyprofile.delete\"\n }\n ],\n \"label\": \"Organization\"\n },\n \"repo\": {\n \"actions\": [\n {\n \"description\": \"Activities related to the creation of a new repository\",\n \"label\": \"Repository Created\",\n \"name\": \"create\"\n },\n {\n \"description\": \"Activities related to the modification of a repository\",\n \"label\": \"Repository Updated\",\n \"name\": \"update\"\n },\n {\n \"description\": \"Activities related to the deletion of a repository\",\n \"label\": \"Repository Deleted\",\n \"name\": \"delete\"\n },\n {\n \"description\": \"Details related to the privacy policies that were updated\",\n \"label\": \"Privacy Changed\",\n \"name\": \"change_privacy\"\n },\n {\n \"description\": \"Details related to updating a repository categories\",\n \"label\": \"Categories updated\",\n \"name\": \"category.updated\"\n },\n {\n \"description\": \"Details related to updating tag immutability of a repository\",\n \"label\": \"Tag immutability updated\",\n \"name\": \"immutable.tags.updated\"\n },\n {\n \"description\": \"Activities related to the tags pushed\",\n \"label\": \"Tag Pushed\",\n \"name\": \"tag.push\"\n },\n {\n \"description\": \"Activities related to the tags deleted\",\n \"label\": \"Tag Deleted\",\n \"name\": \"tag.delete\"\n }\n ],\n \"label\": \"Repository\"\n }\n }\n}", + "value": { + "actions": { + "billing": { + "actions": [ + { + "description": "Occurs when your organization’s billing plan is upgraded to a higher tier plan.", + "label": "Plan Upgraded", + "name": "plan.upgrade" + }, + { + "description": "Occurs when your organization’s billing plan is downgraded to a lower tier plan.", + "label": "Plan Downgraded", + "name": "plan.downgrade" + }, + { + "description": "Occurs when a seat is added to your organization’s billing plan.", + "label": "Seat Added", + "name": "plan.seat_add" + }, + { + "description": "Occurs when a seat is removed from your organization’s billing plan.", + "label": "Seat Removed", + "name": "plan.seat_remove" + }, + { + "description": "Occurs when there is a change in the recurring interval that your organization is charged.", + "label": "Billing Cycle Changed", + "name": "plan.cycle_change" + }, + { + "description": "Occurs when a scheduled plan downgrade for your organization is canceled.", + "label": "Plan Downgrade Canceled", + "name": "plan.downgrade_cancel" + }, + { + "description": "Occurs when a scheduled seat removal for an organization’s billing plan is canceled.", + "label": "Seat Removal Canceled", + "name": "plan.seat_removal_cancel" + }, + { + "description": "Occurs when a user in your organization requests a plan upgrade.", + "label": "Plan Upgrade Requested", + "name": "plan.upgrade.request" + }, + { + "description": "Occurs when a user in your organization requests a plan downgrade.", + "label": "Plan Downgrade Requested", + "name": "plan.downgrade.request" + }, + { + "description": "Occurs when a user in your organization requests an increase in the number of seats.", + "label": "Seat Addition Requested", + "name": "plan.seat_add.request" + }, + { + "description": "Occurs when a user in your organization requests a decrease in the number of seats.", + "label": "Seat Removal Requested", + "name": "plan.seat_removal.request" + }, + { + "description": "Occurs when a user in your organization requests a change in the billing cycle.", + "label": "Billing Cycle Change Requested", + "name": "plan.cycle_change.request" + }, + { + "description": "Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade.", + "label": "Plan Downgrade Cancellation Requested", + "name": "plan.downgrade_cancel.request" + }, + { + "description": "Occurs when a user in your organization requests a cancellation of a scheduled seat removal.", + "label": "Seat Removal Cancellation Requested", + "name": "plan.seat_removal_cancel.request" + }, + { + "description": "Occurs when there is a change in the product that your organization subscribes to.", + "label": "Billing Product Changed", + "name": "plan.product_change" + } + ], + "label": "Billing" + }, + "enterprise": { + "actions": [ + { + "description": "Details of adding an admin settings policy", + "label": "Policy created", + "name": "setting.policy.create" + }, + { + "description": "Details of updating an admin settings policy", + "label": "Policy updated", + "name": "setting.policy.update" + }, + { + "description": "Details of deleting an admin settings policy", + "label": "Policy deleted", + "name": "setting.policy.delete" + }, + { + "description": "Details of transferring an admin settings policy to another owner", + "label": "Policy transferred", + "name": "setting.policy.transfer" + }, + { + "description": "Details of creating a new org/company SSO connection", + "label": "Create SSO Connection", + "name": "sso.connection.create" + }, + { + "description": "Details of updating an existing org/company SSO connection", + "label": "Update SSO Connection", + "name": "sso.connection.update" + }, + { + "description": "Details of deleting an existing org/company SSO connection", + "label": "Delete SSO Connection", + "name": "sso.connection.delete" + }, + { + "description": "Details of toggling enforcement on an existing org/company SSO connection", + "label": "Enforce SSO", + "name": "sso.connection.enforcement_toggle" + }, + { + "description": "Details of toggling SCIM on an existing org/company SSO connection", + "label": "Enforce SCIM", + "name": "sso.connection.scim_toggle" + }, + { + "description": "Details of a SCIM token refresh on an existing org/company SSO connection", + "label": "Refresh SCIM Token", + "name": "sso.connection.scim_token_refresh" + }, + { + "description": "Details of a connection type change on an existing org/company SSO connection", + "label": "Change SSO Connection Type", + "name": "sso.connection.connection_type_change" + }, + { + "description": "Details of a JIT toggle on an existing org/company SSO connection", + "label": "Toggle JIT provisioning", + "name": "sso.connection.jit_toggle" + } + ], + "label": "Enterprise" + }, + "offload": { + "actions": [ + { + "description": "Details of the started Offload lease.", + "label": "Offload lease start", + "name": "lease.start" + }, + { + "description": "Details of the ended Offload lease.", + "label": "Offload lease end", + "name": "lease.end" + } + ], + "label": "Offload" + }, + "oidc": { + "actions": [ + { + "description": "Details of creating an OIDC connection.", + "label": "OIDC connection created", + "name": "connection.create" + }, + { + "description": "Details of updating an OIDC connection.", + "label": "OIDC connection updated", + "name": "connection.update" + }, + { + "description": "Details of deleting an OIDC connection.", + "label": "OIDC connection deleted", + "name": "connection.delete" + } + ], + "label": "OIDC" + }, + "org": { + "actions": [ + { + "description": "Activities related to the creation of a new organization", + "label": "Organization Created", + "name": "create" + }, + { + "description": "Details of the member added to your organization", + "label": "Organization Member Added", + "name": "member.add" + }, + { + "description": "Details about the member removed from your organization", + "label": "Organization Member Removed", + "name": "member.remove" + }, + { + "description": "Details about the role changed for a member in your organization", + "label": "Member Role Changed", + "name": "member.role.change" + }, + { + "description": "Details of the member invited to your organization", + "label": "Org Member Invited", + "name": "member.invite.send" + }, + { + "description": "Activities related to the creation of a team", + "label": "Organization Created", + "name": "team.create" + }, + { + "description": "Activities related to the modification of a team", + "label": "Organization Deleted", + "name": "team.update" + }, + { + "description": "Activities related to the deletion of a team", + "label": "Organization Deleted", + "name": "team.delete" + }, + { + "description": "Details of the member added to your team", + "label": "Team Member Added", + "name": "team.member.add" + }, + { + "description": "Details of the member removed from your team", + "label": "Team Member Removed", + "name": "team.member.remove" + }, + { + "description": "Details of the single sign-on domain added to your organization", + "label": "Single Sign-On domain added", + "name": "domain.create" + }, + { + "description": "Details of the single sign-on domain verified for your organization", + "label": "Single Sign-On domain verified", + "name": "domain.verify" + }, + { + "description": "Details of the single sign-on domain removed from your organization", + "label": "Single Sign-On domain deleted", + "name": "domain.delete" + }, + { + "description": "Details of toggling the Auto-Provisioning feature on a domain on or off", + "label": "Organization Auto-Provisioning Toggled", + "name": "domain.auto-provisioning.toggle" + }, + { + "description": "Details related to the organization setting that was updated", + "label": "Organization Settings Updated", + "name": "settings.update" + }, + { + "description": "Activities related to enabling Registry Access Management", + "label": "Registry Access Management enabled", + "name": "registry_access.enabled" + }, + { + "description": "Activities related to disabling Registry Access Management", + "label": "Registry Access Management disabled", + "name": "registry_access.disabled" + }, + { + "description": "Activities related to the addition of a registry", + "label": "Registry Access Management registry added", + "name": "registry_access.registry_added" + }, + { + "description": "Details related to the registry that was updated", + "label": "Registry Access Management registry updated", + "name": "registry_access.registry_updated" + }, + { + "description": "Activities related to the removal of a registry", + "label": "Registry Access Management registry removed", + "name": "registry_access.registry_removed" + }, + { + "description": "Access token created in organization", + "label": "Access token created", + "name": "access_token.create" + }, + { + "description": "Access token updated in organization", + "label": "Access token updated", + "name": "access_token.update" + }, + { + "description": "Access token deleted in organization", + "label": "Access token deleted", + "name": "access_token.delete" + }, + { + "description": "A custom role was created", + "label": "Custom role created", + "name": "customrole.create" + }, + { + "description": "An existing custom role was updated", + "label": "Custom role updated", + "name": "customrole.update" + }, + { + "description": "A custom role was deleted", + "label": "Custom role deleted", + "name": "customrole.delete" + }, + { + "description": "A secure policy configuration was created", + "label": "Secure Policy Configuration created", + "name": "securepolicyconfigure.create" + }, + { + "description": "A secure policy configuration was updated", + "label": "Secure Policy Configuration updated", + "name": "securepolicyconfigure.update" + }, + { + "description": "A secure policy configuration was deleted", + "label": "Secure Policy Configuration deleted", + "name": "securepolicyconfigure.delete" + }, + { + "description": "A secure policy client was created", + "label": "Secure Policy Client created", + "name": "securepolicyclient.create" + }, + { + "description": "A secure policy client was updated", + "label": "Secure Policy Client updated", + "name": "securepolicyclient.update" + }, + { + "description": "A secure policy client was deleted", + "label": "Secure Policy Client deleted", + "name": "securepolicyclient.delete" + }, + { + "description": "A secure policy profile was created", + "label": "Secure Policy Profile created", + "name": "securepolicyprofile.create" + }, + { + "description": "A secure policy profile was updated", + "label": "Secure Policy Profile updated", + "name": "securepolicyprofile.update" + }, + { + "description": "A secure policy profile was deleted", + "label": "Secure Policy Profile deleted", + "name": "securepolicyprofile.delete" + } + ], + "label": "Organization" + }, + "repo": { + "actions": [ + { + "description": "Activities related to the creation of a new repository", + "label": "Repository Created", + "name": "create" + }, + { + "description": "Activities related to the modification of a repository", + "label": "Repository Updated", + "name": "update" + }, + { + "description": "Activities related to the deletion of a repository", + "label": "Repository Deleted", + "name": "delete" + }, + { + "description": "Details related to the privacy policies that were updated", + "label": "Privacy Changed", + "name": "change_privacy" + }, + { + "description": "Details related to updating a repository categories", + "label": "Categories updated", + "name": "category.updated" + }, + { + "description": "Details related to updating tag immutability of a repository", + "label": "Tag immutability updated", + "name": "immutable.tags.updated" + }, + { + "description": "Activities related to the tags pushed", + "label": "Tag Pushed", + "name": "tag.push" + }, + { + "description": "Activities related to the tags deleted", + "label": "Tag Deleted", + "name": "tag.delete" + } + ], + "label": "Repository" + } + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/GetAuditActionsResponse" + }, + "status": "200" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "response", + "text": "{\n \"detail\": \"Rate limit exceeded\",\n \"error\": false\n}", + "value": { + "detail": "Rate limit exceeded", + "error": false + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get/responses/429/content/application~1json", + "required": null, + "schema": {}, + "status": "429" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + }, + { + "description": "An unexpected error response.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auditlogs~1{account}~1actions/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"identifier\": \"myusername\",\n \"secret\": \"dckr_pat_124509ugsdjga93\"\n}' \\\n 'https://hub.docker.com/v2/auth/token'", + "curlNotes": [], + "deprecated": null, + "description": "Creates and returns a short-lived access token in JWT format for use as a bearer when calling Docker APIs.\n\nIf successful, the access token returned should be used in the HTTP Authorization header like \n`Authorization: Bearer {access_token}`.\n\n_**If your organization has SSO enforced, you must use a personal access token (PAT) instead of a password.**_\n", + "id": "AuthCreateAccessToken", + "line": 253, + "method": "POST", + "parameters": [], + "path": "/v2/auth/token", + "pointer": "/paths/~1v2~1auth~1token/post", + "raw": { + "description": "Creates and returns a short-lived access token in JWT format for use as a bearer when calling Docker APIs.\n\nIf successful, the access token returned should be used in the HTTP Authorization header like \n`Authorization: Bearer {access_token}`.\n\n_**If your organization has SSO enforced, you must use a personal access token (PAT) instead of a password.**_\n", + "operationId": "AuthCreateAccessToken", + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Request to create access token", + "examples": [ + { + "identifier": "myusername", + "secret": "dckr_pat_124509ugsdjga93" + } + ], + "properties": { + "identifier": { + "description": "The identifier of the account to create an access token for. If using a password or personal access token,\nthis must be a username. If using an organization access token, this must be an organization name.\n", + "example": "myusername", + "type": "string" + }, + "secret": { + "description": "The secret of the account to create an access token for. This can be a password, personal access token, or\norganization access token.\n", + "example": "dckr_pat_124509ugsdjga93", + "type": "string" + } + }, + "required": [ + "identifier", + "secret" + ], + "type": "object" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthCreateTokenResponse" + } + } + }, + "description": "Token created" + }, + "401": { + "$ref": "#/components/responses/unauthorized", + "description": "Authentication failed" + } + }, + "security": [], + "summary": "Create access token", + "tags": [ + "authentication-api" + ] + }, + "references": [ + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/AuthCreateTokenResponse", + "url": "/reference/api/hub/latest/schemas/AuthCreateTokenResponse/" + } + ], + "requestSchema": { + "description": "Request to create access token", + "examples": [ + { + "identifier": "myusername", + "secret": "dckr_pat_124509ugsdjga93" + } + ], + "properties": { + "identifier": { + "description": "The identifier of the account to create an access token for. If using a password or personal access token,\nthis must be a username. If using an organization access token, this must be an organization name.\n", + "example": "myusername", + "type": "string" + }, + "secret": { + "description": "The secret of the account to create an access token for. This can be a password, personal access token, or\norganization access token.\n", + "example": "dckr_pat_124509ugsdjga93", + "type": "string" + } + }, + "required": [ + "identifier", + "secret" + ], + "type": "object" + }, + "security": [], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create access token", + "tags": [ + "authentication-api" + ], + "url": "/reference/api/hub/latest/operations/AuthCreateAccessToken/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"identifier\": \"myusername\",\n \"secret\": \"dckr_pat_124509ugsdjga93\"\n}", + "value": { + "identifier": "myusername", + "secret": "dckr_pat_124509ugsdjga93" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auth~1token/post/requestBody/content/application~1json", + "required": null, + "schema": { + "description": "Request to create access token", + "examples": [ + { + "identifier": "myusername", + "secret": "dckr_pat_124509ugsdjga93" + } + ], + "properties": { + "identifier": { + "description": "The identifier of the account to create an access token for. If using a password or personal access token,\nthis must be a username. If using an organization access token, this must be an organization name.\n", + "example": "myusername", + "type": "string" + }, + "secret": { + "description": "The secret of the account to create an access token for. This can be a password, personal access token, or\norganization access token.\n", + "example": "dckr_pat_124509ugsdjga93", + "type": "string" + } + }, + "required": [ + "identifier", + "secret" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "Token created", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auth~1token/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/AuthCreateTokenResponse" + }, + "status": "200" + }, + { + "description": "Authentication failed", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1auth~1token/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"dry_run\": true,\n \"invitees\": [\n \"invitee1DockerId\",\n \"invitee2@docker.com\",\n \"invitee3@docker.com\"\n ],\n \"org\": \"docker\",\n \"role\": \"member\",\n \"team\": \"owners\"\n}' \\\n 'https://hub.docker.com/v2/invites/bulk'", + "curlNotes": [], + "deprecated": null, + "description": "Create multiple invites by emails or DockerIDs. Only a team owner can create invites.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "postV2InvitesBulk", + "line": 2185, + "method": "POST", + "parameters": [ + { + "description": "Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web')", + "in": "header", + "name": "X-Analytics-Client-Feature", + "pointer": "/paths/~1v2~1invites~1bulk/parameters/0", + "schema": { + "type": "string" + } + } + ], + "path": "/v2/invites/bulk", + "pointer": "/paths/~1v2~1invites~1bulk/post", + "raw": { + "description": "Create multiple invites by emails or DockerIDs. Only a team owner can create invites.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "postV2InvitesBulk", + "requestBody": { + "$ref": "#/components/requestBodies/bulk_invite_request" + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bulk_invite" + } + } + }, + "description": "Accepted" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "409": { + "$ref": "#/components/responses/conflict" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Bulk create invites", + "tags": [ + "invites" + ] + }, + "references": [ + { + "ref": "#/components/requestBodies/bulk_invite_request", + "url": null + }, + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/conflict", + "url": null + }, + { + "ref": "#/components/schemas/bulk_invite", + "url": "/reference/api/hub/latest/schemas/bulk_invite/" + } + ], + "requestSchema": { + "examples": [ + { + "dry_run": true, + "invitees": [ + "invitee1DockerId", + "invitee2@docker.com", + "invitee3@docker.com" + ], + "org": "docker", + "role": "member", + "team": "owners" + } + ], + "properties": { + "dry_run": { + "description": "Optional, run through validation but don't actually change data.", + "example": true, + "type": "boolean" + }, + "invitees": { + "description": "list of invitees emails or Docker Ids", + "example": [ + "invitee1DockerId", + "invitee2@docker.com", + "invitee3@docker.com" + ], + "items": { + "description": "invitee email or Docker ID", + "type": "string" + }, + "type": "array" + }, + "org": { + "description": "organization name", + "example": "docker", + "type": "string" + }, + "role": { + "description": "role for invitees", + "example": "member", + "type": "string" + }, + "team": { + "description": "team name", + "example": "owners", + "type": "string" + } + }, + "required": [ + "org", + "invitees" + ], + "type": "object" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Bulk create invites", + "tags": [ + "invites" + ], + "url": "/reference/api/hub/latest/operations/postV2InvitesBulk/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"dry_run\": true,\n \"invitees\": [\n \"invitee1DockerId\",\n \"invitee2@docker.com\",\n \"invitee3@docker.com\"\n ],\n \"org\": \"docker\",\n \"role\": \"member\",\n \"team\": \"owners\"\n}", + "value": { + "dry_run": true, + "invitees": [ + "invitee1DockerId", + "invitee2@docker.com", + "invitee3@docker.com" + ], + "org": "docker", + "role": "member", + "team": "owners" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1bulk/post/requestBody/content/application~1json", + "required": true, + "schema": { + "examples": [ + { + "dry_run": true, + "invitees": [ + "invitee1DockerId", + "invitee2@docker.com", + "invitee3@docker.com" + ], + "org": "docker", + "role": "member", + "team": "owners" + } + ], + "properties": { + "dry_run": { + "description": "Optional, run through validation but don't actually change data.", + "example": true, + "type": "boolean" + }, + "invitees": { + "description": "list of invitees emails or Docker Ids", + "example": [ + "invitee1DockerId", + "invitee2@docker.com", + "invitee3@docker.com" + ], + "items": { + "description": "invitee email or Docker ID", + "type": "string" + }, + "type": "array" + }, + "org": { + "description": "organization name", + "example": "docker", + "type": "string" + }, + "role": { + "description": "role for invitees", + "example": "member", + "type": "string" + }, + "team": { + "description": "team name", + "example": "owners", + "type": "string" + } + }, + "required": [ + "org", + "invitees" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "Accepted", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"invitees\": [\n {\n \"invite\": {\n \"created_at\": \"2021-10-28T18:30:19.520861Z\",\n \"id\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\",\n \"invitee\": \"invitee@docker.com\",\n \"inviter_username\": \"moby\",\n \"org\": \"docker\",\n \"team\": \"owners\"\n },\n \"invitee\": \"invitee@docker.com\",\n \"status\": \"invited\"\n },\n {\n \"invitee\": \"invitee2@docker.com\",\n \"status\": \"existing_org_member\"\n },\n {\n \"invitee\": \"invitee3@docker.com\",\n \"status\": \"invalid_email_or_docker_id\"\n }\n ]\n}", + "value": { + "invitees": [ + { + "invite": { + "created_at": "2021-10-28T18:30:19.520861Z", + "id": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "invitee": "invitee@docker.com", + "inviter_username": "moby", + "org": "docker", + "team": "owners" + }, + "invitee": "invitee@docker.com", + "status": "invited" + }, + { + "invitee": "invitee2@docker.com", + "status": "existing_org_member" + }, + { + "invitee": "invitee3@docker.com", + "status": "invalid_email_or_docker_id" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1bulk/post/responses/202/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/bulk_invite" + }, + "status": "202" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1bulk/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"conflict\"\n}", + "value": { + "errinfo": null, + "message": "conflict" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1bulk/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "409" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/invites/\u003cID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Mark the invite as cancelled so it doesn't show up on the list of pending invites\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "deleteV2InvitesById", + "line": 2132, + "method": "DELETE", + "parameters": [ + { + "description": "ID of the invitation.", + "in": "path", + "name": "id", + "pointer": "/paths/~1v2~1invites~1{id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/invites/{id}", + "pointer": "/paths/~1v2~1invites~1{id}/delete", + "raw": { + "description": "Mark the invite as cancelled so it doesn't show up on the list of pending invites\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "deleteV2InvitesById", + "responses": { + "204": { + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Cancel an invite", + "tags": [ + "invites" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Cancel an invite", + "tags": [ + "invites" + ], + "url": "/reference/api/hub/latest/operations/deleteV2InvitesById/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1invites~1{id}/delete/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/invites/\u003cID\u003e/resend'", + "curlNotes": [], + "deprecated": null, + "description": "Resend a pending invite to the user, any org owner can resend an invite\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "patchV2InvitesByIdResend", + "line": 2161, + "method": "PATCH", + "parameters": [ + { + "description": "ID of the invitation.", + "in": "path", + "name": "id", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/invites/{id}/resend", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/patch", + "raw": { + "description": "Resend a pending invite to the user, any org owner can resend an invite\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "patchV2InvitesByIdResend", + "responses": { + "204": { + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Resend an invite", + "tags": [ + "invites" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Resend an invite", + "tags": [ + "invites" + ], + "url": "/reference/api/hub/latest/operations/patchV2InvitesByIdResend/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/patch/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1invites~1{id}~1resend/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories'", + "curlNotes": [ + "This example uses the first authentication alternative. Review the complete requirements." + ], + "deprecated": null, + "description": "Returns a list of repositories within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\n\n\n**OAT listing behavior**: an OAT with the `scope-repository-list` scope sees all repositories including private ones. An OAT without that scope only sees public repositories. This filtering is silent: the response is a normal `200` with no indication that private repositories were withheld.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "listNamespaceRepositories", + "line": 1278, + "method": "GET", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/parameters/0", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/parameters/1", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + }, + { + "description": "Filter repositories by name (partial match).", + "in": "query", + "name": "name", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/parameters/2", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Order repositories by the specified field. Prefix with '-' for descending order.\nAvailable options:\n- `name` / `-name`: Repository name (ascending/descending)\n- `last_updated` / `-last_updated`: Last update time (ascending/descending)\n- `pull_count` / `-pull_count`: Number of pulls (ascending/descending)\n", + "in": "query", + "name": "ordering", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/parameters/3", + "required": false, + "schema": { + "enum": [ + "name", + "-name", + "last_updated", + "-last_updated", + "pull_count", + "-pull_count" + ], + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get", + "raw": { + "description": "Returns a list of repositories within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\n\n\n**OAT listing behavior**: an OAT with the `scope-repository-list` scope sees all repositories including private ones. An OAT without that scope only sees public repositories. This filtering is silent: the response is a normal `200` with no indication that private repositories were withheld.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "listNamespaceRepositories", + "parameters": [ + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + }, + { + "description": "Filter repositories by name (partial match).", + "in": "query", + "name": "name", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Order repositories by the specified field. Prefix with '-' for descending order.\nAvailable options:\n- `name` / `-name`: Repository name (ascending/descending)\n- `last_updated` / `-last_updated`: Last update time (ascending/descending)\n- `pull_count` / `-pull_count`: Number of pulls (ascending/descending)\n", + "in": "query", + "name": "ordering", + "required": false, + "schema": { + "enum": [ + "name", + "-name", + "last_updated", + "-last_updated", + "pull_count", + "-pull_count" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "repositories_list": { + "value": { + "count": 287, + "next": "https://hub.docker.com/v2/namespaces/docker/repositories?page=2\u0026page_size=2", + "previous": null, + "results": [ + { + "affiliation": "", + "categories": [ + { + "name": "Languages \u0026 frameworks", + "slug": "languages-and-frameworks" + }, + { + "name": "Integration \u0026 delivery", + "slug": "integration-and-delivery" + }, + { + "name": "Operating systems", + "slug": "operating-systems" + } + ], + "content_types": [ + "unrecognized", + "image" + ], + "date_registered": "2015-05-19T21:13:35.937763Z", + "description": "Image for performing Docker build requests", + "is_private": false, + "last_modified": "2024-10-16T13:48:34.145251Z", + "last_updated": "2023-06-20T10:44:45.459826Z", + "media_types": [ + "application/octet-stream", + "application/vnd.docker.container.image.v1+json", + "application/vnd.docker.distribution.manifest.v1+prettyjws" + ], + "name": "highland_builder", + "namespace": "docker", + "pull_count": 15722123, + "repository_type": "image", + "star_count": 7, + "status": 1, + "status_description": "active", + "storage_size": 488723114800 + }, + { + "affiliation": "", + "categories": [ + { + "name": "Languages \u0026 frameworks", + "slug": "languages-and-frameworks" + }, + { + "name": "Integration \u0026 delivery", + "slug": "integration-and-delivery" + } + ], + "content_types": [ + "image" + ], + "date_registered": "2015-06-09T18:16:36.527329Z", + "description": "An image for use in the Docker demo tutorial", + "is_private": false, + "last_modified": "2024-10-16T13:48:34.145251Z", + "last_updated": "2015-06-19T19:06:27.388123Z", + "media_types": [ + "application/vnd.docker.distribution.manifest.v1+prettyjws" + ], + "name": "whalesay", + "namespace": "docker", + "pull_count": 130737682, + "repository_type": null, + "star_count": 757, + "status": 1, + "status_description": "active", + "storage_size": 103666708 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/list_repositories_response" + } + } + }, + "description": "List of repositories" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalid_ordering": { + "summary": "Invalid ordering value", + "value": { + "fields": { + "ordering": [ + "Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count" + ] + }, + "text": "Invalid ordering value" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "Bad Request - Invalid request parameters" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "not found" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "Page not found - occurs when requesting a page number `\u003e1` that exceeds the available results" + } + }, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "summary": "List repositories in a namespace", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/error", + "url": "/reference/api/hub/latest/schemas/error/" + }, + { + "ref": "#/components/schemas/list_repositories_response", + "url": "/reference/api/hub/latest/schemas/list_repositories_response/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List repositories in a namespace", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/listNamespaceRepositories/", + "variants": [ + { + "description": "List of repositories", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "repositories_list", + "text": "{\n \"count\": 287,\n \"next\": \"https://hub.docker.com/v2/namespaces/docker/repositories?page=2\\u0026page_size=2\",\n \"previous\": null,\n \"results\": [\n {\n \"affiliation\": \"\",\n \"categories\": [\n {\n \"name\": \"Languages \\u0026 frameworks\",\n \"slug\": \"languages-and-frameworks\"\n },\n {\n \"name\": \"Integration \\u0026 delivery\",\n \"slug\": \"integration-and-delivery\"\n },\n {\n \"name\": \"Operating systems\",\n \"slug\": \"operating-systems\"\n }\n ],\n \"content_types\": [\n \"unrecognized\",\n \"image\"\n ],\n \"date_registered\": \"2015-05-19T21:13:35.937763Z\",\n \"description\": \"Image for performing Docker build requests\",\n \"is_private\": false,\n \"last_modified\": \"2024-10-16T13:48:34.145251Z\",\n \"last_updated\": \"2023-06-20T10:44:45.459826Z\",\n \"media_types\": [\n \"application/octet-stream\",\n \"application/vnd.docker.container.image.v1+json\",\n \"application/vnd.docker.distribution.manifest.v1+prettyjws\"\n ],\n \"name\": \"highland_builder\",\n \"namespace\": \"docker\",\n \"pull_count\": 15722123,\n \"repository_type\": \"image\",\n \"star_count\": 7,\n \"status\": 1,\n \"status_description\": \"active\",\n \"storage_size\": 488723114800\n },\n {\n \"affiliation\": \"\",\n \"categories\": [\n {\n \"name\": \"Languages \\u0026 frameworks\",\n \"slug\": \"languages-and-frameworks\"\n },\n {\n \"name\": \"Integration \\u0026 delivery\",\n \"slug\": \"integration-and-delivery\"\n }\n ],\n \"content_types\": [\n \"image\"\n ],\n \"date_registered\": \"2015-06-09T18:16:36.527329Z\",\n \"description\": \"An image for use in the Docker demo tutorial\",\n \"is_private\": false,\n \"last_modified\": \"2024-10-16T13:48:34.145251Z\",\n \"last_updated\": \"2015-06-19T19:06:27.388123Z\",\n \"media_types\": [\n \"application/vnd.docker.distribution.manifest.v1+prettyjws\"\n ],\n \"name\": \"whalesay\",\n \"namespace\": \"docker\",\n \"pull_count\": 130737682,\n \"repository_type\": null,\n \"star_count\": 757,\n \"status\": 1,\n \"status_description\": \"active\",\n \"storage_size\": 103666708\n }\n ]\n}", + "value": { + "count": 287, + "next": "https://hub.docker.com/v2/namespaces/docker/repositories?page=2\u0026page_size=2", + "previous": null, + "results": [ + { + "affiliation": "", + "categories": [ + { + "name": "Languages \u0026 frameworks", + "slug": "languages-and-frameworks" + }, + { + "name": "Integration \u0026 delivery", + "slug": "integration-and-delivery" + }, + { + "name": "Operating systems", + "slug": "operating-systems" + } + ], + "content_types": [ + "unrecognized", + "image" + ], + "date_registered": "2015-05-19T21:13:35.937763Z", + "description": "Image for performing Docker build requests", + "is_private": false, + "last_modified": "2024-10-16T13:48:34.145251Z", + "last_updated": "2023-06-20T10:44:45.459826Z", + "media_types": [ + "application/octet-stream", + "application/vnd.docker.container.image.v1+json", + "application/vnd.docker.distribution.manifest.v1+prettyjws" + ], + "name": "highland_builder", + "namespace": "docker", + "pull_count": 15722123, + "repository_type": "image", + "star_count": 7, + "status": 1, + "status_description": "active", + "storage_size": 488723114800 + }, + { + "affiliation": "", + "categories": [ + { + "name": "Languages \u0026 frameworks", + "slug": "languages-and-frameworks" + }, + { + "name": "Integration \u0026 delivery", + "slug": "integration-and-delivery" + } + ], + "content_types": [ + "image" + ], + "date_registered": "2015-06-09T18:16:36.527329Z", + "description": "An image for use in the Docker demo tutorial", + "is_private": false, + "last_modified": "2024-10-16T13:48:34.145251Z", + "last_updated": "2015-06-19T19:06:27.388123Z", + "media_types": [ + "application/vnd.docker.distribution.manifest.v1+prettyjws" + ], + "name": "whalesay", + "namespace": "docker", + "pull_count": 130737682, + "repository_type": null, + "star_count": 757, + "status": 1, + "status_description": "active", + "storage_size": 103666708 + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/list_repositories_response" + }, + "status": "200" + }, + { + "description": "Bad Request - Invalid request parameters", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "invalid_ordering", + "text": "{\n \"fields\": {\n \"ordering\": [\n \"Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count\"\n ]\n },\n \"text\": \"Invalid ordering value\"\n}", + "value": { + "fields": { + "ordering": [ + "Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count" + ] + }, + "text": "Invalid ordering value" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Page not found - occurs when requesting a page number `\u003e1` that exceeds the available results", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"A sample application repository\",\n \"full_description\": \"This is a comprehensive description of my application repository that contains additional details about the project.\",\n \"is_private\": false,\n \"name\": \"my-app\",\n \"namespace\": \"myorganization\",\n \"registry\": \"docker.io\"\n}' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories'", + "curlNotes": [], + "deprecated": null, + "description": "Creates a new repository within the specified namespace. The repository will be created\nwith the provided metadata including name, description, and privacy settings.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "CreateRepository", + "line": 1418, + "method": "POST", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post", + "raw": { + "description": "Creates a new repository within the specified namespace. The repository will be created\nwith the provided metadata including name, description, and privacy settings.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "CreateRepository", + "requestBody": { + "content": { + "application/json": { + "example": { + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "is_private": false, + "name": "my-app", + "namespace": "myorganization", + "registry": "docker.io" + }, + "schema": { + "$ref": "#/components/schemas/repo_creation_request" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "example": { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + }, + "schema": { + "$ref": "#/components/schemas/repository_info" + } + } + }, + "description": "Repository created successfully" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "500": { + "$ref": "#/components/responses/internal_error" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a new repository", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/internal_error", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/repo_creation_request", + "url": "/reference/api/hub/latest/schemas/repo_creation_request/" + }, + { + "ref": "#/components/schemas/repository_info", + "url": "/reference/api/hub/latest/schemas/repository_info/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/repo_creation_request" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create a new repository", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/CreateRepository/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Example", + "text": "{\n \"description\": \"A sample application repository\",\n \"full_description\": \"This is a comprehensive description of my application repository that contains additional details about the project.\",\n \"is_private\": false,\n \"name\": \"my-app\",\n \"namespace\": \"myorganization\",\n \"registry\": \"docker.io\"\n}", + "value": { + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "is_private": false, + "name": "my-app", + "namespace": "myorganization", + "registry": "docker.io" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/repo_creation_request" + }, + "status": "" + }, + { + "description": "Repository created successfully", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Example", + "text": "{\n \"categories\": [],\n \"collaborator_count\": 0,\n \"content_types\": [],\n \"date_registered\": \"2025-01-20T10:30:00Z\",\n \"description\": \"A sample application repository\",\n \"full_description\": \"This is a comprehensive description of my application repository that contains additional details about the project.\",\n \"has_starred\": false,\n \"hub_user\": \"myorganization\",\n \"immutable_tags_settings\": {\n \"enabled\": false,\n \"rules\": []\n },\n \"is_automated\": false,\n \"is_private\": false,\n \"last_updated\": \"2025-01-20T10:30:00Z\",\n \"media_types\": [],\n \"name\": \"my-app\",\n \"namespace\": \"myorganization\",\n \"permissions\": {\n \"admin\": true,\n \"read\": true,\n \"write\": true\n },\n \"pull_count\": 0,\n \"repository_type\": \"image\",\n \"source\": null,\n \"star_count\": 0,\n \"status\": 1,\n \"status_description\": \"Active\",\n \"storage_size\": null,\n \"user\": \"myorganization\"\n}", + "value": { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/repository_info" + }, + "status": "201" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + }, + { + "description": "Internal", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/post/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e'", + "curlNotes": [ + "This example uses the first authentication alternative. Review the complete requirements." + ], + "deprecated": null, + "description": "Returns a repository within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "GetRepository", + "line": 1494, + "method": "GET", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get", + "raw": { + "description": "Returns a repository within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "GetRepository", + "responses": { + "200": { + "content": { + "application/json": { + "example": { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + }, + "schema": { + "$ref": "#/components/schemas/repository_info" + } + } + } + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "500": { + "$ref": "#/components/responses/internal_error" + } + }, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "summary": "Get repository in a namespace", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/internal_error", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/repository_info", + "url": "/reference/api/hub/latest/schemas/repository_info/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get repository in a namespace", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/GetRepository/", + "variants": [ + { + "description": null, + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Example", + "text": "{\n \"categories\": [],\n \"collaborator_count\": 0,\n \"content_types\": [],\n \"date_registered\": \"2025-01-20T10:30:00Z\",\n \"description\": \"A sample application repository\",\n \"full_description\": \"This is a comprehensive description of my application repository that contains additional details about the project.\",\n \"has_starred\": false,\n \"hub_user\": \"myorganization\",\n \"immutable_tags_settings\": {\n \"enabled\": false,\n \"rules\": []\n },\n \"is_automated\": false,\n \"is_private\": false,\n \"last_updated\": \"2025-01-20T10:30:00Z\",\n \"media_types\": [],\n \"name\": \"my-app\",\n \"namespace\": \"myorganization\",\n \"permissions\": {\n \"admin\": true,\n \"read\": true,\n \"write\": true\n },\n \"pull_count\": 0,\n \"repository_type\": \"image\",\n \"source\": null,\n \"star_count\": 0,\n \"status\": 1,\n \"status_description\": \"Active\",\n \"storage_size\": null,\n \"user\": \"myorganization\"\n}", + "value": { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/repository_info" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + }, + { + "description": "Internal", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/get/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --head \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e'", + "curlNotes": [ + "This example uses the first authentication alternative. Review the complete requirements." + ], + "deprecated": null, + "description": "Check a repository within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "CheckRepository", + "line": 1552, + "method": "HEAD", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head", + "raw": { + "description": "Check a repository within the specified namespace (organization or user).\n\nPublic repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "CheckRepository", + "responses": { + "200": {}, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "500": { + "$ref": "#/components/responses/internal_error" + } + }, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "summary": "Check repository in a namespace", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/internal_error", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + }, + {} + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Check repository in a namespace", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/CheckRepository/", + "variants": [ + { + "description": null, + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head/responses/200", + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + }, + { + "description": "Internal", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}/head/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"immutable_tags\": true,\n \"immutable_tags_rules\": [\n \"v.*\",\n \".*-RELEASE\"\n ]\n}' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/immutabletags'", + "curlNotes": [], + "deprecated": null, + "description": "Updates the immutable tags configuration for this repository.\n\n**Only users with administrative privileges for the repository can modify these settings.**\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "UpdateRepositoryImmutableTags", + "line": 1166, + "method": "PATCH", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/immutabletags", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch", + "raw": { + "description": "Updates the immutable tags configuration for this repository.\n\n**Only users with administrative privileges for the repository can modify these settings.**\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "UpdateRepositoryImmutableTags", + "requestBody": { + "$ref": "#/components/requestBodies/update_repository_immutable_tags_request" + }, + "responses": { + "200": { + "$ref": "#/components/responses/update_repository_immutable_tags_response" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update repository immutable tags", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/requestBodies/update_repository_immutable_tags_request", + "url": null + }, + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/responses/update_repository_immutable_tags_response", + "url": null + } + ], + "requestSchema": { + "$ref": "#/components/schemas/update_repository_immutable_tags_request" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update repository immutable tags", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/UpdateRepositoryImmutableTags/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"immutable_tags\": true,\n \"immutable_tags_rules\": [\n \"v.*\",\n \".*-RELEASE\"\n ]\n}", + "value": { + "immutable_tags": true, + "immutable_tags_rules": [ + "v.*", + ".*-RELEASE" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/update_repository_immutable_tags_request" + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"categories\": [],\n \"collaborator_count\": 0,\n \"content_types\": [],\n \"date_registered\": \"2025-01-20T10:30:00Z\",\n \"description\": \"A sample application repository\",\n \"full_description\": \"This is a comprehensive description of my application repository that contains additional details about the project.\",\n \"has_starred\": false,\n \"hub_user\": \"myorganization\",\n \"immutable_tags_settings\": {\n \"enabled\": false,\n \"rules\": []\n },\n \"is_automated\": false,\n \"is_private\": false,\n \"last_updated\": \"2025-01-20T10:30:00Z\",\n \"media_types\": [],\n \"name\": \"my-app\",\n \"namespace\": \"myorganization\",\n \"permissions\": {\n \"admin\": true,\n \"read\": true,\n \"write\": true\n },\n \"pull_count\": 0,\n \"repository_type\": \"image\",\n \"source\": null,\n \"star_count\": 0,\n \"status\": 1,\n \"status_description\": \"Active\",\n \"storage_size\": null,\n \"user\": \"myorganization\"\n}", + "value": { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/repository_info" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"regex\": \"v.*\"\n}' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/immutabletags/verify'", + "curlNotes": [], + "deprecated": null, + "description": "Validates the immutable tags regex passed in the request body and returns a list of tags matching it in this repository.\n\n**Only users with administrative privileges for the repository can call this endpoint.**\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "VerifyRepositoryImmutableTags", + "line": 1196, + "method": "POST", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/immutabletags/verify", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post", + "raw": { + "description": "Validates the immutable tags regex passed in the request body and returns a list of tags matching it in this repository.\n\n**Only users with administrative privileges for the repository can call this endpoint.**\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "VerifyRepositoryImmutableTags", + "requestBody": { + "$ref": "#/components/requestBodies/immutable_tags_verify_request" + }, + "responses": { + "200": { + "$ref": "#/components/responses/immutable_tags_verify_response" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Verify repository immutable tags", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/requestBodies/immutable_tags_verify_request", + "url": null + }, + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/immutable_tags_verify_response", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": { + "$ref": "#/components/schemas/immutable_tags_verify_request" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Verify repository immutable tags", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/VerifyRepositoryImmutableTags/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"regex\": \"v.*\"\n}", + "value": { + "regex": "v.*" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/immutable_tags_verify_request" + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"tags\": [\n \"v1.0.0\",\n \"v2.1.3\",\n \"latest\"\n ]\n}", + "value": { + "tags": [ + "v1.0.0", + "v2.1.3", + "latest" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/immutable_tags_verify_response" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1immutabletags~1verify/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/tags'", + "curlNotes": [], + "deprecated": null, + "description": "Returns the list of tags for the specified repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "ListRepositoryTags", + "line": 1082, + "method": "GET", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get/parameters/0", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get/parameters/1", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/tags", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get", + "raw": { + "description": "Returns the list of tags for the specified repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "ListRepositoryTags", + "parameters": [ + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/list_tags" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List repository tags", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/list_tags", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List repository tags", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/ListRepositoryTags/", + "variants": [ + { + "description": "list repository tags", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"creator\": 1234,\n \"full_size\": 123456,\n \"id\": 12345,\n \"images\": [\n {\n \"architecture\": \"amd64\",\n \"features\": null,\n \"last_pulled\": null,\n \"last_pushed\": \"2021-01-05T21:06:53.506400Z\",\n \"os\": \"linux\",\n \"os_features\": null,\n \"os_version\": null,\n \"size\": 123456,\n \"status\": \"active\",\n \"variant\": null\n }\n ],\n \"last_updated\": \"2021-01-05T21:06:53.506400Z\",\n \"last_updater\": 1234,\n \"last_updater_username\": \"dockeruser\",\n \"name\": \"latest\",\n \"repository\": 5678,\n \"tag_last_pulled\": null,\n \"tag_last_pushed\": \"2021-01-05T21:06:53.506400Z\",\n \"tag_status\": \"active\",\n \"v2\": true\n }\n ]\n}", + "value": { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "creator": 1234, + "full_size": 123456, + "id": 12345, + "images": [ + { + "architecture": "amd64", + "features": null, + "last_pulled": null, + "last_pushed": "2021-01-05T21:06:53.506400Z", + "os": "linux", + "os_features": null, + "os_version": null, + "size": 123456, + "status": "active", + "variant": null + } + ], + "last_updated": "2021-01-05T21:06:53.506400Z", + "last_updater": 1234, + "last_updater_username": "dockeruser", + "name": "latest", + "repository": 5678, + "tag_last_pulled": null, + "tag_last_pushed": "2021-01-05T21:06:53.506400Z", + "tag_status": "active", + "v2": true + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/paginated_tags" + }, + "status": "200" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --head \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/tags'", + "curlNotes": [], + "deprecated": null, + "description": "Checks whether the repository has any tags.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "headV2NamespacesByNamespaceRepositoriesByRepositoryTags", + "line": 1103, + "method": "HEAD", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/tags", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/head", + "raw": { + "description": "Checks whether the repository has any tags.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "headV2NamespacesByNamespaceRepositoriesByRepositoryTags", + "responses": { + "200": { + "description": "Repository contains tags" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Check repository tags", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Check repository tags", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/headV2NamespacesByNamespaceRepositoriesByRepositoryTags/", + "variants": [ + { + "description": "Repository contains tags", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/head/responses/200", + "status": "200" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/head/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/head/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/tags/\u003cTAG\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Returns details for a specific tag in the specified repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "GetRepositoryTag", + "line": 1126, + "method": "GET", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the image tag.", + "in": "path", + "name": "tag", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/2", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/get", + "raw": { + "description": "Returns details for a specific tag in the specified repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "GetRepositoryTag", + "responses": { + "200": { + "$ref": "#/components/responses/get_tag" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Read repository tag", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/get_tag", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Read repository tag", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/GetRepositoryTag/", + "variants": [ + { + "description": "repository tag", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"creator\": 1234,\n \"full_size\": 123456,\n \"id\": 12345,\n \"images\": [\n {\n \"architecture\": \"amd64\",\n \"features\": null,\n \"last_pulled\": null,\n \"last_pushed\": \"2021-01-05T21:06:53.506400Z\",\n \"os\": \"linux\",\n \"os_features\": null,\n \"os_version\": null,\n \"size\": 123456,\n \"status\": \"active\",\n \"variant\": null\n }\n ],\n \"last_updated\": \"2021-01-05T21:06:53.506400Z\",\n \"last_updater\": 1234,\n \"last_updater_username\": \"dockeruser\",\n \"name\": \"latest\",\n \"repository\": 5678,\n \"tag_last_pulled\": null,\n \"tag_last_pushed\": \"2021-01-05T21:06:53.506400Z\",\n \"tag_status\": \"active\",\n \"v2\": true\n}", + "value": { + "creator": 1234, + "full_size": 123456, + "id": 12345, + "images": [ + { + "architecture": "amd64", + "features": null, + "last_pulled": null, + "last_pushed": "2021-01-05T21:06:53.506400Z", + "os": "linux", + "os_features": null, + "os_version": null, + "size": 123456, + "status": "active", + "variant": null + } + ], + "last_updated": "2021-01-05T21:06:53.506400Z", + "last_updater": 1234, + "last_updater_username": "dockeruser", + "name": "latest", + "repository": 5678, + "tag_last_pulled": null, + "tag_last_pushed": "2021-01-05T21:06:53.506400Z", + "tag_status": "active", + "v2": true + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/tag" + }, + "status": "200" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --head \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/namespaces/\u003cNAMESPACE\u003e/repositories/\u003cREPOSITORY\u003e/tags/\u003cTAG\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Checks whether the specified tag exists in the repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "headV2NamespacesByNamespaceRepositoriesByRepositoryTagsByTag", + "line": 1144, + "method": "HEAD", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the image tag.", + "in": "path", + "name": "tag", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/parameters/2", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/head", + "raw": { + "description": "Checks whether the specified tag exists in the repository.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "headV2NamespacesByNamespaceRepositoriesByRepositoryTagsByTag", + "responses": { + "200": { + "description": "Repository tag exists" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Check repository tag", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Check repository tag", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/headV2NamespacesByNamespaceRepositoriesByRepositoryTagsByTag/", + "variants": [ + { + "description": "Repository tag exists", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/head/responses/200", + "status": "200" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/head/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/head/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/access-tokens'", + "curlNotes": [], + "deprecated": null, + "description": "List access tokens for an organization.\n", + "id": "getV2OrgsByNameAccessTokens", + "line": 975, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/parameters/0", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/parameters/1", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + } + ], + "path": "/v2/orgs/{org_name}/access-tokens", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get", + "raw": { + "description": "List access tokens for an organization.\n", + "operationId": "getV2OrgsByNameAccessTokens", + "parameters": [ + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/getOrgAccessTokensResponse" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List access tokens", + "tags": [ + "org-access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/getOrgAccessTokensResponse", + "url": "/reference/api/hub/latest/schemas/getOrgAccessTokensResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List access tokens", + "tags": [ + "org-access-tokens" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByNameAccessTokens/", + "variants": [ + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"created_at\": \"2022-05-20T00:54:18Z\",\n \"created_by\": \"johndoe\",\n \"expires_at\": \"2023-05-20T00:54:18Z\",\n \"id\": \"a7a5ef25-8889-43a0-8cc7-f2a94268e861\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"last_used_at\": \"2022-06-15T12:30:45Z\"\n }\n ],\n \"total\": 1\n}", + "value": { + "next": null, + "previous": null, + "results": [ + { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z" + } + ], + "total": 1 + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/getOrgAccessTokensResponse" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"Token for CI/CD pipeline\",\n \"label\": \"My organization token\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/access-tokens'", + "curlNotes": [], + "deprecated": null, + "description": "Create an access token for an organization.\n", + "id": "postV2OrgsByNameAccessTokens", + "line": 945, + "method": "POST", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/access-tokens", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post", + "raw": { + "description": "Create an access token for an organization.\n", + "operationId": "postV2OrgsByNameAccessTokens", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/createOrgAccessTokenRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/createOrgAccessTokenResponse" + } + } + }, + "description": "Created" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create access token", + "tags": [ + "org-access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/BadRequest", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/createOrgAccessTokenRequest", + "url": "/reference/api/hub/latest/schemas/createOrgAccessTokenRequest/" + }, + { + "ref": "#/components/schemas/createOrgAccessTokenResponse", + "url": "/reference/api/hub/latest/schemas/createOrgAccessTokenResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/createOrgAccessTokenRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create access token", + "tags": [ + "org-access-tokens" + ], + "url": "/reference/api/hub/latest/operations/postV2OrgsByNameAccessTokens/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Token for CI/CD pipeline\",\n \"label\": \"My organization token\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}", + "value": { + "description": "Token for CI/CD pipeline", + "label": "My organization token", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/createOrgAccessTokenRequest" + }, + "status": "" + }, + { + "description": "Created", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"created_at\": \"2022-05-20T00:54:18Z\",\n \"expires_at\": \"2023-05-20T00:54:18Z\",\n \"id\": \"a7a5ef25-8889-43a0-8cc7-f2a94268e861\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"last_used_at\": \"2022-06-15T12:30:45Z\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ],\n \"token\": \"dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo\"\n}", + "value": { + "created_at": "2022-05-20T00:54:18Z", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ], + "token": "dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/createOrgAccessTokenResponse" + }, + "status": "201" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/access-tokens/a7a5ef25-8889-43a0-8cc7-f2a94268e861'", + "curlNotes": [], + "deprecated": null, + "description": "Get details of a specific access token for an organization.\n", + "id": "getV2OrgsByOrgNameAccessTokensByAccessTokenId", + "line": 1010, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The ID of the access token to retrieve", + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "in": "path", + "name": "access_token_id", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/access-tokens/{access_token_id}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get", + "raw": { + "description": "Get details of a specific access token for an organization.\n", + "operationId": "getV2OrgsByOrgNameAccessTokensByAccessTokenId", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/getOrgAccessTokenResponse" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get access token", + "tags": [ + "org-access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/getOrgAccessTokenResponse", + "url": "/reference/api/hub/latest/schemas/getOrgAccessTokenResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get access token", + "tags": [ + "org-access-tokens" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameAccessTokensByAccessTokenId/", + "variants": [ + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"created_at\": \"2022-05-20T00:54:18Z\",\n \"created_by\": \"johndoe\",\n \"expires_at\": \"2023-05-20T00:54:18Z\",\n \"id\": \"a7a5ef25-8889-43a0-8cc7-f2a94268e861\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"last_used_at\": \"2022-06-15T12:30:45Z\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}", + "value": { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/getOrgAccessTokenResponse" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/orgs/myorganization/access-tokens/a7a5ef25-8889-43a0-8cc7-f2a94268e861'", + "curlNotes": [], + "deprecated": null, + "description": "Delete a specific access token for an organization. This action cannot be undone.\n", + "id": "deleteV2OrgsByOrgNameAccessTokensByAccessTokenId", + "line": 1060, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The ID of the access token to retrieve", + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "in": "path", + "name": "access_token_id", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/access-tokens/{access_token_id}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete", + "raw": { + "description": "Delete a specific access token for an organization. This action cannot be undone.\n", + "operationId": "deleteV2OrgsByOrgNameAccessTokensByAccessTokenId", + "responses": { + "204": { + "description": "Access token deleted successfully" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Delete access token", + "tags": [ + "org-access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Delete access token", + "tags": [ + "org-access-tokens" + ], + "url": "/reference/api/hub/latest/operations/deleteV2OrgsByOrgNameAccessTokensByAccessTokenId/", + "variants": [ + { + "description": "Access token deleted successfully", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"Token for CI/CD pipeline\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/access-tokens/a7a5ef25-8889-43a0-8cc7-f2a94268e861'", + "curlNotes": [], + "deprecated": null, + "description": "Update a specific access token for an organization.\n", + "id": "patchV2OrgsByOrgNameAccessTokensByAccessTokenId", + "line": 1032, + "method": "PATCH", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The ID of the access token to retrieve", + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "in": "path", + "name": "access_token_id", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/access-tokens/{access_token_id}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch", + "raw": { + "description": "Update a specific access token for an organization.\n", + "operationId": "patchV2OrgsByOrgNameAccessTokensByAccessTokenId", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/updateOrgAccessTokenRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/updateOrgAccessTokenResponse" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update access token", + "tags": [ + "org-access-tokens" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/updateOrgAccessTokenRequest", + "url": "/reference/api/hub/latest/schemas/updateOrgAccessTokenRequest/" + }, + { + "ref": "#/components/schemas/updateOrgAccessTokenResponse", + "url": "/reference/api/hub/latest/schemas/updateOrgAccessTokenResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/updateOrgAccessTokenRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update access token", + "tags": [ + "org-access-tokens" + ], + "url": "/reference/api/hub/latest/operations/patchV2OrgsByOrgNameAccessTokensByAccessTokenId/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Token for CI/CD pipeline\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}", + "value": { + "description": "Token for CI/CD pipeline", + "is_active": true, + "label": "My organization token", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/updateOrgAccessTokenRequest" + }, + "status": "" + }, + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"created_at\": \"2022-05-20T00:54:18Z\",\n \"created_by\": \"johndoe\",\n \"expires_at\": \"2023-05-20T00:54:18Z\",\n \"id\": \"a7a5ef25-8889-43a0-8cc7-f2a94268e861\",\n \"is_active\": true,\n \"label\": \"My organization token\",\n \"last_used_at\": \"2022-06-15T12:30:45Z\",\n \"resources\": [\n {\n \"path\": \"myorg/myrepo\",\n \"scopes\": [\n \"scope-image-pull\"\n ],\n \"type\": \"TYPE_REPO\"\n }\n ]\n}", + "value": { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/updateOrgAccessTokenResponse" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups'", + "curlNotes": [], + "deprecated": null, + "description": "Get groups of an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameGroups", + "line": 1774, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/parameters/0", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/parameters/1", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + }, + { + "description": "Get groups for the specified username in the organization.", + "in": "query", + "name": "username", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/parameters/2", + "schema": { + "type": "string" + } + }, + { + "description": "Get groups for the specified group in the organization.", + "in": "query", + "name": "search", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/parameters/3", + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get", + "raw": { + "description": "Get groups of an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameGroups", + "parameters": [ + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + }, + { + "description": "Get groups for the specified username in the organization.", + "in": "query", + "name": "username", + "schema": { + "type": "string" + } + }, + { + "description": "Get groups for the specified group in the organization.", + "in": "query", + "name": "search", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + ] + } + ], + "properties": { + "count": { + "example": 1, + "type": "number" + }, + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "$ref": "#/components/schemas/org_group" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get groups of an organization", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_group", + "url": "/reference/api/hub/latest/schemas/org_group/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get groups of an organization", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameGroups/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"description\": \"Development team\",\n \"id\": 10,\n \"member_count\": 1,\n \"name\": \"developers\",\n \"role\": \"member\",\n \"uuid\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\"\n }\n ]\n}", + "value": { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/responses/200/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + ] + } + ], + "properties": { + "count": { + "example": 1, + "type": "number" + }, + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "$ref": "#/components/schemas/org_group" + }, + "type": "array" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"Development team\",\n \"name\": \"developers\"\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups'", + "curlNotes": [], + "deprecated": null, + "description": "Create a new group within an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "postV2OrgsByOrgNameGroups", + "line": 1840, + "method": "POST", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post", + "raw": { + "description": "Create a new group within an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "postV2OrgsByOrgNameGroups", + "requestBody": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_group" + } + } + }, + "description": "Group created successfully" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a new group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_group", + "url": "/reference/api/hub/latest/schemas/org_group/" + } + ], + "requestSchema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create a new group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/postV2OrgsByOrgNameGroups/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"name\": \"developers\"\n}", + "value": { + "description": "Development team", + "name": "developers" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post/requestBody/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "status": "" + }, + { + "description": "Group created successfully", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"id\": 10,\n \"member_count\": 1,\n \"name\": \"developers\",\n \"role\": \"member\",\n \"uuid\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\"\n}", + "value": { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_group" + }, + "status": "201" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers'", + "curlNotes": [], + "deprecated": null, + "description": "Get a group of an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameGroupsByGroupName", + "line": 1883, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get", + "raw": { + "description": "Get a group of an organization.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameGroupsByGroupName", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_group" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get a group of an organization", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_group", + "url": "/reference/api/hub/latest/schemas/org_group/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get a group of an organization", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameGroupsByGroupName/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"id\": 10,\n \"member_count\": 1,\n \"name\": \"developers\",\n \"role\": \"member\",\n \"uuid\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\"\n}", + "value": { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_group" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"Development team\",\n \"name\": \"developers\"\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers'", + "curlNotes": [], + "deprecated": null, + "description": "Update the details for an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "putV2OrgsByOrgNameGroupsByGroupName", + "line": 1907, + "method": "PUT", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put", + "raw": { + "description": "Update the details for an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "putV2OrgsByOrgNameGroupsByGroupName", + "requestBody": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_group" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update the details for an organization group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_group", + "url": "/reference/api/hub/latest/schemas/org_group/" + } + ], + "requestSchema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update the details for an organization group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/putV2OrgsByOrgNameGroupsByGroupName/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"name\": \"developers\"\n}", + "value": { + "description": "Development team", + "name": "developers" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put/requestBody/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "description": "Development team", + "name": "developers" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"id\": 10,\n \"member_count\": 1,\n \"name\": \"developers\",\n \"role\": \"member\",\n \"uuid\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\"\n}", + "value": { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_group" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers'", + "curlNotes": [], + "deprecated": null, + "description": "Delete an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "deleteV2OrgsByOrgNameGroupsByGroupName", + "line": 1988, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete", + "raw": { + "description": "Delete an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "deleteV2OrgsByOrgNameGroupsByGroupName", + "responses": { + "204": { + "description": "Group deleted successfully" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Delete an organization group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Delete an organization group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/deleteV2OrgsByOrgNameGroupsByGroupName/", + "variants": [ + { + "description": "Group deleted successfully", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"description\": \"Development team\",\n \"role\": \"member\"\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers'", + "curlNotes": [], + "deprecated": null, + "description": "Update some details for an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "patchV2OrgsByOrgNameGroupsByGroupName", + "line": 1945, + "method": "PATCH", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch", + "raw": { + "description": "Update some details for an organization group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "patchV2OrgsByOrgNameGroupsByGroupName", + "requestBody": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "description": "Development team", + "role": "member" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "role": { + "description": "Role assigned to the team. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_group" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update some details for an organization group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_group", + "url": "/reference/api/hub/latest/schemas/org_group/" + } + ], + "requestSchema": { + "examples": [ + { + "description": "Development team", + "role": "member" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "role": { + "description": "Role assigned to the team. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "type": "string" + } + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update some details for an organization group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/patchV2OrgsByOrgNameGroupsByGroupName/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"role\": \"member\"\n}", + "value": { + "description": "Development team", + "role": "member" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch/requestBody/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "description": "Development team", + "role": "member" + } + ], + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "role": { + "description": "Role assigned to the team. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "type": "string" + } + } + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"Development team\",\n \"id\": 10,\n \"member_count\": 1,\n \"name\": \"developers\",\n \"role\": \"member\",\n \"uuid\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\"\n}", + "value": { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_group" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers/members'", + "curlNotes": [], + "deprecated": null, + "description": "List the members (users) that are in a group.\nIf user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameGroupsByGroupNameMembers", + "line": 2010, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/parameters/2", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/parameters/3", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + }, + { + "description": "Search members by username, full_name or email", + "in": "query", + "name": "search", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/parameters/4", + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}/members", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get", + "raw": { + "description": "List the members (users) that are in a group.\nIf user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameGroupsByGroupNameMembers", + "parameters": [ + { + "$ref": "#/components/parameters/org_name" + }, + { + "$ref": "#/components/parameters/group_name" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/page_size" + }, + { + "$ref": "#/components/parameters/search" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "id": "0ab70deb065a43fcacd55d48caa945d8", + "type": "User", + "username": "dockeruser" + } + ] + } + ], + "properties": { + "count": { + "example": 1, + "type": "number" + }, + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "$ref": "#/components/schemas/group_member" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List members of a group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/parameters/group_name", + "url": null + }, + { + "ref": "#/components/parameters/org_name", + "url": null + }, + { + "ref": "#/components/parameters/page", + "url": null + }, + { + "ref": "#/components/parameters/page_size", + "url": null + }, + { + "ref": "#/components/parameters/search", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/group_member", + "url": "/reference/api/hub/latest/schemas/group_member/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List members of a group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameGroupsByGroupNameMembers/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"date_joined\": \"2021-01-05T21:06:53.506400Z\",\n \"email\": \"example@docker.com\",\n \"full_name\": \"Jon Snow\",\n \"id\": \"0ab70deb065a43fcacd55d48caa945d8\",\n \"type\": \"User\",\n \"username\": \"dockeruser\"\n }\n ]\n}", + "value": { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "id": "0ab70deb065a43fcacd55d48caa945d8", + "type": "User", + "username": "dockeruser" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/responses/200/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "id": "0ab70deb065a43fcacd55d48caa945d8", + "type": "User", + "username": "dockeruser" + } + ] + } + ], + "properties": { + "count": { + "example": 1, + "type": "number" + }, + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "$ref": "#/components/schemas/group_member" + }, + "type": "array" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"member\": \"jonsnow\"\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers/members'", + "curlNotes": [], + "deprecated": null, + "description": "Add a member to a group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "postV2OrgsByOrgNameGroupsByGroupNameMembers", + "line": 2070, + "method": "POST", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}/members", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post", + "raw": { + "description": "Add a member to a group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "postV2OrgsByOrgNameGroupsByGroupNameMembers", + "parameters": [ + { + "$ref": "#/components/parameters/org_name" + }, + { + "$ref": "#/components/parameters/group_name" + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/add_member_to_org_group" + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "500": { + "$ref": "#/components/responses/internal_error" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Add a member to a group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/parameters/group_name", + "url": null + }, + { + "ref": "#/components/parameters/org_name", + "url": null + }, + { + "ref": "#/components/requestBodies/add_member_to_org_group", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/internal_error", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": { + "examples": [ + { + "member": "jonsnow" + } + ], + "properties": { + "member": { + "example": "jonsnow", + "type": "string" + } + }, + "required": [ + "member" + ], + "type": "object" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Add a member to a group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/postV2OrgsByOrgNameGroupsByGroupNameMembers/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"member\": \"jonsnow\"\n}", + "value": { + "member": "jonsnow" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/requestBody/content/application~1json", + "required": true, + "schema": { + "examples": [ + { + "member": "jonsnow" + } + ], + "properties": { + "member": { + "example": "jonsnow", + "type": "string" + } + }, + "required": [ + "member" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "OK", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/responses/200", + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + }, + { + "description": "Internal", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"internal error\"\n}", + "value": { + "errinfo": null, + "message": "internal error" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/orgs/myorganization/groups/developers/members/jonsnow'", + "curlNotes": [], + "deprecated": null, + "description": "Remove a user from a group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "deleteV2OrgsByOrgNameGroupsByGroupNameMembersByUsername", + "line": 2103, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the group (team) in the organization.", + "in": "path", + "name": "group_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/parameters/1", + "required": true, + "schema": { + "example": "developers", + "type": "string" + } + }, + { + "description": "Username, identifier for the user (namespace, DockerID).", + "in": "path", + "name": "username", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/parameters/2", + "required": true, + "schema": { + "example": "jonsnow", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/groups/{group_name}/members/{username}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete", + "raw": { + "description": "Remove a user from a group.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "deleteV2OrgsByOrgNameGroupsByGroupNameMembersByUsername", + "responses": { + "204": { + "description": "User removed successfully" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Remove a user from a group", + "tags": [ + "groups" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Remove a user from a group", + "tags": [ + "groups" + ], + "url": "/reference/api/hub/latest/operations/deleteV2OrgsByOrgNameGroupsByGroupNameMembersByUsername/", + "variants": [ + { + "description": "User removed successfully", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete/responses/204", + "status": "204" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/invites'", + "curlNotes": [], + "deprecated": null, + "description": "Return all pending invites for a given org, only team owners can call this endpoint\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameInvites", + "line": 1733, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/invites", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/get", + "raw": { + "description": "Return all pending invites for a given org, only team owners can call this endpoint\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameInvites", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "data": [ + { + "created_at": "2021-10-28T18:30:19.520861Z", + "id": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "invitee": "invitee@docker.com", + "inviter_username": "moby", + "org": "docker", + "team": "owners" + } + ] + } + ], + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/invite" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "description": "" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List org invites", + "tags": [ + "invites" + ] + }, + "references": [ + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/invite", + "url": "/reference/api/hub/latest/schemas/invite/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List org invites", + "tags": [ + "invites" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameInvites/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"data\": [\n {\n \"created_at\": \"2021-10-28T18:30:19.520861Z\",\n \"id\": \"e36eca69-4cc8-4f17-9845-ae8c2b832691\",\n \"invitee\": \"invitee@docker.com\",\n \"inviter_username\": \"moby\",\n \"org\": \"docker\",\n \"team\": \"owners\"\n }\n ]\n}", + "value": { + "data": [ + { + "created_at": "2021-10-28T18:30:19.520861Z", + "id": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "invitee": "invitee@docker.com", + "inviter_username": "moby", + "org": "docker", + "team": "owners" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/get/responses/200/content/application~1json", + "required": null, + "schema": { + "examples": [ + { + "data": [ + { + "created_at": "2021-10-28T18:30:19.520861Z", + "id": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "invitee": "invitee@docker.com", + "inviter_username": "moby", + "org": "docker", + "team": "owners" + } + ] + } + ], + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/invite" + }, + "type": "array" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1invites/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/members?type=all\u0026role=owner'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a list of members for an organization.\n\n_The following fields are only visible to orgs with insights enabled._\n\n- `last_logged_in_at`\n- `last_seen_at`\n- `last_desktop_version`\n\nTo make visible, please see [View Insights for organization users](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users).\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameMembers", + "line": 1585, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Search members by username, full_name or email", + "in": "query", + "name": "search", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/1", + "schema": { + "type": "string" + } + }, + { + "description": "Page number (starts on 1).", + "in": "query", + "name": "page", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/2", + "required": false, + "schema": { + "default": 1, + "type": "integer" + } + }, + { + "description": "Number of items (rows) per page.", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/3", + "required": false, + "schema": { + "default": 10, + "type": "integer" + } + }, + { + "description": "Include invites in the response.", + "in": "query", + "name": "invites", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/4", + "schema": { + "type": "boolean" + } + }, + { + "description": "Filter members by membership type.", + "example": "all", + "in": "query", + "name": "type", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/5", + "schema": { + "enum": [ + "all", + "invitee", + "member" + ], + "type": "string" + } + }, + { + "description": "Filter members by their organization role.", + "example": "owner", + "in": "query", + "name": "role", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/parameters/6", + "schema": { + "enum": [ + "owner", + "editor", + "member" + ], + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/members", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get", + "raw": { + "description": "Returns a list of members for an organization.\n\n_The following fields are only visible to orgs with insights enabled._\n\n- `last_logged_in_at`\n- `last_seen_at`\n- `last_desktop_version`\n\nTo make visible, please see [View Insights for organization users](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users).\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameMembers", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_member_paginated" + } + } + }, + "description": "List of members" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List org members", + "tags": [ + "orgs" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_member_paginated", + "url": "/reference/api/hub/latest/schemas/org_member_paginated/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List org members", + "tags": [ + "orgs" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameMembers/", + "variants": [ + { + "description": "List of members", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"date_joined\": \"2021-01-05T21:06:53.506400Z\",\n \"email\": \"example@docker.com\",\n \"full_name\": \"Jon Snow\",\n \"groups\": [\n \"owners\"\n ],\n \"id\": \"0ab70deb065a43fcacd55d48caa945d8\",\n \"is_guest\": false,\n \"role\": \"Owner\",\n \"type\": \"User\",\n \"username\": \"dockeruser\"\n }\n ]\n}", + "value": { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "groups": [ + "owners" + ], + "id": "0ab70deb065a43fcacd55d48caa945d8", + "is_guest": false, + "role": "Owner", + "type": "User", + "username": "dockeruser" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_member_paginated" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "text/csv", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: text/csv' \\\n 'https://hub.docker.com/v2/orgs/myorganization/members/export'", + "curlNotes": [], + "deprecated": null, + "description": "Export members of an organization as a CSV\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "getV2OrgsByOrgNameMembersExport", + "line": 1622, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/members/export", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get", + "raw": { + "description": "Export members of an organization as a CSV\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "getV2OrgsByOrgNameMembersExport", + "responses": { + "200": { + "content": { + "text/csv": { + "example": "Name,Username,Email,Type,Role,Teams,Date Joined\nJon Snow,dockeruser,example@docker.com,User,Owner,owners,2021-01-05 21:06:53.5064 +0000 UTC\n", + "schema": { + "description": "CSV columns: Name, Username, Email, Type, Role, Teams, and Date Joined. The Role column contains the assigned role label. When administrative insights are available, the export also includes Last Logged-in Date, Docker Desktop Version, Last Seen Date, and Opted Out Analytics.", + "type": "string" + } + } + }, + "description": "Exported members", + "headers": { + "Content-Disposition": { + "example": "attachment;filename=\"{org_name}-members-{timestamp}.csv\"", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Export org members CSV", + "tags": [ + "orgs" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Export org members CSV", + "tags": [ + "orgs" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByOrgNameMembersExport/", + "variants": [ + { + "description": "Exported members", + "direction": "Response", + "examples": [ + { + "language": "text", + "name": "Example", + "text": "Name,Username,Email,Type,Role,Teams,Date Joined\nJon Snow,dockeruser,example@docker.com,User,Owner,owners,2021-01-05 21:06:53.5064 +0000 UTC\n", + "value": "Name,Username,Email,Type,Role,Teams,Date Joined\nJon Snow,dockeruser,example@docker.com,User,Owner,owners,2021-01-05 21:06:53.5064 +0000 UTC\n" + } + ], + "headers": { + "Content-Disposition": { + "example": "attachment;filename=\"{org_name}-members-{timestamp}.csv\"", + "schema": { + "type": "string" + } + } + }, + "media": "text/csv", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/200/content/text~1csv", + "required": null, + "schema": { + "description": "CSV columns: Name, Username, Email, Type, Role, Teams, and Date Joined. The Role column contains the assigned role label. When administrative insights are available, the export also includes Last Logged-in Date, Docker Desktop Version, Last Seen Date, and Opted Out Analytics.", + "type": "string" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"role\": \"owner\"\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/members/jonsnow'", + "curlNotes": [], + "deprecated": null, + "description": "Updates the role of a member in the organization.\n***Only users in the \"owners\" group of the organization can use this endpoint.***\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "putV2OrgsByOrgNameMembersByUsername", + "line": 1662, + "method": "PUT", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Username, identifier for the user (namespace, DockerID).", + "in": "path", + "name": "username", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/parameters/1", + "required": true, + "schema": { + "example": "jonsnow", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/members/{username}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put", + "raw": { + "description": "Updates the role of a member in the organization.\n***Only users in the \"owners\" group of the organization can use this endpoint.***\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "putV2OrgsByOrgNameMembersByUsername", + "requestBody": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "role": "owner" + } + ], + "properties": { + "role": { + "description": "Role of the member. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "example": "owner", + "type": "string" + } + }, + "required": [ + "role" + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org_member" + } + } + }, + "description": "Member role updated" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update org member (role)", + "tags": [ + "orgs" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/org_member", + "url": "/reference/api/hub/latest/schemas/org_member/" + } + ], + "requestSchema": { + "examples": [ + { + "role": "owner" + } + ], + "properties": { + "role": { + "description": "Role of the member. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "example": "owner", + "type": "string" + } + }, + "required": [ + "role" + ] + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update org member (role)", + "tags": [ + "orgs" + ], + "url": "/reference/api/hub/latest/operations/putV2OrgsByOrgNameMembersByUsername/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"role\": \"owner\"\n}", + "value": { + "role": "owner" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/requestBody/content/application~1json", + "required": true, + "schema": { + "examples": [ + { + "role": "owner" + } + ], + "properties": { + "role": { + "description": "Role of the member. Valid values are the core roles\n`owner`, `editor`, and `member`, or the name of an\nexisting [custom role](https://docs.docker.com/security/roles-and-permissions/custom-roles/manage/).\nUse the custom role's name identifier, not its label or UUID.\n", + "example": "owner", + "type": "string" + } + }, + "required": [ + "role" + ] + }, + "status": "" + }, + { + "description": "Member role updated", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"date_joined\": \"2021-01-05T21:06:53.506400Z\",\n \"email\": \"example@docker.com\",\n \"full_name\": \"Jon Snow\",\n \"groups\": [\n \"owners\"\n ],\n \"id\": \"0ab70deb065a43fcacd55d48caa945d8\",\n \"is_guest\": false,\n \"role\": \"Owner\",\n \"type\": \"User\",\n \"username\": \"dockeruser\"\n}", + "value": { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "groups": [ + "owners" + ], + "id": "0ab70deb065a43fcacd55d48caa945d8", + "is_guest": false, + "role": "Owner", + "type": "User", + "username": "dockeruser" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/org_member" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://hub.docker.com/v2/orgs/myorganization/members/jonsnow'", + "curlNotes": [], + "deprecated": null, + "description": "Removes the member from the org, ie. all groups in the org, unless they're the last owner\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "deleteV2OrgsByOrgNameMembersByUsername", + "line": 1707, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Username, identifier for the user (namespace, DockerID).", + "in": "path", + "name": "username", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/parameters/1", + "required": true, + "schema": { + "example": "jonsnow", + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/members/{username}", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete", + "raw": { + "description": "Removes the member from the org, ie. all groups in the org, unless they're the last owner\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "deleteV2OrgsByOrgNameMembersByUsername", + "responses": { + "204": { + "description": "Member removed successfully" + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Remove member from org", + "tags": [ + "orgs" + ] + }, + "references": [ + { + "ref": "#/components/responses/bad_request", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/not_found", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Remove member from org", + "tags": [ + "orgs" + ], + "url": "/reference/api/hub/latest/operations/deleteV2OrgsByOrgNameMembersByUsername/", + "variants": [ + { + "description": "Member removed successfully", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete/responses/204", + "status": "204" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/myorganization/settings'", + "curlNotes": [], + "deprecated": null, + "description": "Returns organization settings by name.\n", + "id": "getV2OrgsByNameSettings", + "line": 872, + "method": "GET", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/settings", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/get", + "raw": { + "description": "Returns organization settings by name.\n", + "operationId": "getV2OrgsByNameSettings", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/orgSettings" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get organization settings", + "tags": [ + "org-settings" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/orgSettings", + "url": "/reference/api/hub/latest/schemas/orgSettings/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get organization settings", + "tags": [ + "org-settings" + ], + "url": "/reference/api/hub/latest/operations/getV2OrgsByNameSettings/", + "variants": [ + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"restricted_images\": {\n \"allow_official_images\": true,\n \"allow_verified_publishers\": true,\n \"enabled\": true\n }\n}", + "value": { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/orgSettings" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"restricted_images\": {\n \"allow_official_images\": true,\n \"allow_verified_publishers\": true,\n \"enabled\": true\n }\n}' \\\n 'https://hub.docker.com/v2/orgs/myorganization/settings'", + "curlNotes": [], + "deprecated": null, + "description": "Updates an organization's settings. Some settings are only used when the organization is on a business subscription.\n\n***Only users with administrative privileges for the organization (owner role) can modify these settings.***\n\nThe following settings are only used on a business subscription:\n- `restricted_images`\n", + "id": "putV2OrgsByNameSettings", + "line": 894, + "method": "PUT", + "parameters": [ + { + "description": "Name of the organization (namespace).", + "example": "myorganization", + "in": "path", + "name": "org_name", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/orgs/{org_name}/settings", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put", + "raw": { + "description": "Updates an organization's settings. Some settings are only used when the organization is on a business subscription.\n\n***Only users with administrative privileges for the organization (owner role) can modify these settings.***\n\nThe following settings are only used on a business subscription:\n- `restricted_images`\n", + "operationId": "putV2OrgsByNameSettings", + "requestBody": { + "content": { + "application/json": { + "schema": { + "examples": [ + { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + ], + "properties": { + "restricted_images": { + "allOf": [ + { + "$ref": "#/components/schemas/restricted_images" + }, + { + "required": [ + "enabled", + "allow_official_images", + "allow_verified_publishers" + ], + "type": "object" + } + ] + } + }, + "required": [ + "restricted_images" + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/orgSettings" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Update organization settings", + "tags": [ + "org-settings" + ] + }, + "references": [ + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/orgSettings", + "url": "/reference/api/hub/latest/schemas/orgSettings/" + }, + { + "ref": "#/components/schemas/restricted_images", + "url": "/reference/api/hub/latest/schemas/restricted_images/" + } + ], + "requestSchema": { + "examples": [ + { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + ], + "properties": { + "restricted_images": { + "allOf": [ + { + "$ref": "#/components/schemas/restricted_images" + }, + { + "required": [ + "enabled", + "allow_official_images", + "allow_verified_publishers" + ], + "type": "object" + } + ] + } + }, + "required": [ + "restricted_images" + ] + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update organization settings", + "tags": [ + "org-settings" + ], + "url": "/reference/api/hub/latest/operations/putV2OrgsByNameSettings/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"restricted_images\": {\n \"allow_official_images\": true,\n \"allow_verified_publishers\": true,\n \"enabled\": true\n }\n}", + "value": { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put/requestBody/content/application~1json", + "required": true, + "schema": { + "examples": [ + { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + ], + "properties": { + "restricted_images": { + "allOf": [ + { + "$ref": "#/components/schemas/restricted_images" + }, + { + "required": [ + "enabled", + "allow_official_images", + "allow_verified_publishers" + ], + "type": "object" + } + ] + } + }, + "required": [ + "restricted_images" + ] + }, + "status": "" + }, + { + "description": "OK", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"restricted_images\": {\n \"allow_official_images\": true,\n \"allow_verified_publishers\": true,\n \"enabled\": true\n }\n}", + "value": { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/orgSettings" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1orgs~1{org_name}~1settings/put/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"group_id\": 12345,\n \"permission\": \"write\"\n}' \\\n 'https://hub.docker.com/v2/repositories/\u003cNAMESPACE\u003e/\u003cREPOSITORY\u003e/groups'", + "curlNotes": [], + "deprecated": null, + "description": "Assigns an organization group (team) to a repository with a specified permission level.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "id": "CreateRepositoryGroup", + "line": 1226, + "method": "POST", + "parameters": [ + { + "description": "Namespace of the repository, such as a user or organization name.", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Name of the repository within the namespace.", + "in": "path", + "name": "repository", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/repositories/{namespace}/{repository}/groups", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post", + "raw": { + "description": "Assigns an organization group (team) to a repository with a specified permission level.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n", + "operationId": "CreateRepositoryGroup", + "requestBody": { + "content": { + "application/json": { + "example": { + "group_id": 12345, + "permission": "write" + }, + "schema": { + "$ref": "#/components/schemas/RepositoryGroupCreationRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "example": { + "group_id": 12345, + "group_name": "developers", + "permission": "write" + }, + "schema": { + "$ref": "#/components/schemas/RepositoryGroup" + } + } + }, + "description": "Repository group permission created successfully" + }, + "400": { + "content": { + "application/json": { + "examples": { + "error": { + "summary": "Example error response", + "value": { + "errinfo": null, + "message": "bad request" + } + } + }, + "schema": { + "$ref": "#/components/schemas/error" + } + } + }, + "description": "Bad Request - Invalid request parameters" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Assign a group (Team) to a repository for access", + "tags": [ + "repositories" + ] + }, + "references": [ + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/forbidden", + "url": null + }, + { + "ref": "#/components/responses/unauthorized", + "url": null + }, + { + "ref": "#/components/schemas/RepositoryGroup", + "url": "/reference/api/hub/latest/schemas/RepositoryGroup/" + }, + { + "ref": "#/components/schemas/RepositoryGroupCreationRequest", + "url": "/reference/api/hub/latest/schemas/RepositoryGroupCreationRequest/" + }, + { + "ref": "#/components/schemas/error", + "url": "/reference/api/hub/latest/schemas/error/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/RepositoryGroupCreationRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Assign a group (Team) to a repository for access", + "tags": [ + "repositories" + ], + "url": "/reference/api/hub/latest/operations/CreateRepositoryGroup/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Example", + "text": "{\n \"group_id\": 12345,\n \"permission\": \"write\"\n}", + "value": { + "group_id": 12345, + "permission": "write" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/RepositoryGroupCreationRequest" + }, + "status": "" + }, + { + "description": "Repository group permission created successfully", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Example", + "text": "{\n \"group_id\": 12345,\n \"group_name\": \"developers\",\n \"permission\": \"write\"\n}", + "value": { + "group_id": 12345, + "group_name": "developers", + "permission": "write" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/RepositoryGroup" + }, + "status": "200" + }, + { + "description": "Bad Request - Invalid request parameters", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"bad request\"\n}", + "value": { + "errinfo": null, + "message": "bad request" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"unauthorized\"\n}", + "value": { + "errinfo": null, + "message": "unauthorized" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"permission denied\"\n}", + "value": { + "errinfo": null, + "message": "permission denied" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"errinfo\": null,\n \"message\": \"not found\"\n}", + "value": { + "errinfo": null, + "message": "not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1repositories~1{namespace}~1{repository}~1groups/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/error" + }, + "status": "404" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/ResourceTypes'", + "curlNotes": [], + "deprecated": null, + "description": "Returns all resource types supported for the SCIM configuration.\n", + "id": "getV2Scim20ResourceTypes", + "line": 2229, + "method": "GET", + "parameters": [], + "path": "/v2/scim/2.0/ResourceTypes", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes/get", + "raw": { + "description": "Returns all resource types supported for the SCIM configuration.\n", + "operationId": "getV2Scim20ResourceTypes", + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_resource_types_resp" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "List resource types", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_get_resource_types_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List resource types", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20ResourceTypes/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"Resources\": [\n {\n \"description\": \"User\",\n \"endpoint\": \"/Users\",\n \"id\": \"User\",\n \"name\": \"User\",\n \"schema\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:ResourceType\"\n ]\n }\n ],\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:ListResponse\"\n ],\n \"totalResults\": 1\n}", + "value": { + "Resources": [ + { + "description": "User", + "endpoint": "/Users", + "id": "User", + "name": "User", + "schema": "urn:ietf:params:scim:schemas:core:2.0:User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + ] + } + ], + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1 + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "examples": [ + { + "Resources": [ + { + "description": "User", + "endpoint": "/Users", + "id": "User", + "name": "User", + "schema": "urn:ietf:params:scim:schemas:core:2.0:User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + ] + } + ], + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1 + } + ], + "properties": { + "Resources": { + "items": { + "$ref": "#/components/schemas/scim_resource_type" + }, + "type": "array" + }, + "schemas": { + "items": { + "example": "urn:ietf:params:scim:api:messages:2.0:ListResponse", + "type": "string" + }, + "type": "array" + }, + "totalResults": { + "example": 1, + "type": "integer" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/ResourceTypes/User'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a resource type by name.\n", + "id": "getV2Scim20ResourceTypesByName", + "line": 2247, + "method": "GET", + "parameters": [ + { + "description": "Name of the SCIM resource type.", + "example": "User", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/scim/2.0/ResourceTypes/{name}", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get", + "raw": { + "description": "Returns a resource type by name.\n", + "operationId": "getV2Scim20ResourceTypesByName", + "parameters": [ + { + "description": "Name of the SCIM resource type.", + "example": "User", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_resource_type_resp" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Get a resource type", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_get_resource_type_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get a resource type", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20ResourceTypesByName/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"description\": \"User\",\n \"endpoint\": \"/Users\",\n \"id\": \"User\",\n \"name\": \"User\",\n \"schema\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:ResourceType\"\n ]\n}", + "value": { + "description": "User", + "endpoint": "/Users", + "id": "User", + "name": "User", + "schema": "urn:ietf:params:scim:schemas:core:2.0:User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + ] + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_resource_type" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/Schemas'", + "curlNotes": [], + "deprecated": null, + "description": "Returns all schemas supported for the SCIM configuration.\n", + "id": "getV2Scim20Schemas", + "line": 2275, + "method": "GET", + "parameters": [], + "path": "/v2/scim/2.0/Schemas", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas/get", + "raw": { + "description": "Returns all schemas supported for the SCIM configuration.\n", + "operationId": "getV2Scim20Schemas", + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_schemas_resp" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "List schemas", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_get_schemas_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List schemas", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20Schemas/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"Resources\": [\n {\n \"attributes\": [],\n \"description\": \"User Account\",\n \"id\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"name\": \"User\",\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:Schema\"\n ]\n }\n ],\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:ListResponse\"\n ],\n \"totalResults\": 1\n}", + "value": { + "Resources": [ + { + "attributes": [], + "description": "User Account", + "id": "urn:ietf:params:scim:schemas:core:2.0:User", + "name": "User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Schema" + ] + } + ], + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1 + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "examples": [ + { + "Resources": [ + { + "attributes": [], + "description": "User Account", + "id": "urn:ietf:params:scim:schemas:core:2.0:User", + "name": "User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Schema" + ] + } + ], + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1 + } + ], + "properties": { + "Resources": { + "items": { + "$ref": "#/components/schemas/scim_schema" + }, + "type": "array" + }, + "schemas": { + "items": { + "example": "urn:ietf:params:scim:api:messages:2.0:ListResponse", + "type": "string" + }, + "type": "array" + }, + "totalResults": { + "example": 1, + "type": "integer" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/Schemas/urn:ietf:params:scim:schemas:core:2.0:User'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a schema by ID.\n", + "id": "getV2Scim20SchemasById", + "line": 2293, + "method": "GET", + "parameters": [ + { + "description": "URN identifying the SCIM schema.", + "example": "urn:ietf:params:scim:schemas:core:2.0:User", + "in": "path", + "name": "id", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/scim/2.0/Schemas/{id}", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get", + "raw": { + "description": "Returns a schema by ID.\n", + "operationId": "getV2Scim20SchemasById", + "parameters": [ + { + "description": "URN identifying the SCIM schema.", + "example": "urn:ietf:params:scim:schemas:core:2.0:User", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_schema_resp" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Get a schema", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_get_schema_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get a schema", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20SchemasById/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"attributes\": [],\n \"description\": \"User Account\",\n \"id\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"name\": \"User\",\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:Schema\"\n ]\n}", + "value": { + "attributes": [], + "description": "User Account", + "id": "urn:ietf:params:scim:schemas:core:2.0:User", + "name": "User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Schema" + ] + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_schema" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Schemas~1{id}/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/ServiceProviderConfig'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a service provider config for Docker's configuration.\n", + "id": "getV2Scim20ServiceProviderConfig", + "line": 2211, + "method": "GET", + "parameters": [], + "path": "/v2/scim/2.0/ServiceProviderConfig", + "pointer": "/paths/~1v2~1scim~12.0~1ServiceProviderConfig/get", + "raw": { + "description": "Returns a service provider config for Docker's configuration.\n", + "operationId": "getV2Scim20ServiceProviderConfig", + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_service_provider_config_resp" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Get service provider config", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_get_service_provider_config_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get service provider config", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20ServiceProviderConfig/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"authenticationSchemes\": [\n {\n \"name\": \"OAuth 2.0 Bearer Token\",\n \"specUri\": \"http://tools.ietf.org/html/rfc6750\",\n \"type\": \"oauthbearertoken\"\n }\n ],\n \"bulk\": {\n \"maxOperations\": 0,\n \"maxPayloadSize\": 0,\n \"supported\": false\n },\n \"changePassword\": {\n \"supported\": false\n },\n \"etag\": {\n \"supported\": false\n },\n \"filter\": {\n \"maxResults\": 200,\n \"supported\": true\n },\n \"patch\": {\n \"supported\": true\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig\"\n ],\n \"sort\": {\n \"supported\": true\n }\n}", + "value": { + "authenticationSchemes": [ + { + "name": "OAuth 2.0 Bearer Token", + "specUri": "http://tools.ietf.org/html/rfc6750", + "type": "oauthbearertoken" + } + ], + "bulk": { + "maxOperations": 0, + "maxPayloadSize": 0, + "supported": false + }, + "changePassword": { + "supported": false + }, + "etag": { + "supported": false + }, + "filter": { + "maxResults": 200, + "supported": true + }, + "patch": { + "supported": true + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" + ], + "sort": { + "supported": true + } + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ServiceProviderConfig/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_service_provider_config" + }, + "status": "200" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ServiceProviderConfig/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1ServiceProviderConfig/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/Users?startIndex=1\u0026count=10\u0026filter=userName+eq+%22jon.snow%40docker.com%22\u0026attributes=userName%2CdisplayName\u0026sortBy=userName'", + "curlNotes": [], + "deprecated": null, + "description": "Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results.\n\n**Sorting:**\n\nSorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters.\n\nThe `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are \"ascending\" and \"descending\".\n\n**Filtering:**\n\nYou can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.\n\nSupported operators are listed below.\n\n- `eq` equal\n- `ne` not equal\n- `co` contains\n- `sw` starts with\n- `and` Logical \"and\"\n- `or` Logical \"or\"\n- `not` \"Not\" function\n- `()` Precedence grouping\n", + "id": "getV2Scim20Users", + "line": 2321, + "method": "GET", + "parameters": [ + { + "description": "One-based index of the first result to return.", + "example": 1, + "in": "query", + "name": "startIndex", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/0", + "schema": { + "minimum": 1, + "type": "integer" + } + }, + { + "description": "Maximum number of results to return.", + "example": 10, + "in": "query", + "name": "count", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/1", + "schema": { + "maximum": 200, + "minimum": 1, + "type": "integer" + } + }, + { + "description": "SCIM filter expression used to select users.", + "example": "userName eq \"jon.snow@docker.com\"", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/2", + "schema": { + "type": "string" + } + }, + { + "description": "Comma delimited list of attributes to limit to in the response.", + "example": "userName,displayName", + "in": "query", + "name": "attributes", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/3", + "schema": { + "type": "string" + } + }, + { + "description": "Sort direction applied to the attribute specified by sortBy.", + "in": "query", + "name": "sortOrder", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/4", + "schema": { + "enum": [ + "ascending", + "descending" + ], + "type": "string" + } + }, + { + "description": "User attribute to sort by.", + "example": "userName", + "in": "query", + "name": "sortBy", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/5", + "schema": { + "type": "string" + } + } + ], + "path": "/v2/scim/2.0/Users", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get", + "raw": { + "description": "Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results.\n\n**Sorting:**\n\nSorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters.\n\nThe `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are \"ascending\" and \"descending\".\n\n**Filtering:**\n\nYou can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.\n\nSupported operators are listed below.\n\n- `eq` equal\n- `ne` not equal\n- `co` contains\n- `sw` starts with\n- `and` Logical \"and\"\n- `or` Logical \"or\"\n- `not` \"Not\" function\n- `()` Precedence grouping\n", + "operationId": "getV2Scim20Users", + "parameters": [ + { + "description": "One-based index of the first result to return.", + "example": 1, + "in": "query", + "name": "startIndex", + "schema": { + "minimum": 1, + "type": "integer" + } + }, + { + "description": "Maximum number of results to return.", + "example": 10, + "in": "query", + "name": "count", + "schema": { + "maximum": 200, + "minimum": 1, + "type": "integer" + } + }, + { + "description": "SCIM filter expression used to select users.", + "example": "userName eq \"jon.snow@docker.com\"", + "in": "query", + "name": "filter", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/scim_attributes" + }, + { + "description": "Sort direction applied to the attribute specified by sortBy.", + "in": "query", + "name": "sortOrder", + "schema": { + "enum": [ + "ascending", + "descending" + ], + "type": "string" + } + }, + { + "description": "User attribute to sort by.", + "example": "userName", + "in": "query", + "name": "sortBy", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_users_resp" + }, + "400": { + "$ref": "#/components/responses/scim_bad_request" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "403": { + "$ref": "#/components/responses/scim_forbidden" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "List users", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/parameters/scim_attributes", + "url": null + }, + { + "ref": "#/components/responses/scim_bad_request", + "url": null + }, + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_forbidden", + "url": null + }, + { + "ref": "#/components/responses/scim_get_users_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "List users", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20Users/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"Resources\": [\n {\n \"active\": true,\n \"displayName\": \"jonsnow\",\n \"emails\": [\n {\n \"display\": \"jon.snow@docker.com\",\n \"primary\": true,\n \"value\": \"jon.snow@docker.com\"\n }\n ],\n \"groups\": [\n {\n \"display\": \"nightswatch\",\n \"value\": \"nightswatch\"\n }\n ],\n \"id\": \"d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"meta\": {\n \"created\": \"2022-05-20T00:54:18Z\",\n \"lastModified\": \"2022-05-20T00:54:18Z\",\n \"location\": \"https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"resourceType\": \"User\"\n },\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n }\n ],\n \"itemsPerPage\": 1,\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:ListResponse\"\n ],\n \"startIndex\": 1,\n \"totalResults\": 1\n}", + "value": { + "Resources": [ + { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "itemsPerPage": 1, + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "startIndex": 1, + "totalResults": 1 + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "examples": [ + { + "Resources": [ + { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "itemsPerPage": 1, + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "startIndex": 1, + "totalResults": 1 + } + ], + "properties": { + "Resources": { + "items": { + "$ref": "#/components/schemas/scim_user" + }, + "type": "array" + }, + "itemsPerPage": { + "example": 10, + "type": "integer" + }, + "schemas": { + "example": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "startIndex": { + "example": 1, + "type": "integer" + }, + "totalResults": { + "example": 1, + "type": "integer" + } + }, + "type": "object" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"400\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "400" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/400/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "scimType": { + "description": "Some types of errors will return this per the specification.", + "type": "string" + }, + "status": { + "example": "400" + } + } + } + ] + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"403\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "403" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/403/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "403" + } + } + } + ] + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n --header 'Content-Type: application/scim+json' \\\n --data-raw '{\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}' \\\n 'https://hub.docker.com/v2/scim/2.0/Users'", + "curlNotes": [], + "deprecated": null, + "description": "Creates a user. If the user already exists by email, they are assigned to the organization on the \"company\" team.\n", + "id": "postV2Scim20Users", + "line": 2401, + "method": "POST", + "parameters": [], + "path": "/v2/scim/2.0/Users", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post", + "raw": { + "description": "Creates a user. If the user already exists by email, they are assigned to the organization on the \"company\" team.\n", + "operationId": "postV2Scim20Users", + "requestBody": { + "$ref": "#/components/requestBodies/scim_create_user_request" + }, + "responses": { + "201": { + "$ref": "#/components/responses/scim_create_user_resp" + }, + "400": { + "$ref": "#/components/responses/scim_bad_request" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "403": { + "$ref": "#/components/responses/scim_forbidden" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "409": { + "$ref": "#/components/responses/scim_conflict" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Create user", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/requestBodies/scim_create_user_request", + "url": null + }, + { + "ref": "#/components/responses/scim_bad_request", + "url": null + }, + { + "ref": "#/components/responses/scim_conflict", + "url": null + }, + { + "ref": "#/components/responses/scim_create_user_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_forbidden", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": { + "examples": [ + { + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "properties": { + "name": { + "$ref": "#/components/schemas/scim_user_name" + }, + "schemas": { + "$ref": "#/components/schemas/scim_user_schemas" + }, + "userName": { + "$ref": "#/components/schemas/scim_user_username" + } + }, + "required": [ + "schemas", + "userName" + ], + "type": "object" + }, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create user", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/postV2Scim20Users/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}", + "value": { + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/requestBody/content/application~1scim+json", + "required": true, + "schema": { + "examples": [ + { + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "properties": { + "name": { + "$ref": "#/components/schemas/scim_user_name" + }, + "schemas": { + "$ref": "#/components/schemas/scim_user_schemas" + }, + "userName": { + "$ref": "#/components/schemas/scim_user_username" + } + }, + "required": [ + "schemas", + "userName" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"active\": true,\n \"displayName\": \"jonsnow\",\n \"emails\": [\n {\n \"display\": \"jon.snow@docker.com\",\n \"primary\": true,\n \"value\": \"jon.snow@docker.com\"\n }\n ],\n \"groups\": [\n {\n \"display\": \"nightswatch\",\n \"value\": \"nightswatch\"\n }\n ],\n \"id\": \"d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"meta\": {\n \"created\": \"2022-05-20T00:54:18Z\",\n \"lastModified\": \"2022-05-20T00:54:18Z\",\n \"location\": \"https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"resourceType\": \"User\"\n },\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}", + "value": { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/201/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_user" + }, + "status": "201" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"400\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "400" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/400/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "scimType": { + "description": "Some types of errors will return this per the specification.", + "type": "string" + }, + "status": { + "example": "400" + } + } + } + ] + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"403\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "403" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/403/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "403" + } + } + } + ] + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"409\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "409" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/409/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "409" + } + } + } + ] + }, + "status": "409" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users/post/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n 'https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a user by ID.\n", + "id": "getV2Scim20UsersById", + "line": 2431, + "method": "GET", + "parameters": [ + { + "description": "The user ID.", + "example": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "in": "path", + "name": "id", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/scim/2.0/Users/{id}", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get", + "raw": { + "description": "Returns a user by ID.\n", + "operationId": "getV2Scim20UsersById", + "responses": { + "200": { + "$ref": "#/components/responses/scim_get_user_resp" + }, + "400": { + "$ref": "#/components/responses/scim_bad_request" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "403": { + "$ref": "#/components/responses/scim_forbidden" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Get a user", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/responses/scim_bad_request", + "url": null + }, + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_forbidden", + "url": null + }, + { + "ref": "#/components/responses/scim_get_user_resp", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + } + ], + "requestSchema": null, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Get a user", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/getV2Scim20UsersById/", + "variants": [ + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"active\": true,\n \"displayName\": \"jonsnow\",\n \"emails\": [\n {\n \"display\": \"jon.snow@docker.com\",\n \"primary\": true,\n \"value\": \"jon.snow@docker.com\"\n }\n ],\n \"groups\": [\n {\n \"display\": \"nightswatch\",\n \"value\": \"nightswatch\"\n }\n ],\n \"id\": \"d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"meta\": {\n \"created\": \"2022-05-20T00:54:18Z\",\n \"lastModified\": \"2022-05-20T00:54:18Z\",\n \"location\": \"https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"resourceType\": \"User\"\n },\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}", + "value": { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_user" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"400\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "400" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/400/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "scimType": { + "description": "Some types of errors will return this per the specification.", + "type": "string" + }, + "status": { + "example": "400" + } + } + } + ] + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"403\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "403" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/403/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "403" + } + } + } + ] + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/get/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/scim+json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${SCIM_TOKEN}\" \\\n --header 'Accept: application/scim+json' \\\n --header 'Content-Type: application/scim+json' \\\n --data-raw '{\n \"active\": true,\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}' \\\n 'https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c'", + "curlNotes": [], + "deprecated": null, + "description": "Updates a user. This route is used to change the user's name, activate, and deactivate the user.\n", + "id": "putV2Scim20UsersById", + "line": 2453, + "method": "PUT", + "parameters": [ + { + "description": "The user ID.", + "example": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "in": "path", + "name": "id", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/scim/2.0/Users/{id}", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put", + "raw": { + "description": "Updates a user. This route is used to change the user's name, activate, and deactivate the user.\n", + "operationId": "putV2Scim20UsersById", + "requestBody": { + "$ref": "#/components/requestBodies/scim_update_user_request" + }, + "responses": { + "200": { + "$ref": "#/components/responses/scim_update_user_resp" + }, + "400": { + "$ref": "#/components/responses/scim_bad_request" + }, + "401": { + "$ref": "#/components/responses/scim_unauthorized" + }, + "403": { + "$ref": "#/components/responses/scim_forbidden" + }, + "404": { + "$ref": "#/components/responses/scim_not_found" + }, + "409": { + "$ref": "#/components/responses/scim_conflict" + }, + "500": { + "$ref": "#/components/responses/scim_error" + } + }, + "security": [ + { + "scimToken": [] + } + ], + "summary": "Update a user", + "tags": [ + "scim" + ] + }, + "references": [ + { + "ref": "#/components/requestBodies/scim_update_user_request", + "url": null + }, + { + "ref": "#/components/responses/scim_bad_request", + "url": null + }, + { + "ref": "#/components/responses/scim_conflict", + "url": null + }, + { + "ref": "#/components/responses/scim_error", + "url": null + }, + { + "ref": "#/components/responses/scim_forbidden", + "url": null + }, + { + "ref": "#/components/responses/scim_not_found", + "url": null + }, + { + "ref": "#/components/responses/scim_unauthorized", + "url": null + }, + { + "ref": "#/components/responses/scim_update_user_resp", + "url": null + } + ], + "requestSchema": { + "examples": [ + { + "active": true, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "properties": { + "active": { + "default": false, + "description": "Whether the user is active. Defaults to false when omitted.", + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/scim_user_name" + }, + "schemas": { + "$ref": "#/components/schemas/scim_user_schemas" + }, + "userName": { + "$ref": "#/components/schemas/scim_user_username" + } + }, + "required": [ + "schemas", + "userName" + ], + "type": "object" + }, + "security": [ + { + "scimToken": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Update a user", + "tags": [ + "scim" + ], + "url": "/reference/api/hub/latest/operations/putV2Scim20UsersById/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"active\": true,\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}", + "value": { + "active": true, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/requestBody/content/application~1scim+json", + "required": true, + "schema": { + "examples": [ + { + "active": true, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "properties": { + "active": { + "default": false, + "description": "Whether the user is active. Defaults to false when omitted.", + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/scim_user_name" + }, + "schemas": { + "$ref": "#/components/schemas/scim_user_schemas" + }, + "userName": { + "$ref": "#/components/schemas/scim_user_username" + } + }, + "required": [ + "schemas", + "userName" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"active\": true,\n \"displayName\": \"jonsnow\",\n \"emails\": [\n {\n \"display\": \"jon.snow@docker.com\",\n \"primary\": true,\n \"value\": \"jon.snow@docker.com\"\n }\n ],\n \"groups\": [\n {\n \"display\": \"nightswatch\",\n \"value\": \"nightswatch\"\n }\n ],\n \"id\": \"d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"meta\": {\n \"created\": \"2022-05-20T00:54:18Z\",\n \"lastModified\": \"2022-05-20T00:54:18Z\",\n \"location\": \"https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c\",\n \"resourceType\": \"User\"\n },\n \"name\": {\n \"familyName\": \"Snow\",\n \"givenName\": \"Jon\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"jon.snow@docker.com\"\n}", + "value": { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/200/content/application~1scim+json", + "required": null, + "schema": { + "$ref": "#/components/schemas/scim_user" + }, + "status": "200" + }, + { + "description": "Bad Request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"400\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "400" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/400/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "scimType": { + "description": "Some types of errors will return this per the specification.", + "type": "string" + }, + "status": { + "example": "400" + } + } + } + ] + }, + "status": "400" + }, + { + "description": "Unauthorized", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"401\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "401" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/401/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "401" + } + } + } + ] + }, + "status": "401" + }, + { + "description": "Forbidden", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"403\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "403" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/403/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "403" + } + } + } + ] + }, + "status": "403" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"404\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "404" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/404/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "404" + } + } + } + ] + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"409\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "409" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/409/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "409" + } + } + } + ] + }, + "status": "409" + }, + { + "description": "Internal Error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "error", + "text": "{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"status\": \"500\"\n}", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:Error" + ], + "status": "500" + } + } + ], + "headers": null, + "media": "application/scim+json", + "pointer": "/paths/~1v2~1scim~12.0~1Users~1{id}/put/responses/500/content/application~1scim+json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_error" + }, + { + "properties": { + "status": { + "example": "500" + } + } + } + ] + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"code\": \"123456\",\n \"login_2fa_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}' \\\n 'https://hub.docker.com/v2/users/2fa-login'", + "curlNotes": [], + "deprecated": null, + "description": "When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/auth/token` call.\n\nCreates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "id": "PostUsers2FALogin", + "line": 218, + "method": "POST", + "parameters": [], + "path": "/v2/users/2fa-login", + "pointer": "/paths/~1v2~1users~12fa-login/post", + "raw": { + "description": "When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/auth/token` call.\n\nCreates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "operationId": "PostUsers2FALogin", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + } + } + }, + "description": "Login details.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + } + } + }, + "description": "Authentication successful" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsers2FALoginErrorResponse" + } + } + }, + "description": "Authentication failed" + } + }, + "security": [], + "summary": "Second factor authentication", + "tags": [ + "authentication-api" + ] + }, + "references": [ + { + "ref": "#/components/schemas/PostUsers2FALoginErrorResponse", + "url": "/reference/api/hub/latest/schemas/PostUsers2FALoginErrorResponse/" + }, + { + "ref": "#/components/schemas/PostUsersLoginSuccessResponse", + "url": "/reference/api/hub/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "ref": "#/components/schemas/Users2FALoginRequest", + "url": "/reference/api/hub/latest/schemas/Users2FALoginRequest/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + }, + "security": [], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Second factor authentication", + "tags": [ + "authentication-api" + ], + "url": "/reference/api/hub/latest/operations/PostUsers2FALogin/", + "variants": [ + { + "description": "Login details.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"123456\",\n \"login_2fa_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "code": "123456", + "login_2fa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + }, + "status": "" + }, + { + "description": "Authentication successful", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + }, + "status": "200" + }, + { + "description": "Authentication failed", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"detail\": \"Incorrect authentication credentials\"\n}", + "value": { + "detail": "Incorrect authentication credentials" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsers2FALoginErrorResponse" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"password\": \"p@ssw0rd\",\n \"username\": \"myusername\"\n}' \\\n 'https://hub.docker.com/v2/users/login'", + "curlNotes": [], + "deprecated": true, + "description": "Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\n_**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_\n\n\n Deprecated: Use [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) instead.\n\n", + "id": "PostUsersLogin", + "line": 180, + "method": "POST", + "parameters": [], + "path": "/v2/users/login", + "pointer": "/paths/~1v2~1users~1login/post", + "raw": { + "deprecated": true, + "description": "Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\n_**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_\n\n\n Deprecated: Use [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) instead.\n\n", + "operationId": "PostUsersLogin", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsersLoginRequest" + } + } + }, + "description": "Login details.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + } + } + }, + "description": "Authentication successful" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginErrorResponse" + } + } + }, + "description": "Authentication failed or second factor required" + } + }, + "security": [], + "summary": "Create an authentication token", + "tags": [ + "authentication-api" + ] + }, + "references": [ + { + "ref": "#/components/schemas/PostUsersLoginErrorResponse", + "url": "/reference/api/hub/latest/schemas/PostUsersLoginErrorResponse/" + }, + { + "ref": "#/components/schemas/PostUsersLoginSuccessResponse", + "url": "/reference/api/hub/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "ref": "#/components/schemas/UsersLoginRequest", + "url": "/reference/api/hub/latest/schemas/UsersLoginRequest/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/UsersLoginRequest" + }, + "security": [], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "summary": "Create an authentication token", + "tags": [ + "authentication-api" + ], + "url": "/reference/api/hub/latest/operations/PostUsersLogin/", + "variants": [ + { + "description": "Login details.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"password\": \"p@ssw0rd\",\n \"username\": \"myusername\"\n}", + "value": { + "password": "p@ssw0rd", + "username": "myusername" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/UsersLoginRequest" + }, + "status": "" + }, + { + "description": "Authentication successful", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + }, + "status": "200" + }, + { + "description": "Authentication failed or second factor required", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"detail\": \"Incorrect authentication credentials\"\n}", + "value": { + "detail": "Incorrect authentication credentials" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginErrorResponse" + }, + "status": "401" + } + ] + } + ], + "owner": "docker/docs", + "product": "hub", + "schemaCount": 197, + "schemaURLs": { + "#/components/schemas/AuditLog": "/reference/api/hub/latest/schemas/AuditLog/", + "#/components/schemas/AuditLogAction": "/reference/api/hub/latest/schemas/AuditLogAction/", + "#/components/schemas/AuditLogActions": "/reference/api/hub/latest/schemas/AuditLogActions/", + "#/components/schemas/AuthCreateTokenResponse": "/reference/api/hub/latest/schemas/AuthCreateTokenResponse/", + "#/components/schemas/GetAuditActionsResponse": "/reference/api/hub/latest/schemas/GetAuditActionsResponse/", + "#/components/schemas/GetAuditLogsResponse": "/reference/api/hub/latest/schemas/GetAuditLogsResponse/", + "#/components/schemas/PostUsers2FALoginErrorResponse": "/reference/api/hub/latest/schemas/PostUsers2FALoginErrorResponse/", + "#/components/schemas/PostUsersLoginErrorResponse": "/reference/api/hub/latest/schemas/PostUsersLoginErrorResponse/", + "#/components/schemas/PostUsersLoginSuccessResponse": "/reference/api/hub/latest/schemas/PostUsersLoginSuccessResponse/", + "#/components/schemas/RepositoryGroup": "/reference/api/hub/latest/schemas/RepositoryGroup/", + "#/components/schemas/RepositoryGroupCreationRequest": "/reference/api/hub/latest/schemas/RepositoryGroupCreationRequest/", + "#/components/schemas/Users2FALoginRequest": "/reference/api/hub/latest/schemas/Users2FALoginRequest/", + "#/components/schemas/UsersLoginRequest": "/reference/api/hub/latest/schemas/UsersLoginRequest/", + "#/components/schemas/accessToken": "/reference/api/hub/latest/schemas/accessToken/", + "#/components/schemas/bulk_invite": "/reference/api/hub/latest/schemas/bulk_invite/", + "#/components/schemas/category": "/reference/api/hub/latest/schemas/category/", + "#/components/schemas/createAccessTokenRequest": "/reference/api/hub/latest/schemas/createAccessTokenRequest/", + "#/components/schemas/createAccessTokensResponse": "/reference/api/hub/latest/schemas/createAccessTokensResponse/", + "#/components/schemas/createOrgAccessTokenRequest": "/reference/api/hub/latest/schemas/createOrgAccessTokenRequest/", + "#/components/schemas/createOrgAccessTokenResponse": "/reference/api/hub/latest/schemas/createOrgAccessTokenResponse/", + "#/components/schemas/email_address": "/reference/api/hub/latest/schemas/email_address/", + "#/components/schemas/email_with_username": "/reference/api/hub/latest/schemas/email_with_username/", + "#/components/schemas/error": "/reference/api/hub/latest/schemas/error/", + "#/components/schemas/getAccessTokensResponse": "/reference/api/hub/latest/schemas/getAccessTokensResponse/", + "#/components/schemas/getOrgAccessTokenResponse": "/reference/api/hub/latest/schemas/getOrgAccessTokenResponse/", + "#/components/schemas/getOrgAccessTokensResponse": "/reference/api/hub/latest/schemas/getOrgAccessTokensResponse/", + "#/components/schemas/group_member": "/reference/api/hub/latest/schemas/group_member/", + "#/components/schemas/image": "/reference/api/hub/latest/schemas/image/", + "#/components/schemas/immutable_tags_settings": "/reference/api/hub/latest/schemas/immutable_tags_settings/", + "#/components/schemas/immutable_tags_verify_request": "/reference/api/hub/latest/schemas/immutable_tags_verify_request/", + "#/components/schemas/immutable_tags_verify_response": "/reference/api/hub/latest/schemas/immutable_tags_verify_response/", + "#/components/schemas/invite": "/reference/api/hub/latest/schemas/invite/", + "#/components/schemas/layer": "/reference/api/hub/latest/schemas/layer/", + "#/components/schemas/legacy_email_address": "/reference/api/hub/latest/schemas/legacy_email_address/", + "#/components/schemas/list_repositories_response": "/reference/api/hub/latest/schemas/list_repositories_response/", + "#/components/schemas/orgAccessToken": "/reference/api/hub/latest/schemas/orgAccessToken/", + "#/components/schemas/orgAccessTokenResource": "/reference/api/hub/latest/schemas/orgAccessTokenResource/", + "#/components/schemas/orgSettings": "/reference/api/hub/latest/schemas/orgSettings/", + "#/components/schemas/org_group": "/reference/api/hub/latest/schemas/org_group/", + "#/components/schemas/org_member": "/reference/api/hub/latest/schemas/org_member/", + "#/components/schemas/org_member_paginated": "/reference/api/hub/latest/schemas/org_member_paginated/", + "#/components/schemas/page": "/reference/api/hub/latest/schemas/page/", + "#/components/schemas/paginated_tags": "/reference/api/hub/latest/schemas/paginated_tags/", + "#/components/schemas/patchAccessTokenRequest": "/reference/api/hub/latest/schemas/patchAccessTokenRequest/", + "#/components/schemas/patchAccessTokenResponse": "/reference/api/hub/latest/schemas/patchAccessTokenResponse/", + "#/components/schemas/repo_creation_request": "/reference/api/hub/latest/schemas/repo_creation_request/", + "#/components/schemas/repo_permissions": "/reference/api/hub/latest/schemas/repo_permissions/", + "#/components/schemas/repository_info": "/reference/api/hub/latest/schemas/repository_info/", + "#/components/schemas/repository_list_entry": "/reference/api/hub/latest/schemas/repository_list_entry/", + "#/components/schemas/restricted_images": "/reference/api/hub/latest/schemas/restricted_images/", + "#/components/schemas/scim_email": "/reference/api/hub/latest/schemas/scim_email/", + "#/components/schemas/scim_error": "/reference/api/hub/latest/schemas/scim_error/", + "#/components/schemas/scim_group": "/reference/api/hub/latest/schemas/scim_group/", + "#/components/schemas/scim_resource_type": "/reference/api/hub/latest/schemas/scim_resource_type/", + "#/components/schemas/scim_schema": "/reference/api/hub/latest/schemas/scim_schema/", + "#/components/schemas/scim_schema_attribute": "/reference/api/hub/latest/schemas/scim_schema_attribute/", + "#/components/schemas/scim_schema_parent_attribute": "/reference/api/hub/latest/schemas/scim_schema_parent_attribute/", + "#/components/schemas/scim_service_provider_config": "/reference/api/hub/latest/schemas/scim_service_provider_config/", + "#/components/schemas/scim_user": "/reference/api/hub/latest/schemas/scim_user/", + "#/components/schemas/scim_user_display_name": "/reference/api/hub/latest/schemas/scim_user_display_name/", + "#/components/schemas/scim_user_id": "/reference/api/hub/latest/schemas/scim_user_id/", + "#/components/schemas/scim_user_name": "/reference/api/hub/latest/schemas/scim_user_name/", + "#/components/schemas/scim_user_schemas": "/reference/api/hub/latest/schemas/scim_user_schemas/", + "#/components/schemas/scim_user_username": "/reference/api/hub/latest/schemas/scim_user_username/", + "#/components/schemas/tag": "/reference/api/hub/latest/schemas/tag/", + "#/components/schemas/updateOrgAccessTokenRequest": "/reference/api/hub/latest/schemas/updateOrgAccessTokenRequest/", + "#/components/schemas/updateOrgAccessTokenResponse": "/reference/api/hub/latest/schemas/updateOrgAccessTokenResponse/", + "#/components/schemas/update_repository_immutable_tags_request": "/reference/api/hub/latest/schemas/update_repository_immutable_tags_request/", + "#/components/schemas/user": "/reference/api/hub/latest/schemas/user/" + }, + "schemas": [ + { + "name": "AuditLog", + "pointer": "/components/schemas/AuditLog", + "schema": { + "description": "Audit log event.", + "properties": { + "account": { + "type": "string" + }, + "action": { + "type": "string" + }, + "action_description": { + "type": "string" + }, + "actor": { + "type": "string" + }, + "data": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "name": { + "type": "string" + }, + "timestamp": { + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/AuditLog/" + }, + { + "name": "AuditLogAction", + "pointer": "/components/schemas/AuditLogAction", + "schema": { + "description": "Audit Log action", + "properties": { + "description": { + "description": "Description of audit log action.", + "type": "string" + }, + "label": { + "description": "Label for audit log action.", + "type": "string" + }, + "name": { + "description": "Name of audit log action.", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/AuditLogAction/" + }, + { + "name": "AuditLogActions", + "pointer": "/components/schemas/AuditLogActions", + "schema": { + "properties": { + "actions": { + "description": "List of audit log actions.", + "items": { + "$ref": "#/components/schemas/AuditLogAction" + }, + "type": "array" + }, + "label": { + "description": "Grouping label for a particular set of audit log actions.", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/AuditLogActions/" + }, + { + "name": "AuthCreateTokenResponse", + "pointer": "/components/schemas/AuthCreateTokenResponse", + "schema": { + "description": "successful access token response", + "examples": [ + { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + ], + "properties": { + "access_token": { + "description": "The created access token. This expires in 10 minutes.", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/AuthCreateTokenResponse/" + }, + { + "name": "GetAuditActionsResponse", + "pointer": "/components/schemas/GetAuditActionsResponse", + "schema": { + "description": "GetAuditActions response.", + "properties": { + "actions": { + "additionalProperties": { + "$ref": "#/components/schemas/AuditLogActions" + }, + "description": "Map of audit log actions.", + "type": "object" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/GetAuditActionsResponse/" + }, + { + "name": "GetAuditLogsResponse", + "pointer": "/components/schemas/GetAuditLogsResponse", + "schema": { + "description": "GetAuditLogs response.", + "properties": { + "logs": { + "description": "List of audit log events.", + "items": { + "$ref": "#/components/schemas/AuditLog" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/GetAuditLogsResponse/" + }, + { + "name": "PostUsers2FALoginErrorResponse", + "pointer": "/components/schemas/PostUsers2FALoginErrorResponse", + "schema": { + "description": "failed second factor login response.", + "examples": [ + { + "detail": "Incorrect authentication credentials" + } + ], + "properties": { + "detail": { + "description": "Description of the error.", + "example": "Incorrect authentication credentials", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/PostUsers2FALoginErrorResponse/" + }, + { + "name": "PostUsersLoginErrorResponse", + "pointer": "/components/schemas/PostUsersLoginErrorResponse", + "schema": { + "description": "failed user login response or second factor required", + "examples": [ + { + "detail": "Incorrect authentication credentials" + } + ], + "properties": { + "detail": { + "description": "Description of the error.", + "example": "Incorrect authentication credentials", + "type": "string" + }, + "login_2fa_token": { + "description": "Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled.\n", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "detail" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/PostUsersLoginErrorResponse/" + }, + { + "name": "PostUsersLoginSuccessResponse", + "pointer": "/components/schemas/PostUsersLoginSuccessResponse", + "schema": { + "description": "successful user login response", + "examples": [ + { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + ], + "properties": { + "token": { + "description": "Created authentication token.\nThis token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.\n", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "name": "RepositoryGroup", + "pointer": "/components/schemas/RepositoryGroup", + "schema": { + "properties": { + "group_id": { + "description": "The ID of the group", + "example": 12345, + "format": "int64", + "type": "integer" + }, + "group_name": { + "description": "The name of the group", + "example": "developers", + "type": "string" + }, + "permission": { + "description": "The permission level granted to the group", + "enum": [ + "read", + "write", + "admin" + ], + "example": "write", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/RepositoryGroup/" + }, + { + "name": "RepositoryGroupCreationRequest", + "pointer": "/components/schemas/RepositoryGroupCreationRequest", + "schema": { + "properties": { + "group_id": { + "description": "The ID of the organization group to grant access to", + "example": 12345, + "format": "int64", + "type": "integer" + }, + "permission": { + "description": "The permission level to grant to the group:\n- read: Can view and pull from the repository\n- write: Can view, pull, and push to the repository\n- admin: Can view, pull, push, and manage repository settings\n", + "enum": [ + "read", + "write", + "admin" + ], + "example": "write", + "type": "string" + } + }, + "required": [ + "group_id", + "permission" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/RepositoryGroupCreationRequest/" + }, + { + "name": "Users2FALoginRequest", + "pointer": "/components/schemas/Users2FALoginRequest", + "schema": { + "description": "Second factor user login details", + "examples": [ + { + "code": "123456", + "login_2fa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + ], + "properties": { + "code": { + "description": "The Time-based One-Time Password of the Docker Hub account to authenticate with.\n", + "example": "123456", + "type": "string" + }, + "login_2fa_token": { + "description": "The intermediate 2FA token returned from `/v2/auth/token` API.", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": "string" + } + }, + "required": [ + "login_2fa_token", + "code" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/Users2FALoginRequest/" + }, + { + "name": "UsersLoginRequest", + "pointer": "/components/schemas/UsersLoginRequest", + "schema": { + "description": "User login details", + "examples": [ + { + "password": "p@ssw0rd", + "username": "myusername" + } + ], + "properties": { + "password": { + "description": "The password or personal access token (PAT) of the Docker Hub account to authenticate with.\n", + "example": "p@ssw0rd", + "type": "string" + }, + "username": { + "description": "The username of the Docker Hub account to authenticate with.", + "example": "myusername", + "type": "string" + } + }, + "required": [ + "username", + "password" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/UsersLoginRequest/" + }, + { + "name": "accessToken", + "pointer": "/components/schemas/accessToken", + "schema": { + "properties": { + "client_id": { + "example": "HUB", + "type": "string" + }, + "created_at": { + "example": "2021-07-20T12:00:00.000000Z", + "type": "string" + }, + "creator_ip": { + "example": "127.0.0.1", + "type": "string" + }, + "creator_ua": { + "example": "some user agent", + "type": "string" + }, + "expires_at": { + "example": "2021-10-28T18:30:19.520861Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "generated_by": { + "example": "manual", + "type": "string" + }, + "is_active": { + "example": true, + "type": "boolean" + }, + "last_used": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "scopes": { + "example": [ + "repo:read" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "token": { + "description": "Token value returned on creation. Later responses redact the value as ***.", + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "type": "string" + }, + "token_label": { + "example": "My read only token", + "type": "string" + }, + "uuid": { + "example": "b30bbf97-506c-4ecd-aabc-842f3cb484fb", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/accessToken/" + }, + { + "name": "bulk_invite", + "pointer": "/components/schemas/bulk_invite", + "schema": { + "example": { + "invitees": [ + { + "invite": { + "created_at": "2021-10-28T18:30:19.520861Z", + "id": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "invitee": "invitee@docker.com", + "inviter_username": "moby", + "org": "docker", + "team": "owners" + }, + "invitee": "invitee@docker.com", + "status": "invited" + }, + { + "invitee": "invitee2@docker.com", + "status": "existing_org_member" + }, + { + "invitee": "invitee3@docker.com", + "status": "invalid_email_or_docker_id" + } + ] + }, + "properties": { + "invitees": { + "description": "A list of invitees", + "items": { + "properties": { + "invite": { + "$ref": "#/components/schemas/invite", + "description": "Invite data if successfully invited" + }, + "invitee": { + "description": "invitee email or Docker ID", + "type": "string" + }, + "status": { + "description": "status of the invite or validation error", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/bulk_invite/" + }, + { + "name": "category", + "pointer": "/components/schemas/category", + "schema": { + "description": "Repository category for classification and discovery", + "properties": { + "name": { + "description": "Human-readable name of the category", + "example": "Databases", + "minLength": 1, + "type": "string" + }, + "slug": { + "description": "URL-friendly identifier for the category", + "example": "databases", + "minLength": 1, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", + "type": "string" + } + }, + "required": [ + "name", + "slug" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/category/" + }, + { + "name": "createAccessTokenRequest", + "pointer": "/components/schemas/createAccessTokenRequest", + "schema": { + "examples": [ + { + "scopes": [ + "repo:read" + ], + "token_label": "My read only token" + } + ], + "properties": { + "expires_at": { + "description": "Optional expiration date for the token.\nIf omitted, the token will remain valid indefinitely.\n", + "example": "2021-10-28T18:30:19.520861Z", + "format": "date-time", + "type": "string" + }, + "scopes": { + "description": "Valid scopes: \"repo:admin\", \"repo:write\", \"repo:read\", \"repo:public_read\", \"sandbox:use\". Include one repository scope, \"sandbox:use\", or both.\n", + "example": [ + "repo:read" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "token_label": { + "description": "Friendly name for you to identify the token.", + "example": "My read only token", + "maxLength": 100, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "token_label", + "scopes" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/createAccessTokenRequest/" + }, + { + "name": "createAccessTokensResponse", + "pointer": "/components/schemas/createAccessTokensResponse", + "schema": { + "$ref": "#/components/schemas/accessToken", + "examples": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/createAccessTokensResponse/" + }, + { + "name": "createOrgAccessTokenRequest", + "pointer": "/components/schemas/createOrgAccessTokenRequest", + "schema": { + "examples": [ + { + "description": "Token for CI/CD pipeline", + "label": "My organization token", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + ], + "properties": { + "description": { + "description": "Description of the access token", + "example": "Token for CI/CD pipeline", + "type": "string" + }, + "expires_at": { + "description": "Expiration date for the token", + "example": "2023-05-20T00:54:18Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "label": { + "description": "Label for the access token", + "example": "My organization token", + "type": "string" + }, + "resources": { + "description": "Resources this token has access to", + "items": { + "$ref": "#/components/schemas/orgAccessTokenResource" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "label", + "resources" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/createOrgAccessTokenRequest/" + }, + { + "name": "createOrgAccessTokenResponse", + "pointer": "/components/schemas/createOrgAccessTokenResponse", + "schema": { + "allOf": [ + { + "properties": { + "created_at": { + "example": "2022-05-20T00:54:18Z", + "format": "date-time", + "type": "string" + }, + "expires_at": { + "example": "2023-05-20T00:54:18Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "id": { + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "type": "string" + }, + "is_active": { + "example": true, + "type": "boolean" + }, + "label": { + "example": "My organization token", + "type": "string" + }, + "last_used_at": { + "example": "2022-06-15T12:30:45Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + } + }, + "type": "object" + }, + { + "properties": { + "resources": { + "items": { + "$ref": "#/components/schemas/orgAccessTokenResource" + }, + "type": "array" + }, + "token": { + "description": "The actual token value that can be used for authentication", + "example": "dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo", + "type": "string" + } + }, + "type": "object" + } + ], + "examples": [ + { + "created_at": "2022-05-20T00:54:18Z", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ], + "token": "dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo" + } + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/createOrgAccessTokenResponse/" + }, + { + "name": "email_address", + "pointer": "/components/schemas/email_address", + "schema": { + "properties": { + "email": { + "example": "dockeruser@docker.com", + "type": "string" + }, + "id": { + "type": "number" + }, + "primary": { + "type": "boolean" + }, + "user_id": { + "type": "number" + }, + "verified": { + "type": "boolean" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/email_address/" + }, + { + "name": "email_with_username", + "pointer": "/components/schemas/email_with_username", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/email_address" + }, + { + "properties": { + "username": { + "example": "dockeruser", + "type": "string" + } + }, + "type": "object" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/email_with_username/" + }, + { + "name": "error", + "pointer": "/components/schemas/error", + "schema": { + "description": "Error details vary by endpoint. The message describes the failure; errinfo can contain additional context.", + "properties": { + "detail": { + "type": "string" + }, + "errinfo": { + "additionalProperties": true, + "description": "Additional error context, when available.", + "type": [ + "object", + "null" + ] + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/error/" + }, + { + "name": "getAccessTokensResponse", + "pointer": "/components/schemas/getAccessTokensResponse", + "schema": { + "examples": [ + { + "active_count": 1, + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + } + ], + "properties": { + "active_count": { + "example": 1, + "type": "number" + }, + "count": { + "example": 1, + "type": "number" + }, + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/accessToken" + }, + { + "properties": { + "token": { + "example": "***", + "type": "string" + } + }, + "type": "object" + } + ] + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/getAccessTokensResponse/" + }, + { + "name": "getOrgAccessTokenResponse", + "pointer": "/components/schemas/getOrgAccessTokenResponse", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/orgAccessToken" + }, + { + "properties": { + "resources": { + "description": "Resources this token has access to", + "items": { + "$ref": "#/components/schemas/orgAccessTokenResource" + }, + "type": "array" + } + }, + "type": "object" + } + ], + "examples": [ + { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + ] + }, + "url": "/reference/api/hub/latest/schemas/getOrgAccessTokenResponse/" + }, + { + "name": "getOrgAccessTokensResponse", + "pointer": "/components/schemas/getOrgAccessTokensResponse", + "schema": { + "examples": [ + { + "next": null, + "previous": null, + "results": [ + { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z" + } + ], + "total": 1 + } + ], + "properties": { + "next": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "$ref": "#/components/schemas/orgAccessToken" + }, + "type": "array" + }, + "total": { + "example": 10, + "type": "number" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/getOrgAccessTokensResponse/" + }, + { + "name": "group_member", + "pointer": "/components/schemas/group_member", + "schema": { + "properties": { + "company": { + "example": "Docker Inc", + "type": "string" + }, + "date_joined": { + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": "string" + }, + "email": { + "example": "dockeruser@docker.com", + "type": "string" + }, + "full_name": { + "example": "John Snow", + "type": "string" + }, + "gravatar_email": { + "type": "string" + }, + "gravatar_url": { + "type": "string" + }, + "id": { + "description": "The UUID trimmed", + "example": "0ab70deb065a43fcacd55d48caa945d8", + "type": "string" + }, + "location": { + "type": "string" + }, + "profile_url": { + "type": "string" + }, + "type": { + "enum": [ + "User", + "Org" + ], + "example": "User", + "type": "string" + }, + "username": { + "example": "dockeruser", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/group_member/" + }, + { + "name": "image", + "pointer": "/components/schemas/image", + "schema": { + "properties": { + "architecture": { + "description": "CPU architecture", + "type": "string" + }, + "digest": { + "description": "image digest", + "type": [ + "string", + "null" + ] + }, + "features": { + "description": "CPU features", + "type": [ + "string", + "null" + ] + }, + "last_pulled": { + "description": "datetime of last pull", + "example": "2021-01-05T21:06:53.506400Z", + "type": [ + "string", + "null" + ] + }, + "last_pushed": { + "description": "datetime of last push", + "example": "2021-01-05T21:06:53.506400Z", + "type": [ + "string", + "null" + ] + }, + "layers": { + "items": { + "$ref": "#/components/schemas/layer" + }, + "type": "array" + }, + "os": { + "description": "operating system", + "type": "string" + }, + "os_features": { + "description": "OS features", + "type": [ + "string", + "null" + ] + }, + "os_version": { + "description": "OS version", + "type": [ + "string", + "null" + ] + }, + "size": { + "description": "size of the image", + "type": "integer" + }, + "status": { + "description": "Status of the image", + "enum": [ + "active", + "inactive" + ], + "type": "string" + }, + "variant": { + "description": "CPU variant", + "type": [ + "string", + "null" + ] + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/image/" + }, + { + "name": "immutable_tags_settings", + "pointer": "/components/schemas/immutable_tags_settings", + "schema": { + "properties": { + "enabled": { + "description": "Whether immutable tags are enabled", + "type": "boolean" + }, + "rules": { + "description": "List of immutable tag rules", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "enabled", + "rules" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/immutable_tags_settings/" + }, + { + "name": "immutable_tags_verify_request", + "pointer": "/components/schemas/immutable_tags_verify_request", + "schema": { + "examples": [ + { + "regex": "v.*" + } + ], + "properties": { + "regex": { + "description": "Regular expression using Go regular expression syntax. Commas are not permitted.", + "example": "v.*", + "pattern": "^[^,]*$", + "type": "string" + } + }, + "required": [ + "regex" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/immutable_tags_verify_request/" + }, + { + "name": "immutable_tags_verify_response", + "pointer": "/components/schemas/immutable_tags_verify_response", + "schema": { + "examples": [ + { + "tags": [ + "v1.0.0", + "v2.1.3", + "latest" + ] + } + ], + "properties": { + "tags": { + "description": "List of tags that match the provided regex pattern", + "example": [ + "v1.0.0", + "v2.1.3", + "latest" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "tags" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/immutable_tags_verify_response/" + }, + { + "name": "invite", + "pointer": "/components/schemas/invite", + "schema": { + "properties": { + "created_at": { + "example": "2021-10-28T18:30:19.520861Z", + "type": "string" + }, + "id": { + "description": "uuid representing the invite id", + "example": "e36eca69-4cc8-4f17-9845-ae8c2b832691", + "type": "string" + }, + "invitee": { + "description": "can either be a dockerID for registered users or an email for non-registered users", + "example": "invitee@docker.com", + "type": "string" + }, + "inviter_username": { + "example": "moby", + "type": "string" + }, + "org": { + "description": "name of the org to join", + "example": "docker", + "type": "string" + }, + "team": { + "description": "name of the team (user group) to join", + "example": "owners", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/invite/" + }, + { + "name": "layer", + "pointer": "/components/schemas/layer", + "schema": { + "properties": { + "digest": { + "description": "image layer digest", + "type": [ + "string", + "null" + ] + }, + "instruction": { + "description": "Dockerfile instruction", + "type": "string" + }, + "size": { + "description": "size of the layer", + "type": "integer" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/layer/" + }, + { + "name": "legacy_email_address", + "pointer": "/components/schemas/legacy_email_address", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/email_address" + }, + { + "properties": { + "user": { + "example": "dockeruser", + "type": "string" + } + }, + "type": "object" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/legacy_email_address/" + }, + { + "name": "list_repositories_response", + "pointer": "/components/schemas/list_repositories_response", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/page" + }, + { + "properties": { + "results": { + "items": { + "$ref": "#/components/schemas/repository_list_entry" + }, + "type": "array" + } + }, + "type": "object" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/list_repositories_response/" + }, + { + "name": "orgAccessToken", + "pointer": "/components/schemas/orgAccessToken", + "schema": { + "properties": { + "created_at": { + "example": "2022-05-20T00:54:18Z", + "format": "date-time", + "type": "string" + }, + "created_by": { + "example": "johndoe", + "type": "string" + }, + "expires_at": { + "example": "2023-05-20T00:54:18Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "id": { + "example": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "type": "string" + }, + "is_active": { + "example": true, + "type": "boolean" + }, + "label": { + "example": "My organization token", + "type": "string" + }, + "last_used_at": { + "example": "2022-06-15T12:30:45Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/orgAccessToken/" + }, + { + "name": "orgAccessTokenResource", + "pointer": "/components/schemas/orgAccessTokenResource", + "schema": { + "properties": { + "path": { + "description": "The path of the resource. The format of this will change depending on the type of resource.\n\nFor TYPE_REPO resources:\n- Must be an existing repository name (e.g., \"myorg/myrepo\")\n- Can use glob patterns (e.g., \"myorg/*\" for all repositories in the organization)\n- Use \"*/*/public\" to reference all public repositories\n", + "example": "myorg/myrepo", + "type": "string" + }, + "scopes": { + "description": "The scopes this token has access to", + "items": { + "example": "scope-image-pull", + "type": "string" + }, + "type": "array" + }, + "type": { + "description": "The type of resource", + "enum": [ + "TYPE_REPO", + "TYPE_ORG" + ], + "example": "TYPE_REPO", + "type": "string" + } + }, + "required": [ + "type", + "path", + "scopes" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/orgAccessTokenResource/" + }, + { + "name": "orgSettings", + "pointer": "/components/schemas/orgSettings", + "schema": { + "examples": [ + { + "restricted_images": { + "allow_official_images": true, + "allow_verified_publishers": true, + "enabled": true + } + } + ], + "properties": { + "restricted_images": { + "$ref": "#/components/schemas/restricted_images" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/orgSettings/" + }, + { + "name": "org_group", + "pointer": "/components/schemas/org_group", + "schema": { + "examples": [ + { + "description": "Development team", + "id": 10, + "member_count": 1, + "name": "developers", + "role": "member", + "uuid": "e36eca69-4cc8-4f17-9845-ae8c2b832691" + } + ], + "properties": { + "description": { + "description": "Description of the group", + "example": "Groups description", + "type": "string" + }, + "id": { + "description": "Group ID", + "example": 10, + "type": "number" + }, + "member_count": { + "description": "Member count of the group", + "example": 10, + "type": "number" + }, + "name": { + "description": "Name of the group", + "example": "mygroup", + "type": "string" + }, + "role": { + "description": "Role assigned to the team. A core role (`owner`, `editor`, or `member`)\nor the name of a custom role (not the label or UUID).\n", + "type": [ + "string", + "null" + ] + }, + "uuid": { + "description": "UUID for the group", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/org_group/" + }, + { + "name": "org_member", + "pointer": "/components/schemas/org_member", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/user" + } + ], + "examples": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "groups": [ + "owners" + ], + "id": "0ab70deb065a43fcacd55d48caa945d8", + "is_guest": false, + "role": "Owner", + "type": "User", + "username": "dockeruser" + } + ], + "properties": { + "email": { + "description": "User's email address", + "example": "example@docker.com", + "type": "string" + }, + "groups": { + "description": "Groups (Teams) that the user is member of", + "example": [ + "developers", + "owners" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "is_guest": { + "description": "If the organization has verified domains, members that have email addresses outside of those domains will be flagged as guests.", + "example": false, + "type": "boolean" + }, + "last_desktop_version": { + "description": "Last desktop version the user used. To access this field, you must have insights visible for your organization. See\n[Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users).\n", + "example": "4.29.0", + "type": "string" + }, + "last_logged_in_at": { + "description": "Last time the user logged in. To access this field, you must have insights visible for your organization. See\n[Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users).\n", + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "last_seen_at": { + "description": "Last time the user was seen. To access this field, you must have insights visible for your organization. See\n[Insights](https://docs.docker.com/accounts/organization/insights/#view-insights-for-organization-users).\n", + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "primary_email": { + "deprecated": true, + "description": "The user's email primary address.", + "example": "example@docker.com", + "type": "string" + }, + "role": { + "description": "The member's role in the organization (`Owner`, `Editor`,\n`Member`, or `Invitee` for pending invites).\n", + "enum": [ + "Owner", + "Editor", + "Member", + "Invitee" + ], + "example": "Owner", + "type": "string" + } + } + }, + "url": "/reference/api/hub/latest/schemas/org_member/" + }, + { + "name": "org_member_paginated", + "pointer": "/components/schemas/org_member_paginated", + "schema": { + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "date_joined": "2021-01-05T21:06:53.506400Z", + "email": "example@docker.com", + "full_name": "Jon Snow", + "groups": [ + "owners" + ], + "id": "0ab70deb065a43fcacd55d48caa945d8", + "is_guest": false, + "role": "Owner", + "type": "User", + "username": "dockeruser" + } + ] + } + ], + "properties": { + "count": { + "description": "The total number of items that match with the search.", + "example": 120, + "type": "number" + }, + "next": { + "description": "The URL or link for the next page of items.", + "example": null, + "type": [ + "string", + "null" + ] + }, + "previous": { + "description": "The URL or link for the previous page of items.", + "example": null, + "type": [ + "string", + "null" + ] + }, + "results": { + "description": "List of accounts.", + "items": { + "$ref": "#/components/schemas/org_member" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/org_member_paginated/" + }, + { + "name": "page", + "pointer": "/components/schemas/page", + "schema": { + "properties": { + "count": { + "description": "total number of results available across all pages", + "type": "integer" + }, + "next": { + "description": "link to next page of results if any", + "type": [ + "string", + "null" + ] + }, + "previous": { + "description": "link to previous page of results if any", + "type": [ + "string", + "null" + ] + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/page/" + }, + { + "name": "paginated_tags", + "pointer": "/components/schemas/paginated_tags", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/page" + }, + { + "properties": { + "results": { + "items": { + "$ref": "#/components/schemas/tag" + }, + "type": "array" + } + }, + "type": "object" + } + ], + "examples": [ + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "creator": 1234, + "full_size": 123456, + "id": 12345, + "images": [ + { + "architecture": "amd64", + "features": null, + "last_pulled": null, + "last_pushed": "2021-01-05T21:06:53.506400Z", + "os": "linux", + "os_features": null, + "os_version": null, + "size": 123456, + "status": "active", + "variant": null + } + ], + "last_updated": "2021-01-05T21:06:53.506400Z", + "last_updater": 1234, + "last_updater_username": "dockeruser", + "name": "latest", + "repository": 5678, + "tag_last_pulled": null, + "tag_last_pushed": "2021-01-05T21:06:53.506400Z", + "tag_status": "active", + "v2": true + } + ] + } + ] + }, + "url": "/reference/api/hub/latest/schemas/paginated_tags/" + }, + { + "name": "patchAccessTokenRequest", + "pointer": "/components/schemas/patchAccessTokenRequest", + "schema": { + "examples": [ + { + "is_active": false, + "token_label": "My read only token" + } + ], + "properties": { + "is_active": { + "example": false, + "type": "boolean" + }, + "token_label": { + "example": "My read only token", + "maxLength": 100, + "minLength": 1, + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/patchAccessTokenRequest/" + }, + { + "name": "patchAccessTokenResponse", + "pointer": "/components/schemas/patchAccessTokenResponse", + "schema": { + "$ref": "#/components/schemas/accessToken", + "examples": [ + { + "client_id": "HUB", + "created_at": "2021-07-20T12:00:00.000000Z", + "creator_ip": "127.0.0.1", + "creator_ua": "some user agent", + "expires_at": "2021-10-28T18:30:19.520861Z", + "generated_by": "manual", + "is_active": true, + "last_used": null, + "scopes": [ + "repo:read" + ], + "token": "***", + "token_label": "My read only token", + "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/patchAccessTokenResponse/" + }, + { + "name": "repo_creation_request", + "pointer": "/components/schemas/repo_creation_request", + "schema": { + "properties": { + "description": { + "description": "Short description of the repository", + "example": "A sample application repository", + "maxLength": 100, + "type": "string" + }, + "full_description": { + "description": "Detailed description of the repository", + "example": "This is a comprehensive description of my application repository that contains additional details about the project, its purpose, usage instructions, and other relevant information.", + "maxLength": 25000, + "type": "string" + }, + "is_private": { + "default": false, + "description": "Whether the repository should be private", + "example": false, + "type": "boolean" + }, + "name": { + "description": "The name of the repository. Must be 2-255 characters long and may only include \nalphanumeric characters, periods (.), underscores (_), or hyphens (-). \nLetters must be lowercase.\n", + "example": "my-app", + "maxLength": 255, + "minLength": 2, + "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$", + "type": "string" + }, + "namespace": { + "description": "The namespace where the repository will be created", + "example": "myorganization", + "type": "string" + }, + "registry": { + "description": "The registry where the repository will be hosted", + "example": "docker.io", + "type": "string" + } + }, + "required": [ + "name", + "namespace" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/repo_creation_request/" + }, + { + "name": "repo_permissions", + "pointer": "/components/schemas/repo_permissions", + "schema": { + "properties": { + "admin": { + "description": "Admin permission", + "type": "boolean" + }, + "read": { + "description": "Read permission", + "type": "boolean" + }, + "write": { + "description": "Write permission", + "type": "boolean" + } + }, + "required": [ + "read", + "write", + "admin" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/repo_permissions/" + }, + { + "name": "repository_info", + "pointer": "/components/schemas/repository_info", + "schema": { + "examples": [ + { + "categories": [], + "collaborator_count": 0, + "content_types": [], + "date_registered": "2025-01-20T10:30:00Z", + "description": "A sample application repository", + "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.", + "has_starred": false, + "hub_user": "myorganization", + "immutable_tags_settings": { + "enabled": false, + "rules": [] + }, + "is_automated": false, + "is_private": false, + "last_updated": "2025-01-20T10:30:00Z", + "media_types": [], + "name": "my-app", + "namespace": "myorganization", + "permissions": { + "admin": true, + "read": true, + "write": true + }, + "pull_count": 0, + "repository_type": "image", + "source": null, + "star_count": 0, + "status": 1, + "status_description": "Active", + "storage_size": null, + "user": "myorganization" + } + ], + "properties": { + "affiliation": { + "description": "Repository affiliation", + "type": [ + "string", + "null" + ] + }, + "categories": { + "description": "Repository categories", + "items": { + "$ref": "#/components/schemas/category" + }, + "type": "array" + }, + "collaborator_count": { + "description": "Number of collaborators", + "format": "int64", + "type": "integer" + }, + "content_types": { + "description": "Supported content types", + "items": { + "type": "string" + }, + "type": "array" + }, + "date_registered": { + "description": "ISO 8601 timestamp of when repository was created", + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Short description of the repository", + "type": "string" + }, + "full_description": { + "description": "Full description of the repository", + "type": [ + "string", + "null" + ] + }, + "has_starred": { + "description": "Whether the current user has starred this repository", + "type": "boolean" + }, + "hub_user": { + "description": "Hub user information", + "type": [ + "string", + "null" + ] + }, + "immutable_tags_settings": { + "$ref": "#/components/schemas/immutable_tags_settings" + }, + "is_automated": { + "description": "Whether the repository has automated builds", + "type": "boolean" + }, + "is_private": { + "description": "Whether the repository is private", + "type": "boolean" + }, + "last_modified": { + "description": "ISO 8601 timestamp of when repository was last modified", + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "last_updated": { + "description": "ISO 8601 timestamp of when repository was last updated", + "example": "2021-01-05T21:06:53.506400Z", + "format": "date-time", + "type": "string" + }, + "media_types": { + "description": "Supported media types", + "items": { + "type": [ + "string", + "null" + ] + }, + "type": "array" + }, + "name": { + "description": "Repository name", + "type": "string" + }, + "namespace": { + "description": "Repository namespace", + "type": "string" + }, + "permissions": { + "$ref": "#/components/schemas/repo_permissions" + }, + "pull_count": { + "description": "Number of pulls", + "format": "int64", + "type": "integer" + }, + "repository_type": { + "description": "Type of the repository", + "type": [ + "string", + "null" + ] + }, + "source": { + "description": "Source of the repository, where it was created from", + "type": [ + "string", + "null" + ] + }, + "star_count": { + "description": "Number of stars", + "format": "int64", + "type": "integer" + }, + "status": { + "description": "Repository status code", + "type": "integer" + }, + "status_description": { + "description": "Description of the repository status", + "type": "string" + }, + "storage_size": { + "description": "Storage size in bytes", + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "user": { + "description": "Username of the repository owner", + "type": "string" + } + }, + "required": [ + "user", + "name", + "namespace", + "status", + "status_description", + "description", + "is_private", + "is_automated", + "star_count", + "pull_count", + "last_updated", + "date_registered", + "collaborator_count", + "has_starred", + "permissions", + "media_types", + "content_types", + "categories", + "immutable_tags_settings" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/repository_info/" + }, + { + "name": "repository_list_entry", + "pointer": "/components/schemas/repository_list_entry", + "schema": { + "properties": { + "affiliation": { + "description": "User's affiliation with the repository (empty string if no affiliation)", + "example": "", + "type": "string" + }, + "categories": { + "description": "Categories associated with this repository", + "example": [], + "items": { + "$ref": "#/components/schemas/category" + }, + "type": "array" + }, + "content_types": { + "description": "Content types supported by this repository", + "example": [ + "plugin" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "date_registered": { + "description": "ISO 8601 timestamp of when the repository was created", + "example": "2013-06-19T19:07:54Z", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Repository description", + "example": "Hello World! (an example of minimal Dockerization)", + "type": [ + "string", + "null" + ] + }, + "is_private": { + "description": "Whether the repository is private", + "example": false, + "type": "boolean" + }, + "last_modified": { + "description": "ISO 8601 timestamp of when the repository was last modified", + "example": "2023-12-01T10:30:00Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "last_updated": { + "description": "ISO 8601 timestamp of when the repository was last updated", + "example": "2023-12-01T10:30:00Z", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "media_types": { + "description": "Media types supported by this repository", + "example": [ + "application/vnd.docker.plugin.v1+json" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "name": { + "description": "Name of the repository", + "example": "hello-world", + "type": "string" + }, + "namespace": { + "description": "Namespace (organization or username) that owns the repository", + "example": "docker", + "type": "string" + }, + "pull_count": { + "description": "Total number of pulls for this repository", + "example": 50000000, + "minimum": 0, + "type": "integer" + }, + "repository_type": { + "description": "Type of repository", + "enum": [ + "image", + "plugin", + null + ], + "example": "image", + "type": [ + "string", + "null" + ] + }, + "star_count": { + "description": "Number of users who starred this repository", + "example": 1234, + "minimum": 0, + "type": "integer" + }, + "status": { + "description": "Repository status code", + "example": 1, + "type": "integer" + }, + "status_description": { + "description": "Human-readable repository status", + "enum": [ + "active", + "inactive" + ], + "example": "active", + "type": "string" + }, + "storage_size": { + "description": "Storage size in bytes used by this repository", + "example": 232719127, + "minimum": 0, + "type": "integer" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/repository_list_entry/" + }, + { + "name": "restricted_images", + "pointer": "/components/schemas/restricted_images", + "schema": { + "properties": { + "allow_official_images": { + "description": "Allow usage of official images if \"enabled\" is `true`.", + "example": true, + "type": "boolean" + }, + "allow_verified_publishers": { + "description": "Allow usage of verified publisher images if \"enabled\" is `true`.", + "example": true, + "type": "boolean" + }, + "enabled": { + "description": "Whether or not to restrict image usage for users in the organization.", + "example": true, + "type": "boolean" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/restricted_images/" + }, + { + "name": "scim_email", + "pointer": "/components/schemas/scim_email", + "schema": { + "properties": { + "display": { + "example": "jon.snow@docker.com", + "type": "string" + }, + "primary": { + "example": true, + "type": "boolean" + }, + "value": { + "example": "jon.snow@docker.com", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_email/" + }, + { + "name": "scim_error", + "pointer": "/components/schemas/scim_error", + "schema": { + "properties": { + "detail": { + "description": "Details about why the request failed.", + "type": "string" + }, + "schemas": { + "items": { + "default": "urn:ietf:params:scim:api:messages:2.0:Error", + "type": "string" + }, + "type": "array" + }, + "status": { + "description": "The status code for the response in string format.", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_error/" + }, + { + "name": "scim_group", + "pointer": "/components/schemas/scim_group", + "schema": { + "properties": { + "display": { + "example": "nightswatch", + "type": "string" + }, + "value": { + "example": "nightswatch", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_group/" + }, + { + "name": "scim_resource_type", + "pointer": "/components/schemas/scim_resource_type", + "schema": { + "examples": [ + { + "description": "User", + "endpoint": "/Users", + "id": "User", + "name": "User", + "schema": "urn:ietf:params:scim:schemas:core:2.0:User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + ] + } + ], + "properties": { + "description": { + "example": "User", + "type": "string" + }, + "endpoint": { + "example": "/Users", + "type": "string" + }, + "id": { + "example": "User", + "type": "string" + }, + "name": { + "example": "User", + "type": "string" + }, + "schema": { + "example": "urn:ietf:params:scim:schemas:core:2.0:User", + "type": "string" + }, + "schemas": { + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_resource_type/" + }, + { + "name": "scim_schema", + "pointer": "/components/schemas/scim_schema", + "schema": { + "examples": [ + { + "attributes": [], + "description": "User Account", + "id": "urn:ietf:params:scim:schemas:core:2.0:User", + "name": "User", + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Schema" + ] + } + ], + "properties": { + "attributes": { + "example": [], + "items": { + "$ref": "#/components/schemas/scim_schema_parent_attribute" + }, + "type": "array" + }, + "description": { + "example": "User Account", + "type": "string" + }, + "id": { + "example": "urn:ietf:params:scim:schemas:core:2.0:User", + "type": "string" + }, + "name": { + "example": "User", + "type": "string" + }, + "schemas": { + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Schema" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_schema/" + }, + { + "name": "scim_schema_attribute", + "pointer": "/components/schemas/scim_schema_attribute", + "schema": { + "properties": { + "caseExact": { + "example": false, + "type": "boolean" + }, + "description": { + "example": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users.", + "type": "string" + }, + "multiValued": { + "example": false, + "type": "boolean" + }, + "mutability": { + "example": "readWrite", + "type": "string" + }, + "name": { + "example": "userName", + "type": "string" + }, + "required": { + "example": true, + "type": "boolean" + }, + "returned": { + "example": "default", + "type": "string" + }, + "type": { + "enum": [ + "string", + "boolean", + "complex" + ], + "example": "string", + "type": "string" + }, + "uniqueness": { + "example": "server", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_schema_attribute/" + }, + { + "name": "scim_schema_parent_attribute", + "pointer": "/components/schemas/scim_schema_parent_attribute", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/scim_schema_attribute" + }, + { + "properties": { + "subAttributes": { + "items": { + "$ref": "#/components/schemas/scim_schema_attribute" + }, + "type": "array" + } + }, + "type": "object" + } + ] + }, + "url": "/reference/api/hub/latest/schemas/scim_schema_parent_attribute/" + }, + { + "name": "scim_service_provider_config", + "pointer": "/components/schemas/scim_service_provider_config", + "schema": { + "examples": [ + { + "authenticationSchemes": [ + { + "name": "OAuth 2.0 Bearer Token", + "specUri": "http://tools.ietf.org/html/rfc6750", + "type": "oauthbearertoken" + } + ], + "bulk": { + "maxOperations": 0, + "maxPayloadSize": 0, + "supported": false + }, + "changePassword": { + "supported": false + }, + "etag": { + "supported": false + }, + "filter": { + "maxResults": 200, + "supported": true + }, + "patch": { + "supported": true + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" + ], + "sort": { + "supported": true + } + } + ], + "properties": { + "authenticationSchemes": { + "items": { + "properties": { + "description": { + "example": "The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as \"a string representing an access authorization issued to the client\", rather than using the resource owner's credentials directly.", + "type": "string" + }, + "name": { + "example": "OAuth 2.0 Bearer Token", + "type": "string" + }, + "specUri": { + "example": "http://tools.ietf.org/html/rfc6750", + "type": "string" + }, + "type": { + "example": "oauthbearertoken", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "bulk": { + "properties": { + "maxOperations": { + "type": "integer" + }, + "maxPayloadSize": { + "type": "integer" + }, + "supported": { + "example": false, + "type": "boolean" + } + }, + "type": "object" + }, + "changePassword": { + "properties": { + "supported": { + "example": false, + "type": "boolean" + } + }, + "type": "object" + }, + "documentationUri": { + "example": "", + "type": "string" + }, + "etag": { + "properties": { + "supported": { + "example": false, + "type": "boolean" + } + }, + "type": "object" + }, + "filter": { + "properties": { + "maxResults": { + "example": 200, + "type": "integer" + }, + "supported": { + "example": true, + "type": "boolean" + } + }, + "type": "object" + }, + "patch": { + "properties": { + "supported": { + "example": true, + "type": "boolean" + } + }, + "type": "object" + }, + "schemas": { + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "sort": { + "properties": { + "supported": { + "example": true, + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_service_provider_config/" + }, + { + "name": "scim_user", + "pointer": "/components/schemas/scim_user", + "schema": { + "examples": [ + { + "active": true, + "displayName": "jonsnow", + "emails": [ + { + "display": "jon.snow@docker.com", + "primary": true, + "value": "jon.snow@docker.com" + } + ], + "groups": [ + { + "display": "nightswatch", + "value": "nightswatch" + } + ], + "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "meta": { + "created": "2022-05-20T00:54:18Z", + "lastModified": "2022-05-20T00:54:18Z", + "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "resourceType": "User" + }, + "name": { + "familyName": "Snow", + "givenName": "Jon" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "userName": "jon.snow@docker.com" + } + ], + "properties": { + "active": { + "example": true, + "type": "boolean" + }, + "displayName": { + "$ref": "#/components/schemas/scim_user_display_name" + }, + "emails": { + "items": { + "$ref": "#/components/schemas/scim_email" + }, + "type": "array" + }, + "groups": { + "items": { + "$ref": "#/components/schemas/scim_group" + }, + "type": "array" + }, + "id": { + "$ref": "#/components/schemas/scim_user_id" + }, + "meta": { + "properties": { + "created": { + "description": "The creation date for the user as a RFC3339 formatted string.", + "example": "2022-05-20T00:54:18Z", + "format": "date-time", + "type": "string" + }, + "lastModified": { + "description": "The date the user was last modified as a RFC3339 formatted string.", + "example": "2022-05-20T00:54:18Z", + "format": "date-time", + "type": "string" + }, + "location": { + "example": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "type": "string" + }, + "resourceType": { + "example": "User", + "type": "string" + } + }, + "type": "object" + }, + "name": { + "$ref": "#/components/schemas/scim_user_name" + }, + "schemas": { + "$ref": "#/components/schemas/scim_user_schemas" + }, + "userName": { + "$ref": "#/components/schemas/scim_user_username" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_user/" + }, + { + "name": "scim_user_display_name", + "pointer": "/components/schemas/scim_user_display_name", + "schema": { + "description": "The username in Docker. Also known as the \"Docker ID\".", + "example": "jonsnow", + "type": "string" + }, + "url": "/reference/api/hub/latest/schemas/scim_user_display_name/" + }, + { + "name": "scim_user_id", + "pointer": "/components/schemas/scim_user_id", + "schema": { + "description": "The unique identifier for the user. A v4 UUID.", + "example": "d80f7c79-7730-49d8-9a41-7c42fb622d9c", + "type": "string" + }, + "url": "/reference/api/hub/latest/schemas/scim_user_id/" + }, + { + "name": "scim_user_name", + "pointer": "/components/schemas/scim_user_name", + "schema": { + "properties": { + "familyName": { + "example": "Snow", + "type": "string" + }, + "givenName": { + "example": "Jon", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/scim_user_name/" + }, + { + "name": "scim_user_schemas", + "pointer": "/components/schemas/scim_user_schemas", + "schema": { + "items": { + "example": "urn:ietf:params:scim:schemas:core:2.0:User", + "minItems": 1, + "type": "string" + }, + "type": "array" + }, + "url": "/reference/api/hub/latest/schemas/scim_user_schemas/" + }, + { + "name": "scim_user_username", + "pointer": "/components/schemas/scim_user_username", + "schema": { + "description": "The user's email address. This must be reachable via email.", + "example": "jon.snow@docker.com", + "type": "string" + }, + "url": "/reference/api/hub/latest/schemas/scim_user_username/" + }, + { + "name": "tag", + "pointer": "/components/schemas/tag", + "schema": { + "examples": [ + { + "creator": 1234, + "full_size": 123456, + "id": 12345, + "images": [ + { + "architecture": "amd64", + "features": null, + "last_pulled": null, + "last_pushed": "2021-01-05T21:06:53.506400Z", + "os": "linux", + "os_features": null, + "os_version": null, + "size": 123456, + "status": "active", + "variant": null + } + ], + "last_updated": "2021-01-05T21:06:53.506400Z", + "last_updater": 1234, + "last_updater_username": "dockeruser", + "name": "latest", + "repository": 5678, + "tag_last_pulled": null, + "tag_last_pushed": "2021-01-05T21:06:53.506400Z", + "tag_status": "active", + "v2": true + } + ], + "properties": { + "creator": { + "description": "ID of the user that pushed the tag", + "type": "integer" + }, + "full_size": { + "description": "compressed size (sum of all layers) of the tagged image", + "type": "integer" + }, + "id": { + "description": "tag ID", + "type": "integer" + }, + "images": { + "items": { + "$ref": "#/components/schemas/image" + }, + "type": [ + "array", + "null" + ] + }, + "last_updated": { + "description": "datetime of last update", + "example": "2021-01-05T21:06:53.506400Z", + "type": [ + "string", + "null" + ] + }, + "last_updater": { + "description": "ID of the last user that updated the tag", + "type": "integer" + }, + "last_updater_username": { + "description": "Hub username of the user that updated the tag", + "type": "string" + }, + "name": { + "description": "name of the tag", + "type": "string" + }, + "repository": { + "description": "repository ID", + "type": "integer" + }, + "tag_last_pulled": { + "description": "datetime of last pull", + "example": "2021-01-05T21:06:53.506400Z", + "type": [ + "string", + "null" + ] + }, + "tag_last_pushed": { + "description": "datetime of last push", + "example": "2021-01-05T21:06:53.506400Z", + "type": [ + "string", + "null" + ] + }, + "tag_status": { + "description": "whether a tag has been pushed to or pulled in the past month", + "enum": [ + "active", + "inactive" + ], + "type": "string" + }, + "v2": { + "description": "Whether the tag uses the Registry V2 format.", + "type": "boolean" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/tag/" + }, + { + "name": "updateOrgAccessTokenRequest", + "pointer": "/components/schemas/updateOrgAccessTokenRequest", + "schema": { + "examples": [ + { + "description": "Token for CI/CD pipeline", + "is_active": true, + "label": "My organization token", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + ], + "properties": { + "description": { + "description": "Description of the access token", + "example": "Token for CI/CD pipeline", + "type": "string" + }, + "is_active": { + "description": "Whether the token is active", + "example": true, + "type": "boolean" + }, + "label": { + "description": "Label for the access token", + "example": "My organization token", + "type": "string" + }, + "resources": { + "description": "Resources this token has access to", + "items": { + "$ref": "#/components/schemas/orgAccessTokenResource" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/updateOrgAccessTokenRequest/" + }, + { + "name": "updateOrgAccessTokenResponse", + "pointer": "/components/schemas/updateOrgAccessTokenResponse", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/orgAccessToken" + }, + { + "properties": { + "resources": { + "description": "Resources this token has access to", + "items": { + "$ref": "#/components/schemas/orgAccessTokenResource" + }, + "type": "array" + } + }, + "type": "object" + } + ], + "examples": [ + { + "created_at": "2022-05-20T00:54:18Z", + "created_by": "johndoe", + "expires_at": "2023-05-20T00:54:18Z", + "id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861", + "is_active": true, + "label": "My organization token", + "last_used_at": "2022-06-15T12:30:45Z", + "resources": [ + { + "path": "myorg/myrepo", + "scopes": [ + "scope-image-pull" + ], + "type": "TYPE_REPO" + } + ] + } + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/updateOrgAccessTokenResponse/" + }, + { + "name": "update_repository_immutable_tags_request", + "pointer": "/components/schemas/update_repository_immutable_tags_request", + "schema": { + "examples": [ + { + "immutable_tags": true, + "immutable_tags_rules": [ + "v.*", + ".*-RELEASE" + ] + } + ], + "properties": { + "immutable_tags": { + "description": "Whether immutable tags are enabled", + "type": "boolean" + }, + "immutable_tags_rules": { + "description": "List of immutable tag rules", + "example": [ + "v.*", + ".*-RELEASE" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "immutable_tags", + "immutable_tags_rules" + ], + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/update_repository_immutable_tags_request/" + }, + { + "name": "user", + "pointer": "/components/schemas/user", + "schema": { + "properties": { + "company": { + "example": "Docker Inc", + "type": "string" + }, + "date_joined": { + "example": "2021-01-05T21:06:53.506400Z", + "type": "string" + }, + "full_name": { + "example": "Jon Snow", + "type": "string" + }, + "gravatar_email": { + "type": "string" + }, + "gravatar_url": { + "type": "string" + }, + "id": { + "description": "The UUID trimmed", + "example": "0ab70deb065a43fcacd55d48caa945d8", + "type": "string" + }, + "location": { + "type": "string" + }, + "profile_url": { + "type": "string" + }, + "type": { + "enum": [ + "User", + "Org" + ], + "example": "User", + "type": "string" + }, + "username": { + "example": "dockeruser", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/hub/latest/schemas/user/" + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "scheme": "bearer", + "type": "http" + }, + "bearerSCIMAuth": { + "scheme": "bearer", + "type": "http" + }, + "scimToken": { + "description": "Use the SCIM provisioning token configured for the organization.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker HUB API", + "url": "https://hub.docker.com", + "x-audience": "public" + } + ], + "source": "content/reference/api/hub/latest.yaml", + "sourceURL": "/reference/api/hub/latest.yaml", + "tags": [ + { + "description": "See the [Changelog](https://docs.docker.com/reference/api/hub/changelog) for a summary of changes across Docker Hub API versions.\n", + "kind": "info", + "name": "changelog", + "summary": "Changelog" + }, + { + "description": "The following resources are available to interact with the documented API:\n- [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental)\n", + "kind": "info", + "name": "resources", + "summary": "Resources" + }, + { + "description": "The Docker Hub API is limited on the amount of requests you can perform per minute against it.\n\nIf you haven't hit the limit, each request to the API will return the following headers in the response.\n\n- `X-RateLimit-Limit` - The limit of requests per minute.\n- `X-RateLimit-Remaining` - The remaining amount of calls within the limit period.\n- `X-RateLimit-Reset` - The unix timestamp of when the remaining resets.\n\nIf you have hit the limit, you will receive a response status of `429` and the `Retry-After` header in the response.\n\nThe [`Retry-After` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) specifies the number of seconds to wait until you can call the API again.\n\n**Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting.\nTo learn more about Docker Hub pull rate limiting, see [Usage and limits](https://docs.docker.com/docker-hub/usage/).\n", + "kind": "info", + "name": "rate-limiting", + "summary": "Rate Limiting" + }, + { + "description": "Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them.\n\nAdditionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your subscription (Personal, Pro, or Team) and your account's permissions.\n\nTo learn more about the features available in each subscription and to upgrade your existing subscription, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs\u0026refAction=DocsApiHub).\n\n# Types\n\nThe Docker Hub API supports the following authentication types.\n\nYou must use each authentication type with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) route to obtain a bearer token.\n\n## Password\nUsing a username and password is the most powerful, yet least secure way \nto authenticate with Docker as a user. It allows access to resources \nfor the user without scopes. \n\n_In general, it is recommended to use a personal access token (PAT) instead._\n\n_**The password authentication type is not available if your organization has SSO enforced.**_\n\n## Personal Access Token (PAT)\nUsing a username and PAT is the most secure way to authenticate with \nDocker as a user. PATs are scoped to specific resources and scopes.\n\nCurrently, a PAT is a more secure password due to limited functionality. \nIn the future, we may add fine-grained access like organization \naccess tokens for enhanced usage and security.\n\n## Organization Access Token (OAT)\nOrganization access tokens are scoped to specific resources and scopes \nin an organization. They are managed by organization owners. \n\nThese tokens are meant for automation and are not meant to be used by \nusers.\n\nOperations that support bearer tokens issued from OATs state this in their descriptions.\n\n", + "kind": "info", + "name": "authentication", + "summary": "Authentication" + }, + { + "description": "The authentication endpoints allow you to authenticate with Docker Hub APIs.\n\nFor more information, see [Authentication](#tag/authentication).\n", + "kind": "nav", + "name": "authentication-api", + "summary": "Authentication" + }, + { + "description": "The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/access-tokens/personal-access-tokens/).\n\nYou can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/reference/cli/docker/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token.\n\n### Scopes\n\nFor each scope grouping (in this case \"repo\"), you only need to define 1 scope as any lower scopes are assumed.\nFor example: If you define `repo:write`, the API assumes the scope of both `repo:read` *and* `repo:public_read` as well.\nIf you were to define both `repo:write` *and* `repo:read`, then `repo:read` is assumed by `repo:write` and ignored.\n\n`sandbox:use` is a separate grouping for Cloud Sandboxes. A repository scope does not include it, and it does not include a repository scope. A request can include `sandbox:use` on its own or with one repository scope.\n\n***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.***\n", + "kind": "nav", + "name": "access-tokens", + "summary": "Personal Access Tokens" + }, + { + "description": "The Audit Logs API endpoints allow you to query audit log events across a namespace.\n\nFor more information, see [Audit Logs](https://docs.docker.com/admin/activity-logs/).\n", + "kind": "nav", + "name": "audit-logs", + "summary": "Audit Logs" + }, + { + "description": "The Org Settings API endpoints allow you to manage your organization's settings.\n", + "kind": "nav", + "name": "org-settings", + "summary": "Org Settings" + }, + { + "description": "The repository endpoints allow you to access your repository's tags.\n", + "kind": "nav", + "name": "repositories", + "summary": "Repositories" + }, + { + "description": "The organization endpoints allow you to interact with and manage your organizations.\n\nFor more information, see [Organization administration overview](https://docs.docker.com/admin/organization/).\n", + "kind": "nav", + "name": "orgs", + "summary": "Organizations", + "x-audience": "public" + }, + { + "description": "The groups endpoints allow you to manage your organization's teams and their members.\n\nFor more information, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/).\n", + "kind": "nav", + "name": "groups", + "summary": "Groups (Teams)", + "x-audience": "public" + }, + { + "description": "The invites endpoints allow you to manage invites for users to join your Docker organization.\n\nFor more information, see [Invite members](https://docs.docker.com/accounts/organization/manage/members/#invite-members).\n", + "kind": "nav", + "name": "invites", + "summary": "Invites", + "x-audience": "public" + }, + { + "description": "SCIM is a provisioning system that lets you manage users within your identity provider (IdP).\n\nFor more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/).\n", + "kind": "nav", + "name": "scim", + "summary": "SCIM", + "x-audience": "public" + }, + { + "description": "The organization access token endpoints allow you to manage organization access tokens (OATs). See [Organization access tokens](https://docs.docker.com/security/for-admins/access-tokens/) for more information.\n\nOATs only authenticate requests to the modern namespace-scoped routes under `/v2/namespaces/{namespace}/repositories/`. Legacy repository paths are OAT unsupported, regardless of the token's scopes, and reject every OAT with `403 token issued from organization access token is not allowed`:\n\n- `GET /v2/repositories/{namespace}/{repository}` — use [Get repository](#tag/repositories/operation/GetRepository) instead.\n- `GET /v2/repositories/{namespace}` — use [List repositories](#tag/repositories/operation/listNamespaceRepositories) instead.\n- `GET /v2/users/{username}/repositories` — use [List repositories](#tag/repositories/operation/listNamespaceRepositories) instead.\n", + "kind": "nav", + "name": "org-access-tokens", + "summary": "Organization Access Tokens", + "x-audience": "public" + } + ], + "title": "Docker Hub", + "url": "/reference/api/hub/latest/", + "version": "2-beta" + }, + { + "connection": "hosted", + "description": "The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces. Analytics data can be retrieved in a CSV as raw data, or in a summary format.\n \n#### Summary data\n\nIn your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). \n\nThere are two levels of summary data:\n\n- Repository-level, a summary of every namespace and repository\n- Tag- or digest-level, a summary of every namespace, repository, and reference\n (tag or digest)\n\nThe summary data formats contain the following data points:\n\n- Unique IP address count\n- Pulls by tag count\n- Pulls by digest count\n- Version check count\n\n#### Raw data\n\nIn your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). **Note:** each action is represented as a single row.\n\n- Type (industry)\n- Host (cloud provider)\n- Country (geolocation)\n- Timestamp\n- Namespace\n- Repository\n- Reference (digest is always included, tag is provided when available)\n- HTTP request method\n- Action, one of the following:\n - Pull by tag\n - Pull by digest\n - Version check\n- User-Agent\n", + "diagnostics": [], + "digest": "46e011a53a41887ab2771250758f9f35c0e59c378b09d1c799f3f2348689eb00", + "exampleCount": 30, + "experimental": false, + "guides": [], + "id": "dvp", + "manual": "/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md", + "operations": [ + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/'", + "curlNotes": [], + "deprecated": null, + "description": "Gets a list of your namespaces and repos which have data available.", + "id": "getNamespaces", + "line": 171, + "method": "GET", + "parameters": [], + "path": "/", + "pointer": "/paths/~1/get", + "raw": { + "description": "Gets a list of your namespaces and repos which have data available.", + "operationId": "getNamespaces", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NamespaceData" + } + } + }, + "description": "Success" + } + }, + "summary": "Get namespaces and repos", + "tags": [ + "discovery" + ] + }, + "references": [ + { + "ref": "#/components/schemas/NamespaceData", + "url": "/reference/api/dvp/latest/schemas/NamespaceData/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get namespaces and repos", + "tags": [ + "discovery" + ], + "url": "/reference/api/dvp/latest/operations/getNamespaces/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"namespaces\": [\n \"myorganization\"\n ]\n}", + "value": { + "namespaces": [ + "myorganization" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/NamespaceData" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces'", + "curlNotes": [], + "deprecated": null, + "description": "Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces.", + "id": "getUserNamespaces", + "line": 185, + "method": "GET", + "parameters": [], + "path": "/namespaces", + "pointer": "/paths/~1namespaces/get", + "raw": { + "description": "Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces.", + "operationId": "getUserNamespaces", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "publishers": { + "summary": "Namespace metadata", + "value": [ + { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "raw", + "summary", + "repo-summary", + "namespace-summary", + "geo-repo-summary" + ] + } + ], + "extensionPublisher": false, + "extraRepos": null, + "namespace": "org1", + "publisherType": "DVP" + } + ] + } + }, + "schema": { + "items": { + "$ref": "#/components/schemas/NamespaceMetadata" + }, + "type": "array" + } + } + }, + "description": "Success" + }, + "401": { + "description": "Authentication failed or second factor required" + } + }, + "summary": "Get user's namespaces", + "tags": [ + "discovery" + ] + }, + "references": [ + { + "ref": "#/components/schemas/NamespaceMetadata", + "url": "/reference/api/dvp/latest/schemas/NamespaceMetadata/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get user's namespaces", + "tags": [ + "discovery" + ], + "url": "/reference/api/dvp/latest/operations/getUserNamespaces/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "publishers", + "text": "[\n {\n \"datasets\": [\n {\n \"name\": \"pulls\",\n \"timespans\": [\n \"months\",\n \"weeks\"\n ],\n \"views\": [\n \"raw\",\n \"summary\",\n \"repo-summary\",\n \"namespace-summary\",\n \"geo-repo-summary\"\n ]\n }\n ],\n \"extensionPublisher\": false,\n \"extraRepos\": null,\n \"namespace\": \"org1\",\n \"publisherType\": \"DVP\"\n }\n]", + "value": [ + { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "raw", + "summary", + "repo-summary", + "namespace-summary", + "geo-repo-summary" + ] + } + ], + "extensionPublisher": false, + "extraRepos": null, + "namespace": "org1", + "publisherType": "DVP" + } + ] + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces/get/responses/200/content/application~1json", + "required": null, + "schema": { + "items": { + "$ref": "#/components/schemas/NamespaceMetadata" + }, + "type": "array" + }, + "status": "200" + }, + { + "description": "Authentication failed or second factor required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1namespaces/get/responses/401", + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Gets metadata associated with specified namespace, including extra repos associated with the namespace.", + "id": "getNamespace", + "line": 222, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/namespaces/{namespace}", + "pointer": "/paths/~1namespaces~1{namespace}/get", + "raw": { + "description": "Gets metadata associated with specified namespace, including extra repos associated with the namespace.", + "operationId": "getNamespace", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NamespaceMetadata" + } + } + }, + "description": "Success" + } + }, + "summary": "Get namespace", + "tags": [ + "discovery" + ] + }, + "references": [ + { + "ref": "#/components/schemas/NamespaceMetadata", + "url": "/reference/api/dvp/latest/schemas/NamespaceMetadata/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get namespace", + "tags": [ + "discovery" + ], + "url": "/reference/api/dvp/latest/operations/getNamespace/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"datasets\": [\n {\n \"name\": \"pulls\",\n \"timespans\": [\n \"months\",\n \"weeks\"\n ],\n \"views\": [\n \"raw\",\n \"summary\",\n \"repo-summary\",\n \"namespace-summary\",\n \"geo-repo-summary\"\n ]\n }\n ],\n \"extensionPublisher\": false,\n \"extraRepos\": null,\n \"namespace\": \"org1\",\n \"publisherType\": \"DVP\"\n}", + "value": { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "raw", + "summary", + "repo-summary", + "namespace-summary", + "geo-repo-summary" + ] + } + ], + "extensionPublisher": false, + "extraRepos": null, + "namespace": "org1", + "publisherType": "DVP" + } + }, + { + "language": "json", + "name": "Schema example", + "text": "{\n \"datasets\": [\n {\n \"name\": \"pulls\",\n \"timespans\": [\n \"months\",\n \"weeks\"\n ],\n \"views\": [\n \"repo-summary\",\n \"namespace-summary\"\n ]\n },\n {\n \"name\": \"extensions\",\n \"timespans\": [\n \"months\",\n \"weeks\"\n ],\n \"views\": [\n \"ext-summary\"\n ]\n }\n ],\n \"extensionPublisher\": true,\n \"extraRepos\": null,\n \"namespace\": \"org4\",\n \"publisherType\": \"DVP\"\n}", + "value": { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "repo-summary", + "namespace-summary" + ] + }, + { + "name": "extensions", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "ext-summary" + ] + } + ], + "extensionPublisher": true, + "extraRepos": null, + "namespace": "org4", + "publisherType": "DVP" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/NamespaceMetadata" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/pulls'", + "curlNotes": [], + "deprecated": null, + "description": "Gets pulls for the given namespace.", + "id": "getNamespacePulls", + "line": 243, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/parameters/1", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/parameters/2", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/parameters/3", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "path": "/namespaces/{namespace}/pulls", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get", + "raw": { + "description": "Gets pulls for the given namespace.", + "operationId": "getNamespacePulls", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PullData" + } + } + }, + "description": "Success" + }, + "404": { + "description": "Not found - namespace doesn't exist or user does not have permission to access it" + } + }, + "summary": "Get pull data", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/GroupType", + "url": "/reference/api/dvp/latest/schemas/GroupType/" + }, + { + "ref": "#/components/schemas/PeriodType", + "url": "/reference/api/dvp/latest/schemas/PeriodType/" + }, + { + "ref": "#/components/schemas/PullData", + "url": "/reference/api/dvp/latest/schemas/PullData/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get pull data", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getNamespacePulls/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"pulls\": [\n {\n \"end\": \"2022-08-07T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-01T00:00:00Z\"\n },\n {\n \"end\": \"2022-08-14T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-08T00:00:00Z\"\n }\n ]\n}", + "value": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-08T00:00:00Z" + } + ] + } + }, + { + "language": "json", + "name": "Schema example", + "text": "{\n \"pulls\": null\n}", + "value": { + "pulls": null + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PullData" + }, + "status": "200" + }, + { + "description": "Not found - namespace doesn't exist or user does not have permission to access it", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls/get/responses/404", + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/pulls/exports/years'", + "curlNotes": [], + "deprecated": null, + "description": "Gets a list of years that have data for the given namespace.", + "id": "getNamespaceYears", + "line": 331, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/namespaces/{namespace}/pulls/exports/years", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years/get", + "raw": { + "description": "Gets a list of years that have data for the given namespace.", + "operationId": "getNamespaceYears", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/YearData" + } + } + }, + "description": "Success" + } + }, + "summary": "Get years with data", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/YearData", + "url": "/reference/api/dvp/latest/schemas/YearData/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get years with data", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getNamespaceYears/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"years\": [\n {\n \"year\": 2025\n }\n ]\n}", + "value": { + "years": [ + { + "year": 2025 + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/YearData" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/pulls/exports/years/\u003cYEAR\u003e/\u003cTIMESPANTYPE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Gets a list of timespans of the given type that have data for the given namespace and year.", + "id": "getNamespaceTimespans", + "line": 352, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}/get/parameters/1", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}/get/parameters/2", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + } + ], + "path": "/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}/get", + "raw": { + "description": "Gets a list of timespans of the given type that have data for the given namespace and year.", + "operationId": "getNamespaceTimespans", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimespanData" + } + } + }, + "description": "Success" + } + }, + "summary": "Get timespans with data", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/TimespanData", + "url": "/reference/api/dvp/latest/schemas/TimespanData/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get timespans with data", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getNamespaceTimespans/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"months\": [\n {\n \"month\": 5\n },\n {\n \"month\": 7\n }\n ]\n}", + "value": { + "months": [ + { + "month": 5 + }, + { + "month": 7 + } + ] + } + }, + { + "language": "json", + "name": "Schema example", + "text": "{\n \"weeks\": [\n {\n \"week\": 31\n },\n {\n \"week\": 32\n }\n ]\n}", + "value": { + "weeks": [ + { + "week": 31 + }, + { + "week": 32 + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/TimespanData" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/pulls/exports/years/\u003cYEAR\u003e/\u003cTIMESPANTYPE\u003e/\u003cTIMESPAN\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Gets info about data for the given namespace and timespan.", + "id": "getNamespaceTimespanMetadata", + "line": 385, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/parameters/1", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/parameters/2", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Timespan to fetch data for", + "in": "path", + "name": "timespan", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/parameters/3", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "path": "/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get", + "raw": { + "description": "Gets info about data for the given namespace and timespan.", + "operationId": "getNamespaceTimespanMetadata", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Timespan to fetch data for", + "in": "path", + "name": "timespan", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimespanModel" + } + } + }, + "description": "Success" + }, + "404": { + "description": "Not Found" + } + }, + "summary": "Get namespace metadata for timespan", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/TimespanModel", + "url": "/reference/api/dvp/latest/schemas/TimespanModel/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get namespace metadata for timespan", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getNamespaceTimespanMetadata/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"month\": 7\n}", + "value": { + "month": 7 + } + }, + { + "language": "json", + "name": "Schema example", + "text": "{\n \"week\": 31\n}", + "value": { + "week": 31 + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/TimespanModel" + }, + "status": "200" + }, + { + "description": "Not Found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}/get/responses/404", + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/pulls/exports/years/\u003cYEAR\u003e/\u003cTIMESPANTYPE\u003e/\u003cTIMESPAN\u003e/\u003cDATAVIEW\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Gets a list of URLs that can be used to download the pull data for the given namespace and timespan.", + "id": "getNamespaceDataByTimespan", + "line": 426, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/parameters/1", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/parameters/2", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Timespan to fetch data for", + "in": "path", + "name": "timespan", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/parameters/3", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of data to fetch", + "in": "path", + "name": "dataview", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/parameters/4", + "required": true, + "schema": { + "$ref": "#/components/schemas/DataviewType" + } + } + ], + "path": "/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}/{dataview}", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get", + "raw": { + "description": "Gets a list of URLs that can be used to download the pull data for the given namespace and timespan.", + "operationId": "getNamespaceDataByTimespan", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Year to fetch data for", + "in": "path", + "name": "year", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of timespan to fetch data for", + "in": "path", + "name": "timespantype", + "required": true, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Timespan to fetch data for", + "in": "path", + "name": "timespan", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "description": "Type of data to fetch", + "in": "path", + "name": "dataview", + "required": true, + "schema": { + "$ref": "#/components/schemas/DataviewType" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "download": { + "description": "Use the signed URL returned by the API. The URL and file size in this example are illustrative.", + "summary": "Illustrative download location", + "value": { + "data": [ + { + "size": 1024, + "url": "https://example.invalid/exports/pulls.csv.gz?X-Amz-Expires=21600\u0026X-Amz-Signature=EXAMPLE" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/ResponseData" + } + } + }, + "description": "Success" + } + }, + "summary": "Get namespace data for timespan", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/DataviewType", + "url": "/reference/api/dvp/latest/schemas/DataviewType/" + }, + { + "ref": "#/components/schemas/ResponseData", + "url": "/reference/api/dvp/latest/schemas/ResponseData/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get namespace data for timespan", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getNamespaceDataByTimespan/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "download", + "text": "{\n \"data\": [\n {\n \"size\": 1024,\n \"url\": \"https://example.invalid/exports/pulls.csv.gz?X-Amz-Expires=21600\\u0026X-Amz-Signature=EXAMPLE\"\n }\n ]\n}", + "value": { + "data": [ + { + "size": 1024, + "url": "https://example.invalid/exports/pulls.csv.gz?X-Amz-Expires=21600\u0026X-Amz-Signature=EXAMPLE" + } + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1pulls~1exports~1years~1{year}~1{timespantype}~1{timespan}~1{dataview}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ResponseData" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/namespaces/\u003cNAMESPACE\u003e/repos/\u003cREPO\u003e/pulls'", + "curlNotes": [], + "deprecated": null, + "description": "Gets pulls for the given repo.", + "id": "getRepoPulls", + "line": 284, + "method": "GET", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Repository to fetch data for", + "in": "path", + "name": "repo", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/parameters/2", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/parameters/3", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/parameters/4", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "path": "/namespaces/{namespace}/repos/{repo}/pulls", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get", + "raw": { + "description": "Gets pulls for the given repo.", + "operationId": "getRepoPulls", + "parameters": [ + { + "description": "Namespace to fetch data for", + "in": "path", + "name": "namespace", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Repository to fetch data for", + "in": "path", + "name": "repo", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PullData" + } + } + }, + "description": "Success" + }, + "404": { + "description": "Not found - repo doesn't exist or user does not have permission to access it" + } + }, + "summary": "Get pull data", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/GroupType", + "url": "/reference/api/dvp/latest/schemas/GroupType/" + }, + { + "ref": "#/components/schemas/PeriodType", + "url": "/reference/api/dvp/latest/schemas/PeriodType/" + }, + { + "ref": "#/components/schemas/PullData", + "url": "/reference/api/dvp/latest/schemas/PullData/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get pull data", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getRepoPulls/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"pulls\": [\n {\n \"end\": \"2022-08-07T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-01T00:00:00Z\"\n },\n {\n \"end\": \"2022-08-14T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-08T00:00:00Z\"\n }\n ]\n}", + "value": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-08T00:00:00Z" + } + ] + } + }, + { + "language": "json", + "name": "Schema example", + "text": "{\n \"pulls\": null\n}", + "value": { + "pulls": null + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PullData" + }, + "status": "200" + }, + { + "description": "Not found - repo doesn't exist or user does not have permission to access it", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1namespaces~1{namespace}~1repos~1{repo}~1pulls/get/responses/404", + "status": "404" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/api/publisher/analytics/v1/repos/pulls?repos=%3CREPOS%3E'", + "curlNotes": [], + "deprecated": null, + "description": "Gets pull for the given repos.", + "id": "getManyReposPulls", + "line": 479, + "method": "GET", + "parameters": [ + { + "description": "Repositories to fetch data for (maximum of 50 repositories per request).", + "in": "query", + "name": "repos", + "pointer": "/paths/~1repos~1pulls/get/parameters/0", + "required": true, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "pointer": "/paths/~1repos~1pulls/get/parameters/1", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "pointer": "/paths/~1repos~1pulls/get/parameters/2", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "pointer": "/paths/~1repos~1pulls/get/parameters/3", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "path": "/repos/pulls", + "pointer": "/paths/~1repos~1pulls/get", + "raw": { + "description": "Gets pull for the given repos.", + "operationId": "getManyReposPulls", + "parameters": [ + { + "description": "Repositories to fetch data for (maximum of 50 repositories per request).", + "in": "query", + "name": "repos", + "required": true, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Timespan type for fetching data", + "in": "query", + "name": "timespan", + "required": false, + "schema": { + "$ref": "#/components/schemas/TimespanType" + } + }, + { + "description": "Relative period of the period to fetch data", + "in": "query", + "name": "period", + "required": false, + "schema": { + "$ref": "#/components/schemas/PeriodType" + } + }, + { + "description": "Field to group the data by", + "in": "query", + "name": "group", + "required": false, + "schema": { + "$ref": "#/components/schemas/GroupType" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReposPullData" + } + } + }, + "description": "Success" + } + }, + "summary": "Get pull data for multiple repos", + "tags": [ + "namespaces" + ] + }, + "references": [ + { + "ref": "#/components/schemas/GroupType", + "url": "/reference/api/dvp/latest/schemas/GroupType/" + }, + { + "ref": "#/components/schemas/PeriodType", + "url": "/reference/api/dvp/latest/schemas/PeriodType/" + }, + { + "ref": "#/components/schemas/ReposPullData", + "url": "/reference/api/dvp/latest/schemas/ReposPullData/" + }, + { + "ref": "#/components/schemas/TimespanType", + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + } + ], + "requestSchema": null, + "security": [ + { + "HubAuth": [] + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "summary": "Get pull data for multiple repos", + "tags": [ + "namespaces" + ], + "url": "/reference/api/dvp/latest/operations/getManyReposPulls/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"repos\": {\n \"org2/neo4j\": {\n \"pulls\": [\n {\n \"end\": \"2022-08-07T00:00:00Z\",\n \"ipCount\": 41490,\n \"pullCount\": 272407,\n \"repo\": \"neo4j\",\n \"start\": \"2022-08-01T00:00:00Z\"\n },\n {\n \"end\": \"2022-08-14T00:00:00Z\",\n \"ipCount\": 41490,\n \"pullCount\": 272407,\n \"repo\": \"neo4j\",\n \"start\": \"2022-08-08T00:00:00Z\"\n }\n ]\n },\n \"org2/neo4j-admin\": {\n \"pulls\": [\n {\n \"end\": \"2022-08-07T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-01T00:00:00Z\"\n },\n {\n \"end\": \"2022-08-14T00:00:00Z\",\n \"ipCount\": 10,\n \"pullCount\": 11,\n \"repo\": \"neo4j-admin\",\n \"start\": \"2022-08-08T00:00:00Z\"\n }\n ]\n }\n }\n}", + "value": { + "repos": { + "org2/neo4j": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 41490, + "pullCount": 272407, + "repo": "neo4j", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 41490, + "pullCount": 272407, + "repo": "neo4j", + "start": "2022-08-08T00:00:00Z" + } + ] + }, + "org2/neo4j-admin": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-08T00:00:00Z" + } + ] + } + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1repos~1pulls/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ReposPullData" + }, + "status": "200" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"code\": \"123456\",\n \"login_2fa_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}' \\\n 'https://hub.docker.com/v2/users/2fa-login'", + "curlNotes": [], + "deprecated": null, + "description": "When a user has 2FA enabled, this is the second call to perform after\n`/v2/users/login` call.\n\nCreates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "id": "PostUsers2FALogin", + "line": 135, + "method": "POST", + "parameters": [], + "path": "/v2/users/2fa-login", + "pointer": "/paths/~1v2~1users~12fa-login/post", + "raw": { + "description": "When a user has 2FA enabled, this is the second call to perform after\n`/v2/users/login` call.\n\nCreates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "operationId": "PostUsers2FALogin", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + } + } + }, + "description": "Login details.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + } + } + }, + "description": "Authentication successful" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsers2FALoginErrorResponse" + } + } + }, + "description": "Authentication failed or second factor required" + } + }, + "security": [], + "summary": "Second factor authentication", + "tags": [ + "authentication" + ] + }, + "references": [ + { + "ref": "#/components/schemas/PostUsers2FALoginErrorResponse", + "url": "/reference/api/dvp/latest/schemas/PostUsers2FALoginErrorResponse/" + }, + { + "ref": "#/components/schemas/PostUsersLoginSuccessResponse", + "url": "/reference/api/dvp/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "ref": "#/components/schemas/Users2FALoginRequest", + "url": "/reference/api/dvp/latest/schemas/Users2FALoginRequest/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + }, + "security": [], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com" + } + ], + "summary": "Second factor authentication", + "tags": [ + "authentication" + ], + "url": "/reference/api/dvp/latest/operations/PostUsers2FALogin/", + "variants": [ + { + "description": "Login details.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"123456\",\n \"login_2fa_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "code": "123456", + "login_2fa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/Users2FALoginRequest" + }, + "status": "" + }, + { + "description": "Authentication successful", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + }, + "status": "200" + }, + { + "description": "Authentication failed or second factor required", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"detail\": \"Incorrect authentication credentials\"\n}", + "value": { + "detail": "Incorrect authentication credentials" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~12fa-login/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsers2FALoginErrorResponse" + }, + "status": "401" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"password\": \"hunter2\",\n \"username\": \"myusername\"\n}' \\\n 'https://hub.docker.com/v2/users/login'", + "curlNotes": [], + "deprecated": null, + "description": "Creates and returns a bearer token in JWT format that you can use to\nauthenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "id": "PostUsersLogin", + "line": 99, + "method": "POST", + "parameters": [], + "path": "/v2/users/login", + "pointer": "/paths/~1v2~1users~1login/post", + "raw": { + "description": "Creates and returns a bearer token in JWT format that you can use to\nauthenticate with Docker Hub APIs.\n\nThe returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.\n\nMost Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.\n", + "operationId": "PostUsersLogin", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsersLoginRequest" + } + } + }, + "description": "Login details.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + } + } + }, + "description": "Authentication successful" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostUsersLoginErrorResponse" + } + } + }, + "description": "Authentication failed or second factor required" + } + }, + "security": [], + "summary": "Create an authentication token", + "tags": [ + "authentication" + ] + }, + "references": [ + { + "ref": "#/components/schemas/PostUsersLoginErrorResponse", + "url": "/reference/api/dvp/latest/schemas/PostUsersLoginErrorResponse/" + }, + { + "ref": "#/components/schemas/PostUsersLoginSuccessResponse", + "url": "/reference/api/dvp/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "ref": "#/components/schemas/UsersLoginRequest", + "url": "/reference/api/dvp/latest/schemas/UsersLoginRequest/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/UsersLoginRequest" + }, + "security": [], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com" + } + ], + "summary": "Create an authentication token", + "tags": [ + "authentication" + ], + "url": "/reference/api/dvp/latest/operations/PostUsersLogin/", + "variants": [ + { + "description": "Login details.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"password\": \"hunter2\",\n \"username\": \"myusername\"\n}", + "value": { + "password": "hunter2", + "username": "myusername" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/UsersLoginRequest" + }, + "status": "" + }, + { + "description": "Authentication successful", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n}", + "value": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginSuccessResponse" + }, + "status": "200" + }, + { + "description": "Authentication failed or second factor required", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"detail\": \"Incorrect authentication credentials\"\n}", + "value": { + "detail": "Incorrect authentication credentials" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v2~1users~1login/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/PostUsersLoginErrorResponse" + }, + "status": "401" + } + ] + } + ], + "owner": "docker/docs", + "product": "dvp", + "schemaCount": 69, + "schemaURLs": { + "#/components/schemas/DatasetModel": "/reference/api/dvp/latest/schemas/DatasetModel/", + "#/components/schemas/DatasetType": "/reference/api/dvp/latest/schemas/DatasetType/", + "#/components/schemas/DataviewType": "/reference/api/dvp/latest/schemas/DataviewType/", + "#/components/schemas/GroupType": "/reference/api/dvp/latest/schemas/GroupType/", + "#/components/schemas/MonthData": "/reference/api/dvp/latest/schemas/MonthData/", + "#/components/schemas/MonthModel": "/reference/api/dvp/latest/schemas/MonthModel/", + "#/components/schemas/NamespaceData": "/reference/api/dvp/latest/schemas/NamespaceData/", + "#/components/schemas/NamespaceMetadata": "/reference/api/dvp/latest/schemas/NamespaceMetadata/", + "#/components/schemas/PeriodType": "/reference/api/dvp/latest/schemas/PeriodType/", + "#/components/schemas/PostUsers2FALoginErrorResponse": "/reference/api/dvp/latest/schemas/PostUsers2FALoginErrorResponse/", + "#/components/schemas/PostUsersLoginErrorResponse": "/reference/api/dvp/latest/schemas/PostUsersLoginErrorResponse/", + "#/components/schemas/PostUsersLoginSuccessResponse": "/reference/api/dvp/latest/schemas/PostUsersLoginSuccessResponse/", + "#/components/schemas/PullData": "/reference/api/dvp/latest/schemas/PullData/", + "#/components/schemas/PullModel": "/reference/api/dvp/latest/schemas/PullModel/", + "#/components/schemas/ReposPullData": "/reference/api/dvp/latest/schemas/ReposPullData/", + "#/components/schemas/ResponseData": "/reference/api/dvp/latest/schemas/ResponseData/", + "#/components/schemas/ResponseDataFile": "/reference/api/dvp/latest/schemas/ResponseDataFile/", + "#/components/schemas/TimespanData": "/reference/api/dvp/latest/schemas/TimespanData/", + "#/components/schemas/TimespanModel": "/reference/api/dvp/latest/schemas/TimespanModel/", + "#/components/schemas/TimespanType": "/reference/api/dvp/latest/schemas/TimespanType/", + "#/components/schemas/Users2FALoginRequest": "/reference/api/dvp/latest/schemas/Users2FALoginRequest/", + "#/components/schemas/UsersLoginRequest": "/reference/api/dvp/latest/schemas/UsersLoginRequest/", + "#/components/schemas/WeekData": "/reference/api/dvp/latest/schemas/WeekData/", + "#/components/schemas/WeekModel": "/reference/api/dvp/latest/schemas/WeekModel/", + "#/components/schemas/YearData": "/reference/api/dvp/latest/schemas/YearData/", + "#/components/schemas/YearModel": "/reference/api/dvp/latest/schemas/YearModel/" + }, + "schemas": [ + { + "name": "DatasetModel", + "pointer": "/components/schemas/DatasetModel", + "schema": { + "description": "Datasets and views available to the publisher, based on its entitlements.", + "properties": { + "name": { + "$ref": "#/components/schemas/DatasetType" + }, + "timespans": { + "items": { + "$ref": "#/components/schemas/TimespanType" + }, + "type": "array" + }, + "views": { + "items": { + "$ref": "#/components/schemas/DataviewType" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/DatasetModel/" + }, + { + "name": "DatasetType", + "pointer": "/components/schemas/DatasetType", + "schema": { + "enum": [ + "pulls", + "extensions" + ], + "type": "string" + }, + "url": "/reference/api/dvp/latest/schemas/DatasetType/" + }, + { + "name": "DataviewType", + "pointer": "/components/schemas/DataviewType", + "schema": { + "enum": [ + "raw", + "summary", + "repo-summary", + "namespace-summary", + "geo-repo-summary", + "ext-summary", + "ext-premium-summary", + "ext-premium-geo" + ], + "type": "string" + }, + "url": "/reference/api/dvp/latest/schemas/DataviewType/" + }, + { + "name": "GroupType", + "pointer": "/components/schemas/GroupType", + "schema": { + "enum": [ + "repo", + "namespace" + ], + "type": "string" + }, + "url": "/reference/api/dvp/latest/schemas/GroupType/" + }, + { + "name": "MonthData", + "pointer": "/components/schemas/MonthData", + "schema": { + "examples": [ + { + "months": [ + { + "month": 5 + }, + { + "month": 7 + } + ] + } + ], + "properties": { + "months": { + "items": { + "$ref": "#/components/schemas/MonthModel" + }, + "type": "array" + } + }, + "required": [ + "months" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/MonthData/" + }, + { + "name": "MonthModel", + "pointer": "/components/schemas/MonthModel", + "schema": { + "examples": [ + { + "month": 7 + } + ], + "properties": { + "month": { + "type": "integer" + } + }, + "required": [ + "month" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/MonthModel/" + }, + { + "name": "NamespaceData", + "pointer": "/components/schemas/NamespaceData", + "schema": { + "examples": [ + { + "namespaces": [ + "myorganization" + ] + } + ], + "properties": { + "namespaces": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/NamespaceData/" + }, + { + "name": "NamespaceMetadata", + "pointer": "/components/schemas/NamespaceMetadata", + "schema": { + "examples": [ + { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "raw", + "summary", + "repo-summary", + "namespace-summary", + "geo-repo-summary" + ] + } + ], + "extensionPublisher": false, + "extraRepos": null, + "namespace": "org1", + "publisherType": "DVP" + }, + { + "datasets": [ + { + "name": "pulls", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "repo-summary", + "namespace-summary" + ] + }, + { + "name": "extensions", + "timespans": [ + "months", + "weeks" + ], + "views": [ + "ext-summary" + ] + } + ], + "extensionPublisher": true, + "extraRepos": null, + "namespace": "org4", + "publisherType": "DVP" + } + ], + "properties": { + "datasets": { + "items": { + "$ref": "#/components/schemas/DatasetModel" + }, + "type": "array" + }, + "extensionPublisher": { + "description": "Whether the namespace is an extension publisher.", + "type": "boolean" + }, + "extraRepos": { + "description": "Additional repositories associated with the namespace. Null when none are configured.", + "items": { + "type": "string" + }, + "type": [ + "array", + "null" + ] + }, + "namespace": { + "type": "string" + }, + "publisherType": { + "description": "Publisher program associated with the namespace.", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/NamespaceMetadata/" + }, + { + "name": "PeriodType", + "pointer": "/components/schemas/PeriodType", + "schema": { + "enum": [ + "last-2-months", + "last-3-months", + "last-6-months", + "last-12-months" + ], + "type": "string" + }, + "url": "/reference/api/dvp/latest/schemas/PeriodType/" + }, + { + "name": "PostUsers2FALoginErrorResponse", + "pointer": "/components/schemas/PostUsers2FALoginErrorResponse", + "schema": { + "description": "failed second factor login response.", + "examples": [ + { + "detail": "Incorrect authentication credentials" + } + ], + "properties": { + "detail": { + "description": "Description of the error.", + "example": "Incorrect authentication credentials", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/PostUsers2FALoginErrorResponse/" + }, + { + "name": "PostUsersLoginErrorResponse", + "pointer": "/components/schemas/PostUsersLoginErrorResponse", + "schema": { + "description": "failed user login response or second factor required", + "examples": [ + { + "detail": "Incorrect authentication credentials" + } + ], + "properties": { + "detail": { + "description": "Description of the error.", + "example": "Incorrect authentication credentials", + "type": "string" + }, + "login_2fa_token": { + "description": "Short-lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled.", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "detail" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/PostUsersLoginErrorResponse/" + }, + { + "name": "PostUsersLoginSuccessResponse", + "pointer": "/components/schemas/PostUsersLoginSuccessResponse", + "schema": { + "description": "successful user login response", + "examples": [ + { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + ], + "properties": { + "token": { + "description": "Created authentication token.\n\nThis token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.\n", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/PostUsersLoginSuccessResponse/" + }, + { + "name": "PullData", + "pointer": "/components/schemas/PullData", + "schema": { + "examples": [ + { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-08T00:00:00Z" + } + ] + }, + { + "pulls": null + } + ], + "properties": { + "pulls": { + "description": "Pull statistics for the selected interval. Null when no records are returned.", + "items": { + "$ref": "#/components/schemas/PullModel" + }, + "type": [ + "array", + "null" + ] + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/PullData/" + }, + { + "name": "PullModel", + "pointer": "/components/schemas/PullModel", + "schema": { + "properties": { + "country": { + "description": "Country. Present for results grouped by geography and repository.", + "type": "string" + }, + "end": { + "description": "End of the reporting interval in RFC 3339 format.", + "format": "date-time", + "type": "string" + }, + "ipCount": { + "type": "integer" + }, + "namespace": { + "description": "Namespace name. Present for results grouped by namespace.", + "type": "string" + }, + "pullCount": { + "type": "integer" + }, + "repo": { + "description": "Repository name. Present for results grouped by repository.", + "type": "string" + }, + "start": { + "description": "Start of the reporting interval in RFC 3339 format.", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/PullModel/" + }, + { + "name": "ReposPullData", + "pointer": "/components/schemas/ReposPullData", + "schema": { + "examples": [ + { + "repos": { + "org2/neo4j": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 41490, + "pullCount": 272407, + "repo": "neo4j", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 41490, + "pullCount": 272407, + "repo": "neo4j", + "start": "2022-08-08T00:00:00Z" + } + ] + }, + "org2/neo4j-admin": { + "pulls": [ + { + "end": "2022-08-07T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-01T00:00:00Z" + }, + { + "end": "2022-08-14T00:00:00Z", + "ipCount": 10, + "pullCount": 11, + "repo": "neo4j-admin", + "start": "2022-08-08T00:00:00Z" + } + ] + } + } + } + ], + "properties": { + "repos": { + "additionalProperties": { + "$ref": "#/components/schemas/PullData" + }, + "type": "object" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/ReposPullData/" + }, + { + "name": "ResponseData", + "pointer": "/components/schemas/ResponseData", + "schema": { + "description": "Download locations for the selected export. Large exports can span multiple files.", + "properties": { + "data": { + "description": "Download URLs and file sizes for the export.", + "items": { + "$ref": "#/components/schemas/ResponseDataFile" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/ResponseData/" + }, + { + "name": "ResponseDataFile", + "pointer": "/components/schemas/ResponseDataFile", + "schema": { + "properties": { + "size": { + "description": "Size of the file in bytes.", + "format": "int64", + "type": "integer" + }, + "url": { + "description": "Signed download URL. URLs expire six hours after generation.", + "format": "uri", + "type": "string" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/ResponseDataFile/" + }, + { + "name": "TimespanData", + "pointer": "/components/schemas/TimespanData", + "schema": { + "examples": [ + { + "months": [ + { + "month": 5 + }, + { + "month": 7 + } + ] + }, + { + "weeks": [ + { + "week": 31 + }, + { + "week": 32 + } + ] + } + ], + "oneOf": [ + { + "$ref": "#/components/schemas/MonthData" + }, + { + "$ref": "#/components/schemas/WeekData" + } + ] + }, + "url": "/reference/api/dvp/latest/schemas/TimespanData/" + }, + { + "name": "TimespanModel", + "pointer": "/components/schemas/TimespanModel", + "schema": { + "examples": [ + { + "month": 7 + }, + { + "week": 31 + } + ], + "oneOf": [ + { + "$ref": "#/components/schemas/MonthModel" + }, + { + "$ref": "#/components/schemas/WeekModel" + } + ] + }, + "url": "/reference/api/dvp/latest/schemas/TimespanModel/" + }, + { + "name": "TimespanType", + "pointer": "/components/schemas/TimespanType", + "schema": { + "enum": [ + "months", + "weeks" + ], + "type": "string" + }, + "url": "/reference/api/dvp/latest/schemas/TimespanType/" + }, + { + "name": "Users2FALoginRequest", + "pointer": "/components/schemas/Users2FALoginRequest", + "schema": { + "description": "Second factor user login details", + "examples": [ + { + "code": "123456", + "login_2fa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + } + ], + "properties": { + "code": { + "description": "The Time-based One-Time Password of the Docker Hub account to authenticate with.", + "example": "123456", + "type": "string" + }, + "login_2fa_token": { + "description": "The intermediate 2FA token returned from `/v2/users/login` API.", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", + "type": "string" + } + }, + "required": [ + "login_2fa_token", + "code" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/Users2FALoginRequest/" + }, + { + "name": "UsersLoginRequest", + "pointer": "/components/schemas/UsersLoginRequest", + "schema": { + "description": "User login details", + "examples": [ + { + "password": "hunter2", + "username": "myusername" + } + ], + "properties": { + "password": { + "description": "The password or personal access token (PAT) of the Docker Hub account to authenticate with.", + "example": "hunter2", + "type": "string" + }, + "username": { + "description": "The username of the Docker Hub account to authenticate with.", + "example": "myusername", + "type": "string" + } + }, + "required": [ + "username", + "password" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/UsersLoginRequest/" + }, + { + "name": "WeekData", + "pointer": "/components/schemas/WeekData", + "schema": { + "examples": [ + { + "weeks": [ + { + "week": 31 + }, + { + "week": 32 + } + ] + } + ], + "properties": { + "weeks": { + "items": { + "$ref": "#/components/schemas/WeekModel" + }, + "type": "array" + } + }, + "required": [ + "weeks" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/WeekData/" + }, + { + "name": "WeekModel", + "pointer": "/components/schemas/WeekModel", + "schema": { + "examples": [ + { + "week": 31 + } + ], + "properties": { + "week": { + "type": "integer" + } + }, + "required": [ + "week" + ], + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/WeekModel/" + }, + { + "name": "YearData", + "pointer": "/components/schemas/YearData", + "schema": { + "examples": [ + { + "years": [ + { + "year": 2025 + } + ] + } + ], + "properties": { + "years": { + "items": { + "$ref": "#/components/schemas/YearModel" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/YearData/" + }, + { + "name": "YearModel", + "pointer": "/components/schemas/YearModel", + "schema": { + "properties": { + "year": { + "type": "integer" + } + }, + "type": "object" + }, + "url": "/reference/api/dvp/latest/schemas/YearModel/" + } + ], + "securitySchemes": { + "HubAuth": { + "bearerFormat": "JWT", + "description": "JWT Bearer Authentication is required to access the Docker DVP Data API. \n \nThis authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/latest/#authentication)\n", + "scheme": "bearer", + "type": "http", + "x-displayName": "Docker Hub Authentication" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/api/publisher/analytics/v1" + } + ], + "source": "content/reference/api/dvp/latest.yaml", + "sourceURL": "/reference/api/dvp/latest.yaml", + "tags": [ + { + "description": "Authentication Endpoints reference.", + "kind": "nav", + "name": "authentication", + "summary": "Authentication Endpoints" + }, + { + "description": "Namespace data reference.", + "kind": "nav", + "name": "namespaces", + "summary": "Namespace data" + }, + { + "description": "Discovery reference.", + "kind": "nav", + "name": "discovery", + "summary": "Discovery" + }, + { + "description": "[ResponseDataFile](#schema-ResponseDataFile)\n", + "kind": "info", + "name": "responseDataFile", + "summary": "ResponseDataFile" + }, + { + "description": "[YearModel](#schema-YearModel)\n", + "kind": "info", + "name": "yearModel", + "summary": "Year Data Model" + }, + { + "description": "[MonthModel](#schema-MonthModel)\n", + "kind": "info", + "name": "monthModel", + "summary": "Month Data Model" + }, + { + "description": "[WeekModel](#schema-WeekModel)\n", + "kind": "info", + "name": "weekModel", + "summary": "Week Data Model" + } + ], + "title": "Publisher analytics", + "url": "/reference/api/dvp/latest/", + "version": "1.0.0" + }, + { + "connection": "hosted", + "description": "Docker Hub is an OCI-compliant registry, which means it adheres to the open\nstandards defined by the Open Container Initiative (OCI) for distributing\ncontainer images. This ensures compatibility with a wide range of tools and\nplatforms in the container ecosystem.\n\nThis reference documents the Docker Hub-supported subset of the Registry HTTP API V2.\nIt focuses on pulling, pushing, and deleting images. It does not cover the full OCI Distribution Specification.\n\nFor the complete OCI specification, see [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec).\n", + "diagnostics": [], + "digest": "6676db9e3e34f6529e34a9a5574d4dfa1a20e534e42c2d5810a5fcf8b3dd7453", + "exampleCount": 79, + "experimental": false, + "guides": [ + "/reference/api/registry/auth.md" + ], + "id": "registry", + "manual": "/manuals/docker-hub/repos/", + "operations": [ + { + "acceptMedia": "", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/?mount=sha256%3Aabc123def456...\u0026from=library%2Fbusybox'", + "curlNotes": [], + "deprecated": null, + "description": "Initiate an upload session for a blob (layer or config) in a repository.\n\nThis is the first step in uploading a blob. It returns a `Location` URL where the blob can be uploaded using `PATCH` (chunked) or `PUT` (monolithic).\n\nInstead of uploading a blob, a client may attempt to mount a blob from another repository (if it has read access) by including the `mount` and `from` query parameters.\n\nIf successful, the registry responds with `201 Created` and the blob is reused without re-upload.\n\nIf the mount fails, the upload proceeds as usual and returns a `202 Accepted`.\n\nYou must authenticate with `push` access to the target repository.\n", + "id": "InitiateBlobUpload", + "line": 648, + "method": "POST", + "parameters": [ + { + "description": "Name of the target repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the blob to mount from another repository", + "example": "sha256:abc123def456...", + "in": "query", + "name": "mount", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/1", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Source repository to mount the blob from", + "example": "library/busybox", + "in": "query", + "name": "from", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/2", + "required": false, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/uploads/", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post", + "raw": { + "description": "Initiate an upload session for a blob (layer or config) in a repository.\n\nThis is the first step in uploading a blob. It returns a `Location` URL where the blob can be uploaded using `PATCH` (chunked) or `PUT` (monolithic).\n\nInstead of uploading a blob, a client may attempt to mount a blob from another repository (if it has read access) by including the `mount` and `from` query parameters.\n\nIf successful, the registry responds with `201 Created` and the blob is reused without re-upload.\n\nIf the mount fails, the upload proceeds as usual and returns a `202 Accepted`.\n\nYou must authenticate with `push` access to the target repository.\n", + "operationId": "InitiateBlobUpload", + "parameters": [ + { + "description": "Name of the target repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the blob to mount from another repository", + "example": "sha256:abc123def456...", + "in": "query", + "name": "mount", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Source repository to mount the blob from", + "example": "library/busybox", + "in": "query", + "name": "from", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "201": { + "description": "Blob successfully mounted from another repository.", + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Canonical digest of the mounted blob", + "example": "sha256:abc123...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL where the mounted blob is accessible", + "example": "/v2/library/ubuntu/blobs/sha256:abc123...", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "description": "Upload initiated successfully (fallback if mount fails).", + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Upload-UUID": { + "description": "Server-generated UUID for the upload session", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Upload location URL for `PATCH` or `PUT` requests", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Current upload byte range (typically `0-0` at init)", + "example": "0-0", + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Authentication required." + }, + "403": { + "description": "Access denied." + }, + "404": { + "description": "Repository not found." + }, + "429": { + "description": "Too many requests." + } + }, + "summary": "Initiate blob upload or attempt cross-repository blob mount", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL (Initiate Standard Upload)", + "lang": "Bash", + "source": "# Initiate a standard blob upload session\ncurl -i -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/\n" + }, + { + "label": "cURL (Cross-Repository Blob Mount)", + "lang": "Bash", + "source": "# Attempt a cross-repository blob mount\ncurl -i -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n \"https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/?mount=sha256:abc123def456...\u0026from=library/busybox\"\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Initiate blob upload or attempt cross-repository blob mount", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/InitiateBlobUpload/", + "variants": [ + { + "description": "Blob successfully mounted from another repository.", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Canonical digest of the mounted blob", + "example": "sha256:abc123...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL where the mounted blob is accessible", + "example": "/v2/library/ubuntu/blobs/sha256:abc123...", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/201", + "status": "201" + }, + { + "description": "Upload initiated successfully (fallback if mount fails).", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Upload-UUID": { + "description": "Server-generated UUID for the upload session", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Upload location URL for `PATCH` or `PUT` requests", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Current upload byte range (typically `0-0` at init)", + "example": "0-0", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/202", + "status": "202" + }, + { + "description": "Authentication required.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/401", + "status": "401" + }, + { + "description": "Access denied.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/403", + "status": "403" + }, + { + "description": "Repository not found.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/404", + "status": "404" + }, + { + "description": "Too many requests.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/abc123'", + "curlNotes": [], + "deprecated": null, + "description": "Retrieve the current status of an in-progress blob upload.\n\nThis is useful for:\n- Resuming an interrupted upload\n- Determining how many bytes have been accepted so far\n- Retrying from the correct offset in chunked uploads\n\nThe response includes the `Range` header indicating the byte range received so far, and a `Docker-Upload-UUID` for identifying the session.\n", + "id": "GetBlobUploadStatus", + "line": 898, + "method": "GET", + "parameters": [ + { + "description": "Repository Name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/uploads/{uuid}", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get", + "raw": { + "description": "Retrieve the current status of an in-progress blob upload.\n\nThis is useful for:\n- Resuming an interrupted upload\n- Determining how many bytes have been accepted so far\n- Retrying from the correct offset in chunked uploads\n\nThe response includes the `Range` header indicating the byte range received so far, and a `Docker-Upload-UUID` for identifying the session.\n", + "operationId": "GetBlobUploadStatus", + "parameters": [ + { + "description": "Repository Name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Upload in progress. No body is returned.", + "headers": { + "Docker-Upload-UUID": { + "description": "UUID of the upload session", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL to continue or complete the upload", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Current byte range uploaded (inclusive)", + "example": "0-16383", + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Upload session not found" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Get blob upload status", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# GET upload status\ncurl --include --request GET \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Get blob upload status", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/GetBlobUploadStatus/", + "variants": [ + { + "description": "Upload in progress. No body is returned.", + "direction": "Response", + "examples": [], + "headers": { + "Docker-Upload-UUID": { + "description": "UUID of the upload session", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL to continue or complete the upload", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Current byte range uploaded (inclusive)", + "example": "0-16383", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/responses/204", + "status": "204" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/responses/403", + "status": "403" + }, + { + "description": "Upload session not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/responses/404", + "status": "404" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/get/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Content-Type: application/octet-stream' \\\n --data-binary @request-body \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/abc123?digest=sha256%3Aabcd1234...'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Complete the upload of a blob by finalizing an upload session.\n\nThis request must include the `digest` query parameter and optionally the last chunk of data. When the registry receives this request, it verifies the digest and stores the blob.\n\nThis endpoint supports:\n- Monolithic uploads (upload entire blob in this request)\n- Finalizing chunked uploads (last chunk plus `digest`)\n", + "id": "CompleteBlobUpload", + "line": 962, + "method": "PUT", + "parameters": [ + { + "description": "Repository name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID returned from the POST request", + "example": "abc123", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the uploaded blob", + "example": "sha256:abcd1234...", + "in": "query", + "name": "digest", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/parameters/2", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/uploads/{uuid}", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put", + "raw": { + "description": "Complete the upload of a blob by finalizing an upload session.\n\nThis request must include the `digest` query parameter and optionally the last chunk of data. When the registry receives this request, it verifies the digest and stores the blob.\n\nThis endpoint supports:\n- Monolithic uploads (upload entire blob in this request)\n- Finalizing chunked uploads (last chunk plus `digest`)\n", + "operationId": "CompleteBlobUpload", + "parameters": [ + { + "description": "Repository name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID returned from the POST request", + "example": "abc123", + "in": "path", + "name": "uuid", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the uploaded blob", + "example": "sha256:abcd1234...", + "in": "query", + "name": "digest", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "examples": { + "layer-upload": { + "summary": "Layer tarball blob", + "value": "\u003cbinary data not shown\u003e" + } + }, + "schema": { + "format": "binary", + "type": "string" + } + } + }, + "required": false + }, + "responses": { + "201": { + "description": "Upload completed successfully", + "headers": { + "Content-Length": { + "description": "Always zero for completed uploads", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Canonical digest of the stored blob", + "example": "sha256:abcd1234...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL where the blob is now accessible", + "example": "/v2/library/ubuntu/blobs/sha256:abcd1234...", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "Invalid digest or missing parameters" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Upload session not found" + }, + "416": { + "description": "Requested range not satisfiable (if used in chunked mode)" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Complete blob upload", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# PUT – complete upload (monolithic or final chunk)\ncurl -X PUT \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary @layer.tar.gz \\\n \"https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123?digest=sha256:abcd1234...\"\n" + } + ] + }, + "references": [], + "requestSchema": { + "format": "binary", + "type": "string" + }, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Complete blob upload", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/CompleteBlobUpload/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "text", + "name": "layer-upload", + "text": "\u003cbinary data not shown\u003e", + "value": "\u003cbinary data not shown\u003e" + } + ], + "headers": null, + "media": "application/octet-stream", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/requestBody/content/application~1octet-stream", + "required": false, + "schema": { + "format": "binary", + "type": "string" + }, + "status": "" + }, + { + "description": "Upload completed successfully", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Always zero for completed uploads", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Canonical digest of the stored blob", + "example": "sha256:abcd1234...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL where the blob is now accessible", + "example": "/v2/library/ubuntu/blobs/sha256:abcd1234...", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/201", + "status": "201" + }, + { + "description": "Invalid digest or missing parameters", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/400", + "status": "400" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/403", + "status": "403" + }, + { + "description": "Upload session not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/404", + "status": "404" + }, + { + "description": "Requested range not satisfiable (if used in chunked mode)", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/416", + "status": "416" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/put/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/abc123'", + "curlNotes": [], + "deprecated": null, + "description": "Cancel an in-progress blob upload session.\n\nThis operation discards any data that has been uploaded and invalidates the upload session.\n\nUse this when:\n- An upload fails or is aborted mid-process\n- The client wants to clean up unused upload sessions\n\nAfter cancellation, the UUID is no longer valid and a new `POST` must be issued to restart the upload.\n", + "id": "CancelBlobUpload", + "line": 1139, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/uploads/{uuid}", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete", + "raw": { + "description": "Cancel an in-progress blob upload session.\n\nThis operation discards any data that has been uploaded and invalidates the upload session.\n\nUse this when:\n- An upload fails or is aborted mid-process\n- The client wants to clean up unused upload sessions\n\nAfter cancellation, the UUID is no longer valid and a new `POST` must be issued to restart the upload.\n", + "operationId": "CancelBlobUpload", + "parameters": [ + { + "description": "Name of the repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Upload session cancelled successfully. No body is returned.", + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + } + } + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Upload session not found" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Cancel blob upload", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# DELETE – cancel an upload session\ncurl -X DELETE \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123`\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Cancel blob upload", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/CancelBlobUpload/", + "variants": [ + { + "description": "Upload session cancelled successfully. No body is returned.", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Always zero", + "example": 0, + "schema": { + "type": "integer" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/responses/204", + "status": "204" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/responses/403", + "status": "403" + }, + { + "description": "Upload session not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/responses/404", + "status": "404" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/delete/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request PATCH \\\n --header 'Content-Range: bytes 0-65535' \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Content-Type: application/octet-stream' \\\n --data-binary @request-body \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/abc123'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Upload a chunk of a blob to an active upload session.\n\nUse this method for **chunked uploads**, especially for large blobs or when resuming interrupted uploads.\n\nThe client sends binary data using `PATCH`, optionally including a `Content-Range` header.\n\nAfter each chunk is accepted, the registry returns a `202 Accepted` response with:\n- `Range`: current byte range stored\n- `Docker-Upload-UUID`: identifier for the upload session\n- `Location`: URL to continue the upload or finalize with `PUT`\n", + "id": "UploadBlobChunk", + "line": 1049, + "method": "PATCH", + "parameters": [ + { + "description": "Repository name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional. Byte range of the chunk being sent", + "example": "bytes 0-65535", + "in": "header", + "name": "Content-Range", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/2", + "required": false, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/uploads/{uuid}", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch", + "raw": { + "description": "Upload a chunk of a blob to an active upload session.\n\nUse this method for **chunked uploads**, especially for large blobs or when resuming interrupted uploads.\n\nThe client sends binary data using `PATCH`, optionally including a `Content-Range` header.\n\nAfter each chunk is accepted, the registry returns a `202 Accepted` response with:\n- `Range`: current byte range stored\n- `Docker-Upload-UUID`: identifier for the upload session\n- `Location`: URL to continue the upload or finalize with `PUT`\n", + "operationId": "UploadBlobChunk", + "parameters": [ + { + "description": "Repository name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Upload session UUID", + "example": "abc123", + "in": "path", + "name": "uuid", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional. Byte range of the chunk being sent", + "example": "bytes 0-65535", + "in": "header", + "name": "Content-Range", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "examples": { + "chunk-0": { + "summary": "Upload chunk 0 of a blob", + "value": "\u003cbinary data not shown\u003e" + } + }, + "schema": { + "format": "binary", + "type": "string" + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "Chunk accepted and stored", + "headers": { + "Docker-Upload-UUID": { + "description": "Upload session UUID", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL to continue or finalize the upload", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Byte range uploaded so far (inclusive)", + "example": "0-65535", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "Malformed content or range" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Upload session not found" + }, + "416": { + "description": "Range error (e.g., chunk out of order)" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Upload blob chunk", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# PATCH – upload a chunk (first 64 KiB)\ncurl -X PATCH \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary @chunk-0.bin \\\n \"https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123\"\n" + } + ] + }, + "references": [], + "requestSchema": { + "format": "binary", + "type": "string" + }, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Upload blob chunk", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/UploadBlobChunk/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "text", + "name": "chunk-0", + "text": "\u003cbinary data not shown\u003e", + "value": "\u003cbinary data not shown\u003e" + } + ], + "headers": null, + "media": "application/octet-stream", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/requestBody/content/application~1octet-stream", + "required": true, + "schema": { + "format": "binary", + "type": "string" + }, + "status": "" + }, + { + "description": "Chunk accepted and stored", + "direction": "Response", + "examples": [], + "headers": { + "Docker-Upload-UUID": { + "description": "Upload session UUID", + "example": "abc123", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "URL to continue or finalize the upload", + "example": "/v2/library/ubuntu/blobs/uploads/abc123", + "schema": { + "type": "string" + } + }, + "Range": { + "description": "Byte range uploaded so far (inclusive)", + "example": "0-65535", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/202", + "status": "202" + }, + { + "description": "Malformed content or range", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/400", + "status": "400" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/403", + "status": "403" + }, + { + "description": "Upload session not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/404", + "status": "404" + }, + { + "description": "Range error (e.g., chunk out of order)", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/416", + "status": "416" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "application/octet-stream", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Accept: application/octet-stream' \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/sha256:abc123def456...'", + "curlNotes": [], + "deprecated": null, + "description": "Download the blob identified by digest from the registry.\n\nBlobs include image layers and configuration objects. Clients must use the digest from the manifest to retrieve a blob.\n\nThis endpoint may return a `307 Temporary Redirect` to a CDN or storage location. Clients must follow the redirect to obtain the actual blob content.\n\nThe blob content is typically a gzipped tarball (for layers) or JSON (for configs). The MIME type is usually `application/octet-stream`.\n", + "id": "GetBlob", + "line": 816, + "method": "GET", + "parameters": [ + { + "description": "Repository Name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the Blob", + "example": "sha256:abc123def456...", + "in": "path", + "name": "digest", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/{digest}", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get", + "raw": { + "description": "Download the blob identified by digest from the registry.\n\nBlobs include image layers and configuration objects. Clients must use the digest from the manifest to retrieve a blob.\n\nThis endpoint may return a `307 Temporary Redirect` to a CDN or storage location. Clients must follow the redirect to obtain the actual blob content.\n\nThe blob content is typically a gzipped tarball (for layers) or JSON (for configs). The MIME type is usually `application/octet-stream`.\n", + "operationId": "GetBlob", + "parameters": [ + { + "description": "Repository Name", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the Blob", + "example": "sha256:abc123def456...", + "in": "path", + "name": "digest", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/octet-stream": { + "examples": { + "small-layer": { + "summary": "Example binary blob (gzipped tar layer)", + "value": "\u003cbinary data not shown\u003e" + } + }, + "schema": { + "format": "binary", + "type": "string" + } + } + }, + "description": "Blob content returned directly", + "headers": { + "Content-Length": { + "description": "Size of the blob in bytes", + "example": 32768, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "MIME type of the blob", + "example": "application/octet-stream", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the returned blob", + "example": "sha256:abc123def456...", + "schema": { + "type": "string" + } + } + } + }, + "307": { + "description": "Temporary redirect to blob location", + "headers": { + "Location": { + "description": "Redirect URL for blob download (e.g., S3 or CDN)", + "example": "https://cdn.docker.io/blobs/library/ubuntu/abc123...", + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Blob not found" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Retrieve blob", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# GET (download) a blob\ncurl -L \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/sha256:abc123... \\\n -o layer.tar.gz\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Retrieve blob", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/GetBlob/", + "variants": [ + { + "description": "Blob content returned directly", + "direction": "Response", + "examples": [ + { + "language": "text", + "name": "small-layer", + "text": "\u003cbinary data not shown\u003e", + "value": "\u003cbinary data not shown\u003e" + } + ], + "headers": { + "Content-Length": { + "description": "Size of the blob in bytes", + "example": 32768, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "MIME type of the blob", + "example": "application/octet-stream", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the returned blob", + "example": "sha256:abc123def456...", + "schema": { + "type": "string" + } + } + }, + "media": "application/octet-stream", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/200/content/application~1octet-stream", + "required": null, + "schema": { + "format": "binary", + "type": "string" + }, + "status": "200" + }, + { + "description": "Temporary redirect to blob location", + "direction": "Response", + "examples": [], + "headers": { + "Location": { + "description": "Redirect URL for blob download (e.g., S3 or CDN)", + "example": "https://cdn.docker.io/blobs/library/ubuntu/abc123...", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/307", + "status": "307" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/403", + "status": "403" + }, + { + "description": "Blob not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/404", + "status": "404" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/get/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "application/octet-stream", + "curl": "curl \\\n --head \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Accept: application/octet-stream' \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/sha256:abc123def4567890...'", + "curlNotes": [], + "deprecated": null, + "description": "Check whether a blob (layer or config) exists in the registry.\n\nThis is useful before uploading a blob to avoid duplicates.\n\nIf the blob is present, the registry returns a `200 OK` response with headers like `Content-Length` and `Docker-Content-Digest`.\n\nIf the blob does not exist, the response will be `404 Not Found`.\n", + "id": "CheckBlobExists", + "line": 753, + "method": "HEAD", + "parameters": [ + { + "description": "Name of the Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the blob", + "example": "sha256:abc123def4567890...", + "in": "path", + "name": "digest", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/blobs/{digest}", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head", + "raw": { + "description": "Check whether a blob (layer or config) exists in the registry.\n\nThis is useful before uploading a blob to avoid duplicates.\n\nIf the blob is present, the registry returns a `200 OK` response with headers like `Content-Length` and `Docker-Content-Digest`.\n\nIf the blob does not exist, the response will be `404 Not Found`.\n", + "operationId": "CheckBlobExists", + "parameters": [ + { + "description": "Name of the Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the blob", + "example": "sha256:abc123def4567890...", + "in": "path", + "name": "digest", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Blob exists", + "headers": { + "Content-Length": { + "description": "Size of the blob in bytes", + "example": 32654, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "MIME type of the blob content", + "example": "application/octet-stream", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the blob", + "example": "sha256:abc123def4567890...", + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Blob not found" + }, + "429": { + "description": "Too many requests" + } + }, + "summary": "Check existence of blob", + "tags": [ + "Blobs" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# HEAD to check if a blob exists\ncurl -I \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/sha256:abc123...\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Check existence of blob", + "tags": [ + "Blobs" + ], + "url": "/reference/api/registry/latest/operations/CheckBlobExists/", + "variants": [ + { + "description": "Blob exists", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Size of the blob in bytes", + "example": 32654, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "MIME type of the blob content", + "example": "application/octet-stream", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the blob", + "example": "sha256:abc123def4567890...", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/responses/200", + "status": "200" + }, + { + "description": "Authentication required", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/responses/401", + "status": "401" + }, + { + "description": "Access denied", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/responses/403", + "status": "403" + }, + { + "description": "Blob not found", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/responses/404", + "status": "404" + }, + { + "description": "Too many requests", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1blobs~1{digest}/head/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "application/vnd.docker.distribution.manifest.v2+json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Accept: application/vnd.docker.distribution.manifest.v2+json' \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/manifests/\u003cREFERENCE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Fetch the manifest identified by `name` and `reference`, where `reference` can be a tag (e.g., `latest`) or a digest (e.g., `sha256:...`).\n\nThe manifest contains metadata about the image, including configuration and layer digests. It is required for pulling images from the registry.\n\nThis endpoint requires authentication. Use the `Authorization: Bearer \u003ctoken\u003e` header.\n\nUse the `Accept` header to select the manifest representation. Supported media types:\n\n- `application/vnd.docker.distribution.manifest.v2+json`\n- `application/vnd.docker.distribution.manifest.list.v2+json`\n- `application/vnd.oci.image.manifest.v1+json`\n- `application/vnd.oci.image.index.v1+json`\n", + "id": "GetImageManifest", + "line": 248, + "method": "GET", + "parameters": [ + { + "description": "Name of the target repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest of the target manifest", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/manifests/{reference}", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get", + "raw": { + "description": "Fetch the manifest identified by `name` and `reference`, where `reference` can be a tag (e.g., `latest`) or a digest (e.g., `sha256:...`).\n\nThe manifest contains metadata about the image, including configuration and layer digests. It is required for pulling images from the registry.\n\nThis endpoint requires authentication. Use the `Authorization: Bearer \u003ctoken\u003e` header.\n\nUse the `Accept` header to select the manifest representation. Supported media types:\n\n- `application/vnd.docker.distribution.manifest.v2+json`\n- `application/vnd.docker.distribution.manifest.list.v2+json`\n- `application/vnd.oci.image.manifest.v1+json`\n- `application/vnd.oci.image.index.v1+json`\n", + "operationId": "GetImageManifest", + "parameters": [ + { + "description": "Name of the target repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest of the target manifest", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/vnd.docker.distribution.manifest.v2+json": { + "examples": { + "docker-manifest": { + "summary": "Docker image manifest (schema v2)", + "value": { + "config": { + "digest": "sha256:123456abcdef...", + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 7023 + }, + "layers": [ + { + "digest": "sha256:abcdef123456...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 32654 + }, + { + "digest": "sha256:7890abcdef12...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 16724 + } + ], + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "schemaVersion": 2 + } + } + }, + "schema": { + "properties": { + "config": { + "properties": { + "digest": { + "example": "sha256:a3f3e...c1234", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.container.image.v1+json", + "type": "string" + }, + "size": { + "example": 7023, + "type": "integer" + } + }, + "type": "object" + }, + "layers": { + "items": { + "properties": { + "digest": { + "example": "sha256:bcf2...78901", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "type": "string" + }, + "size": { + "example": 32654, + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "mediaType": { + "example": "application/vnd.docker.distribution.manifest.v2+json", + "type": "string" + }, + "schemaVersion": { + "example": 2, + "type": "integer" + } + }, + "required": [ + "schemaVersion", + "mediaType", + "config", + "layers" + ], + "type": "object" + } + } + }, + "description": "Manifest fetched successfully.", + "headers": { + "Content-Type": { + "description": "Media type of the returned manifest.", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the returned manifest content.", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "Invalid name or reference." + }, + "401": { + "description": "Authentication required." + }, + "403": { + "description": "Access denied." + }, + "404": { + "description": "Repository or manifest not found." + }, + "429": { + "description": "Too many requests." + } + }, + "summary": "Get image manifest", + "tags": [ + "Manifests" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# GET a manifest (by tag or digest)\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/vnd.docker.distribution.manifest.v2+json\" \\\n https://registry-1.docker.io/v2/library/ubuntu/manifests/latest\n" + } + ], + "x-displayName": "Manifests" + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Get image manifest", + "tags": [ + "Manifests" + ], + "url": "/reference/api/registry/latest/operations/GetImageManifest/", + "variants": [ + { + "description": "Manifest fetched successfully.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "docker-manifest", + "text": "{\n \"config\": {\n \"digest\": \"sha256:123456abcdef...\",\n \"mediaType\": \"application/vnd.docker.container.image.v1+json\",\n \"size\": 7023\n },\n \"layers\": [\n {\n \"digest\": \"sha256:abcdef123456...\",\n \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n \"size\": 32654\n },\n {\n \"digest\": \"sha256:7890abcdef12...\",\n \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n \"size\": 16724\n }\n ],\n \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n \"schemaVersion\": 2\n}", + "value": { + "config": { + "digest": "sha256:123456abcdef...", + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 7023 + }, + "layers": [ + { + "digest": "sha256:abcdef123456...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 32654 + }, + { + "digest": "sha256:7890abcdef12...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 16724 + } + ], + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "schemaVersion": 2 + } + } + ], + "headers": { + "Content-Type": { + "description": "Media type of the returned manifest.", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the returned manifest content.", + "schema": { + "type": "string" + } + } + }, + "media": "application/vnd.docker.distribution.manifest.v2+json", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/200/content/application~1vnd.docker.distribution.manifest.v2+json", + "required": null, + "schema": { + "properties": { + "config": { + "properties": { + "digest": { + "example": "sha256:a3f3e...c1234", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.container.image.v1+json", + "type": "string" + }, + "size": { + "example": 7023, + "type": "integer" + } + }, + "type": "object" + }, + "layers": { + "items": { + "properties": { + "digest": { + "example": "sha256:bcf2...78901", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "type": "string" + }, + "size": { + "example": 32654, + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "mediaType": { + "example": "application/vnd.docker.distribution.manifest.v2+json", + "type": "string" + }, + "schemaVersion": { + "example": 2, + "type": "integer" + } + }, + "required": [ + "schemaVersion", + "mediaType", + "config", + "layers" + ], + "type": "object" + }, + "status": "200" + }, + { + "description": "Invalid name or reference.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/400", + "status": "400" + }, + { + "description": "Authentication required.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/401", + "status": "401" + }, + { + "description": "Access denied.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/403", + "status": "403" + }, + { + "description": "Repository or manifest not found.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/404", + "status": "404" + }, + { + "description": "Too many requests.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/get/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Content-Type: application/vnd.docker.distribution.manifest.v2+json' \\\n --data-raw '{\n \"config\": {\n \"digest\": \"sha256:123456abcdef...\",\n \"mediaType\": \"application/vnd.docker.container.image.v1+json\",\n \"size\": 7023\n },\n \"layers\": [\n {\n \"digest\": \"sha256:abcdef123456...\",\n \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n \"size\": 32654\n }\n ],\n \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n \"schemaVersion\": 2\n}' \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/manifests/\u003cREFERENCE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Upload an image manifest for a given tag or digest. This operation registers a manifest in a repository, allowing it to be pulled using the specified reference.\n\nThis endpoint is typically used after all layer and config blobs have been uploaded to the registry.\n\nThe manifest must conform to the expected schema and media type. For Docker image manifest schema version 2, use:\n`application/vnd.docker.distribution.manifest.v2+json`\n\nRequires authentication via a bearer token with `push` scope for the target repository.\n", + "id": "PutImageManifest", + "line": 377, + "method": "PUT", + "parameters": [ + { + "description": "Name of the target Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest to associate with the uploaded Manifest", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/manifests/{reference}", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put", + "raw": { + "description": "Upload an image manifest for a given tag or digest. This operation registers a manifest in a repository, allowing it to be pulled using the specified reference.\n\nThis endpoint is typically used after all layer and config blobs have been uploaded to the registry.\n\nThe manifest must conform to the expected schema and media type. For Docker image manifest schema version 2, use:\n`application/vnd.docker.distribution.manifest.v2+json`\n\nRequires authentication via a bearer token with `push` scope for the target repository.\n", + "operationId": "PutImageManifest", + "parameters": [ + { + "description": "Name of the target Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest to associate with the uploaded Manifest", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/vnd.docker.distribution.manifest.v2+json": { + "examples": { + "sample-manifest": { + "summary": "Sample Docker image manifest (schema v2)", + "value": { + "config": { + "digest": "sha256:123456abcdef...", + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 7023 + }, + "layers": [ + { + "digest": "sha256:abcdef123456...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 32654 + } + ], + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "schemaVersion": 2 + } + } + }, + "schema": { + "properties": { + "config": { + "properties": { + "digest": { + "example": "sha256:123456abcdef...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.container.image.v1+json", + "type": "string" + }, + "size": { + "example": 7023, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "layers": { + "items": { + "properties": { + "digest": { + "example": "sha256:abcdef123456...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "type": "string" + }, + "size": { + "example": 32654, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "type": "array" + }, + "mediaType": { + "example": "application/vnd.docker.distribution.manifest.v2+json", + "type": "string" + }, + "schemaVersion": { + "example": 2, + "type": "integer" + } + }, + "required": [ + "schemaVersion", + "mediaType", + "config", + "layers" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Manifest created successfully.", + "headers": { + "Content-Length": { + "description": "Always zero.", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the stored manifest.", + "example": "sha256:abcdef123456...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Canonical location of the uploaded manifest.", + "example": "/v2/library/ubuntu/manifests/latest", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "Invalid name, reference, or manifest." + }, + "401": { + "description": "Authentication required." + }, + "403": { + "description": "Access denied." + }, + "404": { + "description": "Repository not found." + }, + "405": { + "description": "Operation not allowed." + }, + "429": { + "description": "Too many requests." + } + }, + "summary": "Put image manifest", + "tags": [ + "Manifests" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# PUT a manifest (tag = latest)\ncurl -X PUT \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/vnd.docker.distribution.manifest.v2+json\" \\\n --data-binary @manifest.json \\\n https://registry-1.docker.io/v2/library/ubuntu/manifests/latest\n" + } + ] + }, + "references": [], + "requestSchema": { + "properties": { + "config": { + "properties": { + "digest": { + "example": "sha256:123456abcdef...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.container.image.v1+json", + "type": "string" + }, + "size": { + "example": 7023, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "layers": { + "items": { + "properties": { + "digest": { + "example": "sha256:abcdef123456...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "type": "string" + }, + "size": { + "example": 32654, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "type": "array" + }, + "mediaType": { + "example": "application/vnd.docker.distribution.manifest.v2+json", + "type": "string" + }, + "schemaVersion": { + "example": 2, + "type": "integer" + } + }, + "required": [ + "schemaVersion", + "mediaType", + "config", + "layers" + ], + "type": "object" + }, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Put image manifest", + "tags": [ + "Manifests" + ], + "url": "/reference/api/registry/latest/operations/PutImageManifest/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "sample-manifest", + "text": "{\n \"config\": {\n \"digest\": \"sha256:123456abcdef...\",\n \"mediaType\": \"application/vnd.docker.container.image.v1+json\",\n \"size\": 7023\n },\n \"layers\": [\n {\n \"digest\": \"sha256:abcdef123456...\",\n \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n \"size\": 32654\n }\n ],\n \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n \"schemaVersion\": 2\n}", + "value": { + "config": { + "digest": "sha256:123456abcdef...", + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 7023 + }, + "layers": [ + { + "digest": "sha256:abcdef123456...", + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 32654 + } + ], + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "schemaVersion": 2 + } + } + ], + "headers": null, + "media": "application/vnd.docker.distribution.manifest.v2+json", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/requestBody/content/application~1vnd.docker.distribution.manifest.v2+json", + "required": true, + "schema": { + "properties": { + "config": { + "properties": { + "digest": { + "example": "sha256:123456abcdef...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.container.image.v1+json", + "type": "string" + }, + "size": { + "example": 7023, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "layers": { + "items": { + "properties": { + "digest": { + "example": "sha256:abcdef123456...", + "type": "string" + }, + "mediaType": { + "example": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "type": "string" + }, + "size": { + "example": 32654, + "type": "integer" + } + }, + "required": [ + "mediaType", + "size", + "digest" + ], + "type": "object" + }, + "type": "array" + }, + "mediaType": { + "example": "application/vnd.docker.distribution.manifest.v2+json", + "type": "string" + }, + "schemaVersion": { + "example": 2, + "type": "integer" + } + }, + "required": [ + "schemaVersion", + "mediaType", + "config", + "layers" + ], + "type": "object" + }, + "status": "" + }, + { + "description": "Manifest created successfully.", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Always zero.", + "example": 0, + "schema": { + "type": "integer" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the stored manifest.", + "example": "sha256:abcdef123456...", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Canonical location of the uploaded manifest.", + "example": "/v2/library/ubuntu/manifests/latest", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/201", + "status": "201" + }, + { + "description": "Invalid name, reference, or manifest.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/400", + "status": "400" + }, + { + "description": "Authentication required.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/401", + "status": "401" + }, + { + "description": "Access denied.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/403", + "status": "403" + }, + { + "description": "Repository not found.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/404", + "status": "404" + }, + { + "description": "Operation not allowed.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/405", + "status": "405" + }, + { + "description": "Too many requests.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n 'https://registry-1.docker.io/v2/yourusername%2Fhelloworld/manifests/sha256:abc123def456...'", + "curlNotes": [], + "deprecated": null, + "description": "Delete an image manifest from a repository by digest.\n\nOnly untagged or unreferenced manifests can be deleted. If the manifest is still referenced by a tag or another image, the registry will return `403 Forbidden`.\n\nThis operation requires `delete` access to the repository.\n\n\u003e **Note**\n\u003e\n\u003e Manifest deletion operations may take some time and could return a `500 Internal Server Error`. The system automatically retries the deletion in the background. Manual intervention is not required.\n", + "id": "DeleteImageManifest", + "line": 596, + "method": "DELETE", + "parameters": [ + { + "description": "Name of the repository", + "example": "yourusername/helloworld", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the manifest to delete (e.g., `sha256:...`)", + "example": "sha256:abc123def456...", + "in": "path", + "name": "reference", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/manifests/{reference}", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete", + "raw": { + "description": "Delete an image manifest from a repository by digest.\n\nOnly untagged or unreferenced manifests can be deleted. If the manifest is still referenced by a tag or another image, the registry will return `403 Forbidden`.\n\nThis operation requires `delete` access to the repository.\n\n\u003e **Note**\n\u003e\n\u003e Manifest deletion operations may take some time and could return a `500 Internal Server Error`. The system automatically retries the deletion in the background. Manual intervention is not required.\n", + "operationId": "DeleteImageManifest", + "parameters": [ + { + "description": "Name of the repository", + "example": "yourusername/helloworld", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Digest of the manifest to delete (e.g., `sha256:...`)", + "example": "sha256:abc123def456...", + "in": "path", + "name": "reference", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "description": "Manifest deleted successfully. No content returned." + }, + "401": { + "description": "Authentication required." + }, + "403": { + "description": "Access denied. The manifest may still be referenced." + }, + "404": { + "description": "Manifest or repository not found." + }, + "405": { + "description": "Only digest-based deletion is allowed." + }, + "429": { + "description": "Too many requests." + } + }, + "summary": "Delete image manifest", + "tags": [ + "Manifests" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# DELETE a manifest by digest\ncurl -X DELETE \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/yourusername/helloworld/manifests/sha256:abc123def456...\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Delete image manifest", + "tags": [ + "Manifests" + ], + "url": "/reference/api/registry/latest/operations/DeleteImageManifest/", + "variants": [ + { + "description": "Manifest deleted successfully. No content returned.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/202", + "status": "202" + }, + { + "description": "Authentication required.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/401", + "status": "401" + }, + { + "description": "Access denied. The manifest may still be referenced.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/403", + "status": "403" + }, + { + "description": "Manifest or repository not found.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/404", + "status": "404" + }, + { + "description": "Only digest-based deletion is allowed.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/405", + "status": "405" + }, + { + "description": "Too many requests.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/delete/responses/429", + "status": "429" + } + ] + }, + { + "acceptMedia": "application/vnd.docker.distribution.manifest.v2+json", + "curl": "curl \\\n --head \\\n --header \"Authorization: Bearer ${REGISTRY_TOKEN}\" \\\n --header 'Accept: application/vnd.docker.distribution.manifest.v2+json' \\\n 'https://registry-1.docker.io/v2/library%2Fubuntu/manifests/\u003cREFERENCE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Use this endpoint to verify whether a manifest exists by tag or digest.\n\nThis is a lightweight operation that returns only headers (no body). It is useful for:\n- Checking for the existence of a specific image version\n- Determining the digest or size of a manifest before downloading or deleting\n\nThis endpoint requires authentication with pull scope.\n\nUse the `Accept` header to select the manifest representation. Supported media types:\n\n- `application/vnd.docker.distribution.manifest.v2+json`\n- `application/vnd.docker.distribution.manifest.list.v2+json`\n- `application/vnd.oci.image.manifest.v1+json`\n- `application/vnd.oci.image.index.v1+json`\n", + "id": "HeadImageManifest", + "line": 519, + "method": "HEAD", + "parameters": [ + { + "description": "Name of the Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest to check", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v2/{name}/manifests/{reference}", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head", + "raw": { + "description": "Use this endpoint to verify whether a manifest exists by tag or digest.\n\nThis is a lightweight operation that returns only headers (no body). It is useful for:\n- Checking for the existence of a specific image version\n- Determining the digest or size of a manifest before downloading or deleting\n\nThis endpoint requires authentication with pull scope.\n\nUse the `Accept` header to select the manifest representation. Supported media types:\n\n- `application/vnd.docker.distribution.manifest.v2+json`\n- `application/vnd.docker.distribution.manifest.list.v2+json`\n- `application/vnd.oci.image.manifest.v1+json`\n- `application/vnd.oci.image.index.v1+json`\n", + "operationId": "HeadImageManifest", + "parameters": [ + { + "description": "Name of the Repository", + "example": "library/ubuntu", + "in": "path", + "name": "name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Tag or digest to check", + "examples": { + "by-digest": { + "summary": "Digest", + "value": "sha256:abc123def456..." + }, + "by-tag": { + "summary": "Tag", + "value": "latest" + } + }, + "in": "path", + "name": "reference", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Manifest exists.", + "headers": { + "Content-Length": { + "description": "Size of the manifest in bytes", + "example": 7082, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "Media type of the manifest", + "example": "application/vnd.docker.distribution.manifest.v2+json", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the manifest", + "example": "sha256:abc123...", + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Authentication required." + }, + "403": { + "description": "Access denied." + }, + "404": { + "description": "Manifest not found." + }, + "429": { + "description": "Too many requests." + } + }, + "summary": "Check if manifest exists", + "tags": [ + "Manifests" + ], + "x-codeSamples": [ + { + "label": "cURL", + "lang": "Bash", + "source": "# HEAD /v2/{name}/manifests/{reference}\ncurl -I \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/vnd.docker.distribution.manifest.v2+json\" \\\n https://registry-1.docker.io/v2/library/ubuntu/manifests/latest\n" + } + ] + }, + "references": [], + "requestSchema": null, + "security": [ + { + "registryToken": [] + } + ], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "summary": "Check if manifest exists", + "tags": [ + "Manifests" + ], + "url": "/reference/api/registry/latest/operations/HeadImageManifest/", + "variants": [ + { + "description": "Manifest exists.", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Size of the manifest in bytes", + "example": 7082, + "schema": { + "type": "integer" + } + }, + "Content-Type": { + "description": "Media type of the manifest", + "example": "application/vnd.docker.distribution.manifest.v2+json", + "schema": { + "type": "string" + } + }, + "Docker-Content-Digest": { + "description": "Digest of the manifest", + "example": "sha256:abc123...", + "schema": { + "type": "string" + } + } + }, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/responses/200", + "status": "200" + }, + { + "description": "Authentication required.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/responses/401", + "status": "401" + }, + { + "description": "Access denied.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/responses/403", + "status": "403" + }, + { + "description": "Manifest not found.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/responses/404", + "status": "404" + }, + { + "description": "Too many requests.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/head/responses/429", + "status": "429" + } + ] + } + ], + "owner": "docker/docs", + "product": "registry", + "schemaCount": 62, + "schemaURLs": {}, + "schemas": [], + "securitySchemes": { + "registryToken": { + "description": "Follow the WWW-Authenticate challenge and obtain a repository-scoped registry bearer token. Public image pulls can obtain a token without account credentials; the registry request still sends that token. This token exchange is separate from Hub API authentication.", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "description": "Docker Hub registry API", + "url": "https://registry-1.docker.io", + "x-audience": "public" + } + ], + "source": "content/reference/api/registry/latest.yaml", + "sourceURL": "/reference/api/registry/latest.yaml", + "tags": [ + { + "description": "All endpoints in this API are prefixed by the version and repository name, for example:\n\n```\n/v2/\u003cname\u003e/\n```\n\nThis format provides structured access control and URI-based scoping of image operations.\n\nFor example, to interact with the `library/ubuntu` repository, use:\n\n```\n/v2/library/ubuntu/\n```\n\nRepository names must meet these requirements:\n1. Consist of path components matching `[a-z0-9]+(?:[._-][a-z0-9]+)*`\n2. If more than one component, they must be separated by `/`\n3. Full repository name must be fewer than 256 characters\n", + "kind": "info", + "name": "overview", + "summary": "Overview" + }, + { + "description": "Specifies registry authentication.\n", + "externalDocs": { + "description": "Detailed authentication workflow and token usage", + "url": "https://docs.docker.com/reference/api/registry/auth/" + }, + "kind": "info", + "name": "authentication", + "summary": "Authentication" + }, + { + "description": "Image manifests are JSON documents that describe an image: its configuration blob, the digests of each layer blob, and metadata such as media‑types and annotations.\n", + "kind": "nav", + "name": "Manifests", + "summary": "Manifests" + }, + { + "description": "Blobs are the binary objects referenced from manifests:\nthe config JSON and one or more compressed layer tarballs.\n", + "kind": "nav", + "name": "Blobs", + "summary": "Blobs" + }, + { + "description": "Pulling an image involves retrieving the manifest and downloading each of the image's layer blobs. This section outlines the general steps followed by a working example.\n\n1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/).\n2. [Get the image manifest](#operation/GetImageManifest).\n3. If the response in the previous step is a multi-architecture manifest list, you must do the following:\n - Parse the `manifests[]` array to locate the digest for your target platform (e.g., `linux/amd64`).\n - [Get the image manifest](#operation/GetImageManifest) using the located digest.\n4. [Check if the blob exists](#operation/CheckBlobExists) before downloading. The client should send a `HEAD` request for each layer digest.\n5. [Download each layer blob](#operation/GetBlob) using the digest obtained from the manifest. The client should send a `GET` request for each layer digest.\n\nThe following bash script example pulls `library/ubuntu:latest` from Docker Hub.\n\n```bash\n#!/bin/bash\n\n# Step 1: Get a bearer token\nTOKEN=$(curl -s \"https://auth.docker.io/token?service=registry.docker.io\u0026scope=repository:library/ubuntu:pull\" | jq -r .token)\n\n# Step 2: Get the image manifest. In this example, an image manifest list is returned.\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/vnd.docker.distribution.manifest.list.v2+json\" \\\n https://registry-1.docker.io/v2/library/ubuntu/manifests/latest \\\n -o manifest-list.json\n\n# Step 3a: Parse the `manifests[]` array to locate the digest for your target platform (e.g., `linux/amd64`).\nIMAGE_MANIFEST_DIGEST=$(jq -r '.manifests[] | select(.platform.architecture == \"amd64\" and .platform.os == \"linux\") | .digest' manifest-list.json)\n\n# Step 3b: Get the platform-specific image manifest\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/vnd.docker.distribution.manifest.v2+json\" \\\n https://registry-1.docker.io/v2/library/ubuntu/manifests/$IMAGE_MANIFEST_DIGEST \\\n -o manifest.json\n\n# Step 4: Send a HEAD request to check if the layer blob exists\nDIGEST=$(jq -r '.layers[0].digest' manifest.json)\ncurl -I -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST\n\n# Step 5: Download the layer blob\ncurl -L -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST\n```\n\nThis example pulls the manifest and the first layer for the `ubuntu:latest` image on the `linux/amd64` platform. Repeat steps 4 and 5 for each digest in the `.layers[]` array in the manifest.\n", + "kind": "info", + "name": "pull", + "summary": "Pulling Images" + }, + { + "description": "Pushing an image involves uploading any image blobs (such as the config or layers), and then uploading the manifest that references those blobs.\n\nThis section outlines the basic steps to push an image using the registry API.\n\n1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/)\n\n2. [Check if the blob exists](#operation/CheckBlobExists) using a `HEAD` request for each blob digest.\n\n3. If the blob does not exist, [upload the blob](#operation/CompleteBlobUpload) using a monolithic `PUT` request:\n - First, [initiate the upload](#operation/InitiateBlobUpload) with `POST`.\n - Then [upload and complete](#operation/CompleteBlobUpload) with `PUT`.\n\n **Note**: Alternatively, you can upload the blob in multiple chunks by using `PATCH` requests to send each chunk, followed by a final `PUT` request to complete the upload. This is known as a [chunked upload](#operation/UploadBlobChunk) and is useful for large blobs or when resuming interrupted uploads.\n\n\n4. [Upload the image manifest](#operation/PutImageManifest) using a `PUT` request to associate the config and layers.\n\nThe following bash script example pushes a dummy config blob and manifest to `yourusername/helloworld:latest` on Docker Hub. You can replace `yourusername` with your Docker Hub username and `dckr_pat` with your Docker Hub personal access token.\n\n```bash\n#!/bin/bash\n\nUSERNAME=yourusername\nPASSWORD=dckr_pat\nREPO=yourusername/helloworld\nTAG=latest\nCONFIG=config.json\nMIME_TYPE=application/vnd.docker.container.image.v1+json\n\n# Step 1: Get a bearer token\nTOKEN=$(curl -s -u \"$USERNAME:$PASSWORD\" \\\n\"https://auth.docker.io/token?service=registry.docker.io\u0026scope=repository:$REPO:push,pull\" \\\n| jq -r .token)\n\n# Create a dummy config blob and compute its digest\necho '{\"architecture\":\"amd64\",\"os\":\"linux\",\"config\":{},\"rootfs\":{\"type\":\"layers\",\"diff_ids\":[]}}' \u003e $CONFIG\nDIGEST=\"sha256:$(sha256sum $CONFIG | awk '{print $1}')\"\n\n# Step 2: Check if the blob exists\nSTATUS=$(curl -s -o /dev/null -w \"%{http_code}\" -I \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/$REPO/blobs/$DIGEST)\n\nif [ \"$STATUS\" != \"200\" ]; then\n # Step 3: Upload blob using monolithic upload\n LOCATION=$(curl -sI -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/$REPO/blobs/uploads/ \\\n | grep -i Location | tr -d '\\r' | awk '{print $2}')\n\n curl -s -X PUT \"$LOCATION\u0026digest=$DIGEST\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary @$CONFIG\nfi\n\n# Step 4: Upload the manifest that references the config blob\nMANIFEST=$(cat \u003c\u003cEOF\n{\n \"schemaVersion\": 2,\n \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n \"config\": {\n \"mediaType\": \"$MIME_TYPE\",\n \"size\": $(stat -c%s $CONFIG),\n \"digest\": \"$DIGEST\"\n },\n \"layers\": []\n}\nEOF\n)\n\ncurl -s -X PUT \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/vnd.docker.distribution.manifest.v2+json\" \\\n -d \"$MANIFEST\" \\\n https://registry-1.docker.io/v2/$REPO/manifests/$TAG\n\necho \"Pushed image to $REPO:$TAG\"\n```\n\nThis example pushes a minimal image with no layers. To push a complete image, repeat steps 2–3 for each layer and include the layer digests in the `layers[]` field of the manifest.\n", + "kind": "info", + "name": "push", + "summary": "Pushing Images" + }, + { + "description": "Deleting an image involves removing its manifest by digest. You must first retrieve the manifest digest, then issue a `DELETE` request using that digest.\n\nOnly untagged manifests (or those not referenced by other tags or images) can be deleted. If a manifest is still referenced, the registry returns `403 Forbidden`.\n\n\u003e **Note**\n\u003e\n\u003e Manifest deletion operations may experience latency and could return a `500 Internal Server Error` during deletion. The system automatically retries the deletion in the background, so the manifest will eventually be removed. You do not need to manually retry the request.\n\nThis section outlines the basic steps to delete an image using the registry API.\n\n1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/).\n2. [Get the manifest](#operation/GetImageManifest) using the image's tag.\n3. Retrieve the `Docker-Content-Digest` header from the manifest response. This digest uniquely identifies the manifest.\n4. [Delete the manifest](#operation/DeleteImageManifest) using a `DELETE` request and the digest.\n\nThe following bash script example deletes the `latest` tag from `yourusername/helloworld` on Docker Hub. Replace `yourusername` with your Docker Hub username and `dckr_pat` with your Docker Hub personal access token.\n\n```bash\n#!/bin/bash\n\nUSERNAME=yourusername\nPASSWORD=dckr_pat\nREPO=yourusername/helloworld\nTAG=latest\n\n# Step 1: Get a bearer token\nTOKEN=$(curl -s -u \"$USERNAME:$PASSWORD\" \\\n \"https://auth.docker.io/token?service=registry.docker.io\u0026scope=repository:$REPO:pull,push,delete\" \\\n | jq -r .token)\n\n# Step 2 and 3: Get the manifest and extract the digest from response headers\nDIGEST=$(curl -sI -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/vnd.docker.distribution.manifest.v2+json\" \\\n https://registry-1.docker.io/v2/$REPO/manifests/$TAG \\\n | grep -i Docker-Content-Digest | tr -d '\\r' | awk '{print $2}')\n\necho \"Deleting manifest with digest: $DIGEST\"\n\n# Step 4: Delete the manifest by digest\ncurl -s -X DELETE \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://registry-1.docker.io/v2/$REPO/manifests/$DIGEST\n\necho \"Deleted image: $REPO@$DIGEST\"\n```\n\nThis example deletes the manifest for the `latest` tag. To fully delete all references to an image, ensure no other tags or referrers point to the same manifest digest.\n", + "kind": "info", + "name": "delete", + "summary": "Deleting Images" + } + ], + "title": "Registry", + "url": "/reference/api/registry/latest/", + "version": "2" + }, + { + "connection": "hosted", + "description": "HTTP+JSON API for managing Docker governance policies and rules.\n\n**Resource model.** An organization owns one or more policies. Each policy\ncontains a list of rules grouped into a single domain: either `network` or\n`filesystem`. A policy's domain is derived from its rule actions; mixing\ndomains within a single policy is not permitted.\n\n**Lifecycle.** Create a policy with CreatePolicy, then add rules with\nCreateRule. Rules can be updated in place with UpdateRule or removed with\nDeleteRule. Deleting all rules does not delete the policy itself.\n\n**Rule evaluation.** All rules in a policy are tested against every request.\n`deny` always wins: if any rule matches with `decision: deny`, the request\nis denied regardless of any `allow` rules.\n\n**Enforcement.** Organization policies take precedence over local sandbox\npolicies and cannot be overridden by individual users.\n\n**Propagation.** Policy changes take up to five minutes to reach developer\nmachines after being written.\n\nSee the [AI Governance documentation](https://docs.docker.com/ai/sandboxes/governance/)\nfor product documentation.\n", + "diagnostics": [], + "digest": "4f9f7d5cadd50f50ba01c30333846338283e1a95d2bf7dacada0ccabc84ad19c", + "exampleCount": 59, + "experimental": false, + "guides": [], + "id": "ai-governance", + "manual": "/manuals/ai/sandboxes/governance/", + "operations": [ + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies'", + "curlNotes": [], + "deprecated": null, + "description": "Returns a shallow summary of the organization's policies, one page at a time. The rule set is not included; use GetPolicy to fetch the full object.\n\nResults are paginated with an opaque cursor. Pass `page_size` to bound the page; if more policies remain, the response includes a non-null `next_page_token` to pass as `page_token` on the next request. Iterate until `next_page_token` is `null`. Treat the token as opaque; do not parse or construct it.\n", + "id": "listPolicies", + "line": 56, + "method": "GET", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of policies to return. Defaults to 100 if omitted or zero. The server caps values above 100 at 100.\n", + "in": "query", + "name": "page_size", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/parameters/0", + "required": false, + "schema": { + "default": 100, + "minimum": 0, + "type": "integer" + } + }, + { + "description": "Opaque cursor from a previous response's `next_page_token`. Omit to fetch the first page.\n", + "in": "query", + "name": "page_token", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/parameters/1", + "required": false, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get", + "raw": { + "description": "Returns a shallow summary of the organization's policies, one page at a time. The rule set is not included; use GetPolicy to fetch the full object.\n\nResults are paginated with an opaque cursor. Pass `page_size` to bound the page; if more policies remain, the response includes a non-null `next_page_token` to pass as `page_token` on the next request. Iterate until `next_page_token` is `null`. Treat the token as opaque; do not parse or construct it.\n", + "operationId": "listPolicies", + "parameters": [ + { + "description": "Maximum number of policies to return. Defaults to 100 if omitted or zero. The server caps values above 100 at 100.\n", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "default": 100, + "minimum": 0, + "type": "integer" + } + }, + { + "description": "Opaque cursor from a previous response's `next_page_token`. Omit to fetch the first page.\n", + "in": "query", + "name": "page_token", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "data": [ + { + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "type": "allowlist_v0", + "updated_at": "2026-04-22T00:00:00Z" + } + ], + "next_page_token": "AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ" + } + } + }, + "schema": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/PolicySummary" + }, + "type": "array" + }, + "next_page_token": { + "description": "The opaque cursor for the next page, or `null` on the last page.\n", + "example": "AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "data", + "next_page_token" + ], + "type": "object" + } + } + }, + "description": "Object wrapping an array of policy summaries under `data` and a `next_page_token`, which is null on the last page. Rule sets are not included; use GetPolicy to fetch a full policy." + }, + "400": { + "$ref": "#/components/responses/InvalidArgument" + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/PermissionDenied" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "List policies", + "tags": [ + "policies" + ] + }, + "references": [ + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/InvalidArgument", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/PermissionDenied", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/PolicySummary", + "url": "/reference/api/ai-governance/latest/schemas/PolicySummary/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "List policies", + "tags": [ + "policies" + ], + "url": "/reference/api/ai-governance/latest/operations/listPolicies/", + "variants": [ + { + "description": "Object wrapping an array of policy summaries under `data` and a `next_page_token`, which is null on the last page. Rule sets are not included; use GetPolicy to fetch a full policy.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"data\": [\n {\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research — hardened\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"type\": \"allowlist_v0\",\n \"updated_at\": \"2026-04-22T00:00:00Z\"\n }\n ],\n \"next_page_token\": \"AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ\"\n}", + "value": { + "data": [ + { + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "type": "allowlist_v0", + "updated_at": "2026-04-22T00:00:00Z" + } + ], + "next_page_token": "AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/200/content/application~1json", + "required": null, + "schema": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/PolicySummary" + }, + "type": "array" + }, + "next_page_token": { + "description": "The opaque cursor for the next page, or `null` on the last page.\n", + "example": "AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "data", + "next_page_token" + ], + "type": "object" + }, + "status": "200" + }, + { + "description": "Bad request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"invalid_argument\",\n \"message\": \"name is required\"\n }\n}", + "value": { + "error": { + "code": "invalid_argument", + "message": "name is required" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "400" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, or the org is not entitled to use governance.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/get/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"name\": \"Security Research — hardened\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n }\n}' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies'", + "curlNotes": [], + "deprecated": null, + "description": "Creates a new policy with an empty rule set. Rules are added separately via the rules sub-resource.\n", + "id": "createPolicy", + "line": 131, + "method": "POST", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post", + "raw": { + "description": "Creates a new policy with an empty rule set. Rules are added separately via the rules sub-resource.\n", + "operationId": "createPolicy", + "requestBody": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "name": "Security Research — hardened", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreatePolicyRequest" + } + } + }, + "description": "Policy name and optional scope.", + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + }, + "description": "Policy created. Returns the new policy without its rule set." + }, + "400": { + "$ref": "#/components/responses/InvalidArgument" + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Create policy", + "tags": [ + "policies" + ] + }, + "references": [ + { + "ref": "#/components/responses/Conflict", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/InvalidArgument", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/CreatePolicyRequest", + "url": "/reference/api/ai-governance/latest/schemas/CreatePolicyRequest/" + }, + { + "ref": "#/components/schemas/Policy", + "url": "/reference/api/ai-governance/latest/schemas/Policy/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreatePolicyRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Create policy", + "tags": [ + "policies" + ], + "url": "/reference/api/ai-governance/latest/operations/createPolicy/", + "variants": [ + { + "description": "Policy name and optional scope.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"name\": \"Security Research — hardened\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n }\n}", + "value": { + "name": "Security Research — hardened", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreatePolicyRequest" + }, + "status": "" + }, + { + "description": "Policy created. Returns the new policy without its rule set.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research — hardened\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"updated_at\": \"2026-04-22T00:00:00Z\"\n}", + "value": { + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Policy" + }, + "status": "201" + }, + { + "description": "Bad request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"invalid_argument\",\n \"message\": \"name is required\"\n }\n}", + "value": { + "error": { + "code": "invalid_argument", + "message": "name is required" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "400" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, the org is not entitled to use governance (`permission_denied`), or a creation limit has been reached (`limit_exceeded`): the org already has the maximum number of policies, or the policy already has the maximum number of rules.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "limit_exceeded", + "text": "{\n \"error\": {\n \"code\": \"limit_exceeded\",\n \"message\": \"organization has reached the maximum of 100 policies\"\n }\n}", + "value": { + "error": { + "code": "limit_exceeded", + "message": "organization has reached the maximum of 100 policies" + } + } + }, + { + "language": "json", + "name": "permission_denied", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"conflict\",\n \"message\": \"policy name already in use\"\n }\n}", + "value": { + "error": { + "code": "conflict", + "message": "policy name already in use" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies/post/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Returns the full policy including its `allowlist_v0` rule set.", + "id": "getPolicy", + "line": 185, + "method": "GET", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get", + "raw": { + "description": "Returns the full policy including its `allowlist_v0` rule set.", + "operationId": "getPolicy", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + }, + "description": "Full policy including its `allowlist_v0` rule set." + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/PermissionDenied" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Get policy", + "tags": [ + "policies" + ] + }, + "references": [ + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/PermissionDenied", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/Policy", + "url": "/reference/api/ai-governance/latest/schemas/Policy/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Get policy", + "tags": [ + "policies" + ], + "url": "/reference/api/ai-governance/latest/operations/getPolicy/", + "variants": [ + { + "description": "Full policy including its `allowlist_v0` rule set.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"allowlist_v0\": {\n \"domain\": \"network\",\n \"rules\": [\n {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n ]\n },\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research — hardened\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"updated_at\": \"2026-04-22T00:00:00Z\"\n}", + "value": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Policy" + }, + "status": "200" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, or the org is not entitled to use governance.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/get/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Permanently deletes the policy and its rule set. Returns the deleted\npolicy as a courtesy; its `updated_at` is unchanged by the deletion.\nChanges may take up to five minutes to reach developer machines.\n", + "id": "deletePolicy", + "line": 309, + "method": "DELETE", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete", + "raw": { + "description": "Permanently deletes the policy and its rule set. Returns the deleted\npolicy as a courtesy; its `updated_at` is unchanged by the deletion.\nChanges may take up to five minutes to reach developer machines.\n", + "operationId": "deletePolicy", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "deleted": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DeletePolicyResponse" + } + } + }, + "description": "Policy deleted, returns the deleted policy." + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/PermissionDenied" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Delete policy", + "tags": [ + "policies" + ] + }, + "references": [ + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/PermissionDenied", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/DeletePolicyResponse", + "url": "/reference/api/ai-governance/latest/schemas/DeletePolicyResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Delete policy", + "tags": [ + "policies" + ], + "url": "/reference/api/ai-governance/latest/operations/deletePolicy/", + "variants": [ + { + "description": "Policy deleted, returns the deleted policy.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"deleted\": {\n \"allowlist_v0\": {\n \"domain\": \"network\",\n \"rules\": [\n {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n ]\n },\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research — hardened\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"updated_at\": \"2026-04-22T00:00:00Z\"\n }\n}", + "value": { + "deleted": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/DeletePolicyResponse" + }, + "status": "200" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, or the org is not entitled to use governance.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/delete/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"name\": \"Security Research\"\n}' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Partially updates a policy's metadata. Only fields present in the\nrequest body are updated; absent fields are left unchanged. The `scope`\nobject is patched per sub-field: sending `teams` replaces that list,\nwhile an omitted sub-field is left untouched and an empty list clears\nit (org-wide).\n\nThe rule set is not modified here. Use the rule endpoints for that.\nAt least one field must be present. Returns the policy in both its old\nand new states. Changes may take up to five minutes to reach developer\nmachines.\n", + "id": "updatePolicy", + "line": 223, + "method": "PATCH", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch", + "raw": { + "description": "Partially updates a policy's metadata. Only fields present in the\nrequest body are updated; absent fields are left unchanged. The `scope`\nobject is patched per sub-field: sending `teams` replaces that list,\nwhile an omitted sub-field is left untouched and an empty list clears\nit (org-wide).\n\nThe rule set is not modified here. Use the rule endpoints for that.\nAt least one field must be present. Returns the policy in both its old\nand new states. Changes may take up to five minutes to reach developer\nmachines.\n", + "operationId": "updatePolicy", + "requestBody": { + "content": { + "application/json": { + "examples": { + "rename": { + "summary": "Rename the policy", + "value": { + "name": "Security Research" + } + }, + "scope": { + "summary": "Restrict to a team", + "value": { + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdatePolicyRequest" + } + } + }, + "description": "Fields to update. Absent fields are left unchanged.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "new": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T10:00:00Z" + }, + "old": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdatePolicyResponse" + } + } + }, + "description": "Policy updated, returns old and new states." + }, + "400": { + "$ref": "#/components/responses/InvalidArgument" + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Update policy", + "tags": [ + "policies" + ] + }, + "references": [ + { + "ref": "#/components/responses/Conflict", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/InvalidArgument", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/UpdatePolicyRequest", + "url": "/reference/api/ai-governance/latest/schemas/UpdatePolicyRequest/" + }, + { + "ref": "#/components/schemas/UpdatePolicyResponse", + "url": "/reference/api/ai-governance/latest/schemas/UpdatePolicyResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/UpdatePolicyRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Update policy", + "tags": [ + "policies" + ], + "url": "/reference/api/ai-governance/latest/operations/updatePolicy/", + "variants": [ + { + "description": "Fields to update. Absent fields are left unchanged.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "rename", + "text": "{\n \"name\": \"Security Research\"\n}", + "value": { + "name": "Security Research" + } + }, + { + "language": "json", + "name": "scope", + "text": "{\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n }\n}", + "value": { + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/UpdatePolicyRequest" + }, + "status": "" + }, + { + "description": "Policy updated, returns old and new states.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"new\": {\n \"allowlist_v0\": {\n \"domain\": \"network\",\n \"rules\": [\n {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n ]\n },\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"updated_at\": \"2026-04-22T10:00:00Z\"\n },\n \"old\": {\n \"allowlist_v0\": {\n \"domain\": \"network\",\n \"rules\": [\n {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n ]\n },\n \"created_at\": \"2026-04-22T00:00:00Z\",\n \"id\": \"pol_06evsmp24r1pg71cm8500546pkbn\",\n \"name\": \"Security Research — hardened\",\n \"org\": \"my-org\",\n \"scope\": {\n \"teams\": [\n \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n ]\n },\n \"updated_at\": \"2026-04-22T00:00:00Z\"\n }\n}", + "value": { + "new": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T10:00:00Z" + }, + "old": { + "allowlist_v0": { + "domain": "network", + "rules": [ + { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + ] + }, + "created_at": "2026-04-22T00:00:00Z", + "id": "pol_06evsmp24r1pg71cm8500546pkbn", + "name": "Security Research — hardened", + "org": "my-org", + "scope": { + "teams": [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + }, + "updated_at": "2026-04-22T00:00:00Z" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/UpdatePolicyResponse" + }, + "status": "200" + }, + { + "description": "Bad request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"invalid_argument\",\n \"message\": \"name is required\"\n }\n}", + "value": { + "error": { + "code": "invalid_argument", + "message": "name is required" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "400" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, the org is not entitled to use governance (`permission_denied`), or a creation limit has been reached (`limit_exceeded`): the org already has the maximum number of policies, or the policy already has the maximum number of rules.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "limit_exceeded", + "text": "{\n \"error\": {\n \"code\": \"limit_exceeded\",\n \"message\": \"organization has reached the maximum of 100 policies\"\n }\n}", + "value": { + "error": { + "code": "limit_exceeded", + "message": "organization has reached the maximum of 100 policies" + } + } + }, + { + "language": "json", + "name": "permission_denied", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"conflict\",\n \"message\": \"policy name already in use\"\n }\n}", + "value": { + "error": { + "code": "conflict", + "message": "policy name already in use" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/patch/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"actions\": [\n \"read\",\n \"write\"\n ],\n \"decision\": \"allow\",\n \"name\": \"allow data directory\",\n \"resources\": [\n \"/data\"\n ]\n}' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e/rules'", + "curlNotes": [], + "deprecated": null, + "description": "Adds a rule to the policy's rule set. All rules in a policy must share\nthe same domain (`network`, which includes HTTP, or `filesystem`);\nmixing domains is rejected. A single rule cannot mix L4 network and L7\nHTTP actions.\n\n**Network** actions: `connect:tcp`, `connect:udp`. Resources are\nhostnames (for example, `example.com`), wildcard subdomains (`*.example.com`\nfor one level, `**.example.com` for any depth), hostnames with an optional\nport (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation\n(for example, `10.0.0.0/8` or `2001:db8::/32`).\n\n**Filesystem** actions: `read`, `write`. Resources are paths (for example,\n`/data`). Use `*` to match within a single path segment and `**` to match\nrecursively across segments (for example, `/data/**`).\n\n**HTTP** actions identify request methods, such as `request:get` and\n`request:post`. Use `http_resources` to identify the host, optional port,\nand absolute path glob. HTTP rules must not supply `resources`.\n\nChanges may take up to five minutes to reach developer machines.\n", + "id": "createRule", + "line": 356, + "method": "POST", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/parameters/1", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}/rules", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post", + "raw": { + "description": "Adds a rule to the policy's rule set. All rules in a policy must share\nthe same domain (`network`, which includes HTTP, or `filesystem`);\nmixing domains is rejected. A single rule cannot mix L4 network and L7\nHTTP actions.\n\n**Network** actions: `connect:tcp`, `connect:udp`. Resources are\nhostnames (for example, `example.com`), wildcard subdomains (`*.example.com`\nfor one level, `**.example.com` for any depth), hostnames with an optional\nport (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation\n(for example, `10.0.0.0/8` or `2001:db8::/32`).\n\n**Filesystem** actions: `read`, `write`. Resources are paths (for example,\n`/data`). Use `*` to match within a single path segment and `**` to match\nrecursively across segments (for example, `/data/**`).\n\n**HTTP** actions identify request methods, such as `request:get` and\n`request:post`. Use `http_resources` to identify the host, optional port,\nand absolute path glob. HTTP rules must not supply `resources`.\n\nChanges may take up to five minutes to reach developer machines.\n", + "operationId": "createRule", + "requestBody": { + "content": { + "application/json": { + "examples": { + "filesystem": { + "summary": "Filesystem rule", + "value": { + "actions": [ + "read", + "write" + ], + "decision": "allow", + "name": "allow data directory", + "resources": [ + "/data" + ] + } + }, + "http": { + "summary": "HTTP rule", + "value": { + "actions": [ + "request:get", + "request:head" + ], + "decision": "allow", + "http_resources": [ + { + "host": "api.github.com", + "path": "/repos/docker/**", + "port": 443 + } + ], + "name": "read GitHub repositories" + } + }, + "network": { + "summary": "Network rule", + "value": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateRuleRequest" + } + } + }, + "description": "Rule definition including actions, matching resources, and decision.", + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "examples": { + "filesystem": { + "summary": "Filesystem rule", + "value": { + "actions": [ + "read", + "write" + ], + "decision": "allow", + "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob", + "name": "allow data directory", + "resources": [ + "/data" + ] + } + }, + "http": { + "summary": "HTTP rule", + "value": { + "actions": [ + "request:get", + "request:head" + ], + "decision": "allow", + "http_resources": [ + { + "host": "api.github.com", + "path": "/repos/docker/**", + "port": 443 + } + ], + "id": "rule_08gxuos1lo3rfum2c0pmgcz09lpc", + "name": "read GitHub repositories" + } + }, + "network": { + "summary": "Network rule", + "value": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/Rule" + } + } + }, + "description": "Rule created and added to the policy's rule set." + }, + "400": { + "$ref": "#/components/responses/InvalidArgument" + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Create rule", + "tags": [ + "rules" + ] + }, + "references": [ + { + "ref": "#/components/responses/Conflict", + "url": null + }, + { + "ref": "#/components/responses/Forbidden", + "url": null + }, + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/InvalidArgument", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/CreateRuleRequest", + "url": "/reference/api/ai-governance/latest/schemas/CreateRuleRequest/" + }, + { + "ref": "#/components/schemas/Rule", + "url": "/reference/api/ai-governance/latest/schemas/Rule/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateRuleRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Create rule", + "tags": [ + "rules" + ], + "url": "/reference/api/ai-governance/latest/operations/createRule/", + "variants": [ + { + "description": "Rule definition including actions, matching resources, and decision.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "filesystem", + "text": "{\n \"actions\": [\n \"read\",\n \"write\"\n ],\n \"decision\": \"allow\",\n \"name\": \"allow data directory\",\n \"resources\": [\n \"/data\"\n ]\n}", + "value": { + "actions": [ + "read", + "write" + ], + "decision": "allow", + "name": "allow data directory", + "resources": [ + "/data" + ] + } + }, + { + "language": "json", + "name": "http", + "text": "{\n \"actions\": [\n \"request:get\",\n \"request:head\"\n ],\n \"decision\": \"allow\",\n \"http_resources\": [\n {\n \"host\": \"api.github.com\",\n \"path\": \"/repos/docker/**\",\n \"port\": 443\n }\n ],\n \"name\": \"read GitHub repositories\"\n}", + "value": { + "actions": [ + "request:get", + "request:head" + ], + "decision": "allow", + "http_resources": [ + { + "host": "api.github.com", + "path": "/repos/docker/**", + "port": 443 + } + ], + "name": "read GitHub repositories" + } + }, + { + "language": "json", + "name": "network", + "text": "{\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n}", + "value": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateRuleRequest" + }, + "status": "" + }, + { + "description": "Rule created and added to the policy's rule set.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "filesystem", + "text": "{\n \"actions\": [\n \"read\",\n \"write\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_07fwtnr0kn2qetl1b9olfbyz8kob\",\n \"name\": \"allow data directory\",\n \"resources\": [\n \"/data\"\n ]\n}", + "value": { + "actions": [ + "read", + "write" + ], + "decision": "allow", + "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob", + "name": "allow data directory", + "resources": [ + "/data" + ] + } + }, + { + "language": "json", + "name": "http", + "text": "{\n \"actions\": [\n \"request:get\",\n \"request:head\"\n ],\n \"decision\": \"allow\",\n \"http_resources\": [\n {\n \"host\": \"api.github.com\",\n \"path\": \"/repos/docker/**\",\n \"port\": 443\n }\n ],\n \"id\": \"rule_08gxuos1lo3rfum2c0pmgcz09lpc\",\n \"name\": \"read GitHub repositories\"\n}", + "value": { + "actions": [ + "request:get", + "request:head" + ], + "decision": "allow", + "http_resources": [ + { + "host": "api.github.com", + "path": "/repos/docker/**", + "port": 443 + } + ], + "id": "rule_08gxuos1lo3rfum2c0pmgcz09lpc", + "name": "read GitHub repositories" + } + }, + { + "language": "json", + "name": "network", + "text": "{\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n}", + "value": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Rule" + }, + "status": "201" + }, + { + "description": "Bad request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"invalid_argument\",\n \"message\": \"name is required\"\n }\n}", + "value": { + "error": { + "code": "invalid_argument", + "message": "name is required" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "400" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, the org is not entitled to use governance (`permission_denied`), or a creation limit has been reached (`limit_exceeded`): the org already has the maximum number of policies, or the policy already has the maximum number of rules.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "limit_exceeded", + "text": "{\n \"error\": {\n \"code\": \"limit_exceeded\",\n \"message\": \"organization has reached the maximum of 100 policies\"\n }\n}", + "value": { + "error": { + "code": "limit_exceeded", + "message": "organization has reached the maximum of 100 policies" + } + } + }, + { + "language": "json", + "name": "permission_denied", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"conflict\",\n \"message\": \"policy name already in use\"\n }\n}", + "value": { + "error": { + "code": "conflict", + "message": "policy name already in use" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules/post/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e/rules/\u003cRULE_ID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Deletes a rule from the policy. Returns the deleted rule. Changes may\ntake up to five minutes to reach developer machines.\n", + "id": "deleteRule", + "line": 526, + "method": "DELETE", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique rule identifier within the policy.", + "examples": { + "default": { + "value": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna" + } + }, + "in": "path", + "name": "rule_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/2", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}/rules/{rule_id}", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete", + "raw": { + "description": "Deletes a rule from the policy. Returns the deleted rule. Changes may\ntake up to five minutes to reach developer machines.\n", + "operationId": "deleteRule", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "deleted": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DeleteRuleResponse" + } + } + }, + "description": "Rule deleted, returns the deleted rule." + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/PermissionDenied" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Delete rule", + "tags": [ + "rules" + ] + }, + "references": [ + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/PermissionDenied", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/DeleteRuleResponse", + "url": "/reference/api/ai-governance/latest/schemas/DeleteRuleResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Delete rule", + "tags": [ + "rules" + ], + "url": "/reference/api/ai-governance/latest/operations/deleteRule/", + "variants": [ + { + "description": "Rule deleted, returns the deleted rule.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"deleted\": {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n}", + "value": { + "deleted": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/DeleteRuleResponse" + }, + "status": "200" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, or the org is not entitled to use governance.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/delete/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"resources\": [\n \"research.mitre.org\"\n ]\n}' \\\n 'https://hub.docker.com/v2/orgs/\u003cORG_NAME\u003e/governance/policies/\u003cPOLICY_ID\u003e/rules/\u003cRULE_ID\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "Partially updates a rule. Only fields present in the request body are\nupdated; absent fields are left unchanged. Returns the rule in both its\nold and new states.\n\nChanging `actions` across domains (for example, from network actions to\nfilesystem actions) is rejected while other rules remain in the policy.\nWhen changing a rule between L4 network and L7 HTTP, supply the matching\n`resources` or `http_resources` in the same request. Changes may take up\nto five minutes to reach developer machines.\n", + "id": "updateRule", + "line": 466, + "method": "PATCH", + "parameters": [ + { + "description": "Docker Hub organization name.", + "examples": { + "default": { + "value": "my-org" + } + }, + "in": "path", + "name": "org_name", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique policy identifier.", + "examples": { + "default": { + "value": "pol_06evsmp24r1pg71cm8500546pkbn" + } + }, + "in": "path", + "name": "policy_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Unique rule identifier within the policy.", + "examples": { + "default": { + "value": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna" + } + }, + "in": "path", + "name": "rule_id", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/parameters/2", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/orgs/{org_name}/governance/policies/{policy_id}/rules/{rule_id}", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch", + "raw": { + "description": "Partially updates a rule. Only fields present in the request body are\nupdated; absent fields are left unchanged. Returns the rule in both its\nold and new states.\n\nChanging `actions` across domains (for example, from network actions to\nfilesystem actions) is rejected while other rules remain in the policy.\nWhen changing a rule between L4 network and L7 HTTP, supply the matching\n`resources` or `http_resources` in the same request. Changes may take up\nto five minutes to reach developer machines.\n", + "operationId": "updateRule", + "requestBody": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "resources": [ + "research.mitre.org" + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateRuleRequest" + } + } + }, + "description": "Fields to update. Absent fields are left unchanged.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "default": { + "value": { + "new": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org" + ] + }, + "old": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateRuleResponse" + } + } + }, + "description": "Rule updated, returns old and new states." + }, + "400": { + "$ref": "#/components/responses/InvalidArgument" + }, + "401": { + "$ref": "#/components/responses/Unauthenticated" + }, + "403": { + "$ref": "#/components/responses/PermissionDenied" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + }, + "summary": "Update rule", + "tags": [ + "rules" + ] + }, + "references": [ + { + "ref": "#/components/responses/Conflict", + "url": null + }, + { + "ref": "#/components/responses/InternalError", + "url": null + }, + { + "ref": "#/components/responses/InvalidArgument", + "url": null + }, + { + "ref": "#/components/responses/NotFound", + "url": null + }, + { + "ref": "#/components/responses/PermissionDenied", + "url": null + }, + { + "ref": "#/components/responses/Unauthenticated", + "url": null + }, + { + "ref": "#/components/schemas/UpdateRuleRequest", + "url": "/reference/api/ai-governance/latest/schemas/UpdateRuleRequest/" + }, + { + "ref": "#/components/schemas/UpdateRuleResponse", + "url": "/reference/api/ai-governance/latest/schemas/UpdateRuleResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/UpdateRuleRequest" + }, + "security": [ + { + "bearerAuth": [] + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "summary": "Update rule", + "tags": [ + "rules" + ], + "url": "/reference/api/ai-governance/latest/operations/updateRule/", + "variants": [ + { + "description": "Fields to update. Absent fields are left unchanged.", + "direction": "Request", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"resources\": [\n \"research.mitre.org\"\n ]\n}", + "value": { + "resources": [ + "research.mitre.org" + ] + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/UpdateRuleRequest" + }, + "status": "" + }, + { + "description": "Rule updated, returns old and new states.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"new\": {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\"\n ]\n },\n \"old\": {\n \"actions\": [\n \"connect:tcp\",\n \"connect:udp\"\n ],\n \"decision\": \"allow\",\n \"id\": \"rule_06evsm9qjm1pdsk0a8nkfaxy7jna\",\n \"name\": \"allow research mirrors\",\n \"resources\": [\n \"research.mitre.org\",\n \"cve.mitre.org\"\n ]\n }\n}", + "value": { + "new": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org" + ] + }, + "old": { + "actions": [ + "connect:tcp", + "connect:udp" + ], + "decision": "allow", + "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", + "name": "allow research mirrors", + "resources": [ + "research.mitre.org", + "cve.mitre.org" + ] + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/UpdateRuleResponse" + }, + "status": "200" + }, + { + "description": "Bad request", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"invalid_argument\",\n \"message\": \"name is required\"\n }\n}", + "value": { + "error": { + "code": "invalid_argument", + "message": "name is required" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/400/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "400" + }, + { + "description": "Missing or invalid credentials", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"unauthenticated\",\n \"message\": \"unauthenticated\"\n }\n}", + "value": { + "error": { + "code": "unauthenticated", + "message": "unauthenticated" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/401/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "401" + }, + { + "description": "Caller lacks the required permission for this org, or the org is not entitled to use governance.\n", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"permission_denied\",\n \"message\": \"permission denied\"\n }\n}", + "value": { + "error": { + "code": "permission_denied", + "message": "permission denied" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/403/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "403" + }, + { + "description": "Not found", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"policy not found\"\n }\n}", + "value": { + "error": { + "code": "not_found", + "message": "policy not found" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "Conflict", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"conflict\",\n \"message\": \"policy name already in use\"\n }\n}", + "value": { + "error": { + "code": "conflict", + "message": "policy name already in use" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "Internal server error", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "default", + "text": "{\n \"error\": {\n \"code\": \"internal\",\n \"message\": \"internal error\"\n }\n}", + "value": { + "error": { + "code": "internal", + "message": "internal error" + } + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}~1rules~1{rule_id}/patch/responses/500/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "500" + } + ] + } + ], + "owner": "docker/governor-services", + "product": "ai-governance", + "schemaCount": 45, + "schemaURLs": { + "#/components/schemas/AllowlistV0": "/reference/api/ai-governance/latest/schemas/AllowlistV0/", + "#/components/schemas/CedarV1Policy": "/reference/api/ai-governance/latest/schemas/CedarV1Policy/", + "#/components/schemas/CreatePolicyRequest": "/reference/api/ai-governance/latest/schemas/CreatePolicyRequest/", + "#/components/schemas/CreateRuleRequest": "/reference/api/ai-governance/latest/schemas/CreateRuleRequest/", + "#/components/schemas/DeletePolicyResponse": "/reference/api/ai-governance/latest/schemas/DeletePolicyResponse/", + "#/components/schemas/DeleteRuleResponse": "/reference/api/ai-governance/latest/schemas/DeleteRuleResponse/", + "#/components/schemas/Error": "/reference/api/ai-governance/latest/schemas/Error/", + "#/components/schemas/HTTPResource": "/reference/api/ai-governance/latest/schemas/HTTPResource/", + "#/components/schemas/HTTPResources": "/reference/api/ai-governance/latest/schemas/HTTPResources/", + "#/components/schemas/Policy": "/reference/api/ai-governance/latest/schemas/Policy/", + "#/components/schemas/PolicySummary": "/reference/api/ai-governance/latest/schemas/PolicySummary/", + "#/components/schemas/Rule": "/reference/api/ai-governance/latest/schemas/Rule/", + "#/components/schemas/RuleActions": "/reference/api/ai-governance/latest/schemas/RuleActions/", + "#/components/schemas/RuleDecision": "/reference/api/ai-governance/latest/schemas/RuleDecision/", + "#/components/schemas/RuleResources": "/reference/api/ai-governance/latest/schemas/RuleResources/", + "#/components/schemas/Scope": "/reference/api/ai-governance/latest/schemas/Scope/", + "#/components/schemas/ScopePatch": "/reference/api/ai-governance/latest/schemas/ScopePatch/", + "#/components/schemas/UpdatePolicyRequest": "/reference/api/ai-governance/latest/schemas/UpdatePolicyRequest/", + "#/components/schemas/UpdatePolicyResponse": "/reference/api/ai-governance/latest/schemas/UpdatePolicyResponse/", + "#/components/schemas/UpdateRuleRequest": "/reference/api/ai-governance/latest/schemas/UpdateRuleRequest/", + "#/components/schemas/UpdateRuleResponse": "/reference/api/ai-governance/latest/schemas/UpdateRuleResponse/" + }, + "schemas": [ + { + "name": "AllowlistV0", + "pointer": "/components/schemas/AllowlistV0", + "schema": { + "description": "Network, HTTP, or filesystem allowlist containing a list of rules. Present on\nPolicy when `PolicySummary.type` is `allowlist_v0`; omitted when the\npolicy has no rules yet. All rules in an allowlist share the same domain.\nAll rules are evaluated on every request: `deny` always wins over `allow`.\n", + "properties": { + "domain": { + "description": "The access-control domain shared by all rules in this allowlist. Derived from rule actions: network actions (`connect:tcp`, `connect:udp`) produce `network`; filesystem actions (`read`, `write`) produce `filesystem`. Present when `rules` is non-empty; absent when the allowlist has no rules.\n", + "enum": [ + "network", + "filesystem" + ], + "examples": [ + "network" + ], + "type": "string" + }, + "rules": { + "items": { + "$ref": "#/components/schemas/Rule" + }, + "type": "array" + } + }, + "required": [ + "rules" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/AllowlistV0/" + }, + { + "name": "CedarV1Policy", + "pointer": "/components/schemas/CedarV1Policy", + "schema": { + "description": "Cedar:V1 policy body. Present on `Policy` when `PolicySummary.type` is `cedar_v1`. Cedar policies encode their rules directly in `text` rather than in the rules sub-resource; the rules endpoints are not available for Cedar policies.\n", + "properties": { + "schema_url": { + "description": "URL of the Cedar schema this policy was authored against. The evaluator looks up the schema by this URL from its built-in registry. Use `https://schemas.docker.com/policy/cedar/v1/mcp/v0` for MCP policies.\n", + "examples": [ + "https://schemas.docker.com/policy/cedar/v1/mcp/v0" + ], + "type": "string" + }, + "text": { + "description": "One or more Cedar `permit` or `forbid` statements. Must be syntactically valid Cedar and must not carry an `@id` annotation (IDs are server-assigned).\n", + "examples": [ + "permit(principal, action == MCP::Action::\"call_tool\", resource is MCP::Tool);" + ], + "type": "string" + } + }, + "required": [ + "text", + "schema_url" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/CedarV1Policy/" + }, + { + "name": "CreatePolicyRequest", + "pointer": "/components/schemas/CreatePolicyRequest", + "schema": { + "description": "Fields required to create a new policy. Omitting `cedar_v1` creates an `allowlist_v0` policy with an empty rule set. Supplying `cedar_v1` creates a Cedar:V1 policy; rules are embedded in the Cedar text rather than managed via the rules sub-resource.\n", + "properties": { + "cedar_v1": { + "$ref": "#/components/schemas/CedarV1Policy" + }, + "name": { + "description": "Policy name, unique within the organization.", + "examples": [ + "Security Research — hardened" + ], + "type": "string" + }, + "scope": { + "$ref": "#/components/schemas/Scope" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/CreatePolicyRequest/" + }, + { + "name": "CreateRuleRequest", + "pointer": "/components/schemas/CreateRuleRequest", + "schema": { + "description": "Fields required to create a new rule within a policy's rule set.", + "oneOf": [ + { + "required": [ + "resources" + ], + "type": "object" + }, + { + "required": [ + "http_resources" + ], + "type": "object" + } + ], + "properties": { + "actions": { + "$ref": "#/components/schemas/RuleActions" + }, + "decision": { + "$ref": "#/components/schemas/RuleDecision" + }, + "http_resources": { + "$ref": "#/components/schemas/HTTPResources" + }, + "name": { + "description": "Human-readable label for the rule.", + "examples": [ + "allow research mirrors" + ], + "type": "string" + }, + "resources": { + "$ref": "#/components/schemas/RuleResources" + } + }, + "required": [ + "name", + "actions", + "decision" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/CreateRuleRequest/" + }, + { + "name": "DeletePolicyResponse", + "pointer": "/components/schemas/DeletePolicyResponse", + "schema": { + "description": "The full deleted policy.", + "properties": { + "deleted": { + "$ref": "#/components/schemas/Policy" + } + }, + "required": [ + "deleted" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/DeletePolicyResponse/" + }, + { + "name": "DeleteRuleResponse", + "pointer": "/components/schemas/DeleteRuleResponse", + "schema": { + "description": "The deleted rule.", + "properties": { + "deleted": { + "$ref": "#/components/schemas/Rule" + } + }, + "required": [ + "deleted" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/DeleteRuleResponse/" + }, + { + "name": "Error", + "pointer": "/components/schemas/Error", + "schema": { + "description": "Error envelope returned on all non-2xx responses.", + "properties": { + "error": { + "description": "Error detail.", + "examples": [ + { + "code": "not_found", + "message": "policy not found" + } + ], + "properties": { + "code": { + "description": "Machine-readable error code. `not_found`: the requested resource does not exist, the org does not exist, or the caller is not a member of the organization (the organization's existence is not revealed to callers who cannot access it). `conflict`: a resource with the same name already exists. `invalid_argument`: the request body is malformed or fails validation. `unauthenticated`: missing or invalid credentials. `permission_denied`: the org is not entitled to use governance. `limit_exceeded`: the org has reached its maximum number of policies, or the policy has reached its maximum number of rules. `unimplemented`: the endpoint or feature is not yet available. `internal`: unexpected server error.\n", + "enum": [ + "not_found", + "conflict", + "invalid_argument", + "unauthenticated", + "permission_denied", + "limit_exceeded", + "unimplemented", + "internal" + ], + "type": "string" + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + } + }, + "required": [ + "error" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/Error/" + }, + { + "name": "HTTPResource", + "pointer": "/components/schemas/HTTPResource", + "schema": { + "properties": { + "host": { + "description": "Domain name or domain glob without a URL scheme or port. Use the separate `port` field to restrict the target to one port.\n", + "examples": [ + "api.github.com", + "*.example.com" + ], + "minLength": 1, + "type": "string" + }, + "path": { + "description": "Absolute HTTP path glob. `*` matches one segment and `**` matches any depth, including the bare path.\n", + "examples": [ + "/repos/docker/**" + ], + "pattern": "^/", + "type": "string" + }, + "port": { + "description": "Optional destination port. Omit it to match every port.", + "examples": [ + 443 + ], + "maximum": 65535, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "host", + "path" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/HTTPResource/" + }, + { + "name": "HTTPResources", + "pointer": "/components/schemas/HTTPResources", + "schema": { + "description": "HTTP request targets. Required for HTTP rules and forbidden for network and filesystem rules. A request matches when any target matches.\n", + "items": { + "$ref": "#/components/schemas/HTTPResource" + }, + "minItems": 1, + "type": "array" + }, + "url": "/reference/api/ai-governance/latest/schemas/HTTPResources/" + }, + { + "name": "Policy", + "pointer": "/components/schemas/Policy", + "schema": { + "description": "Full policy representation. Exactly one of `allowlist_v0` or `cedar_v1` is present, depending on the policy type.\n", + "properties": { + "allowlist_v0": { + "$ref": "#/components/schemas/AllowlistV0" + }, + "cedar_v1": { + "$ref": "#/components/schemas/CedarV1Policy" + }, + "created_at": { + "examples": [ + "2026-04-22T00:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "id": { + "examples": [ + "pol_06evsmp24r1pg71cm8500546pkbn" + ], + "type": "string" + }, + "name": { + "description": "Human-readable label, unique within the organization.", + "examples": [ + "Security Research — hardened" + ], + "type": "string" + }, + "org": { + "examples": [ + "my-org" + ], + "type": "string" + }, + "scope": { + "$ref": "#/components/schemas/Scope" + }, + "updated_at": { + "examples": [ + "2026-04-22T00:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "name", + "org", + "scope", + "created_at", + "updated_at" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/Policy/" + }, + { + "name": "PolicySummary", + "pointer": "/components/schemas/PolicySummary", + "schema": { + "description": "Shallow policy representation returned by ListPolicies. Excludes the rule set.", + "properties": { + "created_at": { + "examples": [ + "2026-04-22T00:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "id": { + "examples": [ + "pol_06evsmp24r1pg71cm8500546pkbn" + ], + "type": "string" + }, + "name": { + "description": "Human-readable label, unique within the organization.", + "examples": [ + "Security Research — hardened" + ], + "type": "string" + }, + "org": { + "examples": [ + "my-org" + ], + "type": "string" + }, + "scope": { + "$ref": "#/components/schemas/Scope" + }, + "type": { + "description": "Identifies the policy type. `allowlist_v0` for network, HTTP, and filesystem allowlist policies; `cedar_v1` for Cedar language policies.\n", + "enum": [ + "allowlist_v0", + "cedar_v1" + ], + "examples": [ + "allowlist_v0" + ], + "type": "string" + }, + "updated_at": { + "examples": [ + "2026-04-22T00:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "name", + "org", + "scope", + "created_at", + "updated_at", + "type" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/PolicySummary/" + }, + { + "name": "Rule", + "pointer": "/components/schemas/Rule", + "schema": { + "description": "A single allow or deny rule within an allowlist policy.", + "oneOf": [ + { + "required": [ + "resources" + ], + "type": "object" + }, + { + "required": [ + "http_resources" + ], + "type": "object" + } + ], + "properties": { + "actions": { + "$ref": "#/components/schemas/RuleActions" + }, + "decision": { + "$ref": "#/components/schemas/RuleDecision" + }, + "http_resources": { + "$ref": "#/components/schemas/HTTPResources" + }, + "id": { + "examples": [ + "rule_06evsm9qjm1pdsk0a8nkfaxy7jna" + ], + "type": "string" + }, + "name": { + "description": "Human-readable label for the rule.", + "examples": [ + "allow research mirrors" + ], + "type": "string" + }, + "resources": { + "$ref": "#/components/schemas/RuleResources" + } + }, + "required": [ + "id", + "name", + "actions", + "decision" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/Rule/" + }, + { + "name": "RuleActions", + "pointer": "/components/schemas/RuleActions", + "schema": { + "description": "Network actions: `connect:tcp`, `connect:udp`. Filesystem actions: `read`, `write`. HTTP actions: `request:get`, `request:post`, `request:put`, `request:delete`, `request:patch`, `request:head`, `request:options`, `request:connect`, `request:trace`. All actions in a rule must belong to the same layer; mixing HTTP, network, or filesystem actions in one rule is rejected.\n", + "examples": [ + [ + "connect:tcp", + "connect:udp" + ] + ], + "items": { + "enum": [ + "connect:tcp", + "connect:udp", + "read", + "write", + "request:get", + "request:post", + "request:put", + "request:delete", + "request:patch", + "request:head", + "request:options", + "request:connect", + "request:trace" + ], + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "url": "/reference/api/ai-governance/latest/schemas/RuleActions/" + }, + { + "name": "RuleDecision", + "pointer": "/components/schemas/RuleDecision", + "schema": { + "description": "Outcome applied when this rule matches a request. `deny` always wins: if any rule in the policy matches with `decision: deny`, the request is denied even if other rules match with `decision: allow`.\n", + "enum": [ + "allow", + "deny" + ], + "examples": [ + "allow" + ], + "type": "string" + }, + "url": "/reference/api/ai-governance/latest/schemas/RuleDecision/" + }, + { + "name": "RuleResources", + "pointer": "/components/schemas/RuleResources", + "schema": { + "description": "Network domain: hostnames (for example, `example.com`), wildcard subdomains (`*.example.com` or `**.example.com`), hostnames with port (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation (for example, `10.0.0.0/8` or `2001:db8::/32`). Filesystem domain: paths (for example, `/data`); `*` matches within one path segment, `**` matches recursively (for example, `/data/**`). Required for network and filesystem rules and forbidden for HTTP rules.\n", + "examples": [ + [ + "research.mitre.org", + "cve.mitre.org" + ] + ], + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "url": "/reference/api/ai-governance/latest/schemas/RuleResources/" + }, + { + "name": "Scope", + "pointer": "/components/schemas/Scope", + "schema": { + "description": "Restricts the policy to specific teams. An empty or absent list means the policy applies org-wide.", + "properties": { + "teams": { + "description": "Team IDs the policy applies to. Each must be a valid team in the organization.", + "examples": [ + [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/Scope/" + }, + { + "name": "ScopePatch", + "pointer": "/components/schemas/ScopePatch", + "schema": { + "description": "Per-sub-field patch of a policy's scope. An omitted sub-field is left unchanged; a present list replaces that dimension, and an empty list clears it (making the policy org-wide for that dimension).\n", + "properties": { + "teams": { + "examples": [ + [ + "d290f1ee-6c54-4b01-90e6-d701748f0851" + ] + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/ScopePatch/" + }, + { + "name": "UpdatePolicyRequest", + "pointer": "/components/schemas/UpdatePolicyRequest", + "schema": { + "description": "Partial update of a policy. Only fields present in the body are updated; absent fields are left unchanged. At least one field must be present. For `cedar_v1` policies, supply `cedar_v1` to replace the policy text; `name` and `scope` may be combined freely.\n", + "properties": { + "cedar_v1": { + "$ref": "#/components/schemas/CedarV1Policy" + }, + "name": { + "description": "Policy name, unique within the organization.", + "examples": [ + "Security Research" + ], + "minLength": 1, + "type": "string" + }, + "scope": { + "$ref": "#/components/schemas/ScopePatch" + } + }, + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/UpdatePolicyRequest/" + }, + { + "name": "UpdatePolicyResponse", + "pointer": "/components/schemas/UpdatePolicyResponse", + "schema": { + "description": "The full policy before and after the update.", + "properties": { + "new": { + "$ref": "#/components/schemas/Policy" + }, + "old": { + "$ref": "#/components/schemas/Policy" + } + }, + "required": [ + "old", + "new" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/UpdatePolicyResponse/" + }, + { + "name": "UpdateRuleRequest", + "pointer": "/components/schemas/UpdateRuleRequest", + "schema": { + "description": "Partial update. Only fields present in the body are updated; absent fields are left unchanged.", + "not": { + "required": [ + "resources", + "http_resources" + ], + "type": "object" + }, + "properties": { + "actions": { + "$ref": "#/components/schemas/RuleActions" + }, + "decision": { + "$ref": "#/components/schemas/RuleDecision" + }, + "http_resources": { + "$ref": "#/components/schemas/HTTPResources" + }, + "name": { + "description": "Human-readable label for the rule.", + "examples": [ + "allow research mirrors" + ], + "type": "string" + }, + "resources": { + "$ref": "#/components/schemas/RuleResources" + } + }, + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/UpdateRuleRequest/" + }, + { + "name": "UpdateRuleResponse", + "pointer": "/components/schemas/UpdateRuleResponse", + "schema": { + "description": "The rule state before and after the update.", + "properties": { + "new": { + "$ref": "#/components/schemas/Rule" + }, + "old": { + "$ref": "#/components/schemas/Rule" + } + }, + "required": [ + "old", + "new" + ], + "type": "object" + }, + "url": "/reference/api/ai-governance/latest/schemas/UpdateRuleResponse/" + } + ], + "securitySchemes": { + "bearerAuth": { + "bearerFormat": "JWT", + "description": "Short-lived JWT obtained by exchanging Docker Hub credentials at\n`POST https://hub.docker.com/v2/auth/token`. Pass the JWT in the\n`Authorization: Bearer \u003ctoken\u003e` header. Tokens expire after a short\nperiod; request a fresh one when you receive a `401`.\n\nThe `password` field of the token request accepts any of the following\ncredential types:\n\n| Type | Format | Notes |\n|------|--------|-------|\n| Password | Plain text | Your Docker Hub account password. |\n| Personal Access Token (PAT) | `dckr_pat_*` | Recommended over passwords. Create one under Account Settings → Security. |\n| Organization Access Token (OAT) | `dckr_oat_*` | Scoped to an organization. Create one under Organization Settings → Access Tokens. |\n\nPAT and OAT strings can't be used directly as a bearer token. They must\nbe exchanged at the token endpoint first.\n\nSee [Docker Hub authentication](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)\nfor full details.\n", + "scheme": "bearer", + "type": "http" + } + }, + "servers": [ + { + "url": "https://hub.docker.com/v2" + } + ], + "source": "content/reference/api/ai-governance/api.yaml", + "sourceURL": "/reference/api/ai-governance/api.yaml", + "tags": [ + { + "description": "Policy lifecycle management", + "kind": "nav", + "name": "policies", + "summary": "Policies" + }, + { + "description": "Rule management within an allowlist policy", + "kind": "nav", + "name": "rules", + "summary": "Rules" + } + ], + "title": "AI Governance", + "url": "/reference/api/ai-governance/latest/", + "version": "1" + }, + { + "connection": "hosted", + "description": "Use this API to create sandboxes, run processes, work with files, and manage sandbox resources. Start with a kit through the SDK, or use the HTTP operations here directly.\n\nManagement requests use an Authorization bearer token. File and process requests go to the sandbox endpoint in core.endpoint.uri and require a short-lived scoped endpoint credential, not the management token. The SDK obtains that credential for you. Each operation also checks its declared permissions. Direct Unix socket access uses the operating system's socket access controls instead of HTTP authentication. Interactive WebSocket operations describe their supported credential transports separately.\n\nThe Docker Cloud API base URL is https://connect.docker.com/sandboxes. Append each /v1 path without removing the base URL's path prefix. For sandbox endpoint operations, use the sandbox endpoint as the base URL instead.\n\nOperations list their success and error responses. A 202 response means work is still in progress; read the resource until it reaches the expected state. Errors contain a stable code, a message, and optional details. Inspect the code as well as the HTTP status.\n\nSend the current ETag in If-Match when an operation requires it. Operations that accept Idempotency-Key use that HTTP header to identify retries: the same key and payload return the first result; a different payload fails. Keys are retained for at least 24 hours.\n\nLists use pageSize and pageToken. Continue with nextPageToken until it is empty. Supported filters and ordering are listed on each operation. Resource names contain immutable identifiers; displayName is a label. A 64-bit integer is returned as a JSON string; inputs accept a number or a string.", + "diagnostics": [], + "digest": "e57c2e2d328a3fde9d906ba051cf310ab484b2bdaf98d29501d038f5aeae29ce", + "exampleCount": 81, + "experimental": true, + "guides": [ + "/manuals/ai/sandboxes-api/authentication.md", + "/manuals/ai/sandboxes-api/get-started.md" + ], + "id": "sandboxes", + "manual": "/manuals/ai/sandboxes-api/", + "operations": [ + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/files?path=%3CPATH%3E'", + "curlNotes": [], + "deprecated": null, + "description": "List lists directory entries by path ascending.", + "id": "list", + "line": 26, + "method": "GET", + "parameters": [ + { + "description": "path is the directory path.", + "in": "query", + "name": "path", + "pointer": "/paths/~1v1~1files/get/parameters/0", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1files/get/parameters/1", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an optional continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1files/get/parameters/2", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable field is\npath.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1files/get/parameters/3", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/files", + "pointer": "/paths/~1v1~1files/get", + "raw": { + "description": "List lists directory entries by path ascending.", + "operationId": "list", + "parameters": [ + { + "description": "path is the directory path.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an optional continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable field is\npath.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesListResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "List lists directory entries by path ascending.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesFilesRead" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesListResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesListResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "List lists directory entries by path ascending.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/list/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesListResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request DELETE \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/files?path=%3CPATH%3E'", + "curlNotes": [], + "deprecated": null, + "description": "Remove deletes a path. Removing an absent path succeeds. A nonrecursive\nremoval of a nonempty directory returns FAILED_PRECONDITION unchanged.\nA recursive removal that stops partway still answers OK: check\nRemoveResponse.failed_path, not the operation status. Removed paths stay removed.", + "id": "remove", + "line": 94, + "method": "DELETE", + "parameters": [ + { + "description": "path is the sandbox path to remove.", + "in": "query", + "name": "path", + "pointer": "/paths/~1v1~1files/delete/parameters/0", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "recursive removes directory contents when true.", + "in": "query", + "name": "recursive", + "pointer": "/paths/~1v1~1files/delete/parameters/1", + "required": false, + "schema": { + "title": "recursive", + "type": "boolean" + } + } + ], + "path": "/v1/files", + "pointer": "/paths/~1v1~1files/delete", + "raw": { + "description": "Remove deletes a path. Removing an absent path succeeds. A nonrecursive\nremoval of a nonempty directory returns FAILED_PRECONDITION unchanged.\nA recursive removal that stops partway still answers OK: check\nRemoveResponse.failed_path, not the operation status. Removed paths stay removed.", + "operationId": "remove", + "parameters": [ + { + "description": "path is the sandbox path to remove.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "recursive removes directory contents when true.", + "in": "query", + "name": "recursive", + "required": false, + "schema": { + "title": "recursive", + "type": "boolean" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesRemoveResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Remove deletes a path.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesFilesWrite" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesRemoveResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesRemoveResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Remove deletes a path.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/remove/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files/delete/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesRemoveResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/octet-stream", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/octet-stream' \\\n 'https://sandbox.invalid/v1/files/content?path=%3CPATH%3E'", + "curlNotes": [], + "deprecated": null, + "description": "ReadFile returns raw file content over HTTP; Stat exposes file metadata.\nContent above the unary message cap is refused, never truncated.", + "id": "readFile", + "line": 148, + "method": "GET", + "parameters": [ + { + "description": "path is the sandbox path of a regular file.", + "in": "query", + "name": "path", + "pointer": "/paths/~1v1~1files~1content/get/parameters/0", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + } + ], + "path": "/v1/files/content", + "pointer": "/paths/~1v1~1files~1content/get", + "raw": { + "description": "ReadFile returns raw file content over HTTP; Stat exposes file metadata.\nContent above the unary message cap is refused, never truncated.", + "operationId": "readFile", + "parameters": [ + { + "description": "path is the sandbox path of a regular file.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/octet-stream": { + "schema": { + "contentMediaType": "application/octet-stream" + } + } + }, + "description": "Success", + "headers": { + "Content-Length": { + "description": "Exact byte count of the complete file; this response does not use chunked transfer encoding.", + "required": true, + "schema": { + "minimum": 0, + "type": "integer" + } + } + } + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ReadFile returns raw file content over HTTP; Stat exposes file metadata.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-http-transfer": { + "response": { + "bytesField": "data", + "mediaType": "application/octet-stream" + } + }, + "x-sbx-plane": "data", + "x-sbx-request-schema": { + "$ref": "#/components/schemas/FilesReadFileRequest" + }, + "x-sbx-required-permissions": [ + "sandboxesFilesRead" + ], + "x-sbx-response-schema": { + "$ref": "#/components/schemas/FilesReadFileResponse" + }, + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesReadFileRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesReadFileRequest/" + }, + { + "ref": "#/components/schemas/FilesReadFileResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesReadFileResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ReadFile returns raw file content over HTTP; Stat exposes file metadata.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/readFile/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "Content-Length": { + "description": "Exact byte count of the complete file; this response does not use chunked transfer encoding.", + "required": true, + "schema": { + "minimum": 0, + "type": "integer" + } + } + }, + "media": "application/octet-stream", + "pointer": "/paths/~1v1~1files~1content/get/responses/200/content/application~1octet-stream", + "required": null, + "schema": { + "contentMediaType": "application/octet-stream" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1content/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/octet-stream' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/files/content?path=%3CPATH%3E'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "WriteFile accepts raw content with path and mode query parameters.\nIt replaces the complete target state and carries no request_id.", + "id": "writeFile", + "line": 207, + "method": "PUT", + "parameters": [ + { + "description": "path is the sandbox path.", + "in": "query", + "name": "path", + "pointer": "/paths/~1v1~1files~1content/put/parameters/0", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "mode carries Unix permission bits. Upload applies mode \u0026 0777, or 0644 when\nthat value is zero, without subtracting umask; Download reports stored bits.", + "in": "query", + "name": "mode", + "pointer": "/paths/~1v1~1files~1content/put/parameters/1", + "required": false, + "schema": { + "title": "mode", + "type": "integer" + } + } + ], + "path": "/v1/files/content", + "pointer": "/paths/~1v1~1files~1content/put", + "raw": { + "description": "WriteFile accepts raw content with path and mode query parameters.\nIt replaces the complete target state and carries no request_id.", + "operationId": "writeFile", + "parameters": [ + { + "description": "path is the sandbox path.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + }, + { + "description": "mode carries Unix permission bits. Upload applies mode \u0026 0777, or 0644 when\nthat value is zero, without subtracting umask; Download reports stored bits.", + "in": "query", + "name": "mode", + "required": false, + "schema": { + "title": "mode", + "type": "integer" + } + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "schema": { + "contentMediaType": "application/octet-stream" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesWriteFileResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "WriteFile accepts raw content with path and mode query parameters.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-http-transfer": { + "request": { + "bytesField": "data", + "mediaType": "application/octet-stream" + } + }, + "x-sbx-plane": "data", + "x-sbx-request-schema": { + "$ref": "#/components/schemas/FilesWriteFileRequest" + }, + "x-sbx-required-permissions": [ + "sandboxesFilesWrite" + ], + "x-sbx-response-schema": { + "$ref": "#/components/schemas/FilesWriteFileResponse" + }, + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesWriteFileRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesWriteFileRequest/" + }, + { + "ref": "#/components/schemas/FilesWriteFileResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesWriteFileResponse/" + } + ], + "requestSchema": { + "contentMediaType": "application/octet-stream" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "WriteFile accepts raw content with path and mode query parameters.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/writeFile/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/octet-stream", + "pointer": "/paths/~1v1~1files~1content/put/requestBody/content/application~1octet-stream", + "required": true, + "schema": { + "contentMediaType": "application/octet-stream" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1content/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesWriteFileResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1content/put/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/files/directories'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Mkdir creates a directory. Without parents, a missing parent returns\nNOT_FOUND without creating directories. A repeated Mkdir converges when\nthe leaf already exists as a directory. A converged call leaves\nthe directory's mode unchanged on every request.", + "id": "mkdir", + "line": 275, + "method": "PUT", + "parameters": [], + "path": "/v1/files/directories", + "pointer": "/paths/~1v1~1files~1directories/put", + "raw": { + "description": "Mkdir creates a directory. Without parents, a missing parent returns\nNOT_FOUND without creating directories. A repeated Mkdir converges when\nthe leaf already exists as a directory. A converged call leaves\nthe directory's mode unchanged on every request.", + "operationId": "mkdir", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesMkdirRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesMkdirResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Mkdir creates a directory.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesFilesWrite" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesMkdirRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesMkdirRequest/" + }, + { + "ref": "#/components/schemas/FilesMkdirResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesMkdirResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/FilesMkdirRequest" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Mkdir creates a directory.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/mkdir/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1directories/put/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/FilesMkdirRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1directories/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesMkdirResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1directories/put/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "multipart/mixed", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: multipart/mixed' \\\n 'https://sandbox.invalid/v1/files/download?paths=%3CPATHS%3E'", + "curlNotes": [], + "deprecated": null, + "description": "Download streams file headers, bytes, and per-file errors. A path that\nleaves the jail through a symlink, or names a non-regular object, reports\na FileError with a error reason instead of reading through it.", + "id": "download", + "line": 319, + "method": "GET", + "parameters": [ + { + "description": "paths naming stable regular files or absent entries at canonical absolute paths\nyield contiguous results in request order, including duplicates.", + "in": "query", + "name": "paths", + "pointer": "/paths/~1v1~1files~1download/get/parameters/0", + "required": true, + "schema": { + "items": { + "type": "string" + }, + "minItems": 1, + "title": "paths", + "type": "array" + } + } + ], + "path": "/v1/files/download", + "pointer": "/paths/~1v1~1files~1download/get", + "raw": { + "description": "Download streams file headers, bytes, and per-file errors. A path that\nleaves the jail through a symlink, or names a non-regular object, reports\na FileError with a error reason instead of reading through it.", + "operationId": "download", + "parameters": [ + { + "description": "paths naming stable regular files or absent entries at canonical absolute paths\nyield contiguous results in request order, including duplicates.", + "in": "query", + "name": "paths", + "required": true, + "schema": { + "items": { + "type": "string" + }, + "minItems": 1, + "title": "paths", + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "multipart/mixed": { + "itemEncoding": { + "contentType": "application/json, application/octet-stream", + "headers": { + "Content-Disposition": { + "required": true, + "schema": { + "enum": [ + "attachment; name=metadata", + "attachment; name=content", + "attachment; name=error", + "attachment; name=stream-error" + ], + "type": "string" + } + } + } + }, + "itemSchema": { + "anyOf": [ + { + "$ref": "#/components/schemas/FileHeader" + }, + { + "contentMediaType": "application/octet-stream" + }, + { + "$ref": "#/components/schemas/FileError" + }, + { + "$ref": "#/components/schemas/Error" + } + ] + }, + "x-sbx-framing": { + "description": "Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures.", + "parts": { + "content": { + "contentType": "application/octet-stream", + "schema": { + "contentMediaType": "application/octet-stream" + } + }, + "error": { + "contentType": "application/json", + "schema": { + "$ref": "#/components/schemas/FileError" + } + }, + "metadata": { + "contentType": "application/json", + "schema": { + "$ref": "#/components/schemas/FileHeader" + } + }, + "stream-error": { + "contentType": "application/json", + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "repeatedItems": true, + "requiresClosingDelimiter": true, + "requiresTerminal": false + } + } + }, + "description": "Success\n\nRead metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Download streams file headers, bytes, and per-file errors.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-http-transfer": { + "response": { + "bytesField": "data", + "errorField": "error", + "mediaType": "multipart/mixed", + "metadataField": "header", + "repeatedItems": true + } + }, + "x-sbx-plane": "data", + "x-sbx-request-schema": { + "$ref": "#/components/schemas/FilesDownloadRequest" + }, + "x-sbx-required-permissions": [ + "sandboxesFilesRead" + ], + "x-sbx-response-schema": { + "$ref": "#/components/schemas/FilesDownloadResponse" + }, + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FileError", + "url": "/reference/api/sandboxes/latest/schemas/FileError/" + }, + { + "ref": "#/components/schemas/FileHeader", + "url": "/reference/api/sandboxes/latest/schemas/FileHeader/" + }, + { + "ref": "#/components/schemas/FilesDownloadRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesDownloadRequest/" + }, + { + "ref": "#/components/schemas/FilesDownloadResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesDownloadResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Download streams file headers, bytes, and per-file errors.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/download/", + "variants": [ + { + "description": "Success\n\nRead metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures.", + "direction": "Response", + "examples": [], + "headers": null, + "itemEncoding": { + "contentType": "application/json, application/octet-stream", + "headers": { + "Content-Disposition": { + "required": true, + "schema": { + "enum": [ + "attachment; name=metadata", + "attachment; name=content", + "attachment; name=error", + "attachment; name=stream-error" + ], + "type": "string" + } + } + } + }, + "itemSchema": { + "anyOf": [ + { + "$ref": "#/components/schemas/FileHeader" + }, + { + "contentMediaType": "application/octet-stream" + }, + { + "$ref": "#/components/schemas/FileError" + }, + { + "$ref": "#/components/schemas/Error" + } + ] + }, + "media": "multipart/mixed", + "pointer": "/paths/~1v1~1files~1download/get/responses/200/content/multipart~1mixed", + "required": null, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1download/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/files/move'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Move renames or moves a path. The destination is exact: an existing regular\nfile is replaced, the source basename is never appended, and a directory\ndestination is refused unchanged. A source or destination that leaves the jail\nthrough a symlink refuses with FAILED_PRECONDITION and a error reason.", + "id": "move", + "line": 421, + "method": "POST", + "parameters": [], + "path": "/v1/files/move", + "pointer": "/paths/~1v1~1files~1move/post", + "raw": { + "description": "Move renames or moves a path. The destination is exact: an existing regular\nfile is replaced, the source basename is never appended, and a directory\ndestination is refused unchanged. A source or destination that leaves the jail\nthrough a symlink refuses with FAILED_PRECONDITION and a error reason.", + "operationId": "move", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesMoveRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesMoveResponse" + } + } + }, + "description": "Success" + }, + "409": { + "content": { + "application/json": { + "examples": { + "move_crosses_filesystem": { + "summary": "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary.", + "value": { + "code": "failedPrecondition", + "message": "move_crosses_filesystem: `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + } + }, + "move_destination_is_directory": { + "summary": "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it.", + "value": { + "code": "failedPrecondition", + "message": "move_destination_is_directory: `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." + } + }, + "move_destination_occupied": { + "summary": "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing.", + "value": { + "code": "failedPrecondition", + "message": "move_destination_occupied: `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." + } + }, + "path_authority_nonregular_object": { + "summary": "The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.", + "value": { + "code": "failedPrecondition", + "message": "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + } + }, + "path_authority_symlink_escape": { + "summary": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.", + "value": { + "code": "failedPrecondition", + "message": "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\n\nThe path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.\n\n`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it.\n\n`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing.\n\n`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Move renames or moves a path.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.", + "reason": "path_authority_symlink_escape" + }, + { + "code": "FAILED_PRECONDITION", + "description": "The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.", + "reason": "path_authority_nonregular_object" + }, + { + "code": "FAILED_PRECONDITION", + "description": "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it.", + "reason": "move_destination_is_directory" + }, + { + "code": "FAILED_PRECONDITION", + "description": "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing.", + "reason": "move_destination_occupied" + }, + { + "code": "FAILED_PRECONDITION", + "description": "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary.", + "reason": "move_crosses_filesystem" + } + ], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesFilesWrite" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesMoveRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesMoveRequest/" + }, + { + "ref": "#/components/schemas/FilesMoveResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesMoveResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/FilesMoveRequest" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Move renames or moves a path.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/move/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1move/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/FilesMoveRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1move/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesMoveResponse" + }, + "status": "200" + }, + { + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\n\nThe path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.\n\n`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it.\n\n`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing.\n\n`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "move_crosses_filesystem", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"move_crosses_filesystem: `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "move_crosses_filesystem: `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." + } + }, + { + "language": "json", + "name": "move_destination_is_directory", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"move_destination_is_directory: `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "move_destination_is_directory: `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." + } + }, + { + "language": "json", + "name": "move_destination_occupied", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"move_destination_occupied: `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "move_destination_occupied: `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." + } + }, + { + "language": "json", + "name": "path_authority_nonregular_object", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + } + }, + { + "language": "json", + "name": "path_authority_symlink_escape", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1move/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1move/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/files/stat?path=%3CPATH%3E'", + "curlNotes": [], + "deprecated": null, + "description": "Stat reads metadata for one path.\nA metadata read has a different response from the file-content resource.", + "id": "stat", + "line": 522, + "method": "GET", + "parameters": [ + { + "description": "path is the sandbox path.", + "in": "query", + "name": "path", + "pointer": "/paths/~1v1~1files~1stat/get/parameters/0", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + } + ], + "path": "/v1/files/stat", + "pointer": "/paths/~1v1~1files~1stat/get", + "raw": { + "description": "Stat reads metadata for one path.\nA metadata read has a different response from the file-content resource.", + "operationId": "stat", + "parameters": [ + { + "description": "path is the sandbox path.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "minLength": 1, + "title": "path", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesStatResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Stat reads metadata for one path.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesFilesRead" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FilesStatResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesStatResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Stat reads metadata for one path.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/stat/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1stat/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesStatResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1stat/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: multipart/form-data' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/files/upload'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Upload streams one or more files. The first frame must be FileHeader.\nWriting through a symlink that leaves the jail, or onto an existing\nnon-regular object, refuses with FAILED_PRECONDITION and a error reason.", + "id": "upload", + "line": 567, + "method": "POST", + "parameters": [], + "path": "/v1/files/upload", + "pointer": "/paths/~1v1~1files~1upload/post", + "raw": { + "description": "Upload streams one or more files. The first frame must be FileHeader.\nWriting through a symlink that leaves the jail, or onto an existing\nnon-regular object, refuses with FAILED_PRECONDITION and a error reason.", + "operationId": "upload", + "requestBody": { + "content": { + "multipart/form-data": { + "itemEncoding": { + "contentType": "application/json, application/octet-stream" + }, + "itemSchema": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "metadata": { + "$ref": "#/components/schemas/FileHeader" + } + }, + "required": [ + "metadata" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "content": { + "contentMediaType": "application/octet-stream" + } + }, + "required": [ + "content" + ], + "type": "object" + } + ] + }, + "x-sbx-framing": { + "description": "Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path.", + "partOrder": [ + "metadata", + "content" + ], + "repeatedItems": true, + "requiresClosingDelimiter": true + } + } + }, + "description": "Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path.", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesUploadResponse" + } + } + }, + "description": "Success" + }, + "409": { + "content": { + "application/json": { + "examples": { + "path_authority_nonregular_object": { + "summary": "The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.", + "value": { + "code": "failedPrecondition", + "message": "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + } + }, + "path_authority_symlink_escape": { + "summary": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.", + "value": { + "code": "failedPrecondition", + "message": "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\n\nThe path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Upload streams one or more files.", + "tags": [ + "Files" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.", + "reason": "path_authority_symlink_escape" + }, + { + "code": "FAILED_PRECONDITION", + "description": "The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.", + "reason": "path_authority_nonregular_object" + } + ], + "x-sbx-http-transfer": { + "request": { + "bytesField": "data", + "itemPathField": "header.path", + "mediaType": "multipart/form-data", + "metadataField": "header", + "repeatedItems": true + } + }, + "x-sbx-plane": "data", + "x-sbx-request-schema": { + "$ref": "#/components/schemas/FilesUploadRequest" + }, + "x-sbx-required-permissions": [ + "sandboxesFilesWrite" + ], + "x-sbx-response-schema": { + "$ref": "#/components/schemas/FilesUploadResponse" + }, + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/FileHeader", + "url": "/reference/api/sandboxes/latest/schemas/FileHeader/" + }, + { + "ref": "#/components/schemas/FilesUploadRequest", + "url": "/reference/api/sandboxes/latest/schemas/FilesUploadRequest/" + }, + { + "ref": "#/components/schemas/FilesUploadResponse", + "url": "/reference/api/sandboxes/latest/schemas/FilesUploadResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Upload streams one or more files.", + "tags": [ + "Files" + ], + "url": "/reference/api/sandboxes/latest/operations/upload/", + "variants": [ + { + "description": "Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path.", + "direction": "Request", + "examples": [], + "headers": null, + "itemEncoding": { + "contentType": "application/json, application/octet-stream" + }, + "itemSchema": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "metadata": { + "$ref": "#/components/schemas/FileHeader" + } + }, + "required": [ + "metadata" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "content": { + "contentMediaType": "application/octet-stream" + } + }, + "required": [ + "content" + ], + "type": "object" + } + ] + }, + "media": "multipart/form-data", + "pointer": "/paths/~1v1~1files~1upload/post/requestBody/content/multipart~1form-data", + "required": true, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1upload/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/FilesUploadResponse" + }, + "status": "200" + }, + { + "description": "The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\n\nThe path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "path_authority_nonregular_object", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." + } + }, + { + "language": "json", + "name": "path_authority_symlink_escape", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1upload/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1files~1upload/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/identity/exchange'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "ExchangeDockerCredential consumes an identity token once for the authenticated owner.\nThe exchanged credential is stored for that owner; the response is empty.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "exchangeDockerCredential", + "line": 672, + "method": "POST", + "parameters": [], + "path": "/v1/identity/exchange", + "pointer": "/paths/~1v1~1identity~1exchange/post", + "raw": { + "description": "ExchangeDockerCredential consumes an identity token once for the authenticated owner.\nThe exchanged credential is stored for that owner; the response is empty.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "exchangeDockerCredential", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExchangeCompositionCredentialResponse" + } + } + }, + "description": "Success" + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ExchangeDockerCredential consumes an identity token once for the authenticated owner.", + "tags": [ + "Credentials" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "credentialsExchange" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ExchangeCompositionCredentialResponse", + "url": "/reference/api/sandboxes/latest/schemas/ExchangeCompositionCredentialResponse/" + }, + { + "ref": "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest", + "url": "/reference/api/sandboxes/latest/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ExchangeDockerCredential consumes an identity token once for the authenticated owner.", + "tags": [ + "Credentials" + ], + "url": "/reference/api/sandboxes/latest/operations/exchangeDockerCredential/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1identity~1exchange/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1identity~1exchange/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ExchangeCompositionCredentialResponse" + }, + "status": "200" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1identity~1exchange/post/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1identity~1exchange/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/images'", + "curlNotes": [], + "deprecated": null, + "description": "ListImages lists images in the caller's owner scope.", + "id": "listImages", + "line": 725, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1images/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1images/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name, uid and status.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1images/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1images/get/parameters/3", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/images", + "pointer": "/paths/~1v1~1images/get", + "raw": { + "description": "ListImages lists images in the caller's owner scope.", + "operationId": "listImages", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name, uid and status.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListImagesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListImages lists images in the caller's owner scope.", + "tags": [ + "Images" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "imagesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListImagesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListImagesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListImages lists images in the caller's owner scope.", + "tags": [ + "Images" + ], + "url": "/reference/api/sandboxes/latest/operations/listImages/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListImagesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/images'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox.", + "id": "createImage", + "line": 788, + "method": "POST", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1images/post/parameters/0", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/images", + "pointer": "/paths/~1v1~1images/post", + "raw": { + "description": "CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox.", + "operationId": "createImage", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateImageRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Image" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "pending", + "waitingForPush", + "preparing" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + }, + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Image" + }, + { + "properties": { + "status": { + "enum": [ + "pending", + "waitingForPush", + "preparing" + ] + } + }, + "required": [ + "status" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + }, + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox.", + "tags": [ + "Images" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "imagesWrite" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Image" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CreateImageRequest", + "url": "/reference/api/sandboxes/latest/schemas/CreateImageRequest/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Image", + "url": "/reference/api/sandboxes/latest/schemas/Image/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateImageRequest" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox.", + "tags": [ + "Images" + ], + "url": "/reference/api/sandboxes/latest/operations/createImage/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateImageRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + }, + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images/post/responses/201/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Image" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "pending", + "waitingForPush", + "preparing" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + }, + "status": "201" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + }, + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Image" + }, + { + "properties": { + "status": { + "enum": [ + "pending", + "waitingForPush", + "preparing" + ] + } + }, + "required": [ + "status" + ] + } + ] + }, + "status": "202" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/images/\u003cIMAGE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetImage reads one image by its resource name.", + "id": "getImage", + "line": 909, + "method": "GET", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "pointer": "/paths/~1v1~1images~1{image}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1images~1{image}/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/images/{image}", + "pointer": "/paths/~1v1~1images~1{image}/get", + "raw": { + "description": "GetImage reads one image by its resource name.", + "operationId": "getImage", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Image" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetImage reads one image by its resource name.", + "tags": [ + "Images" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "imagesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Image", + "url": "/reference/api/sandboxes/latest/schemas/Image/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetImage reads one image by its resource name.", + "tags": [ + "Images" + ], + "url": "/reference/api/sandboxes/latest/operations/getImage/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Image" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1images~1{image}/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://connect.docker.com/sandboxes/v1/images/\u003cIMAGE\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeleteImage deletes an image; deleting an already absent image succeeds.", + "id": "deleteImage", + "line": 970, + "method": "DELETE", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "pointer": "/paths/~1v1~1images~1{image}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1images~1{image}/delete/parameters/1", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/images/{image}", + "pointer": "/paths/~1v1~1images~1{image}/delete", + "raw": { + "description": "DeleteImage deletes an image; deleting an already absent image succeeds.", + "operationId": "deleteImage", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Success. The response carries no body." + }, + "409": { + "content": { + "application/json": { + "examples": { + "deletion_content_lease_held": { + "summary": "An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "value": { + "code": "failedPrecondition", + "message": "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + } + }, + "deletion_preparation_incomplete": { + "summary": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.", + "value": { + "code": "failedPrecondition", + "message": "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\n\nAn admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeleteImage deletes an image; deleting an already absent image succeeds.", + "tags": [ + "Images" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.", + "reason": "deletion_preparation_incomplete" + }, + { + "code": "FAILED_PRECONDITION", + "description": "An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "reason": "deletion_content_lease_held" + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "imagesWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeleteImage deletes an image; deleting an already absent image succeeds.", + "tags": [ + "Images" + ], + "url": "/reference/api/sandboxes/latest/operations/deleteImage/", + "variants": [ + { + "description": "Success. The response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1images~1{image}/delete/responses/204", + "status": "204" + }, + { + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\n\nAn admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "deletion_content_lease_held", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + } + }, + { + "language": "json", + "name": "deletion_preparation_incomplete", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/delete/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/images/\u003cIMAGE\u003e/pull-spec'", + "curlNotes": [], + "deprecated": null, + "description": "GetImagePullSpec returns short-lived pull material through registry-transfer support.\nAction: the pull spec is derived material about the image, not a sub-resource of it.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "getImagePullSpec", + "line": 1065, + "method": "GET", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "pointer": "/paths/~1v1~1images~1{image}~1pull-spec/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/images/{image}/pull-spec", + "pointer": "/paths/~1v1~1images~1{image}~1pull-spec/get", + "raw": { + "description": "GetImagePullSpec returns short-lived pull material through registry-transfer support.\nAction: the pull spec is derived material about the image, not a sub-resource of it.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "getImagePullSpec", + "parameters": [ + { + "description": "The image id.", + "in": "path", + "name": "image", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImagePullSpec" + } + } + }, + "description": "Success", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + } + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetImagePullSpec returns short-lived pull material through registry-transfer support.", + "tags": [ + "Images" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "imagesPull" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ImagePullSpec", + "url": "/reference/api/sandboxes/latest/schemas/ImagePullSpec/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetImagePullSpec returns short-lived pull material through registry-transfer support.", + "tags": [ + "Images" + ], + "url": "/reference/api/sandboxes/latest/operations/getImagePullSpec/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}~1pull-spec/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ImagePullSpec" + }, + "status": "200" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}~1pull-spec/get/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1images~1{image}~1pull-spec/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/mcp-servers/\u003cMCPSERVER\u003e/authorization'", + "curlNotes": [], + "deprecated": null, + "description": "GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write.", + "id": "getMcpAuthorization", + "line": 1139, + "method": "GET", + "parameters": [ + { + "description": "The mcpServer id.", + "in": "path", + "name": "mcpServer", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/mcp-servers/{mcpServer}/authorization", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get", + "raw": { + "description": "GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write.", + "operationId": "getMcpAuthorization", + "parameters": [ + { + "description": "The mcpServer id.", + "in": "path", + "name": "mcpServer", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/McpAuthorization" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write.", + "tags": [ + "MCP gateways" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "mcpWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/McpAuthorization", + "url": "/reference/api/sandboxes/latest/schemas/McpAuthorization/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write.", + "tags": [ + "MCP gateways" + ], + "url": "/reference/api/sandboxes/latest/operations/getMcpAuthorization/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/McpAuthorization" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/mcp-servers/\u003cMCPSERVER\u003e/authorization/authorize'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "AuthorizeMcpServer authorizes credentials for one named upstream.\nAction: authorization runs an interactive grant whose result is not the request body.", + "id": "authorizeMcpServer", + "line": 1201, + "method": "POST", + "parameters": [ + { + "description": "The mcpServer id.", + "in": "path", + "name": "mcpServer", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/parameters/1", + "schema": { + "description": "(OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/mcp-servers/{mcpServer}/authorization/authorize", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post", + "raw": { + "description": "AuthorizeMcpServer authorizes credentials for one named upstream.\nAction: authorization runs an interactive grant whose result is not the request body.", + "operationId": "authorizeMcpServer", + "parameters": [ + { + "description": "The mcpServer id.", + "in": "path", + "name": "mcpServer", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization.", + "in": "header", + "name": "If-Match", + "schema": { + "description": "(OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses.", + "title": "If-Match", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization.", + "properties": { + "forceReauth": { + "description": "force_reauth starts a fresh flow while existing credentials serve until completion.\nRepeating a pending flow converges without reminting.", + "type": "boolean" + }, + "remoteUrl": { + "description": "remote_url binds authorization to a concrete upstream URL when supplied.", + "format": "uri", + "type": [ + "string", + "null" + ] + } + }, + "title": "AuthorizeMcpServerRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/McpAuthorization" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "pending" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/McpAuthorization" + }, + { + "properties": { + "status": { + "enum": [ + "pending" + ] + } + }, + "required": [ + "status" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "AuthorizeMcpServer authorizes credentials for one named upstream.", + "tags": [ + "MCP gateways" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "mcpWrite" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/McpAuthorization" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/McpAuthorization", + "url": "/reference/api/sandboxes/latest/schemas/McpAuthorization/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization.", + "properties": { + "forceReauth": { + "description": "force_reauth starts a fresh flow while existing credentials serve until completion.\nRepeating a pending flow converges without reminting.", + "type": "boolean" + }, + "remoteUrl": { + "description": "remote_url binds authorization to a concrete upstream URL when supplied.", + "format": "uri", + "type": [ + "string", + "null" + ] + } + }, + "title": "AuthorizeMcpServerRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "AuthorizeMcpServer authorizes credentials for one named upstream.", + "tags": [ + "MCP gateways" + ], + "url": "/reference/api/sandboxes/latest/operations/authorizeMcpServer/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization.", + "properties": { + "forceReauth": { + "description": "force_reauth starts a fresh flow while existing credentials serve until completion.\nRepeating a pending flow converges without reminting.", + "type": "boolean" + }, + "remoteUrl": { + "description": "remote_url binds authorization to a concrete upstream URL when supplied.", + "format": "uri", + "type": [ + "string", + "null" + ] + } + }, + "title": "AuthorizeMcpServerRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/responses/200/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/McpAuthorization" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "pending" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + }, + "status": "200" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/McpAuthorization" + }, + { + "properties": { + "status": { + "enum": [ + "pending" + ] + } + }, + "required": [ + "status" + ] + } + ] + }, + "status": "202" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/network-policies'", + "curlNotes": [], + "deprecated": null, + "description": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "id": "getNetworkPoliciesInOwnerScope", + "line": 1314, + "method": "GET", + "parameters": [ + { + "description": "Omitted versions accept only destination.v1; an unsupported representation fails closed.", + "in": "query", + "name": "acceptedSelectorVersions", + "pointer": "/paths/~1v1~1network-policies/get/parameters/0", + "required": false, + "schema": { + "items": { + "description": "", + "minLength": 1, + "type": "string" + }, + "maxItems": 8, + "title": "accepted_selector_versions", + "type": "array", + "uniqueItems": true + } + } + ], + "path": "/v1/network-policies", + "pointer": "/paths/~1v1~1network-policies/get", + "raw": { + "description": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "operationId": "getNetworkPoliciesInOwnerScope", + "parameters": [ + { + "description": "Omitted versions accept only destination.v1; an unsupported representation fails closed.", + "in": "query", + "name": "acceptedSelectorVersions", + "required": false, + "schema": { + "items": { + "description": "", + "minLength": 1, + "type": "string" + }, + "maxItems": 8, + "title": "accepted_selector_versions", + "type": "array", + "uniqueItems": true + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetNetworkPoliciesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "tags": [ + "Network policies" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "networkPoliciesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/GetNetworkPoliciesResponse", + "url": "/reference/api/sandboxes/latest/schemas/GetNetworkPoliciesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "tags": [ + "Network policies" + ], + "url": "/reference/api/sandboxes/latest/operations/getNetworkPoliciesInOwnerScope/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1network-policies/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/GetNetworkPoliciesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1network-policies/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/policy-logs?since=2023-01-15T01%3A30%3A15.01Z\u0026until=2023-01-15T01%3A30%3A15.01Z'", + "curlNotes": [], + "deprecated": null, + "description": "ListPolicyLogEntries lists observed policy decisions.", + "id": "listPolicyLogEntriesInOwnerScope", + "line": 1356, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1policy-logs/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1policy-logs/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable field is\ndomain.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1policy-logs/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "since", + "pointer": "/paths/~1v1~1policy-logs/get/parameters/3", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "until", + "pointer": "/paths/~1v1~1policy-logs/get/parameters/4", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + } + ], + "path": "/v1/policy-logs", + "pointer": "/paths/~1v1~1policy-logs/get", + "raw": { + "description": "ListPolicyLogEntries lists observed policy decisions.", + "operationId": "listPolicyLogEntriesInOwnerScope", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable field is\ndomain.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "until", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPolicyLogEntriesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListPolicyLogEntries lists observed policy decisions.", + "tags": [ + "Network policies" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "networkPoliciesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListPolicyLogEntriesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListPolicyLogEntriesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListPolicyLogEntries lists observed policy decisions.", + "tags": [ + "Network policies" + ], + "url": "/reference/api/sandboxes/latest/operations/listPolicyLogEntriesInOwnerScope/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1policy-logs/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListPolicyLogEntriesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1policy-logs/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/processes'", + "curlNotes": [], + "deprecated": null, + "description": "ListProcesses lists processes in creation order.", + "id": "listProcesses", + "line": 1431, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1processes/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an optional continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1processes/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nsession and state.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1processes/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + } + ], + "path": "/v1/processes", + "pointer": "/paths/~1v1~1processes/get", + "raw": { + "description": "ListProcesses lists processes in creation order.", + "operationId": "listProcesses", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an optional continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nsession and state.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListProcessesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ListProcesses lists processes in creation order.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListProcessesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListProcessesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ListProcesses lists processes in creation order.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/listProcesses/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListProcessesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/processes'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateProcess starts a durable interactive process and returns its resource name.", + "id": "createProcess", + "line": 1491, + "method": "POST", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1processes/post/parameters/0", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/processes", + "pointer": "/paths/~1v1~1processes/post", + "raw": { + "description": "CreateProcess starts a durable interactive process and returns its resource name.", + "operationId": "createProcess", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateProcessRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Process" + } + } + }, + "description": "Success" + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "CreateProcess starts a durable interactive process and returns its resource name.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/CreateProcessRequest", + "url": "/reference/api/sandboxes/latest/schemas/CreateProcessRequest/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Process", + "url": "/reference/api/sandboxes/latest/schemas/Process/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateProcessRequest" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "CreateProcess starts a durable interactive process and returns its resource name.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/createProcess/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateProcessRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Process" + }, + "status": "201" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/processes/exec'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Exec runs one command to completion. A retry after transport failure may run it again.\nAction at the collection root: it runs a command to completion instead of creating a\nprocess a caller can address.", + "id": "exec", + "line": 1557, + "method": "POST", + "parameters": [], + "path": "/v1/processes/exec", + "pointer": "/paths/~1v1~1processes~1exec/post", + "raw": { + "description": "Exec runs one command to completion. A retry after transport failure may run it again.\nAction at the collection root: it runs a command to completion instead of creating a\nprocess a caller can address.", + "operationId": "exec", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Exec runs one command to completion.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ExecRequest", + "url": "/reference/api/sandboxes/latest/schemas/ExecRequest/" + }, + { + "ref": "#/components/schemas/ExecResponse", + "url": "/reference/api/sandboxes/latest/schemas/ExecResponse/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/ExecRequest" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Exec runs one command to completion.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/exec/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1exec/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/ExecRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1exec/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ExecResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1exec/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/processes/\u003cPROCESS\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetProcess reads one process by its endpoint-scoped resource name.", + "id": "getProcess", + "line": 1600, + "method": "GET", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "pointer": "/paths/~1v1~1processes~1{process}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/processes/{process}", + "pointer": "/paths/~1v1~1processes~1{process}/get", + "raw": { + "description": "GetProcess reads one process by its endpoint-scoped resource name.", + "operationId": "getProcess", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Process" + } + } + }, + "description": "Success" + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "GetProcess reads one process by its endpoint-scoped resource name.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Process", + "url": "/reference/api/sandboxes/latest/schemas/Process/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "GetProcess reads one process by its endpoint-scoped resource name.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/getProcess/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Process" + }, + "status": "200" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "", + "curl": "", + "curlNotes": [ + "Use a WebSocket client with the subprotocol, credential transport, and frame schemas documented for this operation." + ], + "deprecated": null, + "description": "Interact binds the complete process name from the path to the first Attach frame.\nA conflicting name is INVALID_ARGUMENT before any attach.", + "id": "interact", + "line": 1656, + "method": "GET", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "pointer": "/paths/~1v1~1processes~1{process}~1interact/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/processes/{process}/interact", + "pointer": "/paths/~1v1~1processes~1{process}~1interact/get", + "raw": { + "description": "Interact binds the complete process name from the path to the first Attach frame.\nA conflicting name is INVALID_ARGUMENT before any attach.", + "operationId": "interact", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "101": { + "description": "The connection becomes a sandboxes.v1 session: one InteractRequest per inbound text frame and one ProcessOutput per outbound one. Path parameters identify the target; the first attach frame must agree. Refusals after upgrade carry an error frame followed by a close code." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + }, + { + "sandboxWebSocketBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Interact binds the complete process name from the path to the first Attach frame.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-request-schema": { + "$ref": "#/components/schemas/InteractRequest" + }, + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-response-schema": { + "$ref": "#/components/schemas/ProcessOutput" + }, + "x-sbx-serving-surface": "sandboxEndpoint", + "x-websocket": { + "authentication": "Use exactly one sandbox-scoped Authorization bearer credential or, when endpoint credentialTransports advertises webSocketSubprotocol, offer sandboxes.bearer.v1. followed by canonical unpadded base64url of that credential alongside sandboxes.v1. The decoded token is limited to 4096 bytes. The server echoes only sandboxes.v1; mixed or duplicate credentials, query credentials and cookie-only authentication are refused.", + "bearerSubprotocolPrefix": "sandboxes.bearer.v1.", + "browser": "Open a WSS endpoint using its scoped credential. Browsers may send cookies; the server ignores them as authority and permits cross-origin explicit bearer authentication. Browser WebSocket errors do not expose pre-upgrade HTTP status or bodies; only post-upgrade Error frames are typed. No reconnect or input replay is automatic.", + "closeCode": { + "1000": "The service ended the stream, or the caller cancelled it.", + "1002": "The handshake negotiated no subprotocol.", + "1003": "A frame arrived as binary; every frame is text.", + "1007": "A frame was not the public JSON request message.", + "1008": "The service refused with a 4xx error, or the endpoint credential expired.", + "1009": "A frame exceeded the route’s frame limit.", + "1011": "The service failed with a code the front door maps to a 5xx." + }, + "errorFrame": { + "$ref": "#/components/schemas/Error" + }, + "firstRequestField": "attach", + "maxBearerTokenBytes": 4096, + "preUpgradeStatus": { + "400": "The request has an invalid subprotocol offer, mixed or malformed credentials, an oversized credential, or a query parameter.", + "401": "The scoped credential is missing, invalid or expired.", + "403": "The scoped credential does not grant this endpoint permission.", + "404": "The scoped credential does not address this sandbox endpoint." + }, + "reconnect": "Acquire a fresh scoped credential, open a new connection, and send attach with attach.resumeFrom set to the last received chunk.streamSequence. Resume replays output only; never replay stdin or process creation.", + "requestFrame": { + "$ref": "#/components/schemas/InteractRequest" + }, + "responseFrame": { + "$ref": "#/components/schemas/ProcessOutput" + }, + "resumeRequestField": "attach.resumeFrom", + "resumeResponseField": "chunk.streamSequence", + "subprotocol": "sandboxes.v1", + "terminalFrame": "The last text frame before a close carries the one error body, because a close reason holds at most 123 bytes." + } + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/InteractRequest", + "url": "/reference/api/sandboxes/latest/schemas/InteractRequest/" + }, + { + "ref": "#/components/schemas/ProcessOutput", + "url": "/reference/api/sandboxes/latest/schemas/ProcessOutput/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + }, + { + "sandboxWebSocketBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Interact binds the complete process name from the path to the first Attach frame.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/interact/", + "variants": [ + { + "description": "The connection becomes a sandboxes.v1 session: one InteractRequest per inbound text frame and one ProcessOutput per outbound one. Path parameters identify the target; the first attach frame must agree. Refusals after upgrade carry an error frame followed by a close code.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1processes~1{process}~1interact/get/responses/101", + "status": "101" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1interact/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://sandbox.invalid/v1/processes/\u003cPROCESS\u003e/output'", + "curlNotes": [], + "deprecated": null, + "description": "ReadOutput returns one page of retained output after a stream_sequence, the\nsame cursor Interact resumes from, so a REST client can read what a process printed.", + "id": "readOutput", + "line": 1730, + "method": "GET", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "resume_from returns output after this stream_sequence; 0 means from the start.\nMissing output after this point fails with FAILED_PRECONDITION, as for Attach.", + "in": "query", + "name": "resumeFrom", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get/parameters/1", + "required": false, + "schema": { + "format": "int64", + "title": "resume_from", + "type": [ + "integer", + "string" + ] + } + }, + { + "description": "max_bytes is a soft bound on the page's data: whole chunks only, and the first retained\nchunk always fits so a caller always advances. 0 means the backend's default page.", + "in": "query", + "name": "maxBytes", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get/parameters/2", + "required": false, + "schema": { + "title": "max_bytes", + "type": "integer" + } + } + ], + "path": "/v1/processes/{process}/output", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get", + "raw": { + "description": "ReadOutput returns one page of retained output after a stream_sequence, the\nsame cursor Interact resumes from, so a REST client can read what a process printed.", + "operationId": "readOutput", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "resume_from returns output after this stream_sequence; 0 means from the start.\nMissing output after this point fails with FAILED_PRECONDITION, as for Attach.", + "in": "query", + "name": "resumeFrom", + "required": false, + "schema": { + "format": "int64", + "title": "resume_from", + "type": [ + "integer", + "string" + ] + } + }, + { + "description": "max_bytes is a soft bound on the page's data: whole chunks only, and the first retained\nchunk always fits so a caller always advances. 0 means the backend's default page.", + "in": "query", + "name": "maxBytes", + "required": false, + "schema": { + "title": "max_bytes", + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadOutputResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ReadOutputResponse", + "url": "/reference/api/sandboxes/latest/schemas/ReadOutputResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "ReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/readOutput/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ReadOutputResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1output/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://sandbox.invalid/v1/processes/\u003cPROCESS\u003e/signal'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "Signal sends one signal to an existing process.\nAction: a signal is delivered to a running process and leaves no representation to\nreplace.", + "id": "signal", + "line": 1794, + "method": "POST", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "pointer": "/paths/~1v1~1processes~1{process}~1signal/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/processes/{process}/signal", + "pointer": "/paths/~1v1~1processes~1{process}~1signal/post", + "raw": { + "description": "Signal sends one signal to an existing process.\nAction: a signal is delivered to a running process and leaves no representation to\nreplace.", + "operationId": "signal", + "parameters": [ + { + "description": "The process id.", + "in": "path", + "name": "process", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "SignalRequest sends one signal.", + "properties": { + "signal": { + "$ref": "#/components/schemas/ProcessSignal", + "description": "signal is the signal to send.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "signal" + ], + "title": "SignalRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignalResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Signal sends one signal to an existing process.", + "tags": [ + "Processes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "data", + "x-sbx-required-permissions": [ + "sandboxesExec" + ], + "x-sbx-serving-surface": "sandboxEndpoint" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ProcessSignal", + "url": "/reference/api/sandboxes/latest/schemas/ProcessSignal/" + }, + { + "ref": "#/components/schemas/SignalResponse", + "url": "/reference/api/sandboxes/latest/schemas/SignalResponse/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "SignalRequest sends one signal.", + "properties": { + "signal": { + "$ref": "#/components/schemas/ProcessSignal", + "description": "signal is the signal to send.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "signal" + ], + "title": "SignalRequest", + "type": "object" + }, + "security": [ + { + "sandboxBearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "url": "{endpoint}", + "variables": { + "endpoint": { + "default": "https://sandbox.invalid", + "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." + } + } + } + ], + "summary": "Signal sends one signal to an existing process.", + "tags": [ + "Processes" + ], + "url": "/reference/api/sandboxes/latest/operations/signal/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1signal/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "SignalRequest sends one signal.", + "properties": { + "signal": { + "$ref": "#/components/schemas/ProcessSignal", + "description": "signal is the signal to send.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "signal" + ], + "title": "SignalRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1signal/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/SignalResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1processes~1{process}~1signal/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes'", + "curlNotes": [], + "deprecated": null, + "description": "ListSandboxes lists sandboxes in the caller's owner scope.", + "id": "listSandboxes", + "line": 1856, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1sandboxes/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1sandboxes/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name, uid, status and agent.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1sandboxes/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1sandboxes/get/parameters/3", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/sandboxes", + "pointer": "/paths/~1v1~1sandboxes/get", + "raw": { + "description": "ListSandboxes lists sandboxes in the caller's owner scope.", + "operationId": "listSandboxes", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name, uid, status and agent.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSandboxesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListSandboxes lists sandboxes in the caller's owner scope.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListSandboxesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListSandboxesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListSandboxes lists sandboxes in the caller's owner scope.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/listSandboxes/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListSandboxesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateSandbox admits a sandbox. Unknown fields at any level are rejected before\nreplay lookup, reservation, policy binding, or workload effects.", + "id": "createSandbox", + "line": 1919, + "method": "POST", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes/post/parameters/0", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/sandboxes", + "pointer": "/paths/~1v1~1sandboxes/post", + "raw": { + "description": "CreateSandbox admits a sandbox. Unknown fields at any level are rejected before\nreplay lookup, reservation, policy binding, or workload effects.", + "operationId": "createSandbox", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSandboxRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nKit admission was refused; an available settled report describes the rejected fields.\n\nThe Idempotency-Key was already used with a different payload." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateSandbox admits a sandbox.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [ + { + "permission": "mcpWrite", + "requestFieldPresent": "mcp" + } + ], + "x-sbx-error-details": { + "KitFieldOutcomeReport": { + "$ref": "#/components/schemas/KitFieldOutcomeReport" + } + }, + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "Kit admission was refused; an available settled report describes the rejected fields.", + "detailType": "docker.sandboxes.v1.KitFieldOutcomeReport" + }, + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesCreate" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Sandbox" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CreateSandboxRequest", + "url": "/reference/api/sandboxes/latest/schemas/CreateSandboxRequest/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/KitFieldOutcomeReport", + "url": "/reference/api/sandboxes/latest/schemas/KitFieldOutcomeReport/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateSandboxRequest" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateSandbox admits a sandbox.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/createSandbox/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateSandboxRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/post/responses/201/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + }, + "status": "201" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + }, + "status": "202" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nKit admission was refused; an available settled report describes the rejected fields.\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetSandbox reads one sandbox by its resource name.", + "id": "getSandbox", + "line": 2034, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get", + "raw": { + "description": "GetSandbox reads one sandbox by its resource name.", + "operationId": "getSandbox", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sandbox" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetSandbox reads one sandbox by its resource name.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetSandbox reads one sandbox by its resource name.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/getSandbox/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Sandbox" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeleteSandbox returns the deleting resource while work remains, or an empty message when absent.", + "id": "deleteSandbox", + "line": 2095, + "method": "DELETE", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/parameters/2", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + }, + { + "description": "force requests deletion even when the backend would otherwise refuse the state.", + "in": "query", + "name": "force", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/parameters/3", + "required": false, + "schema": { + "title": "force", + "type": "boolean" + } + } + ], + "path": "/v1/sandboxes/{sandbox}", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete", + "raw": { + "description": "DeleteSandbox returns the deleting resource while work remains, or an empty message when absent.", + "operationId": "deleteSandbox", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + }, + { + "description": "force requests deletion even when the backend would otherwise refuse the state.", + "in": "query", + "name": "force", + "required": false, + "schema": { + "title": "force", + "type": "boolean" + } + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "deleting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "204": { + "description": "Success. The response carries no body." + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The Idempotency-Key was already used with a different payload." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeleteSandbox returns the deleting resource while work remains, or an empty message when absent.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesDelete" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Sandbox" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeleteSandbox returns the deleting resource while work remains, or an empty message when absent.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/deleteSandbox/", + "variants": [ + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "deleting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + }, + "status": "202" + }, + { + "description": "Success. The response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/204", + "status": "204" + }, + { + "description": "The Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PATCH \\\n --header 'Idempotency-Key: \u003cIDEMPOTENCY-KEY\u003e' \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "UpdateSandbox changes only the display label under the observed etag.\nIts resource name, backing identity and child addresses remain unchanged.", + "id": "updateSandbox", + "line": 2215, + "method": "PATCH", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/parameters/1", + "required": true, + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "minLength": 1, + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/parameters/2", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch", + "raw": { + "description": "UpdateSandbox changes only the display label under the observed etag.\nIts resource name, backing identity and child addresses remain unchanged.", + "operationId": "updateSandbox", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "required": true, + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "minLength": 1, + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "UpdateSandboxRequest changes only the display label under the observed etag.", + "properties": { + "displayName": { + "description": "display_name must be present and retains the existing scoped label rules.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]+$", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "displayName" + ], + "title": "UpdateSandboxRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sandbox" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The Idempotency-Key was already used with a different payload." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "UpdateSandbox changes only the display label under the observed etag.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesRename" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "UpdateSandboxRequest changes only the display label under the observed etag.", + "properties": { + "displayName": { + "description": "display_name must be present and retains the existing scoped label rules.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]+$", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "displayName" + ], + "title": "UpdateSandboxRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "UpdateSandbox changes only the display label under the observed etag.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/updateSandbox/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "UpdateSandboxRequest changes only the display label under the observed etag.", + "properties": { + "displayName": { + "description": "display_name must be present and retains the existing scoped label rules.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]+$", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "displayName" + ], + "title": "UpdateSandboxRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Sandbox" + }, + "status": "200" + }, + { + "description": "The Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}/patch/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/endpoint-credentials'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateEndpointCredential grants short-lived access to one sandbox endpoint.\nIssuance checks current authority and never stores a token in the replay ledger.", + "id": "createEndpointCredential", + "line": 2338, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1endpoint-credentials/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/endpoint-credentials", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1endpoint-credentials/post", + "raw": { + "description": "CreateEndpointCredential grants short-lived access to one sandbox endpoint.\nIssuance checks current authority and never stores a token in the replay ledger.", + "operationId": "createEndpointCredential", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "CreateEndpointCredentialRequest requests only endpoint permissions the caller holds.", + "properties": { + "permissions": { + "description": "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite.", + "items": { + "$ref": "#/components/schemas/Permission", + "enum": [ + "sandboxesExec", + "sandboxesFilesRead", + "sandboxesFilesWrite" + ] + }, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl defaults to five minutes; supplied durations are clamped to one second through five minutes." + } + }, + "required": [ + "permissions" + ], + "title": "CreateEndpointCredentialRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndpointCredential" + } + } + }, + "description": "Success", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + } + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateEndpointCredential grants short-lived access to one sandbox endpoint.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesCredential" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Duration", + "url": "/reference/api/sandboxes/latest/schemas/Duration/" + }, + { + "ref": "#/components/schemas/EndpointCredential", + "url": "/reference/api/sandboxes/latest/schemas/EndpointCredential/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Permission", + "url": "/reference/api/sandboxes/latest/schemas/Permission/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "CreateEndpointCredentialRequest requests only endpoint permissions the caller holds.", + "properties": { + "permissions": { + "description": "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite.", + "items": { + "$ref": "#/components/schemas/Permission", + "enum": [ + "sandboxesExec", + "sandboxesFilesRead", + "sandboxesFilesWrite" + ] + }, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl defaults to five minutes; supplied durations are clamped to one second through five minutes." + } + }, + "required": [ + "permissions" + ], + "title": "CreateEndpointCredentialRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateEndpointCredential grants short-lived access to one sandbox endpoint.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/createEndpointCredential/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1endpoint-credentials/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "CreateEndpointCredentialRequest requests only endpoint permissions the caller holds.", + "properties": { + "permissions": { + "description": "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite.", + "items": { + "$ref": "#/components/schemas/Permission", + "enum": [ + "sandboxesExec", + "sandboxesFilesRead", + "sandboxesFilesWrite" + ] + }, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl defaults to five minutes; supplied durations are clamped to one second through five minutes." + } + }, + "required": [ + "permissions" + ], + "title": "CreateEndpointCredentialRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1endpoint-credentials/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/EndpointCredential" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1endpoint-credentials/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/mcp-gateway'", + "curlNotes": [], + "deprecated": null, + "description": "GetMcpGateway reads gateway state for the sandbox.", + "id": "getMcpGateway", + "line": 2414, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/mcp-gateway", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway/get", + "raw": { + "description": "GetMcpGateway reads gateway state for the sandbox.", + "operationId": "getMcpGateway", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/McpGateway" + } + } + }, + "description": "Success" + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetMcpGateway reads gateway state for the sandbox.", + "tags": [ + "MCP gateways" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "mcpRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/McpGateway", + "url": "/reference/api/sandboxes/latest/schemas/McpGateway/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetMcpGateway reads gateway state for the sandbox.", + "tags": [ + "MCP gateways" + ], + "url": "/reference/api/sandboxes/latest/operations/getMcpGateway/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/McpGateway" + }, + "status": "200" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/mcp-gateway/servers'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "AddMcpGatewayServer adds one server to an existing ready gateway.", + "id": "addMcpGatewayServer", + "line": 2464, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway~1servers/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/mcp-gateway/servers", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway~1servers/post", + "raw": { + "description": "AddMcpGatewayServer adds one server to an existing ready gateway.", + "operationId": "addMcpGatewayServer", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "AddMcpGatewayServerRequest adds one server to an existing ready gateway.", + "properties": { + "server": { + "description": "server is the external configured key; a supplied registration must define this same key.\nA mismatch refuses FAILED_PRECONDITION before changing the gateway.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "server" + ], + "title": "AddMcpGatewayServerRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddMcpGatewayServerResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "AddMcpGatewayServer adds one server to an existing ready gateway.", + "tags": [ + "MCP gateways" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "mcpWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/AddMcpGatewayServerResponse", + "url": "/reference/api/sandboxes/latest/schemas/AddMcpGatewayServerResponse/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "AddMcpGatewayServerRequest adds one server to an existing ready gateway.", + "properties": { + "server": { + "description": "server is the external configured key; a supplied registration must define this same key.\nA mismatch refuses FAILED_PRECONDITION before changing the gateway.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "server" + ], + "title": "AddMcpGatewayServerRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "AddMcpGatewayServer adds one server to an existing ready gateway.", + "tags": [ + "MCP gateways" + ], + "url": "/reference/api/sandboxes/latest/operations/addMcpGatewayServer/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway~1servers/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "AddMcpGatewayServerRequest adds one server to an existing ready gateway.", + "properties": { + "server": { + "description": "server is the external configured key; a supplied registration must define this same key.\nA mismatch refuses FAILED_PRECONDITION before changing the gateway.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "server" + ], + "title": "AddMcpGatewayServerRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway~1servers/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/AddMcpGatewayServerResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1mcp-gateway~1servers/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/network-policies'", + "curlNotes": [], + "deprecated": null, + "description": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "id": "getNetworkPolicies", + "line": 2517, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1network-policies/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Omitted versions accept only destination.v1; an unsupported representation fails closed.", + "in": "query", + "name": "acceptedSelectorVersions", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1network-policies/get/parameters/1", + "required": false, + "schema": { + "items": { + "description": "", + "minLength": 1, + "type": "string" + }, + "maxItems": 8, + "title": "accepted_selector_versions", + "type": "array", + "uniqueItems": true + } + } + ], + "path": "/v1/sandboxes/{sandbox}/network-policies", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1network-policies/get", + "raw": { + "description": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "operationId": "getNetworkPolicies", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Omitted versions accept only destination.v1; an unsupported representation fails closed.", + "in": "query", + "name": "acceptedSelectorVersions", + "required": false, + "schema": { + "items": { + "description": "", + "minLength": 1, + "type": "string" + }, + "maxItems": 8, + "title": "accepted_selector_versions", + "type": "array", + "uniqueItems": true + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetNetworkPoliciesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "tags": [ + "Network policies" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "networkPoliciesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/GetNetworkPoliciesResponse", + "url": "/reference/api/sandboxes/latest/schemas/GetNetworkPoliciesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetNetworkPolicies returns effective and exact views of the same installed generation.", + "tags": [ + "Network policies" + ], + "url": "/reference/api/sandboxes/latest/operations/getNetworkPolicies/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1network-policies/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/GetNetworkPoliciesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1network-policies/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/policy-logs?since=2023-01-15T01%3A30%3A15.01Z\u0026until=2023-01-15T01%3A30%3A15.01Z'", + "curlNotes": [], + "deprecated": null, + "description": "ListPolicyLogEntries lists observed policy decisions.", + "id": "listPolicyLogEntries", + "line": 2565, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/1", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/2", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable field is\ndomain.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/3", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "since", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/4", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "until", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/parameters/5", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/policy-logs", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get", + "raw": { + "description": "ListPolicyLogEntries lists observed policy decisions.", + "operationId": "listPolicyLogEntries", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable field is\ndomain.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + }, + { + "description": "An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z.", + "in": "query", + "name": "until", + "required": false, + "schema": { + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPolicyLogEntriesResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListPolicyLogEntries lists observed policy decisions.", + "tags": [ + "Network policies" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "networkPoliciesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListPolicyLogEntriesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListPolicyLogEntriesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListPolicyLogEntries lists observed policy decisions.", + "tags": [ + "Network policies" + ], + "url": "/reference/api/sandboxes/latest/operations/listPolicyLogEntries/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListPolicyLogEntriesResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1policy-logs/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/ports'", + "curlNotes": [], + "deprecated": null, + "description": "ListPorts lists currently published ports for one sandbox.", + "id": "listPorts", + "line": 2646, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/ports", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/get", + "raw": { + "description": "ListPorts lists currently published ports for one sandbox.", + "operationId": "listPorts", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPortsResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListPorts lists currently published ports for one sandbox.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListPortsResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListPortsResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListPorts lists currently published ports for one sandbox.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/listPorts/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListPortsResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/ports'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreatePort makes one sandbox port reachable outside the sandbox.", + "id": "createPort", + "line": 2680, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/ports", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post", + "raw": { + "description": "CreatePort makes one sandbox port reachable outside the sandbox.", + "operationId": "createPort", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "CreatePortRequest publishes one sandbox port.", + "properties": { + "port": { + "$ref": "#/components/schemas/CreatePortRequestPortInput", + "description": "port is the requested publication." + } + }, + "required": [ + "port" + ], + "title": "CreatePortRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Port" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "alreadyExists": { + "summary": "The sandbox already publishes this port number.", + "value": { + "code": "alreadyExists", + "message": "The sandbox already publishes this port number." + } + }, + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe sandbox already publishes this port number.\n\nThe Idempotency-Key was already used with a different payload." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreatePort makes one sandbox port reachable outside the sandbox.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "ALREADY_EXISTS", + "description": "The sandbox already publishes this port number." + }, + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesPorts" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CreatePortRequestPortInput", + "url": "/reference/api/sandboxes/latest/schemas/CreatePortRequestPortInput/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Port", + "url": "/reference/api/sandboxes/latest/schemas/Port/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "CreatePortRequest publishes one sandbox port.", + "properties": { + "port": { + "$ref": "#/components/schemas/CreatePortRequestPortInput", + "description": "port is the requested publication." + } + }, + "required": [ + "port" + ], + "title": "CreatePortRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreatePort makes one sandbox port reachable outside the sandbox.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/createPort/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "CreatePortRequest publishes one sandbox port.", + "properties": { + "port": { + "$ref": "#/components/schemas/CreatePortRequestPortInput", + "description": "port is the requested publication." + } + }, + "required": [ + "port" + ], + "title": "CreatePortRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Port" + }, + "status": "201" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe sandbox already publishes this port number.\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "alreadyExists", + "text": "{\n \"code\": \"alreadyExists\",\n \"message\": \"The sandbox already publishes this port number.\"\n}", + "value": { + "code": "alreadyExists", + "message": "The sandbox already publishes this port number." + } + }, + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/ports/\u003cPORT\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetPort reads one published port by its resource name.", + "id": "getPort", + "line": 2769, + "method": "GET", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The port id.", + "in": "path", + "name": "port", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/parameters/2", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/ports/{port}", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get", + "raw": { + "description": "GetPort reads one published port by its resource name.", + "operationId": "getPort", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The port id.", + "in": "path", + "name": "port", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Port" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "No publication exists for this port resource name.", + "value": { + "code": "notFound", + "message": "No publication exists for this port resource name." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No publication exists for this port resource name." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetPort reads one published port by its resource name.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "No publication exists for this port resource name." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Port", + "url": "/reference/api/sandboxes/latest/schemas/Port/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetPort reads one published port by its resource name.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/getPort/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Port" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/responses/304", + "status": "304" + }, + { + "description": "No publication exists for this port resource name.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"No publication exists for this port resource name.\"\n}", + "value": { + "code": "notFound", + "message": "No publication exists for this port resource name." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/ports/\u003cPORT\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeletePort withdraws one published port. A name that is not published\nsucceeds, so a retried delete reports the same result as the first.", + "id": "deletePort", + "line": 2836, + "method": "DELETE", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The port id.", + "in": "path", + "name": "port", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/parameters/1", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/parameters/2", + "required": true, + "schema": { + "description": "etag identifies the publication version the caller intends to delete.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/ports/{port}", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete", + "raw": { + "description": "DeletePort withdraws one published port. A name that is not published\nsucceeds, so a retried delete reports the same result as the first.", + "operationId": "deletePort", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The port id.", + "in": "path", + "name": "port", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag identifies the publication version the caller intends to delete.", + "title": "If-Match", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Success. The response carries no body." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeletePort withdraws one published port.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesPorts" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeletePort withdraws one published port.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/deletePort/", + "variants": [ + { + "description": "Success. The response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/responses/204", + "status": "204" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ports~1{port}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/renew-timeout'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "RenewSandboxTimeout sets a TTL when timeout renewal is supported. The TTL starts at acceptance, and the response returns the new expires_at with the sandbox's timeout configuration preserved.\nAction: the TTL restarts at acceptance, so the result is not a value the caller could\nPUT.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "renewSandboxTimeout", + "line": 2910, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/renew-timeout", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post", + "raw": { + "description": "RenewSandboxTimeout sets a TTL when timeout renewal is supported. The TTL starts at acceptance, and the response returns the new expires_at with the sandbox's timeout configuration preserved.\nAction: the TTL restarts at acceptance, so the result is not a value the caller could\nPUT.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "renewSandboxTimeout", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "RenewSandboxTimeoutRequest sets a new remaining TTL.", + "properties": { + "timeout": { + "$ref": "#/components/schemas/Duration", + "description": "timeout is the new TTL relative to server acceptance time." + } + }, + "required": [ + "timeout" + ], + "title": "RenewSandboxTimeoutRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sandbox" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "RenewSandboxTimeout sets a TTL when timeout renewal is supported.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesLifecycle" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Duration", + "url": "/reference/api/sandboxes/latest/schemas/Duration/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "RenewSandboxTimeoutRequest sets a new remaining TTL.", + "properties": { + "timeout": { + "$ref": "#/components/schemas/Duration", + "description": "timeout is the new TTL relative to server acceptance time." + } + }, + "required": [ + "timeout" + ], + "title": "RenewSandboxTimeoutRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "RenewSandboxTimeout sets a TTL when timeout renewal is supported.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/renewSandboxTimeout/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "RenewSandboxTimeoutRequest sets a new remaining TTL.", + "properties": { + "timeout": { + "$ref": "#/components/schemas/Duration", + "description": "timeout is the new TTL relative to server acceptance time." + } + }, + "required": [ + "timeout" + ], + "title": "RenewSandboxTimeoutRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Sandbox" + }, + "status": "200" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1renew-timeout/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/snapshots'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateSnapshot checkpoints a running sandbox; a stopped source is rejected.", + "id": "createSnapshot", + "line": 2985, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/snapshots", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post", + "raw": { + "description": "CreateSnapshot checkpoints a running sandbox; a stopped source is rejected.", + "operationId": "createSnapshot", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "CreateSnapshotRequest captures one running sandbox.", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode selects disk-only or memory plus disk capture. A value this\nenum does not define is rejected, never coerced to a capture." + }, + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + } + }, + "required": [ + "displayName" + ], + "title": "CreateSnapshotRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Snapshot" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "creating" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Snapshot" + }, + { + "properties": { + "status": { + "enum": [ + "creating" + ] + } + }, + "required": [ + "status" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateSnapshot checkpoints a running sandbox; a stopped source is rejected.", + "tags": [ + "Snapshots" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "snapshotsWrite" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Snapshot" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CaptureMode", + "url": "/reference/api/sandboxes/latest/schemas/CaptureMode/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Snapshot", + "url": "/reference/api/sandboxes/latest/schemas/Snapshot/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "CreateSnapshotRequest captures one running sandbox.", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode selects disk-only or memory plus disk capture. A value this\nenum does not define is rejected, never coerced to a capture." + }, + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + } + }, + "required": [ + "displayName" + ], + "title": "CreateSnapshotRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateSnapshot checkpoints a running sandbox; a stopped source is rejected.", + "tags": [ + "Snapshots" + ], + "url": "/reference/api/sandboxes/latest/operations/createSnapshot/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "CreateSnapshotRequest captures one running sandbox.", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode selects disk-only or memory plus disk capture. A value this\nenum does not define is rejected, never coerced to a capture." + }, + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + } + }, + "required": [ + "displayName" + ], + "title": "CreateSnapshotRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/responses/201/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Snapshot" + }, + { + "not": { + "properties": { + "status": { + "enum": [ + "creating" + ] + } + }, + "required": [ + "status" + ] + } + } + ] + }, + "status": "201" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Snapshot" + }, + { + "properties": { + "status": { + "enum": [ + "creating" + ] + } + }, + "required": [ + "status" + ] + } + ] + }, + "status": "202" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1snapshots/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/ssh-certificates'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "IssueSSHCert signs a caller-held public key for sandbox SSH access.\nA create: each call mints one certificate under the sandbox's certificate collection.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "issueSSHCert", + "line": 3108, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/ssh-certificates", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post", + "raw": { + "description": "IssueSSHCert signs a caller-held public key for sandbox SSH access.\nA create: each call mints one certificate under the sandbox's certificate collection.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "issueSSHCert", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "IssueSSHCertRequest asks the backend to sign a caller-held public key.", + "properties": { + "publicKey": { + "description": "public_key is the caller-held SSH public key.", + "minLength": 1, + "type": "string" + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl is the requested certificate lifetime." + } + }, + "required": [ + "publicKey" + ], + "title": "IssueSSHCertRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IssueSSHCertResponse" + } + } + }, + "description": "Success", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "IssueSSHCert signs a caller-held public key for sandbox SSH access.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesSsh" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Duration", + "url": "/reference/api/sandboxes/latest/schemas/Duration/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/IssueSSHCertResponse", + "url": "/reference/api/sandboxes/latest/schemas/IssueSSHCertResponse/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "IssueSSHCertRequest asks the backend to sign a caller-held public key.", + "properties": { + "publicKey": { + "description": "public_key is the caller-held SSH public key.", + "minLength": 1, + "type": "string" + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl is the requested certificate lifetime." + } + }, + "required": [ + "publicKey" + ], + "title": "IssueSSHCertRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "IssueSSHCert signs a caller-held public key for sandbox SSH access.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/issueSSHCert/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "IssueSSHCertRequest asks the backend to sign a caller-held public key.", + "properties": { + "publicKey": { + "description": "public_key is the caller-held SSH public key.", + "minLength": 1, + "type": "string" + }, + "ttl": { + "$ref": "#/components/schemas/Duration", + "description": "ttl is the requested certificate lifetime." + } + }, + "required": [ + "publicKey" + ], + "title": "IssueSSHCertRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "const": "no-store", + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/IssueSSHCertResponse" + }, + "status": "201" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": { + "Cache-Control": { + "required": true, + "schema": { + "enum": [ + "no-store" + ], + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1ssh-certificates/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/start'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.\nAction: a lifecycle transition is not a representation a caller can PUT.", + "id": "startSandbox", + "line": 3214, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/2", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/start", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post", + "raw": { + "description": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.\nAction: a lifecycle transition is not a representation a caller can PUT.", + "operationId": "startSandbox", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "StartSandboxRequest starts or resumes a sandbox.", + "properties": {}, + "title": "StartSandboxRequest", + "type": "object" + } + } + }, + "required": false + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The Idempotency-Key was already used with a different payload." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesLifecycle" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Sandbox" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "StartSandboxRequest starts or resumes a sandbox.", + "properties": {}, + "title": "StartSandboxRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/startSandbox/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/requestBody/content/application~1json", + "required": false, + "schema": { + "additionalProperties": false, + "description": "StartSandboxRequest starts or resumes a sandbox.", + "properties": {}, + "title": "StartSandboxRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/200/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + }, + "status": "200" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + }, + "status": "202" + }, + { + "description": "The Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/sandboxes/\u003cSANDBOX\u003e/stop'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it.\nAction: a lifecycle transition is not a representation a caller can PUT.", + "id": "stopSandbox", + "line": 3361, + "method": "POST", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/parameters/2", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/sandboxes/{sandbox}/stop", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post", + "raw": { + "description": "StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it.\nAction: a lifecycle transition is not a representation a caller can PUT.", + "operationId": "stopSandbox", + "parameters": [ + { + "description": "The sandbox id.", + "in": "path", + "name": "sandbox", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "StopSandboxRequest stops a sandbox; a backend advertising memory preservation hibernates it.", + "properties": {}, + "title": "StopSandboxRequest", + "type": "object" + } + } + }, + "required": false + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "stopping" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "stopping" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The Idempotency-Key was already used with a different payload." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it.", + "tags": [ + "Sandboxes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "sandboxesLifecycle" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Sandbox" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "StopSandboxRequest stops a sandbox; a backend advertising memory preservation hibernates it.", + "properties": {}, + "title": "StopSandboxRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it.", + "tags": [ + "Sandboxes" + ], + "url": "/reference/api/sandboxes/latest/operations/stopSandbox/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/requestBody/content/application~1json", + "required": false, + "schema": { + "additionalProperties": false, + "description": "StopSandboxRequest stops a sandbox; a backend advertising memory preservation hibernates it.", + "properties": {}, + "title": "StopSandboxRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/200/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "stopping" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + }, + "status": "200" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "stopping" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + }, + "status": "202" + }, + { + "description": "The Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1stop/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/secrets'", + "curlNotes": [], + "deprecated": null, + "description": "ListSecrets lists secret metadata in the caller's owner scope.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "listSecrets", + "line": 3508, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1secrets/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1secrets/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1secrets/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1secrets/get/parameters/3", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/secrets", + "pointer": "/paths/~1v1~1secrets/get", + "raw": { + "description": "ListSecrets lists secret metadata in the caller's owner scope.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "listSecrets", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSecretsResponse" + } + } + }, + "description": "Success" + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListSecrets lists secret metadata in the caller's owner scope.", + "tags": [ + "Secrets" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "secretsRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListSecretsResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListSecretsResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListSecrets lists secret metadata in the caller's owner scope.", + "tags": [ + "Secrets" + ], + "url": "/reference/api/sandboxes/latest/operations/listSecrets/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListSecretsResponse" + }, + "status": "200" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/get/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/secrets'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateSecret stores new secret material.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "createSecret", + "line": 3589, + "method": "POST", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1secrets/post/parameters/0", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/secrets", + "pointer": "/paths/~1v1~1secrets/post", + "raw": { + "description": "CreateSecret stores new secret material.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "createSecret", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSecretRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateSecret stores new secret material.", + "tags": [ + "Secrets" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + }, + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "secretsWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CreateSecretRequest", + "url": "/reference/api/sandboxes/latest/schemas/CreateSecretRequest/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Secret", + "url": "/reference/api/sandboxes/latest/schemas/Secret/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateSecretRequest" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateSecret stores new secret material.", + "tags": [ + "Secrets" + ], + "url": "/reference/api/sandboxes/latest/operations/createSecret/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateSecretRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Secret" + }, + "status": "201" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/post/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/secrets/\u003cSECRET\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetSecret reads one secret's metadata; material is never returned.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "getSecret", + "line": 3671, + "method": "GET", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/secrets/{secret}", + "pointer": "/paths/~1v1~1secrets~1{secret}/get", + "raw": { + "description": "GetSecret reads one secret's metadata; material is never returned.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "getSecret", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetSecret reads one secret's metadata; material is never returned.", + "tags": [ + "Secrets" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + }, + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "secretsRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Secret", + "url": "/reference/api/sandboxes/latest/schemas/Secret/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetSecret reads one secret's metadata; material is never returned.", + "tags": [ + "Secrets" + ], + "url": "/reference/api/sandboxes/latest/operations/getSecret/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Secret" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request PUT \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/secrets/\u003cSECRET\u003e'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "UpdateSecret replaces secret metadata and material.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "updateSecret", + "line": 3749, + "method": "PUT", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/parameters/2", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/secrets/{secret}", + "pointer": "/paths/~1v1~1secrets~1{secret}/put", + "raw": { + "description": "UpdateSecret replaces secret metadata and material.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "updateSecret", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSecretBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The Idempotency-Key was already used with a different payload." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "UpdateSecret replaces secret metadata and material.", + "tags": [ + "Secrets" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + }, + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "secretsWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Secret", + "url": "/reference/api/sandboxes/latest/schemas/Secret/" + }, + { + "ref": "#/components/schemas/UpdateSecretBody", + "url": "/reference/api/sandboxes/latest/schemas/UpdateSecretBody/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/UpdateSecretBody" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "UpdateSecret replaces secret metadata and material.", + "tags": [ + "Secrets" + ], + "url": "/reference/api/sandboxes/latest/operations/updateSecret/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/UpdateSecretBody" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Secret" + }, + "status": "200" + }, + { + "description": "The Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/put/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/secrets/\u003cSECRET\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.\nIts response carries the credential fence receipt, so it answers 200 with a\nbody rather than the 204 an empty-response delete declares.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "deleteSecret", + "line": 3870, + "method": "DELETE", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/parameters/1", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/secrets/{secret}", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete", + "raw": { + "description": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.\nIts response carries the credential fence receipt, so it answers 200 with a\nbody rather than the 204 an empty-response delete declares.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "deleteSecret", + "parameters": [ + { + "description": "The secret id.", + "in": "path", + "name": "secret", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteSecretResponse" + } + } + }, + "description": "Success" + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.", + "tags": [ + "Secrets" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "secretsWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/DeleteSecretResponse", + "url": "/reference/api/sandboxes/latest/schemas/DeleteSecretResponse/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.", + "tags": [ + "Secrets" + ], + "url": "/reference/api/sandboxes/latest/operations/deleteSecret/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/DeleteSecretResponse" + }, + "status": "200" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1secrets~1{secret}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/snapshots'", + "curlNotes": [], + "deprecated": null, + "description": "ListSnapshots lists snapshots in the caller's owner scope.", + "id": "listSnapshots", + "line": 3962, + "method": "GET", + "parameters": [ + { + "description": "(OPTIONAL) sandbox is the complete resource name, in the form sandboxes/{sandbox}.", + "in": "query", + "name": "sandbox", + "pointer": "/paths/~1v1~1snapshots/get/parameters/0", + "required": false, + "schema": { + "pattern": "^(?:sandboxes/[^/]+)?$", + "title": "sandbox", + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1snapshots/get/parameters/1", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1snapshots/get/parameters/2", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1snapshots/get/parameters/3", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1snapshots/get/parameters/4", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/snapshots", + "pointer": "/paths/~1v1~1snapshots/get", + "raw": { + "description": "ListSnapshots lists snapshots in the caller's owner scope.", + "operationId": "listSnapshots", + "parameters": [ + { + "description": "(OPTIONAL) sandbox is the complete resource name, in the form sandboxes/{sandbox}.", + "in": "query", + "name": "sandbox", + "required": false, + "schema": { + "pattern": "^(?:sandboxes/[^/]+)?$", + "title": "sandbox", + "type": "string" + } + }, + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSnapshotsResponse" + } + } + }, + "description": "Success" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListSnapshots lists snapshots in the caller's owner scope.", + "tags": [ + "Snapshots" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "snapshotsRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListSnapshotsResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListSnapshotsResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListSnapshots lists snapshots in the caller's owner scope.", + "tags": [ + "Snapshots" + ], + "url": "/reference/api/sandboxes/latest/operations/listSnapshots/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListSnapshotsResponse" + }, + "status": "200" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/snapshots/\u003cSNAPSHOT\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetSnapshot reads one snapshot by its resource name.", + "id": "getSnapshot", + "line": 4034, + "method": "GET", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/snapshots/{snapshot}", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get", + "raw": { + "description": "GetSnapshot reads one snapshot by its resource name.", + "operationId": "getSnapshot", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Snapshot" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetSnapshot reads one snapshot by its resource name.", + "tags": [ + "Snapshots" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "snapshotsRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Snapshot", + "url": "/reference/api/sandboxes/latest/schemas/Snapshot/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetSnapshot reads one snapshot by its resource name.", + "tags": [ + "Snapshots" + ], + "url": "/reference/api/sandboxes/latest/operations/getSnapshot/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Snapshot" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://connect.docker.com/sandboxes/v1/snapshots/\u003cSNAPSHOT\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds.", + "id": "deleteSnapshot", + "line": 4095, + "method": "DELETE", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/parameters/1", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/snapshots/{snapshot}", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete", + "raw": { + "description": "DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds.", + "operationId": "deleteSnapshot", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Success. The response carries no body." + }, + "409": { + "content": { + "application/json": { + "examples": { + "deletion_content_lease_held": { + "summary": "An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "value": { + "code": "failedPrecondition", + "message": "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + } + }, + "deletion_preparation_incomplete": { + "summary": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.", + "value": { + "code": "failedPrecondition", + "message": "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\n\nAn admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds.", + "tags": [ + "Snapshots" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.", + "reason": "deletion_preparation_incomplete" + }, + { + "code": "FAILED_PRECONDITION", + "description": "An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "reason": "deletion_content_lease_held" + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "snapshotsWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds.", + "tags": [ + "Snapshots" + ], + "url": "/reference/api/sandboxes/latest/operations/deleteSnapshot/", + "variants": [ + { + "description": "Success. The response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/responses/204", + "status": "204" + }, + { + "description": "The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\n\nAn admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "deletion_content_lease_held", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." + } + }, + { + "language": "json", + "name": "deletion_preparation_incomplete", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/snapshots/\u003cSNAPSHOT\u003e/restore'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "RestoreSnapshot forks a new sandbox from a snapshot.\nAction: a restore creates a sandbox, so the snapshot in the path is the source and not\nthe created resource.", + "id": "restoreSnapshot", + "line": 4190, + "method": "POST", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/parameters/1", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/snapshots/{snapshot}/restore", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post", + "raw": { + "description": "RestoreSnapshot forks a new sandbox from a snapshot.\nAction: a restore creates a sandbox, so the snapshot in the path is the source and not\nthe created resource.", + "operationId": "restoreSnapshot", + "parameters": [ + { + "description": "The snapshot id.", + "in": "path", + "name": "snapshot", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": false, + "description": "RestoreSnapshotRequest creates a new sandbox from one snapshot.", + "properties": { + "displayName": { + "description": "(OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID.", + "maxLength": 64, + "pattern": "^[a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "title": "RestoreSnapshotRequest", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "202": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + } + } + }, + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "RestoreSnapshot forks a new sandbox from a snapshot.", + "tags": [ + "Snapshots" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "snapshotsRead", + "sandboxesCreate" + ], + "x-sbx-resource-response": { + "$ref": "#/components/schemas/Sandbox" + }, + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Sandbox", + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + } + ], + "requestSchema": { + "additionalProperties": false, + "description": "RestoreSnapshotRequest creates a new sandbox from one snapshot.", + "properties": { + "displayName": { + "description": "(OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID.", + "maxLength": 64, + "pattern": "^[a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "title": "RestoreSnapshotRequest", + "type": "object" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "RestoreSnapshot forks a new sandbox from a snapshot.", + "tags": [ + "Snapshots" + ], + "url": "/reference/api/sandboxes/latest/operations/restoreSnapshot/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/requestBody/content/application~1json", + "required": true, + "schema": { + "additionalProperties": false, + "description": "RestoreSnapshotRequest creates a new sandbox from one snapshot.", + "properties": { + "displayName": { + "description": "(OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID.", + "maxLength": 64, + "pattern": "^[a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "title": "RestoreSnapshotRequest", + "type": "object" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/responses/201/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "not": { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + } + ] + }, + "status": "201" + }, + { + "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/responses/202/content/application~1json", + "required": null, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Sandbox" + }, + { + "properties": { + "core": { + "properties": { + "status": { + "enum": [ + "creating", + "starting" + ] + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "core" + ] + } + ] + }, + "status": "202" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1snapshots~1{snapshot}~1restore/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/volumes'", + "curlNotes": [], + "deprecated": null, + "description": "ListVolumes lists volumes in the caller's owner scope.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "listVolumes", + "line": 4312, + "method": "GET", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "pointer": "/paths/~1v1~1volumes/get/parameters/0", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "pointer": "/paths/~1v1~1volumes/get/parameters/1", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "pointer": "/paths/~1v1~1volumes/get/parameters/2", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "pointer": "/paths/~1v1~1volumes/get/parameters/3", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "path": "/v1/volumes", + "pointer": "/paths/~1v1~1volumes/get", + "raw": { + "description": "ListVolumes lists volumes in the caller's owner scope.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "listVolumes", + "parameters": [ + { + "description": "page_size is an optional page size.\n\nOmitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty.", + "in": "query", + "name": "pageSize", + "required": false, + "schema": { + "title": "page_size", + "type": "integer" + } + }, + { + "description": "page_token is an opaque continuation token.", + "in": "query", + "name": "pageToken", + "required": false, + "schema": { + "title": "page_token", + "type": "string" + } + }, + { + "description": "filter is comma-separated exact-match field=value terms; the portable fields are\nname, display_name and uid.", + "in": "query", + "name": "filter", + "required": false, + "schema": { + "title": "filter", + "type": "string" + } + }, + { + "description": "order_by is a single order field with optional direction; the portable fields are\ncreated_at and name.", + "in": "query", + "name": "orderBy", + "required": false, + "schema": { + "title": "order_by", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListVolumesResponse" + } + } + }, + "description": "Success" + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "ListVolumes lists volumes in the caller's owner scope.", + "tags": [ + "Volumes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "volumesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/ListVolumesResponse", + "url": "/reference/api/sandboxes/latest/schemas/ListVolumesResponse/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "ListVolumes lists volumes in the caller's owner scope.", + "tags": [ + "Volumes" + ], + "url": "/reference/api/sandboxes/latest/operations/listVolumes/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/ListVolumesResponse" + }, + "status": "200" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/get/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-binary @request-body \\\n 'https://connect.docker.com/sandboxes/v1/volumes'", + "curlNotes": [ + "Prepare request-body using the selected media type and schema." + ], + "deprecated": null, + "description": "CreateVolume creates a persistent volume.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "createVolume", + "line": 4393, + "method": "POST", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "pointer": "/paths/~1v1~1volumes/post/parameters/0", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "path": "/v1/volumes", + "pointer": "/paths/~1v1~1volumes/post", + "raw": { + "description": "CreateVolume creates a persistent volume.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "createVolume", + "parameters": [ + { + "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", + "in": "header", + "name": "Idempotency-Key", + "schema": { + "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", + "title": "Idempotency-Key", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateVolumeRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Volume" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "409": { + "content": { + "application/json": { + "examples": { + "failedPrecondition": { + "summary": "The Idempotency-Key was already used with a different payload.", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "CreateVolume creates a persistent volume.", + "tags": [ + "Volumes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + }, + { + "code": "FAILED_PRECONDITION", + "description": "The Idempotency-Key was already used with a different payload." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "volumesWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/CreateVolumeRequest", + "url": "/reference/api/sandboxes/latest/schemas/CreateVolumeRequest/" + }, + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Volume", + "url": "/reference/api/sandboxes/latest/schemas/Volume/" + } + ], + "requestSchema": { + "$ref": "#/components/schemas/CreateVolumeRequest" + }, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "CreateVolume creates a persistent volume.", + "tags": [ + "Volumes" + ], + "url": "/reference/api/sandboxes/latest/operations/createVolume/", + "variants": [ + { + "description": null, + "direction": "Request", + "examples": [], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/post/requestBody/content/application~1json", + "required": true, + "schema": { + "$ref": "#/components/schemas/CreateVolumeRequest" + }, + "status": "" + }, + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/post/responses/201/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Volume" + }, + "status": "201" + }, + { + "description": "Creation conflicts with an existing resource (ALREADY_EXISTS).\n\nThe Idempotency-Key was already used with a different payload.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "failedPrecondition", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"The Idempotency-Key was already used with a different payload.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "The Idempotency-Key was already used with a different payload." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/post/responses/409/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "409" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/post/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes/post/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "application/json", + "curl": "curl \\\n --request GET \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n --header 'Accept: application/json' \\\n 'https://connect.docker.com/sandboxes/v1/volumes/\u003cVOLUME\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "GetVolume reads one volume by its resource name.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "getVolume", + "line": 4475, + "method": "GET", + "parameters": [ + { + "description": "The volume id.", + "in": "path", + "name": "volume", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/parameters/1", + "schema": { + "type": "string" + } + } + ], + "path": "/v1/volumes/{volume}", + "pointer": "/paths/~1v1~1volumes~1{volume}/get", + "raw": { + "description": "GetVolume reads one volume by its resource name.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "getVolume", + "parameters": [ + { + "description": "The volume id.", + "in": "path", + "name": "volume", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Volume" + } + } + }, + "description": "Success", + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body." + }, + "404": { + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "The target is absent or not visible within the caller's scope.", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The target is absent or not visible within the caller's scope." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "GetVolume reads one volume by its resource name.", + "tags": [ + "Volumes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "NOT_FOUND", + "description": "The target is absent or not visible within the caller's scope." + }, + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "volumesRead" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "ref": "#/components/schemas/Volume", + "url": "/reference/api/sandboxes/latest/schemas/Volume/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "GetVolume reads one volume by its resource name.", + "tags": [ + "Volumes" + ], + "url": "/reference/api/sandboxes/latest/operations/getVolume/", + "variants": [ + { + "description": "Success", + "direction": "Response", + "examples": [], + "headers": { + "ETag": { + "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", + "schema": { + "type": "string" + } + } + }, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/responses/200/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Volume" + }, + "status": "200" + }, + { + "description": "The resource's etag equals the If-None-Match value, so this response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/responses/304", + "status": "304" + }, + { + "description": "The target is absent or not visible within the caller's scope.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "notFound", + "text": "{\n \"code\": \"notFound\",\n \"message\": \"The target is absent or not visible within the caller's scope.\"\n}", + "value": { + "code": "notFound", + "message": "The target is absent or not visible within the caller's scope." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/responses/404/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "404" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/get/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + }, + { + "acceptMedia": "", + "curl": "curl \\\n --request DELETE \\\n --header 'If-Match: \u003cIF-MATCH\u003e' \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n 'https://connect.docker.com/sandboxes/v1/volumes/\u003cVOLUME\u003e'", + "curlNotes": [], + "deprecated": null, + "description": "DeleteVolume deletes a volume; deleting an already absent volume succeeds.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "id": "deleteVolume", + "line": 4553, + "method": "DELETE", + "parameters": [ + { + "description": "The volume id.", + "in": "path", + "name": "volume", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/parameters/0", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/parameters/1", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "path": "/v1/volumes/{volume}", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete", + "raw": { + "description": "DeleteVolume deletes a volume; deleting an already absent volume succeeds.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", + "operationId": "deleteVolume", + "parameters": [ + { + "description": "The volume id.", + "in": "path", + "name": "volume", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", + "title": "If-Match", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Success. The response carries no body." + }, + "412": { + "content": { + "application/json": { + "examples": { + "etag_mismatch": { + "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + }, + "428": { + "content": { + "application/json": { + "examples": { + "etag_required": { + "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." + }, + "501": { + "content": { + "application/json": { + "examples": { + "unimplemented": { + "summary": "This operation is not available on this service.", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "This operation is not available on this service." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "The structured Error body identifies the failure with a stable code and optional typed details." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "DeleteVolume deletes a volume; deleting an already absent volume succeeds.", + "tags": [ + "Volumes" + ], + "x-sbx-authenticated-only": false, + "x-sbx-conditional-permissions": [], + "x-sbx-error-responses": [ + { + "code": "UNIMPLEMENTED", + "description": "This operation is not available on this service." + } + ], + "x-sbx-plane": "control", + "x-sbx-required-permissions": [ + "volumesWrite" + ], + "x-sbx-serving-surface": "management" + }, + "references": [ + { + "ref": "#/components/schemas/Error", + "url": "/reference/api/sandboxes/latest/schemas/Error/" + } + ], + "requestSchema": null, + "security": [ + { + "bearer": [] + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "summary": "DeleteVolume deletes a volume; deleting an already absent volume succeeds.", + "tags": [ + "Volumes" + ], + "url": "/reference/api/sandboxes/latest/operations/deleteVolume/", + "variants": [ + { + "description": "Success. The response carries no body.", + "direction": "Response", + "examples": [], + "headers": null, + "media": "", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/responses/204", + "status": "204" + }, + { + "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_mismatch", + "text": "{\n \"code\": \"failedPrecondition\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/docker.sandboxes.v1.EtagMismatch\",\n \"currentEtag\": \"v2\"\n }\n ],\n \"message\": \"etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.\"\n}", + "value": { + "code": "failedPrecondition", + "details": [ + { + "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "currentEtag": "v2" + } + ], + "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/responses/412/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "412" + }, + { + "description": "No precondition was sent. The body carries failedPrecondition naming etag_required.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "etag_required", + "text": "{\n \"code\": \"failedPrecondition\",\n \"message\": \"etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required.\"\n}", + "value": { + "code": "failedPrecondition", + "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/responses/428/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "428" + }, + { + "description": "This operation is not available on this service.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "unimplemented", + "text": "{\n \"code\": \"unimplemented\",\n \"message\": \"This operation is not available on this service.\"\n}", + "value": { + "code": "unimplemented", + "message": "This operation is not available on this service." + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/responses/501/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "501" + }, + { + "description": "The structured Error body identifies the failure with a stable code and optional typed details.", + "direction": "Response", + "examples": [ + { + "language": "json", + "name": "Schema example", + "text": "{\n \"code\": \"notFound\",\n \"details\": [],\n \"message\": \"sandbox not found\"\n}", + "value": { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + } + ], + "headers": null, + "media": "application/json", + "pointer": "/paths/~1v1~1volumes~1{volume}/delete/responses/default/content/application~1json", + "required": null, + "schema": { + "$ref": "#/components/schemas/Error" + }, + "status": "default" + } + ] + } + ], + "owner": "docker/sbx-api", + "product": "sandboxes", + "schemaCount": 550, + "schemaURLs": { + "#/components/schemas/AddMcpGatewayServerResponse": "/reference/api/sandboxes/latest/schemas/AddMcpGatewayServerResponse/", + "#/components/schemas/AppliedKit": "/reference/api/sandboxes/latest/schemas/AppliedKit/", + "#/components/schemas/AttachmentMode": "/reference/api/sandboxes/latest/schemas/AttachmentMode/", + "#/components/schemas/AttributedRule": "/reference/api/sandboxes/latest/schemas/AttributedRule/", + "#/components/schemas/BadRequest": "/reference/api/sandboxes/latest/schemas/BadRequest/", + "#/components/schemas/BadRequestErrorDetail": "/reference/api/sandboxes/latest/schemas/BadRequestErrorDetail/", + "#/components/schemas/BadRequestFieldViolation": "/reference/api/sandboxes/latest/schemas/BadRequestFieldViolation/", + "#/components/schemas/CaptureMode": "/reference/api/sandboxes/latest/schemas/CaptureMode/", + "#/components/schemas/CreateImageRequest": "/reference/api/sandboxes/latest/schemas/CreateImageRequest/", + "#/components/schemas/CreatePortRequestPortInput": "/reference/api/sandboxes/latest/schemas/CreatePortRequestPortInput/", + "#/components/schemas/CreateProcessRequest": "/reference/api/sandboxes/latest/schemas/CreateProcessRequest/", + "#/components/schemas/CreateSandboxRequest": "/reference/api/sandboxes/latest/schemas/CreateSandboxRequest/", + "#/components/schemas/CreateSecretRequest": "/reference/api/sandboxes/latest/schemas/CreateSecretRequest/", + "#/components/schemas/CreateVolumeRequest": "/reference/api/sandboxes/latest/schemas/CreateVolumeRequest/", + "#/components/schemas/CredentialFenceReceipt": "/reference/api/sandboxes/latest/schemas/CredentialFenceReceipt/", + "#/components/schemas/CustomInjection": "/reference/api/sandboxes/latest/schemas/CustomInjection/", + "#/components/schemas/CustomSecretMaterial": "/reference/api/sandboxes/latest/schemas/CustomSecretMaterial/", + "#/components/schemas/DebugInfo": "/reference/api/sandboxes/latest/schemas/DebugInfo/", + "#/components/schemas/DebugInfoErrorDetail": "/reference/api/sandboxes/latest/schemas/DebugInfoErrorDetail/", + "#/components/schemas/DeleteSecretResponse": "/reference/api/sandboxes/latest/schemas/DeleteSecretResponse/", + "#/components/schemas/Duration": "/reference/api/sandboxes/latest/schemas/Duration/", + "#/components/schemas/EffectiveCoreLifecycle": "/reference/api/sandboxes/latest/schemas/EffectiveCoreLifecycle/", + "#/components/schemas/EffectiveFeatures": "/reference/api/sandboxes/latest/schemas/EffectiveFeatures/", + "#/components/schemas/EffectiveManagedVolumes": "/reference/api/sandboxes/latest/schemas/EffectiveManagedVolumes/", + "#/components/schemas/EffectiveNetworkPolicy": "/reference/api/sandboxes/latest/schemas/EffectiveNetworkPolicy/", + "#/components/schemas/EffectiveTimeouts": "/reference/api/sandboxes/latest/schemas/EffectiveTimeouts/", + "#/components/schemas/EffectiveVolumeAttachment": "/reference/api/sandboxes/latest/schemas/EffectiveVolumeAttachment/", + "#/components/schemas/EndpointAuthentication": "/reference/api/sandboxes/latest/schemas/EndpointAuthentication/", + "#/components/schemas/EndpointAuthenticationScheme": "/reference/api/sandboxes/latest/schemas/EndpointAuthenticationScheme/", + "#/components/schemas/EndpointCredential": "/reference/api/sandboxes/latest/schemas/EndpointCredential/", + "#/components/schemas/EndpointCredentialTransport": "/reference/api/sandboxes/latest/schemas/EndpointCredentialTransport/", + "#/components/schemas/Error": "/reference/api/sandboxes/latest/schemas/Error/", + "#/components/schemas/ErrorCode": "/reference/api/sandboxes/latest/schemas/ErrorCode/", + "#/components/schemas/ErrorDetail": "/reference/api/sandboxes/latest/schemas/ErrorDetail/", + "#/components/schemas/ErrorInfo": "/reference/api/sandboxes/latest/schemas/ErrorInfo/", + "#/components/schemas/ErrorInfoErrorDetail": "/reference/api/sandboxes/latest/schemas/ErrorInfoErrorDetail/", + "#/components/schemas/EtagMismatch": "/reference/api/sandboxes/latest/schemas/EtagMismatch/", + "#/components/schemas/EtagMismatchErrorDetail": "/reference/api/sandboxes/latest/schemas/EtagMismatchErrorDetail/", + "#/components/schemas/ExactDestination": "/reference/api/sandboxes/latest/schemas/ExactDestination/", + "#/components/schemas/ExactDestinationKind": "/reference/api/sandboxes/latest/schemas/ExactDestinationKind/", + "#/components/schemas/ExactNetworkPolicy": "/reference/api/sandboxes/latest/schemas/ExactNetworkPolicy/", + "#/components/schemas/ExactPolicyConstant": "/reference/api/sandboxes/latest/schemas/ExactPolicyConstant/", + "#/components/schemas/ExactPolicyNode": "/reference/api/sandboxes/latest/schemas/ExactPolicyNode/", + "#/components/schemas/ExactPolicyOperands": "/reference/api/sandboxes/latest/schemas/ExactPolicyOperands/", + "#/components/schemas/ExactPolicyOrigin": "/reference/api/sandboxes/latest/schemas/ExactPolicyOrigin/", + "#/components/schemas/ExactPolicySource": "/reference/api/sandboxes/latest/schemas/ExactPolicySource/", + "#/components/schemas/ExchangeCompositionCredentialResponse": "/reference/api/sandboxes/latest/schemas/ExchangeCompositionCredentialResponse/", + "#/components/schemas/ExecRequest": "/reference/api/sandboxes/latest/schemas/ExecRequest/", + "#/components/schemas/ExecResponse": "/reference/api/sandboxes/latest/schemas/ExecResponse/", + "#/components/schemas/FeatureOptions": "/reference/api/sandboxes/latest/schemas/FeatureOptions/", + "#/components/schemas/FileError": "/reference/api/sandboxes/latest/schemas/FileError/", + "#/components/schemas/FileHeader": "/reference/api/sandboxes/latest/schemas/FileHeader/", + "#/components/schemas/FileInfo": "/reference/api/sandboxes/latest/schemas/FileInfo/", + "#/components/schemas/FileType": "/reference/api/sandboxes/latest/schemas/FileType/", + "#/components/schemas/FilesDownloadRequest": "/reference/api/sandboxes/latest/schemas/FilesDownloadRequest/", + "#/components/schemas/FilesDownloadResponse": "/reference/api/sandboxes/latest/schemas/FilesDownloadResponse/", + "#/components/schemas/FilesListResponse": "/reference/api/sandboxes/latest/schemas/FilesListResponse/", + "#/components/schemas/FilesMkdirRequest": "/reference/api/sandboxes/latest/schemas/FilesMkdirRequest/", + "#/components/schemas/FilesMkdirResponse": "/reference/api/sandboxes/latest/schemas/FilesMkdirResponse/", + "#/components/schemas/FilesMoveRequest": "/reference/api/sandboxes/latest/schemas/FilesMoveRequest/", + "#/components/schemas/FilesMoveResponse": "/reference/api/sandboxes/latest/schemas/FilesMoveResponse/", + "#/components/schemas/FilesReadFileRequest": "/reference/api/sandboxes/latest/schemas/FilesReadFileRequest/", + "#/components/schemas/FilesReadFileResponse": "/reference/api/sandboxes/latest/schemas/FilesReadFileResponse/", + "#/components/schemas/FilesRemoveResponse": "/reference/api/sandboxes/latest/schemas/FilesRemoveResponse/", + "#/components/schemas/FilesStatResponse": "/reference/api/sandboxes/latest/schemas/FilesStatResponse/", + "#/components/schemas/FilesUploadRequest": "/reference/api/sandboxes/latest/schemas/FilesUploadRequest/", + "#/components/schemas/FilesUploadResponse": "/reference/api/sandboxes/latest/schemas/FilesUploadResponse/", + "#/components/schemas/FilesWriteFileRequest": "/reference/api/sandboxes/latest/schemas/FilesWriteFileRequest/", + "#/components/schemas/FilesWriteFileResponse": "/reference/api/sandboxes/latest/schemas/FilesWriteFileResponse/", + "#/components/schemas/GetNetworkPoliciesResponse": "/reference/api/sandboxes/latest/schemas/GetNetworkPoliciesResponse/", + "#/components/schemas/Help": "/reference/api/sandboxes/latest/schemas/Help/", + "#/components/schemas/HelpErrorDetail": "/reference/api/sandboxes/latest/schemas/HelpErrorDetail/", + "#/components/schemas/HelpLink": "/reference/api/sandboxes/latest/schemas/HelpLink/", + "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest": "/reference/api/sandboxes/latest/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest/", + "#/components/schemas/Image": "/reference/api/sandboxes/latest/schemas/Image/", + "#/components/schemas/ImageBlobRef": "/reference/api/sandboxes/latest/schemas/ImageBlobRef/", + "#/components/schemas/ImageFromImage": "/reference/api/sandboxes/latest/schemas/ImageFromImage/", + "#/components/schemas/ImagePullSpec": "/reference/api/sandboxes/latest/schemas/ImagePullSpec/", + "#/components/schemas/ImagePushTarget": "/reference/api/sandboxes/latest/schemas/ImagePushTarget/", + "#/components/schemas/ImageSource": "/reference/api/sandboxes/latest/schemas/ImageSource/", + "#/components/schemas/ImageStatus": "/reference/api/sandboxes/latest/schemas/ImageStatus/", + "#/components/schemas/ImageSummary": "/reference/api/sandboxes/latest/schemas/ImageSummary/", + "#/components/schemas/InteractRequest": "/reference/api/sandboxes/latest/schemas/InteractRequest/", + "#/components/schemas/IssueSSHCertResponse": "/reference/api/sandboxes/latest/schemas/IssueSSHCertResponse/", + "#/components/schemas/KitArtifactInput": "/reference/api/sandboxes/latest/schemas/KitArtifactInput/", + "#/components/schemas/KitFieldDisposition": "/reference/api/sandboxes/latest/schemas/KitFieldDisposition/", + "#/components/schemas/KitFieldOutcome": "/reference/api/sandboxes/latest/schemas/KitFieldOutcome/", + "#/components/schemas/KitFieldOutcomeReport": "/reference/api/sandboxes/latest/schemas/KitFieldOutcomeReport/", + "#/components/schemas/KitFieldOutcomeReportErrorDetail": "/reference/api/sandboxes/latest/schemas/KitFieldOutcomeReportErrorDetail/", + "#/components/schemas/KitFieldReason": "/reference/api/sandboxes/latest/schemas/KitFieldReason/", + "#/components/schemas/KitInput": "/reference/api/sandboxes/latest/schemas/KitInput/", + "#/components/schemas/KitRef": "/reference/api/sandboxes/latest/schemas/KitRef/", + "#/components/schemas/KitStartup": "/reference/api/sandboxes/latest/schemas/KitStartup/", + "#/components/schemas/KitStartupCommand": "/reference/api/sandboxes/latest/schemas/KitStartupCommand/", + "#/components/schemas/ListImagesResponse": "/reference/api/sandboxes/latest/schemas/ListImagesResponse/", + "#/components/schemas/ListPolicyLogEntriesResponse": "/reference/api/sandboxes/latest/schemas/ListPolicyLogEntriesResponse/", + "#/components/schemas/ListPortsResponse": "/reference/api/sandboxes/latest/schemas/ListPortsResponse/", + "#/components/schemas/ListProcessesResponse": "/reference/api/sandboxes/latest/schemas/ListProcessesResponse/", + "#/components/schemas/ListSandboxesResponse": "/reference/api/sandboxes/latest/schemas/ListSandboxesResponse/", + "#/components/schemas/ListSecretsResponse": "/reference/api/sandboxes/latest/schemas/ListSecretsResponse/", + "#/components/schemas/ListSnapshotsResponse": "/reference/api/sandboxes/latest/schemas/ListSnapshotsResponse/", + "#/components/schemas/ListVolumesResponse": "/reference/api/sandboxes/latest/schemas/ListVolumesResponse/", + "#/components/schemas/LocalizedMessage": "/reference/api/sandboxes/latest/schemas/LocalizedMessage/", + "#/components/schemas/LocalizedMessageErrorDetail": "/reference/api/sandboxes/latest/schemas/LocalizedMessageErrorDetail/", + "#/components/schemas/ManagedVolumeOptions": "/reference/api/sandboxes/latest/schemas/ManagedVolumeOptions/", + "#/components/schemas/McpAuthorization": "/reference/api/sandboxes/latest/schemas/McpAuthorization/", + "#/components/schemas/McpAuthorizationStatus": "/reference/api/sandboxes/latest/schemas/McpAuthorizationStatus/", + "#/components/schemas/McpConfigurationMode": "/reference/api/sandboxes/latest/schemas/McpConfigurationMode/", + "#/components/schemas/McpConfigurationOutcome": "/reference/api/sandboxes/latest/schemas/McpConfigurationOutcome/", + "#/components/schemas/McpConfigurationReport": "/reference/api/sandboxes/latest/schemas/McpConfigurationReport/", + "#/components/schemas/McpConfigurationReportErrorDetail": "/reference/api/sandboxes/latest/schemas/McpConfigurationReportErrorDetail/", + "#/components/schemas/McpConfiguredServer": "/reference/api/sandboxes/latest/schemas/McpConfiguredServer/", + "#/components/schemas/McpCreateSpec": "/reference/api/sandboxes/latest/schemas/McpCreateSpec/", + "#/components/schemas/McpGateway": "/reference/api/sandboxes/latest/schemas/McpGateway/", + "#/components/schemas/McpGatewayState": "/reference/api/sandboxes/latest/schemas/McpGatewayState/", + "#/components/schemas/McpServer": "/reference/api/sandboxes/latest/schemas/McpServer/", + "#/components/schemas/McpServerType": "/reference/api/sandboxes/latest/schemas/McpServerType/", + "#/components/schemas/NetworkPolicy": "/reference/api/sandboxes/latest/schemas/NetworkPolicy/", + "#/components/schemas/NetworkPolicyMode": "/reference/api/sandboxes/latest/schemas/NetworkPolicyMode/", + "#/components/schemas/OAuthConfig": "/reference/api/sandboxes/latest/schemas/OAuthConfig/", + "#/components/schemas/OAuthRefreshMaterial": "/reference/api/sandboxes/latest/schemas/OAuthRefreshMaterial/", + "#/components/schemas/OutputRetention": "/reference/api/sandboxes/latest/schemas/OutputRetention/", + "#/components/schemas/Permission": "/reference/api/sandboxes/latest/schemas/Permission/", + "#/components/schemas/Platform": "/reference/api/sandboxes/latest/schemas/Platform/", + "#/components/schemas/PolicyDecision": "/reference/api/sandboxes/latest/schemas/PolicyDecision/", + "#/components/schemas/PolicyDomain": "/reference/api/sandboxes/latest/schemas/PolicyDomain/", + "#/components/schemas/PolicyLayer": "/reference/api/sandboxes/latest/schemas/PolicyLayer/", + "#/components/schemas/PolicyLogEntry": "/reference/api/sandboxes/latest/schemas/PolicyLogEntry/", + "#/components/schemas/Port": "/reference/api/sandboxes/latest/schemas/Port/", + "#/components/schemas/PreconditionFailure": "/reference/api/sandboxes/latest/schemas/PreconditionFailure/", + "#/components/schemas/PreconditionFailureErrorDetail": "/reference/api/sandboxes/latest/schemas/PreconditionFailureErrorDetail/", + "#/components/schemas/PreconditionFailureViolation": "/reference/api/sandboxes/latest/schemas/PreconditionFailureViolation/", + "#/components/schemas/Process": "/reference/api/sandboxes/latest/schemas/Process/", + "#/components/schemas/ProcessAttach": "/reference/api/sandboxes/latest/schemas/ProcessAttach/", + "#/components/schemas/ProcessChunk": "/reference/api/sandboxes/latest/schemas/ProcessChunk/", + "#/components/schemas/ProcessExited": "/reference/api/sandboxes/latest/schemas/ProcessExited/", + "#/components/schemas/ProcessHeartbeat": "/reference/api/sandboxes/latest/schemas/ProcessHeartbeat/", + "#/components/schemas/ProcessOutput": "/reference/api/sandboxes/latest/schemas/ProcessOutput/", + "#/components/schemas/ProcessSignal": "/reference/api/sandboxes/latest/schemas/ProcessSignal/", + "#/components/schemas/ProcessState": "/reference/api/sandboxes/latest/schemas/ProcessState/", + "#/components/schemas/Protocol": "/reference/api/sandboxes/latest/schemas/Protocol/", + "#/components/schemas/PtyConfig": "/reference/api/sandboxes/latest/schemas/PtyConfig/", + "#/components/schemas/PublishedPort": "/reference/api/sandboxes/latest/schemas/PublishedPort/", + "#/components/schemas/QuotaFailure": "/reference/api/sandboxes/latest/schemas/QuotaFailure/", + "#/components/schemas/QuotaFailureErrorDetail": "/reference/api/sandboxes/latest/schemas/QuotaFailureErrorDetail/", + "#/components/schemas/QuotaFailureViolation": "/reference/api/sandboxes/latest/schemas/QuotaFailureViolation/", + "#/components/schemas/RawImageStartup": "/reference/api/sandboxes/latest/schemas/RawImageStartup/", + "#/components/schemas/ReadOutputResponse": "/reference/api/sandboxes/latest/schemas/ReadOutputResponse/", + "#/components/schemas/ReceiptKind": "/reference/api/sandboxes/latest/schemas/ReceiptKind/", + "#/components/schemas/RequestInfo": "/reference/api/sandboxes/latest/schemas/RequestInfo/", + "#/components/schemas/RequestInfoErrorDetail": "/reference/api/sandboxes/latest/schemas/RequestInfoErrorDetail/", + "#/components/schemas/ResourceInfo": "/reference/api/sandboxes/latest/schemas/ResourceInfo/", + "#/components/schemas/ResourceInfoErrorDetail": "/reference/api/sandboxes/latest/schemas/ResourceInfoErrorDetail/", + "#/components/schemas/Resources": "/reference/api/sandboxes/latest/schemas/Resources/", + "#/components/schemas/RetryInfo": "/reference/api/sandboxes/latest/schemas/RetryInfo/", + "#/components/schemas/RetryInfoErrorDetail": "/reference/api/sandboxes/latest/schemas/RetryInfoErrorDetail/", + "#/components/schemas/Sandbox": "/reference/api/sandboxes/latest/schemas/Sandbox/", + "#/components/schemas/SandboxCore": "/reference/api/sandboxes/latest/schemas/SandboxCore/", + "#/components/schemas/SandboxEndpoint": "/reference/api/sandboxes/latest/schemas/SandboxEndpoint/", + "#/components/schemas/SandboxEndpointProtocol": "/reference/api/sandboxes/latest/schemas/SandboxEndpointProtocol/", + "#/components/schemas/SandboxStatus": "/reference/api/sandboxes/latest/schemas/SandboxStatus/", + "#/components/schemas/Secret": "/reference/api/sandboxes/latest/schemas/Secret/", + "#/components/schemas/SecretType": "/reference/api/sandboxes/latest/schemas/SecretType/", + "#/components/schemas/SignalResponse": "/reference/api/sandboxes/latest/schemas/SignalResponse/", + "#/components/schemas/Snapshot": "/reference/api/sandboxes/latest/schemas/Snapshot/", + "#/components/schemas/SnapshotStatus": "/reference/api/sandboxes/latest/schemas/SnapshotStatus/", + "#/components/schemas/SnapshotSummary": "/reference/api/sandboxes/latest/schemas/SnapshotSummary/", + "#/components/schemas/StartupArgv": "/reference/api/sandboxes/latest/schemas/StartupArgv/", + "#/components/schemas/StartupExecution": "/reference/api/sandboxes/latest/schemas/StartupExecution/", + "#/components/schemas/StopMemoryOutcome": "/reference/api/sandboxes/latest/schemas/StopMemoryOutcome/", + "#/components/schemas/StoredSecretOptions": "/reference/api/sandboxes/latest/schemas/StoredSecretOptions/", + "#/components/schemas/StreamType": "/reference/api/sandboxes/latest/schemas/StreamType/", + "#/components/schemas/TerminalSize": "/reference/api/sandboxes/latest/schemas/TerminalSize/", + "#/components/schemas/TimeoutAction": "/reference/api/sandboxes/latest/schemas/TimeoutAction/", + "#/components/schemas/TimeoutOptions": "/reference/api/sandboxes/latest/schemas/TimeoutOptions/", + "#/components/schemas/Timestamp": "/reference/api/sandboxes/latest/schemas/Timestamp/", + "#/components/schemas/TokenSecretMaterial": "/reference/api/sandboxes/latest/schemas/TokenSecretMaterial/", + "#/components/schemas/UnknownErrorDetail": "/reference/api/sandboxes/latest/schemas/UnknownErrorDetail/", + "#/components/schemas/UpdateSecretBody": "/reference/api/sandboxes/latest/schemas/UpdateSecretBody/", + "#/components/schemas/ValidationFieldPath": "/reference/api/sandboxes/latest/schemas/ValidationFieldPath/", + "#/components/schemas/ValidationFieldPathElement": "/reference/api/sandboxes/latest/schemas/ValidationFieldPathElement/", + "#/components/schemas/ValidationFieldType": "/reference/api/sandboxes/latest/schemas/ValidationFieldType/", + "#/components/schemas/ValidationViolation": "/reference/api/sandboxes/latest/schemas/ValidationViolation/", + "#/components/schemas/ValidationViolations": "/reference/api/sandboxes/latest/schemas/ValidationViolations/", + "#/components/schemas/ValidationViolationsErrorDetail": "/reference/api/sandboxes/latest/schemas/ValidationViolationsErrorDetail/", + "#/components/schemas/Volume": "/reference/api/sandboxes/latest/schemas/Volume/", + "#/components/schemas/VolumeAttachment": "/reference/api/sandboxes/latest/schemas/VolumeAttachment/" + }, + "schemas": [ + { + "name": "AddMcpGatewayServerResponse", + "pointer": "/components/schemas/AddMcpGatewayServerResponse", + "schema": { + "description": "AddMcpGatewayServerResponse returns the added or already-present server.", + "properties": { + "server": { + "$ref": "#/components/schemas/McpServer", + "description": "server is the gateway server." + } + }, + "title": "AddMcpGatewayServerResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/AddMcpGatewayServerResponse/" + }, + { + "name": "AppliedKit", + "pointer": "/components/schemas/AppliedKit", + "schema": { + "description": "AppliedKit records kit content that was applied to a sandbox.", + "properties": { + "appliedAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "applied_at is when the kit became active." + }, + "digest": { + "description": "digest identifies the exact applied content.", + "type": "string" + }, + "kind": { + "description": "kind is normalized to \"sandbox\" or \"mixin\".", + "enum": [ + "sandbox", + "mixin" + ], + "type": "string" + }, + "ref": { + "description": "ref is the kit reference supplied or resolved by the backend.", + "type": "string" + } + }, + "required": [ + "kind" + ], + "title": "AppliedKit", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/AppliedKit/" + }, + { + "name": "AttachmentMode", + "pointer": "/components/schemas/AttachmentMode", + "schema": { + "description": "AttachmentMode fixes attachment ownership independently of backend placement.\n\nValues:\nunspecified: unspecified selects exclusive read-write attachment.\nexclusive: exclusive permits one sandbox to attach the volume read-write.", + "enum": [ + "unspecified", + "exclusive" + ], + "title": "AttachmentMode", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/AttachmentMode/" + }, + { + "name": "AttributedRule", + "pointer": "/components/schemas/AttributedRule", + "schema": { + "description": "AttributedRule reports a rule and the layer that supplied it.", + "properties": { + "layer": { + "$ref": "#/components/schemas/PolicyLayer", + "description": "layer identifies where the rule came from." + }, + "network": { + "description": "network is the network name or CIDR.", + "type": "string" + } + }, + "title": "AttributedRule", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/AttributedRule/" + }, + { + "name": "BadRequest", + "pointer": "/components/schemas/BadRequest", + "schema": { + "description": "Describes violations in a client request. This error type focuses on the\nsyntactic aspects of the request.", + "properties": { + "fieldViolations": { + "description": "Describes all violations in a client request.", + "items": { + "$ref": "#/components/schemas/BadRequestFieldViolation" + }, + "type": "array" + } + }, + "title": "BadRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/BadRequest/" + }, + { + "name": "BadRequestErrorDetail", + "pointer": "/components/schemas/BadRequestErrorDetail", + "schema": { + "description": "Describes violations in a client request. This error type focuses on the\nsyntactic aspects of the request.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.BadRequest", + "type": "string" + }, + "fieldViolations": { + "description": "Describes all violations in a client request.", + "items": { + "$ref": "#/components/schemas/BadRequestFieldViolation" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "BadRequestErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/BadRequestErrorDetail/" + }, + { + "name": "BadRequestFieldViolation", + "pointer": "/components/schemas/BadRequestFieldViolation", + "schema": { + "description": "A message type used to describe a single bad request field.", + "properties": { + "description": { + "description": "A description of why the request element is bad.", + "type": "string" + }, + "field": { + "description": "A path that leads to a field in the request body. The value will be a\nsequence of dot-separated identifiers that identify a protocol buffer\nfield.\n\nConsider the following:\n\nmessage CreateContactRequest {\nmessage EmailAddress {\nenum Type {\nTYPE_UNSPECIFIED = 0;\nHOME = 1;\nWORK = 2;\n}\n\noptional string email = 1;\nrepeated EmailType type = 2;\n}\n\nstring full_name = 1;\nrepeated EmailAddress email_addresses = 2;\n}\n\nIn this example, in proto `field` could take one of the following values:\n\n* `full_name` for a violation in the `full_name` value\n* `email_addresses[0].email` for a violation in the `email` field of the\nfirst `email_addresses` message\n* `email_addresses[2].type[1]` for a violation in the second `type`\nvalue in the third `email_addresses` message.\n\nIn JSON, the same values are represented as:\n\n* `fullName` for a violation in the `fullName` value\n* `emailAddresses[0].email` for a violation in the `email` field of the\nfirst `emailAddresses` message\n* `emailAddresses[2].type[1]` for a violation in the second `type`\nvalue in the third `emailAddresses` message.", + "type": "string" + }, + "localizedMessage": { + "$ref": "#/components/schemas/LocalizedMessage", + "description": "Provides a localized error message for field-level errors that is safe to\nreturn to the API consumer." + }, + "reason": { + "description": "The reason of the field-level error. This is a constant value that\nidentifies the proximate cause of the field-level error. It should\nuniquely identify the type of the FieldViolation within the scope of the\nErrorInfo.domain. This should be at most 63\ncharacters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`,\nwhich represents UPPER_SNAKE_CASE.", + "type": "string" + } + }, + "title": "FieldViolation", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/BadRequestFieldViolation/" + }, + { + "name": "CaptureMode", + "pointer": "/components/schemas/CaptureMode", + "schema": { + "description": "CaptureMode selects whether captured images include memory.\n\nValues:\nunspecified: unspecified means disk-only capture.\nall: all captures memory and disk and requires memory-capture support.\ndisk: disk captures disk only.", + "enum": [ + "unspecified", + "all", + "disk" + ], + "title": "CaptureMode", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/CaptureMode/" + }, + { + "name": "CreateImageRequest", + "pointer": "/components/schemas/CreateImageRequest", + "schema": { + "allOf": [ + { + "properties": { + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + }, + "readyCmd": { + "description": "ready_cmd is used to determine readiness for raw image sandboxes.", + "items": { + "type": "string" + }, + "type": "array" + }, + "startCmd": { + "description": "start_cmd is used when the image is launched as a raw image sandbox.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + { + "oneOf": [ + { + "properties": { + "fromImage": { + "$ref": "#/components/schemas/ImageFromImage", + "description": "from_image registers an entry that will receive pushed OCI content." + } + }, + "required": [ + "fromImage" + ], + "title": "from_image", + "type": "object" + } + ] + } + ], + "description": "CreateImageRequest creates a managed image.", + "required": [ + "displayName" + ], + "title": "CreateImageRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/CreateImageRequest/" + }, + { + "name": "CreatePortRequestPortInput", + "pointer": "/components/schemas/CreatePortRequestPortInput", + "schema": { + "additionalProperties": false, + "properties": { + "number": { + "description": "(IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS.", + "format": "int32", + "maximum": 65535, + "minimum": 1, + "type": "integer" + }, + "protocol": { + "description": "(IMMUTABLE) protocol defaults to TCP when unspecified.", + "enum": [ + "unspecified", + "tcp" + ], + "title": "PortInputProtocol", + "type": "string" + } + }, + "required": [ + "number" + ], + "title": "PortInput", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CreatePortRequestPortInput/" + }, + { + "name": "CreateProcessRequest", + "pointer": "/components/schemas/CreateProcessRequest", + "schema": { + "additionalProperties": false, + "description": "CreateProcessRequest starts an interactive process.", + "properties": { + "cmd": { + "description": "cmd is the argv vector.", + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "env": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "env adds environment variables.", + "type": "object" + }, + "label": { + "description": "(OPTIONAL) label is unique within the sandbox; omission retains the server-generated default.", + "minLength": 1, + "type": [ + "string", + "null" + ] + }, + "pty": { + "$ref": "#/components/schemas/PtyConfig", + "description": "pty requests a pseudo-terminal; absence uses separate stdin/stdout/stderr pipes." + }, + "session": { + "description": "session is an optional opaque session tag stored verbatim; empty means untagged.", + "type": "string" + }, + "user": { + "description": "user is the user to run as.", + "type": "string" + }, + "workingDir": { + "description": "working_dir is the process working directory.", + "type": "string" + } + }, + "required": [ + "cmd" + ], + "title": "CreateProcessRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CreateProcessRequest/" + }, + { + "name": "CreateSandboxRequest", + "pointer": "/components/schemas/CreateSandboxRequest", + "schema": { + "allOf": [ + { + "properties": { + "agent": { + "description": "agent names an optional agent profile; unsupported profiles fail explicitly.", + "type": "string" + }, + "displayName": { + "description": "(OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID.", + "maxLength": 64, + "pattern": "^[a-zA-Z0-9_-]*$", + "type": "string" + }, + "displayNamePrefix": { + "description": "(OPTIONAL) display_name_prefix requests a generated label and excludes display_name.", + "type": "string" + }, + "environment": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "environment is non-secret environment metadata.", + "type": "object" + }, + "features": { + "$ref": "#/components/schemas/FeatureOptions", + "description": "features carries typed inputs validated before admission can have effects." + }, + "kits": { + "description": "kits are the kit inputs to apply before readiness, in composition order.", + "items": { + "$ref": "#/components/schemas/KitInput" + }, + "type": "array" + }, + "labels": { + "additionalProperties": { + "description": "", + "title": "value", + "type": "string" + }, + "description": "labels are non-secret caller-assigned key/value metadata recorded at admission.\nThis contract has no verb that changes labels afterwards.", + "maxProperties": 64, + "type": "object" + }, + "mcp": { + "$ref": "#/components/schemas/McpCreateSpec", + "description": "mcp requests an MCP gateway wired before the workload starts." + }, + "networkPolicies": { + "description": "network_policies are inline policies materialized in governance and enforced before the first guest process.\nOmission or an empty list requests no inline policies; unsupported policies fail before create effects.", + "items": { + "$ref": "#/components/schemas/NetworkPolicy" + }, + "type": "array" + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform selects an exact supported, image-compatible tuple when present.\nexplicit platform requires OS and architecture" + }, + "policyIds": { + "description": "policy_ids names existing governance policies, never raw policy content.", + "items": { + "minLength": 1, + "type": "string" + }, + "type": "array" + }, + "pullPolicy": { + "description": "pull_policy retains shared image-pull semantics and explicit support errors.", + "enum": [ + "unspecified", + "always" + ], + "title": "CreateSandboxRequestPullPolicy", + "type": "string" + }, + "resources": { + "$ref": "#/components/schemas/Resources", + "description": "resources requests CPU and memory within the selected placement's limits." + }, + "startupExecution": { + "$ref": "#/components/schemas/StartupExecution", + "description": "startup_execution is ordinary create input and persists for\nthe sandbox lifetime." + } + } + }, + { + "dependentSchemas": { + "image": { + "not": { + "anyOf": [ + { + "required": [ + "imageRef" + ] + } + ] + } + }, + "imageRef": { + "not": { + "anyOf": [ + { + "required": [ + "image" + ] + } + ] + } + } + }, + "properties": { + "image": { + "description": "image is the managed Image resource name.", + "pattern": "^images/[^/]+$", + "type": "string" + }, + "imageRef": { + "description": "image_ref is an external OCI reference, with the existing backend validation.", + "type": "string" + } + } + } + ], + "description": "CreateSandboxRequest validates typed composition intent before replay and\npersists accepted guarantees, distinct enough from legacy create that old\nservers cannot silently drop it.\ndisplay_name and display_name_prefix are mutually exclusive At most one of image, imageRef is set.", + "title": "CreateSandboxRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/CreateSandboxRequest/" + }, + { + "name": "CreateSecretRequest", + "pointer": "/components/schemas/CreateSecretRequest", + "schema": { + "allOf": [ + { + "properties": { + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + }, + "serviceType": { + "description": "service_type identifies the consuming service.", + "type": "string" + } + } + }, + { + "oneOf": [ + { + "properties": { + "custom": { + "$ref": "#/components/schemas/CustomSecretMaterial", + "description": "custom stores an opaque value with caller-authored injection metadata.\nCreateSecretRequest.service_type is server-assigned for custom\nmaterial; leave it empty." + } + }, + "required": [ + "custom" + ], + "title": "custom", + "type": "object" + }, + { + "properties": { + "oauth": { + "$ref": "#/components/schemas/OAuthRefreshMaterial", + "description": "oauth stores OAuth refresh material." + } + }, + "required": [ + "oauth" + ], + "title": "oauth", + "type": "object" + }, + { + "properties": { + "token": { + "$ref": "#/components/schemas/TokenSecretMaterial", + "description": "token stores opaque token material." + } + }, + "required": [ + "token" + ], + "title": "token", + "type": "object" + } + ] + } + ], + "description": "CreateSecretRequest stores new secret material.\nservice_type must be empty for custom material (server-assigned)", + "required": [ + "displayName" + ], + "title": "CreateSecretRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/CreateSecretRequest/" + }, + { + "name": "CreateVolumeRequest", + "pointer": "/components/schemas/CreateVolumeRequest", + "schema": { + "additionalProperties": false, + "description": "CreateVolumeRequest creates one volume.", + "properties": { + "displayName": { + "description": "display_name is a scoped label; the backend assigns the immutable resource ID.", + "minLength": 1, + "not": { + "enum": [ + ".", + ".." + ], + "type": "string" + }, + "pattern": "^[^/]+$", + "type": "string" + } + }, + "required": [ + "displayName" + ], + "title": "CreateVolumeRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CreateVolumeRequest/" + }, + { + "name": "CredentialFenceReceipt", + "pointer": "/components/schemas/CredentialFenceReceipt", + "schema": { + "description": "CredentialFenceReceipt acknowledges one completed generation without granting current use.", + "properties": { + "generation": { + "description": "generation increases for each accepted material/rule replacement on that target.", + "exclusiveMinimum": 0, + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "target": { + "description": "target is the complete Sandbox or Secret resource name bound to this receipt.", + "pattern": "^(sandboxes|secrets)/[^/]+$", + "type": "string" + } + }, + "required": [ + "target", + "generation" + ], + "title": "CredentialFenceReceipt", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CredentialFenceReceipt/" + }, + { + "name": "CustomInjection", + "pointer": "/components/schemas/CustomInjection", + "schema": { + "additionalProperties": false, + "description": "CustomInjection is caller-authored, non-secret metadata for a custom\nsecret: which exact hosts receive the value, in which header and format,\nand how the placeholder is shaped and delivered. Unlike secret material,\nreads return it.", + "properties": { + "envVar": { + "description": "env_var optionally names a sandbox environment variable that carries the\nsecret's placeholder (never the value) as a delivery convenience.", + "type": "string" + }, + "format": { + "description": "format renders the value with exactly one %s; %% escapes a literal\npercent, and any other % sequence is rejected. Empty means \"%s\".", + "type": "string" + }, + "header": { + "description": "header is the HTTP header the value is written to. Routing, framing,\nand cookie headers are rejected.", + "minLength": 1, + "type": "string" + }, + "hosts": { + "description": "hosts are exact lowercase DNS names. Wildcards, IP literals, ports,\nschemes, paths, and hosts a managed integration already serves are\nrejected.", + "items": { + "minLength": 1, + "type": "string" + }, + "maxItems": 10, + "minItems": 1, + "type": "array" + }, + "placeholderTemplate": { + "description": "placeholder_template optionally shapes the placeholder for clients that\nvalidate credential shape before sending (e.g. \"sk-corp-{rand}\"). Each\n{rand} token is expanded server-side; {rand} is the only token. Empty\nuses the backend default (\"sbx-cs-{rand}\").", + "type": "string" + } + }, + "required": [ + "hosts", + "header" + ], + "title": "CustomInjection", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CustomInjection/" + }, + { + "name": "CustomSecretMaterial", + "pointer": "/components/schemas/CustomSecretMaterial", + "schema": { + "additionalProperties": false, + "description": "CustomSecretMaterial is an opaque secret value plus its injection routing.", + "properties": { + "injection": { + "$ref": "#/components/schemas/CustomInjection", + "description": "injection is the caller-authored routing." + }, + "value": { + "description": "value is the secret value.", + "minLength": 1, + "type": "string", + "writeOnly": true + } + }, + "required": [ + "value", + "injection" + ], + "title": "CustomSecretMaterial", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/CustomSecretMaterial/" + }, + { + "name": "DebugInfo", + "pointer": "/components/schemas/DebugInfo", + "schema": { + "description": "Describes additional debugging info.", + "properties": { + "detail": { + "description": "Additional debugging information provided by the server.", + "type": "string" + }, + "stackEntries": { + "description": "The stack trace entries indicating where the error occurred.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "title": "DebugInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/DebugInfo/" + }, + { + "name": "DebugInfoErrorDetail", + "pointer": "/components/schemas/DebugInfoErrorDetail", + "schema": { + "description": "Describes additional debugging info.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.DebugInfo", + "type": "string" + }, + "detail": { + "description": "Additional debugging information provided by the server.", + "type": "string" + }, + "stackEntries": { + "description": "The stack trace entries indicating where the error occurred.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "DebugInfoErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/DebugInfoErrorDetail/" + }, + { + "name": "DeleteSecretResponse", + "pointer": "/components/schemas/DeleteSecretResponse", + "schema": { + "description": "DeleteSecretResponse acknowledges deletion and optional consumer fencing.", + "properties": { + "credentialFence": { + "$ref": "#/components/schemas/CredentialFenceReceipt", + "description": "credential_fence remains the original historical receipt after deletion or name reuse." + } + }, + "title": "DeleteSecretResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/DeleteSecretResponse/" + }, + { + "name": "Duration", + "pointer": "/components/schemas/Duration", + "schema": { + "description": "Seconds with a trailing s, for example 30s or 1.5s.", + "examples": [ + "30s", + "1.5s" + ], + "pattern": "^-?\\d+(\\.\\d{1,9})?s$", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/Duration/" + }, + { + "name": "EffectiveCoreLifecycle", + "pointer": "/components/schemas/EffectiveCoreLifecycle", + "schema": { + "description": "EffectiveCoreLifecycle is persisted at admission and cannot silently degrade.", + "properties": { + "autoResume": { + "description": "auto_resume is the configured authenticated auto-resume setting; absent means unknown.\nSnapshot readback preserves the capture-time value, not current support or a resume guarantee.", + "type": [ + "boolean", + "null" + ] + }, + "canCaptureMemory": { + "description": "can_capture_memory is this sandbox's ALL snapshot support, independently set.", + "type": "boolean" + }, + "stopMemoryOutcome": { + "$ref": "#/components/schemas/StopMemoryOutcome", + "description": "stop_memory_outcome is the selected stop/start guarantee for this sandbox.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "stopMemoryOutcome" + ], + "title": "EffectiveCoreLifecycle", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveCoreLifecycle/" + }, + { + "name": "EffectiveFeatures", + "pointer": "/components/schemas/EffectiveFeatures", + "schema": { + "description": "EffectiveFeatures is emitted only through the composition representation.", + "properties": { + "lifecycle": { + "$ref": "#/components/schemas/EffectiveCoreLifecycle", + "description": "lifecycle is required even when no optional feature is selected." + }, + "managedVolumes": { + "$ref": "#/components/schemas/EffectiveManagedVolumes", + "description": "managed_volumes records stable volume identities and concrete attachment modes." + }, + "outputRetention": { + "$ref": "#/components/schemas/OutputRetention", + "description": "output_retention is the persisted per-process reconnect guarantee." + }, + "timeouts": { + "$ref": "#/components/schemas/EffectiveTimeouts", + "description": "timeouts records frozen defaults and the currently armed deadline, if any." + } + }, + "required": [ + "lifecycle", + "outputRetention" + ], + "title": "EffectiveFeatures", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveFeatures/" + }, + { + "name": "EffectiveManagedVolumes", + "pointer": "/components/schemas/EffectiveManagedVolumes", + "schema": { + "description": "EffectiveManagedVolumes records storage that is not deleted with the sandbox.", + "properties": { + "attachments": { + "description": "attachments retains admission order and stable volume identities.", + "items": { + "$ref": "#/components/schemas/EffectiveVolumeAttachment" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "attachments" + ], + "title": "EffectiveManagedVolumes", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveManagedVolumes/" + }, + { + "name": "EffectiveNetworkPolicy", + "pointer": "/components/schemas/EffectiveNetworkPolicy", + "schema": { + "description": "EffectiveNetworkPolicy is the policy after layering and fail-closed defaults.", + "properties": { + "allowNetworks": { + "description": "allow_networks are effective allowed rules with attribution.", + "items": { + "$ref": "#/components/schemas/AttributedRule" + }, + "type": "array" + }, + "denyNetworks": { + "description": "deny_networks are effective denied rules with attribution.", + "items": { + "$ref": "#/components/schemas/AttributedRule" + }, + "type": "array" + }, + "mode": { + "$ref": "#/components/schemas/NetworkPolicyMode", + "description": "mode is the effective mode and is always concrete in conforming responses.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "mode" + ], + "title": "EffectiveNetworkPolicy", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveNetworkPolicy/" + }, + { + "name": "EffectiveTimeouts", + "pointer": "/components/schemas/EffectiveTimeouts", + "schema": { + "description": "EffectiveTimeouts retains the selected behavior and current action deadline.\nDELETE and STOP retain a resume timeout; RESTART (and its deprecated alias KEEP) does not use one", + "properties": { + "autoResume": { + "description": "auto_resume is explicit; endpoint authorization still precedes any wake-up.", + "type": "boolean" + }, + "expiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "expires_at is present only while a deadline is armed, not before first readiness or while stopped." + }, + "initialTimeout": { + "$ref": "#/components/schemas/Duration", + "description": "Records the accepted initial TTL, not the recurring interval for RESTART or KEEP." + }, + "onTimeout": { + "$ref": "#/components/schemas/TimeoutAction", + "description": "on_timeout remains the accepted disposition through renewal and restart.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "resumeTimeout": { + "$ref": "#/components/schemas/Duration", + "description": "Freezes the action's default for later starts; RESTART and KEEP manage their own interval." + } + }, + "required": [ + "onTimeout", + "initialTimeout" + ], + "title": "EffectiveTimeouts", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveTimeouts/" + }, + { + "name": "EffectiveVolumeAttachment", + "pointer": "/components/schemas/EffectiveVolumeAttachment", + "schema": { + "description": "EffectiveVolumeAttachment retains the identity, not a reusable name lookup.", + "properties": { + "mode": { + "$ref": "#/components/schemas/AttachmentMode", + "description": "mode is explicit and survives sandbox stop/start and backend restart.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "target": { + "description": "target is the accepted normalized absolute guest path.", + "minLength": 1, + "type": "string" + }, + "volume": { + "description": "volume is the resource name recorded for this reference.", + "type": "string" + }, + "volumeUid": { + "description": "volume_uid retains the observed backing incarnation when the backend provides one.", + "readOnly": true, + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "target", + "mode" + ], + "title": "EffectiveVolumeAttachment", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EffectiveVolumeAttachment/" + }, + { + "name": "EndpointAuthentication", + "pointer": "/components/schemas/EndpointAuthentication", + "schema": { + "dependentSchemas": { + "credentialTransports": { + "allOf": [ + { + "if": { + "properties": { + "scheme": { + "const": "localSocket" + } + } + }, + "then": { + "properties": { + "credentialTransports": { + "maxItems": 0 + } + } + } + } + ] + }, + "scheme": { + "allOf": [ + { + "oneOf": [ + { + "properties": { + "defaultTtl": { + "pattern": "^300([.]0{1,9})?s$" + }, + "maxTtl": { + "pattern": "^300([.]0{1,9})?s$" + }, + "scheme": { + "const": "scopedBearer" + } + }, + "required": [ + "defaultTtl", + "maxTtl" + ] + }, + { + "not": { + "anyOf": [ + { + "required": [ + "defaultTtl" + ] + }, + { + "required": [ + "maxTtl" + ] + } + ] + }, + "properties": { + "scheme": { + "const": "localSocket" + } + } + } + ] + } + ] + } + }, + "description": "EndpointAuthentication describes credential issuance without publishing a token.\nlocal sockets cannot advertise bearer credential transports\nscoped bearer discovery states the five-minute credential lifetime; local sockets carry no token lifetime", + "properties": { + "credentialTransports": { + "description": "Omission retains Authorization-header clients; browsers require an explicit subprotocol offer.", + "items": { + "$ref": "#/components/schemas/EndpointCredentialTransport" + }, + "type": "array", + "uniqueItems": true + }, + "defaultTtl": { + "$ref": "#/components/schemas/Duration", + "description": "default_ttl and max_ttl describe CreateEndpointCredential's provider policy." + }, + "maxTtl": { + "$ref": "#/components/schemas/Duration" + }, + "scheme": { + "$ref": "#/components/schemas/EndpointAuthenticationScheme", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "scheme" + ], + "title": "EndpointAuthentication", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EndpointAuthentication/" + }, + { + "name": "EndpointAuthenticationScheme", + "pointer": "/components/schemas/EndpointAuthenticationScheme", + "schema": { + "description": "Values:\nunspecified\nscopedBearer\nlocalSocket", + "enum": [ + "unspecified", + "scopedBearer", + "localSocket" + ], + "title": "EndpointAuthenticationScheme", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/EndpointAuthenticationScheme/" + }, + { + "name": "EndpointCredential", + "pointer": "/components/schemas/EndpointCredential", + "schema": { + "description": "EndpointCredential is returned once with Cache-Control: no-store; never log its token.", + "properties": { + "audience": { + "minLength": 1, + "type": "string" + }, + "expireTime": { + "$ref": "#/components/schemas/Timestamp" + }, + "permissions": { + "description": "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite.", + "items": { + "$ref": "#/components/schemas/Permission", + "enum": [ + "sandboxesExec", + "sandboxesFilesRead", + "sandboxesFilesWrite" + ] + }, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "sandbox": { + "pattern": "^sandboxes/[^/]+$", + "type": "string" + }, + "token": { + "minLength": 1, + "type": "string" + } + }, + "required": [ + "token", + "expireTime", + "permissions", + "sandbox", + "audience" + ], + "title": "EndpointCredential", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EndpointCredential/" + }, + { + "name": "EndpointCredentialTransport", + "pointer": "/components/schemas/EndpointCredentialTransport", + "schema": { + "description": "Values:\nunspecified\nauthorizationHeader\nwebSocketSubprotocol", + "enum": [ + "unspecified", + "authorizationHeader", + "webSocketSubprotocol" + ], + "title": "EndpointCredentialTransport", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/EndpointCredentialTransport/" + }, + { + "name": "Error", + "pointer": "/components/schemas/Error", + "schema": { + "description": "An HTTP refusal, resource failure, or terminal stream error. Clients preserve unknown codes and structured details.", + "examples": [ + { + "code": "notFound", + "details": [], + "message": "sandbox not found" + } + ], + "properties": { + "code": { + "anyOf": [ + { + "$ref": "#/components/schemas/ErrorCode" + }, + { + "type": "string" + } + ] + }, + "details": { + "items": { + "$ref": "#/components/schemas/ErrorDetail" + }, + "type": "array" + }, + "message": { + "type": "string" + } + }, + "required": [ + "code" + ], + "title": "Error", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Error/" + }, + { + "name": "ErrorCode", + "pointer": "/components/schemas/ErrorCode", + "schema": { + "description": "Known public failure categories. Error.code also accepts future strings.", + "enum": [ + "canceled", + "unknown", + "invalidArgument", + "deadlineExceeded", + "notFound", + "alreadyExists", + "permissionDenied", + "resourceExhausted", + "failedPrecondition", + "aborted", + "outOfRange", + "unimplemented", + "internal", + "unavailable", + "dataLoss", + "unauthenticated" + ], + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ErrorCode/" + }, + { + "name": "ErrorDetail", + "pointer": "/components/schemas/ErrorDetail", + "schema": { + "discriminator": { + "mapping": { + "type.googleapis.com/buf.validate.Violations": "#/components/schemas/ValidationViolationsErrorDetail", + "type.googleapis.com/docker.sandboxes.v1.EtagMismatch": "#/components/schemas/EtagMismatchErrorDetail", + "type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport": "#/components/schemas/KitFieldOutcomeReportErrorDetail", + "type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport": "#/components/schemas/McpConfigurationReportErrorDetail", + "type.googleapis.com/google.rpc.BadRequest": "#/components/schemas/BadRequestErrorDetail", + "type.googleapis.com/google.rpc.DebugInfo": "#/components/schemas/DebugInfoErrorDetail", + "type.googleapis.com/google.rpc.ErrorInfo": "#/components/schemas/ErrorInfoErrorDetail", + "type.googleapis.com/google.rpc.Help": "#/components/schemas/HelpErrorDetail", + "type.googleapis.com/google.rpc.LocalizedMessage": "#/components/schemas/LocalizedMessageErrorDetail", + "type.googleapis.com/google.rpc.PreconditionFailure": "#/components/schemas/PreconditionFailureErrorDetail", + "type.googleapis.com/google.rpc.QuotaFailure": "#/components/schemas/QuotaFailureErrorDetail", + "type.googleapis.com/google.rpc.RequestInfo": "#/components/schemas/RequestInfoErrorDetail", + "type.googleapis.com/google.rpc.ResourceInfo": "#/components/schemas/ResourceInfoErrorDetail", + "type.googleapis.com/google.rpc.RetryInfo": "#/components/schemas/RetryInfoErrorDetail" + }, + "propertyName": "@type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BadRequestErrorDetail" + }, + { + "$ref": "#/components/schemas/DebugInfoErrorDetail" + }, + { + "$ref": "#/components/schemas/ErrorInfoErrorDetail" + }, + { + "$ref": "#/components/schemas/HelpErrorDetail" + }, + { + "$ref": "#/components/schemas/LocalizedMessageErrorDetail" + }, + { + "$ref": "#/components/schemas/PreconditionFailureErrorDetail" + }, + { + "$ref": "#/components/schemas/QuotaFailureErrorDetail" + }, + { + "$ref": "#/components/schemas/RequestInfoErrorDetail" + }, + { + "$ref": "#/components/schemas/ResourceInfoErrorDetail" + }, + { + "$ref": "#/components/schemas/RetryInfoErrorDetail" + }, + { + "$ref": "#/components/schemas/ValidationViolationsErrorDetail" + }, + { + "$ref": "#/components/schemas/EtagMismatchErrorDetail" + }, + { + "$ref": "#/components/schemas/KitFieldOutcomeReportErrorDetail" + }, + { + "$ref": "#/components/schemas/McpConfigurationReportErrorDetail" + }, + { + "$ref": "#/components/schemas/UnknownErrorDetail" + } + ] + }, + "url": "/reference/api/sandboxes/latest/schemas/ErrorDetail/" + }, + { + "name": "ErrorInfo", + "pointer": "/components/schemas/ErrorInfo", + "schema": { + "description": "Describes the cause of the error with structured details.\n\nExample of an error when contacting the \"pubsub.googleapis.com\" API when it\nis not enabled:\n\n{ \"reason\": \"API_DISABLED\"\n\"domain\": \"googleapis.com\"\n\"metadata\": {\n\"resource\": \"projects/123\",\n\"service\": \"pubsub.googleapis.com\"\n}\n}\n\nThis response indicates that the pubsub.googleapis.com API is not enabled.\n\nExample of an error that is returned when attempting to create a Spanner\ninstance in a region that is out of stock:\n\n{ \"reason\": \"STOCKOUT\"\n\"domain\": \"spanner.googleapis.com\",\n\"metadata\": {\n\"availableRegions\": \"us-central1,us-east2\"\n}\n}", + "properties": { + "domain": { + "description": "The logical grouping to which the \"reason\" belongs. The error domain\nis typically the registered service name of the tool or product that\ngenerates the error. Example: \"pubsub.googleapis.com\". If the error is\ngenerated by some common infrastructure, the error domain must be a\nglobally unique value that identifies the infrastructure. For Google API\ninfrastructure, the error domain is \"googleapis.com\".", + "type": "string" + }, + "metadata": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "Additional structured details about this error.\n\nKeys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should\nideally be lowerCamelCase. Also, they must be limited to 64 characters in\nlength. When identifying the current value of an exceeded limit, the units\nshould be contained in the key, not the value. For example, rather than\n`{\"instanceLimit\": \"100/request\"}`, should be returned as,\n`{\"instanceLimitPerRequest\": \"100\"}`, if the client exceeds the number of\ninstances that can be created in a single (batch) request.", + "type": "object" + }, + "reason": { + "description": "The reason of the error. This is a constant value that identifies the\nproximate cause of the error. Error reasons are unique within a particular\ndomain of errors. This should be at most 63 characters and match a\nregular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents\nUPPER_SNAKE_CASE.", + "type": "string" + } + }, + "title": "ErrorInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ErrorInfo/" + }, + { + "name": "ErrorInfoErrorDetail", + "pointer": "/components/schemas/ErrorInfoErrorDetail", + "schema": { + "description": "Describes the cause of the error with structured details.\n\nExample of an error when contacting the \"pubsub.googleapis.com\" API when it\nis not enabled:\n\n{ \"reason\": \"API_DISABLED\"\n\"domain\": \"googleapis.com\"\n\"metadata\": {\n\"resource\": \"projects/123\",\n\"service\": \"pubsub.googleapis.com\"\n}\n}\n\nThis response indicates that the pubsub.googleapis.com API is not enabled.\n\nExample of an error that is returned when attempting to create a Spanner\ninstance in a region that is out of stock:\n\n{ \"reason\": \"STOCKOUT\"\n\"domain\": \"spanner.googleapis.com\",\n\"metadata\": {\n\"availableRegions\": \"us-central1,us-east2\"\n}\n}", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.ErrorInfo", + "type": "string" + }, + "domain": { + "description": "The logical grouping to which the \"reason\" belongs. The error domain\nis typically the registered service name of the tool or product that\ngenerates the error. Example: \"pubsub.googleapis.com\". If the error is\ngenerated by some common infrastructure, the error domain must be a\nglobally unique value that identifies the infrastructure. For Google API\ninfrastructure, the error domain is \"googleapis.com\".", + "type": "string" + }, + "metadata": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "Additional structured details about this error.\n\nKeys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should\nideally be lowerCamelCase. Also, they must be limited to 64 characters in\nlength. When identifying the current value of an exceeded limit, the units\nshould be contained in the key, not the value. For example, rather than\n`{\"instanceLimit\": \"100/request\"}`, should be returned as,\n`{\"instanceLimitPerRequest\": \"100\"}`, if the client exceeds the number of\ninstances that can be created in a single (batch) request.", + "type": "object" + }, + "reason": { + "description": "The reason of the error. This is a constant value that identifies the\nproximate cause of the error. Error reasons are unique within a particular\ndomain of errors. This should be at most 63 characters and match a\nregular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents\nUPPER_SNAKE_CASE.", + "type": "string" + } + }, + "required": [ + "@type" + ], + "title": "ErrorInfoErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ErrorInfoErrorDetail/" + }, + { + "name": "EtagMismatch", + "pointer": "/components/schemas/EtagMismatch", + "schema": { + "description": "EtagMismatch is the status detail a stale precondition carries, so a client learns the\ncurrent version for an explicit conflict-resolution decision.", + "properties": { + "currentEtag": { + "description": "current_etag is informational; clients must not silently retry with it.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "currentEtag" + ], + "title": "EtagMismatch", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EtagMismatch/" + }, + { + "name": "EtagMismatchErrorDetail", + "pointer": "/components/schemas/EtagMismatchErrorDetail", + "schema": { + "description": "EtagMismatch is the status detail a stale precondition carries, so a client learns the\ncurrent version for an explicit conflict-resolution decision.", + "properties": { + "@type": { + "const": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "type": "string" + }, + "currentEtag": { + "description": "current_etag is informational; clients must not silently retry with it.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "currentEtag", + "@type" + ], + "title": "EtagMismatchErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/EtagMismatchErrorDetail/" + }, + { + "name": "ExactDestination", + "pointer": "/components/schemas/ExactDestination", + "schema": { + "description": "ExactDestination uses canonical selector values, never legacy glob syntax.\ndnsLabelPrefix requires a canonical DNS label prefix and suffix", + "properties": { + "kind": { + "$ref": "#/components/schemas/ExactDestinationKind", + "description": "kind selects a matching rule; dnsLabelPrefix requires destination.v2.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "port": { + "description": "An absent port matches all numeric ports; zero is invalid when present.", + "maximum": 65535, + "minimum": 1, + "type": [ + "integer", + "null" + ] + }, + "value": { + "description": "For dnsLabelPrefix, crl.digicert.com matches a first label starting with crl\nand remaining labels exactly digicert.com; every value label is canonical ASCII DNS.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "kind", + "value" + ], + "title": "ExactDestination", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactDestination/" + }, + { + "name": "ExactDestinationKind", + "pointer": "/components/schemas/ExactDestinationKind", + "schema": { + "description": "ExactDestinationKind keeps DNS and IP-literal decisions distinct.\n\nValues:\nunspecified\ndns\ndnsLabel\ndnsSubtree\nip\ncidr\ndnsLabelPrefix", + "enum": [ + "unspecified", + "dns", + "dnsLabel", + "dnsSubtree", + "ip", + "cidr", + "dnsLabelPrefix" + ], + "title": "ExactDestinationKind", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactDestinationKind/" + }, + { + "name": "ExactNetworkPolicy", + "pointer": "/components/schemas/ExactNetworkPolicy", + "schema": { + "description": "ExactNetworkPolicy is a complete consumer-installed generation; its last node is the root.\ndnsLabelPrefix requires destination.v2", + "properties": { + "nodes": { + "description": "nodes are complete and topologically ordered; the final node is the root.", + "items": { + "$ref": "#/components/schemas/ExactPolicyNode" + }, + "maxItems": 256, + "minItems": 1, + "type": "array" + }, + "revision": { + "description": "revision binds authority, configuration and resolved conditions to the installed generation.", + "minLength": 1, + "type": "string" + }, + "selectorVersion": { + "description": "selector_version fixes matching semantics across implementations.", + "enum": [ + "destination.v1", + "destination.v2" + ], + "type": "string" + } + }, + "required": [ + "revision", + "selectorVersion", + "nodes" + ], + "title": "ExactNetworkPolicy", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactNetworkPolicy/" + }, + { + "name": "ExactPolicyConstant", + "pointer": "/components/schemas/ExactPolicyConstant", + "schema": { + "description": "ExactPolicyConstant makes both Boolean identities explicit.\n\nValues:\nunspecified\ntrue\nfalse", + "enum": [ + "unspecified", + "true", + "false" + ], + "title": "ExactPolicyConstant", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactPolicyConstant/" + }, + { + "name": "ExactPolicyNode", + "pointer": "/components/schemas/ExactPolicyNode", + "schema": { + "allOf": [ + { + "properties": { + "source": { + "$ref": "#/components/schemas/ExactPolicySource", + "description": "source is required on constants and destinations and absent on Boolean operators." + } + } + }, + { + "oneOf": [ + { + "properties": { + "all": { + "$ref": "#/components/schemas/ExactPolicyOperands", + "description": "all intersects every operand." + } + }, + "required": [ + "all" + ], + "title": "all", + "type": "object" + }, + { + "properties": { + "any": { + "$ref": "#/components/schemas/ExactPolicyOperands", + "description": "any unions its operands without discarding enclosing ceilings." + } + }, + "required": [ + "any" + ], + "title": "any", + "type": "object" + }, + { + "properties": { + "constant": { + "$ref": "#/components/schemas/ExactPolicyConstant", + "description": "constant explicitly allows or denies independently of the destination.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "constant" + ], + "title": "constant", + "type": "object" + }, + { + "properties": { + "destination": { + "$ref": "#/components/schemas/ExactDestination", + "description": "destination matches only its declared DNS or IP kind." + } + }, + "required": [ + "destination" + ], + "title": "destination", + "type": "object" + }, + { + "properties": { + "not": { + "description": "not negates one earlier node.", + "type": "integer" + } + }, + "required": [ + "not" + ], + "title": "not", + "type": "object" + } + ] + } + ], + "description": "ExactPolicyNode is topologically ordered; references must precede this node.", + "title": "ExactPolicyNode", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactPolicyNode/" + }, + { + "name": "ExactPolicyOperands", + "pointer": "/components/schemas/ExactPolicyOperands", + "schema": { + "description": "ExactPolicyOperands contains earlier node indexes; empty Boolean groups are invalid.", + "properties": { + "nodes": { + "description": "nodes must all precede the enclosing operator.", + "items": { + "type": "integer" + }, + "maxItems": 64, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "nodes" + ], + "title": "ExactPolicyOperands", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactPolicyOperands/" + }, + { + "name": "ExactPolicyOrigin", + "pointer": "/components/schemas/ExactPolicyOrigin", + "schema": { + "description": "ExactPolicyOrigin separates governance from attached and runtime-owned permissions.\n\nValues:\nunspecified\norganization\nowner\nattached\nkit\ngateway\ndefault", + "enum": [ + "unspecified", + "organization", + "owner", + "attached", + "kit", + "gateway", + "default" + ], + "title": "ExactPolicyOrigin", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactPolicyOrigin/" + }, + { + "name": "ExactPolicySource", + "pointer": "/components/schemas/ExactPolicySource", + "schema": { + "description": "ExactPolicySource identifies the nonsecret authority of a leaf expression.", + "properties": { + "id": { + "description": "id identifies that source without exposing credentials or policy content.", + "minLength": 1, + "type": "string" + }, + "origin": { + "$ref": "#/components/schemas/ExactPolicyOrigin", + "description": "origin distinguishes the authority that supplied this leaf.", + "not": { + "enum": [ + "unspecified" + ] + } + } + }, + "required": [ + "origin", + "id" + ], + "title": "ExactPolicySource", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExactPolicySource/" + }, + { + "name": "ExchangeCompositionCredentialResponse", + "pointer": "/components/schemas/ExchangeCompositionCredentialResponse", + "schema": { + "title": "ExchangeCompositionCredentialResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExchangeCompositionCredentialResponse/" + }, + { + "name": "ExecRequest", + "pointer": "/components/schemas/ExecRequest", + "schema": { + "additionalProperties": false, + "description": "ExecRequest runs a command to completion.", + "properties": { + "cmd": { + "description": "cmd is the argv vector.", + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "env": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "env adds environment variables.", + "type": "object" + }, + "user": { + "description": "user is the user to run as.", + "type": "string" + }, + "workingDir": { + "description": "working_dir is the process working directory.", + "type": "string" + } + }, + "required": [ + "cmd" + ], + "title": "ExecRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExecRequest/" + }, + { + "name": "ExecResponse", + "pointer": "/components/schemas/ExecResponse", + "schema": { + "description": "ExecResponse returns process output after the command exits.", + "properties": { + "exitCode": { + "description": "exit_code is the process exit code.", + "format": "int32", + "type": "integer" + }, + "incomplete": { + "description": "incomplete is true when the combined capture limit forced stdout and/or\nstderr to discard some of the command's real output; false whenever\nevery byte the command produced was retained, even if that total lands\nexactly at the limit. exit_code is still the real, final exit code: the\ncommand ran to completion, only its captured output was capped. A retry\nwould rerun the command, so this stays a normal successful response\nrather than an error a client might retry.", + "type": "boolean" + }, + "stderr": { + "description": "stderr is captured stderr, up to the capture limit when incomplete.", + "format": "byte", + "type": "string" + }, + "stdout": { + "description": "stdout is captured stdout, up to the capture limit when incomplete.", + "format": "byte", + "type": "string" + } + }, + "title": "ExecResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ExecResponse/" + }, + { + "name": "FeatureOptions", + "pointer": "/components/schemas/FeatureOptions", + "schema": { + "additionalProperties": false, + "description": "FeatureOptions carries typed admission intent; unknown fields are refused.", + "properties": { + "managedVolumes": { + "$ref": "#/components/schemas/ManagedVolumeOptions", + "description": "managed_volumes selects persistent resources and guest targets." + }, + "storedSecrets": { + "$ref": "#/components/schemas/StoredSecretOptions", + "description": "stored_secrets selects authorized stored references, never raw material." + }, + "timeouts": { + "$ref": "#/components/schemas/TimeoutOptions", + "description": "timeouts enables an explicit deadline; omission enables none." + } + }, + "title": "FeatureOptions", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FeatureOptions/" + }, + { + "name": "FileError", + "pointer": "/components/schemas/FileError", + "schema": { + "description": "FileError reports a path-level file error.", + "properties": { + "failure": { + "$ref": "#/components/schemas/Error", + "description": "failure retains the shared typed code and details for this path." + }, + "path": { + "description": "path is the path that failed.", + "type": "string" + } + }, + "required": [ + "failure" + ], + "title": "FileError", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FileError/" + }, + { + "name": "FileHeader", + "pointer": "/components/schemas/FileHeader", + "schema": { + "additionalProperties": false, + "description": "FileHeader starts a file in an upload or download stream.", + "properties": { + "mode": { + "description": "mode carries Unix permission bits. Upload applies mode \u0026 0777, or 0644 when\nthat value is zero, without subtracting umask; Download reports stored bits.", + "type": "integer" + }, + "path": { + "description": "path is the sandbox path.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "path" + ], + "title": "FileHeader", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FileHeader/" + }, + { + "name": "FileInfo", + "pointer": "/components/schemas/FileInfo", + "schema": { + "description": "FileInfo is file metadata.", + "properties": { + "isDir": { + "description": "is_dir reports whether the path is a directory and stays populated on\nevery backend and every caller. type is the richer authority, and\ntype == directory iff is_dir.", + "type": "boolean" + }, + "linkTarget": { + "description": "link_target is the literal readlink() text when type is symlink,\nsince that is the only case where nothing else lets the caller learn what\nthe link names; empty otherwise.", + "type": "string" + }, + "mode": { + "description": "mode is the stored Unix permission bits (0777), without type or special bits.", + "type": "integer" + }, + "path": { + "description": "path is the sandbox path.", + "type": "string" + }, + "size": { + "description": "size is the file size in bytes.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "type": { + "$ref": "#/components/schemas/FileType", + "description": "type classifies the object, and Stat and List populate it for every\ncaller. Stat and List resolve an in-jail symlink and report\nthe resolved target's type; a link that cannot be resolved in-jail\n(dangling, looping, or escaping) reports symlink for itself\nrather than disclosing an out-of-jail target." + } + }, + "title": "FileInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FileInfo/" + }, + { + "name": "FileType", + "pointer": "/components/schemas/FileType", + "schema": { + "description": "FileType classifies the object at a path.\n\nValues:\nunspecified: unspecified means the backend has not classified the object. Stat and List always classify it.\nregular: regular is a regular file.\ndirectory: directory is a directory.\nsymlink: symlink is a symbolic link that could not be resolved to a target inside the jail.\nother: other is a socket, FIFO, device, or other non-regular, non-directory, non-symlink object.", + "enum": [ + "unspecified", + "regular", + "directory", + "symlink", + "other" + ], + "title": "FileType", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/FileType/" + }, + { + "name": "FilesDownloadRequest", + "pointer": "/components/schemas/FilesDownloadRequest", + "schema": { + "additionalProperties": false, + "description": "DownloadRequest asks for one or more paths.", + "properties": { + "paths": { + "description": "paths naming stable regular files or absent entries at canonical absolute paths\nyield contiguous results in request order, including duplicates.", + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "paths" + ], + "title": "DownloadRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesDownloadRequest/" + }, + { + "name": "FilesDownloadResponse", + "pointer": "/components/schemas/FilesDownloadResponse", + "schema": { + "dependentSchemas": { + "data": { + "not": { + "anyOf": [ + { + "required": [ + "error" + ] + }, + { + "required": [ + "header" + ] + } + ] + } + }, + "error": { + "not": { + "anyOf": [ + { + "required": [ + "data" + ] + }, + { + "required": [ + "header" + ] + } + ] + } + }, + "header": { + "not": { + "anyOf": [ + { + "required": [ + "data" + ] + }, + { + "required": [ + "error" + ] + } + ] + } + } + }, + "description": "DownloadResponse is one frame in a download stream. At most one of data, error, header is set.", + "properties": { + "data": { + "description": "data carries bytes for the current file.", + "format": "byte", + "type": "string" + }, + "error": { + "$ref": "#/components/schemas/FileError", + "description": "error reports a path-level failure without aborting the whole stream." + }, + "header": { + "$ref": "#/components/schemas/FileHeader", + "description": "header starts a downloaded file." + } + }, + "title": "DownloadResponse", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesDownloadResponse/" + }, + { + "name": "FilesListResponse", + "pointer": "/components/schemas/FilesListResponse", + "schema": { + "description": "ListResponse returns directory entries and a next-page token.", + "properties": { + "entries": { + "description": "entries is the current page.", + "items": { + "$ref": "#/components/schemas/FileInfo" + }, + "type": "array" + }, + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + } + }, + "title": "ListResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesListResponse/" + }, + { + "name": "FilesMkdirRequest", + "pointer": "/components/schemas/FilesMkdirRequest", + "schema": { + "additionalProperties": false, + "description": "MkdirRequest creates a directory.", + "properties": { + "mode": { + "description": "mode supplies the new leaf's Unix permission bits: mode \u0026 0777, or 0755\nwhen that value is zero, without subtracting umask.", + "type": "integer" + }, + "parents": { + "description": "parents creates missing parents when true.", + "type": "boolean" + }, + "path": { + "description": "path is the directory path.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "path" + ], + "title": "MkdirRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesMkdirRequest/" + }, + { + "name": "FilesMkdirResponse", + "pointer": "/components/schemas/FilesMkdirResponse", + "schema": { + "description": "MkdirResponse has no fields.", + "title": "MkdirResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesMkdirResponse/" + }, + { + "name": "FilesMoveRequest", + "pointer": "/components/schemas/FilesMoveRequest", + "schema": { + "additionalProperties": false, + "description": "MoveRequest moves or renames a path.", + "properties": { + "from": { + "description": "from is the source path.", + "minLength": 1, + "type": "string" + }, + "to": { + "description": "to is the exact destination path.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "from", + "to" + ], + "title": "MoveRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesMoveRequest/" + }, + { + "name": "FilesMoveResponse", + "pointer": "/components/schemas/FilesMoveResponse", + "schema": { + "description": "MoveResponse has no fields.", + "title": "MoveResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesMoveResponse/" + }, + { + "name": "FilesReadFileRequest", + "pointer": "/components/schemas/FilesReadFileRequest", + "schema": { + "additionalProperties": false, + "description": "ReadFileRequest names one regular file.", + "properties": { + "path": { + "description": "path is the sandbox path of a regular file.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "path" + ], + "title": "ReadFileRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesReadFileRequest/" + }, + { + "name": "FilesReadFileResponse", + "pointer": "/components/schemas/FilesReadFileResponse", + "schema": { + "additionalProperties": false, + "description": "ReadFileResponse carries the whole file; HTTP selects data as its raw response body.", + "properties": { + "data": { + "description": "data is the complete content; a file above the message cap is refused.", + "format": "byte", + "type": "string" + }, + "info": { + "$ref": "#/components/schemas/FileInfo", + "description": "info remains available to the internal adapter; HTTP clients use Stat for metadata." + } + }, + "required": [ + "info" + ], + "title": "ReadFileResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesReadFileResponse/" + }, + { + "name": "FilesRemoveResponse", + "pointer": "/components/schemas/FilesRemoveResponse", + "schema": { + "description": "RemoveResponse reports partial recursive progress to every caller: check failed_path,\nnot the operation status, when Remove stops partway. Effects are never rolled back.", + "properties": { + "completedCount": { + "description": "completed_count is the total number of paths removed, which may exceed\nlen(completed_paths).", + "type": "integer" + }, + "completedPaths": { + "description": "completed_paths lists removed paths in traversal order, bounded to the\nfirst 1000; completed_count carries the\ntrue total when it exceeds that bound.", + "items": { + "type": "string" + }, + "type": "array" + }, + "failedPath": { + "description": "failed_path is the path where a recursive removal stopped; empty on full\nsuccess. Every path in completed_paths was removed before this one.", + "type": "string" + } + }, + "title": "RemoveResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesRemoveResponse/" + }, + { + "name": "FilesStatResponse", + "pointer": "/components/schemas/FilesStatResponse", + "schema": { + "description": "StatResponse returns file metadata.", + "properties": { + "info": { + "$ref": "#/components/schemas/FileInfo", + "description": "info is metadata for the path." + } + }, + "title": "StatResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesStatResponse/" + }, + { + "name": "FilesUploadRequest", + "pointer": "/components/schemas/FilesUploadRequest", + "schema": { + "description": "UploadRequest is one frame in an upload stream.", + "oneOf": [ + { + "properties": { + "data": { + "description": "data appends bytes to the current file.", + "format": "byte", + "type": "string" + } + }, + "required": [ + "data" + ], + "title": "data", + "type": "object" + }, + { + "properties": { + "header": { + "$ref": "#/components/schemas/FileHeader", + "description": "header starts a new file. The first frame, and the first frame after each\ncompleted file, must be this arm." + } + }, + "required": [ + "header" + ], + "title": "header", + "type": "object" + } + ], + "title": "UploadRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesUploadRequest/" + }, + { + "name": "FilesUploadResponse", + "pointer": "/components/schemas/FilesUploadResponse", + "schema": { + "description": "UploadResponse reports completed file writes.", + "properties": { + "filesWritten": { + "description": "files_written is the number of files successfully written.", + "type": "integer" + } + }, + "title": "UploadResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesUploadResponse/" + }, + { + "name": "FilesWriteFileRequest", + "pointer": "/components/schemas/FilesWriteFileRequest", + "schema": { + "additionalProperties": false, + "description": "WriteFileRequest replaces one file.", + "properties": { + "data": { + "description": "data is the complete new content; empty writes an empty file.", + "format": "byte", + "type": "string" + }, + "header": { + "$ref": "#/components/schemas/FileHeader", + "description": "header names the path and mode, as an Upload header does." + } + }, + "required": [ + "header" + ], + "title": "WriteFileRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesWriteFileRequest/" + }, + { + "name": "FilesWriteFileResponse", + "pointer": "/components/schemas/FilesWriteFileResponse", + "schema": { + "description": "WriteFileResponse reports the written file.", + "properties": { + "info": { + "$ref": "#/components/schemas/FileInfo", + "description": "info is the file's metadata after the write." + } + }, + "required": [ + "info" + ], + "title": "WriteFileResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/FilesWriteFileResponse/" + }, + { + "name": "GetNetworkPoliciesResponse", + "pointer": "/components/schemas/GetNetworkPoliciesResponse", + "schema": { + "description": "GetNetworkPoliciesResponse binds both views to exact.revision; a partial read fails.", + "properties": { + "effective": { + "$ref": "#/components/schemas/EffectiveNetworkPolicy" + }, + "exact": { + "$ref": "#/components/schemas/ExactNetworkPolicy" + } + }, + "required": [ + "effective", + "exact" + ], + "title": "GetNetworkPoliciesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/GetNetworkPoliciesResponse/" + }, + { + "name": "Help", + "pointer": "/components/schemas/Help", + "schema": { + "description": "Provides links to documentation or for performing an out of band action.\n\nFor example, if a quota check failed with an error indicating the calling\nproject hasn't enabled the accessed service, this can contain a URL pointing\ndirectly to the right place in the developer console to flip the bit.", + "properties": { + "links": { + "description": "URL(s) pointing to additional information on handling the current error.", + "items": { + "$ref": "#/components/schemas/HelpLink" + }, + "type": "array" + } + }, + "title": "Help", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Help/" + }, + { + "name": "HelpErrorDetail", + "pointer": "/components/schemas/HelpErrorDetail", + "schema": { + "description": "Provides links to documentation or for performing an out of band action.\n\nFor example, if a quota check failed with an error indicating the calling\nproject hasn't enabled the accessed service, this can contain a URL pointing\ndirectly to the right place in the developer console to flip the bit.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.Help", + "type": "string" + }, + "links": { + "description": "URL(s) pointing to additional information on handling the current error.", + "items": { + "$ref": "#/components/schemas/HelpLink" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "HelpErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/HelpErrorDetail/" + }, + { + "name": "HelpLink", + "pointer": "/components/schemas/HelpLink", + "schema": { + "description": "Describes a URL link.", + "properties": { + "description": { + "description": "Describes what the link offers.", + "type": "string" + }, + "url": { + "description": "The URL of the link.", + "type": "string" + } + }, + "title": "Link", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/HelpLink/" + }, + { + "name": "IdentityExchangeServiceExchangeDockerCredentialRequest", + "pointer": "/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest", + "schema": { + "additionalProperties": false, + "properties": { + "idToken": { + "description": "id_token is single-use identity material, never an owner selector.", + "minLength": 1, + "type": "string", + "writeOnly": true + } + }, + "required": [ + "idToken" + ], + "title": "IdentityExchangeServiceExchangeDockerCredentialRequest", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest/" + }, + { + "name": "Image", + "pointer": "/components/schemas/Image", + "schema": { + "description": "Image is the detailed managed image view.\nuid must equal the immutable resource ID in name", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode records whether captured content includes memory." + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "etag": { + "description": "etag identifies the observed version of this resource. It is opaque and strong,\nchanges on every visible change, and is what a mutation sends as its precondition.", + "minLength": 1, + "pattern": "^\"[^\"\\x00-\\x20\\x7f]*\"$", + "readOnly": true, + "type": "string" + }, + "failure": { + "$ref": "#/components/schemas/Error", + "description": "failure is set when status is FAILED." + }, + "imageDigest": { + "description": "image_digest is the content digest when known.", + "type": "string" + }, + "imageRef": { + "description": "image_ref is the registry or backend image reference when available.", + "type": "string" + }, + "name": { + "description": "(IDENTIFIER) name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^images/[^/]+$", + "type": "string" + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform is the image platform." + }, + "pushTarget": { + "$ref": "#/components/schemas/ImagePushTarget", + "description": "push_target appears only in from_image create responses awaiting upload, never reads.", + "readOnly": true + }, + "readyCmd": { + "description": "ready_cmd is the readiness command used by raw image sandboxes.", + "items": { + "type": "string" + }, + "type": "array" + }, + "resources": { + "$ref": "#/components/schemas/Resources", + "description": "resources describes the image's preferred runtime resources." + }, + "source": { + "$ref": "#/components/schemas/ImageSource", + "description": "source records how the image was created." + }, + "startCmd": { + "description": "start_cmd is the command used by raw image sandboxes.", + "items": { + "type": "string" + }, + "type": "array" + }, + "status": { + "$ref": "#/components/schemas/ImageStatus", + "description": "status is the image readiness state.", + "not": { + "enum": [ + "unspecified" + ] + }, + "readOnly": true + }, + "totalSizeBytes": { + "description": "total_size_bytes is the approximate stored image size.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "updated_at is the last update timestamp." + } + }, + "required": [ + "uid", + "name", + "status", + "createdAt", + "updatedAt", + "etag" + ], + "title": "Image", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Image/" + }, + { + "name": "ImageBlobRef", + "pointer": "/components/schemas/ImageBlobRef", + "schema": { + "description": "ImageBlobRef describes one pullable blob.", + "properties": { + "digest": { + "description": "digest is the content digest.", + "type": "string" + }, + "mediaType": { + "description": "media_type is the OCI media type.", + "type": "string" + }, + "size": { + "description": "size is the blob size in bytes.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "url": { + "description": "url is a short-lived pull URL.", + "type": "string" + } + }, + "title": "ImageBlobRef", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImageBlobRef/" + }, + { + "name": "ImageFromImage", + "pointer": "/components/schemas/ImageFromImage", + "schema": { + "additionalProperties": false, + "description": "ImageFromImage registers a target for pushed OCI content.", + "properties": { + "captureMode": { + "description": "capture_mode must be unspecified or disk; pushed OCI content cannot include memory.", + "enum": [ + "unspecified", + "disk" + ], + "not": { + "enum": [ + "all" + ] + }, + "title": "ImageFromImageCaptureMode", + "type": "string" + }, + "kitStartup": { + "$ref": "#/components/schemas/KitStartup", + "description": "Startup commands copied from the source sandbox. Services with startup replay run these commands when a sandbox created from the image boots. Services without startup replay accept valid commands without running them." + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform is the platform for the pushed content." + }, + "platformHint": { + "$ref": "#/components/schemas/Platform", + "description": "platform_hint picks among a multi-platform push when platform is absent.\nA hint the backend cannot honor is ignored, never an error." + }, + "resources": { + "$ref": "#/components/schemas/Resources", + "description": "resources describes preferred runtime resources for the resulting image." + } + }, + "title": "ImageFromImage", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImageFromImage/" + }, + { + "name": "ImagePullSpec", + "pointer": "/components/schemas/ImagePullSpec", + "schema": { + "description": "ImagePullSpec describes short-lived pull material for placement.", + "properties": { + "config": { + "$ref": "#/components/schemas/ImageBlobRef", + "description": "config is the image config blob." + }, + "expiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "expires_at is when the pull material expires." + }, + "layers": { + "description": "layers are the image layer blobs.", + "items": { + "$ref": "#/components/schemas/ImageBlobRef" + }, + "type": "array" + }, + "manifestDigest": { + "description": "manifest_digest is the manifest digest.", + "type": "string" + }, + "manifestMediaType": { + "description": "manifest_media_type is the manifest media type.", + "type": "string" + } + }, + "title": "ImagePullSpec", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImagePullSpec/" + }, + { + "name": "ImagePushTarget", + "pointer": "/components/schemas/ImagePushTarget", + "schema": { + "description": "ImagePushTarget carries short-lived upload credentials.", + "properties": { + "accessToken": { + "description": "access_token is the short-lived push credential.", + "type": "string" + }, + "accessTokenExpiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "access_token_expires_at is the token expiry." + }, + "imageRef": { + "description": "image_ref is the registry reference to push.", + "type": "string" + } + }, + "title": "ImagePushTarget", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImagePushTarget/" + }, + { + "name": "ImageSource", + "pointer": "/components/schemas/ImageSource", + "schema": { + "description": "ImageSource records how the image was created.\n\nValues:\nunspecified: unspecified means the source is unknown or not reported.\nimage: image means the image came from pushed or imported image bytes.\nsandbox: sandbox means the image came from a sandbox capture.", + "enum": [ + "unspecified", + "image", + "sandbox" + ], + "title": "ImageSource", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImageSource/" + }, + { + "name": "ImageStatus", + "pointer": "/components/schemas/ImageStatus", + "schema": { + "description": "ImageStatus is the image readiness state.\n\nValues:\nunspecified: unspecified is never a concrete known state.\npending: pending means an asynchronous build has not started or reported progress.\nwaitingForPush: waitingForPush means the backend is waiting for OCI content upload.\npreparing: preparing means the backend is preparing pushed or captured content.\ncompleted: completed means the image is ready to use.\nfailed: failed means image preparation reached a terminal failure.\ndeleted: deleted means the backend exposes a retained delete tombstone.", + "enum": [ + "unspecified", + "pending", + "waitingForPush", + "preparing", + "completed", + "failed", + "deleted" + ], + "title": "ImageStatus", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImageStatus/" + }, + { + "name": "ImageSummary", + "pointer": "/components/schemas/ImageSummary", + "schema": { + "description": "ImageSummary is the list view of an image.\nuid must equal the immutable resource ID in name", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode records whether captured content includes memory." + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "imageDigest": { + "description": "image_digest is the content digest when known.", + "type": "string" + }, + "imageRef": { + "description": "image_ref is the registry or backend image reference when available.", + "type": "string" + }, + "name": { + "description": "name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^images/[^/]+$", + "type": "string" + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform is the image platform." + }, + "source": { + "$ref": "#/components/schemas/ImageSource", + "description": "source records how the image was created." + }, + "status": { + "$ref": "#/components/schemas/ImageStatus", + "description": "status is the image readiness state.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "totalSizeBytes": { + "description": "total_size_bytes is the approximate stored image size.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "updated_at is the last update timestamp." + } + }, + "required": [ + "uid", + "name", + "status", + "createdAt", + "updatedAt" + ], + "title": "ImageSummary", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ImageSummary/" + }, + { + "name": "InteractRequest", + "pointer": "/components/schemas/InteractRequest", + "schema": { + "description": "InteractRequest is one frame on the bidirectional interaction stream.", + "oneOf": [ + { + "properties": { + "attach": { + "$ref": "#/components/schemas/ProcessAttach", + "description": "attach opens or resumes the interaction." + } + }, + "required": [ + "attach" + ], + "title": "attach", + "type": "object" + }, + { + "properties": { + "closeStdin": { + "description": "close_stdin closes standard input when true; false has no effect, including on a PTY.\nOn a PTY, true delivers the terminal's VEOF input through the line discipline and\ndoes not close the PTY master; subsequent stdin frames remain valid. Terminal mode\nowns interpretation: canonical mode treats VEOF as marking the end of input, while\nraw mode delivers it as an ordinary input byte, so this promises delivery, never\ninterpretation. Each true frame on a PTY delivers exactly one VEOF input; unlike the\npipe path, repeated frames are not a no-op.", + "type": "boolean" + } + }, + "required": [ + "closeStdin" + ], + "title": "close_stdin", + "type": "object" + }, + { + "properties": { + "resize": { + "$ref": "#/components/schemas/TerminalSize", + "description": "resize changes terminal size; portable-range dimensions on a running process without a PTY return FAILED_PRECONDITION." + } + }, + "required": [ + "resize" + ], + "title": "resize", + "type": "object" + }, + { + "properties": { + "stdin": { + "description": "stdin writes process standard input.", + "format": "byte", + "type": "string" + } + }, + "required": [ + "stdin" + ], + "title": "stdin", + "type": "object" + } + ], + "title": "InteractRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/InteractRequest/" + }, + { + "name": "IssueSSHCertResponse", + "pointer": "/components/schemas/IssueSSHCertResponse", + "schema": { + "description": "IssueSSHCertResponse returns signed SSH client material, never a private key.", + "properties": { + "certificate": { + "description": "certificate is the signed SSH certificate.", + "type": "string" + }, + "expiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "expires_at is the instant after which the certificate is invalid." + }, + "host": { + "description": "host is the SSH endpoint host to connect to.", + "type": "string" + }, + "knownHosts": { + "description": "known_hosts is host key material that authenticates the SSH endpoint.", + "type": "string" + }, + "port": { + "description": "port is the SSH endpoint port to connect to.", + "type": "integer" + }, + "sshConfig": { + "description": "ssh_config optionally renders the connection fields as OpenSSH client\nconfiguration; the structured fields are canonical.", + "type": "string" + }, + "username": { + "description": "username is the SSH username to present; it carries no authorization.", + "type": "string" + } + }, + "title": "IssueSSHCertResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/IssueSSHCertResponse/" + }, + { + "name": "KitArtifactInput", + "pointer": "/components/schemas/KitArtifactInput", + "schema": { + "allOf": [ + { + "properties": { + "ref": { + "$ref": "#/components/schemas/KitRef" + } + } + }, + { + "oneOf": [ + { + "properties": { + "inline": { + "description": "inline is the artifact in the pinned JSON encoding.", + "format": "byte", + "type": "string" + } + }, + "required": [ + "inline" + ], + "title": "inline", + "type": "object" + } + ] + } + ], + "description": "KitArtifactInput carries a v2 artifact inline or by staged digest.", + "required": [ + "ref" + ], + "title": "KitArtifactInput", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/KitArtifactInput/" + }, + { + "name": "KitFieldDisposition", + "pointer": "/components/schemas/KitFieldDisposition", + "schema": { + "description": "KitFieldDisposition describes a declaration that was not applied.\n\nValues:\nunspecified: unspecified is invalid in a report.\nskipped: skipped identifies a contract-permitted optional skip.\nrefused: refused prevents guest or kit effects.", + "enum": [ + "unspecified", + "skipped", + "refused" + ], + "title": "KitFieldDisposition", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitFieldDisposition/" + }, + { + "name": "KitFieldOutcome", + "pointer": "/components/schemas/KitFieldOutcome", + "schema": { + "description": "KitFieldOutcome identifies one non-applied declaration without exposing its value.", + "properties": { + "digest": { + "description": "digest is the resolved content identity when resolution succeeded.", + "type": "string" + }, + "disposition": { + "$ref": "#/components/schemas/KitFieldDisposition", + "description": "disposition never claims that an accepted declaration has executed.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "fieldPath": { + "description": "field_path is an RFC 6901 pointer into the pinned JSON artifact.", + "type": "string" + }, + "kitIndex": { + "description": "kit_index is the zero-based position in the originating request's kits.", + "exclusiveMaximum": 64, + "type": "integer" + }, + "reason": { + "$ref": "#/components/schemas/KitFieldReason", + "description": "reason is a bounded category, not caller-controlled diagnostic content.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "reasonText": { + "description": "reason_text contains nonsecret explanatory text, never values or command content.", + "type": "string" + }, + "ref": { + "description": "ref preserves the exact requested kit reference.", + "type": "string" + } + }, + "required": [ + "ref", + "fieldPath", + "disposition", + "reason" + ], + "title": "KitFieldOutcome", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitFieldOutcome/" + }, + { + "name": "KitFieldOutcomeReport", + "pointer": "/components/schemas/KitFieldOutcomeReport", + "schema": { + "description": "KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal.", + "properties": { + "complete": { + "description": "complete means every refused or skipped declaration is accounted for; absence proves nothing.", + "type": "boolean" + }, + "outcomes": { + "description": "outcomes follow request index then UTF-8 field-path order and are never truncated.", + "items": { + "$ref": "#/components/schemas/KitFieldOutcome" + }, + "maxItems": 256, + "type": "array" + } + }, + "title": "KitFieldOutcomeReport", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitFieldOutcomeReport/" + }, + { + "name": "KitFieldOutcomeReportErrorDetail", + "pointer": "/components/schemas/KitFieldOutcomeReportErrorDetail", + "schema": { + "description": "KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal.", + "properties": { + "@type": { + "const": "type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport", + "type": "string" + }, + "complete": { + "description": "complete means every refused or skipped declaration is accounted for; absence proves nothing.", + "type": "boolean" + }, + "outcomes": { + "description": "outcomes follow request index then UTF-8 field-path order and are never truncated.", + "items": { + "$ref": "#/components/schemas/KitFieldOutcome" + }, + "maxItems": 256, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "KitFieldOutcomeReportErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitFieldOutcomeReportErrorDetail/" + }, + { + "name": "KitFieldReason", + "pointer": "/components/schemas/KitFieldReason", + "schema": { + "description": "KitFieldReason provides stable, nonsecret diagnostic categories.\n\nValues:\nunspecified: unspecified is invalid in a report.\nunsupported: unsupported means the backend cannot honor the declaration.\nunknownField: unknownField means the pinned schema does not recognize the declaration.\ncredentialUnavailable: credentialUnavailable means the declared credential cannot be injected.", + "enum": [ + "unspecified", + "unsupported", + "unknownField", + "credentialUnavailable" + ], + "title": "KitFieldReason", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitFieldReason/" + }, + { + "name": "KitInput", + "pointer": "/components/schemas/KitInput", + "schema": { + "description": "KitInput is one kit in either shape.", + "oneOf": [ + { + "properties": { + "artifact": { + "$ref": "#/components/schemas/KitArtifactInput" + } + }, + "required": [ + "artifact" + ], + "title": "artifact", + "type": "object" + } + ], + "title": "KitInput", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/KitInput/" + }, + { + "name": "KitRef", + "pointer": "/components/schemas/KitRef", + "schema": { + "additionalProperties": false, + "description": "KitRef names a kit to apply.", + "properties": { + "kind": { + "description": "kind is \"sandbox\", \"mixin\", or empty to defer to the kit's own manifest.", + "enum": [ + "", + "sandbox", + "mixin" + ], + "type": "string" + }, + "ref": { + "description": "ref names the kit source.", + "minLength": 1, + "type": "string" + } + }, + "required": [ + "ref" + ], + "title": "KitRef", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitRef/" + }, + { + "name": "KitStartup", + "pointer": "/components/schemas/KitStartup", + "schema": { + "additionalProperties": false, + "description": "Startup commands retained when creating an image. Services with startup replay run them at each boot; services without it accept valid commands without running them.", + "properties": { + "commands": { + "description": "commands run in order at sandbox boot, on a backend that replays them.", + "items": { + "$ref": "#/components/schemas/KitStartupCommand" + }, + "minItems": 1, + "type": "array" + }, + "kits": { + "description": "kits names the kit identities the commands derive from, in composition\norder. Required.", + "items": { + "minLength": 1, + "type": "string" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "kits", + "commands" + ], + "title": "KitStartup", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitStartup/" + }, + { + "name": "KitStartupCommand", + "pointer": "/components/schemas/KitStartupCommand", + "schema": { + "additionalProperties": false, + "description": "KitStartupCommand is one startup command in a KitStartup set, run in order\nby a backend that replays it at sandbox boot.", + "properties": { + "argv": { + "description": "argv is the command and its arguments, exec-style. An argument other than\nthe executable itself may be empty (an intentional empty string, as in\n`printf %s \"\"`); only the vector itself is required non-empty.", + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "background": { + "description": "background launches the command detached instead of waiting for it.", + "type": "boolean" + }, + "user": { + "description": "user runs the command as this user; empty means the backend default.", + "type": "string" + } + }, + "required": [ + "argv" + ], + "title": "KitStartupCommand", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/KitStartupCommand/" + }, + { + "name": "ListImagesResponse", + "pointer": "/components/schemas/ListImagesResponse", + "schema": { + "description": "ListImagesResponse returns image results and a next-page token.", + "properties": { + "images": { + "description": "images is the current page.", + "items": { + "$ref": "#/components/schemas/ImageSummary" + }, + "type": "array" + }, + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + } + }, + "title": "ListImagesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListImagesResponse/" + }, + { + "name": "ListPolicyLogEntriesResponse", + "pointer": "/components/schemas/ListPolicyLogEntriesResponse", + "schema": { + "description": "ListPolicyLogEntriesResponse returns policy log entries and a next-page token.", + "properties": { + "entries": { + "description": "entries is the current page.", + "items": { + "$ref": "#/components/schemas/PolicyLogEntry" + }, + "type": "array" + }, + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + } + }, + "title": "ListPolicyLogEntriesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListPolicyLogEntriesResponse/" + }, + { + "name": "ListPortsResponse", + "pointer": "/components/schemas/ListPortsResponse", + "schema": { + "description": "ListPortsResponse returns currently published ports.", + "properties": { + "published": { + "description": "published is ordered by number ascending.", + "items": { + "$ref": "#/components/schemas/Port" + }, + "type": "array" + } + }, + "title": "ListPortsResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListPortsResponse/" + }, + { + "name": "ListProcessesResponse", + "pointer": "/components/schemas/ListProcessesResponse", + "schema": { + "description": "ListProcessesResponse returns processes and a next-page token.", + "properties": { + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + }, + "processes": { + "description": "processes is the current page.", + "items": { + "$ref": "#/components/schemas/Process" + }, + "type": "array" + } + }, + "title": "ListProcessesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListProcessesResponse/" + }, + { + "name": "ListSandboxesResponse", + "pointer": "/components/schemas/ListSandboxesResponse", + "schema": { + "description": "ListSandboxesResponse returns sandbox results and a next-page token.", + "properties": { + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + }, + "sandboxes": { + "description": "sandboxes is the current page.", + "items": { + "$ref": "#/components/schemas/Sandbox" + }, + "type": "array" + } + }, + "title": "ListSandboxesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListSandboxesResponse/" + }, + { + "name": "ListSecretsResponse", + "pointer": "/components/schemas/ListSecretsResponse", + "schema": { + "description": "ListSecretsResponse returns secrets and a next-page token.", + "properties": { + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + }, + "secrets": { + "description": "secrets is the current page.", + "items": { + "$ref": "#/components/schemas/Secret" + }, + "type": "array" + } + }, + "title": "ListSecretsResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListSecretsResponse/" + }, + { + "name": "ListSnapshotsResponse", + "pointer": "/components/schemas/ListSnapshotsResponse", + "schema": { + "description": "ListSnapshotsResponse returns snapshot results and a next-page token.", + "properties": { + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + }, + "snapshots": { + "description": "snapshots is the current page.", + "items": { + "$ref": "#/components/schemas/SnapshotSummary" + }, + "type": "array" + } + }, + "title": "ListSnapshotsResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListSnapshotsResponse/" + }, + { + "name": "ListVolumesResponse", + "pointer": "/components/schemas/ListVolumesResponse", + "schema": { + "description": "ListVolumesResponse returns volumes and a next-page token.", + "properties": { + "nextPageToken": { + "description": "next_page_token is empty when there are no more pages.", + "type": "string" + }, + "volumes": { + "description": "volumes is the current page.", + "items": { + "$ref": "#/components/schemas/Volume" + }, + "type": "array" + } + }, + "title": "ListVolumesResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ListVolumesResponse/" + }, + { + "name": "LocalizedMessage", + "pointer": "/components/schemas/LocalizedMessage", + "schema": { + "description": "Provides a localized error message that is safe to return to the user\nwhich can be attached to an operation error.", + "properties": { + "locale": { + "description": "The locale used following the specification defined at\nhttps://www.rfc-editor.org/rfc/bcp/bcp47.txt.\nExamples are: \"en-US\", \"fr-CH\", \"es-MX\"", + "type": "string" + }, + "message": { + "description": "The localized error message in the above locale.", + "type": "string" + } + }, + "title": "LocalizedMessage", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/LocalizedMessage/" + }, + { + "name": "LocalizedMessageErrorDetail", + "pointer": "/components/schemas/LocalizedMessageErrorDetail", + "schema": { + "description": "Provides a localized error message that is safe to return to the user\nwhich can be attached to an operation error.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.LocalizedMessage", + "type": "string" + }, + "locale": { + "description": "The locale used following the specification defined at\nhttps://www.rfc-editor.org/rfc/bcp/bcp47.txt.\nExamples are: \"en-US\", \"fr-CH\", \"es-MX\"", + "type": "string" + }, + "message": { + "description": "The localized error message in the above locale.", + "type": "string" + } + }, + "required": [ + "@type" + ], + "title": "LocalizedMessageErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/LocalizedMessageErrorDetail/" + }, + { + "name": "ManagedVolumeOptions", + "pointer": "/components/schemas/ManagedVolumeOptions", + "schema": { + "additionalProperties": false, + "description": "ManagedVolumeOptions selects existing volumes; it does not create storage.", + "properties": { + "attachments": { + "description": "attachments cannot repeat a volume identity or overlap another mount target.", + "items": { + "$ref": "#/components/schemas/VolumeAttachment" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "attachments" + ], + "title": "ManagedVolumeOptions", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ManagedVolumeOptions/" + }, + { + "name": "McpAuthorization", + "pointer": "/components/schemas/McpAuthorization", + "schema": { + "description": "McpAuthorization is the current authorization incarnation for one named upstream.", + "properties": { + "authorizationUrl": { + "description": "authorization_url is present only while interaction is pending.", + "readOnly": true, + "type": "string" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "readOnly": true + }, + "etag": { + "description": "etag identifies this incarnation and changes with every visible authorization update.", + "readOnly": true, + "type": "string" + }, + "expiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "expires_at bounds the pending flow; expiry records FAILED on this incarnation.", + "readOnly": true + }, + "failure": { + "$ref": "#/components/schemas/Error", + "readOnly": true + }, + "name": { + "description": "(IDENTIFIER) name is the complete singleton resource name.", + "type": "string" + }, + "server": { + "description": "(OPTIONAL) server is the complete resource name, in the form mcp-servers/{server}.", + "pattern": "^(?:mcp-servers/[^/]+)?$", + "type": "string" + }, + "status": { + "$ref": "#/components/schemas/McpAuthorizationStatus", + "readOnly": true + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available.", + "readOnly": true, + "type": [ + "string", + "null" + ] + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp", + "readOnly": true + } + }, + "title": "McpAuthorization", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpAuthorization/" + }, + { + "name": "McpAuthorizationStatus", + "pointer": "/components/schemas/McpAuthorizationStatus", + "schema": { + "description": "McpAuthorizationStatus reports the current upstream authorization outcome.\n\nValues:\nunspecified\npending\nauthorized\nfailed", + "enum": [ + "unspecified", + "pending", + "authorized", + "failed" + ], + "title": "McpAuthorizationStatus", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpAuthorizationStatus/" + }, + { + "name": "McpConfigurationMode", + "pointer": "/components/schemas/McpConfigurationMode", + "schema": { + "description": "McpConfigurationMode identifies desired hosting ownership and discovery behavior.\n\nValues:\nunspecified: unspecified is not a concrete report mode.\ndynamic: dynamic uses a backend-minted gateway with discovery.\nstatic: static uses a backend-minted gateway without discovery.\nattached: attached retains a read-only external binding.", + "enum": [ + "unspecified", + "dynamic", + "static", + "attached" + ], + "title": "McpConfigurationMode", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpConfigurationMode/" + }, + { + "name": "McpConfigurationOutcome", + "pointer": "/components/schemas/McpConfigurationOutcome", + "schema": { + "description": "McpConfigurationOutcome describes one requested server in the reported generation.\n\nValues:\nunspecified: unspecified is not a concrete outcome.\npending: pending has not settled and cannot establish completeness.\napplied: applied is confirmed membership, not upstream authorization.\nskipped: skipped requires an explicitly applicable compatibility rule.\nfailed: failed retains intent that could not be provisioned.", + "enum": [ + "unspecified", + "pending", + "applied", + "skipped", + "failed" + ], + "title": "McpConfigurationOutcome", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpConfigurationOutcome/" + }, + { + "name": "McpConfigurationReport", + "pointer": "/components/schemas/McpConfigurationReport", + "schema": { + "description": "McpConfigurationReport is also returned in Error.details on accepted provisioning failure.", + "properties": { + "complete": { + "description": "complete means every active requested server is applied or explicitly permitted to skip.", + "type": "boolean" + }, + "dormantServers": { + "description": "dormant_servers retains earlier minted intent while attached; it is empty in minted modes.", + "items": { + "$ref": "#/components/schemas/McpServer" + }, + "maxItems": 256, + "type": "array" + }, + "generation": { + "description": "generation is an opaque durable fence, never ordered or synthesized by callers.", + "type": "string" + }, + "mode": { + "$ref": "#/components/schemas/McpConfigurationMode", + "description": "mode separates minted discovery behavior from read-only attachment.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "servers": { + "description": "servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers.", + "items": { + "$ref": "#/components/schemas/McpConfiguredServer" + }, + "maxItems": 256, + "type": "array" + } + }, + "required": [ + "generation", + "mode" + ], + "title": "McpConfigurationReport", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpConfigurationReport/" + }, + { + "name": "McpConfigurationReportErrorDetail", + "pointer": "/components/schemas/McpConfigurationReportErrorDetail", + "schema": { + "description": "McpConfigurationReport is also returned in Error.details on accepted provisioning failure.", + "properties": { + "@type": { + "const": "type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport", + "type": "string" + }, + "complete": { + "description": "complete means every active requested server is applied or explicitly permitted to skip.", + "type": "boolean" + }, + "dormantServers": { + "description": "dormant_servers retains earlier minted intent while attached; it is empty in minted modes.", + "items": { + "$ref": "#/components/schemas/McpServer" + }, + "maxItems": 256, + "type": "array" + }, + "generation": { + "description": "generation is an opaque durable fence, never ordered or synthesized by callers.", + "type": "string" + }, + "mode": { + "$ref": "#/components/schemas/McpConfigurationMode", + "description": "mode separates minted discovery behavior from read-only attachment.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "servers": { + "description": "servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers.", + "items": { + "$ref": "#/components/schemas/McpConfiguredServer" + }, + "maxItems": 256, + "type": "array" + } + }, + "required": [ + "generation", + "mode", + "@type" + ], + "title": "McpConfigurationReportErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpConfigurationReportErrorDetail/" + }, + { + "name": "McpConfiguredServer", + "pointer": "/components/schemas/McpConfiguredServer", + "schema": { + "description": "McpConfiguredServer preserves one canonical requested identity and its provisioning outcome.", + "properties": { + "outcome": { + "$ref": "#/components/schemas/McpConfigurationOutcome", + "description": "outcome is concrete even when the gateway remains ready after a failed add.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "reason": { + "description": "reason is nonsecret context and never carries credentials or credential-bearing URLs.", + "type": "string" + }, + "server": { + "$ref": "#/components/schemas/McpServer", + "description": "server is the resolved requested server; its type cannot silently change within retained intent." + } + }, + "required": [ + "server", + "outcome" + ], + "title": "McpConfiguredServer", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpConfiguredServer/" + }, + { + "name": "McpCreateSpec", + "pointer": "/components/schemas/McpCreateSpec", + "schema": { + "additionalProperties": false, + "description": "McpCreateSpec configures the sandbox's MCP gateway before the workload starts.\nservers must be empty when gateway_url is set", + "properties": { + "gatewayUrl": { + "description": "gateway_url attaches read-only to a pre-existing shareable gateway when supported.", + "format": "uri", + "type": [ + "string", + "null" + ] + }, + "servers": { + "description": "servers are initial server names for a backend-minted gateway.", + "items": { + "minLength": 1, + "type": "string" + }, + "type": "array" + }, + "static": { + "description": "static pins the requested server set and closes gateway-side discovery.", + "type": "boolean" + } + }, + "title": "McpCreateSpec", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpCreateSpec/" + }, + { + "name": "McpGateway", + "pointer": "/components/schemas/McpGateway", + "schema": { + "description": "McpGateway is gateway state for one sandbox.", + "properties": { + "name": { + "description": "(IDENTIFIER) name is the complete singleton resource name.", + "type": "string" + }, + "reused": { + "description": "reused is true when the response reused an existing gateway.", + "type": "boolean" + }, + "servers": { + "description": "servers is the accumulated requested set, not live gateway truth.", + "items": { + "$ref": "#/components/schemas/McpServer" + }, + "type": "array" + }, + "state": { + "$ref": "#/components/schemas/McpGatewayState", + "description": "state is the gateway readiness state." + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available.", + "readOnly": true, + "type": [ + "string", + "null" + ] + }, + "url": { + "description": "url is the gateway endpoint.", + "type": "string" + } + }, + "title": "McpGateway", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpGateway/" + }, + { + "name": "McpGatewayState", + "pointer": "/components/schemas/McpGatewayState", + "schema": { + "description": "McpGatewayState reports gateway readiness.\n\nValues:\nunspecified: unspecified is never a concrete known state.\nprovisioning: provisioning means the gateway is starting.\nready: ready means the gateway can accept server operations.\nfailed: failed means gateway setup failed.", + "enum": [ + "unspecified", + "provisioning", + "ready", + "failed" + ], + "title": "McpGatewayState", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpGatewayState/" + }, + { + "name": "McpServer", + "pointer": "/components/schemas/McpServer", + "schema": { + "description": "McpServer projects one external server key configured on a gateway.", + "properties": { + "name": { + "description": "name is the external configured server key, not an API resource name.", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/McpServerType", + "description": "type is the configured server type." + } + }, + "title": "McpServer", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpServer/" + }, + { + "name": "McpServerType", + "pointer": "/components/schemas/McpServerType", + "schema": { + "description": "McpServerType identifies a gateway server integration style.\n\nValues:\nunspecified: unspecified is not a concrete server type.\nremote: remote is an HTTP remote MCP server.\ncontainer: container is a container-backed MCP server.\nstdio: stdio is a stdio-backed MCP server.", + "enum": [ + "unspecified", + "remote", + "container", + "stdio" + ], + "title": "McpServerType", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/McpServerType/" + }, + { + "name": "NetworkPolicy", + "pointer": "/components/schemas/NetworkPolicy", + "schema": { + "additionalProperties": false, + "description": "NetworkPolicy is an inline policy request materialized in the governance plane.", + "properties": { + "allowNetworks": { + "description": "allow_networks are exact network names or CIDRs allowed by this document.", + "items": { + "type": "string" + }, + "type": "array" + }, + "denyNetworks": { + "description": "deny_networks are exact network names or CIDRs denied by this document.", + "items": { + "type": "string" + }, + "type": "array" + }, + "mode": { + "description": "mode is required and cannot be UNSPECIFIED.", + "enum": [ + "denyAll" + ], + "not": { + "enum": [ + "unspecified" + ] + }, + "title": "NetworkPolicyMode", + "type": "string" + } + }, + "required": [ + "mode" + ], + "title": "NetworkPolicy", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/NetworkPolicy/" + }, + { + "name": "NetworkPolicyMode", + "pointer": "/components/schemas/NetworkPolicyMode", + "schema": { + "description": "NetworkPolicyMode is the top-level egress disposition.\n\nValues:\nunspecified: unspecified is invalid in policy documents and in conforming responses.\nallowAll: allowAll allows egress unless denied by a narrower rule.\ndenyAll: denyAll denies egress unless allowed by a narrower rule.", + "enum": [ + "unspecified", + "allowAll", + "denyAll" + ], + "title": "NetworkPolicyMode", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/NetworkPolicyMode/" + }, + { + "name": "OAuthConfig", + "pointer": "/components/schemas/OAuthConfig", + "schema": { + "description": "OAuthConfig is non-secret OAuth metadata returned on reads.", + "properties": { + "clientId": { + "description": "client_id is the OAuth client id.", + "type": "string" + }, + "tokenEndpoint": { + "description": "token_endpoint is the OAuth token endpoint.", + "type": "string" + } + }, + "title": "OAuthConfig", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/OAuthConfig/" + }, + { + "name": "OAuthRefreshMaterial", + "pointer": "/components/schemas/OAuthRefreshMaterial", + "schema": { + "additionalProperties": false, + "description": "OAuthRefreshMaterial is OAuth secret material. Unlike OAuthRefreshMaterialV2 it pairs\nno bootstrap token with an expiry and stores client_id as the caller supplied it.", + "properties": { + "clientId": { + "description": "client_id is the OAuth client id.", + "type": "string" + }, + "expiresAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "expires_at is the access token expiry when supplied." + }, + "idToken": { + "description": "id_token is an optional OpenID Connect id token.", + "type": "string", + "writeOnly": true + }, + "initialAccessToken": { + "description": "initial_access_token is an optional bootstrap access token.", + "type": "string", + "writeOnly": true + }, + "providerAccountId": { + "description": "provider_account_id identifies the provider account.", + "type": "string" + }, + "refreshToken": { + "description": "refresh_token is the OAuth refresh token.", + "minLength": 1, + "type": "string", + "writeOnly": true + }, + "scopes": { + "description": "scopes are requested OAuth scopes.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "refreshToken" + ], + "title": "OAuthRefreshMaterial", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/OAuthRefreshMaterial/" + }, + { + "name": "OutputRetention", + "pointer": "/components/schemas/OutputRetention", + "schema": { + "description": "OutputRetention records minimum reconnect coverage independently of location.\noutput retention requires a duration or byte floor", + "properties": { + "minBytes": { + "description": "min_bytes retains at least this many recent bytes per process when nonzero.\na byte retention floor must be zero or at least 64 KiB", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "minDuration": { + "$ref": "#/components/schemas/Duration", + "description": "min_duration retains each process's output for at least this age when set." + } + }, + "title": "OutputRetention", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/OutputRetention/" + }, + { + "name": "Permission", + "pointer": "/components/schemas/Permission", + "schema": { + "description": "The actions a credential is allowed to perform. Each operation declares its required permissions; service support does not grant permission.", + "enum": [ + "unspecified", + "sandboxesRead", + "sandboxesCreate", + "sandboxesExec", + "sandboxesFilesRead", + "sandboxesFilesWrite", + "imagesPull", + "secretsWrite", + "sandboxesDelete", + "sandboxesLifecycle", + "sandboxesKits", + "sandboxesPorts", + "sandboxesCredential", + "sandboxesSsh", + "imagesRead", + "imagesWrite", + "secretsRead", + "networkPoliciesRead", + "volumesRead", + "volumesWrite", + "snapshotsRead", + "snapshotsWrite", + "mcpRead", + "mcpWrite", + "credentialsExchange", + "sandboxesRename", + "secretsResolve", + "operator" + ], + "title": "Permission", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/Permission/" + }, + { + "name": "Platform", + "pointer": "/components/schemas/Platform", + "schema": { + "additionalProperties": false, + "description": "Platform is the OCI platform tuple.", + "properties": { + "architecture": { + "description": "architecture is the CPU architecture, for example \"amd64\" or \"arm64\".", + "type": "string" + }, + "os": { + "description": "os is the operating system, for example \"linux\".", + "type": "string" + } + }, + "title": "Platform", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Platform/" + }, + { + "name": "PolicyDecision", + "pointer": "/components/schemas/PolicyDecision", + "schema": { + "description": "PolicyDecision is the outcome of an evaluated access attempt.\n\nValues:\nunspecified: unspecified means the decision is unknown or not reported.\nallowed: allowed means the attempt was allowed.\nblocked: blocked means the attempt was blocked.", + "enum": [ + "unspecified", + "allowed", + "blocked" + ], + "title": "PolicyDecision", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/PolicyDecision/" + }, + { + "name": "PolicyDomain", + "pointer": "/components/schemas/PolicyDomain", + "schema": { + "description": "PolicyDomain identifies a policy subsystem.\n\nValues:\nunspecified: unspecified is not a concrete policy domain.\nnetwork: network is network egress policy.", + "enum": [ + "unspecified", + "network" + ], + "title": "PolicyDomain", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/PolicyDomain/" + }, + { + "name": "PolicyLayer", + "pointer": "/components/schemas/PolicyLayer", + "schema": { + "description": "PolicyLayer identifies where an effective rule came from. ORG and OWNER are\nthe two governance scopes; exactly one governs a caller, so a conforming effective view never mixes them.\n\nValues:\nunspecified: unspecified means the layer is unknown or not reported.\norg: org is org-level governance policy.\nowner: owner is owner-level governance policy.\nkit: kit is the sandbox-scoped policy a kit contributes.\nattached: attached is a governance policy bound to the sandbox: an inline document or a referenced policy id, materialized and bound by the governance plane at create.\ngateway: gateway is an enforced runtime-owned gateway policy contribution, not a backend service-route exemption.\ndefault: default is an explicit installed default-policy contribution, not a substitute for unknown provenance or an owner-level policy.", + "enum": [ + "unspecified", + "org", + "owner", + "kit", + "attached", + "gateway", + "default" + ], + "title": "PolicyLayer", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/PolicyLayer/" + }, + { + "name": "PolicyLogEntry", + "pointer": "/components/schemas/PolicyLogEntry", + "schema": { + "description": "PolicyLogEntry is an aggregated observed policy decision.", + "properties": { + "count": { + "description": "count is the number of coalesced observations.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "decision": { + "$ref": "#/components/schemas/PolicyDecision", + "description": "decision is the observed allow or block outcome." + }, + "domain": { + "$ref": "#/components/schemas/PolicyDomain", + "description": "domain is the policy domain that emitted the entry." + }, + "firstSeen": { + "$ref": "#/components/schemas/Timestamp", + "description": "first_seen is the first observation timestamp." + }, + "lastSeen": { + "$ref": "#/components/schemas/Timestamp", + "description": "last_seen is the most recent observation timestamp." + }, + "proxyType": { + "description": "proxy_type is the proxy or enforcement path that observed the decision.", + "type": "string" + }, + "reason": { + "description": "reason is backend-readable context.", + "type": "string" + }, + "resource": { + "description": "resource is the requested destination or resource.", + "type": "string" + }, + "rule": { + "description": "rule is the matching rule when available.", + "type": "string" + }, + "sandbox": { + "description": "sandbox is the resource name recorded for this reference.", + "type": "string" + }, + "sandboxUid": { + "description": "sandbox_uid retains the observed backing incarnation when the backend provides one.", + "readOnly": true, + "type": [ + "string", + "null" + ] + } + }, + "title": "PolicyLogEntry", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PolicyLogEntry/" + }, + { + "name": "Port", + "pointer": "/components/schemas/Port", + "schema": { + "description": "Port is one sandbox port made reachable from outside the sandbox. The same\nfacts appear inline on SandboxCore.ports for a caller reading the sandbox.", + "properties": { + "etag": { + "description": "etag identifies the observed version of this port.", + "readOnly": true, + "type": "string" + }, + "name": { + "description": "(IDENTIFIER) name identifies the published port number under its sandbox resource name.", + "type": "string" + }, + "number": { + "description": "(IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS.", + "format": "int32", + "maximum": 65535, + "minimum": 1, + "type": "integer" + }, + "protocol": { + "$ref": "#/components/schemas/Protocol", + "description": "(IMMUTABLE) protocol defaults to TCP when unspecified." + }, + "uid": { + "description": "(IMMUTABLE) uid is the durable publication incarnation when the backend provides one.", + "readOnly": true, + "type": [ + "string", + "null" + ] + }, + "url": { + "description": "url is the required externally reachable address, including host-local addresses.", + "readOnly": true, + "type": "string" + } + }, + "required": [ + "number" + ], + "title": "Port", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Port/" + }, + { + "name": "PreconditionFailure", + "pointer": "/components/schemas/PreconditionFailure", + "schema": { + "description": "Describes what preconditions have failed.\n\nFor example, if an operation failed because it required the Terms of Service to be\nacknowledged, it could list the terms of service violation in the\nPreconditionFailure message.", + "properties": { + "violations": { + "description": "Describes all precondition violations.", + "items": { + "$ref": "#/components/schemas/PreconditionFailureViolation" + }, + "type": "array" + } + }, + "title": "PreconditionFailure", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PreconditionFailure/" + }, + { + "name": "PreconditionFailureErrorDetail", + "pointer": "/components/schemas/PreconditionFailureErrorDetail", + "schema": { + "description": "Describes what preconditions have failed.\n\nFor example, if an operation failed because it required the Terms of Service to be\nacknowledged, it could list the terms of service violation in the\nPreconditionFailure message.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.PreconditionFailure", + "type": "string" + }, + "violations": { + "description": "Describes all precondition violations.", + "items": { + "$ref": "#/components/schemas/PreconditionFailureViolation" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "PreconditionFailureErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PreconditionFailureErrorDetail/" + }, + { + "name": "PreconditionFailureViolation", + "pointer": "/components/schemas/PreconditionFailureViolation", + "schema": { + "description": "A message type used to describe a single precondition failure.", + "properties": { + "description": { + "description": "A description of how the precondition failed. Developers can use this\ndescription to understand how to fix the failure.\n\nFor example: \"Terms of service not accepted\".", + "type": "string" + }, + "subject": { + "description": "The subject, relative to the type, that failed.\nFor example, \"google.com/cloud\" relative to the \"TOS\" type would indicate\nwhich terms of service is being referenced.", + "type": "string" + }, + "type": { + "description": "The type of PreconditionFailure. We recommend using a service-specific\nenum type to define the supported precondition violation subjects. For\nexample, \"TOS\" for \"Terms of Service violation\".", + "type": "string" + } + }, + "title": "Violation", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PreconditionFailureViolation/" + }, + { + "name": "Process", + "pointer": "/components/schemas/Process", + "schema": { + "description": "Process is the handle returned before interaction begins.", + "properties": { + "exitCode": { + "description": "exit_code is the process exit code, set only when state is exited and absent otherwise.", + "format": "int32", + "type": [ + "integer", + "null" + ] + }, + "label": { + "description": "(IMMUTABLE) label retains the unique, immutable process label and its generated default.", + "minLength": 1, + "type": "string" + }, + "lastStreamSequence": { + "description": "last_stream_sequence is the highest stream_sequence emitted for the process when this report was assembled; 0 before any output.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "name": { + "description": "(IDENTIFIER) name is scoped to the discovered sandbox endpoint API base.", + "type": "string" + }, + "pid": { + "description": "pid is the process id inside the sandbox when available.", + "format": "int32", + "type": "integer" + }, + "receiptKind": { + "$ref": "#/components/schemas/ReceiptKind", + "description": "receipt_kind classifies this response on CreateProcess; every other operation\nreturning a Process, including ListProcesses, always reports unspecified." + }, + "session": { + "description": "session is the session tag from the create, empty when untagged.", + "type": "string" + }, + "state": { + "$ref": "#/components/schemas/ProcessState", + "description": "state is the process state, concrete in conforming responses." + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing process incarnation, also used as the resource name terminal.", + "readOnly": true, + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "label" + ], + "title": "Process", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Process/" + }, + { + "name": "ProcessAttach", + "pointer": "/components/schemas/ProcessAttach", + "schema": { + "additionalProperties": false, + "description": "Attach selects the process and output resume point.", + "properties": { + "name": { + "description": "name is the complete resource name, in the form processes/{process}.", + "pattern": "^processes/[^/]+$", + "type": "string" + }, + "resumeFrom": { + "description": "resume_from resumes after a received or published stream_sequence; 0 means from the start. Missing output after this point fails with FAILED_PRECONDITION.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "required": [ + "name" + ], + "title": "Attach", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessAttach/" + }, + { + "name": "ProcessChunk", + "pointer": "/components/schemas/ProcessChunk", + "schema": { + "description": "Chunk carries process output.", + "properties": { + "data": { + "description": "data is output bytes.", + "format": "byte", + "type": "string" + }, + "stream": { + "$ref": "#/components/schemas/StreamType", + "description": "stream identifies stdout, stderr, or PTY output." + }, + "streamSequence": { + "description": "stream_sequence is one-based and strictly increases per process output stream.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "title": "Chunk", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessChunk/" + }, + { + "name": "ProcessExited", + "pointer": "/components/schemas/ProcessExited", + "schema": { + "description": "Exited reports process completion.", + "properties": { + "exitCode": { + "description": "exit_code is the process exit code.", + "format": "int32", + "type": "integer" + }, + "reason": { + "description": "reason is backend-readable exit context.", + "type": "string" + } + }, + "title": "Exited", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessExited/" + }, + { + "name": "ProcessHeartbeat", + "pointer": "/components/schemas/ProcessHeartbeat", + "schema": { + "additionalProperties": false, + "description": "Heartbeat is an idle keepalive frame.", + "title": "Heartbeat", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessHeartbeat/" + }, + { + "name": "ProcessOutput", + "pointer": "/components/schemas/ProcessOutput", + "schema": { + "dependentSchemas": { + "chunk": { + "not": { + "anyOf": [ + { + "required": [ + "exited" + ] + }, + { + "required": [ + "heartbeat" + ] + } + ] + } + }, + "exited": { + "not": { + "anyOf": [ + { + "required": [ + "chunk" + ] + }, + { + "required": [ + "heartbeat" + ] + } + ] + } + }, + "heartbeat": { + "not": { + "anyOf": [ + { + "required": [ + "chunk" + ] + }, + { + "required": [ + "exited" + ] + } + ] + } + } + }, + "description": "Output is one server frame on an interaction stream. At most one of chunk, exited, heartbeat is set.", + "properties": { + "chunk": { + "$ref": "#/components/schemas/ProcessChunk", + "description": "chunk carries ordered process output." + }, + "exited": { + "$ref": "#/components/schemas/ProcessExited", + "description": "exited reports process completion." + }, + "heartbeat": { + "$ref": "#/components/schemas/ProcessHeartbeat", + "description": "heartbeat keeps an idle stream alive and carries no resume position." + } + }, + "title": "Output", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessOutput/" + }, + { + "name": "ProcessSignal", + "pointer": "/components/schemas/ProcessSignal", + "schema": { + "description": "Signal is a process signal.\n\nValues:\nunspecified: unspecified is invalid.\nterm: term requests graceful termination.\nkill: kill requests immediate termination.\nint: int requests interrupt.\nhup: hup requests hangup.\nquit: quit requests quit.\nusr1: usr1 requests user signal 1.\nusr2: usr2 requests user signal 2.", + "enum": [ + "unspecified", + "term", + "kill", + "int", + "hup", + "quit", + "usr1", + "usr2" + ], + "title": "Signal", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessSignal/" + }, + { + "name": "ProcessState", + "pointer": "/components/schemas/ProcessState", + "schema": { + "description": "ProcessState is the coarse process lifecycle a process report carries.\n\nValues:\nunspecified: unspecified is not a concrete state; conforming responses never use it.\nrunning: running means the process has not exited.\nexited: exited means the process has exited.", + "enum": [ + "unspecified", + "running", + "exited" + ], + "title": "ProcessState", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ProcessState/" + }, + { + "name": "Protocol", + "pointer": "/components/schemas/Protocol", + "schema": { + "description": "Protocol names the transport protocol for a published port.\n\nValues:\nunspecified: unspecified means the backend default, TCP.\ntcp: tcp publishes TCP traffic.\nudp: udp publishes UDP traffic.\ntcp4: tcp4 publishes IPv4 TCP traffic.\ntcp6: tcp6 publishes IPv6 TCP traffic.\nudp4: udp4 publishes IPv4 UDP traffic.\nudp6: udp6 publishes IPv6 UDP traffic.", + "enum": [ + "unspecified", + "tcp", + "udp", + "tcp4", + "tcp6", + "udp4", + "udp6" + ], + "title": "Protocol", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/Protocol/" + }, + { + "name": "PtyConfig", + "pointer": "/components/schemas/PtyConfig", + "schema": { + "additionalProperties": false, + "description": "PtyConfig configures pseudo-terminal creation.", + "properties": { + "initialSize": { + "$ref": "#/components/schemas/TerminalSize", + "description": "initial_size requests an initial terminal size; absence selects a backend-defined size." + } + }, + "title": "PtyConfig", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PtyConfig/" + }, + { + "name": "PublishedPort", + "pointer": "/components/schemas/PublishedPort", + "schema": { + "description": "PublishedPort reports external reachability for one sandbox port.", + "properties": { + "hostIp": { + "description": "host_ip is the local host bind address when relevant.", + "type": "string" + }, + "hostPort": { + "description": "host_port is the local host port when relevant.", + "type": "integer" + }, + "protocol": { + "$ref": "#/components/schemas/Protocol", + "description": "protocol is the published protocol." + }, + "sandboxPort": { + "description": "sandbox_port is the port inside the sandbox.", + "type": "integer" + }, + "url": { + "description": "url is the required externally reachable address, including host-local addresses.", + "type": "string" + } + }, + "title": "PublishedPort", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/PublishedPort/" + }, + { + "name": "QuotaFailure", + "pointer": "/components/schemas/QuotaFailure", + "schema": { + "description": "Describes how a quota check failed.\n\nFor example if a daily limit was exceeded for the calling project,\na service could respond with a QuotaFailure detail containing the project\nid and the description of the quota limit that was exceeded. If the\ncalling project hasn't enabled the service in the developer console, then\na service could respond with the project id and set `service_disabled`\nto true.\n\nAlso see RetryInfo and Help types for other details about handling a\nquota failure.", + "properties": { + "violations": { + "description": "Describes all quota violations.", + "items": { + "$ref": "#/components/schemas/QuotaFailureViolation" + }, + "type": "array" + } + }, + "title": "QuotaFailure", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/QuotaFailure/" + }, + { + "name": "QuotaFailureErrorDetail", + "pointer": "/components/schemas/QuotaFailureErrorDetail", + "schema": { + "description": "Describes how a quota check failed.\n\nFor example if a daily limit was exceeded for the calling project,\na service could respond with a QuotaFailure detail containing the project\nid and the description of the quota limit that was exceeded. If the\ncalling project hasn't enabled the service in the developer console, then\na service could respond with the project id and set `service_disabled`\nto true.\n\nAlso see RetryInfo and Help types for other details about handling a\nquota failure.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.QuotaFailure", + "type": "string" + }, + "violations": { + "description": "Describes all quota violations.", + "items": { + "$ref": "#/components/schemas/QuotaFailureViolation" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "QuotaFailureErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/QuotaFailureErrorDetail/" + }, + { + "name": "QuotaFailureViolation", + "pointer": "/components/schemas/QuotaFailureViolation", + "schema": { + "description": "A message type used to describe a single quota violation. For example, a\ndaily quota or a custom quota that was exceeded.", + "properties": { + "apiService": { + "description": "The API Service from which the `QuotaFailure.Violation` orginates. In\nsome cases, Quota issues originate from an API Service other than the one\nthat was called. In other words, a dependency of the called API Service\ncould be the cause of the `QuotaFailure`, and this field would have the\ndependency API service name.\n\nFor example, if the called API is Kubernetes Engine API\n(container.googleapis.com), and a quota violation occurs in the\nKubernetes Engine API itself, this field would be\n\"container.googleapis.com\". On the other hand, if the quota violation\noccurs when the Kubernetes Engine API creates VMs in the Compute Engine\nAPI (compute.googleapis.com), this field would be\n\"compute.googleapis.com\".", + "type": "string" + }, + "description": { + "description": "A description of how the quota check failed. Clients can use this\ndescription to find more about the quota configuration in the service's\npublic documentation, or find the relevant quota limit to adjust through\ndeveloper console.\n\nFor example: \"Service disabled\" or \"Daily Limit for read operations\nexceeded\".", + "type": "string" + }, + "futureQuotaValue": { + "description": "The new quota value being rolled out at the time of the violation. At the\ncompletion of the rollout, this value will be enforced in place of\nquota_value. If no rollout is in progress at the time of the violation,\nthis field is not set.\n\nFor example, if at the time of the violation a rollout is in progress\nchanging the number of CPUs quota from 10 to 20, 20 would be the value of\nthis field.", + "format": "int64", + "type": [ + "integer", + "string", + "null" + ] + }, + "quotaDimensions": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "The dimensions of the violated quota. Every non-global quota is enforced\non a set of dimensions. While quota metric defines what to count, the\ndimensions specify for what aspects the counter should be increased.\n\nFor example, the quota \"CPUs per region per VM family\" enforces a limit\non the metric \"compute.googleapis.com/cpus_per_vm_family\" on dimensions\n\"region\" and \"vm_family\". And if the violation occurred in region\n\"us-central1\" and for VM family \"n1\", the quota_dimensions would be,\n\n{\n\"region\": \"us-central1\",\n\"vm_family\": \"n1\",\n}\n\nWhen a quota is enforced globally, the quota_dimensions would always be\nempty.", + "type": "object" + }, + "quotaId": { + "description": "The id of the violated quota. Also know as \"limit name\", this is the\nunique identifier of a quota in the context of an API service.\n\nFor example, \"CPUS-PER-VM-FAMILY-per-project-region\".", + "type": "string" + }, + "quotaMetric": { + "description": "The metric of the violated quota. A quota metric is a named counter to\nmeasure usage, such as API requests or CPUs. When an activity occurs in a\nservice, such as Virtual Machine allocation, one or more quota metrics\nmay be affected.\n\nFor example, \"compute.googleapis.com/cpus_per_vm_family\",\n\"storage.googleapis.com/internet_egress_bandwidth\".", + "type": "string" + }, + "quotaValue": { + "description": "The enforced quota value at the time of the `QuotaFailure`.\n\nFor example, if the enforced quota value at the time of the\n`QuotaFailure` on the number of CPUs is \"10\", then the value of this\nfield would reflect this quantity.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "subject": { + "description": "The subject on which the quota check failed.\nFor example, \"clientip:\u003cip address of client\u003e\" or \"project:\u003cGoogle\ndeveloper project id\u003e\".", + "type": "string" + } + }, + "title": "Violation", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/QuotaFailureViolation/" + }, + { + "name": "RawImageStartup", + "pointer": "/components/schemas/RawImageStartup", + "schema": { + "additionalProperties": false, + "description": "RawImageStartup resolves identity and working directory from the pinned image.", + "properties": { + "start": { + "$ref": "#/components/schemas/StartupArgv", + "description": "start replaces the complete launch argv; omission uses the image command." + } + }, + "title": "RawImageStartup", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/RawImageStartup/" + }, + { + "name": "ReadOutputResponse", + "pointer": "/components/schemas/ReadOutputResponse", + "schema": { + "description": "ReadOutputResponse is one page of ordered output.", + "properties": { + "chunks": { + "description": "chunks is retained output in stream_sequence order, possibly empty.", + "items": { + "$ref": "#/components/schemas/ProcessChunk" + }, + "type": "array" + }, + "exited": { + "$ref": "#/components/schemas/ProcessExited", + "description": "exited is set once the process has exited and no retained bytes follow next_resume_from." + }, + "nextResumeFrom": { + "description": "next_resume_from is the stream_sequence to pass next; equal to resume_from\nwhen nothing new was retained.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "title": "ReadOutputResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ReadOutputResponse/" + }, + { + "name": "ReceiptKind", + "pointer": "/components/schemas/ReceiptKind", + "schema": { + "description": "ReceiptKind classifies whether a CreateProcess response was freshly assembled or\nis the retained receipt of an earlier accepted request.\n\nValues:\nunspecified: unspecified is not a concrete classification; a backend or a client generated before this field existed reports or reads this. It asserts neither freshness nor replay.\nfresh: fresh means this Process was assembled for this specific accepted request; last_stream_sequence reflects live state as of that acceptance.\nreplay: replay means the backend returned the retained result of an earlier accepted request under the synchronous mutation replay rule; last_stream_sequence is frozen at the value observed during that original acceptance.", + "enum": [ + "unspecified", + "fresh", + "replay" + ], + "title": "ReceiptKind", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ReceiptKind/" + }, + { + "name": "RequestInfo", + "pointer": "/components/schemas/RequestInfo", + "schema": { + "description": "Contains metadata about the request that clients can attach when filing a bug\nor providing other forms of feedback.", + "properties": { + "requestId": { + "description": "An opaque string that should only be interpreted by the service generating\nit. For example, it can be used to identify requests in the service's logs.", + "type": "string" + }, + "servingData": { + "description": "Any data that was used to serve this request. For example, an encrypted\nstack trace that can be sent back to the service provider for debugging.", + "type": "string" + } + }, + "title": "RequestInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/RequestInfo/" + }, + { + "name": "RequestInfoErrorDetail", + "pointer": "/components/schemas/RequestInfoErrorDetail", + "schema": { + "description": "Contains metadata about the request that clients can attach when filing a bug\nor providing other forms of feedback.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.RequestInfo", + "type": "string" + }, + "requestId": { + "description": "An opaque string that should only be interpreted by the service generating\nit. For example, it can be used to identify requests in the service's logs.", + "type": "string" + }, + "servingData": { + "description": "Any data that was used to serve this request. For example, an encrypted\nstack trace that can be sent back to the service provider for debugging.", + "type": "string" + } + }, + "required": [ + "@type" + ], + "title": "RequestInfoErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/RequestInfoErrorDetail/" + }, + { + "name": "ResourceInfo", + "pointer": "/components/schemas/ResourceInfo", + "schema": { + "description": "Describes the resource that is being accessed.", + "properties": { + "description": { + "description": "Describes what error is encountered when accessing this resource.\nFor example, updating a cloud project may require the `writer` permission\non the developer console project.", + "type": "string" + }, + "owner": { + "description": "The owner of the resource (optional).\nFor example, \"user:\u003cowner email\u003e\" or \"project:\u003cGoogle developer project\nid\u003e\".", + "type": "string" + }, + "resourceName": { + "description": "The name of the resource being accessed. For example, a shared calendar\nname: \"example.com_4fghdhgsrgh@group.calendar.google.com\", if the current\nerror is\n[CodePERMISSION_DENIED][CodePERMISSION_DENIED].", + "type": "string" + }, + "resourceType": { + "description": "A name for the type of resource being accessed, e.g. \"sql table\",\n\"cloud storage bucket\", \"file\", \"Google calendar\"; or the type URL\nof the resource: e.g. \"type.googleapis.com/google.pubsub.v1.Topic\".", + "type": "string" + } + }, + "title": "ResourceInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ResourceInfo/" + }, + { + "name": "ResourceInfoErrorDetail", + "pointer": "/components/schemas/ResourceInfoErrorDetail", + "schema": { + "description": "Describes the resource that is being accessed.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.ResourceInfo", + "type": "string" + }, + "description": { + "description": "Describes what error is encountered when accessing this resource.\nFor example, updating a cloud project may require the `writer` permission\non the developer console project.", + "type": "string" + }, + "owner": { + "description": "The owner of the resource (optional).\nFor example, \"user:\u003cowner email\u003e\" or \"project:\u003cGoogle developer project\nid\u003e\".", + "type": "string" + }, + "resourceName": { + "description": "The name of the resource being accessed. For example, a shared calendar\nname: \"example.com_4fghdhgsrgh@group.calendar.google.com\", if the current\nerror is\n[CodePERMISSION_DENIED][CodePERMISSION_DENIED].", + "type": "string" + }, + "resourceType": { + "description": "A name for the type of resource being accessed, e.g. \"sql table\",\n\"cloud storage bucket\", \"file\", \"Google calendar\"; or the type URL\nof the resource: e.g. \"type.googleapis.com/google.pubsub.v1.Topic\".", + "type": "string" + } + }, + "required": [ + "@type" + ], + "title": "ResourceInfoErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ResourceInfoErrorDetail/" + }, + { + "name": "Resources", + "pointer": "/components/schemas/Resources", + "schema": { + "additionalProperties": false, + "description": "Resources describes sandbox CPU and memory allocation.", + "properties": { + "cpus": { + "description": "cpus is present only when the caller or backend chooses a CPU count.", + "type": [ + "integer", + "null" + ] + }, + "memoryMib": { + "description": "memory_mib is present only when the caller or backend chooses memory.", + "format": "int64", + "type": [ + "integer", + "string", + "null" + ] + } + }, + "title": "Resources", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Resources/" + }, + { + "name": "RetryInfo", + "pointer": "/components/schemas/RetryInfo", + "schema": { + "description": "Describes when the clients can retry a failed request. Clients could ignore\nthe recommendation here or retry when this information is missing from error\nresponses.\n\nIt's always recommended that clients should use exponential backoff when\nretrying.\n\nClients should wait until `retry_delay` amount of time has passed since\nreceiving the error response before retrying. If retrying requests also\nfail, clients should use an exponential backoff scheme to gradually increase\nthe delay between retries based on `retry_delay`, until either a maximum\nnumber of retries have been reached or a maximum retry delay cap has been\nreached.", + "properties": { + "retryDelay": { + "$ref": "#/components/schemas/Duration", + "description": "Clients should wait at least this long between retrying the same request." + } + }, + "title": "RetryInfo", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/RetryInfo/" + }, + { + "name": "RetryInfoErrorDetail", + "pointer": "/components/schemas/RetryInfoErrorDetail", + "schema": { + "description": "Describes when the clients can retry a failed request. Clients could ignore\nthe recommendation here or retry when this information is missing from error\nresponses.\n\nIt's always recommended that clients should use exponential backoff when\nretrying.\n\nClients should wait until `retry_delay` amount of time has passed since\nreceiving the error response before retrying. If retrying requests also\nfail, clients should use an exponential backoff scheme to gradually increase\nthe delay between retries based on `retry_delay`, until either a maximum\nnumber of retries have been reached or a maximum retry delay cap has been\nreached.", + "properties": { + "@type": { + "const": "type.googleapis.com/google.rpc.RetryInfo", + "type": "string" + }, + "retryDelay": { + "$ref": "#/components/schemas/Duration", + "description": "Clients should wait at least this long between retrying the same request." + } + }, + "required": [ + "@type" + ], + "title": "RetryInfoErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/RetryInfoErrorDetail/" + }, + { + "name": "Sandbox", + "pointer": "/components/schemas/Sandbox", + "schema": { + "description": "Sandbox carries shared core state and the effective state of its selected features.\nuid must equal the immutable resource ID in name", + "properties": { + "core": { + "$ref": "#/components/schemas/SandboxCore", + "description": "core is the backend-neutral sandbox view." + }, + "displayName": { + "description": "display_name is the scoped label; UpdateSandbox changes it without changing identity.", + "type": "string" + }, + "effectiveFeatures": { + "$ref": "#/components/schemas/EffectiveFeatures", + "description": "effective_features is emitted only by the composition contract projection." + }, + "failure": { + "$ref": "#/components/schemas/Error", + "description": "failure is present only while status is FAILED and clears on recovery.", + "readOnly": true + }, + "name": { + "description": "(IDENTIFIER) name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^sandboxes/[^/]+$", + "type": "string" + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + } + }, + "required": [ + "core", + "name", + "uid" + ], + "title": "Sandbox", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Sandbox/" + }, + { + "name": "SandboxCore", + "pointer": "/components/schemas/SandboxCore", + "schema": { + "allOf": [ + { + "properties": { + "agent": { + "description": "agent is the named agent profile, empty for raw image/start-command sandboxes.", + "type": "string" + }, + "appliedKits": { + "description": "applied_kits records kits active in the sandbox.", + "items": { + "$ref": "#/components/schemas/AppliedKit" + }, + "type": "array" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation time." + }, + "endpoint": { + "$ref": "#/components/schemas/SandboxEndpoint", + "description": "endpoint is where process and file services are served for this sandbox." + }, + "environment": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "environment is non-secret environment metadata.", + "type": "object" + }, + "etag": { + "description": "etag identifies the observed version of this resource. It is opaque and strong,\nchanges on every visible change, and is what a mutation sends as its precondition.", + "minLength": 1, + "pattern": "^\"[^\"\\x00-\\x20\\x7f]*\"$", + "readOnly": true, + "type": "string" + }, + "labels": { + "additionalProperties": { + "title": "value", + "type": "string" + }, + "description": "labels are non-secret caller-assigned key/value metadata.", + "type": "object" + }, + "origin": { + "description": "origin is set by merged views to identify the backend that owns this sandbox.", + "type": "string" + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform is the canonical placed platform." + }, + "ports": { + "description": "ports are the currently published ports.", + "items": { + "$ref": "#/components/schemas/PublishedPort" + }, + "type": "array" + }, + "resources": { + "$ref": "#/components/schemas/Resources", + "description": "resources are the sandbox resources." + }, + "status": { + "$ref": "#/components/schemas/SandboxStatus", + "description": "status is the coarse lifecycle state.", + "not": { + "enum": [ + "unspecified" + ] + }, + "readOnly": true + } + } + }, + { + "dependentSchemas": { + "image": { + "not": { + "anyOf": [ + { + "required": [ + "imageRef" + ] + } + ] + } + }, + "imageRef": { + "not": { + "anyOf": [ + { + "required": [ + "image" + ] + } + ] + } + } + }, + "properties": { + "image": { + "description": "image is the managed Image resource name.", + "pattern": "^images/[^/]+$", + "type": "string" + }, + "imageRef": { + "description": "image_ref is an external OCI reference, with the existing backend validation.", + "type": "string" + } + } + } + ], + "description": "SandboxCore is the backend-neutral sandbox view. At most one of image, imageRef is set.", + "required": [ + "status", + "createdAt", + "etag" + ], + "title": "SandboxCore", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/SandboxCore/" + }, + { + "name": "SandboxEndpoint", + "pointer": "/components/schemas/SandboxEndpoint", + "schema": { + "dependentSchemas": { + "authentication": { + "allOf": [ + { + "oneOf": [ + { + "properties": { + "authentication": { + "properties": { + "scheme": { + "const": "scopedBearer" + } + } + }, + "credentialAudience": { + "minLength": 1 + }, + "protocol": { + "const": "http" + } + }, + "required": [ + "credentialAudience" + ] + }, + { + "properties": { + "authentication": { + "properties": { + "scheme": { + "const": "localSocket" + } + } + }, + "credentialAudience": { + "const": "" + }, + "protocol": { + "const": "unixSocket" + } + } + } + ], + "required": [ + "protocol" + ] + } + ] + } + }, + "description": "SandboxEndpoint tells a client where sandbox endpoint services are served.\nnetwork endpoints require scoped credentials; Unix sockets use actual socket access controls\nsandbox must contain the endpoint's immutable sandbox UID", + "properties": { + "apiVersion": { + "const": "v1", + "description": "api_version identifies the /v1 endpoint contract before the client connects.", + "type": "string" + }, + "authentication": { + "$ref": "#/components/schemas/EndpointAuthentication" + }, + "capabilities": { + "description": "capabilities lists supported public operation IDs, independently of caller grants.", + "items": { + "pattern": "^[a-z][A-Za-z0-9]*$", + "type": "string" + }, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "credentialAudience": { + "description": "credential_audience is server-controlled and required for network endpoints.", + "type": "string" + }, + "protocol": { + "$ref": "#/components/schemas/SandboxEndpointProtocol", + "description": "protocol identifies the endpoint transport." + }, + "sandbox": { + "description": "sandbox names the immutable sandbox incarnation served by this endpoint.", + "pattern": "^sandboxes/[^/]+$", + "type": "string" + }, + "sandboxUid": { + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + }, + "uri": { + "description": "uri is the endpoint API base; preserve its path prefix when appending /v1 routes.", + "type": "string" + } + }, + "required": [ + "sandbox", + "sandboxUid", + "apiVersion", + "capabilities", + "authentication" + ], + "title": "SandboxEndpoint", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/SandboxEndpoint/" + }, + { + "name": "SandboxEndpointProtocol", + "pointer": "/components/schemas/SandboxEndpointProtocol", + "schema": { + "description": "SandboxEndpointProtocol identifies the transport used by a sandbox endpoint.\n\nValues:\nunspecified: unspecified is not a concrete endpoint protocol.\nhttp: http is the REST API over HTTP.\nunixSocket: unixSocket is a local unix socket.", + "enum": [ + "unspecified", + "http", + "unixSocket" + ], + "title": "SandboxEndpointProtocol", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/SandboxEndpointProtocol/" + }, + { + "name": "SandboxStatus", + "pointer": "/components/schemas/SandboxStatus", + "schema": { + "description": "SandboxStatus is the backend-neutral lifecycle state.\n\nValues:\nunspecified: unspecified is never a concrete known state.\ncreating: creating means provisioning has not completed.\nstarting: starting means a stopped sandbox is starting or resuming.\nrunning: running means the sandbox is running.\nstopping: stopping means the sandbox is stopping or hibernating.\nstopped: stopped means the sandbox is not running and may be started.\nfailed: failed means the sandbox reached an unrecoverable failure.\ndeleting: deleting means deletion is accepted; reads continue until removal.\ndegraded: degraded means runtime contact is lost; recovery or failure may follow.", + "enum": [ + "unspecified", + "creating", + "starting", + "running", + "stopping", + "stopped", + "failed", + "deleting", + "degraded" + ], + "title": "SandboxStatus", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/SandboxStatus/" + }, + { + "name": "Secret", + "pointer": "/components/schemas/Secret", + "schema": { + "description": "Secret is returned metadata and never includes secret material.\nuid must equal the immutable resource ID in name", + "properties": { + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "etag": { + "description": "etag identifies the observed version of this resource. It is opaque and strong,\nchanges on every visible change, and is what a mutation sends as its precondition.", + "minLength": 1, + "pattern": "^\"[^\"\\x00-\\x20\\x7f]*\"$", + "readOnly": true, + "type": "string" + }, + "injection": { + "$ref": "#/components/schemas/CustomInjection", + "description": "injection is returned only for custom-shaped secrets." + }, + "name": { + "description": "(IDENTIFIER) name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^secrets/[^/]+$", + "type": "string" + }, + "oauthConfig": { + "$ref": "#/components/schemas/OAuthConfig", + "description": "oauth_config is returned only for OAuth-shaped secrets." + }, + "placeholder": { + "description": "placeholder is server-generated per custom secret and stable across value\nrotation; it is not secret material. A client presents it where the\ncredential would go; for the configured hosts the backend replaces the\nconfigured header's value at egress regardless of what was sent.", + "type": "string" + }, + "scopes": { + "description": "scopes are non-secret OAuth scopes.", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceType": { + "description": "service_type identifies the consuming service.", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/SecretType", + "description": "type identifies the stored material shape." + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "updated_at is the last update timestamp." + } + }, + "required": [ + "uid", + "name", + "createdAt", + "updatedAt", + "etag" + ], + "title": "Secret", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Secret/" + }, + { + "name": "SecretType", + "pointer": "/components/schemas/SecretType", + "schema": { + "description": "The stored credential shape: token, OAuth refresh material, custom injection, registry credentials, or a credential resolved from an approved host-owned source. Secret material is never returned.", + "enum": [ + "unspecified", + "token", + "oauthRefresh", + "custom", + "registryV2", + "hostResolved" + ], + "title": "SecretType", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/SecretType/" + }, + { + "name": "SignalResponse", + "pointer": "/components/schemas/SignalResponse", + "schema": { + "description": "SignalResponse has no fields.", + "title": "SignalResponse", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/SignalResponse/" + }, + { + "name": "Snapshot", + "pointer": "/components/schemas/Snapshot", + "schema": { + "description": "Snapshot is the detailed snapshot view.\nuid must equal the immutable resource ID in name", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode is the mode the snapshot was captured with." + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "description": { + "description": "description is caller-supplied text.", + "type": "string" + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "etag": { + "description": "etag identifies the observed version of this resource. It is opaque and strong,\nchanges on every visible change, and is what a mutation sends as its precondition.", + "minLength": 1, + "pattern": "^\"[^\"\\x00-\\x20\\x7f]*\"$", + "readOnly": true, + "type": "string" + }, + "failure": { + "$ref": "#/components/schemas/Error", + "description": "failure is set when status is FAILED." + }, + "name": { + "description": "(IDENTIFIER) name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^snapshots/[^/]+$", + "type": "string" + }, + "platform": { + "$ref": "#/components/schemas/Platform", + "description": "platform is the captured sandbox platform." + }, + "resources": { + "$ref": "#/components/schemas/Resources", + "description": "resources describes the captured sandbox resources." + }, + "sandbox": { + "description": "sandbox is the resource name recorded for this reference.", + "type": "string" + }, + "sandboxUid": { + "description": "sandbox_uid retains the observed backing incarnation when the backend provides one.", + "readOnly": true, + "type": [ + "string", + "null" + ] + }, + "status": { + "$ref": "#/components/schemas/SnapshotStatus", + "description": "status is the snapshot readiness state.", + "not": { + "enum": [ + "unspecified" + ] + }, + "readOnly": true + }, + "totalSizeBytes": { + "description": "total_size_bytes is the approximate stored snapshot size.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + } + }, + "required": [ + "uid", + "name", + "status", + "createdAt", + "etag" + ], + "title": "Snapshot", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Snapshot/" + }, + { + "name": "SnapshotStatus", + "pointer": "/components/schemas/SnapshotStatus", + "schema": { + "description": "SnapshotStatus is snapshot readiness state.\n\nValues:\nunspecified: unspecified is never a concrete known state.\ncreating: creating means capture has not completed.\nready: ready means the snapshot can be restored.\nfailed: failed means capture reached a terminal failure.\ndeleted: deleted means the backend exposes a retained delete tombstone.", + "enum": [ + "unspecified", + "creating", + "ready", + "failed", + "deleted" + ], + "title": "SnapshotStatus", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/SnapshotStatus/" + }, + { + "name": "SnapshotSummary", + "pointer": "/components/schemas/SnapshotSummary", + "schema": { + "description": "SnapshotSummary is the list view of a snapshot.\nuid must equal the immutable resource ID in name", + "properties": { + "captureMode": { + "$ref": "#/components/schemas/CaptureMode", + "description": "capture_mode is the mode the snapshot was captured with." + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "name": { + "description": "name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^snapshots/[^/]+$", + "type": "string" + }, + "sandbox": { + "description": "sandbox is the resource name recorded for this reference.", + "type": "string" + }, + "sandboxUid": { + "description": "sandbox_uid retains the observed backing incarnation when the backend provides one.", + "readOnly": true, + "type": [ + "string", + "null" + ] + }, + "status": { + "$ref": "#/components/schemas/SnapshotStatus", + "description": "status is the snapshot readiness state.", + "not": { + "enum": [ + "unspecified" + ] + } + }, + "totalSizeBytes": { + "description": "total_size_bytes is the approximate stored snapshot size.", + "format": "int64", + "type": [ + "integer", + "string" + ] + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + } + }, + "required": [ + "uid", + "name", + "status", + "createdAt" + ], + "title": "SnapshotSummary", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/SnapshotSummary/" + }, + { + "name": "StartupArgv", + "pointer": "/components/schemas/StartupArgv", + "schema": { + "additionalProperties": false, + "description": "StartupArgv preserves literal arguments, including empty positional arguments.\nstartup argv requires a nonempty executable", + "properties": { + "argv": { + "description": "argv is executed without shell expansion. It carries at least one element,\nand that first element is the executable and must not be empty.", + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "argv" + ], + "title": "StartupArgv", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/StartupArgv/" + }, + { + "name": "StartupExecution", + "pointer": "/components/schemas/StartupExecution", + "schema": { + "description": "StartupExecution retains the accepted execution promise across fresh boots.\nIt is ordinary create input.", + "oneOf": [ + { + "properties": { + "rawImage": { + "$ref": "#/components/schemas/RawImageStartup", + "description": "raw_image executes image commands using OCI identity and directory defaults." + } + }, + "required": [ + "rawImage" + ], + "title": "raw_image", + "type": "object" + } + ], + "title": "StartupExecution", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/StartupExecution/" + }, + { + "name": "StopMemoryOutcome", + "pointer": "/components/schemas/StopMemoryOutcome", + "schema": { + "description": "StopMemoryOutcome records the stop/start guarantee independently of location.\n\nValues:\nunspecified: unspecified is not an advertised or accepted guarantee.\ndiscard: discard retains disk and starts a fresh process tree.\npreserve: preserve restores the stopped process tree on start.", + "enum": [ + "unspecified", + "discard", + "preserve" + ], + "title": "StopMemoryOutcome", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/StopMemoryOutcome/" + }, + { + "name": "StoredSecretOptions", + "pointer": "/components/schemas/StoredSecretOptions", + "schema": { + "additionalProperties": false, + "description": "StoredSecretOptions resolves owner-scoped references before the workload can run.", + "properties": { + "secrets": { + "description": "secrets are complete Secret resource names resolved once at admission.", + "items": { + "pattern": "^secrets/[^/]+$", + "type": "string" + }, + "minItems": 1, + "type": "array" + } + }, + "required": [ + "secrets" + ], + "title": "StoredSecretOptions", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/StoredSecretOptions/" + }, + { + "name": "StreamType", + "pointer": "/components/schemas/StreamType", + "schema": { + "description": "StreamType identifies the source of an output chunk.\n\nValues:\nunspecified: unspecified is not a concrete output stream.\nstdout: stdout is stdout.\nstderr: stderr is stderr.\npty: pty is merged PTY output.", + "enum": [ + "unspecified", + "stdout", + "stderr", + "pty" + ], + "title": "StreamType", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/StreamType/" + }, + { + "name": "TerminalSize", + "pointer": "/components/schemas/TerminalSize", + "schema": { + "additionalProperties": false, + "description": "TerminalSize is a terminal rows/columns pair; 1 through 65535 is the portable range.\nbounded requires rows and cols in 1..65535", + "properties": { + "bounded": { + "description": "bounded requests the portable range enforced on this size, with no opt in\nto perform first. Unset or false keeps the unenforced behavior.", + "type": "boolean" + }, + "cols": { + "description": "cols is the terminal column count.", + "type": "integer" + }, + "rows": { + "description": "rows is the terminal row count.", + "type": "integer" + } + }, + "title": "TerminalSize", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/TerminalSize/" + }, + { + "name": "TimeoutAction", + "pointer": "/components/schemas/TimeoutAction", + "schema": { + "description": "TimeoutAction selects the lifecycle action taken at the reported deadline.\n\nValues:\nunspecified: unspecified is invalid when explicitly supplied.\ndelete: delete deletes the sandbox at expiry.\nstop: stop applies the sandbox's persisted stop guarantee at expiry.\nkeep: Deprecated alias for the restart action, still accepted on input and output. New clients should use the canonical restart action.\nrestart: Preserves memory through backend-managed stop/resume cycles at expiry. Requires memory preservation and the always-on entitlement.", + "enum": [ + "unspecified", + "delete", + "stop", + "keep", + "restart" + ], + "title": "TimeoutAction", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/TimeoutAction/" + }, + { + "name": "TimeoutOptions", + "pointer": "/components/schemas/TimeoutOptions", + "schema": { + "additionalProperties": false, + "description": "TimeoutOptions selects deadline behavior; presence enables this feature for the sandbox.\nan explicit RESTART (or its deprecated alias KEEP) initial timeout must be at least one hour", + "properties": { + "autoResume": { + "description": "Omission selects the advertised default; false does not disable RESTART or KEEP cycles.", + "type": [ + "boolean", + "null" + ] + }, + "onTimeout": { + "description": "on_timeout defaults to DELETE; an explicit UNSPECIFIED is invalid.", + "not": { + "enum": [ + "unspecified" + ] + }, + "oneOf": [ + { + "$ref": "#/components/schemas/TimeoutAction" + }, + { + "type": "null" + } + ] + }, + "timeout": { + "$ref": "#/components/schemas/Duration", + "description": "timeout is the initial TTL; omission selects the advertised action default." + } + }, + "title": "TimeoutOptions", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/TimeoutOptions/" + }, + { + "name": "Timestamp", + "pointer": "/components/schemas/Timestamp", + "schema": { + "description": "An RFC 3339 timestamp in UTC, for example 2026-01-02T03:04:05Z.", + "examples": [ + "2023-01-15T01:30:15.01Z", + "2024-12-25T12:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/Timestamp/" + }, + { + "name": "TokenSecretMaterial", + "pointer": "/components/schemas/TokenSecretMaterial", + "schema": { + "additionalProperties": false, + "description": "TokenSecretMaterial is opaque token material.", + "properties": { + "value": { + "description": "value is the secret token.", + "minLength": 1, + "type": "string", + "writeOnly": true + } + }, + "required": [ + "value" + ], + "title": "TokenSecretMaterial", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/TokenSecretMaterial/" + }, + { + "name": "UnknownErrorDetail", + "pointer": "/components/schemas/UnknownErrorDetail", + "schema": { + "additionalProperties": true, + "description": "A structured error detail identified by @type. Its decoded JSON fields appear beside the type URL.", + "properties": { + "@type": { + "not": { + "enum": [ + "type.googleapis.com/google.rpc.BadRequest", + "type.googleapis.com/google.rpc.DebugInfo", + "type.googleapis.com/google.rpc.ErrorInfo", + "type.googleapis.com/google.rpc.Help", + "type.googleapis.com/google.rpc.LocalizedMessage", + "type.googleapis.com/google.rpc.PreconditionFailure", + "type.googleapis.com/google.rpc.QuotaFailure", + "type.googleapis.com/google.rpc.RequestInfo", + "type.googleapis.com/google.rpc.ResourceInfo", + "type.googleapis.com/google.rpc.RetryInfo", + "type.googleapis.com/buf.validate.Violations", + "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", + "type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport", + "type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport" + ] + }, + "type": "string" + } + }, + "required": [ + "@type" + ], + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/UnknownErrorDetail/" + }, + { + "name": "UpdateSecretBody", + "pointer": "/components/schemas/UpdateSecretBody", + "schema": { + "allOf": [ + { + "properties": { + "serviceType": { + "description": "service_type identifies the consuming service.", + "type": "string" + } + } + }, + { + "oneOf": [ + { + "properties": { + "custom": { + "$ref": "#/components/schemas/CustomSecretMaterial", + "description": "custom stores an opaque value with caller-authored injection metadata.\nUpdateSecretRequest.service_type is server-assigned for custom\nmaterial; leave it empty." + } + }, + "required": [ + "custom" + ], + "title": "custom", + "type": "object" + }, + { + "properties": { + "oauth": { + "$ref": "#/components/schemas/OAuthRefreshMaterial", + "description": "oauth stores OAuth refresh material." + } + }, + "required": [ + "oauth" + ], + "title": "oauth", + "type": "object" + }, + { + "properties": { + "token": { + "$ref": "#/components/schemas/TokenSecretMaterial", + "description": "token stores opaque token material." + } + }, + "required": [ + "token" + ], + "title": "token", + "type": "object" + } + ] + } + ], + "description": "UpdateSecretRequest replaces secret material.\nservice_type must be empty for custom material (server-assigned)", + "title": "UpdateSecretRequest", + "type": "object", + "unevaluatedProperties": false + }, + "url": "/reference/api/sandboxes/latest/schemas/UpdateSecretBody/" + }, + { + "name": "ValidationFieldPath", + "pointer": "/components/schemas/ValidationFieldPath", + "schema": { + "description": "A path to a field, including any parent fields.", + "properties": { + "elements": { + "description": "`elements` contains each element of the path, starting from the root and recursing downward.", + "items": { + "$ref": "#/components/schemas/ValidationFieldPathElement" + }, + "type": "array" + } + }, + "title": "FieldPath", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationFieldPath/" + }, + { + "name": "ValidationFieldPathElement", + "pointer": "/components/schemas/ValidationFieldPathElement", + "schema": { + "allOf": [ + { + "properties": { + "fieldName": { + "description": "`field_name` contains the field name this path element refers to.\nThis can be used to display a human-readable path even if the field number is unknown.", + "type": [ + "string", + "null" + ] + }, + "fieldNumber": { + "description": "`field_number` is the field number this path element refers to.", + "format": "int32", + "type": [ + "integer", + "null" + ] + }, + "fieldType": { + "description": "The type of the field that failed validation.", + "oneOf": [ + { + "$ref": "#/components/schemas/ValidationFieldType" + }, + { + "type": "null" + } + ] + }, + "keyType": { + "description": "`key_type` specifies the map key type of this field. This value is useful when traversing\nunknown fields through wire data: specifically, it allows handling the differences between\ndifferent integer encodings.", + "oneOf": [ + { + "$ref": "#/components/schemas/ValidationFieldType" + }, + { + "type": "null" + } + ] + }, + "valueType": { + "description": "`value_type` specifies map value type of this field. This is useful if you want to display a\nvalue inside unknown fields through wire data.", + "oneOf": [ + { + "$ref": "#/components/schemas/ValidationFieldType" + }, + { + "type": "null" + } + ] + } + } + }, + { + "oneOf": [ + { + "properties": { + "boolKey": { + "description": "`bool_key` specifies a map key of type bool.", + "type": "boolean" + } + }, + "required": [ + "boolKey" + ], + "title": "bool_key", + "type": "object" + }, + { + "properties": { + "index": { + "description": "`index` specifies a 0-based index into a repeated field.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "required": [ + "index" + ], + "title": "index", + "type": "object" + }, + { + "properties": { + "intKey": { + "description": "`int_key` specifies a map key of type int32, int64, sint32, sint64, sfixed32 or sfixed64.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "required": [ + "intKey" + ], + "title": "int_key", + "type": "object" + }, + { + "properties": { + "stringKey": { + "description": "`string_key` specifies a map key of type string.", + "type": "string" + } + }, + "required": [ + "stringKey" + ], + "title": "string_key", + "type": "object" + }, + { + "properties": { + "uintKey": { + "description": "`uint_key` specifies a map key of type uint32, uint64, fixed32 or fixed64.", + "format": "int64", + "type": [ + "integer", + "string" + ] + } + }, + "required": [ + "uintKey" + ], + "title": "uint_key", + "type": "object" + } + ] + } + ], + "description": "One field in a validation path. For a map or list, the subscript identifies the selected element.", + "title": "FieldPathElement", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationFieldPathElement/" + }, + { + "name": "ValidationFieldType", + "pointer": "/components/schemas/ValidationFieldType", + "schema": { + "enum": [ + "TYPE_DOUBLE", + "TYPE_FLOAT", + "TYPE_INT64", + "TYPE_UINT64", + "TYPE_INT32", + "TYPE_FIXED64", + "TYPE_FIXED32", + "TYPE_BOOL", + "TYPE_STRING", + "TYPE_GROUP", + "TYPE_MESSAGE", + "TYPE_BYTES", + "TYPE_UINT32", + "TYPE_ENUM", + "TYPE_SFIXED32", + "TYPE_SFIXED64", + "TYPE_SINT32", + "TYPE_SINT64" + ], + "title": "Type", + "type": "string" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationFieldType/" + }, + { + "name": "ValidationViolation", + "pointer": "/components/schemas/ValidationViolation", + "schema": { + "description": "A validation failure, with the affected field, rule, and a human-readable message.", + "properties": { + "field": { + "description": "The field that failed validation, including its parent fields.", + "oneOf": [ + { + "$ref": "#/components/schemas/ValidationFieldPath" + }, + { + "type": "null" + } + ] + }, + "forKey": { + "description": "`for_key` indicates whether the violation was caused by a map key, rather than a value.", + "type": [ + "boolean", + "null" + ] + }, + "message": { + "description": "`message` is a human-readable error message that describes the nature of the violation.\nThis can be the default error message from the violated `Rule`, or it can be a custom message that gives more context about the violation.", + "type": [ + "string", + "null" + ] + }, + "rule": { + "description": "The validation rule that failed.", + "oneOf": [ + { + "$ref": "#/components/schemas/ValidationFieldPath" + }, + { + "type": "null" + } + ] + }, + "ruleId": { + "description": "`rule_id` is the unique identifier of the `Rule` that was not fulfilled.\nThis is the same `id` that was specified in the `Rule` message, allowing easy tracing of which rule was violated.", + "type": [ + "string", + "null" + ] + } + }, + "title": "Violation", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationViolation/" + }, + { + "name": "ValidationViolations", + "pointer": "/components/schemas/ValidationViolations", + "schema": { + "description": "The validation failures returned for a request.", + "properties": { + "violations": { + "description": "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected.", + "items": { + "$ref": "#/components/schemas/ValidationViolation" + }, + "type": "array" + } + }, + "title": "Violations", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationViolations/" + }, + { + "name": "ValidationViolationsErrorDetail", + "pointer": "/components/schemas/ValidationViolationsErrorDetail", + "schema": { + "description": "The validation failures returned for a request.", + "properties": { + "@type": { + "const": "type.googleapis.com/buf.validate.Violations", + "type": "string" + }, + "violations": { + "description": "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected.", + "items": { + "$ref": "#/components/schemas/ValidationViolation" + }, + "type": "array" + } + }, + "required": [ + "@type" + ], + "title": "ViolationsErrorDetail", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/ValidationViolationsErrorDetail/" + }, + { + "name": "Volume", + "pointer": "/components/schemas/Volume", + "schema": { + "description": "Volume is persistent storage metadata within its owner and contract scope.\nuid must equal the immutable resource ID in name", + "properties": { + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "created_at is the creation timestamp." + }, + "displayName": { + "description": "display_name is a scoped label and never selects the resource.", + "type": "string" + }, + "etag": { + "description": "etag identifies the observed version of this resource. It is opaque and strong,\nchanges on every visible change, and is what a mutation sends as its precondition.", + "minLength": 1, + "pattern": "^\"[^\"\\x00-\\x20\\x7f]*\"$", + "readOnly": true, + "type": "string" + }, + "name": { + "description": "(IDENTIFIER) name ends in the immutable backing ID and never changes with display_name.", + "pattern": "^volumes/[^/]+$", + "type": "string" + }, + "uid": { + "description": "(IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment.", + "minLength": 1, + "readOnly": true, + "type": [ + "string" + ] + } + }, + "required": [ + "uid", + "name", + "createdAt", + "etag" + ], + "title": "Volume", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/Volume/" + }, + { + "name": "VolumeAttachment", + "pointer": "/components/schemas/VolumeAttachment", + "schema": { + "additionalProperties": false, + "description": "VolumeAttachment binds an existing owner-scoped volume before guest execution.", + "properties": { + "mode": { + "$ref": "#/components/schemas/AttachmentMode", + "description": "mode defaults to exclusive; it never silently enables shared writers." + }, + "target": { + "description": "target is an absolute guest path and cannot overlap another mount target.", + "minLength": 1, + "type": "string" + }, + "volume": { + "description": "volume is the complete resource name, in the form volumes/{volume}.", + "pattern": "^volumes/[^/]+$", + "type": "string" + } + }, + "required": [ + "volume", + "target" + ], + "title": "VolumeAttachment", + "type": "object" + }, + "url": "/reference/api/sandboxes/latest/schemas/VolumeAttachment/" + } + ], + "securitySchemes": { + "bearer": { + "description": "A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.", + "scheme": "bearer", + "type": "http" + }, + "sandboxBearer": { + "description": "A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.", + "scheme": "bearer", + "type": "http" + }, + "sandboxWebSocketBearer": { + "description": "Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.", + "in": "header", + "name": "Sec-WebSocket-Protocol", + "type": "apiKey" + } + }, + "servers": [ + { + "description": "The API base URL. Append the /v1 paths while preserving this URL's path prefix.", + "url": "https://connect.docker.com/sandboxes" + } + ], + "source": "content/reference/api/sandboxes/api.yaml", + "sourceURL": "/reference/api/sandboxes/api.yaml", + "tags": [ + { + "description": "Read, write, copy, and manage files inside a sandbox.", + "kind": "nav", + "name": "Files", + "summary": "Files", + "x-displayName": "Files" + }, + { + "description": "Run commands and interact with processes inside a sandbox.", + "kind": "nav", + "name": "Processes", + "summary": "Processes", + "x-displayName": "Processes" + }, + { + "description": "Exchange credentials for the authenticated owner.", + "kind": "nav", + "name": "Credentials", + "summary": "Credentials", + "x-displayName": "Credentials" + }, + { + "description": "Manage images used to create sandboxes.", + "kind": "nav", + "name": "Images", + "summary": "Images", + "x-displayName": "Images" + }, + { + "description": "Configure MCP gateways and authorize upstream servers.", + "kind": "nav", + "name": "MCP gateways", + "summary": "MCP gateways", + "x-displayName": "MCP gateways" + }, + { + "description": "Read enforced outbound network policies and their decision logs.", + "kind": "nav", + "name": "Network policies", + "summary": "Network policies", + "x-displayName": "Network policies" + }, + { + "description": "Create sandboxes and manage their lifecycle, ports, and SSH access.", + "kind": "nav", + "name": "Sandboxes", + "summary": "Sandboxes", + "x-displayName": "Sandboxes" + }, + { + "description": "Store credentials and read their metadata without returning secret material.", + "kind": "nav", + "name": "Secrets", + "summary": "Secrets", + "x-displayName": "Secrets" + }, + { + "description": "Capture sandbox state and restore it into a new sandbox.", + "kind": "nav", + "name": "Snapshots", + "summary": "Snapshots", + "x-displayName": "Snapshots" + }, + { + "description": "Manage persistent storage and attach it to sandboxes.", + "kind": "nav", + "name": "Volumes", + "summary": "Volumes", + "x-displayName": "Volumes" + } + ], + "title": "Docker Sandboxes", + "url": "/reference/api/sandboxes/latest/", + "version": "v1" + } + ], + "legacyAPIs": [ + { + "connection": "unix", + "description": "Manage containers, images, networks, and volumes.", + "title": "Docker Engine", + "url": "/reference/api/engine/" + } + ], + "modelVersion": 1 +} diff --git a/data/cli/buildx/docker_buildx.yaml b/data/cli/buildx/docker_buildx.yaml index 0f8cd0c38346..9a0edb79d3b3 100644 --- a/data/cli/buildx/docker_buildx.yaml +++ b/data/cli/buildx/docker_buildx.yaml @@ -18,6 +18,7 @@ cname: - docker buildx ls - docker buildx policy - docker buildx prune + - docker buildx replay - docker buildx rm - docker buildx stop - docker buildx use @@ -36,6 +37,7 @@ clink: - docker_buildx_ls.yaml - docker_buildx_policy.yaml - docker_buildx_prune.yaml + - docker_buildx_replay.yaml - docker_buildx_rm.yaml - docker_buildx_stop.yaml - docker_buildx_use.yaml @@ -66,6 +68,14 @@ examples: |- ### Override the configured builder instance (--builder) {#builder} You can also use the `BUILDX_BUILDER` environment variable. + + ### Enable the default policy + + Set `BUILDX_DEFAULT_POLICY=1` to enable Buildx's built-in source policy. The + policy verifies signed tags for images managed by Docker, including BuildKit + builder images and Dockerfile frontends. Untagged digest references and images + outside the managed repositories are allowed unchanged. Tagged references + that also contain a digest still have their release identity verified. deprecated: false hidden: false experimental: false diff --git a/data/cli/buildx/docker_buildx_bake.yaml b/data/cli/buildx/docker_buildx_bake.yaml index 7efde6cb06b5..9cbbe2d43fbb 100644 --- a/data/cli/buildx/docker_buildx_bake.yaml +++ b/data/cli/buildx/docker_buildx_bake.yaml @@ -7,11 +7,6 @@ long: |- Read [High-level build options with Bake](/build/bake/) guide for introduction to writing bake files. - - > [!NOTE] - > `buildx bake` command may receive backwards incompatible features in the future - > if needed. We are looking for feedback on improving the command and extending - > the functionality further. usage: docker buildx bake [OPTIONS] [TARGET...] pname: docker buildx plink: docker_buildx.yaml @@ -60,6 +55,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: jobs + shorthand: j + value_type: string + default_value: fail-fast + description: 'Set target execution behavior (format: `N` or `mode[,parallel=N]`)' + details_url: '#jobs' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: list value_type: string description: List targets or variables @@ -274,6 +281,9 @@ examples: |- on the filesystem. Alternatively, you can pass a wildcard (`*`) to allow Bake to access the entire filesystem. + Bake also supports `--allow=buildx.local.delete` to grant local outputs + permission to delete stale files when `mode=delete` is set. + ### Example: fs.read Given the following Bake configuration, Bake would need to access the parent @@ -328,6 +338,66 @@ examples: |- Same as [`build --check`](/reference/cli/docker/buildx/build/#check). + ### Configure target execution behavior (--jobs, -j) {#jobs} + + ```text + --jobs=N + --jobs=[mode,]parallel=N + --jobs=mode + ``` + + The `--jobs` flag (shorthand `-j`) controls target concurrency, output + synchronization, and how Bake handles target failures. It accepts an integer + as shorthand for `parallel=N`, or comma-separated mode and parallel options. + For example, `-j=2` is equivalent to `--jobs=parallel=2`, and + `--jobs=defer-error,parallel=2` combines a mode with a concurrency limit. + The mode can also be written as `mode=defer-error`. + + The default mode is `fail-fast`, which stops the build when a target + fails and cancels targets that are still running. Outputs already written by + successful targets are not removed. + + The `defer-output` mode waits until all participating targets have successfully + evaluated their build results before any target begins exporting output. This is + useful when multiple targets produce related artifacts and you want to withhold + their outputs if a build fails. Exports are not transactional: an export failure + can still leave partial output, and completed exports are not rolled back. + + For multi-node targets, `defer-output` applies to the BuildKit solve and export + boundary for each target. Any manifest list merge or registry push that Buildx + performs after the per-node solves complete is not part of this synchronization + barrier. + + The `defer-error` mode allows independent targets to keep running after another + target fails. Bake still returns an error after all possible targets complete, + but successful targets can finish and write their outputs. Targets that depend + on a failed target cannot complete successfully. When `--metadata-file` is set, + Bake writes metadata for successful targets even if another target fails. + + ```console + $ docker buildx bake --jobs=defer-output # wait for all build results before exporting + $ docker buildx bake --jobs=defer-error # let independent targets finish before returning an error + ``` + + The `parallel` option limits how many Bake targets run at the same time. It + requires a non-negative integer. When omitted or set to `0`, Bake doesn't apply + a target concurrency limit. This controls target scheduling, not BuildKit's + internal parallelism for build steps within a target. Specify the mode and limit + in the same flag value; repeating `--jobs` replaces the previous value. + + ```console + $ docker buildx bake -j=2 # run at most two targets at the same time + $ docker buildx bake --jobs=parallel=1 # run targets sequentially + $ docker buildx bake --jobs=defer-error,parallel=2 # limit concurrency and let independent targets finish after a failure + ``` + + With `defer-output`, every participating target must be able to reach the output + boundary before any target completes. A nonzero jobs limit smaller than the + number of participating targets is therefore rejected. The same restriction + applies when linked targets are present, because their solves may need to be + active together. The count includes implicit targets referenced through + `target:` contexts. + ### Specify a build definition file (-f, --file) {#file} Use the `-f` / `--file` option to specify the build definition file to use. @@ -339,6 +409,14 @@ examples: |- Multiple definitions can be specified by separating them with the system's path separator (typically `;` on Windows and `:` elsewhere), but can be changed with `BUILDX_BAKE_PATH_SEPARATOR`. + By default, local directory build contexts in Bake files are resolved from the + current working directory. To opt in to resolving local directory build contexts + from the Bake file that defines each path, set + `BUILDX_BAKE_FILE_RELATIVE_PATHS=1`. Compose files use the first Compose file + directory as the base, which matches Compose project directory semantics. Use + the `cwd://` prefix for paths that should remain relative to the current working + directory. + You can pass the names of the targets to build, to build only specific target(s). The following example builds the `db` and `webapp-release` targets that are defined in the `docker-bake.dev.hcl` file: @@ -611,64 +689,138 @@ examples: |- is defined in https://golang.org/pkg/path/#Match. ```console - $ docker buildx bake --set target.args.mybuildarg=value + $ docker buildx bake --set target.arg.mybuildarg=value $ docker buildx bake --set target.platform=linux/arm64 - $ docker buildx bake --set foo*.args.mybuildarg=value # overrides build arg for all targets starting with 'foo' - $ docker buildx bake --set *.platform=linux/arm64 # overrides platform for all targets + $ docker buildx bake --set foo*.arg.mybuildarg=value # overrides build arg for all targets starting with 'foo' + $ docker buildx bake --set *.platform=linux/arm64 # overrides platforms for all targets $ docker buildx bake --set foo*.no-cache # bypass caching only for targets starting with 'foo' $ docker buildx bake --set target.platform+=linux/arm64 # appends 'linux/arm64' to the platform list $ docker buildx bake --set target.contexts.bar=../bar # overrides 'bar' named context + $ docker buildx bake --set target.resource.memory=2g # overrides memory resource limit + $ docker buildx bake --set target.secret.aws=env=AWS # overrides source for an existing secret + $ docker buildx bake --set target.tag= # clears all tag values ``` > [!NOTE] > - > `--set` is a repeatable flag. For array fields such as `tags`, repeat `--set` + > `--set` is a repeatable flag. For array fields such as `tag`, repeat `--set` > to provide multiple values or use the `+=` operator to append without - > replacing. Array literal syntax like `--set target.tags=[a,b]` is not - > supported. + > replacing. Array literal syntax like `--set target.tag=[a,b]` is not + > supported. For array fields, a non-append assignment with an empty value + > clears values from the Bake definition and earlier `--set` flags. Subsequent + > assignments or appends add values to the cleared array. You can override the following fields: - * `annotations` + * `annotation` * `attest` - * `args` + * `arg.` * `cache-from` * `cache-to` * `call` * `context` - * `contexts` + * `contexts.` * `dockerfile` - * `entitlements` - * `extra-hosts` - * `labels` + * `entitlement` + * `extra-host.` + * `label.` * `load` * `no-cache` * `no-cache-filter` + * `network` * `output` * `platform` + * `policy` * `pull` * `push` - * `secrets` + * `resource.` + * `secret` + * `secret.` + * `shm-size` * `ssh` - * `tags` + * `tag` * `target` + * `ulimit` You can append using `+=` operator for the following fields: - * `annotations`¹ + * `annotation`¹ * `attest`¹ * `cache-from` * `cache-to` - * `entitlements`¹ + * `entitlement`¹ * `no-cache-filter` * `output` * `platform` - * `secrets` + * `policy` + * `secret` * `ssh` - * `tags` + * `tag` + * `ulimit` > [!NOTE] > ¹ These fields already append by default. + + Override keys use singular names. Existing plural Bake field names and + historical `--set` spellings remain supported as aliases: + + | Alias | Canonical key | + |----------------|---------------| + | `annotations` | `annotation` | + | `args` | `arg` | + | `entitlements` | `entitlement` | + | `extra-hosts` | `extra-host` | + | `labels` | `label` | + | `platforms` | `platform` | + | `resources` | `resource` | + | `secrets` | `secret` | + | `tags` | `tag` | + | `ulimits` | `ulimit` | + + Aliases are normalized before overrides are applied, so they can be mixed + with canonical keys in repeated `--set` options. `context` and `contexts` are + not aliases: `context` sets the build context, while `contexts.` sets a + named context. `secret.` also has separate semantics: it changes the + source of a secret that is already declared by the target. The plural alias + does not support this form; `secrets.` is invalid. + + #### Inline values for composable attributes + + Composable fields such as `ssh`, `secret`, `output`, `cache-to`, `cache-from`, + `attest`, and `annotation` accept a list of object values in a Bake file. When + you override these fields with `--set`, provide each value using the same + inline string syntax as the corresponding build flag, not the HCL object + form. The override replaces or appends to the list as a whole and does not + address individual object fields with a subkey. + + Only `arg`, `contexts`, `extra-host`, `label`, `resource`, and `secret` support + entry-addressed subkeys. For example, use `--set target.arg.MYARG=value` to + override one build argument. As described above, `secret.` changes the + source of an existing secret rather than an object field. + + For example, to set the SSH agent socket or key for a target, use the same + `id=path` form accepted by [`build --ssh`](/reference/cli/docker/buildx/build/#ssh): + + ```console + $ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519" + ``` + + To expose multiple paths for the same `id`, separate them with commas in the + second part: + + ```console + $ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519,$HOME/.ssh/id_rsa" + ``` + + Your shell expands `$HOME` before buildx sees the value. The equivalent Bake + file definition uses the + [`homedir`](/build/bake/stdlib/#homedir) HCL function: + + ```hcl + target "default" { + ssh = [{ id = "default", paths = ["${homedir()}/.ssh/id_ed25519", "${homedir()}/.ssh/id_rsa"] }] + } + ``` deprecated: false hidden: false experimental: false diff --git a/data/cli/buildx/docker_buildx_build.yaml b/data/cli/buildx/docker_buildx_build.yaml index 94a1df478cd4..650ddb52a978 100644 --- a/data/cli/buildx/docker_buildx_build.yaml +++ b/data/cli/buildx/docker_buildx_build.yaml @@ -21,7 +21,7 @@ options: value_type: stringArray default_value: '[]' description: | - Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`) + Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`, `buildx.local.delete`) details_url: '#allow' deprecated: false hidden: false @@ -139,8 +139,7 @@ options: kubernetes: false swarm: false - option: cpu-period - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) period deprecated: false hidden: true @@ -149,8 +148,7 @@ options: kubernetes: false swarm: false - option: cpu-quota - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) quota deprecated: false hidden: true @@ -160,8 +158,7 @@ options: swarm: false - option: cpu-shares shorthand: c - value_type: int64 - default_value: "0" + value_type: string description: CPU shares (relative weight) deprecated: false hidden: true @@ -406,6 +403,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: resource + value_type: stringArray + default_value: '[]' + description: | + Resource limits for build containers (format: `memory=2g`, `cpu-quota=50000`) + details_url: '#resource' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: rm value_type: bool default_value: "true" @@ -651,9 +660,14 @@ examples: |- - `--allow device` - Grants access to all devices. - `--allow device=kind|name` - Grants access to a specific device. - `--allow device=kind|name,alias=kind|name` - Grants access to a specific device, with optional aliasing. + - `buildx.local.delete` - Allows local outputs using `mode=delete` to delete + stale destination files when the destination is the current working directory + or outside it. - For entitlements to be enabled, the BuildKit daemon also needs to allow them - with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](/reference/cli/docker/buildx/create/#buildkitd-flags)). + For BuildKit entitlements to be enabled, the BuildKit daemon also needs to allow + them with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](/reference/cli/docker/buildx/create/#buildkitd-flags)). + The `buildx.local.delete` entitlement is checked by Buildx and isn't sent to the + BuildKit daemon. ```console $ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure' @@ -1225,6 +1239,11 @@ examples: |- Attribute key: - `dest` - destination directory where files will be written + - `mode` - write mode, either `copy` or `delete`. The default is `copy`. + `delete` removes stale files from the destination after exporting the build + result. It can be used without `--allow` when `dest` resolves to a + subdirectory of the current working directory. If `dest` is the current working + directory or resolves outside it, pass `--allow=buildx.local.delete`. For more information, see [Local and tar exporters](/build/exporters/local-tar/). @@ -1631,6 +1650,43 @@ examples: |- > In most cases, it is recommended to let the builder automatically determine > the appropriate configurations. Manual adjustments should only be considered > when specific performance tuning is required for complex build scenarios. + + ### Set CPU and memory limits for build containers (--resource) {#resource} + + The `--resource` flag constrains the resources available to the containers that + run your `RUN` instructions during the build. It's repeatable and takes + `key=value` pairs, where `key` is one of: + + | Key | Description | + |:--------------|:-----------------------------------------------------------------------------| + | `memory` | Memory limit (format: ``, e.g. `512m`, `2g`). | + | `memory-swap` | Total memory plus swap limit. Set to `-1` to allow unlimited swap. | + | `cpu-shares` | CPU shares (relative weight). | + | `cpu-period` | Length of a CPU CFS (Completely Fair Scheduler) period, in microseconds. | + | `cpu-quota` | CPU CFS quota, in microseconds, within each `cpu-period`. | + | `cpuset-cpus` | CPUs in which to allow execution (`0-3`, `0,1`). | + | `cpuset-mems` | Memory nodes (MEMs) in which to allow execution (`0-3`, `0,1`). | + + ```console + $ docker buildx build --resource memory=2g --resource cpu-quota=50000 --resource cpu-period=100000 . + ``` + + These map to the cgroup resource limits of the legacy `docker build` API and + only apply to individual build steps. They don't affect the build cache key. + + > [!NOTE] + > These limits require a BuildKit daemon that supports per-step resource limits + > (the `exec.meta.linux.resources` capability) and only take effect on Linux. + + > [!NOTE] + > Because BuildKit can run build steps in parallel, these limits apply to each + > step in isolation rather than to the build as a whole. When the same step is + > requested with different limits, the most relaxed limits are used. + + > [!NOTE] + > In most cases, it is recommended to let the builder automatically determine + > the appropriate configurations. Manual adjustments should only be considered + > when specific performance tuning is required for complex build scenarios. deprecated: false hidden: false experimental: false diff --git a/data/cli/buildx/docker_buildx_create.yaml b/data/cli/buildx/docker_buildx_create.yaml index 8caec8f7c291..89f59615ec4b 100644 --- a/data/cli/buildx/docker_buildx_create.yaml +++ b/data/cli/buildx/docker_buildx_create.yaml @@ -75,7 +75,7 @@ options: - option: driver value_type: string description: | - Driver to use (available: `docker-container`, `kubernetes`, `remote`) + Driver to use (available: `cloud`, `docker-container`, `kubernetes`, `remote`) details_url: '#driver' deprecated: false hidden: false @@ -244,6 +244,7 @@ examples: |- backend. Buildx supports the following drivers: * `docker` (default) + * `cloud` * `docker-container` * `kubernetes` * `remote` @@ -257,6 +258,34 @@ examples: |- `buildx build`. However, building multi-platform images or exporting cache is not currently supported. + #### `cloud` driver + + Uses Docker Build Cloud builders. For Docker Build Cloud access and setup, see + [Docker Build Cloud setup](/build-cloud/setup/). For + build examples, see [Building with Docker Build Cloud](/build-cloud/usage/). + + Connect Buildx to an existing cloud builder with `--driver cloud` and the + builder name in the form `/` or + `cloud:///`. You must be signed in with `docker login` and + have access to the builder. + + ```console + $ docker buildx create --driver cloud --name cloud-builder --use org/builder + $ docker buildx create --driver cloud --name cloud-builder --use cloud://org/builder + ``` + + When you don't specify an output, an untagged result remains in the cloud build + cache. If you use `--tag`, Buildx automatically loads the image when the build + targets a single platform and runs on one cloud node. For details about loading + behavior, Docker contexts, and other output configurations, see + [Load results from Docker Build Cloud](/build/exporters/). + + When `buildx create` resolves a Build Cloud builder group, each service instance + becomes a Buildx node. `--append` requires the resolved instance names to be + unique in the Buildx builder. Resolved cloud nodes are a create-time snapshot; + recreate the Buildx builder to refresh topology after Build Cloud membership or + placement changes. + #### `docker-container` driver Uses a BuildKit container that will be spawned via Docker. With this driver, @@ -271,6 +300,9 @@ examples: |- Uses Kubernetes pods. With this driver, you can spin up pods with defined BuildKit container image to build your images. + Rootless mode (`--driver-opt rootless=true`) requires Kubernetes v1.30 or later + with support for `securityContext.appArmorProfile`, which is stable in v1.31. + Unlike `docker` driver, built images will not automatically appear in `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used to achieve that. @@ -300,6 +332,18 @@ examples: |- * [`kubernetes` driver](/build/builders/drivers/kubernetes/) * [`remote` driver](/build/builders/drivers/remote/) + With `BUILDX_DEFAULT_POLICY=1`, the `docker-container` driver verifies signed + `moby/buildkit` builder image tags before creating the builder. To explicitly + bypass this verification, set `allow-untrusted-image=true`. For example: + + ```console + $ BUILDX_DEFAULT_POLICY=1 docker buildx create --driver docker-container \ + --driver-opt allow-untrusted-image=true + ``` + + Only use this option for an image that you trust. It disables builder image + verification for the new builder node. + ### Remove a node from a builder (--leave) {#leave} The `--leave` flag changes the action of the command to remove a node from a diff --git a/data/cli/buildx/docker_buildx_dap_build.yaml b/data/cli/buildx/docker_buildx_dap_build.yaml index 44596ceb366c..21050c9dac06 100644 --- a/data/cli/buildx/docker_buildx_dap_build.yaml +++ b/data/cli/buildx/docker_buildx_dap_build.yaml @@ -27,7 +27,7 @@ options: value_type: stringArray default_value: '[]' description: | - Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`) + Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`, `buildx.local.delete`) deprecated: false hidden: false experimental: false @@ -135,8 +135,7 @@ options: kubernetes: false swarm: false - option: cpu-period - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) period deprecated: false hidden: true @@ -145,8 +144,7 @@ options: kubernetes: false swarm: false - option: cpu-quota - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) quota deprecated: false hidden: true @@ -156,8 +154,7 @@ options: swarm: false - option: cpu-shares shorthand: c - value_type: int64 - default_value: "0" + value_type: string description: CPU shares (relative weight) deprecated: false hidden: true @@ -392,6 +389,17 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: resource + value_type: stringArray + default_value: '[]' + description: | + Resource limits for build containers (format: `memory=2g`, `cpu-quota=50000`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: rm value_type: bool default_value: "true" diff --git a/data/cli/buildx/docker_buildx_debug_build.yaml b/data/cli/buildx/docker_buildx_debug_build.yaml index e3e403930c92..942cdaca3930 100644 --- a/data/cli/buildx/docker_buildx_debug_build.yaml +++ b/data/cli/buildx/docker_buildx_debug_build.yaml @@ -20,7 +20,7 @@ options: value_type: stringArray default_value: '[]' description: | - Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`) + Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`, `buildx.local.delete`) deprecated: false hidden: false experimental: false @@ -128,8 +128,7 @@ options: kubernetes: false swarm: false - option: cpu-period - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) period deprecated: false hidden: true @@ -138,8 +137,7 @@ options: kubernetes: false swarm: false - option: cpu-quota - value_type: int64 - default_value: "0" + value_type: string description: Limit the CPU CFS (Completely Fair Scheduler) quota deprecated: false hidden: true @@ -149,8 +147,7 @@ options: swarm: false - option: cpu-shares shorthand: c - value_type: int64 - default_value: "0" + value_type: string description: CPU shares (relative weight) deprecated: false hidden: true @@ -385,6 +382,17 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: resource + value_type: stringArray + default_value: '[]' + description: | + Resource limits for build containers (format: `memory=2g`, `cpu-quota=50000`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: rm value_type: bool default_value: "true" diff --git a/data/cli/buildx/docker_buildx_replay.yaml b/data/cli/buildx/docker_buildx_replay.yaml new file mode 100644 index 000000000000..e111cacb7364 --- /dev/null +++ b/data/cli/buildx/docker_buildx_replay.yaml @@ -0,0 +1,65 @@ +command: docker buildx replay +short: Replay a build from its provenance +long: |- + `buildx replay` reads the SLSA provenance attestation of an existing build and + reproduces the build with the recorded frontend, options, and source digests. + Replay runs on the selected builder and requires BuildKit v0.27 or later. + + Subjects are accepted in three forms: + + - `docker-image://` or a bare `` — resolve through the registry. + - `oci-layout://[:]` — read from a local OCI layout. + - A local attestation file: an in-toto statement (`.intoto.jsonl`), an + unsigned DSSE envelope, a Sigstore bundle, or a bare SLSA provenance + predicate. + + A build can be replayed when: + + - its provenance was recorded with `mode=max` + (`--provenance=mode=max` or `--attest=type=provenance,mode=max`). `mode=min` + provenance omits the build arguments, secrets, and SSH needed for replay; + - its build context was a Git repository or an HTTP(S) URL. Builds that used + local directories, stdin, OCI layouts, or other Bake targets as build + contexts cannot be replayed; + - it did not use `--network=host`, unless a different `--network` is passed + to replay; + - the recorded sources are still available. + + Replay rebuilds one platform at a time. For a multi-platform image, select the + platform with `--platform`. By default, the only platform of the image or the + default platform of the builder is used. +usage: docker buildx replay +pname: docker buildx +plink: docker_buildx.yaml +cname: + - docker buildx replay build +clink: + - docker_buildx_replay_build.yaml +inherited_options: + - option: builder + value_type: string + description: Override the configured builder instance + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/data/cli/buildx/docker_buildx_replay_build.yaml b/data/cli/buildx/docker_buildx_replay_build.yaml new file mode 100644 index 000000000000..ca65b861911a --- /dev/null +++ b/data/cli/buildx/docker_buildx_replay_build.yaml @@ -0,0 +1,201 @@ +command: docker buildx replay build +short: Rebuild an image from provenance and pinned materials +long: |- + `replay build` reconstructs an image from the provenance attestation attached + to an existing subject. + + The replay mode controls how sources are resolved: + + - `materials` (default) pins every source to the digest recorded in the + provenance. A source that is not recorded, or whose content changed, fails + the build. + - `frontend` replays the recorded frontend and options, but resolves sources + again, so the result can differ from the original build. + + Replayed builds do not add new provenance or SBOM attestations. Local outputs + with `mode=delete` are not supported. +usage: docker buildx replay build [OPTIONS] SUBJECT +pname: docker buildx replay +plink: docker_buildx_replay.yaml +options: + - option: dry-run + value_type: bool + default_value: "false" + description: Print a plan of the replay without solving or exporting + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + default_value: pretty + description: Format dry-run output (`pretty` | `json`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: load + value_type: bool + default_value: "false" + description: Shorthand for `--output=type=docker` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: materials + value_type: stringArray + default_value: '[]' + description: | + Materials store (repeatable; format: `provenance` | `oci-layout://[:]` | `` | `=`) + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + description: | + Network mode for RUN instructions (`default` | `none`; defaults to the mode of the original build) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: 'Output destination (format: `type=local,dest=path`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: stringArray + default_value: '[]' + description: | + Platform of the subject to replay (defaults to the only platform of the subject or the builder default platform) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: progress + value_type: string + default_value: auto + description: | + Set type of progress output (`auto` | `plain` | `tty` | `quiet` | `rawjson`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: push + value_type: bool + default_value: "false" + description: Shorthand for `--output=type=registry,unpack=false` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: replay-mode + value_type: string + default_value: materials + description: Replay mode (`materials` | `frontend`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret + value_type: stringArray + default_value: '[]' + description: | + Secret to expose to the replayed build (format: `id=mysecret[,src=/local/secret]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ssh + value_type: stringArray + default_value: '[]' + description: | + SSH agent socket or keys to expose (format: `default|[=|[,]]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tag + shorthand: t + value_type: stringArray + default_value: '[]' + description: 'Image identifier (format: `[registry/]repository[:tag]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: builder + value_type: string + description: Override the configured builder instance + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + ### Replay a registry image and export to an OCI tar + + ```console + docker buildx replay build docker-image://example.com/app@sha256:deadbeef \ + --output=type=oci,dest=replay.oci.tar + ``` + + ### Dry-run a replay to inspect the plan + + ```console + docker buildx replay build docker-image://example.com/app@sha256:deadbeef --dry-run --format=json | jq + ``` + + Dry-run runs the same checks as a real replay, so a subject that cannot be + replayed fails before any build starts. +deprecated: false +hidden: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/data/cli/buildx/docker_buildx_replay_snapshot.yaml b/data/cli/buildx/docker_buildx_replay_snapshot.yaml new file mode 100644 index 000000000000..f2fd2d6900dd --- /dev/null +++ b/data/cli/buildx/docker_buildx_replay_snapshot.yaml @@ -0,0 +1,132 @@ +command: docker buildx replay snapshot +short: Export replay inputs for a subject as a reusable materials store +long: Export replay inputs for a subject as a reusable materials store +usage: docker buildx replay snapshot [OPTIONS] SUBJECT +pname: docker buildx replay +plink: docker_buildx_replay.yaml +options: + - option: dry-run + value_type: bool + default_value: "false" + description: Print a JSON plan of the snapshot without writing output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: include-materials + value_type: bool + default_value: "true" + description: Include material content in the snapshot + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: materials + value_type: stringArray + default_value: '[]' + description: | + Materials store (repeatable; format: `provenance` | `oci-layout://[:]` | `` | `=`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + description: | + Network mode for RUN instructions (`default` | `none`; defaults to the mode of the original build) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: | + Output destination (default: `-` — oci tar to stdout; bare `` writes an oci-layout directory; `type=oci,dest=X[,tar=true|false]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: stringArray + default_value: '[]' + description: | + Platform of the subject to replay (defaults to the only platform of the subject or the builder default platform) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: progress + value_type: string + default_value: auto + description: | + Set type of progress output (`auto` | `plain` | `tty` | `quiet` | `rawjson`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret + value_type: stringArray + default_value: '[]' + description: | + Secret to expose to the replayed build (format: `id=mysecret[,src=/local/secret]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ssh + value_type: stringArray + default_value: '[]' + description: | + SSH agent socket or keys to expose (format: `default|[=|[,]]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: builder + value_type: string + description: Override the configured builder instance + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: true +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/data/cli/buildx/docker_buildx_replay_verify.yaml b/data/cli/buildx/docker_buildx_replay_verify.yaml new file mode 100644 index 000000000000..94de7b558739 --- /dev/null +++ b/data/cli/buildx/docker_buildx_replay_verify.yaml @@ -0,0 +1,122 @@ +command: docker buildx replay verify +short: Replay a subject and compare the result against the original artifact +long: Replay a subject and compare the result against the original artifact +usage: docker buildx replay verify [OPTIONS] SUBJECT +pname: docker buildx replay +plink: docker_buildx_replay.yaml +options: + - option: compare + value_type: string + default_value: digest + description: Comparison mode (`digest` | `artifact`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: materials + value_type: stringArray + default_value: '[]' + description: | + Materials store (repeatable; format: `provenance` | `oci-layout://[:]` | `` | `=`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + description: | + Network mode for RUN instructions (`default` | `none`; defaults to the mode of the original build) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: | + Output destination for the verification result (VSA) (format: `type=local,dest=path`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: stringArray + default_value: '[]' + description: | + Platform of the subject to replay (defaults to the only platform of the subject or the builder default platform) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: progress + value_type: string + default_value: auto + description: | + Set type of progress output (`auto` | `plain` | `tty` | `quiet` | `rawjson`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret + value_type: stringArray + default_value: '[]' + description: | + Secret to expose to the replayed build (format: `id=mysecret[,src=/local/secret]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ssh + value_type: stringArray + default_value: '[]' + description: | + SSH agent socket or keys to expose (format: `default|[=|[,]]`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: builder + value_type: string + description: Override the configured builder instance + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: true +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/data/cli/desktop/docker_desktop.yaml b/data/cli/desktop/docker_desktop.yaml index 6339c6b2e262..825b5acafe9c 100644 --- a/data/cli/desktop/docker_desktop.yaml +++ b/data/cli/desktop/docker_desktop.yaml @@ -15,6 +15,7 @@ cname: - docker desktop disable - docker desktop enable - docker desktop version + - docker desktop auth clink: - docker_desktop_start.yaml - docker_desktop_stop.yaml @@ -26,6 +27,7 @@ clink: - docker_desktop_disable.yaml - docker_desktop_enable.yaml - docker_desktop_version.yaml + - docker_desktop_auth.yaml deprecated: false hidden: false experimental: false diff --git a/data/cli/desktop/docker_desktop_auth.yaml b/data/cli/desktop/docker_desktop_auth.yaml new file mode 100644 index 000000000000..c6285c79b110 --- /dev/null +++ b/data/cli/desktop/docker_desktop_auth.yaml @@ -0,0 +1,15 @@ +command: docker desktop auth +short: Manage Docker Desktop authentication +usage: docker desktop auth +pname: docker desktop +plink: docker_desktop.yaml +cname: + - docker desktop auth status +clink: + - docker_desktop_auth_status.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/cli/desktop/docker_desktop_auth_status.yaml b/data/cli/desktop/docker_desktop_auth_status.yaml new file mode 100644 index 000000000000..58c3592a7a30 --- /dev/null +++ b/data/cli/desktop/docker_desktop_auth_status.yaml @@ -0,0 +1,27 @@ +command: docker desktop auth status +short: Show the current Docker Hub authentication status +long: |- + Show whether you are logged in to Docker Hub and, if so, + display your username, email, plan, organizations, and policy flags. + + The authentication token is never printed. +usage: docker desktop auth status +pname: docker desktop auth +plink: docker_desktop_auth.yaml +options: + - option: format + value_type: string + default_value: pretty + description: 'Format the output. Accepted values are: pretty, json' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/cli/desktop/docker_desktop_kubernetes.yaml b/data/cli/desktop/docker_desktop_kubernetes.yaml index 4beff946dbdd..94ff477b550f 100644 --- a/data/cli/desktop/docker_desktop_kubernetes.yaml +++ b/data/cli/desktop/docker_desktop_kubernetes.yaml @@ -5,8 +5,12 @@ pname: docker desktop plink: docker_desktop.yaml cname: - docker desktop kubernetes images + - docker desktop kubernetes reset-cluster + - docker desktop kubernetes status clink: - - docker_desktop_engine_images.yaml + - docker_desktop_kubernetes_images.yaml + - docker_desktop_kubernetes_reset-cluster.yaml + - docker_desktop_kubernetes_status.yaml deprecated: false hidden: false experimental: false diff --git a/data/cli/desktop/docker_desktop_kubernetes_reset-cluster.yaml b/data/cli/desktop/docker_desktop_kubernetes_reset-cluster.yaml new file mode 100644 index 000000000000..0290c00dd5a1 --- /dev/null +++ b/data/cli/desktop/docker_desktop_kubernetes_reset-cluster.yaml @@ -0,0 +1,11 @@ +command: docker desktop kubernetes reset-cluster +short: Reset the Kubernetes cluster managed by Docker Desktop +usage: docker desktop kubernetes reset-cluster +pname: docker desktop kubernetes +plink: docker_desktop_kubernetes.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cli/desktop/docker_desktop_kubernetes_status.yaml b/data/cli/desktop/docker_desktop_kubernetes_status.yaml new file mode 100644 index 000000000000..765b526b7590 --- /dev/null +++ b/data/cli/desktop/docker_desktop_kubernetes_status.yaml @@ -0,0 +1,22 @@ +command: docker desktop kubernetes status +short: Get the status of the Kubernetes cluster managed by Docker Desktop +usage: docker desktop kubernetes status +pname: docker desktop kubernetes +plink: docker_desktop_kubernetes.yaml +options: + - option: format + value_type: string + default_value: pretty + description: 'Format the output. Accepted values are: pretty, json' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cli/dhi/docker_dhi_customization_build_get.yaml b/data/cli/dhi/docker_dhi_customization_build_get.yaml index 60a2dab345b2..5c4555040da8 100644 --- a/data/cli/dhi/docker_dhi_customization_build_get.yaml +++ b/data/cli/dhi/docker_dhi_customization_build_get.yaml @@ -2,7 +2,7 @@ command: docker dhi customization build get short: Get details of a build long: | Get detailed information about a Docker Hardened Images customization build -usage: docker dhi customization build get +usage: docker dhi customization build get pname: docker dhi customization build plink: docker_dhi_customization_build.yaml options: diff --git a/data/cli/dhi/docker_dhi_customization_build_list.yaml b/data/cli/dhi/docker_dhi_customization_build_list.yaml index 7933657c3919..e98e5e59fda4 100644 --- a/data/cli/dhi/docker_dhi_customization_build_list.yaml +++ b/data/cli/dhi/docker_dhi_customization_build_list.yaml @@ -1,8 +1,7 @@ command: docker dhi customization build list short: List builds of a customization -long: | - List all builds of a Docker Hardened Images customization by repository and name -usage: docker dhi customization build list +long: List all builds of a Docker Hardened Images customization by its ID +usage: docker dhi customization build list pname: docker dhi customization build plink: docker_dhi_customization_build.yaml options: diff --git a/data/cli/dhi/docker_dhi_customization_build_logs.yaml b/data/cli/dhi/docker_dhi_customization_build_logs.yaml index 3a5afe133545..88b24c351319 100644 --- a/data/cli/dhi/docker_dhi_customization_build_logs.yaml +++ b/data/cli/dhi/docker_dhi_customization_build_logs.yaml @@ -1,7 +1,7 @@ command: docker dhi customization build logs short: Get logs of a build long: Get the logs of a Docker Hardened Images customization build -usage: docker dhi customization build logs +usage: docker dhi customization build logs pname: docker dhi customization build plink: docker_dhi_customization_build.yaml options: diff --git a/data/cli/engine/docker.yaml b/data/cli/engine/docker.yaml index e798eac2fd0a..81db02ea6eb1 100644 --- a/data/cli/engine/docker.yaml +++ b/data/cli/engine/docker.yaml @@ -575,7 +575,7 @@ examples: |- | Scheme | Description | Example | |----------------------------------------|---------------------------|----------------------------------| - | `unix://[]` | Unix socket (Linux only) | `unix:///var/run/docker.sock` | + | `unix://[]` | Unix socket | `unix:///var/run/docker.sock` | | `tcp://[[:port]]` | TCP connection | `tcp://174.17.0.1:2376` | | `ssh://[username@][:port]` | SSH connection | `ssh://user@192.168.64.5` | | `npipe://[]` | Named pipe (Windows only) | `npipe:////./pipe/docker_engine` | diff --git a/data/cli/engine/docker_container_create.yaml b/data/cli/engine/docker_container_create.yaml index 722645fbb1b4..c78f81490219 100644 --- a/data/cli/engine/docker_container_create.yaml +++ b/data/cli/engine/docker_container_create.yaml @@ -827,7 +827,7 @@ options: - option: pull value_type: string default_value: missing - description: Pull image before creating (`always`, `|missing`, `never`) + description: Pull image before creating (`always`, `missing`, `never`) deprecated: false hidden: false experimental: false @@ -973,6 +973,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: umask + value_type: umask + default_value: + description: Set umask for the container + deprecated: false + hidden: false + min_api_version: "1.56" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux - option: use-api-socket value_type: bool default_value: "false" diff --git a/data/cli/engine/docker_container_run.yaml b/data/cli/engine/docker_container_run.yaml index 1d8363edbf47..501cbe0547c0 100644 --- a/data/cli/engine/docker_container_run.yaml +++ b/data/cli/engine/docker_container_run.yaml @@ -1026,6 +1026,19 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: umask + value_type: umask + default_value: + description: Set umask for the container + details_url: '#umask' + deprecated: false + hidden: false + min_api_version: "1.56" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux - option: use-api-socket value_type: bool default_value: "false" @@ -2374,6 +2387,56 @@ examples: |- This fails because the caller set `nproc=3` resulting in the first three containers using up the three processes quota set for the `daemon` user. + ### Set umask for the container (--umask) {#umask} + + The `--umask` flag sets the umask for the container's processes, which + controls the default permissions for files and directories created inside + the container. The value must be specified in octal notation. Leading zeros + are optional. For example, a umask of `022` creates new files with `644` + permissions (`-rw-r--r--`) and new directories with `755` permissions + (`drwxr-xr-x`). + + If you don't set the `--umask` flag, the OCI runtime applies its own + default umask. The default OCI runtime (runc) uses a default umask of + `0022`, but this value is implementation-defined and may vary between OCI + runtimes: + + ```console + $ docker run --rm busybox sh -c umask + 0022 + ``` + + When the `--umask` flag is set, the value is included in the OCI process + configuration used for the container's entrypoint, for processes started + with `docker exec`, and for healthchecks. Whether an OCI runtime honors the + value depends on the runtime; runc honors the configured umask for + `docker exec` and for healthchecks. + + To set a custom umask, use the `--umask` flag with an octal value: + + ```console + $ docker run --rm --umask 077 busybox sh -c umask + 0077 + ``` + + The umask is also applied to processes started later with `docker exec`: + + ```console + $ docker run --rm -d --name umask-test --umask 077 busybox sleep 60 + $ docker exec umask-test sh -c umask + 0077 + ``` + + Setting the umask to `0` masks no permission bits, so files and directories + keep their full permissions. The following example creates a file and a + directory inside the container: + + ```console + $ docker run --rm --umask 0 busybox sh -c 'touch file && mkdir dir && stat -c "%a %n" file dir' + 666 file + 777 dir + ``` + ### Stop container with signal (--stop-signal) {#stop-signal} The `--stop-signal` flag sends the system call signal to the diff --git a/data/cli/engine/docker_create.yaml b/data/cli/engine/docker_create.yaml index 432c3c7ddc23..67a0cef41842 100644 --- a/data/cli/engine/docker_create.yaml +++ b/data/cli/engine/docker_create.yaml @@ -810,7 +810,7 @@ options: - option: pull value_type: string default_value: missing - description: Pull image before creating (`always`, `|missing`, `never`) + description: Pull image before creating (`always`, `missing`, `never`) deprecated: false hidden: false experimental: false @@ -956,6 +956,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: umask + value_type: umask + default_value: + description: Set umask for the container + deprecated: false + hidden: false + min_api_version: "1.56" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux - option: use-api-socket value_type: bool default_value: "false" diff --git a/data/cli/engine/docker_image_history.yaml b/data/cli/engine/docker_image_history.yaml index 844acf52c15f..116092da6634 100644 --- a/data/cli/engine/docker_image_history.yaml +++ b/data/cli/engine/docker_image_history.yaml @@ -158,7 +158,7 @@ examples: |- $ docker image pull --quiet --platform=linux/riscv64 alpine docker.io/library/alpine:latest - $ docker image history --platform=linux/s390x alpine + $ docker image history --platform=linux/riscv64 alpine IMAGE CREATED CREATED BY SIZE COMMENT beefdbd8a1da 3 weeks ago /bin/sh -c #(nop) CMD ["/bin/sh"] 0B 3 weeks ago /bin/sh -c #(nop) ADD file:ba2637314e600db5a… 8.46MB diff --git a/data/cli/engine/docker_login.yaml b/data/cli/engine/docker_login.yaml index d8d0c93eb75d..96f9545b230d 100644 --- a/data/cli/engine/docker_login.yaml +++ b/data/cli/engine/docker_login.yaml @@ -158,7 +158,7 @@ options: - option: password shorthand: p value_type: string - description: Password or Personal Access Token (PAT) + description: Password or Personal Access Token (PAT), or `-` to read from stdin deprecated: false hidden: false experimental: false @@ -272,6 +272,13 @@ examples: |- ```console $ cat ~/my_password.txt | docker login --username foo --password-stdin ``` + + You can also pass `-` as the value for `--password` or `-p` to read the + password from `STDIN`. + + ```console + $ cat ~/my_password.txt | docker login --username foo --password - + ``` deprecated: false hidden: false experimental: false diff --git a/data/cli/engine/docker_run.yaml b/data/cli/engine/docker_run.yaml index b2f27bca7365..53a372e66127 100644 --- a/data/cli/engine/docker_run.yaml +++ b/data/cli/engine/docker_run.yaml @@ -986,6 +986,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: umask + value_type: umask + default_value: + description: Set umask for the container + deprecated: false + hidden: false + min_api_version: "1.56" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux - option: use-api-socket value_type: bool default_value: "false" diff --git a/data/cli/engine/docker_service_create.yaml b/data/cli/engine/docker_service_create.yaml index 7653d2b94ab1..2cdb9fad0e87 100644 --- a/data/cli/engine/docker_service_create.yaml +++ b/data/cli/engine/docker_service_create.yaml @@ -1384,7 +1384,9 @@ examples: |- The service mode determines whether this is a _replicated_ service or a _global_ service. A replicated service runs as many tasks as specified, while a global - service runs on each active node in the swarm. + service runs one task on each active node in the swarm. Placement + `--constraint` expressions still apply: a global service only schedules + that task on nodes that match, not on every node. The following command creates a global service: @@ -1398,7 +1400,8 @@ examples: |- ### Specify service constraints (--constraint) {#constraint} You can limit the set of nodes where a task can be scheduled by defining - constraint expressions. Constraint expressions can either use a _match_ (`==`) + constraint expressions. They apply to both replicated and global services + (and to jobs). Constraint expressions can either use a _match_ (`==`) or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows: diff --git a/data/cli/engine/docker_system_prune.yaml b/data/cli/engine/docker_system_prune.yaml index a3995b276f48..62c55d71ece6 100644 --- a/data/cli/engine/docker_system_prune.yaml +++ b/data/cli/engine/docker_system_prune.yaml @@ -2,7 +2,13 @@ command: docker system prune short: Remove unused data long: |- Remove all unused containers, networks, images (both dangling and unused), - and optionally, volumes. + unused [build cache](/build/cache/), and optionally, + volumes. + + Build cache is always eligible for pruning with this command (including BuildKit + cache mounts created with `RUN --mount=type=cache`). Use + [`docker builder prune`](/reference/cli/docker/builder/prune/) if you only want to reclaim build + cache without removing containers, networks, or images. usage: docker system prune [OPTIONS] pname: docker system plink: docker_system.yaml diff --git a/data/cli/offload/docker_offload_start.yaml b/data/cli/offload/docker_offload_start.yaml index 25a818c81d54..d968a6c997d4 100644 --- a/data/cli/offload/docker_offload_start.yaml +++ b/data/cli/offload/docker_offload_start.yaml @@ -26,16 +26,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: idle-timeout - value_type: duration - default_value: "" - description: How long before the engine idles - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - option: timeout value_type: duration default_value: 10s diff --git a/data/cli/offload/docker_offload_stop.yaml b/data/cli/offload/docker_offload_stop.yaml index a78609c3ed95..9a274a3e19a0 100644 --- a/data/cli/offload/docker_offload_stop.yaml +++ b/data/cli/offload/docker_offload_stop.yaml @@ -4,11 +4,10 @@ usage: docker offload stop [OPTIONS] pname: docker offload plink: docker_offload.yaml options: - - option: force - shorthand: f + - option: terminate value_type: bool default_value: "false" - description: Don't prompt for confirmation + description: Terminate the remote lease deprecated: false hidden: false experimental: false diff --git a/data/cli/sandbox/docker_sandbox.yaml b/data/cli/sandbox/docker_sandbox.yaml deleted file mode 100644 index 1b8a76efb53d..000000000000 --- a/data/cli/sandbox/docker_sandbox.yaml +++ /dev/null @@ -1,64 +0,0 @@ -command: docker sandbox -short: Docker Sandbox -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Local sandbox environments for AI agents, using Docker. -usage: docker sandbox -pname: docker -plink: docker.yaml -cname: - - docker sandbox create - - docker sandbox exec - - docker sandbox ls - - docker sandbox network - - docker sandbox reset - - docker sandbox rm - - docker sandbox run - - docker sandbox save - - docker sandbox stop - - docker sandbox version -clink: - - docker_sandbox_create.yaml - - docker_sandbox_exec.yaml - - docker_sandbox_ls.yaml - - docker_sandbox_network.yaml - - docker_sandbox_reset.yaml - - docker_sandbox_rm.yaml - - docker_sandbox_run.yaml - - docker_sandbox_save.yaml - - docker_sandbox_stop.yaml - - docker_sandbox_version.yaml -options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create.yaml b/data/cli/sandbox/docker_sandbox_create.yaml deleted file mode 100644 index 28f02d39c933..000000000000 --- a/data/cli/sandbox/docker_sandbox_create.yaml +++ /dev/null @@ -1,148 +0,0 @@ -command: docker sandbox create -short: Create a sandbox for an agent -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for an agent. - - Available agents are provided as subcommands. Use "create AGENT --help" for agent-specific options. -usage: docker sandbox create [OPTIONS] AGENT WORKSPACE -pname: docker sandbox -plink: docker_sandbox.yaml -cname: - - docker sandbox create cagent - - docker sandbox create claude - - docker sandbox create codex - - docker sandbox create copilot - - docker sandbox create gemini - - docker sandbox create kiro - - docker sandbox create opencode - - docker sandbox create shell -clink: - - docker_sandbox_create_cagent.yaml - - docker_sandbox_create_claude.yaml - - docker_sandbox_create_codex.yaml - - docker_sandbox_create_copilot.yaml - - docker_sandbox_create_gemini.yaml - - docker_sandbox_create_kiro.yaml - - docker_sandbox_create_opencode.yaml - - docker_sandbox_create_shell.yaml -options: - - option: name - value_type: string - description: | - Name for the sandbox (default: -, letters, numbers, hyphens, underscores, periods, plus signs and minus signs only) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: pull-template - value_type: string - default_value: missing - description: | - Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress verbose output - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: template - shorthand: t - value_type: string - description: | - Container image to use for the sandbox (default: agent-specific image) - details_url: '#template' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Claude sandbox - - ```console - $ docker sandbox create claude ~/my-project - ``` - - ### Create with a custom name - - ```console - $ docker sandbox create --name my-sandbox claude ~/my-project - ``` - - ### Use a custom base image (-t, --template) {#template} - - ```text - --template IMAGE - ``` - - Specify a custom container image to use as the sandbox base: - - ```console - $ docker sandbox create --template python:3-alpine claude ~/my-project - ``` - - By default, each agent uses a pre-configured image. - - ### Create and run immediately - - After creating a sandbox, use `run` to start the agent: - - ```console - $ docker sandbox create --name my-sandbox claude ~/my-project - $ docker sandbox run my-sandbox - ``` - - Or use `docker sandbox run` directly to create and run in one step: - - ```console - $ docker sandbox run claude ~/my-project - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_cagent.yaml b/data/cli/sandbox/docker_sandbox_create_cagent.yaml deleted file mode 100644 index 200fe86668a0..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_cagent.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker sandbox create cagent -short: Create a sandbox for cagent -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for cagent. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start cagent after creation. -usage: docker sandbox create cagent WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Cagent sandbox in the current directory - - ```console - $ docker sandbox create cagent . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create cagent /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-cagent cagent ~/my-project - $ docker sandbox run my-cagent - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_claude.yaml b/data/cli/sandbox/docker_sandbox_create_claude.yaml deleted file mode 100644 index 7bef660a7a40..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_claude.yaml +++ /dev/null @@ -1,77 +0,0 @@ -command: docker sandbox create claude -short: Create a sandbox for claude -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for claude. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start claude after creation. -usage: docker sandbox create claude WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -options: - - option: patch-settings - value_type: bool - default_value: "false" - description: Intercept claude settings API call and patch payload - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Claude sandbox in the current directory - - ```console - $ docker sandbox create claude . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create claude /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-claude claude ~/my-project - $ docker sandbox run my-claude - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_codex.yaml b/data/cli/sandbox/docker_sandbox_create_codex.yaml deleted file mode 100644 index 0f415f8b7cbc..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_codex.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker sandbox create codex -short: Create a sandbox for codex -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for codex. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start codex after creation. -usage: docker sandbox create codex WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Codex sandbox in the current directory - - ```console - $ docker sandbox create codex . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create codex /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-codex codex ~/my-project - $ docker sandbox run my-codex - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_copilot.yaml b/data/cli/sandbox/docker_sandbox_create_copilot.yaml deleted file mode 100644 index 06a6af12b28a..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_copilot.yaml +++ /dev/null @@ -1,47 +0,0 @@ -command: docker sandbox create copilot -short: Create a sandbox for copilot -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for copilot. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start copilot after creation. -usage: docker sandbox create copilot WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_gemini.yaml b/data/cli/sandbox/docker_sandbox_create_gemini.yaml deleted file mode 100644 index 6d3a62318268..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_gemini.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker sandbox create gemini -short: Create a sandbox for gemini -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for gemini. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start gemini after creation. -usage: docker sandbox create gemini WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Gemini sandbox in the current directory - - ```console - $ docker sandbox create gemini . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create gemini /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-gemini gemini ~/my-project - $ docker sandbox run my-gemini - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_kiro.yaml b/data/cli/sandbox/docker_sandbox_create_kiro.yaml deleted file mode 100644 index 23ef3a2d081d..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_kiro.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker sandbox create kiro -short: Create a sandbox for kiro -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for kiro. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start kiro after creation. -usage: docker sandbox create kiro WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create a Kiro sandbox in the current directory - - ```console - $ docker sandbox create kiro . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create kiro /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-kiro kiro ~/my-project - $ docker sandbox run my-kiro - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_opencode.yaml b/data/cli/sandbox/docker_sandbox_create_opencode.yaml deleted file mode 100644 index 132e0be55dd4..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_opencode.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker sandbox create opencode -short: Create a sandbox for opencode -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for opencode. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start opencode after creation. -usage: docker sandbox create opencode WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create an OpenCode sandbox in the current directory - - ```console - $ docker sandbox create opencode . - ``` - - ### Create with an absolute path - - ```console - $ docker sandbox create opencode /home/user/my-project - ``` - - ### Create and then run - - ```console - $ docker sandbox create --name my-opencode opencode ~/my-project - $ docker sandbox run my-opencode - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_create_shell.yaml b/data/cli/sandbox/docker_sandbox_create_shell.yaml deleted file mode 100644 index f97e87bb06cd..000000000000 --- a/data/cli/sandbox/docker_sandbox_create_shell.yaml +++ /dev/null @@ -1,47 +0,0 @@ -command: docker sandbox create shell -short: Create a sandbox for shell -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Create a sandbox with access to a host workspace for shell. - - The workspace path is required and will be exposed inside the sandbox at the same path as on the host. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Use 'docker sandbox run SANDBOX' to start shell after creation. -usage: docker sandbox create shell WORKSPACE [EXTRA_WORKSPACE...] -pname: docker sandbox create -plink: docker_sandbox_create.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_exec.yaml b/data/cli/sandbox/docker_sandbox_exec.yaml deleted file mode 100644 index 6e0643d473c0..000000000000 --- a/data/cli/sandbox/docker_sandbox_exec.yaml +++ /dev/null @@ -1,201 +0,0 @@ -command: docker sandbox exec -short: Execute a command inside a sandbox -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Execute a command in a sandbox that was previously created with 'docker sandbox create'. - - The command and any additional arguments are executed inside the sandbox container. -usage: docker sandbox exec [OPTIONS] SANDBOX COMMAND [ARG...] -pname: docker sandbox -plink: docker_sandbox.yaml -options: - - option: detach - shorthand: d - value_type: bool - default_value: "false" - description: 'Detached mode: run command in the background' - details_url: '#detach' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: env - shorthand: e - value_type: stringArray - default_value: '[]' - description: Set environment variables - details_url: '#env' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: env-file - value_type: stringArray - default_value: '[]' - description: Read in a file of environment variables - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to the command - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - details_url: '#user' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - details_url: '#workdir' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Execute a command in a sandbox - - ```console - $ docker sandbox exec my-sandbox ls -la - ``` - - ### Run an interactive shell - - ```console - $ docker sandbox exec -it my-sandbox /bin/bash - ``` - - ### Set environment variables (-e, --env) {#env} - - ```text - --env KEY=VALUE - ``` - - Pass environment variables to the command: - - ```console - $ docker sandbox exec \ - --env NODE_ENV=development \ - --env DATABASE_URL=postgresql://localhost/myapp \ - my-sandbox npm test - ``` - - ### Set working directory (-w, --workdir) {#workdir} - - ```text - --workdir PATH - ``` - - Run the command in a specific directory: - - ```console - $ docker sandbox exec --workdir /app my-sandbox python script.py - ``` - - ### Run as specific user (-u, --user) {#user} - - ```text - --user USER[:GROUP] - ``` - - Execute command as a different user: - - ```console - $ docker sandbox exec --user 1000:1000 my-sandbox id - ``` - - ### Run in background (-d, --detach) {#detach} - - Run a long-running command in the background: - - ```console - $ docker sandbox exec -d my-sandbox python server.py - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_inspect.yaml b/data/cli/sandbox/docker_sandbox_inspect.yaml deleted file mode 100644 index 94b47738b6f5..000000000000 --- a/data/cli/sandbox/docker_sandbox_inspect.yaml +++ /dev/null @@ -1,65 +0,0 @@ -command: docker sandbox inspect -short: Display detailed information on one or more sandboxes -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Display detailed information on one or more sandboxes. - - This command retrieves and displays detailed information about the specified - sandboxes using the Docker API. Each sandbox is identified by its unique ID or name. -usage: docker sandbox inspect [OPTIONS] SANDBOX [SANDBOX...] -pname: docker sandbox -plink: docker_sandbox.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Inspect a sandbox - - ```console - $ docker sandbox inspect abc123def - [ - { - "id": "abc123def69b16c5c0dab4cf699e26f8d01e1ace3aeee06254e0999492e11647", - "name": "claude-sandbox-2025-11-04-170333", - "created_at": "2025-11-04T16:03:33.910642347Z", - "status": "running", - "template": "docker/sandbox-templates:claude-code", - "labels": { - "com.docker.sandbox.agent": "claude", - "com.docker.sandbox.workingDirectory": "/Users/moby/code/docker/sandboxes", - "com.docker.sandbox.workingDirectoryInode": "3041007", - "com.docker.sandboxes": "templates", - "com.docker.sandboxes.base": "ubuntu:questing", - "com.docker.sandboxes.flavor": "claude-code", - "com.docker.sdk": "true", - "com.docker.sdk.client": "0.1.0-alpha011", - "com.docker.sdk.container": "0.1.0-alpha012", - "com.docker.sdk.lang": "go", - "docker/sandbox": "true", - "org.opencontainers.image.ref.name": "ubuntu", - "org.opencontainers.image.version": "25.10" - } - } - ] - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_ls.yaml b/data/cli/sandbox/docker_sandbox_ls.yaml deleted file mode 100644 index 9eccb54007b5..000000000000 --- a/data/cli/sandbox/docker_sandbox_ls.yaml +++ /dev/null @@ -1,122 +0,0 @@ -command: docker sandbox ls -aliases: docker sandbox ls, docker sandbox list -short: List VMs -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - List all VMs managed by sandboxd with their sandboxes -usage: docker sandbox ls [OPTIONS] -pname: docker sandbox -plink: docker_sandbox.yaml -options: - - option: json - value_type: bool - default_value: "false" - description: Output in JSON format - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display VM names - details_url: '#quiet' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### List all VMs - - ```console - $ docker sandbox ls - VM ID NAME STATUS WORKSPACE SOCKET PATH SANDBOXES AGENTS - abc123def claude-vm running /home/user/my-project /Users/.../docker-1764682554072.sock 2 claude - def456ghi gemini-vm stopped /home/user/ml-projects - ``` - - ### Show only VM names (--quiet) {#quiet} - - ```text - --quiet - ``` - - Output only VM names: - - ```console - $ docker sandbox ls --quiet - claude-vm - gemini-vm - ``` - - ### JSON output (--json) - - ```text - --json - ``` - - Output detailed VM information in JSON format: - - ```console - $ docker sandbox ls --json - { - "vms": [ - { - "name": "claude-vm", - "agent": "claude", - "status": "running", - "socket_path": "/Users/user/.docker/sandboxes/vm/claude-vm/docker-1234567890.sock", - "sandbox_count": 2, - "workspaces": [ - "/home/user/my-project", - "/home/user/another-project" - ] - }, - { - "name": "gemini-vm", - "agent": "gemini", - "status": "stopped", - "sandbox_count": 0 - } - ] - } - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_network.yaml b/data/cli/sandbox/docker_sandbox_network.yaml deleted file mode 100644 index 8b91cb27a5de..000000000000 --- a/data/cli/sandbox/docker_sandbox_network.yaml +++ /dev/null @@ -1,64 +0,0 @@ -command: docker sandbox network -short: Manage sandbox networking -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Manage sandbox networking -usage: docker sandbox network -pname: docker sandbox -plink: docker_sandbox.yaml -cname: - - docker sandbox network log - - docker sandbox network proxy -clink: - - docker_sandbox_network_log.yaml - - docker_sandbox_network_proxy.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### View network logs - - ```console - $ docker sandbox network log - ``` - - ### Configure proxy for a sandbox - - ```console - $ docker sandbox network proxy my-sandbox --block-host example.com - ``` - - See the subcommands for more details: - - [`docker sandbox network log`](/reference/cli/docker/sandbox/network/log/) - Show network logs - - [`docker sandbox network proxy`](/reference/cli/docker/sandbox/network/proxy/) - Manage proxy configuration -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_network_log.yaml b/data/cli/sandbox/docker_sandbox_network_log.yaml deleted file mode 100644 index a336553cab3e..000000000000 --- a/data/cli/sandbox/docker_sandbox_network_log.yaml +++ /dev/null @@ -1,132 +0,0 @@ -command: docker sandbox network log -short: Show network logs -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Show network logs -usage: docker sandbox network log -pname: docker sandbox network -plink: docker_sandbox_network.yaml -options: - - option: json - value_type: bool - default_value: "false" - description: Output in JSON format - details_url: '#json' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: limit - value_type: int - default_value: "0" - description: Maximum number of log entries to show - details_url: '#limit' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display log entries - details_url: '#quiet' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Show network logs - - ```console - $ docker sandbox network log - 2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed - 2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed - 2026-01-29T10:15:25Z sandbox=my-sandbox request GET https://blocked.example.com/ denied - ``` - - ### Show only log entries (--quiet) {#quiet} - - ```text - --quiet - ``` - - Suppress headers and only show log entries: - - ```console - $ docker sandbox network log --quiet - 2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed - 2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed - ``` - - ### Limit number of entries (--limit) {#limit} - - ```text - --limit N - ``` - - Show only the last N log entries: - - ```console - $ docker sandbox network log --limit 10 - ``` - - ### JSON output (--json) {#json} - - Output logs in JSON format for parsing: - - ```console - $ docker sandbox network log --json - { - "entries": [ - { - "timestamp": "2026-01-29T10:15:23Z", - "sandbox": "my-sandbox", - "type": "request", - "method": "GET", - "url": "https://api.example.com/data", - "action": "allowed" - } - ] - } - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_network_proxy.yaml b/data/cli/sandbox/docker_sandbox_network_proxy.yaml deleted file mode 100644 index 4d08f7557144..000000000000 --- a/data/cli/sandbox/docker_sandbox_network_proxy.yaml +++ /dev/null @@ -1,208 +0,0 @@ -command: docker sandbox network proxy -short: Manage proxy configuration for a sandbox -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Manage proxy configuration for a sandbox -usage: docker sandbox network proxy [OPTIONS] -pname: docker sandbox network -plink: docker_sandbox_network.yaml -options: - - option: allow-cidr - value_type: string - description: | - Remove an IP range in CIDR notation from the block or bypass lists (can be specified multiple times) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: allow-host - value_type: string - description: Permit access to a domain or IP (can be specified multiple times) - details_url: '#allow-host' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: block-cidr - value_type: string - description: | - Block access to an IP range in CIDR notation (can be specified multiple times) - details_url: '#block-cidr' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: block-host - value_type: string - description: Block access to a domain or IP (can be specified multiple times) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: bypass-cidr - value_type: string - description: | - Bypass MITM proxy for an IP range in CIDR notation (can be specified multiple times) - details_url: '#bypass-cidr' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: bypass-host - value_type: string - description: | - Bypass MITM proxy for a domain or IP (can be specified multiple times) - details_url: '#bypass-host' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: policy - value_type: allow|deny - description: Set the default policy - details_url: '#policy' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Block access to a domain - - ```console - $ docker sandbox network proxy my-sandbox --block-host example.com - ``` - - ### Block multiple domains - - ```console - $ docker sandbox network proxy my-sandbox \ - --block-host example.com \ - --block-host malicious.site - ``` - - ### Block IP range (--block-cidr) {#block-cidr} - - ```text - --block-cidr CIDR - ``` - - Block access to an IP range in CIDR notation: - - ```console - $ docker sandbox network proxy my-sandbox --block-cidr 192.168.1.0/24 - ``` - - ### Allow specific domain (--allow-host) {#allow-host} - - ```text - --allow-host DOMAIN - ``` - - Permit access to a domain (useful with deny-by-default policy): - - ```console - $ docker sandbox network proxy my-sandbox \ - --policy deny \ - --allow-host api.trusted-service.com - ``` - - ### Bypass MITM proxy for domain (--bypass-host) {#bypass-host} - - ```text - --bypass-host DOMAIN - ``` - - Bypass MITM proxy for specific domains: - - ```console - $ docker sandbox network proxy my-sandbox --bypass-host localhost - ``` - - ### Bypass MITM proxy for IP range (--bypass-cidr) {#bypass-cidr} - - ```text - --bypass-cidr CIDR - ``` - - Bypass MITM proxy for an IP range: - - ```console - $ docker sandbox network proxy my-sandbox --bypass-cidr 127.0.0.0/8 - ``` - - ### Set default policy (--policy) {#policy} - - ```text - --policy allow|deny - ``` - - Set the default policy for network access: - - ```console - # Allow by default, block specific hosts - $ docker sandbox network proxy my-sandbox \ - --policy allow \ - --block-host dangerous.example - - # Deny by default, allow specific hosts - $ docker sandbox network proxy my-sandbox \ - --policy deny \ - --allow-host api.trusted.com \ - --allow-host cdn.trusted.com - ``` - - ### Remove rules - - Use `--allow-cidr` to remove IP ranges from block or bypass lists: - - ```console - $ docker sandbox network proxy my-sandbox --allow-cidr 192.168.1.0/24 - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_reset.yaml b/data/cli/sandbox/docker_sandbox_reset.yaml deleted file mode 100644 index af156092fb89..000000000000 --- a/data/cli/sandbox/docker_sandbox_reset.yaml +++ /dev/null @@ -1,92 +0,0 @@ -command: docker sandbox reset -short: Reset all VM sandboxes and clean up state -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Reset all VM sandboxes and permanently delete all VM data. - - This command will: - - Stop all running VMs gracefully (30s timeout) - - Delete all VM state directories in ~/.docker/sandboxes/vm/ - - Clear image cache in ~/.docker/sandboxes/image-cache/ - - Clear all internal registries - - The daemon will continue running with fresh state after reset. - - ⚠️ WARNING: This is a destructive operation that cannot be undone! - All running agents will be forcefully terminated and their work will be lost. - Cached image tars will be deleted and will need to be recreated on next use. - - By default, you will be prompted to confirm (y/N). - Use --force to skip the confirmation prompt. -usage: docker sandbox reset [OPTIONS] -pname: docker sandbox -plink: docker_sandbox.yaml -options: - - option: force - shorthand: f - value_type: bool - default_value: "false" - description: Skip confirmation prompt - details_url: '#force' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Reset with confirmation prompt - - ```console - $ docker sandbox reset - ⚠️ WARNING: This will permanently delete all VM data and stop all running agents! - Are you sure you want to continue? (y/N): y - All VMs reset successfully - ``` - - ### Force reset without confirmation (-f, --force) {#force} - - Skip the confirmation prompt: - - ```console - $ docker sandbox reset --force - All VMs reset successfully - ``` - - > [!CAUTION] - > This is a destructive operation that cannot be undone! - > All running agents will be terminated and their work will be lost. -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_rm.yaml b/data/cli/sandbox/docker_sandbox_rm.yaml deleted file mode 100644 index dce4b78a0b86..000000000000 --- a/data/cli/sandbox/docker_sandbox_rm.yaml +++ /dev/null @@ -1,68 +0,0 @@ -command: docker sandbox rm -aliases: docker sandbox rm, docker sandbox remove -short: Remove one or more sandboxes -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Remove one or more sandboxes and all their associated resources. - - This command will: - - Check if the sandbox exists - - Remove the sandbox and clean up its associated resources -usage: docker sandbox rm SANDBOX [SANDBOX...] -pname: docker sandbox -plink: docker_sandbox.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Remove a sandbox - - ```console - $ docker sandbox rm abc123def - abc123def - ``` - - ### Remove multiple sandboxes - - ```console - $ docker sandbox rm abc123def def456ghi - abc123def - def456ghi - ``` - - ### Remove all sandboxes - - ```console - $ docker sandbox rm $(docker sandbox ls -q) - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_run.yaml b/data/cli/sandbox/docker_sandbox_run.yaml deleted file mode 100644 index 75d93705617d..000000000000 --- a/data/cli/sandbox/docker_sandbox_run.yaml +++ /dev/null @@ -1,171 +0,0 @@ -command: docker sandbox run -short: Run an agent in a sandbox -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Run an agent in a sandbox. Create the sandbox if it does not exist. - - Pass agent arguments after the "--" separator. - Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - - Examples: - # Create and run a sandbox with claude in current directory - docker sandbox run claude - - # Create and run a sandbox with claude in current directory (explicit) - docker sandbox run claude . - - # Create and run with additional workspaces (read-only) - docker sandbox run claude . /path/to/docs:ro - - # Run an existing sandbox - docker sandbox run existing-sandbox - - # Run a sandbox with agent arguments - docker sandbox run claude -- --continue -usage: docker sandbox run SANDBOX [-- AGENT_ARGS...] | AGENT [WORKSPACE] [EXTRA_WORKSPACE...] [-- AGENT_ARGS...] -pname: docker sandbox -plink: docker_sandbox.yaml -options: - - option: detached - shorthand: d - value_type: bool - default_value: "false" - description: Return sandbox ID without running agent (hidden, for testing) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: name - value_type: string - description: 'Name for the sandbox (default: -)' - details_url: '#name' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: patch-settings - value_type: bool - default_value: "false" - description: Intercept claude settings API call and patch payload - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: pull-template - value_type: string - default_value: missing - description: | - Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images) - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: template - shorthand: t - value_type: string - description: | - Container image to use for the sandbox (default: agent-specific image) - details_url: '#template' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Create and run Claude in the current directory - - ```console - $ docker sandbox run claude . - ``` - - ### Run an existing sandbox - - ```console - $ docker sandbox run my-sandbox - ``` - - ### Create and run with a specific workspace - - ```console - $ docker sandbox run claude ~/projects/my-app - ``` - - The workspace directory is mounted at the same absolute path inside the sandbox. - - ### Name the sandbox (--name) {#name} - - ```text - --name NAME - ``` - - Assign a custom name when creating a sandbox: - - ```console - $ docker sandbox run --name my-project claude . - ``` - - ### Use a custom base image (-t, --template) {#template} - - ```text - --template IMAGE - ``` - - Specify a custom container image when creating a sandbox: - - ```console - $ docker sandbox run --template python:3-alpine claude . - ``` - - By default, each agent uses a pre-configured image. The `--template` option - lets you substitute a different image. - - ### Pass arguments to the agent - - Use `--` to separate sandbox options from agent arguments: - - ```console - $ docker sandbox run claude . -- -p "What version are you running?" - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_save.yaml b/data/cli/sandbox/docker_sandbox_save.yaml deleted file mode 100644 index a326ad69ba6e..000000000000 --- a/data/cli/sandbox/docker_sandbox_save.yaml +++ /dev/null @@ -1,64 +0,0 @@ -command: docker sandbox save -short: Save a snapshot of the sandbox as a template -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Save a snapshot of the sandbox as a template. - - By default, the image is loaded into the host's Docker daemon (requires Docker to be running). - Use --output to save the image to a tar file instead. - - Examples: - # Load into host Docker (requires host Docker running) - docker sandbox save my-sandbox myimage:v1.0 - - # Save to file (works without host Docker) - docker sandbox save my-sandbox myimage:v1.0 --output /tmp/myimage.tar -usage: docker sandbox save SANDBOX TAG -pname: docker sandbox -plink: docker_sandbox.yaml -options: - - option: output - shorthand: o - value_type: string - description: | - Save image to specified tar file instead of loading into host Docker - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_stop.yaml b/data/cli/sandbox/docker_sandbox_stop.yaml deleted file mode 100644 index 957b1ee275c0..000000000000 --- a/data/cli/sandbox/docker_sandbox_stop.yaml +++ /dev/null @@ -1,63 +0,0 @@ -command: docker sandbox stop -short: Stop one or more sandboxes without removing them -long: | - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Stop one or more sandboxes without removing them. The sandboxes can be restarted later. -usage: docker sandbox stop SANDBOX [SANDBOX...] -pname: docker sandbox -plink: docker_sandbox.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Stop a sandbox - - ```console - $ docker sandbox stop my-sandbox - my-sandbox - ``` - - ### Stop multiple sandboxes - - ```console - $ docker sandbox stop sandbox1 sandbox2 - sandbox1 - sandbox2 - ``` - - ### Stop all running sandboxes - - ```console - $ docker sandbox stop $(docker sandbox ls -q) - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/sandbox/docker_sandbox_version.yaml b/data/cli/sandbox/docker_sandbox_version.yaml deleted file mode 100644 index e7c0e3a90761..000000000000 --- a/data/cli/sandbox/docker_sandbox_version.yaml +++ /dev/null @@ -1,49 +0,0 @@ -command: docker sandbox version -short: Show sandbox version information -long: |- - > [!WARNING] - > The Docker Desktop-integrated `docker sandbox` commands are deprecated and - > replaced by the standalone [`sbx` CLI](/manuals/ai/sandboxes/_index.md). - > This deprecation applies only to the Docker Desktop integration, not to Docker - > Sandboxes. - - Show sandbox version information -usage: docker sandbox version -pname: docker sandbox -plink: docker_sandbox.yaml -inherited_options: - - option: debug - shorthand: D - value_type: bool - default_value: "false" - description: Enable debug logging - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: socket - value_type: string - description: | - Connect to daemon at specific socket path (for development/debugging) - deprecated: false - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Show version information - - ```console - $ docker sandbox version - github.com/docker/sandboxes/cli-plugin v0.7.1 f00f0d6473647c2201cd0507ce31613345c48ae6 - ``` -deprecated: false -hidden: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/data/cli/scout/docker_scout_compare.yaml b/data/cli/scout/docker_scout_compare.yaml index dfcb4ccc74c8..37e3649c1909 100644 --- a/data/cli/scout/docker_scout_compare.yaml +++ b/data/cli/scout/docker_scout_compare.yaml @@ -69,6 +69,7 @@ options: Output format of the generated vulnerability report: - text: default output, plain text with or without colors depending on the terminal - markdown: Markdown output + - json: JSON output deprecated: false hidden: false experimental: false @@ -226,6 +227,46 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: policy-bundle + value_type: stringArray + default_value: '[]' + description: OCI reference of a policy bundle to evaluate (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-config + value_type: string + description: | + Path or http(s) URL to a JSON file configuring policy enablement and inputs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-dir + value_type: stringArray + default_value: '[]' + description: Path to a directory of local .rego policy files (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-file + value_type: stringArray + default_value: '[]' + description: Path or http(s) URL to a .rego policy file (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: ref value_type: string description: |- diff --git a/data/cli/scout/docker_scout_policy.yaml b/data/cli/scout/docker_scout_policy.yaml index 077907ee2b08..e2772f5ec47c 100644 --- a/data/cli/scout/docker_scout_policy.yaml +++ b/data/cli/scout/docker_scout_policy.yaml @@ -1,6 +1,6 @@ command: docker scout policy short: | - Evaluate policies against an image and display the policy evaluation results (experimental) + Evaluate local Rego policies against an image and display the results (experimental) long: |- The `docker scout policy` command evaluates policies against an image. The image analysis is uploaded to Docker Scout where policies get evaluated. @@ -9,16 +9,11 @@ long: |- usage: docker scout policy [IMAGE | REPO] pname: docker scout plink: docker_scout.yaml +cname: + - docker scout policy publish +clink: + - docker_scout_policy_publish.yaml options: - - option: env - value_type: string - description: Name of the environment to compare to - deprecated: true - hidden: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - option: exit-code shorthand: e value_type: bool @@ -61,26 +56,57 @@ options: swarm: false - option: platform value_type: string - description: Platform of image to pull policy results from + description: Platform of image to evaluate policies against deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false - - option: to-env + - option: policy-bundle + value_type: stringArray + default_value: '[]' + description: OCI reference of a policy bundle to evaluate (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-config value_type: string - description: Name of the environment to compare to + description: | + Path or http(s) URL to a JSON file configuring policy enablement and inputs deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false - - option: to-latest - value_type: bool - default_value: "false" - description: Latest image processed to compare to + - option: policy-dir + value_type: stringArray + default_value: '[]' + description: Path to a directory of local .rego policy files (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-file + value_type: stringArray + default_value: '[]' + description: Path or http(s) URL to a .rego policy file (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: result-file + value_type: string + description: | + Write the full Rego evaluation result (pass, violations, query bindings and OPA metrics) of each evaluated policy to a JSON file (useful when iterating on local --policy-file policies) deprecated: false hidden: false experimental: false diff --git a/data/cli/scout/docker_scout_policy_publish.yaml b/data/cli/scout/docker_scout_policy_publish.yaml new file mode 100644 index 000000000000..c5ea24b9422a --- /dev/null +++ b/data/cli/scout/docker_scout_policy_publish.yaml @@ -0,0 +1,60 @@ +command: docker scout policy publish +short: | + Package local Rego policies into an OCI bundle and push it to a registry (experimental) +long: |- + The docker scout policy publish command packages Rego policies into an OCI policy bundle and pushes it to a registry. The published bundle can then be evaluated with docker scout policy --policy-bundle REFERENCE. + + When no --policy-file or --policy-dir is given, the built-in default policy set is published. Authentication uses your existing registry credentials (run "docker login" first). +usage: docker scout policy publish [OPTIONS] REFERENCE +pname: docker scout policy +plink: docker_scout_policy.yaml +options: + - option: policy-dir + value_type: stringArray + default_value: '[]' + description: | + Path to a directory of local .rego policy files to include (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-file + value_type: stringArray + default_value: '[]' + description: Path or http(s) URL to a .rego policy file to include (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: debug + value_type: bool + default_value: "false" + description: Debug messages + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: verbose-debug + value_type: bool + default_value: "false" + description: Verbose debug + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: " Publish the built-in default policies:\n $ docker scout policy publish registry.example.com/policies:latest\e[0m\n\n Publish a directory of local policies:\n $ docker scout policy publish --policy-dir ./rego registry.example.com/policies:latest\e[0m\n\n Publish specific policy files:\n $ docker scout policy publish --policy-file fixable.rego --policy-file licenses.rego registry.example.com/policies:latest\e[0m" +deprecated: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/data/cli/scout/docker_scout_quickview.yaml b/data/cli/scout/docker_scout_quickview.yaml index 1ff9869c5a32..8932e1361d3e 100644 --- a/data/cli/scout/docker_scout_quickview.yaml +++ b/data/cli/scout/docker_scout_quickview.yaml @@ -115,6 +115,46 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: policy-bundle + value_type: stringArray + default_value: '[]' + description: OCI reference of a policy bundle to evaluate (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-config + value_type: string + description: | + Path or http(s) URL to a JSON file configuring policy enablement and inputs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-dir + value_type: stringArray + default_value: '[]' + description: Path to a directory of local .rego policy files (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: policy-file + value_type: stringArray + default_value: '[]' + description: Path or http(s) URL to a .rego policy file (repeatable) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: ref value_type: string description: |- diff --git a/data/cli/secrets/docker_pass.yaml b/data/cli/secrets/docker_pass.yaml index e2c7989b5550..468af9c14654 100644 --- a/data/cli/secrets/docker_pass.yaml +++ b/data/cli/secrets/docker_pass.yaml @@ -6,6 +6,40 @@ long: |- vaults, and injecting them into containers and host commands when needed. Each backend is implemented as a plugin. + ### Installation + + On Docker Desktop, Secrets Engine and `docker pass` are integrated by default. + For Docker CE, install the packages separately from Docker's official + repository. This requires Docker Engine (`dockerd`) 29.2.0 or later. If you did + not install Docker Engine from that repository, add it with the official + convenience script: + + ```shell + curl -fsSL https://get.docker.com | sh -s -- --setup-repo + ``` + + apt (Debian/Ubuntu): + + ```shell + sudo apt-get update + sudo apt-get install docker-secrets-engine docker-secrets-engine-plugins + ``` + + dnf (Fedora): + + ```shell + sudo dnf install docker-secrets-engine docker-secrets-engine-plugins + ``` + + Then enable the service for your user: + + ```shell + systemctl --user daemon-reload + systemctl --user enable --now docker-secrets-engine.service + ``` + + For full instructions see the [Secrets Engine README](https://github.com/docker/secrets-engine/blob/main/README.md). + ### Secret References A secret reference is written using the `se://` URI scheme and either @@ -52,6 +86,8 @@ long: |- DB_PASSWORD: se://postgres/prod/app-user ``` + Note: `docker compose build` is not supported yet. + #### Host commands `docker pass run` wraps any host process and resolves `se://` @@ -127,6 +163,72 @@ long: |- internal secrets used by other plugins, such as the 1Password service account token). Always on; not configurable. + #### 1Password (configurable) + + Each item matches the requested pattern under up to three candidate IDs: + + 1. **Raw item ID** — the opaque alphanumeric ID that 1Password assigns + (e.g. `alphanumeric_26char`). + 2. **`/`** — the vault's ID joined with the item's + normalized title. + 3. **`<vault-name>/<title>`** — the vault's display name joined with + the item's normalized title. + + Normalization (applied to vault names and titles) follows 1Password's + [secret-reference syntax](https://developer.1password.com/docs/cli/secret-reference-syntax/): + spaces become `-`, `(` and `)` are stripped, `/` and `&` become `_`, + any remaining character outside `[a-zA-Z0-9-._]` is removed, and the + result is lowercased. Following 1Password's matching rules makes the + plugin case-insensitive, so existing `op://` references can be reused + as-is. + Candidates that don't produce a valid ID are skipped silently, so + items with unusual names are still matchable through one of the other + forms. + + ##### CLI version + + - **Plugin name:** `1password-cli` + - **How it authenticates:** delegates to the [`op` CLI](https://developer.1password.com/docs/cli/). + You need `op` installed and an active 1Password session. On macOS + this typically means the 1Password desktop app with biometric unlock + enabled; on other platforms, `op signin`. + - **Setup:** no tokens to manage. If your local `op` is signed in, the + plugin can resolve secrets. + - **Behavior:** when Docker Desktop starts, the plugin performs an + initial fetch of all items, which triggers a 1Password authorization + prompt. The resulting cache is then refreshed periodically. + - **Fatal errors:** the plugin treats a few conditions as + unrecoverable and stops itself instead of retrying: + - the `op` binary cannot be found on `PATH`, + - the user dismisses or lets the 1Password authorization prompt + time out. + + When this happens the plugin is reported as crashed in + `docker pass plugins ls`. Resolve the underlying issue (install + `op`, sign in, accept the prompt) and re-enable the plugin with + `docker pass plugins enable 1password-cli`. + - **Enable / disable:** + ```sh + docker pass plugins enable 1password-cli + docker pass plugins disable 1password-cli + ``` + + ##### Service account token version + + - **Plugin name:** `1password-sdk` + - **How it authenticates:** uses the official 1Password Go SDK with a + [service account token](https://developer.1password.com/docs/service-accounts/get-started/) + scoped to the vaults you want to expose. + - **Setup:** supply the token once on stdin. It is stored in the OS + keychain and the plugin is enabled in the same step: + ```sh + echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup + ``` + - **Teardown:** remove the token and disable the plugin: + ```sh + docker pass plugins 1password purge + ``` + ### Feedback and SDK Use the Go SDK at diff --git a/data/cli/secrets/docker_pass_plugins.yaml b/data/cli/secrets/docker_pass_plugins.yaml index e2b9da8b5501..87104358352e 100644 --- a/data/cli/secrets/docker_pass_plugins.yaml +++ b/data/cli/secrets/docker_pass_plugins.yaml @@ -10,10 +10,12 @@ usage: docker pass plugins pname: docker pass plink: docker_pass.yaml cname: + - docker pass plugins 1password - docker pass plugins disable - docker pass plugins enable - docker pass plugins ls clink: + - docker_pass_plugins_1password.yaml - docker_pass_plugins_disable.yaml - docker_pass_plugins_enable.yaml - docker_pass_plugins_ls.yaml diff --git a/data/cli/secrets/docker_pass_plugins_1password.yaml b/data/cli/secrets/docker_pass_plugins_1password.yaml new file mode 100644 index 000000000000..0e6b9bf6106b --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password.yaml @@ -0,0 +1,42 @@ +command: docker pass plugins 1password +short: Manage the 1Password SDK plugin. +long: |- + Manage the `1password-sdk` plugin, which resolves secret references against 1Password through the official 1Password SDK. + + The plugin authenticates with a [service account token](https://developer.1password.com/docs/service-accounts/get-started/) scoped to the vaults you want to expose. The token is stored in the local OS keychain. Use the subcommands to install the token (and enable the plugin) or to remove it (and disable the plugin). + + Items reachable through this plugin are matched under any of: + + - the raw 1Password item ID, + - `<vault-id>/<title>`, + - `<vault-name>/<title>`, + - a native 1Password secret-reference path (`<vault>/<item>/<field>` or `<vault>/<item>/<section>/<field>`), resolved directly via the SDK as if prefixed with `op://`. + + Matching for the title-based forms follows 1Password's normalization rules and is case-insensitive, so existing `op://` references can be reused as-is. +usage: docker pass plugins 1password +pname: docker pass plugins +plink: docker_pass_plugins.yaml +cname: + - docker pass plugins 1password purge + - docker pass plugins 1password setup +clink: + - docker_pass_plugins_1password_purge.yaml + - docker_pass_plugins_1password_setup.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false +examples: |- + Install the service account token and enable the plugin: + + ```sh + echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup + ``` + + Remove the token and disable the plugin: + + ```sh + docker pass plugins 1password purge + ``` diff --git a/data/cli/secrets/docker_pass_plugins_1password_purge.yaml b/data/cli/secrets/docker_pass_plugins_1password_purge.yaml new file mode 100644 index 000000000000..4985759ef480 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password_purge.yaml @@ -0,0 +1,15 @@ +command: docker pass plugins 1password purge +short: Disable the plugin and remove the stored 1Password service account token. +long: |- + Disable the `1password-sdk` plugin on the running secrets-engine daemon and remove the service account token from the local OS keychain. + + After purge, the plugin no longer participates in secret resolution and the token is gone from local storage. Run `setup` again to re-enable it. +usage: docker pass plugins 1password purge +pname: docker pass plugins 1password +plink: docker_pass_plugins_1password.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_plugins_1password_setup.yaml b/data/cli/secrets/docker_pass_plugins_1password_setup.yaml new file mode 100644 index 000000000000..9dfe9857cc22 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password_setup.yaml @@ -0,0 +1,17 @@ +command: docker pass plugins 1password setup +short: Set the 1Password service account token and enable the plugin. +long: |- + Store a 1Password [service account token](https://developer.1password.com/docs/service-accounts/get-started/) in the local OS keychain and enable the `1password-sdk` plugin. + + The token is read from STDIN and replaces any previously stored token. Once it is stored, the secrets engine is asked to enable the plugin so subsequent lookups resolve against 1Password. + + Service account tokens are scoped to a fixed set of vaults; only items in those vaults are reachable through the plugin. +usage: docker pass plugins 1password setup +pname: docker pass plugins 1password +plink: docker_pass_plugins_1password.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/languages.yaml b/data/languages.yaml deleted file mode 100644 index c3cae399d134..000000000000 --- a/data/languages.yaml +++ /dev/null @@ -1,30 +0,0 @@ -c-sharp: - title: "C#" - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/csharp/csharp-original.svg -cpp: - title: C++ - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/cplusplus/cplusplus-original.svg -go: - title: Go - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/go/go-original.svg -java: - title: Java - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/java/java-original.svg -js: - title: JavaScript - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/javascript/javascript-original.svg -php: - title: PHP - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/php/php-original.svg -python: - title: Python - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/python/python-original.svg -r: - title: R - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/r/r-original.svg -ruby: - title: Ruby - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/ruby/ruby-original.svg -rust: - title: Rust - icon: https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/rust/rust-original.svg diff --git a/data/redirects.yml b/data/redirects.yml index 6cf5aebe1e0e..3af405cce2a4 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -8,8 +8,12 @@ # provide a short, permanent link to refer to a topic in the documentation. # For example, the docker CLI can output https://docs.docker.com/go/some-topic # in its help output, which can be redirected to elsewhere in the documentation. -"/security/access-tokens/": +"/learn/": + - /learn +"/security/access-tokens/personal-access-tokens/": - /go/access-tokens/ +"/agentic-platform/": + - /go/dap/ "/reference/api/engine/#deprecated-api-versions": - /engine/api/v1.18/ - /engine/api/v1.19/ @@ -128,12 +132,54 @@ "https://docker.qualtrics.com/jfe/form/SV_3F9hnsKdzmlIr6m": - /feedback/gha-build-summary/ +# Removed product-tour guides +"/build-cloud/setup/": + - /guides/docker-build-cloud/ + - /learning-paths/docker-build-cloud/ +"/build-cloud/ci/": + - /guides/docker-build-cloud/ci/ +"/build-cloud/usage/": + - /guides/docker-build-cloud/dev/ +"/build-cloud/": + - /guides/docker-build-cloud/common-questions/ + - /guides/docker-build-cloud/why/ +"/compose/gettingstarted/": + - /guides/docker-compose/ + - /learning-paths/docker-compose/ + - /guides/docker-compose/setup/ +"/compose/support-and-feedback/faq/": + - /guides/docker-compose/common-questions/ +"/compose/intro/features-uses/": + - /guides/docker-compose/why/ +"/scout/how-tos/view-create-sboms/": + - /guides/docker-scout/sbom/ + - /scout/concepts/sbom/ +"/build/metadata/attestations/": + - /guides/docker-scout/attestations/ +"/scout/explore/image-details-view/#remediation-recommendations": + - /guides/docker-scout/remediation/ +"https://testcontainers.com/cloud/docs/": + - /guides/testcontainers-cloud/ + - /guides/testcontainers-cloud/common-questions/ + - /guides/testcontainers-cloud/demo-ci/ + - /guides/testcontainers-cloud/demo-local/ + - /guides/testcontainers-cloud/why/ +"/guides/lab-container-supported-development/": + - /guides/container-supported-development/ + # Docker Scout "/scout/": - /go/scout/ - /go/docker-scout/ + - /guides/docker-scout/why/ + - /guides/docker-scout/s3c/ + - /scout/concepts/s3c/ "/scout/quickstart/": - /go/scout-quickstart/ + - /guides/docker-scout/ + - /learning-paths/docker-scout/ + - /guides/docker-scout/common-questions/ + - /guides/docker-scout/demo/ "/scout/explore/dashboard/": - /go/scout-dashboard/ "/scout/policy/": @@ -152,8 +198,9 @@ - /go/scout-policy-dsp006/ "/scout/policy/#approved-base-images": - /go/scout-policy-dsp007/ -"/scout/policy/#sonarqube-quality-gates": +"/retired/#docker-scout-features": - /go/scout-policy-dsp008/ + - "/go/scout-github/" "/scout/policy/configure/": - /go/scout-configure-policy/ "/build/building/best-practices/#pin-base-image-versions": @@ -171,7 +218,7 @@ - "/go/scout-circle-ci/" "/scout/integrations/ci/jenkins/": - "/go/scout-jenkins/" -"/scout/integrations/registry/artifactory": +"/scout/integrations/registry/": - /go/scout-artifactory/ "/scout/integrations/registry/ecr/": - "/go/scout-ecr/" @@ -183,8 +230,6 @@ - "/go/scout-acr/" "/scout/integrations/code-quality/sonarqube/": - "/go/scout-sq/" -"/scout/integrations/source-code-management/github/": - - "/go/scout-github/" "/scout/guides/vex/": - "/go/vex-guide/" "/scout/explore/metrics-exporter/": @@ -239,6 +284,12 @@ - /go/builds-import/ "/build/checks/#experimental-checks": - "/go/build-checks-experimental/" +"/build/": + - /go/build/ +"/build/building/multi-stage/": + - /go/build-multi-stage/ +"/build/concepts/dockerfile/": + - /go/build-dockerfile/ # Build links (external) "https://app.docker.com/build/?utm_campaign=onboard-30-customer-zero&utm_medium=in-product-ad&utm_source=desktop_v4": @@ -249,9 +300,14 @@ - /go/docker-build-cloud/ # Run Cloud links & Docker Cloud & Docker Offload +"https://www.docker.com/products/docker-offload/": + - /go/offload/ +"https://app.docker.com/billing/subscription/dap/compute?returnTo=https://docs.docker.com/offload/quickstart/&ref=cli&refAction=NotEntitled": + - /go/get-offload/ "/": - /go/run-cloud-eap/ "/offload/": + - /go/cloud-flag/ # Onboarding - VDI beta - /go/docker-cloud/ "/offload/about/": @@ -281,7 +337,7 @@ - /go/dockerfile-reference/ - /engine/reference/builder/ - /reference/builder/ -"/get-started/04_sharing_app": +"/get-started/tutorials/run-an-app/": - /go/get-started-sharing/ # Docker Debug @@ -291,7 +347,7 @@ "/desktop/use-desktop/container/#execdebug": - /go/debug-gui/ -# Docker Admin Console - Insights +# Docker Admin Console/Home - Insights "/admin/organization/insights/": - /go/insights/ "/admin/organization/insights/#docker-desktop-users/": @@ -307,8 +363,11 @@ "/admin/organization/insights/#extensions": - /go/insights-extensions/ +"/desktop/enterprise/hardened-desktop/settings-management/": + - /go/settings-management/ + # Billing - cancellation -"/subscription/desktop-license/": +"/subscription-billing/desktop-license/": - /go/desktop-license/ "/docker-hub/usage/pulls/": - /go/hub-pull-limits/ @@ -316,6 +375,13 @@ # Links in Desktop +# Docker Sandboxes +"/ai/sandboxes/governance/access-controls/mcp/": + - /go/mcp-policy/ +"/ai/sandboxes/mcp-gateway/": + - /go/sbx-mcp-gateway/ +"https://www.docker.com/blog/harbor-docker-sandboxes-run-safe-reproducible-agent-evals/": + - /ai/sandboxes/harbor/ # Desktop MCP Toolkit "/ai/mcp-catalog-and-toolkit/toolkit/": @@ -340,6 +406,21 @@ # Desktop DMR "/ai/model-runner/": - /go/model-runner/ + - /guides/genai-pdf-bot/ + - /guides/use-case/genai-pdf-bot/ + - /guides/genai-pdf-bot/containerize/ + - /guides/genai-pdf-bot/develop/ + - /guides/rag-ollama/ + - /guides/use-case/rag-ollama/ + - /guides/rag-ollama/containerize/ + - /guides/rag-ollama/develop/ +"/ai/sandboxes/": + - /guides/github-sonarqube-sandbox/ + - /guides/github-sonarqube-sandbox/customize/ + - /guides/github-sonarqube-sandbox/troubleshoot/ + - /guides/github-sonarqube-sandbox/workflow/ + - /ai/mcp-catalog-and-toolkit/e2b-sandboxes/ + - /ai/mcp-catalog-and-toolkit/sandboxes/ # Docker Desktop - volumes cloud backup "/desktop/use-desktop/volumes/#export-a-volume": @@ -351,15 +432,18 @@ # Link used by Docker Desktop to refer users on how to activate WSL 2 "/desktop/features/wsl/": - /go/wsl2/ - -"/desktop/get-started/#credentials-management-for-linux-users": + - /go/windows-linux-vmm/ +"/desktop/setup/install/linux/": - /go/linux-credentials/ +"/desktop/enterprise/enforce-sign-in/": + - /go/enforce-sign-in/ "/desktop/use-desktop/pause/": - /go/mac-desktop-pause/ - /go/win-desktop-pause/ + - /go/desktop-pause/ "/desktop/settings-and-maintenance/settings/#file-sharing": - /go/mac-file-sharing/ - + - /go/file-sharing/ "/desktop/use-desktop/container/": - /go/container/ "/desktop/use-desktop/images/": @@ -368,10 +452,16 @@ - /go/volumes/ "/extensions/": - /go/extensions/ +"/extensions/extensions-sdk/": + - /go/extensions-sdk/ +"/extensions/extensions-sdk/extensions/": + - /go/publish-extensions/ "/engine/cli/completion/": - /go/completion/ "/desktop/features/vmm/": - /go/vmm/ + - /go/mac-vmm/ + - /go/windows-vmm/ "/security/for-admins/hardened-desktop/enhanced-container-isolation/": - /go/eci/ "/desktop/features/synchronized-file-sharing/": @@ -387,17 +477,116 @@ - /go/compose-bridge/ "/desktop/settings-and-maintenance/settings/": - /go/notifications/ + - /go/settings/ "/desktop/setup/install/mac-install/": - /go/apple-silicon/ "/desktop/setup/install/mac-permission-requirements/#installing-symlinks": - /go/symlinks/ "/desktop/setup/install/mac-permission-requirements/": - /go/permissions/ +"/desktop/setup/install/windows-permission-requirements/": + - /go/windows-permissions/ "/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports": - /go/port-mapping/ "/desktop/release-notes/": # Link to the Docker Desktop release notes. Used for in-product linkage. - /go/desktop-release-notes/ +"/desktop/features/networking/": + - /go/networks/ +"/desktop/troubleshoot-and-support/troubleshoot/": + - /go/troubleshoot/ +"/desktop/troubleshoot-and-support/troubleshoot/#diagnose": + - /go/diagnose/ +"/desktop/troubleshoot-and-support/feedback/": + - /go/feedback/ +"/desktop/": + - /go/desktop/ +"/desktop/features/containerd/": + - /go/containerd/ +"/desktop/use-desktop/logs/": + - /go/desktop-logs/ +"/desktop/setup/install/linux/#general-system-requirements": + - /go/desktop-linux-requirements/ +"/desktop/setup/install/mac-install/#system-requirements": + - /go/desktop-mac-requirements/ +"/desktop/setup/install/windows-install/#system-requirements": + - /go/desktop-windows-requirements/ +"/desktop/setup/install/windows-install/#installation-modes": + - /go/desktop-windows-install-modes/ +"/support/#diagnostic-data-and-privacy": + - /go/diagnostic-data/ + +#app.docker.com links + +"/security/authentication/oidc-connections/rulesets-claims/#subject-claims": + - /go/oidc-subject-claims/ + +"/compose/": + - /go/compose/ +"/reference/compose-file/": + - /go/compose-file/ +"/reference/compose-file/services/": + - /go/compose-file-services/ +"/reference/compose-file/services/#build": + - /go/compose-file-services-build/ +"/reference/compose-file/services/#depends_on": + - /go/compose-file-services-depends_on/ +"/reference/compose-file/services/#develop": + - /go/compose-file-services-develop/ +"/reference/compose-file/services/#env_file": + - /go/compose-file-services-env-file/ +"/reference/compose-file/services/#environment": + - /go/compose-file-services-environment/ +"/reference/compose-file/services/#healthcheck": + - /go/compose-file-services-healthcheck/ +"/reference/compose-file/services/#networks": + - /go/compose-file-services-networks/ +"/reference/compose-file/services/#ports": + - /go/compose-file-services-ports/ +"/reference/compose-file/services/#secrets": + - /go/compose-file-services-secrets/ +"/reference/compose-file/services/#volumes": + - /go/compose-file-services-volumes/ +"/reference/compose-file/networks/": + - /go/compose-file-networks/ +"/reference/compose-file/volumes/": + - /go/compose-file-volumes/ +"/reference/compose-file/configs/": + - /go/compose-file-configs/ +"/reference/compose-file/secrets/": + - /go/compose-file-secrets/ +"/reference/compose-file/interpolation/": + - /go/compose-file-interpolation/ +"/reference/compose-file/include/": + - /go/compose-file-include/ +"/reference/compose-file/profiles/": + - /go/compose-file-profiles/ +"/reference/compose-file/deploy/": + - /go/compose-file-deploy/ +"/compose/how-tos/file-watch/": + - /go/compose-watch/ +"/compose/how-tos/file-watch/#prerequisites": + - /go/compose-watch-prerequisites/ + +"/engine/network/drivers/host/": + - /go/host-network-driver/ +"/engine/storage/bind-mounts/": + - /go/bind-mounts/ +"/engine/storage/volumes/": + - /go/engine-volumes/ + +"/guides/nodejs/": + - /go/nodejs-guide/ +"/guides/python/": + - /go/python-guide/ +"/guides/golang/": + - /go/golang-guide/ +"/guides/java/": + - /go/java-guide/ +"/guides/dotnet/": + - /go/dotnet-guide/ +"/guides/rust/": + - /go/rust-guide/ # Docker Hardened Images (DHI) "/dhi/how-to/customize/": @@ -711,6 +900,7 @@ - /engine/reference/commandline/container_run/ - /engine/reference/commandline/run/ - /reference/cli/docker/run/ + - /go/commandline-run/ "/reference/cli/docker/container/start/": - /edge/engine/reference/commandline/container_start/ - /engine/reference/commandline/container_start/ diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml index df645ebc32d0..0348f491b88e 100644 --- a/data/sbx_cli/sbx.yaml +++ b/data/sbx_cli/sbx.yaml @@ -4,8 +4,12 @@ description: |- Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker. Run without a command to launch interactive mode, or pass a command for CLI usage. -usage: sbx +usage: sbx COMMAND options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -15,21 +19,33 @@ options: default_value: "false" usage: help for sbx see_also: + - sbx attach - Attach to a cloud sandbox, starting it first if it is stopped - sbx completion - Generate the autocompletion script for the specified shell - sbx cp - Copy files or directories between a sandbox and the host - sbx create - Create a sandbox for an agent + - sbx daemon - Manage sandboxd daemon - sbx diagnose - Diagnose common issues with your sbx installation + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file - sbx exec - Execute a command inside a sandbox - sbx kit - (Experimental) Manage kit artifacts - sbx login - Sign in to Docker - - sbx logout - Stop all running sandboxes and sign out of Docker + - sbx logout - Stop running local sandboxes and sign out of Docker - sbx ls - List sandboxes + - sbx mcp - Manage MCP servers + - sbx move - Move a sandbox between local and cloud - sbx policy - Manage sandbox policies - sbx ports - Manage sandbox port publishing + - sbx prune - Remove all stopped sandboxes - sbx reset - Reset all sandboxes and clean up state - sbx rm - Remove one or more sandboxes - sbx run - Run an agent in a sandbox - sbx secret - Manage stored secrets + - sbx settings - Manage Docker Sandboxes settings + - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes + - sbx skills - (Experimental) Manage skills available in sandboxes - sbx stop - Stop one or more sandboxes without removing them - sbx template - Manage sandbox templates + - sbx ttl - Show or extend a cloud sandbox's TTL + - sbx tui - Open the interactive TUI dashboard - sbx version - Show Docker Sandboxes version information + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_attach.yaml b/data/sbx_cli/sbx_attach.yaml new file mode 100644 index 000000000000..40cd65f8487c --- /dev/null +++ b/data/sbx_cli/sbx_attach.yaml @@ -0,0 +1,37 @@ +name: sbx attach +synopsis: | + Attach to a cloud sandbox, starting it first if it is stopped +description: |- + Attach an interactive terminal session to a cloud sandbox. + + SANDBOX is the cloud sandbox ID (sbx_*) or name from "sbx --cloud ls". + + Opens a PTY-backed exec session against the sandbox's agent process. The + sandbox must already exist; a stopped one is started first. Use + `sbx --cloud run` to create a sandbox and attach in one step. + + Only supported with --cloud. See https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model. +usage: sbx attach SANDBOX [flags] +options: + - name: detach-keys + usage: | + Override the detach gesture that leaves the session running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only). + - name: help + shorthand: h + default_value: "false" + usage: help for attach +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Attach to a sandbox by ID or name + sbx --cloud attach sbx_abc123 + sbx --cloud attach claude/my-sandbox +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_completion.yaml b/data/sbx_cli/sbx_completion.yaml index 1416516a628c..dfcfa4ef5509 100644 --- a/data/sbx_cli/sbx_completion.yaml +++ b/data/sbx_cli/sbx_completion.yaml @@ -3,12 +3,17 @@ synopsis: Generate the autocompletion script for the specified shell description: | Generate the autocompletion script for sbx for the specified shell. See each sub-command's help for details on how to use the generated script. +usage: sbx completion COMMAND options: - name: help shorthand: h default_value: "false" usage: help for completion inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_completion_bash.yaml b/data/sbx_cli/sbx_completion_bash.yaml index 4e06d587fb52..c12d6b9231e1 100644 --- a/data/sbx_cli/sbx_completion_bash.yaml +++ b/data/sbx_cli/sbx_completion_bash.yaml @@ -31,9 +31,19 @@ options: default_value: "false" usage: disable completion descriptions inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + # Load completions in the current shell + source <(sbx completion bash) + + # Install for every new shell + sbx completion bash > /etc/bash_completion.d/sbx see_also: - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_fish.yaml b/data/sbx_cli/sbx_completion_fish.yaml index 2d38fe4b2d51..d0b62d64d61b 100644 --- a/data/sbx_cli/sbx_completion_fish.yaml +++ b/data/sbx_cli/sbx_completion_fish.yaml @@ -22,9 +22,19 @@ options: default_value: "false" usage: disable completion descriptions inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + # Load completions in the current shell + sbx completion fish | source + + # Install for every new shell + sbx completion fish > ~/.config/fish/completions/sbx.fish see_also: - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_powershell.yaml b/data/sbx_cli/sbx_completion_powershell.yaml index 6a442b5d993b..3afc10fbb100 100644 --- a/data/sbx_cli/sbx_completion_powershell.yaml +++ b/data/sbx_cli/sbx_completion_powershell.yaml @@ -19,9 +19,19 @@ options: default_value: "false" usage: disable completion descriptions inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + # Load completions in the current session + sbx completion powershell | Out-String | Invoke-Expression + + # Install for every new session + sbx completion powershell >> $PROFILE see_also: - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_completion_zsh.yaml b/data/sbx_cli/sbx_completion_zsh.yaml index 2ccf93f0dd0b..dca27cf0ea74 100644 --- a/data/sbx_cli/sbx_completion_zsh.yaml +++ b/data/sbx_cli/sbx_completion_zsh.yaml @@ -33,9 +33,19 @@ options: default_value: "false" usage: disable completion descriptions inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + # Load completions in the current shell + source <(sbx completion zsh) + + # Install for every new shell + sbx completion zsh > "${fpath[1]}/_sbx" see_also: - sbx completion - Generate the autocompletion script for the specified shell diff --git a/data/sbx_cli/sbx_cp.yaml b/data/sbx_cli/sbx_cp.yaml index 6ae66220a6b7..690b3c9c6f04 100644 --- a/data/sbx_cli/sbx_cp.yaml +++ b/data/sbx_cli/sbx_cp.yaml @@ -2,23 +2,28 @@ name: sbx cp synopsis: Copy files or directories between a sandbox and the host description: |- Either SRC or DST must be a sandbox path, written as SANDBOX:PATH. - The other must be a local path. Copying between two sandboxes is not supported. + The other must be a local path. Copying between two sandboxes is not supported. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". Cloud transfers go through the Docker + Sandboxes Cloud file API instead of the local sandboxd. When copying a directory, the directory itself is placed at the destination. If the destination path does not exist it is created; if it already exists as a directory, the source is placed inside it. -usage: sbx cp [flags] SRC DST +usage: sbx cp SRC DST [flags] options: - name: follow-link shorthand: L default_value: "false" - usage: | - Follow symbolic links in the source path when copying from host to sandbox + usage: Follow symbolic links in the source path - name: help shorthand: h default_value: "false" usage: help for cp inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -32,5 +37,9 @@ example: |4- # Copy a directory sbx cp ./src/ my-sandbox:/home/user/src + + # Copy to/from a cloud sandbox + sbx --cloud cp ./config.json sbx_abc:/workspace/config.json + sbx --cloud cp sbx_abc:/workspace/out.log ./ see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml index f04f139fcd20..0175c8e62750 100644 --- a/data/sbx_cli/sbx_create.yaml +++ b/data/sbx_cli/sbx_create.yaml @@ -3,9 +3,36 @@ synopsis: Create a sandbox for an agent description: |- Create a sandbox with access to a host workspace for an agent. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create [flags] AGENT PATH [PATH...] + The first positional argument may be a built-in agent name or a sandbox kit + reference. Sandbox kit references may be local directories, ZIP files, git + repositories, or OCI references. Relative local references must be explicit + paths such as ./my-kit or ../my-kit.zip. + + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + Available agents: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, shell + + With --cloud: + Create a cloud sandbox for an agent. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create AGENT|SANDBOX_KIT [PATH...] [flags] options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | @@ -13,32 +40,90 @@ options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one - name: help shorthand: h default_value: "false" usage: help for create + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -53,17 +138,33 @@ example: |4- # Create with additional read-only workspaces sbx create claude . /path/to/docs:ro + # Create without a workspace bind mount + sbx create claude + + # Create from a local sandbox kit + sbx create ../path/to/my-agent/ + + # Add a mixin to a built-in agent + sbx create claude --kit ./my-mixin/ + # Run the agent on an in-container clone of the host repo, wired back via a git-daemon sbx create --clone claude . + + # Create a cloud sandbox for claude + sbx --cloud create claude + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project claude --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx - Manage AI coding agent sandboxes. - sbx create claude - Create a sandbox for claude - sbx create codex - Create a sandbox for codex - - sbx create copilot - Create a sandbox for copilot - sbx create cursor - Create a sandbox for cursor + - sbx create devin - Create a sandbox for devin - sbx create docker-agent - Create a sandbox for docker-agent - - sbx create droid - Create a sandbox for droid - sbx create gemini - Create a sandbox for gemini - - sbx create kiro - Create a sandbox for kiro - sbx create opencode - Create a sandbox for opencode - sbx create shell - Create a sandbox for shell diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml index 53bec5c85353..f9f9dd075447 100644 --- a/data/sbx_cli/sbx_create_claude.yaml +++ b/data/sbx_cli/sbx_create_claude.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for claude description: |- Create a sandbox with access to a host workspace for claude. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create claude PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for claude. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create claude [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for claude inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create claude . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create claude . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create claude + + # Create a cloud sandbox for claude + sbx --cloud create claude + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project claude --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml index 67393d652aa1..a9d92908771e 100644 --- a/data/sbx_cli/sbx_create_codex.yaml +++ b/data/sbx_cli/sbx_create_codex.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for codex description: |- Create a sandbox with access to a host workspace for codex. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create codex PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for codex. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create codex [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for codex inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create codex . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create codex . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create codex + + # Create a cloud sandbox for codex + sbx --cloud create codex + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project codex --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_copilot.yaml b/data/sbx_cli/sbx_create_copilot.yaml deleted file mode 100644 index 919955e209e2..000000000000 --- a/data/sbx_cli/sbx_create_copilot.yaml +++ /dev/null @@ -1,60 +0,0 @@ -name: sbx create copilot -synopsis: Create a sandbox for copilot -description: |- - Create a sandbox with access to a host workspace for copilot. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create copilot PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for copilot -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create copilot . - - # Create with a specific path - sbx create copilot /path/to/project - - # Create with additional read-only workspaces - sbx create copilot . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_cursor.yaml b/data/sbx_cli/sbx_create_cursor.yaml index 4052ad4df9cf..24a097f3876f 100644 --- a/data/sbx_cli/sbx_create_cursor.yaml +++ b/data/sbx_cli/sbx_create_cursor.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for cursor description: |- Create a sandbox with access to a host workspace for cursor. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create cursor PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for cursor. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create cursor [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for cursor inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create cursor . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create cursor . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create cursor + + # Create a cloud sandbox for cursor + sbx --cloud create cursor + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project cursor --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_devin.yaml b/data/sbx_cli/sbx_create_devin.yaml new file mode 100644 index 000000000000..bc76d6285969 --- /dev/null +++ b/data/sbx_cli/sbx_create_devin.yaml @@ -0,0 +1,151 @@ +name: sbx create devin +synopsis: Create a sandbox for devin +description: |- + Create a sandbox with access to a host workspace for devin. + + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for devin. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create devin [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for devin +inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) + - name: clone + default_value: "false" + usage: | + Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: cpus + default_value: "0" + usage: | + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) + - name: kit + default_value: '[]' + experimental: true + usage: | + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) + - name: name + usage: | + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress + default_value: "false" + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) +example: |4- + # Create in the current directory + sbx create devin . + + # Create with a specific path + sbx create devin /path/to/project + + # Create with additional read-only workspaces + sbx create devin . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create devin + + # Create a cloud sandbox for devin + sbx --cloud create devin + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project devin --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml index 7dd4bba6ec70..f336967fe185 100644 --- a/data/sbx_cli/sbx_create_docker-agent.yaml +++ b/data/sbx_cli/sbx_create_docker-agent.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for docker-agent description: |- Create a sandbox with access to a host workspace for docker-agent. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create docker-agent PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for docker-agent. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create docker-agent [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for docker-agent inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create docker-agent . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create docker-agent . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create docker-agent + + # Create a cloud sandbox for docker-agent + sbx --cloud create docker-agent + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project docker-agent --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_droid.yaml b/data/sbx_cli/sbx_create_droid.yaml deleted file mode 100644 index 08661c8324ee..000000000000 --- a/data/sbx_cli/sbx_create_droid.yaml +++ /dev/null @@ -1,60 +0,0 @@ -name: sbx create droid -synopsis: Create a sandbox for droid -description: |- - Create a sandbox with access to a host workspace for droid. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create droid PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for droid -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create droid . - - # Create with a specific path - sbx create droid /path/to/project - - # Create with additional read-only workspaces - sbx create droid . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml index 71bc390bd67e..22d2afa7f23d 100644 --- a/data/sbx_cli/sbx_create_gemini.yaml +++ b/data/sbx_cli/sbx_create_gemini.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for gemini description: |- Create a sandbox with access to a host workspace for gemini. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create gemini PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for gemini. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create gemini [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for gemini inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create gemini . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create gemini . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create gemini + + # Create a cloud sandbox for gemini + sbx --cloud create gemini + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project gemini --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_kiro.yaml b/data/sbx_cli/sbx_create_kiro.yaml deleted file mode 100644 index 2ed5e62b5ee0..000000000000 --- a/data/sbx_cli/sbx_create_kiro.yaml +++ /dev/null @@ -1,60 +0,0 @@ -name: sbx create kiro -synopsis: Create a sandbox for kiro -description: |- - Create a sandbox with access to a host workspace for kiro. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create kiro PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for kiro -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create kiro . - - # Create with a specific path - sbx create kiro /path/to/project - - # Create with additional read-only workspaces - sbx create kiro . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml index 9678dc9fd3ce..4365a06f8abb 100644 --- a/data/sbx_cli/sbx_create_opencode.yaml +++ b/data/sbx_cli/sbx_create_opencode.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for opencode description: |- Create a sandbox with access to a host workspace for opencode. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create opencode PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for opencode. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create opencode [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for opencode inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create opencode . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create opencode . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create opencode + + # Create a cloud sandbox for opencode + sbx --cloud create opencode + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project opencode --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml index 7e79dff9d6e4..4f50e5ce11fa 100644 --- a/data/sbx_cli/sbx_create_shell.yaml +++ b/data/sbx_cli/sbx_create_shell.yaml @@ -3,50 +3,129 @@ synopsis: Create a sandbox for shell description: |- Create a sandbox with access to a host workspace for shell. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. - Use "sbx run SANDBOX" to attach to the agent after creation. -usage: sbx create shell PATH [PATH...] [flags] + Omit the path to create a sandbox without a workspace bind mount: the agent + then works in the container's own filesystem instead of on your files. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + With --cloud: + Create a cloud sandbox for shell. + + Cloud sandboxes have no host workspace, so no path follows the agent. Sizing + comes from --cpus and --memory and must land on a billable shape; without them + a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry. + + Cloud sandboxes use cloud network policies. Host network and HTTP policies + do not apply. Set cloud account defaults with + "sbx --cloud policy init <allow-all|balanced|deny-all>". + + Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation. +usage: sbx create shell [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for shell inherited_options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) - name: debug shorthand: D default_value: "false" usage: Enable debug logging + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: | - Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only) - - name: quiet - shorthand: q + Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved) + - name: no-progress default_value: "false" - usage: Suppress verbose output + usage: Suppress progress output + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create shell . @@ -56,5 +135,17 @@ example: |4- # Create with additional read-only workspaces sbx create shell . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create shell + + # Create a cloud sandbox for shell + sbx --cloud create shell + + # Create a named cloud sandbox with a mixin baked in + sbx --cloud create --name my-project shell --kit ./my-mixin/ + + # Create from a template that already exists in the cloud registry + sbx --cloud create -t TEMPLATE see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_daemon.yaml b/data/sbx_cli/sbx_daemon.yaml new file mode 100644 index 000000000000..bad973f22029 --- /dev/null +++ b/data/sbx_cli/sbx_daemon.yaml @@ -0,0 +1,24 @@ +name: sbx daemon +synopsis: Manage sandboxd daemon +usage: sbx daemon COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for daemon +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx daemon log-level - Show or change sandboxd's per-category log levels + - sbx daemon restart - Restart the sandboxd daemon + - sbx daemon start - Start the sandboxd daemon + - sbx daemon status - Show sandboxd daemon status + - sbx daemon stop - Stop the sandboxd daemon diff --git a/data/sbx_cli/sbx_daemon_log-level.yaml b/data/sbx_cli/sbx_daemon_log-level.yaml new file mode 100644 index 000000000000..5c5a769408fd --- /dev/null +++ b/data/sbx_cli/sbx_daemon_log-level.yaml @@ -0,0 +1,20 @@ +name: sbx daemon log-level +synopsis: Show or change sandboxd's per-category log levels +usage: sbx daemon log-level [COMMAND] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for log-level +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx daemon - Manage sandboxd daemon + - 'sbx daemon log-level set - Set a category''s log level (target: proxy, general, or all)' diff --git a/data/sbx_cli/sbx_daemon_log-level_set.yaml b/data/sbx_cli/sbx_daemon_log-level_set.yaml new file mode 100644 index 000000000000..e6ea8e873561 --- /dev/null +++ b/data/sbx_cli/sbx_daemon_log-level_set.yaml @@ -0,0 +1,24 @@ +name: sbx daemon log-level set +synopsis: 'Set a category''s log level (target: proxy, general, or all)' +usage: sbx daemon log-level set TARGET LEVEL [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for set +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx daemon log-level set proxy debug + + # Every category at once + sbx daemon log-level set all info +see_also: + - sbx daemon log-level - Show or change sandboxd's per-category log levels diff --git a/data/sbx_cli/sbx_daemon_restart.yaml b/data/sbx_cli/sbx_daemon_restart.yaml new file mode 100644 index 000000000000..c94e79c7d98d --- /dev/null +++ b/data/sbx_cli/sbx_daemon_restart.yaml @@ -0,0 +1,20 @@ +name: sbx daemon restart +synopsis: Restart the sandboxd daemon +usage: sbx daemon restart [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for restart +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx daemon restart' +see_also: + - sbx daemon - Manage sandboxd daemon diff --git a/data/sbx_cli/sbx_daemon_start.yaml b/data/sbx_cli/sbx_daemon_start.yaml new file mode 100644 index 000000000000..c7e2c4a05976 --- /dev/null +++ b/data/sbx_cli/sbx_daemon_start.yaml @@ -0,0 +1,31 @@ +name: sbx daemon start +synopsis: Start the sandboxd daemon +usage: sbx daemon start [flags] +options: + - name: detach + shorthand: d + default_value: "false" + usage: Run daemon in background + - name: help + shorthand: h + default_value: "false" + usage: help for start + - name: policy + usage: | + Initialize the global network policy: "allow-all", "balanced", or "deny-all" +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx daemon start + + # Run in the background + sbx daemon start --detach +see_also: + - sbx daemon - Manage sandboxd daemon diff --git a/data/sbx_cli/sbx_daemon_status.yaml b/data/sbx_cli/sbx_daemon_status.yaml new file mode 100644 index 000000000000..4053d7a34b61 --- /dev/null +++ b/data/sbx_cli/sbx_daemon_status.yaml @@ -0,0 +1,29 @@ +name: sbx daemon status +synopsis: Show sandboxd daemon status +usage: sbx daemon status [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for status + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx daemon status + + # Machine-readable output + sbx daemon status --format json +see_also: + - sbx daemon - Manage sandboxd daemon diff --git a/data/sbx_cli/sbx_daemon_stop.yaml b/data/sbx_cli/sbx_daemon_stop.yaml new file mode 100644 index 000000000000..b003af079f9c --- /dev/null +++ b/data/sbx_cli/sbx_daemon_stop.yaml @@ -0,0 +1,20 @@ +name: sbx daemon stop +synopsis: Stop the sandboxd daemon +usage: sbx daemon stop [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for stop +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx daemon stop' +see_also: + - sbx daemon - Manage sandboxd daemon diff --git a/data/sbx_cli/sbx_diagnose.yaml b/data/sbx_cli/sbx_diagnose.yaml index e0eac7110fd6..a9c8c16c5c81 100644 --- a/data/sbx_cli/sbx_diagnose.yaml +++ b/data/sbx_cli/sbx_diagnose.yaml @@ -1,21 +1,35 @@ name: sbx diagnose synopsis: Diagnose common issues with your sbx installation -usage: sbx diagnose +usage: sbx diagnose [flags] options: + - name: format + usage: 'Output format: table, json, yaml or github-issue' - name: help shorthand: h default_value: "false" usage: help for diagnose - - name: output - shorthand: o - usage: 'Output format: "json" or "github-issue"' + - name: json + default_value: "false" + usage: Output in JSON format - name: upload default_value: "false" usage: Upload diagnostics to Docker support inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx diagnose + + # Print the report as JSON + sbx diagnose --format json + + # Upload the report to Docker support + sbx diagnose --upload see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_env.yaml b/data/sbx_cli/sbx_env.yaml new file mode 100644 index 000000000000..b7056de72034 --- /dev/null +++ b/data/sbx_cli/sbx_env.yaml @@ -0,0 +1,53 @@ +name: sbx env +synopsis: | + Manage sandboxes declaratively from an sbxenv.yaml file +experimental: true +description: |- + Manage a sandbox declared in an sbxenv.yaml file. The file selects the agent, + kits, workspace mounts, environment variables, secrets, and credential bindings. + + Use create to provision the sandbox, run to start or join its agent session, + exec to run a command, and rm to remove it and its provisioned secrets. + Use plan to preview changes. Changes require approval; --force skips the prompt. + + Lifecycle commands and command-based secrets execute on the host with your + permissions. Keep secret helpers and their dependencies outside writable + sandbox mounts, and use absolute helper paths. + + The environment file is mounted read-only by default when shared with the + sandbox. Set sandboxOptions.writableEnvFiles only when you trust the agent + to change what future invocations run on the host. + + With --cloud, manage a cloud sandbox from the same file. Host workspace mounts, + host port bindings, MCP definitions, registry credentials, and unsnapshotted + dynamic secret sources are unsupported. Clone the project inside the sandbox instead. + + Secrets and bindings are provisioned at creation; changes require recreating + the sandbox. Removal deletes secrets provisioned by this environment; bindings + are retained unless --prune-bindings is passed. Use the same cloud target, + identity, and ordered files for subsequent commands. + + For file syntax and workflows, see: + https://docs.docker.com/ai/sandboxes/configuration/environment-files/ +usage: sbx env COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for env +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx env create - Create a sandbox environment from sbxenv.yaml + - sbx env exec - Execute a command inside a sandbox environment + - sbx env plan - Show what an environment would change outside the sandbox + - sbx env rm - Remove a sandbox environment and its scoped resources + - sbx env run - Create (if needed) and attach to a sandbox environment diff --git a/data/sbx_cli/sbx_env_create.yaml b/data/sbx_cli/sbx_env_create.yaml new file mode 100644 index 000000000000..6d5aa1c4e031 --- /dev/null +++ b/data/sbx_cli/sbx_env_create.yaml @@ -0,0 +1,82 @@ +name: sbx env create +synopsis: Create a sandbox environment from sbxenv.yaml +experimental: true +description: |- + Read the environment file from PATH (default: current directory), + provision its declared secrets at the sandbox scope, merge its credential + bindings, and create the sandbox. Use "sbx env run" to attach. + + Each PATH may be a directory (the file is <PATH>/sbxenv.yaml) or the + path to the environment file itself. Passing more than one PATH deep-merges them + in order (docker-compose `-f` semantics): later files override earlier ones. + Values may reference the arguments the file declares with ${{ env.args.NAME }}, + supplied by --env-arg, plus ${{ env.projectDir }} and ${{ env.fileDir }}. + Nothing else is expanded, so a "$" is literal text. + + A directory PATH selects sbxenv.yaml; a file PATH selects that file. + With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. + Explicit PATHs skip those defaults. Later files override earlier values; + lists such as ports and mcp.servers are concatenated. +usage: sbx env create [PATH...] [flags] +options: + - name: clone + default_value: "false" + usage: | + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: force + shorthand: f + default_value: "false" + usage: Apply the environment plan without asking + - name: help + shorthand: h + default_value: "false" + usage: help for create + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: name + usage: | + Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one. + - name: skip-host-commands + default_value: "false" + usage: Skip the host lifecycle commands the environment declares + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Create the environment described in the current directory + sbx env create + + # Approve the plan without asking + sbx env create --force ./project +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_exec.yaml b/data/sbx_cli/sbx_env_exec.yaml new file mode 100644 index 000000000000..7820785b42b3 --- /dev/null +++ b/data/sbx_cli/sbx_env_exec.yaml @@ -0,0 +1,90 @@ +name: sbx env exec +synopsis: Execute a command inside a sandbox environment +experimental: true +description: |- + Run COMMAND in the sandbox declared in sbxenv.yaml. The sandbox + must already exist (see "sbx env create" and "sbx env run"); a stopped sandbox is + started first. + + Arguments before `--` are environment-file paths, following the same rules as + the other "sbx env" subcommands: each PATH may be a directory (the file is + <PATH>/sbxenv.yaml) or the path to the environment file itself, and passing + more than one deep-merges them in order. Without a `--` every positional + argument forms the command and the environment file is read from the current + directory. + + A directory PATH selects sbxenv.yaml; a file PATH selects that file. + With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. + Explicit PATHs skip those defaults. Later files override earlier values; + lists such as ports and mcp.servers are concatenated. + + Flags match the behavior of "sbx exec". +usage: sbx env exec [flags] [PATH...] -- COMMAND [ARG...] +options: + - name: detach + shorthand: d + default_value: "false" + usage: Detached mode (not supported) + - name: detach-keys + usage: Override the key sequence for detaching a container + - name: env + shorthand: e + default_value: '[]' + usage: Set environment variables + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: env-file + default_value: '[]' + usage: Read in a file of environment variables + - name: help + shorthand: h + default_value: "false" + usage: help for exec + - name: interactive + shorthand: i + default_value: "false" + usage: Keep STDIN open even if not attached + - name: name + usage: | + Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) + - name: privileged + default_value: "false" + usage: Give extended privileges to the command + - name: tty + shorthand: t + default_value: "false" + usage: Allocate a pseudo-TTY + - name: user + shorthand: u + usage: 'Username or UID (format: <name|uid>[:<group|gid>])' + - name: workdir + shorthand: w + usage: Working directory inside the container +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Run a command in the environment declared in the current directory + sbx env exec go test ./... + + # Open a shell + sbx env exec -it -- bash + + # Run against explicitly merged environment files + sbx env exec sbxenv.yaml override.yaml -- npm test +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_plan.yaml b/data/sbx_cli/sbx_env_plan.yaml new file mode 100644 index 000000000000..043fc49c669f --- /dev/null +++ b/data/sbx_cli/sbx_env_plan.yaml @@ -0,0 +1,74 @@ +name: sbx env plan +synopsis: Show what an environment would change outside the sandbox +experimental: true +description: |- + Read the environment file from PATH (default: current directory) and print + everything applying it would set up: the host commands it runs, the credentials + and bindings it provisions, the MCP servers it registers, the directories it + creates, the ports it publishes, and the sandbox itself along with the variables + it runs with. + + The plan is compared against what this environment last applied on this machine, + against what was approved where nothing applied it, and against what is there + now, so a second run shows only what moved. Nothing is applied, approved, or + recorded: use "sbx env create" or "sbx env run" for that. + + Each PATH may be a directory (the file is <PATH>/sbxenv.yaml) or the + path to the environment file itself. Passing more than one PATH deep-merges them + in order, matching the other "sbx env" subcommands. + + A directory PATH selects sbxenv.yaml; a file PATH selects that file. + With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. + Explicit PATHs skip those defaults. Later files override earlier values; + lists such as ports and mcp.servers are concatenated. +usage: sbx env plan [PATH...] [flags] +options: + - name: clone + default_value: "false" + usage: | + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: help + shorthand: h + default_value: "false" + usage: help for plan + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: name + usage: | + Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) + - name: skip-host-commands + default_value: "false" + usage: | + Plan without the host lifecycle commands the environment declares +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx env plan + sbx env plan ./project +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_rm.yaml b/data/sbx_cli/sbx_env_rm.yaml new file mode 100644 index 000000000000..6a9ca0e42238 --- /dev/null +++ b/data/sbx_cli/sbx_env_rm.yaml @@ -0,0 +1,66 @@ +name: sbx env rm +synopsis: Remove a sandbox environment and its scoped resources +experimental: true +description: |- + Remove the sandbox declared in sbxenv.yaml along with the + secret values provisioned at its sandbox scope (service, custom, and registry + credentials). Global credential bindings are left in place by default since + they are user-wide and may be shared with other sandboxes; pass + --prune-bindings to also remove the bindings this environment declares. + + Each PATH may be a directory (the file is <PATH>/sbxenv.yaml) or the + path to the environment file itself. Passing more than one PATH deep-merges them + in order (docker-compose `-f` semantics), so the same set used to create the + environment resolves to the same sandbox on removal. + + A directory PATH selects sbxenv.yaml; a file PATH selects that file. + With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. + Explicit PATHs skip those defaults. Later files override earlier values; + lists such as ports and mcp.servers are concatenated. +usage: sbx env rm [PATH...] [flags] +options: + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: force + shorthand: f + default_value: "false" + usage: | + Skip confirmation prompts and delete even if in use (e.g. an open SSH connection) + - name: help + shorthand: h + default_value: "false" + usage: help for rm + - name: name + usage: | + Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) + - name: prune-bindings + default_value: "false" + usage: | + Also remove this environment's bindings from the global credentials.yaml + - name: skip-host-commands + default_value: "false" + usage: Skip the host lifecycle commands the environment declares +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx env rm + + # Also remove the credential bindings the environment created + sbx env rm --force --prune-bindings ./project +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_run.yaml b/data/sbx_cli/sbx_env_run.yaml new file mode 100644 index 000000000000..28328857d7dd --- /dev/null +++ b/data/sbx_cli/sbx_env_run.yaml @@ -0,0 +1,86 @@ +name: sbx env run +synopsis: Create (if needed) and attach to a sandbox environment +experimental: true +description: |- + Read the environment file from PATH (default: current directory) + and drop into the sandbox shell. If the sandbox already exists it is started + and re-attached without re-provisioning; otherwise it is created first + (provisioning secrets and bindings) and then attached. + + Each PATH may be a directory (the file is <PATH>/sbxenv.yaml) or the + path to the environment file itself. Passing more than one PATH deep-merges them + in order (docker-compose `-f` semantics): later files override earlier ones. + Values may reference the arguments the file declares with ${{ env.args.NAME }}, + supplied by --env-arg, plus ${{ env.projectDir }} and ${{ env.fileDir }}. + Nothing else is expanded, so a "$" is literal text. + + A directory PATH selects sbxenv.yaml; a file PATH selects that file. + With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. + Explicit PATHs skip those defaults. Later files override earlier values; + lists such as ports and mcp.servers are concatenated. +usage: sbx env run [PATH...] [flags] +options: + - name: clone + default_value: "false" + usage: | + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') + - name: detach + shorthand: d + default_value: "false" + usage: Create/start the sandbox without attaching + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: force + shorthand: f + default_value: "false" + usage: Apply the environment plan without asking + - name: help + shorthand: h + default_value: "false" + usage: help for run + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: name + usage: | + Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one. + - name: skip-host-commands + default_value: "false" + usage: Skip the host lifecycle commands the environment declares + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx env run + + # Start without attaching + sbx env run --detach ./project +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_exec.yaml b/data/sbx_cli/sbx_exec.yaml index d060aad82f1f..c2f0809b4942 100644 --- a/data/sbx_cli/sbx_exec.yaml +++ b/data/sbx_cli/sbx_exec.yaml @@ -1,15 +1,19 @@ name: sbx exec synopsis: Execute a command inside a sandbox description: |- - Execute a command in a sandbox. If the sandbox is stopped, it is started first. + Execute a command in a sandbox. If the sandbox is stopped, it is started first. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". - Flags match the behavior of "docker exec". + Flags match the behavior of "docker exec", except detached exec (-d/--detach) + is not supported. Some flags (-d, --user, --privileged) + are not supported with --cloud and are rejected rather than silently ignored. + --detach-keys applies only to an interactive (-i/-t) cloud exec. usage: sbx exec [flags] SANDBOX COMMAND [ARG...] options: - name: detach shorthand: d default_value: "false" - usage: 'Detached mode: run command in the background' + usage: Detached mode (not supported) - name: detach-keys usage: Override the key sequence for detaching a container - name: env @@ -41,6 +45,10 @@ options: shorthand: w usage: Working directory inside the container inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -49,10 +57,11 @@ example: |4- # Open a shell inside a sandbox sbx exec -it my-sandbox bash - # Run a command in the background - sbx exec -d my-sandbox npm start - # Run as root sbx exec -u root my-sandbox apt-get update + + # Cloud: run a command in a cloud sandbox by ID or name + sbx --cloud exec -it sbx_abc123 bash + sbx --cloud exec -it claude/my-sandbox bash see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_kit.yaml b/data/sbx_cli/sbx_kit.yaml index ca3f96c345f2..78a7466acca0 100644 --- a/data/sbx_cli/sbx_kit.yaml +++ b/data/sbx_cli/sbx_kit.yaml @@ -4,8 +4,9 @@ experimental: true description: |- Manage kit artifacts. - Kits are declarative YAML artifacts that extend sandbox agents with additional - credentials, network policies, environment variables, startup commands, and files. + Kits are declarative YAML artifacts that define sandbox agents or extend them + with additional credentials, network policies, environment variables, startup + commands, and files. usage: sbx kit COMMAND options: - name: help @@ -13,15 +14,23 @@ options: default_value: "false" usage: help for kit inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. - - sbx kit add - Add a kit to a running sandbox - - sbx kit inspect - Display details about a kit artifact + - sbx kit add - Add a mixin to a sandbox + - sbx kit builder - Manage the kit builder sandbox + - sbx kit inspect - Show kit artifact details - sbx kit pack - Package a directory as a kit artifact + - sbx kit provenance - Show the SLSA provenance attached to a kit - sbx kit pull - Pull a kit artifact from an OCI registry - sbx kit push - Push a kit artifact to an OCI registry + - sbx kit sign - Sign a kit artifact - sbx kit validate - Validate a kit artifact + - sbx kit verify - Verify a kit artifact's signature diff --git a/data/sbx_cli/sbx_kit_add.yaml b/data/sbx_cli/sbx_kit_add.yaml index 21ff7a8205ad..4a300e367a2b 100644 --- a/data/sbx_cli/sbx_kit_add.yaml +++ b/data/sbx_cli/sbx_kit_add.yaml @@ -1,27 +1,48 @@ name: sbx kit add -synopsis: Add a kit to a running sandbox +synopsis: Add a mixin to a sandbox experimental: true description: |- - Inject a kit artifact into an already-running sandbox. + Add a mixin artifact to an existing sandbox. - The kit's files, init files, and startup commands are applied to the - running container. This allows extending a sandbox without recreating it. + The sandbox's container is recreated with the new kit appended to its + original kit list, preserving kit-owned volumes (e.g. agent session + state) across the swap. Workspace data is unaffected: bind-mounted + sandboxes keep their host-side mount; --clone sandboxes keep their + in-container working tree via a named workspace volume that + reattaches to the swap container. - The sandbox must already exist (created or running). The reference can be a local directory, - ZIP file path, OCI registry reference, or git repository. + The sandbox must already exist and must have been created with the + recreate-aware label set (sandboxes created before the kit-add recreate + feature shipped will be refused with a clear error). The reference can be + a local directory, ZIP file path, OCI registry reference, or git + repository. usage: sbx kit add SANDBOX REFERENCE [flags] options: - name: help shorthand: h default_value: "false" usage: help for add + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # Add a local kit directory to a sandbox + # Add a local mixin directory to a sandbox sbx kit add my-sandbox ./mcp-postgres/ # Add a kit from a ZIP file @@ -32,5 +53,8 @@ example: |4- # Add a kit from a git repository sbx kit add my-sandbox git+https://github.com/org/kits.git#dir=mcp-postgres + + # Add a parameterized kit + sbx kit add my-sandbox ./mcp-postgres/ --kit-arg host=db.internal see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_builder.yaml b/data/sbx_cli/sbx_kit_builder.yaml new file mode 100644 index 000000000000..3522f048b487 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder.yaml @@ -0,0 +1,31 @@ +name: sbx kit builder +synopsis: Manage the kit builder sandbox +experimental: true +description: |- + Manage the kit builder sandbox. + + Source-form kit builds (a local directory or git reference) run inside a + shared builder sandbox named sbx-kit-builder, created on first + use. Its Docker engine store doubles as the kit build cache, so removing + the builder is how the cache is reclaimed; the next source-form build + recreates it. +usage: sbx kit builder COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for builder +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx kit - (Experimental) Manage kit artifacts + - sbx kit builder history - Show kit build history in the builder sandbox + - sbx kit builder rm - Remove the kit builder sandbox and its build cache + - sbx kit builder status - Show the kit builder sandbox and build-cache state diff --git a/data/sbx_cli/sbx_kit_builder_history.yaml b/data/sbx_cli/sbx_kit_builder_history.yaml new file mode 100644 index 000000000000..5811b4fb0cd7 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history.yaml @@ -0,0 +1,32 @@ +name: sbx kit builder history +synopsis: Show kit build history in the builder sandbox +experimental: true +description: |- + Inspect kit build history in the builder sandbox. + + Each subcommand runs the matching docker buildx history command inside + the builder sandbox, against the buildx instance kit builds use. Flags + and arguments pass through verbatim. +usage: sbx kit builder history COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for history +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx kit builder - Manage the kit builder sandbox + - sbx kit builder history export - Export a kit build record into a bundle + - sbx kit builder history inspect - Show a kit build record + - sbx kit builder history logs - Show a kit build's logs + - sbx kit builder history ls - List kit build records + - sbx kit builder history rm - Remove kit build records + - sbx kit builder history trace - Show the execution trace of a kit build diff --git a/data/sbx_cli/sbx_kit_builder_history_export.yaml b/data/sbx_cli/sbx_kit_builder_history_export.yaml new file mode 100644 index 000000000000..2e42ae09db1e --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_export.yaml @@ -0,0 +1,21 @@ +name: sbx kit builder history export +synopsis: Export a kit build record into a bundle +experimental: true +usage: sbx kit builder history export [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for export +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx kit builder history export 3b6l9x --output build.dockerbuild' +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_history_inspect.yaml b/data/sbx_cli/sbx_kit_builder_history_inspect.yaml new file mode 100644 index 000000000000..f2b65ba659f2 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_inspect.yaml @@ -0,0 +1,26 @@ +name: sbx kit builder history inspect +synopsis: Show a kit build record +experimental: true +usage: sbx kit builder history inspect [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for inspect +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # The most recent build + sbx kit builder history inspect + + # One build by record reference + sbx kit builder history inspect 3b6l9x +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_history_logs.yaml b/data/sbx_cli/sbx_kit_builder_history_logs.yaml new file mode 100644 index 000000000000..1ee5ac5579b0 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_logs.yaml @@ -0,0 +1,23 @@ +name: sbx kit builder history logs +synopsis: Show a kit build's logs +experimental: true +usage: sbx kit builder history logs [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for logs +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx kit builder history logs + sbx kit builder history logs 3b6l9x +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_history_ls.yaml b/data/sbx_cli/sbx_kit_builder_history_ls.yaml new file mode 100644 index 000000000000..d3b6e86d5dc5 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_ls.yaml @@ -0,0 +1,21 @@ +name: sbx kit builder history ls +synopsis: List kit build records +experimental: true +usage: sbx kit builder history ls [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ls +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx kit builder history ls' +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_history_rm.yaml b/data/sbx_cli/sbx_kit_builder_history_rm.yaml new file mode 100644 index 000000000000..91be46bedd7c --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_rm.yaml @@ -0,0 +1,30 @@ +name: sbx kit builder history rm +synopsis: Remove kit build records +experimental: true +usage: sbx kit builder history rm [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for rm + - name: "yes" + shorthand: "y" + default_value: "false" + usage: | + Skip confirmation prompt (buildx --force still controls running build records) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx kit builder history rm 3b6l9x + + # Skip the confirmation prompt + sbx kit builder history rm --yes 3b6l9x +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_history_trace.yaml b/data/sbx_cli/sbx_kit_builder_history_trace.yaml new file mode 100644 index 000000000000..0d07b30ab2cb --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_history_trace.yaml @@ -0,0 +1,23 @@ +name: sbx kit builder history trace +synopsis: Show the execution trace of a kit build +experimental: true +usage: sbx kit builder history trace [ARGS...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for trace +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx kit builder history trace + sbx kit builder history trace 3b6l9x +see_also: + - sbx kit builder history - Show kit build history in the builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_rm.yaml b/data/sbx_cli/sbx_kit_builder_rm.yaml new file mode 100644 index 000000000000..1045dc07f01c --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_rm.yaml @@ -0,0 +1,29 @@ +name: sbx kit builder rm +synopsis: Remove the kit builder sandbox and its build cache +experimental: true +usage: sbx kit builder rm [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts and delete even if in use + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx kit builder rm + + # Skip the confirmation prompt + sbx kit builder rm --force +see_also: + - sbx kit builder - Manage the kit builder sandbox diff --git a/data/sbx_cli/sbx_kit_builder_status.yaml b/data/sbx_cli/sbx_kit_builder_status.yaml new file mode 100644 index 000000000000..f5d1d9b60ea1 --- /dev/null +++ b/data/sbx_cli/sbx_kit_builder_status.yaml @@ -0,0 +1,21 @@ +name: sbx kit builder status +synopsis: Show the kit builder sandbox and build-cache state +experimental: true +usage: sbx kit builder status [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for status +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx kit builder status' +see_also: + - sbx kit builder - Manage the kit builder sandbox diff --git a/data/sbx_cli/sbx_kit_inspect.yaml b/data/sbx_cli/sbx_kit_inspect.yaml index fd985cceafbc..b5728d9081fb 100644 --- a/data/sbx_cli/sbx_kit_inspect.yaml +++ b/data/sbx_cli/sbx_kit_inspect.yaml @@ -1,12 +1,22 @@ name: sbx kit inspect -synopsis: Display details about a kit artifact +synopsis: Show kit artifact details experimental: true description: |- Load and display details about a kit artifact. The reference can be a local directory, ZIP file path, OCI registry reference, or git repository. + + Pass --kit-arg to preview how the kit resolves with a given set of + arguments; the output shows the substituted content. + + --offline skips the daemon-backed kit policy (kit.allowedSources, + kit.allowLocalKits, kit.requireSignature) so the command needs neither + sandboxd nor a signed-in session; it only accepts a local directory or + ZIP reference, since those are the only ones this check applies to. usage: sbx kit inspect REFERENCE [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" @@ -14,10 +24,37 @@ options: - name: json default_value: "false" usage: Output in JSON format + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: offline + default_value: "false" + usage: | + Skip the daemon-backed kit policy check; local directory or ZIP references only inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx kit inspect ./my-kit + sbx kit inspect ghcr.io/myorg/my-kit:1.0 + + # Machine-readable output + sbx kit inspect ghcr.io/myorg/my-kit:1.0 --format json + + # Inspect without sandboxd running or a Docker sign-in + sbx kit inspect ./my-kit --offline see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_pack.yaml b/data/sbx_cli/sbx_kit_pack.yaml index 7c5d37569fdc..a24075cccf89 100644 --- a/data/sbx_cli/sbx_kit_pack.yaml +++ b/data/sbx_cli/sbx_kit_pack.yaml @@ -13,11 +13,20 @@ options: usage: help for pack - name: output shorthand: o - usage: 'Output ZIP file path (default: <name>.zip)' + usage: 'Output file path; must end in .zip (default: <name>.zip)' inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx kit pack ./my-kit + + # Choose the archive name + sbx kit pack ./my-kit --output dist/my-kit.zip see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_provenance.yaml b/data/sbx_cli/sbx_kit_provenance.yaml new file mode 100644 index 000000000000..8f3fbdbfbb3d --- /dev/null +++ b/data/sbx_cli/sbx_kit_provenance.yaml @@ -0,0 +1,62 @@ +name: sbx kit provenance +synopsis: Show the SLSA provenance attached to a kit +experimental: true +description: |- + Print the SLSA provenance attestation attached to an OCI kit. + + Provenance is attached by `sbx kit push` as an OCI referrer of the kit + manifest. It records the kit's content digests, the sandbox image its spec + declares, and the source git commit the kit was pushed from. + + Provenance pushed without --sign is unsigned: it is printed but marked + UNSIGNED, because anyone with push access to the repository could have + written it. To verify a signed attestation, pass --key for a key-based + signature, or --certificate-identity (or --certificate-identity-regexp) + together with --certificate-oidc-issuer (or its regexp form) for a keyless + one; only attestations that verify and whose subject matches the kit's own + digest are reported as VERIFIED. +usage: sbx kit provenance REFERENCE [flags] +options: + - name: certificate-identity + usage: Exact keyless signer identity (certificate SAN) + - name: certificate-identity-regexp + usage: Keyless signer identity regexp (certificate SAN) + - name: certificate-oidc-issuer + usage: Exact keyless OIDC issuer + - name: certificate-oidc-issuer-regexp + usage: Keyless OIDC issuer regexp + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for provenance + - name: insecure-ignore-tlog + default_value: "false" + usage: | + Do not require a Rekor transparency-log entry (for private keyless signatures) + - name: json + default_value: "false" + usage: Output in JSON format + - name: key + usage: Public key for key-based verification (PEM) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Show provenance (unsigned attestations are printed as-is) + sbx kit provenance ghcr.io/org/my-kit:1.0 + + # Verify a signed attestation before printing it + sbx kit provenance \ + --certificate-identity user@example.com \ + --certificate-oidc-issuer https://accounts.google.com \ + ghcr.io/org/my-kit:1.0 +see_also: + - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_pull.yaml b/data/sbx_cli/sbx_kit_pull.yaml index 1440d608a268..59c29cf9434c 100644 --- a/data/sbx_cli/sbx_kit_pull.yaml +++ b/data/sbx_cli/sbx_kit_pull.yaml @@ -2,18 +2,15 @@ name: sbx kit pull synopsis: Pull a kit artifact from an OCI registry experimental: true description: |- - Pull a kit artifact from an OCI registry and save its layer payload to a file. + Pull a kit artifact from an OCI registry and save its payload to a file. + Use a registry/repo:tag or registry/repo@sha256:digest reference. - The reference should be in the format "registry/repo:tag" or - "registry/repo@sha256:digest" (e.g., "ghcr.io/myorg/my-plugin:1.0"). - - The file extension is chosen automatically based on the kit's format: - schemaVersion: "1" → <name>.zip (legacy ZIP archive) - schemaVersion: "2" → <name>.tar.gz (standard OCI tar+gzip layer) + The output extension follows the resolved artifact format: .zip for v1, + or .tar.gz for v2. Use --output to choose the file path. + For Docker Hub, the sbx login session takes priority. Other registries use + secrets set with sbx secret set --registry. Both fall back to Docker credentials. The registry must support HTTPS. - - Authentication: sbx registry secrets (sbx secret set --registry) take priority, falling back to the Docker credential store. usage: sbx kit pull REFERENCE [flags] options: - name: help @@ -24,9 +21,18 @@ options: shorthand: o usage: 'Output file path (default: derived from reference + format)' inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx kit pull ghcr.io/myorg/my-kit:1.0 + + # Choose where to save the payload + sbx kit pull ghcr.io/myorg/my-kit:1.0 --output my-kit.tar.gz see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_push.yaml b/data/sbx_cli/sbx_kit_push.yaml index 3de9a8565a4e..973600b4d767 100644 --- a/data/sbx_cli/sbx_kit_push.yaml +++ b/data/sbx_cli/sbx_kit_push.yaml @@ -2,29 +2,51 @@ name: sbx kit push synopsis: Push a kit artifact to an OCI registry experimental: true description: |- - Package and push a kit artifact directory to an OCI registry. + Package a kit directory containing spec.yaml and push it to an OCI registry. + Use a registry/repo:tag reference. The kit's schema selects the artifact format. - The directory must contain a valid spec.yaml. The reference should be - in the format "registry/repo:tag" (e.g., "ghcr.io/myorg/my-plugin:1.0"). + Every push attaches provenance. Use --sign to also sign the manifest and + provenance; signing is keyless unless --key is supplied. - The OCI artifact format is selected from the kit's spec.yaml: - schemaVersion: "1" → legacy ZIP-based artifact - schemaVersion: "2" → v2 tar+gzip layer with the spec in the manifest - config blob and standard OCI annotations (so - distribution tooling can read kit metadata - without pulling layers) - - Authentication uses the Docker credential store. + For Docker Hub, the sbx login session takes priority. Other registries use + secrets set with sbx secret set --registry. Both fall back to Docker credentials. + The registry must support HTTPS. usage: sbx kit push DIRECTORY REFERENCE [flags] options: - name: help shorthand: h default_value: "false" usage: help for push + - name: identity-token + usage: | + OIDC identity token for keyless signing; defaults to the ambient CI provider, then an interactive browser login + - name: identity-token-file + usage: | + File holding the OIDC identity token; keeps it out of the process arguments + - name: key + usage: | + Private key for key-based signing (PEM); omit for keyless signing + - name: sign + default_value: "false" + usage: | + Sign the pushed kit and attach the signature as an OCI referrer + - name: tlog-upload + default_value: "true" + usage: | + Upload the keyless signature to the Rekor transparency log; set false for private kits inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx kit push ./my-kit ghcr.io/myorg/my-kit:1.0 + + # Sign the pushed kit (keyless) + sbx kit push ./my-kit ghcr.io/myorg/my-kit:1.0 --sign see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_sign.yaml b/data/sbx_cli/sbx_kit_sign.yaml new file mode 100644 index 000000000000..5a5c3f1569fa --- /dev/null +++ b/data/sbx_cli/sbx_kit_sign.yaml @@ -0,0 +1,66 @@ +name: sbx kit sign +synopsis: Sign a kit artifact +experimental: true +description: |- + Sign a kit artifact with cosign-compatible Sigstore signatures. + + For a local directory, a detached signature bundle is written to + kit.sig.bundle next to spec.yaml. For an OCI reference, the + signature is attached to the kit manifest as an OCI referrer. + + Signing is keyless by default (Fulcio + Rekor), which requires an OIDC + identity token. In CI the token is minted automatically by the detected + platform (GitHub Actions, Buildkite, GCP, SPIFFE, or a projected + service-account token on disk). Elsewhere, supply one with + --identity-token-file or --identity-token, or complete an interactive + browser login. Prefer the file form: process arguments are readable by + other local users and are recorded in shell history. A token is never + read from SIGSTORE_ID_TOKEN, so it cannot be chosen by anything that can + set an environment variable. Use --key for key-based signing with an + unencrypted PEM private key. + + For private kits whose signing event must not leak to a public log, pass + --tlog-upload=false to skip the Rekor transparency log. This only affects + keyless signing (key-based signing never uploads to Rekor) and requires + the signing config to provide a timestamp authority so the signature stays + verifiable after the short-lived certificate expires. For fully offline, + private signing, prefer key-based signing with --key. +usage: sbx kit sign REFERENCE [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for sign + - name: identity-token + usage: | + OIDC identity token for keyless signing; defaults to the ambient CI provider, then an interactive browser login + - name: identity-token-file + usage: | + File holding the OIDC identity token; keeps it out of the process arguments + - name: key + usage: | + Private key for key-based signing (PEM); omit for keyless signing + - name: tlog-upload + default_value: "true" + usage: | + Upload the keyless signature to the Rekor transparency log; set false for private kits +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Keyless-sign a local kit directory + sbx kit sign ./my-kit/ + + # Key-based sign an OCI kit + sbx kit sign --key cosign.key ghcr.io/org/my-kit:1.0 + + # Keyless-sign without uploading to the public transparency log + sbx kit sign --tlog-upload=false ghcr.io/org/private-kit:1.0 +see_also: + - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_validate.yaml b/data/sbx_cli/sbx_kit_validate.yaml index f11453753d1f..034fabe05a52 100644 --- a/data/sbx_cli/sbx_kit_validate.yaml +++ b/data/sbx_cli/sbx_kit_validate.yaml @@ -5,16 +5,57 @@ description: |- Validate that a directory or ZIP file is a valid kit artifact. The reference can be a local directory, ZIP file path, or git repository. + + A kit that declares required arguments is invalid until they are + supplied, so pass the same --kit-arg values you would pass to sbx + create. + + --offline skips the daemon-backed kit policy (kit.allowedSources, + kit.allowLocalKits, kit.requireSignature) so the command needs neither + sandboxd nor a signed-in session; it only accepts a local directory or + ZIP reference, since those are the only ones this check applies to. usage: sbx kit validate REFERENCE [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for validate + - name: json + default_value: "false" + usage: Output in JSON format + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: offline + default_value: "false" + usage: | + Skip the daemon-backed kit policy check; local directory or ZIP references only inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx kit validate ./my-kit + sbx kit validate ./my-kit.zip + + # Supply the arguments a kit declares + sbx kit validate ./my-kit --kit-arg region=eu + + # Validate without sandboxd running or a Docker sign-in + sbx kit validate ./my-kit --offline see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_verify.yaml b/data/sbx_cli/sbx_kit_verify.yaml new file mode 100644 index 000000000000..d1f1680a46e5 --- /dev/null +++ b/data/sbx_cli/sbx_kit_verify.yaml @@ -0,0 +1,66 @@ +name: sbx kit verify +synopsis: Verify a kit artifact's signature +experimental: true +description: |- + Verify a kit artifact's cosign-compatible signature. + + For a local directory, the kit.sig.bundle sidecar is checked + against the kit's content. For a git reference, the repository is cloned and + its committed kit.sig.bundle sidecar is checked the same way. + For an OCI reference, signatures attached as OCI referrers are checked against + the kit manifest. + + Use --key to verify a key-based signature against a PEM public key. For + keyless signatures, supply the accepted signer identity with + --certificate-identity (or --certificate-identity-regexp) and + --certificate-oidc-issuer (or --certificate-oidc-issuer-regexp). + + Pass --insecure-ignore-tlog to verify a private keyless signature made + with --tlog-upload=false: it drops the requirement for a Rekor + transparency-log entry and relies on the timestamp-authority timestamp + instead. It has no effect on key-based verification. +usage: sbx kit verify REFERENCE [flags] +options: + - name: certificate-identity + usage: Exact keyless signer identity (certificate SAN) + - name: certificate-identity-regexp + usage: Keyless signer identity regexp (certificate SAN) + - name: certificate-oidc-issuer + usage: Exact keyless OIDC issuer + - name: certificate-oidc-issuer-regexp + usage: Keyless OIDC issuer regexp + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for verify + - name: insecure-ignore-tlog + default_value: "false" + usage: | + Do not require a Rekor transparency-log entry (for private keyless signatures) + - name: json + default_value: "false" + usage: Output in JSON format + - name: key + usage: Public key for key-based verification (PEM) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Verify a key-based signature + sbx kit verify --key cosign.pub ghcr.io/org/my-kit:1.0 + + # Verify a keyless signature by identity + sbx kit verify \ + --certificate-identity user@example.com \ + --certificate-oidc-issuer https://accounts.google.com \ + ./my-kit/ +see_also: + - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_login.yaml b/data/sbx_cli/sbx_login.yaml index 4c3c996e03a8..1269ad0d1ed5 100644 --- a/data/sbx_cli/sbx_login.yaml +++ b/data/sbx_cli/sbx_login.yaml @@ -12,9 +12,18 @@ options: - name: username usage: Docker username for non-interactive login inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx login + + # Non-interactive sign-in, for CI + echo "$DOCKER_PAT" | sbx login --username me --password-stdin see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_logout.yaml b/data/sbx_cli/sbx_logout.yaml index aaba60ee737b..9af95f3148ce 100644 --- a/data/sbx_cli/sbx_logout.yaml +++ b/data/sbx_cli/sbx_logout.yaml @@ -1,19 +1,28 @@ name: sbx logout -synopsis: Stop all running sandboxes and sign out of Docker +synopsis: Stop running local sandboxes and sign out of Docker usage: sbx logout [flags] options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompt - name: help shorthand: h default_value: "false" usage: help for logout - - name: "yes" - shorthand: "y" - default_value: "false" - usage: Skip confirmation prompt inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx logout + + # Skip the confirmation prompt + sbx logout --force see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_ls.yaml b/data/sbx_cli/sbx_ls.yaml index 51f664b2744f..1be4d5654e1d 100644 --- a/data/sbx_cli/sbx_ls.yaml +++ b/data/sbx_cli/sbx_ls.yaml @@ -4,6 +4,8 @@ description: | List all sandboxes with their agent, status, published ports, and workspace. usage: sbx ls [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" @@ -16,9 +18,21 @@ options: default_value: "false" usage: Only display sandbox names inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx ls + + # Names only, for scripting + sbx ls -q + + # Machine-readable output + sbx ls --format json see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_mcp.yaml b/data/sbx_cli/sbx_mcp.yaml new file mode 100644 index 000000000000..ba01b1da79b6 --- /dev/null +++ b/data/sbx_cli/sbx_mcp.yaml @@ -0,0 +1,28 @@ +name: sbx mcp +synopsis: Manage MCP servers +description: | + Register and manage MCP servers for use with sandbox sessions. +usage: sbx mcp COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for mcp +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx mcp add - Register an MCP server + - sbx mcp auth - Authorize MCP servers + - sbx mcp inspect - Show MCP server details + - sbx mcp load - Load an already-registered MCP server into a sandbox + - sbx mcp ls - List MCP servers + - sbx mcp rm - Remove a registered MCP server + - sbx mcp unload - Unload an MCP server from a running sandbox diff --git a/data/sbx_cli/sbx_mcp_add.yaml b/data/sbx_cli/sbx_mcp_add.yaml new file mode 100644 index 000000000000..92b3d1352c68 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_add.yaml @@ -0,0 +1,146 @@ +name: sbx mcp add +synopsis: Register an MCP server +description: |- + Register an MCP server for use with sbx create/run --static-mcp. + To attach a registered server to a running sandbox, use sbx mcp load. + + Use --url for a remote MCP endpoint, a community-registry or server-manifest + URL, or a Docker Hardened Image reference. Other image references are unsupported. + Use --command for a local stdio server. Local servers run on the host with your + full permissions; use only trusted executables. + + OAuth metadata is discovered automatically for remote endpoints. Use --client-id + for a pre-registered client, or --oauth-authorization-server when the server + publishes no discovery metadata. Confidential clients need a secret stored as + mcp:NAME:client_secret; use sbx secret set without -t to read it from stdin. + + Use --header for custom headers on remote endpoints. Header values can reference + stored secrets; see the examples below. Header secrets come from this host's + secret store and require a locally connected server. + + For registration and authorization workflows, see: + https://docs.docker.com/ai/sandboxes/mcp-gateway/ +usage: sbx mcp add NAME (--url URL | --command COMMAND) [flags] +options: + - name: args + default_value: '[]' + usage: Command-line arguments for the command + - name: callback-port + default_value: "0" + usage: | + Local port to bind the OAuth callback listener to during add-time authorization (default: OS-assigned ephemeral port). Useful when the port must be pre-registered in an OAuth app's allowed redirect URIs. Applies to --url remote OAuth servers; ignored with a warning if the server turns out not to need OAuth. + - name: client-id + usage: | + OAuth client id for a pre-registered client (with --url; may be used with or without --oauth-authorization-server). A confidential client's secret comes from 'sbx secret set mcp:<server>:client_secret' + - name: command + usage: Executable to run for a local stdio server + - name: dir + usage: Working directory (cwd) for a --command host server + - name: disable-http2 + default_value: "false" + usage: | + Do not negotiate HTTP/2 for this remote server, leaving HTTP/1.1. Applies to --url servers. + - name: header + default_value: '[]' + usage: | + Custom HTTP header to send to a remote --url endpoint, in curl form 'Name: value' (repeatable). A ${placeholder} in the value is substituted at connect time from 'sbx secret set mcp:<server>:<placeholder>' + - name: help + shorthand: h + default_value: "false" + usage: help for add + - name: local + default_value: "false" + usage: Run registry OCI server locally via docker run + - name: no-scope + default_value: "false" + usage: | + Request no scopes during add-time authorization, so the authorization server applies its own default grant. Suppresses required and OIDC fallback scopes; cannot be combined with --scope. Applies to --url remote OAuth servers. + - name: oauth-authorization-server + usage: | + Path or http(s) URL to an RFC 8414 oauth-authorization-server metadata JSON document + - name: resource + usage: | + RFC 8707 resource indicator to send during OAuth: an absolute URI (scheme and host, no fragment) naming the server the token is for. Overrides the value the server publishes in its RFC 9728 metadata and the one derived from --url; set it only when that derived value is wrong. Not honoured by the hosted gateway for a plain remote yet. Applies to --url remote OAuth servers. + - name: scope + default_value: '[]' + usage: | + Default OAuth scope to request at consent time (repeatable; a scope the server's advertised metadata does not recognize prints a warning but is still requested, since advertising a scope never promised the server would grant it either). With no --scope, the scope set the resource itself requires is requested; with neither, whichever of openid, email, profile, and offline_access are advertised are requested; other advertised scopes are excluded from this fallback. Applies to --url remote OAuth servers. + - name: skip-auth + default_value: "false" + usage: | + Register an OAuth server without starting the hosted OAuth flow + - name: skip-ssrf-check + default_value: "false" + usage: | + Skip SSRF checks for this add, including OAuth authorization-server metadata and redirects (operator asserts the provider is trusted) + - name: url + usage: | + MCP server manifest URL, remote endpoint URL, or dhi.io image ref +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Remote MCP endpoint (OAuth auto-detected) + sbx mcp add notion --url https://mcp.notion.com/mcp + sbx mcp add linear --url https://mcp.linear.app/mcp + + # MCP community-registry URL + sbx mcp add fetch --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest + + # Plain server-manifest URL (server.json / server.yaml) + sbx mcp add opine --url https://example.com/mcp/opine/server.yaml + + # Docker Hardened Image (manifest is extracted from the image attestation) + sbx mcp add fetch --url dhi.io/fetch-mcp:latest + + # Registry URL, local mode (runs on host via docker run; stdio packages only) + sbx mcp add fetch --local --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest + + # Private-network endpoint (host resolves to a private address) — opt out of the SSRF guard + sbx mcp add internal --url https://private.example.com/mcp --skip-ssrf-check + + # Remote endpoint with a hand-supplied OAuth override (server publishes no + # well-known OAuth metadata): --oauth-authorization-server is a path or + # http(s) URL to an RFC 8414 metadata document, --client-id the OAuth client id + sbx mcp add acme --url https://mcp.acme.com/mcp --oauth-authorization-server ./acme-as.json --client-id my-client + + # Pre-registered client on a DISCOVERABLE server that has no registration + # endpoint — no --oauth-authorization-server needed (metadata is discovered) + sbx mcp add slack --url https://slack.example.com/mcp --client-id my-preregistered-client + + # Confidential client — store the secret first (prompted, never in argv or + # shell history), then register; the secret is read from the secret store + sbx secret set mcp:slack:client_secret + sbx mcp add slack --url https://slack.example.com/mcp --client-id my-preregistered-client + + # Record default OAuth scopes to request at consent time (a scope the + # server's authorization metadata does not advertise warns but is still + # requested; repeat --scope for each one) + sbx mcp add acme --url https://mcp.acme.com/mcp --scope read --scope write + + # URN- and URL-shaped scope values are ordinary scopes and need no quoting + sbx mcp add fastmail --url https://api.fastmail.com/mcp --scope https://www.fastmail.com/dev/mcp --scope offline_access + + # Correct the RFC 8707 'resource' indicator when the derived one is wrong (a + # server whose published identifier is not its endpoint URL) + sbx mcp add acme --url https://mcp.acme.com/mcp --resource https://api.acme.com/mcp + + # Remote endpoint with custom headers (curl convention; repeatable). The + # ${api-key} value is read from the secret store when a sandbox connects + sbx mcp add acme --url https://mcp.acme.com/mcp --header 'Authorization: Bearer ${api-key}' --header 'Accept: application/json, text/event-stream' + sbx secret set mcp:acme:api-key + + # Local stdio command (runs on host — development only) + sbx mcp add github --command npx --args @modelcontextprotocol/server-github + sbx mcp add postgres --command docker --args "run,-i,--rm,mcp/postgres" + + # Local stdio command with a working directory (cwd) for the host process + sbx mcp add local-fs --command node --args server.js --dir /srv/data +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_auth.yaml b/data/sbx_cli/sbx_mcp_auth.yaml new file mode 100644 index 000000000000..62a2d48f80e8 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_auth.yaml @@ -0,0 +1,98 @@ +name: sbx mcp auth +synopsis: Authorize MCP servers +description: |- + Authorize registered remote MCP servers through the hosted MCP control plane. + + Commands use the Docker Hub account from 'sbx login' as the request principal. + User and tenant identity are derived by the control plane; they are not sent in + the request body. + + Running 'sbx mcp auth <server>' authorizes or reauthorizes one server. If the + stored credential is expired, sbx asks the control plane to refresh it first and + only falls back to interactive OAuth when refresh needs user consent. + + Use 'sbx mcp auth status' to inspect hosted credential status without starting + OAuth, and 'sbx mcp auth rm' to remove hosted credentials without removing + local MCP server registrations. + + Pass --scope (repeatable) to authorize a specific set of scopes for this run, + overriding the default recorded at 'sbx mcp add' time. Precedence is --no-scope > + an explicit --scope > the recorded default > the scope set the RESOURCE says it + requires (from its RFC 9728 metadata or its WWW-Authenticate challenge) > whichever + of openid, email, profile, and offline_access are advertised. Other advertised + scopes are excluded from this fallback. If no scopes are selected, the scope + parameter is omitted so the authorization server can apply its own default grant. + + A resource that publishes a required set therefore gets it requested without any + flag, and the consent block marks that set as derived rather than chosen. Pass + --no-scope to suppress all scope fallbacks and request the server's default grant. + + When using recorded defaults or resource scopes, sbx also requests offline_access + if the authorization server advertises it, allowing refresh tokens. An explicit + --scope on this command requests exactly that set, without adding offline_access. + + Scopes you choose are checked against both the authorization server's RFC 8414 + scopes_supported and the resource's RFC 9728 metadata. A scope present in neither + prints a warning but is still requested. If neither document publishes scopes, + the request is accepted as given. + Membership is not a promise: scopes_supported is what the server SUPPORTS, not + what it will grant this client, so an advertised scope can still be refused at + consent time. In local data-plane mode a refusal prints the requested set, the + advertised set, the scopes the server named, and a narrower retry command; the + hosted control plane reports only that authorization failed or timed out. + + For an existing or freshly completed authorization, the GRANTED set — what the + authorization server actually handed over — is reported alongside the status. An + authorization server may grant less than was asked for; when it restates no set + at all, RFC 6749 §5.1 makes that the set that was requested. + + Scope values may be URN-shaped (urn:ietf:params:oauth:scope:mail) or URL-shaped + (https://www.fastmail.com/dev/mcp); neither needs quoting. +usage: sbx mcp auth [SERVER] [flags] +options: + - name: all + default_value: "false" + usage: Apply to all registered OAuth servers + - name: format + default_value: text + usage: 'Output format: "text" or "json"' + - name: help + shorthand: h + default_value: "false" + usage: help for auth + - name: json + default_value: "false" + usage: Output in JSON format + - name: no-scope + default_value: "false" + usage: | + Request no scopes at all for this run, so the authorization server applies its own default grant. Suppresses recorded, required, and OIDC fallback scopes; cannot be combined with --scope + - name: scope + default_value: '[]' + usage: | + OAuth scope to authorize for this run (repeatable; overrides the recorded default; unrecognized scopes warn but are still requested). With no --scope and no recorded default, the scope set the resource itself requires is requested; with none of those, whichever of openid, email, profile, and offline_access are advertised are requested; other advertised scopes are excluded from this fallback + - name: verbose + default_value: "false" + usage: Print authorization polling progress +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx mcp auth status --all + sbx mcp auth status notion + sbx mcp auth rm --all + sbx mcp auth rm notion + sbx mcp auth --all + sbx mcp auth notion + sbx mcp auth notion --scope read --scope write + sbx mcp auth notion --no-scope +see_also: + - sbx mcp - Manage MCP servers + - sbx mcp auth rm - Remove MCP server OAuth credentials + - sbx mcp auth status - Show MCP server OAuth status diff --git a/data/sbx_cli/sbx_mcp_auth_rm.yaml b/data/sbx_cli/sbx_mcp_auth_rm.yaml new file mode 100644 index 000000000000..6567a8d3a50c --- /dev/null +++ b/data/sbx_cli/sbx_mcp_auth_rm.yaml @@ -0,0 +1,41 @@ +name: sbx mcp auth rm +synopsis: Remove MCP server OAuth credentials +description: |- + Remove hosted OAuth credentials for registered MCP servers. + + This command does not remove local MCP server registrations. Use 'sbx mcp rm' + to remove a registration. +usage: sbx mcp auth rm [SERVER] [flags] +options: + - name: all + default_value: "false" + usage: Apply to all registered OAuth servers + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: format + default_value: text + usage: 'Output format: "text" or "json"' + - name: help + shorthand: h + default_value: "false" + usage: help for rm + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx mcp auth rm --all + sbx mcp auth rm notion + sbx mcp auth rm notion --format=json +see_also: + - sbx mcp auth - Authorize MCP servers diff --git a/data/sbx_cli/sbx_mcp_auth_status.yaml b/data/sbx_cli/sbx_mcp_auth_status.yaml new file mode 100644 index 000000000000..7718e45e96d9 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_auth_status.yaml @@ -0,0 +1,36 @@ +name: sbx mcp auth status +synopsis: Show MCP server OAuth status +description: |- + Show hosted OAuth credential status for registered MCP servers. + + This command does not start OAuth or refresh expired credentials. +usage: sbx mcp auth status [SERVER] [flags] +options: + - name: all + default_value: "false" + usage: Apply to all registered OAuth servers + - name: format + default_value: text + usage: 'Output format: "text" or "json"' + - name: help + shorthand: h + default_value: "false" + usage: help for status + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx mcp auth status --all + sbx mcp auth status notion + sbx mcp auth status --all --format=json +see_also: + - sbx mcp auth - Authorize MCP servers diff --git a/data/sbx_cli/sbx_mcp_inspect.yaml b/data/sbx_cli/sbx_mcp_inspect.yaml new file mode 100644 index 000000000000..b41c704a4dd2 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_inspect.yaml @@ -0,0 +1,29 @@ +name: sbx mcp inspect +synopsis: Show MCP server details +usage: sbx mcp inspect NAME [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx mcp inspect notion + + # Machine-readable output for scripting + sbx mcp inspect notion --json +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_load.yaml b/data/sbx_cli/sbx_mcp_load.yaml new file mode 100644 index 000000000000..cae021dcf268 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_load.yaml @@ -0,0 +1,47 @@ +name: sbx mcp load +synopsis: Load an already-registered MCP server into a sandbox +description: |- + Attach a previously-registered MCP server to a sandbox's gateway. + In a running sandbox, connected agents see the new server's tools immediately + via the standard MCP tools/list_changed notification — no agent restart + required. A stopped sandbox gets the server the next time it starts. + + The server must already exist in the local MCP store (register first with + 'sbx mcp add'). Both remote/hosted and local-stdio servers are supported. + + With --cloud: + Load an MCP server into a running cloud sandbox's gateway. + + There is no local registration: the cloud gateway resolves the server name + itself, and the sandbox may be given by name or sbx_ ID. Connected agents see + the new server's tools immediately. +usage: sbx mcp load NAME --sandbox SANDBOX [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for load + - name: sandbox + usage: Target sandbox name (required) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Register, then load into the running sandbox 'my-sbx'. + sbx mcp add notion --url https://mcp.notion.com/mcp + sbx mcp load notion --sandbox my-sbx + + # Local stdio server. + sbx mcp add github --command npx --args @modelcontextprotocol/server-github + sbx mcp load github --sandbox my-sbx + + # Cloud: load a gateway-known server into a cloud sandbox by name or ID + sbx --cloud mcp load notion --sandbox my-sbx +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_ls.yaml b/data/sbx_cli/sbx_mcp_ls.yaml new file mode 100644 index 000000000000..73df4c3e8afb --- /dev/null +++ b/data/sbx_cli/sbx_mcp_ls.yaml @@ -0,0 +1,63 @@ +name: sbx mcp ls +synopsis: List MCP servers +description: |- + List registered MCP servers under the gateway that serves them. + + The GATEWAY column reports where each server runs, who controls it, and the + signed-in identity; each row also reports its transport and whether it is usable now. + Servers needing authorization carry the 'sbx mcp auth' next step. + + A server registered with custom headers is marked as such; one whose header + placeholder has no stored value carries the 'sbx secret set' next step, and one + whose headers this gateway cannot send is flagged unsupported. Either way the + server cannot connect as it stands. Run 'sbx mcp inspect <name>' for the headers + themselves and the state of each placeholder. + + Auth status is read without starting an OAuth flow — from the local token store + in local data-plane mode, otherwise from the hosted control plane. + + With --cloud: + List MCP servers reported by existing cloud sandbox gateways, with the + sandboxes that reference each server. Servers skipped by a gateway are excluded. + This is not a complete inventory of configured servers: unused configurations + and gateways that do not report server names are absent, including with --quiet. + + Specify a sandbox to show its gateway state and host, requested servers, and + skipped servers. +usage: sbx mcp ls [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display MCP server names +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx mcp ls + + # Machine-readable output for scripting + sbx mcp ls --json + + # Cloud: list servers reported across existing sandboxes + sbx --cloud mcp ls + + # Cloud: show a cloud sandbox's gateway by name or sbx_ ID + sbx --cloud mcp ls my-sbx +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_rm.yaml b/data/sbx_cli/sbx_mcp_rm.yaml new file mode 100644 index 000000000000..c0b76ed0ce0a --- /dev/null +++ b/data/sbx_cli/sbx_mcp_rm.yaml @@ -0,0 +1,24 @@ +name: sbx mcp rm +synopsis: Remove a registered MCP server +usage: sbx mcp rm NAME [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx mcp rm notion' +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_unload.yaml b/data/sbx_cli/sbx_mcp_unload.yaml new file mode 100644 index 000000000000..ea8c30179699 --- /dev/null +++ b/data/sbx_cli/sbx_mcp_unload.yaml @@ -0,0 +1,32 @@ +name: sbx mcp unload +synopsis: Unload an MCP server from a running sandbox +description: |- + Detach an MCP server from a running sandbox's gateway. + Connected agents stop seeing the server's tools immediately via the standard + MCP tools/list_changed notification — no agent restart required. The server + is not restored when the sandbox is restarted. + + The server stays registered in the local MCP store; load it again with + 'sbx mcp load', or remove the registration with 'sbx mcp rm'. +usage: sbx mcp unload NAME --sandbox SANDBOX [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for unload + - name: sandbox + usage: Target sandbox name (required) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Unload the 'notion' server from the running sandbox 'my-sbx'. + sbx mcp unload notion --sandbox my-sbx +see_also: + - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_move.yaml b/data/sbx_cli/sbx_move.yaml new file mode 100644 index 000000000000..93e8578b81f3 --- /dev/null +++ b/data/sbx_cli/sbx_move.yaml @@ -0,0 +1,105 @@ +name: sbx move +synopsis: Move a sandbox between local and cloud +description: |- + Move a sandbox between the local host and Docker's hosted Sandboxes service. + + Move captures the sandbox's filesystem as a container image and starts a new + sandbox from it on the destination. Running processes and in-memory state do + not travel. The destination sandbox gets a new ID; name it with --name. + + Neither direction deletes the source. Moving to cloud stops the local + sandbox; restart it with 'sbx run --name <name>'. Moving to local asks the + cloud source to stop; a refused or unconfirmed stop warns without failing + the move, and the stop may still be finishing when the move returns. + 'sbx --cloud ls' shows it. A cloud sandbox with no agent is left running. + A stopped cloud source keeps its ID and state: 'sbx --cloud run <id>' + resumes it, 'sbx --cloud rm <id>' deletes it. + + A failed or cancelled move restores what it can. It restarts a local source + that was running and removes the transfer templates it created. The restart + re-runs the entrypoint; processes you started by hand are not revived. If a + cleanup step fails, the output names what is left and the command that + recovers it. + + What does not travel: + - The workspace bind mount and other host mounts. Files moved to local + stay inside the sandbox at the image's working directory; copy them out + with 'sbx cp'. + - Secrets managed by sbx. The destination picks its own secrets, so + you may need to sign in again. Credentials saved in copied files + still travel. + - Volumes and environment variables attached to a cloud sandbox, when + moving to local. A local sandbox's environment is part of its image + and travels to the cloud. + - Network rules you added locally. The sandbox's kit network rules do + travel: moving to cloud applies them, as 'sbx create --cloud' does. If + the kit can't be resolved, move warns and the account's cloud policy + applies. Moving to local starts with the host's default policy. Active + local L7 (HTTP) rules prompt before a move to cloud; --force skips the + prompt but keeps the warning. + - Cloud URLs and host port bindings. Moving to cloud republishes TCP + ports under new cloud URLs; a port the cloud refuses is skipped with a + warning. Moving to local saves the published TCP ports and binds them + on loopback while the sandbox runs. Host ports can change on restart; + 'sbx ports SANDBOX' shows them. A cloud port published with an + explicit host binding stops a move to local. + + Sizing and disk: + - Moving to cloud rounds recorded CPU and memory limits up to a cloud + shape. Missing limits use cloud defaults with a warning. Limits above + the largest shape stop the move before anything is captured. Moving to + local uses local defaults. + - Moving to local stages downloaded layers in the host's temporary + directory. Reusing local layers can take up to 32 GiB in addition to + the local runtime's image storage. If reuse fails, the layers are + downloaded. If staging runs out of space, the move falls back to the + export stream. + + The cloud sandbox a move creates expires. The default is the server's TTL, + typically 1h: stopped in place on expiry when the account and sandbox + support it, deleted otherwise. Choose with --ttl and --on-timeout; + '--on-timeout restart' keeps the destination running instead of expiring. + Extend later with 'sbx --cloud ttl'. +usage: sbx move SANDBOX [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip the move confirmation prompt + - name: help + shorthand: h + default_value: "false" + usage: help for move + - name: name + usage: | + Name for the destination sandbox (default: 'moved-' + the source name; a cloud destination always adds a short unique suffix, a local one only when that name is already taken) + - name: on-timeout + usage: | + What happens to the destination cloud sandbox when its TTL lapses: 'stop' stops it in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Not every sandbox supports 'stop', and an explicit request the server refuses fails the move after the source has been stopped and uploaded, so the sandbox is restored but the transfer is spent. With 'restart' a supplied --ttl must be at least 1h. Default: stop when the sandbox supports it, else the server default (delete). Only with --to cloud + - name: to + usage: | + Destination of the move: 'local' (cloud to local) or 'cloud' (local to cloud) + - name: ttl + default_value: 0s + usage: | + Time-to-live for the destination cloud sandbox (15s to 24h, e.g. 30m, 2h; only with --to cloud; default: server-side) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Move a cloud sandbox down to the local host + sbx move sbx_abc123 --to local + + # Move a local sandbox up to the cloud + sbx move my-sandbox --to cloud + + # Give the destination sandbox a custom name + sbx move sbx_abc123 --to local --name big-refactor +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_policy.yaml b/data/sbx_cli/sbx_policy.yaml index 10a30d5152ac..a6a76d1a6fa9 100644 --- a/data/sbx_cli/sbx_policy.yaml +++ b/data/sbx_cli/sbx_policy.yaml @@ -13,6 +13,10 @@ options: default_value: "false" usage: help for policy inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -20,9 +24,12 @@ inherited_options: see_also: - sbx - Manage AI coding agent sandboxes. - sbx policy allow - Add an allow rule for sandboxes + - sbx policy check - Check whether policy allows an access request - sbx policy deny - Add a deny rule for sandboxes + - sbx policy init - Initialize the global network policy + - sbx policy inspect - Show policy or rule details - sbx policy log - Show sandbox policy logs - - sbx policy ls - List sandbox policy rules + - sbx policy ls - List sandbox policies + - sbx policy refresh - Force an immediate policy refresh - sbx policy reset - Reset policies to defaults - sbx policy rm - Remove a policy rule - - sbx policy set-default - Set the default network policy diff --git a/data/sbx_cli/sbx_policy_allow.yaml b/data/sbx_cli/sbx_policy_allow.yaml index bab387669886..a28c0aa4cc80 100644 --- a/data/sbx_cli/sbx_policy_allow.yaml +++ b/data/sbx_cli/sbx_policy_allow.yaml @@ -13,6 +13,10 @@ options: default_value: "false" usage: help for allow inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_allow_network.yaml b/data/sbx_cli/sbx_policy_allow_network.yaml index 1aa59f7010a4..bf6af7e762a4 100644 --- a/data/sbx_cli/sbx_policy_allow_network.yaml +++ b/data/sbx_cli/sbx_policy_allow_network.yaml @@ -3,9 +3,16 @@ synopsis: Allow network access to specified hosts description: |- Allow sandbox network access to the specified hosts. - RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. - Supports exact domains (example.com), wildcard subdomains (*.example.com), - and optional port suffixes (example.com:443). Use "**" to allow all hosts. + RESOURCES is a comma-separated list of hostnames, domains, IP addresses, or + CIDR prefixes. Rules apply to TCP by default; use --protocol to select UDP or + both transports. Supports exact domains (example.com), wildcard subdomains + (*.example.com), multi-label wildcards (**.example.com), single-character + globs (api?.example.com), character classes (api[12].example.com, + api[!1].example.com), and optional port suffixes (example.com:443). An IPv6 + address takes a port in brackets ([2001:db8::1]:443) or a CIDR prefix + (2001:db8::1/128); a bare one is refused. Use "**" to allow all hosts. A bare + "*", an escaped glob character such as "\*", and any other pattern outside + these forms are rejected rather than stored as a rule that matches nothing. The rule applies globally to all sandboxes by default. Use --sandbox to add the rule to policy "local" scoped to a single sandbox instead. @@ -15,10 +22,17 @@ options: shorthand: h default_value: "false" usage: help for network + - name: protocol + usage: | + Network protocol: tcp or udp; repeat or comma-separate for both - name: sandbox usage: | Scope the rule to a specific sandbox (default: all sandboxes) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -36,7 +50,7 @@ example: |4- # Allow all subdomains of a host sbx policy allow network "*.npmjs.org" - # Allow all outbound traffic - sbx policy allow network "**" + # Allow all outbound traffic on both transports + sbx policy allow network --protocol tcp,udp "**" see_also: - sbx policy allow - Add an allow rule for sandboxes diff --git a/data/sbx_cli/sbx_policy_check.yaml b/data/sbx_cli/sbx_policy_check.yaml new file mode 100644 index 000000000000..186da045c314 --- /dev/null +++ b/data/sbx_cli/sbx_policy_check.yaml @@ -0,0 +1,25 @@ +name: sbx policy check +synopsis: Check whether policy allows an access request +description: |- + Check whether the current sandbox policy would authorize an access request. + + The check is read-only and evaluates the same daemon-side policy authorizer + used by sandbox network enforcement. +usage: sbx policy check COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for check +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx policy - Manage sandbox policies + - sbx policy check network - Check network access to a host diff --git a/data/sbx_cli/sbx_policy_check_network.yaml b/data/sbx_cli/sbx_policy_check_network.yaml new file mode 100644 index 000000000000..f3fc7a353895 --- /dev/null +++ b/data/sbx_cli/sbx_policy_check_network.yaml @@ -0,0 +1,47 @@ +name: sbx policy check network +synopsis: Check network access to a host +description: |- + Check whether current policy allows network access to TARGET. + + TARGET may be a hostname, host:port, IP literal, or URL. Bare hosts and IP + literals are evaluated with port 443. HTTP(S) URLs use their default ports; + other URL schemes must include an explicit port. URLs supply only their host + and port: this command evaluates network authorization, not HTTP method or path. +usage: sbx policy check network [--sandbox SANDBOX] TARGET [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for network + - name: json + default_value: "false" + usage: Output in JSON format + - name: protocol + usage: 'Network protocol to evaluate: tcp or udp' + - name: sandbox + usage: Evaluate in a specific sandbox policy context + - name: verbose + default_value: "false" + usage: Show the exact policy request fields +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Check global network policy + sbx policy check network api.example.com + + # Check policy in a sandbox context + sbx policy check network --sandbox my-sandbox api.example.com:443 + + # Check a pasted URL and output JSON + sbx policy check network --json https://api.example.com/v1 +see_also: + - sbx policy check - Check whether policy allows an access request diff --git a/data/sbx_cli/sbx_policy_deny.yaml b/data/sbx_cli/sbx_policy_deny.yaml index 2211ef9680f1..a9a72cd87bbc 100644 --- a/data/sbx_cli/sbx_policy_deny.yaml +++ b/data/sbx_cli/sbx_policy_deny.yaml @@ -3,8 +3,8 @@ synopsis: Add a deny rule for sandboxes description: |- Add a rule that blocks sandboxes from accessing specified resources. - Deny rules always take precedence over allow rules. If a resource matches - both an allow and a deny rule, the request is blocked. + Deny rules take precedence over allow rules for the same hostname or CIDR. An + allowed hostname isn't checked against CIDR rules for its resolved IP address. usage: sbx policy deny COMMAND options: - name: help @@ -12,6 +12,10 @@ options: default_value: "false" usage: help for deny inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_deny_network.yaml b/data/sbx_cli/sbx_policy_deny_network.yaml index c0546f95d53c..558a9bd6b157 100644 --- a/data/sbx_cli/sbx_policy_deny_network.yaml +++ b/data/sbx_cli/sbx_policy_deny_network.yaml @@ -3,8 +3,12 @@ synopsis: Deny network access to specified hosts description: |- Block sandbox network access to the specified hosts. - RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. - Deny rules always take precedence over allow rules. + RESOURCES takes the same forms as "sbx policy allow network": exact domains, + wildcard subdomains, IP addresses, and CIDR prefixes, with optional port + suffixes. Rules apply to TCP and UDP by default; use --protocol to restrict a + rule to one transport. Deny rules take precedence over allow rules for the + same hostname or CIDR. An allowed hostname isn't checked against CIDR rules + for its resolved IP address. The rule applies globally to all sandboxes by default. Use --sandbox to add the rule to policy "local" scoped to a single sandbox instead. @@ -14,10 +18,17 @@ options: shorthand: h default_value: "false" usage: help for network + - name: protocol + usage: | + Restrict the rule to one protocol: tcp or udp (default tcp,udp) - name: sandbox usage: | Scope the rule to a specific sandbox (default: all sandboxes) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -29,7 +40,10 @@ example: |4- # Block a host only for a specific sandbox sbx policy deny network --sandbox my-sandbox ads.example.com - # Block all outbound traffic + # Block all outbound traffic, TCP and UDP sbx policy deny network "**" + + # Block only UDP to a host + sbx policy deny network --protocol udp media.example.com see_also: - sbx policy deny - Add a deny rule for sandboxes diff --git a/data/sbx_cli/sbx_policy_init.yaml b/data/sbx_cli/sbx_policy_init.yaml new file mode 100644 index 000000000000..16bddc6492c2 --- /dev/null +++ b/data/sbx_cli/sbx_policy_init.yaml @@ -0,0 +1,58 @@ +name: sbx policy init +synopsis: Initialize the global network policy +description: |- + Initialize the global network policy before starting a sandbox or adding + custom rules. Per-sandbox rules apply on top of this policy. + + Choose a policy: + + - allow-all: Allow all outbound network traffic. + - balanced: Allow typical development traffic, including AI services and package registries. + - deny-all: Block all outbound network traffic. + + After initialization, use sbx policy allow/deny/rm to change the rules. + Initialization is a one-time setup. Use sbx policy reset to clear all policies + and start over. + + With --cloud: + Set the default network mode of the cloud policy. + + There is no one-time setup: init sets the default mode for the account, or for + one sandbox with --sandbox, keeps the existing allow and deny rules, and can be + run again. balanced is deny-all plus the balanced allow list added to the scope. + Use "sbx --cloud policy reset" to clear the rules first. +usage: sbx policy init allow-all|balanced|deny-all [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for init + - name: sandbox + usage: Target a single cloud sandbox's policy (cloud only) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Initialize with the balanced policy — recommended + sbx policy init balanced + + # Allow all traffic + sbx policy init allow-all + + # Block everything, then allow specific sites + sbx policy init deny-all + sbx policy allow network api.example.com:443 + + # Set the account default to balanced + sbx --cloud policy init balanced + + # Block everything for one sandbox, keeping its allow rules + sbx --cloud policy init deny-all --sandbox my-sandbox +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_inspect.yaml b/data/sbx_cli/sbx_policy_inspect.yaml new file mode 100644 index 000000000000..2a1bda3d736c --- /dev/null +++ b/data/sbx_cli/sbx_policy_inspect.yaml @@ -0,0 +1,44 @@ +name: sbx policy inspect +synopsis: Show policy or rule details +description: |- + Inspect full detail for a selected policy or rule. + + The selector may be a policy ID, policy name, rule ID, or rule name. + Selecting a policy lists every resource with its decision, rule, and status, + plus a rule table showing each rule's RULE_ID, whether it is editable, and + either the exact removal command or the reason it is read-only. Selecting a + rule shows just that rule with the same editability detail. RULE_ID is the + identifier accepted by "sbx policy rm network --id" (local rules only). Use + "sbx policy ls" to find policy names and "sbx policy ls --wide" to find rule + IDs and resource values. +usage: sbx policy inspect POLICY|RULE [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Inspect a policy by name + sbx policy inspect "Developer access" + + # Inspect a rule by ID + sbx policy inspect 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 + + # Machine-readable output for scripting + sbx policy inspect "Developer access" --json +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_log.yaml b/data/sbx_cli/sbx_policy_log.yaml index 34c68a60e9f9..9b3e549176f1 100644 --- a/data/sbx_cli/sbx_policy_log.yaml +++ b/data/sbx_cli/sbx_policy_log.yaml @@ -8,6 +8,8 @@ description: |- issues or auditing network activity. usage: sbx policy log [SANDBOX] [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" @@ -18,14 +20,15 @@ options: - name: limit default_value: "0" usage: Maximum number of log entries to show - - name: quiet - shorthand: q - default_value: "false" - usage: Only display log entries - name: type default_value: all - usage: 'Filter logs by type: "all" or "network" (default "all")' + usage: | + Filter logs by type: "all", "network", or "filesystem" (filesystem logs are not supported yet; default "all") inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml index 5005d5b41dd6..491d9b8328b2 100644 --- a/data/sbx_cli/sbx_policy_ls.yaml +++ b/data/sbx_cli/sbx_policy_ls.yaml @@ -1,18 +1,30 @@ name: sbx policy ls -synopsis: List sandbox policy rules +synopsis: List sandbox policies description: |- - List active policy rules. + List active sandbox policies. - Displays the provenance, scope, rule name (or ID if no name is set), type, - decision (allow/deny), and the associated resources for each rule. + Without SANDBOX, the command shows one overview row per policy with its source, + where it applies, and a summary of decisions by resource type. With SANDBOX, it + summarizes active rules that apply to that sandbox. + + Use --wide to show the detailed rule-level table with separate POLICY, + POLICY_ID, RULE, and RULE_ID columns plus resources, status, and rule + metadata. RULE_ID is the identifier accepted by "sbx policy rm network --id" + (local rules only). Use --json for the filtered daemon response. When remote governance is active, inactive policy rules are hidden by default. Use --include-inactive to show inactive rules for troubleshooting. - - When SANDBOX is specified, only policies that apply to that sandbox are shown - (global rules plus rules scoped to that sandbox). + Use "sbx policy inspect <policy-or-rule>" for full detail on a selected policy or + rule. usage: sbx policy ls [SANDBOX] [flags] options: + - name: created-via + usage: | + Filter policies by how they were created: "default", "added", "provisioned", or "approval" + - name: decision + usage: 'Filter policies by decision: "allow" or "deny"' + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" @@ -20,10 +32,29 @@ options: - name: include-inactive default_value: "false" usage: Show inactive policy rules hidden by remote governance + - name: json + default_value: "false" + usage: Output in JSON format + - name: protocol + usage: 'Filter network rules by protocol: tcp or udp' + - name: quiet + shorthand: q + default_value: "false" + usage: Only display rule IDs (network patterns with --cloud) + - name: source + usage: 'Filter policies by source: "local", "org", or "kit"' - name: type default_value: all - usage: 'Filter policies by type: "all" or "network" (default "all")' + usage: | + Filter policies by type: "all", "network", "filesystem" (default "all") + - name: wide + default_value: "false" + usage: Show detailed rule-level output with rule IDs and resources inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -32,11 +63,26 @@ example: |4- # List all policies sbx policy ls + # List the policies that apply to one sandbox + sbx policy ls my-sandbox + + # Show detailed rule-level rows with rule IDs and resources + sbx policy ls --wide + + # Output filtered rules as JSON + sbx policy ls --json + + # List only rule IDs + sbx policy ls -q + # List only network policies sbx policy ls --type network - # List policies that apply to a specific sandbox - sbx policy ls my-sandbox + # List organization policies that deny access + sbx policy ls --source org --decision deny + + # List persistent rules created from approval prompts + sbx policy ls --wide --created-via approval # Include inactive rules hidden by remote governance sbx policy ls --include-inactive diff --git a/data/sbx_cli/sbx_policy_refresh.yaml b/data/sbx_cli/sbx_policy_refresh.yaml new file mode 100644 index 000000000000..601cf2e07554 --- /dev/null +++ b/data/sbx_cli/sbx_policy_refresh.yaml @@ -0,0 +1,32 @@ +name: sbx policy refresh +synopsis: Force an immediate policy refresh +description: |- + Force sandboxd to fetch and apply governance policy immediately. + + The daemon normally polls for policy changes on a regular interval. Use this + after changing an org policy setting (for example, toggling AI Governance) so + the change takes effect without waiting for the next poll. This also + invalidates the cached registry credential; it never restarts the daemon or + stops running sandboxes. + + The refreshed policy applies to new connections only. Connections a sandbox + opened while the previous policy allowed them stay open even if the new + policy denies them; restart the sandbox to drop them. +usage: sbx policy refresh [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for refresh +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx policy refresh' +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_reset.yaml b/data/sbx_cli/sbx_policy_reset.yaml index 7c4c1ec80b25..38352cbf5a6a 100644 --- a/data/sbx_cli/sbx_policy_reset.yaml +++ b/data/sbx_cli/sbx_policy_reset.yaml @@ -3,11 +3,16 @@ synopsis: Reset policies to defaults description: |- Remove all custom policies and restart the daemon to restore defaults. - This deletes the local policy store and stops the daemon. When the daemon - restarts (automatically on next command), the default policy is installed. + This deletes the local policy store and stops the daemon. The daemon restarts + automatically on the next command, then prompts you to initialize the global + network policy again. If sandboxes are currently running, they will be stopped when the daemon shuts down. You will be prompted for confirmation unless --force is used. + + With --cloud, deletes the custom cloud network policy for your account and + leaves the local daemon alone. You will be prompted for confirmation unless + --force is used. Afterwards the default the server now stores is printed. usage: sbx policy reset [flags] options: - name: force @@ -19,12 +24,16 @@ options: default_value: "false" usage: help for reset inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # Reset policies (prompts if sandboxes are running) + # Reset policies — prompts if sandboxes are running sbx policy reset # Reset policies without confirmation diff --git a/data/sbx_cli/sbx_policy_rm.yaml b/data/sbx_cli/sbx_policy_rm.yaml index 2c7578074d55..e0ac4d5cb1d0 100644 --- a/data/sbx_cli/sbx_policy_rm.yaml +++ b/data/sbx_cli/sbx_policy_rm.yaml @@ -8,6 +8,10 @@ options: default_value: "false" usage: help for rm inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_rm_network.yaml b/data/sbx_cli/sbx_policy_rm_network.yaml index 4f8a72d62525..e472817bf3b0 100644 --- a/data/sbx_cli/sbx_policy_rm_network.yaml +++ b/data/sbx_cli/sbx_policy_rm_network.yaml @@ -3,12 +3,31 @@ synopsis: Remove a network rule description: |- Remove a network rule by rule ID, resource, or both. + --id takes the RULE_ID value shown by "sbx policy ls --wide" and + "sbx policy inspect" — the rule's identifier, not its name. Passing a rule + name fails with an error that names the actual rule ID and, for removable + rules, the exact corrected command. + The rule is removed from the global policy by default. Use --sandbox to remove from policy "local" scoped to a single sandbox instead. - Use "sbx policy ls" to see active policies and their IDs/resources. + Use "sbx policy ls --wide" to see active rule IDs and resources, or + "sbx policy ls --json" for the filtered rules; network values are printed in + the form the CLI accepts back. + + With --cloud: + Remove a cloud network rule by pattern. + + Cloud rules have no IDs: --resource removes the pattern from both the allow + and deny lists, and the output names each list it was removed from. The rule + leaves the account policy by default; use --sandbox to scope the removal to one + sandbox. Use "sbx --cloud policy ls" to see the current rules. usage: sbx policy rm network [--sandbox SANDBOX] [flags] options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts - name: help shorthand: h default_value: "false" @@ -21,13 +40,17 @@ options: usage: | Scope the removal to a specific sandbox (default: global policy) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # List policies to find the ID or resource to remove - sbx policy ls + # List rules to find the ID or resource to remove + sbx policy ls --wide # Remove a global rule by resource sbx policy rm network --resource api.example.com @@ -37,5 +60,11 @@ example: |4- # Remove a sandbox-scoped rule by resource sbx policy rm network --sandbox my-sandbox --resource api.example.com + + # Remove a cloud rule by pattern, from the allow or deny list it is in + sbx --cloud policy rm network --resource api.example.com + + # Remove a pattern from one cloud sandbox's rules + sbx --cloud policy rm network --sandbox my-sandbox --resource api.example.com see_also: - sbx policy rm - Remove a policy rule diff --git a/data/sbx_cli/sbx_policy_set-default.yaml b/data/sbx_cli/sbx_policy_set-default.yaml deleted file mode 100644 index 505ee16fd799..000000000000 --- a/data/sbx_cli/sbx_policy_set-default.yaml +++ /dev/null @@ -1,38 +0,0 @@ -name: sbx policy set-default -synopsis: Set the default network policy -description: |- - Set the default network policy for all sandboxes. - - This must be run before adding custom allow/deny rules or starting a sandbox - for the first time. The default policy determines the baseline network access. - - Available policies: - allow-all All outbound network traffic is allowed - balanced Typical development traffic is allowed (AI services, package registries, etc.) - deny-all All outbound network traffic is blocked - - After setting defaults, use "sbx policy allow/deny" to add custom rules. - Use "sbx policy reset" to clear all policies and start over. -usage: sbx policy set-default <allow-all|balanced|deny-all> [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for set-default -inherited_options: - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging -example: |4- - # Set balanced defaults (recommended) - sbx policy set-default balanced - - # Allow all traffic - sbx policy set-default allow-all - - # Block everything, then allow specific sites - sbx policy set-default deny-all - sbx policy allow network api.example.com:443 -see_also: - - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_ports.yaml b/data/sbx_cli/sbx_ports.yaml index 2bf7767e58e5..985cea42c7d7 100644 --- a/data/sbx_cli/sbx_ports.yaml +++ b/data/sbx_cli/sbx_ports.yaml @@ -3,7 +3,8 @@ synopsis: Manage sandbox port publishing description: |- Manage sandbox port publishing. - List, publish, or unpublish ports for a running sandbox. Without --publish or + List, publish, or unpublish sandbox ports. Publishing a local port starts a + stopped sandbox before creating the host binding. Without --publish or --unpublish flags, lists all published ports. Port spec format: [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] @@ -11,26 +12,51 @@ description: |- If HOST_IP is omitted, the port is bound on loopback, expanded based on PROTOCOL and the sandbox's address families: tcp/udp binds both 127.0.0.1 and ::1 (or only 127.0.0.1 if the sandbox is IPv4-only); tcp4/udp4 binds - only 127.0.0.1; tcp6/udp6 binds only ::1. PROTOCOL defaults to tcp. + only 127.0.0.1; tcp6/udp6 binds only ::1. Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6. + + When publishing without a PROTOCOL, tcp4 is used — so a sandbox service + listening only on IPv4 is reachable without a host client having to avoid + ::1 — or tcp6 when HOST_IP is an IPv6 address. Publish tcp explicitly to + bind both families. + + When unpublishing without a PROTOCOL, the mapping is removed whether it was + published with that same default or as dual-stack tcp. Name the protocol to + remove a tcp6 or udp mapping; anything left behind is reported. + + With --cloud: + Manage the exposed ports of a cloud sandbox. + + List, publish, or unpublish ports on a cloud sandbox given by ID (sbx_*) or + name. Without --publish or --unpublish flags, lists the exposed ports. + + A port is the sandbox port number alone or with a /tcp suffix; UDP and host + bindings are refused. The cloud control plane assigns a publicly reachable URL + for each exposed port. usage: sbx ports SANDBOX [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for ports - name: json default_value: "false" - usage: Output in JSON format (for port listing) + usage: Output in JSON format - name: publish default_value: '[]' usage: | - Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] (local) or SANDBOX_PORT[/tcp] (cloud) - name: unpublish default_value: '[]' usage: | - Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL] + Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL] (local) or SANDBOX_PORT[/tcp] (cloud) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -47,5 +73,11 @@ example: |4- # Unpublish a port sbx ports my-sandbox --unpublish 3000:8080 + + # Expose port 8080 on a cloud sandbox + sbx --cloud ports sbx_abc123 --publish 8080 + + # Remove an exposed port from a cloud sandbox + sbx --cloud ports sbx_abc123 --unpublish 8080 see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_prune.yaml b/data/sbx_cli/sbx_prune.yaml new file mode 100644 index 000000000000..ce5df411bdbf --- /dev/null +++ b/data/sbx_cli/sbx_prune.yaml @@ -0,0 +1,70 @@ +name: sbx prune +synopsis: Remove all stopped sandboxes +description: |- + Remove all stopped sandboxes and their associated resources. + + Only stopped sandboxes are candidates — a running sandbox is never removed, + which makes this safe to run habitually. Stop a sandbox first with + "sbx stop" if you want it pruned. To remove a specific sandbox regardless of + state, use "sbx rm SANDBOX". + + Use --filter until=TIMESTAMP to narrow the set to sandboxes that stopped before + TIMESTAMP. The value can be an RFC 3339 timestamp, Unix timestamp, or Go duration + relative to now (e.g. until=168h keeps anything stopped within the last week). + A sandbox whose stop time the daemon cannot report is left alone, since how long + it has been stopped cannot be established. + + Use --dry-run to list what would be removed without removing anything, and + --format json or --format yaml with it for machine-readable output. + + Pruning requires confirmation; use --force to skip the confirmation prompt + (for non-interactive scripts) and to remove a sandbox that is in use (e.g. an + open SSH connection). This action cannot be undone. + + Secrets scoped to each successfully pruned sandbox are also deleted. + + Local-only: cloud sandboxes expire via their TTL. +usage: sbx prune [flags] +options: + - name: dry-run + default_value: "false" + usage: | + List the sandboxes that would be removed without removing them + - name: filter + default_value: '[]' + usage: | + Filter candidates (supported: until=TIMESTAMP — stopped before TIMESTAMP) + - name: force + shorthand: f + default_value: "false" + usage: | + Skip confirmation prompts and remove even if in use (e.g. an open SSH connection) + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for prune + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Show what would be removed + sbx prune --dry-run + + # Remove without asking + sbx prune --force + + # Only sandboxes stopped before a point in time + sbx prune --filter until=2026-01-01T00:00:00Z +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_reset.yaml b/data/sbx_cli/sbx_reset.yaml index 90f3cf4938ff..2137293367bb 100644 --- a/data/sbx_cli/sbx_reset.yaml +++ b/data/sbx_cli/sbx_reset.yaml @@ -9,6 +9,8 @@ description: |- - Clear all internal registries - Delete all sandbox state - Remove all policies + - Remove the managed SSH configuration + - Clear the Gordon assistant's sessions and history - Delete all stored secrets - Sign out of Docker Sandboxes - Stop the daemon @@ -36,9 +38,18 @@ options: default_value: "false" usage: Keep stored secrets inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx reset + + # Skip the confirmation prompt and keep stored secrets + sbx reset --force --preserve-secrets see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_rm.yaml b/data/sbx_cli/sbx_rm.yaml index 7e38aa80f857..9f39eed20f3e 100644 --- a/data/sbx_cli/sbx_rm.yaml +++ b/data/sbx_cli/sbx_rm.yaml @@ -1,13 +1,23 @@ name: sbx rm synopsis: Remove one or more sandboxes description: |- - Remove one or more sandboxes and all associated resources. + Remove one or more sandboxes and all associated resources. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". - Stops running sandboxes, removes their containers, cleans up any Git - worktrees, and deletes sandbox state. This action cannot be undone. + For local sandboxes, stops them, removes their containers, cleans up any Git + worktrees, deletes sandbox state, and deletes secrets scoped to each removed + sandbox. This action cannot be undone. With --cloud, deletes + the sandbox in Docker Sandboxes Cloud. This action cannot be undone. Once the + server accepts the request, rm waits up to 60 seconds per sandbox for the + deletion. A removal still completing after that exits 0. Verify it later with + "sbx --cloud ls". Removal requires confirmation; use --force to skip confirmation prompts - (for non-interactive scripts). Use --all to remove every sandbox. + (for non-interactive scripts) and to delete a sandbox that is in use + (e.g. an open SSH connection). Use --all to remove every sandbox. With --cloud, --all is + intentionally disabled as a safety gate — the blast radius covers every + sandbox the credential can see, which may include shared or production + workloads. Pass IDs explicitly in --cloud mode. usage: sbx rm [SANDBOX...] [flags] options: - name: all @@ -16,15 +26,33 @@ options: - name: force shorthand: f default_value: "false" - usage: Skip confirmation prompts + usage: | + Skip confirmation prompts and delete even if in use (e.g. an open SSH connection) + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for rm + - name: json + default_value: "false" + usage: Output in JSON format inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx rm my-sandbox + + # Remove several at once + sbx rm one two + + # Remove every sandbox without asking + sbx rm --all --force see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml index 8bbc0367bb3b..6c331411d0f8 100644 --- a/data/sbx_cli/sbx_run.yaml +++ b/data/sbx_cli/sbx_run.yaml @@ -3,14 +3,56 @@ synopsis: Run an agent in a sandbox description: |- Run an agent in a sandbox, creating the sandbox if it does not already exist. + The first positional argument identifies the agent to run. It may be a built-in + agent name or a sandbox kit reference. Sandbox kit references may be local + directories, ZIP files, git repositories, or OCI references. Relative local + references must be explicit paths such as ./my-kit or ../my-kit.zip; bare values + retain their agent or sandbox-name meaning. To re-attach to an existing sandbox + by name, use --name; the agent positional is optional when the named sandbox + already exists and is read from its spec. + Pass agent arguments after the "--" separator. Additional workspaces can be - provided as extra arguments. Append ":ro" to mount them read-only. + provided as extra arguments. Append ":ro" to mount them read-only; a read-only + argument may name a single file, which holds that one path out of reach inside a + workspace the sandbox can otherwise write. + + Omit the path to mount the current directory. Pass a path to mount a different + workspace. + + To create a sandbox without attaching, use "sbx create" instead, or + pass --detach (-d) to print the sandbox ID and exit without opening an + interactive session. + + Available agents: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, shell + + With --cloud: + Run an agent in a cloud sandbox, creating the sandbox if it does not already exist. + + The first positional argument identifies the agent to run: a built-in agent + name or a sandbox kit reference (a local directory, ZIP file, git repository, + or OCI reference). Relative local references must be explicit paths such as + ./my-kit or ../my-kit.zip. Cloud sandboxes have no host workspace, so no path + follows the agent. Pass agent arguments after the "--" separator. - To create a sandbox without attaching, use "sbx create" instead. + Running an agent that has existing sandboxes, running or stopped, prompts you + to pick one to reuse or to create a new one. Pass --new to skip the prompt and + always create a fresh sandbox. --name NAME reuses and restarts the sandbox of + that name when it exists and creates it otherwise. A sandbox kit launch always + creates fresh, as does a launch that bakes a mixin with build content. + --detach skips the prompt: with --name it restarts that sandbox when it + exists, otherwise it creates a new one. A non-interactive run without + --detach is refused, so scripts pass --detach (e.g. + sbx --cloud run -d claude && sbx --cloud exec ...). - Available agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell -usage: sbx run [flags] SANDBOX | AGENT [PATH...] [-- AGENT_ARGS...] + Sizing comes from --cpus and --memory and must land on a billable shape; without + them a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template + must already exist in the cloud registry; the CLI does not upload it. See + https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model. +usage: sbx run [flags] [AGENT|SANDBOX_KIT] [PATH...] [-- AGENT_ARGS...] options: + - name: allow-network + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | @@ -18,42 +60,140 @@ options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64) + - name: deny-network + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: detach + shorthand: d + default_value: "false" + usage: | + Start the sandbox and print its ID without opening an agent session + - name: detach-keys + usage: | + Override the detach gesture that leaves the session running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only). + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it - name: help shorthand: h default_value: "false" usage: help for run + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB) - name: name usage: 'Name for the sandbox (default: <agent>-<workdir>)' + - name: new + default_value: "false" + usage: | + Always create a new cloud sandbox instead of prompting to reuse an existing one (cloud only) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). + - name: platform + usage: | + Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]. Applied when the sandbox is created; ignored when re-attaching (use "sbx ports") + - name: pull + usage: | + Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always) + - name: rm + default_value: "false" + usage: Remove the sandbox after the agent session exits + - name: skills + usage: | + Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. Can only be used when creating a new sandbox. + - name: static-mcp + default_value: '[]' + usage: | + MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time and cannot be changed when re-attaching to an existing sandbox. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway. - name: template shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # Create and run a sandbox with claude in current directory + # Create and run a sandbox with claude in the current directory sbx run claude + # Create and run from a local sandbox kit + sbx run ../path/to/my-agent/ + + # Create and run from an OCI sandbox kit + sbx run ghcr.io/foo/my-agent:latest + + # Add a mixin to a built-in agent + sbx run claude --kit ./my-mixin/ + # Create and run with additional workspaces (read-only) sbx run claude . /path/to/docs:ro - # Run an existing sandbox - sbx run existing-sandbox + # Re-attach to an existing sandbox by name (agent read from its spec) + sbx run --name existing-sandbox + + # Re-attach to an existing sandbox by name and verify the expected agent + sbx run claude --name existing-sandbox # Run a sandbox with agent arguments sbx run claude -- --continue + + # Run claude in a new cloud sandbox + sbx --cloud run claude + + # Create a cloud sandbox non-interactively and print its ID + sbx --cloud run --detach claude + + # Reuse the cloud sandbox of that name, creating it when it does not exist + sbx --cloud run --name my-project claude + + # Run with agent arguments + sbx --cloud run claude -- --continue see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_secret.yaml b/data/sbx_cli/sbx_secret.yaml index faf42534d362..d4d11e1b0e21 100644 --- a/data/sbx_cli/sbx_secret.yaml +++ b/data/sbx_cli/sbx_secret.yaml @@ -10,21 +10,28 @@ description: |- REGISTRY SECRETS (e.g. "ghcr.io", "myregistry.azurecr.io") Used to pull private template images and kit artifacts before sandbox - creation. Host-only secrets (no -g) are not injected into sandboxes; - global secrets (-g) are written as ~/.docker/config.json in every new sandbox. + creation. Unlike service secrets, registry credentials are host-only by + default. They are not injected into sandboxes unless --all-sandboxes or + --sandbox is set (the credential never enters the sandbox filesystem). Use "sbx secret set --registry <host> --password-stdin" to store them. +usage: sbx secret COMMAND options: - name: help shorthand: h default_value: "false" usage: help for secret inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. + - sbx secret import - Import secrets detected in host environment variables - sbx secret ls - List stored secrets - sbx secret rm - Remove a secret - sbx secret set - Create or update a secret diff --git a/data/sbx_cli/sbx_secret_import.yaml b/data/sbx_cli/sbx_secret_import.yaml new file mode 100644 index 000000000000..2da741a36326 --- /dev/null +++ b/data/sbx_cli/sbx_secret_import.yaml @@ -0,0 +1,66 @@ +name: sbx secret import +synopsis: Import secrets detected in host environment variables +description: |- + Import secrets that sbx detects in your host environment + variables (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, GH_TOKEN) into the + global keychain. Once imported, the secret is available to every + sandbox without needing the env var on each shell. + + Each detected env var is offered interactively with a Y/n prompt and a + last-4-char preview of the value. Existing stored entries are never + overwritten silently: + + - Interactive mode prompts for confirmation before overwriting. + - --all imports new entries without prompting but SKIPS overwrites + (use --force when you actually want to replace stored values). + - --force imports unconditionally, including overwriting. + + Services that already have an OAuth token configured (e.g. anthropic + after `sbx run claude … -- auth login`) are skipped: the OAuth token + takes precedence at runtime so any api-key import would never be used. + Run `sbx secret rm <service>` first if you want to switch from + OAuth to api-key auth. + + Available services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai +usage: sbx secret import [SERVICE] [flags] +options: + - name: all + default_value: "false" + usage: Import every detected env var without prompting + - name: dry-run + default_value: "false" + usage: Show what would be imported without writing + - name: force + shorthand: f + default_value: "false" + usage: Overwrite an existing stored entry without confirmation + - name: help + shorthand: h + default_value: "false" + usage: help for import +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Walk every detected env var, prompting before each import + sbx secret import + + # Import only the openai service (uses OPENAI_API_KEY) + sbx secret import openai + + # Non-interactive: import everything detected without prompting + sbx secret import --all + + # Overwrite an existing stored entry without confirmation + sbx secret import openai --force + + # Preview what would be imported without writing + sbx secret import --dry-run +see_also: + - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_ls.yaml b/data/sbx_cli/sbx_secret_ls.yaml index 044b6c6d6a77..5edfbc9786e2 100644 --- a/data/sbx_cli/sbx_secret_ls.yaml +++ b/data/sbx_cli/sbx_secret_ls.yaml @@ -1,7 +1,14 @@ name: sbx secret ls synopsis: List stored secrets -usage: sbx secret ls [SANDBOX] [flags] +description: |- + List stored secrets across global and sandbox scopes. + + With no scope flag, all stored secrets are shown. Use --global to show only + global secrets, or --sandbox to show only secrets scoped to one sandbox. +usage: sbx secret ls [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: global shorthand: g default_value: "false" @@ -10,9 +17,22 @@ options: shorthand: h default_value: "false" usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display secret names + - name: sandbox + usage: Only list secrets for one sandbox - name: service usage: Filter by secret service name inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -25,9 +45,12 @@ example: |4- sbx secret ls -g # List secrets for a specific sandbox - sbx secret ls my-sandbox + sbx secret ls --sandbox my-sandbox # Filter by service sbx secret ls --service github + + # Machine-readable output for scripting + sbx secret ls --json see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_rm.yaml b/data/sbx_cli/sbx_secret_rm.yaml index c555e36263d0..75211af4fb12 100644 --- a/data/sbx_cli/sbx_secret_rm.yaml +++ b/data/sbx_cli/sbx_secret_rm.yaml @@ -1,44 +1,68 @@ name: sbx secret rm synopsis: Remove a secret -usage: sbx secret rm [-g | SANDBOX] [SERVICE] [flags] +usage: sbx secret rm [SERVICE] [flags] options: + - name: all + default_value: "false" + usage: Remove every stored secret across all scopes + - name: all-sandboxes + default_value: "false" + usage: | + Remove registry credentials injected into every sandbox (requires --registry) - name: force shorthand: f default_value: "false" usage: Delete without confirmation prompt - - name: global - shorthand: g - default_value: "false" - usage: Use global secret scope - name: help shorthand: h default_value: "false" usage: help for rm - name: registry usage: Registry hostname to remove pull credentials for + - name: sandbox + usage: | + Scope the removal to one sandbox (default: all scopes when choosing interactively, global with SERVICE) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- + # Choose an existing secret to remove with the arrow keys + sbx secret rm + # Remove a global secret - sbx secret rm -g github + sbx secret rm github # Remove a sandbox-scoped secret - sbx secret rm my-sandbox openai + sbx secret rm openai --sandbox my-sandbox # Remove without confirmation prompt - sbx secret rm -g github -f + sbx secret rm github -f # Remove OpenAI or Anthropic credential(s) from global scope (OAuth and/or API key) - sbx secret rm -g openai - sbx secret rm -g anthropic + sbx secret rm openai + sbx secret rm anthropic + + # Remove custom secret by specifying the placeholder value + sbx secret rm --placeholder docker-placeholder-value # Remove registry pull credentials (removes host-only and global entries) sbx secret rm --registry ghcr.io -f # Remove only the global (all-sandboxes) registry credential - sbx secret rm -g --registry ghcr.io -f + sbx secret rm --all-sandboxes --registry ghcr.io -f + + # Remove every stored secret across every scope (service secrets, custom + # secrets, OAuth tokens, and registry credentials) + sbx secret rm --all + + # Remove a cloud custom secret by its name, or by a host it routes + sbx --cloud secret rm api-example-com + sbx --cloud secret rm --host api.example.com see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_set-custom.yaml b/data/sbx_cli/sbx_secret_set-custom.yaml index b545fdd538a0..0c1a7ebaaf38 100644 --- a/data/sbx_cli/sbx_secret_set-custom.yaml +++ b/data/sbx_cli/sbx_secret_set-custom.yaml @@ -9,30 +9,78 @@ description: |- target host, the proxy replaces the placeholder with the real secret in the request headers — the secret never enters the sandbox directly. - Secrets can be scoped globally (shared across all sandboxes) or to a specific sandbox. -usage: sbx secret set-custom [-g | sandbox] [flags] + --host accepts an exact host, IP address, or wildcard pattern. Repeat --host + to cover multiple unrelated domains with one secret. "*" matches a single label + and "**" matches any number of labels. For example "*.example.com" covers + "cli.example.com" and "ide.example.com" with one entry. + + Custom secrets apply globally by default. Use --sandbox to scope one to a + specific sandbox. + + Command secrets run from a fresh temporary directory on the host during + verification and refresh. The host temporary directory must be absolute and must + remain outside writable sandbox mounts. Relative references such as ./helper or + cat token no longer resolve against the project or daemon working directory. Use an absolute + helper path outside shared workspaces. sbx does not copy helpers, inspect their + dependencies, or confine their execution. Helpers and any code or configuration + they load must remain outside writable sandbox mounts. Explicit paths into shared + workspaces and broad mounts exposing host configuration or the host temporary + directory remain unsafe, including mounts added later with sbx mount. + + With --cloud, --host takes exact DNS names only (no IP addresses or wildcards) + and the proxy sets --header on requests to those hosts instead of substituting + the placeholder. +usage: sbx secret set-custom [flags] options: + - name: command + usage: Use a command's standard output as the secret value - name: env usage: Set this env var in the sandbox to the placeholder value - - name: global - shorthand: g - default_value: "false" - usage: Use global secret scope + - name: format + usage: | + How the value fills the header, with one %s; default "Bearer %s" when --header is omitted (with --cloud) + - name: header + usage: | + HTTP header the proxy sets to the secret on requests to --host; default Authorization (with --cloud) - name: help shorthand: h default_value: "false" usage: help for set-custom - name: host - usage: Host or IP address + default_value: '[]' + usage: | + Host, IP, or wildcard pattern (e.g. *.example.com); repeatable; with --cloud, exact DNS names only + - name: name + usage: | + Secret name; default derived from the first --host (with --cloud) + - name: no-verify + default_value: "false" + usage: Skip checking the --ref or --command source when storing it - name: placeholder usage: | Placeholder value; use {rand} for a random suffix (e.g. sk-{rand}) + - name: ref + usage: | + Use a 1Password op:// reference or AWS Secrets Manager ARN as the secret source + - name: refresh + usage: | + Secret refresh policy: on-demand (default) or after a duration + - name: sandbox + usage: 'Scope the secret to one sandbox (default: all sandboxes)' + - name: show-error + default_value: "false" + usage: | + Show resolver standard error if the initial check fails (may contain secrets) - name: token shorthand: t usage: 'Secret value (less secure: visible in shell history)' - name: value usage: 'Secret value (less secure: visible in shell history)' inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -41,12 +89,18 @@ example: |4- # Create a global custom secret. A unique placeholder is generated automatically. # The sandbox env var API_KEY is set to the placeholder value; outbound requests # to the host have the placeholder replaced with the real secret. - sbx secret set-custom -g --host api.example.com --env API_KEY --value secret123 + sbx secret set-custom --host api.example.com --env API_KEY --value secret123 + + # Use a wildcard host to cover multiple subdomains that share one key. + sbx secret set-custom --host '*.coderabbit.ai' --env CODERABBIT_API_KEY --value secret123 + + # Use multiple --host flags to cover unrelated domains with the same key. + sbx secret set-custom --host api.example.com --host api.other.io --env API_KEY --value secret123 # Scope to a specific sandbox instead of globally. - sbx secret set-custom my-sandbox --host api.example.com --env API_KEY --value secret123 + sbx secret set-custom --sandbox my-sandbox --host api.example.com --env API_KEY --value secret123 # Custom placeholder with {rand} suffix; the CLI prints the generated value. - sbx secret set-custom -g --host api.example.com --placeholder sk-{rand} --value secret123 + sbx secret set-custom --host api.example.com --placeholder sk-{rand} --value secret123 see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_set.yaml b/data/sbx_cli/sbx_secret_set.yaml index c075cfa7fa0e..311b04c771df 100644 --- a/data/sbx_cli/sbx_secret_set.yaml +++ b/data/sbx_cli/sbx_secret_set.yaml @@ -1,40 +1,92 @@ name: sbx secret set synopsis: Create or update a secret description: |- - Create or update a secret for a service or registry. + Create or update a service secret or registry credential. - Available services: anthropic, aws, cursor, droid, github, google, groq, mistral, nebius, openai, openrouter, xai + ### Service secrets - When no arguments are provided, an interactive prompt guides you through - scope and service selection. + Available services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai - Use --registry to store pull credentials for a container registry: - Without -g: host-only — used for template/kit pulls, not injected into sandboxes. - With -g: global — host pulls AND written as ~/.docker/config.json in every new sandbox. - With SANDBOX as the first argument: scoped to that specific sandbox only. -usage: sbx secret set [-g | SANDBOX] [SERVICE] [flags] + Service secrets apply globally by default. Use --sandbox to scope a secret to + one sandbox. When SERVICE is omitted, an interactive prompt selects it. + + ### Dynamic secrets + + Use --ref or --command to store a secret source instead of the secret value. + sbx resolves the source on the host when needed and caches the value according + to the --refresh policy. + + --ref supports 1Password op:// references and AWS Secrets Manager ARNs. The + corresponding op or aws CLI must be installed and authenticated. --command + runs a shell command and uses its standard output as the secret value. + + Command secrets run from a fresh temporary directory on the host during + verification and refresh. The host temporary directory must be absolute and must + remain outside writable sandbox mounts. Relative references such as ./helper or + cat token no longer resolve against the project or daemon working directory. Use an absolute + helper path outside shared workspaces. sbx does not copy helpers, inspect their + dependencies, or confine their execution. Helpers and any code or configuration + they load must remain outside writable sandbox mounts. Explicit paths into shared + workspaces and broad mounts exposing host configuration or the host temporary + directory remain unsafe, including mounts added later with sbx mount. + + ### Registry credentials + + Use --registry to store pull credentials for a container registry. Unlike + service secrets, registry credentials are host-only by default: + + - By default, credentials are used for template and kit pulls on the host. + They are never injected into a sandbox. + - With --all-sandboxes, credentials are used for host pulls and injected by + the proxy into every new sandbox's registry login. The credentials never + enter the sandbox. + - With --sandbox, credentials are injected into the specified sandbox only. + + For a registry whose Bearer authentication endpoint uses a different hostname, + use --registry-auth-endpoint to trust its exact HTTPS URL. +usage: sbx secret set [SERVICE] [flags] options: + - name: all-sandboxes + default_value: "false" + usage: | + Inject registry credentials into every sandbox (requires --registry) + - name: command + usage: Use a command's standard output as the secret value - name: force shorthand: f default_value: "false" usage: Overwrite an existing secret when --token is used - - name: global - shorthand: g - default_value: "false" - usage: Use global secret scope - name: help shorthand: h default_value: "false" usage: help for set + - name: no-verify + default_value: "false" + usage: Skip checking the --ref or --command source when storing it - name: oauth default_value: "false" - usage: Start OAuth flow and store OAuth tokens (openai/global only) + usage: | + Start OAuth flow and store OAuth tokens (openai/global only) With --cloud: openai or anthropic, stored only in the cloud (never the local secrets-engine) - name: password-stdin default_value: "false" usage: | Read registry password or token from stdin (use with --registry) + - name: ref + usage: | + Use a 1Password op:// reference or AWS Secrets Manager ARN as the secret source + - name: refresh + usage: | + Secret refresh policy: on-demand or after a duration (default: 55m) - name: registry usage: Registry hostname for pull credentials (e.g. ghcr.io) + - name: registry-auth-endpoint + usage: Trusted HTTPS auth endpoint for a cross-host registry realm + - name: sandbox + usage: Scope the secret to one sandbox instead of its default scope + - name: show-error + default_value: "false" + usage: | + Show resolver standard error if the initial check fails (may contain secrets) - name: token shorthand: t usage: 'Secret value (less secure: visible in shell history)' @@ -42,30 +94,49 @@ options: usage: | Registry username (use with --registry; omit for token-only auth) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- # Store a GitHub token globally (available to all sandboxes) - sbx secret set -g github + sbx secret set github # Store an OpenAI key for a specific sandbox - sbx secret set my-sandbox openai + sbx secret set openai --sandbox my-sandbox # Non-interactive via stdin (e.g., from a secret manager or env var) - echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic + echo "$ANTHROPIC_API_KEY" | sbx secret set anthropic # Start OpenAI OAuth flow and store global OAuth tokens - sbx secret set -g openai --oauth + sbx secret set openai --oauth + + # Resolve a 1Password reference at use time (requires an authenticated op CLI) + sbx secret set anthropic --ref 'op://Private/Anthropic/api-key' + + # Resolve an AWS Secrets Manager ARN at use time (requires an authenticated aws CLI) + sbx secret set anthropic --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key' + + # Resolve a secret using an arbitrary command + sbx secret set github --command 'gh auth token' # Registry: host-only (template/kit pulls, not injected into sandboxes) gh auth token | sbx secret set --registry ghcr.io --password-stdin - # Registry: global (host pulls + injected into every new sandbox) - gh auth token | sbx secret set -g --registry ghcr.io --password-stdin + # Registry: host pulls + injected into every new sandbox + gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin # Registry: specific sandbox only - gh auth token | sbx secret set my-sandbox --registry ghcr.io --password-stdin + gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin + + # Self-hosted registry with a cross-host authentication endpoint + echo "$GITLAB_PAT" | sbx secret set --all-sandboxes \ + --registry registry.example.com --username "$GITLAB_USER" \ + --registry-auth-endpoint https://gitlab.example.com/jwt/auth \ + --password-stdin see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_settings.yaml b/data/sbx_cli/sbx_settings.yaml new file mode 100644 index 000000000000..8cd0d8d1df89 --- /dev/null +++ b/data/sbx_cli/sbx_settings.yaml @@ -0,0 +1,32 @@ +name: sbx settings +synopsis: Manage Docker Sandboxes settings +description: |- + View and manage settings for Docker Sandboxes. + + Settings can come from defaults, environment variables, or user overrides. + These commands use the local daemon to read evaluated values and manage + overrides, starting it if necessary. + + Most changes take effect within about five seconds. Some require a daemon + restart. +usage: sbx settings COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for settings +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx settings get - Get the value of a setting + - sbx settings ls - List settings + - sbx settings set - Set a setting override + - sbx settings unset - Remove a setting override diff --git a/data/sbx_cli/sbx_settings_get.yaml b/data/sbx_cli/sbx_settings_get.yaml new file mode 100644 index 000000000000..0f946ff78a4c --- /dev/null +++ b/data/sbx_cli/sbx_settings_get.yaml @@ -0,0 +1,35 @@ +name: sbx settings get +synopsis: Get the value of a setting +description: |- + Print the evaluated value of a setting. + + Use --json to print the complete setting record, including its source, type, + default, and description. +usage: sbx settings get KEY [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for get + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Get a setting value + sbx settings get proxy.daemon + + # Get in JSON format with source info + sbx settings get --json proxy.daemon +see_also: + - sbx settings - Manage Docker Sandboxes settings diff --git a/data/sbx_cli/sbx_settings_ls.yaml b/data/sbx_cli/sbx_settings_ls.yaml new file mode 100644 index 000000000000..35edf79352a2 --- /dev/null +++ b/data/sbx_cli/sbx_settings_ls.yaml @@ -0,0 +1,48 @@ +name: sbx settings ls +synopsis: List settings +description: |- + List known settings with their evaluated value, type, source, and description. + + The SOURCE column shows where the value came from (default, envvar, or + override). RESTART identifies settings that require 'sbx daemon restart' for + existing daemon-side consumers. Long values and descriptions are truncated to + keep the table readable; use --no-trunc or --format json for complete output. Use + 'sbx settings get KEY' to print one value in full. +usage: sbx settings ls [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: no-trunc + default_value: "false" + usage: Show full values and descriptions, one setting per block + - name: quiet + shorthand: q + default_value: "false" + usage: Only display setting keys +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # List settings as a table + sbx settings ls + + # List settings as JSON + sbx settings ls --format json + + # List only setting keys + sbx settings ls -q +see_also: + - sbx settings - Manage Docker Sandboxes settings diff --git a/data/sbx_cli/sbx_settings_set.yaml b/data/sbx_cli/sbx_settings_set.yaml new file mode 100644 index 000000000000..574d40a6cb45 --- /dev/null +++ b/data/sbx_cli/sbx_settings_set.yaml @@ -0,0 +1,34 @@ +name: sbx settings set +synopsis: Set a setting override +description: |- + Set a user override for a setting. Values are parsed according to the + setting's type: bool (true or false), int, float, string, or raw JSON. + + Administrator constraints apply; conflicting values are rejected. + Environment variables take precedence over user overrides. + + Most changes take effect within about five seconds. This command reports + when a daemon restart is required. +usage: sbx settings set KEY VALUE [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for set +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Route sandbox, daemon, and CLI egress through an upstream proxy + sbx settings set proxy http://proxy.example.com:3128 + + # Pull template and kit images through a registry mirror + sbx settings set platform.images.registryMirror artifactory.corp/docker-remote +see_also: + - sbx settings - Manage Docker Sandboxes settings diff --git a/data/sbx_cli/sbx_settings_unset.yaml b/data/sbx_cli/sbx_settings_unset.yaml new file mode 100644 index 000000000000..d7a1be65cbef --- /dev/null +++ b/data/sbx_cli/sbx_settings_unset.yaml @@ -0,0 +1,27 @@ +name: sbx settings unset +synopsis: Remove a setting override +description: |- + Remove the user override for a setting. + + Administrator policy remains in effect. Otherwise, the setting evaluates from + its environment variable, remote default, or built-in default. +usage: sbx settings unset KEY [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for unset +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Remove the override for a setting + sbx settings unset proxy.daemon +see_also: + - sbx settings - Manage Docker Sandboxes settings diff --git a/data/sbx_cli/sbx_setup.yaml b/data/sbx_cli/sbx_setup.yaml new file mode 100644 index 000000000000..8d3d5e857b2d --- /dev/null +++ b/data/sbx_cli/sbx_setup.yaml @@ -0,0 +1,30 @@ +name: sbx setup +synopsis: | + Detect host configuration and prepare Docker Sandboxes +experimental: true +description: |- + Detect what is already configured on your host and prepare Docker Sandboxes. + + Agent secrets are detected from the built-in agent kit specs and the + env vars set on this host, and accepted secrets are imported into the global + secrets store (the same store as "sbx secret set"). Setup can enable SSH-agent + forwarding using each client's SSH_AUTH_SOCK, or the native Windows OpenSSH + agent pipe when that variable is unset. A fixed endpoint can also be configured. +usage: sbx setup [COMMAND] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for setup +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx setup ssh - Set up SSH client config for the sandbox endpoint diff --git a/data/sbx_cli/sbx_setup_ssh.yaml b/data/sbx_cli/sbx_setup_ssh.yaml new file mode 100644 index 000000000000..31f621311f33 --- /dev/null +++ b/data/sbx_cli/sbx_setup_ssh.yaml @@ -0,0 +1,40 @@ +name: sbx setup ssh +synopsis: Set up SSH client config for the sandbox endpoint +experimental: true +description: |- + Write a generated SSH config + known_hosts and include it from + ~/.ssh/config so "ssh <name>.sbx" connects with no prompts. Named app instances + use "ssh <name>.sbx-<app>" instead. Re-run any time; it's idempotent. + + No SSH client key is needed — authentication is handled by the daemon's local + socket or named pipe (OS user boundary) combined with an active Docker login. Sign in first + (sbx login). On macOS and Windows, use --auto-create to install the fixed codex.sbx and + claude.sbx desktop profiles. Sandboxes are created with the standard resource defaults. +usage: sbx setup ssh [flags] +options: + - name: alias + default_value: '*.sbx' + usage: ssh_config Host pattern to write + - name: auto-create + default_value: "false" + usage: | + enable managed Codex and Claude Desktop profiles on macOS and Windows + - name: help + shorthand: h + default_value: "false" + usage: help for ssh +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx setup ssh + ssh my-sandbox.sbx -- echo hello +see_also: + - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes + - sbx setup ssh remove - Remove SSH config and desktop targets; keep sandboxes diff --git a/data/sbx_cli/sbx_setup_ssh_remove.yaml b/data/sbx_cli/sbx_setup_ssh_remove.yaml new file mode 100644 index 000000000000..eba80dab2eb9 --- /dev/null +++ b/data/sbx_cli/sbx_setup_ssh_remove.yaml @@ -0,0 +1,21 @@ +name: sbx setup ssh remove +synopsis: Remove SSH config and desktop targets; keep sandboxes +experimental: true +usage: sbx setup ssh remove [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for remove +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx setup ssh remove' +see_also: + - sbx setup ssh - Set up SSH client config for the sandbox endpoint diff --git a/data/sbx_cli/sbx_skills.yaml b/data/sbx_cli/sbx_skills.yaml new file mode 100644 index 000000000000..c0de7e4cd9d9 --- /dev/null +++ b/data/sbx_cli/sbx_skills.yaml @@ -0,0 +1,37 @@ +name: sbx skills +synopsis: Manage skills available in sandboxes +experimental: true +description: |- + Manage skills available to agents in Docker Sandboxes. + + Skills are shared across sandboxes by default: the store's entries are linked + into the agent's skills directory read-only, which stays writable so kits can + install skills beside them. Linking happens at container start, so editing an + existing skill is live through the link, while adding a store entry reaches a + running sandbox only on its next start. Removing one takes effect immediately: + the link in a running sandbox stops resolving at once, and the next start is + what clears the stale link away. Use --skills=off when creating a sandbox to + opt out, or --skills=readwrite to mount the store over that directory so the + sandbox's own writes are shared. +usage: sbx skills COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for skills +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx skills add - Add skills from a Git repository + - sbx skills import - Import skills from supported agent directories + - sbx skills ls - List installed skills + - sbx skills rm - Remove installed skills + - sbx skills update - Update skills added from repositories diff --git a/data/sbx_cli/sbx_skills_add.yaml b/data/sbx_cli/sbx_skills_add.yaml new file mode 100644 index 000000000000..f9eee5676e03 --- /dev/null +++ b/data/sbx_cli/sbx_skills_add.yaml @@ -0,0 +1,44 @@ +name: sbx skills add +synopsis: Add skills from a Git repository +experimental: true +description: |- + Install skills from a Git repository for use in Docker Sandboxes. The + repository must contain one or more valid SKILL.md files. + + All discovered skills are installed when --skill is omitted. Use --skill one + or more times, or pass a comma-separated list, to install only named skills. + Replacing an installed skill requires confirmation; use --force to skip + prompts. + + The repository can be specified as a Git URL or as GitHub owner/repository + shorthand. Skills installed with this command can later be refreshed with + 'sbx skills update'. +usage: sbx skills add REPOSITORY [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Overwrite existing skills without prompting + - name: help + shorthand: h + default_value: "false" + usage: help for add + - name: skill + shorthand: s + default_value: '[]' + usage: Add only the named skill (repeatable or comma-separated) +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx skills add https://github.com/anthropics/skills --skill frontend-design + sbx skills add anthropics/skills --skill frontend-design --skill pdf + sbx skills add https://github.com/anthropics/skills --force +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_import.yaml b/data/sbx_cli/sbx_skills_import.yaml new file mode 100644 index 000000000000..cf266c5eac02 --- /dev/null +++ b/data/sbx_cli/sbx_skills_import.yaml @@ -0,0 +1,47 @@ +name: sbx skills import +synopsis: Import skills from supported agent directories +experimental: true +description: |- + Import skills installed for supported coding agents on this machine. + Directories are checked in order: + + 1. ~/.agents/skills + 2. ~/.claude/skills + 3. ~/.config/opencode/skills + 4. ~/.copilot/skills + 5. ~/.cursor/skills + 6. ~/.factory/skills + + The first copy of each skill is used. Importing replaces an existing skill + completely, including removing obsolete files; --force skips confirmation. + Top-level directory symlinks are followed; symlinks within skills are skipped. +usage: sbx skills import [flags] +options: + - name: dry-run + default_value: "false" + usage: | + Preview which skills would be imported without copying anything + - name: force + shorthand: f + default_value: "false" + usage: Overwrite existing skills without prompting + - name: help + shorthand: h + default_value: "false" + usage: help for import +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx skills import + + # Preview without changing anything + sbx skills import --dry-run +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_ls.yaml b/data/sbx_cli/sbx_skills_ls.yaml new file mode 100644 index 000000000000..ef3ffe6c7477 --- /dev/null +++ b/data/sbx_cli/sbx_skills_ls.yaml @@ -0,0 +1,35 @@ +name: sbx skills ls +synopsis: List installed skills +experimental: true +description: List skills available to agents in Docker Sandboxes. +usage: sbx skills ls [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display skill names +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx skills ls + + # Machine-readable output + sbx skills ls --format json +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_rm.yaml b/data/sbx_cli/sbx_skills_rm.yaml new file mode 100644 index 000000000000..629ea47dc5a7 --- /dev/null +++ b/data/sbx_cli/sbx_skills_rm.yaml @@ -0,0 +1,34 @@ +name: sbx skills rm +synopsis: Remove installed skills +experimental: true +description: |- + Remove one or more installed skills from Docker Sandboxes. + + Running agents may be reading installed skills. Removal cannot be undone and + requires confirmation; use --force to skip confirmation in scripts. +usage: sbx skills rm SKILL... [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: help + shorthand: h + default_value: "false" + usage: help for rm +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx skills rm my-skill + + # Skip the confirmation prompt + sbx skills rm --force my-skill +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_update.yaml b/data/sbx_cli/sbx_skills_update.yaml new file mode 100644 index 000000000000..824c388eb79b --- /dev/null +++ b/data/sbx_cli/sbx_skills_update.yaml @@ -0,0 +1,32 @@ +name: sbx skills update +synopsis: Update skills added from repositories +experimental: true +description: |- + Download the latest versions of skills installed with 'sbx skills add'. + + With no names, every skill added from a repository is updated. Specify one or + more names to update only those skills. Skills installed with 'sbx skills + import' must be added from a repository before they can be updated. +usage: sbx skills update [SKILL...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for update +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Update every skill added from a repository + sbx skills update + + # Update one skill + sbx skills update my-skill +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_stop.yaml b/data/sbx_cli/sbx_stop.yaml index 97b32c1b61de..2c0234ac0379 100644 --- a/data/sbx_cli/sbx_stop.yaml +++ b/data/sbx_cli/sbx_stop.yaml @@ -1,19 +1,47 @@ name: sbx stop synopsis: Stop one or more sandboxes without removing them description: |- - Stop one or more running sandboxes without removing them. + Stop one or more running sandboxes without removing them. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". Stopped sandboxes retain their state and can be restarted with "sbx run". -usage: sbx stop SANDBOX [SANDBOX...] + + With --cloud, stop suspends each sandbox in place: its full state (memory + + disk) is preserved, the host is released, and the sandbox keeps its ID. Stop + returns once the request is accepted. Watch the sandbox reach the stopped + state with "sbx --cloud ls". + Restart it — same ID — with "sbx --cloud attach SANDBOX", with + "sbx --cloud run AGENT --name NAME" (also non-interactively with --detach), + or by running its agent again and picking it from the prompt. + + Stop does not create a template and does not delete the sandbox. To capture + a durable, shareable template from a running sandbox instead, use + "sbx --cloud template save SANDBOX TAG" (which leaves the sandbox + running). +usage: sbx stop SANDBOX... [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for stop + - name: json + default_value: "false" + usage: Output in JSON format inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx stop my-sandbox + + # Stop several at once + sbx stop one two see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_template.yaml b/data/sbx_cli/sbx_template.yaml index ca5a6cea2e23..04e508c64c2e 100644 --- a/data/sbx_cli/sbx_template.yaml +++ b/data/sbx_cli/sbx_template.yaml @@ -4,7 +4,15 @@ description: |- Manage sandbox templates. Templates are saved snapshots of sandboxes that can be reused to create new - sandboxes with: sbx run -t TAG AGENT [WORKSPACE] + sandboxes with: sbx run --pull never -t TAG AGENT [WORKSPACE] + + With --cloud: + Manage cloud sandbox templates. + + Reuse a saved template with: sbx --cloud run --template TEMPLATE + + Cloud snapshots and loads typically produce multi-GB artifacts and take + several minutes. See https://docs.docker.com/ai/sandboxes/ for details. usage: sbx template COMMAND options: - name: help @@ -12,12 +20,17 @@ options: default_value: "false" usage: help for template inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. + - sbx template inspect - Show template details - sbx template load - Load an image from a tar file into the sandbox runtime - sbx template ls - List template images - sbx template rm - Remove a template image diff --git a/data/sbx_cli/sbx_template_inspect.yaml b/data/sbx_cli/sbx_template_inspect.yaml new file mode 100644 index 000000000000..a3fd49a6343a --- /dev/null +++ b/data/sbx_cli/sbx_template_inspect.yaml @@ -0,0 +1,37 @@ +name: sbx template inspect +synopsis: Show template details +description: |- + Show full metadata for a single template. + + NAME|ID can be either a template name (resolved to its ID via the server's + ?name= filter) or a template ID (tmpl_*). + + Cloud-only in v1: requires --cloud. +usage: sbx template inspect NAME|ID [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx --cloud template inspect my-template + sbx --cloud template inspect tmpl_abc123 + + # Output in JSON format + sbx --cloud template inspect my-template --json +see_also: + - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_load.yaml b/data/sbx_cli/sbx_template_load.yaml index 0aeef27e2cb6..2857b18814d5 100644 --- a/data/sbx_cli/sbx_template_load.yaml +++ b/data/sbx_cli/sbx_template_load.yaml @@ -5,13 +5,46 @@ description: |- The loaded image can be used as a template for new sandboxes. Tar files are typically created with: sbx template save SANDBOX TAG --output FILE -usage: sbx template load FILE [flags] + + With --cloud: + Upload a tar file as a cloud template. Takes FILE and NAME; NAME must be + unique per account. Uploads can take several minutes. + + --cpus and --memory-mib are required and must match a billable sandbox shape: + + - micro (1 vCPU / 2048 MiB) + - small (2 vCPU / 4096 MiB) + - medium (4 vCPU / 8192 MiB) + - large (8 vCPU / 16384 MiB) + - xl (16 vCPU / 32768 MiB) + + Use --capture-mode disk for a filesystem snapshot, or all to capture memory, + disk, and the microVM checkpoint for faster resume. +usage: sbx template load FILE [NAME] [flags] options: + - name: capture-mode + default_value: disk + usage: | + What gets captured for this template. "disk" (default) captures only the filesystem — cold-boot from a standard OCI image, faster load. "all" captures memory + disk + microVM checkpoint — sub-second TTI on resume, slower load. Only effective with --cloud. + - name: cpus + default_value: "0" + usage: | + vCPUs; with --memory-mib must name a billable shape (required with --cloud) + - name: description + usage: Optional template description (--cloud only) - name: help shorthand: h default_value: "false" usage: help for load + - name: memory-mib + default_value: "0" + usage: | + Memory in MiB; --cpus/--memory-mib must name a billable shape: micro (1 vCPU / 2048 MiB), small (2 vCPU / 4096 MiB), medium (4 vCPU / 8192 MiB), large (8 vCPU / 16384 MiB), xl (16 vCPU / 32768 MiB) (required with --cloud) inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -22,6 +55,15 @@ example: |4- sbx template load C:\Users\me\myimage.tar # Windows # Use the loaded image as a template - sbx run -t myimage:v1.0 claude + sbx run --pull never -t myimage:v1.0 claude + + # Cloud: upload a tar as a cloud-managed template (disk capture, faster load) + sbx --cloud template load /tmp/myimage.tar my-template --cpus 2 --memory-mib 4096 + + # Cloud: capture memory + disk + microVM checkpoint for sub-second resume + sbx --cloud template load /tmp/myimage.tar my-template --cpus 2 --memory-mib 4096 --capture-mode all + + # Cloud: with a description + sbx --cloud template load /tmp/myimage.tar my-template --cpus 2 --memory-mib 4096 --description "Nightly baseline" see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_ls.yaml b/data/sbx_cli/sbx_template_ls.yaml index 90b28d7740aa..91e0f69030e1 100644 --- a/data/sbx_cli/sbx_template_ls.yaml +++ b/data/sbx_cli/sbx_template_ls.yaml @@ -4,6 +4,8 @@ description: | List all template images stored in the sandbox runtime's image store. usage: sbx template ls [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" @@ -11,7 +13,15 @@ options: - name: json default_value: "false" usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display template names inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_template_rm.yaml b/data/sbx_cli/sbx_template_rm.yaml index f0dd4b670cbe..c9a890038c2f 100644 --- a/data/sbx_cli/sbx_template_rm.yaml +++ b/data/sbx_cli/sbx_template_rm.yaml @@ -6,13 +6,30 @@ description: |- The image can be identified by tag (e.g. "myimage:v1.0") or by image ID (full or prefix, e.g. "abc123"). Use "sbx template ls" to see available images and their IDs. -usage: sbx template rm TAG|ID [flags] + + With --cloud: + The template can be identified by its tmpl_* ID or by its human name + (resolved via the server-side ?name= filter). Use "sbx --cloud template ls". +usage: sbx template rm TAG|ID|NAME [flags] options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for rm + - name: json + default_value: "false" + usage: Output in JSON format inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -23,5 +40,11 @@ example: |4- # Remove by image ID (prefix) sbx template rm abc123 + + # Cloud: remove by name + sbx --cloud template rm my-template + + # Cloud: remove by tmpl_* id + sbx --cloud template rm tmpl_abc123 see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_save.yaml b/data/sbx_cli/sbx_template_save.yaml index cc569b3ea58c..20ad4a3a230f 100644 --- a/data/sbx_cli/sbx_template_save.yaml +++ b/data/sbx_cli/sbx_template_save.yaml @@ -1,15 +1,32 @@ name: sbx template save synopsis: Save a snapshot of the sandbox as a template description: |- - Save a snapshot of the sandbox as a template. + Save a sandbox snapshot as a template in the local image store. + Use --pull never when creating a sandbox from the saved template. - The saved image is stored in the sandbox runtime's image store and can be - used as a template for new sandboxes with: sbx run -t TAG AGENT [WORKSPACE] + Use --output to export a tar file for loading on another host with + sbx template load. - Use --output to also export the image to a tar file that can be shared - and loaded on another host with: sbx template load FILE + With --cloud: + Snapshot a running cloud sandbox into a cloud-managed template. The + snapshot can take several minutes for kit-sized images; the command + polls for completion. Use --description to attach a free-form description + to the saved template. + + --capture-mode controls what gets captured: "disk" (default) cold-boots + from the filesystem; "all" captures memory + disk + microVM checkpoint so + subsequent runs resume in sub-second time at the cost of a slower load. + + Cloud snapshots typically produce multi-GB templates and take several + minutes to complete. See https://docs.docker.com/ai/sandboxes/ for the snapshot/load model. usage: sbx template save SANDBOX TAG [flags] options: + - name: capture-mode + default_value: disk + usage: | + What gets captured for this template. "disk" (default) captures only the filesystem — cold-boot from a standard OCI image, faster load. "all" captures memory + disk + microVM checkpoint — sub-second TTI on resume, slower load. Only effective with --cloud. + - name: description + usage: Description for the template (cloud only) - name: help shorthand: h default_value: "false" @@ -18,6 +35,10 @@ options: shorthand: o usage: Also export the image to a tar file inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" @@ -26,7 +47,19 @@ example: |4- # Save as a template for new sandboxes on this host sbx template save my-sandbox myimage:v1.0 + # Create a sandbox from the saved template + sbx run --pull never -t myimage:v1.0 claude ./project + # Also export to a shareable tar file sbx template save my-sandbox myimage:v1.0 --output /tmp/myimage.tar + + # Cloud: snapshot a running cloud sandbox into a cloud-managed template + sbx --cloud template save sbx_abc123 my-snap + + # Cloud: attach a description to the saved template + sbx --cloud template save sbx_abc123 my-snap --description "nightly build" + + # Cloud: capture memory + disk + microVM checkpoint for sub-second resume + sbx --cloud template save sbx_abc123 my-snap --capture-mode all see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_ttl.yaml b/data/sbx_cli/sbx_ttl.yaml new file mode 100644 index 000000000000..10b79eb66590 --- /dev/null +++ b/data/sbx_cli/sbx_ttl.yaml @@ -0,0 +1,45 @@ +name: sbx ttl +synopsis: Show or extend a cloud sandbox's TTL +description: |- + Inspect or extend a cloud sandbox's TTL. + + With one argument, prints the current expiration and the maximum + remaining time before the sandbox's hard 24h-from-creation ceiling. + + With two arguments — a duration prefixed with '+' followed by a sandbox + ID or name — extends the TTL by that amount, subject to the server-enforced + ceiling. The server cannot shorten an expiration, so DURATION must be + positive. Units are Go's duration units (h, m, s, ms, us, ns), in either + case (+2h, +2H, +1h30m). + + SANDBOX may be given by ID (sbx_*) or name, as shown by "sbx --cloud ls". + + Cloud-only: local sandboxes are not TTL-managed. +usage: sbx ttl [+DURATION] SANDBOX [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for ttl + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Show the remaining TTL + sbx --cloud ttl my-sandbox + + # Extend it by two hours + sbx --cloud ttl +2h my-sandbox +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_tui.yaml b/data/sbx_cli/sbx_tui.yaml new file mode 100644 index 000000000000..da672af28499 --- /dev/null +++ b/data/sbx_cli/sbx_tui.yaml @@ -0,0 +1,20 @@ +name: sbx tui +synopsis: Open the interactive TUI dashboard +usage: sbx tui [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for tui +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx tui' +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_version.yaml b/data/sbx_cli/sbx_version.yaml index cdab8a1f1695..ac3f47eb5dcf 100644 --- a/data/sbx_cli/sbx_version.yaml +++ b/data/sbx_cli/sbx_version.yaml @@ -1,15 +1,29 @@ name: sbx version synopsis: Show Docker Sandboxes version information -usage: sbx version +usage: sbx version [flags] options: + - name: format + usage: 'Output format: table, json or yaml' - name: help shorthand: h default_value: "false" usage: help for version + - name: json + default_value: "false" + usage: Output in JSON format inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) - name: debug shorthand: D default_value: "false" usage: Enable debug logging +example: |4- + sbx version + + # Include daemon and build details + sbx version --debug see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_volume.yaml b/data/sbx_cli/sbx_volume.yaml new file mode 100644 index 000000000000..dc371377383b --- /dev/null +++ b/data/sbx_cli/sbx_volume.yaml @@ -0,0 +1,32 @@ +name: sbx volume +synopsis: Manage persistent volumes (cloud-only) +description: |- + Manage persistent volumes for cloud sandboxes. + + Volumes provide persistent storage that survives across sandbox runs. + Data is saved as a snapshot when a sandbox exits, not continuously + synced. If multiple sandboxes mount the same volume concurrently, the + last sandbox to exit wins — its snapshot overwrites the others. + + Volumes are a cloud-only feature; every subcommand requires --cloud. +usage: sbx volume COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for volume +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx volume create - Create a new persistent volume + - sbx volume inspect - Show volume details + - sbx volume ls - List persistent volumes + - sbx volume rm - Remove a persistent volume diff --git a/data/sbx_cli/sbx_volume_create.yaml b/data/sbx_cli/sbx_volume_create.yaml new file mode 100644 index 000000000000..fe3de350db15 --- /dev/null +++ b/data/sbx_cli/sbx_volume_create.yaml @@ -0,0 +1,30 @@ +name: sbx volume create +synopsis: Create a new persistent volume +description: |- + Create a new persistent volume. + + The volume name must be unique per account; an attempt to create a volume + with a name already in use is rejected. +usage: sbx volume create NAME [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for create + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume create my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_inspect.yaml b/data/sbx_cli/sbx_volume_inspect.yaml new file mode 100644 index 000000000000..a699476126bc --- /dev/null +++ b/data/sbx_cli/sbx_volume_inspect.yaml @@ -0,0 +1,25 @@ +name: sbx volume inspect +synopsis: Show volume details +usage: sbx volume inspect NAME [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume inspect my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_ls.yaml b/data/sbx_cli/sbx_volume_ls.yaml new file mode 100644 index 000000000000..2e541113555a --- /dev/null +++ b/data/sbx_cli/sbx_volume_ls.yaml @@ -0,0 +1,29 @@ +name: sbx volume ls +synopsis: List persistent volumes +usage: sbx volume ls [flags] +options: + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format + - name: quiet + shorthand: q + default_value: "false" + usage: Only display volume names +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume ls' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_rm.yaml b/data/sbx_cli/sbx_volume_rm.yaml new file mode 100644 index 000000000000..efa599f5b315 --- /dev/null +++ b/data/sbx_cli/sbx_volume_rm.yaml @@ -0,0 +1,34 @@ +name: sbx volume rm +synopsis: Remove a persistent volume +description: |- + Delete a persistent volume by name. + + Volumes attached to active sandboxes cannot be deleted; detach them + first by stopping or deleting the sandbox(es) that mount the volume. +usage: sbx volume rm NAME [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompt + - name: format + usage: 'Output format: table, json or yaml' + - name: help + shorthand: h + default_value: "false" + usage: help for rm + - name: json + default_value: "false" + usage: Output in JSON format +inherited_options: + - name: cloud + default_value: "false" + usage: | + Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume rm my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/summary.yaml b/data/summary.yaml index 1732712cbf5d..cae0e0b9817d 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -1,3 +1,9 @@ +2FA: + subscription: [Personal, Pro] + for: Individuals +AI Governance Audit Logs: + subscription: [AI Governance] + requires: Docker Sandboxes [0.39.0](/manuals/ai/sandboxes/release-notes.md) or later Activity logs: subscription: [Team, Business] for: Administrators @@ -67,6 +73,8 @@ Buildx metadata warnings: requires: Docker Buildx [0.16.0](https://github.com/docker/buildx/releases/tag/v0.16.0) and later Buildx no default: requires: Docker Buildx [0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4) and later +Buildx no default OCI artifact: + requires: Docker Buildx [0.36.1](https://github.com/docker/buildx/releases/tag/v0.36.1) and later Cache backend API: availability: Experimental Company: @@ -111,6 +119,8 @@ Compose label file: requires: Docker Compose [2.32.2](https://github.com/docker/compose/releases/tag/v2.32.2) and later Compose lifecycle hooks: requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later +Compose pre_start: + requires: Docker Compose [5.3.0](https://github.com/docker/compose/releases/tag/v5.3.0) and later Compose mac address: requires: Docker Compose [2.23.2](https://github.com/docker/compose/releases/tag/v2.23.2) and later Compose menu: @@ -143,6 +153,9 @@ Compose sbom: requires: Docker Compose [2.39.0](https://github.com/docker/compose/releases/tag/v2.39.0) and later Compose SDK: requires: Docker Compose [5.0.0](https://github.com/docker/compose/releases/tag/v5.0.0) and later +Custom roles: + subscription: [Business] + for: Administrators Dev Environments: availability: Beta Docker Build Cloud: @@ -164,6 +177,9 @@ Docker Hardened Images: subscription: [Docker Hardened Images Select or Enterprise] Docker Hardened Images Enterprise: subscription: [Docker Hardened Images Enterprise] +Docker Hardened Images EU data residency: + availability: Early Access + subscription: [Docker Hardened Images Select or Enterprise] Docker Init: requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later Docker Model Runner: @@ -185,6 +201,9 @@ Docker Projects: availability: Beta Docker Sandboxes sbx: availability: Early Access +Docker Sandboxes SSH: + availability: GA + requires: Docker Sandboxes 0.37.0 or later Docker Sandboxes: availability: Experimental requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later @@ -201,6 +220,9 @@ Docker Scout health scores: availability: Beta Docker Scout Mount Permissions: requires: Docker Desktop [4.34.0](/manuals/desktop/release-notes.md#4340) and later +OIDC connections: + subscription: [Team, Business] + for: Administrators Domain management: subscription: [Business] for: Administrators @@ -238,11 +260,17 @@ Jamf Pro: for: Administrators Load by default: requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later +Evaluate policies: + availability: Experimental MSI installer: subscription: [Business] for: Administrators OATs: subscription: [Team, Business] + for: Administrators +PATs: + subscription: [Personal, Pro] + for: Individuals Pay by invoice: subscription: [Team, Business] PKG installer: @@ -263,10 +291,14 @@ SSO: for: Administrators Synchronized file sharing: subscription: [Pro, Team, Business] +Unassociated machines: + for: Administrators + subscription: [Team, Business] USB/IP support: for: Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend VMM: - for: Docker Desktop on Mac with Apple Silicon + availability: Beta + requires: "Docker Desktop 4.86 or later" Wasm workloads: availability: Beta Wasmtime: diff --git a/data/tags.yaml b/data/tags.yaml index cb5bccf7d9d6..755dd7972dca 100644 --- a/data/tags.yaml +++ b/data/tags.yaml @@ -1,42 +1,30 @@ admin: - title: Administration + title: Admin + description: Manage Docker organizations, users, and access controls. ai: title: AI -app-dev: - title: App development -best-practices: - title: Best practices -cloud-services: - title: Cloud services -data-science: - title: Data science + description: Build AI-powered apps, agents, and integrations with Docker. +cicd: + title: CI/CD + description: Automate builds, tests, and deployments in your pipelines. databases: title: Databases -deploy: - title: Deployment -devops: - title: DevOps -dhi: - title: Docker Hardened Images -distributed-systems: - title: Distributed systems -faq: - title: FAQ -frameworks: - title: Frameworks + description: Run and connect to databases in containers. +deployment: + title: Services & infrastructure + description: Run containerized services and set up development infrastructure. labs: - title: Labs -networking: - title: Networking + title: Hands-on labs + description: Interactive, guided labs you can run directly in your browser. +languages: + title: Languages & frameworks + description: Containerize and develop apps in your language of choice. observability: title: Observability -product-demo: - title: Product demo -release-notes: - title: Release notes -secrets: - title: Secrets -testing-with-docker: - title: Testing with Docker -troubleshooting: - title: Troubleshooting + description: Monitor application metrics and traces with containerized tools. +security: + title: Security + description: Harden images, scan vulnerabilities, and secure your supply chain. +testing: + title: Testing + description: Integration testing with real databases and services. diff --git a/data/whats-new.json b/data/whats-new.json new file mode 100644 index 000000000000..2d78c8a9eab1 --- /dev/null +++ b/data/whats-new.json @@ -0,0 +1,87 @@ +{ + "period_start": "2026-08-29", + "period_end": "2026-09-29", + "items": [ + { + "product": "Docker Home", + "title": "Assign licenses to teams", + "description": "Assign a product license to a team so every current and future member receives it. The Licenses page in Docker Home shows available licenses and whether they are assigned to teams or individuals.", + "url": "/accounts/organization/manage/manage-licenses/#teams", + "published": "2026-09-29", + "source_prs": [26205], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Run sandboxes on Docker-managed cloud infrastructure", + "description": "Create and manage cloud sandboxes with the sbx CLI, including cloud-specific credentials, network policies, lifecycle controls, and transfers between local and cloud environments.", + "url": "/ai/sandboxes/cloud/", + "published": "2026-09-24", + "source_prs": [26142, 26157, 26158, 26181], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Manage cloud sandboxes with the API and TypeScript SDK", + "description": "Create cloud sandboxes, run commands, transfer files, and manage images, snapshots, volumes, and secrets from applications and automated workflows.", + "url": "/ai/sandboxes-api/", + "published": "2026-09-24", + "source_prs": [26142, 26168], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Compose sandbox environments with kits v3", + "description": "Build sandbox environments from workload and mixin kits, combine them into reusable kit sets, and publish the result as a container image.", + "url": "/ai/sandboxes/customize/", + "published": "2026-09-24", + "source_prs": [26065, 26157], + "featured": true + }, + { + "product": "Docker Skills", + "title": "Give coding agents guidance with Docker Skills", + "description": "Install Docker's official open-source skills in compatible coding agents to give them guidance for Dockerfiles, Compose applications, and other Docker tasks.", + "url": "/ai/skills/", + "published": "2026-09-24", + "source_prs": [26169], + "featured": true + }, + { + "product": "Docker Sandboxes", + "title": "Share agent skills read-only by default", + "description": "Sandboxes created with version 0.43.0 mount shared agent skills read-only by default. Choose read-only, read-write, or no access when creating a sandbox.", + "url": "/ai/sandboxes/workflows/agent-skills/#shared-store-behavior", + "published": "2026-09-15", + "source_prs": [26098, 26095], + "featured": false + }, + { + "product": "Docker Sandboxes", + "title": "Run agents without mounting host files", + "description": "Create a sandbox without a host workspace mount. Keep agent files inside the sandbox across stops and restarts, and copy files between the sandbox and host when needed.", + "url": "/ai/sandboxes/usage/#choose-a-workspace", + "published": "2026-09-07", + "source_prs": [25902, 26032], + "featured": false + }, + { + "product": "Docker Sandboxes", + "title": "Install and update shared skills from Git repositories", + "description": "Install agent skills from Git repositories into a persistent store shared across sandboxes, and update or remove them with sbx skills.", + "url": "/ai/sandboxes/workflows/agent-skills/", + "published": "2026-09-07", + "source_prs": [25910, 26032], + "featured": false + }, + { + "product": "Docker Build Cloud", + "title": "Use Docker Build Cloud with standard Buildx", + "description": "Buildx 0.37.0 includes the cloud driver, so you can connect to Docker Build Cloud from the standard Buildx CLI plugin without installing a separate client.", + "url": "/build/builders/drivers/cloud/", + "published": "2026-09-03", + "source_prs": [25885], + "featured": false + } + ] +} diff --git a/docker-bake.hcl b/docker-bake.hcl index cd32840eb6c8..7ecf5517b05e 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -40,7 +40,7 @@ target "release" { } group "validate" { - targets = ["lint", "test", "unused-media", "test-go-redirects", "dockerfile-lint", "validate-vendor"] + targets = ["lint", "test", "unused-media", "test-go-redirects", "dockerfile-lint", "validate-vendor", "validate-api-reference"] } target "test" { @@ -76,6 +76,13 @@ target "test-go-redirects" { provenance = false } +target "releaser-test" { + context = "hack/releaser" + target = "releaser-test" + output = ["type=cacheonly"] + provenance = false +} + target "dockerfile-lint" { call = "check" } @@ -162,6 +169,12 @@ target "validate-vendor" { output = ["type=cacheonly"] } +target "validate-api-reference" { + target = "validate-api-reference" + output = ["type=cacheonly"] + provenance = false +} + variable "UPSTREAM_MODULE_NAME" { default = null } diff --git a/docs_engineer.yml b/docs_engineer.yml deleted file mode 100644 index 1d17737da912..000000000000 --- a/docs_engineer.yml +++ /dev/null @@ -1,311 +0,0 @@ -# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/refs/heads/main/agent-schema.json -agents: - root: - model: opus - description: Docker docs platform engineer for tooling and infrastructure - instruction: | - <objective> - Build and maintain the Docker documentation platform. Handle Hugo templates - and shortcodes, frontend tooling (Tailwind CSS v4, Alpine.js), build system - (Docker Bake), CI/CD workflows, and infrastructure. - </objective> - - <context> - ## Directory structure - - content/ - Documentation content (Markdown) - - layouts/ - Hugo templates (baseof.html, shortcodes/, partials/) - - assets/ - CSS and JavaScript source - - data/ - YAML data for CLI references and configuration - - static/ - Static files (images, fonts) - - _vendor/ - Vendored Hugo modules (read-only) - - hack/ - Build scripts and utilities - - ## Technical Stack - - - Hugo static site generator - - Tailwind CSS v4 (standalone CLI, not PostCSS) - - Alpine.js v3.14 with plugins (collapse, focus, persist) - - Material Symbols for icons - - ### Hugo configuration - - URL transformation: /manuals prefix removed from content/manuals/ - - Hugo modules vendor content from upstream repositories - - Vendored content in _vendor/ directory (read-only) - - CLI reference data in data/ directories (generated from upstream) - - ### Build system - - Docker Buildx Bake as primary orchestrator - - Multi-stage Dockerfile with clear separation - - npm for frontend dependencies - - Hugo for site generation - - Pagefind for client-side search - - ### CI/CD - - GitHub Actions for builds and deployment - - AWS S3 + CloudFront for hosting - - Lambda@Edge for redirects - - OIDC authentication (no long-lived credentials) - - Two environments: main (production), lab (staging) - </context> - - <process> - 1. Understand the request - What needs to be built, fixed, or improved? Is this a template, - shortcode, styling, build configuration, or infrastructure change? - - 2. Explore existing patterns - Use filesystem tools to find related code: - - Templates: layouts/, layouts/shortcodes/, layouts/partials/ - - Styles: assets/css/ - - Scripts: assets/js/ - - Build: docker-bake.hcl, Dockerfile - - CI/CD: .github/workflows/ - - Data: data/ directory - - 3. Plan the implementation - Consider: - - How does this fit with existing architecture? - - What files need to be modified? - - Are there similar patterns to follow? - - Will this affect the build or deployment? - - 4. Implement the changes - Write code following established patterns. Test locally when possible. - - 5. Test and validate - Use the build tool to build the site, then use the validate tool to - check for issues - - 6. Document if needed - Update technical documentation or comments for complex changes. - </process> - - <rules> - <templates> - - Follow Go template syntax: {{ ... }} - - Shortcodes use {{< shortcode >}} not {{% shortcode %}} - - Access page context: .Page, .Inner, .Params - - Use partials for reusable components: {{ partial "name.html" . }} - - Use Hugo functions: resources.Get, resources.Match, dict, slice - - Check for nil before accessing: {{ with .Param "key" }}...{{ end }} - </templates> - - <styling> - - Entry point: assets/css/style.css - - Theme configuration: assets/css/theme.css with @theme inline - - Custom properties defined with CSS variables - - Class scanning from hugo_stats.json (purging) - - Use @layer utilities for custom utilities - - Typography plugin: prose classes for content - - Dark mode: use dark: prefix for dark theme styles - </styling> - - <interactivity> - - Initialize with x-data on parent element - - Use x-init for setup, x-show for visibility - - State management: Alpine.store() for global state - - Persist with x-persist directive (uses localStorage) - - Event handling: @click, @change, @input - - Use $refs for DOM access, $dispatch for events - - Combine with Hugo: generate x-data from page data - </interactivity> - - <build> - - Use docker buildx bake for all builds - - Target naming: lowercase, hyphen-separated - - Cache dependencies: COPY package*.json before npm install - - Multi-stage builds: separate concerns (build, test, release) - - Output handling: use --output or --set flags - - Variables: pass via --set or environment variables - </build> - - <validation> - - Use the validate tool to verify your changes - - Check specific targets: lint, vale, test, unused-media - - Fix markdownlint errors in content files - - Fix htmltest errors (broken links, missing alt text) - - Validate redirects with test-go-redirects - </validation> - - <modules> - - Update go.mod for version changes - - Run VENDOR_MODULE=<module>@<version> docker buildx bake vendor - - Verify with docker buildx bake validate-vendor - - Commit both go.mod and _vendor/ changes - - Never edit _vendor/ content directly - </modules> - - <testing> - - Check that the site builds using the build tool - - Test and validate using the validate tool - </testing> - </rules> - - <examples> - Resource loading: - ``` - {{- $css := resources.Get "css/style.css" - | css.TailwindCSS - | minify - | fingerprint }} - <link rel="stylesheet" href="{{ $css.Permalink }}"> - ``` - - Conditional rendering: - ``` - {{- with .Param "key" }} - {{ . }} - {{- end }} - ``` - - Iteration: - ``` - {{- range .Pages }} - {{ .Title }} - {{- end }} - ``` - - Shortcode structure: - ``` - {{- $param := .Get "param" -}} - <div class="component"> - {{ .Inner }} - </div> - ``` - - Alpine.js with Hugo data: - ``` - <div x-data='{{ dict "items" .Params.items | jsonify }}'> - <template x-for="item in items"> - <div x-text="item.name"></div> - </template> - </div> - ``` - - Tailwind custom utilities: - ```css - @layer utilities { - .custom-class { - @apply flex items-center gap-2; - } - } - ``` - - Docker Bake target: - ```hcl - target "name" { - dockerfile = "Dockerfile" - target = "stage-name" - output = ["type=local,dest=output/"] - args = { - KEY = "value" - } - } - ``` - </examples> - - <reference> - Key architectural patterns and entry points: - - Dual HTML/Markdown publishing: - Pages are published in both HTML and Markdown formats via Hugo's output - formats configuration (hugo.yaml lines 89-94). Each page/section outputs - to both formats. Markdown layouts in layouts/_default/*.markdown.md use - .RenderShortcodes to render shortcodes while preserving markdown - structure. Lambda@Edge on CloudFront performs content negotiation, - serving markdown when Accept: text/markdown header is present. This - enables AI agents to consume documentation as structured markdown. - - AI agent support files: - - metadata.json: Site root JSON file listing all page routes with titles, - descriptions, keywords, and tags. Generated by - layouts/index.metadata.json - - llms.txt: Structured markdown index of all pages grouped by section. - Generated by layouts/_default/index.llms.txt. Follows llms.txt standard - for LLM discovery - - redirects.json: All site redirects for Lambda@Edge routing - - Post-build processing: - hack/flatten-and-resolve.js runs after Hugo build to resolve cross-links - and flatten directory structure. Processes both HTML and markdown output - formats. Critical for correct link resolution across dual formats. - - Hugo module vendoring: - Content is vendored from upstream repos (docker/cli, moby/buildkit, etc.) - into _vendor/ directory. These files are read-only - changes must go - upstream. CLI reference data is generated into data/ directories from - upstream YAML. Manage with: VENDOR_MODULE=<module>@<version> make vendor - - URL transformation: - The /manuals prefix is removed from published URLs via hugo.yaml - permalinks configuration. content/manuals/docker-desktop/install.md - becomes /docker-desktop/install/ on the live site. Critical for link - resolution and redirects. - - Client-side search with Pagefind: - Static search index is built post-Hugo by the pagefind stage in - Dockerfile. Runs after Hugo build completes. Search is entirely - client-side JavaScript, no server required. - - Template entry points: - - layouts/_default/baseof.html: Base template wrapping all pages - - layouts/_default/single.markdown.md: Markdown output for pages - - layouts/_default/list.markdown.md: Markdown output for sections - - layouts/shortcodes/: Reusable components (tabs, accordion, include) - - layouts/partials/: Template fragments (head, header, footer) - - Frontend entry points: - - assets/css/style.css: Main CSS (@import tailwindcss) - - assets/css/theme.css: Tailwind theme configuration (@theme inline) - - assets/js/src/alpine.js: Alpine.js initialization - - Build system: - - docker-bake.hcl: All build targets - - Dockerfile: Multi-stage build definition - - Key targets: release (production), validate (all checks), vendor - (update modules) - - Configuration files: - - hugo.yaml: Hugo configuration (modules, permalinks, markup, output - formats) - - go.mod: Hugo module versions - - package.json: Frontend dependencies - </reference> - - <reporting> - Work silently without narration. - - No "Let me", "Now I'll", "I'm going to" phrases - - Don't explain before doing - just execute - - Keep communication concise. Report only essential findings and blockers. - </reporting> - - <success_criteria> - - Code follows established patterns - - Changes tested with build tool - - Validation passes (validate tool) - - No regressions introduced - - Complex changes documented - </success_criteria> - - toolsets: - - type: filesystem - - type: fetch - - type: shell - - type: todo - - type: script - shell: - validate: - cmd: "docker buildx bake validate > .validation.log 2>&1" - description: | - Run all validation checks (lint, vale, test, etc.) - Output written to .validation.log - read this file to see results - build: - cmd: "docker buildx bake release" - description: Build production site with Hugo and all assets - -models: - opus: - provider: anthropic - model: claude-opus-4-5 - temperature: 0.3 diff --git a/go.mod b/go.mod index 426ba2e994f1..7f985a98c76e 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/docker/docs -go 1.26.0 +go 1.26.8 // This go.mod file is used by hugo to vendor documentation from upstream // repositories. Use the "require" section to specify the version of the @@ -8,18 +8,20 @@ go 1.26.0 // // Make sure to add an entry in the "tools" section when adding a new repository. require ( - github.com/docker/buildx v0.34.1 - github.com/docker/cli v29.5.1+incompatible - github.com/docker/compose/v5 v5.1.4 + github.com/docker/buildx v0.38.1 + github.com/docker/cli v29.8.2+incompatible + github.com/docker/compose/v5 v5.6.1 + github.com/docker/docker-agent v1.126.0 github.com/docker/model-runner v1.1.36 - github.com/moby/buildkit v0.30.0 - github.com/moby/moby/api v1.54.2 + github.com/moby/buildkit v0.34.0 + github.com/moby/moby/api v1.56.1 ) tool ( github.com/docker/buildx github.com/docker/cli github.com/docker/compose/v5 + github.com/docker/docker-agent github.com/docker/model-runner github.com/docker/scout-cli github.com/moby/buildkit diff --git a/go.sum b/go.sum index 4f3fc44d33b4..22669ab73121 100644 --- a/go.sum +++ b/go.sum @@ -2,6 +2,7 @@ github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEK github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E= github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY= github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU= +github.com/Microsoft/go-winio v0.6.3-0.20251027160822-ad3df93bed29 h1:0kQAzHq8vLs7Pptv+7TxjdETLf/nIqJpIB4oC6Ba4vY= github.com/alecthomas/chroma/v2 v2.14.0 h1:R3+wzpnUArGcQz7fCETQBzO5n9IMNi13iIs46aU4V9E= github.com/alecthomas/chroma/v2 v2.14.0/go.mod h1:QolEbTfmUHIMVpBqxeDnNBj2uoeI4EbYP4i6n68SG4I= github.com/alecthomas/chroma/v2 v2.20.0 h1:sfIHpxPyR07/Oylvmcai3X/exDlE8+FA820NTz+9sGw= @@ -36,6 +37,11 @@ github.com/containerd/containerd/v2 v2.2.1/go.mod h1:NR70yW1iDxe84F2iFWbR9xfAN0N github.com/containerd/containerd/v2 v2.2.2 h1:mjVQdtfryzT7lOqs5EYUFZm8ioPVjOpkSoG1GJPxEMY= github.com/containerd/containerd/v2 v2.2.2/go.mod h1:5Jhevmv6/2J+Iu/A2xXAdUIdI5Ah/hfyO7okJ4AFIdY= github.com/containerd/containerd/v2 v2.2.3 h1:mOBRLaHGvmgy0bRo1Sg6OD8ugMKZIvCoWWMeMMygliA= +github.com/containerd/containerd/v2 v2.2.4 h1:8x2UdXqww7NYqGNabQ7i1nAgB5LegzjC9KQzO/900iA= +github.com/containerd/containerd/v2 v2.2.5 h1:KTFzB02LviYmmfRmz8r9UFd+n6YlddVFK+5lbgQXUTU= +github.com/containerd/containerd/v2 v2.3.3 h1:MUNBVVBTBpPll7KPh5GTvkC3cfG03PQLAHVdsUoue9k= +github.com/containerd/containerd/v2 v2.3.4 h1:c2PJo/9UGVdiiw8SwrxuLxWGY+9b3jQ6Xp9zntneIvI= +github.com/containerd/containerd/v2 v2.3.6 h1:huoqZXaDW1x1kgPvFC4rMwxv92vUJnqgq7I5b1rSddM= github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI= github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M= github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE= @@ -48,6 +54,7 @@ github.com/containerd/platforms v1.0.0-rc.3 h1:YdvwaHtrN6wHcGJ2mYRYP3Nso8OcysuqF github.com/containerd/platforms v1.0.0-rc.3/go.mod h1:gw0R+alP3nFQPh1L4K9bv13fRWeeyokLGLu2fKuqI10= github.com/containerd/platforms v1.0.0-rc.4 h1:M42JrUT4zfZTqtkUwkr0GzmUWbfyO5VO0Q5b3op97T4= github.com/containerd/platforms v1.0.0-rc.4/go.mod h1:lKlMXyLybmBedS/JJm11uDofzI8L2v0J2ZbYvNsbq1A= +github.com/containerd/platforms v1.0.0-rc.5 h1:vXd569rDrz8LeMXzAnBsy6LADV5YtsD8oyaRarxdmSU= github.com/containerd/stargz-snapshotter v0.17.0 h1:djNS4KU8ztFhLdEDZ1bsfzOiYuVHT6TgSU5qwRk+cNc= github.com/containerd/stargz-snapshotter v0.18.2 h1:Ev/sxfQUjwzJQ9eqy3XzttcQ3osMIqkQgMYlcET+10M= github.com/containerd/stargz-snapshotter/estargz v0.17.0 h1:+TyQIsR/zSFI1Rm31EQBwpAA1ovYgIKHy7kctL3sLcE= @@ -55,6 +62,7 @@ github.com/containerd/stargz-snapshotter/estargz v0.17.0/go.mod h1:s06tWAiJcXQo9 github.com/containerd/stargz-snapshotter/estargz v0.18.2 h1:yXkZFYIzz3eoLwlTUZKz2iQ4MrckBxJjkmD16ynUTrw= github.com/containerd/typeurl/v2 v2.2.3 h1:yNA/94zxWdvYACdYO8zofhrTVuQY73fFU1y++dYSw40= github.com/containerd/typeurl/v2 v2.2.3/go.mod h1:95ljDnPfD3bAbDJRugOiShd/DlAAsxGtUBhJxIn7SCk= +github.com/containerd/typeurl/v2 v2.3.0 h1:HZHPhRWo5XMy3QGQoPrUzbW/2ckwjfweHmOwlkIrPAQ= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -79,6 +87,22 @@ github.com/docker/buildx v0.34.0 h1:ivBYUNCMKMOwqCziC66p79dNkd8mv+DSrnyrY9PY9vQ= github.com/docker/buildx v0.34.0/go.mod h1:RG8352TWR2gg8P7uqu1ZvlSpqxUcnVvGfjqQsKpmSAY= github.com/docker/buildx v0.34.1 h1:gDnnCPmnbPt/5FTABZIhTlBc6kYibWNyVJzE29Mb5yM= github.com/docker/buildx v0.34.1/go.mod h1:RG8352TWR2gg8P7uqu1ZvlSpqxUcnVvGfjqQsKpmSAY= +github.com/docker/buildx v0.35.0 h1:5r/ZcAC0s2oZ1XOJHvYFYbj44I4rxRsIdfsRBeXClks= +github.com/docker/buildx v0.35.0/go.mod h1:kO/9ZBoZmhi1OsZbeLJqWclckB2TKu/yeW6aj6xxdt0= +github.com/docker/buildx v0.36.0 h1:5UYbvkIXhkjiRZG15ZoWuA1BIuFatexA9yeL+b72MpM= +github.com/docker/buildx v0.36.0/go.mod h1:APOldMT9ejTIiYJ44OxhFX1zt+MM1cR9zz4DQLq8qLw= +github.com/docker/buildx v0.36.1 h1:U7JTUSSeooFXbG+0HcI+CMjEIkvuZgJegXRZ1q7K63Q= +github.com/docker/buildx v0.36.1/go.mod h1:pkpx66TqJD4HOS65fORu9MYBEDbeiRxnGdN3VpH8SPM= +github.com/docker/buildx v0.37.0 h1:DYvrhY0P/qhJkqCQHH7qbcL4torLNoI2lgayxdmU0DY= +github.com/docker/buildx v0.37.0/go.mod h1:caF6XsZtJ9OAE22LVRsl2OUz5eL+P0+cS2YrnKhuryA= +github.com/docker/buildx v0.37.1 h1:uFwAbgh1znGPz7YCg/tr6dHuR/+OqxAWc1YMxxAO/m4= +github.com/docker/buildx v0.37.1/go.mod h1:caF6XsZtJ9OAE22LVRsl2OUz5eL+P0+cS2YrnKhuryA= +github.com/docker/buildx v0.37.2 h1:6EYElyvQe7aPnp2yDmCLa4/0jXYs8dAHfWKVO6dsFwA= +github.com/docker/buildx v0.37.2/go.mod h1:3CTKuzEyWIMz4TdAutpRjEfNpAp8mhK62ssOuwLWG4w= +github.com/docker/buildx v0.38.0 h1:LKfznm3wgm0hYaQDkiuoK9hyDS1GU/GChnXYsBr3A00= +github.com/docker/buildx v0.38.0/go.mod h1:4lEDxmaYDJ17HtXTND9A53BaDoHCJbk5WUgcmfipN7Q= +github.com/docker/buildx v0.38.1 h1:7J7nReQndOnDTUFjun6otmQqehoi9sCOvRwFjkngYlc= +github.com/docker/buildx v0.38.1/go.mod h1:4lEDxmaYDJ17HtXTND9A53BaDoHCJbk5WUgcmfipN7Q= github.com/docker/cli v29.1.2+incompatible h1:s4QI7drXpIo78OM+CwuthPsO5kCf8cpNsck5PsLVTH8= github.com/docker/cli v29.1.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v29.1.5+incompatible h1:GckbANUt3j+lsnQ6eCcQd70mNSOismSHWt8vk2AX8ao= @@ -97,6 +121,20 @@ github.com/docker/cli v29.4.3+incompatible h1:u+UliYm2J/rYrIh2FqHQg32neRG8GjbvNu github.com/docker/cli v29.4.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v29.5.1+incompatible h1:NiufLAJoRcPauFoBNYthfuM4REFwM8H2h9xnLABNHGs= github.com/docker/cli v29.5.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.5.3+incompatible h1:nbEFfz774vBwQ5KRYv7c/AghjReqnGISvrRhzjV0evs= +github.com/docker/cli v29.5.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.6.0+incompatible h1:nw9himxMMZ7eIeherJNlKQq+acnlzGgHd+4uf10QRSc= +github.com/docker/cli v29.6.0+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.6.1+incompatible h1:oO7F4nn3Ovr/5TlfTUWFbMwBSS/B7Xs6Epv26gBrUP8= +github.com/docker/cli v29.6.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.6.2+incompatible h1:/bjePvcbbFTnRrMfWJBY7AjfICdsiLVgHn6LwTVOcqw= +github.com/docker/cli v29.6.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.7.1+incompatible h1:ILZpP6B7fedIr6ANy824QkDp1WMJuouIq0O2SrBkB2w= +github.com/docker/cli v29.7.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.7.2+incompatible h1:dlkwallR8XqfeVnA2ELEhdwvb4lsSwuB4IgsG8Q9cLY= +github.com/docker/cli v29.7.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.8.2+incompatible h1:2zgdFuoFst2T80oS42vhKGxkd0JRo305eIEKTsxR7pQ= +github.com/docker/cli v29.8.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/compose/v5 v5.0.0 h1:J2uMCzJ/5xLcoIVVXvMmPe6HBzVQpmJThKa7Qk7Xldc= github.com/docker/compose/v5 v5.0.0/go.mod h1:BurapGv8zmYnsbSmlpCz5EU2Pi3YFV/PjeUnoFpcw64= github.com/docker/compose/v5 v5.0.1 h1:5yCjDJbwUqcuI+6WNFHNWz2/3vyBDsNnfe8LlFjyxEc= @@ -107,14 +145,45 @@ github.com/docker/compose/v5 v5.1.2 h1:HxtfGZA0DESw/+hvrNJDjM8VKmCond7OkmgVJCHku github.com/docker/compose/v5 v5.1.2/go.mod h1:JJ2H+lRSugOH50/zxCbkBwN8jU91qDtRCp7gEHWZdgo= github.com/docker/compose/v5 v5.1.4 h1:72mGZplTVlbq6JxxhCW/bX2o1h+tT8mwt7mc+QtmA6o= github.com/docker/compose/v5 v5.1.4/go.mod h1:ImZiWTwIFm7BziHjX2MZVzwOiIkClXRzv+rkU18lQoc= +github.com/docker/compose/v5 v5.2.0 h1:WuZgtAM91BjFWy7xMKcM2Huq9OksVqRgkgBKFiEXs2Q= +github.com/docker/compose/v5 v5.2.0/go.mod h1:tjYsBMooQQZ8XGtVoUnc+/T9peXtkMmTdmMakW8/ZXE= +github.com/docker/compose/v5 v5.3.0 h1:JdcwUbJi2al3vOi+PZmjqPzHBIYyezZ9OaCXLO5I6f0= +github.com/docker/compose/v5 v5.3.0/go.mod h1:iZngpxvhuLn2VYsKS5cIa/5bTPKIdLGi5ZyjcdHBaZQ= +github.com/docker/compose/v5 v5.3.1 h1:rZiPwrtg1dBmVGcHiioLtzCS+TcvZq81zl0zs2BwtbE= +github.com/docker/compose/v5 v5.3.1/go.mod h1:qTcMBinqXyp2CQT6OJfBqtG8UPfYgOk1rwqIGYKLpGk= +github.com/docker/compose/v5 v5.4.0 h1:i0xFmVvWv9QILfRE2PD07GmQqJYjpYAGutafIrJLURE= +github.com/docker/compose/v5 v5.4.0/go.mod h1:bNeEncwZhG0F4MN+0zgln4EA2ILqGZC7knRI8QYJz9U= +github.com/docker/compose/v5 v5.5.0 h1:B5Eh5CtlbscCMlbyMydbEj3rpIuP9GthdD7PC0IsvgQ= +github.com/docker/compose/v5 v5.5.0/go.mod h1:5yn5qs7G7V7OZc1Kkd6wLz72Le0C45xLNJQ7dgASvMk= +github.com/docker/compose/v5 v5.5.1 h1:saWlMxB0tfQ+FVUlWGIUjLvR0jF5cfTU18KI5zKLD/M= +github.com/docker/compose/v5 v5.5.1/go.mod h1:I1MDqH4C/vHlbaWcA6A9pKTOBx9vhtQO3hx3e45igDE= +github.com/docker/compose/v5 v5.6.0 h1:WCDEV0D1CtZLyPdklHdEjFBnCStosBYkfsD3tvM/ITU= +github.com/docker/compose/v5 v5.6.0/go.mod h1:NLnbMzshDO3QlhgzMxd9sm981O1yLjPybL1WGStUesI= +github.com/docker/compose/v5 v5.6.1 h1:Ddp7wM/MXZQ3w1+sDuEEZXn3HcLv7QM4epFaouu4vds= +github.com/docker/compose/v5 v5.6.1/go.mod h1:NLnbMzshDO3QlhgzMxd9sm981O1yLjPybL1WGStUesI= github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk= github.com/docker/distribution v2.8.3+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w= github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaftjlSWt4AFexzM= github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk= +github.com/docker/docker-agent v1.96.0 h1:wt018652ejWtHpMOdhvjwIxaeI46rc6o8snqb9QsmiI= +github.com/docker/docker-agent v1.96.0/go.mod h1:PJlLIntWPY0KPepCIeR4+WRo2fmQnmnONYBmb/ULorM= +github.com/docker/docker-agent v1.103.0 h1:hmS2u0fU4MMyUnXrjJlhcfjpBUzkBEBM9/DrmL0yTpY= +github.com/docker/docker-agent v1.103.0/go.mod h1:KUYwjuxrs2N3BBrAQ6CMNPVQxOfoZoLUYpbxyGTM02w= +github.com/docker/docker-agent v1.110.0 h1:B5LJRkEvIk1WLojMR09gD6ZAD2hD43SIRSbjKs+yyc4= +github.com/docker/docker-agent v1.110.0/go.mod h1:TcrFxPYbc9SL0ouAcb/YwwjePfS0ULYkzfTJkvDUfzY= +github.com/docker/docker-agent v1.120.0 h1:aogSNNlZWiL/6EYmrXhEtkqIgEcL7wt2bhYItgjan4o= +github.com/docker/docker-agent v1.120.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= +github.com/docker/docker-agent v1.122.0 h1:xOei5d7L1M0stvZNwULnOssOS4CzDRE2Xj7k192rS3Q= +github.com/docker/docker-agent v1.122.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= +github.com/docker/docker-agent v1.124.0 h1:dNVrrRozYq5IMgokjaSm6grYReEMP1inrEaHVnVQiyg= +github.com/docker/docker-agent v1.124.0/go.mod h1:CyLlU/NVcq3kSjffVzRKNaO0XIngqKPOxhgmbru+LWE= +github.com/docker/docker-agent v1.126.0 h1:GjX84SHcvS4Txo7dGjatWhKGFLNpDqKcGAoIsyvfj40= +github.com/docker/docker-agent v1.126.0/go.mod h1:K38q6CsnSTHDOrLP46HLGhKwv3i+vjmu33cjmjpkAvg= github.com/docker/docker-credential-helpers v0.9.3 h1:gAm/VtF9wgqJMoxzT3Gj5p4AqIjCBS4wrsOh9yRqcz8= github.com/docker/docker-credential-helpers v0.9.3/go.mod h1:x+4Gbw9aGmChi3qTLZj8Dfn0TD20M/fuWy0E5+WDeCo= github.com/docker/docker-credential-helpers v0.9.5 h1:EFNN8DHvaiK8zVqFA2DT6BjXE0GzfLOZ38ggPTKePkY= github.com/docker/docker-credential-helpers v0.9.5/go.mod h1:v1S+hepowrQXITkEfw6o4+BMbGot02wiKpzWhGUZK6c= +github.com/docker/docker-credential-helpers v0.9.8 h1:bIREROb7So6PRlq6KTtdS9MPEjC29OQRkFNlvK2OX8Q= github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94= github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE= github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c= @@ -149,6 +218,7 @@ github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/ github.com/fatih/color v1.19.0 h1:Zp3PiM21/9Ld6FzSKyL5c/BULoe/ONr9KlbYVOfG8+w= github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg= github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc= github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ= github.com/fsnotify/fsnotify v1.6.0/go.mod h1:sl3t1tCWJFWoRz9R8WJCbQihKKwmorjAbSClcnxKAGw= github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k= @@ -168,6 +238,7 @@ github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69 github.com/google/go-containerregistry v0.20.6 h1:cvWX87UxxLgaH76b4hIvya6Dzz9qHB31qAwjAohdSTU= github.com/google/go-containerregistry v0.20.6/go.mod h1:T0x8MuoAoKX/873bkeSfLD2FAkwCDf9/HZgsFJ02E2Y= github.com/google/go-containerregistry v0.20.7 h1:24VGNpS0IwrOZ2ms2P1QE3Xa5X9p4phx0aUgzYzHW6I= +github.com/google/go-containerregistry v0.21.6 h1:T+yqQIlJXKrM98Om4DlW3GoWQAmhZuLMwoDOvVrtiUM= github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= @@ -208,6 +279,8 @@ github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxh github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE= github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ= github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao= +github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk= +github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8= github.com/kolesnikovae/go-winjob v1.0.0 h1:OKEtCHB3sYNAiqNwGDhf08Y6luM7C8mP+42rp1N6SeE= github.com/kolesnikovae/go-winjob v1.0.0/go.mod h1:k0joOLP3/NBrRmDQjPV2+oN1TPmEWt6arTNtFjVeQuM= github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY= @@ -240,6 +313,20 @@ github.com/moby/buildkit v0.29.0 h1:wxLEFbCOJntEDjSNNN2YWd8zxltZxT5muDQ0LzpbtpU= github.com/moby/buildkit v0.29.0/go.mod h1:Dmv2FeDe34t75QuzeU87rBoZpAAkcpT5zeu4hXzmASc= github.com/moby/buildkit v0.30.0 h1:OsK8T3BaYH52UNStpKd7gytDtHWWt2Fawak/lAPWatU= github.com/moby/buildkit v0.30.0/go.mod h1:k2wuw5ddaOqzh58RLt+mBn2XhK34gi6+gd0faONQ1xU= +github.com/moby/buildkit v0.31.0 h1:hMUAbQGgjtzJDDOZ6o7MQk5XBZkBTyzLWEvnjguHHQI= +github.com/moby/buildkit v0.31.0/go.mod h1:YM5iNEbNCc6L1Zt3YWFB/aXNLufvf4Rcu0DPlc9HwQg= +github.com/moby/buildkit v0.32.0 h1:slXarYQoMo4cp2d9x30M9t0L4R+c0CVMov+5P1hhiHY= +github.com/moby/buildkit v0.32.0/go.mod h1:Y10FBWvqxl/Wmhdzjee1Y2wQfjifTiwxENIUdaVNdME= +github.com/moby/buildkit v0.32.1 h1:gIygb6hNTKrSh3PRIOmXJGNZJQf7n7mmVxzo1omKjAM= +github.com/moby/buildkit v0.32.1/go.mod h1:0GB/EJ1d+4VIVqIAgy3asaoGkVXy7IrDfVy7mPhOvg8= +github.com/moby/buildkit v0.32.2 h1:Sfy7+u6dUv/2yuBc9KCoK70Re8atuV8aPZ5UOC068Vc= +github.com/moby/buildkit v0.32.2/go.mod h1:0GB/EJ1d+4VIVqIAgy3asaoGkVXy7IrDfVy7mPhOvg8= +github.com/moby/buildkit v0.33.0 h1:zBbt1FiMcTB/oFg1iCNcKa83k5Rn8MGcVjXFIcfYhuQ= +github.com/moby/buildkit v0.33.0/go.mod h1:uNKSZnfMk1aSa18JiCR5BT68M/3jIDGo6XuAByUK3ek= +github.com/moby/buildkit v0.33.1 h1:UUrdifmRdRadykO+f5l8BT1CseUXst2sJHV7AmkjjxE= +github.com/moby/buildkit v0.33.1/go.mod h1:584wW8T/WG4O+lpXUCoDaWEc5e+rTGC3iP+l9mNcX8E= +github.com/moby/buildkit v0.34.0 h1:bG5h2y1s5IVvc/uSGo6hVlYbd2eXVFRuADl9Zf+jeJM= +github.com/moby/buildkit v0.34.0/go.mod h1:e+Za70y2a3nL1U2Y0P8TvhPyKp2Ok2NS+Q4siSArDiM= github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0= github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo= github.com/moby/locker v1.0.1 h1:fOXqR41zeveg4fFODix+1Ch4mj/gT0NE1XJbp/epuBg= @@ -254,6 +341,12 @@ github.com/moby/moby/api v1.54.1 h1:TqVzuJkOLsgLDDwNLmYqACUuTehOHRGKiPhvH8V3Nn4= github.com/moby/moby/api v1.54.1/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs= github.com/moby/moby/api v1.54.2 h1:wiat9QAhnDQjA7wk1kh/TqHz2I1uUA7M7t9SAl/JNXg= github.com/moby/moby/api v1.54.2/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs= +github.com/moby/moby/api v1.55.0 h1:2/sexvQyqIWS8pRSCFddBfpW2qE7vR7FCL+vN8pxwMc= +github.com/moby/moby/api v1.55.0/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs= +github.com/moby/moby/api v1.56.0 h1:GQzua3NA599ASSIICx0iFgiJeO9YkdDARvQsm23ZZuQ= +github.com/moby/moby/api v1.56.0/go.mod h1:sZ+THbVWkjOmBPPfbnzdD/G1LuIexWhqlSHHPTDQ1Uk= +github.com/moby/moby/api v1.56.1 h1:PpWkvVPB7Fr/No8w+TfyJ/I6rWZ2YPZhT3JorIg+06c= +github.com/moby/moby/api v1.56.1/go.mod h1:sZ+THbVWkjOmBPPfbnzdD/G1LuIexWhqlSHHPTDQ1Uk= github.com/moby/moby/client v0.2.1 h1:1Grh1552mvv6i+sYOdY+xKKVTvzJegcVMhuXocyDz/k= github.com/moby/moby/client v0.2.1/go.mod h1:O+/tw5d4a1Ha/ZA/tPxIZJapJRUS6LNZ1wiVRxYHyUE= github.com/moby/moby/client v0.2.2 h1:Pt4hRMCAIlyjL3cr8M5TrXCwKzguebPAc2do2ur7dEM= @@ -262,6 +355,7 @@ github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs= github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU= github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko= +github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8= github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ= github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc= github.com/modelpack/model-spec v0.0.7 h1:3fAxau4xUqF0Pf1zzFC5lItF0gEaiXLxaCcPAH8PW8I= @@ -297,14 +391,19 @@ github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINE github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk= github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE= +github.com/prometheus/client_model v0.6.3 h1:O0jaTVAYNxTHYInEPFJt5I3+sN8zqBtVMPTB1qyxiEo= github.com/prometheus/common v0.67.1 h1:OTSON1P4DNxzTg4hmKCc37o4ZAZDv0cfXLkOt0oEowI= github.com/prometheus/common v0.67.1/go.mod h1:RpmT9v35q2Y+lsieQsdOh5sXZ6ajUGC8NjZAmr8vb0Q= github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4= github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw= +github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY= +github.com/prometheus/common v0.71.0 h1:9KDAKb7Mj3HEVKyFCK6Dc/HIwlBzZIN2l7/lrHl3KK8= github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg= github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is= github.com/prometheus/procfs v0.17.0 h1:FuLQ+05u4ZI+SS/w9+BWEM2TXiHKsUQ9TADiRH7DuK0= github.com/prometheus/procfs v0.17.0/go.mod h1:oPQLaDAMRbA+u8H5Pbfq+dl3VDAvHxMUOVhe0wYB2zw= +github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc= +github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI= github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ= @@ -314,6 +413,7 @@ github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w= github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g= +github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo= github.com/smallnest/ringbuffer v0.0.0-20241116012123-461381446e3d h1:3VwvTjiRPA7cqtgOWddEL+JrcijMlXUmj99c/6YyZoY= github.com/smallnest/ringbuffer v0.0.0-20241116012123-461381446e3d/go.mod h1:tAG61zBM1DYRaGIPloumExGvScf08oHuo0kFoOqdbT0= github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s= @@ -328,6 +428,7 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/vbatts/tar-split v0.12.2 h1:w/Y6tjxpeiFMR47yzZPlPj/FcPLpXbTUi/9H7d3CPa4= github.com/vbatts/tar-split v0.12.2/go.mod h1:eF6B6i6ftWQcDqEn3/iGFRFRo8cBIMSJVOpnNdfTMFA= +github.com/vbatts/tar-split v0.12.3 h1:Cd46rkGXI3Td4yrVNwU8ripbxFaQbmesqhjBUUYAJSw= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM= github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= @@ -346,6 +447,8 @@ go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbE go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 h1:RbKq8BG0FI8OiXhBfcRtqqHcZcka+gU3cskNuf05R18= go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0/go.mod h1:h06DGIukJOevXaj/xrNjhi/2098RZzcLTbc0jDAUbsg= go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 h1:CqXxU8VOmDefoh0+ztfGaymYbhdB/tT3zs79QaZTNGY= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.70.0 h1:LMuyCAyfalSjDyjdC65nK6N0zoTT63+E/u95X0JovZI= go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8= go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM= go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms= @@ -354,6 +457,7 @@ go.opentelemetry.io/otel v1.42.0 h1:lSQGzTgVR3+sgJDAU/7/ZMjN9Z+vUip7leaqBKy4sho= go.opentelemetry.io/otel v1.42.0/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc= go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I= go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0= +go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU= go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.38.0 h1:vl9obrcoWVKp/lwl8tRE33853I8Xru9HFbw/skNeLs8= go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.38.0/go.mod h1:GAXRxmLJcVM3u22IjTg74zWBrRCKq8BnOqUVLodpcpw= go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.40.0 h1:NOyNnS19BF2SUDApbOKbDtWZ0IK7b8FJ2uAGdIWOGb0= @@ -371,6 +475,7 @@ go.opentelemetry.io/otel/metric v1.42.0 h1:2jXG+3oZLNXEPfNmnpxKDeZsFI5o4J+nz6xUl go.opentelemetry.io/otel/metric v1.42.0/go.mod h1:RlUN/7vTU7Ao/diDkEpQpnz3/92J9ko05BIwxYa2SSI= go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM= go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY= +go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc= go.opentelemetry.io/otel/sdk v1.38.0 h1:l48sr5YbNf2hpCUj/FoGhW9yDkl+Ma+LrVl8qaM5b+E= go.opentelemetry.io/otel/sdk v1.38.0/go.mod h1:ghmNdGlVemJI3+ZB5iDEuk4bWA3GkTpW+DOoZMYBVVg= go.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8= @@ -387,12 +492,15 @@ go.opentelemetry.io/otel/trace v1.42.0 h1:OUCgIPt+mzOnaUTpOQcBiM/PLQ/Op7oq6g4Len go.opentelemetry.io/otel/trace v1.42.0/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc= go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A= go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0= +go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk= go.opentelemetry.io/proto/otlp v1.7.1 h1:gTOMpGDb0WTBOP8JaO72iL3auEZhVmAQg4ipjOVAtj4= go.opentelemetry.io/proto/otlp v1.7.1/go.mod h1:b2rVh6rfI/s2pHWNlB7ILJcRALpcNDzKhACevjI+ZnE= go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A= go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g= +go.opentelemetry.io/proto/otlp v1.11.0 h1:5rrYs0Ykyj50sdU/JU0x8etU+LubXWb+gED6TbEdMIk= go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0= go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8= +go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= @@ -406,8 +514,13 @@ golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts= golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos= golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI= +golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988= +golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto= +golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw= +golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M= golang.org/x/exp v0.0.0-20250911091902-df9299821621 h1:2id6c1/gto0kaHYyrixvknJ8tUK/Qs5IsmBtrc+FtgU= golang.org/x/exp v0.0.0-20250911091902-df9299821621/go.mod h1:TwQYMMnGpvZyc+JpB/UAuTNIsVJifOlSkrZkhcvpVUk= +golang.org/x/exp v0.0.0-20260603202125-055de637280b h1:v1uXiEBHo8QA0LiGCo7UgHMzHT4Kdfpl2zmtH5vaP1Q= golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= golang.org/x/mod v0.29.0 h1:HV8lRxZC4l2cr3Zq1LvtOsi/ThTgWnUk/y64QSs8GwA= @@ -417,6 +530,7 @@ golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg= golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8= golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w= golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI= +golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4= golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= @@ -428,6 +542,11 @@ golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY= golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o= golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo= golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA= +golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8= +golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o= +golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE= +golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To= +golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= @@ -437,6 +556,7 @@ golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4= golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI= golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4= golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= +golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= @@ -459,6 +579,8 @@ golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI= golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ= +golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY= +golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw= golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU= golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254= golang.org/x/term v0.38.0 h1:PQ5pkm/rLO6HnxFR7N2lJHOZX6Kez5Y1gDSJla6jo7Q= @@ -466,6 +588,8 @@ golang.org/x/term v0.38.0/go.mod h1:bSEAKrOT1W+VSu9TSCMtoGEOUcKxOKgl3LE5QEF/xVg= golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg= golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU= golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY= +golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4= +golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM= @@ -475,6 +599,8 @@ golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY= golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE= golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk= golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg= +golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc= +golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE= @@ -488,6 +614,7 @@ golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc= golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg= golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s= +golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -510,6 +637,8 @@ google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aO google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE= google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= +google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af h1:+5/Sw3GsDNlEmu7TfklWKPdQ0Ykja5VEmq2i817+jbI= +google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ= gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw= diff --git a/hack/api-docs/README.md b/hack/api-docs/README.md new file mode 100644 index 000000000000..d6d49fd0944a --- /dev/null +++ b/hack/api-docs/README.md @@ -0,0 +1,115 @@ +# API reference build + +This tool validates the Hub, DVP, Registry, AI Governance, and Sandboxes OpenAPI sources +in `content/reference/api/` and generates presentation data for Hugo. Engine +retains its existing sources and renderer. + +## Commands + +Site builds use the committed `data/api-reference.json`. To build the site, +use Hugo and the site's Node dependencies. From the repository root: + +```console +$ npm ci +$ hugo server +``` + +For a static build with HTML/Markdown checks, run +`./hack/api-docs/run.sh build`. To serve that build on port 1314, run +`./hack/api-docs/run.sh serve`. Set `DOCS_URL` and `DOCS_PORT` when using another +address. These commands use the committed data without running the generator. + +After changing a specification, source manifest entry, or generator code, use +the Go version declared in `hack/api-docs/go.mod` to regenerate the data. + +Install the Vacuum version pinned in the [Dockerfile](../../Dockerfile) and make +the `vacuum` executable available on `PATH`. The script runs Vacuum and the Go +generator without installing tools. + +```console +$ ./hack/api-docs/run.sh test +$ ./hack/api-docs/run.sh generate +``` + +Commit `data/api-reference.json` with the source changes. With +`docker compose watch`, the regenerated JSON syncs to the server and Hugo +rebuilds the reference. Docker builds and Netlify deploy previews also use the +committed JSON. Validation reports and local builds remain under +`tmp/api-reference/`. + +## Processor inputs + +`sources.json` registers input specifications and their product/manual +relationships. Both generation and the validation wrapper use this manifest. +Hugo reads the generated presentation data, rather than this file. Authentication +descriptions come from the specifications and linked guides. + +`validation/` contains the Vacuum rules and locked official +schema resources. `testdata/` contains validation fixtures. The presentation model +version and supported dialect are defined by the processor, not configurable +manifest fields. + +## Pipeline + +1. Parse the authoritative YAML with `libopenapi` and preserve source values and + reference identities. Verify locked OpenAPI dialect resources. +2. Run Vacuum policy checks and JSON Schema validation of schemas and supplied + examples, followed by documentation profile checks. +3. Generate presentation model version 1: operations, effective security and + servers, parameters, media variants, examples, schema links, and provenance. +4. Render HTML and Markdown through the content adapter and `api-docs` templates. +5. Run the shared site flattening script, then check generated operation, + parameter, media, schema, and link coverage. + +The shared `hack/flatten-and-resolve.js` script resolves Markdown link destinations +relative to each original file, then moves `index.md` files to flattened paths. +It preserves code examples and other text. API pages use the same processing as +other pages; links that already use published URLs remain unchanged. + +The published YAML URLs still serve the source files directly. + +## Validation + +`check` is strict and reports every documentation profile failure: + +```console +$ ./hack/api-docs/run.sh check +``` + +Generation runs the same strict validation. Any diagnostic fails generation; +there is no exception baseline. Reports are written to +`tmp/api-reference/validation.json`. + +The build workflow's validation matrix runs API reference checks alongside the +other validation targets. It runs tests, validates the sources, regenerates the +JSON, and compares the result with the committed file to detect stale data. +This matrix entry is advisory: failures do not block site builds or deployment. + +Run the same check locally with Docker: + +```console +$ docker buildx bake validate-api-reference +``` + +This target runs generator tests, strict validation, and a byte-for-byte +comparison inside Docker. It leaves the working tree unchanged and is also +included in the `validate` Bake group. + +## Tests and scope + +Go fixtures cover dialects, references, recursion, boolean schemas, examples, +security overrides, server and parameter precedence, and request generation. +`verify-output.mjs` checks all generated HTML/Markdown pairs, retention of +Engine v1.40–v1.56 in ReDoc, and byte-identical published specifications. It +also checks local links and fragments from API pages, including links to +`docs.docker.com`. The site `htmltest` checks include migrated Hub, DVP, +Registry, and AI Governance references. `browser-checks.mjs` exports a +Playwright check for navigation, page aliases, filtering, requests, and narrow +screens. + +Callbacks and webhook navigation are unsupported and fail validation. Request +examples are POSIX shell templates; they do not make service calls. + +Examples are optional. Supplied examples must validate against their schemas. +When a request body has no example, the generated cURL command reads from +`request-body` and directs the reader to prepare that file from the schema. diff --git a/hack/api-docs/browser-checks.mjs b/hack/api-docs/browser-checks.mjs new file mode 100644 index 000000000000..fe419e246e61 --- /dev/null +++ b/hack/api-docs/browser-checks.mjs @@ -0,0 +1,141 @@ +// Run with a Playwright Page against a built site; no product API calls. +export default async function verify(page, base = "http://localhost:1314") { + const results = []; + const assert = (condition, message) => { + if (!condition) throw Error(message); + results.push(message); + }; + await page.setViewportSize({ width: 1440, height: 1000 }); + await page.goto(base + "/reference/api/"); + assert( + (await page.locator(".api-card").count()) === 6, + "Six API catalog entries", + ); + assert( + (await page.locator("nav.navbar-font").count()) === 1, + "Catalog retains Reference sidebar", + ); + await page.goto(base + "/reference/api/dvp/latest/"); + assert( + (await page.locator(".api-nav").count()) === 1 && + (await page.locator("nav.navbar-font").count()) === 0, + "Reference uses local navigation", + ); + const first = page.locator("[data-api-filter-item]").first(); + const operationURL = await first.getAttribute("href"); + await page.goto(base + "/reference/api/hub/dvp/"); + await page.waitForURL("**/reference/api/dvp/latest/"); + assert( + page.url().endsWith("/reference/api/dvp/latest/"), + "DVP alias reaches overview", + ); + await page.goto(base + operationURL); + await page.context().grantPermissions(["clipboard-read", "clipboard-write"]); + const copy = page.locator("[data-api-copy]"); + await copy.focus(); + await page.keyboard.press("Enter"); + await page.waitForFunction( + () => document.querySelector("[data-api-copy]").textContent === "Copied", + ); + assert( + (await page.evaluate(() => navigator.clipboard.readText())).includes( + "curl", + ), + "Keyboard copies a request", + ); + await page.locator(".api-nav-back").focus(); + await page.keyboard.press("Enter"); + await page.waitForURL("**/reference/api/"); + assert( + (await page.locator("nav.navbar-font").count()) === 1, + "Keyboard back link restores catalog", + ); + await page.goto(base + "/reference/api/hub/latest/"); + await page.locator("[data-api-filter]").fill("token"); + const rows = page.locator("[data-api-filter-item]:visible"); + assert( + (await rows.count()) > 0 && + (await rows.allTextContents()).every((x) => + x.toLowerCase().includes("token"), + ), + "Operation filtering", + ); + const schemaURL = await page + .locator(".api-schema-links a") + .first() + .getAttribute("href"); + await page.goto(base + schemaURL); + assert( + (await page.locator('[data-api-view="schema"]').count()) === 1, + "Linked schema page", + ); + await page.setViewportSize({ width: 390, height: 844 }); + await page.goto(base + operationURL); + assert( + await page.evaluate( + () => document.documentElement.scrollWidth <= innerWidth + 1, + ), + "No narrow-screen document overflow", + ); + await page.goto(base + "/reference/api/engine/version/v1.56/"); + assert( + (await page.locator("redoc").count()) === 1, + "Latest Engine retains ReDoc", + ); + await page.goto(base + "/reference/api/ai-governance/"); + await page.waitForURL("**/reference/api/ai-governance/latest/"); + assert( + (await page.locator('[data-api-view="overview"]').count()) === 1, + "Governance alias reaches generated overview", + ); + await page.goto(base + "/ai/sandboxes-api/"); + assert( + (await page + .locator('nav.navbar-font a[href="/reference/api/sandboxes/latest/"]') + .count()) === 1, + "Sandboxes manual links to the API reference in the sidebar", + ); + await page.goto(base + "/reference/api/sandboxes/"); + await page.waitForURL("**/reference/api/sandboxes/latest/"); + assert( + (await page.locator("article").textContent()).includes("experimental"), + "Sandboxes alias reaches the experimental API overview", + ); + await page.goto( + base + "/reference/api/sandboxes/latest/operations/download/", + ); + assert( + (await page.locator("article").textContent()).includes("itemEncoding"), + "File download renders stream encoding", + ); + await page.goto( + base + "/reference/api/sandboxes/latest/operations/interact/", + ); + assert( + (await page.locator("article").textContent()).includes( + "WebSocket session", + ) && (await page.locator("[data-api-copy]").count()) === 0, + "Interactive processes show WebSocket requirements instead of a plain HTTP example", + ); + assert( + await page.evaluate( + () => document.documentElement.scrollWidth <= innerWidth + 1, + ), + "Sandboxes operation fits a narrow screen", + ); + const context = await page + .context() + .browser() + .newContext({ javaScriptEnabled: false }); + try { + const staticPage = await context.newPage(); + await staticPage.goto(base + operationURL); + assert( + (await staticPage.locator("[data-api-copy-source]").count()) === 1, + "Request content exists without JavaScript", + ); + } finally { + await context.close(); + } + return results; +} diff --git a/hack/api-docs/contracts_test.go b/hack/api-docs/contracts_test.go new file mode 100644 index 000000000000..e963eb7d9d14 --- /dev/null +++ b/hack/api-docs/contracts_test.go @@ -0,0 +1,128 @@ +package main + +import ( + "path/filepath" + "strings" + "testing" +) + +func localDocument(t *testing.T, api string) *Document { + t.Helper() + d, err := loadDocument(filepath.Join("..", "..", "content", "reference", "api", api, "latest.yaml"), "validation/dialects") + if err != nil { + t.Fatal(err) + } + d.Source = Source{ID: api} + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("%s must pass strict validation: %+v", api, d.Diagnostics) + } + return d +} + +func TestHubResponseContracts(t *testing.T) { + d := localDocument(t, "hub") + for _, tc := range []struct { + pointer, value string + valid bool + }{ + {"/components/schemas/createOrgAccessTokenRequest", `{"label":"CI token"}`, false}, + {"/components/schemas/createOrgAccessTokenRequest", `{"label":"CI token","resources":[]}`, false}, + {"/components/schemas/createOrgAccessTokenRequest", `{"label":"CI token","resources":[{"type":"TYPE_REPO","path":"myorg/myrepo","scopes":["scope-image-pull"]}]}`, true}, + {"/components/schemas/error", `{"message":"not found","errinfo":null}`, true}, + {"/components/schemas/error", `{"errinfo":{"field":["invalid"],"limit":5}}`, true}, + {"/components/schemas/error", `{"errinfo":[]}`, false}, + {"/components/schemas/getAccessTokensResponse", `{"next":null,"previous":null,"results":[]}`, true}, + {"/components/schemas/getOrgAccessTokensResponse", `{"next":null,"previous":null,"results":[]}`, true}, + {"/components/schemas/org_member_paginated", `{"count":0,"next":null,"previous":null,"results":[]}`, true}, + {"/components/schemas/org_member_paginated", `[]`, false}, + {"/components/schemas/bulk_invite", `{"invitees":[]}`, true}, + {"/components/schemas/bulk_invite", `{"invitees":{"invitees":[]}}`, false}, + {"/components/schemas/tag", `{"v2":true,"images":[{"architecture":"amd64","variant":null,"features":null,"os_features":null,"os_version":null}]}`, true}, + {"/components/schemas/tag", `{"v2":"true","images":{}}`, false}, + {"/components/schemas/immutable_tags_verify_request", `{"regex":"v.*"}`, true}, + {"/components/schemas/immutable_tags_verify_request", `{"regex":"v1,v2"}`, false}, + {"/components/schemas/scim_service_provider_config", `{"authenticationSchemes":[{"type":"oauthbearertoken"}]}`, true}, + {"/components/schemas/scim_service_provider_config", `{"authenticationSchemes":{}}`, false}, + {"/components/requestBodies/scim_update_user_request/content/application~1scim+json/schema", `{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"user@example.com","active":false}`, true}, + {"/components/requestBodies/scim_update_user_request/content/application~1scim+json/schema", `{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"]}`, false}, + {"/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/200/content/text~1csv/schema", `"Name,Username\nUser,dockeruser\n"`, true}, + {"/paths/~1v2~1orgs~1{org_name}~1members~1export/get/responses/200/content/text~1csv/schema", `[{"Name":"User"}]`, false}, + } { + t.Run(tc.pointer+"/"+tc.value, func(t *testing.T) { + s, err := d.Compiler.Compile(d.URI + "#" + tc.pointer) + if err != nil { + t.Fatal(err) + } + if err := s.Validate(jsonNumber(tc.value)); (err == nil) != tc.valid { + t.Fatalf("valid = %t, want %t: %v", err == nil, tc.valid, err) + } + }) + } + for _, response := range []string{"scim_get_resource_types_resp", "scim_get_schemas_resp", "scim_get_users_resp"} { + v, err := pointer(d.Root, "/components/responses/"+response+"/content/application~1scim+json/schema/properties") + if err != nil { + t.Fatal(err) + } + if obj(v)["Resources"] == nil || obj(v)["resources"] != nil { + t.Fatalf("incorrect SCIM list field casing: %s", response) + } + } +} + +func TestRegistryRequests(t *testing.T) { + d := localDocument(t, "registry") + for _, raw := range arr(d.model()["operations"]) { + op := obj(raw) + curl := str(op["curl"]) + if strings.Count(curl, "Authorization:") != 1 || !strings.Contains(curl, "${REGISTRY_TOKEN}") { + t.Errorf("incorrect registry authentication: %s", curl) + } + if strings.Count(curl, "Content-Type:") > 1 { + t.Errorf("duplicate content type: %s", curl) + } + if (op["id"] == "GetImageManifest" || op["id"] == "HeadImageManifest") && !strings.Contains(curl, "Accept: application/vnd.docker.distribution.manifest.v2+json") { + t.Errorf("missing manifest negotiation: %s", curl) + } + if op["id"] == "GetBlobUploadStatus" && !strings.Contains(curl, "--request GET") { + t.Errorf("incorrect upload status method: %s", curl) + } + } +} + +func TestReservedHeaderParameters(t *testing.T) { + for _, name := range []string{"Authorization", "accept", "CONTENT-TYPE", "Content-Range"} { + t.Run(name, func(t *testing.T) { + d := fixture(t, "valid.yaml") + op := obj(obj(obj(d.Root["paths"])["/public"])["get"]) + op["parameters"] = []any{Object{"name": name, "in": "header", "description": "Header value.", "schema": Object{"type": "string"}}} + d.validate("") + found := false + for _, diag := range d.Diagnostics { + found = found || (diag.Rule == "S8" && strings.Contains(diag.Message, "ignores")) + } + if found != (name != "Content-Range") { + t.Fatalf("unexpected header validation: %+v", d.Diagnostics) + } + }) + } +} + +func TestExampleText(t *testing.T) { + for _, tc := range []struct { + media string + value any + text, language string + }{ + {"text/csv", "Name,Username\nUser,dockeruser\n", "Name,Username\nUser,dockeruser\n", "text"}, + {"text/plain", "<html>&\n", "<html>&\n", "text"}, + {"application/json", "a\nb", `"a\nb"`, "json"}, + {"application/scim+json", false, "false", "json"}, + {"application/json", jsonNumber("0"), "0", "json"}, + } { + text, language := exampleText(tc.media, tc.value) + if text != tc.text || language != tc.language { + t.Errorf("got %q (%s), want %q (%s)", text, language, tc.text, tc.language) + } + } +} diff --git a/hack/api-docs/go.mod b/hack/api-docs/go.mod new file mode 100644 index 000000000000..6f45e2016a8f --- /dev/null +++ b/hack/api-docs/go.mod @@ -0,0 +1,18 @@ +module github.com/docker/docs/hack/api-docs + +go 1.26.5 + +require ( + github.com/pb33f/libopenapi v0.38.7 + github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 +) + +require ( + github.com/bahlo/generic-list-go v0.2.0 // indirect + github.com/buger/jsonparser v1.1.2 // indirect + github.com/pb33f/jsonpath v0.8.2 // indirect + github.com/pb33f/ordered-map/v2 v2.3.1 // indirect + go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect + golang.org/x/sync v0.22.0 // indirect + golang.org/x/text v0.14.0 // indirect +) diff --git a/hack/api-docs/go.sum b/hack/api-docs/go.sum new file mode 100644 index 000000000000..304e372c1e29 --- /dev/null +++ b/hack/api-docs/go.sum @@ -0,0 +1,30 @@ +github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk= +github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg= +github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk= +github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= +github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= +github.com/pb33f/jsonpath v0.8.2 h1:Ou4C7zjYClBm97dfZjDCjdZGusJoynv/vrtiEKNfj2Y= +github.com/pb33f/jsonpath v0.8.2/go.mod h1:zBV5LJW4OQOPatmQE2QdKpGQJvhDTlE5IEj6ASaRNTo= +github.com/pb33f/libopenapi v0.38.7 h1:Q2jfgRPdnU38WW8wQvrX2HEPGiqsxj01PX1BHmAEihc= +github.com/pb33f/libopenapi v0.38.7/go.mod h1:naZ03Auhn7i+RJtMv8ck8l7Ag8E2/x2w66j9vsDFL38= +github.com/pb33f/ordered-map/v2 v2.3.1 h1:5319HDO0aw4DA4gzi+zv4FXU9UlSs3xGZ40wcP1nBjY= +github.com/pb33f/ordered-map/v2 v2.3.1/go.mod h1:qxFQgd0PkVUtOMCkTapqotNgzRhMPL7VvaHKbd1HnmQ= +github.com/pb33f/testify v0.1.0 h1:g48/HDU/jn2COspS4nM0scptxiKTJ4DnbX/4ehK6IZ8= +github.com/pb33f/testify v0.1.0/go.mod h1:nq283P/jJ8hXMmdhAqfj7BJIz0y+6IOHj9q0044rKt4= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= +go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= +golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek= +golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= +golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= +golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/hack/api-docs/main.go b/hack/api-docs/main.go new file mode 100644 index 000000000000..dccb9eee656b --- /dev/null +++ b/hack/api-docs/main.go @@ -0,0 +1,757 @@ +// api-docs prepares a source-preserving reference model for Docker API documentation. +package main + +import ( + "bytes" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "net/url" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/pb33f/libopenapi" + "github.com/pb33f/libopenapi/datamodel" + js "github.com/santhosh-tekuri/jsonschema/v6" + yaml "go.yaml.in/yaml/v4" +) + +type Object = map[string]any + +const dialect = "https://spec.openapis.org/oas/3.1/dialect/base" + +var methods = []string{"get", "put", "post", "delete", "options", "head", "patch", "trace", "query"} + +func obj(v any) Object { + m, _ := v.(map[string]any) + if m == nil { + return Object{} + } + return m +} +func arr(v any) []any { a, _ := v.([]any); return a } +func str(v any) string { s, _ := v.(string); return s } +func keys(m Object) []string { + a := make([]string, 0, len(m)) + for k := range m { + a = append(a, k) + } + sort.Strings(a) + return a +} +func hash(b []byte) string { s := sha256.Sum256(b); return hex.EncodeToString(s[:]) } +func encoded(v any) []byte { + b, e := json.MarshalIndent(v, "", " ") + if e != nil { + panic(e) + } + return append(b, '\n') +} +func esc(s string) string { return strings.ReplaceAll(strings.ReplaceAll(s, "~", "~0"), "/", "~1") } +func pointer(root any, p string) (any, error) { + if p == "" { + return root, nil + } + if !strings.HasPrefix(p, "/") { + return nil, fmt.Errorf("unsupported pointer %s", p) + } + for _, k := range strings.Split(p[1:], "/") { + k = strings.ReplaceAll(strings.ReplaceAll(k, "~1", "/"), "~0", "~") + switch v := root.(type) { + case map[string]any: + var ok bool + root, ok = v[k] + if !ok { + return nil, fmt.Errorf("missing pointer %s", p) + } + case []any: + var n int + if _, e := fmt.Sscanf(k, "%d", &n); e != nil || n < 0 || n >= len(v) { + return nil, fmt.Errorf("invalid array pointer %s", p) + } + root = v[n] + default: + return nil, fmt.Errorf("non-container pointer %s", p) + } + } + return root, nil +} +func readJSON(p string) (any, error) { + b, e := os.ReadFile(p) + if e != nil { + return nil, e + } + return js.UnmarshalJSON(bytes.NewReader(b)) +} +func writeJSON(p string, v any) error { + if e := os.MkdirAll(filepath.Dir(p), 0755); e != nil { + return e + } + return os.WriteFile(p, encoded(v), 0644) +} + +type Diagnostic struct { + Rule string `json:"rule"` + Pointer string `json:"pointer"` + Message string `json:"message"` +} +type Source struct { + Experimental bool `json:"experimental,omitempty"` + ID string `json:"id"` + Product string `json:"product"` + Title string `json:"title"` + Source string `json:"source"` + Owner string `json:"owner"` + Manual string `json:"manual"` + Connection string `json:"connection"` + Guides []string `json:"guides"` +} +type Registry struct{ resources map[string]any } + +func (r *Registry) Load(uri string) (any, error) { + if v, ok := r.resources[uri]; ok { + return v, nil + } + return nil, fmt.Errorf("unlocked resource: %s", uri) +} + +type Document struct { + Root Object + URI string + Registry *Registry + Diagnostics []Diagnostic + Schemas map[string]any + Locations map[string]int + Compiler *js.Compiler + Compiled map[string]*js.Schema + Digest string + Source Source + SchemaCount int + ExampleCount int +} + +func (d *Document) issue(rule, p, msg string) { + d.Diagnostics = append(d.Diagnostics, Diagnostic{Rule: rule, Pointer: p, Message: strings.ReplaceAll(msg, d.URI, "source:"+d.Source.ID)}) +} +func walk(v any, p string, fn func(Object, string)) { + switch n := v.(type) { + case map[string]any: + fn(n, p) + for _, k := range keys(n) { + walk(n[k], p+"/"+esc(k), fn) + } + case []any: + for i, x := range n { + walk(x, fmt.Sprintf("%s/%d", p, i), fn) + } + } +} +func strictSource(file string) (Object, libopenapi.Document, error) { + b, e := os.ReadFile(file) + if e != nil { + return nil, nil, e + } + cfg := datamodel.NewDocumentConfiguration() + cfg.AllowRemoteReferences = false + cfg.AllowFileReferences = false + cfg.SkipExternalRefResolution = true + doc, e := libopenapi.NewDocumentWithConfiguration(b, cfg) + if e != nil { + return nil, nil, e + } + v, e := strictFragment(file) + return obj(v), doc, e +} + +// YAML timestamp scalars are strings in the JSON data model. Decode source nodes +// explicitly: libopenapi's JSON convenience view normalizes their spelling. +func strictFragment(file string) (any, error) { + b, e := os.ReadFile(file) + if e != nil { + return nil, e + } + var node yaml.Node + if e = yaml.Unmarshal(b, &node); e != nil { + return nil, e + } + v, e := sourceValue(&node, map[*yaml.Node]bool{}) + if e != nil { + return nil, e + } + raw, e := json.Marshal(v) + if e != nil { + return nil, e + } + return js.UnmarshalJSON(bytes.NewReader(raw)) +} +func sourceValue(n *yaml.Node, active map[*yaml.Node]bool) (any, error) { + if active[n] { + return nil, errors.New("cyclic YAML alias") + } + active[n] = true + defer delete(active, n) + switch n.Kind { + case yaml.DocumentNode: + if len(n.Content) != 1 { + return nil, errors.New("expected one YAML document") + } + return sourceValue(n.Content[0], active) + case yaml.AliasNode: + return sourceValue(n.Alias, active) + case yaml.MappingNode: + m := Object{} + for i := 0; i < len(n.Content); i += 2 { + k := n.Content[i] + if k.Kind != yaml.ScalarNode || k.Value == "<<" { + return nil, errors.New("complex/merge YAML keys are outside the source profile") + } + if _, ok := m[k.Value]; ok { + return nil, fmt.Errorf("duplicate key %s at line %d", k.Value, k.Line) + } + v, e := sourceValue(n.Content[i+1], active) + if e != nil { + return nil, e + } + m[k.Value] = v + } + return m, nil + case yaml.SequenceNode: + a := []any{} + for _, c := range n.Content { + v, e := sourceValue(c, active) + if e != nil { + return nil, e + } + a = append(a, v) + } + return a, nil + case yaml.ScalarNode: + if n.Tag == "!!str" || n.Tag == "!!timestamp" { + return n.Value, nil + } + var v any + e := n.Decode(&v) + return v, e + } + return nil, errors.New("unsupported YAML node") +} + +func loadDocument(file, metaDir string) (*Document, error) { + abs, _ := filepath.Abs(file) + root, parsed, e := strictSource(abs) + if e != nil { + return nil, e + } + uri := (&url.URL{Scheme: "file", Path: abs}).String() + b, _ := os.ReadFile(file) + d := &Document{Root: root, URI: uri, Diagnostics: []Diagnostic{}, Registry: &Registry{resources: map[string]any{uri: root}}, Schemas: map[string]any{}, Locations: map[string]int{}, Compiled: map[string]*js.Schema{}, Digest: hash(b)} + // libopenapi's typed model supplies operation views/locations; schema serialization is never used. + model, modelErr := parsed.BuildV3Model() + if modelErr == nil && model != nil && model.Model.Paths != nil { + for p, item := range model.Model.Paths.PathItems.FromOldest() { + for m, op := range item.GetOperations().FromOldest() { + if op.GoLow().RootNode != nil { + d.Locations["/paths/"+esc(p)+"/"+m] = op.GoLow().RootNode.Line + } + } + } + } + // All file resources are acquired before compilation, under a bounded source directory. + var acquire func(any, string) error + acquire = func(v any, base string) error { + var failure error + walk(v, "", func(n Object, _ string) { + for _, k := range []string{"$ref", "$dynamicRef"} { + ref, ok := n[k].(string) + if !ok { + continue + } + u, er := url.Parse(ref) + if er != nil { + failure = er + return + } + bu, _ := url.Parse(base) + u = bu.ResolveReference(u) + u.Fragment = "" + id := u.String() + if _, ok := d.Registry.resources[id]; ok { + continue + } + if u.Scheme != "file" { + failure = fmt.Errorf("unlocked reference %s", id) + return + } + rel, er := filepath.Rel(filepath.Dir(abs), u.Path) + if er != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) { + failure = fmt.Errorf("reference escapes package: %s", ref) + return + } + r, er := strictFragment(u.Path) + if er != nil { + failure = er + return + } + d.Registry.resources[id] = r + if er = acquire(r, id); er != nil { + failure = er + } + } + }) + return failure + } + if e = acquire(root, uri); e != nil { + return nil, e + } + lockRaw, e := os.ReadFile(filepath.Join(metaDir, "lock.json")) + if e != nil { + return nil, e + } + var lock []struct{ File, URI, SHA256 string } + if e = json.Unmarshal(lockRaw, &lock); e != nil { + return nil, e + } + for _, l := range lock { + b, e := os.ReadFile(filepath.Join(metaDir, l.File)) + if e != nil { + return nil, e + } + if hash(b) != l.SHA256 { + return nil, fmt.Errorf("dialect digest mismatch: %s", l.File) + } + v, e := js.UnmarshalJSON(bytes.NewReader(b)) + if e != nil { + return nil, e + } + d.Registry.resources[l.URI] = v + if id := str(obj(v)["$id"]); id != "" { + d.Registry.resources[id] = v + } + } + d.Compiler = js.NewCompiler() + d.Compiler.DefaultDraft(js.Draft2020) + d.Compiler.UseLoader(d.Registry) + for id, v := range d.Registry.resources { + if e = d.Compiler.AddResource(id, v); e != nil { + return nil, e + } + } + return d, nil +} +func (d *Document) resolve(v any) any { + seen := map[string]bool{} + for { + r := str(obj(v)["$ref"]) + if r == "" { + return v + } + if seen[r] { + return v + } + seen[r] = true + u, e := url.Parse(r) + if e != nil { + return v + } + base, _ := url.Parse(d.URI) + u = base.ResolveReference(u) + frag := u.Fragment + u.Fragment = "" + target, ok := d.Registry.resources[u.String()] + if !ok { + return v + } + resolved, e := pointer(target, frag) + if e != nil { + return v + } + merged := Object{} + for k, x := range obj(resolved) { + merged[k] = x + } + for _, k := range []string{"summary", "description"} { + if x, ok := obj(v)[k]; ok { + merged[k] = x + } + } + if len(merged) == 0 { + return resolved + } + v = merged + } +} +func (d *Document) schemaRoots(v any, p string) { + switch n := v.(type) { + case map[string]any: + for _, k := range keys(n) { + x := n[k] + q := p + "/" + esc(k) + if k == "schemas" && p == "/components" { + for name, s := range obj(x) { + d.Schemas[q+"/"+esc(name)] = s + } + } else if k == "schema" || k == "itemSchema" { + d.Schemas[q] = x + } else if !strings.HasPrefix(k, "x-") && k != "example" && k != "examples" && k != "value" { + d.schemaRoots(x, q) + } + } + case []any: + for i, x := range n { + d.schemaRoots(x, fmt.Sprintf("%s/%d", p, i)) + } + } +} +func (d *Document) validate(metaDir string) { + if d.Root["openapi"] != "3.2.0" { + d.issue("S1", "/openapi", "Expected OpenAPI 3.2.0") + } + if d.Root["jsonSchemaDialect"] != dialect { + d.issue("S1", "/jsonSchemaDialect", "Expected the selected OAS dialect") + } + documentSchema, e := d.Compiler.Compile("https://spec.openapis.org/oas/3.2/schema/2025-09-17") + if e != nil { + d.issue("structure", "", e.Error()) + } else if e = documentSchema.Validate(d.Root); e != nil { + d.issue("structure", "", e.Error()) + } + // OAS Reference Objects also need explicit validation: a document schema cannot prove their target exists. + walk(d.Root, "", func(n Object, p string) { + if r := str(n["$ref"]); r != "" { + u, er := url.Parse(r) + if er != nil { + d.issue("reference", p, er.Error()) + return + } + base, _ := url.Parse(d.URI) + u = base.ResolveReference(u) + frag := u.Fragment + u.Fragment = "" + v, ok := d.Registry.resources[u.String()] + if !ok { + d.issue("reference", p, "Unregistered resource "+r) + } else if strings.HasPrefix(frag, "/") { + if _, er = pointer(v, frag); er != nil { + d.issue("reference", p, er.Error()) + } + } + } + }) + if len(obj(d.Root["webhooks"])) > 0 { + d.issue("capability", "/webhooks", "Webhook navigation is not supported by the reference renderer") + } + walk(d.Root, "", func(n Object, p string) { + if len(obj(n["callbacks"])) > 0 { + d.issue("capability", p+"/callbacks", "Callback navigation is not supported by the reference renderer") + } + }) + d.schemaRoots(d.Root, "") + schemaMeta, e := d.Compiler.Compile(dialect) + if e != nil { + d.issue("dialect", "", e.Error()) + return + } + for _, p := range keys(d.Schemas) { + s := d.Schemas[p] + d.SchemaCount++ + if e = schemaMeta.Validate(s); e != nil { + d.issue("schema", p, e.Error()) + continue + } + compiled, e := d.Compiler.Compile(d.URI + "#" + p) + if e != nil { + d.issue("schema", p, e.Error()) + continue + } + d.Compiled[p] = compiled + d.schemaExamples(s, p) + } + // Media, parameter and header examples are separate from examples nested inside schemas. + walk(d.Root, "", func(n Object, p string) { + schemaKey := "schema" + if _, ok := n["itemSchema"]; ok { + schemaKey = "itemSchema" + } + c := d.Compiled[p+"/"+schemaKey] + if c == nil { + return + } + if v, ok := n["example"]; ok { + d.example(c, v, p+"/example") + } + for _, name := range keys(obj(n["examples"])) { + ex := obj(d.resolve(obj(n["examples"])[name])) + if v, ok := ex["value"]; ok { + d.example(c, v, p+"/examples/"+esc(name)+"/value") + } + if _, ok := ex["externalValue"]; ok { + d.issue("example-external", p+"/examples/"+esc(name), "External example requires a locked media fixture") + } + } + }) + ids := map[string]bool{} + tags := map[string]string{} + for _, raw := range arr(d.Root["tags"]) { + t := obj(raw) + tags[str(t["name"])] = str(t["kind"]) + } + for _, op := range d.operations() { + id := str(op["id"]) + p := str(op["pointer"]) + if id == "" || ids[id] { + d.issue("S4", p, "Operation ID must be present and unique") + } + for i, requirement := range arr(op["security"]) { + for _, name := range keys(obj(requirement)) { + if _, ok := obj(obj(d.Root["components"])["securitySchemes"])[name]; !ok { + d.issue("security", fmt.Sprintf("%s/security/%d/%s", p, i, esc(name)), "Undefined security scheme: "+name) + } + } + } + ids[id] = true + opTags := arr(op["tags"]) + if len(opTags) == 0 || tags[str(opTags[0])] != "nav" { + d.issue("S5", p+"/tags", "The first operation tag must identify a declared navigation group") + } + for _, tag := range opTags { + if _, ok := tags[str(tag)]; !ok { + d.issue("S5", p+"/tags", "Operation tag is undeclared: "+str(tag)) + } + } + if len(arr(op["servers"])) == 0 && d.Source.Connection != "unix" { + d.issue("S6", p, "Operation needs effective servers or a local connection profile") + } + if strings.TrimSpace(str(op["description"])) == "" { + d.issue("S4", p+"/description", "Operation description required") + } + for _, pr := range arr(op["parameters"]) { + param := obj(pr) + if param["in"] == "header" { + switch strings.ToLower(str(param["name"])) { + case "authorization", "accept", "content-type": + d.issue("S8", str(param["pointer"]), "OpenAPI ignores this header parameter; use security or media types") + } + } + if str(param["description"]) == "" { + d.issue("S8", str(param["pointer"])+"/description", "Parameter description requires editorial review") + } + } + + } +} +func (d *Document) schemaExamples(s any, p string) { + n := obj(s) + if len(n) == 0 { + return + } + if _, ok := n["$schema"]; ok && n["$schema"] != dialect { + d.issue("S1", p+"/$schema", "Schema dialect override is outside the profile") + } + c, e := d.Compiler.Compile(d.URI + "#" + p) + if e == nil { + if v, ok := n["example"]; ok { + d.example(c, v, p+"/example") + } + for i, v := range arr(n["examples"]) { + d.example(c, v, fmt.Sprintf("%s/examples/%d", p, i)) + } + } + for k, x := range n { + switch k { + case "properties", "patternProperties", "$defs", "dependentSchemas": + for _, name := range keys(obj(x)) { + d.schemaExamples(obj(x)[name], p+"/"+k+"/"+esc(name)) + } + case "allOf", "anyOf", "oneOf", "prefixItems": + for i, v := range arr(x) { + d.schemaExamples(v, fmt.Sprintf("%s/%s/%d", p, k, i)) + } + case "items", "additionalProperties", "unevaluatedProperties", "contains", "not", "if", "then", "else", "contentSchema", "propertyNames": + d.schemaExamples(x, p+"/"+k) + } + } +} +func (d *Document) example(c *js.Schema, v any, p string) { + d.ExampleCount++ + if e := c.Validate(v); e != nil { + d.issue("example", p, e.Error()) + } +} +func (d *Document) effective(root, item, op Object, k string) any { + if v, ok := op[k]; ok { + return v + } + if k == "servers" { + if v, ok := item[k]; ok { + return v + } + } + return root[k] +} +func (d *Document) parameters(item, op Object, p string) []any { + a := []any{} + positions := map[string]int{} + for i, container := range []Object{item, op} { + for j, raw := range arr(container["parameters"]) { + v := obj(d.resolve(raw)) + c := Object{} + for k, x := range v { + c[k] = x + } + prefix := p + if i == 0 { + prefix = p[:strings.LastIndex(p, "/")] + } + c["pointer"] = fmt.Sprintf("%s/parameters/%d", prefix, j) + key := str(v["in"]) + ":" + str(v["name"]) + if n, ok := positions[key]; ok { + a[n] = c + } else { + positions[key] = len(a) + a = append(a, c) + } + } + } + return a +} +func (d *Document) exampleList(v Object) []any { + out := []any{} + if x, ok := v["example"]; ok { + out = append(out, Object{"name": "Example", "value": x}) + } + for _, name := range keys(obj(v["examples"])) { + x := obj(d.resolve(obj(v["examples"])[name])) + if value, ok := x["value"]; ok { + out = append(out, Object{"name": name, "value": value}) + } + } + return out +} +func (d *Document) variants(op Object, p string) []any { + out := []any{} + add := func(direction, status string, raw any, ptr string) { + container := obj(d.resolve(raw)) + content := obj(container["content"]) + if len(content) == 0 { + out = append(out, Object{"direction": direction, "status": status, "description": container["description"], "headers": container["headers"], "media": "", "pointer": ptr, "examples": []any{}}) + } + for _, media := range keys(content) { + v := obj(content[media]) + a := Object{"direction": direction, "status": status, "description": container["description"], "headers": container["headers"], "media": media, "pointer": ptr + "/content/" + esc(media), "examples": d.mediaExamples(v), "required": container["required"]} + for _, k := range []string{"schema", "itemSchema", "encoding", "itemEncoding", "prefixEncoding"} { + if s, ok := v[k]; ok { + a[k] = s + } + } + out = append(out, a) + } + } + if v, ok := op["requestBody"]; ok { + add("Request", "", v, p+"/requestBody") + } + for _, code := range keys(obj(op["responses"])) { + add("Response", code, obj(op["responses"])[code], p+"/responses/"+esc(code)) + } + return out +} +func (d *Document) operations() []Object { + out := []Object{} + for _, path := range keys(obj(d.Root["paths"])) { + item := obj(d.resolve(obj(d.Root["paths"])[path])) + ms := append([]string{}, methods...) + for m := range obj(item["additionalOperations"]) { + ms = append(ms, m) + } + for _, method := range ms { + raw, ok := item[method] + extra := !ok + if !ok { + raw, ok = obj(item["additionalOperations"])[method] + } + if !ok { + continue + } + op := obj(raw) + p := "/paths/" + esc(path) + "/" + method + if extra { + p = "/paths/" + esc(path) + "/additionalOperations/" + esc(method) + } + v := Object{"id": op["operationId"], "method": strings.ToUpper(method), "path": path, "pointer": p, "line": d.Locations[p], "summary": op["summary"], "description": op["description"], "tags": op["tags"], "deprecated": op["deprecated"], "servers": d.effective(d.Root, item, op, "servers"), "security": d.effective(d.Root, item, op, "security"), "parameters": d.parameters(item, op, p), "variants": d.variants(op, p), "raw": op} + out = append(out, v) + } + } + return out +} +func main() { + if e := run(); e != nil { + fmt.Fprintln(os.Stderr, e) + os.Exit(1) + } +} +func run() error { + if len(os.Args) < 3 { + return errors.New("usage: api-docs check|generate|inspect|sources ROOT") + } + command := os.Args[1] + if command != "check" && command != "generate" && command != "inspect" && command != "sources" { + return fmt.Errorf("unknown command: %s", command) + } + if len(os.Args) > 3 { + return errors.New("unexpected arguments") + } + root, _ := filepath.Abs(os.Args[2]) + dir := filepath.Join(root, "hack/api-docs") + meta := filepath.Join(dir, "validation", "dialects") + manifestRaw, e := os.ReadFile(filepath.Join(dir, "sources.json")) + if e != nil { + return e + } + var manifest struct { + APIs []Source `json:"apis"` + LegacyAPIs []Object `json:"legacyAPIs"` + } + if e = json.Unmarshal(manifestRaw, &manifest); e != nil { + return e + } + if command == "sources" { + for _, src := range manifest.APIs { + fmt.Printf("%s\t%s\n", src.ID, src.Source) + } + return nil + } + reports := []any{} + models := []any{} + blocking := 0 + for _, src := range manifest.APIs { + d, e := loadDocument(filepath.Join(root, src.Source), meta) + if e != nil { + return fmt.Errorf("%s: %w", src.ID, e) + } + d.Source = src + d.validate(meta) + blocking += len(d.Diagnostics) + reports = append(reports, Object{"api": src.ID, "sha256": d.Digest, "schemas": d.SchemaCount, "examples": d.ExampleCount, "operations": len(d.operations()), "diagnostics": d.Diagnostics}) + models = append(models, d.model()) + fmt.Printf("%s: %d operations, %d schema roots, %d examples, %d diagnostics\n", src.ID, len(d.operations()), d.SchemaCount, d.ExampleCount, len(d.Diagnostics)) + } + out := filepath.Join(root, "tmp/api-reference") + if e = writeJSON(filepath.Join(out, "validation.json"), reports); e != nil { + return e + } + if command == "inspect" { + return nil + } + if blocking > 0 { + return fmt.Errorf("%d blocking diagnostics; see tmp/api-reference/validation.json", blocking) + } + if command == "generate" { + if e = writeJSON(filepath.Join(root, "data/api-reference.json"), Object{"modelVersion": 1, "apis": models, "legacyAPIs": manifest.LegacyAPIs}); e != nil { + return e + } + } + return nil +} diff --git a/hack/api-docs/main_test.go b/hack/api-docs/main_test.go new file mode 100644 index 000000000000..6fab054f0515 --- /dev/null +++ b/hack/api-docs/main_test.go @@ -0,0 +1,429 @@ +package main + +import ( + js "github.com/santhosh-tekuri/jsonschema/v6" + "os" + "path/filepath" + "reflect" + "strings" + "testing" +) + +func fixture(t *testing.T, name string) *Document { + t.Helper() + d, e := loadDocument(filepath.Join("testdata", name), "validation/dialects") + if e != nil { + t.Fatal(e) + } + d.Source = Source{ID: "test"} + return d +} +func TestActualDialectAndReferences(t *testing.T) { + d := fixture(t, "valid.yaml") + d.validate("") + for _, x := range d.Diagnostics { + t.Errorf("%s: %s", x.Rule, x.Message) + } + if len(d.operations()) != 4 { + t.Fatal("operation omitted") + } + var query Object + for _, op := range d.operations() { + if op["method"] == "QUERY" { + query = op + } + } + if query == nil { + t.Fatal("QUERY omitted") + } + if obj(arr(query["servers"])[0])["url"] != "https://search.example.test" { + t.Fatal("path server override lost") + } + p := obj(arr(query["parameters"])[0]) + if p["example"] != jsonNumber("0") { + t.Fatalf("parameter override/zero lost: %#v", p["example"]) + } + if len(arr(query["parameters"])) != 1 { + t.Fatal("duplicate overridden parameter") + } +} + +func TestSequentialMediaEncodingPreserved(t *testing.T) { + d := fixture(t, "valid.yaml") + op := obj(obj(obj(d.Root["paths"])["/events"])["get"]) + response := obj(obj(op["responses"])["200"]) + encoding := Object{"contentType": "application/json", "headers": Object{ + "Content-Disposition": Object{"schema": Object{"type": "string"}}, + }} + response["content"] = Object{"multipart/mixed": Object{ + "itemSchema": true, "example": jsonNumber("0"), "itemEncoding": encoding, + }} + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("sequential media fixture must be valid: %+v", d.Diagnostics) + } + variants := d.variants(op, "/paths/~1events/get") + if len(variants) != 1 || !reflect.DeepEqual(obj(variants[0])["itemEncoding"], encoding) { + t.Fatalf("stream content types and part headers were lost: %#v", variants) + } +} + +func TestWebSocketDoesNotProducePlainHTTPRequest(t *testing.T) { + op := Object{"method": "GET", "path": "/interact", "raw": Object{ + "x-websocket": Object{"subprotocol": "sandboxes.v1"}, + }} + command, notes := curlExample(Source{}, op) + if command != "" || len(notes) == 0 || !strings.Contains(notes[0], "WebSocket") { + t.Fatalf("WebSocket operation must describe its client requirements, not a plain HTTP request: %q %v", command, notes) + } +} +func jsonNumber(s string) any { + v, e := js.UnmarshalJSON(strings.NewReader(s)) + if e != nil { + panic(e) + } + return v +} +func TestNegativeFixtures(t *testing.T) { + for _, tc := range []struct{ name, rule string }{{"invalid-info.yaml", "structure"}, {"invalid-item-type.yaml", "schema"}, {"invalid-example.yaml", "example"}, {"profile-missing-id.yaml", "S4"}} { + t.Run(tc.name, func(t *testing.T) { + d := fixture(t, tc.name) + d.validate("") + found := false + for _, x := range d.Diagnostics { + found = found || x.Rule == tc.rule + } + if !found { + t.Fatalf("missing %s diagnostic: %+v", tc.rule, d.Diagnostics) + } + }) + } + for _, name := range []string{"duplicate-key.yaml", "invalid-stream-ref.yaml"} { + t.Run(name, func(t *testing.T) { + d, e := loadDocument(filepath.Join("testdata", name), "validation/dialects") + if e == nil { + d.validate("") + for _, x := range d.Diagnostics { + if x.Rule == "reference" || x.Rule == "schema" { + return + } + } + t.Fatal("invalid source accepted") + } + }) + } +} +func TestSchemaSemantics(t *testing.T) { + d := fixture(t, "valid.yaml") + c := d.Compiler + cases := []struct { + name string + schema any + valid, invalid any + }{{"boolean false", false, nil, "x"}, {"ref siblings", Object{"$defs": Object{"base": Object{"type": "object", "required": []any{"a"}}}, "$ref": "#/$defs/base", "required": []any{"b"}}, Object{"a": true, "b": true}, Object{"b": true}}, {"recursive", Object{"type": "object", "properties": Object{"next": Object{"$ref": "#"}}}, Object{"next": Object{}}, Object{"next": 1}}, {"anchor", Object{"$defs": Object{"x": Object{"$anchor": "x", "type": "boolean"}}, "$ref": "#x"}, false, "false"}, {"dynamic", Object{"$dynamicAnchor": "node", "type": "object", "properties": Object{"child": Object{"$dynamicRef": "#node"}}}, Object{"child": Object{}}, Object{"child": false}}} + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + uri := "https://fixtures.test/" + strings.ReplaceAll(tc.name, " ", "-") + s := tc.schema + if m, ok := s.(map[string]any); ok { + m["$schema"] = dialect + } + if e := c.AddResource(uri, s); e != nil { + t.Fatal(e) + } + compiled, e := c.Compile(uri) + if e != nil { + t.Fatal(e) + } + if tc.valid != nil { + if e = compiled.Validate(tc.valid); e != nil { + t.Fatal(e) + } + } + if e = compiled.Validate(tc.invalid); e == nil { + t.Fatal("invalid example accepted") + } + }) + } +} +func TestAuthAndCurl(t *testing.T) { + schemes := Object{"bearer": Object{"type": "http", "scheme": "bearer"}, "key": Object{"type": "apiKey", "in": "header", "name": "X-Key"}} + op := Object{"method": "GET", "path": "/flag/{id}", "servers": []any{Object{"url": "https://api.test"}}, "securitySchemes": schemes, "security": []any{Object{"bearer": []any{}, "key": []any{}}, Object{}}, "parameters": []any{Object{"name": "id", "in": "path", "required": true, "example": "a/b"}, Object{"name": "enabled", "in": "query", "example": false}, Object{"name": "limit", "in": "query", "example": 0}}} + curl, _ := curlExample(Source{}, op) + for _, want := range []string{"a%2Fb", "enabled=false", "limit=0", "${TOKEN}", "X-Key: ${API_KEY}"} { + if !strings.Contains(curl, want) { + t.Errorf("missing %s: %s", want, curl) + } + } + op["security"] = []any{} + curl, _ = curlExample(Source{}, op) + if strings.Contains(curl, "Authorization") { + t.Fatal("anonymous operation gained auth") + } + op["method"] = "HEAD" + curl, _ = curlExample(Source{Connection: "unix", ID: "engine-1.56"}, op) + if !strings.Contains(curl, "--head") || !strings.Contains(curl, "--unix-socket") { + t.Fatal(curl) + } + d := &Document{} + root := Object{"security": []any{Object{"bearer": []any{}}}} + if !reflect.DeepEqual(d.effective(root, Object{}, Object{"security": []any{}}, "security"), []any{}) { + t.Fatal("empty override lost") + } +} +func TestFalseSchemaAndExamplePreserved(t *testing.T) { + b, e := os.ReadFile("testdata/valid.yaml") + if e != nil { + t.Fatal(e) + } + tmp := t.TempDir() + if e = os.WriteFile(filepath.Join(tmp, "spec.yaml"), []byte(strings.ReplaceAll(string(b), "schema: true", "schema: false")), 0600); e != nil { + t.Fatal(e) + } + if e = os.Mkdir(filepath.Join(tmp, "schemas"), 0700); e != nil { + t.Fatal(e) + } + event, _ := os.ReadFile("testdata/schemas/event.yaml") + os.WriteFile(filepath.Join(tmp, "schemas/event.yaml"), event, 0600) + d, e := loadDocument(filepath.Join(tmp, "spec.yaml"), "validation/dialects") + if e != nil { + t.Fatal(e) + } + d.validate("") + v, e := pointer(d.Root, "/paths/~1search/query/responses/200/content/application~1json/schema") + if e != nil || v != false { + t.Fatal("false schema changed") + } + for _, op := range d.operations() { + if op["path"] == "/public" { + ex := obj(arr(obj(arr(op["variants"])[0])["examples"])[0]) + if ex["value"] != false { + t.Fatal("false example omitted") + } + } + } +} + +func TestMediaExamplesFollowReferenceAnnotations(t *testing.T) { + d := &Document{URI: "https://example.test/api.yaml", Registry: &Registry{resources: map[string]any{ + "https://example.test/api.yaml": Object{ + "alias": Object{"$ref": "#/base", "examples": []any{false, jsonNumber("0")}}, + "base": Object{"example": "base example"}, + "cycle": Object{"$ref": "#/cycle"}, + }, + "https://example.test/schemas/alias.yaml": Object{"$ref": "base.yaml"}, + "https://example.test/schemas/base.yaml": Object{"example": "external example"}, + }}} + for _, tc := range []struct { + name string + media Object + values []any + }{ + {"intermediate annotations", Object{"schema": Object{"$ref": "#/alias"}}, []any{false, jsonNumber("0")}}, + {"nearest schema annotation", Object{"schema": Object{"$ref": "#/alias", "example": "local"}}, []any{"local"}}, + {"media annotation", Object{"example": false, "schema": Object{"$ref": "#/alias"}}, []any{false}}, + {"relative external reference", Object{"schema": Object{"$ref": "schemas/alias.yaml"}}, []any{"external example"}}, + {"cycle", Object{"schema": Object{"$ref": "#/cycle"}}, []any{}}, + } { + t.Run(tc.name, func(t *testing.T) { + values := []any{} + for _, ex := range d.mediaExamples(tc.media) { + values = append(values, obj(ex)["value"]) + } + if !reflect.DeepEqual(values, tc.values) { + t.Fatalf("examples = %#v, want %#v", values, tc.values) + } + }) + } +} + +func TestDVPResponseContracts(t *testing.T) { + d, err := loadDocument(filepath.Join("..", "..", "content", "reference", "api", "dvp", "latest.yaml"), "validation/dialects") + if err != nil { + t.Fatal(err) + } + d.Source = Source{ID: "dvp"} + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("DVP must pass without exceptions: %+v", d.Diagnostics) + } + for _, tc := range []struct { + schema string + value string + valid bool + }{ + {"TimespanModel", `{"month":7}`, true}, + {"TimespanModel", `{"week":31}`, true}, + {"TimespanModel", `{}`, false}, + {"TimespanModel", `{"month":7,"week":31}`, false}, + {"TimespanModel", `{"month":{"month":7}}`, false}, + {"TimespanModel", `7`, false}, + {"TimespanData", `{"months":[{"month":5},{"month":7}]}`, true}, + {"TimespanData", `{"weeks":[]}`, true}, + {"TimespanData", `{"months":[],"weeks":[]}`, false}, + {"TimespanData", `{"months":[{}]}`, false}, + {"TimespanData", `{"weeks":null}`, false}, + {"NamespaceMetadata", `{"namespace":"org1","extraRepos":null,"extensionPublisher":false}`, true}, + {"PullData", `{"pulls":null}`, true}, + {"PullData", `{"pulls":[{"start":"2022-08-01T00:00:00Z","pullCount":0}]}`, true}, + } { + t.Run(tc.schema+"/"+tc.value, func(t *testing.T) { + s, err := d.Compiler.Compile(d.URI + "#/components/schemas/" + tc.schema) + if err != nil { + t.Fatal(err) + } + value, err := js.UnmarshalJSON(strings.NewReader(tc.value)) + if err != nil { + t.Fatal(err) + } + if err := s.Validate(value); (err == nil) != tc.valid { + t.Fatalf("valid = %t, want %t: %v", err == nil, tc.valid, err) + } + }) + } +} + +func TestTimestampStringsRetainSpelling(t *testing.T) { + p := filepath.Join(t.TempDir(), "schema.yaml") + if e := os.WriteFile(p, []byte("type: string\nexample: 2021-01-05T21:06:53.506400Z\n"), 0600); e != nil { + t.Fatal(e) + } + v, e := strictFragment(p) + if e != nil { + t.Fatal(e) + } + if obj(v)["example"] != "2021-01-05T21:06:53.506400Z" { + t.Fatalf("timestamp spelling changed: %v", v) + } +} +func TestCaseSensitiveSchemaRoutes(t *testing.T) { + if slug("Error") == slug("error") { + t.Fatal("schema route collision") + } +} +func TestUnlockedResourcesAndUnknownDialect(t *testing.T) { + d := fixture(t, "valid.yaml") + if _, e := d.Compiler.Compile("https://unlocked.test/schema"); e == nil { + t.Fatal("unlocked schema fetched") + } + if e := d.Compiler.AddResource("https://fixtures.test/custom", Object{"$schema": "https://unlocked.test/dialect", "type": "object"}); e != nil { + t.Fatal(e) + } + if _, e := d.Compiler.Compile("https://fixtures.test/custom"); e == nil { + t.Fatal("unknown dialect accepted") + } +} + +func TestUndefinedSecurityRequirements(t *testing.T) { + for _, inherited := range []bool{false, true} { + d := fixture(t, "valid.yaml") + requirements := []any{Object{"bearerAuth": []any{}}, Object{"missingAuth": []any{}}} + if inherited { + d.Root["security"] = requirements + } else { + obj(obj(obj(d.Root["paths"])["/public"])["get"])["security"] = requirements + } + d.validate("") + found := false + for _, diagnostic := range d.Diagnostics { + if diagnostic.Rule == "security" && strings.Contains(diagnostic.Message, "missingAuth") { + found = true + } + } + if !found { + t.Fatalf("undefined security accepted (inherited=%v)", inherited) + } + } +} + +func TestReferencedMediaExample(t *testing.T) { + d := fixture(t, "valid.yaml") + obj(d.Root["components"])["examples"] = Object{"Flag": Object{"value": false}} + media := obj(obj(obj(obj(obj(d.Root["paths"])["/public"])["get"])["responses"])["200"]) + v := obj(obj(media["content"])["application/json"]) + delete(v, "example") + v["examples"] = Object{"flag": Object{"$ref": "#/components/examples/Flag"}} + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("referenced example rejected: %v", d.Diagnostics) + } + examples := d.mediaExamples(v) + if len(examples) != 1 || obj(examples[0])["value"] != false { + t.Fatalf("referenced false example lost: %#v", examples) + } +} + +func TestExternalDynamicReference(t *testing.T) { + original, err := os.ReadFile("testdata/valid.yaml") + if err != nil { + t.Fatal(err) + } + dir := t.TempDir() + if err := os.Mkdir(filepath.Join(dir, "schemas"), 0755); err != nil { + t.Fatal(err) + } + event, err := os.ReadFile("testdata/schemas/event.yaml") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "schemas/event.yaml"), event, 0644); err != nil { + t.Fatal(err) + } + file := filepath.Join(dir, "api.yaml") + if err := os.WriteFile(file, []byte(strings.Replace(string(original), "$ref: ./schemas/event.yaml", "$dynamicRef: ./schemas/event.yaml", 1)), 0644); err != nil { + t.Fatal(err) + } + d, err := loadDocument(file, "validation/dialects") + if err != nil { + t.Fatal(err) + } + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("external dynamic reference rejected: %v", d.Diagnostics) + } +} + +func TestExamplesAreOptionalButValidatedWhenPresent(t *testing.T) { + d := fixture(t, "valid.yaml") + var remove func(any) + remove = func(value any) { + switch v := value.(type) { + case map[string]any: + delete(v, "example") + delete(v, "examples") + for _, child := range v { + remove(child) + } + case []any: + for _, child := range v { + remove(child) + } + } + } + remove(d.Root) + d.validate("") + if len(d.Diagnostics) != 0 { + t.Fatalf("missing examples must be accepted: %+v", d.Diagnostics) + } + invalid := fixture(t, "invalid-example.yaml") + invalid.validate("") + for _, diagnostic := range invalid.Diagnostics { + if diagnostic.Rule == "example" { + return + } + } + t.Fatal("invalid supplied example must still fail") +} + +func TestRequestWithoutExampleUsesBodyFile(t *testing.T) { + op := Object{"method": "POST", "path": "/jobs", "servers": []any{Object{"url": "https://api.test"}}, + "variants": []any{Object{"direction": "Request", "media": "application/json", "required": true, "examples": []any{}}}, + } + command, notes := curlExample(Source{}, op) + if !strings.Contains(command, "--data-binary @request-body") || strings.Contains(command, "--data-raw") { + t.Fatalf("request must use a body file, not an invented payload: %s", command) + } + if !strings.Contains(strings.Join(notes, " "), "Prepare request-body") { + t.Fatalf("missing body instructions: %v", notes) + } +} diff --git a/hack/api-docs/model.go b/hack/api-docs/model.go new file mode 100644 index 000000000000..9af969d8768d --- /dev/null +++ b/hack/api-docs/model.go @@ -0,0 +1,296 @@ +package main + +import ( + "net/url" + "sort" + "strings" +) + +func route(id string) string { + return "/reference/api/" + id + "/latest/" +} +func slug(s string) string { return url.PathEscape(s) } +func (d *Document) model() Object { + ops := d.operations() + schemas := []any{} + schemaURLs := Object{} + for _, name := range keys(obj(obj(d.Root["components"])["schemas"])) { + p := "/components/schemas/" + esc(name) + u := route(d.Source.ID) + "schemas/" + slug(name) + "/" + schemaURLs["#"+p] = u + schemas = append(schemas, Object{"name": name, "pointer": p, "url": u, "schema": obj(obj(d.Root["components"])["schemas"])[name]}) + } + for _, op := range ops { + for _, raw := range arr(op["variants"]) { + v := obj(raw) + for _, rawEx := range arr(v["examples"]) { + ex := obj(rawEx) + ex["text"], ex["language"] = exampleText(str(v["media"]), ex["value"]) + } + } + } + for _, op := range ops { + op["url"] = route(d.Source.ID) + "operations/" + slug(str(op["id"])) + "/" + op["securitySchemes"] = obj(d.Root["components"])["securitySchemes"] + op["acceptMedia"] = responseMedia(op) + // HEAD negotiates the GET representation but has no response body. + if op["method"] == "HEAD" && op["acceptMedia"] == "" { + for _, get := range ops { + if get["method"] == "GET" && get["path"] == op["path"] { + op["acceptMedia"] = responseMedia(get) + break + } + } + } + op["curl"], op["curlNotes"] = curlExample(d.Source, op) + op["references"] = refs(op["raw"], schemaURLs) + op["requestSchema"] = firstRequestSchema(op) + } + return Object{"experimental": d.Source.Experimental, "id": d.Source.ID, "product": d.Source.Product, "title": d.Source.Title, "version": obj(d.Root["info"])["version"], "description": obj(d.Root["info"])["description"], "url": route(d.Source.ID), "manual": d.Source.Manual, "guides": d.Source.Guides, "connection": d.Source.Connection, "servers": d.Root["servers"], "securitySchemes": obj(d.Root["components"])["securitySchemes"], "tags": d.Root["tags"], "operations": ops, "schemas": schemas, "schemaURLs": schemaURLs, "digest": d.Digest, "owner": d.Source.Owner, "source": d.Source.Source, "sourceURL": "/" + strings.TrimPrefix(d.Source.Source, "content/"), "diagnostics": d.Diagnostics, "schemaCount": d.SchemaCount, "exampleCount": d.ExampleCount} +} +func refs(v any, urls Object) []any { + found := map[string]bool{} + walk(v, "", func(n Object, _ string) { + if s := str(n["$ref"]); s != "" { + found[s] = true + } + }) + out := []any{} + names := []string{} + for n := range found { + names = append(names, n) + } + sort.Strings(names) + for _, n := range names { + out = append(out, Object{"ref": n, "url": urls[n]}) + } + return out +} +func firstRequestSchema(op Object) any { + for _, v := range arr(op["variants"]) { + m := obj(v) + if m["direction"] == "Request" { + return m["schema"] + } + } + return nil +} +func shell(s string) string { return "'" + strings.ReplaceAll(s, "'", "'\"'\"'") + "'" } +func scalar(v any) string { + if s, ok := v.(string); ok { + return s + } + return strings.TrimSpace(string(encoded(v))) +} +func parameterValue(p Object) (any, bool) { + if v, ok := p["example"]; ok { + return v, true + } + s := obj(p["schema"]) + if v, ok := s["example"]; ok { + return v, true + } + if a := arr(s["examples"]); len(a) > 0 { + return a[0], true + } + return nil, false +} + +func exampleText(media string, value any) (string, string) { + if s, ok := value.(string); ok && !strings.Contains(media, "json") { + return s, "text" + } + return strings.TrimSpace(string(encoded(value))), "json" +} + +func responseMedia(op Object) string { + for _, raw := range arr(op["variants"]) { + v := obj(raw) + if v["direction"] == "Response" && strings.HasPrefix(str(v["status"]), "2") && str(v["media"]) != "" { + return str(v["media"]) + } + } + return "" +} + +func curlExample(src Source, op Object) (string, []string) { + if len(obj(obj(op["raw"])["x-websocket"])) > 0 { + return "", []string{"Use a WebSocket client with the subprotocol, credential transport, and frame schemas documented for this operation."} + } + notes := []string{} + args := []string{"curl"} + if op["method"] == "HEAD" { + args = append(args, "--head") + } else { + args = append(args, "--request "+str(op["method"])) + } + server := "" + if a := arr(op["servers"]); len(a) > 0 { + m := obj(a[0]) + server = str(m["url"]) + for name, v := range obj(m["variables"]) { + server = strings.ReplaceAll(server, "{"+name+"}", str(obj(v)["default"])) + } + } + if src.Connection == "unix" { + args = append(args, "--unix-socket \"${DOCKER_SOCKET:-/var/run/docker.sock}\"") + if !strings.HasPrefix(server, "/") { + server = "/v" + strings.TrimPrefix(src.ID, "engine-") + } + server = "http://localhost" + server + } + if server == "" { + server = "https://<SERVER>" + notes = append(notes, "Set the API server address.") + } + target := strings.TrimRight(server, "/") + str(op["path"]) + query := []string{} + for _, raw := range arr(op["parameters"]) { + p := obj(raw) + name := str(p["name"]) + v, has := parameterValue(p) + required, _ := p["required"].(bool) + if !has && !required { + continue + } + value := "<" + strings.ToUpper(name) + ">" + if has { + value = scalar(v) + } + location := str(p["in"]) + if location == "path" { + part := value + if has { + part = url.PathEscape(value) + } + target = strings.ReplaceAll(target, "{"+name+"}", part) + } else if location == "header" { + args = append(args, "--header "+shell(name+": "+value)) + } else if location == "query" { + style := str(p["style"]) + if style == "" { + style = "form" + } + explode := true + if x, ok := p["explode"].(bool); ok { + explode = x + } + if list, ok := v.([]any); ok && style == "form" { + parts := []string{} + for _, x := range list { + parts = append(parts, scalar(x)) + } + if explode { + for _, x := range parts { + query = append(query, url.QueryEscape(name)+"="+url.QueryEscape(x)) + } + } else { + query = append(query, url.QueryEscape(name)+"="+url.QueryEscape(strings.Join(parts, ","))) + } + } else if len(obj(v)) > 0 || style != "form" { + notes = append(notes, "Serialize "+name+" using its documented "+style+" rules; this parameter is not generated.") + } else { + query = append(query, url.QueryEscape(name)+"="+url.QueryEscape(value)) + } + } else { + notes = append(notes, "Supply "+name+" using its documented "+location+" encoding.") + } + } + if len(query) > 0 { + target += "?" + strings.Join(query, "&") + } + security := arr(op["security"]) + if len(security) > 0 { + first := obj(security[0]) + for _, scheme := range keys(first) { + definition := obj(obj(op["securitySchemes"])[scheme]) + switch { + case definition["type"] == "http" && definition["scheme"] == "bearer": + token := "TOKEN" + if scheme == "scimToken" { + token = "SCIM_TOKEN" + } + if scheme == "registryToken" { + token = "REGISTRY_TOKEN" + } + args = append(args, "--header \"Authorization: Bearer ${"+token+"}\"") + case definition["type"] == "apiKey" && definition["in"] == "header": + args = append(args, "--header \""+str(definition["name"])+": ${API_KEY}\"") + default: + notes = append(notes, "Configure authentication scheme "+scheme+" using its documented transport or credential format.") + } + } + if len(security) > 1 { + notes = append(notes, "This example uses the first authentication alternative. Review the complete requirements.") + } + } + if media := str(op["acceptMedia"]); media != "" { + args = append(args, "--header "+shell("Accept: "+media)) + } + for _, raw := range arr(op["variants"]) { + v := obj(raw) + if v["direction"] != "Request" { + continue + } + media := str(v["media"]) + if media == "" { + continue + } + args = append(args, "--header "+shell("Content-Type: "+media)) + examples := arr(v["examples"]) + if len(examples) > 0 && strings.Contains(media, "json") { + args = append(args, "--data-raw "+shell(strings.TrimSpace(string(encoded(obj(examples[0])["value"]))))) + } else { + args = append(args, "--data-binary @request-body") + notes = append(notes, "Prepare request-body using the selected media type and schema.") + } + break + } + args = append(args, shell(target)) + return strings.Join(args, " \\\n "), notes +} + +// Examples are annotations: retrieve them without flattening schema constraints. +func (d *Document) mediaExamples(v Object) []any { + out := d.exampleList(v) + if len(out) > 0 { + return out + } + s := v["schema"] + seen := map[string]bool{} + base, _ := url.Parse(d.URI) + for s != nil { + n := obj(s) + if x, ok := n["example"]; ok { + return []any{Object{"name": "Schema example", "value": x}} + } + if xs := arr(n["examples"]); len(xs) > 0 { + for _, x := range xs { + out = append(out, Object{"name": "Schema example", "value": x}) + } + return out + } + ref := str(n["$ref"]) + if ref == "" { + break + } + u, err := url.Parse(ref) + if err != nil { + break + } + u = base.ResolveReference(u) + if seen[u.String()] { + break + } + seen[u.String()] = true + fragment := u.Fragment + u.Fragment = "" + // Follow one reference at a time so intermediate schema annotations survive. + s, err = pointer(d.Registry.resources[u.String()], fragment) + if err != nil { + break + } + base = u + } + return out +} diff --git a/hack/api-docs/run.sh b/hack/api-docs/run.sh new file mode 100755 index 000000000000..b079e66754b3 --- /dev/null +++ b/hack/api-docs/run.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail +ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd) +cd "$ROOT" +mkdir -p "$ROOT/tmp/api-reference/reports" +export GOWORK=off +api_docs() { + (cd hack/api-docs && go run . "$@" "$ROOT") +} +policy() { + local sources + sources=$(api_docs sources) + while IFS=$'\t' read -r api source; do + vacuum lint --no-update-check --remote=false --ruleset hack/api-docs/validation/rules.yaml --fail-severity error --min-score 0 --no-banner --no-style --details "$source" > "tmp/api-reference/reports/$api-vacuum.txt" 2>&1 || { + cat "tmp/api-reference/reports/$api-vacuum.txt"; return 1; + } + done <<< "$sources" +} +case "${1:-build}" in + check|generate) policy; api_docs "$1" ;; + test) (cd hack/api-docs && go test ./...) ;; + build|serve) + hugo --destination tmp/api-reference/site --baseURL "${DOCS_URL:-http://localhost:1314}" --cleanDestinationDir + node hack/flatten-and-resolve.js tmp/api-reference/site + node hack/api-docs/verify-output.mjs tmp/api-reference/site + if [[ "${1:-build}" == serve ]]; then + exec python3 -m http.server "${DOCS_PORT:-1314}" --bind 127.0.0.1 --directory tmp/api-reference/site + fi + ;; + *) printf '%s\n' 'Usage: run.sh check|generate|test|build|serve' >&2; exit 2 ;; +esac diff --git a/hack/api-docs/sources.json b/hack/api-docs/sources.json new file mode 100644 index 000000000000..4928579a9f34 --- /dev/null +++ b/hack/api-docs/sources.json @@ -0,0 +1,66 @@ +{ + "apis": [ + { + "id": "hub", + "product": "hub", + "title": "Docker Hub", + "source": "content/reference/api/hub/latest.yaml", + "owner": "docker/docs", + "manual": "/manuals/docker-hub/", + "connection": "hosted", + "guides": ["/manuals/security/provisioning/scim/provision-scim.md"] + }, + { + "id": "dvp", + "product": "dvp", + "title": "Publisher analytics", + "source": "content/reference/api/dvp/latest.yaml", + "owner": "docker/docs", + "manual": "/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md", + "connection": "hosted", + "guides": [] + }, + { + "id": "registry", + "product": "registry", + "title": "Registry", + "source": "content/reference/api/registry/latest.yaml", + "owner": "docker/docs", + "manual": "/manuals/docker-hub/repos/", + "connection": "hosted", + "guides": ["/reference/api/registry/auth.md"] + }, + { + "id": "ai-governance", + "product": "ai-governance", + "title": "AI Governance", + "source": "content/reference/api/ai-governance/api.yaml", + "owner": "docker/governor-services", + "manual": "/manuals/ai/sandboxes/governance/", + "connection": "hosted", + "guides": [] + }, + { + "id": "sandboxes", + "product": "sandboxes", + "title": "Docker Sandboxes", + "source": "content/reference/api/sandboxes/api.yaml", + "owner": "docker/sbx-api", + "manual": "/manuals/ai/sandboxes-api/", + "connection": "hosted", + "experimental": true, + "guides": [ + "/manuals/ai/sandboxes-api/authentication.md", + "/manuals/ai/sandboxes-api/get-started.md" + ] + } + ], + "legacyAPIs": [ + { + "title": "Docker Engine", + "url": "/reference/api/engine/", + "connection": "unix", + "description": "Manage containers, images, networks, and volumes." + } + ] +} diff --git a/hack/api-docs/testdata/duplicate-key.yaml b/hack/api-docs/testdata/duplicate-key.yaml new file mode 100644 index 000000000000..739c796ab82b --- /dev/null +++ b/hack/api-docs/testdata/duplicate-key.yaml @@ -0,0 +1,102 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: '1' + version: '2' + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/event.yaml + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/invalid-example.yaml b/hack/api-docs/testdata/invalid-example.yaml new file mode 100644 index 000000000000..37015deb1a44 --- /dev/null +++ b/hack/api-docs/testdata/invalid-example.yaml @@ -0,0 +1,101 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: '1' + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/event.yaml + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: not-a-boolean + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/invalid-info.yaml b/hack/api-docs/testdata/invalid-info.yaml new file mode 100644 index 000000000000..3280debcaee6 --- /dev/null +++ b/hack/api-docs/testdata/invalid-info.yaml @@ -0,0 +1,100 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/event.yaml + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/invalid-item-type.yaml b/hack/api-docs/testdata/invalid-item-type.yaml new file mode 100644 index 000000000000..524584656267 --- /dev/null +++ b/hack/api-docs/testdata/invalid-item-type.yaml @@ -0,0 +1,101 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: '1' + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + type: definitely-invalid + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/invalid-stream-ref.yaml b/hack/api-docs/testdata/invalid-stream-ref.yaml new file mode 100644 index 000000000000..7d4edd2052bb --- /dev/null +++ b/hack/api-docs/testdata/invalid-stream-ref.yaml @@ -0,0 +1,101 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: '1' + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/missing.yaml + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/profile-missing-id.yaml b/hack/api-docs/testdata/profile-missing-id.yaml new file mode 100644 index 000000000000..99fba5ceccbd --- /dev/null +++ b/hack/api-docs/testdata/profile-missing-id.yaml @@ -0,0 +1,100 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: '1' + description: Component capability fixture. +servers: +- url: https://api.example.test/v1 +security: +- bearerAuth: [] +tags: +- name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + responses: + '200': + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/event.yaml + /search: + parameters: + - name: limit + in: query + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + parameters: + - name: limit + in: query + schema: + type: integer + example: 0 + responses: + '200': + description: Search result + content: + application/json: + schema: true + /public: + get: + tags: + - operations + summary: Public result + security: [] + responses: + '200': + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + responses: + '200': + description: Item + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + description: Description beside a reference. +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: '#/components/schemas/Item' + - type: 'null' diff --git a/hack/api-docs/testdata/schemas/event.yaml b/hack/api-docs/testdata/schemas/event.yaml new file mode 100644 index 000000000000..b158529a5656 --- /dev/null +++ b/hack/api-docs/testdata/schemas/event.yaml @@ -0,0 +1,9 @@ +type: object +required: +- event +- data +properties: + event: + type: string + data: + type: string diff --git a/hack/api-docs/testdata/valid.yaml b/hack/api-docs/testdata/valid.yaml new file mode 100644 index 000000000000..3ec382de30c6 --- /dev/null +++ b/hack/api-docs/testdata/valid.yaml @@ -0,0 +1,110 @@ +openapi: 3.2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Docker documentation tooling fixture + version: "1" + description: Component capability fixture. +servers: + - url: https://api.example.test/v1 +security: + - bearerAuth: [] +tags: + - name: operations + summary: Operations + kind: nav + description: Fixture operations. +paths: + /events: + get: + operationId: listEvents + tags: + - operations + summary: List events + description: List events. + responses: + "200": + description: Event stream + content: + text/event-stream: + itemSchema: + $ref: ./schemas/event.yaml + example: { event: message, data: hello } + /search: + parameters: + - name: limit + in: query + description: Maximum number of results. + schema: + type: integer + example: 10 + servers: + - url: https://search.example.test + query: + operationId: querySearch + tags: + - operations + summary: Search + description: Search. + parameters: + - name: limit + in: query + description: Maximum number of results. + schema: + type: integer + example: 0 + responses: + "200": + description: Search result + content: + application/json: + schema: true + example: 0 + /public: + get: + operationId: getPublic + tags: + - operations + summary: Public result + description: Public result. + security: [] + responses: + "200": + description: A flag + content: + application/json: + schema: + type: boolean + example: false + /items: + get: + operationId: getItems + tags: + - operations + summary: Get items + description: Get items. + responses: + "200": + description: Item + content: + application/json: + schema: + $ref: "#/components/schemas/Item" + description: Description beside a reference. + example: { id: 1, next: { id: 2, next: null } } +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + schemas: + Item: + type: object + required: + - id + properties: + id: + type: integer + next: + anyOf: + - $ref: "#/components/schemas/Item" + - type: "null" diff --git a/hack/api-docs/validation/dialects/lock.json b/hack/api-docs/validation/dialects/lock.json new file mode 100644 index 000000000000..7fb2c1b1cdad --- /dev/null +++ b/hack/api-docs/validation/dialects/lock.json @@ -0,0 +1,20 @@ +[ + { + "file": "oas-dialect.json", + "uri": "https://spec.openapis.org/oas/3.1/dialect/base", + "resolvedURL": "https://spec.openapis.org/oas/3.1/dialect/base", + "sha256": "8a0e89e365dadbebce2921ce6244340c1090e9d544c60d977e9ad6b97a61227b" + }, + { + "file": "oas-vocabulary.json", + "uri": "https://spec.openapis.org/oas/3.1/meta/base", + "resolvedURL": "https://spec.openapis.org/oas/3.1/meta/base", + "sha256": "267a88226e64e96dfc8c89dbd7e863160c84715e0fb893ca1d9fbf9f830f1f54" + }, + { + "file": "oas-document.json", + "uri": "https://spec.openapis.org/oas/3.2/schema/2025-09-17", + "resolvedURL": "https://spec.openapis.org/oas/3.2/schema/2025-09-17", + "sha256": "0c9d74bf25f9b9388b2d81e421ef60fdefa9feffa94898dadfc501b342b3bfcc" + } +] diff --git a/hack/api-docs/validation/dialects/oas-dialect.json b/hack/api-docs/validation/dialects/oas-dialect.json new file mode 100644 index 000000000000..eae8386e8ad3 --- /dev/null +++ b/hack/api-docs/validation/dialects/oas-dialect.json @@ -0,0 +1,25 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/dialect/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + + "title": "OpenAPI 3.1 Schema Object Dialect", + "description": "A JSON Schema dialect describing schemas found in OpenAPI documents", + + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/core": true, + "https://json-schema.org/draft/2020-12/vocab/applicator": true, + "https://json-schema.org/draft/2020-12/vocab/unevaluated": true, + "https://json-schema.org/draft/2020-12/vocab/validation": true, + "https://json-schema.org/draft/2020-12/vocab/meta-data": true, + "https://json-schema.org/draft/2020-12/vocab/format-annotation": true, + "https://json-schema.org/draft/2020-12/vocab/content": true, + "https://spec.openapis.org/oas/3.1/vocab/base": false + }, + + "$dynamicAnchor": "meta", + + "allOf": [ + { "$ref": "https://json-schema.org/draft/2020-12/schema" }, + { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } + ] +} diff --git a/hack/api-docs/validation/dialects/oas-document.json b/hack/api-docs/validation/dialects/oas-document.json new file mode 100644 index 000000000000..9453eeb20bec --- /dev/null +++ b/hack/api-docs/validation/dialects/oas-document.json @@ -0,0 +1,1666 @@ +{ + "$id": "https://spec.openapis.org/oas/3.2/schema/2025-09-17", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The description of OpenAPI v3.2.x Documents without Schema Object validation", + "type": "object", + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.2\\.\\d+(-.+)?$" + }, + "$self": { + "type": "string", + "format": "uri-reference", + "$comment": "MUST NOT contain a fragment", + "pattern": "^[^#]*$" + }, + "info": { + "$ref": "#/$defs/info" + }, + "jsonSchemaDialect": { + "type": "string", + "format": "uri-reference", + "default": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + }, + "default": [ + { + "url": "/" + } + ] + }, + "paths": { + "$ref": "#/$defs/paths" + }, + "webhooks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item" + } + }, + "components": { + "$ref": "#/$defs/components" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/$defs/tag" + } + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "openapi", + "info" + ], + "anyOf": [ + { + "required": [ + "paths" + ] + }, + { + "required": [ + "components" + ] + }, + { + "required": [ + "webhooks" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "info": { + "$comment": "https://spec.openapis.org/oas/v3.2#info-object", + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string", + "format": "uri-reference" + }, + "contact": { + "$ref": "#/$defs/contact" + }, + "license": { + "$ref": "#/$defs/license" + }, + "version": { + "type": "string" + } + }, + "required": [ + "title", + "version" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "contact": { + "$comment": "https://spec.openapis.org/oas/v3.2#contact-object", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + }, + "email": { + "type": "string", + "format": "email" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "license": { + "$comment": "https://spec.openapis.org/oas/v3.2#license-object", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "identifier": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "required": [ + "name" + ], + "dependentSchemas": { + "identifier": { + "not": { + "required": [ + "url" + ] + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server": { + "$comment": "https://spec.openapis.org/oas/v3.2#server-object", + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/server-variable" + } + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server-variable": { + "$comment": "https://spec.openapis.org/oas/v3.2#server-variable-object", + "type": "object", + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "default": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "required": [ + "default" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "components": { + "$comment": "https://spec.openapis.org/oas/v3.2#components-object", + "type": "object", + "properties": { + "schemas": { + "type": "object", + "additionalProperties": { + "$dynamicRef": "#meta" + } + }, + "responses": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/response-or-reference" + } + }, + "parameters": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + }, + "requestBodies": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/request-body-or-reference" + } + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "securitySchemes": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/security-scheme-or-reference" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "pathItems": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item" + } + }, + "mediaTypes": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type-or-reference" + } + } + }, + "patternProperties": { + "^(?:schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems|mediaTypes)$": { + "$comment": "Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected", + "propertyNames": { + "pattern": "^[a-zA-Z0-9._-]+$" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "paths": { + "$comment": "https://spec.openapis.org/oas/v3.2#paths-object", + "type": "object", + "patternProperties": { + "^/": { + "$ref": "#/$defs/path-item" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item": { + "$comment": "https://spec.openapis.org/oas/v3.2#path-item-object", + "type": "object", + "properties": { + "$ref": { + "type": "string", + "format": "uri-reference" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "parameters": { + "$ref": "#/$defs/parameters" + }, + "additionalOperations": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/operation" + }, + "propertyNames": { + "$comment": "RFC9110 restricts methods to \"1*tchar\" in ABNF", + "pattern": "^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$", + "not": { + "enum": [ + "GET", + "PUT", + "POST", + "DELETE", + "OPTIONS", + "HEAD", + "PATCH", + "TRACE", + "QUERY" + ] + } + } + }, + "get": { + "$ref": "#/$defs/operation" + }, + "put": { + "$ref": "#/$defs/operation" + }, + "post": { + "$ref": "#/$defs/operation" + }, + "delete": { + "$ref": "#/$defs/operation" + }, + "options": { + "$ref": "#/$defs/operation" + }, + "head": { + "$ref": "#/$defs/operation" + }, + "patch": { + "$ref": "#/$defs/operation" + }, + "trace": { + "$ref": "#/$defs/operation" + }, + "query": { + "$ref": "#/$defs/operation" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "operation": { + "$comment": "https://spec.openapis.org/oas/v3.2#operation-object", + "type": "object", + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "$ref": "#/$defs/parameters" + }, + "requestBody": { + "$ref": "#/$defs/request-body-or-reference" + }, + "responses": { + "$ref": "#/$defs/responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "external-documentation": { + "$comment": "https://spec.openapis.org/oas/v3.2#external-documentation-object", + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + }, + "not": { + "allOf": [ + { + "contains": { + "type": "object", + "properties": { + "in": { + "const": "query" + } + }, + "required": [ + "in" + ] + } + }, + { + "contains": { + "type": "object", + "properties": { + "in": { + "const": "querystring" + } + }, + "required": [ + "in" + ] + } + } + ] + }, + "contains": { + "type": "object", + "properties": { + "in": { + "const": "querystring" + } + }, + "required": [ + "in" + ] + }, + "minContains": 0, + "maxContains": 1 + }, + "parameter": { + "$comment": "https://spec.openapis.org/oas/v3.2#parameter-object", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "querystring", + "header", + "path", + "cookie" + ] + }, + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "$ref": "#/$defs/content", + "minProperties": 1, + "maxProperties": 1 + } + }, + "required": [ + "name", + "in" + ], + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/specification-extensions" + }, + { + "if": { + "properties": { + "in": { + "const": "query" + } + } + }, + "then": { + "properties": { + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + } + } + }, + { + "if": { + "properties": { + "in": { + "const": "querystring" + } + } + }, + "then": { + "required": [ + "content" + ] + } + } + ], + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie" + }, + { + "$ref": "#/$defs/styles-for-form" + } + ], + "$defs": { + "styles-for-path": { + "if": { + "properties": { + "in": { + "const": "path" + } + } + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "matrix", + "label", + "simple" + ] + }, + "required": { + "const": true + } + }, + "required": [ + "required" + ] + } + }, + "styles-for-header": { + "if": { + "properties": { + "in": { + "const": "header" + } + } + }, + "then": { + "properties": { + "style": { + "default": "simple", + "const": "simple" + } + } + } + }, + "styles-for-query": { + "if": { + "properties": { + "in": { + "const": "query" + } + } + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + } + } + } + }, + "styles-for-cookie": { + "if": { + "properties": { + "in": { + "const": "cookie" + } + } + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form", + "cookie" + ] + } + } + } + } + } + } + }, + "unevaluatedProperties": false + }, + "parameter-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/parameter" + } + }, + "request-body": { + "$comment": "https://spec.openapis.org/oas/v3.2#request-body-object", + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "content": { + "$ref": "#/$defs/content" + }, + "required": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "content" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "request-body-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/request-body" + } + }, + "content": { + "$comment": "https://spec.openapis.org/oas/v3.2#fixed-fields-10", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type-or-reference" + }, + "propertyNames": { + "format": "media-range" + } + }, + "media-type": { + "$comment": "https://spec.openapis.org/oas/v3.2#media-type-object", + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "itemSchema": { + "$dynamicRef": "#meta" + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/encoding" + } + }, + "prefixEncoding": { + "type": "array", + "items": { + "$ref": "#/$defs/encoding" + } + }, + "itemEncoding": { + "$ref": "#/$defs/encoding" + } + }, + "dependentSchemas": { + "encoding": { + "properties": { + "prefixEncoding": false, + "itemEncoding": false + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/specification-extensions" + } + ], + "unevaluatedProperties": false + }, + "media-type-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/media-type" + } + }, + "encoding": { + "$comment": "https://spec.openapis.org/oas/v3.2#encoding-object", + "type": "object", + "properties": { + "contentType": { + "type": "string", + "format": "media-range" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "style": { + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean" + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/encoding" + } + }, + "prefixEncoding": { + "type": "array", + "items": { + "$ref": "#/$defs/encoding" + } + }, + "itemEncoding": { + "$ref": "#/$defs/encoding" + } + }, + "dependentSchemas": { + "encoding": { + "properties": { + "prefixEncoding": false, + "itemEncoding": false + } + }, + "style": { + "properties": { + "allowReserved": { + "default": false + } + } + }, + "explode": { + "properties": { + "style": { + "default": "form" + }, + "allowReserved": { + "default": false + } + } + }, + "allowReserved": { + "properties": { + "style": { + "default": "form" + } + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/styles-for-form" + } + ], + "unevaluatedProperties": false + }, + "responses": { + "$comment": "https://spec.openapis.org/oas/v3.2#responses-object", + "type": "object", + "properties": { + "default": { + "$ref": "#/$defs/response-or-reference" + } + }, + "patternProperties": { + "^[1-5](?:[0-9]{2}|XX)$": { + "$ref": "#/$defs/response-or-reference" + } + }, + "minProperties": 1, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "if": { + "$comment": "either default, or at least one response code property must exist", + "patternProperties": { + "^[1-5](?:[0-9]{2}|XX)$": false + } + }, + "then": { + "required": [ + "default" + ] + } + }, + "response": { + "$comment": "https://spec.openapis.org/oas/v3.2#response-object", + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "content": { + "$ref": "#/$defs/content" + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/response" + } + }, + "callbacks": { + "$comment": "https://spec.openapis.org/oas/v3.2#callback-object", + "type": "object", + "$ref": "#/$defs/specification-extensions", + "additionalProperties": { + "$ref": "#/$defs/path-item" + } + }, + "callbacks-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/callbacks" + } + }, + "example": { + "$comment": "https://spec.openapis.org/oas/v3.2#example-object", + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "dataValue": true, + "serializedValue": { + "type": "string" + }, + "value": true, + "externalValue": { + "type": "string", + "format": "uri-reference" + } + }, + "allOf": [ + { + "not": { + "required": [ + "value", + "externalValue" + ] + } + }, + { + "not": { + "required": [ + "value", + "dataValue" + ] + } + }, + { + "not": { + "required": [ + "value", + "serializedValue" + ] + } + }, + { + "not": { + "required": [ + "serializedValue", + "externalValue" + ] + } + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "example-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/example" + } + }, + "link": { + "$comment": "https://spec.openapis.org/oas/v3.2#link-object", + "type": "object", + "properties": { + "operationRef": { + "type": "string", + "format": "uri-reference" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "$ref": "#/$defs/map-of-strings" + }, + "requestBody": true, + "description": { + "type": "string" + }, + "server": { + "$ref": "#/$defs/server" + } + }, + "oneOf": [ + { + "required": [ + "operationRef" + ] + }, + { + "required": [ + "operationId" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "link-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/link" + } + }, + "header": { + "$comment": "https://spec.openapis.org/oas/v3.2#header-object", + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "$ref": "#/$defs/content", + "minProperties": 1, + "maxProperties": 1 + } + }, + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "default": "simple", + "const": "simple" + }, + "explode": { + "default": false, + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/specification-extensions" + } + ], + "unevaluatedProperties": false + }, + "header-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/header" + } + }, + "tag": { + "$comment": "https://spec.openapis.org/oas/v3.2#tag-object", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + }, + "parent": { + "type": "string" + }, + "kind": { + "type": "string" + } + }, + "required": [ + "name" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "reference": { + "$comment": "https://spec.openapis.org/oas/v3.2#reference-object", + "type": "object", + "properties": { + "$ref": { + "type": "string", + "format": "uri-reference" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + } + } + }, + "schema": { + "$comment": "https://spec.openapis.org/oas/v3.2#schema-object", + "$dynamicAnchor": "meta", + "type": [ + "object", + "boolean" + ] + }, + "security-scheme": { + "$comment": "https://spec.openapis.org/oas/v3.2#security-scheme-object", + "type": "object", + "properties": { + "type": { + "enum": [ + "apiKey", + "http", + "mutualTLS", + "oauth2", + "openIdConnect" + ] + }, + "description": { + "type": "string" + }, + "deprecated": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-apikey" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http-bearer" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oauth2" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oidc" + } + ], + "unevaluatedProperties": false, + "$defs": { + "type-apikey": { + "if": { + "properties": { + "type": { + "const": "apiKey" + } + } + }, + "then": { + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "cookie" + ] + } + }, + "required": [ + "name", + "in" + ] + } + }, + "type-http": { + "if": { + "properties": { + "type": { + "const": "http" + } + } + }, + "then": { + "properties": { + "scheme": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-http-bearer": { + "if": { + "properties": { + "type": { + "const": "http" + }, + "scheme": { + "type": "string", + "pattern": "^[Bb][Ee][Aa][Rr][Ee][Rr]$" + } + }, + "required": [ + "type", + "scheme" + ] + }, + "then": { + "properties": { + "bearerFormat": { + "type": "string" + } + } + } + }, + "type-oauth2": { + "if": { + "properties": { + "type": { + "const": "oauth2" + } + } + }, + "then": { + "properties": { + "flows": { + "$ref": "#/$defs/oauth-flows" + }, + "oauth2MetadataUrl": { + "type": "string", + "format": "uri-reference" + } + }, + "required": [ + "flows" + ] + } + }, + "type-oidc": { + "if": { + "properties": { + "type": { + "const": "openIdConnect" + } + } + }, + "then": { + "properties": { + "openIdConnectUrl": { + "type": "string", + "format": "uri-reference" + } + }, + "required": [ + "openIdConnectUrl" + ] + } + } + } + }, + "security-scheme-or-reference": { + "if": { + "type": "object", + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/security-scheme" + } + }, + "oauth-flows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/$defs/oauth-flows/$defs/implicit" + }, + "password": { + "$ref": "#/$defs/oauth-flows/$defs/password" + }, + "clientCredentials": { + "$ref": "#/$defs/oauth-flows/$defs/client-credentials" + }, + "authorizationCode": { + "$ref": "#/$defs/oauth-flows/$defs/authorization-code" + }, + "deviceAuthorization": { + "$ref": "#/$defs/oauth-flows/$defs/device-authorization" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "implicit": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "password": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "client-credentials": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "authorization-code": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "device-authorization": { + "type": "object", + "properties": { + "deviceAuthorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "deviceAuthorizationUrl", + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + } + } + }, + "security-requirement": { + "$comment": "https://spec.openapis.org/oas/v3.2#security-requirement-object", + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "specification-extensions": { + "$comment": "https://spec.openapis.org/oas/v3.2#specification-extensions", + "patternProperties": { + "^x-": true + } + }, + "examples": { + "properties": { + "example": true, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + } + }, + "not": { + "required": [ + "example", + "examples" + ] + } + }, + "map-of-strings": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "styles-for-form": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } +} diff --git a/hack/api-docs/validation/dialects/oas-vocabulary.json b/hack/api-docs/validation/dialects/oas-vocabulary.json new file mode 100644 index 000000000000..a7a59f1c7d13 --- /dev/null +++ b/hack/api-docs/validation/dialects/oas-vocabulary.json @@ -0,0 +1,87 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/meta/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + + "title": "OAS Base vocabulary", + "description": "A JSON Schema Vocabulary used in the OpenAPI Schema Dialect", + + "$vocabulary": { + "https://spec.openapis.org/oas/3.1/vocab/base": true + }, + + "$dynamicAnchor": "meta", + + "type": ["object", "boolean"], + "properties": { + "example": true, + "discriminator": { "$ref": "#/$defs/discriminator" }, + "externalDocs": { "$ref": "#/$defs/external-docs" }, + "xml": { "$ref": "#/$defs/xml" } + }, + + "$defs": { + "extensible": { + "patternProperties": { + "^x-": true + } + }, + + "discriminator": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": ["propertyName"], + "unevaluatedProperties": false + }, + + "external-docs": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "required": ["url"], + "unevaluatedProperties": false + }, + + "xml": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean" + }, + "wrapped": { + "type": "boolean" + } + }, + "unevaluatedProperties": false + } + } +} diff --git a/hack/api-docs/validation/rules.yaml b/hack/api-docs/validation/rules.yaml new file mode 100644 index 000000000000..e3fdaa5d5a43 --- /dev/null +++ b/hack/api-docs/validation/rules.yaml @@ -0,0 +1,24 @@ +# Structural and dialect validation run against locked OAI schemas in the Go command. +# Vacuum supplies independently named Docker policy rules with source locations. +rules: + docker-operation-id: + description: Every operation needs a stable operation ID. + severity: error + given: $.paths[*][get,put,post,delete,options,head,patch,trace,query] + then: + field: operationId + function: truthy + docker-info-description: + description: Every API needs an overview. + severity: error + given: $.info + then: + field: description + function: truthy + docker-info-version: + description: Every API needs a version identity. + severity: error + given: $.info + then: + field: version + function: truthy diff --git a/hack/api-docs/verify-output.mjs b/hack/api-docs/verify-output.mjs new file mode 100644 index 000000000000..ee6f3ccddd75 --- /dev/null +++ b/hack/api-docs/verify-output.mjs @@ -0,0 +1,171 @@ +import fs from "node:fs"; +import path from "node:path"; +import { isDeepStrictEqual } from "node:util"; +const root = path.resolve(import.meta.dirname, "../.."); +const base = path.resolve(process.argv[2] || "public"); +const data = JSON.parse( + fs.readFileSync(path.join(root, "data/api-reference.json")), +); +const decode = (s) => + s + .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))) + .replaceAll("&", "&") + .replaceAll(""", '"') + .replaceAll("'", "'") + .replaceAll("<", "<") + .replaceAll(">", ">"); +// Hugo's production minifier removes optional attribute quotes. +function attributes(html, name) { + const pattern = new RegExp( + `\\s${name}=(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, + "g", + ); + return [...html.matchAll(pattern)].map((m) => decode(m[1] ?? m[2] ?? m[3])); +} +let count = 0; +const problems = []; +function check(url) { + const htmlPath = path.join(base, url, "index.html"); + const mdPath = path.join(base, url.replace(/\/$/, "")) + ".md"; + if (!fs.existsSync(htmlPath) || !fs.existsSync(mdPath)) { + problems.push(`Missing HTML/Markdown: ${url}`); + return ["", ""]; + } + const html = fs.readFileSync(htmlPath, "utf8"), + md = fs.readFileSync(mdPath, "utf8"); + count++; + return [decode(html), md]; +} +check("/reference/api/"); +for (const api of data.apis) { + check(api.url); + const publishedSource = fs.readFileSync(path.join(base, api.sourceURL)); + if (!publishedSource.equals(fs.readFileSync(path.join(root, api.source)))) + problems.push(`Published specification differs from source: ${api.id}`); + + for (const op of api.operations) { + const [html, md] = check(op.url); + for (const variant of op.variants) { + if ( + !attributes(html, "data-api-variant").includes(variant.pointer) || + !md.includes(`### ${variant.direction} ${variant.status}`) + ) + problems.push(`Missing variant: ${op.url} ${variant.pointer}`); + for (const example of variant.examples) { + if ( + !html.includes(example.text.trim()) || + !md.includes("```" + example.language + "\n" + example.text) + ) + problems.push(`Example mismatch: ${op.url} ${variant.pointer}`); + } + } + for (const p of op.parameters) + if ( + !attributes(html, "data-api-parameter").includes(p.name) || + !md.includes(`### ${p.name}`) + ) + problems.push(`Missing parameter: ${op.url} ${p.name}`); + if (!html.includes(op.path) || !md.includes(op.method + " " + op.path)) + problems.push(`Missing operation signature: ${op.url}`); + if (!md.includes(op.curl)) + problems.push(`Request example mismatch: ${op.url}`); + } + for (const schema of api.schemas) { + const [html, md] = check(schema.url); + if ( + ![...md.matchAll(/```json\n([\s\S]*?)\n```/g)].some((m) => { + try { + return isDeepStrictEqual(JSON.parse(m[1]), schema.schema); + } catch { + return false; + } + }) + ) + problems.push(`Incomplete Markdown schema: ${schema.url}`); + if (!html.includes(schema.name)) + problems.push(`Missing schema heading: ${schema.url}`); + } +} +// Check local links and fragments in generated API pages, including specification prose. +function files(dir) { + return fs + .readdirSync(dir, { withFileTypes: true }) + .flatMap((e) => + e.isDirectory() + ? files(path.join(dir, e.name)) + : [path.join(dir, e.name)], + ); +} +for (const file of [...files(path.join(base, "reference/api"))].filter((p) => + p.endsWith(".html"), +)) { + const html = fs.readFileSync(file, "utf8"); + if (!html.includes("data-api-view=")) continue; + const article = html.match( + /<article\b[^>]*class=["']?api-reference[\s\S]*?<\/article>/, + )?.[0]; + if (!article) { + problems.push(`Missing API article: ${path.relative(base, file)}`); + continue; + } + for (const href of attributes(article, "href")) { + let url; + try { + url = new URL(href, "http://localhost:1314/" + path.relative(base, file)); + } catch { + continue; + } + if ( + !["localhost", "docs.docker.com"].includes(url.hostname) || + !["http:", "https:"].includes(url.protocol) + ) + continue; + const target = path.join( + base, + decodeURIComponent(url.pathname), + url.pathname.endsWith("/") ? "index.html" : "", + ); + if (!fs.existsSync(target)) { + problems.push(`Broken API link: ${path.relative(base, file)} -> ${href}`); + } else if (url.hash && target.endsWith(".html")) { + const targetHTML = fs.readFileSync(target, "utf8"); + const anchors = [ + ...attributes(targetHTML, "id"), + ...attributes(targetHTML, "name"), + ]; + if (!anchors.includes(decodeURIComponent(url.hash.slice(1)))) + problems.push( + `Broken API anchor: ${path.relative(base, file)} -> ${href}`, + ); + } + } +} +if (fs.existsSync(path.join(base, "api-prototype"))) + problems.push("Unexpected prototype routes"); +// Historical Engine pages must keep the original renderer at their existing URLs. +for (let minor = 40; minor <= 56; minor++) { + const url = `/reference/api/engine/version/v1.${minor}/`; + const html = fs.readFileSync(path.join(base, url, "index.html"), "utf8"); + if (!html.includes("<redoc") || html.includes("data-api-view=")) + problems.push(`Legacy Engine renderer changed: ${url}`); +} +if (problems.length) + throw Error( + problems.slice(0, 25).join("\n") + `\n${problems.length} output failures`, + ); +const bytes = files(path.join(base, "reference/api")).reduce( + (n, p) => n + fs.statSync(p).size, + 0, +); +fs.mkdirSync(path.join(root, "tmp/api-reference/reports"), { recursive: true }); +fs.writeFileSync( + path.join(root, "tmp/api-reference/reports/output.json"), + JSON.stringify( + { htmlMarkdownPagePairs: count, referenceBytes: bytes, result: "pass" }, + null, + 2, + ) + "\n", +); +console.log( + `Verified ${count} HTML/Markdown page pairs and API reference links.`, +); diff --git a/hack/flatten-and-resolve.js b/hack/flatten-and-resolve.js index 04532d343eb5..b79ca5e21208 100755 --- a/hack/flatten-and-resolve.js +++ b/hack/flatten-and-resolve.js @@ -1,236 +1,99 @@ #!/usr/bin/env node /** - * Flattens markdown directory structure and resolves all links to absolute paths. - * - * This script: - * 1. Moves index.md files up one level (ai/model-runner/index.md -> ai/model-runner.md) - * 2. Fixes _index.md and index.md references in links - * 3. Strips /manuals/ prefix from paths (Hugo config removes this) - * 4. Resolves all relative links to absolute HTML paths for RAG ingestion - * - * Usage: node flatten-and-resolve.js [public-dir] + * Resolve Markdown links relative to each original file, then flatten index.md. + * Only link destinations change; examples and other text stay byte-identical. + * Usage: node hack/flatten-and-resolve.js [public-dir] */ - -const fs = require('fs'); -const path = require('path'); - -const PUBLIC_DIR = path.resolve(process.argv[2] || 'public'); - -if (!fs.existsSync(PUBLIC_DIR)) { - console.error(`Error: Directory ${PUBLIC_DIR} does not exist`); - process.exit(1); +const fs = require("node:fs"); +const path = require("node:path"); + +const publicDir = path.resolve(process.argv[2] || "public"); + +function markdownFiles(dir) { + return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const file = path.join(dir, entry.name); + return entry.isDirectory() + ? markdownFiles(file) + : file.endsWith(".md") + ? [file] + : []; + }); } -/** - * Recursively find all files matching a predicate - */ -function findFiles(dir, predicate) { - const results = []; - const entries = fs.readdirSync(dir, { withFileTypes: true }); - - for (const entry of entries) { - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - results.push(...findFiles(fullPath, predicate)); - } else if (entry.isFile() && predicate(entry.name)) { - results.push(fullPath); - } - } - - return results; +function resolveLink(link, file) { + // External URLs, protocol-relative URLs, and same-page anchors are complete. + if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(link)) return link; + const [, pathname, suffix] = link.match(/^([^?#]*)(.*)$/s); + if (!pathname) return link; + let url = pathname.startsWith("/") + ? pathname + : "/" + + path + .relative(publicDir, path.resolve(path.dirname(file), pathname)) + .split(path.sep) + .join("/"); + url = url.replace(/^\/manuals\//, "/"); + url = url.replace(/\/_?index\.md$/, "/").replace(/\.md$/, "/"); + return url + suffix; } -/** - * Step 1: Flatten index.md files - * Move path/to/section/index.md -> path/to/section.md - * Before moving, rewrite sibling links (e.g., "get-started.md" -> "section/get-started.md") - */ -function flattenIndexFiles() { - const indexFiles = findFiles(PUBLIC_DIR, name => name === 'index.md'); - let count = 0; - - for (const file of indexFiles) { - // Skip root index.md - if (file === path.join(PUBLIC_DIR, 'index.md')) { - continue; - } - - const dir = path.dirname(file); - const dirname = path.basename(dir); - - // Read content and fix sibling links - let content = fs.readFileSync(file, 'utf8'); - - // Rewrite relative links that don't start with /, ../, or http - // These are sibling files that will become children after flattening - content = content.replace( - /\[([^\]]+)\]\(([a-zA-Z0-9][^):]*)\)/g, - (match, text, link) => { - // Skip if it's a URL or starts with special chars - if (link.startsWith('http://') || link.startsWith('https://') || - link.startsWith('#')) { - return match; - } - return `[${text}](${dirname}/${link})`; - } - ); - - // Also fix reference-style links - content = content.replace( - /^\[([^\]]+)\]:\s+([a-zA-Z0-9][^: ]*\.md)$/gm, - (match, ref, link) => `[${ref}]: ${dirname}/${link}` - ); - - fs.writeFileSync(file, content, 'utf8'); - - // Move file up one level - const parentDir = path.dirname(dir); - const newPath = path.join(parentDir, `${dirname}.md`); - fs.renameSync(file, newPath); - - count++; +// Micromark provides exact destination spans, excluding labels, titles, and code. +// Apply edits backwards so offsets stay valid and formatting stays untouched. +function rewriteLinks(content, events, file) { + const destinations = events + .filter( + ([event, token]) => + event === "enter" && + ["resourceDestinationString", "definitionDestinationString"].includes( + token.type, + ), + ) + .map(([, token]) => token) + .sort((a, b) => b.start.offset - a.start.offset); + for (const token of destinations) { + const start = token.start.offset; + const end = token.end.offset; + const destination = content.slice(start, end); + content = + content.slice(0, start) + + resolveLink(destination, file) + + content.slice(end); } - - console.log(`Flattened ${count} index.md files`); - return count; + return content; } -/** - * Step 2: Fix _index.md and index.md references in all files - * Also strip /manuals/ prefix from paths - */ -function fixIndexReferences() { - const mdFiles = findFiles(PUBLIC_DIR, name => name.endsWith('.md')); - let count = 0; - - for (const file of mdFiles) { - const dir = path.dirname(file); - const dirname = path.basename(dir); - const parentDir = path.dirname(dir); - const parentDirname = path.basename(parentDir); - - let content = fs.readFileSync(file, 'utf8'); - const original = content; - - // Fix path/_index.md or path/index.md -> path.md - content = content.replace(/([a-zA-Z0-9_/-]+)\/_?index\.md/g, '$1.md'); - - // Fix bare _index.md or index.md -> ../dirname.md - content = content.replace(/_?index\.md/g, `../${dirname}.md`); - - // Fix ../_index.md that became ...md -> ../../parentdirname.md - if (parentDir !== PUBLIC_DIR) { - content = content.replace(/\.\.\.md/g, `../../${parentDirname}.md`); - } - - // Strip /manuals/ prefix (both /manuals/ and manuals/) - content = content.replace(/\/?manuals\//g, '/'); - +async function main() { + const { parse, preprocess, postprocess } = await import("micromark"); + const files = markdownFiles(publicDir); + let rewritten = 0; + let flattened = 0; + for (const file of files) { + const original = fs.readFileSync(file, "utf8"); + const events = postprocess( + parse() + .document() + .write(preprocess()(original, "utf8", true)), + ); + const content = rewriteLinks(original, events, file); if (content !== original) { - fs.writeFileSync(file, content, 'utf8'); - count++; + fs.writeFileSync(file, content); + rewritten++; } - } - - console.log(`Fixed _index.md references in ${count} files`); - return count; -} - -/** - * Step 3: Resolve all relative links to absolute HTML paths - */ -function resolveLinks() { - const mdFiles = findFiles(PUBLIC_DIR, name => name.endsWith('.md')); - let count = 0; - - for (const file of mdFiles) { - let content = fs.readFileSync(file, 'utf8'); - const original = content; - - // Process inline links: [text](path) - content = content.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, text, link) => { - const resolved = resolveLinkPath(link, file); - return `[${text}](${resolved})`; - }); - - // Process reference-style links: [ref]: path - content = content.replace(/^\[([^\]]+)\]:\s+(.+)$/gm, (match, ref, link) => { - const resolved = resolveLinkPath(link, file); - return `[${ref}]: ${resolved}`; - }); - - if (content !== original) { - fs.writeFileSync(file, content, 'utf8'); - count++; + if ( + path.basename(file) === "index.md" && + file !== path.join(publicDir, "index.md") + ) { + fs.renameSync(file, path.dirname(file) + ".md"); + flattened++; } } - - console.log(`Resolved links in ${count} files`); - return count; -} - -/** - * Resolve a link path to absolute HTML format - */ -function resolveLinkPath(linkPath, currentFile) { - // Skip external URLs and mailto - if (linkPath.startsWith('http://') || linkPath.startsWith('https://') || - linkPath.startsWith('mailto:')) { - return linkPath; - } - - // Skip same-page anchors - if (linkPath.startsWith('#')) { - return linkPath; - } - - // Split path and anchor - const hashIndex = linkPath.indexOf('#'); - const pathPart = hashIndex >= 0 ? linkPath.substring(0, hashIndex) : linkPath; - const anchorPart = hashIndex >= 0 ? linkPath.substring(hashIndex) : ''; - - if (!pathPart) { - // Just an anchor - return linkPath; - } - - // Handle absolute paths - just convert to HTML format - if (pathPart.startsWith('/')) { - return toHtmlPath(pathPart) + anchorPart; - } - - // Resolve relative path to absolute - const currentDir = path.dirname(currentFile); - const absolutePath = path.resolve(currentDir, pathPart); - const relativePath = path.relative(PUBLIC_DIR, absolutePath); - - // Convert to URL path (forward slashes) - const urlPath = '/' + relativePath.split(path.sep).join('/'); - - return toHtmlPath(urlPath) + anchorPart; -} - -/** - * Convert a path to HTML format (strip .md, add trailing /) - */ -function toHtmlPath(urlPath) { - if (urlPath.endsWith('.md')) { - return urlPath.slice(0, -3) + '/'; - } - return urlPath; + console.log( + `Markdown: rewrote links in ${rewritten} files; flattened ${flattened} index.md files`, + ); } -// Main execution -console.log('Starting markdown flattening and link resolution...'); -console.log(''); - -const flattenCount = flattenIndexFiles(); -const fixCount = fixIndexReferences(); -const resolveCount = resolveLinks(); - -console.log(''); -console.log('Done!'); -console.log(`- Flattened: ${flattenCount} files`); -console.log(`- Fixed references: ${fixCount} files`); -console.log(`- Resolved links: ${resolveCount} files`); +main().catch((error) => { + console.error(error); + process.exitCode = 1; +}); diff --git a/hack/moby-sync-release.sh b/hack/moby-sync-release.sh index dc1192c4872d..edce7938574e 100755 --- a/hack/moby-sync-release.sh +++ b/hack/moby-sync-release.sh @@ -18,9 +18,12 @@ docs_notes=$(mktemp -t new) github_notes=$(mktemp -t old) # Get the release notes from the docs. -grep -A 10000 "## ${version}" "content/manuals/engine/release-notes/${major_version}.md" | \ - grep -m 2 -A 0 -B 10000 '^## ' | \ - sed '$d' | \ +awk -v heading="## ${version}" ' + $0 == heading { found = 1; print; next } + found && /^## / { exit } + found { print } + END { if (!found) exit 1 } +' "content/manuals/engine/release-notes/${major_version}.md" | \ sed '/{{< release-date /{N;d;}' \ > "$docs_notes" || { echo "Release notes for ${version} not found" && exit 1; } diff --git a/hack/releaser/Dockerfile b/hack/releaser/Dockerfile index c2983b304c56..fa4c6f6dc46e 100644 --- a/hack/releaser/Dockerfile +++ b/hack/releaser/Dockerfile @@ -15,6 +15,12 @@ RUN --mount=type=bind,target=. \ --mount=type=cache,target=/root/.cache/go-build \ go build -o /out/releaser . +# releaser-test runs the unit tests for the CloudFront redirect Lambda function. +FROM base AS releaser-test +RUN apk add --no-cache nodejs +RUN --mount=type=bind,target=. \ + node --test cloudfront-lambda-redirects.test.js + FROM base AS aws-lambda-invoke ARG DRY_RUN=false ARG AWS_REGION diff --git a/hack/releaser/cloudfront-lambda-redirects.js b/hack/releaser/cloudfront-lambda-redirects.js index 6fbc40e5b182..7d3d4cfe1992 100644 --- a/hack/releaser/cloudfront-lambda-redirects.js +++ b/hack/releaser/cloudfront-lambda-redirects.js @@ -1,91 +1,118 @@ -'use strict'; +"use strict"; exports.handler = (event, context, callback) => { - //console.log("event", JSON.stringify(event)); - const request = event.Records[0].cf.request; - const requestUrl = request.uri.replace(/\/$/, "") + //console.log("event", JSON.stringify(event)); + const request = event.Records[0].cf.request; + const requestUrl = request.uri.replace(/\/$/, ""); - const redirects = JSON.parse(`{{.RedirectsJSON}}`); - for (let key in redirects) { - const redirectTarget = key.replace(/\/$/, "") - if (redirectTarget !== requestUrl) { - continue; - } - //console.log(`redirect: ${requestUrl} to ${redirects[key]}`); - const response = { - status: '301', - statusDescription: 'Moved Permanently', - headers: { - location: [{ - key: 'Location', - value: redirects[key], - }], - }, - } - callback(null, response); - return + // Preserve the query string (e.g. UTM tags) when issuing a redirect. + const withQuery = (location) => { + if (!request.querystring) { + return location; } + const isRelative = location.startsWith("/") && !location.startsWith("//"); + const url = new URL(location, "https://docs.docker.com"); + const query = new URLSearchParams(request.querystring); + for (const [key, value] of query) { + url.searchParams.append(key, value); + } + return isRelative ? url.pathname + url.search + url.hash : url.href; + }; + + const redirects = JSON.parse(`{{.RedirectsJSON}}`); + for (let key in redirects) { + const redirectTarget = key.replace(/\/$/, ""); + const exactMatch = key === request.uri; + // Preserve slash-insensitive matching without redirecting a canonical + // slash-terminated destination back to itself. + const normalizedMatch = + redirectTarget === requestUrl && redirects[key] !== request.uri; + if (!exactMatch && !normalizedMatch) { + continue; + } + //console.log(`redirect: ${requestUrl} to ${redirects[key]}`); + const response = { + status: "301", + statusDescription: "Moved Permanently", + headers: { + location: [ + { + key: "Location", + value: withQuery(redirects[key]), + }, + ], + }, + }; + callback(null, response); + return; + } - const redirectsPrefixes = JSON.parse(`{{.RedirectsPrefixesJSON}}`); - for (let x in redirectsPrefixes) { - const rp = redirectsPrefixes[x]; - if (!request.uri.startsWith(`/${rp['prefix']}`)) { - continue; - } - let newlocation = "/"; - if (rp['strip']) { - let re = new RegExp(`(^/${rp['prefix']})`, 'gi'); - newlocation = request.uri.replace(re,'/'); - } - //console.log(`redirect: ${request.uri} to ${redirectsPrefixes[key]}`); - const response = { - status: '301', - statusDescription: 'Moved Permanently', - headers: { - location: [{ - key: 'Location', - value: newlocation, - }], - }, - } - callback(null, response); - return + const redirectsPrefixes = JSON.parse(`{{.RedirectsPrefixesJSON}}`); + for (let x in redirectsPrefixes) { + const rp = redirectsPrefixes[x]; + if (!request.uri.startsWith(`/${rp["prefix"]}`)) { + continue; + } + let newlocation = "/"; + if (rp["strip"]) { + let re = new RegExp(`(^/${rp["prefix"]})`, "gi"); + newlocation = request.uri.replace(re, "/"); } + //console.log(`redirect: ${request.uri} to ${redirectsPrefixes[key]}`); + const response = { + status: "301", + statusDescription: "Moved Permanently", + headers: { + location: [ + { + key: "Location", + value: withQuery(newlocation), + }, + ], + }, + }; + callback(null, response); + return; + } - // Check Accept header for markdown/text requests - const headers = request.headers; - const acceptHeader = headers.accept ? headers.accept[0].value : ''; - const wantsMarkdown = acceptHeader.includes('text/markdown') || - acceptHeader.includes('text/plain'); + // Check Accept header for markdown/text requests + const headers = request.headers; + const acceptHeader = headers.accept ? headers.accept[0].value : ""; + const wantsMarkdown = + acceptHeader.includes("text/markdown") || + acceptHeader.includes("text/plain"); - // Handle directory requests by appending index.html or index.md for requests without file extensions - let uri = request.uri; + // Handle directory requests by appending index.html or index.md for requests without file extensions + let uri = request.uri; - // Check if the URI has a dot after the last slash (indicating a filename) - // This is more accurate than just checking the end of the URI - const hasFileExtension = /\.[^/]*$/.test(uri.split('/').pop()); + // Check if the URI has a dot after the last slash (indicating a filename) + // This is more accurate than just checking the end of the URI + const hasFileExtension = /\.[^/]*$/.test(uri.split("/").pop()); - // If it's not a file, treat it as a directory - if (!hasFileExtension) { - if (wantsMarkdown) { - // Markdown files are flattened: /path/to/page.md not /path/to/page/index.md. - // The homepage markdown output remains at /index.md. - const stripped = uri.replace(/\/$/, ''); - uri = stripped === '' ? '/index.md' : stripped + '.md'; - } else { - // HTML uses directory structure with index.html - if (!uri.endsWith("/")) { - uri += "/"; - } - uri += "index.html"; - } - request.uri = uri; - } else if (wantsMarkdown && uri.endsWith('/index.html')) { - // If requesting index.html but wants markdown, use the flattened .md file. - // The homepage markdown output lives at /index.md. - uri = uri === '/index.html' ? '/index.md' : uri.replace(/\/index\.html$/, '.md'); - request.uri = uri; + // If it's not a file, treat it as a directory + if (!hasFileExtension) { + if (wantsMarkdown) { + // Markdown files are flattened: /path/to/page.md not /path/to/page/index.md. + // The homepage markdown output remains at /index.md. + const stripped = uri.replace(/\/$/, ""); + uri = stripped === "" ? "/index.md" : stripped + ".md"; + } else { + // HTML uses directory structure with index.html + if (!uri.endsWith("/")) { + uri += "/"; + } + uri += "index.html"; } + request.uri = uri; + } else if (wantsMarkdown && uri.endsWith("/index.html")) { + // If requesting index.html but wants markdown, use the flattened .md file. + // The homepage markdown output lives at /index.md. + uri = + uri === "/index.html" + ? "/index.md" + : uri.replace(/\/index\.html$/, ".md"); + request.uri = uri; + } - callback(null, request); + callback(null, request); }; diff --git a/hack/releaser/cloudfront-lambda-redirects.test.js b/hack/releaser/cloudfront-lambda-redirects.test.js new file mode 100644 index 000000000000..915e33b10d68 --- /dev/null +++ b/hack/releaser/cloudfront-lambda-redirects.test.js @@ -0,0 +1,153 @@ +"use strict"; + +// Tests for cloudfront-lambda-redirects.js. +// +// The function source is a Go text/template (see aws.go) with two +// placeholders that are filled with JSON at build time. These tests render +// the template the same way aws.go does, then load and exercise the handler. +// +// Run with: node --test hack/releaser/cloudfront-lambda-redirects.test.js + +const { test } = require("node:test"); +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const path = require("node:path"); +const Module = require("node:module"); + +const SRC = path.join(__dirname, "cloudfront-lambda-redirects.js"); + +const REDIRECTS = { + "/learn": "/learn/", + "/old/page/": "/new/page/", + "/target-with-query/": "/dest/?ref=docs", + "/target-with-fragment/": "/dest/?ref=docs#install", + "/external-target/": "https://www.docker.com/example?ref=docs#install", +}; + +const REDIRECTS_PREFIXES = [ + { prefix: "keep/", strip: false }, + { prefix: "strip/", strip: true }, +]; + +// Render the template the same way getLambdaFunctionZip in aws.go does, then +// evaluate it as a CommonJS module so we can call handler() directly. +function loadHandler() { + const rendered = fs + .readFileSync(SRC, "utf8") + // Function replacers avoid String.replace's special handling of `$` + // sequences in the replacement, in case a redirect target contains one. + .replace("{{.RedirectsJSON}}", () => JSON.stringify(REDIRECTS)) + .replace("{{.RedirectsPrefixesJSON}}", () => + JSON.stringify(REDIRECTS_PREFIXES), + ); + + const m = new Module(SRC); + m._compile(rendered, SRC); + return m.exports.handler; +} + +const handler = loadHandler(); + +// invoke wraps the callback-style handler in a promise. +function invoke({ uri, querystring = "", accept = "text/html" }) { + const request = { + uri, + querystring, + headers: { accept: [{ key: "Accept", value: accept }] }, + }; + const event = { Records: [{ cf: { request } }] }; + return new Promise((resolve, reject) => { + handler(event, {}, (err, result) => { + if (err) return reject(err); + resolve({ result, request }); + }); + }); +} + +function locationOf(result) { + return result.headers.location[0].value; +} + +test("exact redirect preserves the query string", async () => { + const { result } = await invoke({ + uri: "/old/page/", + querystring: "utm_source=newsletter&utm_campaign=launch", + }); + assert.equal(result.status, "301"); + assert.equal( + locationOf(result), + "/new/page/?utm_source=newsletter&utm_campaign=launch", + ); +}); + +test("exact redirect without a query string is unchanged", async () => { + const { result } = await invoke({ uri: "/old/page/" }); + assert.equal(result.status, "301"); + assert.equal(locationOf(result), "/new/page/"); +}); + +test("bare path redirects without redirecting the canonical target to itself", async () => { + const { result: bareResult } = await invoke({ uri: "/learn" }); + assert.equal(bareResult.status, "301"); + assert.equal(locationOf(bareResult), "/learn/"); + + const { result: canonicalResult, request } = await invoke({ uri: "/learn/" }); + assert.equal(canonicalResult, request); + assert.equal(request.uri, "/learn/index.html"); +}); + +test("exact redirect appends with & when target already has a query string", async () => { + const { result } = await invoke({ + uri: "/target-with-query/", + querystring: "utm_medium=email", + }); + assert.equal(locationOf(result), "/dest/?ref=docs&utm_medium=email"); +}); + +test("exact redirect inserts the query string before a fragment", async () => { + const { result } = await invoke({ + uri: "/target-with-fragment/", + querystring: "utm_medium=email", + }); + assert.equal(locationOf(result), "/dest/?ref=docs&utm_medium=email#install"); +}); + +test("exact redirect preserves an absolute target URL", async () => { + const { result } = await invoke({ + uri: "/external-target/", + querystring: "utm_medium=email", + }); + assert.equal( + locationOf(result), + "https://www.docker.com/example?ref=docs&utm_medium=email#install", + ); +}); + +test("prefix redirect (strip) preserves the query string", async () => { + const { result } = await invoke({ + uri: "/strip/some/path", + querystring: "utm_source=x", + }); + assert.equal(result.status, "301"); + assert.equal(locationOf(result), "/some/path?utm_source=x"); +}); + +test("prefix redirect (no strip) preserves the query string", async () => { + const { result } = await invoke({ + uri: "/keep/anything", + querystring: "utm_source=x", + }); + assert.equal(result.status, "301"); + assert.equal(locationOf(result), "/?utm_source=x"); +}); + +test("directory rewrite passes the request through with query string intact", async () => { + const { result, request } = await invoke({ + uri: "/some/page", + querystring: "utm_source=x", + }); + // No redirect response: the handler forwards the (mutated) request. + assert.equal(result, request); + assert.equal(request.uri, "/some/page/index.html"); + assert.equal(request.querystring, "utm_source=x"); +}); diff --git a/hack/sandboxes/README.md b/hack/sandboxes/README.md new file mode 100644 index 000000000000..f6e0b3d23808 --- /dev/null +++ b/hack/sandboxes/README.md @@ -0,0 +1,48 @@ +# Sandboxes documentation import + +The public cookbook export is published to the `generated` branch of +`docker/sbx-api` after its documentation CI passes. `source.json` pins both +the generated commit and the source commit recorded in that export's `SOURCE` +file. The guide list explicitly selects the recipes to publish. + +`name-a-sandbox-and-find-it-again.md` is temporarily excluded pending a +working example. Restore its manifest entry and import it after verification. + +Run the import from the repository root with Python 3 and `gh` authenticated for +`docker/sbx-api`: + +```console +$ python3 hack/sync-sandboxes-docs.py +``` + +The import writes: + +- Cookbook recipes to `content/manuals/ai/sandboxes-api/cookbook/` +- The public OpenAPI specification to + `content/reference/api/sandboxes/api.yaml` + +Treat these files as generated. Make prose, example, and API corrections in +`docker/sbx-api`, then import the updated export. The cookbook's `_index.md` +is maintained in docker/docs, along with the overview, installation, +authentication, concepts, errors, and limits pages. + +The import copies the selected recipes and OpenAPI specification byte for byte. +It excludes the upstream overview, installation page, and generated Markdown +API reference. Recipe installation links point to the canonical Docker Docs +installation page. + +The specification is registered in `hack/api-docs/sources.json`. The shared API +renderer generates an overview and separate operation and schema pages under +`/reference/api/sandboxes/latest/`, in HTML and Markdown. Run +`./hack/api-docs/run.sh generate` after importing a specification and commit +`data/api-reference.json` with the source changes. Strict validation checks the +specification and its examples. Fix failures upstream and re-import the export. + +To update, change both commit IDs in `source.json`, review additions or removals +in the upstream guide list, and run the import. Removed guides require explicit +deletion and a link check. Review the diff and build the site before committing. +The import does not select the latest release or push changes. + +Release automation can update this manifest and run the same command in a pull +request once upstream publishes a release-to-export mapping. Keep the source +and generated commits paired rather than importing a moving branch. diff --git a/hack/sandboxes/source.json b/hack/sandboxes/source.json new file mode 100644 index 000000000000..b532cbb645ba --- /dev/null +++ b/hack/sandboxes/source.json @@ -0,0 +1,43 @@ +{ + "repository": "docker/sbx-api", + "generatedCommit": "74627446ce26418b25c996e55e1c7cfe49216b8f", + "sourceCommit": "de20ec671b32ac17b79eb0b690f13d17d55a98bf", + "guides": [ + "add-a-docker-credential-for-cloud-sandboxes.md", + "add-tools-with-kits.md", + "attach-persistent-storage.md", + "clone-a-cloud-sandbox.md", + "connect-to-cloud-with-a-bearer-token.md", + "control-what-a-sandbox-can-reach.md", + "copy-a-file-into-a-cloud-sandbox.md", + "create-your-first-sandbox.md", + "delete-a-cloud-sandbox.md", + "expose-a-port-from-a-cloud-sandbox.md", + "find-a-process-you-lost-track-of.md", + "get-a-stored-secret-into-a-sandbox.md", + "get-an-ssh-certificate.md", + "get-image-pull-urls.md", + "give-a-sandbox-an-mcp-gateway.md", + "handle-errors-and-degradation.md", + "keep-a-cloud-sandbox-running.md", + "let-a-stopped-sandbox-resume-on-demand.md", + "manage-cloud-secrets.md", + "manage-network-policies.md", + "page-through-and-filter-lists.md", + "read-files-out-of-a-sandbox.md", + "recover-when-the-endpoint-moves.md", + "register-and-manage-an-image.md", + "retry-without-creating-duplicates.md", + "run-a-complete-example.md", + "run-an-interactive-shell-in-a-cloud-sandbox.md", + "run-something-that-produces-real-output.md", + "run-work-across-many-sandboxes.md", + "run-your-first-command.md", + "run-your-own-container-image.md", + "send-values-the-api-accepts.md", + "snapshot-and-fork-a-sandbox.md", + "stop-and-restart-a-sandbox.md", + "what-your-workload-starts-with.md", + "work-within-the-limits.md" + ] +} diff --git a/hack/sbx-release-notes.py b/hack/sbx-release-notes.py index 07c61e415c93..90f47218c3fa 100755 --- a/hack/sbx-release-notes.py +++ b/hack/sbx-release-notes.py @@ -4,12 +4,13 @@ # dependencies = ["jinja2"] # /// """ -Fetch recent stable releases from docker/sbx-releases and splice them into -content/manuals/ai/sandboxes/release-notes.md between the BEGIN/END markers. +Fetch recent stable releases from a GitHub releases page and splice them into +a docs markdown file between the BEGIN/END markers. Usage (from repo root): ./hack/sbx-release-notes.py + ./hack/sbx-release-notes.py --preset dhi GITHUB_TOKEN=$(gh auth token) ./hack/sbx-release-notes.py ./hack/sbx-release-notes.py --minor-releases 3 """ @@ -29,8 +30,18 @@ from jinja2 import Template -DEFAULT_REPO = "docker/sbx-releases" -DEFAULT_FILE = Path("content/manuals/ai/sandboxes/release-notes.md") +PRESETS: dict[str, dict] = { + "sbx": { + "repo": "docker/sbx-releases", + "file": Path("content/manuals/ai/sandboxes/release-notes.md"), + }, + "dhi": { + "repo": "docker-hardened-images/dhictl", + "file": Path("content/manuals/dhi/release-notes/cli.md"), + }, +} + +DEFAULT_PRESET = "sbx" DEFAULT_MINOR_RELEASES = 3 BEGIN = "<!-- BEGIN GENERATED RELEASES -->" @@ -89,7 +100,7 @@ def parse_stable(raw: list[dict]) -> list[dict]: "version": f"{major}.{minor}.{patch}", "date": r["published_at"][:10], "url": r["html_url"], - "body": shift_headings(body), + "body": normalize_body(shift_headings(body)), } ) out.sort(key=lambda r: (r["major"], r["minor"], r["patch"]), reverse=True) @@ -123,6 +134,41 @@ def shift_headings(body: str) -> str: return "\n".join(lines) +def normalize_body(body: str) -> str: + """Fix Markdown lint issues in release body content: + - Ensure a blank line follows each heading (MD022). + - Add 'console' language tag to fenced code blocks that have none (MD040). + Safe to run on content that already complies — no double blank lines are added.""" + lines = body.splitlines() + result: list[str] = [] + in_fence = False + + for i, line in enumerate(lines): + stripped = line.lstrip(" \t") + + if stripped.startswith(("```", "~~~")): + if not in_fence: + # Opening fence: add language tag if missing + fence_marker = "```" if stripped.startswith("```") else "~~~" + lang = stripped[len(fence_marker):].strip() + if not lang: + indent = line[: len(line) - len(stripped)] + line = f"{indent}{fence_marker}console" + in_fence = not in_fence + result.append(line) + continue + + result.append(line) + + # Outside fences: insert blank line after a heading if the next line is non-empty + if not in_fence and stripped.startswith("#"): + next_line = lines[i + 1] if i + 1 < len(lines) else "" + if next_line.strip(): + result.append("") + + return "\n".join(result) + + def splice(path: Path, generated: str) -> None: src = path.read_text() try: @@ -135,20 +181,30 @@ def splice(path: Path, generated: str) -> None: def main() -> None: p = argparse.ArgumentParser(description=__doc__) - p.add_argument("--repo", default=DEFAULT_REPO) - p.add_argument("--file", type=Path, default=DEFAULT_FILE) + p.add_argument( + "--preset", + choices=list(PRESETS), + default=DEFAULT_PRESET, + help="Named preset that sets --repo and --file defaults (default: %(default)s)", + ) + p.add_argument("--repo", default=None, help="GitHub repo (owner/name), overrides preset") + p.add_argument("--file", type=Path, default=None, help="Target markdown file, overrides preset") p.add_argument("--minor-releases", type=int, default=DEFAULT_MINOR_RELEASES) args = p.parse_args() - releases = pick_minor_releases(parse_stable(fetch(args.repo)), args.minor_releases) + preset = PRESETS[args.preset] + repo = args.repo or preset["repo"] + file = args.file or preset["file"] + + releases = pick_minor_releases(parse_stable(fetch(repo)), args.minor_releases) if not releases: sys.exit("no stable releases found") generated = TEMPLATE.render(releases=releases) - splice(args.file, generated) + splice(file, generated) if shutil.which("npx"): - subprocess.run(["npx", "--no-install", "prettier", "--write", str(args.file)], check=False) - print(f"Wrote {len(releases)} releases (latest {args.minor_releases} minor releases) to {args.file}") + subprocess.run(["npx", "--no-install", "rumdl", "fmt", str(file)], check=False) + print(f"Wrote {len(releases)} releases (latest {args.minor_releases} minor releases) to {file}") if __name__ == "__main__": diff --git a/hack/sync-governance-api.sh b/hack/sync-governance-api.sh new file mode 100755 index 000000000000..601696737ce0 --- /dev/null +++ b/hack/sync-governance-api.sh @@ -0,0 +1,55 @@ +#!/bin/bash +# Re-vendor the AI Governance OpenAPI spec from docker/governor-services. +# +# The spec at content/reference/api/ai-governance/api.yaml is a verbatim copy +# of the upstream openapi.yaml — no transformation is applied. This script +# fetches the latest version and overwrites the local copy, then prints a diff +# summary so you can sanity-check before committing. +# +# Requires: gh (authenticated with access to the private docker/governor-services +# repo). No secrets are stored in this repo — auth comes from your own gh login. +# +# Usage: hack/sync-governance-api.sh [ref] +# ref optional git ref (branch, tag, or SHA). Defaults to the repo default branch. +set -euo pipefail + +REPO="docker/governor-services" +SRC_PATH="governor-service-api/openapi.yaml" +DEST="content/reference/api/ai-governance/api.yaml" +REF="${1:-}" + +# Resolve this repo's root so the script works from any working directory. +ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)" +DEST_ABS="$ROOT/$DEST" + +if ! command -v gh >/dev/null 2>&1; then + echo "error: gh CLI not found. Install it and run 'gh auth login'." >&2 + exit 1 +fi + +api_path="repos/$REPO/contents/$SRC_PATH" +[ -n "$REF" ] && api_path="$api_path?ref=$REF" + +echo "Fetching $SRC_PATH from $REPO${REF:+@$REF}..." +tmp="$(mktemp)" +trap 'rm -f "$tmp"' EXIT + +if ! gh api "$api_path" --jq '.content' | base64 -d > "$tmp"; then + echo "error: failed to fetch spec. Check 'gh auth status' and repo access." >&2 + exit 1 +fi + +if [ ! -s "$tmp" ]; then + echo "error: fetched spec is empty — aborting without overwriting $DEST." >&2 + exit 1 +fi + +if diff -q "$DEST_ABS" "$tmp" >/dev/null 2>&1; then + echo "Already up to date — $DEST is identical to upstream." + exit 0 +fi + +cp "$tmp" "$DEST_ABS" +echo "Updated $DEST. Review the change:" +echo +git -C "$ROOT" --no-pager diff --stat -- "$DEST" diff --git a/hack/sync-sandboxes-docs.py b/hack/sync-sandboxes-docs.py new file mode 100644 index 000000000000..02885d2a0dd6 --- /dev/null +++ b/hack/sync-sandboxes-docs.py @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +"""Import the pinned public cookbook export. See hack/sandboxes/README.md.""" + +import io +import json +from pathlib import Path +import subprocess +import tarfile + + +ROOT = Path(__file__).resolve().parent.parent +MANIFEST = ROOT / "hack/sandboxes/source.json" +GUIDES = ROOT / "content/manuals/ai/sandboxes-api/cookbook" +REFERENCE = ROOT / "content/reference/api/sandboxes" + + +def main(): + source = json.loads(MANIFEST.read_text()) + archive = subprocess.check_output([ + "gh", "api", + f"repos/{source['repository']}/tarball/{source['generatedCommit']}", + ]) + with tarfile.open(fileobj=io.BytesIO(archive), mode="r:gz") as tar: + files = {} + for member in tar.getmembers(): + if member.isfile(): + path = member.name.split("/", 1)[1] + files[path] = tar.extractfile(member).read() + + if files["SOURCE"].decode().strip() != source["sourceCommit"]: + raise SystemExit("The generated export does not match the recorded source commit") + + # Prepare every output before changing the working tree. Fail if an upstream + # page disappears instead of silently dropping a published recipe. + outputs = {} + for name in source["guides"]: + if Path(name).name != name or not name.endswith(".md"): + raise SystemExit(f"Invalid guide filename: {name}") + outputs[GUIDES / name] = files[f"cookbook/outputs/guides/{name}"] + + outputs[REFERENCE / "api.yaml"] = files["cookbook/outputs/api-reference/api.yaml"] + + for destination, content in outputs.items(): + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_bytes(content) + print(f"Imported {len(source['guides'])} recipes and the public OpenAPI specification") + + +if __name__ == "__main__": + main() diff --git a/hack/test/flatten-and-resolve.mjs b/hack/test/flatten-and-resolve.mjs new file mode 100644 index 000000000000..697287c35350 --- /dev/null +++ b/hack/test/flatten-and-resolve.mjs @@ -0,0 +1,119 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { execFileSync } from "node:child_process"; + +const script = path.resolve(import.meta.dirname, "../flatten-and-resolve.js"); + +test("flattens all pages while preserving examples and resolving documentation links", () => { + const site = fs.mkdtempSync(path.join(os.tmpdir(), "docs-flatten-")); + const generated = + "# API\n\n" + + "[Guide](/reference/api/registry/auth/)\n\n" + + '```json\n{"path":"/manuals/example/index.md","text":"[sample](file.md)"}\n```\n'; + const write = (name, value) => { + const file = path.join(site, name); + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, value); + }; + try { + write("reference/api/index.md", generated); + write("reference/api/registry/latest/index.md", generated); + write( + "reference/api/registry/auth/index.md", + "# Guide\n\n[Example](example.md)\n", + ); + write("reference/api/registry/auth/example.md", "# Example\n"); + for (let run = 0; run < 2; run++) { + execFileSync(process.execPath, [script, site], { stdio: "pipe" }); + assert.equal( + fs.readFileSync(path.join(site, "reference/api.md"), "utf8"), + generated, + ); + assert.equal( + fs.readFileSync( + path.join(site, "reference/api/registry/latest.md"), + "utf8", + ), + generated, + ); + assert.ok( + !fs.existsSync( + path.join(site, "reference/api/registry/latest/index.md"), + ), + ); + assert.match( + fs.readFileSync( + path.join(site, "reference/api/registry/auth.md"), + "utf8", + ), + /\[Example\]\(\/reference\/api\/registry\/auth\/example\/\)/, + ); + } + } finally { + fs.rmSync(site, { recursive: true, force: true }); + } +}); + +test("rewrites only destinations and preserves Markdown syntax", () => { + const site = fs.mkdtempSync(path.join(os.tmpdir(), "docs-links-")); + const cases = [ + ["[Guide](/manuals/engine/_index.md#install)", "[Guide](/engine/#install)"], + ["[Parent](../index.md)", "[Parent](/guide/)"], + ["[Root](/index.md)", "[Root](/)"], + [ + '[Title](<file.md> "A title")', + '[Title](</guide/section/file/> "A title")', + ], + [ + "[Nested **label**](file(test).md?q=1#part)", + "[Nested **label**](/guide/section/file(test)/?q=1#part)", + ], + ["[`odd ] bracket`](file.md)", "[`odd ] bracket`](/guide/section/file/)"], + [ + "![Image [label]](picture.png)", + "![Image [label]](/guide/section/picture.png)", + ], + [ + '[ref]: /manuals/engine/index.md "Title"\n\n[Reference][ref]', + '[ref]: /engine/ "Title"\n\n[Reference][ref]', + ], + ["> - [Guide](file.md)", "> - [Guide](/guide/section/file/)"], + [ + "[External](https://example.com/manuals/index.md)", + "[External](https://example.com/manuals/index.md)", + ], + [ + "[CDN](//example.com/manuals/index.md)", + "[CDN](//example.com/manuals/index.md)", + ], + ["[Mail](mailto:docs@example.com)", "[Mail](mailto:docs@example.com)"], + ["[Anchor](#example)", "[Anchor](#example)"], + ["`[Example](/manuals/index.md)`", "`[Example](/manuals/index.md)`"], + [" [Example](/manuals/index.md)", " [Example](/manuals/index.md)"], + [ + '~~~json\n{"file":"/manuals/index.md"}\n~~~', + '~~~json\n{"file":"/manuals/index.md"}\n~~~', + ], + [ + "A literal /manuals/example/index.md filename.", + "A literal /manuals/example/index.md filename.", + ], + ]; + try { + fs.mkdirSync(path.join(site, "guide/section"), { recursive: true }); + fs.writeFileSync( + path.join(site, "guide/section/index.md"), + cases.map(([before]) => before).join("\n\n"), + ); + execFileSync(process.execPath, [script, site]); + assert.equal( + fs.readFileSync(path.join(site, "guide/section.md"), "utf8"), + cases.map(([, after]) => after).join("\n\n"), + ); + } finally { + fs.rmSync(site, { recursive: true, force: true }); + } +}); diff --git a/hack/validate-whats-new.mjs b/hack/validate-whats-new.mjs new file mode 100644 index 000000000000..e4e7e0548150 --- /dev/null +++ b/hack/validate-whats-new.mjs @@ -0,0 +1,92 @@ +#!/usr/bin/env node + +import fs from "node:fs"; + +const [path, expectedStart, expectedEnd] = process.argv.slice(2); +if (!expectedEnd) { + throw new Error(`usage: ${process.argv[1]} FILE START END`); +} + +const data = JSON.parse(fs.readFileSync(path, "utf8")); +const requiredItemKeys = [ + "product", + "title", + "description", + "url", + "published", + "source_prs", + "featured", +]; + +if (data.period_start !== expectedStart) { + throw new Error(`period_start must be ${expectedStart}`); +} +if (data.period_end !== expectedEnd) { + throw new Error(`period_end must be ${expectedEnd}`); +} +if (!Array.isArray(data.items)) { + throw new Error("items must be an array"); +} +for (const [index, item] of data.items.entries()) { + const missing = requiredItemKeys.filter((key) => !(key in item)); + if (missing.length > 0) { + throw new Error(`item ${index + 1} is missing: ${missing.join(", ")}`); + } + + for (const key of requiredItemKeys.slice(0, 4)) { + if (typeof item[key] !== "string" || item[key].trim() === "") { + throw new Error(`item ${index + 1} has an empty ${key}`); + } + } + + if (!item.url.startsWith("/") || item.url.startsWith("/manuals/")) { + throw new Error(`item ${index + 1} url must be an internal published URL`); + } + if ( + typeof item.published !== "string" || + !/^\d{4}-\d{2}-\d{2}$/.test(item.published) || + new Date(`${item.published}T00:00:00Z`).toISOString().slice(0, 10) !== + item.published + ) { + throw new Error(`item ${index + 1} has an invalid published date`); + } + if (item.published < data.period_start || item.published > data.period_end) { + throw new Error(`item ${index + 1} published date is outside the period`); + } + if ( + !Array.isArray(item.source_prs) || + item.source_prs.length === 0 || + !item.source_prs.every((number) => Number.isInteger(number) && number > 0) + ) { + throw new Error( + `item ${index + 1} source_prs must contain pull request numbers`, + ); + } + if (typeof item.featured !== "boolean") { + throw new Error(`item ${index + 1} featured must be a boolean`); + } +} + +const featuredCount = data.items.filter((item) => item.featured).length; +const expectedFeaturedCount = Math.min(5, data.items.length); +if (featuredCount !== expectedFeaturedCount) { + throw new Error( + `items must contain ${expectedFeaturedCount} featured highlights`, + ); +} + +const publishedDates = data.items.map((item) => item.published); +const sortedDates = [...publishedDates].sort().reverse(); +if (publishedDates.join() !== sortedDates.join()) { + throw new Error("items must be sorted by published date, newest first"); +} + +const titles = data.items.map((item) => item.title); +if (new Set(titles).size !== titles.length) { + throw new Error("items must not contain duplicate titles"); +} + +const urls = data.items.map((item) => item.url); +if (new Set(urls).size !== urls.length) { + throw new Error("items must not contain duplicate URLs"); +} diff --git a/hugo.yaml b/hugo.yaml index ea53a7e3085b..e0f4acf255cf 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -10,14 +10,19 @@ ignoreLogs: taxonomies: {} +security: + exec: + allow: + - ^(dart-)?sass$ + - ^go$ + - ^git$ + - ^node$ + - ^postcss$ + - ^tailwindcss$ + # Cascade layout and type settings to content subtrees. # See https://gohugo.io/configuration/cascade/#target cascade: - # Guide sections use the series layout (metadata card + modules list) - - target: - path: /guides/** - kind: section - layout: series # Sample pages use the samples type (routes to layouts/samples/) - target: path: /reference/samples/** @@ -37,6 +42,14 @@ cascade: - target: path: /reference/cli/sbx/** layout: sbx-cli + # Docker Agent section indexes are mounted navigation stubs; skip + # rendering them so they don't produce empty pages (same pattern as + # gordon/concepts and other render:never section indexes) + - target: + path: /manuals/ai/docker-agent/** + kind: section + build: + render: never # Remove the /manuals prefix for content in the manuals section permalinks: @@ -141,7 +154,6 @@ params: stage: 3218181 google: GTM-WL2QLG5 onetrust: 65425fb0-7b36-4317-9f10-7b3e08039af0 - vwo: 723167 marlin: # Public-write API keys for the Marlin analytics SDK. apiKey: @@ -160,16 +172,16 @@ params: # Use `grep` to figure out how they might be used. # Latest version of the Docker Engine API - latest_engine_api_version: "1.54" + latest_engine_api_version: "1.56" # Latest version of Docker Engine - docker_ce_version: "29.5.3" + docker_ce_version: "29.8.2" # Previous version of the Docker Engine # (Used to show e.g., "latest" and "latest"-1 in engine install examples - docker_ce_version_prev: "29.5.2" + docker_ce_version_prev: "29.8.1" # Latest Docker Compose version - compose_version: "v5.1.2" + compose_version: "v5.6.0" # Latest BuildKit version - buildkit_version: "0.28.0" + buildkit_version: "0.32.0" # Latest actions version bake_action_version: "v7" build_push_action_version: "v7" @@ -185,7 +197,7 @@ params: cache_action_version: "v5" # Example runtime/library/os versions - example_go_version: "1.25" + example_go_version: "1.26" example_alpine_version: "3.23" example_node_version: "24" @@ -314,6 +326,8 @@ module: extended: false min: "0.156.0" mounts: + - source: data + target: data # Mount the assets directory so it doesn't get overwritten - source: assets target: assets @@ -390,3 +404,29 @@ module: - source: cmd/cli/docs/reference target: data/cli/model files: ["*.yaml"] + + # Docker Agent + # Single-sources https://docker.github.io/docker-agent/ content; + # bumped on each docker-agent release by sync-docker-agent-docs.yml. + # Sections are mounted individually so hugo mod vendor does not + # vendor the upstream Jekyll site files that also live in docs/. + - path: github.com/docker/docker-agent + mounts: + - source: docs/getting-started + target: content/manuals/ai/docker-agent/getting-started + - source: docs/concepts + target: content/manuals/ai/docker-agent/concepts + - source: docs/configuration + target: content/manuals/ai/docker-agent/configuration + - source: docs/tools + target: content/manuals/ai/docker-agent/tools + - source: docs/providers + target: content/manuals/ai/docker-agent/providers + - source: docs/features + target: content/manuals/ai/docker-agent/features + - source: docs/guides + target: content/manuals/ai/docker-agent/guides + - source: docs/community + target: content/manuals/ai/docker-agent/community + - source: docs/demo.gif + target: content/manuals/ai/docker-agent/demo.gif diff --git a/layouts/_markup/render-codeblock-mermaid.html b/layouts/_markup/render-codeblock-mermaid.html index 25ddaa2bd0b2..fa3c10d59747 100644 --- a/layouts/_markup/render-codeblock-mermaid.html +++ b/layouts/_markup/render-codeblock-mermaid.html @@ -1,5 +1,34 @@ {{- .Page.Store.Set "mermaid" true -}} -<pre - class="mermaid not-prose my-4 flex justify-center bg-transparent" - data-pagefind-ignore ->{{- .Inner -}}</pre> +{{- $title := .Attributes.title -}} +{{- $caption := .Attributes.caption -}} +{{- if or $title $caption -}} + {{- $id := printf "mermaid-%s-%d" .Page.File.UniqueID .Ordinal -}} + <figure + class="my-4" + {{- with $title }} aria-labelledby="{{ $id }}-title"{{ end }} + {{- with $caption }} aria-describedby="{{ $id }}-caption"{{ end }} + > + {{- with $title }} + <p id="{{ $id }}-title" class="mb-2 text-center font-medium"> + {{ . }} + </p> + {{- end }} + <pre + class="mermaid not-prose flex justify-center bg-transparent" + data-pagefind-ignore + >{{- $.Inner -}}</pre> + {{- with $caption }} + <figcaption + id="{{ $id }}-caption" + class="text-center text-gray-600 dark:text-gray-400" + > + {{ . }} + </figcaption> + {{- end }} + </figure> +{{- else -}} + <pre + class="mermaid not-prose my-4 flex justify-center bg-transparent" + data-pagefind-ignore + >{{- .Inner -}}</pre> +{{- end -}} diff --git a/layouts/_partials/api-ref/curl.html b/layouts/_partials/api-ref/curl.html deleted file mode 100644 index 5baa2107c8d2..000000000000 --- a/layouts/_partials/api-ref/curl.html +++ /dev/null @@ -1,139 +0,0 @@ -{{/* Build a curl command for an OpenAPI operation. - - Input dict: - api — unmarshaled spec root - op — operation object - method — http method (lowercase string) - path — path string (e.g. "/orgs/{org_name}/policies") - sharedParams — already-resolved path-level parameters - - Output: a multi-line curl command string (line-continued with " \\\n "). - Path placeholders are filled from parameter examples when available; - unresolved path params fall back to `<name>`. Query params without an - example are omitted. Bearer-auth schemes contribute an Authorization - header with the literal `$TOKEN` placeholder. -*/}} -{{- $api := .api -}} -{{- $op := .op -}} -{{- $method := .method -}} -{{- $path := .path -}} -{{- $sharedParams := .sharedParams -}} - -{{/* Combine path-level + operation-level parameters, resolving $refs. */}} -{{- $params := $sharedParams -}} -{{- with index $op "parameters" -}} - {{- range . -}} - {{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $params = $params | append $p -}} - {{- end -}} -{{- end -}} - -{{/* Substitute path placeholders. */}} -{{- $url := $path -}} -{{- range $params -}} - {{- if eq .in "path" -}} - {{- $val := printf "<%s>" .name -}} - {{- with .example -}}{{- $val = . | string -}}{{- end -}} - {{- with .examples -}} - {{- $picked := false -}} - {{- with index . "default" -}} - {{- with .value -}} - {{- $val = . | string -}}{{- $picked = true -}} - {{- end -}} - {{- end -}} - {{- if not $picked -}} - {{- range . -}} - {{- if not $picked -}} - {{- with .value -}} - {{- $val = . | string -}}{{- $picked = true -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- $url = replace $url (printf "{%s}" .name) $val -}} - {{- end -}} -{{- end -}} - -{{/* Append query string from query parameters that have examples. */}} -{{- $qs := slice -}} -{{- range $params -}} - {{- if eq .in "query" -}} - {{- $val := "" -}} - {{- with .example -}}{{- $val = . | string -}}{{- end -}} - {{- with .examples -}} - {{- $picked := false -}} - {{- with index . "default" -}} - {{- with .value -}} - {{- $val = . | string -}}{{- $picked = true -}} - {{- end -}} - {{- end -}} - {{- if not $picked -}} - {{- range . -}} - {{- if not $picked -}} - {{- with .value -}} - {{- $val = . | string -}}{{- $picked = true -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- if $val -}} - {{- $qs = $qs | append (printf "%s=%s" .name $val) -}} - {{- end -}} - {{- end -}} -{{- end -}} -{{- if $qs -}}{{- $url = printf "%s?%s" $url (delimit $qs "&") -}}{{- end -}} - -{{/* Prepend base URL from the first server entry. */}} -{{- $base := "" -}} -{{- with index $api.servers 0 -}}{{- $base = .url -}}{{- end -}} -{{- $fullURL := printf "%s%s" $base $url -}} - -{{- $lines := slice (printf "curl -X %s '%s'" (upper $method) $fullURL) -}} - -{{/* Bearer auth header if the spec defines a bearer scheme. */}} -{{- $hasBearer := false -}} -{{- with $api.components -}} - {{- with .securitySchemes -}} - {{- range . -}} - {{- if and (eq .type "http") (eq .scheme "bearer") -}} - {{- $hasBearer = true -}} - {{- end -}} - {{- end -}} - {{- end -}} -{{- end -}} -{{- if $hasBearer -}} - {{- $lines = $lines | append "-H 'Authorization: Bearer $TOKEN'" -}} -{{- end -}} - -{{/* Request body example. Picks the first content type declared. */}} -{{- with $op.requestBody -}} - {{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $ct := "" -}} - {{- $media := dict -}} - {{- range $name, $m := $body.content -}} - {{- if not $ct -}}{{- $ct = $name -}}{{- $media = $m -}}{{- end -}} - {{- end -}} - {{- if $ct -}} - {{- $lines = $lines | append (printf "-H 'Content-Type: %s'" $ct) -}} - {{- $example := "" -}} - {{- with $media.examples -}} - {{- with index . "default" -}} - {{- with .value -}}{{- $example = . | jsonify -}}{{- end -}} - {{- end -}} - {{- if not $example -}} - {{- range . -}} - {{- if not $example -}} - {{- with .value -}}{{- $example = . | jsonify -}}{{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} - {{- if $example -}} - {{- $lines = $lines | append (printf "-d '%s'" $example) -}} - {{- end -}} - {{- end -}} -{{- end -}} - -{{- return (delimit $lines " \\\n ") -}} diff --git a/layouts/_partials/api-ref/nav.html b/layouts/_partials/api-ref/nav.html deleted file mode 100644 index f182e4d8a369..000000000000 --- a/layouts/_partials/api-ref/nav.html +++ /dev/null @@ -1,86 +0,0 @@ -{{/* Right-rail navigation for an OpenAPI reference page. - - Input: the unmarshaled spec root (plain map from transform.Unmarshal). - - Lists Authentication, every tag with its operations (linking to the same - anchors the operation cards expose), and the Schemas section heading. -*/}} -{{- $api := . -}} -{{- $paths := $api.paths -}} -{{- $methods := slice "get" "post" "put" "patch" "delete" -}} -{{- $methodColors := dict - "get" "text-blue-700 dark:text-blue-300" - "post" "text-green-700 dark:text-green-300" - "put" "text-yellow-700 dark:text-yellow-300" - "patch" "text-yellow-700 dark:text-yellow-300" - "delete" "text-red-700 dark:text-red-300" --}} - - -<p - class="mb-3 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400" -> - On this page -</p> -<ul class="space-y-1"> - {{- with $api.components }} - {{- if .securitySchemes }} - <li> - <a - href="#authentication" - class="block py-0.5 text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400" - > - Authentication - </a> - </li> - {{- end }} - {{- end }} - {{- range $api.tags }} - {{- $tagName := .name }} - <li class="mt-3"> - <a - href="#tag-{{ $tagName | urlize }}" - class="block py-0.5 text-xs font-semibold tracking-wider text-gray-500 uppercase hover:text-blue-600 dark:text-gray-400 dark:hover:text-blue-400" - > - {{ $tagName | title }} - </a> - <ul class="mt-1 space-y-0.5"> - {{- range $path, $item := $paths }} - {{- range $methods }} - {{- $method := . }} - {{- with index $item $method }} - {{- $op := . }} - {{- if in $op.tags $tagName }} - {{- $label := $op.summary | default $op.operationId | default $path }} - <li> - <a - href="#operation-{{ $op.operationId }}" - class="flex items-baseline gap-2 py-0.5 text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400" - > - <span - class="{{ index $methodColors $method }} w-12 flex-none font-mono text-[10px] font-bold uppercase" - >{{ upper $method }}</span - > - <span class="min-w-0 truncate">{{ $label }}</span> - </a> - </li> - {{- end }} - {{- end }} - {{- end }} - {{- end }} - </ul> - </li> - {{- end }} - {{- with $api.components }} - {{- if .schemas }} - <li class="mt-3"> - <a - href="#schemas" - class="block py-0.5 text-xs font-semibold tracking-wider text-gray-500 uppercase hover:text-blue-600 dark:text-gray-400 dark:hover:text-blue-400" - > - Schemas - </a> - </li> - {{- end }} - {{- end }} -</ul> diff --git a/layouts/_partials/api-ref/resolve.html b/layouts/_partials/api-ref/resolve.html deleted file mode 100644 index 80c7e25fe7de..000000000000 --- a/layouts/_partials/api-ref/resolve.html +++ /dev/null @@ -1,26 +0,0 @@ -{{/* Resolve a possibly-$ref'd OpenAPI node against the spec root. - - Input dict: - api — the unmarshaled spec root (plain map from transform.Unmarshal) - node — the node to resolve; may be a map, slice, primitive, or nil - - Returns: - - if node is a map containing a "$ref" key, returns the target node - reached by walking the JSON-Pointer fragment (only internal "#/" refs - are supported) - - otherwise returns node unchanged -*/}} -{{- $node := .node -}} -{{- if reflect.IsMap $node -}} - {{- with index $node "$ref" -}} - {{- if hasPrefix . "#/" -}} - {{- $parts := after 1 (split . "/") -}} - {{- $cur := $.api -}} - {{- range $parts -}} - {{- $cur = index $cur . -}} - {{- end -}} - {{- $node = $cur -}} - {{- end -}} - {{- end -}} -{{- end -}} -{{- return $node -}} diff --git a/layouts/_partials/api-reference/description.html b/layouts/_partials/api-reference/description.html new file mode 100644 index 000000000000..1616cc83a7f5 --- /dev/null +++ b/layouts/_partials/api-reference/description.html @@ -0,0 +1,13 @@ +{{- $text := .text | default "" -}} +{{- $api := .api -}} +{{- range $api.operations -}} + {{- $text = replace $text (printf "(#operation/%s)" .id) (printf "(%s)" .url) -}} + {{- $text = replaceRE (printf "\\(#tag/[^)]+/operation/%s\\)" .id) (printf "(%s)" .url) $text -}} +{{- end -}} +{{- range $api.schemas -}} + {{- $text = replace $text (printf "(#schema-%s)" .name) (printf "(%s)" .url) -}} +{{- end -}} +{{- range $api.tags -}} + {{- $text = replace $text (printf "(#tag/%s)" .name) (printf "(%s#tag-%s)" $api.url (.name | urlize)) -}} +{{- end -}} +{{- return $text -}} diff --git a/layouts/_partials/api-reference/manual-link.html b/layouts/_partials/api-reference/manual-link.html new file mode 100644 index 000000000000..e0fd881505a6 --- /dev/null +++ b/layouts/_partials/api-reference/manual-link.html @@ -0,0 +1,13 @@ +{{ if ne .Params.apiReferenceBanner false }} + {{ $data := index hugo.Data "api-reference" }} + {{ range $data.apis }} + {{ $manual := site.GetPage .manual }} + {{ if and $manual (eq $manual.RelPermalink $.RelPermalink) }} + <p + class="my-4 rounded border border-blue-200 bg-blue-50 p-4 text-sm text-blue-900 dark:border-blue-600 dark:bg-blue-950 dark:text-blue-100" + > + <a href="{{ .url }}">Explore the {{ .title }} API {{ .version }} →</a> + </p> + {{ end }} + {{ end }} +{{ end }} diff --git a/layouts/_partials/api-reference/navigation.html b/layouts/_partials/api-reference/navigation.html new file mode 100644 index 000000000000..3a814260e04e --- /dev/null +++ b/layouts/_partials/api-reference/navigation.html @@ -0,0 +1,36 @@ +{{ $data := index hugo.Data "api-reference" }} +<nav class="api-nav" aria-label="API navigation"> + <a class="api-nav-back" href="/reference/api/">← API catalog</a> + {{ range $data.apis }} + {{ if eq .id $.Params.apiID }} + <h2>{{ .title }}</h2> + <p class="api-nav-version">API {{ .version }}</p> + <a + href="{{ .url }}" + {{ if eq $.Params.view "overview" }} + aria-current="page" id="sidebar-current-page" + {{ end }} + >Overview</a + > + {{ range .tags }} + {{ if eq .kind "nav" }} + {{ $tag := .name }} + <h3>{{ .summary }}</h3> + {{ range (index (where $data.apis "id" $.Params.apiID) 0).operations }} + {{ if eq (index .tags 0) $tag }} + <a + class="api-nav-operation" + href="{{ .url }}" + {{ if eq .id $.Params.operationID }} + aria-current="page" id="sidebar-current-page" + {{ end }} + ><small data-method="{{ .method }}">{{ .method }}</small + ><span>{{ .summary }}</span></a + > + {{ end }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} +</nav> diff --git a/layouts/_partials/api-reference/overview-tags.html b/layouts/_partials/api-reference/overview-tags.html new file mode 100644 index 000000000000..796138cc1c00 --- /dev/null +++ b/layouts/_partials/api-reference/overview-tags.html @@ -0,0 +1,11 @@ +{{- /* Navigation placeholders and schema-only links are covered by the indexes. */ -}} +{{- $visible := slice -}} +{{- range .tags -}} + {{- $description := strings.TrimSpace (.description | default "") -}} + {{- $placeholder := or (eq $description (printf "%s reference." .summary)) (eq $description (printf "%s operations." .name)) -}} + {{- $schemaLink := findRE `^\[[^\]]+\]\(#schema-[^)]+\)$` $description -}} + {{- if and $description (not $placeholder) (not $schemaLink) -}} + {{- $visible = $visible | append . -}} + {{- end -}} +{{- end -}} +{{- return $visible -}} diff --git a/layouts/_partials/api-reference/path.html b/layouts/_partials/api-reference/path.html new file mode 100644 index 000000000000..cb8045e25430 --- /dev/null +++ b/layouts/_partials/api-reference/path.html @@ -0,0 +1,4 @@ +{{- /* Break long paths between segments without changing their copied text. */ -}} +{{- range $i, $segment := split . "/" -}} + {{- if $i -}}<wbr />/{{- end -}}{{- $segment -}} +{{- end -}} diff --git a/layouts/_partials/api-reference/schema.html b/layouts/_partials/api-reference/schema.html new file mode 100644 index 000000000000..d044f93dafab --- /dev/null +++ b/layouts/_partials/api-reference/schema.html @@ -0,0 +1,85 @@ +{{ $s := .schema }}{{ $api := .api }}{{ $depth := .depth }} +{{ if reflect.IsMap $s }} + {{ with index $s "$ref" }} + {{ $url := index $api.schemaURLs . }} + <p class="api-ref"> + Schema: + {{ if $url }} + <a href="{{ $url }}" + ><code>{{ strings.TrimPrefix "#/components/schemas/" . }}</code></a + > + {{ else }} + <code>{{ . }}</code> + {{ end }} + </p> + {{ end }} + {{ with $s.type }} + <p class="api-type"> + Type: + <code + >{{ if reflect.IsSlice . }} + {{ delimit . " | " }} + {{ else }} + {{ . }} + {{ end }}</code + > + </p> + {{ end }} + {{ with $s.description }} + <div class="prose dark:prose-invert">{{ . | markdownify }}</div> + {{ end }} + {{ if lt $depth 3 }} + {{ range $name,$v := $s.properties }} + <details class="api-field" {{ if eq $depth 0 }}open{{ end }}> + <summary> + <code>{{ $name }}</code>{{ if in $s.required $name }} + · required + {{ end }}{{ if $v.readOnly }} + · response only + {{ end }}{{ if $v.writeOnly }}· request only{{ end }} + </summary> + {{ partial "api-reference/schema.html" (dict "schema" $v "api" $api "depth" (add $depth 1)) }} + </details> + {{ end }} + {{ range $keyword := slice "allOf" "oneOf" "anyOf" }} + {{ with index $s $keyword }} + <details class="api-field" open> + <summary> + {{ if eq $keyword "allOf" }} + All constraints apply + {{ else if eq $keyword "oneOf" }} + Exactly one alternative must match + {{ else }} + One or more alternatives must match + {{ end }} + </summary> + {{ range . }} + {{ partial "api-reference/schema.html" (dict "schema" . "api" $api "depth" (add $depth 1)) }} + {{ end }} + </details> + {{ end }} + {{ end }} + {{ if isset $s "items" }} + <details class="api-field"> + <summary>Array item</summary> + {{ partial "api-reference/schema.html" (dict "schema" $s.items "api" $api "depth" (add $depth 1)) }} + </details> + {{ end }} + {{ end }} + {{ if or (ge $depth 3) (not (index $s "$ref")) (gt (len $s) 1) }} + <details class="api-constraints"> + <summary>All schema constraints and annotations</summary> + <pre><code>{{ $s | jsonify (dict "indent" " ") }}</code></pre> + </details> + {{ end }} +{{ else }} + <p> + {{ if eq $s false }} + No value satisfies this schema. + {{ else if eq $s true }} + Any value satisfies this schema. + {{ else }} + No schema is declared. + {{ end }} + </p> +{{ end }} diff --git a/layouts/_partials/api-reference/websocket.html b/layouts/_partials/api-reference/websocket.html new file mode 100644 index 000000000000..4f6f9a425ec6 --- /dev/null +++ b/layouts/_partials/api-reference/websocket.html @@ -0,0 +1,19 @@ +{{ $socket := .socket }} +{{ $api := .api }} +<section> + <h2>WebSocket session</h2> + <p>Subprotocol: <code>{{ $socket.subprotocol }}</code></p> + {{ range $key := slice "authentication" "browser" "reconnect" "terminalFrame" }} + {{ with index $socket $key }}<p>{{ . }}</p>{{ end }} + {{ end }} + {{ range $frame := slice (dict "key" "requestFrame" "title" "Client frames") (dict "key" "responseFrame" "title" "Server frames") (dict "key" "errorFrame" "title" "Error frames") }} + {{ with index $socket $frame.key }} + <h3>{{ $frame.title }}</h3> + {{ partial "api-reference/schema.html" (dict "schema" . "api" $api "depth" 0) }} + {{ end }} + {{ end }} + <details> + <summary>Handshake, resume fields, and close codes</summary> + <pre><code>{{ $socket | jsonify (dict "indent" " ") }}</code></pre> + </details> +</section> diff --git a/layouts/_partials/aside.html b/layouts/_partials/aside.html index bed195c70852..5ed76e1a20cb 100644 --- a/layouts/_partials/aside.html +++ b/layouts/_partials/aside.html @@ -1,5 +1,5 @@ <aside - class="sticky top-16 h-[calc(100vh-64px)] min-w-52 space-y-4 overflow-y-auto py-4 w-full" + class="scrollbar-hover sticky top-16 h-[calc(100vh-64px)] min-w-52 space-y-4 overflow-y-auto py-4 w-full" > {{ partial "github-links.html" . }} <div id="TableOfContents" class="overflow-x-auto"> diff --git a/layouts/_partials/content-default.html b/layouts/_partials/content-default.html index 48b333564e25..4dcb550f6309 100644 --- a/layouts/_partials/content-default.html +++ b/layouts/_partials/content-default.html @@ -1,5 +1,10 @@ {{ partial "breadcrumbs.html" . }} <h1 data-pagefind-weight="10">{{ .Title | safeHTML }}</h1> +{{- if and (eq .Type "guides") .Params.summary }} + <p class="mt-0 text-lg text-gray-500 dark:text-gray-400"> + {{ .Params.summary }} + </p> +{{- end }} <div class="hidden lg:block"> {{ partialCached "md-dropdown.html" "-" "-" }} </div> @@ -7,6 +12,10 @@ <h1 data-pagefind-weight="10">{{ .Title | safeHTML }}</h1> {{ partialCached "pagemeta.html" . . }} <hr /> </div> +{{ partial "api-reference/manual-link.html" . }} +{{ if and .CurrentSection.Params.recipeCatalog (not .IsSection) }} + <p><a href="{{ .CurrentSection.RelPermalink }}">Browse all recipes</a></p> +{{ end }} {{ .Content }} {{- if and (eq .Type "guides") (not .IsSection) (ne .CurrentSection .FirstSection) -}} {{- with .PrevInSection -}} diff --git a/layouts/_partials/footer.html b/layouts/_partials/footer.html index 4004ed3b3dba..6ec3a678cfec 100644 --- a/layouts/_partials/footer.html +++ b/layouts/_partials/footer.html @@ -65,10 +65,10 @@ </button> <span class="mx-1 text-gray-400">|</span> <a - title="Docker Terms of Service" - href="https://www.docker.com/legal/docker-terms-service" + title="Docker Terms of Use" + href="https://www.docker.com/legal/docker-terms-use/" class="whitespace-normal md:truncate" - >Terms of Service</a + >Terms of Use</a > <span class="mx-1 text-gray-400">|</span> <a @@ -93,3 +93,4 @@ >Copyright © 2013-{{ time.Now.Year }} Docker Inc. All rights reserved.</span > </div> +<a href="{{ "bot-detection/" | relURL }}" hidden>Automated traffic detection</a> diff --git a/layouts/_partials/gordon-chat.html b/layouts/_partials/gordon-chat.html index 6349e8c3dd5f..ad9740ef90c4 100644 --- a/layouts/_partials/gordon-chat.html +++ b/layouts/_partials/gordon-chat.html @@ -334,7 +334,7 @@ x-transition:leave="transition ease-in duration-200" x-transition:leave-start="translate-x-0" x-transition:leave-end="translate-x-full" - class="fixed top-0 right-0 z-50 flex h-screen w-full flex-col overflow-hidden rounded-none bg-white shadow-2xl transition-all duration-200 md:w-[min(80ch,90vw)] dark:bg-gray-950" + class="fixed top-0 right-0 z-50 flex h-screen w-full flex-col overflow-hidden overscroll-contain rounded-none bg-white shadow-2xl transition-all duration-200 md:w-[min(80ch,90vw)] dark:bg-gray-950" > <!-- Header --> <div @@ -385,21 +385,20 @@ <!-- Messages container --> <div x-ref="messagesContainer" - class="flex-1 space-y-4 p-6" + class="flex min-h-0 flex-1 flex-col space-y-4 overflow-y-auto overscroll-contain p-6" style="scrollbar-width: none; &::-webkit-scrollbar: { display: none; }" - :class="{ 'overflow-y-auto': messages.length > 0 }" > <!-- Welcome message when empty --> <template x-if="messages.length === 0"> <div - class="flex h-full flex-col items-center justify-start overflow-y-auto px-2 pt-4 pb-2 text-center" + class="my-auto flex flex-col items-center gap-2 px-2 pt-4 pb-2 text-center" > - <div class="mx-auto mb-2 w-4/5 max-w-xs" aria-hidden="true"> - <div - class="motion-safe:animate-[robotFloat_5s_ease-in-out_infinite]" - > - {{ partialCached "icon" "images/gordon-robot.svg" "images/gordon-robot.svg" }} - </div> + <div + class="mx-auto mb-2" + style="width: clamp(80px, 35%, 160px)" + aria-hidden="true" + > + {{ partialCached "icon" "images/gordon-robot.svg" "images/gordon-robot.svg" }} </div> <div class="flex w-full flex-col items-center justify-start gap-3"> <h3 class="text-xl font-semibold text-gray-900 dark:text-white"> @@ -711,17 +710,6 @@ <h3 class="text-xl font-semibold text-gray-900 dark:text-white"> <!-- Styles for Gordon chat --> <style> - /* Robot floating animation */ - @keyframes robotFloat { - 0%, - 100% { - transform: translateY(0px) rotate(0deg); - } - 50% { - transform: translateY(-15px) rotate(1deg); - } - } - /* Code block styles */ #gordon-chat pre { background: #0d1117; diff --git a/layouts/_partials/guide-languages.html b/layouts/_partials/guide-languages.html deleted file mode 100644 index 681f6d1ebfa1..000000000000 --- a/layouts/_partials/guide-languages.html +++ /dev/null @@ -1,15 +0,0 @@ -{{- range . -}} - {{- $lang := index hugo.Data.languages . -}} - {{- with $lang }} - <span class="chip"> - <img - class="py-1" - height="18" - width="18" - title="{{ .title }}" - src="{{ .icon }}" - /> - <span>{{ .title }}</span> - </span> - {{- end -}} -{{- end -}} diff --git a/layouts/_partials/guide-tags.html b/layouts/_partials/guide-tags.html deleted file mode 100644 index 52f36a21b26e..000000000000 --- a/layouts/_partials/guide-tags.html +++ /dev/null @@ -1,9 +0,0 @@ -{{- range . -}} - {{- $tag := index hugo.Data.tags . -}} - {{- with $tag }} - <span class="chip"> - <span class="icon-svg icon-sm pb-0.5">{{ partialCached "icon" "tag" "tag" }}</span> - {{ .title }} - </span> - {{- end -}} -{{- end -}} diff --git a/layouts/_partials/guides-stepper.html b/layouts/_partials/guides-stepper.html deleted file mode 100644 index 362497520ba6..000000000000 --- a/layouts/_partials/guides-stepper.html +++ /dev/null @@ -1,58 +0,0 @@ -{{/* - Multi-page guide: render a progress bar - */}} -<div class="my-4 flex flex-col items-start text-sm"> - {{ $totalPages := len .CurrentSection.Pages }} - {{/* - initialize the page store - - $stepper_seen controls the color of the item in the stepper - - green: "completed" - index is lower than current page - blue: current page - gray: next in section - for the section page, they're all gray - - default to true if kind = section - (make all entries gray) - - - - */}} - {{ page.Store.Set "stepper_seen" .IsSection }} - {{/* - Loop over the pages in this guide - */}} - {{ range $i, $e := .CurrentSection.Pages }} - {{ $isLast := eq (add $i 1) $totalPages }} - <div class="flex"> - <div class="flex flex-col items-center"> - {{/* - Render the page's index digit (1,2,3,4 etc) - */}} - <a - href="{{ .Permalink }}" - class="{{ if (page.Store.Get "stepper_seen") }} - bg-gray-400 dark:bg-gray-500 - {{ else if (eq . page) }} - {{ .Store.Set "stepper_seen" true }} bg-blue-400 dark:bg-blue-800 - {{ else }} - bg-green-400 dark:bg-green-dark-400 - {{ end }} flex h-8 w-8 items-center justify-center rounded-full text-white no-underline" - > - {{ add $i 1 }} - </a> - {{/* - Render the vertical border - */}} - {{ if not $isLast }} - <div - class="{{ if (page.Store.Get "stepper_seen") }} - border-gray-400 dark:border-gray-400 - {{ else if (eq . page) }} - border-blue-400 dark:border-blue-400 - {{ else }} - border-green-400 dark:border-green-400 - {{ end }} h-6 border-l-2" - ></div> - {{ end }} - </div> - {{/* - Render the page's title - */}} - <div class="ml-2 flex h-8 items-center self-start"> - <a href="{{ .Permalink }}"> - {{ .LinkTitle }} - </a> - </div> - </div> - {{ end }} -</div> diff --git a/layouts/_partials/head.html b/layouts/_partials/head.html index 15afc7ad4338..e4023bd13f4e 100644 --- a/layouts/_partials/head.html +++ b/layouts/_partials/head.html @@ -43,19 +43,6 @@ })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv='); </script> {{- else if (eq hugo.Environment "staging") -}} - <!-- Start VWO Async SmartCode --> - <link rel="preconnect" href="https://dev.visualwebsiteoptimizer.com" /> - <script type='text/javascript' id='vwoCode'> - window._vwo_code || (function() { - var account_id={{ site.Params.analytics.vwo | safeJS }}, - version=2.1, - settings_tolerance=2000, - hide_element='body', - hide_element_style = 'opacity:0 !important;filter:alpha(opacity=0) !important;background:none !important', - /* DO NOT EDIT BELOW THIS LINE */ - f=false,w=window,d=document,v=d.querySelector('#vwoCode'),cK='_vwo_'+account_id+'_settings',cc={};try{var c=JSON.parse(localStorage.getItem('_vwo_'+account_id+'_config'));cc=c&&typeof c==='object'?c:{}}catch(e){}var stT=cc.stT==='session'?w.sessionStorage:w.localStorage;code={use_existing_jquery:function(){return typeof use_existing_jquery!=='undefined'?use_existing_jquery:undefined},library_tolerance:function(){return typeof library_tolerance!=='undefined'?library_tolerance:undefined},settings_tolerance:function(){return cc.sT||settings_tolerance},hide_element_style:function(){return'{'+(cc.hES||hide_element_style)+'}'},hide_element:function(){if(performance.getEntriesByName('first-contentful-paint')[0]){return''}return typeof cc.hE==='string'?cc.hE:hide_element},getVersion:function(){return version},finish:function(e){if(!f){f=true;var t=d.getElementById('_vis_opt_path_hides');if(t)t.parentNode.removeChild(t);if(e)(new Image).src='https://dev.visualwebsiteoptimizer.com/ee.gif?a='+account_id+e}},finished:function(){return f},addScript:function(e){var t=d.createElement('script');t.type='text/javascript';if(e.src){t.src=e.src}else{t.text=e.text}d.getElementsByTagName('head')[0].appendChild(t)},load:function(e,t){var i=this.getSettings(),n=d.createElement('script'),r=this;t=t||{};if(i){n.textContent=i;d.getElementsByTagName('head')[0].appendChild(n);if(!w.VWO||VWO.caE){stT.removeItem(cK);r.load(e)}}else{var o=new XMLHttpRequest;o.open('GET',e,true);o.withCredentials=!t.dSC;o.responseType=t.responseType||'text';o.onload=function(){if(t.onloadCb){return t.onloadCb(o,e)}if(o.status===200){_vwo_code.addScript({text:o.responseText})}else{_vwo_code.finish('&e=loading_failure:'+e)}};o.onerror=function(){if(t.onerrorCb){return t.onerrorCb(e)}_vwo_code.finish('&e=loading_failure:'+e)};o.send()}},getSettings:function(){try{var e=stT.getItem(cK);if(!e){return}e=JSON.parse(e);if(Date.now()>e.e){stT.removeItem(cK);return}return e.s}catch(e){return}},init:function(){if(d.URL.indexOf('__vwo_disable__')>-1)return;var e=this.settings_tolerance();w._vwo_settings_timer=setTimeout(function(){_vwo_code.finish();stT.removeItem(cK)},e);var t;if(this.hide_element()!=='body'){t=d.createElement('style');var i=this.hide_element(),n=i?i+this.hide_element_style():'',r=d.getElementsByTagName('head')[0];t.setAttribute('id','_vis_opt_path_hides');v&&t.setAttribute('nonce',v.nonce);t.setAttribute('type','text/css');if(t.styleSheet)t.styleSheet.cssText=n;else t.appendChild(d.createTextNode(n));r.appendChild(t)}else{t=d.getElementsByTagName('head')[0];var n=d.createElement('div');n.style.cssText='z-index: 2147483647 !important;position: fixed !important;left: 0 !important;top: 0 !important;width: 100% !important;height: 100% !important;background: white !important;';n.setAttribute('id','_vis_opt_path_hides');n.classList.add('_vis_hide_layer');t.parentNode.insertBefore(n,t.nextSibling)}var o='https://dev.visualwebsiteoptimizer.com/j.php?a='+account_id+'&u='+encodeURIComponent(d.URL)+'&vn='+version;if(w.location.search.indexOf('_vwo_xhr')!==-1){this.addScript({src:o})}else{this.load(o+'&x=true')}}};w._vwo_code=code;code.init();})(); - </script> - <!-- End VWO Async SmartCode --> <script> (function(h,o,t,j,a,r){ h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)}; diff --git a/layouts/_partials/interactive-diagram-script.html b/layouts/_partials/interactive-diagram-script.html new file mode 100644 index 000000000000..84c0ec2fa443 --- /dev/null +++ b/layouts/_partials/interactive-diagram-script.html @@ -0,0 +1,4 @@ +{{ $diagram := resources.Get "js/interactive-diagram.js" + | js.Build (dict "minify" true "targetPath" "interactive-diagram.js") +}} +<script defer src="{{ $diagram.RelPermalink }}"></script> diff --git a/layouts/_partials/sidebar/guides.html b/layouts/_partials/sidebar/guides.html deleted file mode 100644 index 584d9530f10d..000000000000 --- a/layouts/_partials/sidebar/guides.html +++ /dev/null @@ -1,39 +0,0 @@ -{{- $guide := cond (eq .CurrentSection .FirstSection) . .CurrentSection -}} -<div class="flex flex-col gap-4 px-4 pt-2"> - <div class="font-semibold"> - <a href="{{ $guide.Permalink }}">{{ $guide.Title }}</a> - </div> - <div>{{ $guide.Summary }}</div> - <div class="space-y-4"> - <div class="flex flex-wrap gap-2"> - {{- with $guide.Params.languages }} - {{ partial "guide-languages.html" . }} - {{- end }} - {{- with $guide.Params.tags }} - {{ partial "guide-tags.html" . }} - {{- end }} - </div> - {{- with $guide.Params.time }} - <div class="flex gap-2 text-gray-400 dark:text-gray-400"> - <span class="icon-svg" - >{{ partialCached "icon" "clock" "clock" }}</span - > - <span>{{ . }}</span> - </div> - {{- end -}} - </div> - {{- if gt (len $guide.Pages) 0 }} - {{- partial "guides-stepper.html" . }} - {{- end }} - {{- with $guide.Params.resource_links }} - <div class="space-y-2"> - <p>Resources:</p> - <ul class="ml-4 space-y-2"> - {{- range . }} - <li><a href="{{ .url }}" class="link">{{ .title }}</a></li> - {{- end }} - </ul> - </div> - {{- end }} - <a href="/guides/" class="link mt-2">« Back to all guides</a> -</div> diff --git a/layouts/_partials/sidebar/sections.html b/layouts/_partials/sidebar/sections.html index 843e3f6a9dbe..8dc3433b6b3c 100644 --- a/layouts/_partials/sidebar/sections.html +++ b/layouts/_partials/sidebar/sections.html @@ -8,34 +8,50 @@ */ -}} <!-- section tree --> -<nav class="navbar-font flex flex-col mt-1 mx-1"> +<nav class="navbar-font mx-1 mt-1 flex flex-col"> <ul> - {{ template "renderChildren" .FirstSection }} + {{ template "renderChildren" (dict "section" .FirstSection "revealHidden" false) }} </ul> </nav> {{ define "renderChildren" }} - {{- $pages := where .Pages "Params.sitemap" "ne" "false" }} - {{- if .Params.sidebar.reverse }} - {{ $pages = .Pages.Reverse }} + {{- $section := .section }} + {{- $revealHidden := .revealHidden }} + {{- $sourcePages := $section.Pages }} + {{- if $section.Params.sidebar.reverse }} + {{ $sourcePages = $sourcePages.Reverse }} + {{- end }} + {{- $pages := slice }} + {{- range $sourcePages }} + {{- $isActive := or (eq page .) (page.IsDescendant .) }} + {{- if and (or (not $section.Params.sidebar.activeChildrenOnly) $isActive) (or (ne .Params.sitemap false) $isActive $revealHidden) }} + {{- $pages = $pages | append . }} + {{- end }} {{- end }} {{- $ungrouped := where $pages "Params.sidebar.group" "==" nil }} + {{- if $section.Params.sidebar.activeChildrenOnly }} + {{- $ungrouped = $pages }} + {{- end }} {{- range $ungrouped }} - {{- if .IsSection }} - {{- template "renderList" . }} + {{- if and .IsSection (not .Params.apiID) }} + {{- template "renderList" (dict "section" . "revealHidden" $revealHidden) }} {{- else }} {{- template "renderSingle" . }} {{- end }} {{- end }} - {{- range .Params.sidebar.groups }} + {{- $groups := $section.Params.sidebar.groups }} + {{- if $section.Params.sidebar.activeChildrenOnly }} + {{- $groups = slice }} + {{- end }} + {{- range $groups }} <!-- Main titles --> <div class="navbar-group"> <li class="navbar-group-font-title"> {{ . }} </li> {{- range where $pages "Params.sidebar.group" . }} - {{- if .IsSection }} - {{- template "renderList" . }} + {{- if and .IsSection (not .Params.apiID) }} + {{- template "renderList" (dict "section" . "revealHidden" $revealHidden) }} {{- else }} {{- template "renderSingle" . }} {{- end }} @@ -47,8 +63,10 @@ {{/* Recursive template for sidebar items */}} {{ define "renderList" }} - {{ $isCurrent := eq page . }} - {{ $expanded := or $isCurrent (page.IsDescendant .) }} + {{- $section := .section }} + {{- $isCurrent := eq page $section }} + {{- $expanded := or $isCurrent (page.IsDescendant $section) }} + {{- $revealHidden := or .revealHidden (and (eq $section.Params.sitemap false) $expanded) }} <li class="" x-data="{ expanded: {{ $expanded }} }"> <div class="{{ if $isCurrent }} @@ -56,7 +74,7 @@ {{ end }} flex w-full items-center justify-between rounded-sm" > <div class="navbar-entry-margin w-full truncate"> - {{- if .Permalink }} + {{- if $section.Permalink }} {{/* If the link is not empty, use it */}} <!-- Sections that have children and linking to a page --> <a @@ -64,9 +82,9 @@ aria-current="page" id="sidebar-current-page" {{ end }} class="hover:text-blue block select-none hover:dark:text-blue-400" - href="{{ .Permalink }}" + href="{{ $section.Permalink }}" > - {{ template "renderTitle" . }} + {{ template "renderTitle" $section }} </a> {{- else }} {{/* Otherwise, just expand the section */}} @@ -75,38 +93,45 @@ @click="expanded = !expanded" class="hover:text-blue w-full text-left select-none hover:dark:text-blue-400" > - {{ template "renderTitle" . }} + {{ template "renderTitle" $section }} </button> {{- end }} </div> {{/* Only show expand group button if section has children */}} - {{- $hasChildren := gt (len (where .Pages "Params.sitemap" "ne" "false")) 0 }} + {{- $children := slice }} + {{- range $section.Pages }} + {{- $isActive := or (eq page .) (page.IsDescendant .) }} + {{- if and (or (not $section.Params.sidebar.activeChildrenOnly) $isActive) (or (ne .Params.sitemap false) $isActive $revealHidden) }} + {{- $children = $children | append . }} + {{- end }} + {{- end }} + {{- $hasChildren := gt (len $children) 0 }} {{- if $hasChildren }} - <!-- Expand group button --> - <button - @click="expanded = !expanded" - class="rounded-sm px-1 hover:bg-gray-200 hover:dark:bg-gray-800" - > - <span - :class="{ 'hidden' : expanded }" - class="icon-svg icon-sm {{ if $expanded }}hidden{{ end }}" - > - {{ partialCached "icon" "chevron-down" "chevron-down" }} - </span> - <span - :class="{ 'hidden' : !expanded }" - class="icon-svg icon-sm {{ if not $expanded }}hidden{{ end }}" + <!-- Expand group button --> + <button + @click="expanded = !expanded" + class="rounded-sm px-1 hover:bg-gray-200 hover:dark:bg-gray-800" > - {{ partialCached "icon" "chevron-up" "chevron-up" }} - </span> - </button> + <span + :class="{ 'hidden' : expanded }" + class="icon-svg icon-sm {{ if $expanded }}hidden{{ end }}" + > + {{ partialCached "icon" "chevron-down" "chevron-down" }} + </span> + <span + :class="{ 'hidden' : !expanded }" + class="icon-svg icon-sm {{ if not $expanded }}hidden{{ end }}" + > + {{ partialCached "icon" "chevron-up" "chevron-up" }} + </span> + </button> {{- end }} </div> <ul :class="{ 'hidden' : !expanded }" class="{{ if not $expanded }}hidden{{ end }} ml-3" > - {{ template "renderChildren" . }} + {{ template "renderChildren" (dict "section" $section "revealHidden" $revealHidden) }} </ul> </li> {{ end }} diff --git a/layouts/_partials/whats-new.html b/layouts/_partials/whats-new.html new file mode 100644 index 000000000000..e050bc717004 --- /dev/null +++ b/layouts/_partials/whats-new.html @@ -0,0 +1,79 @@ +{{- $data := index hugo.Data "whats-new" -}} +{{- with $data.items -}} + {{- $items := sort . "published" "desc" -}} + {{- $more := where $items "featured" false -}} + <section class="py-10 md:py-12" x-data="{ expanded: false }"> + <div class="container mx-auto max-w-4xl px-4"> + <header class="mb-6 border-b border-gray-200 pb-4 dark:border-gray-800"> + <h2 class="text-2xl font-semibold text-gray-900 dark:text-white"> + What's new + </h2> + </header> + <ol> + {{ range $items }} + <li + {{ if not .featured }} + x-cloak x-show="expanded" x-collapse.duration.300ms + {{ end }} + class="grid grid-cols-[1fr] md:grid-cols-[5rem_1fr] md:gap-x-6" + > + <time + class="hidden pt-5 text-right text-sm text-gray-500 md:block dark:text-gray-400" + datetime="{{ .published }}" + >{{ .published | time.Format "Jan 2" }}</time + > + <a + href="{{ .url }}" + class="group relative block border-l border-gray-200 py-5 pl-7 dark:border-gray-700" + > + <span + aria-hidden="true" + class="absolute top-6 -left-[5px] size-[9px] rounded-full bg-gray-300 ring-4 ring-gray-50 transition group-hover:bg-blue-500 dark:bg-gray-600 dark:ring-gray-950 dark:group-hover:bg-blue-400" + ></span> + <span + class="mb-1 flex flex-wrap items-center gap-x-2 text-sm font-medium text-blue-600 dark:text-blue-400" + > + {{ .product }} + <time + class="font-normal text-gray-500 md:hidden dark:text-gray-400" + datetime="{{ .published }}" + >{{ .published | time.Format "Jan 2" }}</time + > + </span> + <span class="flex items-center gap-2"> + <span + class="font-medium text-gray-900 transition group-hover:text-blue-500 dark:text-white dark:group-hover:text-blue-400" + >{{ .title }}</span + > + <span + class="icon-svg shrink-0 text-gray-400 transition group-hover:translate-x-1 group-hover:text-blue-500 dark:text-gray-500 dark:group-hover:text-blue-400" + > + {{ partialCached "icon" "arrow-right" "arrow-right" }} + </span> + </span> + <span class="mt-1 block text-sm text-gray-600 dark:text-gray-300" + >{{ .description }}</span + > + </a> + </li> + {{ end }} + </ol> + {{ with $more }} + <button + type="button" + @click="expanded = !expanded" + :aria-expanded="expanded" + class="mt-4 ml-7 inline-flex items-center gap-1 text-sm font-medium text-blue-600 hover:text-blue-500 md:ml-[6.5rem] dark:text-blue-400 dark:hover:text-blue-300" + > + <span x-text="expanded ? 'Show less' : 'Show more'">Show more</span> + <span class="icon-svg icon-sm" x-show="!expanded"> + {{ partialCached "icon" "chevron-down" "chevron-down" }} + </span> + <span class="icon-svg icon-sm" x-cloak x-show="expanded"> + {{ partialCached "icon" "chevron-up" "chevron-up" }} + </span> + </button> + {{ end }} + </div> + </section> +{{- end -}} diff --git a/layouts/_shortcodes/button.html b/layouts/_shortcodes/button.html index 6155ecbf829a..071ec37e0dcd 100644 --- a/layouts/_shortcodes/button.html +++ b/layouts/_shortcodes/button.html @@ -1,5 +1,6 @@ {{ $text := .Get "text" }} {{ $url := .Get "url" }} +{{ $marlinLabel := .Get "marlin_label" }} {{- if (strings.HasPrefix $url "http") -}} {{ $url = $url | safeURL }} {{- else if (strings.FindRE `([^_]|^)index.md` $url 1) -}} @@ -7,4 +8,4 @@ {{- else -}} {{ $url = ref .Page $url }} {{- end -}} -<a class="button not-prose" href="{{ $url }}">{{ $text }}</a> +<a class="button not-prose" href="{{ $url }}"{{ with $marlinLabel }} marlin-label="{{ . }}"{{ end }}>{{ $text }}</a> diff --git a/layouts/_shortcodes/copy-as-prompt.html b/layouts/_shortcodes/copy-as-prompt.html new file mode 100644 index 000000000000..2373ebd95861 --- /dev/null +++ b/layouts/_shortcodes/copy-as-prompt.html @@ -0,0 +1,63 @@ +{{- $prompt := printf "%s\n\n%s" (.Get "instruction") (strings.TrimSpace .Inner) -}} +<div + data-prompt="{{ $prompt }}" + x-data="{ + status: 'idle', + async copy() { + this.status = 'copying'; + try { + await navigator.clipboard.writeText(this.$root.dataset.prompt); + this.status = 'copied'; + setTimeout(() => this.status = 'idle', 2000); + } catch { + this.status = 'failed'; + } + } + }" +> + <div + data-pagefind-ignore + x-cloak + class="not-prose my-4 flex flex-wrap items-center gap-3" + > + <button + type="button" + :aria-label="status === 'copied' ? 'Copied!' : status === 'copying' ? 'Copying…' : 'Copy as prompt'" + class="button inline-flex cursor-pointer items-center gap-2 transition duration-150 hover:shadow-sm disabled:cursor-default motion-safe:hover:-translate-y-0.5 motion-safe:active:scale-95 motion-reduce:transition-none" + :class="status === 'copied' ? 'bg-green-800 hover:bg-green-800 dark:bg-green-800 dark:hover:bg-green-800' : ''" + :disabled="status === 'copying' || status === 'copied'" + @click="copy()" + > + <span class="grid" aria-hidden="true"> + <span + class="icon-svg icon-sm col-start-1 row-start-1 transition duration-150 motion-reduce:scale-100 motion-reduce:rotate-0 motion-reduce:transition-none" + :class="status === 'copied' ? 'scale-75 -rotate-12 opacity-0' : 'scale-100 rotate-0 opacity-100'" + > + {{ partialCached "icon" "document-duplicate" "document-duplicate" }} + </span> + <span + class="icon-svg icon-sm col-start-1 row-start-1 transition duration-150 motion-reduce:scale-100 motion-reduce:rotate-0 motion-reduce:transition-none" + :class="status === 'copied' ? 'scale-100 rotate-0 opacity-100' : 'scale-75 rotate-12 opacity-0'" + > + {{ partialCached "icon" "check-circle" "check-circle" }} + </span> + </span> + <span class="grid text-center"> + <span class="invisible col-start-1 row-start-1" aria-hidden="true" + >Copy as prompt</span + > + <span + role="status" + class="col-start-1 row-start-1" + x-text="status === 'copied' ? 'Copied!' : status === 'copying' ? 'Copying…' : 'Copy as prompt'" + ></span> + </span> + </button> + <span + role="status" + class="text-sm" + x-text="status === 'failed' ? 'Could not copy. Select and copy the section text instead.' : ''" + ></span> + </div> + {{ .Page.RenderString (dict "display" "block") .Inner }} +</div> diff --git a/layouts/_shortcodes/copy-as-prompt.markdown.md b/layouts/_shortcodes/copy-as-prompt.markdown.md new file mode 100644 index 000000000000..c862a9a59e87 --- /dev/null +++ b/layouts/_shortcodes/copy-as-prompt.markdown.md @@ -0,0 +1 @@ +{{ .Inner -}} diff --git a/layouts/_shortcodes/desktop-install-v2.html b/layouts/_shortcodes/desktop-install-v2.html index 638d4fb9d368..518fd0a11b1e 100644 --- a/layouts/_shortcodes/desktop-install-v2.html +++ b/layouts/_shortcodes/desktop-install-v2.html @@ -12,6 +12,7 @@ {{- if or $all $win }} <li> <a rel="noopener" + marlin-label="download_exe_click" href="https://desktop.docker.com/win/main/amd64{{ $build_path }}Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows">Windows</a> (<a rel="noopener" href="https://desktop.docker.com/win/main/amd64{{ $build_path }}checksums.txt">checksum</a>) @@ -20,6 +21,7 @@ {{- if or $win_arm_release }} <li> <a rel="noopener" + marlin-label="download_exe_click" href="https://desktop.docker.com/win/main/arm64{{ $build_path }}Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows">Windows ARM {{ $win_arm_release }}</a> (<a rel="noopener" href="https://desktop.docker.com/win/main/arm64{{ $build_path }}checksums.txt">checksum</a>) @@ -30,12 +32,12 @@ {{- if or $all $mac }} <ul> <li> - <a rel="noopener" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64">Mac with Apple chip</a> + <a rel="noopener" marlin-label="download_dmg_click" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64">Mac with Apple chip</a> (<a rel="noopener" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}checksums.txt">checksum</a>) </li> <li> - <a rel="noopener" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64">Mac with Intel chip</a> + <a rel="noopener" marlin-label="download_dmg_click" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64">Mac with Intel chip</a> (<a rel="noopener" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}checksums.txt">checksum</a>) </li> diff --git a/layouts/_shortcodes/desktop-install.html b/layouts/_shortcodes/desktop-install.html index 148de3a7171b..bf1a18333f94 100644 --- a/layouts/_shortcodes/desktop-install.html +++ b/layouts/_shortcodes/desktop-install.html @@ -10,22 +10,24 @@ <p> {{- if or $all $win }} <a rel="noopener" + marlin-label="download_exe_click" href="https://desktop.docker.com/win/main/amd64{{ $build_path }}Docker%20Desktop%20Installer.exe">Windows</a> (<a rel="noopener" href="https://desktop.docker.com/win/main/amd64{{ $build_path }}checksums.txt">checksum</a>) | {{ end }} {{- if or $win_arm_release }} <a rel="noopener" + marlin-label="download_exe_click" href="https://desktop.docker.com/win/main/arm64{{ $build_path }}Docker%20Desktop%20Installer.exe">Windows ARM {{ $win_arm_release }}</a> (<a rel="noopener" href="https://desktop.docker.com/win/main/arm64{{ $build_path }}checksums.txt">checksum</a>) | {{ end }} {{- if or $all $mac }} - <a rel="noopener" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}Docker.dmg">Mac + <a rel="noopener" marlin-label="download_dmg_click" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}Docker.dmg">Mac with Apple chip</a> (<a rel="noopener" href="https://desktop.docker.com/mac/main/arm64{{ $build_path }}checksums.txt">checksum</a>) | - <a rel="noopener" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}Docker.dmg">Mac + <a rel="noopener" marlin-label="download_dmg_click" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}Docker.dmg">Mac with Intel chip</a> (<a rel="noopener" href="https://desktop.docker.com/mac/main/amd64{{ $build_path }}checksums.txt">checksum</a>) diff --git a/layouts/_shortcodes/file.html b/layouts/_shortcodes/file.html index 3df6a6cdb949..9e62391bc013 100644 --- a/layouts/_shortcodes/file.html +++ b/layouts/_shortcodes/file.html @@ -3,7 +3,7 @@ The body must be a fenced code block. The fence's info string is used as the syntax-highlighting language. Wrapping the body in a fence keeps - markdownlint and Vale happy (they treat fence content as code and skip + rumdl and Vale happy (they treat fence content as code and skip lint rules that would otherwise fire on `#` comment lines). Usage: diff --git a/layouts/_shortcodes/include.html b/layouts/_shortcodes/include.html index 8beb853f2b94..2faab47dd21f 100644 --- a/layouts/_shortcodes/include.html +++ b/layouts/_shortcodes/include.html @@ -1,3 +1,17 @@ +{{/* + include shortcode — inlines a reusable snippet from content/includes. + + Usage: + {{% include "root-errors.md" %}} + {{% include "compose/services.md" %}} + + The argument is a path relative to content/includes. The build fails with + a clear message if the target does not exist, so a renamed or deleted + snippet surfaces immediately instead of silently rendering nothing. +*/}} {{ $fileToInclude := .Get 0 }} {{ $filePath := printf "includes/%s" $fileToInclude }} -{{ readFile $filePath | safeHTML }} \ No newline at end of file +{{ if not (fileExists $filePath) }} + {{- errorf "include shortcode: file %q not found: %s" $filePath .Position -}} +{{ end }} +{{ readFile $filePath | safeHTML }} diff --git a/layouts/_shortcodes/interactive-diagram.html b/layouts/_shortcodes/interactive-diagram.html new file mode 100644 index 000000000000..cbf20dfd79d0 --- /dev/null +++ b/layouts/_shortcodes/interactive-diagram.html @@ -0,0 +1,102 @@ +{{- $src := .Get "src" -}} +{{- if not $src -}} + {{- errorf "interactive-diagram shortcode: missing src: %s" .Position -}} +{{- end -}} +{{- $filePath := path.Join .Page.File.Dir $src -}} +{{- if not (fileExists $filePath) -}} + {{- errorf "interactive-diagram shortcode: file %q not found: %s" $filePath .Position -}} +{{- end -}} +{{- $diagram := readFile $filePath | transform.Unmarshal -}} +{{- $type := $diagram.type | default "sequence" -}} +{{- $id := printf "interactive-diagram-%s-%d" .Page.File.UniqueID .Ordinal -}} +{{- .Page.Store.Set "interactive-diagram" true -}} +<figure + id="{{ $id }}" + class="interactive-diagram interactive-diagram--{{ $type }} not-prose my-6" + data-interactive-diagram + data-diagram-type="{{ $type }}" + aria-labelledby="{{ $id }}-title" +> + <figcaption class="interactive-diagram__header"> + <div class="interactive-diagram__header-copy"> + <p id="{{ $id }}-title" class="interactive-diagram__title"> + {{ $diagram.title }} + </p> + <p class="interactive-diagram__description">{{ $diagram.description }}</p> + </div> + </figcaption> + <div class="interactive-diagram__stage" data-diagram-stage></div> + {{- if eq $type "topology" }} + <div + class="interactive-diagram__topology-detail" + data-topology-detail + aria-live="polite" + aria-atomic="true" + > + <p class="interactive-diagram__topology-category" data-topology-category> + {{ $diagram.overview.category }} + </p> + <div class="interactive-diagram__topology-detail-copy"> + <p class="interactive-diagram__topology-title" data-topology-title> + {{ $diagram.overview.label }} + </p> + <p class="interactive-diagram__topology-body" data-topology-body> + {{ $diagram.overview.body }} + </p> + </div> + </div> + {{- else }} + <div + class="interactive-diagram__status" + aria-live="polite" + aria-atomic="true" + > + <div class="interactive-diagram__step-copy"> + <span class="interactive-diagram__step-number" data-step-number></span> + <div> + <p class="interactive-diagram__step-title" data-step-title></p> + <p class="interactive-diagram__step-body" data-step-body></p> + </div> + </div> + <p class="interactive-diagram__state" data-step-state></p> + </div> + <div class="interactive-diagram__controls" data-diagram-controls> + <button + type="button" + class="interactive-diagram__button" + data-step-previous + > + Previous + </button> + <div + class="interactive-diagram__progress" + data-step-progress + aria-label="Diagram steps" + ></div> + <button type="button" class="interactive-diagram__button" data-step-next> + Next + </button> + </div> + {{- end }} + <div class="interactive-diagram__fallback"> + {{- if eq $type "topology" }} + <ul> + {{- range $diagram.nodes }} + <li>{{ .label }}: {{ .details }}</li> + {{- end }} + {{- range $diagram.edges }} + <li>{{ .label }}: {{ .details }}</li> + {{- end }} + </ul> + {{- else }} + <ol> + {{- range $diagram.steps }} + <li>{{ .label }}: {{ .body }}</li> + {{- end }} + </ol> + {{- end }} + </div> + <script type="application/json" data-interactive-diagram-config> + {{- $diagram | jsonify | safeJS -}} + </script> +</figure> diff --git a/layouts/_shortcodes/interactive-diagram.markdown.md b/layouts/_shortcodes/interactive-diagram.markdown.md new file mode 100644 index 000000000000..c50b4317a993 --- /dev/null +++ b/layouts/_shortcodes/interactive-diagram.markdown.md @@ -0,0 +1,13 @@ +{{- $src := .Get "src" -}} +{{- $filePath := path.Join .Page.File.Dir $src -}} +{{- if not (fileExists $filePath) -}} + {{- errorf "interactive-diagram shortcode: file %q not found: %s" $filePath .Position -}} +{{- end -}} +{{- $diagram := readFile $filePath | transform.Unmarshal -}} +{{ $diagram.title }} + +{{ $diagram.description }} + +{{ range $index, $step := $diagram.steps -}} +{{ add $index 1 }}. {{ $step.label }}: {{ $step.body }} +{{ end -}} diff --git a/layouts/_shortcodes/recipe-list.html b/layouts/_shortcodes/recipe-list.html new file mode 100644 index 000000000000..7523a68bc76e --- /dev/null +++ b/layouts/_shortcodes/recipe-list.html @@ -0,0 +1,17 @@ +{{ $recipes := where .Page.RegularPages "Params.sidebar.group" (.Get "group") }} +<ul + class="not-prose mb-8 grid list-none grid-cols-1 gap-x-8 p-0 md:grid-cols-2" +> + {{ range $recipes }} + <li class="border-t border-gray-200 py-4 dark:border-gray-700"> + <a + class="font-semibold text-blue-600 hover:underline dark:text-blue-400" + href="{{ .RelPermalink }}" + >{{ .LinkTitle }}</a + > + <p class="mt-2 text-sm text-gray-600 dark:text-gray-400"> + {{ .Description }} + </p> + </li> + {{ end }} +</ul> diff --git a/layouts/_shortcodes/recipe-list.markdown.md b/layouts/_shortcodes/recipe-list.markdown.md new file mode 100644 index 000000000000..f61ffdf21914 --- /dev/null +++ b/layouts/_shortcodes/recipe-list.markdown.md @@ -0,0 +1,3 @@ +{{ range where .Page.RegularPages "Params.sidebar.group" (.Get "group") }} +- [{{ .LinkTitle }}]({{ .Permalink }}): {{ .Description }} +{{ end }} diff --git a/layouts/_shortcodes/restricted.html b/layouts/_shortcodes/restricted.html deleted file mode 100644 index 17a8a696741c..000000000000 --- a/layouts/_shortcodes/restricted.html +++ /dev/null @@ -1,9 +0,0 @@ -<div class="px-4 border-l-2 border-l-magenta-light dark:border-l-magenta-dark"> - <p class="not-prose flex gap-2 items-center text-magenta-light dark:text-magenta-dark"> - <span class="icon-svg pb-1"> - {{ partialCached "icon" "rocket-launch" "rocket-launch" }} - </span> - <strong>{{ .Get "title" | default (i18n "restricted") }}</strong> - </p> - {{ .InnerDeindent | safe.HTML }} -</div> diff --git a/layouts/_shortcodes/restricted.markdown.md b/layouts/_shortcodes/restricted.markdown.md deleted file mode 100644 index dd18b991b61f..000000000000 --- a/layouts/_shortcodes/restricted.markdown.md +++ /dev/null @@ -1,3 +0,0 @@ -> **{{ .Get "title" | default (i18n "restricted") }}** -> -> {{ .InnerDeindent }} diff --git a/layouts/_shortcodes/sandbox-auth.html b/layouts/_shortcodes/sandbox-auth.html new file mode 100644 index 000000000000..b19b2261b5f3 --- /dev/null +++ b/layouts/_shortcodes/sandbox-auth.html @@ -0,0 +1,96 @@ +<div + class="not-prose my-6 overflow-hidden rounded-lg border border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-900" + x-data="{ agent: 'codex', auth: 'codex-subscription' }" +> + <div + class="grid gap-4 border-b border-gray-200 bg-gray-50 p-4 sm:grid-cols-2 dark:border-gray-700 dark:bg-gray-800/50" + > + <label + class="grid gap-1.5 text-sm font-medium text-gray-700 dark:text-gray-200" + > + Agent + <select + class="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none dark:border-gray-600 dark:bg-gray-900 dark:text-gray-100 dark:focus:border-blue-400" + x-model="agent" + @change="auth = { codex: 'codex-subscription', claude: 'claude-subscription', opencode: 'opencode-anthropic' }[$event.target.value]" + > + <option value="codex">Codex</option> + <option value="claude">Claude Code</option> + <option value="opencode">OpenCode</option> + </select> + </label> + + <label + class="grid gap-1.5 text-sm font-medium text-gray-700 dark:text-gray-200" + > + Authentication + <select + class="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none dark:border-gray-600 dark:bg-gray-900 dark:text-gray-100 dark:focus:border-blue-400" + x-model="auth" + x-show="agent === 'codex'" + > + <option value="codex-subscription">ChatGPT subscription</option> + <option value="codex-openai">OpenAI API key</option> + </select> + <select + class="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none dark:border-gray-600 dark:bg-gray-900 dark:text-gray-100 dark:focus:border-blue-400" + x-model="auth" + x-cloak + x-show="agent === 'claude'" + > + <option value="claude-subscription">Claude subscription</option> + <option value="claude-anthropic">Anthropic API key</option> + </select> + <select + class="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none dark:border-gray-600 dark:bg-gray-900 dark:text-gray-100 dark:focus:border-blue-400" + x-model="auth" + x-cloak + x-show="agent === 'opencode'" + > + <option value="opencode-anthropic">Anthropic API key</option> + <option value="opencode-openai">OpenAI API key</option> + <option value="opencode-openrouter">OpenRouter API key</option> + <option value="opencode-google">Google API key</option> + </select> + </label> + </div> + + <div class="p-4 sm:p-5" aria-live="polite"> + <div x-show="auth === 'codex-subscription'"> + <p class="m-0 text-gray-700 dark:text-gray-200"> + No secret configuration is needed. When you run Codex, <code>sbx</code> + opens the OpenAI sign-in flow on your host before creating the sandbox. + </p> + </div> + <div x-cloak x-show="auth === 'claude-subscription'"> + <p class="m-0 text-gray-700 dark:text-gray-200"> + No secret configuration is needed. After Claude Code starts in the + sandbox, enter <code>/login</code> and sign in with your Claude account. + </p> + </div> + + {{ range $choice := slice + (dict "id" "codex-openai" "service" "openai" "provider" "OpenAI") + (dict "id" "claude-anthropic" "service" "anthropic" "provider" "Anthropic") + (dict "id" "opencode-anthropic" "service" "anthropic" "provider" "Anthropic") + (dict "id" "opencode-openai" "service" "openai" "provider" "OpenAI") + (dict "id" "opencode-openrouter" "service" "openrouter" "provider" "OpenRouter") + (dict "id" "opencode-google" "service" "google" "provider" "Google") + }} + <div x-cloak x-show="auth === '{{ $choice.id }}'"> + <p class="mt-0 mb-3 text-gray-700 dark:text-gray-200"> + Store your {{ $choice.provider }} API key in the host credential + store. The command prompts for the key without displaying it: + </p> + <div + class="syntax-light dark:syntax-dark overflow-hidden rounded-md border border-gray-200 dark:border-gray-700" + > + {{ transform.Highlight + (printf "$ sbx secret set %s" $choice.service) + "console" "" + }} + </div> + </div> + {{ end }} + </div> +</div> diff --git a/layouts/_shortcodes/sandbox-auth.markdown.md b/layouts/_shortcodes/sandbox-auth.markdown.md new file mode 100644 index 000000000000..90f29dfc122a --- /dev/null +++ b/layouts/_shortcodes/sandbox-auth.markdown.md @@ -0,0 +1,10 @@ +Choose the authentication method for your agent: + +- Codex with a ChatGPT subscription: No secret configuration is needed. `sbx` + opens the OpenAI sign-in flow on your host before creating the sandbox. +- Claude Code with a Claude subscription: No secret configuration is needed. + After Claude Code starts, enter `/login` inside the sandbox. +- Codex with an OpenAI API key: Run `sbx secret set openai`. +- Claude Code with an Anthropic API key: Run `sbx secret set anthropic`. +- OpenCode with an API key: Run `sbx secret set` with the service name + `anthropic`, `openai`, `openrouter`, or `google`. diff --git a/layouts/_shortcodes/setting-metadata.html b/layouts/_shortcodes/setting-metadata.html new file mode 100644 index 000000000000..d80bb01bd1a2 --- /dev/null +++ b/layouts/_shortcodes/setting-metadata.html @@ -0,0 +1,21 @@ +{{ if or (not (isset .Params "type")) (not (isset .Params "default")) }} + {{ errorf "setting-metadata requires type and default: %s" .Position }} +{{ end }} +<dl + class="not-prose my-4 grid grid-cols-2 gap-x-6 gap-y-3 rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm shadow-sm dark:border-gray-700 dark:bg-gray-900" +> + <div class="min-w-0"> + <dt class="text-gray-600 dark:text-gray-400">Type</dt> + <dd class="mt-1 wrap-anywhere">{{ .Get "type" }}</dd> + </div> + <div class="min-w-0"> + <dt class="text-gray-600 dark:text-gray-400">Default</dt> + <dd class="mt-1 wrap-anywhere">{{ .Get "default" }}</dd> + </div> + {{ with .Get "env" }} + <div class="col-span-2 min-w-0"> + <dt class="text-gray-600 dark:text-gray-400">Environment variable</dt> + <dd class="mt-1 wrap-anywhere"><code>{{ . }}</code></dd> + </div> + {{ end }} +</dl> diff --git a/layouts/_shortcodes/setting-metadata.markdown.md b/layouts/_shortcodes/setting-metadata.markdown.md new file mode 100644 index 000000000000..7c28b2693c68 --- /dev/null +++ b/layouts/_shortcodes/setting-metadata.markdown.md @@ -0,0 +1,7 @@ +{{ if or (not (isset .Params "type")) (not (isset .Params "default")) }} + {{ errorf "setting-metadata requires type and default: %s" .Position }} +{{ end }} +- Type: {{ .Get "type" }} +- Default: {{ .Get "default" }} +{{ with .Get "env" }}- Environment variable: `{{ . }}` +{{ end }} diff --git a/layouts/_shortcodes/summary-bar.html b/layouts/_shortcodes/summary-bar.html index a849ca7c305b..aa434c1dd17c 100644 --- a/layouts/_shortcodes/summary-bar.html +++ b/layouts/_shortcodes/summary-bar.html @@ -13,6 +13,7 @@ "Docker Hardened Images Enterprise" "/icons/dhi.svg" "Docker Hardened Images Select or Enterprise" "/icons/dhi.svg" "Docker Offload" "cloud" + "AI Governance" "shield-check" }} {{ $availabilityIcons := dict "Experimental" "beaker" @@ -22,12 +23,13 @@ "Retired" "archive-box" }} {{ $requiresIcon := "arrow-down-circle" }} - {{ $forIcon := "shield-check" }} + {{ $forIcons := dict + "Administrators" "shield-check" + "Individuals" "user-circle" + }} - <div - class="not-prose summary-bar" - > + <div class="not-prose summary-bar"> {{ with $feature.subscription }} <div class="flex flex-wrap gap-1"> <span class="font-bold">Subscription:</span> @@ -74,9 +76,9 @@ <div class="flex flex-wrap gap-1"> <span class="font-bold">For:</span> <span>{{ . }}</span> - {{ if eq . "Administrators" }} + {{ with index $forIcons . }} <span class="icon-svg icon-sm"> - {{ partialCached "icon" $forIcon $forIcon }} + {{ partialCached "icon" . . }} </span> {{ end }} </div> diff --git a/layouts/_shortcodes/whats-new.markdown.md b/layouts/_shortcodes/whats-new.markdown.md new file mode 100644 index 000000000000..9689ff97dace --- /dev/null +++ b/layouts/_shortcodes/whats-new.markdown.md @@ -0,0 +1,9 @@ +{{- $data := index hugo.Data "whats-new" -}} +{{- with $data.items }} + +## What's new + +{{ range . }} +{{ printf "- [%s: %s](%s): %s (%s)\n" .product .title .url .description (.published | time.Format "Jan 2, 2006") -}} +{{ end }} +{{- end }} diff --git a/layouts/api-docs.html b/layouts/api-docs.html new file mode 100644 index 000000000000..1dd811efe53e --- /dev/null +++ b/layouts/api-docs.html @@ -0,0 +1,403 @@ +{{ define "head-extra" }} + {{ $style := resources.Get "api-reference/reference.css" | fingerprint }} + <link rel="stylesheet" href="{{ $style.RelPermalink }}" /> + {{ $script := resources.Get "api-reference/reference.js" | fingerprint }} + <script src="{{ $script.RelPermalink }}" defer></script> +{{ end }} +{{ define "left" }} + {{ partial "sidebar/mainnav.html" . }} + {{ if eq .Params.view "catalog" }} + {{ partial "sidebar/sections.html" . }} + {{ else }} + {{ partial "api-reference/navigation.html" . }} + {{ end }} +{{ end }} +{{ define "main" }} + <article class="api-reference" data-api-view="{{ .Params.view }}"> + {{ $data := index hugo.Data "api-reference" }} + {{ $api := dict }}{{ range $data.apis }} + {{ if eq .id $.Params.apiID }}{{ $api = . }}{{ end }} + {{ end }} + {{ if eq .Params.view "catalog" }} + <p class="api-eyebrow">Developer reference</p> + <h1>Docker APIs</h1> + <p class="api-lead"> + Build with Docker, from your local daemon to hosted services. + </p> + <p> + Choose an API to find connection guidance, operations, and data models. + </p> + <div class="api-cards"> + {{ range $data.apis }} + <a class="api-card" href="{{ .url }}" + ><span class="api-label" + >{{ if eq .connection "unix" }} + Your daemon + {{ else }} + Hosted service + {{ end }}</span + > + <h2>{{ .title }}{{ if .experimental }}· Experimental{{ end }}</h2> + <p>API {{ .version }} · {{ len .operations }} operations</p> + <span>Explore reference →</span></a + > + {{ end }} + {{ range $data.legacyAPIs }} + <a class="api-card" href="{{ .url }}"> + <span class="api-label" + >{{ if eq .connection "unix" }} + Your daemon + {{ else }} + Hosted service + {{ end }}</span + > + <h2>{{ .title }}{{ if .experimental }}· Experimental{{ end }}</h2> + <p>{{ .description }}</p> + <span>Explore reference →</span> + </a> + {{ end }} + </div> + {{ else }} + <nav class="api-crumbs" aria-label="API breadcrumb"> + <a href="/reference/api/">APIs</a> / + <a href="{{ $api.url }}">{{ $api.title }}</a> / + <span>API {{ $api.version }}</span> + </nav> + {{ if $api.experimental }} + <p class="api-label">Experimental</p> + {{ if eq .Params.view "overview" }} + <p> + This API is experimental. Features, interfaces, and behavior may + change. + </p> + {{ end }} + {{ end }} + <div class="api-tools"> + <label + >API version + <select data-api-version> + {{ range $data.apis }} + {{ if eq .product $api.product }} + <option + value="{{ .url }}" + {{ if eq .id $api.id }}selected{{ end }} + > + {{ .version }} + </option> + {{ end }} + {{ end }} + </select></label + ><a href="{{ ref . $api.manual }}">Product manual</a + ><a href="{{ $api.sourceURL }}">Download OpenAPI specification</a + ><a href="{{ partial "utils/markdown-url.html" . }}">Markdown</a> + </div> + <meta + data-pagefind-meta="title:{{ .Title }} — {{ $api.title }} API {{ $api.version }}" + /> + {{ if eq .Params.view "overview" }} + <p class="api-eyebrow"> + {{ if eq $api.connection "unix" }} + User-operated API + {{ else }} + Hosted API + {{ end }} + </p> + <h1>{{ $api.title }} API</h1> + <p class="api-lead"> + API {{ $api.version }} · {{ len $api.operations }} operations · + {{ len $api.schemas }} named schemas + </p> + <section class="api-overview" aria-labelledby="api-overview-title"> + <h2 id="api-overview-title">Overview</h2> + <div class="prose dark:prose-invert"> + {{ partial "api-reference/description.html" (dict "text" $api.description "api" $api) | markdownify }} + </div> + </section> + <section class="api-connection" id="authentication"> + <h2> + {{ if eq $api.connection "unix" }} + Connecting to + {{ $api.title }} + {{ else }} + Connecting to the {{ $api.title }} API + {{ end }} + </h2> + {{ range $name, $scheme := $api.securitySchemes }} + {{ with $scheme.description }} + <h3>{{ index $scheme "x-displayName" | default $name }}</h3> + <div class="prose dark:prose-invert">{{ . | markdownify }}</div> + {{ end }} + {{ end }} + {{ if eq $api.connection "unix" }} + <pre><code>curl --unix-socket /var/run/docker.sock http://localhost/v{{ $api.version }}/version</code></pre> + {{ else }} + {{ range $api.servers }}<code>{{ .url }}</code>{{ end }} + {{ end }}{{ range $api.guides }} + {{ $guide := site.GetPage (index (split . "#") 0) }} + <p><a href="{{ ref $ . }}">{{ $guide.Title }}</a></p> + {{ end }} + </section> + <div class="api-overview"> + {{ $overviewTags := partial "api-reference/overview-tags.html" $api }} + {{ range $api.tags }} + {{ if not (in $overviewTags .) }} + <span id="tag-{{ .name | urlize }}"></span> + {{ end }} + {{ end }} + {{ range $overviewTags }} + <section id="tag-{{ .name | urlize }}"> + <h2>{{ .summary }}</h2> + <div class="prose dark:prose-invert"> + {{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }} + </div> + </section> + {{ end }} + </div> + <h2>Operations</h2> + <label class="api-filter-label" + >Filter operations + <input + type="search" + placeholder="Method, path, or operation name" + data-api-filter + /></label> + <div class="api-operation-list"> + {{ range $api.operations }} + <a class="api-operation-row" href="{{ .url }}" data-api-filter-item + ><span class="api-method" data-method="{{ .method }}" + >{{ .method }}</span + ><code>{{ partial "api-reference/path.html" .path }}</code + ><span>{{ .summary }}</span></a + > + {{ end }} + </div> + <h2 id="schemas">Schemas</h2> + <ul class="api-schema-links" aria-label="Schemas"> + {{ range $api.schemas }} + <li> + <a href="{{ .url }}"><code>{{ .name }}</code></a> + </li> + {{ end }} + </ul> + {{ else if eq .Params.view "operation" }} + {{ range $api.operations }} + {{ if eq .id $.Params.operationID }} + <h1>{{ .summary }}</h1> + <div class="api-signature"> + <span class="api-method" data-method="{{ .method }}" + >{{ .method }}</span + ><code>{{ partial "api-reference/path.html" .path }}</code + >{{ if .deprecated }} + <span>Deprecated</span> + {{ end }} + </div> + <div class="api-operation-grid"> + <div class="api-reading"> + <div class="api-description prose dark:prose-invert"> + {{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }} + </div> + <h2>Connection and access</h2> + <p> + <a href="{{ $api.url }}#authentication" + >API connection and authentication guidance</a + > + </p> + {{ if and (eq $api.product "engine") (where .parameters "name" "X-Registry-Auth") }} + <p> + <code>X-Registry-Auth</code> delegates registry credentials + and does not authenticate the daemon caller. + </p> + {{ end }} + {{ range .servers }} + <p> + <code>{{ .url }}</code>{{ with .description }} + — + {{ . }} + {{ end }} + </p> + {{ end }} + {{ range .servers }} + {{ range $name, $variable := .variables }} + <p><code>{{ $name }}</code>: {{ $variable.description }}</p> + {{ end }} + {{ end }} + {{ if not .security }} + <p> + No HTTP authentication requirement is declared for this + operation. Transport access controls can still apply. + </p> + {{ else }} + <p> + Use one of these alternatives. Requirements within an + alternative apply together. + </p> + <ul> + {{ range .security }} + <li> + {{ $first := true }}{{ range $name, $scopes := . }} + {{ if not $first }} + AND + {{ end }}{{ $first = false }}<code>{{ $name }}</code>{{ with $scopes }} + ({{ delimit . ", " }}) + {{ end }} + {{ end }}{{ if $first }}Anonymous access{{ end }} + </li> + {{ end }} + </ul> + {{ end }} + {{ with index .raw "x-websocket" }} + {{ partial "api-reference/websocket.html" (dict "socket" . "api" $api) }} + {{ end }} + <h2>Parameters</h2> + {{ if not .parameters }} + <p>No parameters are declared.</p> + {{ end }} + {{ range .parameters }} + <section class="api-field" data-api-parameter="{{ .name }}"> + <h3> + <code>{{ .name }}</code> + <small>{{ .in }}</small> + {{ if .required }} + <small class="api-required">Required</small> + {{ end }} + </h3> + <div class="prose dark:prose-invert"> + {{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }} + </div> + {{ if isset . "schema" }} + {{ partial "api-reference/schema.html" (dict "schema" .schema "api" $api "depth" 0) }} + {{ end }}{{ with .content }} + <pre><code>{{ . | jsonify (dict "indent" " ") }}</code></pre> + {{ end }}{{ with .style }} + <p>Serialization: <code>{{ . }}</code></p> + {{ end }} + </section> + {{ end }} + <h2>Request and responses</h2> + <label + >Media type + <select data-api-media-select> + <option value="">All media types</option> + {{ $media := slice }}{{ range .variants }} + {{ if .media }} + {{ $media = $media | append .media }} + {{ end }} + {{ end }}{{ range ($media | uniq | sort) }} + <option value="{{ . }}">{{ . }}</option> + {{ end }} + </select></label + > + {{ range $i, $v := .variants }} + <section + class="api-variant" + data-api-variant="{{ $v.pointer }}" + data-api-media="{{ $v.media }}" + > + <h3> + <span>{{ $v.direction | humanize }}</span> + {{ with $v.status }} + <code class="api-status">{{ . }}</code> + {{ end }} + </h3> + <div class="prose dark:prose-invert"> + {{ partial "api-reference/description.html" (dict "text" $v.description "api" $api) | markdownify }} + </div> + {{ if $v.media }} + <p class="api-media"><code>{{ $v.media }}</code></p> + {{ else }} + <p>No response content is declared.</p> + {{ end }} + {{ with $v.headers }} + <h4>Headers</h4> + {{ range $name,$header := . }} + <div class="api-field"> + <code>{{ $name }}</code> + <p>{{ $header.description }}</p> + <pre><code>{{ $header | jsonify (dict "indent" " ") }}</code></pre> + </div> + {{ end }} + {{ end }} + {{ if isset $v "schema" }} + {{ partial "api-reference/schema.html" (dict "schema" $v.schema "api" $api "depth" 0) }} + {{ end }} + {{ if isset $v "itemSchema" }} + <h4>Stream item</h4> + {{ partial "api-reference/schema.html" (dict "schema" $v.itemSchema "api" $api "depth" 0) }} + {{ end }} + {{ range $key := slice "encoding" "itemEncoding" "prefixEncoding" }} + {{ with index $v $key }} + <details> + <summary> + {{ $key }}: content types and part headers + </summary> + <pre><code>{{ . | jsonify (dict "indent" " ") }}</code></pre> + </details> + {{ end }} + {{ end }} + {{ if $v.examples }} + <div data-api-examples> + {{ if gt (len $v.examples) 1 }} + <label + >Example + <select data-api-example-select> + {{ range $j,$ex := $v.examples }} + <option value="{{ $j }}">{{ $ex.name }}</option> + {{ end }} + </select></label + > + {{ end }}{{ range $j,$ex := $v.examples }} + <div data-api-example="{{ $j }}"> + <h4>{{ $ex.name }}</h4> + <pre><code>{{ $ex.text }}</code></pre> + </div> + {{ end }} + </div> + {{ end }} + </section> + {{ end }} + <h2>Referenced schemas</h2> + {{ range .references }} + {{ if .url }} + <p><a href="{{ .url }}">{{ .ref }}</a></p> + {{ end }} + {{ end }} + <details> + <summary>Complete operation contract</summary> + <pre><code>{{ .raw | jsonify (dict "indent" " ") }}</code></pre> + </details> + </div> + <aside class="api-request"> + <div class="api-request-heading"> + <h2> + {{ if .curl }} + Example request + {{ else }} + WebSocket client + {{ end }} + </h2> + {{ if .curl }}<span>Shell</span>{{ end }} + </div> + {{ if .curl }} + <p> + Replace placeholders and supply the required credentials or + request body. + </p> + <pre><code data-api-copy-source>{{ .curl }}</code></pre> + <button type="button" data-api-copy>Copy request</button> + {{ end }}{{ range .curlNotes }}<p>{{ . }}</p>{{ end }} + </aside> + </div> + {{ end }} + {{ end }} + {{ else if eq .Params.view "schema" }} + {{ range $api.schemas }} + {{ if eq .name $.Params.schemaName }} + <p class="api-eyebrow">Schema</p> + <h1>{{ .name }}</h1> + {{ partial "api-reference/schema.html" (dict "schema" .schema "api" $api "depth" 0) }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} + </article> +{{ end }} diff --git a/layouts/api-docs.markdown.md b/layouts/api-docs.markdown.md new file mode 100644 index 000000000000..eba2f14ba3ee --- /dev/null +++ b/layouts/api-docs.markdown.md @@ -0,0 +1,192 @@ +{{- $data := index hugo.Data "api-reference" -}} +{{- $api := dict -}}{{- range $data.apis -}}{{- if eq .id $.Params.apiID -}}{{- $api = . -}}{{- end -}}{{- end -}} +# {{ .Title }} + +{{ if eq .Params.view "catalog" }} +Choose a Docker HTTP API: +{{ range $data.apis }} +- [{{ .title }} API {{ .version }}]({{ .url }}): {{ len .operations }} operations; {{ .connection }} connection +{{ end }} +{{ range $data.legacyAPIs }} +- [{{ .title }}]({{ .url }}): {{ .description }} +{{ end }} +{{ else }} +[API catalog](/reference/api/) · [{{ $api.title }} overview]({{ $api.url }}) · [Product manual]({{ ref . $api.manual }}) · [OpenAPI specification]({{ $api.sourceURL }}) + +API version: {{ $api.version }} + +{{ if $api.experimental }} +> This API is experimental. Features, interfaces, +> and behavior may change. +{{ end }} + +{{ if eq .Params.view "overview" }} +## Overview + +{{ partial "api-reference/description.html" (dict "text" $api.description "api" $api) }} +## {{ if eq $api.connection "unix" }}Connecting to {{ $api.title }}{{ else }}Connecting to the {{ $api.title }} API{{ end }} + +{{ range $name, $scheme := $api.securitySchemes }}{{ with $scheme.description }} +### {{ index $scheme "x-displayName" | default $name }} + +{{ . }} +{{ end }}{{ end }} +{{ range $api.servers }} +Server: `{{ .url }}` +{{ range $name,$variable := .variables }} +`{{ $name }}`: {{ $variable.description }} +{{ end }}{{ end }} +{{ if eq $api.connection "unix" }} +```console +curl --unix-socket /var/run/docker.sock http://localhost/v{{ $api.version }}/version +``` +{{ end }} +{{ range $api.guides }} +{{ $guide := site.GetPage (index (split . "#") 0) }} +- [{{ $guide.Title }}]({{ ref $ . }}) +{{ end }} + +{{ range (partial "api-reference/overview-tags.html" $api) }} +## {{ .summary }} + +{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} +{{ end }} +## Operations +{{ range $api.operations }} +- [{{ .method }} {{ .path }}]({{ .url }}): {{ .summary }} +{{ end }} +## Schemas +{{ range $api.schemas }} +- [{{ .name }}]({{ .url }}) +{{ end }} +{{ else if eq .Params.view "operation" }} +{{ range $api.operations }}{{ if eq .id $.Params.operationID }} +`{{ .method }} {{ .path }}` + +{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} +{{ if .deprecated }} +Deprecated operation. +{{ end }} +## Connection and access + +[API connection and authentication guidance]({{ $api.url }}#authentication) +{{ if and (eq $api.product "engine") (where .parameters "name" "X-Registry-Auth") }} +`X-Registry-Auth` delegates registry credentials and does not authenticate the daemon caller. +{{ end }} +{{ range .servers }} +Server: `{{ .url }}` +{{ range $name,$variable := .variables }} +`{{ $name }}`: {{ $variable.description }} +{{ end }}{{ end }} +Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. + +```json +{{ .security | jsonify (dict "indent" " ") }} +``` +{{ if .curl }} +## Example request + +Replace placeholders and provide the required credentials or request body. + +```console +{{ .curl }} +``` +{{ end }} +{{ range .curlNotes }} +{{ . }} +{{ end }} +{{ with index .raw "x-websocket" }} +## WebSocket session + +Subprotocol: `{{ .subprotocol }}` + +{{ .authentication }} + +{{ .browser }} + +{{ .reconnect }} + +{{ .terminalFrame }} + +```json +{{ . | jsonify (dict "indent" " ") }} +``` +{{ end }} +## Parameters +{{ range .parameters }} +### {{ .name }} + +Location: {{ .in }}. Required: {{ if .required }}yes{{ else }}no{{ end }}. + +{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} + +```json +{{ . | jsonify (dict "indent" " ") }} +``` +{{ end }} +## Request and responses +{{ range .variants }} +### {{ .direction }} {{ .status }} {{ .media }} + +{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} +{{ if not .media }} +No response content is declared. +{{ end }} +{{ if isset . "schema" }} +Schema: + +```json +{{ .schema | jsonify (dict "indent" " ") }} +``` +{{ end }} +{{ if isset . "itemSchema" }} +Stream item schema: + +```json +{{ .itemSchema | jsonify (dict "indent" " ") }} +``` +{{ end }} +{{ with .headers }} +Headers: + +```json +{{ . | jsonify (dict "indent" " ") }} +``` +{{ end }} +{{ $variant := . }} +{{ range $key := slice "encoding" "itemEncoding" "prefixEncoding" }} +{{ with index $variant $key }} +{{ $key }}: + +```json +{{ . | jsonify (dict "indent" " ") }} +``` +{{ end }}{{ end }} +{{ range .examples }} +{{ .name }}: +```{{ .language }} +{{ .text }} +``` +{{ end }} +{{ end }} +## Complete operation contract + +```json +{{ .raw | jsonify (dict "indent" " ") }} +``` + +## Referenced schemas +{{ range .references }} +- {{ if .url }}[{{ .ref }}]({{ .url }}){{ else }}`{{ .ref }}`{{ end }} +{{ end }} +{{ end }}{{ end }} +{{ else if eq .Params.view "schema" }} +{{ range $api.schemas }}{{ if eq .name $.Params.schemaName }} +Schema constraints and annotations: + +```json +{{ .schema | jsonify (dict "indent" " ") }} +``` +{{ end }}{{ end }} +{{ end }} +{{ end }} diff --git a/layouts/api-reference.html b/layouts/api-reference.html deleted file mode 100644 index 5767de1595f2..000000000000 --- a/layouts/api-reference.html +++ /dev/null @@ -1,700 +0,0 @@ -{{/* Wide-mode API reference layout. - - Reads the colocated *.yaml Page Resource, unmarshals it into a plain Hugo - map with transform.Unmarshal, and renders the OpenAPI 3 spec inline using - Docker docs styling. Overrides baseof's "main" block so the article spans - the full available width; the built-in right-rail TOC is replaced with a - custom endpoint navigator (partials/api-ref/nav.html) sticky-pinned to - the viewport. - - $ref nodes are resolved on the fly through partials/api-ref/resolve.html; - no oapi-codegen or third-party JS runtime is involved. -*/}} - -{{ define "main" }} - {{- $specRes := .Resources.GetMatch "*.yaml" -}} - {{- if not $specRes -}} - {{- errorf "api-reference: no .yaml resource found alongside %s" .File.Path -}} - {{- end -}} - {{- $api := $specRes | transform.Unmarshal -}} - - - <div class="flex w-full min-w-0 gap-8"> - <div class="min-w-0 flex-1"> - {{ partial "breadcrumbs.html" . }} - <h1 data-pagefind-weight="10" class="mb-2 text-3xl font-bold"> - {{ .Title | safeHTML }} - </h1> - {{ with .Description }} - <p class="text-gray-600 dark:text-gray-400">{{ . }}</p> - {{ end }} - {{ template "api-ref-meta" (dict "api" $api "spec" $specRes) }} - {{ partialCached "md-dropdown.html" "-" "-" }} - - {{ template "api-ref-overview" $api }} - {{ template "api-ref-auth" $api }} - {{ template "api-ref-tags" $api }} - {{ template "api-ref-schemas" $api }} - </div> - - <aside class="hidden w-56 flex-none lg:block"> - <nav - class="sticky top-20 max-h-[calc(100vh-6rem)] overflow-y-auto text-sm" - > - {{ partial "api-ref/nav.html" $api }} - </nav> - </aside> - </div> -{{ end }} - -{{/* ── Meta strip: version, base URL, download link ──────────────────────── */}} -{{ define "api-ref-meta" }} - {{- $api := .api -}} - {{- $spec := .spec -}} - <div class="mt-4 flex flex-wrap items-center gap-x-6 gap-y-2 text-sm"> - {{- with $api.info }} - {{- with .version }} - <div> - <span class="font-medium text-gray-500 dark:text-gray-400" - >Version</span - > - <code - class="ml-1 rounded bg-gray-100 px-1.5 py-0.5 text-xs dark:bg-gray-800" - >{{ . }}</code - > - </div> - {{- end }} - {{- end }} - {{- range $api.servers }} - <div> - <span class="font-medium text-gray-500 dark:text-gray-400" - >Base URL</span - > - <code - class="ml-1 rounded bg-gray-100 px-1.5 py-0.5 text-xs text-blue-600 dark:bg-gray-800 dark:text-blue-400" - >{{ .url }}</code - > - </div> - {{- end }} - <a - href="{{ $spec.Permalink }}" - class="ml-auto text-blue-600 hover:underline dark:text-blue-400" - >Download OpenAPI specification</a - > - </div> -{{ end }} - -{{/* ── Overview ─────────────────────────────────────────────────────────── */}} -{{ define "api-ref-overview" }} - {{- $api := . -}} - {{- with $api.info }} - {{- with .description }} - <section class="mb-10"> - <div class="prose dark:prose-invert max-w-none"> - {{ . | markdownify }} - </div> - </section> - {{- end }} - {{- end }} -{{ end }} - -{{/* ── Authentication ───────────────────────────────────────────────────── */}} -{{ define "api-ref-auth" }} - {{- $api := . -}} - {{- with $api.components }} - {{- with .securitySchemes }} - <section class="mb-12"> - <h2 - id="authentication" - class="mb-4 scroll-mt-24 text-2xl font-semibold" - > - Authentication - </h2> - {{- range $name, $scheme := . }} - <div class="mb-4 flex flex-wrap items-center gap-x-4 gap-y-1 text-sm"> - <code - class="rounded bg-gray-100 px-1.5 py-0.5 text-xs dark:bg-gray-800" - >{{ $name }}</code - > - {{- with $scheme.type }} - <span class="text-gray-500 dark:text-gray-400" - >type: <code class="text-xs">{{ . }}</code></span - > - {{- end }} - {{- with $scheme.scheme }} - <span class="text-gray-500 dark:text-gray-400" - >scheme: <code class="text-xs">{{ . }}</code></span - > - {{- end }} - {{- with $scheme.bearerFormat }} - <span class="text-gray-500 dark:text-gray-400" - >bearer format: <code class="text-xs">{{ . }}</code></span - > - {{- end }} - </div> - {{- with $scheme.description }} - <div class="prose dark:prose-invert max-w-none"> - {{ . | markdownify }} - </div> - {{- end }} - {{- end }} - </section> - {{- end }} - {{- end }} -{{ end }} - -{{/* ── Endpoints grouped by tag ─────────────────────────────────────────── */}} -{{ define "api-ref-tags" }} - {{- $api := . -}} - {{- $paths := $api.paths -}} - {{- $methods := slice "get" "post" "put" "patch" "delete" -}} - {{- range $api.tags }} - {{- $tagName := .name -}} - <section class="mb-14"> - <h2 - id="tag-{{ $tagName | urlize }}" - class="mb-1 scroll-mt-24 text-2xl font-semibold" - > - {{ $tagName | title }} - </h2> - {{- with .description }} - <p class="mb-6 text-sm text-gray-500 dark:text-gray-400">{{ . }}</p> - {{- end }} - - {{- range $path, $item := $paths }} - {{/* Resolve shared (path-level) parameters once. */}} - {{- $sharedParams := slice -}} - {{- with index $item "parameters" -}} - {{- range . -}} - {{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $sharedParams = $sharedParams | append $p -}} - {{- end -}} - {{- end -}} - - {{- range $methods -}} - {{- $method := . -}} - {{- with index $item $method -}} - {{- $op := . -}} - {{- if in $op.tags $tagName -}} - {{ template "api-ref-operation" (dict - "api" $api - "op" $op - "method" $method - "path" $path - "sharedParams" $sharedParams - ) - }} - {{- end -}} - {{- end -}} - {{- end -}} - {{- end }} - </section> - {{- end }} -{{ end }} - -{{/* ── Single operation card ────────────────────────────────────────────── */}} -{{ define "api-ref-operation" }} - {{- $api := .api -}} - {{- $op := .op -}} - {{- $method := .method -}} - {{- $path := .path -}} - {{- $sharedParams := .sharedParams -}} - - {{- $methodColors := dict - "get" "bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300" - "post" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300" - "put" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300" - "patch" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300" - "delete" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" - -}} - - {{- $anchor := "" -}} - {{- with $op.operationId -}} - {{- $anchor = printf "operation-%s" . -}} - {{- end -}} - - {{- $curl := partial "api-ref/curl.html" (dict - "api" $api - "op" $op - "method" $method - "path" $path - "sharedParams" $sharedParams - ) - -}} - - - <div - {{ with $anchor }}id="{{ . }}"{{ end }} - class="mb-8 scroll-mt-24 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700" - > - <div - class="flex flex-wrap items-center gap-3 border-b border-gray-200 bg-gray-50 px-4 py-3 dark:border-gray-700 dark:bg-gray-900" - > - <span - class="{{ index $methodColors $method }} inline-block rounded px-2 py-0.5 font-mono text-xs font-bold uppercase" - >{{ upper $method }}</span - > - <code class="font-mono text-sm">{{ $path }}</code> - <div class="ml-auto flex items-center gap-3"> - {{- with $op.summary }} - <span class="text-sm font-medium text-gray-700 dark:text-gray-300" - >{{ . }}</span - > - {{- end }} - <button - x-data="{ copied: false }" - @click="navigator.clipboard.writeText({{ $curl | jsonify }}).then(() => { copied = true; setTimeout(() => copied = false, 2000) })" - :title="copied ? 'Copied!' : 'Copy as cURL'" - class="inline-flex cursor-pointer items-center gap-1 rounded border border-gray-200 bg-white px-2 py-1 text-xs font-medium text-gray-700 transition-colors hover:bg-gray-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700" - > - <span class="icon-svg icon-sm" x-show="!copied" x-cloak> - {{ partialCached "icon" "document-duplicate" "document-duplicate" }} - </span> - <span - class="icon-svg icon-sm text-green-600 dark:text-green-400" - x-show="copied" - x-cloak - > - {{ partialCached "icon" "check-circle" "check-circle" }} - </span> - <span x-text="copied ? 'Copied' : 'cURL'"></span> - </button> - </div> - </div> - - <div class="p-5"> - {{- with $op.description }} - <div class="prose dark:prose-invert prose-sm mb-5 max-w-none"> - {{ . | markdownify }} - </div> - {{- end }} - - {{ template "api-ref-params" (dict - "api" $api - "op" $op - "sharedParams" $sharedParams - ) - }} - - {{ template "api-ref-body" (dict "api" $api "op" $op) }} - - {{ template "api-ref-responses" (dict "api" $api "op" $op) }} - </div> - </div> -{{ end }} - -{{/* ── Parameters table (path + operation; in: path/query/header) ───────── */}} -{{ define "api-ref-params" }} - {{- $api := .api -}} - {{- $op := .op -}} - {{- $params := .sharedParams -}} - {{- with index $op "parameters" -}} - {{- range . -}} - {{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $params = $params | append $p -}} - {{- end -}} - {{- end -}} - - {{- if $params }} - <div class="mb-5"> - <h4 - class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400" - > - Parameters - </h4> - <table class="w-full border-collapse text-sm"> - <thead> - <tr class="border-b border-gray-200 dark:border-gray-700"> - <th - class="w-36 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Name - </th> - <th - class="w-16 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - In - </th> - <th - class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Type - </th> - <th - class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Required - </th> - <th - class="py-1.5 text-left font-medium text-gray-700 dark:text-gray-300" - > - Description - </th> - </tr> - </thead> - <tbody> - {{- range $params }} - <tr - class="border-b border-gray-100 last:border-0 dark:border-gray-800" - > - <td class="py-1.5 pr-4 align-top"> - <code class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800" - >{{ .name }}</code - > - </td> - <td - class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400" - > - {{ .in }} - </td> - <td - class="py-1.5 pr-4 align-top font-mono text-xs text-gray-500 dark:text-gray-400" - > - {{ template "api-ref-type" (dict "api" $api "schema" .schema) }} - </td> - <td - class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400" - > - {{ if .required }}yes{{ else }}no{{ end }} - </td> - <td - class="py-1.5 align-top text-sm text-gray-600 dark:text-gray-400" - > - {{ with .description }}{{ . | markdownify }}{{ end }} - </td> - </tr> - {{- end }} - </tbody> - </table> - </div> - {{- end }} -{{ end }} - -{{/* ── Request body ─────────────────────────────────────────────────────── */}} -{{ define "api-ref-body" }} - {{- $api := .api -}} - {{- $op := .op -}} - {{- with $op.requestBody }} - {{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) }} - <div class="mb-5"> - <h4 - class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400" - > - Request body - </h4> - {{- with $body.description }} - <p class="mb-2 text-sm text-gray-600 dark:text-gray-400"> - {{ . | markdownify }} - </p> - {{- end }} - {{- $ct := "" -}} - {{- $media := dict -}} - {{- range $name, $m := $body.content -}} - {{- if not $ct -}}{{- $ct = $name -}}{{- $media = $m -}}{{- end -}} - {{- end -}} - {{- if $ct }} - <p class="mb-2 text-xs text-gray-500 dark:text-gray-400"> - Content type: - <code class="rounded bg-gray-100 px-1 dark:bg-gray-800" - >{{ $ct }}</code - > - </p> - {{ template "api-ref-schema-link" (dict "api" $api "schema" $media.schema) }} - {{ template "api-ref-examples" (dict - "examples" $media.examples - "prefix" "req" - ) - }} - {{- end }} - </div> - {{- end }} -{{ end }} - -{{/* ── Responses ────────────────────────────────────────────────────────── */}} -{{ define "api-ref-responses" }} - {{- $api := .api -}} - {{- $op := .op -}} - {{- $statusColors := dict - "200" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300" - "201" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300" - "204" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300" - "400" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300" - "401" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" - "403" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" - "404" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" - "409" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300" - "500" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" - -}} - {{- with $op.responses }} - <div> - <h4 - class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400" - > - Responses - </h4> - <div class="space-y-2"> - {{- range $code, $resp := . }} - {{- $r := partial "api-ref/resolve.html" (dict "api" $api "node" $resp) }} - <details - {{ if hasPrefix $code "2" }}open{{ end }} - class="group rounded border border-gray-200 dark:border-gray-700" - > - <summary - class="flex cursor-pointer list-none items-center gap-2 rounded-t bg-gray-50 px-3 py-2 dark:bg-gray-900 [&::-webkit-details-marker]:hidden" - > - <span - class="inline-block text-gray-400 transition-transform group-open:rotate-90 dark:text-gray-500" - >▸</span - > - <span - class="{{ index $statusColors $code | default "bg-gray-100 text-gray-700 dark:bg-gray-800 dark:text-gray-300" }} inline-block rounded px-1.5 py-0.5 font-mono text-xs font-semibold" - >{{ $code }}</span - > - <span class="text-sm text-gray-600 dark:text-gray-400" - >{{ $r.description }}</span - > - </summary> - {{- $ct := "" -}} - {{- $media := dict -}} - {{- range $name, $m := $r.content -}} - {{- if not $ct -}} - {{- $ct = $name -}}{{- $media = $m -}} - {{- end -}} - {{- end -}} - {{- if $ct }} - <div class="px-3 pt-2 pb-3"> - {{ template "api-ref-schema-link" (dict "api" $api "schema" $media.schema) }} - {{ template "api-ref-examples" (dict - "examples" $media.examples - "prefix" (printf "resp-%s" $code) - ) - }} - </div> - {{- end }} - </details> - {{- end }} - </div> - </div> - {{- end }} -{{ end }} - -{{/* ── Example block with optional tabs ─────────────────────────────────── */}} -{{ define "api-ref-examples" }} - {{- $examples := .examples -}} - {{- $prefix := .prefix -}} - {{- $tabs := slice -}} - {{- range $name, $ex := $examples -}} - {{- $tabs = $tabs | append (dict "name" $name "ex" $ex) -}} - {{- end -}} - {{- if $tabs }} - {{- $first := (index $tabs 0).name -}} - <div - {{ if gt (len $tabs) 1 }}x-data="{ tab: {{ $first | jsonify }} }"{{ end }} - > - {{- if gt (len $tabs) 1 }} - <div class="mb-2 flex flex-wrap gap-1"> - {{- range $tabs }} - {{- $label := .name -}} - {{- with .ex.summary }}{{ $label = . }}{{ end -}} - <button - @click="tab = {{ .name | jsonify }}" - :class="tab === {{ .name | jsonify }} ? 'bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300' : 'bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400'" - class="rounded px-2 py-0.5 text-xs font-medium" - > - {{ $label }} - </button> - {{- end }} - </div> - {{- end }} - {{- range $tabs }} - <div - {{ if gt (len $tabs) 1 }} - x-show="tab === {{ .name | jsonify }}" - {{ end }} - > - {{- with .ex.value -}} - <div - class="syntax-light dark:syntax-dark not-prose overflow-hidden rounded border border-gray-200 dark:border-gray-700" - > - {{ highlight (. | jsonify (dict "indent" " ")) "json" "" }} - </div> - {{- end }} - </div> - {{- end }} - </div> - {{- end }} -{{ end }} - -{{/* ── Inline schema-reference link (used in body/response) ─────────────── */}} -{{ define "api-ref-schema-link" }} - {{- $api := .api -}} - {{- $schema := .schema -}} - {{- if reflect.IsMap $schema -}} - {{- with index $schema "$ref" -}} - {{- $parts := split . "/" -}} - {{- $name := index $parts (sub (len $parts) 1) -}} - <p class="mb-2 text-xs text-gray-500 dark:text-gray-400"> - Schema: - <a - href="#schema-{{ $name | urlize }}" - class="font-mono text-blue-600 hover:underline dark:text-blue-400" - >{{ $name }}</a - > - </p> - {{- end -}} - {{- end -}} -{{ end }} - -{{/* ── Type rendering for parameter / property tables ───────────────────── */}} -{{ define "api-ref-type" }} - {{- $api := .api -}} - {{- $schema := .schema -}} - {{- if not (reflect.IsMap $schema) -}} - — - {{- else -}} - {{- with index $schema "$ref" -}} - {{- $parts := split . "/" -}} - {{- $name := index $parts (sub (len $parts) 1) -}} - <a - href="#schema-{{ $name | urlize }}" - class="text-blue-600 hover:underline dark:text-blue-400" - >{{ $name }}</a - > - {{- else -}} - {{- with $schema.type -}} - {{- if eq . "array" -}} - array<{{ template "api-ref-type" (dict "api" $api "schema" $schema.items) }}> - {{- else -}} - {{ . }} - {{- end -}} - {{- else -}} - {{- if $schema.allOf -}} - object - {{- else if $schema.anyOf -}} - any - {{- else if $schema.oneOf -}} - any - {{- else -}} - — - {{- end -}} - {{- end -}} - {{- end -}} - {{- end -}} -{{ end }} - -{{/* ── Schemas section ──────────────────────────────────────────────────── */}} -{{ define "api-ref-schemas" }} - {{- $api := . -}} - {{- with $api.components -}} - {{- with .schemas }} - <section class="mb-12"> - <h2 id="schemas" class="mb-6 scroll-mt-24 text-2xl font-semibold"> - Schemas - </h2> - {{- range $name, $schema := . }} - <div - id="schema-{{ $name | urlize }}" - class="mb-8 scroll-mt-24 rounded border border-gray-200 p-4 dark:border-gray-700" - > - <h3 class="mb-1 font-mono text-base font-semibold">{{ $name }}</h3> - {{- with $schema.description }} - <div - class="prose dark:prose-invert prose-sm mb-3 max-w-none text-sm" - > - {{ . | markdownify }} - </div> - {{- end }} - {{- with $schema.enum }} - <p class="mb-3 text-sm text-gray-500 dark:text-gray-400"> - Enum: - {{- range $i, $v := . -}} - {{- if $i }},{{ end -}} - <code - class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800" - >{{ $v }}</code - > - {{- end -}} - </p> - {{- end }} - {{- with $schema.properties }} - {{ template "api-ref-properties" (dict - "api" $api - "schema" $schema - ) - }} - {{- else }} - {{- with $schema.items }} - <p class="text-sm text-gray-500 dark:text-gray-400"> - Items: - <span class="font-mono" - >{{ template "api-ref-type" (dict "api" $api "schema" .) }}</span - > - </p> - {{- end }} - {{- end }} - </div> - {{- end }} - </section> - {{- end }} - {{- end }} -{{ end }} - -{{/* ── Property table for a schema ──────────────────────────────────────── */}} -{{ define "api-ref-properties" }} - {{- $api := .api -}} - {{- $schema := .schema -}} - {{- $required := $schema.required | default slice -}} - <table class="w-full border-collapse text-sm"> - <thead> - <tr class="border-b border-gray-200 dark:border-gray-700"> - <th - class="w-40 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Property - </th> - <th - class="w-32 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Type - </th> - <th - class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300" - > - Required - </th> - <th - class="py-1.5 text-left font-medium text-gray-700 dark:text-gray-300" - > - Description - </th> - </tr> - </thead> - <tbody> - {{- range $propName, $prop := $schema.properties }} - <tr class="border-b border-gray-100 last:border-0 dark:border-gray-800"> - <td class="py-1.5 pr-4 align-top"> - <code class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800" - >{{ $propName }}</code - > - </td> - <td - class="py-1.5 pr-4 align-top font-mono text-xs text-gray-500 dark:text-gray-400" - > - {{ template "api-ref-type" (dict "api" $api "schema" $prop) }} - </td> - <td - class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400" - > - {{ if in $required $propName }}yes{{ else }}no{{ end }} - </td> - <td class="py-1.5 align-top text-sm text-gray-600 dark:text-gray-400"> - {{- $resolved := partial "api-ref/resolve.html" (dict "api" $api "node" $prop) -}} - {{- with $resolved.description -}} - {{ . | markdownify }} - {{- end -}} - </td> - </tr> - {{- end }} - </tbody> - </table> -{{ end }} diff --git a/layouts/api-reference.markdown.md b/layouts/api-reference.markdown.md deleted file mode 100644 index 182a063d3cb1..000000000000 --- a/layouts/api-reference.markdown.md +++ /dev/null @@ -1,185 +0,0 @@ -{{- /* - Markdown rendering of an OpenAPI reference page. - - Mirrors the HTML api-reference layout: unmarshals the colocated YAML - Page Resource into a plain Hugo map and walks the spec to produce a - flat markdown document. Used by the "View Markdown" / "Copy Markdown" - actions and the .md alternate link. -*/ -}} -{{- $specRes := .Resources.GetMatch "*.yaml" -}} -{{- $api := $specRes | transform.Unmarshal -}} -{{- $methods := slice "get" "post" "put" "patch" "delete" -}} -{{- $paths := $api.paths -}} -# {{ .Title }} - -{{ with .Description }}{{ . }}{{ end }} - -{{ with $api.info }} -{{- with .version }}- **Version**: `{{ . }}` -{{ end -}} -{{ end -}} -{{- range $api.servers }}- **Base URL**: `{{ .url }}` -{{ end }} -- **OpenAPI specification**: [`{{ path.Base $specRes.RelPermalink }}`]({{ $specRes.Permalink }}) - -{{ with $api.info }}{{ with .description }}{{ . }}{{ end }}{{ end }} - -{{ with $api.components }}{{ with .securitySchemes }} -## Authentication - -{{ range $name, $scheme := . }} -**`{{ $name }}`**{{ with $scheme.type }} — type: `{{ . }}`{{ end }}{{ with $scheme.scheme }}, scheme: `{{ . }}`{{ end }}{{ with $scheme.bearerFormat }}, bearer format: `{{ . }}`{{ end }} - -{{ with $scheme.description }}{{ . }}{{ end }} -{{ end -}} -{{ end }}{{ end }} - -{{- range $api.tags }} -## {{ .name | title }} - -{{ with .description }}{{ . }}{{ end }} - -{{- $tagName := .name -}} -{{- range $path, $item := $paths -}} - {{- $sharedParams := slice -}} - {{- with index $item "parameters" -}} - {{- range . -}} - {{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $sharedParams = $sharedParams | append $p -}} - {{- end -}} - {{- end -}} - {{- range $methods -}} - {{- $method := . -}} - {{- with index $item $method -}} - {{- $op := . -}} - {{- if in $op.tags $tagName }} -### `{{ upper $method }}` `{{ $path }}` - -{{ with $op.summary }}**{{ . }}**{{ end }} - -{{ with $op.description }}{{ . }}{{ end }} - -{{- $params := $sharedParams -}} -{{- with index $op "parameters" -}} - {{- range . -}} - {{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}} - {{- $params = $params | append $p -}} - {{- end -}} -{{- end -}} -{{ if $params }} -**Parameters** - -{{ range $params -}} -- `{{ .name }}` ({{ .in }}{{ with .schema }}{{ with .type }}, {{ . }}{{ end }}{{ end }}{{ if .required }}, required{{ end }}){{ with .description }} — {{ . | strings.TrimSpace }}{{ end }} -{{ end }} -{{- end }} - -{{- with $op.requestBody -}} - {{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) }} -**Request body**{{ with $body.description }} — {{ . | strings.TrimSpace }}{{ end }} - -{{- $ct := "" -}} -{{- $media := dict -}} -{{- range $n, $m := $body.content -}} - {{- if not $ct -}}{{- $ct = $n -}}{{- $media = $m -}}{{- end -}} -{{- end -}} -{{ if $ct }} -Content type: `{{ $ct }}` - -{{ template "api-ref-md-schema-link" (dict "schema" $media.schema) }} -{{ range $exName, $ex := $media.examples }}{{ with $ex.value }} -```json -{{ . | jsonify (dict "indent" " ") }} -``` -{{ end }}{{ end }} -{{- end }} -{{- end }} - -{{- with $op.responses }} -**Responses** - -{{ range $code, $resp := . -}} -{{- $r := partial "api-ref/resolve.html" (dict "api" $api "node" $resp) }} -`{{ $code }}` — {{ with $r.description }}{{ . | strings.TrimSpace }}{{ end }} -{{- $ct := "" -}} -{{- $media := dict -}} -{{- range $n, $m := $r.content -}} - {{- if not $ct -}}{{- $ct = $n -}}{{- $media = $m -}}{{- end -}} -{{- end }} -{{ if $ct }} -{{ template "api-ref-md-schema-link" (dict "schema" $media.schema) }} -{{ range $exName, $ex := $media.examples }}{{ with $ex.value }} -```json -{{ . | jsonify (dict "indent" " ") }} -``` -{{ end }}{{ end }} -{{- end }} -{{ end }} -{{ end -}} - - {{ end -}} - {{- end -}} - {{- end -}} -{{- end }} -{{- end }} - -{{- with $api.components }}{{ with .schemas }} -## Schemas - -{{ range $name, $schema := . }} -### `{{ $name }}` - -{{ with $schema.description }}{{ . | strings.TrimSpace }}{{ end }} - -{{ with $schema.enum -}} -Enum: {{ range $i, $v := . }}{{ if $i }}, {{ end }}`{{ $v }}`{{ end }} -{{ end }} - -{{- with $schema.properties }} -{{- $required := $schema.required | default slice }} -| Property | Type | Required | Description | -| -------- | ---- | -------- | ----------- | -{{ range $propName, $prop := . -}} -| `{{ $propName }}` | {{ template "api-ref-md-type" $prop }} | {{ if in $required $propName }}yes{{ else }}no{{ end }} | {{ with $prop.description }}{{ . | strings.TrimSpace | strings.ReplaceRE "\\s*\\n\\s*" " " }}{{ end }} | -{{ end }} -{{ end -}} - -{{ end -}} -{{ end }}{{ end }} - -{{- /* ── Helpers ───────────────────────────────────────────────────────── */ -}} - -{{- define "api-ref-md-type" -}} - {{- $s := . -}} - {{- if reflect.IsMap $s -}} - {{- with index $s "$ref" -}} - {{- $parts := split . "/" -}} - {{- $name := index $parts (sub (len $parts) 1) -}} - `{{ $name }}` - {{- else -}} - {{- with $s.type -}} - {{- if eq . "array" -}} - `array<`{{ template "api-ref-md-type" $s.items }}`>` - {{- else -}} - `{{ . }}` - {{- end -}} - {{- else -}} - {{- if $s.allOf -}}`object` - {{- else if or $s.anyOf $s.oneOf -}}`any` - {{- else -}}—{{- end -}} - {{- end -}} - {{- end -}} - {{- else -}}—{{- end -}} -{{- end -}} - -{{- define "api-ref-md-schema-link" -}} - {{- $schema := .schema -}} - {{- $indent := .indent | default "" -}} - {{- if reflect.IsMap $schema -}} - {{- with index $schema "$ref" -}} - {{- $parts := split . "/" -}} - {{- $name := index $parts (sub (len $parts) 1) -}} -{{ $indent }}Schema: `{{ $name }}` - {{- end -}} - {{- end -}} -{{- end -}} diff --git a/layouts/api.html b/layouts/api.html index 888f27d18584..bfa48f550bbe 100644 --- a/layouts/api.html +++ b/layouts/api.html @@ -117,6 +117,6 @@ {{ end }} </article> </main> - <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script> + <script src="https://cdn.redoc.ly/redoc/v2.5.1/bundles/redoc.standalone.js"></script> </body> </html> diff --git a/layouts/baseof.html b/layouts/baseof.html index 062ff2bec1b7..7d4354bcc353 100644 --- a/layouts/baseof.html +++ b/layouts/baseof.html @@ -2,6 +2,7 @@ <html lang="en"> <head> {{ partial "head.html" . }} + {{ block "head-extra" . }}{{ end }} </head> <body @@ -30,7 +31,7 @@ } } })" - class="bg-background-toc dark:bg-background-toc fixed top-0 z-40 hidden h-screen w-full flex-none overflow-x-hidden overflow-y-auto md:sticky md:top-16 md:z-auto md:block md:h-[calc(100vh-64px)] md:w-[320px]" + class="bg-background-toc dark:bg-background-toc fixed top-0 z-40 hidden h-screen w-full flex-none overflow-x-hidden overflow-y-auto{{ if ne .Type "guides" }} md:sticky md:top-16 md:z-auto md:block md:h-[calc(100vh-64px)] md:w-[320px]{{ end }}" :class="{ 'hidden': ! $store.showSidebar }" > <!-- Gray backdrop on small screens --> @@ -53,11 +54,7 @@ <!-- Actual Sidebar Content --> {{ block "left" . }} {{ partial "sidebar/mainnav.html" . }} - {{ if eq .Type "guides" }} - {{ partial "sidebar/guides.html" . }} - {{ else }} - {{ partial "sidebar/sections.html" . }} - {{ end }} + {{ partial "sidebar/sections.html" . }} {{ end }} </div> </div> @@ -99,5 +96,9 @@ {{ with .Store.Get "mermaid" }} {{ partialCached "mermaid-script.html" "-" "-" }} {{ end }} + {{/* Load interactive diagrams only on pages that contain the shortcode */}} + {{ with .Store.Get "interactive-diagram" }} + {{ partialCached "interactive-diagram-script.html" "-" "-" }} + {{ end }} </body> </html> diff --git a/layouts/cli.html b/layouts/cli.html index b1b4ad5b9c28..19c5c1691782 100644 --- a/layouts/cli.html +++ b/layouts/cli.html @@ -133,10 +133,10 @@ <h1>{{ .Title }}</h1> {{ partialCached "components/badge.html" (dict "color" "red" "content" "Deprecated") "deprecated" }} {{ end }} {{ with .experimental }} - {{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (daemon)") "exp" }} + {{ partialCached "components/badge.html" (dict "color" "violet" "content" "experimental (daemon)") "exp" }} {{ end }} {{ with .experimentalcli }} - {{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (CLI)") "exp-cli" }} + {{ partialCached "components/badge.html" (dict "color" "violet" "content" "experimental (CLI)") "exp-cli" }} {{ end }} {{ with .kubernetes }} {{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }} diff --git a/layouts/get-started.html b/layouts/get-started.html new file mode 100644 index 000000000000..35f213160c59 --- /dev/null +++ b/layouts/get-started.html @@ -0,0 +1,82 @@ +{{ define "right" }}{{ end }} +{{ define "article" }} + <article class="w-full max-w-5xl pb-10 md:pb-16"> + {{ partial "breadcrumbs.html" . }} + <header class="max-w-3xl pb-8 md:pb-10"> + <h1 + data-pagefind-weight="10" + class="mb-3 text-4xl leading-tight font-semibold tracking-tight text-balance text-gray-950 md:text-5xl dark:text-white" + > + Get started with Docker + </h1> + <p + class="max-w-2xl text-lg leading-relaxed text-gray-600 dark:text-gray-300" + > + Install what you need, then choose a tutorial that matches what you want + to do. + </p> + </header> + + <section class="mb-12 md:mb-16" aria-labelledby="install-heading"> + <h2 + id="install-heading" + class="mb-5 text-2xl leading-tight font-semibold tracking-tight text-gray-950 dark:text-white" + > + Install what you need + </h2> + <div class="grid grid-cols-1 gap-4 md:grid-cols-2"> + {{ range .Params.installs }} + <a + href="{{ .link }}" + class="group block rounded-xl border border-gray-200 bg-white p-5 transition hover:scale-[1.01] hover:border-blue-500 focus:outline-none focus-visible:ring-4 focus-visible:ring-blue-400/40 motion-reduce:transform-none dark:border-gray-700 dark:bg-gray-900 dark:hover:border-blue-500" + > + <p + class="mb-2 font-mono text-xs font-semibold tracking-[0.12em] text-gray-600 uppercase dark:text-gray-300" + > + {{ .eyebrow }} + </p> + <h3 + class="mb-1 text-lg font-semibold text-gray-950 transition-colors group-hover:text-blue-600 dark:text-white dark:group-hover:text-blue-400" + > + {{ .title }} + </h3> + <p class="leading-relaxed text-gray-600 dark:text-gray-300"> + {{ .description }} + </p> + </a> + {{ end }} + </div> + </section> + + <section aria-labelledby="tutorials-heading"> + <h2 + id="tutorials-heading" + class="mb-5 text-2xl leading-tight font-semibold tracking-tight text-gray-950 dark:text-white" + > + Choose a tutorial + </h2> + <div class="grid grid-cols-1 gap-4 lg:grid-cols-3"> + {{ range .Params.tutorials }} + <a + href="{{ .link }}" + class="group flex h-full flex-col rounded-xl border border-gray-200 bg-white p-6 transition hover:scale-[1.01] hover:border-blue-500 focus:outline-none focus-visible:ring-4 focus-visible:ring-blue-400/40 motion-reduce:transform-none dark:border-gray-700 dark:bg-gray-900 dark:hover:border-blue-500" + > + <p + class="mb-3 font-mono text-xs font-semibold tracking-[0.12em] text-gray-600 uppercase dark:text-gray-300" + > + {{ .audience }} + </p> + <h3 + class="mb-2 text-xl leading-tight font-semibold tracking-tight text-gray-950 transition-colors group-hover:text-blue-600 dark:text-white dark:group-hover:text-blue-400" + > + {{ .title }} + </h3> + <p class="leading-relaxed text-gray-600 dark:text-gray-300"> + {{ .description }} + </p> + </a> + {{ end }} + </div> + </section> + </article> +{{ end }} diff --git a/layouts/guides/landing.html b/layouts/guides/landing.html index 18c93bf4eda1..9b0fdebe491b 100644 --- a/layouts/guides/landing.html +++ b/layouts/guides/landing.html @@ -1,273 +1,218 @@ {{ define "left" }} {{- partial "sidebar/mainnav.html" . }} - <div class="navbar-font flex flex-col gap-2 p-4 text-sm"> - <p>Filter guides by tag or programming language.</p> - <p></p> - <div - class="space-y-4" - x-data="{ - filters: { tags: [], languages: [] }, - toggleFilter(grp, tag) { - this.filters[grp].includes(tag) - ? this.filters[grp] = this.filters[grp].filter(el => el != tag) - : this.filters[grp].push(tag); +{{ end }} - // Update URL - const url = new URL(window.location.href); - if (this.filters[grp].length > 0) { - url.searchParams.set(grp, this.filters[grp].join('~')); - } else { - url.searchParams.delete(grp); - } - window.history.replaceState({}, '', url); +{{ define "main" }} + {{- $tagOrder := slice "languages" "ai" "testing" "cicd" "observability" "security" "databases" "deployment" "admin" "labs" }} - this.$dispatch('guide-filter', { filters: this.filters }); + <div + class="not-prose mx-auto flex min-h-[calc(100dvh-7rem)] max-w-7xl flex-col" + x-data="{ + query: '', + tagFilter: '', + words() { return this.query.trim().toLowerCase().split(/\s+/).filter(Boolean) }, + textFiltering() { return this.query.trim().length > 0 }, + filtering() { return this.textFiltering() || this.tagFilter !== '' }, + matchText(text) { return this.words().every(w => text.includes(w)) }, + rowVisible(el) { return !this.textFiltering() || this.matchText(el.dataset.search) }, + sectionVisible(el) { + if (this.tagFilter) return el.dataset.tag === this.tagFilter; + if (this.textFiltering()) return Array.from(el.querySelectorAll('[data-guide]')).some(r => this.matchText(r.dataset.search)); + return true; }, - - init() { - const url = new URL(window.location.href); - const tags = url.searchParams.get('tags') - const langs = url.searchParams.get('languages') - if (tags != null) { - this.filters['tags'] = tags.split('~'); - } - if (langs != null) { - this.filters['languages'] = langs.split('~'); - } - } + resultCount() { + if (this.tagFilter) return document.querySelectorAll('section[data-tag=' + this.tagFilter + '] [data-guide]').length; + return Array.from(document.querySelectorAll('[data-guide]')).filter(r => this.matchText(r.dataset.search)).length; + }, + selectTag(tag) { this.tagFilter = this.tagFilter === tag ? '' : tag; this.query = ''; window.scrollTo({ top: 0, behavior: 'smooth' }); }, + clear() { this.query = ''; this.tagFilter = ''; } }" - @guide-filter.window="filters = $event.detail.filters;" - > - <div class="pl-2"><strong>Tags</strong></div> - <fieldset class="flex flex-col gap-2"> - {{- range $name, $data := hugo.Data.tags }} - {{- if where $.Pages "Params.tags" "intersect" (slice $name) }} - {{- $id := anchorize (fmt.Printf "tag-%s" $name) }} - <div class="flex gap-2 pl-2"> - <input - value="{{ $name }}" - type="checkbox" - id="{{ $id }}" - @change="toggleFilter('tags', '{{ $name }}')" - :checked="filters['tags'].includes('{{ $name }}')" - /> - <label class="select-none" for="{{ $id }}" - >{{ $data.title }}</label - > - </div> - {{- end }} - {{ end }} - </fieldset> - <div class="pl-2"><strong>Languages</strong></div> - <fieldset class="flex flex-wrap gap-2 pl-2"> - {{- range $name, $data := hugo.Data.languages }} - {{- if where $.Pages "Params.languages" "intersect" (slice $name) }} - {{- $id := anchorize (fmt.Printf "lang-%s" $name) }} + > + {{- partial "breadcrumbs.html" . }} + + <div class="mt-4"> + <h1 + data-pagefind-weight="10" + class="scroll-mt-36 text-5xl font-bold tracking-tight" + > + Guides + </h1> + {{- with .Description }} + <p class="mt-3 text-lg text-gray-500 dark:text-gray-400">{{ . }}</p> + {{- end }} + </div> + + <!-- Text filter --> + <div class="relative mt-8 mb-10 max-w-xl"> + <span + class="icon-svg icon-sm pointer-events-none absolute top-1/2 left-3.5 -translate-y-1/2 text-gray-400 dark:text-gray-500" + > + {{ partialCached "icon" "magnifying-glass" "magnifying-glass" }} + </span> + <input + type="search" + x-model="query" + @input="tagFilter = ''" + @keydown.escape="clear()" + aria-label="Filter guides" + placeholder="Filter guides by name, topic, or tag…" + class="w-full rounded-xl border border-gray-300 bg-white py-2.5 pr-10 pl-11 text-sm text-gray-900 shadow-sm transition placeholder:text-gray-400 focus:border-blue-400 focus:ring-2 focus:ring-blue-400/40 focus:outline-none dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100 dark:placeholder:text-gray-500" + /> + <button + x-show="query" + x-cloak + @click="clear()" + aria-label="Clear filter" + class="icon-svg icon-sm absolute top-1/2 right-2.5 -translate-y-1/2 rounded-md p-1 text-gray-400 transition hover:bg-gray-100 hover:text-gray-700 dark:hover:bg-gray-800 dark:hover:text-gray-200" + > + {{ partialCached "icon" "x-mark" "x-mark" }} + </button> + </div> + + <div class="flex flex-1 gap-16 xl:gap-24"> + <!-- Sticky topic filter --> + <nav class="sticky top-20 hidden w-52 flex-none flex-col self-start text-gray-500 xl:flex dark:text-gray-400"> + <p class="mb-3 text-xs font-semibold tracking-widest text-gray-400 uppercase dark:text-gray-500"> + Browse + </p> + <button + type="button" + @click="clear()" + class="flex items-center justify-between py-1.5 text-left text-sm transition-colors" + :class="!filtering() ? 'text-black dark:text-white font-medium' : 'text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100'" + > + <span class="flex items-center gap-2.5"> + <span>All guides</span> + </span> + <span class="text-xs tabular-nums text-gray-300 dark:text-gray-600">{{ len .RegularPagesRecursive }}</span> + </button> + {{- range $i, $tag := $tagOrder }} + {{- $tagData := index hugo.Data.tags $tag }} + {{- $pages := where $.RegularPagesRecursive "Params.tags" "intersect" (slice $tag) }} + {{- if $pages }} <button - class="border-divider-light dark:border-divider-dark flex gap-1 rounded-full border bg-white px-2 py-1 dark:bg-gray-800" - :class="{ 'ring-3-2 ring-3-blue-light-400 dark:ring-3-blue-dark-400': filters['languages'].includes('{{ $name }}') }" - @click="toggleFilter('languages', '{{ $name }}')" + type="button" + @click="selectTag('{{ $tag }}')" + class="flex items-center justify-between py-1.5 text-left text-sm transition-colors" + :class="tagFilter === '{{ $tag }}' ? 'text-black dark:text-white font-medium' : 'text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100'" > - <img - height="18" - width="18" - title="{{ $data.title }}" - src="{{ $data.icon }}" - /> - <span>{{ $data.title }}</span> + <span class="flex items-center gap-2.5"> + <span>{{ $tagData.title }}</span> + </span> + <span class="text-xs tabular-nums text-gray-300 dark:text-gray-600">{{ len $pages }}</span> </button> {{- end }} - {{ end }} - </fieldset> - </div> - </div> -{{ end }} + {{- end }} + </nav> -{{ define "main" }} - <div class="flex w-full gap-8"> - <article class="prose dark:prose-invert max-w-none min-w-0"> - {{- partial "breadcrumbs.html" . }} - <h1 data-pagefind-weight="10" class="scroll-mt-36">{{ .Title }}</h1> - {{ .Content }} + <!-- Guide list --> <div - class="not-prose min-h-screen" - x-data="{ - filters: { tags: [], languages: [] }, - hidden: [], - total: {{ len .Pages }}, - - noFilters() { - return Object.values(this.filters).every(arr=> Array.isArray(arr) && arr.length === 0); - }, - - isVisible(el) { - return !this.hidden.includes(el.id); - }, - - updateVisible() { - const hiddenSet = new Set(); - // show if no filters have been selected - if (this.noFilters()) { - this.hidden = []; - return; - }; - const guideContainer = this.$refs['guide-container']; - const guides = guideContainer.children - - // Loop over the filters object - for (const [key, value] of Object.entries(this.filters)) { - if (!value || value.length === 0) continue; - - for (const g of guides) { - // Get the dataset for the current guide (e.g., languages or tags) - const terms = JSON.parse(g.dataset[key]); - - // Check if any of the filter values exist in the terms - const containsSome = terms.some(term => this.filters[key].includes(term)); - - // If none of the terms match the filter, mark the guide as hidden - if (!containsSome) { - hiddenSet.add(g.id) - } - } - } - - this.hidden = Array.from(hiddenSet) - }, - - init() { - const url = new URL(window.location.href); - const tags = url.searchParams.get('tags') - const langs = url.searchParams.get('languages') - if (tags != null) { - this.filters['tags'] = tags.split('~'); - } - if (langs != null) { - this.filters['languages'] = langs.split('~'); - } - this.updateVisible(); - } - }" - x-cloak - @guide-filter.window="filters = $event.detail.filters; updateVisible(); $nextTick(() => { window.scrollTo({ top: 0 }) })" + class="min-w-0 flex-1" + :class="{ 'guides-flat': filtering() }" > - <div x-show="noFilters()"> - <h2>Featured guides</h2> - <div - class="not-prose grid grid-cols-1 gap-8 py-4 lg:grid-cols-2 xl:grid-cols-3" - > - {{- $featured := where .Pages "Params.featured" true }} - {{- with $featured }} - {{- range . }} - <div class="flex h-full flex-col"> - <a class="hover:underline" href="{{ .Permalink }}"> - {{- $img := resources.Get (.Params.image | default "/images/thumbnail.webp") }} - <img - class="h-64 w-full rounded-sm object-cover shadow" - src="{{ $img.Permalink }}" - /> - <p class="my-4 text-xl leading-snug">{{ .Title }}</p> - </a> - <p class="flex-grow text-sm">{{ .Summary }}</p> - <div class="mt-4"> - {{ template "guide-metadata" . }} - </div> - </div> + <!-- Featured: curated highlights, shown only in the default view --> + {{- $featured := where $.RegularPagesRecursive "Params.featured" true }} + {{- with $featured }} + <div x-show="!filtering()" class="mb-12"> + <p class="mb-4 flex items-center gap-1.5 text-xs font-semibold tracking-widest text-gray-400 uppercase dark:text-gray-500"> + <span class="icon-svg icon-sm text-blue-500">{{ partialCached "icon" "star" "star" }}</span> + Featured + </p> + <div class="grid gap-4 sm:grid-cols-2 xl:grid-cols-3"> + {{- range .ByWeight }} + <a + href="{{ .Permalink }}" + class="group flex flex-col gap-1.5 rounded-lg border border-gray-200 p-4 transition-colors hover:border-gray-300 dark:border-gray-800 dark:hover:border-gray-700" + > + <span class="font-medium leading-snug text-gray-900 transition-colors group-hover:text-blue-600 dark:text-gray-100 dark:group-hover:text-blue-400">{{ .Title }}</span> + <span class="line-clamp-2 text-sm leading-relaxed text-gray-500 dark:text-gray-400">{{ .Summary }}</span> + </a> {{- end }} - {{- end }} + </div> </div> - <hr class="text-divider-light dark:text-divider-dark" /> + {{- end }} + + <!-- Filtering meta bar --> + <div + x-show="filtering()" + x-cloak + class="mb-8 flex items-center justify-between border-b border-gray-200 pb-4 dark:border-gray-800" + > + <p class="text-sm text-gray-500 dark:text-gray-400"> + <span class="font-semibold text-gray-900 dark:text-gray-100" x-text="resultCount()"></span> + of {{ len .RegularPagesRecursive }} guides + </p> + <button + @click="clear()" + class="text-sm font-medium text-blue-600 transition hover:underline dark:text-blue-400" + > + Clear filter + </button> </div> - <h2 x-show="noFilters()" id="all-guides" class="scroll-mt-36"> - All guides - </h2> - <div x-show="!noFilters()" class="flex flex-col gap-2 pb-8"> - <div class="flex items-center gap-2"> - <span class="icon-svg icon-sm mb-1" - >{{ partialCached "icon" "funnel" "funnel" }}</span + + {{- range $i, $tag := $tagOrder }} + {{- $tagData := index hugo.Data.tags $tag }} + {{- $pages := where $.RegularPagesRecursive "Params.tags" "intersect" (slice $tag) }} + {{- if $pages }} + <section + id="{{ $tag }}" + data-tag="{{ $tag }}" + x-show="sectionVisible($el)" + class="scroll-mt-16 border-t border-gray-200 py-12 first:border-t-0 first:pt-0 dark:border-gray-800" > - <p> - Filtered results: showing - <span x-text="total - hidden.length"></span> out of - <span x-text="total"></span> guides. - </p> - </div> - <div class="flex items-center gap-2 pl-4"> - {{- range $name, $data := hugo.Data.tags }} - <div x-show="filters.tags.includes('{{ $name }}')"> - {{ template "termchip" $data.title }} + <div class="mb-6" x-show="!filtering()"> + <p class="mb-1 text-xs font-semibold tracking-widest text-gray-400 uppercase dark:text-gray-500"> + {{- printf "%02d" (add $i 1) -}} + </p> + <h2 class="text-2xl font-bold">{{ $tagData.title }}</h2> + {{- with $tagData.description }} + <p class="mt-1 text-gray-500 dark:text-gray-400">{{ . }}</p> + {{- end }} </div> - {{- end }} - {{- range $name, $data := hugo.Data.languages }} - <div - x-show="filters.languages.includes('{{ $name }}')" - class="border-divider-light dark:border-divider-dark inline-flex items-center gap-1 rounded-full border bg-gray-100 px-2 text-sm text-gray-200 select-none dark:bg-gray-800 dark:text-gray-300" - > - <img - class="py-1" - height="18" - width="18" - title="{{ $data.title }}" - src="{{ $data.icon }}" - /> - <span>{{ $data.title }}</span> - </div> - {{- end }} - </div> - </div> - <div x-ref="guide-container"> - {{- range .Pages }} - <div - id="guide-{{ math.Counter }}" - data-languages="{{ jsonify (.Params.languages | default slice) }}" - data-tags="{{ jsonify (.Params.tags | default slice) }}" - x-show="isVisible($el);" - class="border-divider-light dark:border-divider-dark flex flex-col justify-between border-b p-4 hover:bg-gray-100 hover:dark:bg-gray-800" - > - <div class="flex flex-col justify-between xl:flex-row"> - <a - href="{{ .Permalink }}" - class="mb-2 truncate text-lg hover:underline xl:mb-0" - >{{ .Title }}</a - > - {{ template "guide-metadata" . }} + <div class="divide-y divide-gray-200 dark:divide-gray-800"> + {{- range $pages }} + {{- $tagTitles := slice }} + {{- range .Params.tags }}{{ $tagTitles = $tagTitles | append (index hugo.Data.tags .).title }}{{ end }} + {{- $search := lower (printf "%s %s %s %s" .Title .Summary (delimit .Params.tags " ") (delimit $tagTitles " ")) }} + {{- $search = $search | replaceRE "\\s+" " " }} + <div + data-guide + data-search="{{ $search }}" + x-show="rowVisible($el)" + class="grid grid-cols-[5fr_6fr] items-start gap-6 py-4" + > + <a + href="{{ .Permalink }}" + class="font-medium leading-snug text-gray-900 hover:underline dark:text-gray-100" + >{{ .Title }}</a> + <span class="text-sm leading-relaxed text-gray-500 dark:text-gray-400">{{ .Summary }}</span> + </div> + {{- end }} </div> - </div> + </section> {{- end }} - </div> - </div> - </article> - </div> -{{ end }} + {{- end }} -{{- define "guide-metadata" }} - <div - class="flex items-center justify-between gap-8 text-sm text-gray-400 dark:text-gray-300" - > - <div class="flex flex-wrap gap-2"> - {{- with .Params.languages }} - {{ partial "guide-languages.html" . }} - {{- end }} - {{- with .Params.tags }} - {{ partial "guide-tags.html" . }} - {{- end }} - </div> - {{- with .Params.time }} - <div class="flex flex-shrink gap-2 whitespace-nowrap"> - <span class="icon-svg" - >{{ partialCached "icon" "clock" "clock" }}</span + <!-- No matches --> + <div + x-show="filtering() && resultCount() === 0" + x-cloak + class="flex flex-col items-center justify-center gap-3 py-24 text-center" > - <span>{{ . }}</span> + <span class="icon-svg icon-lg text-gray-300 dark:text-gray-600"> + {{ partialCached "icon" "magnifying-glass" "magnifying-glass" }} + </span> + <p class="text-gray-500 dark:text-gray-400"> + No guides match “<span class="font-medium text-gray-700 dark:text-gray-200" x-text="query"></span>”. + </p> + <button + @click="clear()" + class="text-sm font-medium text-blue-600 transition hover:underline dark:text-blue-400" + > + Clear filter + </button> + </div> </div> - {{- end }} + </div> </div> -{{- end }} - -{{- define "termchip" }} - <span class="chip"> - <span class="icon-svg icon-sm pb-0.5"> - {{ partialCached "icon" "tag" "tag" }} - </span> - {{ . }} - </span> -{{- end }} +{{ end }} diff --git a/layouts/guides/single.html b/layouts/guides/single.html new file mode 100644 index 000000000000..5d7ab8ed1ff3 --- /dev/null +++ b/layouts/guides/single.html @@ -0,0 +1,14 @@ +{{ define "left" }} + {{- partial "sidebar/mainnav.html" . }} +{{ end }} + +{{ define "main" }} + <div class="mx-auto flex w-full max-w-7xl justify-center gap-12"> + <article class="prose dark:prose-invert min-w-0 max-w-[92ch]"> + {{ partial "content-default.html" . }} + </article> + <div class="-mt-8 hidden w-72 flex-none lg:block"> + {{ partial "aside.html" . }} + </div> + </div> +{{ end }} diff --git a/layouts/home.html b/layouts/home.html index a5f86f937e5c..be53a510e1a5 100644 --- a/layouts/home.html +++ b/layouts/home.html @@ -60,7 +60,7 @@ {{ range slice "How do I get started with Docker?" "Can I run my AI agent in a sandbox?" - "What is a container?" + "How do I containerize an application?" "What are Docker Hardened Images?" "Why should I use Docker Compose?" }} @@ -80,7 +80,7 @@ <div class="container mx-auto px-4 xl:max-w-[1200px]"> <div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-4"> {{ range slice - (dict "url" "/get-started/" "icon" "rocket-launch" "title" "Get started" "description" "Learn Docker basics.") + (dict "url" "/get-started/" "icon" "rocket-launch" "title" "Get started" "description" "Containerize an app, sandbox an agent, or pilot Docker for your organization.") (dict "url" "/guides/" "icon" "book-open" "title" "Guides" "description" "Optimize your development workflows with Docker.") (dict "url" "/manuals/" "icon" "document-text" "title" "Manuals" "description" "Install, set up, configure, and use Docker products.") (dict "url" "/reference/" "icon" "command-line" "title" "Reference" "description" "Browse the CLI and API documentation.") @@ -116,43 +116,7 @@ </div> </section> - <!-- Popular Topics Section --> - <section class="py-8"> - <div class="container mx-auto max-w-3xl px-4"> - <h2 - class="mb-8 text-center text-2xl font-semibold text-gray-900 dark:text-white" - > - Featured topics - </h2> - <div - class="divide-y divide-gray-200 rounded-xl border border-gray-200 bg-white dark:divide-gray-700 dark:border-gray-700 dark:bg-gray-900" - > - {{ range slice - (dict "url" "/dhi/" "title" "Docker Hardened Images") - (dict "url" "/ai/sandboxes/get-started/" "title" "Get started with Docker Sandboxes") - (dict "url" "/desktop/" "title" "Docker Desktop overview") - (dict "url" "/engine/install/" "title" "Install Docker Engine") - (dict "url" "/reference/dockerfile/" "title" "Dockerfile reference") - (dict "url" "/build/" "title" "Docker Build overview") - }} - <a - href="{{ .url }}" - class="group flex items-center justify-between px-4 py-3 transition hover:bg-blue-50 dark:hover:bg-gray-700" - > - <span - class="text-gray-900 transition group-hover:text-blue-500 dark:text-white dark:group-hover:text-blue-400" - >{{ .title }}</span - > - <span - class="icon-svg text-gray-400 transition group-hover:translate-x-1 dark:text-gray-500" - > - {{ partialCached "icon" "arrow-right" "arrow-right" }} - </span> - </a> - {{ end }} - </div> - </div> - </section> + {{ partial "whats-new.html" . }} </main> <footer>{{ partialCached "footer.html" . }}</footer> </body> diff --git a/layouts/home.llms.txt b/layouts/home.llms.txt index 43d00260c030..79f0b3c4caf3 100644 --- a/layouts/home.llms.txt +++ b/layouts/home.llms.txt @@ -16,7 +16,8 @@ Hub, Docker Scout, and Docker AI features. Use this file as a generated discovery guide for the docs site. For the complete page index, use [llms-full.txt](https://docs.docker.com/llms-full.txt). -> MCP endpoint for structured agent access: https://mcp-docs.docker.com/mcp +> Docker Skills for AI coding agents: https://docs.docker.com/ai/skills/ +> MCP endpoint for structured agent access: https://ai-backend-service.docker.com/mcp > Bulk text corpus for offline indexing: https://docs.docker.com/llms-full.txt ## Primary sections @@ -31,10 +32,7 @@ page index, use [llms-full.txt](https://docs.docker.com/llms-full.txt). {{ with $getStarted }} ## Starter paths -{{- range index .Params "get-started" }} -- [{{ .title }}]({{ .link | absURL }}): {{ .description }} -{{- end }} -{{- range index .Params "get-started2" }} +{{- range .Params.tutorials }} - [{{ .title }}]({{ .link | absURL }}): {{ .description }} {{- end }} {{- end }} diff --git a/layouts/home.redirects.json b/layouts/home.redirects.json index c92190149551..9d7ed82c9f05 100644 --- a/layouts/home.redirects.json +++ b/layouts/home.redirects.json @@ -24,9 +24,14 @@ {{- range hugo.Sites -}} {{- range .Pages -}} {{- if .Params.aliases -}} + {{- $page := . -}} {{- $target := .RelPermalink -}} {{- range .Params.aliases -}} - {{ $redirects.SetInMap "paths" . $target }} + {{- $alias := . -}} + {{- if eq (strings.TrimSuffix "/" $alias) (strings.TrimSuffix "/" $target) -}} + {{- errorf "alias %q in %s resolves to the page itself" $alias $page.File.Path -}} + {{- end -}} + {{- $redirects.SetInMap "paths" $alias $target -}} {{- end -}} {{- end -}} {{- end -}} diff --git a/layouts/home.robots.txt b/layouts/home.robots.txt index 7c2c07975479..8f718496139e 100644 --- a/layouts/home.robots.txt +++ b/layouts/home.robots.txt @@ -6,7 +6,6 @@ {{- if hugo.IsProduction -}} User-agent: * -Disallow: /unassociated-machines/ Content-Signal: ai-train=yes, search=yes, ai-input=yes diff --git a/layouts/redirect/single.html b/layouts/redirect/single.html deleted file mode 100644 index 03bf721b353b..000000000000 --- a/layouts/redirect/single.html +++ /dev/null @@ -1 +0,0 @@ -{{- template "alias.html" (dict "Permalink" .Params.target) -}} diff --git a/layouts/sbx-cli.html b/layouts/sbx-cli.html index 0b10f5e0fa6a..77c59e9e47ca 100644 --- a/layouts/sbx-cli.html +++ b/layouts/sbx-cli.html @@ -28,6 +28,22 @@ <h1>{{ .Title }}</h1> </table> </div> + {{- /* Experimental callout (command-level) */ -}} + {{ if $data.experimental }} + <div class="px-4 border-l-2 border-l-magenta-light dark:border-l-magenta-dark"> + <p class="not-prose flex gap-2 items-center text-magenta-light dark:text-magenta-dark"> + <span class="icon-svg pb-1">{{ partialCached "icon" "beaker" "beaker" }}</span> + <strong>{{ i18n "experimental" }}</strong> + </p> + <p><strong>This command is experimental.</strong></p> + <p> + Experimental features are intended for testing and feedback as their + functionality or design may change between releases without warning or + can be removed entirely in a future release. + </p> + </div> + {{ end }} + {{- /* Description */ -}} {{ with $data.description }} {{ $heading := dict "level" 2 "text" "Description" }} @@ -54,7 +70,14 @@ <h1>{{ .Title }}</h1> {{ $child := index hugo.Data.sbx_cli .Params.datafile }} <tr> <td class="text-left"><a class="link" href="{{ .Permalink }}"><code>{{ .Title }}</code></a></td> - <td class="text-left">{{ $child.synopsis }}</td> + <td class="text-left"> + <span class="inline-flex items-center gap-2"> + {{ if $child.experimental }} + {{ partialCached "components/badge.html" (dict "color" "violet" "content" "experimental") "sbx-exp" }} + {{ end }} + {{ $child.synopsis }} + </span> + </td> </tr> {{ end }} {{ end }} @@ -91,9 +114,14 @@ <h1>{{ .Title }}</h1> {{ end }} </td> <td> - {{ with .usage }} - {{ strings.TrimSpace . }} - {{ end }} + <span class="inline-flex items-center gap-2"> + {{ with .experimental }} + {{ partialCached "components/badge.html" (dict "color" "violet" "content" "experimental") "sbx-exp" }} + {{ end }} + {{ with .usage }} + {{ strings.TrimSpace . }} + {{ end }} + </span> </td> </tr> {{ end }} @@ -132,9 +160,14 @@ <h1>{{ .Title }}</h1> {{ end }} </td> <td> - {{ with .usage }} - {{ strings.TrimSpace . }} - {{ end }} + <span class="inline-flex items-center gap-2"> + {{ with .experimental }} + {{ partialCached "components/badge.html" (dict "color" "violet" "content" "experimental") "sbx-exp" }} + {{ end }} + {{ with .usage }} + {{ strings.TrimSpace . }} + {{ end }} + </span> </td> </tr> {{ end }} diff --git a/layouts/sitemap.xml b/layouts/sitemap.xml index 0c8f565eff16..9d56679e953b 100644 --- a/layouts/sitemap.xml +++ b/layouts/sitemap.xml @@ -10,7 +10,9 @@ {{- if ne .Params.sitemap false }} <url> <loc>{{ .Permalink}}</loc> + {{- if not .Lastmod.IsZero }} <lastmod>{{ .Lastmod | time.Format "2006-01-02" }}</lastmod> + {{- end }} <changefreq>monthly</changefreq> <priority>0.5</priority> </url> diff --git a/netlify.toml b/netlify.toml index 10bff81d0034..45b666756557 100644 --- a/netlify.toml +++ b/netlify.toml @@ -10,4 +10,4 @@ HUGO_ENVIRONMENT = "preview" SECRETS_SCAN_OMIT_PATHS = "public/contribute/file-conventions/index.html" [context.deploy-preview] -command = "hugo --gc --minify -b $DEPLOY_PRIME_URL && ./hack/flatten-and-resolve.js && npx pagefind@v1.5.2" +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL && node hack/flatten-and-resolve.js && node hack/api-docs/verify-output.mjs && npx pagefind@v1.5.2" diff --git a/package-lock.json b/package-lock.json index 3b2d9df13feb..53d434980a39 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@alpinejs/collapse": "3.15.8", "@alpinejs/focus": "3.15.8", "@alpinejs/persist": "3.15.8", - "@docker/marlin-sdk-web-public": "0.3.0", + "@docker/marlin-sdk-web-public": "0.6.0", "@floating-ui/dom": "1.7.6", "@tailwindcss/cli": "4.2.1", "@tailwindcss/typography": "0.5.19", @@ -21,13 +21,14 @@ "highlight.js": "11.11.1", "marked": "17.0.4", "mermaid": "11.15.0", + "micromark": "4.0.2", "tailwindcss": "4.2.1" }, "devDependencies": { - "markdownlint": "0.40.0", "prettier": "3.8.1", "prettier-plugin-go-template": "0.0.15", - "prettier-plugin-tailwindcss": "0.7.2" + "prettier-plugin-tailwindcss": "0.7.2", + "rumdl": "0.2.49" } }, "node_modules/@alpinejs/collapse": { @@ -110,9 +111,9 @@ "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==" }, "node_modules/@docker/marlin-sdk-web-public": { - "version": "0.3.0", - "resolved": "https://registry.npmjs.org/@docker/marlin-sdk-web-public/-/marlin-sdk-web-public-0.3.0.tgz", - "integrity": "sha512-MzolUogdFKPeBw66dNR2k3I1wPZVgYk6/BRYKKnextfg9IQY1A65WvQPyGF6dXfl2STsrhcmu5QFCxNnwjBOHQ==", + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/@docker/marlin-sdk-web-public/-/marlin-sdk-web-public-0.6.0.tgz", + "integrity": "sha512-WO6ufqJnJrRcc8IsPn7oQkpi1TFVBaBM/+dRiD/o8Lpmo7SJlzZ1m6+b03G7dNTJYMg8wiawOJeJeeOiKGz5Sw==", "dependencies": { "@bufbuild/protobuf": "2.11.0", "@bufbuild/protovalidate": "1.1.1", @@ -508,6 +509,118 @@ "url": "https://opencollective.com/parcel" } }, + "node_modules/@rumdl/cli-darwin-arm64": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-darwin-arm64/-/cli-darwin-arm64-0.2.49.tgz", + "integrity": "sha512-NuMdcOWyZRzzcgcWtGCxQkevvAbQ6h8Fs5utanWhrP9ncES1231ptj8jnD6LkBwZfG4D8sv2MwNfRzSm3b+sjw==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-darwin-x64": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-darwin-x64/-/cli-darwin-x64-0.2.49.tgz", + "integrity": "sha512-KzX9tj29f2GxEigsU6YPRhJIuhm5IhI9l5r2GiKzFUG4TRRewVHv4ZuL6DpG8rdPg2bPEauEWv5tRroKUdogvQ==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-linux-arm64": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-linux-arm64/-/cli-linux-arm64-0.2.49.tgz", + "integrity": "sha512-HOmc3M//I0G2EVx8MxObVTT/gm2LXCMrIpEdbB+8y1kvzxNjg8j+gk7BZIrOVOBnXQaIo+KBdvXSx1999hVv/g==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-linux-arm64-musl": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-linux-arm64-musl/-/cli-linux-arm64-musl-0.2.49.tgz", + "integrity": "sha512-bNKWWtkXVgqNUZRV7F3Bt/SKg1sNLopbVK4k2Cqr0rEVQz6wH5hG+conx2RsmUDUytcrf6g55DSufzcGObT1Qg==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-linux-x64": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-linux-x64/-/cli-linux-x64-0.2.49.tgz", + "integrity": "sha512-1xr+rj5UwwYeAD3kfCM0ImX1AC3P+zums0J6xBENEqFv6Tgo5qbdkVw1RxtvTRzA5lt7Jw/A3WUwpteg58nlCQ==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-linux-x64-musl": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-linux-x64-musl/-/cli-linux-x64-musl-0.2.49.tgz", + "integrity": "sha512-eBLx7p6/nGM9KS0iaYig4QmwyzrEw7Z+nCUYiGLGtFJ77Db2+FAFr4vjCPPrcV0WtlSjFFQKLhcwct998uTT3w==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@rumdl/cli-win32-x64": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/@rumdl/cli-win32-x64/-/cli-win32-x64-0.2.49.tgz", + "integrity": "sha512-P3VkUqmdBXNLp0JA+dfNKdt/POiqXeEdcHVObh0X/HEvUCJb3ZPW4G8+8OPJJTbEqH3aXMMiRbn6/eY+ONrkJQ==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18.0.0" + } + }, "node_modules/@tailwindcss/cli": { "version": "4.2.1", "resolved": "https://registry.npmjs.org/@tailwindcss/cli/-/cli-4.2.1.tgz", @@ -1062,11 +1175,9 @@ } }, "node_modules/@types/debug": { - "version": "4.1.12", - "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", - "integrity": "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==", - "dev": true, - "license": "MIT", + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", "dependencies": { "@types/ms": "*" } @@ -1076,19 +1187,10 @@ "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz", "integrity": "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==" }, - "node_modules/@types/katex": { - "version": "0.16.7", - "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.7.tgz", - "integrity": "sha512-HMwFiRujE5PjrgwHQ25+bsLJgowjGjm5Z8FVSf0N6PwgJrwxH0QxzHYDcKsTfV3wva0vzrpqMTJS2jXPr5BMEQ==", - "dev": true, - "license": "MIT" - }, "node_modules/@types/ms": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", - "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", - "dev": true, - "license": "MIT" + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==" }, "node_modules/@types/trusted-types": { "version": "2.0.7", @@ -1096,13 +1198,6 @@ "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==", "optional": true }, - "node_modules/@types/unist": { - "version": "2.0.11", - "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", - "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", - "dev": true, - "license": "MIT" - }, "node_modules/@upsetjs/venn.js": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/@upsetjs/venn.js/-/venn.js-2.0.0.tgz", @@ -1136,19 +1231,6 @@ "@vue/reactivity": "~3.1.1" } }, - "node_modules/ansi-regex": { - "version": "6.2.2", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", - "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/ansi-regex?sponsor=1" - } - }, "node_modules/braces": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", @@ -1165,30 +1247,6 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, - "node_modules/character-entities-legacy": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", - "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, - "node_modules/character-reference-invalid": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", - "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", - "dev": true, - "license": "MIT", "funding": { "type": "github", "url": "https://github.com/sponsors/wooorm" @@ -1697,8 +1755,6 @@ "version": "4.4.3", "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "dev": true, - "license": "MIT", "dependencies": { "ms": "^2.1.3" }, @@ -1712,11 +1768,9 @@ } }, "node_modules/decode-named-character-reference": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.2.0.tgz", - "integrity": "sha512-c6fcElNV6ShtZXmsgNgFFV5tVX2PaV4g+MOAkb8eXHvn6sryJBrZa9r0zV6+dtTyoCKxtDy5tyQ5ZwQuidtd+Q==", - "dev": true, - "license": "MIT", + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", "dependencies": { "character-entities": "^2.0.0" }, @@ -1737,8 +1791,6 @@ "version": "2.0.3", "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", - "dev": true, - "license": "MIT", "engines": { "node": ">=6" } @@ -1759,8 +1811,6 @@ "version": "1.1.0", "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", - "dev": true, - "license": "MIT", "dependencies": { "dequal": "^2.0.0" }, @@ -1816,19 +1866,6 @@ "tabbable": "^5.3.3" } }, - "node_modules/get-east-asian-width": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.5.0.tgz", - "integrity": "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, "node_modules/graceful-fs": { "version": "4.2.11", "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", @@ -1887,43 +1924,6 @@ "node": ">=12" } }, - "node_modules/is-alphabetical": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", - "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, - "node_modules/is-alphanumerical": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", - "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", - "dev": true, - "license": "MIT", - "dependencies": { - "is-alphabetical": "^2.0.0", - "is-decimal": "^2.0.0" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, - "node_modules/is-decimal": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", - "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, "node_modules/is-extglob": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", @@ -1945,17 +1945,6 @@ "node": ">=0.10.0" } }, - "node_modules/is-hexadecimal": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", - "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", - "dev": true, - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, "node_modules/is-number": { "version": "7.0.0", "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", @@ -2272,30 +2261,6 @@ "@jridgewell/sourcemap-codec": "^1.5.5" } }, - "node_modules/markdownlint": { - "version": "0.40.0", - "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.40.0.tgz", - "integrity": "sha512-UKybllYNheWac61Ia7T6fzuQNDZimFIpCg2w6hHjgV1Qu0w1TV0LlSgryUGzM0bkKQCBhy2FDhEELB73Kb0kAg==", - "dev": true, - "license": "MIT", - "dependencies": { - "micromark": "4.0.2", - "micromark-core-commonmark": "2.0.3", - "micromark-extension-directive": "4.0.0", - "micromark-extension-gfm-autolink-literal": "2.1.0", - "micromark-extension-gfm-footnote": "2.1.0", - "micromark-extension-gfm-table": "2.1.1", - "micromark-extension-math": "3.1.0", - "micromark-util-types": "2.0.2", - "string-width": "8.1.0" - }, - "engines": { - "node": ">=20" - }, - "funding": { - "url": "https://github.com/sponsors/DavidAnson" - } - }, "node_modules/marked": { "version": "17.0.4", "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.4.tgz", @@ -2351,7 +2316,6 @@ "version": "4.0.2", "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2362,7 +2326,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "@types/debug": "^4.0.0", "debug": "^4.0.0", @@ -2387,7 +2350,6 @@ "version": "2.0.3", "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2398,7 +2360,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", @@ -2418,107 +2379,10 @@ "micromark-util-types": "^2.0.0" } }, - "node_modules/micromark-extension-directive": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz", - "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==", - "dev": true, - "license": "MIT", - "dependencies": { - "devlop": "^1.0.0", - "micromark-factory-space": "^2.0.0", - "micromark-factory-whitespace": "^2.0.0", - "micromark-util-character": "^2.0.0", - "micromark-util-symbol": "^2.0.0", - "micromark-util-types": "^2.0.0", - "parse-entities": "^4.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/unified" - } - }, - "node_modules/micromark-extension-gfm-autolink-literal": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", - "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", - "dev": true, - "license": "MIT", - "dependencies": { - "micromark-util-character": "^2.0.0", - "micromark-util-sanitize-uri": "^2.0.0", - "micromark-util-symbol": "^2.0.0", - "micromark-util-types": "^2.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/unified" - } - }, - "node_modules/micromark-extension-gfm-footnote": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", - "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", - "dev": true, - "license": "MIT", - "dependencies": { - "devlop": "^1.0.0", - "micromark-core-commonmark": "^2.0.0", - "micromark-factory-space": "^2.0.0", - "micromark-util-character": "^2.0.0", - "micromark-util-normalize-identifier": "^2.0.0", - "micromark-util-sanitize-uri": "^2.0.0", - "micromark-util-symbol": "^2.0.0", - "micromark-util-types": "^2.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/unified" - } - }, - "node_modules/micromark-extension-gfm-table": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", - "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", - "dev": true, - "license": "MIT", - "dependencies": { - "devlop": "^1.0.0", - "micromark-factory-space": "^2.0.0", - "micromark-util-character": "^2.0.0", - "micromark-util-symbol": "^2.0.0", - "micromark-util-types": "^2.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/unified" - } - }, - "node_modules/micromark-extension-math": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/micromark-extension-math/-/micromark-extension-math-3.1.0.tgz", - "integrity": "sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg==", - "dev": true, - "license": "MIT", - "dependencies": { - "@types/katex": "^0.16.0", - "devlop": "^1.0.0", - "katex": "^0.16.0", - "micromark-factory-space": "^2.0.0", - "micromark-util-character": "^2.0.0", - "micromark-util-symbol": "^2.0.0", - "micromark-util-types": "^2.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/unified" - } - }, "node_modules/micromark-factory-destination": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2529,7 +2393,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", @@ -2540,7 +2403,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2551,7 +2413,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "devlop": "^1.0.0", "micromark-util-character": "^2.0.0", @@ -2563,7 +2424,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2574,7 +2434,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-types": "^2.0.0" @@ -2584,7 +2443,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2595,7 +2453,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", @@ -2607,7 +2464,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2618,7 +2474,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", @@ -2630,7 +2485,6 @@ "version": "2.1.1", "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2641,7 +2495,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" @@ -2651,7 +2504,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2662,7 +2514,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-symbol": "^2.0.0" } @@ -2671,7 +2522,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2682,7 +2532,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", @@ -2693,7 +2542,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2704,7 +2552,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-chunked": "^2.0.0", "micromark-util-types": "^2.0.0" @@ -2714,7 +2561,6 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2725,7 +2571,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-symbol": "^2.0.0" } @@ -2734,7 +2579,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2744,14 +2588,12 @@ "type": "OpenCollective", "url": "https://opencollective.com/unified" } - ], - "license": "MIT" + ] }, "node_modules/micromark-util-html-tag-name": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2761,14 +2603,12 @@ "type": "OpenCollective", "url": "https://opencollective.com/unified" } - ], - "license": "MIT" + ] }, "node_modules/micromark-util-normalize-identifier": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2779,7 +2619,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-symbol": "^2.0.0" } @@ -2788,7 +2627,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2799,7 +2637,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-types": "^2.0.0" } @@ -2808,7 +2645,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2819,7 +2655,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", @@ -2830,7 +2665,6 @@ "version": "2.1.0", "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2841,7 +2675,6 @@ "url": "https://opencollective.com/unified" } ], - "license": "MIT", "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", @@ -2853,7 +2686,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2863,14 +2695,12 @@ "type": "OpenCollective", "url": "https://opencollective.com/unified" } - ], - "license": "MIT" + ] }, "node_modules/micromark-util-types": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2880,8 +2710,7 @@ "type": "OpenCollective", "url": "https://opencollective.com/unified" } - ], - "license": "MIT" + ] }, "node_modules/micromatch": { "version": "4.0.8", @@ -2908,9 +2737,7 @@ "node_modules/ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true, - "license": "MIT" + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, "node_modules/node-addon-api": { "version": "7.1.1", @@ -2923,26 +2750,6 @@ "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.6.0.tgz", "integrity": "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==" }, - "node_modules/parse-entities": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", - "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", - "dev": true, - "license": "MIT", - "dependencies": { - "@types/unist": "^2.0.0", - "character-entities-legacy": "^3.0.0", - "character-reference-invalid": "^2.0.0", - "decode-named-character-reference": "^1.0.0", - "is-alphanumerical": "^2.0.0", - "is-decimal": "^2.0.0", - "is-hexadecimal": "^2.0.0" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/wooorm" - } - }, "node_modules/path-data-parser": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/path-data-parser/-/path-data-parser-0.1.0.tgz", @@ -3120,6 +2927,27 @@ "points-on-path": "^0.2.1" } }, + "node_modules/rumdl": { + "version": "0.2.49", + "resolved": "https://registry.npmjs.org/rumdl/-/rumdl-0.2.49.tgz", + "integrity": "sha512-pV6Ks5jr/wu4s7rBCaY5HJek3ZhG7W2knznRAhiw8AFc1DGgyuceirdH5S0k3XpSc6Ee92Ex4fyRTrZsHMIyHA==", + "dev": true, + "bin": { + "rumdl": "bin/rumdl" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "@rumdl/cli-darwin-arm64": "0.2.49", + "@rumdl/cli-darwin-x64": "0.2.49", + "@rumdl/cli-linux-arm64": "0.2.49", + "@rumdl/cli-linux-arm64-musl": "0.2.49", + "@rumdl/cli-linux-x64": "0.2.49", + "@rumdl/cli-linux-x64-musl": "0.2.49", + "@rumdl/cli-win32-x64": "0.2.49" + } + }, "node_modules/rw": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz", @@ -3139,39 +2967,6 @@ "node": ">=0.10.0" } }, - "node_modules/string-width": { - "version": "8.1.0", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.1.0.tgz", - "integrity": "sha512-Kxl3KJGb/gxkaUMOjRsQ8IrXiGW75O4E3RPjFIINOVH8AMl2SQ/yWdTzWwF3FevIX9LcMAjJW+GRwAlAbTSXdg==", - "dev": true, - "license": "MIT", - "dependencies": { - "get-east-asian-width": "^1.3.0", - "strip-ansi": "^7.1.0" - }, - "engines": { - "node": ">=20" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/strip-ansi": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz", - "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==", - "dev": true, - "license": "MIT", - "dependencies": { - "ansi-regex": "^6.2.2" - }, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/chalk/strip-ansi?sponsor=1" - } - }, "node_modules/stylis": { "version": "4.4.0", "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.4.0.tgz", diff --git a/package.json b/package.json index 346e083091c6..bb4de3c29c77 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "@alpinejs/collapse": "3.15.8", "@alpinejs/focus": "3.15.8", "@alpinejs/persist": "3.15.8", - "@docker/marlin-sdk-web-public": "0.3.0", + "@docker/marlin-sdk-web-public": "0.6.0", "@floating-ui/dom": "1.7.6", "@tailwindcss/cli": "4.2.1", "@tailwindcss/typography": "0.5.19", @@ -26,12 +26,13 @@ "highlight.js": "11.11.1", "marked": "17.0.4", "mermaid": "11.15.0", + "micromark": "4.0.2", "tailwindcss": "4.2.1" }, "devDependencies": { - "markdownlint": "0.40.0", "prettier": "3.8.1", "prettier-plugin-go-template": "0.0.15", - "prettier-plugin-tailwindcss": "0.7.2" + "prettier-plugin-tailwindcss": "0.7.2", + "rumdl": "0.2.49" } } diff --git a/scripts/lint.sh b/scripts/lint.sh index ab49f01be4e7..1201d4fb4851 100755 --- a/scripts/lint.sh +++ b/scripts/lint.sh @@ -1,27 +1,41 @@ #!/bin/bash -# Run markdownlint and vale on specific files. -# Usage: scripts/lint.sh <file> [file...] +# Run rumdl and Vale on specific Markdown files. +# Usage: scripts/lint.sh <markdown-file> [markdown-file...] # # Scoped output — no repo-wide noise. For full repo validation, use: # docker buildx bake validate set -uo pipefail if [ $# -eq 0 ]; then - echo "Usage: $0 <file> [file...]" >&2 + echo "Usage: $0 <markdown-file> [markdown-file...]" >&2 exit 1 fi +for file in "$@"; do + if [[ "$file" != *.md ]]; then + echo "Error: scripts/lint.sh only accepts Markdown files: $file" >&2 + exit 2 + fi +done + +repo_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) + exit_code=0 -echo "=== markdownlint ===" -if ! npx markdownlint-cli "$@" 2>&1; then +echo "=== rumdl ===" +if ! npx --no-install rumdl check "$@" 2>&1; then exit_code=1 fi echo "" echo "=== vale ===" -if ! vale "$@" 2>&1; then +if ! vale --no-global --config="$repo_root/.vale.ini" sync 2>&1; then + exit_code=1 +elif ! vale --no-global --config="$repo_root/.vale.ini" "$@" 2>&1; then exit_code=1 fi +echo "" +echo "Review Vale warnings and suggestions on changed lines; they don't affect the exit status." + exit $exit_code diff --git a/static/assets/images/extensions-private-marketplace.webp b/static/assets/images/extensions-private-marketplace.webp deleted file mode 100644 index 5120ba2c3284..000000000000 Binary files a/static/assets/images/extensions-private-marketplace.webp and /dev/null differ diff --git a/static/assets/images/extensions.webp b/static/assets/images/extensions.webp deleted file mode 100644 index 58b301f1b895..000000000000 Binary files a/static/assets/images/extensions.webp and /dev/null differ diff --git a/tech_writer.yml b/tech_writer.yml deleted file mode 100644 index b21bcd7b8902..000000000000 --- a/tech_writer.yml +++ /dev/null @@ -1,322 +0,0 @@ -# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/refs/heads/main/agent-schema.json -agents: - root: - model: coordinator - description: Documentation coordinator for analysis and delegation - instruction: | - <objective> - Coordinate documentation work by analyzing requests, discovering existing - content, scoping the work, and delegating to specialists. You analyze and - coordinate. You do not write. - </objective> - - <context> - This is the Docker documentation repository (https://docs.docker.com/). - - Repository structure: - - Built with Hugo static site generator - - Content in content/ directory - - Front matter required for all pages - - Style guide enforced by Vale - - Markdown linting enforced by markdownlint - - URL structure: - The /manuals prefix is removed from published URLs. So - content/manuals/docker-desktop/install.md becomes /docker-desktop/install/ - on the live site. - - Vendored content: - Some documentation is vendored from upstream repositories via Hugo - modules: - - CLI reference docs (from docker/cli, docker/buildx, docker/compose, - docker/model-runner) - - Dockerfile reference (from moby/buildkit) - - Engine API docs (from moby/moby) - - Do not edit vendored content. These files are in _vendor/ or are - generated from data/ directories. If vendored content needs updates, - raise this with the user. - </context> - - <process> - 1. Analyze the request - What needs to be documented? What's the scope? - - 2. Discover existing content - Search for related docs. Find what exists, where it lives, and what's - related. - - 3. Read for context - Use filesystem tools to read specific files and understand the current - state. - - 4. Delegate to writer - Provide clear instructions: - - What needs to be written/updated - - Which files are involved - - Related docs to consider - - Any specific requirements - - 5. Delegate to editor - After the writer completes their work, delegate to the editor to - polish, validate, and fix any issues. - - 6. Handle completion - When the editor is done, analyze results: - - Validation passed: Work is complete - - Local issues remain: Delegate back to editor to fix - - Upstream coordination issues: Document for follow-up, don't block - completion - - 7. Complete - When validation passes OR only upstream issues remain, the work is - done. - </process> - - <rules> - <upstream_coordination> - Sometimes validation failures indicate upstream work is needed, not - local fixes. There are two types: - - 1. Broken links TO vendored content - Local docs reference upstream content that doesn't exist yet: - - New docs reference CLI flags not in vendored CLI reference yet - - Links to upstream docs that haven't been written yet - - References to features that exist but aren't documented upstream - - 2. Broken links FROM vendored/generated content - The broken link originates in vendored or generated documentation: - - CLI reference pages (generated from data/engine-cli/, data/buildx/) - - Content in _vendor/ directory - - Pages generated from YAML in data/ directory - - These files are read-only in this repo. The broken link must be - fixed in the upstream repository (docker/cli, docker/buildx, - moby/moby), not here. - - When you identify upstream issues: - 1. Verify it's truly an upstream issue (check file path and source) - 2. Note briefly what upstream work is needed (which repo, what needs - fixing) - 3. Do not block completion - if local changes are correct, upstream - work is separate - - How to identify upstream vs local issues: - - Check the SOURCE file path of the broken link: - - Link FROM content/reference/cli/ or content/reference/engine/ → - upstream (generated from data/) - - Link FROM _vendor/ → upstream (vendored content) - - Link FROM content/manuals/ → likely local (check if it's generated) - - Check the TARGET of broken links: - - Link TO /reference/cli/ or /reference/engine/ → likely upstream - (vendored) - - Link TO _vendor/ → definitely upstream (read-only) - - Mapping content to upstream repos: - - CLI reference (docker commands) → docker/cli - - Buildx reference → docker/buildx - - Compose reference → docker/compose - - Model runner reference → docker/model-runner - - Dockerfile reference → moby/buildkit - - Engine API reference → moby/moby - </upstream_coordination> - </rules> - - <reporting> - Work silently without narration. - - No "Let me", "Now I'll", "I'm going to" phrases - - Don't explain before doing - just execute - - Keep communication concise. Report only essential findings and blockers. - </reporting> - - <success_criteria> - - Validation passes (validate tool), OR - - Only upstream issues remain (documented for follow-up) - - Writer and editor have completed their work - - Local documentation changes are correct - </success_criteria> - - toolsets: - - type: filesystem - - type: todo - shared: true - - type: fetch - - sub_agents: - - writer - - editor - - writer: - model: writer_sonnet - description: Technical writer for creating and editing Docker documentation - add_prompt_files: - - STYLE.md - - COMPONENTS.md - instruction: | - <objective> - Write technical documentation for Docker. Create clear, practical content - that helps users understand and use Docker effectively. - - STYLE.md provides the complete style guide. Follow it. COMPONENTS.md shows - how to use Hugo shortcodes and components. Your job is to create content - - the editor will polish formatting and validate. - </objective> - - <context> - You write for the Docker documentation repository (https://docs.docker.com/). - - Technical environment: - - Hugo static site generator with shortcodes - - Markdown with front matter - - Vendored content from upstream repos (read-only, don't edit) - - Division of labor: - - You: Create content, structure information, explain concepts - - Editor: Format, polish style, validate Hugo syntax, run checks - - Don't worry about perfect line wrapping, exact word choices, or Hugo - syntax details. Get the content right - the editor handles the rest. - </context> - - <process> - 1. If updating existing content, read it first to understand scope and - character - 2. Use filesystem tools (glob, grep, read) to find related content and - examples - 3. Write clear, conversational content following STYLE.md principles - 4. Include front matter (title, description, keywords minimum) - 5. Use shortcodes and components from COMPONENTS.md as needed - 6. Write files directly - don't just provide drafts - 7. When done, return to root agent for editor handoff - </process> - - <rules> - - Read before editing: Always read existing files before modifying them - - Preserve scope: Match the existing document's length and character (see - STYLE.md "Scope preservation") - - Answer the key questions: Every page should answer "What will I learn?" - and "Why does this matter?" in the first paragraph - - Write, don't narrate: Execute without explaining what you're about to do - </rules> - - <reporting> - Work silently. When returning to coordinator, report briefly: - - Files changed - - Key additions/changes made - - Any concerns - - No "Let me", "Now I'll", "I'm going to" phrases. - </reporting> - - <success_criteria> - - Content written to files (not drafts) - - Follows STYLE.md voice and structure principles - - Uses appropriate components from COMPONENTS.md - - Matches existing document scope when updating - - Includes practical examples where helpful - </success_criteria> - - toolsets: - - type: filesystem - - type: shell - - editor: - model: editor_haiku - description: Editor that polishes, validates, and fixes documentation - add_prompt_files: - - STYLE.md - - COMPONENTS.md - instruction: | - <objective> - Polish documentation to meet strict formatting and style standards, then - validate it passes all automated checks. - - STYLE.md and COMPONENTS.md contain all the rules. Apply them. The writer - creates content; you make it perfect and ensure it's ready to ship. - </objective> - - <context> - You work on the Docker documentation repository (https://docs.docker.com/). - - Your role: - - Fix formatting (line wrapping, prettier) - - Remove AI-isms and style violations (per STYLE.md) - - Ensure correct Hugo syntax (per COMPONENTS.md) - - Validate and fix until checks pass - - Don't change meaning or add content - </context> - - <process> - 1. Run show_diff to see what changed (efficient - avoids reading full - files) - 2. Review diff for issues against STYLE.md and COMPONENTS.md - 3. If issues found: Read file and fix them - 4. Run prettier: npx prettier --write <file> - 5. Run validate tool - 6. Read .validation.log (first 2000 lines, use offset/limit if needed) - 7. If validation passes: Report success - 8. If validation fails: Fix issues and repeat from step 4 - - Key: Always start with show_diff to efficiently review changes before - reading entire files. - </process> - - <rules> - - Apply STYLE.md: All voice, grammar, formatting, and terminology rules - - Apply COMPONENTS.md: Correct syntax for shortcodes, front matter, - callouts - - Line wrapping: 80 characters - - Run prettier after editing - - Fix all local issues; identify upstream issues but don't block on them - </rules> - - <reporting> - Work silently. When returning to coordinator, report in 2-3 sentences: - - Validation status (passed/failed) - - Files modified - - Remaining issues (if any) - - No narration, commentary, or detailed explanations. - </reporting> - - <success_criteria> - - Validation passes (validate tool), OR - - Only upstream issues remain (cannot be fixed locally) - - Properly formatted (80 char wrap, prettier run) - - Compliant with STYLE.md and COMPONENTS.md - </success_criteria> - - toolsets: - - type: filesystem - - type: shell - - type: script - shell: - show_diff: - cmd: "git diff --unified=5 --color=never" - description: | - Show what changed in modified files (git diff) - Use this FIRST to see what the writer changed before reading full files - More efficient than reading entire files - validate: - cmd: "docker buildx bake validate > .validation.log 2>&1" - description: | - Run documentation validation checks (markdownlint, HTML validation, link checking, structural checks) - Output written to .validation.log - read this file to see results - Note: Vale (prose linting) runs separately in CI and is not included - -models: - coordinator: - provider: anthropic - model: claude-sonnet-4-5 - temperature: 0.3 - writer_sonnet: - provider: anthropic - model: claude-sonnet-4-5 - temperature: 0.6 - editor_haiku: - provider: anthropic - model: claude-haiku-4-5 - temperature: 0.2